@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/color.js

@@ -1,6 +1,7 @@
 /**
  * Terminal color representation, parsing, downgrading, and ANSI code generation.
  */
+import { Memo } from "./memo.js";
 // --- ColorRgba ---
 function hex2(byte) {
     return byte.toString(16).padStart(2, "0");
@@ -73,8 +74,9 @@ export class ColorRgba {
 /**
  * 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
+ * exports that picture its output (`resolveLook`), 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);
@@ -110,36 +112,27 @@ 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) {
+// `matchWhere`'s "nearest by the distance `match` uses" cannot drift, and
+// `Effected` weighs a written colour against `ColorSpec.matchOn` by it too.
+export 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;
 }
+/**
+ * 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.
+ */
 export class ColorTable {
     colors;
     firstIndex;
-    matchCache = new Map();
-    readableCache = new Map();
+    // Keyed by colours a host computes without end (ramp stops, mixes), so bounded.
+    matchMemo = new Memo();
+    readableMemo = new Memo();
     constructor(colors, firstIndex = 0) {
         this.colors = colors;
         this.firstIndex = firstIndex;
@@ -164,9 +157,9 @@ export class ColorTable {
      */
     match(value) {
         const key = `${value.red},${value.green},${value.blue},${value.alpha}`;
-        const cached = this.matchCache.get(key);
-        if (cached !== undefined)
-            return cached;
+        return this.matchMemo.get(key, () => this.nearest(value));
+    }
+    nearest(value) {
         let bestIndex = 0;
         let bestDist = Infinity;
         for (let i = 0; i < this.colors.length; i++) {
@@ -177,7 +170,7 @@ export class ColorTable {
                 bestIndex = i;
             }
         }
-        return remember(this.matchCache, key, this.firstIndex + bestIndex);
+        return this.firstIndex + bestIndex;
     }
     /**
      * The nearest entry to `value` (the distance `match` uses) among those that
@@ -190,9 +183,9 @@ export class ColorTable {
      */
     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;
+        return this.readableMemo.get(key, () => this.nearestReadable(value, on, minRatio));
+    }
+    nearestReadable(value, on, minRatio) {
         const lOn = relativeLuminance(on);
         let best = 0;
         let bestPasses = false;
@@ -212,7 +205,7 @@ export class ColorTable {
                 bestScore = score;
             }
         }
-        return remember(this.readableCache, key, this.firstIndex + best);
+        return this.firstIndex + best;
     }
     /**
      * The nearest entry to `value` (the distance `match` uses) among those
@@ -238,38 +231,62 @@ export var ColorDepth;
     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
+/**
+ * How many colours a depth can name, as a rank. WINDOWS is a sixteen-colour
+ * depth whose enum value sits above TRUECOLOR, so the enum's order is not this.
+ * STANDARD and WINDOWS share a rank: the same sixteen slots, drawn by
+ * different terminals, so each converts to the other by keeping the slot.
+ */
+function fidelity(depth) {
+    switch (depth) {
+        case ColorDepth.DEFAULT:
+            return 0;
+        case ColorDepth.STANDARD:
+        case ColorDepth.WINDOWS:
+            return 1;
+        case ColorDepth.EIGHT_BIT:
+            return 2;
+        case ColorDepth.TRUECOLOR:
+            return 3;
+    }
+}
+// The depths a colour system is named for. Its keys and "auto" are the whole
+// vocabulary: `ColorSystemName` is derived from them, so the type and the
+// table cannot disagree. [LAW:one-source-of-truth]
+const COLOR_SYSTEM_DEPTHS = {
     truecolor: ColorDepth.TRUECOLOR,
     "256": ColorDepth.EIGHT_BIT,
     ansi: ColorDepth.STANDARD,
     none: null,
+};
+// [LAW:one-source-of-truth] What the environment says about colour, by the
+// value it says it with: FORCE_COLOR values (the chalk/supports-color
+// convention), TERM_PROGRAM identifiers, and exact TERM names whose colour
+// capability is known. A different vocabulary from `ColorSystemName`, so a
+// different table: `FORCE_COLOR=none` is not a request for no colour. A `Map`,
+// so a value naming an `Object.prototype` member is unknown, not a function.
+// `null` means "no color".
+const ENV_DEPTHS = new Map([
     // FORCE_COLOR values
-    "0": null,
-    false: null,
-    "1": ColorDepth.STANDARD,
-    true: ColorDepth.STANDARD,
-    "2": ColorDepth.EIGHT_BIT,
-    "3": ColorDepth.TRUECOLOR,
+    ["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,
+    ["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,
-};
+    ["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.
  *
@@ -296,12 +313,21 @@ function forcedColorSystem(env) {
     const force = env["FORCE_COLOR"];
     if (force === undefined || force === "")
         return undefined;
-    const mapped = STRING_TO_DEPTH[force];
+    const mapped = ENV_DEPTHS.get(force);
     return mapped !== undefined ? mapped : ColorDepth.STANDARD;
 }
 function envOf(options) {
     return options.env ?? (typeof process !== "undefined" ? process.env : {});
 }
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
+ * cursor.
+ */
+export function isDumbTerminal(env) {
+    const term = env["TERM"];
+    return term === "dumb" || term === "unknown";
+}
 // 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.
@@ -311,19 +337,19 @@ function terminalColorSystem(options) {
         (typeof process !== "undefined" ? (process.stdout?.isTTY ?? false) : false);
     if (!isTTY)
         return null;
-    const term = env["TERM"] ?? "";
-    if (term === "dumb" || term === "unknown")
+    if (isDumbTerminal(env))
         return null;
+    const term = env["TERM"] ?? "";
     const colorterm = env["COLORTERM"];
     if (colorterm === "truecolor" || colorterm === "24bit") {
         return ColorDepth.TRUECOLOR;
     }
-    const termDepth = STRING_TO_DEPTH[term];
+    const termDepth = ENV_DEPTHS.get(term);
     if (termDepth !== undefined)
         return termDepth;
     const termProgram = env["TERM_PROGRAM"];
     if (termProgram !== undefined) {
-        const mapped = STRING_TO_DEPTH[termProgram];
+        const mapped = ENV_DEPTHS.get(termProgram);
         if (mapped !== undefined)
             return mapped;
     }
@@ -364,20 +390,20 @@ export function resolveDestination(spec, options) {
     };
 }
 /**
- * Resolve a string spec into a `ColorDepth` (or `null` for no color).
+ * Resolve a colour system name 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.
+ * `"auto"` triggers env-based detection; every other name is a fixed depth.
+ * A name outside the vocabulary — reachable only from untyped JavaScript —
+ * throws: silent fallback would mask a typo.
  *
- * [LAW:single-enforcer] All string→ColorDepth resolution flows through here.
+ * [LAW:single-enforcer] All name→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")`);
+    if (Object.hasOwn(COLOR_SYSTEM_DEPTHS, spec))
+        return COLOR_SYSTEM_DEPTHS[spec];
+    throw new ColorParseError(`Unknown color system name: ${JSON.stringify(spec)} (expected "auto", "truecolor", "256", "ansi", or "none")`);
 }
 // --- ColorSpec ---
 export class ColorParseError extends Error {
@@ -386,8 +412,8 @@ export class ColorParseError extends Error {
         this.name = "ColorParseError";
     }
 }
-// [LAW:one-source-of-truth] Parse cache is the single source for parsed ColorSpec instances
-const parseCache = new Map();
+// [LAW:one-source-of-truth] The single source for parsed ColorSpec instances.
+const colorSpecParseMemo = new Memo();
 export class ColorSpec {
     name;
     type;
@@ -408,8 +434,9 @@ export class ColorSpec {
      * 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.
+     * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15,
+     * the default colour and a blend reaching either are the terminal theme's
+     * own, so they have none.
      */
     get fixedValue() {
         switch (this.type) {
@@ -489,7 +516,7 @@ export class ColorSpec {
     downgrade(targetSystem) {
         if (this.type === ColorDepth.DEFAULT)
             return this;
-        if (this.type <= targetSystem)
+        if (this.type === targetSystem || fidelity(this.type) < fidelity(targetSystem))
             return this;
         const cached = this.downgradeCache.get(targetSystem);
         if (cached)
@@ -507,19 +534,14 @@ export class ColorSpec {
                 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);
-            }
+                return this.number < 16 ? resolveTerminal(theme, this.type).ansiColors.get(this.number) : EIGHT_BIT_TABLE.get(this.number);
+            case ColorDepth.STANDARD:
+            case ColorDepth.WINDOWS:
+                return resolveTerminal(theme, this.type).ansiColors.get(this.number);
             case ColorDepth.DEFAULT: {
-                const t = theme ?? INTERNAL_DEFAULT_THEME;
+                const t = resolveTerminal(theme, this.type);
                 return foreground ? t.foregroundColor : t.backgroundColor;
             }
-            case ColorDepth.WINDOWS: {
-                const t = theme ?? INTERNAL_DEFAULT_THEME;
-                return t.ansiColors.get(this.number);
-            }
         }
     }
     // --- Static factories ---
@@ -537,34 +559,83 @@ export class ColorSpec {
         return ColorSpec.fromRgba(new ColorRgba(r, g, b));
     }
     /**
-     * Parse a color string. Cached — identical strings return the same instance.
+     * The colour `t` of the way from `from` to `to`: what `blend(from,to,t)`
+     * parses to. Two fixed colours mix to a fixed colour. A mix reaching a
+     * theme's own colour stays a mix until it is drawn, so whatever theme draws
+     * an end draws the mix from it: exported under a theme whose `blue` is
+     * #61afef, a mix with `blue` starts from #61afef. A terminal is told its RGB
+     * under the standard table, the only one a render has.
+     *
+     * Each end is one opaque colour: `default` is no colour to mix, and a
+     * translucent end has no one shade until it is laid on a ground.
+     */
+    static blend(from, to, t) {
+        for (const end of [from, to]) {
+            if (end.isDefault)
+                throw new ColorParseError(`A blend cannot mix "default", which is no colour`);
+            if (end.value !== undefined && end.value.alpha < 1) {
+                throw new ColorParseError(`A blend's ends are opaque; "${end.name}" is translucent`);
+            }
+        }
+        if (!(t >= 0 && t <= 1))
+            throw new ColorParseError(`A blend's fraction is in [0, 1]; got ${t}`);
+        const a = from.fixedValue;
+        const b = to.fixedValue;
+        return a !== undefined && b !== undefined ? ColorSpec.fromRgba(blendRgb(a, b, t)) : new ColorBlend(from, to, t);
+    }
+    /**
+     * The spec that draws `value` nearest to it at `depth` on a terminal known
+     * to show `theme`, as the colour of the glyph (`foreground`) or of the
+     * ground. Where `downgrade` knows no terminal, and so rounds only against
+     * colours every terminal fixes (or, at sixteen colours, the stock
+     * sixteen), this rounds against every colour the depth can write whose
+     * look `theme` fixes: the default colour, the theme's sixteen, and at 256
+     * colours the cube and grey ramp too. A colour read off any of those and
+     * moved a little is drawn as the colour it came from — or, where the theme
+     * gives two slots one colour, as the lower slot, which looks the same.
+     *
+     * `value` is opaque: a translucent colour has no one look until it is laid
+     * on a ground (`flattenAlpha`).
+     */
+    static matchOn(value, depth, theme, foreground) {
+        if (value.alpha < 1)
+            throw new RangeError(`matchOn rounds an opaque colour; got alpha ${value.alpha}`);
+        if (depth === ColorDepth.TRUECOLOR)
+            return ColorSpec.fromRgba(value);
+        if (depth === ColorDepth.DEFAULT)
+            return ColorSpec.default();
+        const slot = theme.ansiColors.match(value);
+        // [LAW:dataflow-not-control-flow] Every candidate is scored; the depth
+        // only decides whether the cube is among them. Ties go to the earlier.
+        const candidates = [
+            [ColorSpec.default(), foreground ? theme.foregroundColor : theme.backgroundColor],
+            [new ColorSpec(`color(${slot})`, depth === ColorDepth.WINDOWS ? depth : ColorDepth.STANDARD, slot), theme.ansiColors.get(slot)],
+            ...(depth === ColorDepth.EIGHT_BIT ? [cubeCandidate(value)] : []),
+        ];
+        return candidates.reduce((best, next) => (rgbDistance(next[1], value) < rgbDistance(best[1], value) ? next : best))[0];
+    }
+    /**
+     * Parse a color string. Memoized (`Memo`): a string parsed again while
+     * remembered returns 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;
+        return colorSpecParseMemo.get(colorString.toLowerCase().trim(), parseSingle);
     }
     // --- private ---
     performDowngrade(targetSystem) {
-        // Get the true RGB of this color
-        const triplet = this.getTruecolor();
+        // The colour as the terminal this depth assumes draws it: a blend's named
+        // ends are the Windows console's own at WINDOWS.
+        const triplet = this.getTruecolor(resolveTerminal(undefined, targetSystem));
         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);
+            case ColorDepth.EIGHT_BIT:
+                return ColorSpec.fromAnsi(downgradeTable(targetSystem).match(triplet));
+            case ColorDepth.STANDARD:
+            case ColorDepth.WINDOWS: {
+                // An ANSI slot is already one of the sixteen either depth writes; only
+                // a fixed colour is matched against the depth's table, as Rich does.
+                const index = this.number !== undefined && this.number < 16 ? this.number : downgradeTable(targetSystem).match(triplet);
+                return new ColorSpec(`color(${index})`, targetSystem, 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:
@@ -572,11 +643,47 @@ export class ColorSpec {
         }
     }
 }
+/** The cube or grey-ramp entry nearest `value`, and its colour. */
+function cubeCandidate(value) {
+    const index = EIGHT_BIT_DOWNGRADE_TABLE.match(value);
+    return [ColorSpec.fromAnsi(index), EIGHT_BIT_DOWNGRADE_TABLE.get(index)];
+}
+function mix(from, to, t, theme) {
+    return blendRgb(from.getTruecolor(theme), to.getTruecolor(theme), t);
+}
+// How a blend spells an end: by what it draws as, so every spelling of one
+// colour ("blue", "color(4)", an EIGHT_BIT 4) gives the blend one name.
+function blendTerm(end) {
+    return end.fixedValue?.hex ?? (end.number !== undefined ? `color(${end.number})` : end.name);
+}
+/**
+ * `ColorSpec.blend` with an end the theme draws. A terminal is told it as a
+ * truecolor value, so it is one, and `value` is what it is told; a theme is
+ * asked of its two ends instead. Its name is what `ColorSpec.parse` reads back.
+ */
+class ColorBlend extends ColorSpec {
+    from;
+    to;
+    t;
+    constructor(from, to, t) {
+        super(`blend(${blendTerm(from)},${blendTerm(to)},${t})`, ColorDepth.TRUECOLOR, undefined, mix(from, to, t));
+        this.from = from;
+        this.to = to;
+        this.t = t;
+    }
+    get fixedValue() {
+        return undefined;
+    }
+    getTruecolor(theme) {
+        return mix(this.from, this.to, this.t, theme);
+    }
+}
 // --- 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+)\)$/;
+const BLEND_RE = /^blend\((.*)\)$/;
+// A decimal as `String(number)` spells one, exponent included; `blend` owns its range.
+const FRACTION_RE = /^\s*(?:\d+(?:\.\d+)?|\.\d+)(?:e[+-]?\d+)?\s*$/;
 function parseSingle(key) {
     if (key === "default" || key === "") {
         return ColorSpec.default();
@@ -587,15 +694,8 @@ function parseSingle(key) {
         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]));
+    if (key.startsWith("#")) {
+        return new ColorSpec(key, ColorDepth.TRUECOLOR, undefined, parseHexColor(key));
     }
     // rgb()
     const rgbMatch = RGB_RE.exec(key);
@@ -612,8 +712,38 @@ function parseSingle(key) {
         const type = n < 16 ? ColorDepth.STANDARD : ColorDepth.EIGHT_BIT;
         return new ColorSpec(key, type, n);
     }
+    // blend(a,b,t)
+    const blendMatch = BLEND_RE.exec(key);
+    if (blendMatch) {
+        const terms = blendTerms(blendMatch[1]);
+        const fraction = terms[2] ?? "";
+        if (terms.length !== 3 || !FRACTION_RE.test(fraction)) {
+            throw new ColorParseError(`ColorSpec "${key}": a blend is blend(<color>,<color>,<fraction>)`);
+        }
+        return ColorSpec.blend(ColorSpec.parse(terms[0]), ColorSpec.parse(terms[1]), Number(fraction));
+    }
     throw new ColorParseError(`Failed to parse color: "${key}"`);
 }
+// A blend's terms, split at the commas outside parentheses so an `rgb(…)` or a
+// nested `blend(…)` stays one term.
+function blendTerms(inner) {
+    const terms = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < inner.length; i++) {
+        const c = inner[i];
+        if (c === "(")
+            depth++;
+        else if (c === ")")
+            depth--;
+        else if (c === "," && depth === 0) {
+            terms.push(inner.slice(start, i));
+            start = i + 1;
+        }
+    }
+    terms.push(inner.slice(start));
+    return terms;
+}
 // [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.
@@ -625,26 +755,45 @@ function parseByte(key, digits, field) {
     return n;
 }
 // --- Utility functions ---
+// [LAW:single-enforcer] The hex colour grammar, checked here and nowhere else:
+// every string spelling a colour in hex — a ColorSpec, a theme's data, a colour
+// reference, a template argument — becomes one through the three parsers below,
+// and each is this check at the lengths it admits. Each digit pair is a byte, so
+// the grammar holding is what keeps `ColorRgba`'s channels in range.
+const HEX_DIGITS_RE = /^[0-9a-fA-F]+$/;
+// Each admitted digit count, by the grammar it spells: the message a failure
+// carries is read off the lengths a parser admits, so the two cannot disagree.
+const HEX_GRAMMARS = { 6: "RRGGBB", 8: "RRGGBBAA" };
+function hexColor(input, lead, digits, lengths) {
+    if (!lengths.includes(digits.length) || !HEX_DIGITS_RE.test(digits)) {
+        const expected = lengths.map((n) => lead + HEX_GRAMMARS[n]).join(" or ");
+        throw new ColorParseError(`Invalid hex colour ${JSON.stringify(input)} (expected ${expected})`);
+    }
+    const byte = (at) => parseInt(digits.slice(at, at + 2), 16);
+    return new ColorRgba(byte(0), byte(2), byte(4), digits.length === 8 ? byte(6) / 255 : 1);
+}
+/** Six hex digits, no `#`, as an opaque colour. @throws {ColorParseError} on anything else. */
 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);
+    return hexColor(hex, "", hex, [6]);
 }
+/** Eight hex digits, no `#`, the last pair alpha. @throws {ColorParseError} on anything else. */
 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);
+    return hexColor(hex, "", hex, [8]);
+}
+/**
+ * A `#RRGGBB` or `#RRGGBBAA` literal, exactly — no surrounding whitespace.
+ * @throws {ColorParseError} on anything else.
+ */
+export function parseHexColor(literal) {
+    return hexColor(literal, "#", literal.startsWith("#") ? literal.slice(1) : "", [6, 8]);
 }
 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.
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * 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")`
@@ -661,6 +810,11 @@ export class TerminalTheme {
         this.foregroundColor = foregroundColor;
         this.ansiColors = ansiColors;
         this.palette = palette;
+        // [LAW:parse-dont-validate] Every reader indexes `ansiColors` 0–15 as the
+        // terminal's sixteen, so a theme is the proof it holds exactly those.
+        if (ansiColors.firstIndex !== 0 || ansiColors.size !== 16) {
+            throw new RangeError(`a TerminalTheme's ansiColors are the sixteen ANSI colours, indices 0–15; got ${ansiColors.size} from index ${ansiColors.firstIndex}`);
+        }
     }
 }
 // --- ColorTable data ---
@@ -702,24 +856,29 @@ function build256Table() {
     }
     return colors;
 }
+/**
+ * The Windows console's own sixteen (its default Campbell scheme), in ANSI
+ * index order: a WINDOWS colour is written as the same `30+n`/`90+n` SGR a
+ * STANDARD one is, so slot `n` here is the colour the console draws for it.
+ */
 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
+        new ColorRgba(12, 12, 12), // 0  black
+        new ColorRgba(197, 15, 31), // 1  red
+        new ColorRgba(19, 161, 14), // 2  green
+        new ColorRgba(193, 156, 0), // 3  yellow
+        new ColorRgba(0, 55, 218), // 4  blue
+        new ColorRgba(136, 23, 152), // 5  magenta
+        new ColorRgba(58, 150, 221), // 6  cyan
+        new ColorRgba(204, 204, 204), // 7  white
+        new ColorRgba(118, 118, 118), // 8  bright_black
+        new ColorRgba(231, 72, 86), // 9  bright_red
+        new ColorRgba(22, 198, 12), // 10 bright_green
+        new ColorRgba(249, 241, 165), // 11 bright_yellow
+        new ColorRgba(59, 120, 255), // 12 bright_blue
+        new ColorRgba(180, 0, 158), // 13 bright_magenta
+        new ColorRgba(97, 214, 214), // 14 bright_cyan
+        new ColorRgba(242, 242, 242), // 15 bright_white
     ];
 }
 export const STANDARD_TABLE = new ColorTable(buildStandard16());
@@ -739,14 +898,43 @@ export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
 // `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`.
+// `getTruecolor()` retains a fallback for callers that omit `theme`: the
+// terminal a colour's depth assumes, built from that depth's own sixteen with
+// an empty Palette — sufficient for the lookups it serves, 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()));
+/** The Windows console in its default Campbell scheme: a WINDOWS colour's terminal. */
+const WINDOWS_CONSOLE_THEME = new TerminalTheme(WINDOWS_TABLE.get(0), WINDOWS_TABLE.get(7), WINDOWS_TABLE, new Palette("windows", true, new Map()));
+/**
+ * The terminal a colour at `depth` is drawn by: `theme`, or when a caller names
+ * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
+ * sixteen otherwise — for `ColorSpec.getTruecolor` and the contrast measurement
+ * that reads it. (Widgets fall back to `DEFAULT_TERMINAL_THEME`, which carries a
+ * palette this does not.)
+ */
+export function resolveTerminal(theme, depth) {
+    return theme ?? (depth === ColorDepth.WINDOWS ? WINDOWS_CONSOLE_THEME : INTERNAL_DEFAULT_THEME);
+}
+/**
+ * The table a downgrade to `depth` rounds a fixed colour against.
+ * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a colour is
+ * written as from it, and colorMath hands back its entries as colours the
+ * writer rounds to those same indices.
+ */
+export function downgradeTable(depth) {
+    switch (depth) {
+        case ColorDepth.EIGHT_BIT:
+            return EIGHT_BIT_DOWNGRADE_TABLE;
+        case ColorDepth.STANDARD:
+            return STANDARD_TABLE;
+        case ColorDepth.WINDOWS:
+            return WINDOWS_TABLE;
+    }
+}
 // --- ANSI ColorSpec Names ---
 // [LAW:one-source-of-truth] Single canonical mapping from name → palette index
 /**