magus-cli 0.0.0-placeholder → 7.0.0

package/src/ui/theme-mode.ts

@@ -0,0 +1,352 @@
+import type { ThemeMode } from "@opentui/core";
+
+/**
+ * The one place magus needs to know whether the terminal is light or dark.
+ *
+ * Everything else in the palette avoids this question on purpose: accents are
+ * chosen to clear 3:1 against both backgrounds, and body text uses the terminal's
+ * own foreground. A *disabled row tint* is the exception, because "subtle" is
+ * defined relative to the page — a wash that sits gently on cream is a bright
+ * band on near-black, and there is no third colour that is quiet on both.
+ *
+ * ANSI cannot help here either: there is no alpha channel, so the tint cannot be
+ * expressed as "the page, 8% toward the foreground". OpenTUI's alpha blending
+ * lives only in its 3d module, not the text renderer.
+ *
+ * So we resolve, once at startup, through `theme-resolve.ts`: flag, then
+ * `MAGUS_THEME`, then `TERM_THEME`, then the bounded OSC probe, then
+ * `COLORFGBG`, then dark. **There is no unknown.** Resolution always yields a
+ * mode; when nothing answered it is dark, because that is the user's stated
+ * default, not because dark was detected.
+ */
+
+let detected: ThemeMode = "dark";
+
+/** Set once at startup from `resolveTheme()`. */
+export function setThemeMode(mode: ThemeMode): void {
+	detected = mode;
+}
+
+export function getThemeMode(): ThemeMode {
+	return detected;
+}
+
+/** Test seam — return to the pre-resolution default between cases. */
+export function resetThemeMode(): void {
+	detected = "dark";
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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*.
+ *
+ * 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.
+ */
+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" },
+	},
+} 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`.
+ *
+ * Four strengths, because a badge and a bar cannot share an ink: twenty characters of a
+ * colour weigh far more than six, so what reads as a label reads as a slab when it is a
+ * chart. `bg`/`fg` are the chip; `bar` is the distribution bar's fill; `label` is the ink a
+ * word takes when it is written ON that fill.
+ *
+ * ## Why `label` exists, and why `fg` could not do its job
+ *
+ * A segment of the workflow chart is one block of one colour with its model's name written
+ * on it. The name used to be drawn as the CHIP — `fg` on `bg`, inset into the bar — which
+ * put a second, visibly different rectangle inside a block that is supposed to read as one
+ * thing. Reported exactly that way: "do not add additional background colour to model
+ * segments".
+ *
+ * Deleting the chip and keeping `fg` was not an option: MEASURED, `fg` on the same model's
+ * `bar` runs 1.74:1 (sonnet dark) to 2.99:1 (haiku dark), which is a smudge rather than a
+ * word. `fg` is built to sit on `bg`, and `bg` is not what a bar is painted with.
+ *
+ * So each model owns a fourth ink, chosen against its OWN bar and nothing else. Every one is
+ * the model's own hue taken deep — the same family, not a fifth palette — and every one
+ * clears 4.5:1 with margin; the measured value is on each line below. `inherit` is the one
+ * that runs the other way: its bar is a dark recessive grey rather than a bright mid-tone,
+ * so its label is near-white on the dark page. That is forced by the fill, not a stylistic
+ * exception.
+ *
+ * ## The two pages are built differently, deliberately
+ *
+ * `COMPONENT_BADGE` 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,
+ * and rejected on sight as "dark looks like the light theme". A dark chip is therefore a
+ * SATURATED MID-TONE under near-white ink: a wash toward black is dark, a wash toward white
+ * is the light theme, and neither of those is a colour.
+ *
+ * ## 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
+ * 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.
+ *
+ * Hues stay far apart for the same reason the scope squares' do: one or two characters of
+ * colour carry no readable hue SHIFT, only a readable hue DIFFERENCE.
+ *
+ * ## The mates are ONE hue family, and that is the exception that proves the rule
+ *
+ * `mate1`, `mate2` and `kangaroo` are three different external models, so they need three
+ * distinguishable inks — but they all mean the same thing (someone else's model, reached
+ * through claudish), and four unrelated hues would say the opposite. They therefore share a
+ * warm outback band nothing else on this screen occupies: measured hue angles 39° / 23° / 6°
+ * on the dark page and 41° / 25° / 10° on the light one — ochre, terracotta, red earth. The
+ * four Claude models sit at teal 190°, green 150°, purple 265° and grey, so a mate cannot be
+ * mistaken for one of them at a glance, and a mate cannot be mistaken for another mate
+ * either, because ~17° of hue at full saturation is a readable difference where ~17° of
+ * LUMINANCE would not be.
+ *
+ * Measured contrast, ink on its own fill (the number the chip has to clear):
+ *
+ *   mate1     light 5.60:1   dark 4.82:1
+ *   mate2     light 5.82:1   dark 4.96:1
+ *   kangaroo  light 5.98:1   dark 5.68:1
+ *
+ * And the dark fills against every plausible dark ground — pure black,
+ * `CONTRAST_REFERENCE_KEYS.dark`, One Dark's `#282C34` — plus the cream page a mis-detected
+ * theme would put them on:
+ *
+ *   mate1     4.09 / 3.32 / 2.73   cream 4.81
+ *   mate2     3.83 / 3.10 / 2.55   cream 5.14
+ *   kangaroo  3.31 / 2.68 / 2.21   cream 5.94
+ *
+ * which is the same band the four Claude fills occupy, so a mate chip carries the same weight
+ * as the models beside it rather than reading as a second-class one.
+ *
+ * There is a FOURTH warm entry, `mates`, and it is not a slot: it is the family's own ink,
+ * worn by the one collapsed segment a workflow bar draws for all external work at once. Its
+ * own note below says why a slot's ink could not do that job.
+ */
+export const MODEL_BADGE = {
+	opus: {
+		/** label 4.88:1 on its bar */
+		light: { bg: "#D3E7EC", fg: "#0E5F73", bar: "#92CEDC", label: "#125463" },
+		/** label 4.93:1 on its bar */
+		dark: { bg: "#0E7C94", fg: "#F0FDFF", bar: "#48C8E0", label: "#044B58" },
+	},
+	sonnet: {
+		/** label 4.84:1 on its bar */
+		light: { bg: "#D6EEDD", fg: "#166534", bar: "#93D9B2", label: "#145D34" },
+		/** label 4.84:1 on its bar */
+		dark: { bg: "#12804F", fg: "#EFFFF6", bar: "#4FD98F", label: "#07572C" },
+	},
+	haiku: {
+		/** label 4.81:1 on its bar */
+		light: { bg: "#E6E6E0", fg: "#4B5563", bar: "#C9CCD2", label: "#4B5362" },
+		/** label 4.91:1 on its bar — the dark grey bar is the dimmest of the four, so
+		 *  its label is the closest to black of them. */
+		dark: { bg: "#697180", fg: "#F8FAFC", bar: "#8A92A2", label: "#21252E" },
+	},
+	fable: {
+		/** label 4.86:1 on its bar */
+		light: { bg: "#E9DCF5", fg: "#6B21A8", bar: "#C3A6EC", label: "#520FB0" },
+		/** label 4.81:1 on its bar */
+		dark: { bg: "#7B4CD6", fg: "#F6F0FF", bar: "#A87BE8", label: "#310570" },
+	},
+	/** Ochre. The first external slot, and the lightest step of the warm family.
+	 *  label 4.87:1 light / 4.81:1 dark, each on its own bar. */
+	mate1: {
+		light: { bg: "#F6E6C4", fg: "#7A5210", bar: "#E2C27A", label: "#654909" },
+		dark: { bg: "#926511", fg: "#FFF7E8", bar: "#D8A445", label: "#533807" },
+	},
+	/** Terracotta — the middle step, a clear ~17° of hue from either neighbour.
+	 *  label 4.80:1 light / 4.83:1 dark, each on its own bar. */
+	mate2: {
+		light: { bg: "#F7DDCB", fg: "#8A3E12", bar: "#EAB08A", label: "#793406" },
+		dark: { bg: "#A8501B", fg: "#FFF1E8", bar: "#E08A52", label: "#552404" },
+	},
+	/** Red earth. The third slot wears the reddest step, and it is still nowhere near
+	 *  `theme.colors.danger` — this is a desaturated earth tone, not a warning.
+	 *  label 4.86:1 light / 4.82:1 dark, each on its own bar. */
+	kangaroo: {
+		light: { bg: "#F6D6D0", fg: "#8E2F26", bar: "#E5A096", label: "#7B1C0E" },
+		dark: { bg: "#A83A2E", fg: "#FFEFEC", bar: "#E07A6C", label: "#571107" },
+	},
+	/**
+	 * THE FAMILY, not a fourth slot — the ink of the collapsed `mates` bar segment.
+	 *
+	 * A workflow bar draws every mate-routed agent as ONE run, because the question a bar
+	 * answers is "how much of this workflow leaves Claude Code" and that is one number. That
+	 * run cannot wear a slot's ink: painting a two-slot segment in `mate1`'s ochre says the
+	 * work went to `mate1`, and painting it in whichever slot contributes most makes the same
+	 * segment change colour when a count changes — the identical label in two hues down one
+	 * chart. So the family gets an ink of its own: honey amber, hue 35° light / 31° dark.
+	 *
+	 * It does NOT try to be a fourth distinguishable step, and it could not be. The warm band
+	 * is 0–50° and already holds three slots at ~17° spacing, so the widest gap left is about
+	 * 11° — under the separation the slots themselves needed. It does not have to be: the
+	 * family tone and the slot tones never appear in ONE graphic. The chart and the colour key
+	 * under it use only this; the tier table and the agent table use only the slots.
+	 *
+	 * MEASURED, same battery as the slots above:
+	 *   label on its own bar   light 4.97:1   dark 4.78:1
+	 *   fg on its own bg       light 5.87:1   dark 4.83:1
+	 *   dark bg vs grounds     4.03 (black) / 3.27 (#1C1C1E) / 2.69 (#282C34)   cream 4.88
+	 */
+	mates: {
+		light: { bg: "#F6E3C9", fg: "#80480F", bar: "#E5B77F", label: "#6B3D07" },
+		dark: { bg: "#9E5D16", fg: "#FFF5E8", bar: "#DB9A4C", label: "#553106" },
+	},
+	/** Not a model — the absence of a routing decision. Grey on both pages, so it never
+	 *  reads as another choice sitting beside the real ones. A mate is NOT this: a mate is
+	 *  a decision to route elsewhere, which is why it gets a colour and this does not.
+	 *
+	 *  Its label is a NEUTRAL grey at 4.82:1 light / 4.83:1 dark, and on the dark page it
+	 *  is the only label that is pale rather than deep — this is the one bar that is itself
+	 *  dark, so nothing darker could be read on it. */
+	inherit: {
+		light: { bg: "#EFEFE6", fg: "#8A8A80", bar: "#DEDED2", label: "#5E5E57" },
+		dark: { bg: "#4A4A54", fg: "#D0D2D8", bar: "#4E4E58", label: "#C6C6CA" },
+	},
+} as const;
+
+export type ModelBadgeKind = keyof typeof MODEL_BADGE;
+
+export interface ModelInk {
+	bg: string;
+	fg: string;
+	bar: string;
+	/** Ink for a word written ON `bar`. Never `fg` — see the note above `MODEL_BADGE`. */
+	label: string;
+}
+
+/**
+ * Chip and bar colours for one model, for the resolved mode.
+ *
+ * Total by construction: a name this build does not know gets `inherit`'s grey, which reads
+ * as "magus does not recognise this" rather than as a missing colour. A hand-edited
+ * config can name anything.
+ */
+export function modelBadge(kind: string): ModelInk {
+	const key = (kind in MODEL_BADGE ? kind : "inherit") as ModelBadgeKind;
+	return MODEL_BADGE[key][detected];
+}
+
+/**
+ * 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.
+ */
+export const TRACK_FILL = {
+	light: SCOPE_OFF_FILL.light,
+	dark: "#4A4A52",
+} as const;
+
+/** Fill for an unlit track segment, for the resolved mode. */
+export function trackFill(): string {
+	return TRACK_FILL[detected];
+}
+
+/**
+ * Effort's colour ramp — TEXT only, never a fill, so a row never paints two blocks.
+ *
+ * Effort is an ORDINAL, so these are a ramp rather than four unrelated hues. The ramp avoids
+ * green and red, which already mean "on" and "failed" elsewhere on the same screen: one
+ * colour, one meaning, app-wide. Dark runs brighter than light for the reason `MODEL_BADGE`
+ * gives — a dim colour on a dark page is a grey one.
+ */
+export const EFFORT_INK = {
+	low: { light: "#6B7280", dark: "#9AA0AC" },
+	medium: { light: "#0E7490", dark: "#6FD9F0" },
+	high: { light: "#B45309", dark: "#F2B25E" },
+	xhigh: { light: "#A21CAF", dark: "#E49BFF" },
+} as const;
+
+export type EffortInkKind = keyof typeof EFFORT_INK;
+
+/** Ink for one effort level, for the resolved mode. Unknown words take the lowest step. */
+export function effortInk(effort: string): string {
+	const key = (effort in EFFORT_INK ? effort : "low") as EffortInkKind;
+	return EFFORT_INK[key][detected];
+}
+
+/**
+ * The two reference pages, mirrored from `theme.ts`'s `CONTRAST_REFERENCE`.
+ *
+ * Duplicated deliberately: `theme.ts` imports opentui's RGBA, which drags the
+ * renderer into anything that touches it. This module is pure data by design so
+ * the colour tests can run without a terminal. A test asserts the two agree.
+ */
+export const CONTRAST_REFERENCE_KEYS = {
+	light: "#FAFAD2",
+	dark: "#1C1C1E",
+} as const;
+
+/** Chip colours for one component kind, for the resolved mode. */
+export function componentBadge(kind: ComponentBadgeKind): {
+	bg: string;
+	fg: string;
+} {
+	return COMPONENT_BADGE[kind][detected];
+}

package/src/ui/theme-resolve.ts

@@ -0,0 +1,147 @@
+import type { ThemeMode } from "@opentui/core";
+
+/**
+ * Terminal theme resolution — the one order magus follows, decided once at
+ * process start, first answer wins:
+ *
+ *   1. `--theme` flag
+ *   2. `MAGUS_THEME`
+ *   3. `TERM_THEME`
+ *   4. OSC 10/11 probe (bounded, interactive tty only)
+ *   5. `COLORFGBG`
+ *   6. dark
+ *
+ * A step with no answer says nothing and the next one runs; nothing before
+ * step 6 ever asserts dark. Every theme word is compared exactly — the byte
+ * strings `light` and `dark`, lowercase, untrimmed — because the same test has
+ * to run in a POSIX `case` and a tmux format, and only the exact comparison is
+ * free in all three.
+ *
+ * This module is pure by design: no `process` access except as a *default
+ * argument* to `snapshotThemeEnv`, no I/O, no renderer. Everything it needs is
+ * passed in, so the whole contract runs in a test without a terminal.
+ */
+
+export type ThemeSource =
+	| "flag"
+	| "variable"
+	| "TERM_THEME"
+	| "osc11"
+	| "COLORFGBG"
+	| "default";
+
+export interface ThemeResolution {
+	/** Never null — when nothing answered, it is dark by decision. */
+	mode: ThemeMode;
+	source: ThemeSource;
+}
+
+/** The three variables the resolver reads, captured BEFORE .env is merged. */
+export interface ThemeEnv {
+	TERM_THEME?: string;
+	MAGUS_THEME?: string;
+	COLORFGBG?: string;
+}
+
+export interface ResolveThemeInput {
+	/** Already validated by the router: only "light" | "dark" | undefined arrive here. */
+	flag?: ThemeMode;
+	env: ThemeEnv;
+	/** stdin AND stdout are TTYs. Decided by the caller; the resolver never touches process. */
+	isInteractive: boolean;
+	/** Bounded OSC 10/11 probe. Called at most once, and only when step 4 is reached. */
+	probe: () => Promise<ThemeMode | null>;
+}
+
+/** Exact match on "light" | "dark"; everything else is no opinion. */
+export function parseThemeWord(value: string | undefined): ThemeMode | null {
+	if (value === "light") return "light";
+	if (value === "dark") return "dark";
+	return null;
+}
+
+/** The literal background fields that answer — the same set as the statusline's `case`. */
+const LIGHT_BACKGROUNDS: ReadonlySet<string> = new Set(["7", "15"]);
+const DARK_BACKGROUNDS: ReadonlySet<string> = new Set([
+	"0",
+	"1",
+	"2",
+	"3",
+	"4",
+	"5",
+	"6",
+	"8",
+	"9",
+	"10",
+	"11",
+	"12",
+	"13",
+	"14",
+]);
+
+/**
+ * Last ";"-field is the background: 7|15 → light, 0-6|8-14 → dark, else null.
+ *
+ * Exact string membership, not numeric parsing: the statusline's
+ * `parse_colorfgbg` is a POSIX `case` over the literal words, so `07`, `015`
+ * and `00` are no opinion there, and that literal set is the contract the two
+ * tools share. `Number("07")` would make magus say light where the
+ * statusline says nothing.
+ *
+ * A value without a `;` is not `<fg>;<bg>` at all — a lone `7` is no opinion,
+ * matching the statusline's `case "$1" in *\;*)` guard so the two tools agree.
+ */
+export function parseColorFgBg(value: string | undefined): ThemeMode | null {
+	if (value === undefined || !value.includes(";")) return null;
+	const bg = value.slice(value.lastIndexOf(";") + 1);
+	if (LIGHT_BACKGROUNDS.has(bg)) return "light";
+	if (DARK_BACKGROUNDS.has(bg)) return "dark";
+	return null;
+}
+
+/**
+ * Copy the three variables out of `env` — call this before loadProjectDotenv.
+ *
+ * Copies, never references: the returned object must not observe later writes
+ * to `process.env`, which is exactly what a merged `.env` would be.
+ */
+export function snapshotThemeEnv(
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): ThemeEnv {
+	const snapshot: ThemeEnv = {};
+	if (env.TERM_THEME !== undefined) snapshot.TERM_THEME = env.TERM_THEME;
+	if (env.MAGUS_THEME !== undefined) snapshot.MAGUS_THEME = env.MAGUS_THEME;
+	if (env.COLORFGBG !== undefined) snapshot.COLORFGBG = env.COLORFGBG;
+	return snapshot;
+}
+
+export async function resolveTheme(
+	input: ResolveThemeInput,
+): Promise<ThemeResolution> {
+	if (input.flag !== undefined) {
+		return { mode: input.flag, source: "flag" };
+	}
+
+	const variable = parseThemeWord(input.env.MAGUS_THEME);
+	if (variable !== null) return { mode: variable, source: "variable" };
+
+	const termTheme = parseThemeWord(input.env.TERM_THEME);
+	if (termTheme !== null) return { mode: termTheme, source: "TERM_THEME" };
+
+	// Steps 1-3 answered nothing, so this is the only path that probes. Not
+	// reaching here is what keeps first paint undelayed when a word answered.
+	if (input.isInteractive) {
+		let probed: ThemeMode | null = null;
+		try {
+			probed = await input.probe();
+		} catch {
+			probed = null;
+		}
+		if (probed !== null) return { mode: probed, source: "osc11" };
+	}
+
+	const colorFgBg = parseColorFgBg(input.env.COLORFGBG);
+	if (colorFgBg !== null) return { mode: colorFgBg, source: "COLORFGBG" };
+
+	return { mode: "dark", source: "default" };
+}

package/src/ui/theme.ts

@@ -0,0 +1,175 @@
+import { RGBA } from "@opentui/core";
+
+/**
+ * magus's palette: our own vivid accents, on the terminal's own canvas.
+ *
+ * Three rules, and the reason for each:
+ *
+ *  1. **Backgrounds are never ours.** Surfaces and modals use the terminal's
+ *     background. Painting an absolute fill boxes the UI into whichever theme we
+ *     guessed, and it was the original sin here — modals hardcoded #1C1C1E.
+ *  2. **Body text is never ours.** Normal text uses the terminal's foreground,
+ *     which is the only colour guaranteed to clear a text-grade contrast ratio
+ *     against that terminal's own background. `text` used to be the string
+ *     `"white"` — OpenTUI resolves that to rgb(255,255,255), not to "the
+ *     terminal's white" — so on a light theme every installed plugin was drawn
+ *     white-on-cream and vanished while the *un*installed ones, in grey, stayed
+ *     readable. The list read exactly backwards.
+ *  3. **Accents ARE ours, and vivid.** Deferring accents to ANSI slots 0-15 made
+ *     everything legible but flattened it: a theme that renders slots 2 and 3 as
+ *     neighbouring olives leaves user/project/local scope squares indistinguishable,
+ *     and slot 8 chips melt into the page. Distinction is a product decision, so
+ *     these are chosen, not inherited.
+ *
+ * ## How the accents were chosen
+ *
+ * By measurement, not taste. A single colour CANNOT reach 4.5:1 against both a
+ * light and a dark terminal — clearing 4.5:1 on cream needs relative luminance
+ * <= ~0.17, clearing it on near-black needs >= ~0.22, and those do not overlap.
+ * So the bar is 3:1, WCAG's threshold for UI components and large text, which
+ * admits a band of mid-dark saturated colours. Every accent below clears 3:1
+ * against BOTH reference backgrounds, verified in theme-adaptive-colors.test.ts —
+ * so a colour that only works on dark cannot be added without failing the build.
+ *
+ * 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.
+ */
+
+/** Reference backgrounds every accent is measured against. */
+export const CONTRAST_REFERENCE = {
+	light: "#FAFAD2",
+	dark: "#1C1C1E",
+} 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.
+ */
+export const brand = {
+	accent: "#9333EA", // 5.04 / 3.16 — brand purple
+	link: "#2563EB", // 4.84 / 3.29
+	info: "#0E7490", // 5.02 / 3.18 — teal
+	success: "#15803D", // 4.70 / 3.39
+	warning: "#B45309", // 4.70 / 3.39 — amber
+	danger: "#DC2626", // 4.52 / 3.52
+	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",
+	/**
+	 * De-emphasised ink on the SELECTION fill, and nowhere else.
+	 *
+	 * Measured on a screenshot: `muted` (#6B7280) on the selection purple is
+	 * 1.11:1, `warning` 1.07:1, `danger` 1.11:1 — every meta tone was invisible
+	 * the moment its row was selected, and `(default)` on the Models screen
+	 * disappeared entirely. The page-level greys cannot help here: they are
+	 * chosen to sit between a cream and a near-black terminal, and the selection
+	 * is neither.
+	 *
+	 * 3.64:1 on the selection fill, and 1.48:1 against `ink` — far enough from
+	 * white to still read as secondary. Like `ink`, it is measured against a fill
+	 * WE paint rather than against the terminal, so it is exempt from the
+	 * both-backgrounds rule the accents above obey.
+	 */
+	selectionDim: "#D4D4D8",
+} as const;
+
+/** Any colour a component may hand to a JSX colour prop. */
+export type UiColor = string | RGBA;
+
+/** The terminal's own foreground — the only honest "normal text" colour. */
+const fg = () => RGBA.defaultForeground();
+
+/** The terminal's own background — for surfaces, never for ink. */
+const bg = () => RGBA.defaultBackground();
+
+export const theme = {
+	colors: {
+		/** Adaptive by rule 2 — never make this one of ours. */
+		text: fg(),
+		muted: brand.muted,
+		/** 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. */
+		byline: brand.accent,
+		success: brand.success,
+		warning: brand.warning,
+		danger: brand.danger,
+		info: brand.info,
+	},
+
+	/**
+	 * The selected row owns the colour channel.
+	 *
+	 * A row's normal palette is chosen against the TERMINAL's background; on the
+	 * selection fill none of it clears even 1.2:1. So a selected row has exactly
+	 * two inks — `fg` for what it is saying, `dim` for what it is saying quietly —
+	 * and any tone a row would otherwise carry is surrendered while it is
+	 * selected. The words survive; the hue does not, and cannot.
+	 */
+	selection: {
+		bg: brand.accent,
+		fg: brand.ink,
+		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 },
+	},
+
+	meta: {
+		muted: brand.muted,
+		warning: brand.warning,
+		success: brand.success,
+		danger: brand.danger,
+	},
+
+	/**
+	 * Footer key chips. A vivid block with white ink, because the point of a chip
+	 * is to read as a pressable key at a glance — the previous neutral-grey chip
+	 * melted into a light page. Dark slates were measured and rejected: they clear
+	 * 3:1 on cream but drop to ~2.2 on a dark terminal, i.e. an invisible block.
+	 */
+	hints: {
+		defaultBg: brand.accent,
+		primaryBg: brand.info,
+		dangerBg: brand.danger,
+		fg: brand.ink,
+	},
+
+	/** Panels and modals sit on the terminal's own background and are separated by
+	 *  their border, never by an absolute fill that fights the user's theme. */
+	surface: {
+		bg: bg(),
+		border: brand.muted,
+	},
+
+	spacing: {
+		rowIndent: 1,
+		sectionGap: 1,
+		panelPadding: 1,
+	},
+} as const;
+
+export { fg as defaultFg, bg as defaultBg };