magus-cli 7.3.1 → 7.4.0

package/src/ui/text-width.ts

@@ -0,0 +1,341 @@
+/**
+ * ui/text-width.ts — a copy of the bunjs `tui` skill's `assets/theme/text.ts`.
+ * Copied, never retyped; the lint override for it lives in biome.json.
+ *
+ * Display-cell maths OpenTUI does not ship: `text-table-width.ts`
+ * is internal, and Yoga measures layout, not the columns a string occupies. All
+ * four count TERMINAL DISPLAY COLUMNS, never code units. Surface-neutral: no
+ * OpenTUI import in this file.
+ *
+ * TWO CONTRACTS, and they are deliberately different:
+ *
+ * - `displayWidth` MEASURES. It reports what a terminal paints, so a control
+ *   character costs 0 — that is the oracle's answer and the terminal's.
+ * - `truncate` / `padTo` / `padStartTo` PRODUCE. They sanitise first (see
+ *   `sanitize`), so their output is always ONE LINE of exactly the columns
+ *   claimed. `displayWidth(s)` and `displayWidth(padTo(s, w))` therefore need not
+ *   agree for control-bearing `s`, and that is stated here rather than left to be
+ *   discovered: a newline costs 0 columns to measure and 1 column to print.
+ *
+ * ANSI escapes are still NOT accepted — styled text in is a caller bug. It no
+ * longer corrupts the layout (the ESC is neutralised to a space, so it cannot move
+ * the cursor), but the sequence body prints literally. That is the intended loud
+ * failure; do not "fix" it by stripping sequences, which would silently swallow the
+ * caller's bug and their colours with it.
+ */
+
+/**
+ * `Bun.stringWidth` — a native, maintained Unicode width table — is the width
+ * oracle whenever it exists, which per this skill's stated support matrix is
+ * always. The hand table below is a FALLBACK for a non-Bun runtime, nothing more.
+ *
+ * Bound through `globalThis` rather than the `Bun` global so this file typechecks
+ * when it is copied into a project with no `@types/bun`. Bun's defaults are the
+ * ones wanted: `ambiguousIsNarrow` (so `⚠` is 1 column, as every modern terminal
+ * paints it) and ANSI excluded from the count.
+ */
+const NATIVE_WIDTH: ((s: string) => number) | null = (() => {
+	const b = (globalThis as { Bun?: { stringWidth?: (s: string) => number } })
+		.Bun;
+	return typeof b?.stringWidth === "function" ? b.stringWidth.bind(b) : null;
+})();
+
+/**
+ * FALLBACK ONLY — East_Asian_Width Wide/Fullwidth, MINUS the emoji, which
+ * `\p{Emoji_Presentation}` covers far better than any literal range can. Sorted and
+ * non-overlapping; `isWide` binary-searches it.
+ *
+ * Splitting the work this way is what fixed the four measured defects at once: the
+ * engine's own Unicode tables answer "is this an emoji that defaults to Wide?", so
+ * `🌡` and `🖥` (text presentation) stop being force-widened by a block-coarse
+ * `[0x1f300, 0x1f9ff]` run, while an explicit range brings in the non-emoji planes
+ * that run never covered — Tangut, Nushu, Khitan, Kana Extended.
+ *
+ * MEASURED 2026-07-30 against `Bun.stringWidth` across all 1,112,064 codepoints:
+ * 1,081 disagreements, down from 11,205 for the previous hand table. 749 are lone
+ * combining marks and 237 are codepoints this engine's Unicode tables do not know;
+ * neither occurs in real text. Only 17 are anything else, 14 of them Unicode 16
+ * emoji where the FALLBACK is right and the oracle is behind. `color.test.ts` pins
+ * every one of those numbers, so widening a run without a sweep fails the suite.
+ */
+const WIDE: ReadonlyArray<readonly [number, number]> = [
+	[0x1100, 0x115f],
+	[0x2329, 0x232a],
+	[0x2e80, 0x303e],
+	[0x3041, 0x31e3],
+	[0x31e6, 0x3247],
+	[0x3250, 0x33ff],
+	[0x3400, 0x4dbf],
+	[0x4e00, 0x9fff],
+	[0xa000, 0xa4cf],
+	[0xa960, 0xa97f],
+	[0xac00, 0xd7a3],
+	[0xf900, 0xfaff],
+	[0xfe10, 0xfe19],
+	[0xfe30, 0xfe6f],
+	[0xff00, 0xff60],
+	[0xffe0, 0xffe6],
+	[0x16fe0, 0x16fe4],
+	[0x16ff0, 0x16ff1],
+	[0x17000, 0x187f7],
+	[0x18800, 0x18cd5],
+	[0x18d00, 0x18d08],
+	[0x1aff0, 0x1aff3],
+	[0x1aff5, 0x1affb],
+	[0x1affd, 0x1affe],
+	[0x1b000, 0x1b122],
+	[0x1b132, 0x1b132],
+	[0x1b150, 0x1b152],
+	[0x1b155, 0x1b155],
+	[0x1b164, 0x1b167],
+	[0x1b170, 0x1b2fb],
+	[0x1f200, 0x1f202],
+	[0x1f210, 0x1f23b],
+	[0x1f240, 0x1f248],
+	[0x1f250, 0x1f251],
+	[0x1f260, 0x1f265],
+	[0x20000, 0x2fffd],
+	[0x30000, 0x3fffd],
+];
+
+const seg = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** U+FE0F VARIATION SELECTOR-16, spelled by codepoint: as a bare literal it is an
+ * invisible character in the source, which is how a `includes("…")` test for it
+ * survives review while matching nothing. Its sibling U+FE0E (text presentation)
+ * needs no branch — MEASURED against the oracle, it narrows nothing: `⚠︎` is 1
+ * because `⚠` already is, and `⛔︎` stays 2 because U+26D4 is intrinsically Wide. */
+const VS16 = "\uFE0F";
+
+/** Zero-width in the fallback: format characters (`Cf`) — U+00AD SOFT HYPHEN,
+ * U+200B ZERO WIDTH SPACE, U+200D ZWJ, U+FEFF. The previous table had no notion of
+ * these at all and billed each one a column. Anchored, because it classifies a
+ * grapheme cluster by the codepoint that STARTS it. */
+const LEADING_FORMAT = /^\p{Cf}/u;
+
+/** Wide in the fallback, part two: emoji whose default presentation is Wide. This
+ * is the engine's own table, so it tracks Unicode releases without an edit here. */
+const LEADING_EMOJI_PRESENTATION = /^\p{Emoji_Presentation}/u;
+
+/** C0, DEL and C1. Every one is unprintable, and three of them actively wreck a
+ * frame: `\n` breaks the row, `\t` advances to an unknowable tab stop, ESC can
+ * reposition the cursor anywhere on screen. */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/**
+ * THE CONTROL-CHARACTER CONTRACT for everything that returns a string: every C0
+ * control, DEL and every C1 control is REPLACED BY ONE SPACE. Not stripped, not
+ * rejected.
+ *
+ * - Not rejected, because these functions render whatever a log line contains, and
+ *   a tab in a log line must not throw inside a render loop.
+ * - Not stripped, because deleting `\n` fuses the words either side of it
+ *   (`"a\nbc"` → `"abc"`), which reads as a different message. One space keeps the
+ *   boundary and costs exactly one predictable column.
+ * - One rule with no exceptions, so the guarantee is total: the output of
+ *   `truncate`, `padTo` and `padStartTo` can never contain a newline, a tab or an
+ *   ESC, and `Bun.stringWidth(padTo(s, w)) === w` holds for EVERY `s`.
+ *
+ * `.replace` with a `/g` regex is used unconditionally — `CONTROL.test()` as a
+ * fast-path guard would be a stateful-`lastIndex` bug that skips every other call.
+ */
+const sanitize = (s: string): string => s.replace(CONTROL, " ");
+
+/**
+ * THE NUMERIC CONTRACT for every column count in this file: floored to whole
+ * columns, clamped at 0, and NON-FINITE THROWS.
+ *
+ * Fractional is tolerated because it is a legitimate computation — `width / 3`
+ * across a flex row — and half a column cannot be painted, so flooring is the only
+ * answer and it cannot be wrong. Non-finite is never a legitimate computation: it
+ * means the caller's arithmetic already broke, every column downstream is garbage,
+ * and there is no honest value to return. `padTo("abcdef", NaN)` used to answer six
+ * columns and `padTo("abcdef", Infinity)` used to throw a `RangeError` from
+ * `String.repeat` naming neither the function nor the argument. Both now fail at
+ * the boundary, loudly, pointing at the caller.
+ *
+ * Note this governs WIDTHS only. A `splitCells` PART is a datum, not a dimension,
+ * and keeps its documented "negative/NaN/Infinity → 0" rule: a missing measurement
+ * sensibly contributes nothing, whereas a missing dimension has no sensible value.
+ */
+function columns(n: number, fn: string, arg = "width"): number {
+	if (!Number.isFinite(n))
+		throw new RangeError(`${fn}: ${arg} must be a finite number, got ${n}`);
+	return Math.max(0, Math.floor(n));
+}
+
+/** Binary search over `WIDE`. Linear `.some()` was fine at 18 runs and is not at 37:
+ * this runs once per grapheme on the fallback path. */
+function isWide(cp: number): boolean {
+	let lo = 0;
+	let hi = WIDE.length - 1;
+	while (lo <= hi) {
+		const mid = (lo + hi) >> 1;
+		const [a, b] = WIDE[mid]!;
+		if (cp < a) hi = mid - 1;
+		else if (cp > b) lo = mid + 1;
+		else return true;
+	}
+	return false;
+}
+
+/** Fallback width of ONE grapheme cluster, classified by the codepoint that starts
+ * it plus a VS16 check. Exported for the test that measures the fallback against
+ * the oracle — without a way to reach it, the fallback would ship unmeasured on
+ * the one runtime that never runs the oracle. */
+export function fallbackClusterWidth(cluster: string): number {
+	const cp = cluster.codePointAt(0) ?? 0;
+	if (cp < 0x20 || (cp >= 0x7f && cp <= 0x9f) || LEADING_FORMAT.test(cluster))
+		return 0;
+	return isWide(cp) ||
+		LEADING_EMOJI_PRESENTATION.test(cluster) ||
+		cluster.includes(VS16)
+		? 2
+		: 1;
+}
+
+/**
+ * Columns `s` occupies. `Bun.stringWidth` answers this directly and correctly; the
+ * loop below is the fallback for a runtime without it and counts GRAPHEME CLUSTERS,
+ * so a cluster costs the same however many code units it spans.
+ *
+ * Either way: controls and format characters are 0, a ZWJ sequence counts as its
+ * base cluster (one emoji = 2), Wide/Fullwidth and U+FE0F-forced emoji presentation
+ * are 2, everything else printable is 1. Both paths are grapheme-additive — summing
+ * per cluster equals measuring the whole string — which is what lets `truncate`
+ * clip cluster by cluster and still land on the width it promises.
+ */
+export function displayWidth(s: string): number {
+	if (NATIVE_WIDTH) return NATIVE_WIDTH(s);
+	let w = 0;
+	for (const { segment } of seg.segment(s)) w += fallbackClusterWidth(segment);
+	return w;
+}
+
+/**
+ * Clip to `width` columns, NEVER WRAP: the last column becomes "…". A wide grapheme
+ * that would straddle the edge is dropped whole, never split in half.
+ *
+ * "Never wrap" is a promise about the OUTPUT, so the input is sanitised first — a
+ * returned `"a\n…"` was two rows wearing a one-row width, and it reached `padTo`
+ * and `padStartTo` too. Output may be SHORTER than `width` when a wide cluster is
+ * dropped (`truncate("日本語", 4)` is 3 columns); it is never longer, and it is
+ * never more than one line.
+ */
+export function truncate(s: string, width: number): string {
+	const n = columns(width, "truncate");
+	if (n === 0) return "";
+	const clean = sanitize(s);
+	if (displayWidth(clean) <= n) return clean;
+	let out = "";
+	let w = 0;
+	for (const { segment } of seg.segment(clean)) {
+		const cw = displayWidth(segment);
+		if (w + cw > n - 1) break;
+		out += segment;
+		w += cw;
+	}
+	return `${out}…`;
+}
+
+/**
+ * Exactly `width` columns: clip if long, pad if short. `displayWidth(padTo(s, w))
+ * === w`, always — and so does `Bun.stringWidth(padTo(s, w))`, which is the
+ * stronger claim and the one a terminal actually settles.
+ *
+ * `padEnd()` and `.slice()` are BANNED here — they count UTF-16 code units, so they
+ * split surrogate pairs and under-count CJK by half, the exact failure
+ * `displayWidth` exists to fix. Build on truncate + displayWidth.
+ */
+export function padTo(s: string, width: number): string {
+	const n = columns(width, "padTo");
+	if (n === 0) return "";
+	const clean = sanitize(s);
+	const clipped = displayWidth(clean) > n ? truncate(clean, n) : clean;
+	return clipped + " ".repeat(Math.max(0, n - displayWidth(clipped)));
+}
+
+/**
+ * `padTo`'s mirror: exactly `width` columns with the content flush RIGHT. This is
+ * what `aesthetics-and-color.md`'s "right-align numerals and pad to a fixed width"
+ * needs — `padTo` left-aligns, so a numeral column padded with it jitters at the
+ * decimal point, which is the drift that rule exists to stop.
+ *
+ * `padStart()` is BANNED here for the same reason as `padEnd()`: it counts UTF-16
+ * code units, so `"日本".padStart(6)` adds 4 spaces for a string already 4 columns
+ * wide. Built on `truncate` + `displayWidth`, so `displayWidth(padStartTo(s, w)) === w`
+ * holds for CJK, combining marks and ZWJ emoji alike.
+ *
+ * Over-long input clips from the END (`"1234567" → "123…"`), matching `padTo`: keeping
+ * the tail instead would print a numeral's low-order digits and read as a smaller
+ * number.
+ */
+export function padStartTo(s: string, width: number): string {
+	const n = columns(width, "padStartTo");
+	if (n === 0) return "";
+	const clean = sanitize(s);
+	const clipped = displayWidth(clean) > n ? truncate(clean, n) : clean;
+	return " ".repeat(Math.max(0, n - displayWidth(clipped))) + clipped;
+}
+
+/**
+ * Apportion `cells` across `parts` by share, LARGEST-REMAINDER rounding, so the
+ * result sums to EXACTLY `cells` — naive per-segment rounding leaves a stacked bar
+ * a cell short and every column right of it drifts. Precondition
+ * `cells >= nonZeroParts`: every non-zero part then gets >= 1 cell, stolen from the
+ * largest allocation. Over-subscribed (4 parts into 3 cells) that is dropped — the
+ * `cells` largest parts get 1 each, rest 0, sum still `cells`. ALL PARTS ZERO →
+ * zeros, sum 0, NOT `cells`.
+ *
+ * `cells` is a DIMENSION and obeys `columns()`: floored, clamped at 0, non-finite
+ * throws. `cells <= 0` → zeros. It used to return `[2, 1]` for two parts and 2.5
+ * cells — a sum of 3 from a request for 2.5, breaking the one invariant this
+ * function exists to hold — and NaN allocations for NaN or Infinity.
+ *
+ * `parts` are DATA and are forgiving: negative, NaN and Infinity all read as 0.
+ * They are also overflow-safe. `[MAX_VALUE, MAX_VALUE]` overflowed `sum` to
+ * Infinity and made every share `Infinity / Infinity` = NaN; dividing through by
+ * the largest part first is exact in ratio and lands every share back in 0..1.
+ * Shares are then `cells * (p / sum)` and not `(cells * p) / sum`, because the
+ * latter overflows on a single part near MAX_VALUE even when `sum` is finite.
+ */
+export function splitCells(parts: number[], cells: number): number[] {
+	const n = columns(cells, "splitCells", "cells");
+	const finite = parts.map((p) => (Number.isFinite(p) && p > 0 ? p : 0));
+	const out = finite.map(() => 0);
+	let safe = finite;
+	let sum = finite.reduce((a, b) => a + b, 0);
+	if (!Number.isFinite(sum)) {
+		const max = finite.reduce((a, b) => (b > a ? b : a), 0);
+		safe = finite.map((p) => p / max);
+		sum = safe.reduce((a, b) => a + b, 0);
+	}
+	if (n <= 0 || sum <= 0) return out;
+	const byShare = safe.map((p, i) => ({ p, i })).sort((a, b) => b.p - a.p);
+	if (n < byShare.filter(({ p }) => p > 0).length) {
+		for (const { i } of byShare.slice(0, n)) out[i] = 1;
+		return out;
+	}
+	const exact = safe.map((p) => n * (p / sum));
+	exact.forEach((e, i) => {
+		out[i] = Math.floor(e);
+	});
+	const rank = exact
+		.map((e, i) => ({ rem: e % 1, i }))
+		.sort((a, b) => b.rem - a.rem);
+	for (
+		let k = 0, left = n - out.reduce((a, b) => a + b, 0);
+		left > 0;
+		k++, left--
+	)
+		out[rank[k % rank.length]!.i]! += 1;
+	for (const { p, i } of byShare)
+		if (p > 0 && out[i] === 0) {
+			const d = byShare.reduce((m, c) => (out[c.i]! > out[m]! ? c.i : m), 0);
+			if (out[d]! > 1) {
+				out[d]! -= 1;
+				out[i] = 1;
+			}
+		}
+	return out;
+}

package/src/ui/theme-mode.ts

@@ -37,70 +37,30 @@ export function resetThemeMode(): void {
 }
 
 /**
- * Fill for an UNLIT segment of the three-square scope bar.
- *
- * The bar reads as three segments, each lit (in its scope colour) or unlit. Unlit
- * used to be the same mid-grey as body de-emphasis, `#6B7280`, which is dark —
- * so an unlit segment carried the same visual weight as a lit one and the bar
- * read as three similar blobs. Reported directly: "non installed state is dark as
- * well - confusing".
- *
- * An unlit segment should recede toward the page, and "toward the page" is the
- * one thing a fixed colour cannot express: a pale fill that sits quietly on cream
- * is a bright block on near-black. Hence the two values, chosen per resolved
- * mode — this is the only place magus asks.
- */
-export const SCOPE_OFF_FILL = {
-	/** Just off a light page — a filled but quiet segment. */
-	light: "#D9D9CC",
-	/** Just off a dark page. */
-	dark: "#3A3A40",
-} as const;
-
-/** Fill colour for an unlit scope segment. Always a colour — never undefined,
- *  because the segment is a filled block whatever the terminal turns out to be. */
-export function scopeOffFill(): string {
-	return SCOPE_OFF_FILL[detected];
-}
-
-/**
- * Badge colours for the four plugin component kinds.
+ * The chip behind a plugin component's type glyph (`✱` `/` `@` `⬢`).
+ *
+ * ONE neutral wash for every kind. The glyph already says the kind, so a hue per
+ * kind said it twice — and the four it used (purple / teal / blue / amber) each
+ * meant something else elsewhere: amber is "needs a look", purple the cursor. On
+ * hundreds of rows at once that was the loudest decoration on the screen and it
+ * carried no signal. A kind is chrome; chrome recedes.
  *
- * These are chips, not accents: they sit on hundreds of rows at once, so the
- * fill has to be a *wash* of the hue rather than the hue itself. That runs into
- * the same wall `SCOPE_OFF_FILL` documents above — a wash is defined relative to
- * the page, ANSI has no alpha, so the two ends are picked by hand.
+ * It is still a wash rather than nothing, because the chip is what anchors a
+ * component row under its plugin. A wash is defined relative to the page and
+ * ANSI has no alpha, so the two ends are picked by hand, MEASURED:
  *
- * Hues are deliberately far apart (purple / teal / blue / amber) for the reason
- * the scope squares are: one character of colour carries no readable hue shift,
- * only a readable hue *difference*.
+ *            chip vs page      glyph on chip
+ *   light    1.20 (cream)      6.95
+ *   dark     1.42 (#1C1C1E)    7.80    (1.17 on One Dark's #282C34, 1.76 on black)
  *
- * The glyph colour is set per mode too. Reusing the vivid accent over a dark
- * wash would drop it below the contrast the palette guarantees against the
- * page — the accent's measured ratio is against `CONTRAST_REFERENCE`, not
- * against another tint laid on top of it.
+ * Quiet against the page (under 1.6, where a wash stops being a tint and starts
+ * being a highlight bar), and the glyph clears 4.5:1 on its own chip.
  */
-export const COMPONENT_BADGE = {
-	skill: {
-		light: { bg: "#E9DCF5", fg: "#6B21A8" },
-		dark: { bg: "#2E2140", fg: "#C4A5F0" },
-	},
-	command: {
-		light: { bg: "#D3E7EC", fg: "#0E5F73" },
-		dark: { bg: "#123037", fg: "#7DD3E0" },
-	},
-	agent: {
-		light: { bg: "#DCE4F7", fg: "#1D4ED8" },
-		dark: { bg: "#1B2740", fg: "#A5C0F5" },
-	},
-	mcp: {
-		light: { bg: "#F0E2CE", fg: "#92400E" },
-		dark: { bg: "#3A2A15", fg: "#E5B877" },
-	},
+export const COMPONENT_CHIP = {
+	light: { bg: "#E4E4D6", fg: "#4A4A44" },
+	dark: { bg: "#36363F", fg: "#D0D0D8" },
 } as const;
 
-export type ComponentBadgeKind = keyof typeof COMPONENT_BADGE;
-
 /**
  * Badge and chart colours for the four Claude models, the three external-model slots, and
  * `inherit`.
@@ -131,7 +91,7 @@ export type ComponentBadgeKind = keyof typeof COMPONENT_BADGE;
  *
  * ## The two pages are built differently, deliberately
  *
- * `COMPONENT_BADGE` above explains why a chip needs two ends at all. This map goes one step
+ * `COMPONENT_CHIP` above explains why a chip needs two ends at all. This map goes one step
  * further and does not MIRROR them. Cream already carries the light, so a light chip is a
  * pale wash under mid-tone ink and stays quiet. A near-black page carries none, so the same
  * construction turns grey and the screen goes flat — a symmetric palette was built, shown,
@@ -142,8 +102,8 @@ export type ComponentBadgeKind = keyof typeof COMPONENT_BADGE;
  * ## The dark fills clear a page we cannot see
  *
  * `CONTRAST_REFERENCE_KEYS.dark` is `#1C1C1E`, but a real terminal may be pure black or a
- * slate like One Dark's `#282C34`. MEASURED, the `COMPONENT_BADGE` dark washes sit at
- * 1.00–1.07:1 against that slate — the same luminance as the page — so the chip loses its
+ * slate like One Dark's `#282C34`. MEASURED, the per-kind component washes this file used to
+ * carry sat at 1.00–1.07:1 against that slate — the same luminance as the page — so a chip lost its
  * edge and reads as a hole punched in the row. These fills clear every ground: 3.1–4.3:1 on
  * black, 2.8–2.9 on slate, and they still clear 4.5:1 on cream, so even a mis-detected theme
  * is merely odd rather than unreadable.
@@ -380,14 +340,17 @@ export function modelBadge(kind: string): ModelInk {
 /**
  * The UNLIT track: the `·` behind an effort dot, the `░` behind a bar.
  *
- * Light reuses `SCOPE_OFF_FILL`, which already solves this there. Dark does NOT: at
- * `#3A3A40` the track measures 1.51:1 on the reference page and simply vanishes, so a bar
- * reads as a floating block with no scale and the effort dots lose the denominator that
- * makes them a level rather than a count. `#4A4A52` is 1.94:1 — still recessive, still
- * visible.
+ * An unlit segment should recede toward the page, and "toward the page" is the one thing a
+ * fixed colour cannot express: a pale fill that sits quietly on cream is a bright block on
+ * near-black. Hence two values, one per resolved mode.
+ *
+ * Light is `#D9D9CC`, just off the cream page. Dark cannot mirror it: at `#3A3A40` the
+ * track measures 1.51:1 on the reference page and simply vanishes, so a bar reads as a
+ * floating block with no scale and the effort dots lose the denominator that makes them a
+ * level rather than a count. `#4A4A52` is 1.94:1 — still recessive, still visible.
  */
 export const TRACK_FILL = {
-	light: SCOPE_OFF_FILL.light,
+	light: "#D9D9CC",
 	dark: "#4A4A52",
 } as const;
 
@@ -419,7 +382,7 @@ export function trackFill(): string {
  * the label sits near the page.
  *
  * Both pages are built from the greys already in this file — the light label is
- * `SCOPE_OFF_FILL.light`, the dark key is `TRACK_FILL.dark` — so the footer sits
+ * `TRACK_FILL.light`, the dark key is `TRACK_FILL.dark` — so the footer sits
  * in the same neutral family as every other quiet fill rather than introducing a
  * third grey ramp.
  */
@@ -485,10 +448,10 @@ export const CONTRAST_REFERENCE_KEYS = {
 	dark: "#1C1C1E",
 } as const;
 
-/** Chip colours for one component kind, for the resolved mode. */
-export function componentBadge(kind: ComponentBadgeKind): {
+/** The component-kind chip, for the resolved mode. */
+export function componentChip(): {
 	bg: string;
 	fg: string;
 } {
-	return COMPONENT_BADGE[kind][detected];
+	return COMPONENT_CHIP[detected];
 }

package/src/ui/theme.ts

@@ -34,7 +34,29 @@ import { RGBA } from "@opentui/core";
  * Where we own a badge's background we also own its ink, so `ink` is plain white
  * and its contrast is deterministic rather than a function of the user's theme.
  * That is why badge ink is not slot 0 or the terminal background: on a light
- * theme, terminal-background ink on a yellow chip is unreadable.
+ * theme, terminal-background ink on an amber chip is unreadable.
+ *
+ * ## One hue, one meaning
+ *
+ * Every token is named for what it MEANS, never for what it looks like, and
+ * each hue carries exactly one meaning across every screen:
+ *
+ *   accent   magus's own chrome — headings, the active tab, the selected row
+ *   info     reference facts — paths, URLs, counts, names in a detail heading
+ *   success  on, installed, done
+ *   warning  needs a look — an update, unverified, unapplied, needs config
+ *   danger   broken, failed, a rule violated, a destructive key
+ *   muted    quiet — unset, off, not installed, chrome, work in progress
+ *
+ * Two consequences worth stating. Loading is `muted`, never `warning`: amber
+ * says "look at this", and a spinner asks for nothing. And the three scopes no
+ * longer own a hue each — they were blue / green / amber, which made green
+ * mean both "installed" and "project" and amber both "warning" and "local".
+ * A scope square is now identified by POSITION (user, project, local) and its
+ * state by SHAPE (■ installed, □ not), so it reads without colour at all; the
+ * filled square wears `success` because that is what it says.
+ *
+ * `link` (a sixth hue, blue) folded into `info`: a URL is a reference fact.
  */
 
 /** Reference backgrounds every accent is measured against. */
@@ -44,18 +66,16 @@ export const CONTRAST_REFERENCE = {
 } as const;
 
 /**
- * The vivid set. Ratios are (on light / on dark), measured — see the test.
- * Hues for the three scopes are deliberately far apart (blue / green / amber)
- * because they appear as single-character squares, where a subtle hue shift is
- * not readable at all.
+ * The vivid set: five hues and a grey. Ratios are (on light / on dark),
+ * measured — see the test. Each value is named for its meaning; the hue is
+ * noted beside it only so a reader can picture it.
  */
 export const brand = {
-	accent: "#9333EA", // 5.04 / 3.16 — brand purple
-	link: "#2563EB", // 4.84 / 3.29
+	accent: "#9333EA", // 5.04 / 3.16 — purple
 	info: "#0E7490", // 5.02 / 3.18 — teal
-	success: "#15803D", // 4.70 / 3.39
+	success: "#15803D", // 4.70 / 3.39 — green
 	warning: "#B45309", // 4.70 / 3.39 — amber
-	danger: "#DC2626", // 4.52 / 3.52
+	danger: "#DC2626", // 4.52 / 3.52 — red
 	muted: "#6B7280", // 4.53 / 3.52 — de-emphasis, still legible on both
 	/** Ink on OUR badges. We own both sides, so contrast is deterministic. */
 	ink: "#FFFFFF",
@@ -80,6 +100,9 @@ export const brand = {
 /** Any colour a component may hand to a JSX colour prop. */
 export type UiColor = string | RGBA;
 
+/** A group header's role — a key of `theme.badge`. */
+export type BadgeTone = "neutral" | "info" | "success" | "warning" | "danger";
+
 /** The terminal's own foreground — the only honest "normal text" colour. */
 const fg = () => RGBA.defaultForeground();
 
@@ -94,9 +117,9 @@ export const theme = {
 		/** Same grey as `muted`; a third level should come from layout, not colour. */
 		dim: brand.muted,
 		border: brand.muted,
-		link: brand.link,
 		accent: brand.accent,
-		/** Low-key brand tint for bylines — readable, deliberately not attention-grabbing. */
+		/** magus's own mark on its makers' marketplaces — the accent, because it is
+		 *  our chrome, and never `success`, which would read as a status. */
 		byline: brand.accent,
 		success: brand.success,
 		warning: brand.warning,
@@ -119,27 +142,26 @@ export const theme = {
 		dim: brand.selectionDim,
 	},
 
-	/** Blue / green / amber: the widest hue separation available, because these
-	 *  render as one-character squares where a subtle shift reads as noise. */
-	scopes: {
-		user: brand.link,
-		project: brand.success,
-		local: brand.warning,
-	},
-
-	/** Badge colours. `fg` is the ink ON the block; `badgeFg` is the same hue used
-	 *  as ink on the normal background instead. */
-	category: {
-		purple: { bg: brand.accent, fg: brand.ink, badgeFg: brand.accent },
-		green: { bg: brand.success, fg: brand.ink, badgeFg: brand.success },
-		teal: { bg: brand.info, fg: brand.ink, badgeFg: brand.info },
-		yellow: { bg: brand.warning, fg: brand.ink, badgeFg: brand.warning },
-		gray: { bg: brand.muted, fg: brand.ink, badgeFg: brand.muted },
-		red: { bg: brand.danger, fg: brand.ink, badgeFg: brand.danger },
+	/**
+	 * Filled group headers, by what the group IS. `fg` is the ink ON the block;
+	 * `badgeFg` is the same role used as ink on the page, for the badge after it.
+	 *
+	 * Most groups are just groups and wear `neutral`. A hue is earned only by a
+	 * group whose name is a state — "Installed" is `success`, a deprecated
+	 * marketplace `danger`. There is no accent header: the accent fill is the
+	 * selected row, and a header wearing it reads as the cursor.
+	 */
+	badge: {
+		neutral: { bg: brand.muted, fg: brand.ink, badgeFg: brand.muted },
+		info: { bg: brand.info, fg: brand.ink, badgeFg: brand.info },
+		success: { bg: brand.success, fg: brand.ink, badgeFg: brand.success },
+		warning: { bg: brand.warning, fg: brand.ink, badgeFg: brand.warning },
+		danger: { bg: brand.danger, fg: brand.ink, badgeFg: brand.danger },
 	},
 
 	meta: {
 		muted: brand.muted,
+		info: brand.info,
 		warning: brand.warning,
 		success: brand.success,
 		danger: brand.danger,

package/src/utils/request-gate.ts

@@ -0,0 +1,37 @@
+/**
+ * The latest request wins.
+ *
+ * A screen that reloads on mount AND on an external refresh signal can have two
+ * loads in flight at once, and they settle in whatever order the network
+ * decides. Applying every result means the one that finishes LAST wins — which
+ * is often the older one, carrying data from before the thing that triggered
+ * the newer load. A gate makes the rule explicit: take a token when a load
+ * starts, and apply the result only if that token is still the newest.
+ *
+ * ```ts
+ * const gate = createRequestGate();
+ * async function load() {
+ *   const token = gate.begin();
+ *   const data = await fetchSomething();
+ *   if (!gate.isCurrent(token)) return; // a newer load started meanwhile
+ *   apply(data);
+ * }
+ * ```
+ */
+export interface RequestGate {
+	/** Start a request. Every token handed out before this one stops being current. */
+	begin(): number;
+	/** Is `token` the most recently started request? Asking changes nothing. */
+	isCurrent(token: number): boolean;
+}
+
+export function createRequestGate(): RequestGate {
+	let latest = 0;
+	return {
+		begin: () => {
+			latest += 1;
+			return latest;
+		},
+		isCurrent: (token) => token === latest,
+	};
+}