Review round: the standard palette, by JP's call

The console keeps its stock kernel palette - black background, classic
PC hues - instead of the custom setvtrgb remap. MESH_THEME_16 is
re-tuned against the stock slots, which hands back the map's own
language for free: clients wear bright pink (13), repeaters purple (5),
rooms cyan (6), sensors brown (3). The cost is one dark grey - muted,
faint and track all collapse onto slot 8. Heat quantizes on plain human
units (15 min / 1 h / 1 day). The custom design is archived, not
deleted: theme._VT_SLOTS_CUSTOM + MESHTERM_CUSTOM_PALETTE=1 on the font
script reinstalls it, with the parity test keeping the two in sync.

Undoing the remap on the device exposed a trap: setvtrgb overwrites the
kernel's DEFAULT colormap, so the OSC palette-reset "resets" straight
back to the custom values - the script's default mode now programs the
stock palette explicitly (verified live; specimen screenshot in
.claude/plans/p3-specimen-stock.png).

The header also follows JP's spec: the handheld brands the app -
"MeshTerm vX" - instead of naming a soldered port that never changes,
and the activity pulse takes whatever room remains.

Also root-causes the intermittent suite flake: Rich memoizes a parsed
Style's ANSI codes on first render (Style.parse is globally cached), so
a raw hex style first rendered by a truecolor console replays 38;2
verbatim on a standard console later in the process. The specimen's
nodes row now wears the type.* theme styles - which is also just
correct: the marks now match the names row. Six consecutive clean
full-suite runs.

Deferred at JP's request: the glyph substitution map (he will redo it),
the F-key lane design (awaits his explicit spec), the CLI fold gap.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5 committed 2026-08-01 14:53:31 -04:00
1 parent e425e8fc41
commit 2f8f77be49
7 files changed
+158 -91

No files matched your search

+4 -3
View File
@@ -143,9 +143,10 @@ PICOCALC = Platform(
readable_cols=53,
readable_rows=26,
frame_border=False,
# P4 decides "keep pulse" once it can measure whether it still earns its cells at 53;
# conservatively excluded until then. Version is dropped outright (plan decision).
header_atoms=("device", "badges", "battery"),
# JP's call (2026-08-01, post-P7 review): the handheld's header brands the app —
# "MeshTerm vX" — rather than naming the device/port (on a soldered radio the port
# never changes), and the activity pulse takes whatever room remains.
header_atoms=("version", "badges", "pulse", "battery"),
footer_fkeys=True,
width_reclaim=False,
emoji=False,
+11 -5
View File
@@ -17,7 +17,7 @@ from rich.text import Text
from ..platforms import get_platform
from .packet_viewer import KIND_ICONS, PAYLOAD_ICONS
from .theme import _VT_SLOTS, fold_text, glyph, name_style, snr_style
from .widgets import _NODE_GLYPHS, _recency_style, channel_glyph
from .widgets import _recency_style, channel_glyph
#: Demo identities for the name-colour row: (name, key, node type registered for it).
#: Keys are synthetic and only ever registered inside the one-shot specimen process.
@@ -57,7 +57,7 @@ def specimen_lines() -> list[RenderableType]:
lines.append(Text.assemble(("Specimen", "accent"), (" · ", "muted"), platform.name))
lines.append(Text())
lines.append(_palette_row())
legend = Text("0 bg · 5 track · 6 faint · 8 muted · 15 you", style="muted")
legend = Text("stock palette · 8 muted · 13 clients · 15 you", style="muted")
lines.append(legend)
lines.append(Text())
@@ -66,11 +66,17 @@ def specimen_lines() -> list[RenderableType]:
status.append(mark + " ", style=style)
lines.append(status)
# The node marks wear the *type* styles (not the map's raw hex colours): on the
# console they resolve to exact palette slots, and the row then agrees with the
# names row below it. Raw hex here would also trip Rich's per-Style ANSI memo —
# a style first rendered by a truecolor console replays truecolor everywhere.
nodes = Text("nodes ")
nodes.append("★ ", style="you")
for node_type, (mark, colour) in _NODE_GLYPHS.items():
nodes.append(mark + " ", style=colour)
nodes.append("○", style="muted")
for mark, style in (
("● ", "type.node"), ("▲ ", "type.repeater"), ("■ ", "type.room"),
("◉ ", "type.sensor"), ("○", "muted"),
):
nodes.append(mark, style=style)
lines.append(nodes)
classes = Text("classes ")
+71 -44
View File
@@ -90,11 +90,11 @@ MESH_THEME = Theme(
# Node-type colours, used where the platform colours names by *type* instead of by
# key (PicoCalc — see name_style). Defined in both themes so the names always
# resolve; the regular platform simply never asks for them. Hues follow the map's
# marker language where the 16-slot palette can: repeaters the calm violet, sensors
# the map's orange; rooms take the brand teal and plain client nodes a quiet light
# grey, so infrastructure pops while the crowd stays calm.
"type.node": "#cbd5e1",
"type.repeater": "#a5b4fc",
# marker language: clients the map's pink, repeaters its violet, sensors its
# orange; rooms take a teal of their own (the map's white square is reserved for
# "you" in name contexts).
"type.node": "#f472b6",
"type.repeater": "#a78bfa",
"type.room": "#5eead4",
"type.sensor": "#fb923c",
# The heard-age heat scale's quantized steps (hot → cold). The regular platform
@@ -108,60 +108,87 @@ MESH_THEME = Theme(
}
)
#: The PicoCalc console's 16 palette slots and the RGB each is programmed to (via
#: ``setvtrgb``; see :func:`vtrgb_lines` and the boot oneshot installed by
#: ``scripts/calculinux-console-font.sh``). This table *is* the palette design:
#: The PicoCalc console's 16 palette slots — the **standard kernel VT palette**, by JP's
#: decision (2026-08-01): the console is not remapped, so other software looks stock and
#: the black background stays black. :data:`MESH_THEME_16` is designed against these
#: RGBs, and the fold's stray-truecolor quantizer matches against them. Rules that still
#: bind:
#:
#: * Slots keep their conventional **hue families** (1/9 red, 2/10 green, 3/11
#: yellow-orange, 4/12 blue-indigo, 7/15 light/white, 8 grey) so other console
#: software — and Rich's own nearest-colour downsampling of any stray truecolor —
#: still lands somewhere sane; only the exact RGBs are retuned to MeshTerm's theme.
#: * Two slots are repurposed outright for the theme's dark slates (5 ``track``,
#: 6 ``faint``): the app never uses magenta or dim cyan, and three greys don't fit
#: in one "bright black" slot.
#: * The kernel VT renders **bold as brightness**: ``bold`` on a 0–7 foreground jumps
#: it to slot N+8. Styles below therefore only combine ``bold`` with a slot whose
#: +8 partner is the same hue family — and never with 5/6, whose partners (13/14)
#: are unrelated colours.
#: * The kernel VT renders **bold as brightness**: ``bold`` on a 0–7 foreground jumps it
#: to slot N+8. A style may only combine ``bold`` with a dim slot when the bright
#: partner keeps its meaning — and never with 5/6, whose partners are claimed by
#: *different* semantics here (5 purple = repeater names, 13 pink = client names;
#: 6 cyan = room names/hint.brand, 14 bright cyan = brand).
#: * Backgrounds can only address slots 0–7 (SGR 40–47).
_VT_SLOTS: tuple[tuple[int, str, str], ...] = (
(0, "background", "#0f172a"),
(0, "background (black)", "#000000"),
(1, "red (hint.err)", "#aa0000"),
(2, "green (hint.ok)", "#00aa00"),
(3, "brown/orange (hint.warn, batt.mid, heat.cool, sensors)", "#aa5500"),
(4, "blue (hint.accent, bluetooth bg)", "#0000aa"),
(5, "purple (repeater names)", "#aa00aa"),
(6, "cyan (room names, hint.brand)", "#00aaaa"),
(7, "light grey (default text, heat.cold)", "#aaaaaa"),
(8, "dark grey (muted, faint, track)", "#555555"),
(9, "bright red (err)", "#ff5555"),
(10, "bright green (ok)", "#55ff55"),
(11, "bright yellow (warn, heat.warm)", "#ffff55"),
(12, "bright blue (accent)", "#5555ff"),
(13, "bright pink (client names — the map's pink, for free)", "#ff55ff"),
(14, "bright cyan (brand)", "#55ffff"),
(15, "white (you, heat.hot)", "#ffffff"),
)
#: The custom 16-slot remap P3 originally shipped (tailwind-family RGBs programmed via
#: ``setvtrgb``) — **archived, not installed**: JP chose the standard palette but asked
#: to keep this in case he changes his mind. Reinstall with
#: ``MESHTERM_CUSTOM_PALETTE=1 sh scripts/calculinux-console-font.sh`` (whose opt-in
#: block a test keeps byte-identical to :func:`vtrgb_lines`); MESH_THEME_16 would then
#: want re-tuning against it (see git history at c6485c6 for the matching theme).
_VT_SLOTS_CUSTOM: tuple[tuple[int, str, str], ...] = (
(0, "background slate", "#0f172a"),
(1, "red (hint.err)", "#ef4444"),
(2, "green (hint.ok)", "#22c55e"),
(3, "orange (hint.warn, batt.mid, sensors)", "#f59e0b"),
(4, "indigo (hint.accent, bluetooth bg)", "#6366f1"),
(3, "orange", "#f59e0b"),
(4, "indigo (hint.accent)", "#6366f1"),
(5, "track slate (was magenta)", "#334155"),
(6, "faint slate (was dim cyan)", "#64748b"),
(7, "light grey (title.muted, client nodes)", "#cbd5e1"),
(7, "light grey", "#cbd5e1"),
(8, "muted grey", "#94a3b8"),
(9, "err red", "#f87171"),
(10, "ok green", "#4ade80"),
(11, "warn amber", "#fbbf24"),
(12, "accent indigo", "#818cf8"),
(13, "lavender (title.accent, repeaters)", "#a5b4fc"),
(13, "lavender", "#a5b4fc"),
(14, "brand teal", "#5eead4"),
(15, "white (you)", "#ffffff"),
(15, "white", "#ffffff"),
)
def vtrgb_lines() -> str:
"""The ``setvtrgb`` palette file content for :data:`_VT_SLOTS` (three CSV lines).
"""The ``setvtrgb`` file content for the **archived custom** palette (three CSV lines).
``setvtrgb`` takes one line of 16 decimal values per colour channel. The deploy
script carries this same content literally (a test keeps the two in sync), so a
fresh SD card gets the palette without running Python.
Not installed by default — see :data:`_VT_SLOTS_CUSTOM`. The deploy script's opt-in
block carries this same content literally (a test keeps the two in sync), so the
remap stays one environment variable away without running Python.
"""
channels = []
for shift in (16, 8, 0):
values = [(int(hex_.lstrip("#"), 16) >> shift) & 0xFF for _, _, hex_ in _VT_SLOTS]
values = [
(int(hex_.lstrip("#"), 16) >> shift) & 0xFF for _, _, hex_ in _VT_SLOTS_CUSTOM
]
channels.append(",".join(str(v) for v in values))
return "\n".join(channels) + "\n"
#: The 16-slot palette theme: the same style names as :data:`MESH_THEME`, expressed as
#: ``color(N)`` references into :data:`_VT_SLOTS`. Kept literal (rather than derived) so
#: a slot choice is reviewable next to its meaning; the bold-brightness and background
#: rules it must obey are documented on :data:`_VT_SLOTS` and pinned by tests.
#: ``color(N)`` references into :data:`_VT_SLOTS` — the **standard** VT palette. Kept
#: literal (rather than derived) so a slot choice is reviewable next to its meaning; the
#: bold-brightness and background rules it must obey are documented on
#: :data:`_VT_SLOTS` and pinned by tests. Notable stock-palette wins: bright pink (13)
#: is the map's client colour for free, and dim purple (5) stands in for the map's
#: repeater violet. The cost: the three grey depths (muted/faint/track) all collapse
#: onto slot 8 — the stock palette has exactly one dark grey.
MESH_THEME_16 = Theme(
{
"brand": "bold color(14)",
@@ -176,36 +203,36 @@ MESH_THEME_16 = Theme(
"warn": "bold color(11)",
"err": "bold color(9)",
"muted": "color(8)",
"title.accent": "bold color(13)",
"title.accent": "bold color(12)",
"title.muted": "bold color(7)",
"title.warn": "bold color(11)",
"title.err": "bold color(9)",
"title.ok": "bold color(10)",
"title.brand": "bold color(14)",
"hint.accent": "color(4)",
"hint.muted": "color(6)",
"hint.muted": "color(8)",
"hint.warn": "color(3)",
"hint.err": "color(1)",
"hint.ok": "color(2)",
"hint.brand": "color(14)",
"faint": "color(6)",
"track": "color(5)",
"hint.brand": "color(6)",
"faint": "color(8)",
"track": "color(8)",
"snr.good": "bold color(10)",
"snr.ok": "bold color(11)",
"snr.bad": "bold color(9)",
"batt.high": "bold color(10)",
"batt.mid": "color(3)",
"batt.low": "bold color(9)",
"batt.dim": "color(5)",
"type.node": "color(7)",
"type.repeater": "color(13)",
"type.room": "color(14)",
"batt.dim": "color(8)",
"type.node": "color(13)",
"type.repeater": "color(5)",
"type.room": "color(6)",
"type.sensor": "color(3)",
"heat.hot": "bold color(15)",
"heat.warm": "color(11)",
"heat.cool": "color(3)",
"heat.cold": "color(8)",
"heat.never": "color(6)",
"heat.cold": "color(7)",
"heat.never": "color(8)",
}
)
+7 -5
View File
@@ -882,15 +882,17 @@ def _recency_gradient(secs: Optional[float]) -> str:
def _recency_quantized(secs: Optional[float]) -> str:
"""PicoCalc's heat: the gradient collapsed onto the theme's four ``heat.*`` steps.
White within the hour, amber within six, orange within the day, muted beyond —
the gradient's own anchors, minus its red step (on a 16-slot console red is
reserved for errors). ``heat.never`` keeps never-heard a shade below ever-heard.
The boundaries are the plain human units (JP's spec: useful, easily understood):
white within the **quarter hour** (fresh — inside a typical advert interval),
yellow within the **hour**, orange within the **day**, default-grey beyond. No red
step — on the console red is reserved for errors. ``heat.never`` keeps never-heard
a shade below ever-heard.
"""
if secs is None:
return "heat.never"
if secs <= 3600:
if secs <= 900:
return "heat.hot"
if secs <= 21600:
if secs <= 3600:
return "heat.warm"
if secs <= 86400:
return "heat.cool"
+46 -19
View File
@@ -345,28 +345,33 @@ fi
echo "persisted FONT=$FONT_NAME in $VCONSOLE (loads on every boot)"
echo "A/B: 'setfont $OUT8' for 53x40, 'setfont $OUT' for 53x26; persist the winner in $VCONSOLE"
# --- palette: program the 16 console slots to MeshTerm's colours ------------------------
# The panel's VT layer is 16 fg / 8 bg palette slots -- no per-cell RGB -- so MeshTerm's
# 16-slot theme (meshterm/ui/theme.MESH_THEME_16) is designed against the slot meanings
# below, and this section programs the slots' actual RGB values. The palette file matches
# theme.vtrgb_lines() exactly (a test keeps them in sync); the boot oneshot re-applies it
# every start (same pattern as wifi-kick). setvtrgb does the work where kbd ships it; the
# fallback printf speaks the kernel VT's own OSC palette sequences, so nothing is required.
# --- palette -----------------------------------------------------------------------------
# JP's decision (2026-08-01): the console keeps its STANDARD kernel palette -- black
# background, stock hues -- and meshterm/ui/theme.MESH_THEME_16 is designed against those
# (theme._VT_SLOTS). The custom tailwind-family remap P3 originally shipped is ARCHIVED,
# one environment variable away in case he changes his mind:
#
# MESHTERM_CUSTOM_PALETTE=1 sh calculinux-console-font.sh
#
# The opt-in block's values match theme.vtrgb_lines() / theme._VT_SLOTS_CUSTOM exactly (a
# test keeps them in sync). A DEFAULT run removes any previously-installed remap and
# resets the live palette to stock.
VTRGB=/etc/vtrgb
APPLIER=/usr/local/sbin/meshterm-vtrgb
UNIT=/etc/systemd/system/meshterm-vtrgb.service
echo "writing $VTRGB ..."
cat > "$VTRGB" <<'EOF'
if [ "${MESHTERM_CUSTOM_PALETTE:-0}" = 1 ]; then
echo "writing $VTRGB (custom palette opt-in) ..."
cat > "$VTRGB" <<'EOF'
15,239,34,245,99,51,100,203,148,248,74,251,129,165,94,255
23,68,197,158,102,65,116,213,163,113,222,191,140,180,234,255
42,68,94,11,241,85,139,225,184,113,128,36,248,252,212,255
EOF
mkdir -p "$(dirname "$APPLIER")"
cat > "$APPLIER" <<'EOF'
mkdir -p "$(dirname "$APPLIER")"
cat > "$APPLIER" <<'EOF'
#!/bin/sh
# Apply the MeshTerm console palette (slots documented in meshterm/ui/theme._VT_SLOTS).
# Apply the MeshTerm custom console palette (meshterm/ui/theme._VT_SLOTS_CUSTOM).
if command -v setvtrgb >/dev/null 2>&1; then
exec setvtrgb /etc/vtrgb
fi
@@ -374,11 +379,11 @@ fi
TTY=${1:-/dev/tty1}
printf '\033]P00f172a\033]P1ef4444\033]P222c55e\033]P3f59e0b\033]P46366f1\033]P5334155\033]P664748b\033]P7cbd5e1\033]P894a3b8\033]P9f87171\033]Pa4ade80\033]Pbfbbf24\033]Pc818cf8\033]Pda5b4fc\033]Pe5eead4\033]Pfffffff' > "$TTY"
EOF
chmod +x "$APPLIER"
chmod +x "$APPLIER"
cat > "$UNIT" <<EOF
cat > "$UNIT" <<EOF
[Unit]
Description=MeshTerm console palette (16-slot vtrgb)
Description=MeshTerm console palette (custom 16-slot vtrgb)
After=systemd-vconsole-setup.service
[Service]
@@ -389,9 +394,31 @@ RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable meshterm-vtrgb.service >/dev/null 2>&1 || true
"$APPLIER" || echo "warning: could not apply the palette live (boot service will)"
echo "palette installed ($VTRGB + boot oneshot)"
systemctl daemon-reload
systemctl enable meshterm-vtrgb.service >/dev/null 2>&1 || true
"$APPLIER" || echo "warning: could not apply the palette live (boot service will)"
echo "custom palette installed ($VTRGB + boot oneshot)"
else
systemctl disable meshterm-vtrgb.service >/dev/null 2>&1 || true
rm -f "$UNIT" "$VTRGB" "$APPLIER"
systemctl daemon-reload 2>/dev/null || true
# Restore the STANDARD palette explicitly: a previous setvtrgb overwrote the
# kernel's *default* colormap, so the OSC reset (ESC ] R) alone would "reset"
# straight back to the custom values. Program the stock PC palette, then reset.
TTY=/dev/tty1
[ -c "$TTY" ] || TTY=/dev/tty0
if command -v setvtrgb >/dev/null 2>&1; then
STOCK=$(mktemp)
cat > "$STOCK" <<'EOF'
0,170,0,170,0,170,0,170,85,255,85,255,85,255,85,255
0,0,170,85,0,0,170,170,85,85,255,255,85,85,255,255
0,0,0,0,170,170,170,170,85,85,85,85,255,255,255,255
EOF
setvtrgb "$STOCK" || true
rm -f "$STOCK"
fi
printf '\033]P0000000\033]P1aa0000\033]P200aa00\033]P3aa5500\033]P40000aa\033]P5aa00aa\033]P600aaaa\033]P7aaaaaa\033]P8555555\033]P9ff5555\033]Pa55ff55\033]Pbffff55\033]Pc5555ff\033]Pdff55ff\033]Pe55ffff\033]Pfffffff\033]R' > "$TTY" 2>/dev/null || true
echo "palette: standard (custom remap removed; opt back in with MESHTERM_CUSTOM_PALETTE=1)"
fi
echo "done -- launch 'meshterm' to see braille charts, node glyphs, framed panels, and the > cursor."
+9 -8
View File
@@ -41,8 +41,9 @@ def test_bordered_frame_is_unchanged_on_regular() -> None:
assert any("╭" in line or "┌" in line for line in plain), "regular keeps its Panel"
def test_picocalc_header_drops_version_and_pulse() -> None:
"""The header_atoms wiring: no brand/version mark, no pulse row under picocalc."""
def test_picocalc_header_brands_the_app_not_the_device() -> None:
"""The header_atoms wiring, per JP's spec: picocalc shows ``MeshTerm vX`` (a soldered
radio's port never changes, so the device segment earns nothing), regular keeps both."""
from meshterm.ui.menu import _header_segments
class _Badges:
@@ -58,13 +59,13 @@ def test_picocalc_header_drops_version_and_pulse() -> None:
watchtower = _Badges()
set_platform(PICOCALC)
segments = _header_segments(_Ctx(), {})
text = "".join(seg.plain for seg in segments)
assert "MeshTerm" not in text and "v" not in text.split()[0]
assert "simulator" in text
text = "".join(seg.plain for seg in _header_segments(_Ctx(), {}))
assert "MeshTerm" in text
assert "simulator" not in text # the device atom is composed out
assert "pulse" in PICOCALC.header_atoms # the sparkline takes the remaining room
set_platform(REGULAR)
segments = _header_segments(_Ctx(), {})
assert "MeshTerm" in "".join(seg.plain for seg in segments)
text = "".join(seg.plain for seg in _header_segments(_Ctx(), {}))
assert "MeshTerm" in text and "simulator" in text
def test_fkey_lane_resolution_and_banks() -> None:
+10 -7
View File
@@ -57,8 +57,9 @@ def test_theme16_uses_only_the_sixteen_slots() -> None:
def test_theme16_bold_never_jumps_a_dim_slot_to_an_unrelated_bright_one() -> None:
"""The VT draws bold as brightness: bold on slots 0-7 lands on N+8.
Slots 5 and 6 are the repurposed dark slates whose +8 partners (lavender, teal) are
unrelated colours, so no style may combine bold with them.
Slots 5 and 6 carry semantics whose bright partners mean something *else* here
(5 purple = repeater names vs 13 pink = client names; 6 cyan = rooms/hint.brand vs
14 = brand), so no style may combine bold with them.
"""
for name, style in _our_styles(MESH_THEME_16).items():
if style.bold and style.color is not None and style.color.number in (5, 6):
@@ -77,12 +78,14 @@ def test_theme16_backgrounds_stay_in_the_dim_bank() -> None:
)
def test_deploy_script_carries_the_canonical_palette() -> None:
"""`/etc/vtrgb` in the deploy script matches ``theme.vtrgb_lines()`` byte for byte,
and the no-kbd OSC fallback spells the same sixteen RGB values."""
def test_deploy_script_carries_the_archived_custom_palette() -> None:
"""The script's **opt-in** block matches ``theme.vtrgb_lines()`` byte for byte, and
its no-kbd OSC fallback spells the same sixteen RGB values — so the archived custom
palette stays one environment variable away, in sync with `_VT_SLOTS_CUSTOM`."""
script = _FONT_SCRIPT.read_text(encoding="utf-8")
assert "MESHTERM_CUSTOM_PALETTE" in script, "the opt-in gate vanished"
assert theme.vtrgb_lines() in script, "scripts/calculinux-console-font.sh vtrgb drifted"
for index, (_, _, hex_) in enumerate(theme._VT_SLOTS):
for index, (_, _, hex_) in enumerate(theme._VT_SLOTS_CUSTOM):
sequence = f"\\033]P{index:x}{hex_.lstrip('#').lower()}"
assert sequence in script, f"OSC fallback missing slot {index}: {sequence}"
@@ -154,7 +157,7 @@ def test_fold_quantizes_embedded_truecolor_to_the_slots() -> None:
set_platform(PICOCALC)
folded = fold_text("\x1b[38;2;148;163;184m○\x1b[0m")
assert "38;2;" not in folded
assert "\x1b[90m" in folded # #94a3b8 is exactly slot 8 (muted)
assert "\x1b[37m" in folded # #94a3b8 → nearest stock slot is 7 (#aaaaaa)
background = fold_text("\x1b[48;2;94;234;212mX\x1b[0m")
assert "48;2;" not in background
assert re.search(r"\x1b\[4[0-7]m", background), background # bg clamps to the dim bank