fix(tui): render light theme with readable roles

Author: TheGreatAxios

docs/TUI.md

@@ -134,8 +134,10 @@ titlebar row: the model label sits right-aligned in the top rule as
 `profile · model · effort · mode` (empty segments omitted), and a
 compact `mcp !` sits immediately left of it when any MCP server still needs
 authorization (`/mcp` is the surface that names them), painted in
-`UI.warning` (sand, `#d1ad7d`) — the same role `plugin !` uses. Orange is
-not spent on these standing marks. The brand
+`UI.warning` — the same role `plugin !` uses. Warning is caution gold in the
+dark theme and muted plum (`#655275`) in the light theme; a bronze warning on
+cream is perceptually indistinguishable from machine emphasis, while plum stays
+separate without spending action orange or failure red. The brand
 lockup sits at the left of the bottom rule with the working directory and git
 branch at its right (`AppShell.promptTopRule` / `promptBottomRule`,
 `src/tui/shell/internals.ts`). Context occupancy rides that bottom rule as a percent:
@@ -239,6 +241,13 @@ Ongoing, non-decision status uses the bronze/sand/ember chrome ramp and green
 The one deliberate exception is diff removals, where orange is content (the
 removed line), not a decision marker, and no decision-marker shares that row.
 
+The shell selects its final theme before constructing or mounting renderables.
+An explicit `light` or `dark` setting wins; otherwise `COLORFGBG` wins when it
+identifies the terminal background, then macOS appearance is read synchronously,
+and unknown environments fall back to dark. The macOS read has a 500 ms process
+timeout. Production does not query OSC 11 or switch themes after mount, so the
+first frame cannot mix palettes across transcript, prompt, borders, or overlays.
+
 ## The live task list panel
 
 **Parked pending rebuild.** `formatChromeZones` (`src/tui/chrome-state.ts`)
@@ -418,7 +427,7 @@ framed content in the shell, and their body is shaped rather than merely
 listed (`src/tui/overlay-body.ts`): a dithered header (`░▒▓`) carries the
 subject in the action color — the only Breakthrough Orange on the card. The
 overlay host border and title use calm dim chrome (`UI.textDim`); consequence
-impact in the description zone paints `UI.warning` (sand), not orange. A
+impact in the description zone paints `UI.warning`, not orange. A
 blank row separates the subject from context. Choices are deliberately small:
 each one is a bare, single-line action name (`Reject`, `Accept once`, the
 scope's label) with no consequence text folded into the row. A scope's hint

src/tui/diff-rows.test.ts

@@ -11,7 +11,7 @@ import { toolCallRow } from "./diff";
 import { withTestRenderer, type Harness } from "./harness";
 import { appendStreamRow } from "./shell/chrome";
 import { createAppShell } from "./shell/index";
-import { DIFF_FG } from "./stream";
+import { UI } from "./theme";
 import { toolResultRow } from "./mcp-view";
 
 const WIDE = { width: 100, height: 30 } as const;
@@ -78,8 +78,8 @@ describe("diff transcript rows", () => {
       const spans = spansWithHex(h);
       const del = spans.find((s) => s.text.includes("-") && s.text.length <= 2);
       const add = spans.find((s) => s.text.includes("+") && s.text.length <= 2);
-      expect(del?.fg).toBe(DIFF_FG.del);
-      expect(add?.fg).toBe(DIFF_FG.add);
+      expect(del?.fg).toBe(UI.action);
+      expect(add?.fg).toBe(UI.done);
     }, WIDE);
   });
 
@@ -97,13 +97,13 @@ describe("diff transcript rows", () => {
       const changedAdded = spans.find((s) => s.text.includes("product(a,"));
       const shared = spans.filter((s) => s.text.includes("const"));
 
-      expect(changedRemoved?.fg).toBe(DIFF_FG.del);
-      expect(changedAdded?.fg).toBe(DIFF_FG.add);
+      expect(changedRemoved?.fg).toBe(UI.action);
+      expect(changedAdded?.fg).toBe(UI.done);
       // Bold attribute distinguishes the changed tokens inside the line.
       expect(defined(changedRemoved).attributes).toBeGreaterThan(0);
       // "const" is shared by both sides, so it stays in the context tone.
       expect(shared.length).toBeGreaterThan(0);
-      expect(shared.every((s) => s.fg === DIFF_FG.context)).toBe(true);
+      expect(shared.every((s) => s.fg === UI.textDim)).toBe(true);
     }, WIDE);
   });
 

src/tui/diff.test.ts

@@ -11,7 +11,8 @@ import {
   toolCallRow,
   type DiffLine,
 } from "./diff.js";
-import { DIFF_FG, isDiffRow, isMarkdownRow } from "./stream.js";
+import { isDiffRow, isMarkdownRow } from "./stream.js";
+import { UI } from "./theme.js";
 
 const textOf = (line: DiffLine): string => line.map((seg) => seg.text).join("");
 
@@ -91,19 +92,19 @@ describe("renderDiff", () => {
     const delBody = defined(lines[0]).slice(2);
     const addBody = defined(lines[1]).slice(2);
     const delChanged = delBody
-      .filter((s) => s.fg === DIFF_FG.del)
+      .filter((s) => s.fg === UI.action)
       .map((s) => s.text)
       .join("");
     const addChanged = addBody
-      .filter((s) => s.fg === DIFF_FG.add)
+      .filter((s) => s.fg === UI.done)
       .map((s) => s.text)
       .join("");
     expect(delChanged).toContain("bar");
     expect(addChanged).toContain("baz");
     expect(delChanged).not.toContain("const");
     expect(addChanged).not.toContain("const");
     expect(
-      delBody.some((s) => s.text.includes("const") && s.fg === DIFF_FG.context),
+      delBody.some((s) => s.text.includes("const") && s.fg === UI.textDim),
     ).toBe(true);
   });
 
@@ -118,7 +119,7 @@ describe("renderDiff", () => {
     const lines = renderDiff("a b c", "a x c", 40);
     const changed = defined(lines[0])
       .slice(2)
-      .filter((s) => s.fg === DIFF_FG.del)
+      .filter((s) => s.fg === UI.action)
       .map((s) => s.text.trim())
       .filter(Boolean);
     expect(changed).toEqual(["b"]);
@@ -130,26 +131,26 @@ describe("renderDiff", () => {
     expect(
       defined(removed)
         .slice(1)
-        .every((s) => s.fg === DIFF_FG.del),
+        .every((s) => s.fg === UI.action),
     ).toBe(true);
     expect(
       defined(added)
         .slice(1)
-        .every((s) => s.fg === DIFF_FG.add),
+        .every((s) => s.fg === UI.done),
     ).toBe(true);
   });
 
   test("context rows take the muted context tone", () => {
     const lines = renderDiff("a\nb", "a\nB", 40);
-    expect(defined(lines[0]).every((s) => s.fg === DIFF_FG.context)).toBe(true);
+    expect(defined(lines[0]).every((s) => s.fg === UI.textDim)).toBe(true);
   });
 
   test("line-number column always uses the muted context tone", () => {
     const lines = renderDiff("a\nb", "a\nB", 40);
     expect(lines.map((line) => defined(line[0]).fg)).toEqual([
-      DIFF_FG.context,
-      DIFF_FG.context,
-      DIFF_FG.context,
+      UI.textDim,
+      UI.textDim,
+      UI.textDim,
     ]);
   });
 

src/tui/diff.ts

@@ -16,7 +16,8 @@ import { describeToolCall } from "./tool-formatter.js";
 // The one wrap implementation: a diff row soft-wraps by the same column rules
 // as every other row, so a wide glyph cannot overflow the gutter here alone.
 import { wrapRanges } from "./view/height.js";
-import { DIFF_FG, type StreamRow } from "./stream.js";
+import type { StreamRow } from "./stream.js";
+import { UI } from "./theme.js";
 import { toolArgsView } from "./tool-args.js";
 
 export type DiffRowKind = "add" | "del" | "context";
@@ -139,9 +140,9 @@ const GUTTER: Record<DiffRowKind, string> = {
 };
 
 function rowColor(kind: DiffRowKind): string {
-  if (kind === "add") return DIFF_FG.add;
-  if (kind === "del") return DIFF_FG.del;
-  return DIFF_FG.context;
+  if (kind === "add") return UI.done;
+  if (kind === "del") return UI.action;
+  return UI.textDim;
 }
 
 // Attach each row's position in the old/new file before any collapsing, so a
@@ -227,7 +228,7 @@ export function wordDiffSegments(
   const m = other.length;
   while (i < n && j < m) {
     if (self[i] === other[j]) {
-      out.push({ text: requireDiffLine(self, i), fg: DIFF_FG.context });
+      out.push({ text: requireDiffLine(self, i), fg: UI.textDim });
       i++;
       j++;
     } else if (lcsCell(lcs, i + 1, j) >= lcsCell(lcs, i, j + 1)) {
@@ -351,7 +352,7 @@ export function renderDiff(
           ? [
               {
                 text: idx === 0 ? numCol : " ".repeat(numColWidth),
-                fg: DIFF_FG.context,
+                fg: UI.textDim,
               },
             ]
           : []),
@@ -453,7 +454,7 @@ export function editDiffView(
           [
             {
               text: `… ${all.length - MAX_DIFF_LINES} more diff lines`,
-              fg: DIFF_FG.context,
+              fg: UI.textDim,
             },
           ],
         ]

src/tui/lockup.test.ts

@@ -1,4 +1,6 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
+import { rgbToHex, type CapturedSpan } from "@opentui/core";
+import { defined } from "../../tests/helpers/defined.js";
 
 import {
   LOCKUP_FADE_MS,
@@ -13,7 +15,9 @@ import {
   STALL_BLINK_CYCLE_MS,
   type RampPhase,
 } from "./ramp";
-import { UI } from "./theme";
+import { withTestRenderer } from "./harness";
+import { createAppShell } from "./shell/index";
+import { corbitsLight, setTheme, UI } from "./theme";
 
 const idle = (nowMs: number): LockupInput => ({
   nowMs,
@@ -40,6 +44,28 @@ const live = (
 
 const still = (nowMs = 0) => lockupCells(idle(nowMs));
 
+function colorHex(color: CapturedSpan["fg"]): string {
+  return rgbToHex(color).toLowerCase().slice(0, 7);
+}
+
+function luminance(hex: string): number {
+  const channel = (offset: number): number => {
+    const value = Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+}
+
+function contrast(foreground: string, background: string): number {
+  const fg = luminance(foreground);
+  const bg = luminance(background);
+  return (Math.max(fg, bg) + 0.05) / (Math.min(fg, bg) + 0.05);
+}
+
+afterEach(() => {
+  setTheme("corbits-dark");
+});
+
 describe("brand lockup", () => {
   test("idle is the wordmark alone", () => {
     const cells = still();
@@ -69,6 +95,32 @@ describe("brand lockup", () => {
     expect(lockupWidth(input)).toBe(lockupCells(input).length);
   });
 
+  test("light wordmark renders with readable paint-time chrome", async () => {
+    setTheme("corbits-light");
+    await withTestRenderer(async (h) => {
+      const shell = createAppShell(h.renderer, {
+        terminal: { columns: 80, rows: 24 },
+        wireKeys: false,
+      });
+      try {
+        await h.renderOnce();
+        await h.renderOnce();
+        const wordmark = h
+          .captureSpans()
+          .lines.flatMap((line) => line.spans)
+          .find((span) => span.text.includes(LOCKUP_WORDMARK));
+        const painted = defined(wordmark, "rendered wordmark span");
+        const foreground = colorHex(painted.fg);
+        const background = colorHex(painted.bg);
+        expect(foreground).toBe(corbitsLight.textDim);
+        expect(background).toBe(corbitsLight.ground);
+        expect(contrast(foreground, background)).toBeGreaterThanOrEqual(4.5);
+      } finally {
+        shell.dispose();
+      }
+    });
+  });
+
   test("the wordmark stays chrome-dim", () => {
     for (const cell of still()) {
       expect(cell.fg).toBe(UI.textDim);

src/tui/lockup.ts

@@ -48,8 +48,8 @@ export const LOCKUP_FADE_MS = 240;
  * Fade ramps, faintest first. A terminal has no alpha, so a transition steps
  * through the warm dim tones toward its resting tone instead of blending.
  */
-const WORDMARK_FADE = [UI.textFaint, UI.textDim] as const;
-const PHASE_FADE = [UI.textFaint, UI.textDim, UI.text] as const;
+const wordmarkFade = (): readonly string[] => [UI.textFaint, UI.textDim];
+const phaseFade = (): readonly string[] => [UI.textFaint, UI.textDim, UI.text];
 
 export interface LockupInput {
   readonly nowMs: number;
@@ -105,7 +105,7 @@ export function lockupCells(input: LockupInput): readonly MarkCell[] {
 
   const progress = fadeProgress(input);
   const cells: MarkCell[] = [];
-  const textTone = toneAt(live ? PHASE_FADE : WORDMARK_FADE, progress);
+  const textTone = toneAt(live ? phaseFade() : wordmarkFade(), progress);
   for (const char of label) {
     cells.push({ char, fg: textTone });
   }