From 282334c7618404d03a68bd4a2a70df8a3abbe55b Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Wed, 16 Sep 2026 00:05:23 -0400 Subject: [PATCH] The purge preview shows the evidence in lanes of its own kind MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The preview's rows led on a PCTL lane and followed it with WHY IT RANKS LOW, one header over three lanes that held a contact's n-th weakest reason — so a message count, an age, a packet tally and a hop count moved between columns from row to row and nothing in a column meant the same thing twice. The lanes are fixed by kind now: HEARD and PKTS first, in the Contacts list's own order and drawn in its own grammar (the column age under recency heat, a tally muted, a faint dash for none), then the two the sweep adds, MSGS and HOPS. Each is measured across the victims and headed by a word right-aligned over its own values. The percentile goes with the phrases. A rank is the score's reading of itself, so a lane of them restated the order the list was already in; what an audit needs is the measurements, which is what a reader can check against what they know. The row pins its name out of the horizontal scroll instead — the evidence is what a narrow terminal cuts, and the name is what says whose evidence it is. ScoredContact drops the reasons it was the only consumer of. A lane also stops trusting a name to be ordinary text. A name is written by whoever owns the radio, so fit_cells — THE lane fitter, and every column's — now cuts between glyphs rather than codepoints and folds what no terminal can draw: cutting an emoji sequence in half stranded a joiner that swallowed the ellipsis appended after it, leaving the lane a cell short of what was drawn and every column right of the name starting late, and a newline or an escape in a name ended the row mid-lane whatever it measured. Both are settled in emoji_width, which already owns what this terminal really does with these codepoints. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/core/contact_score.py | 88 +++----------- meshterm/ui/menus.py | 21 +++- meshterm/ui/purge_screen.py | 215 +++++++++++++++++++++------------ meshterm/ui/tui/emoji_width.py | 110 ++++++++++++++++- tests/test_contact_score.py | 10 -- tests/test_device_config.py | 5 +- tests/test_emoji_width.py | 42 +++++++ tests/test_menus.py | 31 +++++ 8 files changed, 356 insertions(+), 166 deletions(-) diff --git a/meshterm/core/contact_score.py b/meshterm/core/contact_score.py index 6ddbe89..9b3b6b6 100644 --- a/meshterm/core/contact_score.py +++ b/meshterm/core/contact_score.py @@ -41,11 +41,13 @@ admin credentials are stored, and the unobserved contact above. They are still s still ranked — they are real contacts and the percentile scale is the whole population — but they are never swept. -**What is displayed is the percentile, never the score.** A raw ``47.3`` means nothing -without the distribution it came from; a contact's *rank against your other contacts* is -self-calibrating, needs no legend, and stays comparable when the weights change. So -:class:`ScoredContact` carries :attr:`~ScoredContact.percentile` and the UI shows only that -(see :func:`percentile_rank`). +**The score is never displayed.** A raw ``47.3`` means nothing without the distribution it +came from. What this module hands a screen instead is a *rank* — the list comes back ordered, +and :attr:`~ScoredContact.percentile` places one contact in the field without a legend and +without going stale when the weights change (see :func:`percentile_rank`). What a screen draws +beside a contact is neither: the purge preview shows the :class:`ContactSignals` themselves, a +lane per measured kind, because the thing a reader can check against what they know is the +evidence, not this module's reading of it. """ from __future__ import annotations @@ -198,22 +200,24 @@ class ContactSignals: @dataclass(frozen=True) class ScoredContact: - """One contact's standing among the others: its score, its percentile, and why. + """One contact's standing among the others: its score, its rank, and the evidence for both. Attributes: contact: The contact this describes. signals: The evidence the score was computed from. score: The weighted sum plus any newcomer grace. Never displayed — see :attr:`percentile`, and the module docstring for why. - percentile: Percentile rank within the scored population, ``0``–``100``. **This is - the only number the UI shows**: it is self-calibrating (a mesh of 30 contacts - and one of 300 both read the same way), needs no legend, and stays meaningful - if the weights are ever retuned. + percentile: Percentile rank within the scored population, ``0``–``100``. The + score's one publishable reading: self-calibrating (a mesh of 30 contacts and + one of 300 both read the same way), needing no legend, and still meaningful if + the weights are ever retuned. protection: Why this contact can never be swept, or ``None`` if it can. One of the ``PROTECT_*`` constants. - reasons: Short lowercase phrases naming what this contact's standing rests on — - its weakest lanes when it is a purge candidate, so the preview row explains - itself without the reader having to know the formula. + + The **signals** are what a screen shows, not the score or its terms: the purge preview + draws one lane per measured kind straight off :attr:`signals` (see + :mod:`~meshterm.ui.purge_screen`), so a reader auditing a sweep reads the evidence in + the same units it was gathered in rather than a phrase this module chose for them. """ contact: Contact @@ -221,7 +225,6 @@ class ScoredContact: score: float percentile: int protection: str | None = None - reasons: tuple[str, ...] = () @property def protected(self) -> bool: @@ -395,7 +398,7 @@ def protection_for(signals: ContactSignals) -> str | None: #: unknown. _MIN_LOCATED = 4 -#: The term names, in the order a :class:`ScoredContact` reports its reasons. +#: The term names, in the order the weighted sum walks them. _TERM_NAMES = ("dm", "recency", "volume", "channel", "hops", "distance") @@ -449,54 +452,6 @@ def percentile_rank(score: float, population: Sequence[float]) -> int: return int(round(100.0 * (below + 0.5 * equal) / len(population))) -def _reasons( - signals: ContactSignals, terms: dict[str, float], weights: ScoreWeights -) -> tuple[str, ...]: - """Name what this contact's standing rests on, weakest lane first. - - The preview has one line per contact and the reader should not have to know the formula - to audit a sweep — so each row says, in plain words, the two things that put it where it - is. Phrases are drawn from the *measured* signals rather than from the term values, so - "3 packets" is the actual tally and not a normalised fraction. - """ - phrases: list[tuple[float, str]] = [] - contribution = { - "dm": terms["dm"] * weights.dm, - "recency": terms["recency"] * weights.recency, - "volume": terms["volume"] * weights.volume, - "hops": terms["hops"] * weights.hops, - } - if signals.dm_total: - phrases.append((contribution["dm"], f"{signals.dm_total} messages")) - else: - phrases.append((0.0, "never messaged")) - if signals.heard_age_days is None: - phrases.append((0.0, "never heard")) - else: - phrases.append((contribution["recency"], _age_phrase(signals.heard_age_days))) - packets = signals.packets - phrases.append((contribution["volume"], f"{packets} pkt{'' if packets == 1 else 's'}")) - if signals.hops is not None: - hops = signals.hops - label = "direct" if hops < 0.5 else f"{hops:g} hops" - phrases.append((contribution["hops"], label)) - phrases.sort(key=lambda pair: pair[0]) - return tuple(phrase for _, phrase in phrases[:3]) - - -def _age_phrase(days: float) -> str: - """A last-heard age in the fewest words: ``today`` / ``4d`` / ``6w`` / ``9mo`` / ``2y``.""" - if days < 1: - return "today" - if days < 14: - return f"{int(days)}d" - if days < 60: - return f"{int(days / 7)}w" - if days < 365: - return f"{int(days / 30)}mo" - return f"{days / 365:.0f}y" - - def rank_contacts( contacts: Sequence[Contact], signals: dict[str, ContactSignals], @@ -550,7 +505,6 @@ def rank_contacts( filled = {name: _fill_unknowns(column) for name, column in columns.items()} scores: list[float] = [] - per_contact_terms: list[dict[str, float]] = [] for index, sig in enumerate(gathered): terms = {name: filled[name][index] for name in _TERM_NAMES} total = ( @@ -562,7 +516,6 @@ def rank_contacts( + terms["distance"] * weights.distance + term_grace(sig, weights) ) - per_contact_terms.append(terms) scores.append(total) ranked = [ @@ -572,11 +525,8 @@ def rank_contacts( score=score, percentile=percentile_rank(score, scores), protection=protection_for(sig), - reasons=_reasons(sig, terms, weights), - ) - for contact, sig, score, terms in zip( - contacts, gathered, scores, per_contact_terms, strict=True ) + for contact, sig, score in zip(contacts, gathered, scores, strict=True) ] ranked.sort(key=lambda scored: (-scored.score, scored.contact.name.casefold())) return ranked diff --git a/meshterm/ui/menus.py b/meshterm/ui/menus.py index 78fb64d..86d5bee 100644 --- a/meshterm/ui/menus.py +++ b/meshterm/ui/menus.py @@ -51,6 +51,7 @@ from rich.text import Text from ..platforms import get_platform from .theme import glyph from .tui import Choice, Separator +from .tui.emoji_width import cut_cells, drawable if TYPE_CHECKING: from ..context import AppContext @@ -619,6 +620,17 @@ def fit_cells(text: str, width: int, *, align: str = "left") -> str: truncation are measured in display cells (wide glyphs count 2), so a name carrying an emoji or CJK character can't skew the lanes the way ``str.ljust`` would. + A lane's text is very often a **node's name**, which is written by whoever owns the + radio and arrives over the air, so two more things are settled here rather than by + every caller: whatever a terminal cannot draw is folded to a space + (:func:`~meshterm.ui.tui.emoji_width.drawable` — a newline or an escape in a name + would end the row mid-lane, and no width table can measure that away), and the cut + falls **between** glyphs (:func:`~meshterm.ui.tui.emoji_width.cut_cells`), never + inside one. A cut a codepoint at a time slices an emoji sequence in half, and the + stranded joiner it leaves swallows the ellipsis appended after it — the lane then + measures one cell short of what the terminal draws, and every column to its right + starts late. + Args: text: The text to fit. width: The exact cell width to return. @@ -627,13 +639,10 @@ def fit_cells(text: str, width: int, *, align: str = "left") -> str: Returns: A string measuring exactly ``width`` cells. """ + if not text.isprintable(): + text = drawable(text) if cell_len(text) > width: - kept = "" - for ch in text: - if cell_len(kept + ch) > width - 1: - break - kept += ch - text = kept + "…" + text = cut_cells(text, width - 1) + "…" pad = " " * max(0, width - cell_len(text)) return pad + text if align == "right" else text + pad diff --git a/meshterm/ui/purge_screen.py b/meshterm/ui/purge_screen.py index 9f6eacc..1c79a37 100644 --- a/meshterm/ui/purge_screen.py +++ b/meshterm/ui/purge_screen.py @@ -13,9 +13,10 @@ the pushed Contacts list: computed from the actual ranking rather than from arithmetic on the table size, because protected contacts are never victims. 2. **Read the list, and edit it.** Every contact the sweep would take, weakest first, with - its percentile and the two or three facts that put it there — for the age rungs too, - since knowing how the contacts an age threshold caught actually *rank* is exactly the - check that threshold cannot do for itself. ``Delete`` drops a row from the list, so a + the evidence beside it in lanes — how lately it was heard, what it has sent, whether you + ever messaged it, how far out it sits. For the age rungs too, since seeing what the + contacts an age threshold caught have actually *done* is exactly the check that threshold + cannot do for itself. ``Delete`` drops a row from the list, so a contact the reader wants to keep is spared without abandoning the whole sweep and picking a shallower rung; ``←→`` scroll a row too wide for the terminal. Enter on a contact opens its detail page to *look* at, with the page's own contact-management verbs withheld (see @@ -29,10 +30,15 @@ the pushed Contacts list: the Archived list is one row away on the Contacts screen, and a restore is a single write. Saving the red for what cannot be undone is what keeps the red meaning anything. -**Only the percentile is ever shown.** A raw score means nothing without the distribution -it came from, and would need a legend the moment the weights were ever retuned; a contact's -rank against your other contacts explains itself. See :mod:`~meshterm.core.contact_score` -for the scoring itself, which is pure and lives in core. +**The preview shows the evidence, never the verdict.** Not the score — a weighted sum means +nothing without the distribution it came from, and would need a legend the moment the weights +were retuned. Not the percentile either, which led the row for one round: a rank is the +score's own reading of itself, so a lane of them restated the order the list was already in +and spent five columns saying "trust me". What an audit needs is the measurements, each in a +lane of its own kind — headed like the Contacts list heads the two they share — so a column +means one thing all the way down and the reader can check the sweep against what they know +rather than against its arithmetic. See :mod:`~meshterm.core.contact_score` for the scoring +itself, which is pure, lives in core, and still ranks the list. **Archived, not deleted.** The sweep removes each contact from the *device* — freeing the slot, which is the whole point — and records it in the cross-session store with an archive @@ -50,7 +56,8 @@ from __future__ import annotations import math import time -from dataclasses import replace +from collections.abc import Callable +from dataclasses import dataclass, replace from typing import TYPE_CHECKING from rich.cells import cell_len @@ -67,15 +74,16 @@ from .menus import Lane, column_header, fit_cells, section_heading from .theme import name_style from .tui import Choice, Separator from .tui.screen import CANCEL +from .widgets import _recency_style, format_age if TYPE_CHECKING: from ..context import AppContext #: The keep-the-strongest rungs the target picker offers, as a share of the *sweepable* -#: contacts. Percentages rather than absolute counts because the score itself is only ever -#: read as a percentile: a rung and the lane it filters against then speak one language, and -#: the ladder means the same thing on a table of thirty and a table of three hundred without -#: a single value needing to be retuned. Coarse at the aggressive end — the difference +#: contacts. Percentages rather than absolute counts because a share is the one form the +#: ladder can state once and have mean the same thing on a table of thirty and a table of +#: three hundred — the ranking underneath is a rank, so a count would have to be retuned +#: for every mesh and a share never does. Coarse at the aggressive end — the difference #: between keeping 90% and 75% is a tidy-up, between 50% and 25% a decision. KEEP_RUNGS: tuple[int, ...] = (90, 75, 60, 50, 25) @@ -101,91 +109,142 @@ AGE_RUNGS: tuple[tuple[str, int], ...] = ( #: The age-rung value meaning the never-heard bucket (contacts with no advert time at all). _NEVER = -1 -#: Percentile lane width, plus its gap — three digits and two cells of air. -_PCTL_W = 5 +#: The gap between two lanes, in cells — the air that keeps a right-aligned value clear of +#: the one before it, and what a lane's declared width carries on top of its content. +_GAP = 2 #: Name lane width in the preview, plus its gap. Wide enough for the 20-odd bytes a -#: MeshCore advert name runs to, and narrow enough to leave the reasons lane readable at +#: MeshCore advert name runs to, and narrow enough to leave the evidence lanes readable at #: the PicoCalc's 53 columns. _NAME_W = 22 -def _pctl_style(percentile: int) -> str: - """The style a percentile is drawn in — the same quality reading ``snr_style`` gives SNR. +def _count_cell(tally: int | None) -> tuple[str, str]: + """A tally lane's value: the number muted, or a faint ``—`` where there is nothing. - Three bands rather than a gradient: the heat ramp is spoken for (it colours *ages*, and - a second gradient in a neighbouring lane would read as the same scale), and a percentile - in a purge preview only ever answers one question — is this contact near the bottom? + The Contacts list's ``count`` reading exactly (see + :func:`~meshterm.ui.contactlist._lane_cell`), clamp included — a runaway tally widens no + column — because the reader arrived here from that list and must not have to learn a + second grammar for the same fact. """ - if percentile >= 66: - return "ok" - if percentile >= 33: - return "warn" - return "err" + if not tally: + return "—", "faint" + return f"{min(tally, 99999)}", "muted" -def _pctl_cell(percentile: int) -> Text: - """One right-aligned percentile lane: the number alone, coloured by band.""" - return Text(f"{percentile:>3} ", style=_pctl_style(percentile)) +def _heard_cell(scored: ScoredContact) -> tuple[str, str]: + """The last-heard lane: the column age under recency heat, or a cold ``never``. - -def _preview_header(width: int) -> str: - """The preview's pinned column header, fitted to the terminal. - - ``WHY IT RANKS LOW`` heads all three reason lanes at once rather than naming each: a - lane holds a contact's *n*-th weakest reason, so its phrases are of mixed kinds — a - message count over an age over a hop count — and a per-lane word would claim a kind the - column does not keep. + :func:`~meshterm.ui.widgets.format_age` and the heat the Contacts list colours its own + ``HEARD`` lane with — one grammar for one fact, whichever screen is asking it. """ - return column_header( - [ - Lane("PCTL", _PCTL_W), - Lane("NAME", _NAME_W), - Lane(("WHY IT RANKS LOW", "WHY")), - ], - width, - ) + secs = age_seconds(scored) + return format_age(secs), _recency_style(secs) -def _reason_lanes(victims: list[ScoredContact]) -> tuple[int, ...]: - """Each reason lane's width: the widest phrase any victim puts in it. +def _hops_cell(scored: ScoredContact) -> tuple[str, str]: + """The distance lane: ``direct`` for a neighbour, else the mean hop count it arrives by.""" + hops = scored.signals.hops + if hops is None: + return "—", "faint" + return ("direct" if hops < 0.5 else f"{hops:g}"), "muted" - Measured against the list rather than fixed, so the lanes are only as wide as the words - in them — and remeasured whenever a spared row leaves, which can only tighten them. + +@dataclass(frozen=True) +class _Evidence: + """One evidence lane: the word over it, and how to read a contact's value for it. + + A declaration rather than a branch, like :class:`~meshterm.ui.contactlist.ContactLane` + next door: the header builder, the row builder and the width arithmetic all walk the + same tuple, so a lane is added — or reordered — in one place. + + Attributes: + label: The header word. Right-aligned over its lane, where its digits will land. + read: The contact's value for this lane, as ``(text, style)``. + """ + + label: str + read: Callable[[ScoredContact], tuple[str, str]] + + +#: The preview's evidence lanes, left to right. ``HEARD`` and ``PKTS`` lead, in the Contacts +#: list's own order and drawn in its own grammar: the reader has just come from that list, +#: and these are the two lanes they were already reading. ``MSGS`` and ``HOPS`` follow — the +#: two the sweep adds, and the two nearly always empty in a list of candidates (a contact you +#: have messaged is rarely weak enough to be swept), so a terminal too narrow for the whole +#: row cuts the least informative end first and ``←→`` brings it back. +_EVIDENCE: tuple[_Evidence, ...] = ( + _Evidence("HEARD", _heard_cell), + _Evidence("PKTS", lambda scored: _count_cell(scored.signals.packets)), + _Evidence("MSGS", lambda scored: _count_cell(scored.signals.dm_total)), + _Evidence("HOPS", _hops_cell), +) + + +def _lane_widths(victims: list[ScoredContact]) -> tuple[int, ...]: + """Each evidence lane's width: its header word, or the widest value under it. + + Measured against the list rather than fixed, so a lane of single digits is one cell of + numbers instead of five of air — and remeasured whenever a spared row leaves, which can + only tighten it. """ - count = max((len(scored.reasons) for scored in victims), default=0) return tuple( - max((cell_len(s.reasons[i]) for s in victims if len(s.reasons) > i), default=0) - for i in range(count) + max([cell_len(lane.label), *(cell_len(lane.read(v)[0]) for v in victims)]) + for lane in _EVIDENCE ) -def _victim_row(scored: ScoredContact, reason_lanes: tuple[int, ...]) -> Text: - """One preview line: percentile, the contact's name in its own hue, then why it ranks low. +def _preview_header(widths: tuple[int, ...], width: int) -> str: + """The preview's pinned column header: the name lane, then one word per evidence lane. - The name keeps its key-derived colour like everywhere else in the app — this is a list - of nodes, and a reader picking one out of thirty rows should not have to read it letter - by letter because the screen it is on happens to be about deleting things. + Each word is right-aligned inside its own lane, over values right-aligned too, so a + header sits where its digits will land rather than off to the left of them — how the + Contacts list heads the same two lanes. - The reasons sit in lanes of their own (``reason_lanes``, see :func:`_reason_lanes`), - weakest first, so each one starts in the same column on every row instead of wherever - the phrase before it happened to end. The last phrase on a row is left unpadded, as a - trailing lane is: nothing follows it to line up. + One word per lane is the whole point of the layout. A single ``WHY IT RANKS LOW`` used to + head three lanes at once, and could not name any of them: a lane held a contact's *n*-th + weakest reason, so a message count, an age and a hop count moved between columns from row + to row and nothing in a column meant the same thing twice. The lanes are fixed by *kind* + now, which is what makes them comparable down the list — and what lets a reader see that + the contact they were unsure about is the one that has never sent a packet. + """ + lanes = [Lane("NAME", _NAME_W)] + last = len(_EVIDENCE) - 1 + for index, (lane, lane_w) in enumerate(zip(_EVIDENCE, widths, strict=True)): + lanes.append(Lane(f"{lane.label:>{lane_w}}", 0 if index == last else lane_w + _GAP)) + return column_header(lanes, width) + + +def _victim_row(scored: ScoredContact, widths: tuple[int, ...]) -> Text: + """One preview line: the contact's name in its own hue, then its evidence, lane by lane. + + The name keeps its key-derived colour like everywhere else in the app — this is a list of + nodes, and a reader picking one out of thirty rows should not have to read it letter by + letter because the screen it is on happens to be about archiving things. It goes through + :func:`~meshterm.ui.menus.fit_cells`, so an over-long name ends on an ellipsis that says + it was shortened, the lane is measured in display cells, and a name carrying an emoji is + cut between glyphs rather than through one — a name is whatever a stranger's radio + advertised, and it is the one value on this screen that can be anything at all. + + Every other lane is right-aligned into its measured width and carries its own style: the + heard age its recency heat, a tally muted, an absent one a faint ``—``. The row is built + on an unstyled :class:`~rich.text.Text` rather than under the name's own style, because + Rich merges a base style into every span — a faint ``—`` under a name-hue base would come + out faint *in that node's colour*. """ contact = scored.contact - row = _pctl_cell(scored.percentile) name = contact.name or contact.key_prefix or "?" - # Through ``fit_cells``, so an over-long name ends on an ellipsis that says it was - # shortened — and so the lane is measured in display cells, which is the only measure - # that keeps the column straight once a name carries a wide glyph. + row = Text() row.append( - fit_cells(name, _NAME_W - 2) + " ", + fit_cells(name, _NAME_W - _GAP) + " " * _GAP, style=name_style(name, contact.public_key or contact.key_prefix), ) - last = len(scored.reasons) - 1 - for index, phrase in enumerate(scored.reasons): - cell = phrase if index == last else fit_cells(phrase, reason_lanes[index]) + " " - row.append(cell, style="muted") + last = len(_EVIDENCE) - 1 + for index, (lane, lane_w) in enumerate(zip(_EVIDENCE, widths, strict=True)): + value, style = lane.read(scored) + row.append(fit_cells(value, lane_w, align="right"), style=style) + if index != last: + row.append(" " * _GAP) return row @@ -444,19 +503,19 @@ def _preview_items(victims: list[ScoredContact]) -> list: """The preview's rows: a pinned column header, one line per victim, then Apply/Back. Each contact row is ``deletable``, so ``Delete`` lifts it out of the sweep, and pins its - percentile lane out of the ``←→`` scroll (``hscroll_from``): the number is the reader's - place in a list ordered by it, and sliding it away to read a long reasons lane would - cost the row its bearing to gain nothing — the percentile is the part that already fits. + **name** out of the ``←→`` scroll (``hscroll_from``): the evidence lanes are what a + narrow terminal cuts, and sliding the name away to read them would cost the row the one + thing that says which contact is being read. - The reason lanes are measured here, across every victim, which is also why a spared row - rebuilds the rows through this function rather than dropping one: the lanes it leaves - behind may have been sized by the phrase that just left. + The lanes are measured here, across every victim, which is also why a spared row rebuilds + the rows through this function rather than dropping one: the widths it leaves behind may + have been set by the value that just left. """ - lanes = _reason_lanes(victims) + widths = _lane_widths(victims) return [ - Separator(_preview_header, pinned=True), + Separator(lambda w: _preview_header(widths, w), pinned=True), *( - Choice(title=_victim_row(v, lanes), value=v, deletable=True, hscroll_from=_PCTL_W) + Choice(title=_victim_row(v, widths), value=v, deletable=True, hscroll_from=_NAME_W) for v in victims ), # The same shape ``exit_rows`` draws, in this flow's own words: Apply has no key of diff --git a/meshterm/ui/tui/emoji_width.py b/meshterm/ui/tui/emoji_width.py index 3e54d27..68c8aef 100644 --- a/meshterm/ui/tui/emoji_width.py +++ b/meshterm/ui/tui/emoji_width.py @@ -87,15 +87,24 @@ presentation, an emoji outside Emoji_Presentation (``🛣`` U+1F6E3, ``🕸`` U+ one-cell text glyph, which is what both authorities said. Forcing one to two reserves a cell the terminal never draws and pulls the row's border a column *in* — see :data:`_DEFAULT_WIDE_BASE` for the case that proved it. + +Two jobs beside the measuring belong here, because they are the same question asked of the same +table. **Where a string may be cut** (:func:`cut_cells`, over :func:`clusters`): a lane that +truncates a name a codepoint at a time cuts through the middle of a glyph, and the pieces that +leaves — a stranded joiner, half a flag — are exactly what every correction above is written +against. And **what may be drawn at all** (:func:`drawable`): an advert name is written by a +stranger and can carry a newline or an escape, which no width table can make safe. """ from __future__ import annotations import os import sys -from collections.abc import Callable +import unicodedata +from collections.abc import Callable, Iterator from prompt_toolkit.layout.controls import FormattedTextControl +from rich.cells import cell_len from ...core import win32dll @@ -121,6 +130,12 @@ _EXTENDERS = frozenset((_VS16, *_MODIFIERS)) #: measured at its own East-Asian width, with no VS16 "promote to 2" step. _ZERO_WIDTH = (_ZWJ, _VS16) +#: Unicode general categories holding nothing a terminal can draw: control characters +#: (``Cc``), the format and bidi-control block (``Cf``), surrogates (``Cs``), and the line +#: and paragraph separators (``Zl``/``Zp``). See :func:`drawable`, which folds them to a +#: space — and keeps the one ``Cf`` codepoint that matters, the zero-width joiner. +_UNDRAWABLE = frozenset(("Cc", "Cf", "Cs", "Zl", "Zp")) + #: The probe: a sun. Its base (U+2600) is East-Asian *narrow* (1), and Rich #: promotes the U+2600+U+FE0F pair to 2. So a terminal that reports 1 for this is #: exactly the terminal whose borders Rich currently misaligns. @@ -234,6 +249,97 @@ def _joined_out(text: str) -> str: return "".join(kept) +def clusters(text: str) -> Iterator[str]: + """Split ``text`` into the glyphs the terminal actually draws, never inside one. + + The same run :func:`_join_zwj_clusters` gathers out of a laid-out line, read off a plain + string instead: a base, whatever extends it (:data:`_EXTENDERS` — a variation selector, a + skin tone), then any number of *joiner + component + extenders* groups, plus the + Regional Indicator **pair** a country flag is drawn from. A joiner that joins nothing + (:func:`_joins`) is a cluster of its own, because it is not part of the glyph before it. + + The unit a lane has to cut on: every correction in this module measures a *whole* glyph, + so a cut through the middle of one leaves two pieces neither authority can measure — a + lone Regional Indicator drawn as a letter, a skin tone with no base, or the stranded + joiner that goes on to swallow the ellipsis the cut appended. See :func:`cut_cells`. + """ + index = 0 + count = len(text) + while index < count: + start = index + index += 1 + while index < count and text[index] in _EXTENDERS: + index += 1 + if _is_regional_indicator(text[start]) and index < count: + if _is_regional_indicator(text[index]): + index += 1 + while index < count and text[index] in _EXTENDERS: + index += 1 + while index + 1 < count and text[index] == _ZWJ and _joins(text[index + 1]): + index += 2 # the joiner and the codepoint it joins + while index < count and text[index] in _EXTENDERS: + index += 1 + yield text[start:index] + + +def cut_cells(text: str, width: int) -> str: + """The longest prefix of ``text`` that fits ``width`` cells, cut **between** glyphs. + + What a fixed lane needs when a name outruns it (:func:`~meshterm.ui.menus.fit_cells`), + and the reason it cannot simply walk the string a character at a time: a MeshCore name + is written by whoever owns the radio, so it arrives carrying whatever emoji they typed, + and a codepoint-by-codepoint cut lands inside one about as often as not. Cutting + ``"👨‍👩‍👧"`` after its first joiner leaves a stranded joiner at the end of the lane, + which then folds the ellipsis the caller appends into the glyph before it + (:func:`_joined_out`) — the ellipsis measures nothing, the terminal draws it anyway, and + every lane after the name starts a column late. Cutting a flag in half leaves a lone + Regional Indicator, which is a letter rather than half a flag. + + So the prefix is built out of whole :func:`clusters`, and a trailing joiner — stranded + by the cut itself, or already stranded in the name — is dropped rather than left to + swallow whatever comes next. + + Args: + text: The text to cut. + width: The most cells the result may occupy. + + Returns: + A prefix measuring at most ``width`` cells, with every glyph in it whole. + """ + kept: list[str] = [] + used = 0 + for cluster in clusters(text): + size = cell_len(cluster) + if used + size > width: + break + kept.append(cluster) + used += size + while kept and kept[-1] == _ZWJ: + kept.pop() + return "".join(kept) + + +def drawable(text: str) -> str: + """``text`` with every codepoint a terminal cannot *draw* folded to a space. + + A name comes off the air from a stranger's radio, and nothing on the way in promises it + holds only characters. A newline in one ends the row mid-lane; an ``ESC`` starts an + escape sequence in the middle of a screen the app composed; a bidi override (``U+202E``) + reverses everything drawn after it. All three measure zero cells and none of them is a + width bug that any allowlist here could fix — they are text that must not reach the + terminal at all, so a lane folds them to the one character that is always safe. + + Folded: control characters, the format and bidi-control block, surrogates, and the line + and paragraph separators. **Kept:** the zero-width joiner, which is format-class too and + is the tell that holds an emoji sequence together, along with every mark and modifier a + glyph is built from. Private-use codepoints are kept as well — that block is where a + Nerd Font keeps the powerline glyphs the path line is drawn with. + """ + return "".join( + " " if char != _ZWJ and unicodedata.category(char) in _UNDRAWABLE else char for char in text + ) + + def _narrow_lone_set() -> frozenset[str]: """The lone-codepoint emoji to measure as one cell (see :data:`_DEFAULT_NARROW_LONE`). @@ -716,4 +822,4 @@ class ClusterTextControl(FormattedTextControl): return content -__all__ = ["ClusterTextControl", "calibrate"] +__all__ = ["ClusterTextControl", "calibrate", "clusters", "cut_cells", "drawable"] diff --git a/tests/test_contact_score.py b/tests/test_contact_score.py index b98fdf5..1e83b87 100644 --- a/tests/test_contact_score.py +++ b/tests/test_contact_score.py @@ -306,16 +306,6 @@ def test_a_contact_with_no_signals_at_all_is_protected() -> None: assert ranked[0].protection == PROTECT_UNOBSERVED -def test_reasons_name_the_weakest_lanes_in_plain_words() -> None: - """Each preview row explains itself without the reader having to know the formula.""" - ranked = _rank(("Quiet", {"packets": 3, "heard_age_days": 240.0, "dm_total": 0})) - reasons = ranked[0].reasons - assert "never messaged" in reasons - assert "3 pkts" in reasons - # The age reads in the fewest words that are still true — months, here. - assert any(r.endswith("mo") for r in reasons) - - def test_a_stronger_contact_never_scores_below_a_weaker_one_on_every_axis() -> None: """Sanity: dominance is preserved — better everywhere means ranked above.""" ranked = _by_name( diff --git a/tests/test_device_config.py b/tests/test_device_config.py index 499b2b5..2d6b7ec 100644 --- a/tests/test_device_config.py +++ b/tests/test_device_config.py @@ -491,7 +491,10 @@ async def test_purge_sweeps_under_a_progress_bar_and_reports_in_a_dialog() -> No # The preview lists exactly who would go, and commits on its Apply row (the default). preview = await _step_until_screen(session, lambda s: "to archive" in getattr(s, "title", "")) body = _screen_text(preview) - assert "PCTL" in body # the standing lane is a percentile, never a raw score + # The evidence, one lane per kind — never a score, and no longer a percentile either: + # the row shows what was measured, and the list's order is the ranking. + lanes = ["NAME", "HEARD", "PKTS", "MSGS", "HOPS"] + assert [body.index(word) for word in lanes] == sorted(body.index(word) for word in lanes) assert all(v.name in body for v in victims) preview.handle("enter") diff --git a/tests/test_emoji_width.py b/tests/test_emoji_width.py index 20a341c..eb21a98 100644 --- a/tests/test_emoji_width.py +++ b/tests/test_emoji_width.py @@ -278,6 +278,48 @@ def test_a_stranded_joiner_leaves_the_next_character_its_cell(monkeypatch) -> No _restore(snap) +def test_clusters_split_between_glyphs_and_never_inside_one() -> None: + """The unit a lane may cut on: one entry per glyph the terminal actually draws. + + A joined run, a flag's indicator *pair*, and a toned base each come back whole, because + each is one glyph — while a joiner that joins nothing stands on its own, as it does + everywhere else in this module (see :func:`~meshterm.ui.tui.emoji_width._joins`). + """ + assert list(ew.clusters(f"a{_FAMILY}{_CA}{_THUMB}b")) == ["a", _FAMILY, _CA, _THUMB, "b"] + # Two flags in a row pair up one at a time rather than running together into four. + assert list(ew.clusters(_CA + _CN)) == [_CA, _CN] + # A name cut at its byte limit just past a joiner: the joiner is not part of the flag. + assert list(ew.clusters(_STRANDED)) == [_FLAG, _ZWJ] + + +def test_cut_cells_keeps_every_glyph_whole_and_strands_no_joiner() -> None: + """A lane's truncation lands between glyphs, so nothing measures what is not drawn. + + The failure this exists for: cutting a codepoint at a time leaves a trailing joiner, + which folds whatever the caller appends — the lane's ellipsis — into the glyph before + it. The ellipsis then measures nothing while the terminal still draws it, and every + column right of the name starts a cell late. + """ + assert ew.cut_cells(f"Bob {_FAMILY}", 6) == f"Bob {_FAMILY}" # it fits, so it is kept + assert ew.cut_cells(f"Bob {_FAMILY}", 5) == "Bob " # it doesn't: dropped whole + assert ew.cut_cells(_CA, 1) == "" # half a flag is a letter, not half a glyph + assert ew.cut_cells(_STRANDED, 4) == _FLAG # the joiner cannot swallow what follows + assert ew.cut_cells("plain name", 5) == "plain" + + +def test_drawable_folds_only_what_no_terminal_can_draw() -> None: + """A newline, an escape or a bidi override in an advert name is folded to a space. + + None of them is a width bug an allowlist could fix — they are text that must not reach + the terminal at all. The joiner is format-class too and is the one kept, because it is + what holds an emoji sequence together. + """ + assert ew.drawable("line\nbreak") == "line break" + assert ew.drawable("esc\x1b[31mape") == "esc [31mape" + assert ew.drawable("flip‮me") == "flip me" + assert ew.drawable(f"Bob {_FAMILY}{_THUMB}") == f"Bob {_FAMILY}{_THUMB}" + + def test_join_zwj_clusters_merges_only_joined_runs() -> None: """The fragment merge gathers a whole sequence and leaves everything else alone. diff --git a/tests/test_menus.py b/tests/test_menus.py index 8a204b9..3bf75f2 100644 --- a/tests/test_menus.py +++ b/tests/test_menus.py @@ -143,6 +143,37 @@ def test_fit_cells_measures_display_cells_not_characters() -> None: assert fit_cells("ab", 5, align="right") == " ab" +def test_fit_cells_keeps_a_broken_name_inside_its_lane() -> None: + """A name is written by a stranger's radio, and no part of one may skew the lane. + + Two failures, one lane. A cut through the middle of an emoji sequence leaves a stranded + joiner, which folds the ellipsis appended after it into the glyph before it — the lane + then measures a cell short of what the terminal draws, and every column right of the + name starts late. And a name carrying a newline or an escape ends the row mid-lane + whatever it measures. Both are settled inside ``fit_cells`` (see + :mod:`meshterm.ui.tui.emoji_width`), so every column in the app is covered by the one + helper they all fit their labels through. + """ + from rich.cells import cell_len + + family = "\U0001f468‍\U0001f469‍\U0001f467" # one glyph, three joined people + flag = "\U0001f1e8\U0001f1e6" # one glyph, two Regional Indicators + + for name in (f"Bob {family} Family", f"{flag} Canada Hub", "line\nbreak\x1b[31m"): + for width in range(4, 24): + assert cell_len(fit_cells(name, width)) == width, (name, width) + + # The cut falls between glyphs: half a family is not a glyph, and half a flag is a letter. + assert family in fit_cells(f"Bob {family}", 8) # it fits: the glyph is kept whole + assert "‍" not in fit_cells(f"Bob {family}", 5) # it doesn't: no joiner left behind + assert fit_cells(f"{flag} Hub", 4).startswith(flag) # the pair survives, or neither does + + # What the terminal cannot draw never reaches it; an ordinary name is left alone. + assert "\n" not in fit_cells("line\nbreak", 12) + assert "\x1b" not in fit_cells("esc\x1b[31mape", 12) + assert fit_cells("plain", 12).strip() == "plain" + + def test_main_menu_sections_answer_the_menus_own_question() -> None: """Each section is a *doing*, in workflow order, and holds only what shares it.