The record page reads by its sections, and the ground drawing spends the page's width

Three body headings — Stats, Area walked, Route — each with the note that used to be a
faint caption under its block, so a page this tall can be skimmed by its landmarks. The
record's identity leads its stats: the spec walked and when it was set, then what the
walk measured. The area drawing takes the page's whole width and rows in step with it,
a quarter of the columns (half as tall as wide in braille dots), so a wider page is a
bigger shape rather than a padded one; rows a flat shape leaves blank are still
trimmed, so a tall box costs it nothing.

widgets.body_heading is THE form for a heading inside a page's body — accent title,
muted note — hoisted from the Time Machine's private copy.

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 03:10:01 -04:00
1 parent b56987b24b
commit 4b605c1da7
4 files changed
+113 -62

No files matched your search

+35 -27
View File
@@ -58,6 +58,7 @@ from .tui.screen import Screen
from .widgets import (
NodeResolver,
TypeOf,
body_heading,
name_rgb,
node_marker,
node_type_legend,
@@ -88,14 +89,16 @@ _GRAPH_ROWS = 3
#: colour, so the shape reads as one flat silhouette rather than two brightnesses.
_AREA_TONE: RGB = (148, 163, 184)
#: The area drawing's cell box, a block of its own under the stats: as wide as the page up
#: to a cap (proportions are kept, so past it a shape only gains blank canvas), a fixed
#: number of rows, and a floor of columns below which it is dropped rather than squeezed
#: into illegibility. It used to ride beside the stats in a third of the width, which left
#: no room for a label on any pin.
_AREA_MAX_W = 40
#: The area drawing's cell box, a block of its own under the stats: the page's whole width
#: (proportions are kept, so a wider page is a bigger shape, never a padded one), rows in
#: step with the width — a quarter of the columns, which in braille dots is a box half as
#: tall as it is wide — with a floor on the rows, and a width below which the drawing is
#: dropped rather than squeezed into illegibility. Rows a flat shape leaves blank are
#: trimmed (:func:`_drawn_rows`), so a tall box costs a flat shape nothing. It used to ride
#: beside the stats in a third of the width, which left no room for a label on any pin.
_AREA_MIN_W = 16
_AREA_ROWS = 8
_AREA_MIN_ROWS = 8
_AREA_ROWS_PER_COL = 4
#: 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.
_AREA_PAD_X = 8.0
@@ -438,17 +441,18 @@ class RecordScreen(Screen):
"""The walk's ground, as a block of its own between the stats and the route graph.
Empty when there is no drawable shape, or the page is too narrow for one to be
legible. Otherwise a blank line, the drawing trimmed to the rows something landed
on (:func:`_drawn_rows`), and a faint caption reading the drawing back the way the
graph's does. It used to ride beside the stats in a third of the width, which
squeezed the shape and left no cell for a label on any pin.
legible. Otherwise a blank line, the section's heading (its note reading the
drawing back the way the route graph's does), and the drawing itself — the page's
whole width, rows in step with it, trimmed to the rows something landed on
(:func:`_drawn_rows`). It used to ride beside the stats in a third of the width,
which squeezed the shape and left no cell for a label on any pin.
"""
if not self._shape or width < _AREA_MIN_W:
return []
lines = [""]
lines.extend(_drawn_rows(self._shape_lines(min(width, _AREA_MAX_W), _AREA_ROWS)))
caption = Text("area walked · north up · labels = hash byte", style="faint")
lines.append(render_to_ansi(caption, width, no_wrap=True))
heading = body_heading("Area walked", "north up · labels = hash byte")
lines = ["", render_to_ansi(heading, width, no_wrap=True)]
rows = max(_AREA_MIN_ROWS, width // _AREA_ROWS_PER_COL)
lines.extend(_drawn_rows(self._shape_lines(width, rows)))
return lines
def _shape_lines(self, cell_w: int, cell_h: int) -> list[str]:
@@ -550,18 +554,30 @@ class RecordScreen(Screen):
record = self._record
lines: list[str] = []
# Three sections, each under a body heading (THE form, widgets.body_heading): the
# stats, the ground the walk covered, and the route two ways. The headings are what
# lets a page this tall be skimmed — a reader after the route scrolls to "Route"
# rather than reading down through the drawing to find it.
lines.append(render_to_ansi(body_heading("Stats"), width, no_wrap=True))
# 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")
spec.append(f" ({record.width_bytes}-byte hops)", style="muted")
lines.extend(render_hanging(self._label("spec"), spec, width, indent=_LABEL_W))
when = Text(record.discovered_at.astimezone().strftime("%b %d %Y %H:%M"))
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())
lines.extend(self._area_lines(width))
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))
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))
lines.append("")
# The walk itself, on THE path widget, across the card's whole width. No ``route``
# label lane: the line under a route graph captioned "you → … → you" is the route,
# label lane: the line under a route graph headed "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
@@ -580,14 +596,6 @@ class RecordScreen(Screen):
dim_self=False,
)
lines.extend(render_to_ansi(line, width, no_wrap=True) for line in route.wrapped(width))
spec = Text(record.spec, style="brand")
spec.append(f" ({record.width_bytes}-byte hops)", style="muted")
lines.extend(render_hanging(self._label("spec"), spec, width, indent=_LABEL_W))
stamp = record.discovered_at.astimezone().strftime("%b %d %Y %H:%M")
when = Text(stamp)
when.append(f" · MeshTerm {record.app_version}", style="muted")
lines.append(render_to_ansi(self._lane("recorded", when), width, no_wrap=True))
return lines
+16 -20
View File
@@ -52,6 +52,7 @@ from .widgets import (
ContactsSort,
_age_seconds,
_recency_style,
body_heading,
format_ago,
highlighted_hash,
)
@@ -211,13 +212,6 @@ def _quarter_axis(frac: float) -> str:
return f"{round(frac * 24)} h"
def _heading(title: str, note: str) -> Text:
"""A section heading in the dashboard's voice: accent title, muted note."""
text = Text(title, style="accent")
text.append(f" · {note}", style="muted")
return text
class TimeMachineScreen(Screen):
"""One subject's history page: scrollable sections, ``w`` cycles the window."""
@@ -363,7 +357,7 @@ def _node_sections(
volume = bucketize(stamps, start, now, buckets)
out: list[RenderableType] = []
out.append(_heading("Volume", f"{len(observations)} receptions"))
out.append(body_heading("Volume", f"{len(observations)} receptions"))
out.extend(
axis_chart(
timeline_rows(volume, rows=_CHART_ROWS),
@@ -379,7 +373,7 @@ def _node_sections(
lo, hi = chart_span(medians)
rows = timeline_rows(medians, rows=_SNR_ROWS, style=_snr_cell_style)
out.append(Text())
out.append(_heading("SNR", "median dB per slice · grey line = 0"))
out.append(body_heading("SNR", "median dB per slice · grey line = 0"))
out.extend(
axis_chart(
rows,
@@ -393,7 +387,7 @@ def _node_sections(
out.append(Text())
out.append(
_heading("Rhythm", f"receptions by local time of day · {_slice_note(slice_minutes)}")
body_heading("Rhythm", f"receptions by local time of day · {_slice_note(slice_minutes)}")
)
out.extend(
axis_chart(
@@ -406,7 +400,7 @@ def _node_sections(
)
out.append(Text())
out.append(_heading("Record", "this window"))
out.append(body_heading("Record", "this window"))
first, last = observations[0].observed_at, observations[-1].observed_at
line = Text("heard ", style="muted")
line.append(f"first {_when_label(first)} · last {_when_label(last)}")
@@ -486,7 +480,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis
volume = bucketize(stamps, start, now, buckets)
out: list[RenderableType] = []
out.append(_heading("Activity", f"{len(stamps)} sent · traces + messages"))
out.append(body_heading("Activity", f"{len(stamps)} sent · traces + messages"))
out.extend(
axis_chart(
timeline_rows(volume, rows=_CHART_ROWS),
@@ -502,7 +496,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis
lo, hi = chart_span(medians)
rows = timeline_rows(medians, rows=_SNR_ROWS, style=_snr_cell_style)
out.append(Text())
out.append(_heading("Reach", "trace bottleneck dB per slice · grey line = 0"))
out.append(body_heading("Reach", "trace bottleneck dB per slice · grey line = 0"))
out.extend(
axis_chart(
rows,
@@ -516,7 +510,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis
out.append(Text())
out.append(
_heading("Rhythm", f"transmissions by local time of day · {_slice_note(slice_minutes)}")
body_heading("Rhythm", f"transmissions by local time of day · {_slice_note(slice_minutes)}")
)
out.extend(
axis_chart(
@@ -529,7 +523,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis
)
out.append(Text())
out.append(_heading("Ledger", "this window"))
out.append(body_heading("Ledger", "this window"))
first, last = stamps[0], stamps[-1]
line = Text("active ", style="muted")
line.append(f"first {_when_label(first)} · last {_when_label(last)}")
@@ -996,7 +990,7 @@ def _mesh_sections(
pkt_title, node_title = (
("Packets per hour", "Nodes per hour") if hourly else ("Packets per day", "Nodes per day")
)
out.append(_heading(pkt_title, "local hours" if hourly else "local days"))
out.append(body_heading(pkt_title, "local hours" if hourly else "local days"))
out.extend(
axis_chart(
timeline_rows(_day_columns(packets, chars), rows=_CHART_ROWS),
@@ -1009,7 +1003,7 @@ def _mesh_sections(
nodes = [d[2] for d in shown]
out.append(Text())
out.append(_heading(node_title, "distinct nodes heard"))
out.append(body_heading(node_title, "distinct nodes heard"))
out.extend(
axis_chart(
timeline_rows(_day_columns(nodes, chars), rows=_CHART_ROWS),
@@ -1024,7 +1018,9 @@ def _mesh_sections(
# keep their own finer width but share the day charts' gutter, so this chart's left
# edge lines up with the two above it.
out.append(Text())
out.append(_heading("Rhythm", f"packets by local time of day · {_slice_note(slice_minutes)}"))
out.append(
body_heading("Rhythm", f"packets by local time of day · {_slice_note(slice_minutes)}")
)
out.extend(
axis_chart(
timeline_rows(slots, rows=_CHART_ROWS),
@@ -1040,7 +1036,7 @@ def _mesh_sections(
# below (every heard node *is* a first-seen node, so the counts agree).
heard = ctx.repo.heard_nodes()
out.append(Text())
out.append(_heading("Arrivals", "nodes heard for the first time ever"))
out.append(body_heading("Arrivals", "nodes heard for the first time ever"))
if not arrivals:
out.append(Text("none in this window", style="muted"))
else:
@@ -1095,7 +1091,7 @@ def _mesh_sections(
total_nodes = sum(1 for n in heard if n.node)
busiest = max(all_days, key=lambda d: d[1])
out.append(Text())
out.append(_heading("Ledger", "everything ever recorded"))
out.append(body_heading("Ledger", "everything ever recorded"))
out.append(
Text.assemble(
("history ", "muted"),
+22
View File
@@ -917,6 +917,28 @@ def _format_age(secs: float | None) -> str:
return f"{int(secs // 604800)}w"
def body_heading(title: str, note: str = "") -> Text:
"""A section heading inside a screen's body: accent title, optional muted `` · note``.
THE form for a heading that sits *in* a page's prose or drawings (the Time Machine's
Volume / SNR / Rhythm, a record's Stats / Area walked / Route), as opposed to a grouped
list's ``── Label ──`` landmark (:func:`~meshterm.ui.menus.section_heading`), which
pins and is jumped to. The note reads the block back — its unit, its window, what its
labels mean — and is muted so the title stays the landmark.
Args:
title: The section's name, sentence case.
note: An aside after the roomy separator, or ``""`` for none.
Returns:
The heading as one styled line.
"""
text = Text(title, style="accent")
if note:
text.append(f" · {note}", style="muted")
return text
def format_ago(secs: float | None) -> str:
"""The relative-age *phrase* — ``now``, ``5m ago``, ``never`` — for running prose.
+40 -15
View File
@@ -109,11 +109,13 @@ def test_record_dialog_shows_stats_route_and_the_trace_action() -> None:
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."""
body = _plain(_dialog(_record()).render_body(60))
graph = body[: body.index("labels = hash byte")]
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]
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 graph.count("★") == 2 # our node marks both endpoints of the round trip
assert "labels = hash byte" in body # the graph's caption
assert any("⠀" <= ch <= "⣿" for ch in body) # braille edges are drawn
assert any("⠀" <= ch <= "⣿" for ch in graph) # braille edges are drawn
def test_record_graph_is_only_as_tall_as_one_lane_needs() -> None:
@@ -138,17 +140,17 @@ def test_record_dialog_route_runs_unlabelled_across_the_whole_card() -> None:
"""
dialog = _dialog(_record(route=tuple([HUB_ID, FAR_ID] * 4)))
body = _plain(dialog.render_body(60)).splitlines()
spec_at = next(i for i, line in enumerate(body) if line.startswith("spec"))
# The route's own first line: the last one before the spec that isn't a hanging fold.
route_at = next(i for i in range(spec_at - 1, 0, -1) if not body[i].startswith(" "))
route = body[route_at:spec_at]
# The route closes the Route section: it runs from under the graph's legend to the
# blank line before the action rows.
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
assert route[0].startswith("★") # our end opens the walk on the app-wide star…
assert route[-1].endswith("★") # …and closes it on the same
assert "Homestead" not in "".join(route) # never our name, and never our key
assert "Hilltop-Repeater" in "".join(route) # the hops themselves are named in full
assert len(route) > 1 # it folded rather than truncating…
# …every fold hanging under the step, and the labelled lanes resume at the spec.
# …every fold hanging under the step.
assert all(line.startswith(" ") for line in route[1:])
@@ -310,26 +312,49 @@ def test_record_draws_the_enclosed_area_under_the_stats_with_hash_byte_pins() ->
).splitlines()
first_blank = lines.index("")
stats = lines[:first_blank]
assert stats[0].startswith("score")
assert stats[0] == "Stats" # under its own heading…
assert stats[1].startswith("spec") and stats[2].startswith("recorded") # …identity first
assert stats[3].startswith("score")
assert not any(_is_braille(ch) for ch in "\n".join(stats)), "no drawing beside the lanes"
assert "Far" in "\n".join(stats) # the far-point name is a stat, not a drawing label
area = lines[first_blank + 1 : lines.index("", first_blank + 1)]
block = "\n".join(area)
assert area[0].startswith("Area walked") and "labels = hash byte" in area[0] # heading
block = "\n".join(area[1:])
assert any(_is_braille(ch) for ch in block) # the area, in braille
assert "★" in block # us pinned at the origin
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 area[-1].startswith("area walked") # the caption closes the block
graph_caption = next(i for i, line in enumerate(lines) if line.startswith("you → … → you"))
assert graph_caption > lines.index(area[-1]), "the route graph follows the drawing"
assert len(area) - 1 >= 8, "the drawing spends the rows it is given"
# The three section headings, in reading order: each opens its block right after a
# blank line, so a page this tall can be skimmed by its landmarks.
at = {
name: next(i for i, line in enumerate(lines) if line.split(" · ")[0] == name)
for name in ("Stats", "Area walked", "Route")
}
assert at["Stats"] < at["Area walked"] < at["Route"]
assert all(lines[i - 1] == "" for name, i in at.items() if name != "Stats")
assert at["Route"] > lines.index(area[-1]), "the route graph follows the drawing"
def test_record_area_drawing_spends_the_width_it_is_given() -> None:
"""The drawing is as wide as the page: a wider page is a bigger, not a padded, shape."""
narrow = _plain(_dialog(_record(), shape=_loop_shape()).render_body(40)).splitlines()
wide = _plain(_dialog(_record(), shape=_loop_shape()).render_body(72)).splitlines()
def drawn_width(lines: list[str]) -> int:
start = next(i for i, line in enumerate(lines) if line.startswith("Area walked")) + 1
block = lines[start : lines.index("", start)]
return max(len(line.rstrip()) for line in block)
assert drawn_width(wide) > drawn_width(narrow)
def test_record_drops_the_area_drawing_when_too_narrow() -> None:
"""Below the drawing's floor the block is left out; the far name stays in the stats."""
body = _plain(_dialog(_record(), far_label="Far", shape=_loop_shape()).render_body(14))
lines = body.splitlines()
assert "area walked" not in body # no drawing, no caption for one
assert "Area walked" not in body # no drawing, no heading for one
# The stats run straight into the blank line before the route graph; nothing pinned.
assert "★" not in "\n".join(lines[: lines.index("")])
assert "Far" in body # the far-point name survives the drop