A record's tabs are Info, Route and Area, organized like the node page

Info is the record's stats with the page's actions at its foot, the cursor opening on
Trace; Route is the walk two ways — THE route graph, its key, the route line — with
Trace this path as its one row, so Enter there walks the route on show, the node page's
rule for its Routes tab; Area is the ground drawing, unchanged. Each tab's stage is
composed once per width and cached, and the footer names only what the tab answers: a
lone action row earns no ↑↓ atom. The gallery gains the Route tab as a specimen.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5.1 committed 2026-09-12 13:13:01 -04:00
1 parent ea8ae61812
commit aae3d3f0fe
3 files changed
+151 -102

No files matched your search

+72 -58
View File
@@ -56,7 +56,6 @@ from .tui.screen import Screen
from .widgets import (
NodeResolver,
TypeOf,
body_heading,
name_rgb,
node_marker,
node_type_legend,
@@ -99,11 +98,10 @@ _AREA_TONE: RGB = (148, 163, 184)
_AREA_MIN_W = 16
_AREA_MIN_ROWS = 8
#: The page's tabs, in strip order. The Area tab is offered only for a walk with a
#: drawable shape; a lone tab collapses to a plain heading
#: (:func:`~meshterm.ui.widgets.tab_strip`), so a record with no ground to draw still
#: reads as the same page.
_TAB_STATS = "Stats"
#: The page's tabs, in strip order — the node page's Info / Routes, plus the ground. The
#: Area tab is offered only for a walk with a drawable shape.
_TAB_INFO = "Info"
_TAB_ROUTE = "Route"
_TAB_AREA = "Area"
#: Dots kept clear inside the box's edges — wider on the sides than above and below, so a
#: pin at the eastern or western extreme still has the cells its hash-byte label needs.
@@ -206,12 +204,14 @@ class RecordScreen(Screen):
reads *back*. It used to float as a 62-column card, which read as a question over the
list rather than as the page it is.
A **tabbed stage**, the node page's shape (:func:`~meshterm.ui.widgets.tab_strip`,
``Tab``/``Shift+Tab`` to switch): **Stats** is the record read — its stats, then the
route two ways — with the action rows at its foot; **Area** is the walk's ground, drawn
across the whole stage the viewport leaves under the strip, so the shape gets every row
and column the page has rather than the corner a stacked layout could spare it. The
Area tab is offered only when there is a shape to draw.
A **tabbed stage**, organized like the node page (:func:`~meshterm.ui.widgets.tab_strip`,
``Tab``/``Shift+Tab`` to switch): **Info** is the record's stats with the page's
action rows at its foot; **Route** is the walk two ways — THE route graph over the
route line — with *Trace this path* under it, so Enter there walks the route on show;
**Area** is the walk's ground, drawn across the whole stage the viewport leaves under
the strip, so the shape gets every row and column the page has rather than the corner
a stacked layout could spare it. The Area tab is offered only when there is a shape to
draw.
Every stat the walk was measured by — a reliability read from the far node's trace
history, the far point named with the node it reached, the longest leg drawn as the
@@ -275,14 +275,14 @@ class RecordScreen(Screen):
self._shape = list(shape) if shape else None
self._reliability = reliability
self._type_of = type_of
self._actions = ("trace", "delete")
self._index = 0
self._cursor: int | None = None
self._tabs = [_TAB_STATS] + ([_TAB_AREA] if self._shape else [])
self._tabs = [_TAB_INFO, _TAB_ROUTE] + ([_TAB_AREA] if self._shape else [])
self._tab_index = 0
# The Stats tab's composed page above the action rows, per width, and the Area
# tab's drawing, per (width, rows): both pure functions of the frozen record.
self._stats_cache: tuple[int, list[str]] | None = None
# Each tab's composed stage above its action rows, per width — and the Area tab's
# drawing per (width, rows) — all pure functions of the frozen record.
self._info_cache: tuple[int, list[str]] | None = None
self._route_cache: tuple[int, list[str]] | None = None
self._area_cache: tuple[tuple[int, int], list[str]] | None = None
# The page opens at the top, reading down; the arrows drive (and follow) the action
# cursor, while PgUp/PgDn/Home/End scroll the body free of it (see cursor_line).
@@ -293,46 +293,57 @@ class RecordScreen(Screen):
"""The tab filling the stage."""
return self._tabs[self._tab_index]
@property
def _actions(self) -> tuple[str, ...]:
"""The active tab's action rows, in cursor order.
Info carries the page's actions, the cursor opening on the safe one; Route carries
*Trace this path* alone, so Enter there walks the route on show — the node page's
rule, where Enter on a route arms its trace; Area is a picture and carries none.
"""
if self._tab == _TAB_INFO:
return ("trace", "delete")
if self._tab == _TAB_ROUTE:
return ("trace",)
return ()
@property
def fkey_lane(self):
"""The shared pager, dimmed where nothing scrolls, plus the tab switch on F3.
The chip names the tab it would take you *to*, never the one you are on — the node
page's rule (see :attr:`~meshterm.ui.node_detail_screen.NodeDetailScreen.fkey_lane`).
A record with no drawable ground has one tab and nothing to switch, so the slot
stays empty; the Area tab is a picture sized to the viewport, so the pager is dim
there.
The Area tab is a picture sized to the viewport, so the pager is dim there.
"""
from .tui.fkeys import FPair, default_lane
lane = list(default_lane(nav=self._tab == _TAB_STATS and self.content_overflows))
if len(self._tabs) >= 2:
lane[2] = FPair(self._tabs[(self._tab_index + 1) % len(self._tabs)], "tab")
lane = list(default_lane(nav=self._tab != _TAB_AREA and self.content_overflows))
lane[2] = FPair(self._tabs[(self._tab_index + 1) % len(self._tabs)], "tab")
return lane
@property
def footer_hint(self) -> str: # type: ignore[override]
"""The hint line: tab switch, then the Stats tab's move/scroll/select, Esc last.
"""The hint line: tab switch, then the tab's move/scroll/select, Esc last.
Each atom is gated on there being something for its key to do — the Area tab has
no cursor and never scrolls, so it names only the switch and Esc.
Each atom is gated on there being something for its key to do — a lone action row
has nothing for ↑↓ to move between, and the Area tab has no cursor and never
scrolls, so it names only the switch and Esc.
"""
parts: list[str] = []
if len(self._tabs) >= 2:
parts.append("Tab/⇧Tab switch")
if self._tab == _TAB_STATS:
parts = ["Tab/⇧Tab switch"]
actions = self._actions
if len(actions) > 1:
parts.append("↑↓ move")
if self.content_overflows:
parts.append("PgUp/PgDn scroll")
if actions and self.content_overflows:
parts.append("PgUp/PgDn scroll")
if actions:
parts.append("Enter select")
parts.append("Esc back")
return " · ".join(parts)
def _switch_tab(self, delta: int) -> None:
"""Move the active tab; the page opens at the top, free of the cursor."""
if len(self._tabs) < 2:
return
"""Move the active tab; its page opens at the top, the cursor on its first row."""
self._tab_index = (self._tab_index + delta) % len(self._tabs)
self._index = 0
self._follow = False
self.scroll_to_top()
@@ -348,7 +359,7 @@ class RecordScreen(Screen):
self._switch_tab(-1)
elif action == "escape":
self.resolve(None)
elif self._tab != _TAB_STATS:
elif self._tab == _TAB_AREA:
return
elif action == "up":
self._follow = True
@@ -589,11 +600,11 @@ class RecordScreen(Screen):
def render_body(self, width: int) -> list[str]:
"""The tab strip, then the active tab's stage.
The Stats tab is the record read — stat lanes, the route graph, the route — and
closes on the action rows; it scrolls when it outgrows the viewport. The Area tab
is the ground drawing sized to the rows the strip leaves, so it never does.
Everything above the action rows is a pure function of the frozen record and the
width (and, for the drawing, the rows), so it is composed once and cached; only the
Info is the stat lanes and Route the graph over the route line, each closing on its
action rows and scrolling if it ever outgrows the viewport. The Area tab is the
ground drawing sized to the rows the strip leaves, so it never does. Everything
above the action rows is a pure function of the frozen record and the width (and,
for the drawing, the rows), so it is composed once and cached; only the
cursor-bearing action rows re-render per repaint.
"""
# The pinned chrome every tab opens under: the strip in its air (see widgets.tab_air).
@@ -606,10 +617,16 @@ class RecordScreen(Screen):
self._scroll_total = max(1, len(lines))
return lines
cached = self._stats_cache
if cached is None or cached[0] != width:
cached = (width, self._stats_lines(width))
self._stats_cache = cached
if self._tab == _TAB_INFO:
cached = self._info_cache
if cached is None or cached[0] != width:
cached = (width, self._info_lines(width))
self._info_cache = cached
else:
cached = self._route_cache
if cached is None or cached[0] != width:
cached = (width, self._route_lines(width))
self._route_cache = cached
lines.extend(cached[1])
lines.append("")
@@ -638,16 +655,10 @@ class RecordScreen(Screen):
self._scroll_total = max(1, len(lines))
return lines
def _stats_lines(self, width: int) -> list[str]:
"""The Stats tab above its action rows: the stat lanes, then the route two ways.
The tab is the page's title, so the stats open directly under the strip; the route
block is set apart under a body heading (THE form, widgets.body_heading) whose note
reads the graph's labels back.
"""
def _info_lines(self, width: int) -> list[str]:
"""The Info tab above its action rows: the record's identity, then its stats."""
record = self._record
lines: list[str] = []
# The record's identity leads its stats: the spec that was walked and when it was
# set, then what the walk measured.
spec = Text(record.spec, style="brand")
@@ -657,15 +668,18 @@ class RecordScreen(Screen):
when.append(f" · MeshTerm {record.app_version}", style="muted")
lines.append(render_to_ansi(self._lane("recorded", when), width, no_wrap=True))
lines.extend(render_to_ansi(lane, width, no_wrap=True) for lane in self._stat_lanes())
return lines
lines.append("")
heading = body_heading("Route", "you → … → you · labels = hash byte")
lines.append(render_to_ansi(heading, width, no_wrap=True))
lines.extend(self._graph_lines(width))
def _route_lines(self, width: int) -> list[str]:
"""The Route tab above its action row: THE route graph, its key, then the route line."""
record = self._record
lines = self._graph_lines(width)
caption = Text("you → … → you · labels = hash byte", style="faint")
lines.append(render_to_ansi(caption, width, no_wrap=True))
lines.append(render_to_ansi(node_type_legend(), width, no_wrap=True))
# The walk itself, on THE path widget, across the card's whole width. No ``route``
# label lane: the line under a route graph headed "you → … → you" is the route,
# label lane: the line under a route graph captioned "you → … → you" is the route,
# and the twelve cells a label would take are hops the reader came here for. It wraps
# at hop boundaries (never mid-name, never mid-chip) rather than hanging under a lane.
# Our two ends stand on the app-wide ★ rather than repeating our name and key — the
+8
View File
@@ -700,6 +700,13 @@ def _record_area(cols: int, rows: int) -> Screen:
],
)
screen.note_metrics(rows, rows)
screen.handle("shift_tab") # Info → Area, the last tab
return screen
def _record_route(cols: int, rows: int) -> Screen:
"""A record turned to its Route tab: the graph, its key, the route line, the trace row."""
screen = _record_dialog(cols, rows)
screen.handle("tab")
return screen
@@ -927,6 +934,7 @@ _ENTRIES: list[_Entry] = [
_Entry("path_composer", _path_composer),
_Entry("courier_outbox", _courier_outbox),
_Entry("record_dialog", _record_dialog),
_Entry("record_route", _record_route),
_Entry("record_area", _record_area),
_Entry("packet_viewer", _packet_viewer),
_Entry("trace", _trace),
+71 -44
View File
@@ -97,23 +97,28 @@ def _dialog(record: DiscoveredPath, rank: int = 1, **kw) -> RecordScreen:
def test_record_dialog_shows_stats_route_and_the_trace_action() -> None:
"""Score in the category's unit, the resolved route bracketed by us, and actions."""
body = _plain(_dialog(_record()).render_body(60))
assert "2 nodes" in body # the score, in the discipline's own unit
assert "Hilltop-Repeater" in body # a resolved relay on the route
assert "Homestead" in body # us, bracketing the walked route
assert "Trace this path" in body # the renamed action (was "Walk again")
assert "Walk again" not in body
assert "Delete record" in body
assert "Back" not in body # no exit row: Esc leaves the page
screen = _dialog(_record())
info = _plain(screen.render_body(60))
assert "2 nodes" in info # the score, in the discipline's own unit
assert "Trace this path" in info # the renamed action (was "Walk again")
assert "Walk again" not in info
assert "Delete record" in info
assert "Back" not in info # no exit row: Esc leaves the page
screen.handle("tab")
route = _plain(screen.render_body(60))
assert "Hilltop-Repeater" in route # a resolved relay on the route
assert "Homestead" in route # us, bracketing the walked route
assert "Trace this path" in route and "Delete record" not in route # Enter here traces
def test_record_dialog_draws_the_walk_as_a_route_graph() -> None:
"""The walk is drawn on THE route graph — us starred at both ends, over a caption."""
lines = _plain(_dialog(_record()).render_body(60)).splitlines()
heading = next(i for i, line in enumerate(lines) if line.startswith("Route"))
assert "you → … → you" in lines[heading] and "labels = hash byte" in lines[heading]
screen = _dialog(_record())
screen.handle("tab") # the Route tab
lines = _plain(screen.render_body(60)).splitlines()
legend = next(i for i, line in enumerate(lines) if "▲ repeater" in line)
graph = "\n".join(lines[heading + 1 : legend]) # the drawing, up to its legend
assert "you → … → you" in lines[legend - 1] and "labels = hash byte" in lines[legend - 1]
graph = "\n".join(lines[_strip_end(lines) : legend - 1]) # the drawing, up to its caption
assert graph.count("★") == 2 # our node marks both endpoints of the round trip
assert any("⠀" <= ch <= "⣿" for ch in graph) # braille edges are drawn
@@ -139,9 +144,10 @@ def test_record_dialog_route_runs_unlabelled_across_the_whole_card() -> None:
our own two ends stand on the ★ the graph above already marks us with.
"""
dialog = _dialog(_record(route=tuple([HUB_ID, FAR_ID] * 4)))
dialog.handle("tab") # the Route tab
body = _plain(dialog.render_body(60)).splitlines()
# The route closes the Route section: it runs from under the graph's legend to the
# blank line before the action rows.
# The route closes the Route tab's stage: it runs from under the graph's legend to
# the blank line before the action row.
legend_at = next(i for i, line in enumerate(body) if "▲ repeater" in line)
route = body[legend_at + 1 : body.index("", legend_at)]
assert not route[0].startswith("route") # no label lane
@@ -156,7 +162,9 @@ def test_record_dialog_route_runs_unlabelled_across_the_whole_card() -> None:
def test_record_dialog_shows_the_node_type_legend() -> None:
"""The standard node-type key sits under the graph, so its markers read."""
body = _plain(_dialog(_record()).render_body(60))
screen = _dialog(_record())
screen.handle("tab") # the Route tab
body = _plain(screen.render_body(60))
assert "★ you" in body and "▲ repeater" in body and "◉ sensor" in body
@@ -312,41 +320,58 @@ def _strip_end(lines: list[str]) -> int:
raise AssertionError(f"no tab strip in {lines[:5]}")
def test_record_opens_on_the_stats_tab_with_the_area_tab_beside_it() -> None:
"""A drawable walk gets two tabs — Stats, then Area — and opens on Stats.
def test_record_opens_on_info_with_route_and_area_tabs_beside_it() -> None:
"""A drawable walk gets three tabs — Info, Route, Area — and opens on Info.
The node page's shape: the strip is the page's title, so the stats open directly
under it (identity first), the route follows under its own heading, and nothing of the
ground is drawn on this tab — the drawing has a tab of its own.
Organized like the node page: the strip is the page's title, so the stats open
directly under it (identity first) with the page's actions at the foot, and nothing
of the route or the ground is drawn on this tab — each has a tab of its own.
"""
screen = _dialog(_record(), far_label="Far", shape=_loop_shape())
lines = _plain(screen.render_body(58)).splitlines()
strip = "\n".join(lines[: _strip_end(lines)])
assert "Stats" in strip and "Area" in strip, "both tabs boxed in the strip"
assert "Info" in strip and "Route" in strip and "Area" in strip, "all three boxed"
body = [line for line in lines[_strip_end(lines) :] if line]
assert body[0].startswith("spec") and body[1].startswith("recorded") # identity first
assert body[2].startswith("score")
assert any(line.startswith("Route") for line in body) # the route, under its heading
assert "Trace this path" in "\n".join(body) # the actions close the Stats tab
assert not any(
_is_braille(ch)
for line in body[: body.index("Route · you → … → you · labels = hash byte")]
for ch in line
)
assert "Trace this path" in "\n".join(body) and "Delete record" in "\n".join(body)
assert not any(_is_braille(ch) for line in body for ch in line), "no drawing here"
assert "Hilltop-Repeater" not in "\n".join(body), "the route has a tab of its own"
assert "Far" in "\n".join(body) # the far-point name is a stat, not a drawing label
def test_record_route_tab_draws_the_walk_and_enter_traces_it() -> None:
"""The Route tab: the graph over the route line, with Trace this path as its one row.
The node page's rule for its Routes tab — Enter on the route on show arms its trace —
so the tab carries that action alone; the page's Delete stays on Info.
"""
screen = _dialog(_record(), far_label="Far", shape=_loop_shape())
screen.handle("tab")
lines = _plain(screen.render_body(58)).splitlines()
stage = [line for line in lines[_strip_end(lines) :] if line]
assert "▲ repeater" in "\n".join(stage) # the graph's key
assert any(line.startswith("★") and line.endswith("★") for line in stage) # the route line
assert stage[-1].endswith("Trace this path — reopen in Trace path")
assert "Delete record" not in "\n".join(stage)
assert "spec" not in "\n".join(stage), "the stats have a tab of their own"
captured: list = []
screen.resolve = captured.append # type: ignore[method-assign]
screen.handle("enter")
assert captured == ["trace"]
def test_record_area_tab_fills_the_stage_with_hash_byte_pins() -> None:
"""Tab turns to the Area tab: the ground, pinned and labelled, sized to the viewport.
"""⇧Tab turns to the Area tab: the ground, pinned and labelled, sized to the viewport.
The drawing used to ride beside the stats in a third of the width, unlabelled — there
was no cell for a label. It has a tab of its own now and spends every row the strip
leaves, so a pin and the graph node on the Stats tab can be matched by their shared
leaves, so a pin and the graph node on the Route tab can be matched by their shared
byte, and a taller terminal is a bigger shape.
"""
screen = _dialog(_record(), far_label="Far", shape=_loop_shape())
screen.note_metrics(40, 24)
screen.handle("tab")
screen.handle("shift_tab") # Info → Area, the last tab
lines = _plain(screen.render_body(58)).splitlines()
stage = [line for line in lines[_strip_end(lines) :] if line]
block = "\n".join(stage)
@@ -355,15 +380,15 @@ def test_record_area_tab_fills_the_stage_with_hash_byte_pins() -> None:
assert "▲" in block # the repeater vertex, in its map glyph
assert HUB_ID[:2] in block and FAR_ID[:2] in block # each hop's hash byte beside its pin
assert stage[-1] == "north up · labels = hash byte" # the caption reads the drawing back
assert "Trace this path" not in block # the actions belong to the Stats tab
assert "Trace this path" not in block # a picture: no action rows
assert len(lines) <= 24, "the Area tab never outgrows the viewport"
screen.note_metrics(40, 40)
taller = _plain(screen.render_body(58)).splitlines()
assert len(taller) > len(lines), "a taller viewport is a taller drawing"
screen.handle("tab") # …and back round to Stats
assert "Trace this path" in _plain(screen.render_body(58))
screen.handle("tab") # …and round to Info again
assert "Delete record" in _plain(screen.render_body(58))
def test_record_area_drawing_spends_the_width_it_is_given() -> None:
@@ -373,7 +398,7 @@ def test_record_area_drawing_spends_the_width_it_is_given() -> None:
screen = _dialog(_record(), shape=_loop_shape())
# Rows enough that the shape's proportions bind on the width, not the height.
screen.note_metrics(40, 40)
screen.handle("tab")
screen.handle("shift_tab") # the Area tab
lines = _plain(screen.render_body(width)).splitlines()
return max(len(line.rstrip()) for line in lines[_strip_end(lines) : -1])
@@ -383,30 +408,32 @@ def test_record_area_drawing_spends_the_width_it_is_given() -> None:
def test_record_area_tab_says_so_when_too_narrow_to_draw() -> None:
"""Below the drawing's floor the Area tab says why it is empty instead of squeezing."""
screen = _dialog(_record(), far_label="Far", shape=_loop_shape())
screen.handle("tab")
screen.handle("shift_tab") # the Area tab
body = _plain(screen.render_body(12))
assert not any(_is_braille(ch) for ch in body)
assert "no room" in body # cut at the edge like any row, but there
def test_record_without_a_shape_has_one_tab_and_nothing_to_switch() -> None:
"""No positioned hops, no Area tab: the strip collapses to a heading and Tab is inert."""
def test_record_without_a_shape_has_no_area_tab() -> None:
"""No positioned hops, no Area tab: Info and Route still switch between themselves."""
screen = _dialog(_record())
lines = _plain(screen.render_body(60)).splitlines()
assert "── Stats ──" in "\n".join(lines[: _strip_end(lines)])
assert "Area" not in "\n".join(lines)
assert "Tab" not in screen.footer_hint
screen.handle("tab")
assert screen._tab_index == 0
strip = "\n".join(lines[: _strip_end(lines)])
assert "Info" in strip and "Route" in strip and "Area" not in strip
screen.handle("shift_tab")
assert screen._tab == "Route"
def test_record_footer_names_only_what_each_tab_answers() -> None:
"""The Stats tab hints the cursor keys; the Area tab, a picture, only the switch and Esc."""
"""Info hints the cursor keys, Route only Enter (one row), Area only the switch and Esc."""
screen = _dialog(_record(), shape=_loop_shape())
assert screen.footer_hint == "Tab/⇧Tab switch · ↑↓ move · Enter select · Esc back"
screen.note_metrics(40, 10) # taller than the viewport: the pager earns its atom
assert "PgUp/PgDn scroll" in screen.footer_hint
screen.handle("tab")
screen.note_metrics(10, 24)
assert screen.footer_hint == "Tab/⇧Tab switch · Enter select · Esc back"
screen.handle("tab")
assert screen.footer_hint == "Tab/⇧Tab switch · Esc back"
screen.handle("down") # inert on the Area tab
assert screen._index == 0