claudeup 4.35.1 → 4.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.35.1",
+  "version": "4.36.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -64,8 +64,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "claudeup-darwin-arm64": "4.35.1",
-    "claudeup-darwin-x64": "4.35.1",
-    "claudeup-linux-x64": "4.35.1"
+    "claudeup-darwin-arm64": "4.36.0",
+    "claudeup-darwin-x64": "4.36.0",
+    "claudeup-linux-x64": "4.36.0"
   }
 }

package/src/__tests__/scope-squares.test.tsx

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type React from "react";
+import { ScopeSquares } from "../ui/components/primitives/ScopeSquares.js";
+import {
+	SCOPE_OFF_FALLBACK,
+	SCOPE_OFF_FILL,
+	resetThemeMode,
+	setThemeMode,
+} from "../ui/theme-mode.js";
+import { CONTRAST_REFERENCE, theme } from "../ui/theme.js";
+
+/**
+ * The scope bar is three filled segments; only the fill says lit or unlit.
+ *
+ * Its unlit fill was `theme.colors.muted` (#6B7280) — the same mid-dark grey as
+ * de-emphasised text. On a light page that is a *dark* block, so an unlit segment
+ * carried the same visual weight as a lit one and the bar read as three similar
+ * blobs: "non installed state is dark as well - confusing".
+ *
+ * An unlit segment has to recede toward the page, which is exactly what a fixed
+ * colour cannot do — a pale fill that sits quietly on cream is a bright block on
+ * near-black. So the fill follows the detected terminal, and these tests pin both
+ * that behaviour and its fallback.
+ */
+
+interface SpanLike {
+	props: { fg: string; children: string };
+}
+
+function segments(el: React.ReactElement): SpanLike[] {
+	const children = (el.props as { children: unknown }).children;
+	return (Array.isArray(children) ? children : [children]) as SpanLike[];
+}
+
+const glyphs = (el: React.ReactElement) =>
+	segments(el).map((c) => c.props.children);
+const fills = (el: React.ReactElement) => segments(el).map((c) => c.props.fg);
+
+function relativeLuminance(hex: string): number {
+	const n = hex.replace("#", "");
+	const ch = [0, 2, 4].map((i) => Number.parseInt(n.slice(i, i + 2), 16) / 255);
+	const lin = ch.map((c) =>
+		c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4,
+	);
+	return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+}
+
+afterEach(() => resetThemeMode());
+
+describe("every segment is a filled block", () => {
+	test("lit and unlit alike use the filled glyph", () => {
+		setThemeMode("light");
+		const el = ScopeSquares({ user: true, project: false, local: true });
+		expect(glyphs(el)).toEqual(["■", "■", "■"]);
+	});
+
+	test("local is omitted when the caller does not pass it", () => {
+		setThemeMode("light");
+		expect(glyphs(ScopeSquares({ user: true, project: false }))).toEqual([
+			"■",
+			"■",
+		]);
+	});
+});
+
+describe("fill distinguishes lit from unlit", () => {
+	test("each lit segment keeps its own scope hue", () => {
+		setThemeMode("light");
+		const el = ScopeSquares({ user: true, project: true, local: true });
+		expect(fills(el)).toEqual([
+			theme.scopes.user,
+			theme.scopes.project,
+			theme.scopes.local,
+		]);
+	});
+
+	test("unlit segments take the page-relative off fill", () => {
+		setThemeMode("light");
+		const el = ScopeSquares({ user: false, project: false, local: false });
+		expect(new Set(fills(el))).toEqual(new Set([SCOPE_OFF_FILL.light]));
+
+		setThemeMode("dark");
+		const dark = ScopeSquares({ user: false, project: false, local: false });
+		expect(new Set(fills(dark))).toEqual(new Set([SCOPE_OFF_FILL.dark]));
+	});
+
+	test("a mixed bar shows lit and unlit fills side by side", () => {
+		setThemeMode("light");
+		const el = ScopeSquares({ user: false, project: true, local: false });
+		expect(fills(el)).toEqual([
+			SCOPE_OFF_FILL.light,
+			theme.scopes.project,
+			SCOPE_OFF_FILL.light,
+		]);
+	});
+
+	test("an undetected terminal still gets a visible fill, never nothing", () => {
+		resetThemeMode();
+		const el = ScopeSquares({ user: false, project: false, local: false });
+		expect(new Set(fills(el))).toEqual(new Set([SCOPE_OFF_FALLBACK]));
+	});
+});
+
+describe("the unlit fill recedes toward the page it is on", () => {
+	/**
+	 * How far a fill sits from the page, relative to the NEAREST lit segment.
+	 *
+	 * The naive property — "unlit is closer to the page than a lit colour" — is
+	 * too weak, and measurably so: the old #6B7280 satisfied it on a light page
+	 * (0.766 vs 0.774) while still looking wrong. What made the bar read as three
+	 * similar blobs was that unlit sat **99% as far** from the page as a lit
+	 * segment: essentially the same visual weight. Ratio, not order, is the
+	 * property that captures the defect.
+	 */
+	const pageDistanceRatio = (fill: string, page: string) => {
+		const d = (hex: string) =>
+			Math.abs(relativeLuminance(hex) - relativeLuminance(page));
+		const nearestLit = Math.min(...Object.values(theme.scopes).map(d));
+		return d(fill) / nearestLit;
+	};
+
+	/** Unlit must be at most half as far from the page as the nearest lit segment. */
+	const MAX_RATIO = 0.5;
+
+	test("light page: unlit recedes (measured 0.32)", () => {
+		expect(
+			pageDistanceRatio(SCOPE_OFF_FILL.light, CONTRAST_REFERENCE.light),
+		).toBeLessThan(MAX_RATIO);
+	});
+
+	test("dark page: unlit recedes (measured 0.22)", () => {
+		expect(
+			pageDistanceRatio(SCOPE_OFF_FILL.dark, CONTRAST_REFERENCE.dark),
+		).toBeLessThan(MAX_RATIO);
+	});
+
+	test("the old mid-grey fails the property on BOTH pages", () => {
+		// Pins why the value changed, and guards against anyone reinstating it:
+		// 0.99 on cream and 1.10 on near-black — an unlit segment as heavy as a lit
+		// one, or heavier.
+		expect(
+			pageDistanceRatio("#6B7280", CONTRAST_REFERENCE.light),
+		).toBeGreaterThan(MAX_RATIO);
+		expect(
+			pageDistanceRatio("#6B7280", CONTRAST_REFERENCE.dark),
+		).toBeGreaterThan(MAX_RATIO);
+	});
+});
+
+describe("selected rows", () => {
+	test("unlit segments recede into the selection block, lit take its ink", () => {
+		setThemeMode("light");
+		const el = ScopeSquares({
+			user: true,
+			project: false,
+			local: true,
+			selected: true,
+		});
+		expect(fills(el)).toEqual([
+			theme.selection.fg,
+			theme.selection.bg,
+			theme.selection.fg,
+		]);
+	});
+});

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

@@ -0,0 +1,307 @@
+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";
+
+/**
+ * claudeup 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 ──────────────────────────────────────────────────────────────
+
+const ACCENTS = Object.entries(brand).filter(([name]) => name !== "ink");
+
+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("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);
+	});
+});

package/src/__tests__/uppercase-keybindings.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { parseKeypress } from "@opentui/core";
+import fs from "fs-extra";
+
+/**
+ * A shifted key never arrives as an uppercase `name`.
+ *
+ * OpenTUI reports Shift+U as `{name: "u", shift: true, sequence: "U"}`, so
+ * `event.name === "U"` is unreachable. That is not merely dead code: in
+ * PluginsScreen the dead branch sat BELOW `event.name === "u"`, so pressing
+ * Shift+U — advertised in the footer as "update" — fell through to the plain "u"
+ * branch and installed the plugin at user scope instead. Reported from the real
+ * UI: "U instead of update install user scope".
+ *
+ * The same shape was in McpRegistryScreen (`"R"` for refresh), where nothing
+ * shadowed it, so refresh silently did nothing at all.
+ */
+
+const UI_DIR = path.join(import.meta.dir, "..", "ui");
+
+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)) out.push(full);
+	}
+	return out;
+}
+
+const isComment = (line: string) => {
+	const t = line.trim();
+	return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+};
+
+describe("shifted keys parse to a lowercase name plus a flag", () => {
+	// Pin the platform behaviour the rule depends on. If OpenTUI ever changed
+	// this, the guard below would be enforcing a rule that no longer holds.
+	test("Shift+letter keeps the unshifted name and sets shift", () => {
+		for (const [raw, name] of [
+			["U", "u"],
+			["A", "a"],
+			["R", "r"],
+		] as const) {
+			const k = parseKeypress(raw);
+			expect({ raw, name: k?.name, shift: k?.shift }).toEqual({
+				raw,
+				name,
+				shift: true,
+			});
+		}
+	});
+
+	test("an unshifted letter reports shift false", () => {
+		const k = parseKeypress("u");
+		expect({ name: k?.name, shift: k?.shift }).toEqual({
+			name: "u",
+			shift: false,
+		});
+	});
+});
+
+describe("no binding compares name to an uppercase letter", () => {
+	test("uppercase name comparisons are absent from the UI", 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;
+				if (/\bname\s*===\s*"[A-Z]"/.test(line)) {
+					offenders.push(
+						`${path.relative(UI_DIR, file)}:${i + 1}  ${line.trim()}`,
+					);
+				}
+			});
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	test("an uppercase binding is reachable only via the shift flag", async () => {
+		// The positive half: Shift+U must actually route to update. Asserting only
+		// the absence of `=== "U"` would also pass if someone deleted the binding.
+		const src = await fs.readFile(
+			path.join(UI_DIR, "screens", "PluginsScreen.tsx"),
+			"utf8",
+		);
+		const update = src.indexOf('event.name === "u" && event.shift');
+		const userScope = src.indexOf(
+			'event.name === "u") handleScopeToggle("user")',
+		);
+		expect(update).toBeGreaterThan(-1);
+		expect(userScope).toBeGreaterThan(-1);
+		// Order matters: the shifted branch has to be tested first, or the plain
+		// "u" branch swallows it again — which is exactly the original bug.
+		expect(update).toBeLessThan(userScope);
+	});
+});

package/src/main.tsx

@@ -1,12 +1,13 @@
 #!/usr/bin/env bun
 
-import { createCliRenderer } from "@opentui/core";
+import { RGBA, createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
-import { App } from "./ui/App.js";
-import { route } from "./cli/router.js";
 // Static import so `bun build --compile` embeds package.json into the binary;
 // a dynamic require("../package.json") is not resolvable inside the bunfs root.
 import pkg from "../package.json";
+import { route } from "./cli/router.js";
+import { App } from "./ui/App.js";
+import { setThemeMode } from "./ui/theme-mode.js";
 
 export const VERSION = (pkg as { version: string }).version;
 
@@ -24,8 +25,23 @@ async function main(): Promise<void> {
 		process.exit(outcome.exitCode ?? 0);
 	}
 
-	// Create OpenTUI renderer (handles alternate screen buffer automatically)
-	const renderer = await createCliRenderer();
+	// Create OpenTUI renderer (handles alternate screen buffer automatically).
+	//
+	// The background is the terminal's own, not a colour of ours: painting an
+	// absolute fill would box the UI into whatever theme we guessed. OpenTUI's
+	// built-in default for unstyled cells is truecolor white, which is why every
+	// element now names an adaptive colour explicitly — see src/ui/theme.ts.
+	const renderer = await createCliRenderer({
+		backgroundColor: RGBA.defaultBackground(),
+	});
+
+	// Ask the terminal whether it is light or dark, once. Only the disabled-row
+	// tint needs this — see src/ui/theme-mode.ts for why that one case cannot be
+	// solved the way the rest of the palette is. Bounded wait: a terminal that
+	// ignores the OSC query must not delay first paint, and `null` simply means
+	// no tint.
+	setThemeMode(await renderer.waitForThemeMode(250).catch(() => null));
+
 	const root = createRoot(renderer);
 
 	// Cleanup function to restore terminal