@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/renderer/term-caps.ts

@@ -0,0 +1,318 @@
+/**
+ * term-caps.ts — Terminal capability detection and color downsampling.
+ *
+ * Probes the terminal's color support level once at renderer init and exposes
+ * a `downsampleColor` function that maps hex/RGB color strings to the
+ * appropriate SGR parameter string for the detected capability level.
+ *
+ * Capability levels (in ascending order):
+ *   none      — NO_COLOR set or TERM=dumb; emit no SGR color sequences.
+ *   basic16   — 16 ANSI colors (\x1b[30-37m / \x1b[90-97m / \x1b[40-47m).
+ *   ansi256   — 256-color palette (\x1b[38;5;Nm).
+ *   truecolor — 24-bit RGB (\x1b[38;2;R;G;Bm).
+ *
+ * References:
+ *   - NO_COLOR spec: https://no-color.org/ (any non-empty value disables color)
+ *   - TERM=dumb: conventional dumb-terminal indicator
+ *   - getColorDepth(): Node.js WriteStream API returns 1/4/8/24
+ */
+
+export type ColorCapability = 'none' | 'basic16' | 'ansi256' | 'truecolor';
+
+export interface TermColorCaps {
+  capability: ColorCapability;
+  /**
+   * Whether to emit DEC Synchronized Output (mode 2026) markers.
+   * True when capability != 'none' and TERM != 'dumb'.
+   */
+  syncedOutput: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Capability probe
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe terminal color capabilities from environment and the write stream.
+ * Call once at compositor/renderer construction time.
+ *
+ * @param stdout - The writable stream for terminal output (process.stdout or mock).
+ */
+export function probeTermCaps(stdout: NodeJS.WriteStream): TermColorCaps {
+  // NO_COLOR: any non-empty value disables color, per https://no-color.org/
+  const noColor = process.env['NO_COLOR'];
+  if (noColor !== undefined && noColor !== '') {
+    return { capability: 'none', syncedOutput: false };
+  }
+
+  const term = process.env['TERM'] ?? '';
+  if (term === 'dumb') {
+    return { capability: 'none', syncedOutput: false };
+  }
+
+  // getColorDepth() returns bit depth: 1=none, 4=basic16, 8=ansi256, 24=truecolor
+  const depth: number = typeof stdout.getColorDepth === 'function'
+    ? stdout.getColorDepth()
+    : 1;
+
+  let capability: ColorCapability;
+  if (depth >= 24) {
+    capability = 'truecolor';
+  } else if (depth >= 8) {
+    capability = 'ansi256';
+  } else if (depth >= 4) {
+    capability = 'basic16';
+  } else {
+    capability = 'none';
+  }
+
+  const syncedOutput = capability !== 'none';
+  return { capability, syncedOutput };
+}
+
+// ---------------------------------------------------------------------------
+// Color parsing helpers
+// ---------------------------------------------------------------------------
+
+/** Parse "#rrggbb" → [r, g, b]. Returns null for invalid input. */
+function parseHex(hex: string): [number, number, number] | null {
+  if (hex.length === 7 && hex[0] === '#') {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    if (!isNaN(r) && !isNaN(g) && !isNaN(b)) return [r, g, b];
+  }
+  return null;
+}
+
+/**
+ * Parse a sanitized color string in one of two forms:
+ *   - "#rrggbb"  → RGB tuple
+ *   - "r;g;b"    → RGB tuple (already decomposed by sanitizeColor)
+ *   - "N"        → null (already a palette index — pass through)
+ * Returns [r, g, b] or null (non-RGB / palette index).
+ */
+function parseRgbString(color: string): [number, number, number] | null {
+  if (color.startsWith('#')) return parseHex(color);
+  if (color.includes(';')) {
+    const parts = color.split(';');
+    if (parts.length === 3) {
+      const r = parseInt(parts[0]!, 10);
+      const g = parseInt(parts[1]!, 10);
+      const b = parseInt(parts[2]!, 10);
+      if (!isNaN(r) && !isNaN(g) && !isNaN(b)) return [r, g, b];
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 256-color cube math
+// ---------------------------------------------------------------------------
+
+/**
+ * Map [r, g, b] (0-255 each) to the nearest xterm-256 palette index.
+ *
+ * The 256-color palette is structured as:
+ *   0-15:   System colors (16 named colors) — we avoid these for predictability
+ *           and instead target the 6×6×6 cube + grayscale ramp.
+ *   16-231: 6×6×6 color cube, index = 16 + 36*r6 + 6*g6 + b6
+ *           where r6/g6/b6 ∈ 0-5 map via [0,95,135,175,215,255]
+ *   232-255: Grayscale ramp, index = 232 + round((v - 8) / 10)
+ *            values: 8, 18, 28, ..., 238 (24 steps, step=10)
+ */
+const CUBE_STEPS = [0, 95, 135, 175, 215, 255] as const;
+
+function nearestCubeStep(v: number): number {
+  let best = 0;
+  let bestDist = Math.abs(v - CUBE_STEPS[0]!);
+  for (let i = 1; i < CUBE_STEPS.length; i++) {
+    const dist = Math.abs(v - CUBE_STEPS[i]!);
+    if (dist < bestDist) { bestDist = dist; best = i; }
+  }
+  return best;
+}
+
+function cubeIndex(r: number, g: number, b: number): number {
+  const r6 = nearestCubeStep(r);
+  const g6 = nearestCubeStep(g);
+  const b6 = nearestCubeStep(b);
+  return 16 + 36 * r6 + 6 * g6 + b6;
+}
+
+function grayscaleIndex(v: number): number {
+  // Grayscale ramp: 232..255, values 8,18,28,...,238
+  // index 232 = value 8, index 255 = value 238, step 10
+  const clamped = Math.max(8, Math.min(238, v));
+  return 232 + Math.round((clamped - 8) / 10);
+}
+
+function sqDist(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number): number {
+  return (r1 - r2) ** 2 + (g1 - g2) ** 2 + (b1 - b2) ** 2;
+}
+
+/**
+ * Find the nearest xterm-256 index for [r, g, b].
+ * Compares the nearest cube color vs the nearest grayscale color and picks best.
+ */
+export function nearestAnsi256(r: number, g: number, b: number): number {
+  const ci = cubeIndex(r, g, b);
+  const r6 = nearestCubeStep(r);
+  const g6 = nearestCubeStep(g);
+  const b6 = nearestCubeStep(b);
+  const cubeR = CUBE_STEPS[r6]!;
+  const cubeG = CUBE_STEPS[g6]!;
+  const cubeB = CUBE_STEPS[b6]!;
+  const cubeDist = sqDist(r, g, b, cubeR, cubeG, cubeB);
+
+  // Nearest grayscale step
+  const gray = Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b);
+  const gi = grayscaleIndex(gray);
+  const grayVal = 8 + (gi - 232) * 10;
+  const grayDist = sqDist(r, g, b, grayVal, grayVal, grayVal);
+
+  return grayDist < cubeDist ? gi : ci;
+}
+
+// ---------------------------------------------------------------------------
+// 16-color nearest-color table
+// ---------------------------------------------------------------------------
+
+/**
+ * Standard 16 ANSI colors. Each entry is [r, g, b, fgCode, bgCode].
+ * The fg code is the SGR parameter for foreground (30-37, 90-97);
+ * the bg code is 40 higher.
+ *
+ * These values approximate the most common terminal palettes (xterm defaults).
+ */
+const ANSI16_PALETTE: ReadonlyArray<readonly [number, number, number, number]> = [
+  // [r, g, b, SGR-fg-code]
+  [0,   0,   0,   30],  // 0: black
+  [170, 0,   0,   31],  // 1: red
+  [0,   170, 0,   32],  // 2: green
+  [170, 85,  0,   33],  // 3: yellow/brown
+  [0,   0,   170, 34],  // 4: blue
+  [170, 0,   170, 35],  // 5: magenta
+  [0,   170, 170, 36],  // 6: cyan
+  [170, 170, 170, 37],  // 7: light gray
+  [85,  85,  85,  90],  // 8: dark gray (bright black)
+  [255, 85,  85,  91],  // 9: bright red
+  [85,  255, 85,  92],  // 10: bright green
+  [255, 255, 85,  93],  // 11: bright yellow
+  [85,  85,  255, 94],  // 12: bright blue
+  [255, 85,  255, 95],  // 13: bright magenta
+  [85,  255, 255, 96],  // 14: bright cyan
+  [255, 255, 255, 97],  // 15: white
+];
+
+/**
+ * Find the nearest ANSI 16-color SGR foreground code for [r, g, b].
+ * Returns a number like 31 (red fg), 92 (bright green fg), etc.
+ */
+export function nearestAnsi16Fg(r: number, g: number, b: number): number {
+  let bestCode = 37;
+  let bestDist = Infinity;
+  for (const [pr, pg, pb, code] of ANSI16_PALETTE) {
+    const d = sqDist(r, g, b, pr!, pg!, pb!);
+    if (d < bestDist) { bestDist = d; bestCode = code!; }
+  }
+  return bestCode;
+}
+
+/**
+ * Convert an ANSI16 fg code to the corresponding bg code.
+ * fg 30-37 → bg 40-47; fg 90-97 → bg 100-107.
+ */
+function ansi16FgToBg(fgCode: number): number {
+  // Both ranges (30-37 and 90-97) shift by +10 to reach their bg equivalents
+  // (30-37 → 40-47, 90-97 → 100-107).
+  return fgCode + 10;
+}
+
+// ---------------------------------------------------------------------------
+// Public downsampler
+// ---------------------------------------------------------------------------
+
+/**
+ * Downsample a color for the given capability.
+ *
+ * @param rawColor - A color string as seen in Cell.fg / Cell.bg, before
+ *   sanitizeColor() decomposition. Supported forms:
+ *   - "#rrggbb"  hex
+ *   - "r;g;b"    pre-decomposed RGB (from sanitizeColor)
+ *   - "N"        already a palette index — returned as-is for ansi256/truecolor,
+ *                or omitted for none
+ *
+ * @param caps - The probed terminal capabilities.
+ * @param role - 'fg' or 'bg' — determines which SGR range to use for basic16.
+ *
+ * @returns The SGR parameter string suitable for embedding in \x1b[38;2;...m
+ *   (truecolor), \x1b[38;5;Nm (ansi256), \x1b[Nm (basic16 fg), etc.
+ *   Returns null when capability is 'none' (caller should skip the sequence).
+ *
+ * Caller usage:
+ *   const fg = downsampleColor(cell.fg, caps, 'fg');
+ *   if (fg !== null) {
+ *     const isRgb = fg.includes(';');  // truecolor path
+ *     style += isRgb ? `\x1b[38;2;${fg}m` : `\x1b[38;5;${fg}m`;
+ *   }
+ *
+ * For basic16 the caller must use a different SGR prefix — see applyStyles.
+ */
+export function downsampleColor(
+  rawColor: string,
+  caps: TermColorCaps,
+  role: 'fg' | 'bg',
+): string | null {
+  if (!rawColor) return null;
+  if (caps.capability === 'none') return null;
+
+  const rgb = parseRgbString(rawColor);
+
+  if (caps.capability === 'truecolor') {
+    // Pass hex through as r;g;b decomposed, pass r;g;b through as-is
+    if (rgb) return `${rgb[0]};${rgb[1]};${rgb[2]}`;
+    // Already a palette index — emit as 256-color
+    return rawColor; // caller will use 38;5;N or 48;5;N
+  }
+
+  if (caps.capability === 'ansi256') {
+    if (rgb) return String(nearestAnsi256(rgb[0], rgb[1], rgb[2]));
+    // Already a palette index — pass through
+    return rawColor;
+  }
+
+  // basic16
+  if (rgb) {
+    const fgCode = nearestAnsi16Fg(rgb[0], rgb[1], rgb[2]);
+    if (role === 'fg') return String(fgCode);
+    // bg: shift by 10 (30→40, 90→100)
+    return String(ansi16FgToBg(fgCode));
+  }
+  // Palette index in basic16 mode: map 256-color index to the nearest 16-color.
+  // We don't have the RGB for arbitrary palette indices here; treat as empty
+  // (the caller will skip the sequence rather than emit garbage).
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// DEC 2026 Synchronized Output helpers
+// ---------------------------------------------------------------------------
+
+/** DEC private mode 2026: begin synchronized update (suppress screen updates). */
+export const SYNC_BEGIN = '\x1b[?2026h';
+/** DEC private mode 2026: end synchronized update (flush to screen). */
+export const SYNC_END = '\x1b[?2026l';
+
+/**
+ * Wrap a diff string in DEC 2026 synchronized-update markers if the
+ * terminal supports it.
+ *
+ * @param diff - The raw ANSI diff string.
+ * @param caps - The probed terminal capabilities.
+ * @returns The diff string, optionally wrapped.
+ */
+export function wrapSynced(diff: string, caps: TermColorCaps): string {
+  if (!diff || !caps.syncedOutput) return diff;
+  return `${SYNC_BEGIN}${diff}${SYNC_END}`;
+}

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

@@ -0,0 +1,373 @@
+/**
+ * terminal-bg-probe — OSC 11 terminal-background detection for `auto` theme mode.
+ *
+ * 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 here is best-effort and conservative: any timeout, any
+ * unparseable reply, any ambiguity resolves to DARK, the historical default,
+ * which keeps headless/unsupported terminals byte-stable.
+ *
+ * Timing (render dark first, repaint once if light wins): the probe never blocks
+ * startup. The first frame renders in dark; if a light reply arrives within the
+ * timeout the caller flips the active mode to light and repaints ONCE. This adds
+ * zero startup latency and costs at most one dark→light repaint on genuinely
+ * light terminals.
+ *
+ * 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. 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 bytes never leak into the
+ * input pipeline.
+ *
+ * tmux: when $TMUX is set the query is wrapped in the DCS passthrough envelope so
+ * the outer terminal sees it. This only elicits a reply if `allow-passthrough`
+ * is enabled; otherwise the query is swallowed and the timeout fallback (dark)
+ * covers it silently.
+ *
+ * W4-R2 adaptation (agent): the theme-application coupling is INJECTED rather
+ * than imported from theme.ts. R2 owns this module; R4 owns the theme system
+ * (theme.ts / theme-mode-config.ts) and wires installBackgroundThemeProbe with
+ * `applyThemeMode: setActiveThemeMode`. Keeping the coupling injected lets R2
+ * land the probe (and its stream-safety guarantees) before R4's theme.ts exists.
+ */
+
+import type { ConfigKey, ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/** Resolved appearance mode. R4's theme.ts converges on this literal union. */
+export type ThemeMode = 'light' | 'dark';
+
+/** The stored appearance preference (config `display.themeMode`). */
+export type ThemeModeSetting = 'auto' | ThemeMode;
+
+/** Config key backing the appearance/theme-mode preference. */
+export const THEME_MODE_CONFIG_KEY = 'display.themeMode';
+
+/** Default when unset: probe the terminal background on startup. */
+export const THEME_MODE_DEFAULT: ThemeModeSetting = 'auto';
+
+/** 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. `display` exists in the SDK
+ * DEFAULT_CONFIG, so get() returns undefined for the absent field rather than
+ * throwing; any unexpected error resolves to the honest default.
+ */
+export function resolveConfiguredThemeMode(
+  configManager: Pick<ConfigManager, 'get'>,
+): ThemeModeSetting {
+  try {
+    return coerceThemeModeSetting(configManager.get(THEME_MODE_CONFIG_KEY as ConfigKey));
+  } catch {
+    return THEME_MODE_DEFAULT;
+  }
+}
+
+/** 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). 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.
+ */
+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'>;
+  /**
+   * Applies the resolved appearance mode (R2 injection point — R4 passes its
+   * theme.ts setActiveThemeMode). Called before the first paint for a forced
+   * mode, or once on a light OSC 11 reply.
+   */
+  readonly applyThemeMode: (mode: ThemeMode) => void;
+  /** 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  → apply immediately (before first paint); no probe.
+ *   - auto + TTY  → leave dark, fire the OSC 11 query, and on a light reply apply
+ *                   light + repaint once.
+ *   - 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') {
+    options.applyThemeMode(pref);
+    return { filterInput: (chunk) => chunk };
+  }
+
+  // pref === 'auto'
+  if (!options.isTTY) {
+    options.applyThemeMode('dark');
+    return { filterInput: (chunk) => chunk };
+  }
+
+  const probe = new TerminalBackgroundProbe({
+    timeoutMs: options.timeoutMs,
+    onResolve: (result) => {
+      if (result.mode === 'light') {
+        options.applyThemeMode('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) };
+}