@agi-fans/dsh-tui 0.21.0 → 0.22.0

package/lib/chrome/terminal-colors.js

@@ -0,0 +1,230 @@
+/**
+ * Colors the terminal reports about itself (OSC 10 foreground, OSC 11
+ * background, OSC 4 palette entries, CSI ?997 color scheme) and the perceptual
+ * math used to adapt a palette to them.
+ *
+ * A terminal only answers these when it is interactive and willing; every
+ * helper here is pure so a caller can probe once, keep whatever arrived, and
+ * fall back to the shipped palettes when nothing did.
+ * @module @agi-fans/dsh-tui/terminal-colors
+ */
+/**
+ * Query the default foreground, background and all sixteen palette entries.
+ * `ST` terminates instead of `BEL` because a query is written before the
+ * terminal has proven it understands either form.
+ */
+export const COLOR_QUERY = '\x1b]10;?\x1b\\\x1b]11;?\x1b\\'
+    + Array.from({ length: 16 }, (_, index) => `\x1b]4;${index};?\x1b\\`).join('');
+/** Query whether the terminal considers itself dark or light (CSI ?997). */
+export const COLOR_SCHEME_QUERY = '\x1b[?997;?n';
+const OSC_COLOR_REPLY = /^(?:1([01])|4;(\d{1,3}));(.+)$/u;
+const HEX6 = /^#([0-9a-f]{6})$/iu;
+const HEX12 = /^#([0-9a-f]{12})$/iu;
+const RGB_SPEC = /^rgba?:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})$/iu;
+function channel(hex) {
+    return Math.round((Number.parseInt(hex, 16) / (16 ** hex.length - 1)) * 255);
+}
+/** Parse one OSC 10/11/4 reply body (the text between the introducer and the terminator). */
+export function parseOscColorReply(body) {
+    const match = OSC_COLOR_REPLY.exec(body);
+    if (match === null)
+        return undefined;
+    const target = match[1] === '0' ? 'foreground'
+        : match[1] === '1' ? 'background'
+            : Number.parseInt(match[2] ?? '', 10);
+    if (typeof target === 'number' && !(target >= 0 && target <= 15))
+        return undefined;
+    const color = parseColorSpec(match[3] ?? '');
+    return color === undefined ? { target } : { target, color };
+}
+/** Parse the color spec a terminal uses in a color reply (`#rrggbb`, `#rrrrggggbbbb`, `rgb:r/g/b`). */
+export function parseColorSpec(spec) {
+    const value = spec.trim();
+    const hex6 = HEX6.exec(value);
+    if (hex6 !== null) {
+        const hex = hex6[1];
+        return { r: Number.parseInt(hex.slice(0, 2), 16), g: Number.parseInt(hex.slice(2, 4), 16), b: Number.parseInt(hex.slice(4, 6), 16) };
+    }
+    const hex12 = HEX12.exec(value);
+    if (hex12 !== null) {
+        const hex = hex12[1];
+        return { r: channel(hex.slice(0, 4)), g: channel(hex.slice(4, 8)), b: channel(hex.slice(8, 12)) };
+    }
+    const rgb = RGB_SPEC.exec(value);
+    if (rgb !== null)
+        return { r: channel(rgb[1]), g: channel(rgb[2]), b: channel(rgb[3]) };
+    return undefined;
+}
+/** Parse a CSI ?997 report; `2` means the terminal describes itself as light. */
+export function parseSchemeReply(data) {
+    const match = /^\x1b\[\?997;([12])n$/u.exec(data);
+    if (match === null)
+        return undefined;
+    return match[1] === '2' ? 'light' : 'dark';
+}
+/** Fold one reply into the accumulated description, keeping earlier fields the reply does not answer. */
+export function mergeColorReply(colors, reply) {
+    if (reply.target === 'foreground')
+        return reply.color === undefined ? colors : { ...colors, foreground: reply.color };
+    if (reply.target === 'background')
+        return reply.color === undefined ? colors : { ...colors, background: reply.color };
+    if (reply.color === undefined)
+        return colors;
+    const entries = Array.from({ length: 16 }, (_, index) => colors.entries?.[index] ?? colors.palette?.[index]);
+    entries[reply.target] = reply.color;
+    // Publishing needs every index present; the accumulator keeps the partial
+    // report until then.
+    return entries.every((entry) => entry !== undefined)
+        ? { ...colors, entries, palette: entries }
+        : { ...colors, entries };
+}
+/**
+ * Stable key for everything reported colors can change; two reports with the
+ * same colors produce the same key, so caches never stale-hit across a
+ * light/dark switch.
+ */
+export function terminalColorsKey(colors) {
+    if (colors === undefined)
+        return '';
+    // Every frame asks once per cached block; a new report is a new object.
+    const known = terminalColorsKeys.get(colors);
+    if (known !== undefined)
+        return known;
+    const rgb = (color) => color === undefined ? '' : `${color.r},${color.g},${color.b}`;
+    const key = [rgb(colors.foreground), rgb(colors.background), colors.scheme ?? '', (colors.palette ?? []).map(rgb).join(';')].join('|');
+    terminalColorsKeys.set(colors, key);
+    return key;
+}
+const terminalColorsKeys = new WeakMap();
+/** Convert one 8-bit sRGB color to Oklab (Björn Ottosson's transform). */
+export function toOklab(color) {
+    const linear = (value) => {
+        const channelValue = value / 255;
+        return channelValue <= 0.04045 ? channelValue / 12.92 : ((channelValue + 0.055) / 1.055) ** 2.4;
+    };
+    const r = linear(color.r);
+    const g = linear(color.g);
+    const b = linear(color.b);
+    const l = Math.cbrt(0.412_221_470_8 * r + 0.536_332_536_3 * g + 0.051_445_992_9 * b);
+    const m = Math.cbrt(0.211_903_498_2 * r + 0.680_699_545_1 * g + 0.107_396_956_6 * b);
+    const s = Math.cbrt(0.088_302_461_9 * r + 0.281_718_837_6 * g + 0.629_978_700_5 * b);
+    return [
+        0.210_454_255_3 * l + 0.793_617_785 * m - 0.004_072_046_8 * s,
+        1.977_998_495_1 * l - 2.428_592_205 * m + 0.450_593_709_9 * s,
+        0.025_904_037_1 * l + 0.782_771_766_2 * m - 0.808_675_766 * s,
+    ];
+}
+/** Squared Oklab distance; ordering is all that matters for nearest-color picks. */
+export function labDistance(left, right) {
+    const dl = left[0] - right[0];
+    const da = left[1] - right[1];
+    const db = left[2] - right[2];
+    return dl * dl + da * da + db * db;
+}
+/**
+ * Index of the palette entry closest to `color` in Oklab, which is what a
+ * 16-color terminal can actually show. Returns undefined for an empty palette.
+ */
+export function nearestPaletteIndex(color, palette) {
+    if (palette.length === 0)
+        return undefined;
+    const target = toOklab(color);
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < palette.length; index += 1) {
+        const entry = palette[index];
+        // A caller may hand us a partial report; a missing entry is not a color.
+        if (entry === undefined)
+            continue;
+        const distance = labDistance(target, toOklab(entry));
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = index;
+        }
+    }
+    return best;
+}
+/** WCAG relative luminance of one color. */
+export function relativeLuminance(color) {
+    const channelLuminance = (value) => {
+        const channelValue = value / 255;
+        return channelValue <= 0.039_28 ? channelValue / 12.92 : ((channelValue + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channelLuminance(color.r) + 0.7152 * channelLuminance(color.g) + 0.0722 * channelLuminance(color.b);
+}
+/** WCAG contrast ratio; 1 means identical colors. */
+export function contrastRatio(left, right) {
+    const a = relativeLuminance(left);
+    const b = relativeLuminance(right);
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+/** The xterm 256-color entries above the sixteen the user configures: the 6×6×6 cube and the gray ramp. */
+const XTERM_256 = (() => {
+    const levels = [0, 95, 135, 175, 215, 255];
+    const entries = [];
+    for (let index = 16; index < 232; index += 1) {
+        const offset = index - 16;
+        entries.push({ index, lab: toOklab({ r: levels[Math.floor(offset / 36)], g: levels[Math.floor(offset / 6) % 6], b: levels[offset % 6] }) });
+    }
+    for (let index = 232; index < 256; index += 1) {
+        const value = 8 + (index - 232) * 10;
+        entries.push({ index, lab: toOklab({ r: value, g: value, b: value }) });
+    }
+    return entries;
+})();
+const xterm256Cache = new Map();
+/**
+ * The xterm-256 entry closest to `color` in Oklab, from the fixed cube and
+ * gray ramp only: indices 0-15 follow the user's palette and would make the
+ * result depend on a terminal theme we cannot see.
+ */
+/** First xterm-256 index of the 24-step neutral ramp. */
+const GREY_RAMP_START = 232;
+/**
+ * Nearest xterm-256 entry, restricted to the 24-step neutral ramp.
+ *
+ * The ramp is `232..255`, and it exists because a *surface* swatch is usually a
+ * near-neutral. Left to the whole palette, three swatches that differ by a few
+ * units of warmth all land on one entry, which is why a pending, a successful,
+ * and a failed tool card used to share a single fill on a 256-color terminal.
+ * `hueSteps` keeps that from happening: see {@link surfaceXterm256}.
+ */
+export function nearestXterm256Grey(color) {
+    const key = `g:${color.r},${color.g},${color.b}`;
+    const known = xterm256Cache.get(key);
+    if (known !== undefined)
+        return known;
+    const target = toOklab(color);
+    let best = GREY_RAMP_START;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const entry of XTERM_256) {
+        if (entry.index < GREY_RAMP_START)
+            continue;
+        const distance = labDistance(target, entry.lab);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = entry.index;
+        }
+    }
+    xterm256Cache.set(key, best);
+    return best;
+}
+export function nearestXterm256(color) {
+    const key = `${color.r},${color.g},${color.b}`;
+    const known = xterm256Cache.get(key);
+    if (known !== undefined)
+        return known;
+    const target = toOklab(color);
+    let best = 16;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const entry of XTERM_256) {
+        const distance = labDistance(target, entry.lab);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = entry.index;
+        }
+    }
+    xterm256Cache.set(key, best);
+    return best;
+}
+//# sourceMappingURL=terminal-colors.js.map

package/lib/chrome/terminal-colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-colors.js","sourceRoot":"","sources":["../../src/chrome/terminal-colors.ts"],"names":[],"mappings":"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"}

package/lib/chrome/terminal-images.d.ts

@@ -15,7 +15,15 @@ export interface ImagePlacement {
     columns: number;
     rows: number;
 }
-/** Only known direct terminals opt in. Outer-terminal hints do not prove passthrough. */
+/**
+ * Which inline-image protocol this terminal speaks, if any.
+ *
+ * Every hint here is one a terminal actually sets: the Kitty flags, the
+ * Ghostty/WezTerm/Warp markers, and the multiplexers that forward the protocol
+ * (Herdr and Rex, whose panes leak the outer terminal's variables, so they are
+ * decided first). `OMDSH_IMAGE_PROTOCOL` forces an answer when detection is
+ * wrong: `kitty`, `iterm2`, or `none`.
+ */
 export declare function imageProtocol(env: NodeJS.ProcessEnv): ImageProtocol | undefined;
 /** Fit in display cells while preserving the source's pixel aspect ratio. */
 export declare function imageSize(image: PreviewImage, columns: number, rows: number, cell?: {

package/lib/chrome/terminal-images.js

@@ -1,11 +1,34 @@
-/** Only known direct terminals opt in. Outer-terminal hints do not prove passthrough. */
+/**
+ * Which inline-image protocol this terminal speaks, if any.
+ *
+ * Every hint here is one a terminal actually sets: the Kitty flags, the
+ * Ghostty/WezTerm/Warp markers, and the multiplexers that forward the protocol
+ * (Herdr and Rex, whose panes leak the outer terminal's variables, so they are
+ * decided first). `OMDSH_IMAGE_PROTOCOL` forces an answer when detection is
+ * wrong: `kitty`, `iterm2`, or `none`.
+ */
 export function imageProtocol(env) {
-    if (env.TMUX || env.STY || env.ZELLIJ || env.HERDR_ENV === '1' || /^(?:tmux|screen)/u.test(env.TERM ?? ''))
+    const forced = (env.OMDSH_IMAGE_PROTOCOL ?? '').trim().toLowerCase();
+    if (forced === 'none')
+        return undefined;
+    if (forced === 'kitty' || forced === 'iterm2')
+        return forced;
+    // Multiplexers that do not carry graphics through to the outer terminal.
+    if (env.TMUX || env.STY || env.ZELLIJ || /^(?:tmux|screen)/u.test(env.TERM ?? ''))
         return undefined;
     const program = (env.TERM_PROGRAM ?? '').toLowerCase();
-    if (env.KITTY_WINDOW_ID || env.TERM === 'xterm-kitty' || ['ghostty', 'wezterm'].includes(program))
+    const term = env.TERM ?? '';
+    if (program === 'herdr' || program === 'rex' || env.HERDR_ENV === '1')
+        return 'kitty';
+    if (env.KITTY_WINDOW_ID || term === 'xterm-kitty' || program === 'kitty')
+        return 'kitty';
+    if (program === 'ghostty' || term.includes('ghostty') || env.GHOSTTY_RESOURCES_DIR)
+        return 'kitty';
+    if (env.WEZTERM_PANE || program === 'wezterm')
+        return 'kitty';
+    if (program === 'warpterminal' || env.WARP_SESSION_ID || env.WARP_TERMINAL_SESSION_UUID)
         return 'kitty';
-    if (program === 'iterm.app' || env.LC_TERMINAL === 'iTerm2')
+    if (program === 'iterm.app' || env.ITERM_SESSION_ID || env.LC_TERMINAL === 'iTerm2')
         return 'iterm2';
     return undefined;
 }

package/lib/chrome/terminal-images.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-images.js","sourceRoot":"","sources":["../../src/chrome/terminal-images.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terminal-images.js","sourceRoot":"","sources":["../../src/chrome/terminal-images.ts"],"names":[],"mappings":"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"}

package/lib/chrome/theme.d.ts

@@ -3,6 +3,7 @@
  * glyphs used by terminal views.
  * @module @agi-fans/dsh-tui
  */
+import { type TerminalColors } from './terminal-colors.ts';
 /** Rounded-box drawing characters (OMP unicode preset). */
 export declare const BOX: {
     readonly topLeft: "╭";
@@ -50,9 +51,17 @@ export declare const SYMBOL: {
 /** Braille activity spinner (OMP unicode activity frames). */
 export declare const SPINNER: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 /** Semantic colors the view addresses. */
-export type ThemeColor = 'accent' | 'border' | 'borderAccent' | 'borderMuted' | 'success' | 'error' | 'warning' | 'muted' | 'dim' | 'text' | 'userMessageText' | 'userMessageBg' | 'toolPendingBg' | 'toolSuccessBg' | 'toolErrorBg' | 'toolTitle' | 'toolOutput' | 'toolDiffAdded' | 'toolDiffRemoved' | 'toolDiffContext' | 'mdHeading' | 'mdLink' | 'mdLinkUrl' | 'mdCode' | 'mdCodeBlock' | 'mdCodeBlockBorder' | 'mdKeyword' | 'syntaxString' | 'syntaxNumber' | 'syntaxFunction' | 'syntaxType' | 'mdQuote' | 'mdListBullet' | 'thinkingText' | 'customMessageLabel';
+export type ThemeColor = 'accent' | 'border' | 'borderAccent' | 'borderMuted' | 'success' | 'error' | 'warning' | 'muted' | 'dim' | 'text' | 'userMessageText' | 'userMessageBg' | 'toolPendingBg' | 'toolSuccessBg' | 'toolAltBg' | 'toolErrorBg' | 'toolTitle' | 'toolOutput' | 'toolDiffAdded' | 'toolDiffRemoved' | 'toolDiffContext' | 'mdHeading' | 'mdLink' | 'mdLinkUrl' | 'mdCode' | 'mdCodeBlock' | 'mdCodeBlockBorder' | 'mdKeyword' | 'syntaxString' | 'syntaxNumber' | 'syntaxFunction' | 'syntaxType' | 'mdQuote' | 'mdQuoteBorder' | 'mdHr' | 'mdListBullet' | 'shellMode' | 'thinkingText' | 'customMessageLabel';
 /** Built-in palettes, including a few well-known oh-my-pi coding themes. */
-export declare const THEME_NAMES: readonly ["dark", "light", "midnight", "solarized", "catppuccin", "dracula", "nord", "gruvbox", "rose-pine", "mono"];
+/**
+ * Shipped palettes: one dark, one light, and the one that follows the terminal.
+ *
+ * A theme is a contract the whole TUI is read through — every card, diff, and
+ * syntax token has to stay legible on it — so the set stays small enough to hold
+ * to that standard. `system` is not a third design: it derives its surfaces from
+ * the colours the terminal reports and then follows the same rules.
+ */
+export declare const THEME_NAMES: readonly ["dark", "light", "system"];
 /** One shipped palette name. */
 export type ThemeName = (typeof THEME_NAMES)[number];
 /** True when `value` is a shipped palette name. */
@@ -65,8 +74,12 @@ export interface Theme {
     readonly name: ThemeName;
     /** Whether SGR is emitted. */
     readonly colors: boolean;
-    /** Whether hex colors become 24-bit SGR (else 16-color). */
+    /** Whether hex colors become 24-bit SGR. */
     readonly trueColor: boolean;
+    /** How swatches are encoded; meaningful only when {@link Theme.colors} is true. */
+    readonly depth: ColorDepth;
+    /** Cache fingerprint covering the palette, SGR flag, depth, and reported terminal colors. */
+    readonly key: string;
     fg(color: ThemeColor, text: string): string;
     bg(color: ThemeColor, text: string): string;
     getFgAnsi(color: ThemeColor): string;
@@ -81,6 +94,12 @@ export interface Theme {
 }
 /** Paint a fixed surface, restoring its paired ink and fill after nested resets. */
 export declare function paintSurface(theme: Theme, background: ThemeColor, foreground: ThemeColor, text: string): string;
+/**
+ * How many colors the terminal can show, which decides how a swatch is
+ * encoded. It is independent of what the terminal reports about its palette:
+ * a report changes the target values, never the encoding.
+ */
+export type ColorDepth = 'ansi16' | 'ansi256' | 'truecolor';
 /**
  * True when the environment asks for no color at all: a non-empty `NO_COLOR`
  * (https://no-color.org) or `FORCE_COLOR=0`. An empty `NO_COLOR` counts as
@@ -88,18 +107,22 @@ export declare function paintSurface(theme: Theme, background: ThemeColor, foreg
  */
 export declare function colorDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
 /**
- * Detect 24-bit color. `NO_COLOR` (any non-empty value) and `FORCE_COLOR=0`
- * suppress 24-bit color and outrank every capability hint; `COLORTERM` and
- * Windows Terminal enable it, and only known 16-color hosts disqualify it.
+ * Detect the color depth. `NO_COLOR` (any non-empty value) and `FORCE_COLOR=0`
+ * outrank every capability hint and leave 16 colors; `COLORTERM` and Windows
+ * Terminal prove 24-bit color. Apple Terminal advertises `xterm-256color` but
+ * misdraws 24-bit sequences on the releases still in use, so it gets the
+ * 256-color cube. Known 16-color hosts stay at 16, and every other terminal is
+ * assumed to be a modern 24-bit one.
  */
-export declare function detectTrueColor(env?: NodeJS.ProcessEnv): boolean;
+export declare function detectColorDepth(env?: NodeJS.ProcessEnv): ColorDepth;
 /**
  * Build a theme.
  * @param colors - emit SGR when true.
- * @param trueColor - 24-bit hex; ignored when colors is false.
+ * @param depth - color depth, or a boolean for 24-bit versus 16 colors; ignored when colors is false.
  * @param name - shipped palette (`dark` default).
+ * @param terminal - what the terminal reported about itself, when a probe answered.
  */
-export declare function createTheme(colors: boolean, trueColor?: boolean, name?: ThemeName): Theme;
+export declare function createTheme(colors: boolean, depth?: ColorDepth | boolean, name?: ThemeName, terminal?: TerminalColors): Theme;
 /** DeepSeek mark adapted from the official SVG for a 20×6 terminal cell. */
 export declare const DEEPSEEK_LOGO: readonly ["         ⢀⣀  ⢀⡀     ", "⢀⣤⣶⣿⣿⣿⣿⣿⣿⣿⣧⣄⡀⢻⣿⣷⣶⣶⣶⡿", "⣿⡟⠛⠛⠛⠿⢿⣿⣿⣿⣿⡿⢿⣷⣾⣿⣿⠉⠉ ", "⢻⣿⣄⡀  ⢀⠈⠛⢿⣿⣿⣶⣿⣿⡿⠃   ", " ⠙⠻⢿⣶⣦⣼⣿⣷⣦⣭⣿⠿⣿⣷⠦    ", "     ⠉⠉⠉⠉⠉⠁         "];
 /**