@promptctl/rich-js 0.12.0 → 0.14.0

package/dist/core/color.d.ts

@@ -31,11 +31,42 @@ export declare class ColorRgba {
      */
     compositeOver(bg: ColorRgba): 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
+ * the colour text is chosen against is the colour the writer draws.
+ */
+export declare const SURFACE_BLACK: ColorRgba;
+/**
+ * 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 declare function relativeLuminance(c: ColorRgba): number;
+/**
+ * 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 declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
 export declare class ColorTable {
     private readonly colors;
+    private readonly firstIndex;
     private readonly matchCache;
-    constructor(colors: ColorRgba[]);
+    private readonly readableCache;
+    constructor(colors: ColorRgba[], firstIndex?: number);
     get(index: number): ColorRgba;
+    private luminanceCache;
+    /** Each entry's relative luminance, computed once per table. */
+    private luminances;
+    /** How many entries the table holds (terminal indices `firstIndex`…). */
     get size(): number;
     /**
      * Finds the nearest table index to the given color (Euclidean RGB distance, cached).
@@ -43,6 +74,16 @@ export declare class ColorTable {
      * don't collide, but is not used in the distance metric.
      */
     match(value: ColorRgba): number;
+    /**
+     * 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: ColorRgba, on: ColorRgba, minRatio: number): number;
 }
 export declare enum ColorDepth {
     DEFAULT = 0,
@@ -153,6 +194,13 @@ export declare class TerminalTheme {
 }
 export declare const STANDARD_TABLE: ColorTable;
 export declare const EIGHT_BIT_TABLE: ColorTable;
+/**
+ * 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 declare const EIGHT_BIT_DOWNGRADE_TABLE: ColorTable;
 export declare const WINDOWS_TABLE: ColorTable;
 export declare const ANSI_COLOR_NAMES: Record<string, number>;
 /**

package/dist/core/color.js

@@ -65,16 +65,82 @@ export class ColorRgba {
         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;
+}
 export class ColorTable {
     colors;
+    firstIndex;
     matchCache = new Map();
-    constructor(colors) {
+    readableCache = new Map();
+    constructor(colors, firstIndex = 0) {
         this.colors = colors;
+        this.firstIndex = firstIndex;
     }
     get(index) {
-        return this.colors[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;
     }
@@ -101,8 +167,45 @@ export class ColorTable {
                 bestIndex = i;
             }
         }
-        this.matchCache.set(key, bestIndex);
-        return bestIndex;
+        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;
+            const dr = c.red - value.red;
+            const dg = c.green - value.green;
+            const db = c.blue - value.blue;
+            // A passing entry scores by closeness; a failing one only by contrast,
+            // and loses to every passing one.
+            const score = passes ? -(dr * dr + dg * dg + db * db) : ratio;
+            if ((passes && !bestPasses) ||
+                (passes === bestPasses && score > bestScore)) {
+                best = i;
+                bestPasses = passes;
+                bestScore = score;
+            }
+        }
+        return remember(this.readableCache, key, this.firstIndex + best);
     }
 }
 // --- Enums ---
@@ -370,7 +473,7 @@ export class ColorSpec {
         const triplet = this.getTruecolor();
         switch (targetSystem) {
             case ColorDepth.EIGHT_BIT: {
-                const index = EIGHT_BIT_TABLE.match(triplet);
+                const index = EIGHT_BIT_DOWNGRADE_TABLE.match(triplet);
                 return ColorSpec.fromAnsi(index);
             }
             case ColorDepth.STANDARD: {
@@ -537,6 +640,13 @@ function buildWindowsTable() {
 }
 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 ---
 //

package/dist/core/strip.js

@@ -26,8 +26,8 @@
  * styling, so the cell type does too.
  */
 import { Segment } from "./segment.js";
-import { Style, SURFACE_BLACK } from "./style.js";
-import { ColorSpec, blendRgb } from "./color.js";
+import { Style } from "./style.js";
+import { ColorSpec, SURFACE_BLACK, blendRgb } from "./color.js";
 import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {

package/dist/core/style.d.ts

@@ -1,8 +1,7 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { ColorRgba, ColorSpec, ColorDepth } from "./color.js";
-export declare const SURFACE_BLACK: ColorRgba;
+import { ColorSpec, ColorDepth } from "./color.js";
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by
  * `Style.parse` / `Style.toString` and the template bindings — adding an

package/dist/core/style.js

@@ -1,14 +1,11 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { COLOR_NAMES, ColorRgba, ColorSpec, } from "./color.js";
+import { COLOR_NAMES, ColorSpec, SURFACE_BLACK, } from "./color.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 // [LAW:one-way-deps] `core/style` depends only on `core/color` and the leaf
-// `core/osc8` (the link wire grammar). The substrate fallback is the
-// canonical canvas color (black), inlined to avoid pulling in any preset
-// theme constants. Preset themes live in `src/themes/` and depend on core,
-// never the reverse.
-export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
+// `core/osc8` (the link wire grammar). The substrate a translucent colour is
+// flattened over is `SURFACE_BLACK`, defined beside `compositeOver`.
 // --- Attribute definitions ---
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by

package/dist/template-bindings/color-funcs.d.ts

@@ -55,7 +55,13 @@
  * from that point on the math is pure. A consumer with no theme system at all still gets
  * the full color vocabulary by feeding it hex literals. [LAW:one-way-deps]
  */
-import type { FuncMap } from "@promptctl/go-template-js";
+import type { FuncMap, TemplateFunc } from "@promptctl/go-template-js";
+import { ColorDepth } from "../core/color.js";
+/**
+ * The `readableOn` binding, measuring at the depth `drawnAt` names when it is
+ * evaluated — a consumer that renders at a per-call depth registers its own.
+ */
+export declare const readableOnFunc: (drawnAt: () => ColorDepth) => TemplateFunc;
 /**
  * The palette-free color vocabulary: every function takes colors and returns a
  * color, so they compose by nesting.
@@ -73,5 +79,9 @@ import type { FuncMap } from "@promptctl/go-template-js";
  *
  * Pair with `paletteFuncs()` to name colors from a theme, and with
  * `richTextStyleFuncs()`'s `fg`/`bg` to paint them onto text.
+ *
+ * @param drawnAt the depth the terminal will draw at, read on every
+ *   `readableOn` evaluation so a host that learns its depth per render passes
+ *   one getter; defaults to truecolor.
  */
-export declare function colorFuncs(): FuncMap;
+export declare function colorFuncs(drawnAt?: () => ColorDepth): FuncMap;

package/dist/template-bindings/color-funcs.js

@@ -55,7 +55,7 @@
  * from that point on the math is pure. A consumer with no theme system at all still gets
  * the full color vocabulary by feeding it hex literals. [LAW:one-way-deps]
  */
-import { blendRgb } from "../core/color.js";
+import { blendRgb, ColorDepth } from "../core/color.js";
 import { Oklch, IDENTITY } from "../core/oklch.js";
 import { HEX_COLOR_RE, parseHexColor } from "../themes/colorRef.js";
 import { darken, contrastFor, ensureContrast } from "../themes/colorMath.js";
@@ -147,7 +147,11 @@ const RATIO_RANGE = {
     note: "4.5 = AA body text, 3 = AA large text",
 };
 const contrastOnFunc = colorFunc(["string"], ((bgHex) => contrastFor(asColor(bgHex, "contrastOn")).hex));
-const readableOnFunc = colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE)).hex));
+/**
+ * The `readableOn` binding, measuring at the depth `drawnAt` names when it is
+ * evaluated — a consumer that renders at a per-call depth registers its own.
+ */
+export const readableOnFunc = (drawnAt) => colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE), drawnAt()).hex));
 // --- OKLCH axes ---
 //
 // [LAW:one-source-of-truth] One function per `ThemeKey` axis, and the table is
@@ -198,14 +202,18 @@ function oklchAxisFuncs() {
  *
  * Pair with `paletteFuncs()` to name colors from a theme, and with
  * `richTextStyleFuncs()`'s `fg`/`bg` to paint them onto text.
+ *
+ * @param drawnAt the depth the terminal will draw at, read on every
+ *   `readableOn` evaluation so a host that learns its depth per render passes
+ *   one getter; defaults to truecolor.
  */
-export function colorFuncs() {
+export function colorFuncs(drawnAt = () => ColorDepth.TRUECOLOR) {
     return {
         darken: darkenFunc,
         lighten: lightenFunc,
         mix: mixFunc,
         contrastOn: contrastOnFunc,
-        readableOn: readableOnFunc,
+        readableOn: readableOnFunc(drawnAt),
         ...oklchAxisFuncs(),
     };
 }

package/dist/template-bindings/index.d.ts

@@ -36,13 +36,15 @@
 import { type Engine, type FuncMap } from "@promptctl/go-template-js";
 import { RichText } from "../core/text.js";
 import { Segment } from "../core/segment.js";
+import { ColorDepth } from "../core/color.js";
 export { paletteFuncs } from "./palette-funcs.js";
-export { colorFuncs } from "./color-funcs.js";
+export { colorFuncs, readableOnFunc } from "./color-funcs.js";
 /**
  * Funcs registered by the rich-js binding — the colour sinks, the palette-free
- * colour math, text attributes, and the `link` cell-splitter. Everything here
- * is configuration-free by construction; the two that need a theme (`color`,
- * `ramp`) ship separately via `paletteFuncs(getPalette)`, merged consumer-side.
+ * colour math, text attributes, and the `link` cell-splitter. Nothing here
+ * needs a theme; the two that do (`color`, `ramp`) ship separately via
+ * `paletteFuncs(getPalette)`, merged consumer-side. `drawnAt` is forwarded to
+ * `colorFuncs` — the depth `readableOn` measures at, truecolor when omitted.
  *
  * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
  * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output
@@ -55,7 +57,7 @@ export { colorFuncs } from "./color-funcs.js";
  * into a wider engine must keep `T = RichText`; merging into an engine
  * whose `T` is something else will compile but fail at evaluation time.
  */
-export declare function richTextFuncs(): FuncMap;
+export declare function richTextFuncs(drawnAt?: () => ColorDepth): FuncMap;
 /**
  * Construct an `Engine<RichText>` with the rich-js style-function set
  * registered. Consumers that already manage their own engine should call

package/dist/template-bindings/index.js

@@ -40,12 +40,13 @@ import { Segment } from "../core/segment.js";
 import { richTextStyleFuncs } from "./style-funcs.js";
 import { colorFuncs } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
-export { colorFuncs } from "./color-funcs.js";
+export { colorFuncs, readableOnFunc } from "./color-funcs.js";
 /**
  * Funcs registered by the rich-js binding — the colour sinks, the palette-free
- * colour math, text attributes, and the `link` cell-splitter. Everything here
- * is configuration-free by construction; the two that need a theme (`color`,
- * `ramp`) ship separately via `paletteFuncs(getPalette)`, merged consumer-side.
+ * colour math, text attributes, and the `link` cell-splitter. Nothing here
+ * needs a theme; the two that do (`color`, `ramp`) ship separately via
+ * `paletteFuncs(getPalette)`, merged consumer-side. `drawnAt` is forwarded to
+ * `colorFuncs` — the depth `readableOn` measures at, truecolor when omitted.
  *
  * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
  * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output
@@ -58,8 +59,10 @@ export { colorFuncs } from "./color-funcs.js";
  * into a wider engine must keep `T = RichText`; merging into an engine
  * whose `T` is something else will compile but fail at evaluation time.
  */
-export function richTextFuncs() {
-    return { ...richTextStyleFuncs(), ...colorFuncs() };
+// [LAW:one-source-of-truth] The truecolor default lives on `colorFuncs` alone;
+// an omitted `drawnAt` is forwarded as omitted.
+export function richTextFuncs(drawnAt) {
+    return { ...richTextStyleFuncs(), ...colorFuncs(drawnAt) };
 }
 /**
  * Construct an `Engine<RichText>` with the rich-js style-function set

package/dist/themes/colorMath.d.ts

@@ -1,4 +1,4 @@
-import { ColorRgba } from "../core/color.js";
+import { ColorDepth, ColorRgba, contrastRatio, relativeLuminance } from "../core/color.js";
 /**
  * Darken a color by N levels, where each level reduces HSL lightness by 10%.
  * Negative levels lighten. Level 0 returns an equivalent triplet (after the
@@ -17,26 +17,11 @@ export declare function alphaBlend(fg: ColorRgba, bg: ColorRgba, alpha: number):
 /**
  * Pick a contrasting foreground (black or white) for a background, using the
  * WCAG relative-luminance threshold of 0.179 (the perceptually correct cutoff
- * where black and white are equally readable).
+ * where black and white are equally readable). A translucent `bg` is judged
+ * as drawn: composited over `substrate` (see `drawnBackground`).
  */
-export declare function contrastFor(bg: ColorRgba): ColorRgba;
-/**
- * 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 declare function relativeLuminance(c: ColorRgba): number;
-/**
- * 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 declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
+export declare function contrastFor(bg: ColorRgba, substrate?: ColorRgba): ColorRgba;
+export { relativeLuminance, contrastRatio };
 /**
  * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
  * color *recognizably itself*. If the themed `fg` already passes it is returned
@@ -48,10 +33,18 @@ export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
  * background where even pure black-or-white tops out below the target) does it
  * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
  *
- * A translucent `fg` is flattened over `bg` first (the displayed color is
- * `fg` composited over `bg`), so the ratio is measured on what the eye
- * actually sees and the returned color is opaque. `bg` is treated as the
- * opaque substrate.
+ * A translucent `bg` is measured as it is drawn — composited over
+ * `substrate`, the SGR writer's black by default — and a translucent `fg` is
+ * then flattened over that drawn background, the order the writer composites
+ * in, so the ratio is measured on what the eye actually sees and the returned
+ * color is opaque.
+ *
+ * `drawnAt` is the depth the terminal will draw the pair at. At 256 colours
+ * the terminal rounds text and background independently, and two roundings
+ * can meet in the middle, so the ratio is measured on the drawn pair: a
+ * colour that loses the floor there is replaced by the nearest cube/grey entry
+ * that clears it (whose own rounding is itself). Every other depth draws a
+ * colour the chosen one IS (truecolor) or one only the terminal knows (ANSI).
  *
  * [LAW:single-enforcer] The one place "is this text readable, and if not fix
  * it" is decided. Callers route every fg/bg pair through here and the
@@ -59,4 +52,5 @@ export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
  * function always runs; the measured ratio (data) decides how far the
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
-export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number): ColorRgba;
+export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number, // WCAG AA for normal text
+drawnAt?: ColorDepth, substrate?: ColorRgba): ColorRgba;

package/dist/themes/colorMath.js

@@ -1,4 +1,4 @@
-import { ColorRgba, blendRgb } from "../core/color.js";
+import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, blendRgb, contrastRatio, relativeLuminance, SURFACE_BLACK, } from "../core/color.js";
 import { Oklch } from "../core/oklch.js";
 const LEVEL_STEP = 0.1;
 function rgbToHsl(c) {
@@ -82,43 +82,20 @@ export function alphaBlend(fg, bg, alpha) {
 /**
  * Pick a contrasting foreground (black or white) for a background, using the
  * WCAG relative-luminance threshold of 0.179 (the perceptually correct cutoff
- * where black and white are equally readable).
+ * where black and white are equally readable). A translucent `bg` is judged
+ * as drawn: composited over `substrate` (see `drawnBackground`).
  */
-export function contrastFor(bg) {
-    const lum = relativeLuminance(bg);
+export function contrastFor(bg, substrate = SURFACE_BLACK) {
+    const lum = relativeLuminance(drawnBackground(bg, substrate));
     return lum > 0.179
         ? new ColorRgba(0, 0, 0)
         : new ColorRgba(255, 255, 255);
 }
-/**
- * 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) {
-    const la = relativeLuminance(a);
-    const lb = relativeLuminance(b);
-    const hi = la > lb ? la : lb;
-    const lo = la > lb ? lb : la;
-    return (hi + 0.05) / (lo + 0.05);
-}
+// [LAW:one-way-deps] The WCAG measures live in core/color.ts, beside the
+// ColorTable whose `matchReadable` needs them to pick a drawn text colour, and
+// below the theme math here. Re-exported so this module stays the colour-math
+// surface.
+export { relativeLuminance, contrastRatio };
 // Iterations for the lightness bisection below. 20 resolves L to ~1e-6 — far
 // finer than 8-bit quantization or the eye.
 const CONTRAST_ITERS = 20;
@@ -133,10 +110,18 @@ const CONTRAST_ITERS = 20;
  * background where even pure black-or-white tops out below the target) does it
  * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
  *
- * A translucent `fg` is flattened over `bg` first (the displayed color is
- * `fg` composited over `bg`), so the ratio is measured on what the eye
- * actually sees and the returned color is opaque. `bg` is treated as the
- * opaque substrate.
+ * A translucent `bg` is measured as it is drawn — composited over
+ * `substrate`, the SGR writer's black by default — and a translucent `fg` is
+ * then flattened over that drawn background, the order the writer composites
+ * in, so the ratio is measured on what the eye actually sees and the returned
+ * color is opaque.
+ *
+ * `drawnAt` is the depth the terminal will draw the pair at. At 256 colours
+ * the terminal rounds text and background independently, and two roundings
+ * can meet in the middle, so the ratio is measured on the drawn pair: a
+ * colour that loses the floor there is replaced by the nearest cube/grey entry
+ * that clears it (whose own rounding is itself). Every other depth draws a
+ * colour the chosen one IS (truecolor) or one only the terminal knows (ANSI).
  *
  * [LAW:single-enforcer] The one place "is this text readable, and if not fix
  * it" is decided. Callers route every fg/bg pair through here and the
@@ -144,7 +129,52 @@ const CONTRAST_ITERS = 20;
  * function always runs; the measured ratio (data) decides how far the
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
-export function ensureContrast(fg, bg, minRatio = 4.5) {
+export function ensureContrast(fg, bg, minRatio = 4.5, // WCAG AA for normal text
+drawnAt = ColorDepth.TRUECOLOR, substrate = SURFACE_BLACK) {
+    const ground = drawnBackground(bg, substrate);
+    const chosen = ensureTruecolorContrast(fg, ground, minRatio);
+    // [LAW:dataflow-not-control-flow] The depth names the table the terminal
+    // draws from; only one whose entries have a known RGB can be measured.
+    const table = MEASURABLE_DOWNGRADE[drawnAt];
+    if (table === undefined)
+        return chosen;
+    const drawnBg = table.get(table.match(ground));
+    const drawn = table.get(table.match(chosen));
+    if (contrastRatio(drawn, drawnBg) >= minRatio)
+        return chosen;
+    return table.get(table.matchReadable(chosen, drawnBg, minRatio));
+}
+/**
+ * A background as it is drawn: composited over the surface beneath it. That
+ * surface is a fact about where the pair is drawn, so it arrives as a value:
+ * the SGR writer (`Style.toSgrCodes`) composites over `SURFACE_BLACK`, the
+ * default here; a caller choosing text for a different surface — an export's
+ * canvas, `exportCanvas(theme).background` — names that one.
+ * [LAW:no-silent-failure] A surface has nothing under it, so a translucent one
+ * has no drawn colour to offer; `compositeOver` would read its raw RGB as if
+ * it were opaque, so it is refused here rather than measured wrong.
+ * [LAW:one-source-of-truth] Text is chosen against the colour the surface will
+ * show — measuring the raw RGBA reads a colour that is drawn nowhere, and text
+ * that "clears" it can land below the floor. Opaque colours composite to
+ * themselves.
+ */
+function drawnBackground(bg, substrate) {
+    if (substrate.alpha !== 1) {
+        throw new RangeError(`a contrast substrate is the opaque surface under a translucent background; got ${substrate.hex}`);
+    }
+    return bg.compositeOver(substrate);
+}
+/**
+ * The downgrade tables whose entries the terminal draws at a known RGB, by the
+ * depth that draws from them. 256 colours is the one: its cube and grey ramp
+ * are fixed by xterm. ANSI 0–15 and the default colour are the terminal
+ * theme's own, so text drawn there has no ratio to keep; truecolor draws the
+ * chosen colour itself.
+ */
+const MEASURABLE_DOWNGRADE = {
+    [ColorDepth.EIGHT_BIT]: EIGHT_BIT_DOWNGRADE_TABLE,
+};
+function ensureTruecolorContrast(fg, bg, minRatio) {
     // Flatten translucency so the guarantee holds for the displayed color, not
     // the raw bytes (e.g. a "#FFFFFF60" text-disabled over a light surface).
     const opaqueFg = fg.compositeOver(bg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "type": "module",
   "sideEffects": false,