The purge preview shows the evidence in lanes of its own kind

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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-16 00:05:23 -04:00
1 parent 1da1c9db0d
commit 282334c761
8 files changed
+356 -166

No files matched your search

+19 -69
View File
@@ -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
+15 -6
View File
@@ -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
+137 -78
View File
@@ -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
+108 -2
View File
@@ -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"]
-10
View File
@@ -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(
+4 -1
View File
@@ -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")
+42
View File
@@ -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.
+31
View File
@@ -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.