Files
MeshTerm/meshterm/ui/pathline.py
T
Jean-Pierre MartineauandClaude Fable 5 2c04fb5b96 Path line: path_text-parity factory, cursor-aware wrap, plain pin for tests
path_line() builds a PathLine from path_text's exact vocabulary (verified
character-for-character in tests), wrapped() carries the composer's
insertion cursor — riding the trailing arrow when its seam is the line
break — and conftest pins MESHTERM_POWERLINE=0 so screen assertions never
depend on which terminal runs the suite.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26 20:30:50 -04:00

447 lines
20 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Path lines — the flexible hop-sequence text widget (powerline chips or arrows).
This is the successor to :func:`~meshterm.ui.widgets.path_text` as THE way a hop
sequence renders as text — a trace's walked route, a packet's ``via`` chain, a
message's delivery paths, the composer's preview, a trophy row. Where ``path_text``
is one fixed presentation (arrow-joined, one line, overflow left entirely to the
caller), a :class:`PathLine` separates *what the hops are* from *how the line is
drawn*, so every surface the survey found can eventually route through it:
* **Two separator styles.** ``plain`` joins hops with muted ``→`` arrows — today's
look, unchanged. ``powerline`` renders each hop as a colour-filled chip joined by
the solid-triangle separator U+E0B0 (foreground = previous chip's fill, background
= next's — the interlocking oh-my-posh look), the chip fill being the node's
hash-derived hue (:func:`~meshterm.ui.theme.node_style`), our own node the pure
``you`` white, a keyless hop grey. ``auto`` (the default) picks powerline exactly
when the terminal can draw it (:func:`~meshterm.ui.termfont.powerline_enabled` —
a recommended font, a glyph-capable renderer, or the user's override) and falls
back to arrows everywhere else, so no terminal ever sees tofu.
* **Three overflow answers**, matching the three patterns the surfaces already use:
:meth:`PathLine.text` is the full one-liner (for callers that ellipsize or
h-scroll it themselves), :meth:`PathLine.ellipsized` fits a width by eliding
*middle* hops behind a ``⋯`` mark — both endpoints survive, unlike a tail
truncation that amputates the destination — and :meth:`PathLine.wrapped` breaks
at hop boundaries under a hanging indent (never mid-name, never mid-chip).
* **The same hop semantics everywhere.** A :class:`PathHop` carries what the app's
conventions need: the label (a name, or a hash standing as identity), the key any
known prefix of which picks the hue, the ``you`` flag, the trace-flavour
``(3d)`` annotation, the lit-prefix width for hash labels (the
``highlighted_hash`` two-tone), the ``dim`` fade for resolved return legs, and an
explicit style override for context colourings that outrank identity. Chips keep
the exact same words as arrows — only colours and separators change — so a route
reads identically whichever mode drew it.
Existing call sites still render through ``path_text``; migrating them here is a
separate, per-surface pass. The composer's insertion cursor is the one deliberate
mode exception: a render asked for ``cursor_arrow`` always draws plain arrows, since
an insertion point lives *between* hops and chips fuse that seam shut.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Callable, Optional, Sequence
from rich.text import Text
from ..core.models import LOCAL_DEVICE_LABEL
from .termfont import powerline_enabled
from .theme import MESH_THEME, node_style
#: The powerline solid right-pointing triangle (U+E0B0) — the one glyph the widget
#: uses, deliberately the *core* set so every recommended font qualifies (the rounded
#: caps at U+E0B4+ exist only in full Nerd Font patches).
POWERLINE_SEP = "\ue0b0"
#: The plain-mode joining arrow, exactly as ``path_text`` draws it today.
_ARROW = " → "
#: Chip ink: near-black slate for readable text on every spectrum hue and on white.
_CHIP_FG = "#0f172a"
#: Chip ink, softened — annotations and a hash label's unlit tail (the two-tone).
_CHIP_FG_SOFT = "#334155"
#: Chip fill for a keyless hop — the ``faint`` grey; colour stays reserved for
#: keyed identities in chips just as it is in arrow mode.
_KEYLESS_BG = "#64748b"
#: Our own node's chip fill: the pure ``you`` white.
_YOU_BG = "#ffffff"
#: A dimmed hop's chip: dark slate fill with muted ink, receding like ``faint`` text.
_DIM_BG = "#334155"
_DIM_FG = "#94a3b8"
#: The mark standing in for elided middle hops (see :meth:`PathLine.ellipsized`) —
#: rendered as a dim pseudo-hop so it recedes in both modes.
_ELISION = "⋯"
@dataclass(frozen=True)
class PathHop:
"""One hop of a path line — the semantics, independent of how it is drawn.
Attributes:
label: What is shown — a resolved name, or a hash standing as the node's
identity (set ``lit_bytes`` for the two-tone prefix in that case).
key: Any known prefix of the node's key/hash — picks the hash-derived hue
(its first byte, so every prefix agrees). ``None`` renders muted/grey:
colour is reserved for keyed identities.
you: Our own node — pure white, in either mode.
annotation: The trace-flavour hash note, rendered ``" (3d)"`` after the
label in both modes (pass the bare ``3d``, no parentheses).
lit_bytes: For a hash label: leading *bytes* drawn in the hue (the
``highlighted_hash`` two-tone), the rest muted/soft. ``0`` for names.
dim: Fade the hop (and the arrow leading into it) — a planned route's
resolved return leg, "not yours to compose".
style: Explicit colour override — a hex style (``"#rrggbb"``, attributes
allowed) or theme name — for context colourings that outrank identity.
Plain mode uses it as the label style; powerline as the chip fill.
"""
label: str
key: Optional[str] = None
you: bool = False
annotation: Optional[str] = None
lit_bytes: int = 0
dim: bool = False
style: Optional[str] = None
def _style_hex(style: str) -> Optional[str]:
"""The ``#rrggbb`` a style string or theme name resolves to, else ``None``."""
for token in reversed(style.split()):
if token.startswith("#") and len(token) == 7:
return token
themed = MESH_THEME.styles.get(style)
if themed is not None and themed.color is not None:
try:
return "#" + themed.color.get_truecolor().hex.lstrip("#")
except Exception:
return None
return None
class PathLine:
"""A hop sequence, renderable as arrow-joined text or powerline chips.
Build one from :class:`PathHop` entries, then ask for the shape the surface
needs: :meth:`text` (full line), :meth:`ellipsized` (middle-elided to a width),
or :meth:`wrapped` (hop-boundary lines under a hanging indent).
Args:
hops: The hops in display order (the widget never reorders; a reversed or
mirrored walk is the caller's composition).
mode: ``"auto"`` (powerline when the terminal can draw it — the default),
``"powerline"``, or ``"plain"``.
separator: The plain-mode joiner. Defaults to the app-wide ``" → "``; a
surface with its own convention (the atlas trail's ``" › "``) may pass
it. Ignored by powerline mode.
empty: The muted text a hopless path reads as (``"direct"``).
"""
def __init__(
self,
hops: Sequence[PathHop],
*,
mode: str = "auto",
separator: str = _ARROW,
empty: str = "direct",
) -> None:
self._hops = list(hops)
self._mode = mode
self._separator = separator
self._empty = empty
@property
def hops(self) -> list[PathHop]:
"""The hops, for callers that splice lines together (endpoints + relays)."""
return list(self._hops)
# --- the three shapes ---------------------------------------------------------
def text(self, *, cursor_arrow: Optional[int] = None) -> Text:
"""The full one-line rendering; overflow is the caller's call, per surface.
Args:
cursor_arrow: Draw this joining gap (0-based, between hops *j* and
*j+1*) as the composer's reverse-video insertion cursor. Forces
plain mode for the render — chips fuse the seam an insertion
point needs to sit in.
Returns:
A one-line :class:`Text` (the ``empty`` note when there are no hops).
"""
if not self._hops:
return Text(self._empty, style="muted")
return self._render(self._hops, cursor_arrow=cursor_arrow)
def ellipsized(self, width: int) -> Text:
"""The line fitted to ``width`` by eliding *middle* hops behind ``⋯``.
Endpoints matter most — a route reads origin and destination first — so the
fit keeps the first hop and as much of the tail as possible, then drops the
head too if it must, and only as a last resort truncates a single over-long
hop the classic way.
Args:
width: The cell budget the returned line must fit in.
Returns:
A one-line :class:`Text` no wider than ``width``.
"""
full = self.text()
if full.cell_len <= width or not self._hops:
return full
mark = PathHop(_ELISION, dim=True)
count = len(self._hops)
for head in (1, 0):
for tail in range(count - 1 - head, 0, -1):
kept = self._hops[:head] + [mark] + self._hops[-tail:]
candidate = self._render(kept)
if candidate.cell_len <= width:
return candidate
last = self._render([mark, self._hops[-1]]) if count > 1 else full
last.truncate(width, overflow="ellipsis")
return last
def wrapped(
self, width: int, *, indent: int = 0, cursor_arrow: Optional[int] = None
) -> list[Text]:
"""The line broken at hop boundaries, hanging under ``indent`` columns.
The hanging-indent convention: the caller lays its label lane on the first
line, so that line is returned *without* the indent prefix while every
continuation starts with ``indent`` spaces; all lines fit ``width`` and the
content column is uniformly ``width - indent`` wide. Plain-mode lines that
continue end with a trailing ``→`` (the "path goes on" cue); chip lines
always close with their pointed edge. A single hop wider than the content
column stands alone, truncated with an ellipsis.
Args:
width: The full line budget, indent included.
indent: The hanging-indent column the continuations align under.
cursor_arrow: The composer's insertion cursor, as in :meth:`text` (0-based
seam index). Forces plain arrows; a cursor sitting exactly on a line
break lands on that line's trailing cue, so it is always visible.
Returns:
The lines, in order (a single ``empty`` note when there are no hops).
"""
if not self._hops:
return [Text(self._empty, style="muted")]
budget = max(1, width - indent)
plain = cursor_arrow is not None or self._resolved_mode() != "powerline"
trail = Text.assemble((" →", "muted")) if plain else Text()
groups: list[list[PathHop]] = [[]]
for hop in self._hops:
candidate = groups[-1] + [hop]
rendered = self._render(candidate, force_plain=plain)
# Reserve the continuation cue: any line but the last will carry it.
if groups[-1] and rendered.cell_len + trail.cell_len > budget:
groups.append([hop])
else:
groups[-1] = candidate
lines: list[Text] = []
base = 0 # the global index of the group's first hop, for cursor mapping
for i, group in enumerate(groups):
local: Optional[int] = None
if cursor_arrow is not None and 0 <= cursor_arrow - base < len(group) - 1:
local = cursor_arrow - base
line = Text() if i == 0 else Text(" " * indent)
body = self._render(group, cursor_arrow=local, force_plain=plain)
if body.cell_len > budget:
body.truncate(budget, overflow="ellipsis")
line.append_text(body)
if plain and i < len(groups) - 1:
if cursor_arrow == base + len(group) - 1: # the cursor rides the break
line.append(" ")
line.append("→", style="selected")
else:
line.append_text(trail.copy())
base += len(group)
lines.append(line)
return lines
# --- rendering ----------------------------------------------------------------
def _resolved_mode(self) -> str:
"""The effective mode: ``auto`` resolves against the terminal's verdict."""
if self._mode != "auto":
return self._mode
return "powerline" if powerline_enabled() else "plain"
def _render(
self,
hops: list[PathHop],
*,
cursor_arrow: Optional[int] = None,
force_plain: bool = False,
) -> Text:
"""Join ``hops`` in the effective mode (plain whenever a cursor is asked)."""
if not force_plain and cursor_arrow is None and self._resolved_mode() == "powerline":
return self._render_chips(hops)
return self._render_plain(hops, cursor_arrow)
def _render_plain(self, hops: list[PathHop], cursor_arrow: Optional[int]) -> Text:
"""Arrow-joined hops — ``path_text``'s presentation, hop by hop."""
text = Text()
for i, hop in enumerate(hops):
if i:
if cursor_arrow is not None and i - 1 == cursor_arrow:
text.append(" ")
text.append("→", style="selected")
text.append(" ")
else:
text.append(self._separator, style="faint" if hop.dim else "muted")
text.append_text(self._plain_hop(hop))
return text
def _plain_hop(self, hop: PathHop) -> Text:
"""One arrow-mode hop: label in its identity style, annotation muted."""
note_style = "faint" if hop.dim else "muted"
text = Text()
if hop.dim:
text.append(hop.label, style="faint")
elif hop.style:
text.append(hop.label, style=hop.style)
elif hop.you:
text.append(hop.label, style="you")
elif hop.key and hop.lit_bytes > 0:
split = hop.lit_bytes * 2 # the highlighted_hash two-tone, in hex digits
text.append(hop.label[:split], style=node_style(hop.key))
text.append(hop.label[split:], style="muted")
elif hop.key:
text.append(hop.label, style=node_style(hop.key))
else:
text.append(hop.label, style="muted")
if hop.annotation:
text.append(f" ({hop.annotation})", style=note_style)
return text
def _render_chips(self, hops: list[PathHop]) -> Text:
"""Powerline chips: each hop filled with its hue, seams interlocked."""
fills = [self._chip_fill(hop) for hop in hops]
text = Text()
for i, hop in enumerate(hops):
if i:
text.append(POWERLINE_SEP, style=f"{fills[i - 1]} on {fills[i]}")
text.append_text(self._chip(hop, fills[i]))
text.append(POWERLINE_SEP, style=fills[-1]) # the pointed edge into the page
return text
def _chip_fill(self, hop: PathHop) -> str:
"""A chip's fill colour: override, white you, dim slate, hue, keyless grey."""
if hop.style:
resolved = _style_hex(hop.style)
if resolved:
return resolved
if hop.you:
return _YOU_BG
if hop.dim:
return _DIM_BG
if hop.key:
return _style_hex(node_style(hop.key)) or _KEYLESS_BG
return _KEYLESS_BG
def _chip(self, hop: PathHop, fill: str) -> Text:
"""One chip: same words as arrow mode, dark ink on the identity fill."""
ink = _DIM_FG if hop.dim else _CHIP_FG
soft = _DIM_FG if hop.dim else _CHIP_FG_SOFT
text = Text()
text.append(" ", style=f"on {fill}")
if hop.lit_bytes > 0 and not hop.dim:
split = hop.lit_bytes * 2
text.append(hop.label[:split], style=f"bold {ink} on {fill}")
text.append(hop.label[split:], style=f"{soft} on {fill}")
else:
weight = "" if hop.dim else "bold "
text.append(hop.label, style=f"{weight}{ink} on {fill}")
if hop.annotation:
text.append(f" ({hop.annotation})", style=f"{soft} on {fill}")
text.append(" ", style=f"on {fill}")
return text
def _shorten(value: str, hash_bytes: Optional[int]) -> str:
"""Bare lowercase hex, truncated to ``hash_bytes`` bytes (whole when falsy)."""
raw = value.lower().removeprefix("0x")
return raw[: hash_bytes * 2] if hash_bytes else raw
def path_line(
hops: Sequence[Optional[str]],
resolve: Callable[[str], Optional[str]] = lambda hop: hop,
*,
prefix_bytes: int = 0,
self_name: Optional[str] = None,
empty: str = "direct",
show_hash: bool = False,
hash_bytes: Optional[int] = None,
device_hash: Optional[str] = None,
dim_from: Optional[int] = None,
hash_as_name: bool = False,
mode: str = "auto",
) -> PathLine:
"""Build a :class:`PathLine` from raw hop hashes — ``path_text``'s vocabulary.
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, ``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.
Args:
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).
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"``).
show_hash: Annotate named hops (and, with ``device_hash``, our device) with
their hash in parentheses — the trace presentation.
hash_bytes: Truncate shown/annotated hashes to this byte width.
device_hash: Our own device's key, annotated onto ``None`` hops when
``show_hash`` is on.
dim_from: Fade hops at/after this rendered index (``None`` dims nothing).
hash_as_name: Present each unnamed hop as its muted identity hash at the
``prefix_bytes`` width, annotated with its addressed byte.
mode: The :class:`PathLine` mode (``"auto"``/``"powerline"``/``"plain"``).
Returns:
The assembled :class:`PathLine`.
"""
shown = [h for h in hops if h is None or h]
built: list[PathHop] = []
for i, hop in enumerate(shown):
dim = dim_from is not None and i >= dim_from
if hop is None:
note = _shorten(device_hash, hash_bytes) if (show_hash and device_hash) else None
built.append(
PathHop(self_name or LOCAL_DEVICE_LABEL, you=True, annotation=note, dim=dim)
)
continue
named = resolve(hop)
if named and named != hop:
built.append(PathHop(
named,
key=hop,
you=bool(self_name and named == self_name),
annotation=_shorten(hop, hash_bytes) if show_hash else None,
dim=dim,
))
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))
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))
return PathLine(built, mode=mode, empty=empty)