Atlas redesigned: walk the mesh from a focus node

The whole-graph radar view drew every node on concentric hop rings at
once — a hairball past a dozen nodes, its pan/zoom camera unable to fix
what was fundamentally overplotted. The atlas is now a graph walker:

* One node holds the focus (you, to open). The canvas draws only that
  neighbourhood — focus centred, direct neighbours fanned around it,
  braille edges coloured by SNR and faded by evidence age — and sizes
  itself to the crowd, so a two-node link is a tight six rows while a
  hub earns the full fan. The node the trail came from anchors due
  west: walking reads as moving right, backing up as moving left.
* Beneath it the links list the same neighbours as selectable rows,
  strongest first: glyph, name (palette hue, you in white), hash in the
  shared hash widget, SNR with a quality bar, samples, source tags,
  age, and how many links continue onward. The highlighted row's marker
  lights white on the canvas.
* Enter walks (the breadcrumb trail grows across the top), ⌫ steps
  back, walking into the trail-back row retraces instead of ping-pong
  growing, Home refocuses you. Typing finds any node in the graph —
  nearest first, islands flagged — and Enter teleports there, the
  trail restarting since the walk never crossed the gap. ^R rebuilds
  from storage and keeps whatever of the trail survives.

The per-node details dialog is gone (focusing a node is its details),
and the ring-relaxation layout service with it — the fan needs no
global relaxation. PgUp/PgDn page the highlight, dashboard-style.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-12 04:17:03 -04:00
1 parent 34c6ada1ae
commit 34a3b0a01d
4 files changed
+603 -899

No files matched your search

-189
View File
@@ -1,189 +0,0 @@
"""The Mesh Atlas's graph layout: hop-distance rings with force-relaxed angles.
The atlas answers the mesh's first spatial question — *how far out is everything?* —
so the layout is radial by construction: our own node pins the origin and every other
node sits at a radius fixed by its evidenced hop distance (BFS over the link graph).
That leaves exactly one degree of freedom per node, its **angle**, and that is what
the relaxation optimises: nodes are pulled toward the circular mean of their
neighbours' bearings (weighted by link strength), so chains stay radial, clusters
gather into wedges, and edges shorten — then each ring's members are pushed apart to
a minimum angular separation so markers and labels never pile up. One angular degree
of freedom keeps the optimisation deterministic and stable (no oscillating springs,
no random restarts): the same evidence lays out the same picture every time, and a
node keeps roughly the same bearing across rebuilds because its seed angle is a hash
of its id.
Evidence islands — link clusters known only through a repeater's neighbour table,
with no observed path back to us — take one shared ring outside everything reached;
their mutual edges pull them into a visible cluster there.
Positions come out in **unit space**: radius ``ring / max_ring`` (≤ 1.0), centre at
the origin. The screen owns projection — aspect, zoom, and pan — so the layout never
needs recomputing as the user moves the camera; only fresh evidence relays it.
Pure data-in/data-out (no UI, no storage), like every service.
"""
from __future__ import annotations
import math
import zlib
from dataclasses import dataclass
_TAU = math.tau
#: Angular relaxation sweeps. Each sweep moves every node part-way toward its
#: neighbours' mean bearing then re-spaces each ring; a few dozen sweeps settle a
#: mesh-sized graph (tens of nodes) far below one dot of movement.
_RELAX_SWEEPS = 48
#: How far a node moves toward its neighbours' mean bearing per sweep (0..1).
_RELAX_ALPHA = 0.35
#: The widest minimum angular separation a ring enforces (radians, ≈20°). Crowded
#: rings fall back to their even-spacing angle (2π/n) — the most separation that
#: exists — so the floor only ever *relaxes*, never over-constrains.
_MIN_SEPARATION = 0.35
#: Separation passes per sweep: each pass walks the ring once, splitting deficits
#: between neighbouring pairs; a handful converges since rings hold few nodes.
_SEPARATION_PASSES = 4
@dataclass(slots=True)
class AtlasLayout:
"""One laid-out atlas graph, in unit space.
Attributes:
positions: Per-node ``(x, y)`` with the centre at the origin and every
radius ≤ 1.0. The screen projects these through aspect/zoom/pan.
rings: Per-node hop ring (0 = our own node; islands share the outermost).
islands: Nodes with no observed path back to us.
max_ring: The outermost ring index in use (0 for a lone node).
"""
positions: dict[str, tuple[float, float]]
rings: dict[str, int]
islands: frozenset[str]
max_ring: int
def _hash_angle(node: str) -> float:
"""A deterministic per-node seed bearing, stable across processes and rebuilds.
A CRC rather than :func:`hash`, which Python salts per process — the whole point
is that a node sits at the same clock position tomorrow as today.
"""
return zlib.crc32(node.encode()) / 0xFFFFFFFF * _TAU
def _circular_mean(bearings: list[tuple[float, float]]) -> float | None:
"""The weighted circular mean of ``(angle, weight)`` bearings, or ``None`` if flat."""
sin_sum = sum(w * math.sin(a) for a, w in bearings)
cos_sum = sum(w * math.cos(a) for a, w in bearings)
if abs(sin_sum) < 1e-12 and abs(cos_sum) < 1e-12:
return None
return math.atan2(sin_sum, cos_sum) % _TAU
def _toward(angle: float, target: float, alpha: float) -> float:
"""``angle`` moved ``alpha`` of the way toward ``target`` along the short arc."""
delta = (target - angle + math.pi) % _TAU - math.pi
return (angle + alpha * delta) % _TAU
def _space_ring(members: list[str], angles: dict[str, float]) -> None:
"""Push one ring's members apart to the separation floor, preserving their order.
Members are walked in angular order and every adjacent pair (wrap included)
closer than the floor is split apart symmetrically. Deficits propagate around
the ring over :data:`_SEPARATION_PASSES` passes; a full ring (n·floor ≥ 2π)
degrades gracefully toward even spacing rather than fighting itself, because
the floor never exceeds ``2π / n``.
"""
n = len(members)
if n < 2:
return
floor = min(_MIN_SEPARATION, _TAU / n)
for _ in range(_SEPARATION_PASSES):
ordered = sorted(members, key=lambda m: angles[m])
moved = False
for i in range(n):
a, b = ordered[i], ordered[(i + 1) % n]
gap = (angles[b] - angles[a]) % _TAU
if gap + 1e-12 < floor:
push = (floor - gap) / 2
angles[a] = (angles[a] - push) % _TAU
angles[b] = (angles[b] + push) % _TAU
moved = True
if not moved:
return
def compute_layout(self_id: str, links: list[tuple[str, str, float]]) -> AtlasLayout:
"""Lay the evidence graph out on hop rings with relaxed angular placement.
Args:
self_id: Canonical id of our own node (always placed, even with no links).
links: The evidence graph as ``(a, b, strength)`` triples (strength > 0;
parallel duplicates keep their strongest reading).
Returns:
The unit-space :class:`AtlasLayout`.
"""
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))
# Hop rings: BFS from us; unreached nodes (islands) share one outer ring.
rings: dict[str, int] = {self_id: 0}
frontier = [self_id]
while frontier:
nxt: list[str] = []
for node in frontier:
for other in sorted(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)
# Seed every bearing from the node's id hash, then relax: each sweep pulls a
# node toward the strength-weighted circular mean of its neighbours' bearings
# (the centre node exerts no pull — it has no bearing) and re-spaces each ring.
angles: dict[str, float] = {
node: _hash_angle(node) for node in adjacency if node != self_id
}
by_ring: dict[int, list[str]] = {}
for node, ring in rings.items():
if ring:
by_ring.setdefault(ring, []).append(node)
order = sorted(angles) # a stable sweep order keeps the result deterministic
for _ in range(_RELAX_SWEEPS):
for node in order:
bearings = [
(angles[other], strength)
for other, strength in adjacency[node].items()
if other != self_id
]
target = _circular_mean(bearings)
if target is not None:
angles[node] = _toward(angles[node], target, _RELAX_ALPHA)
for members in by_ring.values():
_space_ring(members, angles)
positions: dict[str, tuple[float, float]] = {self_id: (0.0, 0.0)}
for node, angle in angles.items():
radius = rings[node] / max_ring if max_ring else 1.0
positions[node] = (radius * math.cos(angle), radius * math.sin(angle))
return AtlasLayout(
positions=positions, rings=rings, islands=islands, max_ring=max_ring
)
+9 -8
View File
@@ -1,11 +1,12 @@
"""The ``atlas`` tool: the mesh's observed shape, drawn as a live link graph.
"""The ``atlas`` tool: the mesh's observed shape, explored one node at a time.
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 on hop-distance rings around
our own node. Pannable and zoomable like the street map, with find-as-you-type node
search, Tab-walking, and per-link detail. The geographic map answers *where* the mesh
is; the atlas answers *how it hangs together*.
Opens the full-screen Mesh atlas (see :mod:`meshterm.ui.atlas_screen`): a walkable
browser over the evidence graph — trace walks, firmware routes, overheard relay
chains, repeater neighbour tables. One node holds the focus, its neighbourhood draws
as SNR-coloured braille edges on a small clean canvas, and its links list beneath as
rows with quality bars and evidence; Enter walks the graph, ⌫ backtracks along the
breadcrumb trail, and typing finds any node (islands included). 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
@@ -34,7 +35,7 @@ class AtlasTool(Tool):
# the column the others align to. The wireframe globe reads as the logical topology,
# the geographic map's 🌍 counterpart.
icon = "🌐"
help = "Draw the mesh's observed topology — links, SNR, hop rings"
help = "Walk the mesh's observed topology — links, SNR, evidence"
category = "Mesh"
order = 32 # beside Map: the logical shape next to the geographic one
File diff suppressed because it is too large. Load diff
+123 -165
View File
@@ -1,17 +1,16 @@
"""Mesh Atlas tests: the ring layout service and the screen's camera, find, and panel.
"""Mesh atlas tests: the focus-and-walk browser over a hand-built topology.
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.
The screen is driven headless against a fake session, the same approach as the
dashboard tests: render_body is pure lines-out, handle() is pure state, so walking,
backtracking, find, and the canvas/list split are all assertable without a terminal.
"""
from __future__ import annotations
import math
import re
from datetime import timedelta
from meshterm.core.models import Contact, utcnow
from meshterm.services.atlas_layout import _MIN_SEPARATION, compute_layout
from meshterm.services.topology import MeshTopology
from meshterm.ui.atlas_screen import AtlasScreen
@@ -61,73 +60,29 @@ def _plain(lines: list[str]) -> str:
return re.sub(r"\x1b\[[0-9;]*m", "", "\n".join(lines))
def _radius(pos: tuple[float, float]) -> float:
return math.hypot(*pos)
# --- rendering ----------------------------------------------------------------------------
def _angle(pos: tuple[float, float]) -> float:
return math.atan2(pos[1], pos[0]) % math.tau
# --- the layout service ------------------------------------------------------------------
def test_layout_rings_by_hop_distance() -> None:
"""Us at the origin, direct links on ring 1, their neighbours on ring 2."""
layout = compute_layout(US, [(US, "n1", 1.0), ("n1", "n2", 1.0)])
assert layout.rings == {US: 0, "n1": 1, "n2": 2}
assert not layout.islands and layout.max_ring == 2
assert layout.positions[US] == (0.0, 0.0)
assert 0 < _radius(layout.positions["n1"]) < _radius(layout.positions["n2"]) <= 1.0
def test_layout_islands_take_the_outermost_ring() -> None:
"""A cluster with no path to us lands outside everything reached."""
layout = compute_layout(US, [(US, "n1", 1.0), ("x1", "x2", 1.0)])
assert layout.islands == {"x1", "x2"}
assert layout.rings["x1"] == layout.rings["x2"] == layout.rings["n1"] + 1
def test_layout_chains_stay_radial() -> None:
"""Relaxation pulls a chain's outer node onto its parent's bearing."""
layout = compute_layout(US, [(US, "n1", 1.0), ("n1", "n2", 1.0)])
gap = abs(_angle(layout.positions["n1"]) - _angle(layout.positions["n2"]))
gap = min(gap, math.tau - gap)
assert gap < 0.15 # essentially the same bearing: a straight radial spoke
def test_layout_spreads_a_ring_and_stays_deterministic() -> None:
"""Ring members keep a minimum angular gap, and the same input lays out the same."""
links = [(US, f"n{i}", 1.0) for i in range(8)]
first = compute_layout(US, links)
second = compute_layout(US, links)
assert first.positions == second.positions
angles = sorted(_angle(first.positions[f"n{i}"]) for i in range(8))
gaps = [b - a for a, b in zip(angles, angles[1:])]
gaps.append(math.tau - angles[-1] + angles[0])
assert min(gaps) >= min(_MIN_SEPARATION, math.tau / 8) - 1e-6
def test_layout_stays_in_unit_space() -> None:
"""Every position lands within the unit circle the screen projects from."""
links = [(US, f"n{i}", 1.0) for i in range(6)] + [("n0", "m0", 1.0), ("q1", "q2", 0.5)]
layout = compute_layout(US, links)
assert all(_radius(p) <= 1.0 + 1e-9 for p in layout.positions.values())
# --- the screen: rendering ----------------------------------------------------------------
def test_atlas_renders_graph_and_overview_panel() -> None:
"""The canvas fills the viewport and the panel carries legend and evidence."""
def test_atlas_opens_focused_on_us_with_the_link_list() -> None:
"""The default focus is our own node: canvas, legend, and its links beneath."""
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 "rings = hops out" in body # the overview hint row
assert "Mesh atlas · 3 nodes · 2 links" == screen.title
body = _plain(screen.render_body(80))
assert "Homestead" in body and "this device" in body
assert "Links" in body and "strongest observed first" in body
assert "YUL-Cartierville" in body # our one neighbour, as a selectable row
assert "edge = SNR" in body # the canvas legend
assert screen.title == "Mesh atlas — Homestead · 3 nodes · 2 links"
def test_atlas_link_rows_carry_snr_evidence_and_onward_count() -> None:
"""A neighbour row reads SNR, samples, source tags, age, and its onward links."""
screen = _screen(_topo())
body = _plain(screen.render_body(80))
row = next(line for line in body.split("\n") if "YUL-Cartierville" in line and "❯" in line)
assert "+6.0" in row # the link's median SNR
assert "1×" in row # samples
assert "T" in row # trace evidence tag
assert "⋯ 1" in row # one link onward (YUL — Alice)
def test_atlas_empty_graph_renders_guidance() -> None:
@@ -139,127 +94,129 @@ def test_atlas_empty_graph_renders_guidance() -> None:
assert "trace" in body
def test_atlas_details_lists_every_link() -> None:
"""The Enter dialog's body carries neighbour, SNR, samples, and source."""
# --- walking ------------------------------------------------------------------------------
def test_atlas_enter_walks_and_grows_the_trail() -> None:
"""Enter focuses the highlighted neighbour; the breadcrumb trail reads the walk."""
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
# --- the screen: camera -------------------------------------------------------------------
def test_atlas_zooms_pans_and_resets_like_the_map() -> None:
"""PgUp/PgDn step the zoom, arrows pan (clamped), Home restores the full fit."""
screen = _screen(_topo())
screen.render_body(80)
assert screen._zoom == 1.0
screen.handle("pageup")
screen.handle("pageup")
assert screen._zoom == 2.25
screen.render_body(80)
assert "2.2×" in screen.title
screen.handle("right")
screen.handle("down")
assert screen._cam != (0.0, 0.0)
# At 1× the camera clamps back to the origin — the graph can't be lost.
screen.handle("pagedown")
screen.handle("pagedown")
screen.handle("pagedown")
assert screen._zoom == 1.0 and screen._cam == (0.0, 0.0)
screen.handle("pageup")
screen.handle("left")
screen.handle("home")
assert screen._zoom == 1.0 and screen._cam == (0.0, 0.0)
def test_atlas_fine_pan_moves_less_than_coarse() -> None:
"""Shift+arrow nudges the camera a fraction of a coarse step."""
screen = _screen(_topo())
screen.render_body(80)
screen.handle("pageup") # free some pan range
screen.handle("right")
coarse = screen._cam[0]
screen.handle("home")
screen.handle("pageup")
screen.handle("shift_right")
assert 0 < screen._cam[0] < coarse
# --- the screen: selection and find --------------------------------------------------------
def test_atlas_tab_walks_and_fills_the_panel() -> None:
"""Tab 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("tab")
body = _plain(screen.render_body(80))
assert "this device" in body
screen.handle("tab")
screen.handle("enter") # walk to YUL (our only neighbour)
assert screen._focus == topo.canonical(YUL.public_key)
body = _plain(screen.render_body(80))
assert "Homestead › YUL-Cartierville" in body # the trail
assert "repeater" in body and "1 hop out" in body
assert "+6.0" in body # the us↔YUL link's median SNR
# Esc peels the selection back to the overview.
screen.handle("escape")
assert "rings = hops out" in _plain(screen.render_body(80))
assert "Alice" in body # YUL's onward neighbour is now a row
assert "⌫ back" in body # the row leading home is marked
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("tab")
body = _plain(screen.render_body(80))
assert "island — no observed path to us" in body
def test_atlas_find_filters_selects_and_peels() -> None:
"""Typing narrows to matches, Enter adopts the first, Esc peels layer by layer."""
import asyncio
def test_atlas_backspace_steps_back_along_the_trail() -> None:
"""⌫ pops the trail one step; at the trail's start it does nothing."""
topo = _topo()
screen = _screen(topo)
screen.render_body(80)
screen.handle("enter")
assert len(screen._trail) == 2
screen.handle("backspace")
assert screen._trail == [topo.self_id]
screen.handle("backspace") # already home — inert
assert screen._trail == [topo.self_id]
def test_atlas_walking_into_the_back_node_pops_instead_of_growing() -> None:
"""Enter on the trail-back row retraces rather than appending a ping-pong walk."""
topo = _topo()
screen = _screen(topo)
screen.render_body(80)
screen.handle("enter") # us → YUL
rows = screen._rows()
screen._index = rows.index(topo.self_id) # highlight the row leading back home
screen.handle("enter")
assert screen._trail == [topo.self_id] # popped, not [us, yul, us]
def test_atlas_home_refocuses_us() -> None:
"""Home resets the walk to our own node from anywhere."""
topo = _topo()
screen = _screen(topo)
screen.render_body(80)
screen.handle("enter") # us → YUL
screen.handle("home")
assert screen._trail == [topo.self_id]
def test_atlas_came_from_anchors_west_on_the_canvas() -> None:
"""The node the trail arrived from sits due west of the focus."""
topo = _topo()
screen = _screen(topo)
screen.render_body(80)
screen.handle("enter") # focus YUL; we came from us
placed = screen._place_neighbours(100, 40, 60.0, 30.0)
assert placed[topo.self_id] == (40, 40) # cx - rx, level with the centre
alice = topo.canonical(ALICE.public_key)
assert placed[alice][0] > 100 # everyone else fans east
# --- find ---------------------------------------------------------------------------------
def test_atlas_find_lists_matches_and_teleports() -> None:
"""Typing filters every known node; Enter focuses the match and restarts the trail."""
topo = _topo()
screen = _screen(topo)
screen.render_body(80)
for ch in "ali":
screen.handle("text", ch)
assert screen._filter == "ali"
screen.render_body(80)
assert "1 match" in screen.title
assert "find: ali" in screen.footer_hint
body = _plain(screen.render_body(80))
assert "1 of" in body and "Alice" in body # the find panel names the match
# Non-matching labels drop to context; the match stays labelled on canvas.
canvas_only = _plain(screen.render_body(80)[:-4])
assert "Alice" in canvas_only and "YUL-Cartierville" not in canvas_only
assert "Matches" in body and "Alice" in body
assert "2 hops out" in body # the match row says how far away it sits
assert "1 match" in screen.title
screen.handle("enter") # adopt the first match
screen.handle("enter")
alice = topo.canonical(ALICE.public_key)
assert screen._focus == alice
assert screen._trail == [alice] # a teleport restarts the trail
assert screen._filter == ""
assert screen._selected == topo.canonical(ALICE.public_key)
def test_atlas_find_marks_islands() -> None:
"""A match with no path to us reads island, and focusing it says why."""
screen = _screen(_topo(with_island=True))
screen.render_body(80)
for ch in "c3":
screen.handle("text", ch)
body = _plain(screen.render_body(80))
assert "island" in body
screen.handle("enter")
body = _plain(screen.render_body(80))
assert "island — no observed path to you" in body
def test_atlas_esc_peels_find_then_dismisses() -> None:
"""Esc clears an active find first; the next Esc leaves the screen."""
import asyncio
screen = _screen(_topo())
screen.render_body(80)
screen.handle("text", "a")
async def drive() -> object:
screen.future = asyncio.get_running_loop().create_future()
screen.handle("escape") # selection → overview
assert screen._selected is None and not screen.future.done()
screen.handle("escape") # overview → dismiss
screen.handle("escape") # peels the filter
assert screen._filter == "" and not screen.future.done()
screen.handle("escape") # dismisses
return await screen.future
assert asyncio.run(drive()) is None
def test_atlas_rebuild_refreshes_the_evidence() -> None:
"""Ctrl+R re-reads storage and the new link count shows on the next paint."""
# --- rebuild ------------------------------------------------------------------------------
def test_atlas_rebuild_refreshes_the_evidence_and_keeps_the_trail() -> None:
"""^R re-reads storage; the trail survives where its nodes still exist."""
grown = _topo(with_island=True)
screen = AtlasScreen(
session=_FakeSession(),
@@ -273,3 +230,4 @@ def test_atlas_rebuild_refreshes_the_evidence() -> None:
screen.handle("retry")
screen.render_body(80)
assert "3 links" in screen.title
assert screen._trail == [grown.self_id]