@promptctl/rich-js 0.17.0 → 0.18.0

package/dist/core/color.js

@@ -1,1029 +0,0 @@
-/**
- * Terminal color representation, parsing, downgrading, and ANSI code generation.
- */
-// --- ColorRgba ---
-function hex2(byte) {
-    return byte.toString(16).padStart(2, "0");
-}
-function assertChannel(name, v) {
-    if (!Number.isInteger(v) || v < 0 || v > 255) {
-        throw new RangeError(`ColorRgba.${name} must be an integer in [0, 255]; got ${v}`);
-    }
-}
-/**
- * Immutable RGBA color value. Alpha defaults to 1 (fully opaque).
- *
- * [LAW:single-enforcer] The constructor is the sole validation site for
- * channel/alpha invariants. Float-arithmetic callers (HSL roundtrips, blends,
- * lerps) are responsible for `Math.round` + clamp before construction; the
- * constructor throws rather than silently masking out-of-range input.
- */
-export class ColorRgba {
-    red;
-    green;
-    blue;
-    alpha;
-    constructor(red, green, blue, alpha = 1) {
-        this.red = red;
-        this.green = green;
-        this.blue = blue;
-        this.alpha = alpha;
-        assertChannel("red", red);
-        assertChannel("green", green);
-        assertChannel("blue", blue);
-        if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
-            throw new RangeError(`ColorRgba.alpha must be a finite number in [0, 1]; got ${alpha}`);
-        }
-    }
-    /** 6-char `#RRGGBB` when fully opaque, 8-char `#RRGGBBAA` otherwise. */
-    get hex() {
-        const rgb = "#" + hex2(this.red) + hex2(this.green) + hex2(this.blue);
-        return this.alpha === 1 ? rgb : rgb + hex2(Math.round(this.alpha * 255));
-    }
-    /** `rgb(r,g,b)` when fully opaque, `rgba(r,g,b,a)` otherwise. */
-    get rgb() {
-        return this.alpha === 1
-            ? `rgb(${this.red},${this.green},${this.blue})`
-            : `rgba(${this.red},${this.green},${this.blue},${this.alpha})`;
-    }
-    /** [r/255, g/255, b/255, alpha] — alpha is already 0..1, no division. */
-    get normalized() {
-        return [this.red / 255, this.green / 255, this.blue / 255, this.alpha];
-    }
-    /**
-     * Composite this color over an opaque background. Returns a fully opaque
-     * ColorRgba (alpha=1). Per-channel linear interpolation by alpha.
-     *
-     * [LAW:dataflow-not-control-flow] alpha=1 short-circuits to `this`, so
-     * callers can invoke this unconditionally; the data decides whether work
-     * happens.
-     */
-    compositeOver(bg) {
-        if (this.alpha === 1)
-            return this;
-        const t = this.alpha;
-        return new ColorRgba(Math.round(bg.red + (this.red - bg.red) * t), Math.round(bg.green + (this.green - bg.green) * t), Math.round(bg.blue + (this.blue - bg.blue) * t), 1);
-    }
-}
-/**
- * The surface a terminal draws a translucent colour over. A terminal cannot
- * know what lies under its cells, so the SGR writer (`Style.toSgrCodes`), the
- * strip's seam test and the contrast choosers (`themes/colorMath`) all
- * composite over this one colour. [LAW:one-source-of-truth] One constant, so
- * the colour text is chosen against is the colour the writer draws.
- */
-export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
-/**
- * WCAG 2.x relative luminance (0..1) of an opaque color. The single
- * luminance function in the codebase — `contrastFor`, `contrastRatio`, and
- * any caller that needs to reason about readability all funnel through it.
- * [LAW:one-source-of-truth]
- */
-export function relativeLuminance(c) {
-    const ch = (v) => {
-        const x = v / 255;
-        return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4);
-    };
-    return 0.2126 * ch(c.red) + 0.7152 * ch(c.green) + 0.0722 * ch(c.blue);
-}
-/**
- * WCAG 2.x contrast ratio between two colors, in [1, 21]. Symmetric — the
- * order of arguments does not matter. 4.5 is the AA threshold for normal
- * text, 3.0 for large text.
- *
- * Assumes opaque inputs: alpha is ignored, since the displayed contrast of a
- * translucent color depends on what it composites over. For a translucent
- * foreground, flatten it first (or use `ensureContrast`, which does).
- */
-export function contrastRatio(a, b) {
-    return luminanceRatio(relativeLuminance(a), relativeLuminance(b));
-}
-// [LAW:single-enforcer] The WCAG ratio over two relative luminances — the one
-// formula `contrastRatio` and `ColorTable.matchReadable` (which caches its
-// entries' luminances) both measure with.
-function luminanceRatio(la, lb) {
-    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
-}
-// --- ColorTable ---
-/**
- * An indexed palette: entry `i` of `colors` is terminal index `firstIndex + i`.
- * `firstIndex` lets a table hold only the part of a palette a downgrade may
- * choose (the 256-colour cube and grey ramp start at 16) while every index it
- * reports is the terminal's own.
- */
-// [LAW:single-enforcer] The one size policy for ColorTable's memos: a key is
-// derived from colours a long-running host computes without end (ramp stops,
-// mixes), so an unbounded map grows with every render. Clearing at the cap is
-// the policy `cellLen` already uses; a refill costs one table scan per key.
-const TABLE_CACHE_MAX = 4096;
-function remember(cache, key, index) {
-    if (cache.size >= TABLE_CACHE_MAX)
-        cache.clear();
-    cache.set(key, index);
-    return index;
-}
-// [LAW:one-source-of-truth] The one distance every table scan ranks by, so
-// `matchWhere`'s "nearest by the distance `match` uses" cannot drift.
-function rgbDistance(a, b) {
-    const dr = a.red - b.red;
-    const dg = a.green - b.green;
-    const db = a.blue - b.blue;
-    return dr * dr + dg * dg + db * db;
-}
-export class ColorTable {
-    colors;
-    firstIndex;
-    matchCache = new Map();
-    readableCache = new Map();
-    constructor(colors, firstIndex = 0) {
-        this.colors = colors;
-        this.firstIndex = firstIndex;
-    }
-    get(index) {
-        return this.colors[index - this.firstIndex];
-    }
-    luminanceCache;
-    /** Each entry's relative luminance, computed once per table. */
-    luminances() {
-        this.luminanceCache ??= this.colors.map(relativeLuminance);
-        return this.luminanceCache;
-    }
-    /** How many entries the table holds (terminal indices `firstIndex`…). */
-    get size() {
-        return this.colors.length;
-    }
-    /**
-     * Finds the nearest table index to the given color (Euclidean RGB distance, cached).
-     * Alpha is part of the cache key so two values that differ only in alpha
-     * don't collide, but is not used in the distance metric.
-     */
-    match(value) {
-        const key = `${value.red},${value.green},${value.blue},${value.alpha}`;
-        const cached = this.matchCache.get(key);
-        if (cached !== undefined)
-            return cached;
-        let bestIndex = 0;
-        let bestDist = Infinity;
-        for (let i = 0; i < this.colors.length; i++) {
-            const c = this.colors[i];
-            const dist = rgbDistance(c, value);
-            if (dist < bestDist) {
-                bestDist = dist;
-                bestIndex = i;
-            }
-        }
-        return remember(this.matchCache, key, this.firstIndex + bestIndex);
-    }
-    /**
-     * The nearest entry to `value` (the distance `match` uses) among those that
-     * clear `minRatio` against `on`; when none does, the entry with the most
-     * contrast against `on`. Text downgraded on its own background: `match`
-     * moves text and background independently, and two independent roundings
-     * can meet in the middle, so a pair that read at 4.5:1 in truecolor can
-     * draw at 2:1. [LAW:dataflow-not-control-flow] One scan scores every entry;
-     * the ratio decides which one wins.
-     */
-    matchReadable(value, on, minRatio) {
-        const key = `${value.red},${value.green},${value.blue}|${on.red},${on.green},${on.blue}|${minRatio}`;
-        const cached = this.readableCache.get(key);
-        if (cached !== undefined)
-            return cached;
-        const lOn = relativeLuminance(on);
-        let best = 0;
-        let bestPasses = false;
-        let bestScore = -Infinity;
-        for (let i = 0; i < this.colors.length; i++) {
-            const c = this.colors[i];
-            const lc = this.luminances()[i];
-            const ratio = luminanceRatio(lc, lOn);
-            const passes = ratio >= minRatio;
-            // A passing entry scores by closeness; a failing one only by contrast,
-            // and loses to every passing one.
-            const score = passes ? -rgbDistance(c, value) : ratio;
-            if ((passes && !bestPasses) ||
-                (passes === bestPasses && score > bestScore)) {
-                best = i;
-                bestPasses = passes;
-                bestScore = score;
-            }
-        }
-        return remember(this.readableCache, key, this.firstIndex + best);
-    }
-    /**
-     * The nearest entry to `value` (the distance `match` uses) among those
-     * `accept` takes, given each entry's colour and terminal index; `undefined`
-     * when it takes none. Entries are offered nearest-first (ties to the lower
-     * index) and the first taken wins, so an expensive predicate runs only as
-     * far out as the answer. Uncached: the predicate is the caller's, and a
-     * closure has no key.
-     */
-    matchWhere(value, accept) {
-        const dist = this.colors.map((c) => rgbDistance(c, value));
-        const nearestFirst = [...dist.keys()].sort((a, b) => dist[a] - dist[b]);
-        const found = nearestFirst.find((i) => accept(this.colors[i], this.firstIndex + i));
-        return found === undefined ? undefined : this.firstIndex + found;
-    }
-}
-// --- Enums ---
-export var ColorDepth;
-(function (ColorDepth) {
-    ColorDepth[ColorDepth["DEFAULT"] = 0] = "DEFAULT";
-    ColorDepth[ColorDepth["STANDARD"] = 1] = "STANDARD";
-    ColorDepth[ColorDepth["EIGHT_BIT"] = 2] = "EIGHT_BIT";
-    ColorDepth[ColorDepth["TRUECOLOR"] = 3] = "TRUECOLOR";
-    ColorDepth[ColorDepth["WINDOWS"] = 4] = "WINDOWS";
-})(ColorDepth || (ColorDepth = {}));
-// [LAW:one-source-of-truth] One table covers every recognized string form
-// that resolves to a ColorDepth: user-facing CLI/config specs, FORCE_COLOR
-// values (the chalk/supports-color convention), TERM_PROGRAM identifiers,
-// and exact TERM names whose color capability is known. Keys are disjoint
-// across these sources, so one table is honest. `null` means "no color".
-// "auto" is intentionally absent — it routes to env detection.
-const STRING_TO_DEPTH = {
-    // CLI/config specs
-    truecolor: ColorDepth.TRUECOLOR,
-    "256": ColorDepth.EIGHT_BIT,
-    ansi: ColorDepth.STANDARD,
-    none: null,
-    // FORCE_COLOR values
-    "0": null,
-    false: null,
-    "1": ColorDepth.STANDARD,
-    true: ColorDepth.STANDARD,
-    "2": ColorDepth.EIGHT_BIT,
-    "3": ColorDepth.TRUECOLOR,
-    // TERM_PROGRAM identifiers
-    "iTerm.app": ColorDepth.TRUECOLOR,
-    Apple_Terminal: ColorDepth.EIGHT_BIT,
-    vscode: ColorDepth.TRUECOLOR,
-    Tabby: ColorDepth.TRUECOLOR,
-    // Known truecolor TERM names
-    "xterm-kitty": ColorDepth.TRUECOLOR,
-    "xterm-ghostty": ColorDepth.TRUECOLOR,
-    wezterm: ColorDepth.TRUECOLOR,
-    alacritty: ColorDepth.TRUECOLOR,
-    foot: ColorDepth.TRUECOLOR,
-    contour: ColorDepth.TRUECOLOR,
-};
-/**
- * Detect the terminal's color capability from env + TTY state.
- *
- * Probes (in priority order): NO_COLOR (per https://no-color.org —
- * any non-empty value disables color), FORCE_COLOR (numeric/boolean override),
- * TTY presence, TERM=dumb/unknown, COLORTERM, known terminal/TERM_PROGRAM
- * names, and TERM regex patterns. Returns `null` for "no color".
- *
- * [LAW:dataflow-not-control-flow] Same probes run every call; variability is
- * in the env values, not in which checks execute.
- */
-export function detectColorSystem(options = {}) {
-    // NO_COLOR and FORCE_COLOR are preferences about colour, not facts about the
-    // terminal, so they sit outside the probe. NO_COLOR (any non-empty value)
-    // beats FORCE_COLOR; FORCE_COLOR beats TTY/TERM detection.
-    const noColor = envOf(options)["NO_COLOR"];
-    if (noColor !== undefined && noColor !== "")
-        return null;
-    const forced = forcedColorSystem(envOf(options));
-    return forced !== undefined ? forced : terminalColorSystem(options);
-}
-// FORCE_COLOR's depth: `undefined` when unset, `null` for its off values.
-function forcedColorSystem(env) {
-    const force = env["FORCE_COLOR"];
-    if (force === undefined || force === "")
-        return undefined;
-    const mapped = STRING_TO_DEPTH[force];
-    return mapped !== undefined ? mapped : ColorDepth.STANDARD;
-}
-function envOf(options) {
-    return options.env ?? (typeof process !== "undefined" ? process.env : {});
-}
-// What the destination can draw, preferences aside: TTY presence,
-// TERM=dumb/unknown, COLORTERM, known terminal names, TERM patterns. `null`
-// here means the destination takes no escapes at all.
-function terminalColorSystem(options) {
-    const env = envOf(options);
-    const isTTY = options.isTTY ??
-        (typeof process !== "undefined" ? (process.stdout?.isTTY ?? false) : false);
-    if (!isTTY)
-        return null;
-    const term = env["TERM"] ?? "";
-    if (term === "dumb" || term === "unknown")
-        return null;
-    const colorterm = env["COLORTERM"];
-    if (colorterm === "truecolor" || colorterm === "24bit") {
-        return ColorDepth.TRUECOLOR;
-    }
-    const termDepth = STRING_TO_DEPTH[term];
-    if (termDepth !== undefined)
-        return termDepth;
-    const termProgram = env["TERM_PROGRAM"];
-    if (termProgram !== undefined) {
-        const mapped = STRING_TO_DEPTH[termProgram];
-        if (mapped !== undefined)
-            return mapped;
-    }
-    if (/-256(color)?$/i.test(term))
-        return ColorDepth.EIGHT_BIT;
-    if (/-truecolor$/i.test(term))
-        return ColorDepth.TRUECOLOR;
-    if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(term)) {
-        return ColorDepth.STANDARD;
-    }
-    if (colorterm !== undefined && colorterm !== "")
-        return ColorDepth.STANDARD;
-    // Default: a terminal exists (isTTY=true) but we couldn't classify it.
-    // Assume safe baseline rather than disabling color.
-    return ColorDepth.STANDARD;
-}
-/**
- * Resolve a colour spec into a `Destination`.
- *
- * [LAW:single-enforcer] The one place a spec becomes both facts. A hyperlink is
- * not a colour: an explicit depth — `"none"` and `null` included — states a
- * colour choice and keeps links, and under `"auto"` links follow what the
- * terminal can take (no TTY, TERM=dumb: none) while NO_COLOR and FORCE_COLOR=0,
- * colour preferences, leave them alone. A FORCE_COLOR that forces colour on
- * declares the destination takes escapes, so it keeps links on a pipe too.
- */
-export function resolveDestination(spec, options) {
-    if (spec !== "auto") {
-        return {
-            colorSystem: typeof spec === "string" ? resolveColorSystem(spec) : spec,
-            hyperlinks: true,
-        };
-    }
-    return {
-        colorSystem: detectColorSystem(options),
-        hyperlinks: (forcedColorSystem(envOf(options ?? {})) ?? null) !== null ||
-            terminalColorSystem(options ?? {}) !== null,
-    };
-}
-/**
- * Resolve a string spec into a `ColorDepth` (or `null` for no color).
- *
- * `"auto"` triggers env-based detection; all other recognized specs are
- * direct table lookups against `STRING_TO_DEPTH`. Throws on unknown specs
- * — silent fallback would mask user typos.
- *
- * [LAW:single-enforcer] All string→ColorDepth resolution flows through here.
- */
-export function resolveColorSystem(spec, options) {
-    if (spec === "auto")
-        return detectColorSystem(options);
-    if (Object.hasOwn(STRING_TO_DEPTH, spec))
-        return STRING_TO_DEPTH[spec];
-    throw new ColorParseError(`Unknown color depth spec: ${JSON.stringify(spec)} (expected "auto", "truecolor", "256", "ansi", or "none")`);
-}
-// --- ColorSpec ---
-export class ColorParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "ColorParseError";
-    }
-}
-// [LAW:one-source-of-truth] Parse cache is the single source for parsed ColorSpec instances
-const parseCache = new Map();
-export class ColorSpec {
-    name;
-    type;
-    number;
-    value;
-    downgradeCache = new Map();
-    constructor(name, type, number, value) {
-        this.name = name;
-        this.type = type;
-        this.number = number;
-        this.value = value;
-    }
-    get isDefault() {
-        return this.type === ColorDepth.DEFAULT;
-    }
-    /**
-     * The colour every terminal draws this spec as, where that is fixed — before
-     * any alpha is flattened, so a translucent value is drawn composited over
-     * its ground (`flattenAlpha`) and should be measured that way: a
-     * truecolor value, or a 256-colour cube or grey-ramp entry (xterm fixes
-     * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15
-     * and the default colour are the terminal theme's own, so they have none.
-     */
-    get fixedValue() {
-        switch (this.type) {
-            case ColorDepth.TRUECOLOR:
-                return this.value;
-            case ColorDepth.EIGHT_BIT:
-                // The constructor admits an EIGHT_BIT spec at 0–15; those are the
-                // theme's own slots whatever depth names them.
-                return this.number < 16 ? undefined : EIGHT_BIT_TABLE.get(this.number);
-            case ColorDepth.DEFAULT:
-            case ColorDepth.STANDARD:
-            case ColorDepth.WINDOWS:
-                return undefined;
-        }
-    }
-    get isSystemDefined() {
-        return (this.type === ColorDepth.STANDARD || this.type === ColorDepth.WINDOWS);
-    }
-    /**
-     * Generates SGR parameter strings for this color.
-     */
-    getAnsiCodes(foreground = true) {
-        switch (this.type) {
-            case ColorDepth.DEFAULT:
-                return [foreground ? "39" : "49"];
-            case ColorDepth.STANDARD: {
-                const n = this.number;
-                if (foreground) {
-                    return n < 8 ? [`${30 + n}`] : [`${90 + n - 8}`];
-                }
-                return n < 8 ? [`${40 + n}`] : [`${100 + n - 8}`];
-            }
-            case ColorDepth.EIGHT_BIT:
-                return [foreground ? "38" : "48", "5", `${this.number}`];
-            case ColorDepth.TRUECOLOR: {
-                const t = this.value;
-                return [
-                    foreground ? "38" : "48",
-                    "2",
-                    `${t.red}`,
-                    `${t.green}`,
-                    `${t.blue}`,
-                ];
-            }
-            case ColorDepth.WINDOWS: {
-                const n = this.number;
-                if (foreground) {
-                    return n < 8 ? [`${30 + n}`] : [`${90 + n - 8}`];
-                }
-                return n < 8 ? [`${40 + n}`] : [`${100 + n - 8}`];
-            }
-        }
-    }
-    /**
-     * Composite this color's alpha (if any) against an opaque background,
-     * returning a fully-opaque ColorSpec. Non-truecolor specs (palette
-     * indices, default) have no alpha and pass through unchanged.
-     *
-     * [LAW:single-enforcer] Sole alpha-flattening site for the render
-     * pipeline. Run *before* downgrade — otherwise palette matching on the
-     * still-translucent RGB silently drops alpha (the "flatten then lose
-     * alpha" path the unification ticket forbids).
-     *
-     * [LAW:dataflow-not-control-flow] `ColorRgba.compositeOver` is a no-op
-     * when alpha=1, so callers invoke this unconditionally; the data
-     * (alpha value) decides whether work happens.
-     */
-    flattenAlpha(bg) {
-        if (this.type !== ColorDepth.TRUECOLOR || !this.value)
-            return this;
-        const flat = this.value.compositeOver(bg);
-        return flat === this.value ? this : ColorSpec.fromRgba(flat);
-    }
-    /**
-     * Downgrade to a lower-fidelity color depth. Cached.
-     */
-    downgrade(targetSystem) {
-        if (this.type === ColorDepth.DEFAULT)
-            return this;
-        if (this.type <= targetSystem)
-            return this;
-        const cached = this.downgradeCache.get(targetSystem);
-        if (cached)
-            return cached;
-        const result = this.performDowngrade(targetSystem);
-        this.downgradeCache.set(targetSystem, result);
-        return result;
-    }
-    /**
-     * Resolves to an actual RGB(A) value for any color type.
-     */
-    getTruecolor(theme, foreground = true) {
-        switch (this.type) {
-            case ColorDepth.TRUECOLOR:
-                return this.value;
-            case ColorDepth.EIGHT_BIT:
-                return EIGHT_BIT_TABLE.get(this.number);
-            case ColorDepth.STANDARD: {
-                const t = theme ?? INTERNAL_DEFAULT_THEME;
-                return t.ansiColors.get(this.number);
-            }
-            case ColorDepth.DEFAULT: {
-                const t = theme ?? INTERNAL_DEFAULT_THEME;
-                return foreground ? t.foregroundColor : t.backgroundColor;
-            }
-            case ColorDepth.WINDOWS: {
-                const t = theme ?? INTERNAL_DEFAULT_THEME;
-                return t.ansiColors.get(this.number);
-            }
-        }
-    }
-    // --- Static factories ---
-    static default() {
-        return new ColorSpec("default", ColorDepth.DEFAULT);
-    }
-    static fromAnsi(n) {
-        const type = n < 16 ? ColorDepth.STANDARD : ColorDepth.EIGHT_BIT;
-        return new ColorSpec(`color(${n})`, type, n);
-    }
-    static fromRgba(value) {
-        return new ColorSpec(value.hex, ColorDepth.TRUECOLOR, undefined, value);
-    }
-    static fromRgb(r, g, b) {
-        return ColorSpec.fromRgba(new ColorRgba(r, g, b));
-    }
-    /**
-     * Parse a color string. Cached — identical strings return the same instance.
-     */
-    static parse(colorString) {
-        const key = colorString.toLowerCase().trim();
-        const cached = parseCache.get(key);
-        if (cached)
-            return cached;
-        const result = parseSingle(key);
-        parseCache.set(key, result);
-        return result;
-    }
-    // --- private ---
-    performDowngrade(targetSystem) {
-        // Get the true RGB of this color
-        const triplet = this.getTruecolor();
-        switch (targetSystem) {
-            case ColorDepth.EIGHT_BIT: {
-                const index = EIGHT_BIT_DOWNGRADE_TABLE.match(triplet);
-                return ColorSpec.fromAnsi(index);
-            }
-            case ColorDepth.STANDARD: {
-                const index = STANDARD_TABLE.match(triplet);
-                return new ColorSpec(`color(${index})`, ColorDepth.STANDARD, index);
-            }
-            // WINDOWS is a detection result (max enum value), not a downgrade target.
-            // The `this.type <= targetSystem` guard in downgrade() always short-circuits
-            // before reaching this method with WINDOWS, so this case is unreachable.
-            case ColorDepth.WINDOWS:
-            case ColorDepth.TRUECOLOR:
-                return this;
-            case ColorDepth.DEFAULT:
-                return ColorSpec.default();
-        }
-    }
-}
-// --- Parsing internals ---
-const HEX_RE = /^#([0-9a-f]{6})$/;
-const HEX_RGBA_RE = /^#([0-9a-f]{8})$/;
-const RGB_RE = /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/;
-const COLOR_NUMBER_RE = /^color\((\d{1,3})\)$/;
-function parseSingle(key) {
-    if (key === "default" || key === "") {
-        return ColorSpec.default();
-    }
-    // Named color
-    const namedIndex = ANSI_COLOR_NAMES[key];
-    if (namedIndex !== undefined) {
-        const type = namedIndex < 16 ? ColorDepth.STANDARD : ColorDepth.EIGHT_BIT;
-        return new ColorSpec(key, type, namedIndex);
-    }
-    // Hex (8-char with alpha takes precedence over 6-char to avoid the 6-char
-    // regex matching a prefix of an 8-char string).
-    const hexRgbaMatch = HEX_RGBA_RE.exec(key);
-    if (hexRgbaMatch) {
-        return new ColorSpec(key, ColorDepth.TRUECOLOR, undefined, parseRgbaHex(hexRgbaMatch[1]));
-    }
-    const hexMatch = HEX_RE.exec(key);
-    if (hexMatch) {
-        return new ColorSpec(key, ColorDepth.TRUECOLOR, undefined, parseRgbHex(hexMatch[1]));
-    }
-    // rgb()
-    const rgbMatch = RGB_RE.exec(key);
-    if (rgbMatch) {
-        const r = parseInt(rgbMatch[1], 10);
-        const g = parseInt(rgbMatch[2], 10);
-        const b = parseInt(rgbMatch[3], 10);
-        return new ColorSpec(key, ColorDepth.TRUECOLOR, undefined, new ColorRgba(r, g, b));
-    }
-    // color(N)
-    const numMatch = COLOR_NUMBER_RE.exec(key);
-    if (numMatch) {
-        const n = parseInt(numMatch[1], 10);
-        if (n > 255) {
-            throw new ColorParseError(`ColorSpec number ${n} is out of range (0-255)`);
-        }
-        const type = n < 16 ? ColorDepth.STANDARD : ColorDepth.EIGHT_BIT;
-        return new ColorSpec(key, type, n);
-    }
-    throw new ColorParseError(`Failed to parse color: "${key}"`);
-}
-// --- Utility functions ---
-export function parseRgbHex(hex) {
-    const r = parseInt(hex.slice(0, 2), 16);
-    const g = parseInt(hex.slice(2, 4), 16);
-    const b = parseInt(hex.slice(4, 6), 16);
-    return new ColorRgba(r, g, b);
-}
-export function parseRgbaHex(hex) {
-    const r = parseInt(hex.slice(0, 2), 16);
-    const g = parseInt(hex.slice(2, 4), 16);
-    const b = parseInt(hex.slice(4, 6), 16);
-    const a = parseInt(hex.slice(6, 8), 16) / 255;
-    return new ColorRgba(r, g, b, a);
-}
-export function blendRgb(color1, color2, crossFade = 0.5) {
-    return new ColorRgba(Math.round(color1.red + (color2.red - color1.red) * crossFade), Math.round(color1.green + (color2.green - color1.green) * crossFade), Math.round(color1.blue + (color2.blue - color1.blue) * crossFade), color1.alpha + (color2.alpha - color1.alpha) * crossFade);
-}
-// --- TerminalTheme ---
-/**
- * A terminal theme — surface/foreground baseline, the ANSI 16/256 LUT, and a
- * semantic palette.
- *
- * **`ansiColors` is the canonical ANSI table, not a per-theme override.** All
- * preset themes in this codebase use `STANDARD_TABLE` for `ansiColors`. Theme
- * identity lives entirely in `palette` (primary, accent, text-*, surface, ...);
- * `ColorSpec.parse("red")` is intentionally consistent across themes — same
- * design as Textual itself, which models theming at the truecolor/semantic
- * layer rather than overloading the ANSI 16. Custom callers building bespoke
- * themes that *do* want to retint ANSI 16 are free to pass their own
- * `ColorTable`; that path is supported but not how the built-in presets work.
- */
-export class TerminalTheme {
-    backgroundColor;
-    foregroundColor;
-    ansiColors;
-    palette;
-    constructor(backgroundColor, foregroundColor, ansiColors, palette) {
-        this.backgroundColor = backgroundColor;
-        this.foregroundColor = foregroundColor;
-        this.ansiColors = ansiColors;
-        this.palette = palette;
-    }
-}
-// --- ColorTable data ---
-function buildStandard16() {
-    return [
-        new ColorRgba(0, 0, 0), // 0  black
-        new ColorRgba(128, 0, 0), // 1  red
-        new ColorRgba(0, 128, 0), // 2  green
-        new ColorRgba(128, 128, 0), // 3  yellow
-        new ColorRgba(0, 0, 128), // 4  blue
-        new ColorRgba(128, 0, 128), // 5  magenta
-        new ColorRgba(0, 128, 128), // 6  cyan
-        new ColorRgba(192, 192, 192), // 7  white
-        new ColorRgba(128, 128, 128), // 8  bright_black
-        new ColorRgba(255, 0, 0), // 9  bright_red
-        new ColorRgba(0, 255, 0), // 10 bright_green
-        new ColorRgba(255, 255, 0), // 11 bright_yellow
-        new ColorRgba(0, 0, 255), // 12 bright_blue
-        new ColorRgba(255, 0, 255), // 13 bright_magenta
-        new ColorRgba(0, 255, 255), // 14 bright_cyan
-        new ColorRgba(255, 255, 255), // 15 bright_white
-    ];
-}
-function build256Table() {
-    const colors = buildStandard16();
-    // 6x6x6 color cube (indices 16-231)
-    const levels = [0, 95, 135, 175, 215, 255];
-    for (let r = 0; r < 6; r++) {
-        for (let g = 0; g < 6; g++) {
-            for (let b = 0; b < 6; b++) {
-                colors.push(new ColorRgba(levels[r], levels[g], levels[b]));
-            }
-        }
-    }
-    // Grayscale ramp (indices 232-255)
-    for (let i = 0; i < 24; i++) {
-        const grey = 8 + 10 * i;
-        colors.push(new ColorRgba(grey, grey, grey));
-    }
-    return colors;
-}
-function buildWindowsTable() {
-    return [
-        new ColorRgba(0, 0, 0), // 0
-        new ColorRgba(0, 0, 128), // 1
-        new ColorRgba(0, 128, 0), // 2
-        new ColorRgba(0, 128, 128), // 3
-        new ColorRgba(128, 0, 0), // 4
-        new ColorRgba(128, 0, 128), // 5
-        new ColorRgba(128, 128, 0), // 6
-        new ColorRgba(192, 192, 192), // 7
-        new ColorRgba(128, 128, 128), // 8
-        new ColorRgba(0, 0, 255), // 9
-        new ColorRgba(0, 255, 0), // 10
-        new ColorRgba(0, 255, 255), // 11
-        new ColorRgba(255, 0, 0), // 12
-        new ColorRgba(255, 0, 255), // 13
-        new ColorRgba(255, 255, 0), // 14
-        new ColorRgba(255, 255, 255), // 15
-    ];
-}
-export const STANDARD_TABLE = new ColorTable(buildStandard16());
-export const EIGHT_BIT_TABLE = new ColorTable(build256Table());
-/**
- * What a downgrade to 256 colours may choose: the cube and the grey ramp,
- * indices 16–255. Indices 0–15 are the terminal's own ANSI colours, which
- * every theme redefines, so their RGB is unknown and a match against them is
- * a guess; Python Rich never picks them either.
- */
-export const EIGHT_BIT_DOWNGRADE_TABLE = new ColorTable(build256Table().slice(16), 16);
-export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
-// --- Internal fallback theme ---
-//
-// [LAW:one-way-deps] Preset themes (DEFAULT_TERMINAL_THEME, MONOKAI, NORD, ...)
-// live in `src/themes/terminalThemes.ts` because they need `buildPalette` from
-// `themes/`. Keeping them out of `core/color.ts` makes the dependency strictly
-// `themes/* -> core/color`, with no runtime back-edge.
-//
-// `getTruecolor()` retains a fallback for callers that omit `theme`. The
-// fallback uses STANDARD_TABLE + black/white + an empty Palette — sufficient
-// for STANDARD/DEFAULT/WINDOWS lookups, which never read `palette`.
-//
-// Runtime-importing `Palette` from `themes/palette.ts` is safe: that module
-// only `import type`s from `core/color.ts`, so there is no runtime cycle.
-import { Palette } from "../themes/palette.js";
-const INTERNAL_DEFAULT_THEME = new TerminalTheme(new ColorRgba(0, 0, 0), new ColorRgba(255, 255, 255), STANDARD_TABLE, new Palette("default", true, new Map()));
-// --- ANSI ColorSpec Names ---
-// [LAW:one-source-of-truth] Single canonical mapping from name → palette index
-/**
- * The table with every `greyNN` name repeated under the `grayNN` spelling.
- *
- * Rich accepts both spellings and the xterm palette only defines one, so the
- * aliases are part of what this table *is* rather than a patch applied to it.
- *
- * [LAW:no-ambient-temporal-coupling] Which is why they arrive as an initializer
- * and not as the loop that used to mutate the finished map: that loop made "has
- * the aliases yet" a fact about module evaluation order, so the table had two
- * shapes and nothing in its type said which one you were holding. It also made
- * this module do work at import time, which is the claim `package.json`'s
- * `sideEffects: false` makes on its behalf — see
- * `test/seam/import-time-effects.ts`.
- */
-function withGrayAliases(names) {
-    const aliases = Object.entries(names)
-        .filter(([name]) => name.includes("grey"))
-        .map(([name, index]) => [name.replace("grey", "gray"), index]);
-    return { ...names, ...Object.fromEntries(aliases) };
-}
-export const ANSI_COLOR_NAMES = withGrayAliases({
-    // Standard 16
-    black: 0,
-    red: 1,
-    green: 2,
-    yellow: 3,
-    blue: 4,
-    magenta: 5,
-    cyan: 6,
-    white: 7,
-    bright_black: 8,
-    bright_red: 9,
-    bright_green: 10,
-    bright_yellow: 11,
-    bright_blue: 12,
-    bright_magenta: 13,
-    bright_cyan: 14,
-    bright_white: 15,
-    // 6x6x6 color cube (16-231)
-    grey0: 16,
-    navy_blue: 17,
-    dark_blue: 18,
-    blue3: 19,
-    blue2: 20,
-    blue1: 21,
-    dark_green: 22,
-    deep_sky_blue4: 23,
-    deep_sky_blue5: 24,
-    deep_sky_blue6: 25,
-    dodger_blue3: 26,
-    dodger_blue2: 27,
-    green4: 28,
-    spring_green4: 29,
-    turquoise4: 30,
-    deep_sky_blue3: 31,
-    deep_sky_blue7: 32,
-    dodger_blue1: 33,
-    green3: 34,
-    spring_green3: 35,
-    dark_cyan: 36,
-    light_sea_green: 37,
-    deep_sky_blue2: 38,
-    deep_sky_blue1: 39,
-    green5: 40,
-    spring_green5: 41,
-    spring_green2: 42,
-    cyan3: 43,
-    dark_turquoise: 44,
-    turquoise2: 45,
-    green1: 46,
-    spring_green6: 47,
-    spring_green1: 48,
-    medium_spring_green: 49,
-    cyan2: 50,
-    cyan1: 51,
-    dark_red: 52,
-    deep_pink4: 53,
-    purple4: 54,
-    purple5: 55,
-    purple3: 56,
-    blue_violet: 57,
-    orange4: 58,
-    grey37: 59,
-    medium_purple4: 60,
-    slate_blue3: 61,
-    slate_blue4: 62,
-    royal_blue1: 63,
-    chartreuse4: 64,
-    dark_sea_green4: 65,
-    pale_turquoise4: 66,
-    steel_blue: 67,
-    steel_blue3: 68,
-    cornflower_blue: 69,
-    chartreuse3: 70,
-    dark_sea_green5: 71,
-    cadet_blue: 72,
-    cadet_blue2: 73,
-    sky_blue3: 74,
-    steel_blue1: 75,
-    chartreuse5: 76,
-    pale_green3: 77,
-    sea_green3: 78,
-    aquamarine3: 79,
-    medium_turquoise: 80,
-    steel_blue2: 81,
-    chartreuse2: 82,
-    sea_green2: 83,
-    sea_green1: 84,
-    sea_green4: 85,
-    aquamarine1: 86,
-    dark_slate_gray2: 87,
-    dark_red2: 88,
-    deep_pink5: 89,
-    dark_magenta: 90,
-    dark_magenta2: 91,
-    dark_violet: 92,
-    purple2: 93,
-    orange5: 94,
-    light_pink4: 95,
-    plum4: 96,
-    medium_purple3: 97,
-    medium_purple5: 98,
-    slate_blue1: 99,
-    yellow4: 100,
-    wheat4: 101,
-    grey53: 102,
-    light_slate_grey: 103,
-    medium_purple: 104,
-    light_slate_blue: 105,
-    yellow5: 106,
-    dark_olive_green3: 107,
-    dark_sea_green: 108,
-    light_sky_blue3: 109,
-    light_sky_blue4: 110,
-    sky_blue2: 111,
-    chartreuse6: 112,
-    dark_olive_green4: 113,
-    pale_green4: 114,
-    dark_sea_green3: 115,
-    dark_slate_gray3: 116,
-    sky_blue1: 117,
-    chartreuse1: 118,
-    light_green: 119,
-    light_green2: 120,
-    pale_green1: 121,
-    aquamarine2: 122,
-    dark_slate_gray1: 123,
-    red3: 124,
-    deep_pink6: 125,
-    medium_violet_red: 126,
-    magenta3: 127,
-    dark_violet2: 128,
-    purple: 129,
-    dark_orange3: 130,
-    indian_red: 131,
-    hot_pink3: 132,
-    medium_orchid3: 133,
-    medium_orchid: 134,
-    medium_purple2: 135,
-    dark_goldenrod: 136,
-    light_salmon3: 137,
-    rosy_brown: 138,
-    grey63: 139,
-    medium_purple6: 140,
-    medium_purple1: 141,
-    gold3: 142,
-    dark_khaki: 143,
-    navajo_white3: 144,
-    grey69: 145,
-    light_steel_blue3: 146,
-    light_steel_blue: 147,
-    yellow3: 148,
-    dark_olive_green5: 149,
-    dark_sea_green6: 150,
-    dark_sea_green2: 151,
-    light_cyan3: 152,
-    light_sky_blue1: 153,
-    green_yellow: 154,
-    dark_olive_green2: 155,
-    pale_green2: 156,
-    dark_sea_green7: 157,
-    dark_sea_green1: 158,
-    pale_turquoise1: 159,
-    red4: 160,
-    deep_pink3: 161,
-    deep_pink8: 162,
-    magenta4: 163,
-    magenta5: 164,
-    magenta2: 165,
-    dark_orange4: 166,
-    indian_red2: 167,
-    hot_pink4: 168,
-    hot_pink2: 169,
-    orchid: 170,
-    medium_orchid1: 171,
-    orange3: 172,
-    light_salmon4: 173,
-    light_pink3: 174,
-    pink3: 175,
-    plum3: 176,
-    violet: 177,
-    gold4: 178,
-    light_goldenrod3: 179,
-    tan: 180,
-    misty_rose3: 181,
-    thistle3: 182,
-    plum2: 183,
-    yellow6: 184,
-    khaki3: 185,
-    light_goldenrod2: 186,
-    light_yellow3: 187,
-    grey84: 188,
-    light_steel_blue1: 189,
-    yellow2: 190,
-    dark_olive_green1: 191,
-    dark_olive_green6: 192,
-    dark_sea_green8: 193,
-    honeydew2: 194,
-    light_cyan1: 195,
-    red1: 196,
-    deep_pink2: 197,
-    deep_pink1: 198,
-    deep_pink9: 199,
-    magenta6: 200,
-    magenta1: 201,
-    orange_red1: 202,
-    indian_red1: 203,
-    indian_red3: 204,
-    hot_pink5: 205,
-    hot_pink: 206,
-    medium_orchid2: 207,
-    dark_orange: 208,
-    salmon1: 209,
-    light_coral: 210,
-    pale_violet_red1: 211,
-    orchid2: 212,
-    orchid1: 213,
-    orange1: 214,
-    sandy_brown: 215,
-    light_salmon1: 216,
-    light_pink1: 217,
-    pink1: 218,
-    plum1: 219,
-    gold1: 220,
-    light_goldenrod4: 221,
-    light_goldenrod5: 222,
-    navajo_white1: 223,
-    misty_rose1: 224,
-    thistle1: 225,
-    yellow1: 226,
-    light_goldenrod1: 227,
-    khaki1: 228,
-    wheat1: 229,
-    cornsilk1: 230,
-    grey100: 231,
-    // Grayscale ramp (232-255)
-    grey3: 232,
-    grey7: 233,
-    grey11: 234,
-    grey15: 235,
-    grey19: 236,
-    grey23: 237,
-    grey27: 238,
-    grey30: 239,
-    grey35: 240,
-    grey39: 241,
-    grey42: 242,
-    grey46: 243,
-    grey50: 244,
-    grey54: 245,
-    grey58: 246,
-    grey62: 247,
-    grey66: 248,
-    grey70: 249,
-    grey74: 250,
-    grey78: 251,
-    grey82: 252,
-    grey85: 253,
-    grey89: 254,
-    grey93: 255,
-});
-/**
- * Every word `ColorSpec.parse` accepts as a name rather than a `#hex`,
- * `rgb()` or `color(N)` form: `default` and the named palette entries, which
- * are exactly the two name checks `parseSingle` makes.
- */
-export const COLOR_NAMES = ["default", ...Object.keys(ANSI_COLOR_NAMES)];