@promptctl/rich-js 0.14.0 → 0.16.0

package/dist/core/color.d.ts

@@ -84,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,
@@ -131,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

@@ -122,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;
@@ -158,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;
@@ -192,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;
@@ -207,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;
@@ -345,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.d.ts

@@ -67,7 +67,7 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
 export interface PowerlineJoinerOptions {
-    /** Glyph used for every join. */
+    /** Glyph for every join between two coloured items. */
     glyph: string;
     /**
      * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
@@ -75,12 +75,30 @@ export interface PowerlineJoinerOptions {
      * shared background.
      */
     divider: string;
+    /**
+     * Glyph for every join a coloured item is entered from nothing — the strip's
+     * start, or a colourless left neighbour — painted in the right item's
+     * background. `""` begins a coloured run flat.
+     */
+    lead: string;
+    /**
+     * Glyph for every join a coloured item leaves into nothing — the strip's end,
+     * or a colourless right neighbour — painted in the left item's background.
+     * `""` ends a coloured run flat.
+     */
+    tail: string;
 }
-/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+/**
+ * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
+ * led by U+E0B2 (left-arrow) and tailed by the arrow itself — so a strip's two
+ * ends are one shape.
+ */
 export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
 export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
     private readonly _glyph;
     private readonly _divider;
+    private readonly _lead;
+    private readonly _tail;
     constructor(options?: PowerlineJoinerOptions);
     join(left: T | null, right: T | null): Renderable;
 }

package/dist/core/strip.js

@@ -27,7 +27,7 @@
  */
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { ColorSpec, SURFACE_BLACK, blendRgb } from "./color.js";
+import { ColorDepth, ColorSpec, blendRgb } from "./color.js";
 import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {
@@ -101,6 +101,18 @@ function bgAsFg(edge) {
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
+// A cap or arrow is its cell continuing: that cell's ground as the writer draws
+// it, so a translucent ground is not composited a second time over whatever it
+// enters.
+function drawnGround(bg) {
+    return new Style({ bgcolor: bg }).drawnColors().bgcolor;
+}
+// A cap is its glyph in its cell's ground, and "" is a flat end: no glyph, so
+// no segment — the same output as a join with nothing to paint.
+function* cap(glyph, bg) {
+    if (glyph !== "")
+        yield new Segment(glyph, new Style({ color: drawnGround(bg) }));
+}
 // --- PowerlineJoiner ---
 /**
  * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
@@ -110,63 +122,97 @@ 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" });
+/**
+ * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
+ * led by U+E0B2 (left-arrow) and tailed by the arrow itself — so a strip's two
+ * ends are one shape.
+ */
+export const POWERLINE_JOINER_GLYPHS = Object.freeze({
+    glyph: "\ue0b0",
+    divider: "\ue0b1",
+    lead: "\ue0b2",
+    tail: "\ue0b0",
+});
 export class PowerlineJoiner {
     _glyph;
     _divider;
+    _lead;
+    _tail;
     constructor(options = POWERLINE_JOINER_GLYPHS) {
         this._glyph = options.glyph;
         this._divider = options.divider;
+        this._lead = options.lead;
+        this._tail = options.tail;
     }
     join(left, right) {
-        // [LAW:dataflow-not-control-flow] One expression for all three positions
-        // (start cap, mid-join, end cap). The powerline separator is painted in the
-        // LEFT edge's bg — the colour bleeding rightward — over the RIGHT edge's bg.
-        // The endpoints are not control-flow special cases; they are the DATA cases
+        // [LAW:dataflow-not-control-flow] One table for all three positions (start
+        // cap, mid-join, end cap), read off which side has a colour to paint. The
+        // endpoints are not control-flow special cases; they are the DATA cases
         // where a neighbour (hence its bg) is absent:
-        //   • no left bg — the start cap, OR a left item with no background — has no
-        //     colour to bleed, so there is no separator to paint and the join
-        //     yields nothing. (This matches vim-airline / tmux-powerline: a
-        //     colourless arrow is not drawn.)
-        //   • no right bg — the end cap — bleeds the left colour out over the
-        //     terminal background (fg = left bg, no bg).
+        //   • both bgs — the arrow in the LEFT bg (the colour bleeding rightward)
+        //     over the RIGHT bg.
+        //   • left bg only — the end cap, OR a coloured item before a colourless
+        //     one — the tail bleeds the left colour out over the terminal
+        //     background (fg = left bg, no bg).
+        //   • right bg only — the start cap, OR a colourless item before a coloured
+        //     one — the lead: the right colour reaching back over the terminal
+        //     background (fg = right bg, no bg).
+        //   • neither — nothing to paint, so the join yields nothing.
         // Equal REAL bgs still emit: a same-bg seam between two distinct items is a
         // 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
         // both to undefined so an explicit `… on default` cannot smuggle a separator.
         const glyph = this._glyph;
         const divider = this._divider;
+        const lead = this._lead;
+        const tail = this._tail;
         return deferred(function* (options) {
             const leftEdge = left?.edgeStyle("right", options);
             const leftBg = paintableBg(leftEdge?.bgcolor);
-            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 }));
+            if (leftBg === undefined) {
+                if (rightBg !== undefined)
+                    yield* cap(lead, rightBg);
+                return;
+            }
+            if (rightBg === undefined) {
+                yield* cap(tail, leftBg);
+                return;
+            }
+            const arrow = new Style({ color: drawnGround(leftBg), 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

@@ -69,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

@@ -264,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 —
@@ -278,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

@@ -43,8 +43,11 @@ export { relativeLuminance, contrastRatio };
  * 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
@@ -54,3 +57,26 @@ export { relativeLuminance, contrastRatio };
  */
 export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number, // WCAG AA for normal text
 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, SURFACE_BLACK, } 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) {
@@ -120,8 +120,11 @@ const CONTRAST_ITERS = 20;
  * 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
@@ -134,16 +137,55 @@ 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(ground));
-    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));
 }
+/**
+ * `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:
@@ -165,14 +207,17 @@ function drawnBackground(bg, substrate) {
     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.
+ * 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.14.0",
+  "version": "0.16.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "type": "module",
   "sideEffects": false,