@pellux/goodvibes-tui 1.7.0 → 1.9.0

package/src/renderer/terminal-bg-probe.ts

@@ -0,0 +1,339 @@
+/**
+ * terminal-bg-probe — OSC 11 terminal-background detection for `auto` theme mode.
+ *
+ * DEBT-2 / F5. On startup, when appearance is `auto` and stdout is a TTY, we ask
+ * the terminal for its background colour with an OSC 11 query and classify the
+ * reply as light or dark. Everything about this is best-effort and conservative:
+ * any timeout, any unparseable reply, any ambiguity resolves to DARK, which is
+ * the historical default and keeps headless/unsupported terminals byte-stable.
+ *
+ * Timing (Option B — render dark first, repaint once if light wins):
+ *   The probe never blocks startup. The splash renders immediately in dark; if a
+ *   light reply arrives within the timeout window the caller flips the active mode
+ *   to light and repaints ONCE. Rationale vs. blocking the first paint until the
+ *   reply/timeout: blocking would tax EVERY non-responding terminal (tmux without
+ *   passthrough, CI, old SSH hosts, dumb terminals) with up to `timeoutMs` of blank
+ *   screen on every launch — the common failure case. Option B adds zero startup
+ *   latency and costs at most a single dark→light repaint on genuinely light
+ *   terminals (rare for this audience, one frame).
+ *
+ * Stream safety (never corrupt the composer):
+ *   The reply arrives on the same stdin the keyboard uses. filterInput() sits at
+ *   the very front of the stdin handler (before blocking-input / paste / the
+ *   tokenizer). It passes every non-OSC-11 byte straight through — interleaved
+ *   keystrokes reach the tokenizer untouched — and consumes ONLY a matched OSC 11
+ *   reply (whole or split across chunks). On timeout, any buffered reply fragment
+ *   is discarded rather than flushed, so partial/garbled response bytes can never
+ *   leak into the input pipeline.
+ *
+ * tmux:
+ *   When $TMUX is set the query is wrapped in the tmux DCS passthrough envelope so
+ *   the outer terminal sees it. This only elicits a reply if the user has
+ *   `allow-passthrough` enabled; otherwise the query is swallowed and the timeout
+ *   fallback (dark) covers it silently.
+ */
+
+import { setActiveThemeMode, type ThemeMode } from './theme.ts';
+import { resolveConfiguredThemeMode } from './theme-mode-config.ts';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/** OSC 11 "query background colour" request, ST-terminated. */
+export const OSC11_QUERY = '\x1b]11;?\x1b\\';
+
+/** The response prefix we scan for: ESC ] 1 1 ; */
+const OSC11_PREFIX = '\x1b]11;';
+
+/** Default probe window. Cooperating terminals reply in single-digit ms. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 150;
+
+/** Luminance split point (normalized 0..1). At/above → light; below → dark. */
+export const LUMINANCE_LIGHT_THRESHOLD = 0.5;
+
+/** An 8-bit-per-channel colour parsed from an OSC 11 reply. */
+export interface ProbeRgb {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+
+// ---------------------------------------------------------------------------
+// Pure parsing / classification (exercised directly by the fake-terminal harness)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single hex channel of `len` digits into an 8-bit value.
+ * Scales by the channel's own full-scale (16^len - 1) so `ffff`→255, `ff`→255,
+ * `80`→128, `8000`→128. Returns null on non-hex input.
+ */
+function parseHexChannel(hex: string): number | null {
+  if (hex.length === 0 || !/^[0-9a-fA-F]+$/.test(hex)) return null;
+  const max = 16 ** hex.length - 1;
+  return Math.round((parseInt(hex, 16) / max) * 255);
+}
+
+/**
+ * Parse an OSC 11 colour spec into 8-bit RGB. Accepts:
+ *   - `rgb:RRRR/GGGG/BBBB` and `rgb:RR/GG/BB` (1–4 hex digits per channel)
+ *   - `rgba:R/G/B/A` (alpha ignored)
+ *   - `#RRGGBB` and `#RRRRGGGGBBBB`
+ * Returns null for anything else (→ caller treats as dark).
+ */
+export function parseColorSpec(spec: string): ProbeRgb | null {
+  const trimmed = spec.trim();
+
+  if (trimmed.startsWith('rgb:') || trimmed.startsWith('rgba:')) {
+    const body = trimmed.slice(trimmed.indexOf(':') + 1);
+    const parts = body.split('/');
+    if (parts.length < 3) return null;
+    const r = parseHexChannel(parts[0]!);
+    const g = parseHexChannel(parts[1]!);
+    const b = parseHexChannel(parts[2]!);
+    if (r === null || g === null || b === null) return null;
+    return { r, g, b };
+  }
+
+  if (trimmed.startsWith('#')) {
+    const hex = trimmed.slice(1);
+    if (hex.length !== 6 && hex.length !== 12) return null;
+    if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+    const per = hex.length / 3;
+    const r = parseHexChannel(hex.slice(0, per));
+    const g = parseHexChannel(hex.slice(per, per * 2));
+    const b = parseHexChannel(hex.slice(per * 2));
+    if (r === null || g === null || b === null) return null;
+    return { r, g, b };
+  }
+
+  return null;
+}
+
+/**
+ * Classify a background colour as 'light' or 'dark' by relative luminance.
+ * Uses the Rec. 601 luma weights (0.299/0.587/0.114) normalized to 0..1 and
+ * splits at LUMINANCE_LIGHT_THRESHOLD (0.5): a background at least half as
+ * luminous as white reads as light. Conservative by construction — the exact
+ * threshold only matters for mid-grey backgrounds, which are rare.
+ */
+export function classifyBackgroundLuminance(rgb: ProbeRgb): ThemeMode {
+  const luma = (0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b) / 255;
+  return luma >= LUMINANCE_LIGHT_THRESHOLD ? 'light' : 'dark';
+}
+
+/** Where a terminator starts and where the byte after it is, within a buffer. */
+interface TerminatorSpan {
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * Find the OSC string terminator at/after `from`: BEL (\x07) or ST (ESC \).
+ * Returns null if no terminator is present yet (reply still arriving). A lone
+ * trailing ESC returns null (wait for the next byte to tell ST from a stray ESC);
+ * an ESC followed by a non-'\' byte is treated as the end boundary (malformed
+ * terminator — the body before it is still parsed, the stray byte passes through).
+ */
+function findTerminator(buffer: string, from: number): TerminatorSpan | null {
+  for (let k = from; k < buffer.length; k++) {
+    const c = buffer[k];
+    if (c === '\x07') return { start: k, end: k + 1 };
+    if (c === '\x1b') {
+      if (k + 1 >= buffer.length) return null;
+      return buffer[k + 1] === '\\' ? { start: k, end: k + 2 } : { start: k, end: k + 1 };
+    }
+  }
+  return null;
+}
+
+/**
+ * Longest suffix of `buffer` that is a PROPER prefix of OSC11_PREFIX, used to
+ * hold back a partial reply-prefix split across chunk boundaries (e.g. a chunk
+ * ending in a bare ESC that might become `\x1b]11;`). Only consulted when the
+ * full prefix is not present in the buffer.
+ */
+function trailingPrefixLen(buffer: string): number {
+  const maxLen = Math.min(OSC11_PREFIX.length - 1, buffer.length);
+  for (let len = maxLen; len >= 1; len--) {
+    if (buffer.endsWith(OSC11_PREFIX.slice(0, len))) return len;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// TerminalBackgroundProbe — the stateful stream filter + timing
+// ---------------------------------------------------------------------------
+
+export interface ProbeResolution {
+  readonly mode: ThemeMode;
+  readonly reason: 'light-reply' | 'dark-reply' | 'unparseable' | 'timeout';
+}
+
+export interface TerminalBackgroundProbeOptions {
+  /** Called exactly once with the resolved mode + reason. */
+  readonly onResolve: (result: ProbeResolution) => void;
+  /** Probe window in ms (default DEFAULT_PROBE_TIMEOUT_MS). */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Stateful OSC 11 reply filter. feed() takes a raw stdin chunk and returns the
+ * bytes that should continue down the input pipeline (everything except a matched
+ * OSC 11 reply). Resolves once — on the first complete reply or on timeout.
+ */
+export class TerminalBackgroundProbe {
+  /** True until resolved. filterInput() only calls feed() while active. */
+  public active = true;
+
+  private buffer = '';
+  private resolved = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private readonly onResolve: (result: ProbeResolution) => void;
+  private readonly timeoutMs: number;
+
+  constructor(options: TerminalBackgroundProbeOptions) {
+    this.onResolve = options.onResolve;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+  }
+
+  /** Arm the timeout fallback. Call after writing the query. */
+  startTimeout(): void {
+    this.timer = setTimeout(() => this.resolve('dark', 'timeout'), this.timeoutMs);
+    // Never keep the event loop alive for the probe timer.
+    (this.timer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  /**
+   * Consume a raw stdin chunk. Returns the passthrough bytes (keystrokes and any
+   * non-OSC-11 sequences), having stripped and acted on any OSC 11 reply.
+   */
+  feed(chunk: string): string {
+    if (!this.active) return chunk;
+    this.buffer += chunk;
+    let out = '';
+
+    for (;;) {
+      const prefixIdx = this.buffer.indexOf(OSC11_PREFIX);
+      if (prefixIdx === -1) {
+        // No full reply prefix. Release everything except a possible partial
+        // prefix at the tail (held back to disambiguate next chunk).
+        const keep = trailingPrefixLen(this.buffer);
+        out += this.buffer.slice(0, this.buffer.length - keep);
+        this.buffer = keep > 0 ? this.buffer.slice(this.buffer.length - keep) : '';
+        break;
+      }
+
+      // Release bytes before the reply (interleaved keystrokes survive).
+      out += this.buffer.slice(0, prefixIdx);
+      const term = findTerminator(this.buffer, prefixIdx + OSC11_PREFIX.length);
+      if (term === null) {
+        // Incomplete reply: hold from the prefix onward, await more bytes.
+        this.buffer = this.buffer.slice(prefixIdx);
+        break;
+      }
+
+      // Complete reply. Capture the post-reply remainder BEFORE resolving
+      // (resolve() clears the buffer to discard reply residue, so any trailing
+      // keystrokes must be preserved here, not read back off this.buffer).
+      const spec = this.buffer.slice(prefixIdx + OSC11_PREFIX.length, term.start);
+      const remainder = this.buffer.slice(term.end);
+      const rgb = parseColorSpec(spec);
+      if (rgb === null) {
+        this.resolve('dark', 'unparseable');
+      } else {
+        const mode = classifyBackgroundLuminance(rgb);
+        this.resolve(mode, mode === 'light' ? 'light-reply' : 'dark-reply');
+      }
+      // Resolved (active is now false): forward the post-reply keystrokes and stop.
+      out += remainder;
+      break;
+    }
+
+    return out;
+  }
+
+  /** Resolve once; clears the timer and (on timeout) discards reply residue. */
+  private resolve(mode: ThemeMode, reason: ProbeResolution['reason']): void {
+    if (this.resolved) return;
+    this.resolved = true;
+    this.active = false;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    // Any bytes still buffered here are an incomplete/garbled reply fragment —
+    // discard them so they can never leak into the composer.
+    this.buffer = '';
+    this.onResolve({ mode, reason });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// tmux passthrough + install entry
+// ---------------------------------------------------------------------------
+
+/** Wrap a control sequence in the tmux DCS passthrough envelope (ESC doubled). */
+export function wrapForTmuxPassthrough(seq: string): string {
+  return `\x1bPtmux;${seq.replace(/\x1b/g, '\x1b\x1b')}\x1b\\`;
+}
+
+/** The stdin filter the caller installs at the front of its data handler. */
+export interface ThemeProbeHandle {
+  /** Filter a raw stdin chunk; returns the bytes to forward downstream. */
+  filterInput(chunk: string): string;
+}
+
+export interface InstallThemeProbeOptions {
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  /** Whether stdout is a real TTY (probe only runs on a TTY in auto mode). */
+  readonly isTTY: boolean;
+  /** Process env (only TMUX is read). */
+  readonly env: Record<string, string | undefined>;
+  /** Writes the query bytes (caller wraps in its terminal-output guard). */
+  readonly writeQuery: (bytes: string) => void;
+  /** Called when a light reply wins within the window → repaint once. */
+  readonly requestRepaint: () => void;
+  /** Optional timeout override (tests). */
+  readonly timeoutMs?: number;
+  /** Optional resolution observer (tests / diagnostics). */
+  readonly onResolve?: (result: ProbeResolution) => void;
+}
+
+/**
+ * Read the appearance preference and set up the active theme mode:
+ *   - dark/light  → force immediately (before first paint); no probe.
+ *   - auto + TTY  → leave dark, fire the OSC 11 query, and on a light reply flip
+ *                   to light + repaint once (Option B).
+ *   - auto + !TTY → stay dark (headless/piped; probe cannot run).
+ * Returns a handle whose filterInput() the caller wires at the front of its
+ * stdin data handler. For non-auto and non-TTY cases the filter is a passthrough.
+ */
+export function installBackgroundThemeProbe(options: InstallThemeProbeOptions): ThemeProbeHandle {
+  const pref = resolveConfiguredThemeMode(options.configManager);
+
+  if (pref === 'dark' || pref === 'light') {
+    setActiveThemeMode(pref);
+    return { filterInput: (chunk) => chunk };
+  }
+
+  // pref === 'auto'
+  if (!options.isTTY) {
+    setActiveThemeMode('dark');
+    return { filterInput: (chunk) => chunk };
+  }
+
+  const probe = new TerminalBackgroundProbe({
+    timeoutMs: options.timeoutMs,
+    onResolve: (result) => {
+      if (result.mode === 'light') {
+        setActiveThemeMode('light');
+        options.requestRepaint();
+      }
+      options.onResolve?.(result);
+    },
+  });
+
+  const query = options.env['TMUX'] ? wrapForTmuxPassthrough(OSC11_QUERY) : OSC11_QUERY;
+  options.writeQuery(query);
+  probe.startTimeout();
+
+  return { filterInput: (chunk) => (probe.active ? probe.feed(chunk) : chunk) };
+}

package/src/renderer/terminal-escapes.ts

@@ -0,0 +1,20 @@
+/**
+ * terminal-escapes — the raw control sequences main.ts writes to enter/leave the
+ * TUI's terminal mode (alt screen, mouse, cursor, keyboard-extension, paste, and
+ * focus reporting). Extracted from main.ts as plain constants so the entry file
+ * stays within the source-file line-count gate; behaviour is unchanged.
+ */
+
+export const ALT_SCREEN_ENTER = '\x1b[?1049h';
+export const ALT_SCREEN_EXIT = '\x1b[?1049l';
+export const MOUSE_ENABLE = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
+export const MOUSE_DISABLE = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+export const CURSOR_HIDE = '\x1b[?25l';
+export const CURSOR_SHOW = '\x1b[?25h';
+export const CLEAR_SCREEN = '\x1b[2J\x1b[3J\x1b[H';
+export const KEYBOARD_EXT_ENABLE = '\x1b[>4;2m' + '\x1b[?1u';
+export const KEYBOARD_EXT_DISABLE = '\x1b[>4;0m' + '\x1b[?1l';
+export const PASTE_ENABLE = '\x1b[?2004h';
+export const PASTE_DISABLE = '\x1b[?2004l';
+export const FOCUS_ENABLE = '\x1b[?1004h';
+export const FOCUS_DISABLE = '\x1b[?1004l';

package/src/renderer/theme-mode-config.ts

@@ -0,0 +1,67 @@
+/**
+ * theme-mode-config — the appearance/theme-mode preference, TUI-side.
+ *
+ * The preference lives at the config key `display.themeMode` (auto | dark |
+ * light, default auto). It is stored under the existing SDK `display` section
+ * rather than a new `appearance` section on purpose: the SDK ConfigManager's
+ * resolvePath() throws for any dot-path whose top-level section is absent from
+ * DEFAULT_CONFIG, and adding an `appearance` section would require an SDK schema
+ * change (out of scope for this TUI-only work order). Storing under `display`
+ * reuses the same proven "TUI-local synthetic setting" pattern the codebase
+ * already uses for tts.speed / behavior.notifyAfterSeconds / storage.codeIndexEnabled:
+ * ConfigManager.setDynamic writes it to settings.json and get() reads it back,
+ * with zero SDK changes.
+ *
+ * This module is deliberately free of any terminal/probe state so both the
+ * settings-modal data layer (input) and the probe (renderer) can import it
+ * without pulling in the stateful probe class.
+ */
+
+import type { ThemeModeSetting } from './theme.ts';
+import type { ConfigKey, ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/** Config key backing the appearance/theme-mode preference (see module doc). */
+export const THEME_MODE_CONFIG_KEY = 'display.themeMode';
+
+/** The three valid preference values, in settings-cycle order. */
+export const THEME_MODE_VALUES: readonly ThemeModeSetting[] = ['auto', 'dark', 'light'];
+
+/** Default when unset: probe the terminal background on startup. */
+export const THEME_MODE_DEFAULT: ThemeModeSetting = 'auto';
+
+/**
+ * Human-facing description for the settings-modal entry. States the honest
+ * timing contract: forced modes apply on next full paint immediately; `auto`
+ * only re-probes at startup, so switching TO auto takes effect next launch.
+ */
+export const THEME_MODE_DESCRIPTION =
+  'Terminal background theme. auto probes the terminal background colour once at '
+  + 'startup (OSC 11) and picks light or dark; dark/light force a fixed theme. '
+  + 'Forced modes take effect immediately; auto is only evaluated at startup, so '
+  + 'selecting auto takes effect on the next launch. Unreadable/unsupported '
+  + 'terminals fall back to dark. Scope (honest): transcript markdown, modal '
+  + 'accents, and the header/footer/thinking chrome all flip with this setting; '
+  + 'only the background colour itself follows your terminal.';
+
+/** Narrow an unknown config value to a valid ThemeModeSetting, else the default. */
+export function coerceThemeModeSetting(raw: unknown): ThemeModeSetting {
+  return raw === 'auto' || raw === 'dark' || raw === 'light' ? raw : THEME_MODE_DEFAULT;
+}
+
+/**
+ * Read the configured theme-mode preference. Reads the TUI-local key via a cast
+ * (it is not in the SDK ConfigKey union). Safe: the `display` section exists in
+ * DEFAULT_CONFIG, so get() returns undefined for the absent field rather than
+ * throwing, and we coerce undefined → 'auto'.
+ */
+export function resolveConfiguredThemeMode(
+  configManager: Pick<ConfigManager, 'get'>,
+): ThemeModeSetting {
+  try {
+    // Cast key: display.themeMode is TUI-local, not in the SDK ConfigKey union.
+    return coerceThemeModeSetting(configManager.get(THEME_MODE_CONFIG_KEY as ConfigKey));
+  } catch {
+    // Defensive: any unexpected resolvePath/section error → honest default.
+    return THEME_MODE_DEFAULT;
+  }
+}

package/src/renderer/theme.ts

@@ -184,6 +184,22 @@ type DeepWidenToString<T> = T extends string ? string : { [K in keyof T]: DeepWi
 
 export type UiToneTokens = DeepWidenToString<typeof UI_TONES>;
 
+//
+// chrome.* — persistent header/footer/thinking foregrounds that paint on the
+// TRANSPARENT terminal background (see the chrome group's doc in
+// ui-primitives.ts). Unlike fg.muted/fg.dim (which stay light for the opaque
+// dark modal/panel boxes), these invert toward dark so they read on a light
+// terminal. Contrast ratios below are against a white terminal (#ffffff),
+// matching the discipline of the LIGHT ThemeTokens above:
+//   label: Slate-500 (#64748b) — header title; ~4.9:1 on #fff (matches modelNameDim)
+//   faint: Slate-400 (#94a3b8) — version/rule/clean-git; ~2.7:1 on #fff, deliberately
+//          faint (mirrors the low-contrast intent of the dark fg.dim role)
+//   warn:  Amber-700 (#b45309) — dirty git / pending risk; ~5.0:1 on #fff (matches diffAccent)
+//   bad:   Red-600  (#dc2626) — DANGER banner / shell risk (bold); ~5.3:1 on #fff
+//   good:  Forest-700 (#15803d) — tool-call ✓ status; ~5.02:1 on #fff (matches checkboxChecked)
+//   remote: Violet-700 (#6d28d9) — risk:remote marker / plain status; ~7.10:1 on #fff,
+//          deliberately distinct from reasoningAccent (#7c3aed) so the remote-risk cue
+//          never reads as a reasoning accent on a light terminal
 const UI_TONES_LIGHT: UiToneTokens = {
   ...UI_TONES,
   state: {
@@ -197,10 +213,20 @@ const UI_TONES_LIGHT: UiToneTokens = {
     gradientStart: LIGHT.heading1,
     gradientEnd: LIGHT.reasoningAccent,
   },
+  chrome: {
+    ...UI_TONES.chrome,
+    label: '#64748b',
+    faint: '#94a3b8',
+    warn:  '#b45309',
+    bad:   '#dc2626',
+    good:  '#15803d',
+    remote: '#6d28d9',
+  },
 };
 
 Object.freeze(UI_TONES_LIGHT.state);
 Object.freeze(UI_TONES_LIGHT.accent);
+Object.freeze(UI_TONES_LIGHT.chrome);
 Object.freeze(UI_TONES_LIGHT);
 
 /**
@@ -208,8 +234,72 @@ Object.freeze(UI_TONES_LIGHT);
  * set for the given background mode. Single read path for UI_TONES; the
  * 'dark' resolution is byte-identical to the UI_TONES constant.
  *
- * Call with 'dark' (the safe default) until terminal-bg-probe lands.
+ * Prefer activeUiTones() at call sites — resolveUiTones is the pure per-mode
+ * resolver underneath it.
  */
 export function resolveUiTones(mode: ThemeMode): Readonly<UiToneTokens> {
   return mode === 'light' ? UI_TONES_LIGHT : UI_TONES;
 }
+
+// ===========================================================================
+// Active-mode runtime (DEBT-2 / F5 terminal-bg-probe landing).
+//
+// The mode is decided ONCE at startup — from appearance config (display.themeMode
+// forced dark/light) or the terminal-background probe (auto) — and is then stable
+// for the session. Two read shapes exist because the two token layers are
+// consumed differently:
+//
+//   - Transcript tokens (ThemeTokens): read live per render via activeTheme(),
+//     so a dark→light repaint (auto mode, light wins within the probe window)
+//     re-resolves without any module reload.
+//
+//   - Chrome tokens (UiToneTokens): baked into module-level palette CONSTANTS
+//     (DEFAULT_PANEL_PALETTE, DEFAULT_OVERLAY_PALETTE, FULLSCREEN_PALETTE,
+//     DEFAULT_STYLE) that hundreds of call sites read by reference. Those
+//     constants cannot be re-resolved per call without a rewrite, so each owner
+//     registers an in-place rebuild via registerThemeRefresh(); setActiveThemeMode
+//     runs every rebuild in registration order (base palettes before the
+//     extendPalette-derived panel palettes) so a single mode flip updates them
+//     all. The rebuild is fully reversible: light→dark restores byte-identical
+//     dark values (tests rely on this to keep the shared test process's default
+//     at dark).
+// ===========================================================================
+
+/** User-facing appearance preference: auto probes the terminal; dark/light force. */
+export type ThemeModeSetting = 'auto' | 'dark' | 'light';
+
+/** The resolved mode in effect for the current session. Dark is the safe default. */
+let activeMode: ThemeMode = 'dark';
+
+/** In-place palette rebuilders, run (in registration order) on every mode flip. */
+const themeRefreshers: Array<() => void> = [];
+
+/**
+ * Register an in-place palette rebuild to run whenever the active mode changes.
+ * Base-palette owners register at their own module-eval time (before any
+ * extendPalette-derived palette, which depends on the base), so refreshers run
+ * base-first — the ordering the extended palettes require to re-merge correctly.
+ */
+export function registerThemeRefresh(rebuild: () => void): void {
+  themeRefreshers.push(rebuild);
+}
+
+/**
+ * Set the active background mode and rebuild every registered chrome palette
+ * in place. Idempotent and reversible. Callers: startup (forced mode or probe
+ * result) and the settings-modal change hook for forced modes.
+ */
+export function setActiveThemeMode(mode: ThemeMode): void {
+  activeMode = mode;
+  for (const rebuild of themeRefreshers) rebuild();
+}
+
+/** Transcript tokens for the active mode — read live, per render. */
+export function activeTheme(): Readonly<ThemeTokens> {
+  return resolveTheme(activeMode);
+}
+
+/** Chrome tokens for the active mode — used to build (and rebuild) palettes. */
+export function activeUiTones(): Readonly<UiToneTokens> {
+  return resolveUiTones(activeMode);
+}

package/src/renderer/thinking.ts

@@ -1,14 +1,22 @@
 import { type Line } from '../types/grid.ts';
-import { BORDERS, COLORS } from './layout.ts';
+import { BORDERS } from './layout.ts';
 import { renderConversationNotice } from './conversation-surface.ts';
+import { activeUiTones } from './theme.ts';
 
 export function renderThinkingBlock(text: string, width: number): Line[] {
+  // Thinking notices paint the ▌ marker and italic body on the TRANSPARENT
+  // terminal background (renderConversationNotice passes no bodyBg), so both
+  // colors resolve per-render through activeUiTones() to stay legible on a
+  // light terminal. Dark values are byte-identical to the prior static reads
+  // (state.reasoning for the accent, chrome.faint — which equals fg.dim — for
+  // the body text).
+  const t = activeUiTones();
   return renderConversationNotice(
     text,
     width,
     {
-      accent: BORDERS.THINKING.color,
-      text: COLORS.DIM_TEXT,
+      accent: t.state.reasoning,
+      text: t.chrome.faint,
       dim: true,
       italic: true,
     },

package/src/renderer/tool-call.ts

@@ -4,7 +4,8 @@ import { getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
 import type { ToolCall } from '@pellux/goodvibes-sdk/platform/types';
 import { stripDangerousAnsi } from './ansi-sanitize.ts';
 import { formatElapsed } from '../utils/format-elapsed.ts';
-import { UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { activeUiTones } from './theme.ts';
 
 const TOOL_NAME_MIN_WIDTH = 8;
 const TOOL_NAME_MAX_WIDTH = 20;
@@ -46,6 +47,7 @@ function buildLeftSegments(
 ): Array<{ text: string; fg: string; bold?: boolean; dim?: boolean }> {
   if (leftBudget <= 0) return [];
 
+  const t = activeUiTones();
   const segments: Array<{ text: string; fg: string; bold?: boolean; dim?: boolean }> = [];
   const suffixBudget = suffixText ? Math.min(Math.max(12, Math.floor(leftBudget * 0.3)), 20) : 0;
   const suffixDisplay = suffixBudget > 0 ? truncateDisplay(suffixText, suffixBudget) : '';
@@ -74,14 +76,14 @@ function buildLeftSegments(
     segments.push({ text: toolNameDisplay, fg: '#00ffcc', bold: true });
   }
   if (keyArgDisplay) {
-    segments.push({ text: '  ', fg: UI_TONES.fg.primary });
+    segments.push({ text: '  ', fg: t.fg.primary });
     segments.push({ text: keyArgDisplay, fg: '252' });
   }
   if (suffixDisplay) {
-    segments.push({ text: '  ', fg: UI_TONES.fg.primary });
+    segments.push({ text: '  ', fg: t.fg.primary });
     segments.push({
       text: suffixDisplay,
-      fg: suffixText.startsWith('- ') ? UI_TONES.state.bad : '244',
+      fg: suffixText.startsWith('- ') ? t.chrome.bad : '244',
       dim: true,
     });
   }
@@ -155,7 +157,7 @@ function extractKeyArg(toolCall: ToolCall): string {
  */
 export function renderToolCallBlock(
   toolCall: ToolCall,
-  status: 'executing' | 'done' | 'error',
+  status: 'executing' | 'done' | 'error' | 'pending',
   resultSummary: string | undefined,
   width: number,
   durationMs?: number,
@@ -164,16 +166,20 @@ export function renderToolCallBlock(
   startedAtMs?: number,
 ): Line[] {
   const line = createEmptyLine(width);
+  const t = activeUiTones();
   const margin = LAYOUT.LEFT_MARGIN;
   const rightMargin = LAYOUT.RIGHT_MARGIN;
   const contentEnd = width - rightMargin;
 
-  // Status icon
+  // Status icon. 'pending' means the tool is still awaiting a decision
+  // (e.g. an approval prompt) and has NOT run yet — it uses the hollow idle
+  // glyph so a not-yet-run tool never shows the completed green ✓ (UX-B 2c).
   const icon = status === 'done' ? TOOL_STATUS.SUCCESS_ICON
     : status === 'error' ? TOOL_STATUS.FAIL_ICON
+    : status === 'pending' ? GLYPHS.status.idle
     : TOOL_STATUS.SPINNER_FRAMES[(frameIndex ?? 0) % TOOL_STATUS.SPINNER_FRAMES.length];
-  const iconColor = status === 'done' ? UI_TONES.state.good
-    : status === 'error' ? UI_TONES.state.bad
+  const iconColor = status === 'done' ? t.chrome.good
+    : status === 'error' ? t.chrome.bad
     : '244';
   const rightText = (() => {
     if (durationMs !== undefined && status === 'done') {
@@ -198,7 +204,7 @@ export function renderToolCallBlock(
   let col: number = leftStart;
 
   if (col < leftEndExclusive) {
-    line[col] = createStyledCell(icon, { fg: iconColor, bold: status !== 'executing' });
+    line[col] = createStyledCell(icon, { fg: iconColor, bold: status === 'done' || status === 'error' });
   }
   col += 2; // icon + space