Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

13.0 KB
Raw Blame
/**
 * theme-mode.ts — the ONE place claudish knows whether the terminal is light or dark.
 *
 * Dependency-free on purpose (node builtins only): this module is imported by plain
 * CLI command files, the raw-ANSI printers AND the OpenTUI palettes, so it must never
 * pull @opentui/core into a code path that today runs without it.
 *
 * Detection sources, in precedence order:
 *
 *   1. `CLAUDISH_THEME=light|dark` — explicit user override, and the deterministic
 *      lever tests and screenshot harnesses use. Always wins.
 *   2. An OSC 11 query — ask the terminal its background color over the tty and
 *      classify by WCAG relative luminance. A MEASUREMENT, so it also yields the
 *      background COLOUR itself (see `getTerminalBackgroundHex`). Bounded by a
 *      timeout: a terminal that never answers must not stall startup.
 *   3. `COLORFGBG` — set by some terminals (iTerm2, rxvt). Free and synchronous,
 *      but only a HINT: it is written once and goes stale, and tmux inherits a
 *      stale value across a theme change. Measured on a real cream terminal it
 *      reported `15;0` ("dark") while OSC 11 returned `#f9f6da` ("light"). It is
 *      therefore the fallback, not the primary — used when nobody answers OSC,
 *      and by the sync path, which cannot await.
 *
 * `null` (unknown) is a real state, not an error: every consumer treats it as
 * "behave exactly as claudish behaved before light-theme support" — the dark
 * palette for the TUI, the classic 16-color escapes for CLI output. A wrong guess
 * would paint dark-on-dark or light-on-light; the status quo merely looks like
 * yesterday's claudish.
 *
 * The OpenTUI surfaces do NOT use the OSC path here — the renderer runs its own
 * OSC handshake (`renderer.waitForThemeMode`) and feeds the result into
 * `setThemeMode`, so the whole process shares one answer either way.
 */

export type TerminalThemeMode = "dark" | "light";

let detected: TerminalThemeMode | null = null;

/** Listeners run synchronously on every mode change (palette refreshers). */
const listeners: Array<(mode: TerminalThemeMode | null) => void> = [];

export function getThemeMode(): TerminalThemeMode | null {
  return detected;
}

export function setThemeMode(mode: TerminalThemeMode | null): void {
  detected = mode;
  for (const cb of listeners) cb(mode);
}

/**
 * Register a palette refresher. It is invoked immediately with the CURRENT mode
 * (so a module loaded after detection still syncs) and again on every change.
 */
export function onThemeModeChange(cb: (mode: TerminalThemeMode | null) => void): void {
  listeners.push(cb);
  cb(detected);
}

/**
 * Test seam — restore the pre-detection state between cases.
 *
 * Deliberately does NOT clear the listener registry: listeners are one-time
 * MODULE-level registrations (tui/theme.ts, viz/tokens.ts) and Bun runs sibling
 * test files in one process, so dropping them here would silently freeze the
 * palette for every test file that runs after this one. Resetting means
 * "publish null again", which resolves to the dark palette — the same state a
 * fresh process starts in.
 */
export function resetThemeModeForTests(): void {
  setThemeMode(null);
  background = null;
}

// ---------------------------------------------------------------------------
// Source 1: explicit override
// ---------------------------------------------------------------------------

export function themeModeOverride(env: NodeJS.ProcessEnv = process.env): TerminalThemeMode | null {
  const raw = env.CLAUDISH_THEME?.trim().toLowerCase();
  if (raw === "light" || raw === "dark") return raw;
  return null;
}

// ---------------------------------------------------------------------------
// Source 2: COLORFGBG ("fg;bg" or "fg;default;bg" — bg is an ANSI slot number)
// ---------------------------------------------------------------------------

export function themeModeFromColorFgBg(
  env: NodeJS.ProcessEnv = process.env
): TerminalThemeMode | null {
  const raw = env.COLORFGBG;
  if (!raw) return null;
  const last = raw.split(";").pop()?.trim();
  if (!last || !/^\d+$/.test(last)) return null;
  const bg = Number.parseInt(last, 10);
  // Slots 7 and 15 are the light grays / white; 0-6 and 8 are dark.
  if (bg === 7 || bg === 15) return "light";
  if (bg <= 8) return "dark";
  return null;
}

// ---------------------------------------------------------------------------
// Source 3: OSC 11 background query
// ---------------------------------------------------------------------------

/** WCAG 2.1 relative luminance of an sRGB triplet scaled 0..1. */
export function relativeLuminance(r: number, g: number, b: number): number {
  const lin = (c: number): number => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
}

// Keep the light/dark boundary at the perceptual midpoint of the encoded sRGB
// range. Its WCAG-linearized luminance is lower than 0.5 because sRGB is gamma
// encoded, so compare like with like rather than applying 0.5 after linearizing.
const MID_SRGB_LUMINANCE = relativeLuminance(0.5, 0.5, 0.5);

/**
 * Parse an OSC 11 reply — `\x1b]11;rgb:RRRR/GGGG/BBBB\x07` (or ST-terminated;
 * channels may be 1-4 hex digits) — into a theme mode by luminance.
 * Exported for tests.
 */
export function classifyOscBackground(reply: string): TerminalThemeMode | null {
  const m = reply.match(/\]11;rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})/);
  if (!m) return null;
  const channel = (hex: string): number => {
    // Scale by the field's own width: "ff" -> 255/255, "ffff" -> 65535/65535.
    const max = 16 ** hex.length - 1;
    return Number.parseInt(hex, 16) / max;
  };
  const lum = relativeLuminance(channel(m[1]!), channel(m[2]!), channel(m[3]!));
  return lum >= MID_SRGB_LUMINANCE ? "light" : "dark";
}

/**
 * The terminal's ACTUAL background as `#rrggbb`, from the same OSC 11 reply.
 * Exported for tests.
 *
 * The classifier above reduces this reply to one bit and discards the colour,
 * which is why the TUI painted `#ffffff` over a cream terminal and `#000000`
 * over a soft-black one: correct light/dark, visibly wrong shade. The full-screen
 * page cannot simply be transparent — the 1Password add-wizard is an absolute
 * overlay that relies on an opaque `C.bg` to occlude the list beneath it — so
 * matching the terminal exactly is how the page becomes invisible while STAYING
 * opaque.
 */
export function parseOscBackgroundHex(reply: string): string | null {
  const m = reply.match(/\]11;rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})/);
  if (!m) return null;
  const byte = (hex: string): string => {
    const max = 16 ** hex.length - 1;
    const v = Math.round((Number.parseInt(hex, 16) / max) * 255);
    return v.toString(16).padStart(2, "0");
  };
  return `#${byte(m[1]!)}${byte(m[2]!)}${byte(m[3]!)}`;
}

/**
 * Terminal background colour, once an OSC 11 query has answered. `null` means
 * unknown — under a pipe, a `dumb` terminal, or a terminal that never replies —
 * and every consumer must fall back to its palette's own page colour rather
 * than guessing.
 */
let background: { hex: string; mode: TerminalThemeMode } | null = null;

export function getTerminalBackgroundHex(): string | null {
  return background?.hex ?? null;
}

/**
 * The measured background AND the light/dark mode its own luminance implies.
 *
 * The pair travels together so a consumer can refuse to paint the colour under
 * a palette chosen for the OTHER mode. That is a real risk rather than a
 * theoretical one: the published mode can come from somewhere else entirely —
 * OpenTUI's own handshake, `COLORFGBG`, or an explicit `CLAUDISH_THEME` — and
 * cream under dark-mode foregrounds is unreadable, which is strictly worse than
 * the hardcoded page colour this replaces.
 */
export function getTerminalBackground(): { hex: string; mode: TerminalThemeMode } | null {
  return background;
}

/** Test seam — also cleared by {@link resetThemeModeForTests}. */
export function setTerminalBackgroundHex(hex: string | null): void {
  if (!hex) {
    background = null;
    return;
  }
  const mode = classifyOscBackground(
    `]11;rgb:${hex.slice(1, 3)}/${hex.slice(3, 5)}/${hex.slice(5, 7)}`
  );
  background = mode ? { hex, mode } : null;
}

/**
 * Ask the terminal for its background color (OSC 11) and classify it.
 *
 * Only runs when stdin AND stdout are TTYs — the query goes out on stdout and the
 * reply arrives on stdin, and under a pipe (claudish as a proxy inside Claude
 * Code) neither holds, so this can never inject escape sequences into a
 * conversation with another program's TUI.
 */
export async function queryTerminalThemeMode(timeoutMs = 150): Promise<TerminalThemeMode | null> {
  const stdin = process.stdin;
  const stdout = process.stdout;
  if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") return null;
  if (process.env.TERM === "dumb") return null;

  return await new Promise<TerminalThemeMode | null>((resolve) => {
    let buffer = "";
    let settled = false;
    const wasRaw = stdin.isRaw === true;

    const finish = (mode: TerminalThemeMode | null): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      stdin.off("data", onData);
      try {
        if (!wasRaw) stdin.setRawMode(false);
        stdin.pause();
      } catch {
        // Terminal went away mid-query; the mode result still stands.
      }
      resolve(mode);
    };

    const onData = (chunk: Buffer): void => {
      buffer += chunk.toString("latin1");
      // Reply ends with BEL or ST (ESC \).
      // biome-ignore lint/suspicious/noControlCharactersInRegex: the OSC 11 reply terminator IS a control char (BEL or ESC \)
      if (/\]11;[^\x07\x1b]*(\x07|\x1b\\)/.test(buffer)) {
        // Keep the COLOUR as well as the light/dark bit — the TUI paints its
        // page with it so the page matches the terminal exactly. Both are
        // derived from THIS reply, so they cannot disagree.
        const mode = classifyOscBackground(buffer);
        const hex = parseOscBackgroundHex(buffer);
        background = hex && mode ? { hex, mode } : null;
        finish(mode);
      }
    };

    const timer = setTimeout(() => finish(null), timeoutMs);

    try {
      if (!wasRaw) stdin.setRawMode(true);
      stdin.resume();
      stdin.on("data", onData);
      stdout.write("\x1b]11;?\x07");
    } catch {
      finish(null);
    }
  });
}

// ---------------------------------------------------------------------------
// The composed detector
// ---------------------------------------------------------------------------

/**
 * Detect and publish the terminal theme mode. Cheap sources first; the OSC
 * round-trip only runs when they were silent and both ends of the terminal are
 * ours. Call once, early, from interactive entry points. Safe to call again —
 * a second call just re-publishes.
 */
export async function detectAndSetThemeMode(): Promise<TerminalThemeMode | null> {
  const override = themeModeOverride();
  if (override) {
    // An explicit CLAUDISH_THEME is a choice of PALETTE, so the terminal's own
    // colour is not adopted — the user may well be forcing dark on a light
    // terminal, and painting their background under our dark foregrounds would
    // be unreadable. Skipping the OSC round-trip entirely is also free here.
    setTerminalBackgroundHex(null);
    setThemeMode(override);
    return override;
  }

  // OSC 11 IS AUTHORITATIVE, ABOVE COLORFGBG. It used to be the last resort,
  // short-circuited whenever COLORFGBG answered. Two measurements on a real
  // terminal overturned that ordering:
  //
  //   COLORFGBG="15;0"                     → "dark"   (bg slot 0 = black)
  //   OSC 11 reply, 19ms                   → "light", background #f9f6da
  //
  // The terminal is genuinely cream. COLORFGBG was simply WRONG — it is a hint
  // the emulator sets once, and tmux inherits a stale value that survives a
  // theme change. Believing it produced a dark palette on a light terminal AND
  // discarded the only accurate reading available.
  //
  // An OSC reply is a MEASUREMENT of the actual background, and it settles the
  // mode and the colour together, so the two can never contradict each other —
  // which is what made the previous "sources disagree" reconciliation
  // necessary. That reconciliation is gone with it.
  //
  // COLORFGBG remains the fallback for terminals that do not answer (and the
  // sync path, which cannot await, still has nothing else). Cost when nobody
  // answers is one bounded 150ms wait per interactive launch; the measured
  // reply here arrived in 19ms.
  const fromOsc = await queryTerminalThemeMode(150);
  if (fromOsc) {
    setThemeMode(fromOsc);
    return fromOsc;
  }

  const fromEnv = themeModeFromColorFgBg();
  setThemeMode(fromEnv);
  return fromEnv;
}

/**
 * Synchronous variant for paths that cannot await (no OSC round-trip). Publishes
 * only when a cheap source answered; otherwise leaves the current state alone.
 */
export function detectAndSetThemeModeSync(): TerminalThemeMode | null {
  const mode = themeModeOverride() ?? themeModeFromColorFgBg();
  if (mode) setThemeMode(mode);
  return mode ?? detected;
}