@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/color.js

@@ -0,0 +1,1038 @@
+/**
+ * Terminal color representation, parsing, downgrading, and ANSI code generation.
+ */
+// --- ColorRgba ---
+function hex2(byte) {
+    return byte.toString(16).padStart(2, "0");
+}
+// [LAW:one-source-of-truth] The one statement of a colour byte's range: the
+// constructor asserts it and the string parser reports it, from this predicate.
+function isByte(v) {
+    return Number.isInteger(v) && v >= 0 && v <= 255;
+}
+function assertChannel(name, v) {
+    if (!isByte(v)) {
+        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:
+                // Slots 0–15 are the theme's own whatever depth names them, as `fixedValue` says.
+                return this.number < 16 ? (theme ?? INTERNAL_DEFAULT_THEME).ansiColors.get(this.number) : 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+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/;
+const COLOR_NUMBER_RE = /^color\((\d+)\)$/;
+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 = parseByte(key, rgbMatch[1], "red");
+        const g = parseByte(key, rgbMatch[2], "green");
+        const b = parseByte(key, rgbMatch[3], "blue");
+        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 = parseByte(key, numMatch[1], "number");
+        const type = n < 16 ? ColorDepth.STANDARD : ColorDepth.EIGHT_BIT;
+        return new ColorSpec(key, type, n);
+    }
+    throw new ColorParseError(`Failed to parse color: "${key}"`);
+}
+// [LAW:single-enforcer] The regexes admit any run of digits and leave the
+// range to this check alone, so every out-of-range byte is a ColorParseError
+// naming the field, never the generic parse failure or the constructor's RangeError.
+function parseByte(key, digits, field) {
+    const n = parseInt(digits, 10);
+    if (!isByte(n)) {
+        throw new ColorParseError(`ColorSpec "${key}": ${field} ${digits} is out of range (0-255)`);
+    }
+    return n;
+}
+// --- 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 theme's own sixteen colours**, the shades a terminal
+ * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
+ * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * as it is in Rich, where each `TerminalTheme` carries its own table.
+ */
+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)];