Colour marks an identified node: unknown hashes go grey

A hash whose node nobody can name reads whole in node.unknown — path
lines, key lanes, the walk, the packet card, the arrivals — never in a
hue its bytes would derive, exactly as the path graph already drew it.
highlighted_hash gains a known flag; the two path widgets decide it from
their resolver, and the node page threads it per hop.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5 committed 2026-08-08 19:11:12 -04:00
1 parent 05f3dc9bc6
commit 6a79ec5b5e
9 files changed
+125 -56

No files matched your search

+6 -1
View File
@@ -273,7 +273,12 @@ def _lane(
text.append(f"{min(row.count, 99999):>5}", style="muted")
text.append(_GAP_S) # the lane gap the header's KEY lane keeps (see _header)
if row.key:
text.append_text(highlighted_hash(row.key, prefix_bytes, width=hash_w))
# A nameless row is an unidentified node: its key lane greys whole (prefix
# unlit) like every unknown-node hash in the app, the name lane's muted
# ``unknown`` beside it making the same claim.
text.append_text(
highlighted_hash(row.key, prefix_bytes, width=hash_w, known=bool(row.name))
)
else:
text.append("?", style="muted")
return text
+27 -14
View File
@@ -88,7 +88,7 @@ from .pathgraph import (
)
from .theme import mark_rgb, name_style, snr_style
from .tui.render import crop_cells, render_hanging, render_lines, render_to_ansi
from .pathline import PathHop, PathLine, path_line
from .pathline import PathHop, PathLine
from .tui.screen import CANCEL, ListWindow, Screen
from .widgets import (
_DEFAULT_GLYPH,
@@ -1166,7 +1166,7 @@ async def open_node_detail(ctx: "AppContext", contact: Optional["Contact"]) -> N
# -- the info block (identity + how-heard + where; the routes fold into the Routes tab).
info_rows: list[tuple[str, Text]] = []
if key:
info_rows.append(("key", highlighted_hash(key, prefix_bytes)))
info_rows.append(("key", highlighted_hash(key, prefix_bytes, known=bool(name))))
else:
info_rows.append(("key", Text("?", style="muted")))
if not you:
@@ -1225,6 +1225,7 @@ async def open_node_detail(ctx: "AppContext", contact: Optional["Contact"]) -> N
self_key=self_key,
node_label=label,
name_key=key,
node_known=name is not None,
hash_bytes=prefix_bytes,
)
@@ -1338,6 +1339,8 @@ def _route_line(
weakest: Optional[float],
samples: int,
*,
resolve, # noqa: ANN001 - NodeResolver, kept loose like the graph callbacks
node_known: bool,
self_name: Optional[str],
self_key: Optional[str],
hash_bytes: int,
@@ -1347,21 +1350,29 @@ def _route_line(
The whole route reads left to right in the graph's own direction (contact on the left, us
on the right), so the row and the drawn line cross-read. ``path`` is one
:class:`~meshterm.ui.pathline.PathLine` — every hop, endpoints included, shown as its hash
at our own node's path-hash-mode width rather than a resolved name, so the line reads as
the same key-derived identity the graph's chips and column colours already use, and at the
width the device itself carries per hop, as powerline chips where the terminal can draw
them. ``context`` is the bottleneck SNR, sample count, and a ``★ best`` / ``device route``
tag marking the winner and the firmware's learned route — kept off the pathline itself so
a long hash chain never crowds it out, and empty when a route earns none of them.
at our own node's path-hash-mode width rather than a resolved name, at the width the
device itself carries per hop, as powerline chips where the terminal can draw them. A hop
the resolver can name keeps the key-derived hue the graph's chips and column colours
already use; a hop nobody can name — and the page's own node, when it has no name — reads
in the app-wide unknown-node grey, exactly as it does in the graph above. ``context`` is
the bottleneck SNR, sample count, and a ``★ best`` / ``device route`` tag marking the
winner and the firmware's learned route — kept off the pathline itself so a long hash
chain never crowds it out, and empty when a route earns none of them.
"""
hash_bytes = max(hash_bytes, 1) # an unknown mode still needs a real width to slice
relays = path_line(
list(reversed(hops_out)), lambda _hop: None, prefix_bytes=hash_bytes,
self_name=self_name, hash_bytes=hash_bytes,
)
def hop_of(hop: str) -> PathHop:
shown = _hop_hash(hop, hop, hash_bytes)
named = resolve(hop)
if named and named != hop:
return PathHop(shown, key=hop, lit_bytes=hash_bytes)
return PathHop(shown) # unknown node: grey whole, no key-derived hue
head = _hop_hash(name_key, node_label, hash_bytes)
path = PathLine([
PathHop(_hop_hash(name_key, node_label, hash_bytes), key=name_key, lit_bytes=hash_bytes),
*relays.hops,
PathHop(head, key=name_key, lit_bytes=hash_bytes) if node_known and name_key
else PathHop(head),
*(hop_of(hop) for hop in reversed(hops_out)),
PathHop(_hop_hash(self_key, self_name or "us", hash_bytes), you=True),
]).text()
@@ -1458,6 +1469,7 @@ def _routes_view(
self_key,
node_label,
name_key,
node_known,
hash_bytes,
) -> _RoutesView:
"""Build the Routes tab's selectable routes (node → us) + graph callbacks, or a muted note.
@@ -1532,6 +1544,7 @@ def _routes_view(
spec = render_forced_spec(hops_out, target_hash, width_bytes) if target_hash else ""
path, context = _route_line(
node_label, name_key, hops_out, tag, weakest, samples,
resolve=resolve, node_known=node_known,
self_name=self_name, self_key=self_key, hash_bytes=hash_bytes,
)
routes.append(_Route(draw=tuple(reversed(hops_out)), spec=spec, path=path, context=context))
+4 -4
View File
@@ -787,18 +787,18 @@ class PacketViewer(Screen):
The ``from`` row's own presentation, minus the node-type glyph — a one-byte hash
is too thin an identity to plant a type mark on. A node we can't name shows the
hash alone, lit by :func:`~meshterm.ui.widgets.highlighted_hash` like every other
hash on the card.
hash alone, grey whole (``known=False``) like every unknown-node hash in the app.
"""
text = Text()
named = self._resolve(value)
if named and named != value:
known = bool(named and named != value)
if known:
style = "you" if self._self_name and named == self._self_name else name_style(
named, value
)
text.append(named, style=style)
text.append(" ")
text.append_text(highlighted_hash(value, self._prefix_bytes or 1))
text.append_text(highlighted_hash(value, self._prefix_bytes or 1, known=known))
return text
def _decrypt_rows(self, raw: dict) -> list[tuple[str, RenderableType]]:
+10 -6
View File
@@ -739,9 +739,9 @@ def path_line(
The migration bridge: every parameter means exactly what it means to
:func:`~meshterm.ui.widgets.path_text` (see there for the full rendering rules),
so a call site swaps builders without changing what it says — a named hop reads
``Name`` (annotated ``Name (3d)`` under ``show_hash``), an unnamed hop its
prefix-lit hash (or its muted identity hash under ``hash_as_name``), ``None`` is
our own device in white — or, under ``bare_self``, the lone ``★`` — and
``Name`` (annotated ``Name (3d)`` under ``show_hash``), an unnamed hop its hash in
the unknown-node grey (colour marks an identified node, as in the path graph),
``None`` is our own device in white — or, under ``bare_self``, the lone ``★`` — and
``dim_from`` fades a resolved tail. The plain rendering
is character- and style-identical to ``path_text``; what the swap buys is the
:class:`PathLine` shapes (ellipsized / wrapped) and the powerline mode.
@@ -750,7 +750,8 @@ def path_line(
hops: The hops in propagation order — hex hashes, ``None`` marking our own
device (empty strings are skipped; ``dim_from`` counts rendered hops).
resolve: Maps a hop hash to a friendly name when known.
prefix_bytes: Path-hash width to light in unnamed hops' hashes (0 = none).
prefix_bytes: Path-hash width an unnamed hop's identity hash presents at under
``hash_as_name`` (unnamed hops are otherwise shown grey whole, no prefix lit).
self_name: Our own node's name — white when a resolved name matches it, and
naming any ``None`` device hop.
empty: The muted text shown when there are no hops (e.g. ``"direct"``).
@@ -815,13 +816,16 @@ def path_line(
continue
compact = _shorten(hop, hash_bytes)
if dim: # a faded unnamed hop shows its compact hash, exactly as path_text does
built.append(PathHop(compact, key=hop, dim=True))
built.append(PathHop(compact, dim=True))
elif hash_as_name:
identity = _shorten(hop, prefix_bytes or None)
note = compact if (show_hash and compact and compact != identity) else None
built.append(PathHop(identity, annotation=note))
else:
built.append(PathHop(compact, key=hop, lit_bytes=prefix_bytes))
# No name resolved: the node is unknown, so its hash carries no key — the hop
# takes the app-wide unknown-node grey (arrow and chip alike), never a hue its
# bytes would derive. Colour marks an identified node, as in the path graph.
built.append(PathHop(compact))
if cursor is not None:
built.insert(max(0, min(cursor, len(built))), PathHop(CURSOR_GLYPH, cursor=True))
return PathLine(built, mode=mode, empty=empty)
+15 -3
View File
@@ -585,7 +585,8 @@ class WalkScreen(Screen):
short = self._short_hash(node)
if short:
line.append(" (", style="muted")
line.append_text(highlighted_hash(short, self._prefix_bytes))
line.append_text(highlighted_hash(short, self._prefix_bytes,
known=self._known(node)))
line.append(")", style="muted")
if node == self._topo.self_id:
line.append(" · this device", style="muted")
@@ -1004,7 +1005,8 @@ class WalkScreen(Screen):
name_style_ = self._list_name_style(other)
row.append(fit_cells(self._label(other), name_w), style=name_style_)
row.append(" ")
row.append_text(highlighted_hash(other, self._prefix_bytes, width=key_w))
row.append_text(highlighted_hash(other, self._prefix_bytes, width=key_w,
known=self._known(other)))
row.append(" ")
snr = link.median_snr
if snr is not None:
@@ -1041,7 +1043,8 @@ class WalkScreen(Screen):
row.append(" ")
row.append(fit_cells(self._label(node), name_w), style=self._list_name_style(node))
row.append(" ")
row.append_text(highlighted_hash(node, self._prefix_bytes, width=key_w))
row.append_text(highlighted_hash(node, self._prefix_bytes, width=key_w,
known=self._known(node)))
row.append(" ")
if node == self._topo.self_id:
row.append("this device", style="muted")
@@ -1063,6 +1066,15 @@ class WalkScreen(Screen):
return "node.unknown"
return name_style(label, node)
def _known(self, node: str) -> bool:
"""Whether the node is identified — named, or us — so its hash may carry a hue.
The gate every hash lane here passes to :func:`~meshterm.ui.widgets.highlighted_hash`:
an unknown node's hash reads grey whole, matching its ``node.unknown`` name lane
and its ``○`` ring on the canvas.
"""
return self._list_name_style(node) != "node.unknown"
def _marker_rgb(self, node: str) -> RGB:
"""The marker colour for a node: its key-derived hue, ours white, a keyless id grey.
+28 -16
View File
@@ -273,9 +273,10 @@ def path_text(
The one way MeshTerm shows a walked, relayed, or planned hop sequence, wherever one
appears: a packet's ``via`` row, a message's delivery paths, a feed note, a trace's
walked route or planned spec. Each hop renders as its resolved name — coloured in
the app-wide per-name hue, our own node pure white — or, unnamed, as its hash
through :func:`highlighted_hash` (the addressed prefix lit, the rest muted; colour
stays the "this is a name" signal). Hops are joined by muted ``→`` arrows and, by
the app-wide per-name hue, our own node pure white — or, unnamed, as its hash in
the ``node.unknown`` grey (colour marks an identified node, exactly as in the path
graph; an unresolvable hop never wears a hue its bytes would derive). Hops are
joined by muted ``→`` arrows and, by
default, no hash is repeated after a name, so the compact form survives a 72-column
row. The trace-flavoured options: ``show_hash`` annotates each named hop with the
hash it is addressed by (``Alice (3d63)``), a ``None`` hop is our own device at a
@@ -291,7 +292,8 @@ def path_text(
hops: The hops in propagation order — hex hashes, with ``None`` marking our
own device (empty strings are skipped; ``dim_from`` counts rendered hops).
resolve: Maps a hop hash to a friendly name when known.
prefix_bytes: Path-hash width to light in unnamed hops' hashes (0 = none).
prefix_bytes: Path-hash width an unnamed hop's identity hash presents at under
``hash_as_name`` (unnamed hops are otherwise shown grey whole, no prefix lit).
self_name: Our own node's name — drawn in the white ``you`` style when a
resolved name matches it, and naming any ``None`` device hop.
empty: The muted text shown when there are no hops (e.g. ``"direct"``).
@@ -423,28 +425,34 @@ def _path_node(
# the whole shown hash. So a 3-byte mode reads ``e839f2 (e8)`` and still
# cross-references a byte-labelled route graph.
identity = _shorten_hash(hop, prefix_bytes or None)
text = highlighted_hash(identity, 0)
text = highlighted_hash(identity, 0, known=False)
if show_hash and shown and shown != identity:
text.append(f" ({shown})", style=note_style)
return text
return highlighted_hash(shown, prefix_bytes)
# No name resolved: the node is unknown, and an unknown node's hash is grey whole —
# the prefix never lights (colour marks an identified node; see highlighted_hash).
return highlighted_hash(shown, prefix_bytes, known=False)
def highlighted_hash(value: str, prefix_bytes: int, width: Optional[int] = None) -> Text:
def highlighted_hash(
value: str, prefix_bytes: int, width: Optional[int] = None, *, known: bool = True
) -> Text:
"""Render a hex key with its leading path-hash prefix highlighted — THE hash widget.
The one way MeshTerm displays a hash, wherever one appears: the first
``prefix_bytes`` bytes are the slice other nodes address in a forced trace path
(the path-hash), lit in the node's hash-derived palette hue — the same hue its
name wears (see :func:`~meshterm.ui.theme.node_style`) — with the remainder muted,
so the addressable prefix stands out within the otherwise full key and carries the
node's identity colour even where no name is known. A ``width`` budget
shorter than the key ellipsizes it (the ``…`` takes the colour of the digit it
replaces, so a highlight wider than the budget still reads as one).
so the addressable prefix stands out within the otherwise full key. A ``width``
budget shorter than the key ellipsizes it (the ``…`` takes the colour of the digit
it replaces, so a highlight wider than the budget still reads as one).
With ``prefix_bytes=0`` nothing is lit and the key is standing in *as* a name — a node
we can't identify — so the whole run takes ``node.unknown`` rather than ``muted``: it
is the row's content, not the dim tail of a hash whose head already carries the hue.
Colour marks an *identified* node (JP, 2026-08-08): a hash whose node nobody can
name passes ``known=False`` and reads whole in the app-wide ``node.unknown`` grey —
exactly as an unknown node draws in the path graph — never in a hue its bytes would
derive. ``prefix_bytes=0`` on a known node likewise lights nothing and the key,
standing in *as* a name, takes ``node.unknown`` rather than ``muted``: it is the
row's content, not the dim tail of a hash whose head already carries the hue.
Args:
value: The key as hex, optionally ``0x``-prefixed and mixed-case.
@@ -454,12 +462,14 @@ def highlighted_hash(value: str, prefix_bytes: int, width: Optional[int] = None)
bytes that fit in ``width - 1`` cells (an even digit count — a hash reads in
bytes, two hex digits each) plus an ellipsis, a shorter one is right-padded to
the budget so lanes stay aligned. ``None`` shows the key whole, unpadded.
known: Whether the hash belongs to a node the caller can identify (name it, or
place it as a real contact). ``False`` greys the whole run, prefix included.
Returns:
A styled :class:`Text` of the key (exactly ``width`` cells when given).
"""
raw = value.lower().removeprefix("0x")
split = max(0, prefix_bytes) * 2
split = max(0, prefix_bytes) * 2 if known else 0
pad = 0
ellipsis = False
if width is not None and len(raw) > width:
@@ -472,7 +482,9 @@ def highlighted_hash(value: str, prefix_bytes: int, width: Optional[int] = None)
pad = width - kept - 1
elif width is not None:
pad = width - len(raw)
hue = node_style(value) # from the untruncated key, though any prefix agrees
# The hue derives from the untruncated key (any prefix agrees) — but only an
# identified node earns one at all; an unknown node's hash is grey throughout.
hue = node_style(value) if known else "node.unknown"
rest = "muted" if split else "node.unknown"
text = Text()
text.append(raw[:split], style=hue)
+24
View File
@@ -194,6 +194,7 @@ def test_route_line_shows_hashes_not_names() -> None:
"""The pathline runs contact → relays → us, every hop by its hash; the tag trails on context."""
path, context = _route_line(
"Far", FAR.public_key, ("3d63c6429436",), "device", None, 0,
resolve=make_node_resolver([HUB]), node_known=True,
self_name="Us", self_key=US + "0" * 52, hash_bytes=1,
)
line = path.plain
@@ -204,10 +205,29 @@ def test_route_line_shows_hashes_not_names() -> None:
assert context.plain == "device route" # the firmware-route tag, off the pathline itself
def test_route_line_greys_hops_nobody_can_name() -> None:
"""A hop the resolver can name keeps its key-derived hue on the hash; a hop nobody can
name — and a page node with no name — reads in the unknown-node grey, like the graph."""
from meshterm.ui.theme import node_style
path, _context = _route_line(
"f2c24f54551e", FAR.public_key, ("3d63c6429436", "abcd1234ef56"), "", None, 0,
resolve=make_node_resolver([HUB]), node_known=False,
self_name="Us", self_key=US + "0" * 52, hash_bytes=1,
)
styles = {path.plain[s.start : s.end]: str(s.style) for s in path.spans}
assert styles.get("ab") == "node.unknown" # no contact names it → grey, no key hue
assert styles.get("f2") == "node.unknown" # the nameless page node greys its own hash
hued = {path.plain[s.start : s.end] for s in path.spans
if str(s.style) == node_style("3d63c6429436")}
assert "3d" in hued # the Hub is a named contact, so its hash keeps the hue
def test_route_line_hash_width_follows_our_path_hash_mode() -> None:
"""A device carrying 3-byte routing hashes shows 3-byte hops, not the 1-byte default."""
path, _context = _route_line(
"Far", FAR.public_key, ("3d63c6429436",), "", None, 0,
resolve=make_node_resolver([HUB]), node_known=True,
self_name="Us", self_key=US + "0" * 52, hash_bytes=3,
)
line = path.plain
@@ -220,6 +240,7 @@ def test_route_line_marks_the_best_route_and_its_context() -> None:
"""The winner wears ★ best and trails its bottleneck SNR and sample count, on the context line."""
_path, context = _route_line(
"Far", FAR.public_key, ("3d63c6429436",), "best", 6.5, 4,
resolve=make_node_resolver([HUB]), node_known=True,
self_name="Us", self_key=US + "0" * 52, hash_bytes=1,
)
line = context.plain
@@ -230,6 +251,7 @@ def test_route_line_direct_route_has_no_relay() -> None:
"""A zero-hop route reads contact → us with nothing between them."""
path, _context = _route_line(
"Far", FAR.public_key, (), "best", None, 0,
resolve=make_node_resolver([HUB]), node_known=True,
self_name="Us", self_key=US + "0" * 52, hash_bytes=1,
)
line = path.plain
@@ -264,6 +286,7 @@ def _view(topo, suggested, device_route, target, node_label, contacts, name_key=
style=route_graph_style, self_name="Us", self_key=US + "0" * 52,
node_label=node_label,
name_key=name_key or (target + "0" * 52),
node_known=True,
hash_bytes=1,
)
@@ -284,6 +307,7 @@ def test_routes_view_draws_evidence_and_notes_its_absence() -> None:
key_of=make_name_key_resolver([FAR]), style=route_graph_style, self_name="Us",
self_key=US + "0" * 52,
node_label="Far", name_key=FAR.public_key,
node_known=True,
hash_bytes=1,
)
assert not note.routes and "no route observed" in note.note
+5 -3
View File
@@ -621,15 +621,17 @@ def test_picker_row_lanes_align_under_the_header() -> None:
span.style == "muted" and span.start <= unknown_at < span.end
for span in row.spans
)
# The key's 2-byte hash is lit in the key's hue, the tail muted.
# A nameless node is unidentified, so its key lane greys whole — the prefix never
# lights (colour marks an identified node, exactly as in the path graph).
from meshterm.ui.theme import node_style
hash_at = plain.index("3d" * 6)
assert any(
span.style == node_style("3d" * 6)
and span.start == hash_at and span.end == hash_at + 4
span.style == "node.unknown"
and span.start == hash_at and span.end == hash_at + 12
for span in row.spans
)
assert not any(span.style == node_style("3d" * 6) for span in row.spans)
# Header labels land over their lanes (+2 covers the select pointer column); the lanes
# now read NAME · HEARD · PKTS · KEY, with the key closing the row.
header = _header(10, ContactsSort.from_name("heard")).plain
+6 -9
View File
@@ -53,18 +53,15 @@ def test_path_text_empty_reads_as_direct() -> None:
assert path_text([], _resolve, empty="direct — no relays").plain == "direct — no relays"
def test_path_text_lights_the_hash_prefix() -> None:
"""An unnamed hop renders through the shared hash widget, its prefix lit in the
node's hash-derived hue."""
def test_path_text_greys_an_unnamed_hop_whole() -> None:
"""An unresolvable hop is an unknown node: its hash reads ``node.unknown`` whole,
the prefix never lit — colour marks an identified node, as in the path graph."""
from meshterm.ui.theme import node_style
text = path_text(["77bb"], _resolve, prefix_bytes=1)
lit = [
text.plain[s.start : s.end]
for s in text.spans
if str(s.style) == node_style("77bb")
]
assert "77" in lit # the addressed prefix stands out within the hash
styles = {text.plain[s.start : s.end]: str(s.style) for s in text.spans}
assert styles.get("77bb") == "node.unknown"
assert not any(str(s.style) == node_style("77bb") for s in text.spans)
def test_path_text_hash_as_name_shows_grey_identity_hash() -> None: