From b42375799afc3f0a38a59b396077bb520cdea41d Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Fri, 7 Aug 2026 19:24:52 -0400 Subject: [PATCH] F-key lane: chips name actions, not keys MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The lane read as a keyboard: Top, End, PgUp, PgDn — the names of keys this keyboard doesn't even have, standing in for whatever the screen did with them. A chip's job is to name the action it performs *here*. The shared lane now speaks the vocabulary of the one thing it assumes — a scrolling body: Top, Bottom, Page ↑, Page ↓. The chat speaks its own, since neither end of a conversation is a "top": Oldest reaches back to the first message, Latest returns to the newest and the compose line. The map already got Reset and Zoom ±. Empty and dim now make different claims. Dim says "a thing here, just not right now"; empty says "not a thing here at all" — so a channel chat's F8 carries no Retry, because a channel message is never acknowledged and there is nothing a retry could mean. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 13 ++++++---- meshterm/ui/chat.py | 22 +++++++++------- meshterm/ui/tui/fkeys.py | 47 ++++++++++++++++++++++------------- tests/test_chat.py | 26 +++++++++++++++++++ tests/test_picocalc_chrome.py | 9 ++++--- 5 files changed, 82 insertions(+), 35 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3ee44dd..21c6f67 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -173,11 +173,14 @@ branch on the platform per frame, and never `from meshterm.platforms import PLAT quantizes to the `heat.*` steps, and footer hints are replaced by the **F-key lane** (`ui/tui/fkeys.py`): five `FPair` slots per screen, F1–F5 primary and F6–F10 their paired opposites (physical Shift+F1..F5), labels ≤7 cells. Screens override - `fkey_lane` for their own verbs; slots 3/4 are the customary free pair. The lane *is* - the footer here, so it obeys the hint line's rule — never advertise a key that would - do nothing: a slot whose action is out of reach this paint clears `enabled` / - `opp_enabled` and draws dimmed (label kept, fill dropped), and a screen that - repurposes the nav actions relabels them (`default_lane(nav=…)`, `MapScreen`). + `fkey_lane` for their own verbs; slots 3/4 are the customary free pair. **A chip names + an action, never a key** — `Page ↑`, not `PgUp`; `Latest` on a transcript; `Reset` on + the map, whose Home refits and whose paging zooms. The lane *is* the footer here, so it + obeys the hint line's rule — never advertise a key that would do nothing. Empty and dim + are different claims: leave the slot **empty** when the action isn't a thing on this + screen (Retry in a channel), and clear `enabled`/`opp_enabled` to draw it **dim** (label + kept, fill dropped) when it's a thing that just isn't available this paint. Dimming is + presentational — `handle` stays the authority and no-ops. - `meshterm specimen` prints the whole visual language through the real funnels — the acceptance card on-device, a preview under `--platform picocalc` on the desktop. - Dev loop: `meshterm --mock --platform picocalc` in a 53×40 window; the gallery and diff --git a/meshterm/ui/chat.py b/meshterm/ui/chat.py index 4f0d205..fdb2dac 100644 --- a/meshterm/ui/chat.py +++ b/meshterm/ui/chat.py @@ -80,27 +80,31 @@ class ChatScreen(Screen): @property def fkey_lane(self): - """The PicoCalc lane: jump-to-ends on F1/F2, message paths/retry on F3/F8. + """The PicoCalc lane in the transcript's own words: Oldest/Latest, Paths, Retry. The default lane's F1/F2 dispatch the plain ``home``/``end`` actions, but here those are already claimed by the compose line's cursor (see :meth:`handle`) — so without an override, both keys land on the same "clear the pick, stick to the tail" fallthrough and read as if either one scrolls to the bottom. F1/F2 dispatch - ``ctrl_home``/``ctrl_end`` instead, the actions that actually walk the transcript. + ``ctrl_home``/``ctrl_end`` instead, and say what those do to a conversation: + reach back to the *oldest* message, or return to the *latest* and the compose + line. F4/F5 keep the shared paging pair, which is what a screenful of transcript + looks like from the outside even though it is the pick that moves. - Every slot dims when it would do nothing (the lane's standing rule): all four nav - keys walk the *pick*, so an empty transcript leaves them inert; *Paths* needs a - picked message to have paths of; *Retry* needs a direct message that went out and - was never acknowledged. + The F3 pair follows the lane's two claims. *Retry* is absent in a channel — a + channel message is never acknowledged, so there is no such thing to retry there — + and merely dim in a direct chat with nothing outstanding. *Paths* needs a picked + message to have paths of, and all four nav slots need a transcript to walk. """ from .tui.fkeys import FPair, default_lane lane = list(default_lane(nav=bool(self._messages))) live = bool(self._messages) - lane[0] = FPair("Top", "ctrl_home", enabled=live) - lane[1] = FPair("End", "ctrl_end", enabled=live) + lane[0] = FPair("Oldest", "ctrl_home", enabled=live) + lane[1] = FPair("Latest", "ctrl_end", enabled=live) + retry = ("Retry", "retry") if not self._is_channel else ("", "") lane[2] = FPair( - "Paths", "paths", "Retry", "retry", + "Paths", "paths", *retry, enabled=self._selected is not None and self._paths is not None, opp_enabled=self._retry_target() is not None, ) diff --git a/meshterm/ui/tui/fkeys.py b/meshterm/ui/tui/fkeys.py index f60be41..b06f835 100644 --- a/meshterm/ui/tui/fkeys.py +++ b/meshterm/ui/tui/fkeys.py @@ -7,13 +7,23 @@ literal hardware behaviour and the app simply binds all ten. By JP's spec (2026-08-01): a lane slot is for functionality that would otherwise be *hard to reach* — not a shortcut to a key that is already close at hand. Enter and Esc sit right on the keyboard and are already the easiest keys to hit, so they never occupy -a slot. Paging (PgUp/PgDn) has no physical key at all, so a screen that scrolls earns it -the prime F4/F5 pair. Ctrl+letter chords (Ctrl+P for message paths, Ctrl+arrows for a -sort column, …) are fiddly to hold on this keyboard, so a screen promotes its own onto -the lone F3 slot (a second, if it has one, riding F3's Shift companion). The five -*plain* keys carry a screen's most-used, otherwise-awkward actions — reachable with no -Shift at all — and the Shift bank (F6-F10) is overflow for a screen with more than five -such actions. A lane can, and does, differ from screen to screen. +a slot. Paging has no physical key at all, so a screen that scrolls earns it the prime +F4/F5 pair. Ctrl+letter chords (Ctrl+P for message paths, Ctrl+arrows for a sort column, +…) are fiddly to hold on this keyboard, so a screen promotes its own onto the lone F3 +slot (a second, if it has one, riding F3's Shift companion). The five *plain* keys carry +a screen's most-used, otherwise-awkward actions — reachable with no Shift at all — and +the Shift bank (F6-F10) is overflow for a screen with more than five such actions. A +lane can, and does, differ from screen to screen. + +**A chip names an action, never a key** (JP, 2026-08-07). ``PgUp``, ``End`` and their +kin are the names of keys this keyboard doesn't even have; what the slot is for is the +thing it does *here* — ``Page ↑`` through a body, ``Latest`` on a transcript, ``Reset`` +on the map, whose Home key refits the view and whose paging keys zoom. A screen that +repurposes a shared action relabels it; a screen the action means nothing on leaves the +slot **empty** rather than filling the lane out. Empty and dim are different claims: +empty says *not a thing here* (Retry in a channel, where nothing is ever acknowledged), +dim says *a thing here, just not right now* (Retry in a direct chat with everything +delivered). A screen describes its lane as five :class:`FPair` slots (``None`` = unassigned); the session resolves a pressed F-key to the slot's action string and dispatches it through @@ -79,18 +89,20 @@ class FPair: #: A lane is five slots, F1..F5 left to right; ``None`` leaves a slot unassigned. Lane = Sequence[Optional[FPair]] -#: The screen-agnostic default lane. No Enter or Esc slot — both keys sit right on the -#: keyboard already. F4/F5 (the most reachable pair) carry paging, which has no physical -#: key at all; F1/F2 carry the nav cluster's jump-to-top/end, Fn-layered on the physical -#: keyboard and so worth a slot too, just a notch behind paging; F3 is the lone slot a -#: screen's own :attr:`~meshterm.ui.tui.screen.Screen.fkey_lane` override reaches for -#: first — typically a Ctrl+letter chord promoted up because chording is a pain here. +#: The default lane, in the vocabulary of a screen that is one scrolling body: move +#: through it a page at a time, or jump to either end. No Enter or Esc slot — both keys +#: sit right on the keyboard already. F4/F5 (the most reachable pair) carry paging, which +#: has no physical key at all; F1/F2 carry the jumps, Fn-layered on the physical keyboard +#: and so worth a slot too, just a notch behind paging; F3 is the lone slot a screen's own +#: :attr:`~meshterm.ui.tui.screen.Screen.fkey_lane` override reaches for first — typically +#: a Ctrl+letter chord promoted up because chording is a pain here. A screen whose body is +#: not one scrolling column says so in its own words (see :class:`ChatScreen`, ``MapScreen``). DEFAULT_LANE: tuple[Optional[FPair], ...] = ( FPair("Top", "home"), - FPair("End", "end"), + FPair("Bottom", "end"), None, - FPair("PgUp", "pageup"), - FPair("PgDn", "pagedown"), + FPair("Page ↑", "pageup"), + FPair("Page ↓", "pagedown"), ) @@ -100,7 +112,8 @@ def default_lane(*, nav: bool = True) -> tuple[Optional[FPair], ...]: The shared slots all *move* something — the jump-to-ends pair and the paging pair — so on a screen with nothing to move (a body that fits its viewport, a transcript with no messages) all four are inert and say so. Screens that repurpose the nav actions - for something always live (the map's zoom) build from :data:`DEFAULT_LANE` instead. + for something always live (the map's zoom) build from :data:`DEFAULT_LANE` instead, + relabelling as they go. Args: nav: Whether the nav keys would do anything on this paint — typically diff --git a/tests/test_chat.py b/tests/test_chat.py index aa6cd7e..5f73869 100644 --- a/tests/test_chat.py +++ b/tests/test_chat.py @@ -30,6 +30,7 @@ from meshterm.services.chat_service import ChatService from meshterm.services.event_hub import EventHub from meshterm.tools.chat import _PREVIEW_WIDTH, _LiveLasts, _preview_text, _title from meshterm.ui.chat import ChatScreen +from meshterm.ui.tui import fkeys from meshterm.ui.tui.screen import CANCEL @@ -899,6 +900,31 @@ async def test_chat_fkey_lane_dims_retry_and_the_nav_slots() -> None: await asyncio.sleep(0) assert failed.acked is True assert screen.fkey_lane[2].opp_enabled is False # acknowledged — nothing left to retry + assert screen.fkey_lane[2].opp_label == "Retry" # dim, not gone: it belongs on this screen + + +def test_chat_fkey_lane_speaks_the_transcript_and_drops_channel_retry() -> None: + """Chips name what they do here — and a channel has no such thing as a retry.""" + messages = [ChatMessage(text="hi", peer="d4e5f6a7")] + direct = _screen(_StubSession(), send=None, messages=messages) + + # Not "Top"/"End": what these do to a conversation is reach its oldest message, or + # come back to the latest one and the compose line. + assert [pair.label for pair in direct.fkey_lane[:2]] == ["Oldest", "Latest"] + assert [pair.action for pair in direct.fkey_lane[:2]] == ["ctrl_home", "ctrl_end"] + assert direct.fkey_lane[2].opp_label == "Retry" + + channel = ChatScreen( + Conversation(label="#general", is_channel=True, channel_id="1"), + messages, + send=None, + names={}, + session=_StubSession(), + ) + # A channel message is never acknowledged, so retrying one isn't a thing here: the + # slot is empty rather than dimmed, and its key resolves to nothing. + assert channel.fkey_lane[2].opp_label == "" + assert fkeys.action_for(channel.fkey_lane, 8) is None def test_chat_screen_up_picks_and_ctrl_end_returns_to_compose() -> None: diff --git a/tests/test_picocalc_chrome.py b/tests/test_picocalc_chrome.py index 3f713f9..11cb817 100644 --- a/tests/test_picocalc_chrome.py +++ b/tests/test_picocalc_chrome.py @@ -99,7 +99,8 @@ def test_fkey_lane_text_fits_and_flips() -> None: primary = lane_text(DEFAULT_LANE) shifted = lane_text(DEFAULT_LANE, shifted=True) assert cell_len(primary.plain) == 53 and cell_len(shifted.plain) == 53 - assert "F1 Top" in primary.plain and "F4 PgUp" in primary.plain and "F5 PgDn" in primary.plain + assert "F1 Top" in primary.plain # the chips name actions, not the keys they sit on + assert "F4 Page ↑" in primary.plain and "F5 Page ↓" in primary.plain # No slot has a Shift companion by default: the whole shifted bank renders unfilled. for number in (6, 7, 8, 9): assert f"F{number}" in shifted.plain @@ -130,10 +131,10 @@ def test_default_lane_dims_every_nav_slot_when_nothing_moves() -> None: assert default_lane() is DEFAULT_LANE # the live lane is the constant itself dim = default_lane(nav=False) - assert [pair.label for pair in dim if pair] == ["Top", "End", "PgUp", "PgDn"] + assert [pair.label for pair in dim if pair] == ["Top", "Bottom", "Page ↑", "Page ↓"] assert not any(pair.enabled for pair in dim if pair) row = lane_text(dim) - assert cell_len(row.plain) == 53 and "F1 Top" in row.plain and "F5 PgDn" in row.plain + assert cell_len(row.plain) == 53 and "F1 Top" in row.plain and "F5 Page ↓" in row.plain assert {str(span.style) for span in row.spans} == {"muted"} @@ -150,7 +151,7 @@ def test_lane_is_built_after_the_body_renders() -> None: composed = frame.compose_base(Text("hdr"), screen, "hint", 53, 26, footer_lane=build) assert seen["nav"] is True # lit on the very first paint, with no stale frame to lag - assert "F4 PgUp" in _plain(composed.split("\n")[-1]) + assert "F4 Page ↑" in _plain(composed.split("\n")[-1]) def test_scroll_screen_lane_tracks_whether_its_body_overflows() -> None: