The widgets CLAUDE.md names as THE widgets have public names

A leading underscore says "internal to this file, don't import me", and the
column-age formatter and the node glyph table wore one while seventeen modules
imported them and CLAUDE.md named them as the one place each concept lives.
format_age sits beside format_ago now (prose age, column age), NODE_GLYPHS and
DEFAULT_GLYPH beside them, age_seconds with the ages. A mechanical rename, 140
references across 24 files, CLAUDE.md's three lines with them so the guide and
the code move as one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5.1 committed 2026-09-13 01:13:18 -04:00
1 parent c974085384
commit 356ca6a94a
24 files changed
+105 -105

No files matched your search

+3 -3
View File
@@ -28,7 +28,7 @@ them instead of hand-rolling:
the language below).
- `ui/widgets.py` — `highlighted_hash` (THE key widget — shows a key, lights its hash),
`format_ago` (prose ages),
`_format_age` (column ages), `channel_glyph`, `_NODE_GLYPHS`, heard-age heat colouring.
`format_age` (column ages), `channel_glyph`, `NODE_GLYPHS`, heard-age heat colouring.
- `ui/theme.py` — `name_style`/`node_style` (per-node hues, hash-derived), `snr_style`,
the `you` white.
@@ -65,7 +65,7 @@ only). A behaviour value belongs in the preference registry, not as a module con
not in `config.toml`: a code constant a reader can't reach is a preference nobody has.
Relative ages: `format_ago` for prose ("now", "5m ago", "never" — never "now ago"),
`_format_age` for aligned columns ("now", "5m").
`format_age` for aligned columns ("now", "5m").
### Navigation — the stack
@@ -429,7 +429,7 @@ splitting safe has gone, because splitting is the machine face's job now.
quoting stays and always will (`script._escaped`): a node broadcasts its own name and a
stranger fills in a message body, and neither may end the record it sits in.
- **A time is an age** — `now`, `5m`, `3h`, `never` (`script.age`, delegating to
`widgets._format_age` so the two faces cannot drift). An absolute instant survives where
`widgets.format_age` so the two faces cannot drift). An absolute instant survives where
the instant *is* the fact (`script.stamp`, `fields.instant`): the device clock, an
appointment set with `--at`, a live capture's own `TIME`, every column under `--absolute`.
`--absolute` is an override of the `cli_time_format` **preference**, not a switch beside
+4 -4
View File
@@ -49,7 +49,7 @@ from ..ui.fields import ChannelRef, NodeRef
from ..ui.menus import Lane, column_header, fit_cells, section_heading
from ..ui.theme import name_style
from ..ui.tui import Choice, DeleteRequest, Separator
from ..ui.widgets import _NODE_GLYPHS, _age_seconds, _format_age, channel_glyph
from ..ui.widgets import NODE_GLYPHS, age_seconds, channel_glyph, format_age
from .base import Tool, ToolResult, register
if TYPE_CHECKING:
@@ -834,7 +834,7 @@ def _title(
#: The standard companion pink — the shared plain-node ``●`` colour — the contact dot's
#: hue: the shape (filled/hollow) marks history, the colour marks "a companion", and the
#: name beside it carries the person's own key-derived hue.
_COMPANION_DOT_STYLE = _NODE_GLYPHS[NODE_TYPE_CHAT][1]
_COMPANION_DOT_STYLE = NODE_GLYPHS[NODE_TYPE_CHAT][1]
def _append_marker(
@@ -910,7 +910,7 @@ def _append_body(text: Text, body: str, key_of: NameKeyResolver) -> None:
def _ago(when: Any) -> str:
"""The column age for a message time, through THE grammar (``_format_age``).
"""The column age for a message time, through THE grammar (``format_age``).
One deliberate difference from the widget: a missing or naive timestamp (a stray one
from the wire) reads as a *blank* lane rather than ``never`` — the picker wants an
@@ -918,7 +918,7 @@ def _ago(when: Any) -> str:
"""
if getattr(when, "tzinfo", None) is None:
return ""
return _format_age(_age_seconds(when))
return format_age(age_seconds(when))
def _channel_ref(idx: int | None, label: str, secret: bytes | None) -> ChannelRef:
+2 -2
View File
@@ -488,13 +488,13 @@ def _target_items(contacts: list[Contact], admin: Contact) -> list:
from ..ui.theme import name_style
from ..ui.tui import Choice
from ..ui.widgets import _DEFAULT_GLYPH, _NODE_GLYPHS
from ..ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS
def row(contact: Contact) -> Any:
# The type mark keeps its own fixed hue; the *name* takes the node's key-derived
# colour like every other list of nodes (a style on the Text itself would be the
# row's base and would paint the name the type's colour too).
glyph, glyph_style = _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH)
label = Text()
label.append(f"{glyph} ", style=glyph_style)
label.append(
+2 -2
View File
@@ -45,7 +45,7 @@ def admin_picker_rows(ctx: AppContext, contacts: list[Contact]) -> tuple[list, l
from .menus import section_heading
from .theme import name_style
from .tui import Choice
from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS
from .widgets import DEFAULT_GLYPH, NODE_GLYPHS
candidates = [c for c in contacts if (c.public_key or c.key_prefix).strip()]
if not candidates:
@@ -55,7 +55,7 @@ def admin_picker_rows(ctx: AppContext, contacts: list[Contact]) -> tuple[list, l
# The type mark keeps its own fixed hue; the *name* takes the node's key-derived
# colour like every other list of nodes (a style on the Text itself would be the
# row's base and would paint the name the type's colour too).
glyph, glyph_style = _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH)
label = Text()
label.append(f"{glyph} ", style=glyph_style)
label.append(
+3 -3
View File
@@ -70,7 +70,7 @@ from .menus import (
from .qr import share_screen
from .theme import glyph
from .tui import CANCEL, Choice, SelectScreen, Separator
from .widgets import _age_seconds, _format_age, channel_glyph, format_ago
from .widgets import age_seconds, channel_glyph, format_age, format_ago
if TYPE_CHECKING:
from ..context import AppContext
@@ -564,7 +564,7 @@ def _slot_text(ctx: AppContext, slot: ChannelSlot, stats: _LiveStats, name_w: in
# no messages drew the same glyph twice meaning different things.
text.append(f"{'○':>{_COUNT_WIDTH}}", style="muted")
text.append(" ")
age = _format_age(_age_seconds(st.last_at)) if st is not None and st.last_at else ""
age = format_age(age_seconds(st.last_at)) if st is not None and st.last_at else ""
text.append(f"{age:>{_AGE_WIDTH}}", style="muted")
text.append(" ")
# The shared peak across all channels, so every row's sparkline uses one scale.
@@ -676,7 +676,7 @@ def _detail_summary(ctx: AppContext, slot: ChannelSlot, stats: _LiveStats) -> st
if _is_muted(ctx, slot):
parts.append("muted")
if st is not None and st.last_at is not None:
parts.append(f"last {format_ago(_age_seconds(st.last_at))}")
parts.append(f"last {format_ago(age_seconds(st.last_at))}")
width = get_platform().readable_cols
while len(parts) > 1 and cell_len(" · ".join(parts)) > width:
parts.pop()
+9 -9
View File
@@ -34,12 +34,12 @@ from .menus import fit_cells
from .theme import name_style
from .tui.select import Choice, SelectScreen, Separator
from .widgets import (
_DEFAULT_GLYPH,
_NODE_GLYPHS,
DEFAULT_GLYPH,
NODE_GLYPHS,
ContactsSort,
_age_seconds,
_format_age,
_recency_style,
age_seconds,
format_age,
highlighted_hash,
)
@@ -270,7 +270,7 @@ def _header(
def _lane_cell(row: ContactRow, lane: ContactLane) -> Text:
"""One row's value for one lane, right-aligned into the lane's width and styled by kind.
An ``age`` lane draws the relative age in the column form (:func:`_format_age`) under
An ``age`` lane draws the relative age in the column form (:func:`format_age`) under
recency heat, so a fresh value glows and a cold one greys — the same reading whatever
the event the lane times. A ``count`` lane draws the tally muted, or a faint ``—`` where
there is nothing to count, and clamps so a runaway tally can't widen the column.
@@ -280,8 +280,8 @@ def _lane_cell(row: ContactRow, lane: ContactLane) -> Text:
if value is None:
return Text(f"{'—':>{lane.width}}", style="faint")
return Text(f"{min(value, 99999):>{lane.width}}", style="muted")
secs = _age_seconds(value)
return Text(f"{_format_age(secs):>{lane.width}}", style=_recency_style(secs))
secs = age_seconds(value)
return Text(f"{format_age(secs):>{lane.width}}", style=_recency_style(secs))
def _you_lane(
@@ -353,7 +353,7 @@ def _lane(
"""
if row.you:
return _you_lane(row, name_w, prefix_bytes, hash_w, lanes)
glyph, glyph_style = _NODE_GLYPHS.get(row.node_type, _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(row.node_type, DEFAULT_GLYPH)
text = Text(no_wrap=True, overflow="ellipsis")
text.append(glyph, style=glyph_style)
text.append(" ")
@@ -413,7 +413,7 @@ def _ordered(
value = getattr(row, lane.field, None)
if lane.kind == "count":
return value or 0
secs = _age_seconds(value)
secs = age_seconds(value)
return secs if secs is not None else float("inf")
ordered = sorted(rows, key=key_name)
+2 -2
View File
@@ -34,7 +34,7 @@ from .contactlist import SORT_COLUMNS, SORT_OPENS_ASCENDING, ContactListScreen,
from .menus import icon_lane, marked_label, run_steps, section_heading
from .tui import CANCEL, DM_BYTE_LIMIT, Choice, SelectScreen, Separator
from .watchtower_screen import contact_watch_key
from .widgets import ContactsSort, _age_seconds, contact_packets, format_ago
from .widgets import ContactsSort, age_seconds, contact_packets, format_ago
if TYPE_CHECKING:
from ..context import AppContext
@@ -323,7 +323,7 @@ def _done_row(message: QueuedMessage, lane: int = _MARK_LANE) -> Text:
when = message.finished or message.created
verb = "delivered" if message.status == DELIVERED else "gave up"
row.append(
f" · {verb} {format_ago(_age_seconds(when))}"
f" · {verb} {format_ago(age_seconds(when))}"
f" · {message.attempts} attempt{'s' if message.attempts != 1 else ''}",
style="muted",
)
+8 -8
View File
@@ -117,10 +117,10 @@ from .theme import mark_rgb, name_style, snr_style
from .tui.render import crop_cells, render_hanging, render_lines, render_to_ansi
from .tui.screen import CANCEL, ListWindow, Screen
from .widgets import (
_DEFAULT_GLYPH,
_NODE_GLYPHS,
_age_seconds,
DEFAULT_GLYPH,
NODE_GLYPHS,
_recency_style,
age_seconds,
format_ago,
highlighted_hash,
node_type_legend,
@@ -1192,7 +1192,7 @@ async def open_node_detail(
glyph, glyph_style = SELF_MARK
name_hue = "you"
else:
glyph, glyph_style = _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(node_type, DEFAULT_GLYPH)
name_hue = name_style(name, key) if name else "muted"
header = Text()
header.append(f"{glyph} ", style=glyph_style)
@@ -1235,7 +1235,7 @@ async def open_node_detail(
# one node. Only a node that is no contact, or one whose merge could not read our
# history, falls back to the raw reception stat.
heard_at = contact.last_seen if contact else None
secs = _age_seconds(heard_at or (hn.last_seen if hn else None))
secs = age_seconds(heard_at or (hn.last_seen if hn else None))
heard_val = Text(format_ago(secs), style=_recency_style(secs))
if first_heard is not None:
heard_val.append(f" · first {first_heard.astimezone():%b %d %Y}", style="muted")
@@ -1759,10 +1759,10 @@ def _cluster_presentation(members: tuple[str, ...], type_of) -> _Cluster: # noq
types = {type_of(m) for m in members}
only = next(iter(types)) if len(types) == 1 else None
if only is not None:
glyph, color = _NODE_GLYPHS.get(only, _DEFAULT_GLYPH)
glyph, color = NODE_GLYPHS.get(only, DEFAULT_GLYPH)
kind = NODE_TYPE_LABELS.get(only, "node")
else:
glyph, color = _DEFAULT_GLYPH
glyph, color = DEFAULT_GLYPH
kind = "node"
return _Cluster(glyph=glyph, color=color, label=f"{len(members)} {kind}s", rgb=mark_rgb(color))
@@ -1953,7 +1953,7 @@ def _routes_view(
return (cluster.glyph, cluster.color) if cluster is not None else base_glyph_of(node)
glyph_of = _with_target_glyph(
cluster_glyph_of, _NODE_GLYPHS.get(type_of(canonical_target), _DEFAULT_GLYPH)
cluster_glyph_of, NODE_GLYPHS.get(type_of(canonical_target), DEFAULT_GLYPH)
)
return _RoutesView(
routes=routes,
+5 -5
View File
@@ -60,11 +60,11 @@ from .trace_screen import snr_bar
from .tui.render import render_lines, render_to_ansi
from .tui.screen import Screen
from .widgets import (
_DEFAULT_GLYPH,
_NODE_GLYPHS,
DEFAULT_GLYPH,
NODE_GLYPHS,
NameKeyResolver,
TypeOf,
_age_seconds,
age_seconds,
format_ago,
highlighted_hash,
node_type_legend,
@@ -727,7 +727,7 @@ class PacketViewer(Screen):
icon, class_label = class_chrome(entry)
rows.append(("class", Text(f"{icon} {class_label}")))
secs = _age_seconds(entry.when)
secs = age_seconds(entry.when)
heard = Text(entry.when.astimezone().strftime("%b %d %H:%M:%S"))
heard.append(f" ({format_ago(secs)})", style="muted")
rows.append(("heard", heard))
@@ -779,7 +779,7 @@ class PacketViewer(Screen):
node_type = self._type_of(entry.node)
if node_type is None:
return UNKNOWN_MARK
return _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH)
return NODE_GLYPHS.get(node_type, DEFAULT_GLYPH)
def _tail_rows(self, entry: PacketEntry) -> list[tuple[str, RenderableType]]:
"""The rows below the route graph: location, the message/ack fields, the raw dump."""
+2 -2
View File
@@ -79,7 +79,7 @@ from .pathline import PathLine, cut_to, path_line
from .theme import snr_style
from .tui.render import query_line, render_lines, render_to_ansi
from .tui.screen import ListWindow, Screen
from .widgets import NodeResolver, _age_seconds, _format_age, identity_label, path_text
from .widgets import NodeResolver, age_seconds, format_age, identity_label, path_text
#: Sentinel spec meaning "no forced path — let the device route" (the trace screen's
#: empty-spec convention). Only meaningful in target mode; a path walk has no target
@@ -551,7 +551,7 @@ class PathComposerScreen(Screen):
text.append(" ↔ ", style="muted")
text.append(f"{snr:+.1f} dB", style=snr_style(snr))
text.append(f" {link.samples}×", style="muted")
age = _format_age(_age_seconds(link.last_seen))
age = format_age(age_seconds(link.last_seen))
text.append(f" · {age}", style="muted")
tags = "".join(_SOURCE_TAGS[s] for s in sorted(link.sources & _SOURCE_TAGS.keys()))
if tags:
+2 -2
View File
@@ -285,7 +285,7 @@ async def purge_contacts(ctx: AppContext, self_key: str) -> int:
return await _sweep(ctx, self_key, victims)
def _age_seconds(scored: ScoredContact) -> float | None:
def age_seconds(scored: ScoredContact) -> float | None:
"""A scored contact's last-heard age in seconds, or ``None`` if it was never heard."""
days = scored.signals.heard_age_days
return None if days is None else days * _DAY
@@ -319,7 +319,7 @@ def victims_for(
return sweep_candidates(ranked, keep=math.ceil(len(sweepable) * int(value) / 100))
matched = []
for scored in sweepable:
age = _age_seconds(scored)
age = age_seconds(scored)
if value == _NEVER:
if age is None:
matched.append(scored)
+5 -5
View File
@@ -182,7 +182,7 @@ def stamp(when: datetime | None) -> str:
Stored times are timezone-aware UTC; a naive one is a time whose offset we do not
actually know, which is not a fact and so reads as absent — the same rule
:func:`~meshterm.ui.widgets._age_seconds` applies to ages.
:func:`~meshterm.ui.widgets.age_seconds` applies to ages.
Args:
when: The instant to format.
@@ -201,7 +201,7 @@ def age(when: datetime | None, *, absent: str = NONE) -> str:
The default time form, and the reason is the premise change: a person at a prompt
reading ``2026-09-07T19:58:53-04:00`` is doing arithmetic to answer "recently?", which
is the question they typed the command to ask. Delegates to
:func:`~meshterm.ui.widgets._format_age` so the two faces cannot drift apart.
:func:`~meshterm.ui.widgets.format_age` so the two faces cannot drift apart.
Args:
when: The instant to age. A naive datetime has no offset we know, so it reads as
@@ -214,10 +214,10 @@ def age(when: datetime | None, *, absent: str = NONE) -> str:
Returns:
The age, or ``absent``.
"""
from .widgets import _age_seconds, _format_age
from .widgets import age_seconds, format_age
seconds = _age_seconds(when)
return absent if seconds is None else _format_age(seconds)
seconds = age_seconds(when)
return absent if seconds is None else format_age(seconds)
def number(value: Any, spec: str = "") -> str:
+1 -1
View File
@@ -76,7 +76,7 @@ def specimen_lines() -> list[RenderableType]:
lines.append(status)
# The node-type marks in the theme's own ``type.*`` entries — the same styles every
# typed node in the app is drawn in (ui.widgets._NODE_GLYPHS), so this row *is* the
# typed node in the app is drawn in (ui.widgets.NODE_GLYPHS), so this row *is* the
# marker language rather than a restatement of it. The star and the unknown ring have
# no type of their own: they take the ``you`` white and ``muted`` grey they carry
# everywhere else.
+1 -1
View File
@@ -139,7 +139,7 @@ MESH_THEME = Theme(
"batt.flash": "not bold #000000 on #dc2626",
"batt.flash.off": "bold #f87171",
# The node-type *marks* — THE colours behind ● ▲ ■ ◉ wherever a typed node is
# drawn (see ui.widgets._NODE_GLYPHS), and the map's own marker language: clients
# drawn (see ui.widgets.NODE_GLYPHS), and the map's own marker language: clients
# the loud pink, repeaters the calmer violet, rooms a white square, sensors an
# orange ringed dot. Named styles rather than raw hex so the 16-slot console picks
# its slot *deliberately* — a naive downsample of the violet lands on grey, which
+4 -4
View File
@@ -50,8 +50,8 @@ from .tui.screen import CANCEL, Screen
from .tui.select import Choice, Separator
from .widgets import (
ContactsSort,
_age_seconds,
_recency_style,
age_seconds,
body_heading,
format_ago,
highlighted_hash,
@@ -404,7 +404,7 @@ def _node_sections(
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)}")
line.append(f" ({format_ago(_age_seconds(last))})", style="muted")
line.append(f" ({format_ago(age_seconds(last))})", style="muted")
out.append(line)
snrs = [p[1] for p in snr_pairs]
if snrs:
@@ -527,7 +527,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis
first, last = stamps[0], stamps[-1]
line = Text("active ", style="muted")
line.append(f"first {_when_label(first)} · last {_when_label(last)}")
line.append(f" ({format_ago(_age_seconds(last))})", style="muted")
line.append(f" ({format_ago(age_seconds(last))})", style="muted")
out.append(line)
if ledger.trace_total:
@@ -1073,7 +1073,7 @@ def _mesh_sections(
)
)
for key, name, first in listed:
secs = _age_seconds(first)
secs = age_seconds(first)
line = Text(" ", no_wrap=True, overflow="ellipsis")
line.append(
fit_cells(name or "unknown", name_w),
+7 -7
View File
@@ -75,7 +75,7 @@ from .theme import mark_rgb, name_style, snr_style
from .trace_screen import snr_bar
from .tui.render import crop_cells, query_line, render_to_ansi
from .tui.screen import ListWindow, Screen
from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS, _format_age, highlighted_hash
from .widgets import DEFAULT_GLYPH, NODE_GLYPHS, format_age, highlighted_hash
if TYPE_CHECKING:
from ..context import AppContext
@@ -752,7 +752,7 @@ class WalkScreen(Screen):
line.append(f" · {ring} hop{'s' if ring != 1 else ''} out", style="muted")
if contact is not None and contact.last_seen is not None:
secs = max(0.0, (utcnow() - contact.last_seen).total_seconds())
line.append(f" · heard {_format_age(secs)}", style="muted")
line.append(f" · heard {format_age(secs)}", style="muted")
return line
def _short_hash(self, node: str) -> str:
@@ -1134,8 +1134,8 @@ class WalkScreen(Screen):
legend = Text()
for (glyph, colour), word in (
(SELF_MARK, " you "),
(_NODE_GLYPHS[NODE_TYPE_REPEATER], " repeater "),
(_DEFAULT_GLYPH, " node "),
(NODE_GLYPHS[NODE_TYPE_REPEATER], " repeater "),
(DEFAULT_GLYPH, " node "),
(UNKNOWN_MARK, " unknown"),
):
legend.append(glyph, style=colour)
@@ -1280,7 +1280,7 @@ class WalkScreen(Screen):
row.append(f" {min(link.samples, 999):>3}×", style="muted")
tags = "".join(_SOURCE_TAGS[s] for s in sorted(link.sources & _SOURCE_TAGS.keys()))
row.append(f" {tags:<4}", style="faint")
age = _format_age(
age = format_age(
max(0.0, (utcnow() - link.last_seen).total_seconds())
if link.last_seen is not None and getattr(link.last_seen, "tzinfo", None)
else None
@@ -1392,7 +1392,7 @@ class WalkScreen(Screen):
def _glyph(self, node: str) -> tuple[str, str]:
"""A node's mark: the type glyph and the colour that type wears app-wide.
The shared marks (:data:`~meshterm.ui.widgets._NODE_GLYPHS`) and the shared
The shared marks (:data:`~meshterm.ui.widgets.NODE_GLYPHS`) and the shared
``type.*`` colours behind them, so a node is pinned here in exactly the glyph and
hue the map, the route graph and the contact list pin it in — ``▲`` violet for a
repeater, ``■`` for a room, ``◉`` for a sensor, ``●`` pink for a plain node, our
@@ -1410,7 +1410,7 @@ class WalkScreen(Screen):
contact = self._contacts.get(node)
if contact is None:
return UNKNOWN_MARK
return _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH)
return NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH)
def _label(self, node: str) -> str:
"""A node's display name: its own name for us, contact name, or short hash."""
+8 -8
View File
@@ -27,7 +27,7 @@ from ..services.trace_runner import make_name_key_resolver
from .menus import icon_lane, icon_mark, marked_label, section_heading
from .theme import name_style
from .tui import Choice, Separator
from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS, _age_seconds, _format_age
from .widgets import DEFAULT_GLYPH, NODE_GLYPHS, age_seconds, format_age
if TYPE_CHECKING:
from ..context import AppContext
@@ -254,10 +254,10 @@ def _alert_lanes(
row.append("○ ", style="muted")
else:
row.append("● ", style="err")
age = _format_age(_age_seconds(alert.when))
age = format_age(age_seconds(alert.when))
row.append(f"{age:>5} ", style="muted")
row.append(alert.kind.ljust(10), style=_KIND_STYLES.get(alert.kind, "brand"))
glyph, glyph_style = _NODE_GLYPHS.get(type_of(alert.label), _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(type_of(alert.label), DEFAULT_GLYPH)
row.append(f"{glyph} ", style="muted" if alert.acked else glyph_style)
if alert.acked:
row.append(alert.label, style="muted")
@@ -282,7 +282,7 @@ def _watched_row(entry: WatchedNode, type_of: Callable[[str], int | None]) -> Te
glyph — and the name takes its key-derived hue (the entry's 12-hex watch key).
"""
node_type = entry.node_type if entry.node_type is not None else type_of(entry.key)
glyph, glyph_style = _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(node_type, DEFAULT_GLYPH)
row = Text()
row.append(f"{glyph} ", style=glyph_style)
row.append(entry.name, style=name_style(entry.name, entry.key))
@@ -292,7 +292,7 @@ def _watched_row(entry: WatchedNode, type_of: Callable[[str], int | None]) -> Te
if entry.silent_since is not None:
row.append(" · ⚠ silent", style="err")
elif entry.last_heard is not None:
row.append(f" · heard {_format_age(_age_seconds(entry.last_heard))}", style="muted")
row.append(f" · heard {format_age(age_seconds(entry.last_heard))}", style="muted")
return row
@@ -318,19 +318,19 @@ async def _pick_node(ctx: AppContext, contacts: list[Contact]) -> None:
return
def recency(pair: tuple[str, Contact]) -> float:
seen = _age_seconds(pair[1].last_seen)
seen = age_seconds(pair[1].last_seen)
return seen if seen is not None else float("inf")
items: list = []
for key, contact in sorted(candidates, key=recency):
glyph, glyph_style = _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH)
glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH)
row = Text()
row.append(f"{glyph} ", style=glyph_style)
row.append(
contact.name,
style=name_style(contact.name, contact.public_key or contact.key_prefix),
)
row.append(f" heard {_format_age(_age_seconds(contact.last_seen))}", style="muted")
row.append(f" heard {format_age(age_seconds(contact.last_seen))}", style="muted")
items.append(Choice(row, (key, contact)))
picked = await session.select(
"Watch a node",
+14 -14
View File
@@ -636,7 +636,7 @@ def route_graph_style(
if type_of is not None:
node_type = type_of(node)
if node_type is not None:
return _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH)
return NODE_GLYPHS.get(node_type, DEFAULT_GLYPH)
named = resolve(node)
return NODE_MARK if named and named != node else UNKNOWN_MARK
@@ -846,13 +846,13 @@ def stats_panel(
# The colours are the theme's ``type.*`` entries rather than raw hex, so the 16-slot console
# picks its slot deliberately (the violet would otherwise downsample to grey, and a repeater
# would read as an unknown node); on the regular platform they *are* the map's hues.
_NODE_GLYPHS: dict[int, tuple[str, str]] = {
NODE_GLYPHS: dict[int, tuple[str, str]] = {
NODE_TYPE_REPEATER: (REPEATER_MARK[0], "type.repeater"),
NODE_TYPE_ROOM: ("■", "type.room"),
NODE_TYPE_SENSOR: ("◉", "type.sensor"),
NODE_TYPE_CHAT: (NODE_MARK[0], "type.node"),
}
_DEFAULT_GLYPH: tuple[str, str] = (NODE_MARK[0], "type.node")
DEFAULT_GLYPH: tuple[str, str] = (NODE_MARK[0], "type.node")
def node_marker(node_type: int | None) -> tuple[str, RGB]:
@@ -860,13 +860,13 @@ def node_marker(node_type: int | None) -> tuple[str, RGB]:
The shared node-type marks (``▲`` repeater, ``■`` room, ``◉`` sensor, ``●`` plain
node) in the map's own colours, minted here for a braille raster the way
:data:`_NODE_GLYPHS` mints them for a Rich row — so a spatial drawing pins its nodes
:data:`NODE_GLYPHS` mints them for a Rich row — so a spatial drawing pins its nodes
in the exact glyphs and hues the map and the nodes list use. Both read the same
``type.*`` theme entry (through :func:`~meshterm.ui.theme.mark_rgb` here), so the
raster and the row agree on whatever the platform's palette can afford. An unknown
type falls back to the plain node mark.
"""
glyph, style = _NODE_GLYPHS.get(node_type or -1, _DEFAULT_GLYPH)
glyph, style = NODE_GLYPHS.get(node_type or -1, DEFAULT_GLYPH)
return glyph, mark_rgb(style)
@@ -890,14 +890,14 @@ _HEAT_STOPS: tuple[tuple[float, tuple[int, int, int]], ...] = (
_RECENCY_NEVER = "#64748b" # never heard — the coldest slate
def _age_seconds(when: datetime | None) -> float | None:
def age_seconds(when: datetime | None) -> float | None:
"""Seconds since ``when`` (aware UTC), or ``None`` when unknown/naive."""
if when is None or getattr(when, "tzinfo", None) is None:
return None
return max(0.0, (utcnow() - when).total_seconds())
def _format_age(secs: float | None) -> str:
def format_age(secs: float | None) -> str:
"""A compact relative age — ``now``, ``5m``, ``3h``, ``2d``, ``4w`` — or ``never``."""
if secs is None:
return "never"
@@ -941,9 +941,9 @@ def format_ago(secs: float | None) -> str:
sighting reads as bare ``now`` and an unknown one as bare ``never`` (neither takes
the suffix — "now ago" is nonsense), while any measured age reads ``5m ago``.
Callers embedding an age in a sentence or parenthetical use this;
:func:`_format_age` stays the bare column form for aligned age lanes.
:func:`format_age` stays the bare column form for aligned age lanes.
"""
age = _format_age(secs)
age = format_age(secs)
return age if age in ("now", "never") else f"{age} ago"
@@ -1142,7 +1142,7 @@ def _sort_header(label: str, column: str, sort: ContactsSort) -> str:
def node_type_legend(indent: str = "") -> Text:
"""The one-line key to the node-type marks: ``★ you ▲ repeater ● node …``.
Every glyph in its shared map colour (see :data:`_NODE_GLYPHS`), each named muted after
Every glyph in its shared map colour (see :data:`NODE_GLYPHS`), each named muted after
it. THE legend for any surface that draws typed node markers — the contacts list under its
table, the route graph under its lanes — so one glyph means one thing app-wide.
@@ -1153,7 +1153,7 @@ def node_type_legend(indent: str = "") -> Text:
legend.append(SELF_MARK[0], style=SELF_MARK[1])
legend.append(" you", style="muted")
for node_type in (NODE_TYPE_REPEATER, NODE_TYPE_CHAT, NODE_TYPE_ROOM, NODE_TYPE_SENSOR):
glyph, color = _NODE_GLYPHS[node_type]
glyph, color = NODE_GLYPHS[node_type]
legend.append(" ")
legend.append(glyph, style=color)
legend.append(f" {NODE_TYPE_LABELS[node_type]}", style="muted")
@@ -1346,13 +1346,13 @@ def contacts_table(
)
table.add_section()
for c in ordered_contacts(contacts, counts, sort):
secs = _age_seconds(c.last_seen)
glyph, glyph_style = _NODE_GLYPHS.get(c.node_type, _DEFAULT_GLYPH)
secs = age_seconds(c.last_seen)
glyph, glyph_style = NODE_GLYPHS.get(c.node_type, DEFAULT_GLYPH)
pkts = contact_packets(c, counts)
table.add_row(
Text(glyph, style=glyph_style),
Text(c.name, style=name_style(c.name, c.public_key or c.key_prefix)),
Text(_format_age(secs), style=_recency_style(secs)),
Text(format_age(secs), style=_recency_style(secs)),
Text(str(pkts), style="muted") if pkts else Text("—", style="faint"),
highlighted_hash(c.public_key, prefix_bytes) if c.public_key else unknown,
)
+2 -2
View File
@@ -95,7 +95,7 @@ from meshterm.ui.tui.prompt import CountdownDialog
from meshterm.ui.tx_screen import TxSweepScreen
from meshterm.ui.walk_screen import WalkScreen
from meshterm.ui.widgets import (
_NODE_GLYPHS,
NODE_GLYPHS,
ContactsSort,
highlighted_hash,
node_marker,
@@ -276,7 +276,7 @@ def _archived(cols: int, rows: int) -> Screen:
def _node_detail_header() -> Text:
# Through the app's own marker and name styles, not a hand-spelled hex: the gallery is
# a specimen of what the platform draws, so a stub colour would hide a palette bug.
glyph, glyph_style = _NODE_GLYPHS[NODE_TYPE_REPEATER]
glyph, glyph_style = NODE_GLYPHS[NODE_TYPE_REPEATER]
header = Text(f"{glyph} ", style=glyph_style)
header.append("Hilltop-Repeater", style=name_style("Hilltop-Repeater", _HUB_KEY))
header.append(" repeater", style="muted")
+2 -2
View File
@@ -363,7 +363,7 @@ def test_picker_rows_hue_each_name_by_its_own_key(tui_ctx) -> None:
"""
from meshterm.ui.admin_picker import admin_picker_rows
from meshterm.ui.theme import name_style
from meshterm.ui.widgets import _NODE_GLYPHS
from meshterm.ui.widgets import NODE_GLYPHS
contacts = [
Contact(name="Hub-North", public_key="a1" * 32, key_prefix="a1b2c3d4", node_type=2),
@@ -372,7 +372,7 @@ def test_picker_rows_hue_each_name_by_its_own_key(tui_ctx) -> None:
rows, candidates = admin_picker_rows(tui_ctx, contacts)
assert [c.name for c in candidates] == ["Hub-North", "Hub-South"]
glyph, glyph_style = _NODE_GLYPHS[2]
glyph, glyph_style = NODE_GLYPHS[2]
titles = {str(row.value): row.title for row in rows if getattr(row, "value", None) is not None}
hues = set()
for contact in contacts:
+2 -2
View File
@@ -126,7 +126,7 @@ def test_stamp_is_absolute_local_iso_to_the_second() -> None:
def test_stamp_reads_an_unknown_offset_as_absent() -> None:
"""A naive datetime is a time whose offset we don't know, which is not a fact.
The same rule :func:`~meshterm.ui.widgets._age_seconds` applies to relative ages.
The same rule :func:`~meshterm.ui.widgets.age_seconds` applies to relative ages.
"""
assert script.stamp(None) == script.NONE
assert script.stamp(datetime(2026, 9, 7, 22, 22, 41)) == script.NONE
@@ -162,7 +162,7 @@ def test_a_time_is_an_age_unless_the_instant_is_itself_the_fact() -> None:
def test_the_age_ladder_steps_where_a_person_would_step(seconds: int, expected: str) -> None:
"""``now``, ``5m``, ``3h``, ``2d``, ``4w`` — the menu's own column ladder.
Delegated to :func:`~meshterm.ui.widgets._format_age` rather than re-derived, so the
Delegated to :func:`~meshterm.ui.widgets.format_age` rather than re-derived, so the
two faces of the same age cannot drift apart.
"""
assert script.age(datetime.now(timezone.utc) - timedelta(seconds=seconds)) == expected
+5 -5
View File
@@ -872,7 +872,7 @@ def test_picker_glyph_reflects_resolved_node_type() -> None:
"""A node with no stored type takes its contact's type for the leading glyph."""
from meshterm.core.models import NODE_TYPE_REPEATER
from meshterm.ui.timemachine_screen import MESH, SELF
from meshterm.ui.widgets import _DEFAULT_GLYPH, _NODE_GLYPHS
from meshterm.ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS
listed = _heard_nodes() # every node's stored node_type is None
repeater = listed[0][0].node # Alice's id — the one the resolver knows as a repeater
@@ -882,8 +882,8 @@ def test_picker_glyph_reflects_resolved_node_type() -> None:
c.value[0]: c.label.plain[0] for c in screen._choices() if c.value not in (MESH, SELF)
}
# The resolved repeater takes ▲; a node the resolver can't place keeps the plain-node ●.
assert glyphs[repeater] == _NODE_GLYPHS[NODE_TYPE_REPEATER][0]
assert glyphs[listed[1][0].node] == _DEFAULT_GLYPH[0]
assert glyphs[repeater] == NODE_GLYPHS[NODE_TYPE_REPEATER][0]
assert glyphs[listed[1][0].node] == DEFAULT_GLYPH[0]
def test_picker_stored_node_type_wins_over_the_resolver() -> None:
@@ -892,7 +892,7 @@ def test_picker_stored_node_type_wins_over_the_resolver() -> None:
from meshterm.core.models import NODE_TYPE_REPEATER, NODE_TYPE_SENSOR, HeardNode
from meshterm.ui.timemachine_screen import MESH, SELF
from meshterm.ui.widgets import _NODE_GLYPHS
from meshterm.ui.widgets import NODE_GLYPHS
sensor = HeardNode(
node="ab" * 6,
@@ -906,7 +906,7 @@ def test_picker_stored_node_type_wins_over_the_resolver() -> None:
)
screen = _picker([(sensor, "Probe")], type_of=lambda _node: NODE_TYPE_REPEATER)
glyph = next(c.label.plain[0] for c in screen._choices() if c.value not in (MESH, SELF))
assert glyph == _NODE_GLYPHS[NODE_TYPE_SENSOR][0]
assert glyph == NODE_GLYPHS[NODE_TYPE_SENSOR][0]
def test_picker_resort_keeps_the_highlight_on_its_node_and_the_filter() -> None:
+5 -5
View File
@@ -214,11 +214,11 @@ def test_watched_row_type_glyph_and_hued_name(tmp_path: Path) -> None:
from meshterm.core.watch_store import WatchedNode
from meshterm.ui.theme import name_style
from meshterm.ui.watchtower_screen import _watched_row
from meshterm.ui.widgets import _NODE_GLYPHS
from meshterm.ui.widgets import NODE_GLYPHS
entry = WatchedNode(key="a1" * 6, name="Roof", node_type=2, last_heard=utcnow())
row = _watched_row(entry, lambda key: None)
glyph, glyph_style = _NODE_GLYPHS[2]
glyph, glyph_style = NODE_GLYPHS[2]
assert row.plain.startswith(f"{glyph} Roof")
assert any(s.style == glyph_style and s.start == 0 for s in row.spans)
name_at = row.plain.index("Roof")
@@ -260,7 +260,7 @@ def test_alert_row_leads_node_name_with_type_glyph(tmp_path: Path) -> None:
"""The node name is preceded by its shared type glyph (own colour, muted when acked)."""
from meshterm.core.watch_store import Alert
from meshterm.ui.watchtower_screen import _alert_lanes
from meshterm.ui.widgets import _DEFAULT_GLYPH, _NODE_GLYPHS
from meshterm.ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS
def key_of(label):
return None
@@ -268,7 +268,7 @@ def test_alert_row_leads_node_name_with_type_glyph(tmp_path: Path) -> None:
def type_of(label):
return 2 if label == "Roof" else None # Roof advertises as a repeater
glyph, glyph_style = _NODE_GLYPHS[2]
glyph, glyph_style = NODE_GLYPHS[2]
alert = Alert(ident=1, when=utcnow(), kind="silence", label="Roof", message="quiet")
row = _alert_lanes(alert, key_of, type_of)
@@ -278,7 +278,7 @@ def test_alert_row_leads_node_name_with_type_glyph(tmp_path: Path) -> None:
# Unknown type (and a keyless kind like courier) falls back to the plain-node glyph.
ghost = Alert(ident=2, when=utcnow(), kind="courier", label="Ghost", message="gave up")
assert f"{_DEFAULT_GLYPH[0]} Ghost" in _alert_lanes(ghost, key_of).plain
assert f"{DEFAULT_GLYPH[0]} Ghost" in _alert_lanes(ghost, key_of).plain
# An acked alert mutes the glyph with the rest of its history.
acked = Alert(ident=3, when=utcnow(), kind="silence", label="Roof", message="quiet", acked=True)
+7 -7
View File
@@ -18,7 +18,7 @@ from meshterm.ui.pathline import (
)
from meshterm.ui.theme import node_style
from meshterm.ui.widgets import (
_format_age,
format_age,
format_ago,
name_chip,
path_text,
@@ -33,12 +33,12 @@ def _span_style(text: Text, run: str) -> Style:
def test_format_age_is_the_bare_column_form() -> None:
"""The lane form stays suffix-free at every magnitude, for aligned age columns."""
assert _format_age(None) == "never"
assert _format_age(5) == "now"
assert _format_age(90) == "1m"
assert _format_age(7200) == "2h"
assert _format_age(180000) == "2d"
assert _format_age(1300000) == "2w"
assert format_age(None) == "never"
assert format_age(5) == "now"
assert format_age(90) == "1m"
assert format_age(7200) == "2h"
assert format_age(180000) == "2d"
assert format_age(1300000) == "2w"
def test_format_ago_speaks_grammatical_prose() -> None: