F-key lane: chips name actions, not keys

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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-08-07 19:24:52 -04:00
1 parent ba6e92107d
commit b42375799a
5 files changed
+82 -35

No files matched your search

+8 -5
View File
@@ -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
+13 -9
View File
@@ -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,
)
+30 -17
View File
@@ -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
+26
View File
@@ -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:
+5 -4
View File
@@ -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: