@promptctl/rich-js 0.11.0 → 0.13.0

package/dist/core/color.d.ts

@@ -31,11 +31,34 @@ export declare class ColorRgba {
      */
     compositeOver(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 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 +66,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 +186,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,74 @@ 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);
     }
 }
+/**
+ * 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 +159,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 +465,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 +632,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/oklch.d.ts

@@ -41,6 +41,13 @@ export interface ThemeKey {
     /** Additive on lightness; applied *after* the scale. */
     readonly lightnessShift: number;
 }
+/** How far `Oklch.mixAxes` moves each axis toward its target, each in [0, 1]. */
+export interface OklchWeights {
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+    readonly alpha: number;
+}
 export declare const IDENTITY: ThemeKey;
 /**
  * Flip lightness around the midpoint (`L' = 1 - L`) with hue and chroma
@@ -70,6 +77,7 @@ export declare function isIdentityKey(k: ThemeKey): boolean;
  * sRGB-quantization step normalizes them.
  */
 export declare class Oklch {
+    #private;
     readonly l: number;
     readonly c: number;
     readonly h: number;
@@ -115,6 +123,32 @@ export declare class Oklch {
      * there too.
      */
     mix(toward: Oklch, t: number): Oklch;
+    /**
+     * `mix` with each axis moved its own share of the way: `weights.l` of the
+     * lightness gap, `weights.c` of the chroma gap, and so on, each in [0, 1].
+     * `mix(toward, t)` is `mixAxes` with every weight `t` — one interpolation,
+     * so the shorter-arc hue and the powerless-endpoint rule are the same
+     * whichever is called.
+     *
+     * It exists because perceptual axes are independent: a tint can take most of
+     * a hue's colourfulness while keeping close to the lightness it started at,
+     * which a single `t` cannot say — raising `t` for chroma drags lightness with
+     * it. Every weight is required: an axis left out would need a default, and
+     * "unchanged" (0) and "same as the others" are both plausible readings.
+     *
+     * A weak `h` beside a strong `c` shows the starting colour's hue at high
+     * chroma. The powerless rule covers only a truly achromatic start, so a
+     * near-grey whose hue is noise (a theme surface at c ≈ 0.004) keeps that
+     * noise in proportion. To land on the target's hue, pass `h: 1`.
+     */
+    mixAxes(toward: Oklch, weights: OklchWeights): Oklch;
+    /**
+     * ΔE_OK — the Euclidean distance between this colour and `other` in OKLab
+     * (CSS Color 4's `deltaEOK`), where ~0.02 is the smallest difference the eye
+     * resolves. Alpha is not a coordinate of the space and does not count.
+     * Symmetric and pure.
+     */
+    deltaE(other: Oklch): number;
     /** Linear-sRGB coordinates for an explicit (l, C, h). Pure; `toRgba` passes
      * already-normalized values so this never sees out-of-range inputs. */
     private toLinearRgb;

package/dist/core/oklch.js

@@ -20,7 +20,11 @@
  * nothing else from inside the project. Nothing in core/ depends back on
  * this file.
  */
+var _a;
 import { ColorRgba } from "./color.js";
+// The axes `mixAxes` checks, named once so a weights object's own keys — a
+// missing one, or an extra field riding along — never decide what is checked.
+const OKLCH_AXES = ["l", "c", "h", "alpha"];
 export const IDENTITY = Object.freeze({
     hueShift: 0,
     chromaScale: 1,
@@ -144,7 +148,7 @@ export class Oklch {
         const bLab = 0.0259040371 * lCube + 0.7827717662 * mCube - 0.8086757660 * sCube;
         const C = Math.sqrt(aLab * aLab + bLab * bLab);
         const H = wrapHue(Math.atan2(bLab, aLab) * (180 / Math.PI));
-        return new Oklch(L, C, hueOf(C, H), a);
+        return new _a(L, C, hueOf(C, H), a);
     }
     /**
      * Polar → OKLab → linear → sRGB (with chroma-bisection gamut clamping).
@@ -181,7 +185,7 @@ export class Oklch {
         const newL = clamp01(this.l * k.lightnessScale + k.lightnessShift);
         const newC = Math.max(0, this.c * k.chromaScale);
         const newH = wrapHue(this.h + k.hueShift);
-        return new Oklch(newL, newC, hueOf(newC, newH), this.alpha);
+        return new _a(newL, newC, hueOf(newC, newH), this.alpha);
     }
     /**
      * The color `t` of the way from this one toward `toward`, in OKLCH.
@@ -208,6 +212,38 @@ export class Oklch {
         if (!(t >= 0 && t <= 1)) {
             throw new RangeError(`Oklch.mix: t must be in [0, 1]; got ${t}`);
         }
+        return this.#interpolate(toward, t, t, t, t);
+    }
+    /**
+     * `mix` with each axis moved its own share of the way: `weights.l` of the
+     * lightness gap, `weights.c` of the chroma gap, and so on, each in [0, 1].
+     * `mix(toward, t)` is `mixAxes` with every weight `t` — one interpolation,
+     * so the shorter-arc hue and the powerless-endpoint rule are the same
+     * whichever is called.
+     *
+     * It exists because perceptual axes are independent: a tint can take most of
+     * a hue's colourfulness while keeping close to the lightness it started at,
+     * which a single `t` cannot say — raising `t` for chroma drags lightness with
+     * it. Every weight is required: an axis left out would need a default, and
+     * "unchanged" (0) and "same as the others" are both plausible readings.
+     *
+     * A weak `h` beside a strong `c` shows the starting colour's hue at high
+     * chroma. The powerless rule covers only a truly achromatic start, so a
+     * near-grey whose hue is noise (a theme surface at c ≈ 0.004) keeps that
+     * noise in proportion. To land on the target's hue, pass `h: 1`.
+     */
+    mixAxes(toward, weights) {
+        for (const axis of OKLCH_AXES) {
+            const w = weights[axis];
+            if (!(w >= 0 && w <= 1)) {
+                throw new RangeError(`Oklch.mixAxes: ${axis} weight must be in [0, 1]; got ${w}`);
+            }
+        }
+        return this.#interpolate(toward, weights.l, weights.c, weights.h, weights.alpha);
+    }
+    // The one interpolation both entry points share; each has already checked
+    // its own weights, so this is the arithmetic alone.
+    #interpolate(toward, wl, wc, wh, walpha) {
         const thisHasHue = this.c >= ACHROMATIC_EPS;
         const towardHasHue = toward.c >= ACHROMATIC_EPS;
         const fromH = wrapHue(thisHasHue ? this.h : towardHasHue ? toward.h : 0);
@@ -219,8 +255,19 @@ export class Oklch {
         const arc = toH - fromH;
         const fromU = arc < -180 ? fromH - 360 : fromH;
         const toU = arc > 180 ? toH - 360 : toH;
-        const c = lerp(this.c, toward.c, t);
-        return new Oklch(lerp(this.l, toward.l, t), c, hueOf(c, wrapHue(lerp(fromU, toU, t))), lerp(this.alpha, toward.alpha, t));
+        const c = lerp(this.c, toward.c, wc);
+        return new _a(lerp(this.l, toward.l, wl), c, hueOf(c, wrapHue(lerp(fromU, toU, wh))), lerp(this.alpha, toward.alpha, walpha));
+    }
+    /**
+     * ΔE_OK — the Euclidean distance between this colour and `other` in OKLab
+     * (CSS Color 4's `deltaEOK`), where ~0.02 is the smallest difference the eye
+     * resolves. Alpha is not a coordinate of the space and does not count.
+     * Symmetric and pure.
+     */
+    deltaE(other) {
+        const a = (this.h * Math.PI) / 180;
+        const b = (other.h * Math.PI) / 180;
+        return Math.hypot(this.l - other.l, this.c * Math.cos(a) - other.c * Math.cos(b), this.c * Math.sin(a) - other.c * Math.sin(b));
     }
     /** Linear-sRGB coordinates for an explicit (l, C, h). Pure; `toRgba` passes
      * already-normalized values so this never sees out-of-range inputs. */
@@ -262,3 +309,4 @@ export class Oklch {
         return lo;
     }
 }
+_a = Oklch;

package/dist/core/strip.d.ts

@@ -58,12 +58,29 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
     constructor(items: readonly T[], joiner: Joiner<T>);
     render(options: RenderOptions): Iterable<Segment>;
 }
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export declare const SEAM_MIN_DELTA_E = 0.04;
 export interface PowerlineJoinerOptions {
-    /** Glyph used for every join (default: U+E0B0, the powerline right-arrow). */
-    glyph?: string;
+    /** Glyph used for every join. */
+    glyph: string;
+    /**
+     * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
+     * in the left item's text colour — the arrow itself would vanish into the
+     * shared background.
+     */
+    divider: string;
 }
+/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+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;
     constructor(options?: PowerlineJoinerOptions);
     join(left: T | null, right: T | null): Renderable;
 }

package/dist/core/strip.js

@@ -26,8 +26,9 @@
  * styling, so the cell type does too.
  */
 import { Segment } from "./segment.js";
-import { Style } from "./style.js";
+import { Style, SURFACE_BLACK } from "./style.js";
 import { ColorSpec, blendRgb } from "./color.js";
+import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {
     items;
@@ -100,10 +101,38 @@ function bgAsFg(edge) {
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
+// --- PowerlineJoiner ---
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * 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)
+        return false;
+    const av = a.flattenAlpha(SURFACE_BLACK).value;
+    const bv = b.flattenAlpha(SURFACE_BLACK).value;
+    return av !== undefined && bv !== undefined
+        ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
+        : a.type === b.type && a.number === b.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" });
 export class PowerlineJoiner {
     _glyph;
-    constructor(options) {
-        this._glyph = options?.glyph ?? "";
+    _divider;
+    constructor(options = POWERLINE_JOINER_GLYPHS) {
+        this._glyph = options.glyph;
+        this._divider = options.divider;
     }
     join(left, right) {
         // [LAW:dataflow-not-control-flow] One expression for all three positions
@@ -117,20 +146,27 @@ export class PowerlineJoiner {
         //     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).
-        // Equal REAL bgs still emit: the glyph is drawn in its own background colour
-        // and is invisible, but the cell is present — a same-bg seam between two
-        // distinct items is a structural boundary, never suppressed. Background
-        // colour is paint, not structure; its ABSENCE (nothing to paint) is the only
-        // thing that elides the separator, and that is paint logic, not structure.
+        // 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.
+        // 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;
         return deferred(function* (options) {
-            const leftBg = paintableBg(left?.edgeStyle("right", options).bgcolor);
+            const leftEdge = left?.edgeStyle("right", options);
+            const leftBg = paintableBg(leftEdge?.bgcolor);
             if (leftBg === undefined)
                 return;
             const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
-            yield new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
+            yield indistinct(leftBg, rightBg)
+                ? new Segment(divider, new Style({ color: leftEdge?.color, bgcolor: rightBg }))
+                : new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
         });
     }
 }

package/dist/core/style.d.ts

@@ -1,7 +1,8 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { ColorSpec, ColorDepth } from "./color.js";
+import { ColorRgba, ColorSpec, ColorDepth } from "./color.js";
+export declare const SURFACE_BLACK: ColorRgba;
 /**
  * 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

@@ -8,7 +8,7 @@ import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 // 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.
-const SURFACE_BLACK = new ColorRgba(0, 0, 0);
+export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
 // --- Attribute definitions ---
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by

package/dist/core/text.js

@@ -48,8 +48,9 @@ function hangingWhitespace(line) {
 // [LAW:single-enforcer] RichText is the data-model trust boundary for link
 // URLs: a `Style` is sanitized as it enters (`admitStyle`), and the `Style` a
 // stored string resolves to is sanitized as it leaves for a render
-// (`resolveStyle`). Wire-byte safety is enforced separately in render.ts and
-// style.ts through the same `stripOscTerminators`.
+// (`resolveStyle`). Wire-byte safety is enforced separately by `osc8Open`
+// (core/osc8.ts), which every link producer calls and which applies the same
+// `stripOscTerminators`.
 function sanitizeStyleLink(style) {
     const link = style.link;
     if (!link)

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
 export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
 export type { DetectColorOptions } from "./core/color.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
-export type { ThemeKey } from "./core/oklch.js";
+export type { ThemeKey, OklchWeights } from "./core/oklch.js";
 export { Palette } from "./themes/palette.js";
 export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
 export { buildPalette } from "./themes/buildPalette.js";
@@ -28,7 +28,7 @@ export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
 export type { RichTextOptions } from "./core/text.js";
-export { Strip, PowerlineJoiner, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
 export type { StyledRenderable, Joiner, PowerlineJoinerOptions, CapsuleJoinerOptions, PlainJoinerOptions, GradientJoinerOptions, } from "./core/strip.js";
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 export type { RenderToStringOptions } from "./core/render.js";

package/dist/index.js

@@ -38,7 +38,7 @@ export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
 export { Span, RichText } from "./core/text.js";
 // Strip + Joiner
-export { Strip, PowerlineJoiner, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back

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
@@ -20,23 +20,7 @@ export declare function alphaBlend(fg: ColorRgba, bg: ColorRgba, alpha: number):
  * where black and white are equally readable).
  */
 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 { 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
@@ -53,10 +37,18 @@ export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
  * actually sees and the returned color is opaque. `bg` is treated as the
  * opaque substrate.
  *
+ * `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
  * unreadable state never reaches output. [LAW:dataflow-not-control-flow] the
  * 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): 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, } from "../core/color.js";
 import { Oklch } from "../core/oklch.js";
 const LEVEL_STEP = 0.1;
 function rgbToHsl(c) {
@@ -90,35 +90,11 @@ export function contrastFor(bg) {
         ? 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;
@@ -138,13 +114,44 @@ const CONTRAST_ITERS = 20;
  * actually sees and the returned color is opaque. `bg` is treated as the
  * opaque substrate.
  *
+ * `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
  * unreadable state never reaches output. [LAW:dataflow-not-control-flow] the
  * 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) {
+    const chosen = ensureTruecolorContrast(fg, bg, 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(bg));
+    const drawn = table.get(table.match(chosen));
+    if (contrastRatio(drawn, 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.
+ */
+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.11.0",
+  "version": "0.13.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "type": "module",
   "sideEffects": false,