From 9501505bed5bcc7cb3a0224638326abd936e0a1f Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sat, 11 Jul 2026 05:23:49 -0400 Subject: [PATCH] Mesh Atlas: the observed topology, drawn as a walkable braille graph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The trace path composer's evidence graph — trace walks, firmware routes, overheard relay chains, repeater neighbour tables — finally gets a face. A new full-screen Mesh section tool draws every link the graph holds on the street map's braille canvas: our node at the centre, everything else on concentric rings at its evidenced hop distance, edges coloured by median SNR and faded by evidence age. Clusters we only know exist from a repeater's neighbour table (no observed path back to us) ride an outermost island ring and say so. Rings place members at even angular slots ordered by the bearing of their strongest parent, with the whole ring rotated to best fit those wishes plus a per-ring twist — sparse meshes are pairs all the way out, and without the twist every ring collapses onto one crowded line. ←/→ walk the graph node by node (selection brightens its links and fills the bottom panel strongest-first), Enter floats a per-link detail dialog, r rebuilds from storage. Nothing transmits, ever: the atlas is a reading of what the radio already heard. Co-Authored-By: Claude Fable 5 --- meshterm/services/topology.py | 8 + meshterm/tools/atlas.py | 70 ++++ meshterm/ui/atlas_screen.py | 694 ++++++++++++++++++++++++++++++++++ tests/test_atlas.py | 162 ++++++++ 4 files changed, 934 insertions(+) create mode 100644 meshterm/tools/atlas.py create mode 100644 meshterm/ui/atlas_screen.py create mode 100644 tests/test_atlas.py diff --git a/meshterm/services/topology.py b/meshterm/services/topology.py index ab396fb..cc8141a 100644 --- a/meshterm/services/topology.py +++ b/meshterm/services/topology.py @@ -373,6 +373,14 @@ class MeshTopology: """How many distinct links the graph holds evidence for.""" return len(self._links) + def links(self) -> list[Link]: + """Every link the graph holds evidence for (no particular order). + + The whole-graph view the Mesh Atlas draws; path queries should prefer + :meth:`next_hops` / :meth:`scenarios`, which rank and filter. + """ + return list(self._links.values()) + def link(self, a: str, b: str) -> Optional[Link]: """The evidence for the undirected link between ``a`` and ``b``, if any.""" return self._links.get((a, b) if a < b else (b, a)) diff --git a/meshterm/tools/atlas.py b/meshterm/tools/atlas.py new file mode 100644 index 0000000..a29de36 --- /dev/null +++ b/meshterm/tools/atlas.py @@ -0,0 +1,70 @@ +"""The ``atlas`` tool: the mesh's observed shape, drawn as a live link graph. + +Opens the full-screen Mesh Atlas (see :mod:`meshterm.ui.atlas_screen`): every link the +evidence graph holds — trace walks, firmware routes, overheard relay chains, repeater +neighbour tables — drawn as braille edges coloured by SNR around our own node, with +node-by-node walking and per-link detail. The geographic map answers *where* the mesh +is; the atlas answers *how it hangs together*. + +Menu-only: the atlas is an interactive reading of stored evidence (and transmits +nothing), so there is no scripted one-shot to register — ``trace``-family commands +already print path evidence in scripted runs. +""" + +from __future__ import annotations + +from typing import Any, Optional + +import typer + +from ..context import AppContext +from .base import Tool, ToolResult, register + + +@register +class AtlasTool(Tool): + """See how the mesh hangs together: the observed link graph, walkable.""" + + name = "atlas" + title = "Mesh atlas" + icon = "🕸️" + help = "Draw the mesh's observed topology — links, SNR, hop rings" + category = "Mesh" + order = 32 # beside Map: the logical shape next to the geographic one + + async def prompt_params(self, ctx: AppContext) -> Optional[dict[str, Any]]: + """Run the atlas; there are never parameters to collect. + + The screen presents everything itself and returns when dismissed, so + returning ``None`` tells the menu the invocation is complete (the same + pattern as the ``dashboard`` tool). + + Args: + ctx: Shared application context. + + Returns: + Always ``None``. + """ + from ..ui.atlas_screen import open_atlas + + await open_atlas(ctx) + return None + + async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: + """Nothing runs here: the atlas lives inside :meth:`prompt_params`. + + Args: + ctx: Shared application context. + params: Unused. + + Returns: + An empty :class:`ToolResult` (only reachable from a scripted call). + """ + return ToolResult(summary={}) + + def register_cli(self, app: typer.Typer) -> None: + """Register no CLI command — the atlas is an interactive, menu-only screen. + + Args: + app: The Typer application (untouched). + """ diff --git a/meshterm/ui/atlas_screen.py b/meshterm/ui/atlas_screen.py new file mode 100644 index 0000000..d4e26e5 --- /dev/null +++ b/meshterm/ui/atlas_screen.py @@ -0,0 +1,694 @@ +"""The Mesh Atlas: the mesh's observed shape, drawn as a live braille link graph. + +The interactive face of the ``atlas`` tool. The trace path composer already distills +every fragment of topology we ever received — trace walks, firmware routes, RX-logged +relay chains, repeater neighbour tables — into one evidence graph +(:mod:`~meshterm.services.topology`); this screen is that graph made visible. Nothing +here transmits: the atlas is a reading of what the radio has already heard. + +Our own node anchors the centre and every other node sits on a concentric ring at its +evidenced hop distance, so the picture answers the mesh's first spatial question — *how +far out is everything?* — at a glance. Edges are braille lines coloured by the link's +median SNR (green → amber → red, slate for links with no reading) and faded by evidence +age, drawn on the same :class:`~meshterm.ui.mapcanvas.MapCanvas` the street map uses. +Evidence islands — link clusters we know of only through a repeater's neighbour table, +with no observed path back to us — ride an outermost ring of their own. + +``←``/``→`` walk the graph node by node: the selection brightens its links, dims the +rest, and fills the bottom panel with the node's links strongest-first; ``Enter`` floats +a detail dialog with every link's readings. ``r`` rebuilds from storage (new evidence +lands while the screen is open), ``Esc`` backs out. +""" + +from __future__ import annotations + +import asyncio +import math +import zlib +from datetime import datetime +from typing import TYPE_CHECKING, Callable, Optional + +from rich.text import Text + +from ..core.models import ( + NODE_TYPE_LABELS, + NODE_TYPE_REPEATER, + Contact, + utcnow, +) +from ..services.topology import Link, MeshTopology +from .map_render import _NODE, _REPEATER, _SELF +from .mapcanvas import RGB, MapCanvas, parse_hex +from .theme import snr_style +from .tui.render import render_to_ansi +from .tui.screen import Screen +from .widgets import _format_age + +if TYPE_CHECKING: + from ..context import AppContext + +_TAU = math.tau + +#: Horizontal / vertical dot-space margins the ring layout keeps clear of the canvas +#: edge, so a node's marker glyph and its collision-avoided label have room to land. +_PAD_X_DOTS = 16 +_PAD_Y_DOTS = 5 + +#: Bottom lines reserved under the canvas for the info panel (a spacer + three rows). +_PANEL_H = 4 + +#: The widest a node label may render on the canvas before it is ellipsized. +_LABEL_W = 16 + +#: Radians each successive ring is twisted beyond its wish-fitted rotation. Sparse +#: rings (a two-node mesh is *pairs* all the way out) would otherwise all align along +#: their parents' axis and the whole graph would degenerate to one crowded line; the +#: twist staggers the rings so markers and labels get their own rows. +_RING_TWIST = 0.55 + +#: SNR (dB) → edge colour anchors, interpolated linearly and clamped at the ends: the +#: red/amber/green of the app's snr styles, so the graph and the tables agree. +_SNR_STOPS: tuple[tuple[float, RGB], ...] = ( + (-15.0, (239, 68, 68)), + (0.0, (250, 204, 21)), + (10.0, (74, 222, 128)), +) + +#: Edge colour for a link with no SNR reading at all (e.g. known only from a route). +_NO_READING: RGB = (100, 116, 139) + +#: Marker style for a node no contact matches — heard of, never identified. +_UNKNOWN = ("○", "#94a3b8") + + +def _snr_rgb(snr: Optional[float]) -> RGB: + """The edge colour for a link's median SNR (see :data:`_SNR_STOPS`).""" + if snr is None: + return _NO_READING + if snr <= _SNR_STOPS[0][0]: + return _SNR_STOPS[0][1] + if snr >= _SNR_STOPS[-1][0]: + return _SNR_STOPS[-1][1] + (x0, c0), (x1, c1) = next( + (lo, hi) for lo, hi in zip(_SNR_STOPS, _SNR_STOPS[1:]) if lo[0] <= snr <= hi[0] + ) + f = (snr - x0) / (x1 - x0) + return tuple(round(a + (b - a) * f) for a, b in zip(c0, c1)) # type: ignore[return-value] + + +def _scaled(rgb: RGB, factor: float) -> RGB: + """``rgb`` dimmed (or mildly brightened) by ``factor``, clamped to byte range.""" + return tuple(max(0, min(255, round(c * factor))) for c in rgb) # type: ignore[return-value] + + +def _freshness(last_seen: Optional[datetime], now: datetime) -> float: + """How brightly a link draws for its evidence age: 1.0 fresh → 0.5 stale.""" + if last_seen is None or getattr(last_seen, "tzinfo", None) is None: + return 0.55 + age = (now - last_seen).total_seconds() + if age < 86400: + return 1.0 + if age < 7 * 86400: + return 0.8 + return 0.5 + + +def _hash_angle(node: str) -> float: + """A deterministic per-node angle, so a node keeps its bearing across rebuilds. + + Derived from a CRC of the canonical id rather than :func:`hash`, which Python + salts per process — the whole point is that YUL sits at the same clock position + tomorrow as today. + """ + return zlib.crc32(node.encode()) / 0xFFFFFFFF * _TAU + + +def _ring_angles(desired: dict[str, float], twist: float = 0.0) -> dict[str, float]: + """Distribute one ring's members evenly, honouring their desired bearings. + + Members are placed at exactly even angular slots — the only spacing that keeps + markers and their labels apart on a crowded ring — but in the *order* of the + angles they wished for, and with the whole ring rotated to the circular best + fit of those wishes plus ``twist`` (see :data:`_RING_TWIST`). A child therefore + still comes out on its parent's side of the graph; it just never piles onto a + sibling, and successive rings never fall into one straight line. + """ + if not desired: + return {} + ordered = sorted(desired, key=lambda n: desired[n] % _TAU) + count = len(ordered) + slots = [i * _TAU / count for i in range(count)] + sin_sum = sum(math.sin(desired[n] - s) for n, s in zip(ordered, slots)) + cos_sum = sum(math.cos(desired[n] - s) for n, s in zip(ordered, slots)) + phase = math.atan2(sin_sum, cos_sum) if (sin_sum or cos_sum) else 0.0 + return {n: (s + phase + twist) % _TAU for n, s in zip(ordered, slots)} + + +def radial_layout( + self_id: str, + links: list[tuple[str, str, float]], + dot_w: int, + dot_h: int, +) -> tuple[dict[str, tuple[int, int]], dict[str, int], frozenset[str]]: + """Place every linked node on concentric rings around our own node. + + Rings are evidenced hop distance (BFS over the link graph from ``self_id``); + nodes with no observed path to us — evidence islands — take one shared ring + outside everything reached. Within a ring each node *wants* the angle of its + strongest parent one ring in (ring one and islands want a stable per-id hash + angle instead), and the wishes are then pushed apart (:func:`_relax`) so markers + and labels never pile up. Rings span an ellipse fitted to the canvas, using the + terminal's width rather than forcing a circle into it. + + Args: + self_id: Canonical id of our own node (always placed, even with no links). + links: The evidence graph as ``(a, b, strength)`` triples. + dot_w: Canvas width in braille dots. + dot_h: Canvas height in braille dots. + + Returns: + ``(positions, rings, islands)``: dot-space coordinates per node, the ring + number per node (0 = us), and the ids that had no path back to us. + """ + adjacency: dict[str, dict[str, float]] = {self_id: {}} + for a, b, strength in links: + adjacency.setdefault(a, {}) + adjacency.setdefault(b, {}) + adjacency[a][b] = max(strength, adjacency[a].get(b, 0.0)) + adjacency[b][a] = max(strength, adjacency[b].get(a, 0.0)) + + rings: dict[str, int] = {self_id: 0} + frontier = [self_id] + while frontier: + nxt: list[str] = [] + for node in frontier: + for other in adjacency.get(node, {}): + if other not in rings: + rings[other] = rings[node] + 1 + nxt.append(other) + frontier = nxt + + islands = frozenset(n for n in adjacency if n not in rings) + if islands: + island_ring = max(rings.values(), default=0) + 1 + for node in islands: + rings[node] = island_ring + max_ring = max(rings.values(), default=0) + + angles: dict[str, float] = {self_id: 0.0} + for ring in range(1, max_ring + 1): + members = sorted(n for n, r in rings.items() if r == ring) + if not members: + continue + desired: dict[str, float] = {} + for node in members: + parents = sorted( + ( + (strength, p) + for p, strength in adjacency.get(node, {}).items() + if rings.get(p) == ring - 1 and p in angles and rings[p] > 0 + ), + key=lambda t: -t[0], + ) + if parents: + # Near the strongest parent, offset a touch by identity so siblings + # wish for distinct bearings before the even spacing orders them. + desired[node] = ( + angles[parents[0][1]] + (_hash_angle(node) / _TAU - 0.5) * 0.4 + ) + else: + # Ring one (and any orphan) wishes for its stable per-id bearing, so + # a node keeps roughly the same clock position across rebuilds. + desired[node] = _hash_angle(node) + angles.update(_ring_angles(desired, twist=_RING_TWIST * (ring - 1))) + + cx, cy = dot_w / 2.0, dot_h / 2.0 + rx = max(8.0, dot_w / 2.0 - _PAD_X_DOTS) + ry = max(6.0, dot_h / 2.0 - _PAD_Y_DOTS) + positions: dict[str, tuple[int, int]] = {} + for node, ring in rings.items(): + if ring == 0: + positions[node] = (round(cx), round(cy)) + continue + frac = ring / max_ring if max_ring else 1.0 + a = angles[node] + positions[node] = ( + round(cx + rx * frac * math.cos(a)), + round(cy + ry * frac * math.sin(a)), + ) + return positions, rings, islands + + +class AtlasScreen(Screen): + """The full-screen atlas: canvas on top, a live info panel along the bottom.""" + + floating = False + footer_hint = "←/→ walk nodes · Enter details · r rebuild · Esc back" + + def __init__( + self, + *, + session, # noqa: ANN001 - TuiSession, imported lazily to avoid a cycle + topo: MeshTopology, + contacts: dict[str, Contact], + self_label: str, + rebuild: Optional[Callable[[], MeshTopology]] = None, + ) -> None: + """Create the atlas over a built topology snapshot. + + Args: + session: The running TUI session (size, repaints, and the detail dialog). + topo: The evidence graph to draw. + contacts: Contacts keyed by canonical id, for glyphs, names, and ages. + self_label: Display name for our own node (its mesh name when known). + rebuild: Rebuilds the graph from storage for the ``r`` key; ``None`` + leaves the snapshot fixed (tests, and the odd caller without a repo). + """ + super().__init__() + self._session = session + self._topo = topo + self._contacts = contacts + self._self_label = self_label + self._rebuild = rebuild + #: Selected canonical id, or ``None`` for the whole-mesh overview. + self._selected: Optional[str] = None + #: Selection cycle: us first, then rings inside-out, each ring by angle. + self._cycle: list[str] = [] + self._positions: dict[str, tuple[int, int]] = {} + self._rings: dict[str, int] = {} + self._islands: frozenset[str] = frozenset() + self._layout_key: Optional[tuple[int, int, int]] = None + self._generation = 0 # bumped by rebuild so the layout cache invalidates + self._dialog_open = False + self._needs_scrub = True # braille smear scrub, exactly like the map + + # --- input ----------------------------------------------------------------------- + + def handle(self, action: str, data: str = "") -> None: + """Walk the selection, open details, rebuild, or dismiss.""" + if action == "escape": + self.resolve(None) + return + if action in ("right", "down", "tab"): + self._step_selection(1) + elif action in ("left", "up"): + self._step_selection(-1) + elif action == "enter": + self._open_details() + elif action == "text": + low = data.lower() + if low == "r": + self._do_rebuild() + elif low == "q": + self.resolve(None) + return + self._needs_scrub = True + self._session.invalidate() + + def _step_selection(self, delta: int) -> None: + """Cycle ``… → overview → us → ring by ring …`` in either direction.""" + if not self._cycle: + return + stops: list[Optional[str]] = [None, *self._cycle] + at = stops.index(self._selected) if self._selected in stops else 0 + self._selected = stops[(at + delta) % len(stops)] + + def _do_rebuild(self) -> None: + """Re-read the evidence and relayout, keeping the selection when it survives.""" + if self._rebuild is None: + return + self._topo = self._rebuild() + self._generation += 1 + self._layout_key = None # force a relayout on the next paint + + def _open_details(self) -> None: + """Float the selected node's full link listing over the atlas.""" + node = self._selected + if node is None or self._dialog_open: + return + self._dialog_open = True + + async def run() -> None: + try: + await self._session.message_dialog( + self._details_text(node), title=self._label(node) + ) + finally: + self._dialog_open = False + self._session.invalidate() + + try: + asyncio.ensure_future(run()) + except RuntimeError: # pragma: no cover - no running loop (unit rendering) + self._dialog_open = False + + # --- smear scrub (same fallback-glyph problem as the map) ------------------------- + + def consume_edge_scrub(self) -> int: + """Right-edge columns to force-repaint after a redraw (see the map screen).""" + if not self._needs_scrub: + return 0 + self._needs_scrub = False + return 2 + + # --- rendering --------------------------------------------------------------------- + + def render_body(self, width: int) -> list[str]: + """Draw the graph canvas and the info panel to exactly the viewport height.""" + _, cell_h = self._session.base_body_size() + canvas_h = max(4, cell_h - _PANEL_H) + + links = self._topo.links() + self.title = ( + f"Mesh Atlas · {max(0, len(self._layout_nodes(links)) )} nodes" + f" · {len(links)} links" + ) + if not links: + return self._empty_state(width) + + self._ensure_layout(width * 2, canvas_h * 4, links) + canvas = MapCanvas(width, canvas_h) + now = utcnow() + + for link in links: + pa = self._positions.get(link.a) + pb = self._positions.get(link.b) + if pa is None or pb is None: + continue + color = _scaled(_snr_rgb(link.median_snr), _freshness(link.last_seen, now)) + priority = 2 + if self._selected is not None: + if self._selected in (link.a, link.b): + priority = 3 # the selection's own links win their cells + else: + color = _scaled(color, 0.3) + priority = 1 + canvas.draw_line([pa, pb], color, priority) + + for node in self._marker_order(): + x, y = self._positions[node] + glyph, color_hex = self._glyph(node) + rgb = (255, 255, 255) if node == self._selected else parse_hex(color_hex) + canvas.marker(x, y, glyph, rgb) + for node in self._marker_order(): + x, y = self._positions[node] + label = self._label(node) + if len(label) > _LABEL_W: + label = label[: _LABEL_W - 1] + "…" + _, color_hex = self._glyph(node) + rgb = (255, 255, 255) if node == self._selected else parse_hex(color_hex) + # Both sides of a crowded marker (the centre, typically) can be claimed; + # retry a cell below, then above, before giving the label up entirely. + for dy in (0, 4, -4): + if canvas.marker_label(x, y + dy, label, rgb): + break + + return canvas.to_ansi_lines() + self._panel_lines(width, links) + + def _empty_state(self, width: int) -> list[str]: + """A friendly explanation while the evidence graph is still empty.""" + lines = [ + Text(), + Text("The atlas has no evidence to draw yet.", style="accent"), + Text(), + Text("Topology accrues passively as the mesh talks:", style="muted"), + Text(" · every successful trace maps each link it walked", style="muted"), + Text(" · firmware routes and overheard relay chains fill in more", style="muted"), + Text(" · a repeater's neighbour table adds its own vantage point", style="muted"), + Text(), + Text("Run a trace, or just leave MeshTerm listening.", style="muted"), + ] + return [render_to_ansi(t, width, no_wrap=True) for t in lines] + + def _layout_nodes(self, links: list[Link]) -> set[str]: + """Every node the graph mentions, plus us (drawn even when alone).""" + nodes = {self._topo.self_id} + for link in links: + nodes.add(link.a) + nodes.add(link.b) + return nodes + + def _ensure_layout(self, dot_w: int, dot_h: int, links: list[Link]) -> None: + """(Re)compute positions when the canvas size or the evidence changed.""" + key = (dot_w, dot_h, self._generation) + if key == self._layout_key: + return + self._layout_key = key + now = utcnow() + triples = [(l.a, l.b, l.strength(now)) for l in links] + self._positions, self._rings, self._islands = radial_layout( + self._topo.self_id, triples, dot_w, dot_h + ) + order = sorted( + (n for n in self._positions if n != self._topo.self_id), + key=lambda n: (self._rings.get(n, 99), _hash_angle(n)), + ) + self._cycle = [self._topo.self_id, *order] + if self._selected is not None and self._selected not in self._positions: + self._selected = None # the rebuild dropped it + + def _marker_order(self) -> list[str]: + """Marker/label placement order: the selection first (its label must win), + then us, then repeaters, then everything else working outward.""" + + def rank(node: str) -> tuple[int, int, float]: + if node == self._selected: + lead = 0 + elif node == self._topo.self_id: + lead = 1 + elif self._contacts.get(node) is not None and ( + self._contacts[node].node_type == NODE_TYPE_REPEATER + ): + lead = 2 + else: + lead = 3 + return (lead, self._rings.get(node, 99), _hash_angle(node)) + + return sorted(self._positions, key=rank) + + def _glyph(self, node: str) -> tuple[str, str]: + """The marker glyph and hex colour for a node, by identity and type.""" + if node == self._topo.self_id: + return _SELF + contact = self._contacts.get(node) + if contact is None: + return _UNKNOWN + if contact.node_type == NODE_TYPE_REPEATER: + return _REPEATER + return _NODE + + def _label(self, node: str) -> str: + """A node's display name: its own name for us, contact name, or short hash.""" + if node == self._topo.self_id: + return self._self_label + return self._topo.display_name(node) or node[:8] + + # --- the info panel ------------------------------------------------------------ + + def _panel_lines(self, width: int, links: list[Link]) -> list[str]: + """The bottom panel: a spacer plus three lines of overview or selection.""" + if self._selected is None: + rows = self._overview_rows(links) + else: + rows = self._selection_rows(self._selected) + rows = (rows + [Text()] * 3)[:3] + return [""] + [render_to_ansi(t, width, no_wrap=True) for t in rows] + + def _overview_rows(self, links: list[Link]) -> list[Text]: + """Legend, evidence tallies, and the graph's age span.""" + legend = Text() + for glyph, color in (_SELF, _REPEATER, _NODE, _UNKNOWN): + legend.append(glyph, style=color) + legend.append( + {"★": " you ", "▲": " repeater ", "●": " node ", "○": " unknown"}[glyph], + style="muted", + ) + legend.append(" · edge colour = SNR · faint = stale", style="muted") + + counts = { + src: sum(1 for l in links if src in l.sources) + for src in ("trace", "route", "packet", "neighbour") + } + evidence = Text("evidence ", style="muted") + parts = [f"{src} {n}" for src, n in counts.items() if n] + evidence.append(" · ".join(parts) if parts else "—", style="brand") + evidence.append(" (links seen by each source)", style="muted") + + stamps = [l.last_seen for l in links if l.last_seen is not None] + span = Text("", style="muted") + if stamps: + newest = max(0.0, (utcnow() - max(stamps)).total_seconds()) + oldest = max(0.0, (utcnow() - min(stamps)).total_seconds()) + span.append("freshest ", style="muted") + span.append(_format_age(newest), style="brand") + span.append(" · oldest ", style="muted") + span.append(_format_age(oldest), style="brand") + span.append(" · ", style="muted") + span.append("←/→ walk the graph", style="muted") + return [legend, evidence, span] + + def _selection_rows(self, node: str) -> list[Text]: + """Who the selection is, its links strongest-first, and its evidence roll-up.""" + glyph, color = self._glyph(node) + contact = self._contacts.get(node) + + who = Text() + who.append(glyph, style=color) + who.append(f" {self._label(node)} ", style="bold") + who.append(f"({node[:12]})", style="muted") + if node == self._topo.self_id: + who.append(" · this device", style="muted") + else: + kind = ( + NODE_TYPE_LABELS.get(contact.node_type, "node") + if contact is not None + else "unknown node" + ) + who.append(f" · {kind}", style="muted") + if node in self._islands: + who.append(" · island — no observed path to us", style="warn") + else: + ring = self._rings.get(node, 0) + who.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()) + who.append(f" · heard {_format_age(secs)}", style="muted") + + now = utcnow() + neighbours = sorted( + ( + (link.strength(now), link.b if link.a == node else link.a, link) + for link in self._topo.links() + if node in (link.a, link.b) + ), + key=lambda t: -t[0], + ) + row = Text("links ", style="muted") + row.append(str(len(neighbours)), style="brand") + row.append(" strongest first: ", style="muted") + for i, (_s, other, link) in enumerate(neighbours): + if i: + row.append(" · ", style="muted") + row.append(self._label(other)) + snr = link.median_snr + if snr is not None: + row.append(f" {snr:+.1f}", style=snr_style(snr)) + else: + row.append(" —", style="muted") + + samples = sum(link.samples for _s, _o, link in neighbours) + sources = sorted({src for _s, _o, link in neighbours for src in link.sources}) + stamps = [link.last_seen for _s, _o, link in neighbours if link.last_seen] + rollup = Text("evidence ", style="muted") + rollup.append(f"{samples} reading{'s' if samples != 1 else ''}", style="brand") + if sources: + rollup.append(f" · {', '.join(sources)}", style="muted") + if stamps: + newest = max(0.0, (utcnow() - max(stamps)).total_seconds()) + rollup.append(" · freshest ", style="muted") + rollup.append(_format_age(newest), style="brand") + rollup.append(" · Enter for details", style="muted") + return [who, row, rollup] + + def _details_text(self, node: str) -> Text: + """The Enter dialog: every link off ``node``, one line each, strongest first.""" + now = utcnow() + neighbours = sorted( + ( + (link.strength(now), link.b if link.a == node else link.a, link) + for link in self._topo.links() + if node in (link.a, link.b) + ), + key=lambda t: -t[0], + ) + if not neighbours: + return Text("No observed links.", style="muted") + name_w = min( + _LABEL_W, max(len(self._label(other)) for _s, other, _l in neighbours) + ) + body = Text() + for i, (_s, other, link) in enumerate(neighbours): + if i: + body.append("\n") + label = self._label(other) + if len(label) > name_w: + label = label[: name_w - 1] + "…" + body.append(label.ljust(name_w + 2)) + snr = link.median_snr + if snr is not None: + body.append(f"{snr:+5.1f} dB", style=snr_style(snr)) + else: + body.append(" — dB", style="muted") + body.append(f" {link.samples:>3}×", style="brand") + body.append(f" {'+'.join(sorted(link.sources))}", style="muted") + if link.last_seen is not None: + secs = max(0.0, (now - link.last_seen).total_seconds()) + body.append(f" {_format_age(secs)}", style="muted") + return body + + +async def open_atlas(ctx: "AppContext") -> None: + """Build the evidence graph and run the full-screen atlas until dismissed. + + Contacts and our own identity come from the device when one is reachable + (best-effort — the stored evidence draws fine without them, just with hashes for + names), the graph itself comes entirely from the repository, and the ``r`` key + re-reads storage so evidence landing while the screen is open can be pulled in. + No transmissions, ever. + + Args: + ctx: The shared application context (must be running the interactive TUI). + + Raises: + RuntimeError: If called outside the interactive menu (no full-screen session). + """ + from ..services.topology import build_topology + from .surface import TuiUi + + if not isinstance(ctx.ui, TuiUi): # pragma: no cover - guarded by the menu-only caller + raise RuntimeError("the atlas is only available in the menu") + session = ctx.ui.session + + contacts: list[Contact] = [] + self_label = "you" + self_hash: Optional[str] = None + try: + if ctx.is_connected or ctx.settings.connect_on_start: + device = await ctx.device() + contacts = await device.get_contacts() + info = await device.get_self_info() + self_label = str(info.get("name") or "you") + self_hash = str(info.get("public_key") or "") or None + except Exception: # noqa: BLE001 - names are a nicety; the graph renders without them + contacts = [] + + def build() -> MeshTopology: + """One fresh graph from everything currently stored.""" + return build_topology( + self_id=self_hash or "local", + contacts=contacts, + trace_paths=ctx.repo.trace_paths(), + packet_paths=ctx.repo.packet_paths(), + neighbour_links=ctx.repo.neighbour_links(), + ) + + topo = build() + by_id: dict[str, Contact] = {} + for contact in contacts: + canonical = topo.canonical(contact.public_key or contact.key_prefix) + if canonical: + by_id[canonical] = contact + + screen = AtlasScreen( + session=session, + topo=topo, + contacts=by_id, + self_label=self_label, + rebuild=build, + ) + try: + await session.run_screen(screen) + finally: + # The same clean-slate repaint as the map: braille fallback glyphs may have + # smeared cells prompt_toolkit's differential paint will never rewrite. + session.request_full_repaint() diff --git a/tests/test_atlas.py b/tests/test_atlas.py new file mode 100644 index 0000000..cc7fc2e --- /dev/null +++ b/tests/test_atlas.py @@ -0,0 +1,162 @@ +"""Mesh Atlas tests: the radial layout and the screen's rendering and selection. + +The layout is a pure function, tested directly; the screen is driven headless against a +fake session and a hand-built topology, the same approach as the dashboard tests. +""" + +from __future__ import annotations + +import re +from datetime import timedelta + +from meshterm.core.models import Contact, utcnow +from meshterm.services.topology import MeshTopology +from meshterm.ui.atlas_screen import AtlasScreen, radial_layout + +US = "aa" * 6 +YUL = Contact(name="YUL-Cartierville", public_key="3d" * 32, node_type=2) +ALICE = Contact(name="Alice", public_key="b2" * 32, last_seen=utcnow() - timedelta(minutes=5)) + + +class _FakeSession: + def __init__(self, cell_h: int = 24) -> None: + self.cell_h = cell_h + self.repaints = 0 + + def base_body_size(self) -> tuple[int, int]: + return (80, self.cell_h) + + def invalidate(self) -> None: + self.repaints += 1 + + +def _topo(*, with_island: bool = False) -> MeshTopology: + """us — YUL — Alice as a two-ring chain, optionally plus a detached island pair.""" + topo = MeshTopology(US, contacts=[YUL, ALICE]) + yul = topo.canonical(YUL.public_key) + alice = topo.canonical(ALICE.public_key) + when = utcnow() + topo.add_walk([topo.self_id, yul], snrs=[6.0], when=when, source="trace") + topo.add_walk([yul, alice], snrs=[-2.0], when=when, source="packet") + if with_island: + topo.add_walk(["c3" * 6, "d4" * 6], snrs=[1.0], when=when, source="neighbour") + return topo + + +def _screen(topo: MeshTopology, cell_h: int = 24) -> AtlasScreen: + return AtlasScreen( + session=_FakeSession(cell_h), + topo=topo, + contacts={ + topo.canonical(YUL.public_key): YUL, + topo.canonical(ALICE.public_key): ALICE, + }, + self_label="Homestead", + ) + + +def _plain(lines: list[str]) -> str: + return re.sub(r"\x1b\[[0-9;]*m", "", "\n".join(lines)) + + +# --- the layout ------------------------------------------------------------------------ + + +def test_layout_rings_by_hop_distance() -> None: + """Us at the centre, direct links ring 1, their neighbours ring 2.""" + links = [(US, "n1", 1.0), ("n1", "n2", 1.0)] + positions, rings, islands = radial_layout(US, links, 160, 96) + assert rings == {US: 0, "n1": 1, "n2": 2} + assert not islands + cx, cy = positions[US] + d1 = abs(positions["n1"][0] - cx) + abs(positions["n1"][1] - cy) + d2 = abs(positions["n2"][0] - cx) + abs(positions["n2"][1] - cy) + assert 0 < d1 < d2 # farther evidence, farther out + + +def test_layout_islands_take_the_outermost_ring() -> None: + """A cluster with no path to us lands outside everything reached.""" + links = [(US, "n1", 1.0), ("x1", "x2", 1.0)] + _positions, rings, islands = radial_layout(US, links, 160, 96) + assert islands == {"x1", "x2"} + assert rings["x1"] == rings["x2"] == rings["n1"] + 1 + + +def test_layout_spreads_a_ring_and_stays_deterministic() -> None: + """Ring members never collide, and the same input lays out the same twice.""" + links = [(US, f"n{i}", 1.0) for i in range(8)] + first = radial_layout(US, links, 200, 120) + second = radial_layout(US, links, 200, 120) + assert first == second + positions = first[0] + ring_cells = {(x // 2, y // 4) for n, (x, y) in positions.items() if n != US} + assert len(ring_cells) == 8 # every marker in its own character cell + + +def test_layout_keeps_nodes_on_canvas() -> None: + """Every position lands within the dot grid, margins included.""" + links = [(US, f"n{i}", 1.0) for i in range(6)] + [("n0", "m0", 1.0)] + positions, _rings, _islands = radial_layout(US, links, 144, 64) + for x, y in positions.values(): + assert 0 <= x < 144 and 0 <= y < 64 + + +# --- the screen ------------------------------------------------------------------------ + + +def test_atlas_renders_graph_and_overview_panel() -> None: + """The canvas fills the viewport and the panel carries legend and evidence.""" + screen = _screen(_topo()) + lines = screen.render_body(80) + assert len(lines) == 24 # canvas rows + spacer + three panel rows + body = _plain(lines) + assert "Homestead" in body and "YUL-Cartierville" in body and "Alice" in body + assert "trace 1" in body and "packet 1" in body + assert "Mesh Atlas · 3 nodes · 2 links" == screen.title + + +def test_atlas_selection_walks_and_fills_the_panel() -> None: + """→ steps overview → us → nodes; the panel reads the selection's links.""" + screen = _screen(_topo()) + screen.render_body(80) # establish the layout and the cycle + screen.handle("right") + body = _plain(screen.render_body(80)) + assert "this device" in body + screen.handle("right") + body = _plain(screen.render_body(80)) + assert "repeater" in body and "1 hop out" in body + assert "+6.0" in body # the us↔YUL link's median SNR + screen.handle("left") + screen.handle("left") + assert "←/→ walk the graph" in _plain(screen.render_body(80)) # back to overview + + +def test_atlas_marks_islands_in_the_panel() -> None: + """An island selection says so instead of quoting a bogus hop count.""" + screen = _screen(_topo(with_island=True)) + screen.render_body(80) + for _ in range(4): # overview → us → YUL → Alice → first island node + screen.handle("right") + body = _plain(screen.render_body(80)) + assert "island — no observed path to us" in body + + +def test_atlas_empty_graph_renders_guidance() -> None: + """With no evidence at all the screen explains how the atlas fills up.""" + topo = MeshTopology(US, contacts=[]) + screen = _screen(topo) + body = _plain(screen.render_body(80)) + assert "no evidence to draw yet" in body + assert "trace" in body + + +def test_atlas_details_lists_every_link() -> None: + """The Enter dialog's body carries neighbour, SNR, samples, and source.""" + topo = _topo() + screen = _screen(topo) + screen.render_body(80) + yul = topo.canonical(YUL.public_key) + text = screen._details_text(yul).plain + assert "Homestead" in text and "Alice" in text + assert "+6.0 dB" in text and "-2.0 dB" in text + assert "1×" in text and "trace" in text and "packet" in text