@promptctl/rich-js 0.13.0 → 0.15.0

package/dist/core/color.d.ts

@@ -31,6 +31,14 @@ 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
@@ -76,6 +84,15 @@ export declare class ColorTable {
      * the ratio decides which one wins.
      */
     matchReadable(value: ColorRgba, on: ColorRgba, minRatio: number): number;
+    /**
+     * 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: ColorRgba, accept: (entry: ColorRgba, index: number) => boolean): number | undefined;
 }
 export declare enum ColorDepth {
     DEFAULT = 0,
@@ -123,6 +140,15 @@ export declare class ColorSpec {
     private downgradeCache;
     constructor(name: string, type: ColorDepth, number?: number, value?: ColorRgba);
     get isDefault(): boolean;
+    /**
+     * 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(): ColorRgba | undefined;
     get isSystemDefined(): boolean;
     /**
      * Generates SGR parameter strings for this color.

package/dist/core/color.js

@@ -65,6 +65,14 @@ 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
@@ -114,6 +122,14 @@ function remember(cache, key, index) {
     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;
@@ -150,10 +166,7 @@ export class ColorTable {
         let bestDist = Infinity;
         for (let i = 0; i < this.colors.length; i++) {
             const c = this.colors[i];
-            const dr = c.red - value.red;
-            const dg = c.green - value.green;
-            const db = c.blue - value.blue;
-            const dist = dr * dr + dg * dg + db * db;
+            const dist = rgbDistance(c, value);
             if (dist < bestDist) {
                 bestDist = dist;
                 bestIndex = i;
@@ -184,12 +197,9 @@ export class ColorTable {
             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;
+            const score = passes ? -rgbDistance(c, value) : ratio;
             if ((passes && !bestPasses) ||
                 (passes === bestPasses && score > bestScore)) {
                 best = i;
@@ -199,6 +209,20 @@ export class ColorTable {
         }
         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;
@@ -337,6 +361,28 @@ export class ColorSpec {
     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);
     }

package/dist/core/console.js

@@ -243,6 +243,7 @@ export class Console {
             asciiOnly: false,
             theme: this._theme,
             onStyleError: this._onStyleError,
+            colorSystem: this._colorSystem,
         };
     }
     // --- Print ---

package/dist/core/protocol.d.ts

@@ -4,6 +4,7 @@
  */
 import type { Segment } from "./segment.js";
 import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
+import type { ColorDepth } from "./color.js";
 export interface RenderOptions {
     /**
      * The cells this renderable may occupy. A count of cells, so a non-negative
@@ -25,6 +26,14 @@ export interface RenderOptions {
     noWrap?: boolean;
     highlight?: unknown;
     markup?: unknown;
+    /**
+     * The depth the output will be encoded at, `null` when it carries no colour.
+     * A renderable choosing between two ways of drawing something — the strip's
+     * arrow or its divider — decides on the colours the terminal will draw at
+     * this depth, which at 256 colours or fewer are not the colours it was
+     * handed. Absent means truecolor.
+     */
+    colorSystem?: ColorDepth | null;
     /**
      * The names a style string may use. A `Console` passes its own; absent, the
      * built-in defaults apply. Read it through `getStyle` rather than directly.

package/dist/core/render.js

@@ -132,6 +132,9 @@ export function renderToString(renderable, options) {
         isTerminal: false,
         encoding: "utf-8",
         asciiOnly: false,
+        // [LAW:one-source-of-truth] The depth the segments below are encoded at,
+        // so a renderable measures what this very call will draw.
+        colorSystem,
     };
     return segmentsToString(renderable.render(renderOptions), colorSystem);
 }

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 { ColorDepth, ColorSpec, blendRgb } from "./color.js";
 import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {
@@ -110,20 +110,25 @@ function paintableBg(bg) {
  * one cell wide.
  */
 export const SEAM_MIN_DELTA_E = 0.04;
-// Two backgrounds the eye cannot tell apart. What is measured is what is
-// drawn: each colour flattened onto the substrate Style.toSgrCodes flattens it
-// onto, so two alphas over one RGB are the two greys they render as. A palette
-// colour has no value here, so two of them are the same only when they are the
-// same palette slot — `type` + `number`, never the name, which spells one slot
-// many ways ("red", "color(1)").
-function indistinct(a, b) {
-    if (b === undefined)
+// An arrow the eye cannot tell from the ground it is drawn on. What is
+// measured is what is drawn — `Style.drawnColors`, the colours the writer
+// encodes: the arrow's colour flattened onto its ground and the ground onto
+// the terminal's black, both downgraded to the depth the render encodes at,
+// so two grounds 256 colours round to one cube entry are the one entry they
+// render as. A colour whose RGB is the terminal theme's own (ANSI 0–15) has no
+// value here, so two of them are the same only when they are the same palette
+// slot — its `number`, never the name or the depth that spells it ("red",
+// "color(1)", an EIGHT_BIT spec on 0–15 are one slot).
+function vanishes(arrow, colorSystem) {
+    // No colour emitted draws nothing to tell apart; measure what was handed.
+    const { color, bgcolor } = arrow.drawnColors(colorSystem ?? ColorDepth.TRUECOLOR);
+    if (color === undefined || bgcolor === undefined)
         return false;
-    const av = a.flattenAlpha(SURFACE_BLACK).value;
-    const bv = b.flattenAlpha(SURFACE_BLACK).value;
+    const av = color.fixedValue;
+    const bv = bgcolor.fixedValue;
     return av !== undefined && bv !== undefined
         ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
-        : a.type === b.type && a.number === b.number;
+        : color.number === bgcolor.number;
 }
 /** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
 export const POWERLINE_JOINER_GLYPHS = Object.freeze({ glyph: "\ue0b0", divider: "\ue0b1" });
@@ -150,8 +155,10 @@ export class PowerlineJoiner {
         // structural boundary, never suppressed. The arrow would be drawn in its own
         // background colour there and vanish, so the seam is the DIVIDER instead, in
         // the left item's text colour — the vim-airline convention for neighbours
-        // that share a background. "Equal" is perceptual (SEAM_MIN_DELTA_E): an
-        // arrow a hair off its background is as invisible as one exactly on it.
+        // that share a background. "Equal" is perceptual (SEAM_MIN_DELTA_E) and
+        // measured on the colours the terminal draws at `options.colorSystem`: an
+        // arrow a hair off its background is as invisible as one exactly on it,
+        // and two backgrounds 256 colours round to one entry are one background.
         // Background colour is paint, not structure; its ABSENCE (nothing to paint)
         // is the only thing that elides the separator, and that is paint logic.
         // "Absent" = no bg OR the terminal default (transparent) — paintableBg folds
@@ -164,9 +171,16 @@ export class PowerlineJoiner {
             if (leftBg === undefined)
                 return;
             const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
-            yield indistinct(leftBg, rightBg)
-                ? new Segment(divider, new Style({ color: leftEdge?.color, bgcolor: rightBg }))
-                : new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
+            // The arrow is the left cell continuing: its ground as the writer draws
+            // it, so a translucent ground is not composited a second time over the
+            // right one.
+            const leftDrawn = new Style({ bgcolor: leftBg }).drawnColors().bgcolor;
+            const arrow = new Style({ color: leftDrawn, bgcolor: rightBg });
+            // The divider is the left item's text on the left item's own ground,
+            // so it reads exactly as well as that item's text does, at any depth.
+            yield vanishes(arrow, options.colorSystem)
+                ? new Segment(divider, new Style({ color: leftEdge?.color, bgcolor: leftBg }))
+                : new Segment(glyph, arrow);
         });
     }
 }

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
@@ -70,6 +69,17 @@ export declare class Style {
      */
     add(other: Style | undefined): Style;
     equals(other: Style): boolean;
+    /**
+     * The colours this style puts on screen at `colorSystem`: each flattened
+     * onto what lies beneath it — the background onto the terminal's black, the
+     * foreground onto that background — then downgraded to the depth. The one
+     * account of what a style draws: `toSgrCodes` encodes exactly these, and a
+     * renderable choosing between two ways of drawing measures them.
+     */
+    drawnColors(colorSystem?: ColorDepth): {
+        readonly color: ColorSpec | undefined;
+        readonly bgcolor: ColorSpec | undefined;
+    };
     /**
      * Returns the SGR parameter list this style emits (e.g. `"1;31;48;2;0;0;255"`),
      * or `""` when the style has no SGR contribution. Excludes OSC 8 link bytes —

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
@@ -267,6 +264,28 @@ export class Style {
             this.overline === other.overline &&
             this.link === other.link);
     }
+    /**
+     * The colours this style puts on screen at `colorSystem`: each flattened
+     * onto what lies beneath it — the background onto the terminal's black, the
+     * foreground onto that background — then downgraded to the depth. The one
+     * account of what a style draws: `toSgrCodes` encodes exactly these, and a
+     * renderable choosing between two ways of drawing measures them.
+     */
+    drawnColors(colorSystem) {
+        // [LAW:dataflow-not-control-flow] Always resolve a substrate and flatten
+        // alpha before downgrade. Opaque colors short-circuit inside compositeOver,
+        // so the same code path runs every render — the alpha value is the data,
+        // not a branch.
+        const surface = SURFACE_BLACK;
+        const bgFlat = this.bgcolor?.flattenAlpha(surface);
+        const fgSubstrate = bgFlat?.getTruecolor(undefined, false) ?? surface;
+        const fgFlat = this.color?.flattenAlpha(fgSubstrate);
+        const at = (c) => colorSystem !== undefined ? c.downgrade(colorSystem) : c;
+        return {
+            color: fgFlat === undefined ? undefined : at(fgFlat),
+            bgcolor: bgFlat === undefined ? undefined : at(bgFlat),
+        };
+    }
     /**
      * Returns the SGR parameter list this style emits (e.g. `"1;31;48;2;0;0;255"`),
      * or `""` when the style has no SGR contribution. Excludes OSC 8 link bytes —
@@ -281,22 +300,11 @@ export class Style {
         if (this.isNull)
             return "";
         const attrs = [];
-        // [LAW:dataflow-not-control-flow] Always resolve a substrate and flatten
-        // alpha before downgrade. Opaque colors short-circuit inside compositeOver,
-        // so the same code path runs every render — the alpha value is the data,
-        // not a branch.
-        const surface = SURFACE_BLACK;
-        const bgFlat = this.bgcolor?.flattenAlpha(surface);
-        const fgSubstrate = bgFlat?.getTruecolor(undefined, false) ?? surface;
-        const fgFlat = this.color?.flattenAlpha(fgSubstrate);
-        if (fgFlat) {
-            const c = colorSystem !== undefined ? fgFlat.downgrade(colorSystem) : fgFlat;
-            attrs.push(...c.getAnsiCodes(true));
-        }
-        if (bgFlat) {
-            const c = colorSystem !== undefined ? bgFlat.downgrade(colorSystem) : bgFlat;
-            attrs.push(...c.getAnsiCodes(false));
-        }
+        const drawn = this.drawnColors(colorSystem);
+        if (drawn.color)
+            attrs.push(...drawn.color.getAnsiCodes(true));
+        if (drawn.bgcolor)
+            attrs.push(...drawn.bgcolor.getAnsiCodes(false));
         // An attribute set false writes nothing, as in Python Rich 9d8f9a3's
         // `_make_ansi_codes`. It overrides an inherited attribute when styles
         // combine, and every styled run is written after a reset, so no off

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACU
 export { getThemePalette, listThemePalettes } from "./themes/registry.js";
 export type { ThemeName } from "./themes/registry.js";
 export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
-export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, } from "./themes/colorMath.js";
+export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
 export { ColorRamp, RAMP_EASING_NAMES, parseRampEasing } from "./themes/ramp.js";
 export type { ColorStop, RampEasing } from "./themes/ramp.js";
 export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";

package/dist/index.js

@@ -21,7 +21,7 @@ export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "
 // reaches for to tint a resolved color against itself (e.g. a focused-while-open
 // menu cell lightening its inherited background) without re-deriving from a
 // palette name. Negative levels invert (lighten(c,-n) === darken(c,n)).
-export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, } from "./themes/colorMath.js";
+export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
 // A number → a color through ordered stops, interpolated in OKLCH — the one
 // color operation whose input is a measurement rather than a color, so a
 // gradient (or, with the `step` easing, a threshold cascade) stays inside the

package/dist/themes/colorMath.d.ts

@@ -17,9 +17,10 @@ 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;
+export declare function contrastFor(bg: ColorRgba, substrate?: ColorRgba): ColorRgba;
 export { relativeLuminance, contrastRatio };
 /**
  * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
@@ -32,17 +33,21 @@ export { relativeLuminance, contrastRatio };
  * 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).
+ * that clears it (whose own rounding is itself). At ANSI the terminal draws
+ * its own theme's colours, so the ratio is measured on the table's nominal
+ * ones (`DRAWN_FROM`): they say which side of the ground text belongs on, and
+ * text on its background's index measures 1:1 and is always replaced.
+ * Truecolor draws the colour chosen.
  *
  * [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
@@ -51,4 +56,27 @@ export { relativeLuminance, contrastRatio };
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
 export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number, // WCAG AA for normal text
-drawnAt?: ColorDepth): ColorRgba;
+drawnAt?: ColorDepth, substrate?: ColorRgba): ColorRgba;
+/**
+ * `chosen` (composited opaque over `substrate`), or — when the depth the
+ * terminal draws at rounds it to a colour `accept` refuses — the nearest colour that depth draws as itself which
+ * `accept` takes. `accept` sees the candidate as drawn, and `drawn`, the same
+ * rounding for any other colour it measures against, so the caller states a
+ * floor once and it holds on the colours the terminal shows — at ANSI, on
+ * the table's nominal colours, as `ensureContrast` measures there. Truecolor
+ * draws from no table, so a colour refused there has no replacement;
+ * `undefined` means nothing the depth draws is accepted.
+ *
+ * `ensureContrast` is this with a contrast ratio as the floor; this is for a
+ * floor that is not text on its background (an open state standing off every
+ * closed cell, two planes standing off each other).
+ */
+export declare function ensureDrawn(chosen: ColorRgba, drawnAt: ColorDepth, accept: (candidate: ColorRgba, drawn: (c: ColorRgba) => ColorRgba) => boolean, substrate?: ColorRgba): ColorRgba | undefined;
+/**
+ * The colour a ground is shown as at `drawnAt`: composited over `substrate`
+ * (the SGR writer's black by default), then rounded to the table that depth
+ * draws from — at ANSI, that table's nominal colour stands in for the
+ * theme's. The one account `ensureDrawn` and `ensureContrast` measure by, for
+ * a caller that measures a floor of its own.
+ */
+export declare function drawnColour(colour: ColorRgba, drawnAt: ColorDepth, substrate?: ColorRgba): ColorRgba;

package/dist/themes/colorMath.js

@@ -1,4 +1,4 @@
-import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, blendRgb, contrastRatio, relativeLuminance, } from "../core/color.js";
+import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, STANDARD_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,10 +82,11 @@ 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);
@@ -109,17 +110,21 @@ 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).
+ * that clears it (whose own rounding is itself). At ANSI the terminal draws
+ * its own theme's colours, so the ratio is measured on the table's nominal
+ * ones (`DRAWN_FROM`): they say which side of the ground text belongs on, and
+ * text on its background's index measures 1:1 and is always replaced.
+ * Truecolor draws the colour chosen.
  *
  * [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
@@ -128,28 +133,91 @@ const CONTRAST_ITERS = 20;
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
 export function ensureContrast(fg, bg, minRatio = 4.5, // WCAG AA for normal text
-drawnAt = ColorDepth.TRUECOLOR) {
-    const chosen = ensureTruecolorContrast(fg, bg, minRatio);
+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];
+    // draws from; every table is measured the same way.
+    const table = DRAWN_FROM[drawnAt];
     if (table === undefined)
         return chosen;
-    const drawnBg = table.get(table.match(bg));
-    const drawn = table.get(table.match(chosen));
-    if (contrastRatio(drawn, drawnBg) >= minRatio)
+    const drawnBg = drawnColour(ground, drawnAt, substrate);
+    if (contrastRatio(drawnColour(chosen, drawnAt, substrate), drawnBg) >= minRatio)
         return chosen;
     return table.get(table.matchReadable(chosen, drawnBg, minRatio));
 }
 /**
- * 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.
+ * `chosen` (composited opaque over `substrate`), or — when the depth the
+ * terminal draws at rounds it to a colour `accept` refuses — the nearest colour that depth draws as itself which
+ * `accept` takes. `accept` sees the candidate as drawn, and `drawn`, the same
+ * rounding for any other colour it measures against, so the caller states a
+ * floor once and it holds on the colours the terminal shows — at ANSI, on
+ * the table's nominal colours, as `ensureContrast` measures there. Truecolor
+ * draws from no table, so a colour refused there has no replacement;
+ * `undefined` means nothing the depth draws is accepted.
+ *
+ * `ensureContrast` is this with a contrast ratio as the floor; this is for a
+ * floor that is not text on its background (an open state standing off every
+ * closed cell, two planes standing off each other).
+ */
+export function ensureDrawn(chosen, drawnAt, accept, substrate = SURFACE_BLACK) {
+    // The floor was measured on `chosen` composited over `substrate`, so that
+    // opaque colour is what is returned — never a translucent one a different
+    // ground would composite into a colour `accept` never saw.
+    const opaque = drawnBackground(chosen, substrate);
+    const drawn = (c) => drawnColour(c, drawnAt, substrate);
+    if (accept(drawn(opaque), drawn))
+        return opaque;
+    // [LAW:dataflow-not-control-flow] Truecolor draws from no table, so it has
+    // no candidates: a refusal there is `undefined` like any exhausted search.
+    const table = DRAWN_FROM[drawnAt];
+    const index = table?.matchWhere(opaque, (entry) => accept(entry, drawn));
+    return index === undefined ? undefined : table.get(index);
+}
+/**
+ * The colour a ground is shown as at `drawnAt`: composited over `substrate`
+ * (the SGR writer's black by default), then rounded to the table that depth
+ * draws from — at ANSI, that table's nominal colour stands in for the
+ * theme's. The one account `ensureDrawn` and `ensureContrast` measure by, for
+ * a caller that measures a floor of its own.
+ */
+export function drawnColour(colour, drawnAt, substrate = SURFACE_BLACK) {
+    const opaque = drawnBackground(colour, substrate);
+    const table = DRAWN_FROM[drawnAt];
+    return table === undefined ? opaque : table.get(table.match(opaque));
+}
+/**
+ * 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 table the terminal draws from, by depth, measured at each
+ * entry's colour. The 256-colour cube and grey ramp are fixed by xterm, so
+ * those measurements are exact. ANSI 0–15 are the terminal theme's own, so
+ * the table's nominal colours stand in for them: they are wrong in hue from
+ * theme to theme, but not about which side of a ground an entry sits on —
+ * and two colours on one index are one colour in every theme, which the
+ * nominal ratio of 1 refuses. Truecolor draws the chosen colour itself.
  */
-const MEASURABLE_DOWNGRADE = {
+const DRAWN_FROM = {
     [ColorDepth.EIGHT_BIT]: EIGHT_BIT_DOWNGRADE_TABLE,
+    [ColorDepth.STANDARD]: STANDARD_TABLE,
 };
 function ensureTruecolorContrast(fg, bg, minRatio) {
     // Flatten translucency so the guarantee holds for the displayed color, not

package/dist/widgets/screen.js

@@ -245,6 +245,10 @@ let DefaultScreen = (() => {
                 maxWidth: width,
                 isTerminal: true,
                 encoding: "utf-8",
+                // [LAW:one-source-of-truth] The depth the frame is encoded at (below,
+                // `segmentsToString`), so a renderable that decides on drawn colours
+                // decides on the ones this screen draws.
+                colorSystem: this.colorSystem,
             };
             const lines = [];
             const boundsList = [];

package/package.json

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