F-key lane: dim a slot whose action isn't available

The PicoCalc lane replaces the footer hint outright, so it inherits the
hint line's standing rule — never name a key that would do nothing. Until
now it named several: Retry with nothing unacknowledged, the paging pair
on a body that already fits whole, and, worst, the map's End, bound to
nothing at all while PgUp/PgDn were labelled as paging when they zoom.

An FPair now carries enabled/opp_enabled per bank. A cleared slot keeps
its label and drops its fill, landing in the same muted "nothing to
press" class as an unassigned one — so the key still reads as what it
would do, it just plainly isn't live. The dimming stays presentational:
action_for still resolves a dim slot, and the screen's own handle()
remains the authority (it no-ops), so a lane built from stale metrics can
never swallow a key that works.

Applied where a screen can tell honestly: default_lane(nav=…) for the
shared slots (result windows and the dashboard gate on content_overflows,
the chat on having a transcript), the chat's Retry on there being an
unacknowledged direct message, and the map gets its own lane — Reset,
Zoom +, Zoom - — with F2 left unassigned rather than dead. The chat's
regular-platform hint drops ^R on the same gate.

compose_base now takes the lane as a builder and calls it after the body
renders, so those gates read this paint's scroll metrics instead of the
previous paint's.

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:01:01 -04:00
1 parent f69d1785b7
commit 790e17932e
11 files changed
+286 -35

No files matched your search

+5 -1
View File
@@ -173,7 +173,11 @@ 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.
`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`).
- `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
+35 -14
View File
@@ -86,13 +86,23 @@ class ChatScreen(Screen):
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.
"""
from .tui.fkeys import DEFAULT_LANE, FPair
lane = list(DEFAULT_LANE)
lane[0] = FPair("Top", "ctrl_home")
lane[1] = FPair("End", "ctrl_end")
lane[2] = FPair("Paths", "paths", "Retry", "retry")
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.
"""
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[2] = FPair(
"Paths", "paths", "Retry", "retry",
enabled=self._paths is not None,
opp_enabled=self._retry_target() is not None,
)
return lane
def __init__(
@@ -165,14 +175,16 @@ class ChatScreen(Screen):
@property
def footer_hint(self) -> str:
"""Key hint, reflecting whether a message is picked and what Enter does to it."""
"""Key hint, reflecting whether a message is picked and what Enter does to it.
``^R retry failed`` appears only while there is something to retry (see
:meth:`_retry_target`) — the same rule the F-key lane dims its slots by.
"""
if self._selected is not None:
if self._is_channel:
return "Enter reply (@mention) · ^P paths · ↑↓ pick · ^End/Esc cancel"
return "Enter paths · ↑↓ pick · ^End/Esc cancel"
if not self._is_channel and any(
m.outbound and m.acked is False for m in self._messages
):
if self._retry_target() is not None:
return "Enter send · ↑ pick a message · ^R retry failed · ^P paths · Esc back"
return "Enter send · ↑ pick a message · ^P paths · Esc back"
@@ -817,14 +829,23 @@ class ChatScreen(Screen):
self._stick = True
self._session.invalidate()
def _retry(self) -> None:
"""Re-attempt delivery of the most recent unacknowledged direct message (Ctrl-R)."""
def _retry_target(self) -> Optional[ChatMessage]:
"""The message ^R would re-send, or ``None`` when there is nothing to retry.
The newest outbound direct message that went out and was never acknowledged —
and only while a retry could actually start: no send already in flight, a resend
path wired (channels have none, since a channel message is never acked).
"""
if self._sending or self._resend is None:
return
target = next(
return None
return next(
(m for m in reversed(self._messages) if m.outbound and m.acked is False),
None,
)
def _retry(self) -> None:
"""Re-attempt delivery of the most recent unacknowledged direct message (Ctrl-R)."""
target = self._retry_target()
if target is None:
return
self._sending = True
+12
View File
@@ -137,6 +137,18 @@ class DashboardScreen(Screen):
return "↑↓ PgUp/PgDn scroll · Esc back"
return "Esc back"
@property
def fkey_lane(self):
"""The shared lane, dimmed on the same gate the hint above uses.
The PicoCalc draws no hint line at all — the lane *is* the footer — so the rule
the hint follows has to hold there too: an overview that fits whole has nothing
for Top/End or the paging pair to move.
"""
from .tui.fkeys import default_lane
return default_lane(nav=self.content_overflows)
def __init__(
self,
*,
+19
View File
@@ -66,6 +66,25 @@ class MapScreen(Screen):
#: mysteriously dim the context markers.
find_enabled = True
@property
def fkey_lane(self):
"""The PicoCalc lane: reset on F1, zoom on F4/F5 — nothing that doesn't act here.
The map is the one screen that repurposes the nav actions: PgUp/PgDn zoom and
Home refits the view, while ``end`` is bound to nothing at all. The shared lane
would label those keys as paging and offer a fifth that does nothing, so the map
names its own verbs and leaves F2 unassigned. All three are always live — a map
can always zoom or refit — so no slot dims.
"""
from .tui.fkeys import DEFAULT_LANE, FPair
lane = list(DEFAULT_LANE)
lane[0] = FPair("Reset", "home")
lane[1] = None # End does nothing on a map
lane[3] = FPair("Zoom +", "pageup")
lane[4] = FPair("Zoom -", "pagedown")
return lane
def __init__(
self,
session, # noqa: ANN001 - TuiSession, imported lazily to avoid a cycle
+50 -3
View File
@@ -20,11 +20,23 @@ session resolves a pressed F-key to the slot's action string and dispatches it t
the normal action funnel, so screens gain F-key support without any key handling of
their own. An :class:`FPair` need not carry a Shift-bank action at all — a "lone" slot
(``opp_label=""``) simply renders blank in the shifted bank and F(n+5) does nothing.
**A slot never advertises a key that would do nothing.** The lane is the PicoCalc's whole
footer — it stands in for the hint line the other platform draws, and that line has always
dropped an atom whose key is inert (see :attr:`~meshterm.ui.tui.screen.Screen.content_overflows`).
So a screen rebuilds its lane each paint and clears :attr:`FPair.enabled` /
:attr:`FPair.opp_enabled` on whatever is out of reach right now: the chat's *Paths* with
no message picked, its *Retry* with nothing unacknowledged, the shared nav slots on a
screen with nothing to move (:func:`default_lane`). A dimmed slot keeps its label — muted,
unfilled, like an unassigned slot — so the key still reads as *what it would do*, it just
plainly isn't live. The dimming is presentational: the screen's own ``handle`` stays the
authority on what an action does (it no-ops), so a lane built from one-paint-stale metrics
can never swallow a key that would have worked.
"""
from __future__ import annotations
from dataclasses import dataclass
from dataclasses import dataclass, replace
from typing import Optional, Sequence
from rich.text import Text
@@ -50,12 +62,18 @@ class FPair:
companion — the shifted bank then renders that chip blank and the
corresponding F(n+5) does nothing.
opp_action: The action the Shift-bank companion dispatches, or ``""``.
enabled: Whether the plain key's action is available *right now*. ``False`` draws
the chip dimmed — label kept, fill dropped — rather than pretending (see the
module docstring).
opp_enabled: The same, for the Shift-bank companion.
"""
label: str
action: str
opp_label: str = ""
opp_action: str = ""
enabled: bool = True
opp_enabled: bool = True
#: A lane is five slots, F1..F5 left to right; ``None`` leaves a slot unassigned.
@@ -76,12 +94,37 @@ DEFAULT_LANE: tuple[Optional[FPair], ...] = (
)
def default_lane(*, nav: bool = True) -> tuple[Optional[FPair], ...]:
""":data:`DEFAULT_LANE`, with its four nav slots dimmed unless ``nav``.
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.
Args:
nav: Whether the nav keys would do anything on this paint — typically
:attr:`~meshterm.ui.tui.screen.Screen.content_overflows`.
Returns:
The five slots, ready for a screen to overwrite the ones it claims.
"""
if nav:
return DEFAULT_LANE
return tuple(
None if pair is None else replace(pair, enabled=False, opp_enabled=False)
for pair in DEFAULT_LANE
)
def action_for(lane: Lane, number: int) -> Optional[str]:
"""The action F-key ``number`` (1-10) resolves to on this lane, or ``None``.
F1-F5 take the slot's plain-key action, F6-F10 (the physical Shift bank) take its
companion — or resolve to nothing when the slot has none (a lone slot, or an
unassigned one).
unassigned one). A *dimmed* slot still resolves: dimming is how the lane draws an
action the screen would no-op anyway, and resolving it regardless keeps a lane built
from stale metrics from ever swallowing a key that works (see the module docstring).
"""
index = (number - 1) % 5
if index >= len(lane) or lane[index] is None:
@@ -124,5 +167,9 @@ def lane_text(lane: Lane, *, shifted: bool = False) -> Text:
key = f"F{number}" if number < 10 else "10"
row.append(f"{key}{' ' * (_CHIP_WIDTH - len(key))}", style="muted")
continue
row.append(_chip(number, label), style=fill)
live = pair.opp_enabled if shifted else pair.enabled
# A dimmed slot drops the fill and keeps the label, landing in the same muted
# "nothing to press" class as an unassigned one — while still saying what the
# key is for once it becomes available.
row.append(_chip(number, label), style=fill if live else "muted")
return row
+15 -9
View File
@@ -8,7 +8,7 @@ header and footer so the whole view fits the terminal exactly (never overflowing
from __future__ import annotations
from collections import OrderedDict
from typing import Optional, Sequence
from typing import Callable, Optional, Sequence
from rich.cells import cell_len
from rich.console import Group, RenderableType
@@ -221,7 +221,7 @@ def compose_base(
footer_hint: str,
cols: int,
rows: int,
footer_lane: RenderableType | None = None,
footer_lane: Callable[[], RenderableType] | None = None,
) -> str:
"""Compose the full-screen ANSI view: header, the base screen's panel, and a footer.
@@ -231,8 +231,10 @@ def compose_base(
footer_hint: The active screen's key hint, shown at the very bottom.
cols: Terminal width.
rows: Terminal height.
footer_lane: A pre-built footer row (the PicoCalc F-key lane) that replaces the
hint string when the platform runs fixed F-key hints.
footer_lane: Builds the footer row (the PicoCalc F-key lane) that replaces the
hint string when the platform runs fixed F-key hints. Called *after* the body
renders, since a lane dims its slots from the screen's scroll metrics — which
this paint has only just recorded (see :func:`~meshterm.ui.tui.fkeys.default_lane`).
Returns:
An ANSI string of exactly ``rows`` lines, each within ``cols`` columns.
@@ -243,9 +245,13 @@ def compose_base(
# wraps it onto a second line (which would push the panel down and misreport its height).
header_lines = render_lines(header, cols, no_wrap=True)
header_h = len(header_lines)
footer = footer_lane if footer_lane is not None else Text.from_markup(
f"[muted]{footer_hint}[/muted]"
)
def footer_row() -> RenderableType:
"""The bottom line: the platform's F-key lane, else the muted hint string."""
if footer_lane is not None:
return footer_lane()
return Text.from_markup(f"[muted]{footer_hint}[/muted]")
if platform.frame_border:
viewport = max(1, rows - header_h - 1 - 2) # minus footer(1) and panel border(2)
# Record the viewport *before* the body renders, so a screen that windows a
@@ -265,7 +271,7 @@ def compose_base(
body = _BASE_BOX_CACHE[1]
else:
panel = _panel_box(base.title, visible, more_above, more_below, "accent")
body = render_lines(Group(panel, footer), cols)
body = render_lines(Group(panel, footer_row()), cols)
if footer_lane is None:
_BASE_BOX_CACHE = (key, body)
else:
@@ -279,7 +285,7 @@ def compose_base(
body = (
render_lines(bar, cols, no_wrap=True)
+ visible
+ render_lines(footer, cols, no_wrap=True)
+ render_lines(footer_row(), cols, no_wrap=True)
)
# The glow pass lights the outer frame *and* any tool panels nested in the body. It only
# ever recolours truecolor foregrounds (see glow._advance_fg), so on a platform without
+18
View File
@@ -70,6 +70,12 @@ class Screen:
F1/F2, and leaves F3 as the one lone slot — the first a screen reaches for to
promote its own otherwise-fiddly shortcut (a Ctrl+letter chord, say). A screen
overrides this property for its own verbs; the lane may differ screen to screen.
Read fresh every paint, so an override dims the slots whose action would do
nothing right now rather than advertising a dead key — the lane's standing rule
(see :mod:`~meshterm.ui.tui.fkeys`). Screens whose nav keys only scroll gate the
shared slots on :attr:`content_overflows`; this base can't assume that much,
since a nav key elsewhere moves a cursor, a pick, or the map's zoom.
"""
from .fkeys import DEFAULT_LANE
@@ -422,6 +428,18 @@ class ScrollScreen(Screen):
top/bottom.
"""
@property
def fkey_lane(self):
"""The shared lane, its nav slots dimmed when the content already fits.
Every nav key here scrolls and nothing else, so a result window short enough to
read whole has four inert slots — the same gate the footer hint uses on the other
platform (:attr:`Screen.content_overflows`).
"""
from .fkeys import default_lane
return default_lane(nav=self.content_overflows)
def __init__(
self,
renderable: RenderableType,
+13 -4
View File
@@ -1299,14 +1299,23 @@ class TuiSession:
if not base.chrome:
return self._emit(frame.compose_startup(base, cols, rows))
footer = self.top.footer_hint if self.top else base.footer_hint
lane = None
if get_platform().footer_fkeys:
active = self.top or base
lane = fkeys.lane_text(active.fkey_lane, shifted=modifier_watch.shift_down())
lane = self._fkey_lane(self.top or base)
return self._emit(
frame.compose_base(self._header(cols), base, footer, cols, rows, footer_lane=lane)
)
@staticmethod
def _fkey_lane(active: Screen) -> Optional[Callable[[], Text]]:
"""A deferred F-key lane row for ``active``, or ``None`` on a platform without one.
Deferred because the frame resolves it *after* the body renders: a lane dims the
slots whose action would do nothing, and that reading comes from the scroll
metrics this paint is about to record (see :func:`~meshterm.ui.tui.fkeys.default_lane`).
"""
if not get_platform().footer_fkeys:
return None
return lambda: fkeys.lane_text(active.fkey_lane, shifted=modifier_watch.shift_down())
def _render_float_layer(self, index: int) -> ANSI:
"""Render the ``index``-th floating dialog (bottom-to-top) as a centered box."""
layers = self._float_layers()
+34 -3
View File
@@ -491,14 +491,21 @@ async def test_service_records_channel_messages_in_arrival_order(repo: Repositor
# -- chat screen --------------------------------------------------------------
def _screen(session: _StubSession, send, *, messages=None) -> ChatScreen:
def _screen(session: _StubSession, send, *, messages=None, resend=None) -> ChatScreen:
"""Build a ChatScreen for a direct conversation with a stub session and send hook."""
conv = Conversation(
label="Alice",
is_channel=False,
contact=Contact(name="Alice", public_key="d4" + "0" * 62, key_prefix="d4e5f6a7"),
)
return ChatScreen(conv, messages or [], send=send, names={"d4e5f6a7": "Alice"}, session=session)
return ChatScreen(
conv,
messages or [],
send=send,
names={"d4e5f6a7": "Alice"},
session=session,
resend=resend,
)
def test_chat_screen_renders_transcript_and_input() -> None:
@@ -718,12 +725,15 @@ def test_chat_screen_shows_delivery_glyphs() -> None:
"""Outbound direct messages end with delivery marks: a spinner, then ✓ / ✗."""
from meshterm.ui.tui.spinner import Spinner
async def resend(message): # noqa: ANN001, ANN202 - never awaited here
return message
messages = [
ChatMessage(text="delivered", outbound=True, peer="d4e5f6a7", acked=True),
ChatMessage(text="dropped", outbound=True, peer="d4e5f6a7", acked=False),
ChatMessage(text="inflight", outbound=True, peer="d4e5f6a7", acked=None),
]
screen = _screen(_StubSession(), send=None, messages=messages)
screen = _screen(_StubSession(), send=None, messages=messages, resend=resend)
joined = "\n".join(screen.render_body(60))
# A message still awaiting its ack spins (a Braille frame); resolved ones show the
@@ -870,6 +880,27 @@ async def test_chat_screen_retry_resends_failed_message() -> None:
assert "✓" in "\n".join(screen.render_body(60))
async def test_chat_fkey_lane_dims_retry_and_the_nav_slots() -> None:
"""The lane offers Retry only with something to retry, and nav only with a transcript."""
async def resend(message: ChatMessage) -> ChatMessage:
message.acked = True
return message
empty = _screen(_StubSession(), send=None, resend=resend)
assert not any(pair.enabled for pair in empty.fkey_lane if pair) # nothing to walk
failed = ChatMessage(text="oops", outbound=True, peer="d4e5f6a7", acked=False)
screen = _screen(_StubSession(), send=None, messages=[failed], resend=resend)
assert all(pair.enabled for pair in screen.fkey_lane[:2]) # Top/End walk the pick
assert screen.fkey_lane[2].opp_enabled is True # F8 Retry: the message never acked
screen.handle("retry")
await asyncio.sleep(0)
assert failed.acked is True
assert screen.fkey_lane[2].opp_enabled is False # acknowledged — nothing left to retry
def test_chat_screen_up_picks_and_ctrl_end_returns_to_compose() -> None:
"""↑ picks the newest message (detaching from the tail); ^End returns to compose."""
messages = [
+19
View File
@@ -568,6 +568,25 @@ def test_map_screen_shift_pans_by_a_single_cell() -> None:
assert screen._viewport.center_lon == pytest.approx(expected_lon)
def test_map_fkey_lane_names_zoom_and_drops_the_dead_slot() -> None:
"""The map repurposes the nav keys, so its lane labels them — and offers no dead key."""
from meshterm.ui.map_render import MapMarker
from meshterm.ui.map_screen import MapScreen
from meshterm.ui.tui.fkeys import action_for
screen = MapScreen(_StubSession(80, 24), [MapMarker("A", 45.5, -73.6)], _StubSource(), 14)
lane = screen.fkey_lane
# PgUp/PgDn zoom here and Home refits — the shared "Top/End/PgUp/PgDn" labels would
# all be lies, and "end" is bound to nothing at all.
assert [pair.label if pair else None for pair in lane] == [
"Reset", None, None, "Zoom +", "Zoom -",
]
assert action_for(lane, 2) is None # F2 offers nothing rather than a dead End
assert action_for(lane, 1) == "home" and action_for(lane, 4) == "pageup"
assert all(pair.enabled for pair in lane if pair) # a map can always zoom or refit
def test_map_screen_find_filters_frames_and_clears() -> None:
"""Typing builds the find query; Enter frames matches; Esc peels filter then map."""
import asyncio
+66 -1
View File
@@ -7,7 +7,13 @@ from rich.text import Text
from meshterm.platforms import PICOCALC, REGULAR, set_platform
from meshterm.ui.tui import frame
from meshterm.ui.tui.fkeys import DEFAULT_LANE, FPair, action_for, lane_text
from meshterm.ui.tui.fkeys import (
DEFAULT_LANE,
FPair,
action_for,
default_lane,
lane_text,
)
from meshterm.ui.tui.screen import ScrollScreen
from tests.conftest import plain as _plain
@@ -19,6 +25,12 @@ def _screen(lines: int = 40) -> ScrollScreen:
return screen
def _slot_style(row: Text, index: int) -> str:
"""The style the lane painted onto slot ``index``'s chip (slots are 9 cells + 2 gap)."""
start = index * 11
return next(str(span.style) for span in row.spans if span.start <= start < span.end)
def test_borderless_frame_swaps_the_panel_for_a_title_bar() -> None:
set_platform(PICOCALC)
composed = frame.compose_base(Text("hdr"), _screen(), "hint", 53, 26).split("\n")
@@ -97,6 +109,59 @@ def test_fkey_lane_text_fits_and_flips() -> None:
assert cell_len(lane_text(wide, shifted=True).plain) == 53
def test_fkey_slot_dims_when_its_action_is_unavailable() -> None:
"""An unavailable slot keeps its label and drops its fill — it never offers a dead key."""
lane = [FPair("Paths", "paths", "Retry", "retry", enabled=False)] + [None] * 4
primary = lane_text(lane)
shifted = lane_text(lane, shifted=True)
# The label survives: the lane still says what F1 is for, just not that it acts now.
assert "F1 Paths" in primary.plain and _slot_style(primary, 0) == "muted"
# Its Shift companion is untouched — the two banks gate independently.
assert "F6 Retry" in shifted.plain and _slot_style(shifted, 0) == "fkey.chip.shift"
# The row is still exactly the lane's width, dim chips and all.
assert cell_len(primary.plain) == 53 and cell_len(shifted.plain) == 53
# Dimming is presentational: the key still resolves, and the screen's handler no-ops.
assert action_for(lane, 1) == "paths"
def test_default_lane_dims_every_nav_slot_when_nothing_moves() -> None:
"""A screen with nothing to move gets the shared lane back inert, not absent."""
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 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 {str(span.style) for span in row.spans} == {"muted"}
def test_lane_is_built_after_the_body_renders() -> None:
"""The frame defers the lane, so its gates read this paint's metrics, not the last one's."""
set_platform(PICOCALC)
screen = _screen() # 40 body rows into a 23-row viewport: it overflows
seen: dict[str, bool] = {}
def build() -> Text:
seen["nav"] = all(pair.enabled for pair in screen.fkey_lane if pair)
return lane_text(screen.fkey_lane)
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])
def test_scroll_screen_lane_tracks_whether_its_body_overflows() -> None:
"""The result window's nav slots light only once there is something to scroll to."""
screen = _screen()
screen.note_metrics(4, 20) # the whole body fits the viewport
assert not any(pair.enabled for pair in screen.fkey_lane if pair)
screen.note_metrics(80, 20) # taller than the viewport
assert all(pair.enabled for pair in screen.fkey_lane if pair)
def test_host_battery_reads_the_sysfs_supply(tmp_path, monkeypatch) -> None:
"""The PicoCalc battery path: a true percent and charging flag straight from sysfs."""
from meshterm.services import battery_service