magus-cli 0.0.0-placeholder → 7.0.0

package/src/__tests__/tabbar-layout.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { TABS, barWidth, layoutTabs } from "../ui/components/TabBar.js";
+
+const FULL = TABS.map((t) => `${t.key}:${t.label}`);
+const FULL_WIDTH = barWidth(FULL);
+
+/** The widest the compacted bar ever gets — whichever active label is longest. */
+const WIDEST_COMPACT = Math.max(
+	...TABS.map((tab) => barWidth(layoutTabs(TABS, tab.screen, 0))),
+);
+
+describe("tab bar layout", () => {
+	test("shows every label when the bar fits", () => {
+		expect(layoutTabs(TABS, "plugins", FULL_WIDTH)).toEqual(FULL);
+	});
+
+	test("drops inactive labels when the bar does not fit", () => {
+		// A 94-column pane leaves ~90 usable, and ten full tabs need ~110 — the
+		// width at which OpenTUI clipped each cell into a meaningless stub.
+		const texts = layoutTabs(TABS, "styles", 90);
+		expect(texts).toContain("9:Styles");
+		expect(texts).toContain("1");
+		expect(texts).not.toContain("1:Plugins");
+	});
+
+	test("the compact bar actually fits a narrow pane", () => {
+		// The point of compacting is that the result fits. If it did not, the
+		// fallback would just be a differently-truncated mess.
+		expect(barWidth(layoutTabs(TABS, "styles", 90))).toBeLessThanOrEqual(90);
+	});
+
+	test("the full bar no longer fits a standard window, so compacting is the norm", () => {
+		// The tenth tab pushed the full bar past 100 columns. That is not a
+		// regression — it is why the compact form has to stay readable, and why
+		// the test below measures it rather than assuming.
+		expect(FULL_WIDTH).toBeGreaterThan(100);
+		expect(layoutTabs(TABS, "models", 100)).not.toEqual(FULL);
+	});
+
+	test("the compact bar fits an 80-column terminal, on every tab", () => {
+		// The real question a tenth tab raises. ScreenLayout pads the bar by 1
+		// each side inside a container padded by 1, so an 80-column terminal
+		// leaves 76 — and the widest compact bar is well under it.
+		expect(WIDEST_COMPACT).toBeLessThanOrEqual(76);
+		for (const tab of TABS) {
+			expect(barWidth(layoutTabs(TABS, tab.screen, 76))).toBeLessThanOrEqual(
+				76,
+			);
+		}
+	});
+
+	test("keeps the label of whichever tab is active", () => {
+		for (const tab of TABS) {
+			const texts = layoutTabs(TABS, tab.screen, 40);
+			expect(texts).toContain(`${tab.key}:${tab.label}`);
+			// Exactly one tab keeps its label.
+			expect(texts.filter((t) => t.includes(":"))).toHaveLength(1);
+		}
+	});
+
+	test("compacting never changes how many tabs are drawn", () => {
+		expect(layoutTabs(TABS, "plugins", 20)).toHaveLength(TABS.length);
+		expect(layoutTabs(TABS, "plugins", 10_000)).toHaveLength(TABS.length);
+	});
+
+	test("barWidth counts padding and separators", () => {
+		// " a " + "│" + " bb " = 3 + 1 + 4
+		expect(barWidth(["a", "bb"])).toBe(8);
+		expect(barWidth([])).toBe(0);
+	});
+
+	test("every tab key is a digit the global handler binds", () => {
+		// The compact bar shows only the number, so the number must be the key
+		// that actually navigates. Models is keyed "0" and sits last, because the
+		// number row reads 1…9 then 0 — the order here and the order under the
+		// fingers have to agree.
+		expect(TABS.map((t) => t.key)).toEqual([
+			"1",
+			"2",
+			"3",
+			"4",
+			"5",
+			"6",
+			"7",
+			"8",
+			"9",
+			"0",
+		]);
+		expect(TABS.at(-1)).toEqual({
+			key: "0",
+			label: "Models",
+			screen: "models",
+		});
+	});
+
+	test("no two tabs share a key or a screen", () => {
+		expect(new Set(TABS.map((t) => t.key)).size).toBe(TABS.length);
+		expect(new Set(TABS.map((t) => t.screen)).size).toBe(TABS.length);
+	});
+});

package/src/__tests__/terminology-filler.test.ts

@@ -0,0 +1,214 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import { splitFrontmatter } from "../services/styles-manager.js";
+import {
+	buildPrompt,
+	fillTemplate,
+	fillTerminology,
+	parseTerminologyRows,
+	terminologyStyleFile,
+} from "../services/terminology-filler.js";
+
+/** The shape the shipped template actually has. */
+const TEMPLATE = [
+	"### Terminology",
+	"",
+	"One concept, one name, everywhere.",
+	"",
+	"| Use | Not | Because |",
+	"|---|---|---|",
+	"| <!-- filled during apply --> | | |",
+	"",
+	"Rules that hold regardless of the table above:",
+	"",
+	"- Use the domain's word, not the implementation's.",
+].join("\n");
+
+describe("parseTerminologyRows", () => {
+	test("reads well-formed rows", () => {
+		expect(
+			parseTerminologyRows(
+				"| booking | reservation | the domain says booking\n",
+			),
+		).toEqual([
+			{
+				use: "booking",
+				not: "reservation",
+				because: "the domain says booking",
+			},
+		]);
+	});
+
+	test("ignores commentary around the table", () => {
+		// `claude -p` often frames its answer, however firmly it is told not to.
+		const out = [
+			"Here are the rows I found:",
+			"",
+			"| booking | reservation | the domain says booking |",
+			"| tenant | account | billing is per tenant |",
+			"",
+			"Let me know if you want more.",
+		].join("\n");
+		expect(parseTerminologyRows(out)).toHaveLength(2);
+	});
+
+	test("drops a header row and separator the model added anyway", () => {
+		const out = [
+			"| Use | Not | Because |",
+			"|---|---|---|",
+			"| booking | reservation | the domain says booking |",
+		].join("\n");
+		expect(parseTerminologyRows(out)).toEqual([
+			{
+				use: "booking",
+				not: "reservation",
+				because: "the domain says booking",
+			},
+		]);
+	});
+
+	test("drops an aligned separator too", () => {
+		expect(parseTerminologyRows("|:---|:---:|---:|\n| a | b | c |")).toEqual([
+			{ use: "a", not: "b", because: "c" },
+		]);
+	});
+
+	test("skips rows with the wrong number of cells", () => {
+		expect(parseTerminologyRows("| only | two |")).toEqual([]);
+		expect(parseTerminologyRows("| a | b | c | d |")).toEqual([]);
+	});
+
+	test("skips rows missing the two cells that carry meaning", () => {
+		expect(parseTerminologyRows("|  |  | because |")).toEqual([]);
+		expect(parseTerminologyRows("| use |  | because |")).toEqual([]);
+	});
+
+	test("returns nothing for output with no table at all", () => {
+		expect(parseTerminologyRows("I could not find any terminology.")).toEqual(
+			[],
+		);
+	});
+});
+
+describe("fillTemplate", () => {
+	test("replaces the placeholder row", () => {
+		const filled = fillTemplate(TEMPLATE, [
+			{ use: "booking", not: "reservation", because: "the domain says so" },
+		]);
+		expect(filled).not.toContain("filled during");
+		expect(filled).toContain("| booking | reservation | the domain says so |");
+	});
+
+	test("keeps the rules below the table verbatim", () => {
+		// These are substantive guidance. Losing them would leave a style that
+		// looks filled in and says almost nothing.
+		const filled = fillTemplate(TEMPLATE, [
+			{ use: "a", not: "b", because: "c" },
+		]);
+		expect(filled).toContain("Rules that hold regardless of the table above:");
+		expect(filled).toContain(
+			"- Use the domain's word, not the implementation's.",
+		);
+		expect(filled).toContain("### Terminology");
+	});
+
+	test("still places rows if the placeholder is gone", () => {
+		// Guards against the upstream template changing shape and this silently
+		// producing an empty table.
+		const noPlaceholder = TEMPLATE.replace(
+			"| <!-- filled during apply --> | | |\n",
+			"",
+		);
+		const filled = fillTemplate(noPlaceholder, [
+			{ use: "a", not: "b", because: "c" },
+		]);
+		expect(filled).toContain("| a | b | c |");
+	});
+
+	test("refuses to produce a table with no rows", () => {
+		expect(() => fillTemplate(TEMPLATE, [])).toThrow(/No usable table rows/);
+	});
+});
+
+describe("terminologyStyleFile", () => {
+	test("keeps coding instructions on", () => {
+		const { frontmatter } = splitFrontmatter(terminologyStyleFile("### x"));
+		expect(frontmatter["keep-coding-instructions"]).toBe("true");
+		expect(frontmatter.name).toBe("terminology");
+	});
+});
+
+describe("buildPrompt", () => {
+	test("asks for rows only and includes the template for context", () => {
+		const prompt = buildPrompt(TEMPLATE);
+		expect(prompt).toContain("ONLY markdown table rows");
+		expect(prompt).toContain("No header row");
+		expect(prompt).toContain("### Terminology");
+	});
+});
+
+describe("fillTerminology", () => {
+	let dir: string;
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "magus-terminology-"));
+	});
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	test("writes the filled style into the project so it commits with the repo", async () => {
+		const result = await fillTerminology({
+			projectPath: dir,
+			templateBody: TEMPLATE,
+			run: async () =>
+				"| booking | reservation | the domain says booking |\n| tenant | account | billing is per tenant |",
+		});
+
+		expect(result.rows).toHaveLength(2);
+		expect(result.path).toBe(
+			join(dir, ".claude", "output-styles", "terminology.md"),
+		);
+
+		const written = await fs.readFile(result.path, "utf8");
+		const { frontmatter, body } = splitFrontmatter(written);
+		expect(frontmatter.name).toBe("terminology");
+		expect(frontmatter["keep-coding-instructions"]).toBe("true");
+		expect(body).toContain("| booking | reservation |");
+		expect(body).toContain("Rules that hold regardless of the table above:");
+	});
+
+	test("writes nothing when the model returns no usable rows", async () => {
+		await expect(
+			fillTerminology({
+				projectPath: dir,
+				templateBody: TEMPLATE,
+				run: async () => "I could not determine any terminology.",
+			}),
+		).rejects.toThrow(/no usable table rows/i);
+
+		// A half-written or empty style file is worse than none: it would show up
+		// under Team looking finished.
+		expect(await fs.pathExists(join(dir, ".claude", "output-styles"))).toBe(
+			false,
+		);
+	});
+
+	test("propagates a failure from the subprocess without writing", async () => {
+		await expect(
+			fillTerminology({
+				projectPath: dir,
+				templateBody: TEMPLATE,
+				run: async () => {
+					throw new Error("claude exited 1");
+				},
+			}),
+		).rejects.toThrow(/claude exited 1/);
+		expect(await fs.pathExists(join(dir, ".claude", "output-styles"))).toBe(
+			false,
+		);
+	});
+});

package/src/__tests__/theme-adaptive-colors.test.ts

@@ -0,0 +1,354 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { RGBA } from "@opentui/core";
+import fs from "fs-extra";
+import { CONTRAST_REFERENCE, brand, theme } from "../ui/theme.js";
+
+/**
+ * magus uses its own vivid accents on the terminal's own canvas.
+ *
+ * The bug this file exists for: `theme.colors.text` was the string `"white"`,
+ * which OpenTUI resolves to rgb(255,255,255) — not "the terminal's white". On a
+ * light theme every installed plugin was drawn white-on-cream and vanished,
+ * while the *un*installed ones, drawn in grey, stayed readable. The list read
+ * exactly backwards.
+ *
+ * The first fix pushed everything onto ANSI slots 0-15. That made it legible and
+ * flattened it: a theme rendering slots 2 and 3 as neighbouring olives leaves the
+ * scope squares indistinguishable, and slot-8 chips melt into a light page. So
+ * accents are now chosen by us — which means WE are responsible for their
+ * contrast, and these tests are how that responsibility is discharged.
+ *
+ * Invariants:
+ *  1. Backgrounds and body text stay the terminal's (it is the only colour that
+ *     can clear a text-grade ratio against that terminal's own background).
+ *  2. Every accent clears 3:1 against BOTH reference backgrounds.
+ *  3. Ink on our own badges clears 4.5:1 against that badge.
+ *  4. The three scope colours are far enough apart in hue to read as squares.
+ *  5. No component invents a colour outside the palette.
+ */
+
+// ─── Contrast maths (WCAG 2.1 relative luminance) ─────────────────────────────
+
+function relativeLuminance(hex: string): number {
+	const n = hex.replace("#", "");
+	const channels = [0, 2, 4].map(
+		(i) => Number.parseInt(n.slice(i, i + 2), 16) / 255,
+	);
+	const linear = channels.map((c) =>
+		c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4,
+	);
+	return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+}
+
+function contrastRatio(a: string, b: string): number {
+	const [hi, lo] = [relativeLuminance(a), relativeLuminance(b)].sort(
+		(x, y) => y - x,
+	);
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Perceptual distance (CIE76 ΔE) in L*a*b*.
+ *
+ * Contrast ratio is the wrong tool for "are these two swatches telling apart":
+ * it only compares luminance, and the scope colours are deliberately close in
+ * luminance — that is precisely what lets each of them clear 3:1 against both a
+ * light and a dark background. Measured, they sit at ratios of 1.00-1.03 to each
+ * other while being obviously different colours. ΔE sees the hue difference that
+ * a luminance ratio is blind to.
+ */
+function deltaE(aHex: string, bHex: string): number {
+	const toLab = (hex: string): [number, number, number] => {
+		const n = hex.replace("#", "");
+		const [r, g, b] = [0, 2, 4].map((i) => {
+			const c = Number.parseInt(n.slice(i, i + 2), 16) / 255;
+			return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+		});
+		// sRGB -> XYZ (D65), then XYZ -> Lab
+		const x = (r * 0.4124 + g * 0.3576 + b * 0.1805) / 0.95047;
+		const y = r * 0.2126 + g * 0.7152 + b * 0.0722;
+		const z = (r * 0.0193 + g * 0.1192 + b * 0.9505) / 1.08883;
+		const f = (t: number) =>
+			t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
+		const [fx, fy, fz] = [f(x), f(y), f(z)];
+		return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+	};
+	const [l1, a1, b1] = toLab(aHex);
+	const [l2, a2, b2] = toLab(bHex);
+	return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+
+/** WCAG threshold for UI components and large text. 4.5 is unreachable against
+ *  both a light and a dark background at once — the luminance bands do not overlap. */
+const UI_CONTRAST = 3;
+const INK_CONTRAST = 4.5;
+
+describe("contrast maths", () => {
+	// Guard the ruler before measuring with it: a broken luminance function would
+	// make every assertion below meaningless in whichever direction it was broken.
+	test("known reference ratios are correct", () => {
+		expect(contrastRatio("#FFFFFF", "#000000")).toBeCloseTo(21, 1);
+		expect(contrastRatio("#000000", "#FFFFFF")).toBeCloseTo(21, 1);
+		expect(contrastRatio("#777777", "#777777")).toBeCloseTo(1, 5);
+	});
+});
+
+// ─── The palette ──────────────────────────────────────────────────────────────
+
+/**
+ * Inks we paint on a fill WE own, so they are measured against that fill and
+ * not against the terminal. They cannot satisfy the both-backgrounds rule and
+ * are not supposed to: `selectionDim` is a light grey chosen for the selection
+ * purple, which on a cream terminal would be invisible — and is never drawn
+ * there.
+ */
+const OWN_FILL_INKS = new Set(["ink", "selectionDim"]);
+
+const ACCENTS = Object.entries(brand).filter(
+	([name]) => !OWN_FILL_INKS.has(name),
+);
+
+describe("accents are legible on light AND dark terminals", () => {
+	test("the palette is non-empty (guards the loops below)", () => {
+		expect(ACCENTS.length).toBeGreaterThanOrEqual(6);
+	});
+
+	for (const [name, hex] of ACCENTS) {
+		test(`${name} clears ${UI_CONTRAST}:1 on both backgrounds`, () => {
+			const onLight = contrastRatio(hex, CONTRAST_REFERENCE.light);
+			const onDark = contrastRatio(hex, CONTRAST_REFERENCE.dark);
+			// Reported together so a failure names the side that broke.
+			expect({
+				name,
+				onLight: onLight >= UI_CONTRAST,
+				onDark: onDark >= UI_CONTRAST,
+			}).toEqual({ name, onLight: true, onDark: true });
+		});
+	}
+
+	test("badge ink clears 4.5:1 on every badge colour we paint", () => {
+		const failures: string[] = [];
+		for (const [tone, colors] of Object.entries(theme.category)) {
+			const r = contrastRatio(brand.ink, colors.bg as string);
+			if (r < INK_CONTRAST) failures.push(`category.${tone} ${r.toFixed(2)}`);
+		}
+		for (const key of ["defaultBg", "primaryBg", "dangerBg"] as const) {
+			const r = contrastRatio(brand.ink, theme.hints[key]);
+			if (r < INK_CONTRAST) failures.push(`hints.${key} ${r.toFixed(2)}`);
+		}
+		const sel = contrastRatio(theme.selection.fg, theme.selection.bg);
+		if (sel < INK_CONTRAST) failures.push(`selection ${sel.toFixed(2)}`);
+		expect(failures).toEqual([]);
+	});
+
+	test("a SELECTED row has two legible inks, and the page palette is not among them", () => {
+		// Found on a screenshot: `(default)` was drawn in `theme.colors.muted` on
+		// the selection purple and simply was not there. Every page-level tone
+		// fails the same way — they are chosen against the terminal's background,
+		// and the selection fill is neither of the two references.
+		const bg = theme.selection.bg;
+		expect(contrastRatio(theme.selection.fg, bg)).toBeGreaterThanOrEqual(
+			INK_CONTRAST,
+		);
+		expect(contrastRatio(theme.selection.dim, bg)).toBeGreaterThanOrEqual(
+			UI_CONTRAST,
+		);
+
+		// And it must READ as secondary next to the primary ink, or the
+		// distinction it exists to make is not visible.
+		expect(
+			contrastRatio(theme.selection.dim, theme.selection.fg),
+		).toBeGreaterThan(1.2);
+		expect(contrastRatio(theme.selection.dim, bg)).toBeLessThan(
+			contrastRatio(theme.selection.fg, bg),
+		);
+	});
+
+	test("the meta tones are exactly why a selected row cannot use them", () => {
+		// The negative half of the rule above, kept measurable: if a future
+		// palette change made one of these legible on the selection, the
+		// selection-aware branch in MetaText would still be right, but this test
+		// would tell us the reasoning had changed.
+		const unreadable = Object.entries(theme.meta).filter(
+			([, hex]) => contrastRatio(hex, theme.selection.bg) < UI_CONTRAST,
+		);
+		expect(unreadable.map(([name]) => name).sort()).toEqual(
+			Object.keys(theme.meta).sort(),
+		);
+	});
+
+	test("the three scope colours are perceptually far apart", () => {
+		// They render as single-character squares, where a subtle shift is not
+		// readable at all. Deferring to ANSI put project and local on slots 2 and 3,
+		// which one real theme drew as two near-identical olives — the reason this
+		// rule exists. ΔE > 25 is comfortably past "different colour" (~2.3 is the
+		// just-noticeable difference); the bar is set high because these are tiny.
+		const scopes = Object.entries(theme.scopes) as [string, string][];
+		const tooClose: string[] = [];
+		for (let i = 0; i < scopes.length; i++) {
+			for (let j = i + 1; j < scopes.length; j++) {
+				const d = deltaE(scopes[i][1], scopes[j][1]);
+				if (d < 25)
+					tooClose.push(`${scopes[i][0]}~${scopes[j][0]} ΔE=${d.toFixed(1)}`);
+			}
+		}
+		expect(tooClose).toEqual([]);
+		expect(new Set(scopes.map(([, hex]) => hex)).size).toBe(scopes.length);
+	});
+
+	test("ΔE agrees that identical colours are identical (guards the metric)", () => {
+		expect(deltaE(brand.success, brand.success)).toBeCloseTo(0, 5);
+		expect(deltaE("#000000", "#FFFFFF")).toBeGreaterThan(90);
+	});
+});
+
+describe("the canvas stays the terminal's", () => {
+	test("normal text is the terminal's own foreground", () => {
+		// The original regression: this was `"white"`.
+		expect(theme.colors.text).toBeInstanceOf(RGBA);
+		expect((theme.colors.text as RGBA).intent).toBe("default");
+	});
+
+	test("surfaces use the terminal background, never an absolute fill", () => {
+		expect(theme.surface.bg).toBeInstanceOf(RGBA);
+		expect((theme.surface.bg as RGBA).intent).toBe("default");
+	});
+});
+
+// ─── Source guard ─────────────────────────────────────────────────────────────
+
+const UI_DIR = path.join(import.meta.dir, "..", "ui");
+/** The palette layer. Colour literals are these files' whole job. */
+const PALETTE_FILES = new Set([
+	path.join(UI_DIR, "theme.ts"),
+	path.join(UI_DIR, "theme-mode.ts"),
+]);
+
+async function uiSourceFiles(dir: string): Promise<string[]> {
+	const out: string[] = [];
+	for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...(await uiSourceFiles(full)));
+		else if (/\.tsx?$/.test(entry.name) && !PALETTE_FILES.has(full))
+			out.push(full);
+	}
+	return out;
+}
+
+const CSS_NAMES =
+	"white|black|gray|grey|red|green|yellow|blue|cyan|magenta|orange|purple";
+
+/** A line that is purely a comment. Prose describing a colour is not a defect. */
+function isComment(line: string): boolean {
+	const t = line.trim();
+	return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+}
+
+describe("components draw only from the palette", () => {
+	test("no colour literal outside theme.ts", async () => {
+		const files = await uiSourceFiles(UI_DIR);
+		expect(files.length).toBeGreaterThan(10); // guard: the walk found real files
+
+		const offenders: string[] = [];
+		for (const file of files) {
+			const text = await fs.readFile(file, "utf8");
+			text.split("\n").forEach((line, i) => {
+				if (isComment(line)) return;
+				const hex = /#[0-9a-fA-F]{6}\b/.test(line);
+				const named = new RegExp(
+					`\\b(fg|bg|backgroundColor|borderColor|titleColor|textColor|color)\\s*[=:]\\s*"(${CSS_NAMES})"`,
+				).test(line);
+				if (hex || named) {
+					offenders.push(
+						`${path.relative(UI_DIR, file)}:${i + 1}  ${line.trim()}`,
+					);
+				}
+			});
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	test("no <text> element renders without naming a colour", async () => {
+		// OpenTUI's fallback for an unstyled cell is truecolor white, NOT the
+		// terminal's foreground. Measured on the real TUI: after the palette was
+		// first fixed, `tmux capture-pane -e` still showed 139 truecolor-white runs,
+		// and the one carrying a visible glyph was a bare `<text>Plugins: 17</text>`.
+		// A correct palette cannot save an element that never asks for a colour.
+		const files = await uiSourceFiles(UI_DIR);
+		const offenders: string[] = [];
+		for (const file of files) {
+			const text = await fs.readFile(file, "utf8");
+			text.split("\n").forEach((line, i) => {
+				if (isComment(line)) return;
+				if (/<text>/.test(line)) {
+					offenders.push(
+						`${path.relative(UI_DIR, file)}:${i + 1}  ${line.trim()}`,
+					);
+				}
+			});
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	test("no element falls back to `undefined` for a colour", async () => {
+		// `fg={selected ? x : undefined}` reads as "leave it alone", but OpenTUI's
+		// fallback for an unstyled cell is truecolor white — so every unselected
+		// SelectableRow rendered white-on-cream and vanished on a light theme. Same
+		// root cause as the original bug, reached by omission rather than by a wrong
+		// literal, which is why the `<text>` guard alone did not catch it.
+		const files = await uiSourceFiles(UI_DIR);
+		const offenders: string[] = [];
+		for (const file of files) {
+			const text = await fs.readFile(file, "utf8");
+			text.split("\n").forEach((line, i) => {
+				if (isComment(line)) return;
+				if (/\bfg=\{[^}]*\bundefined\b/.test(line)) {
+					offenders.push(
+						`${path.relative(UI_DIR, file)}:${i + 1}  ${line.trim()}`,
+					);
+				}
+			});
+		}
+		// `bg` legitimately falls back to the terminal page — that is how a row sits
+		// on the terminal's own background — so only `fg` is checked. The pattern is
+		// anchored to fg itself: filtering whole lines flagged
+		// `fg={x} bg={cond ? y : undefined}`, which is correct code.
+		expect(offenders).toEqual([]);
+	});
+
+	test("a background we paint never carries the terminal's ink", async () => {
+		// `theme.colors.text` is the TERMINAL's foreground. It is the right choice on
+		// the terminal's own page and the wrong one on a block we painted: on a light
+		// theme it is dark, so `bg={accent} fg={colors.text}` renders dark-on-purple.
+		// Reported from the real UI as the top tab bar showing "black on purple".
+		// It was not one tab — 16 sites shared it, across tabs, badges and chips.
+		//
+		// The rule: if we own the background, we own the ink (theme.hints.fg).
+		const files = await uiSourceFiles(UI_DIR);
+		const offenders: string[] = [];
+		for (const file of files) {
+			const text = await fs.readFile(file, "utf8");
+			text.split("\n").forEach((line, i) => {
+				if (isComment(line)) return;
+				if (/\bbg=\{[^}]+\}\s+fg=\{theme\.colors\.text\}/.test(line)) {
+					offenders.push(
+						`${path.relative(UI_DIR, file)}:${i + 1}  ${line.trim()}`,
+					);
+				}
+			});
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	test("the comment filter does not swallow a real offender", () => {
+		// The guards skip comment lines, because a doc comment that merely mentions
+		// `<text>` or a hex value is not a defect — one legitimately did, and failed
+		// the build. A filter that silently hid real code would be worse than the
+		// false positive it replaced, so pin both directions.
+		expect(isComment("  // <text>foo</text>")).toBe(true);
+		expect(isComment('   * fg="white" in a docblock')).toBe(true);
+		expect(isComment("  <text>real</text>")).toBe(false);
+		expect(isComment('  <span fg="white">real</span>')).toBe(false);
+	});
+});