@pellux/goodvibes-tui 2.0.21 → 2.1.1

package/src/renderer/syntax-theme.ts

@@ -0,0 +1,51 @@
+/**
+ * syntax-theme.ts, the one role -> colour map for code.
+ *
+ * Both highlighters resolve through here: the tree-sitter path
+ * (syntax-highlighter.ts, NODE_TYPE_COLORS holds roles, not colours) and the
+ * regex fallback (code-block.ts). So a code block looks the same whichever
+ * path rendered it, and both follow the active theme.
+ */
+
+import { activeTokens, type PaletteTokens } from './theme.ts';
+
+/** A syntax colour role. `plain` is text with no specific role. */
+export type SyntaxRole =
+  | 'keyword'
+  | 'string'
+  | 'number'
+  | 'comment'
+  | 'function'
+  | 'type'
+  | 'operator'
+  | 'property'
+  | 'builtin'
+  | 'plain';
+
+export interface SyntaxStyle {
+  readonly fg: string;
+  readonly italic?: boolean;
+}
+
+const stylesByPalette = new WeakMap<PaletteTokens, Readonly<Record<SyntaxRole, SyntaxStyle>>>();
+
+/** Role styles for a token table (memoized per table; defaults to the active theme). */
+export function syntaxStyles(tokens: Readonly<PaletteTokens> = activeTokens()): Readonly<Record<SyntaxRole, SyntaxStyle>> {
+  const cached = stylesByPalette.get(tokens);
+  if (cached !== undefined) return cached;
+  const styles: Record<SyntaxRole, SyntaxStyle> = {
+    keyword: { fg: tokens.syntaxKeyword },
+    string: { fg: tokens.syntaxString },
+    number: { fg: tokens.syntaxNumber },
+    comment: { fg: tokens.syntaxComment, italic: true },
+    function: { fg: tokens.syntaxFunction },
+    type: { fg: tokens.syntaxType },
+    operator: { fg: tokens.syntaxOperator },
+    property: { fg: tokens.syntaxProperty },
+    builtin: { fg: tokens.syntaxBuiltin },
+    plain: { fg: tokens.text },
+  };
+  Object.freeze(styles);
+  stylesByPalette.set(tokens, styles);
+  return styles;
+}

package/src/renderer/system-message.ts

@@ -94,6 +94,5 @@ export function renderSystemMessage(
   return renderConversationNotice(content, width, {
     accent,
     text: textColor,
-    dim: msgType === 'info',
   }, border.char);
 }

package/src/renderer/term-caps.ts

@@ -56,7 +56,7 @@ export function probeTermCaps(stdout: NodeJS.WriteStream): TermColorCaps {
     : 1;
 
   let capability: ColorCapability;
-  if (depth >= 24) {
+  if (depth >= 24 || (depth >= 8 && advertisesTruecolor(process.env))) {
     capability = 'truecolor';
   } else if (depth >= 8) {
     capability = 'ansi256';
@@ -70,6 +70,47 @@ export function probeTermCaps(stdout: NodeJS.WriteStream): TermColorCaps {
   return { capability, syncedOutput };
 }
 
+/** TERM values of terminals that draw 24-bit color without saying so in COLORTERM. */
+const TRUECOLOR_TERMS: ReadonlySet<string> = new Set([
+  'xterm-ghostty', 'xterm-kitty', 'alacritty', 'foot', 'foot-extra', 'wezterm', 'contour', 'rio', 'xterm-direct',
+]);
+
+/** TERM_PROGRAM values of terminals that draw 24-bit color. */
+const TRUECOLOR_PROGRAMS: ReadonlySet<string> = new Set([
+  'ghostty', 'wezterm', 'iterm.app', 'vscode', 'hyper', 'tabby', 'rio', 'warpterminal',
+]);
+
+/**
+ * Whether the environment says the terminal draws 24-bit color. The stream's
+ * own depth check only trusts COLORTERM and a short list, so it reports 256
+ * colors for Ghostty, kitty, Alacritty and foot, and a 256-color downsample
+ * turns every gradient into visible bands. This reads COLORTERM
+ * (truecolor / 24bit), a TERM ending in "-direct" (the terminfo convention for
+ * direct color), and TERM / TERM_PROGRAM values of terminals known to draw it.
+ */
+function advertisesTruecolor(env: Readonly<Record<string, string | undefined>>): boolean {
+  const colorterm = (env['COLORTERM'] ?? '').toLowerCase();
+  if (colorterm === 'truecolor' || colorterm === '24bit') return true;
+  const term = (env['TERM'] ?? '').toLowerCase();
+  if (term.endsWith('-direct') || TRUECOLOR_TERMS.has(term)) return true;
+  return TRUECOLOR_PROGRAMS.has((env['TERM_PROGRAM'] ?? '').toLowerCase());
+}
+
+/**
+ * Whether the terminal can draw unicode (box drawing, beads, triangles), read
+ * from the environment: TERM=dumb cannot, and a locale naming a charset other
+ * than UTF-8 (including C and POSIX) cannot. No locale variables at all counts
+ * as capable, which is what modern terminal emulators report in practice.
+ * The conversation work tree draws ascii on a terminal this reports as limited.
+ */
+export function probeUnicodeSupport(env: Readonly<Record<string, string | undefined>> = process.env): boolean {
+  if ((env['TERM'] ?? '') === 'dumb') return false;
+  const locale = env['LC_ALL'] || env['LC_CTYPE'] || env['LANG'] || '';
+  if (locale === '') return true;
+  if (locale === 'C' || locale === 'POSIX') return false;
+  return /utf-?8/i.test(locale);
+}
+
 // ---------------------------------------------------------------------------
 // Color parsing helpers
 // ---------------------------------------------------------------------------

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * 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
@@ -27,15 +27,29 @@
  *   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.
+ *   The query goes out as it is. tmux answers OSC 10 / 11 / 4 itself from the
+ *   attached terminal's colours; the DCS passthrough envelope this used to use
+ *   is discarded unless allow-passthrough is on (off by default). A query
+ *   written while no client is attached is dropped by tmux, which is what the
+ *   palette reader's retries are for.
+ *
+ * Palette (opt-in via `probePalette`):
+ *   OSC 10 (foreground) and OSC 4;0..15 ride in the same write, after the OSC 11
+ *   query. This probe's filter runs first and hands the OSC 11 body to the
+ *   palette reader (terminal-palette-reader.ts), whose round consumes the other
+ *   17 replies within a 175 ms window (150 ms + 25 ms margin) and stores the
+ *   result via terminal-palette.ts. A round with no colours is retried; a late
+ *   palette re-themes and, in auto mode after a background timeout, settles
+ *   light vs dark. With `probePalette` unset the bytes written and the
+ *   filtering are exactly as described above.
  */
 
-import { setActiveThemeMode, type ThemeMode } from './theme.ts';
-import { resolveConfiguredThemeMode } from './theme-mode-config.ts';
+import { refreshForTerminalPalette, setActiveThemeMode, setActiveThemeName, type ThemeMode } from './theme.ts';
+import { resolveConfiguredThemeMode, resolveConfiguredThemeName } from './theme-mode-config.ts';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { PALETTE_QUERIES, type PaletteProbeResolution } from './terminal-palette-probe.ts';
+import { TerminalPaletteReader, type TerminalPaletteReaderOptions } from './terminal-palette-reader.ts';
+import { setTerminalPalette } from './terminal-palette.ts';
 
 /** OSC 11 "query background colour" request, ST-terminated. */
 export const OSC11_QUERY = '\x1b]11;?\x1b\\';
@@ -172,6 +186,12 @@ export interface TerminalBackgroundProbeOptions {
   readonly onResolve: (result: ProbeResolution) => void;
   /** Probe window in ms (default DEFAULT_PROBE_TIMEOUT_MS). */
   readonly timeoutMs?: number;
+  /**
+   * Observer for the raw body of a complete OSC 11 reply (before
+   * classification). The palette probe uses it to record the background
+   * colour, since this filter consumes the reply ahead of it.
+   */
+  readonly onReplySpec?: (spec: string) => void;
 }
 
 /**
@@ -187,10 +207,12 @@ export class TerminalBackgroundProbe {
   private resolved = false;
   private timer: ReturnType<typeof setTimeout> | null = null;
   private readonly onResolve: (result: ProbeResolution) => void;
+  private readonly onReplySpec: ((spec: string) => void) | undefined;
   private readonly timeoutMs: number;
 
   constructor(options: TerminalBackgroundProbeOptions) {
     this.onResolve = options.onResolve;
+    this.onReplySpec = options.onReplySpec;
     this.timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
   }
 
@@ -235,6 +257,7 @@ export class TerminalBackgroundProbe {
       // 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);
+      this.onReplySpec?.(spec);
       const rgb = parseColorSpec(spec);
       if (rgb === null) {
         this.resolve('dark', 'unparseable');
@@ -267,14 +290,9 @@ export class TerminalBackgroundProbe {
 }
 
 // ---------------------------------------------------------------------------
-// tmux passthrough + install entry
+// 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. */
@@ -285,8 +303,6 @@ 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. */
@@ -295,6 +311,23 @@ export interface InstallThemeProbeOptions {
   readonly timeoutMs?: number;
   /** Optional resolution observer (tests / diagnostics). */
   readonly onResolve?: (result: ProbeResolution) => void;
+  /**
+   * Also read the terminal palette (OSC 10 + OSC 4;0..15) in the same write as
+   * the OSC 11 query, and keep asking until it arrives (terminal-palette-reader.ts).
+   * Runs on a TTY in every appearance mode; the result lands in the
+   * terminal-palette store. Default false (query bytes unchanged).
+   */
+  readonly probePalette?: boolean;
+  /** Palette window override (tests). Default PALETTE_PROBE_TIMEOUT_MS. */
+  readonly paletteTimeoutMs?: number;
+  /** Optional palette round observer (tests / diagnostics). */
+  readonly onPaletteResolve?: (result: PaletteProbeResolution) => void;
+  /** Palette retry tuning (tests). */
+  readonly paletteRetry?: Pick<TerminalPaletteReaderOptions, 'retryDelayMs' | 'maxRounds' | 'minRoundSpacingMs' | 'now'>;
+  /** Where an Esc / Alt+] key held at a palette round's close goes (the input pipeline). */
+  readonly forwardInput?: (bytes: string) => void;
+  /** Subscribe to terminal resizes (a client attaching); retries an unanswered palette read. */
+  readonly subscribeResize?: (listener: () => void) => void;
 }
 
 /**
@@ -305,13 +338,32 @@ export interface InstallThemeProbeOptions {
  *   - 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.
+ *
+ * The queries are always written as they are, never wrapped for tmux
+ * passthrough: tmux answers OSC 10, OSC 11 and OSC 4 itself from the attached
+ * terminal's colours, while a passthrough envelope is discarded unless the
+ * user turned allow-passthrough on (it is off by default), which left every
+ * tmux user without a palette.
  */
 export function installBackgroundThemeProbe(options: InstallThemeProbeOptions): ThemeProbeHandle {
   const pref = resolveConfiguredThemeMode(options.configManager);
+  // The configured theme applies before the first paint; the mode below
+  // (forced, or dark until the probe answers) completes the resolution.
+  setActiveThemeName(resolveConfiguredThemeName(options.configManager));
+  let backgroundTimedOut = false;
+  const palette = options.probePalette === true && options.isTTY
+    ? createPaletteReader(options, pref, () => backgroundTimedOut)
+    : null;
+  if (palette !== null) options.subscribeResize?.(() => palette.noteResize());
 
   if (pref === 'dark' || pref === 'light') {
     setActiveThemeMode(pref);
-    return { filterInput: (chunk) => chunk };
+    if (palette === null) return { filterInput: (chunk) => chunk };
+    // Forced mode: no background classification, but the palette batch (which
+    // still carries OSC 11 for the background colour) goes out and the
+    // reader's filter consumes every reply.
+    palette.start();
+    return { filterInput: (chunk) => palette.feed(chunk) };
   }
 
   // pref === 'auto'
@@ -322,7 +374,9 @@ export function installBackgroundThemeProbe(options: InstallThemeProbeOptions):
 
   const probe = new TerminalBackgroundProbe({
     timeoutMs: options.timeoutMs,
+    onReplySpec: palette === null ? undefined : (spec) => palette.noteBackgroundSpec(spec),
     onResolve: (result) => {
+      backgroundTimedOut = result.reason === 'timeout';
       if (result.mode === 'light') {
         setActiveThemeMode('light');
         options.requestRepaint();
@@ -331,9 +385,52 @@ export function installBackgroundThemeProbe(options: InstallThemeProbeOptions):
     },
   });
 
-  const query = options.env['TMUX'] ? wrapForTmuxPassthrough(OSC11_QUERY) : OSC11_QUERY;
-  options.writeQuery(query);
+  if (palette === null) {
+    options.writeQuery(OSC11_QUERY);
+    probe.startTimeout();
+    return { filterInput: (chunk) => (probe.active ? probe.feed(chunk) : chunk) };
+  }
+
+  // One write: OSC 11 first (so the background reply arrives first and the
+  // background probe's timing is unchanged), then OSC 10 and OSC 4;0..15.
+  palette.start();
   probe.startTimeout();
+  return {
+    filterInput: (chunk) => {
+      const afterBackground = probe.active ? probe.feed(chunk) : chunk;
+      return palette.feed(afterBackground);
+    },
+  };
+}
 
-  return { filterInput: (chunk) => (probe.active ? probe.feed(chunk) : chunk) };
+/**
+ * Palette reader whose result is stored beside the background probe's. In auto
+ * mode a palette that arrives after the background probe timed out (tmux with
+ * no client attached yet) still settles light vs dark from its background.
+ */
+function createPaletteReader(
+  options: InstallThemeProbeOptions,
+  pref: ThemeMode | 'auto',
+  backgroundTimedOut: () => boolean,
+): TerminalPaletteReader {
+  return new TerminalPaletteReader({
+    ...options.paletteRetry,
+    timeoutMs: options.paletteTimeoutMs,
+    writeBatch: () => options.writeQuery(OSC11_QUERY + PALETTE_QUERIES),
+    onFlush: options.forwardInput,
+    onRoundResolve: (result) => options.onPaletteResolve?.(result),
+    onPalette: (result) => {
+      setTerminalPalette(result);
+      let repaint = refreshForTerminalPalette();
+      if (pref === 'auto' && backgroundTimedOut() && result.background !== undefined) {
+        const rgb = parseColorSpec(result.background);
+        if (rgb !== null && classifyBackgroundLuminance(rgb) === 'light') {
+          setActiveThemeMode('light');
+          repaint = true;
+        }
+      }
+      // The system theme is generated from this palette: re-resolve and repaint.
+      if (repaint) options.requestRepaint();
+    },
+  });
 }

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

@@ -0,0 +1,322 @@
+/**
+ * terminal-palette-probe, reads the terminal's foreground and 16 ANSI colours.
+ *
+ * The queries (OSC 10 foreground, OSC 4;0..15 palette) go out in the SAME write
+ * as the existing OSC 11 background query (see installBackgroundThemeProbe in
+ * terminal-bg-probe.ts), so the whole batch costs one write and one round trip.
+ * Terminals answer in request order: OSC 11 first, which keeps the background
+ * probe's timing exactly as before, then OSC 10, then OSC 4;0..15.
+ *
+ * Budget:
+ *   The collection window is PALETTE_PROBE_TIMEOUT_MS = 175 ms, which is the
+ *   background probe's 150 ms (DEFAULT_PROBE_TIMEOUT_MS) plus a 25 ms margin
+ *   (PALETTE_PROBE_MARGIN_MS) for the 17 replies queued behind the OSC 11 one.
+ *   Both windows start from the same write. Nothing blocks on it: first paint
+ *   is not delayed, the only cost is that the stdin filter stays in front of the
+ *   input pipeline for at most 25 ms longer than before. A terminal that
+ *   answers all 18 queries ends the window early (typically single-digit ms).
+ *
+ * Stream safety mirrors the background probe: only matched OSC 4 / OSC 10 /
+ * OSC 11 replies are consumed, every other byte passes through in order, a
+ * reply split across chunks is held until complete, and on timeout any held
+ * reply fragment is discarded rather than flushed into the composer.
+ *
+ * This module deliberately imports nothing from terminal-bg-probe.ts (that file
+ * imports this one), so the two never form an import cycle.
+ */
+
+import {
+  emptyTerminalPalette,
+  TERMINAL_PALETTE_ANSI_SLOTS,
+  type TerminalPalette,
+} from './terminal-palette.ts';
+
+/** OSC 10 "query default foreground colour", ST-terminated. */
+const OSC10_QUERY = '\x1b]10;?\x1b\\';
+
+/** OSC 4 "query palette entry N", ST-terminated. */
+function osc4Query(index: number): string {
+  return `\x1b]4;${index};?\x1b\\`;
+}
+
+/** OSC 10 followed by OSC 4;0 .. OSC 4;15, appended after the OSC 11 query. */
+export const PALETTE_QUERIES: string = OSC10_QUERY
+  + Array.from({ length: TERMINAL_PALETTE_ANSI_SLOTS }, (_, i) => osc4Query(i)).join('');
+
+/** Extra time the palette window stays open past the background probe window. */
+const PALETTE_PROBE_MARGIN_MS = 25;
+
+/** Palette collection window: background probe window (150 ms) + margin (25 ms). */
+export const PALETTE_PROBE_TIMEOUT_MS = 150 + PALETTE_PROBE_MARGIN_MS;
+
+// ---------------------------------------------------------------------------
+// Pure parsing
+// ---------------------------------------------------------------------------
+
+/** Scale a 1..4 digit hex channel to 8 bits against its own full scale. */
+function channelTo8Bit(hex: string): number | null {
+  if (!/^[0-9a-fA-F]{1,4}$/.test(hex)) return null;
+  const max = 16 ** hex.length - 1;
+  return Math.round((parseInt(hex, 16) / max) * 255);
+}
+
+function toHexByte(value: number): string {
+  return value.toString(16).padStart(2, '0');
+}
+
+/**
+ * Parse an OSC colour reply body into `#rrggbb`. Accepts `rgb:R/G/B` with 1 to
+ * 4 hex digits per channel (each channel scaled by its own width, so `f`, `ff`,
+ * `fff`, `ffff` all give `ff`), `rgba:R/G/B/A` (alpha ignored), and `#rrggbb` /
+ * `#rrrrggggbbbb`. Returns null for anything else.
+ */
+export function parseOscColorToHex(spec: string): string | null {
+  const trimmed = spec.trim();
+  let channels: string[];
+
+  if (trimmed.startsWith('rgb:') || trimmed.startsWith('rgba:')) {
+    const parts = trimmed.slice(trimmed.indexOf(':') + 1).split('/');
+    const expected = trimmed.startsWith('rgba:') ? 4 : 3;
+    if (parts.length !== expected) return null;
+    channels = parts.slice(0, 3);
+  } else if (trimmed.startsWith('#')) {
+    const hex = trimmed.slice(1);
+    if (hex.length !== 6 && hex.length !== 12) return null;
+    const per = hex.length / 3;
+    channels = [hex.slice(0, per), hex.slice(per, per * 2), hex.slice(per * 2)];
+  } else {
+    return null;
+  }
+
+  const values = channels.map(channelTo8Bit);
+  if (values.some((v) => v === null)) return null;
+  return `#${(values as number[]).map(toHexByte).join('')}`;
+}
+
+/** Start of a reply we own: ESC ] 4 ; N ;  or  ESC ] 10 ;  or  ESC ] 11 ; */
+const REPLY_INTRODUCER = /\x1b\](?:4;(\d{1,3});|(1[01]);)/;
+
+/** A buffer tail that could still grow into REPLY_INTRODUCER. */
+const PARTIAL_INTRODUCER = /\x1b(?:\](?:4(?:;\d{0,3})?|1[01]?)?)?$/;
+
+/** Length of a trailing partial introducer to hold back, or 0. */
+function trailingPartialLen(buffer: string): number {
+  const esc = buffer.lastIndexOf('\x1b');
+  if (esc === -1) return 0;
+  const tail = buffer.slice(esc);
+  const m = PARTIAL_INTRODUCER.exec(tail);
+  return m !== null && m.index === 0 ? tail.length : 0;
+}
+
+/**
+ * OSC string terminator at/after `from`: BEL or ST (ESC \). Same rules as the
+ * background probe: a lone trailing ESC waits for the next byte; an ESC followed
+ * by anything other than `\` ends the body (malformed terminator).
+ */
+function findTerminator(buffer: string, from: number): { start: number; end: number } | 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;
+}
+
+// ---------------------------------------------------------------------------
+// TerminalPaletteProbe, the stateful stream filter
+// ---------------------------------------------------------------------------
+
+export interface PaletteProbeResolution {
+  /** Collected colours; unanswered or unparseable slots are undefined. */
+  readonly palette: TerminalPalette;
+  /** 'complete' when all 18 replies arrived, 'timeout' when the window closed. */
+  readonly reason: 'complete' | 'timeout';
+  /** How many of the 18 queries got a reply (parseable or not). */
+  readonly replies: number;
+}
+
+export interface TerminalPaletteProbeOptions {
+  /** Called exactly once, on completion or timeout. */
+  readonly onResolve: (result: PaletteProbeResolution) => void;
+  /** Window in ms (default PALETTE_PROBE_TIMEOUT_MS). */
+  readonly timeoutMs?: number;
+  /**
+   * Receives a key held at the window's close that never became a reply: a
+   * lone ESC (Esc) or ESC ] (Alt+]). Without it they are dropped, which is
+   * tolerable for the startup window only; a retry round can open while the
+   * user is typing.
+   */
+  readonly onFlush?: (bytes: string) => void;
+}
+
+/** Total replies expected: background + foreground + 16 ANSI slots. */
+const EXPECTED_REPLIES = 2 + TERMINAL_PALETTE_ANSI_SLOTS;
+
+/**
+ * Stateful OSC 4 / 10 / 11 reply filter. feed() takes a raw stdin chunk and
+ * returns the bytes that continue down the input pipeline. The background
+ * probe, when it runs in front of this filter and consumes the OSC 11 reply,
+ * hands the reply body over with noteBackgroundSpec().
+ */
+export class TerminalPaletteProbe {
+  /** True until resolved. */
+  public active = true;
+
+  private buffer = '';
+  private resolved = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private readonly palette: TerminalPalette = emptyTerminalPalette();
+  private backgroundAnswered = false;
+  private foregroundAnswered = false;
+  private readonly ansiAnswered = new Array<boolean>(TERMINAL_PALETTE_ANSI_SLOTS).fill(false);
+  private readonly onResolve: (result: PaletteProbeResolution) => void;
+  private readonly onFlush: ((bytes: string) => void) | undefined;
+  private readonly timeoutMs: number;
+
+  constructor(options: TerminalPaletteProbeOptions) {
+    this.onResolve = options.onResolve;
+    this.onFlush = options.onFlush;
+    this.timeoutMs = options.timeoutMs ?? PALETTE_PROBE_TIMEOUT_MS;
+  }
+
+  /** Arm the window. Call right after writing the batched query. */
+  startTimeout(): void {
+    this.timer = setTimeout(() => this.resolve('timeout'), this.timeoutMs);
+    (this.timer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  /** Record an OSC 11 reply body consumed upstream by the background probe. */
+  noteBackgroundSpec(spec: string): void {
+    if (!this.active) return;
+    this.recordBackground(spec);
+    if (this.isComplete()) this.resolve('complete');
+  }
+
+  /** Consume a raw stdin chunk; returns the passthrough bytes. */
+  feed(chunk: string): string {
+    if (!this.active) return chunk;
+    this.buffer += chunk;
+    let out = '';
+
+    for (;;) {
+      const m = REPLY_INTRODUCER.exec(this.buffer);
+      if (m === null) {
+        const keep = trailingPartialLen(this.buffer);
+        out += this.buffer.slice(0, this.buffer.length - keep);
+        this.buffer = keep > 0 ? this.buffer.slice(this.buffer.length - keep) : '';
+        break;
+      }
+
+      out += this.buffer.slice(0, m.index);
+      const bodyStart = m.index + m[0].length;
+      const term = findTerminator(this.buffer, bodyStart);
+      if (term === null) {
+        this.buffer = this.buffer.slice(m.index);
+        break;
+      }
+
+      const spec = this.buffer.slice(bodyStart, term.start);
+      if (m[1] !== undefined) this.recordAnsi(Number(m[1]), spec);
+      else if (m[2] === '10') this.recordForeground(spec);
+      else this.recordBackground(spec);
+      this.buffer = this.buffer.slice(term.end);
+
+      if (this.isComplete()) {
+        // Keep the post-reply bytes before resolve() clears the buffer.
+        const remainder = this.buffer;
+        this.resolve('complete');
+        out += remainder;
+        break;
+      }
+    }
+
+    return out;
+  }
+
+  private recordBackground(spec: string): void {
+    this.backgroundAnswered = true;
+    this.palette.background = parseOscColorToHex(spec) ?? undefined;
+  }
+
+  private recordForeground(spec: string): void {
+    this.foregroundAnswered = true;
+    this.palette.foreground = parseOscColorToHex(spec) ?? undefined;
+  }
+
+  private recordAnsi(index: number, spec: string): void {
+    // Replies for slots we never asked about are still consumed, not recorded.
+    if (index < 0 || index >= TERMINAL_PALETTE_ANSI_SLOTS) return;
+    this.ansiAnswered[index] = true;
+    this.palette.ansi[index] = parseOscColorToHex(spec) ?? undefined;
+  }
+
+  private replyCount(): number {
+    return (this.backgroundAnswered ? 1 : 0)
+      + (this.foregroundAnswered ? 1 : 0)
+      + this.ansiAnswered.filter(Boolean).length;
+  }
+
+  private isComplete(): boolean {
+    return this.replyCount() === EXPECTED_REPLIES;
+  }
+
+  private resolve(reason: PaletteProbeResolution['reason']): void {
+    if (this.resolved) return;
+    this.resolved = true;
+    this.active = false;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    // A held reply fragment is discarded, never flushed into the composer.
+    // The two holds that are real keys (Esc, Alt+]) are handed on.
+    const held = this.buffer;
+    this.buffer = '';
+    if (held === '\x1b' || held === '\x1b]') this.onFlush?.(held);
+    this.onResolve({
+      palette: { ...this.palette, ansi: [...this.palette.ansi] },
+      reason,
+      replies: this.replyCount(),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Late replies (outside any collection window)
+// ---------------------------------------------------------------------------
+
+/** One reply found by sweepPaletteReplies. */
+export interface PaletteReply {
+  readonly slot: 'background' | 'foreground' | number;
+  /** `#rrggbb`, or undefined when the body did not parse. */
+  readonly hex: string | undefined;
+}
+
+/**
+ * Remove complete OSC 4 / 10 / 11 replies from a chunk that arrived outside a
+ * collection window (a reply slower than the window, over ssh or a busy
+ * multiplexer). Unlike the probe's own filter this never holds bytes back: a
+ * reply split across chunks passes through, so a lone Esc key is never
+ * delayed. Replies are complete in one read in practice.
+ */
+export function sweepPaletteReplies(chunk: string): { readonly out: string; readonly replies: PaletteReply[] } {
+  if (!chunk.includes('\x1b]')) return { out: chunk, replies: [] };
+  const replies: PaletteReply[] = [];
+  let rest = chunk;
+  let out = '';
+  for (;;) {
+    const m = REPLY_INTRODUCER.exec(rest);
+    if (m === null) break;
+    const term = findTerminator(rest, m.index + m[0].length);
+    if (term === null) break;
+    const hex = parseOscColorToHex(rest.slice(m.index + m[0].length, term.start)) ?? undefined;
+    const slot = m[1] !== undefined ? Number(m[1]) : m[2] === '10' ? 'foreground' : 'background';
+    if (typeof slot !== 'number' || slot < TERMINAL_PALETTE_ANSI_SLOTS) replies.push({ slot, hex });
+    out += rest.slice(0, m.index);
+    rest = rest.slice(term.end);
+  }
+  return { out: out + rest, replies };
+}