@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/measure.js

@@ -0,0 +1,67 @@
+/**
+ * Measurement — min/max cell width calculation for renderables.
+ */
+import { isMeasurable, measuring } from "./protocol.js";
+export class Measurement {
+    minimum;
+    maximum;
+    constructor(minimum, maximum) {
+        this.minimum = minimum;
+        this.maximum = maximum;
+    }
+    get span() {
+        return this.maximum - this.minimum;
+    }
+    /**
+     * A range with no cell meaning becomes one with the nearest meaning there is:
+     * negative floors to zero, an inverted pair collapses to its ceiling, and NaN
+     * reads as zero cells the same way `cellCount` reads it.
+     *
+     * NaN and Infinity are not treated alike here, and the difference is the whole
+     * point. `Infinity` is a maximum a renderable means — `Table` reports it when
+     * a column asks for every cell there is, and `withBoundedWidth` throws on it
+     * so a caller learns their offer was unanswerable. Flooring it to zero would
+     * turn that loud failure into a table measured at no width at all.
+     */
+    normalize() {
+        const cells = (n) => (Number.isNaN(n) ? 0 : n);
+        const min = Math.max(0, Math.min(cells(this.minimum), cells(this.maximum)));
+        const max = Math.max(0, cells(this.maximum));
+        return new Measurement(min, max);
+    }
+    withMaximum(width) {
+        return new Measurement(Math.min(this.minimum, width), Math.min(this.maximum, width));
+    }
+    withMinimum(width) {
+        const min = Math.max(this.minimum, width);
+        const max = Math.max(this.maximum, min);
+        return new Measurement(min, max);
+    }
+    clamp(minWidth, maxWidth) {
+        return new Measurement(Math.min(Math.max(this.minimum, minWidth), maxWidth), Math.min(Math.max(this.maximum, minWidth), maxWidth));
+    }
+    // [LAW:single-enforcer] Single entry point for measuring a renderable. One
+    // that cannot measure itself asks for the whole offer, as the reference's
+    // `Measurement.get` answers for it — so under an unbounded offer it asks for
+    // `Infinity`, and `withBoundedWidth` refuses rather than guessing a width.
+    static get(options, renderable) {
+        if (options.maxWidth < 1)
+            return new Measurement(0, 0);
+        if (!isMeasurable(renderable))
+            return new Measurement(0, options.maxWidth);
+        const { minimum, maximum } = renderable.measure(measuring(options));
+        return new Measurement(minimum, Math.min(maximum, options.maxWidth)).normalize();
+    }
+}
+export function measureRenderables(options, renderables) {
+    if (renderables.length === 0)
+        return new Measurement(0, 0);
+    let minOfAll = 0;
+    let maxOfAll = 0;
+    for (const m of renderables) {
+        const measurement = Measurement.get(options, m);
+        minOfAll = Math.max(minOfAll, measurement.minimum);
+        maxOfAll = Math.max(maxOfAll, measurement.maximum);
+    }
+    return new Measurement(minOfAll, maxOfAll);
+}

package/dist/core/memo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * memo — a string-keyed memo with a size bound: the one cache shape for a
+ * pure computation whose keys a long-running host derives without end. A
+ * statusline daemon redrawing a time-varying colour parses a new hex string,
+ * matches a new RGB triple, measures a new cell, on every frame; a memo that
+ * never evicts grows by one entry per frame for the life of the process.
+ */
+export declare const MEMO_MAX = 4096;
+/**
+ * `get(key, compute)` returns the value remembered for `key`, computing and
+ * remembering it on a miss. Holds at most `MEMO_MAX` entries. `compute` must
+ * be a pure function of `key`, so a value recomputed after a clear is the one
+ * that was dropped.
+ */
+export declare class Memo<V extends NonNullable<unknown>> {
+    private readonly entries;
+    get size(): number;
+    get(key: string, compute: (key: string) => V): V;
+}

package/dist/core/memo.js

@@ -0,0 +1,34 @@
+/**
+ * memo — a string-keyed memo with a size bound: the one cache shape for a
+ * pure computation whose keys a long-running host derives without end. A
+ * statusline daemon redrawing a time-varying colour parses a new hex string,
+ * matches a new RGB triple, measures a new cell, on every frame; a memo that
+ * never evicts grows by one entry per frame for the life of the process.
+ */
+// [LAW:single-enforcer] The one size policy for every memo in the library.
+// Clearing at the cap rather than evicting least-recently-used: a refill costs
+// one recomputation per key, and a clear needs no bookkeeping on the hit path.
+export const MEMO_MAX = 4096;
+/**
+ * `get(key, compute)` returns the value remembered for `key`, computing and
+ * remembering it on a miss. Holds at most `MEMO_MAX` entries. `compute` must
+ * be a pure function of `key`, so a value recomputed after a clear is the one
+ * that was dropped.
+ */
+export class Memo {
+    entries = new Map();
+    get size() {
+        return this.entries.size;
+    }
+    get(key, compute) {
+        const remembered = this.entries.get(key);
+        if (remembered !== undefined)
+            return remembered;
+        // Computed before the clear, so a compute that throws costs no entries.
+        const value = compute(key);
+        if (this.entries.size >= MEMO_MAX)
+            this.entries.clear();
+        this.entries.set(key, value);
+        return value;
+    }
+}

package/dist/core/oklch.d.ts

@@ -0,0 +1,161 @@
+/**
+ * OKLCH color space — perceptually-uniform polar form of OKLab.
+ *
+ * Math from Björn Ottosson's OKLab specification:
+ *   https://bottosson.github.io/posts/oklab/
+ *
+ * The full pipeline:
+ *   sRGB (0..255 int)  ↔  sRGB linear (0..1 float)  ↔  OKLab  ↔  OKLCH polar
+ * `fromRgba` walks left→right, `toRgba` walks right→left. The only lossy
+ * step is the final 0..255 quantization; the float math itself is
+ * reversible to within a few ULP.
+ *
+ * [LAW:one-type-per-behavior] OKLCH and sRGB are different *behaviors*:
+ * sRGB is the wire format terminals consume (what ANSI escape codes
+ * carry); OKLCH is the perceptual manipulation space (where equal
+ * numerical deltas mean equal perceptual deltas, which is the property
+ * "transposition" requires). Two types, mutual conversion, no hybrid.
+ *
+ * [LAW:one-way-deps] This module imports `ColorRgba` from core/color and
+ * nothing else from inside the project. Nothing in core/ depends back on
+ * this file.
+ */
+import { ColorRgba } from "./color.js";
+/**
+ * A perceptually-uniform color transform.
+ *
+ * [LAW:dataflow-not-control-flow] Identity is *data* (`IDENTITY`), not a
+ * special case. Every transposition runs the same code path — the values
+ * decide whether the operation is a no-op or a 180° rotation.
+ *
+ * Lightness is parameterized as `L' = clamp01(L * scale + shift)` to make
+ * "invert" expressible as `{scale: -1, shift: 1}` without a boolean knob.
+ */
+export interface ThemeKey {
+    /** Hue offset in degrees; positive rotates toward warmer→cooler→back. */
+    readonly hueShift: number;
+    /** Multiplier on chroma. 0 = grayscale, 1 = identity, >1 = more saturated. */
+    readonly chromaScale: number;
+    /** Multiplier on lightness. 1 = identity, -1 = invert around the L axis. */
+    readonly lightnessScale: number;
+    /** 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
+ * untouched. Combined with the anchor logic in `transposePalette`, this
+ * converts a dark theme to its light "octave": semantic anchors
+ * (error/success/warning) still lightness-invert — only their *hue* is
+ * preserved — so errors stay red and dark-on-light becomes light-on-dark.
+ */
+export declare const INVERT_LIGHTNESS: ThemeKey;
+/**
+ * Whether a key is the no-op transform. Exported so that callers
+ * (`transposePalette`) can fast-path byte-exact identity without going
+ * through the lossy sRGB↔OKLCH round-trip. [LAW:one-source-of-truth] —
+ * the predicate lives once, here.
+ */
+export declare function isIdentityKey(k: ThemeKey): boolean;
+/**
+ * Immutable OKLCH color. `l` ∈ [0, 1] (lightness), `c` ≥ 0 (chroma; typical
+ * sRGB-representable colors top out near 0.32), `h` ∈ [0, 360) (hue
+ * degrees), `alpha` ∈ [0, 1].
+ *
+ * [LAW:single-enforcer] Constructor is the only validation site, matching
+ * the `ColorRgba` pattern. Out-of-range `alpha` throws. l/c/h must be
+ * finite but are *not* clamped at construction — they're clamped during
+ * `toRgba` instead, so transforms can pass through intermediate
+ * representations (e.g. h = 720°, c = -0.1 mid-pipeline) before the final
+ * sRGB-quantization step normalizes them.
+ */
+export declare class Oklch {
+    #private;
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+    readonly alpha: number;
+    constructor(l: number, c: number, h: number, alpha?: number);
+    /** sRGB → linear → OKLab → polar. Pure; no I/O, no allocation beyond the result. */
+    static fromRgba(color: ColorRgba): Oklch;
+    /**
+     * Polar → OKLab → linear → sRGB (with chroma-bisection gamut clamping).
+     *
+     * [LAW:single-enforcer] All sRGB-gamut clamping for OKLCH happens here.
+     * Callers don't see intermediate float channels; they get a valid
+     * `ColorRgba` or a thrown error.
+     */
+    toRgba(): ColorRgba;
+    /**
+     * Apply a `ThemeKey`. Returns a new `Oklch`; pure.
+     *
+     * [LAW:dataflow-not-control-flow] Identity short-circuits to `this` —
+     * same shape as `ColorRgba.compositeOver(bg)` returning `this` when
+     * `alpha === 1`. Callers invoke unconditionally; the data decides.
+     */
+    applyKey(k: ThemeKey): Oklch;
+    /**
+     * The color `t` of the way from this one toward `toward`, in OKLCH.
+     * `t = 0` is this color, `t = 1` is `toward`; pure.
+     *
+     * Lightness, chroma and alpha interpolate linearly. Hue takes the shorter
+     * arc around the wheel, so blue → red passes through magenta rather than
+     * sweeping across green. An achromatic endpoint has no hue of its own —
+     * `fromRgba` pins it to 0, which is red — so it adopts the other
+     * endpoint's hue (CSS Color 4's "powerless" rule): gray → red stays a red
+     * that gains chroma, instead of rotating through the wheel from 0°.
+     *
+     * `t` must lie in [0, 1]: this is interpolation, not extrapolation, and a
+     * `t` outside it (NaN included) is a RangeError, never a colour off the
+     * far end of the segment. [LAW:no-silent-failure]
+     *
+     * [LAW:one-source-of-truth] Achromatic means the same `ACHROMATIC_EPS`
+     * that `fromRgba` and `applyKey` pin hue by, so a gray produced by either
+     * is a gray here — and the result's hue goes through the same `hueOf`, so
+     * a gray produced HERE (t = 0 from a gray, t = 1 toward one) is a gray
+     * 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;
+    /**
+     * Largest chroma ≤ `c` whose (l, h) projection lies in sRGB.
+     * Standard chroma-reduction-by-bisection: 24 iterations gives ~1e-7
+     * precision, more than enough since the next step quantizes to 1/255.
+     */
+    private findInGamutChroma;
+}

package/dist/core/oklch.js

@@ -0,0 +1,312 @@
+/**
+ * OKLCH color space — perceptually-uniform polar form of OKLab.
+ *
+ * Math from Björn Ottosson's OKLab specification:
+ *   https://bottosson.github.io/posts/oklab/
+ *
+ * The full pipeline:
+ *   sRGB (0..255 int)  ↔  sRGB linear (0..1 float)  ↔  OKLab  ↔  OKLCH polar
+ * `fromRgba` walks left→right, `toRgba` walks right→left. The only lossy
+ * step is the final 0..255 quantization; the float math itself is
+ * reversible to within a few ULP.
+ *
+ * [LAW:one-type-per-behavior] OKLCH and sRGB are different *behaviors*:
+ * sRGB is the wire format terminals consume (what ANSI escape codes
+ * carry); OKLCH is the perceptual manipulation space (where equal
+ * numerical deltas mean equal perceptual deltas, which is the property
+ * "transposition" requires). Two types, mutual conversion, no hybrid.
+ *
+ * [LAW:one-way-deps] This module imports `ColorRgba` from core/color and
+ * 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,
+    lightnessScale: 1,
+    lightnessShift: 0,
+});
+/**
+ * Flip lightness around the midpoint (`L' = 1 - L`) with hue and chroma
+ * untouched. Combined with the anchor logic in `transposePalette`, this
+ * converts a dark theme to its light "octave": semantic anchors
+ * (error/success/warning) still lightness-invert — only their *hue* is
+ * preserved — so errors stay red and dark-on-light becomes light-on-dark.
+ */
+export const INVERT_LIGHTNESS = Object.freeze({
+    hueShift: 0,
+    chromaScale: 1,
+    lightnessScale: -1,
+    lightnessShift: 1,
+});
+/**
+ * Whether a key is the no-op transform. Exported so that callers
+ * (`transposePalette`) can fast-path byte-exact identity without going
+ * through the lossy sRGB↔OKLCH round-trip. [LAW:one-source-of-truth] —
+ * the predicate lives once, here.
+ */
+export function isIdentityKey(k) {
+    return (k.hueShift % 360 === 0 && // a whole turn (0, 360, -360, …) is a no-op
+        k.chromaScale === 1 &&
+        k.lightnessScale === 1 &&
+        k.lightnessShift === 0);
+}
+// ---------------------------------------------------------------------------
+// Pure conversion helpers (private).
+// ---------------------------------------------------------------------------
+function srgbToLinear(v) {
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+function linearToSrgb(v) {
+    return v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+// Small tolerance so float-fuzz at the gamut edge doesn't trigger needless
+// chroma reduction on colors that are already representable.
+const GAMUT_EPS = 1e-4;
+// [LAW:one-source-of-truth] Below this chroma a color is achromatic and its
+// hue is pinned to 0 so round-trips stay stable — the one threshold every
+// chroma reader here shares.
+const ACHROMATIC_EPS = 1e-7;
+// The one spelling of that pin: every producer of an `Oklch` (`fromRgba`,
+// `applyKey`, `mix`) passes its result's chroma and hue through here, so a
+// gray from any of them carries the same hue. The constructor does not —
+// it passes intermediates through by contract. [LAW:single-enforcer]
+const hueOf = (c, h) => (c < ACHROMATIC_EPS ? 0 : h);
+// Endpoint-exact: `t = 0` returns `a` and `t = 1` returns `b` bit-for-bit,
+// which `a + (b - a) * t` does not (the subtraction rounds). One shape for
+// every axis `mix` interpolates. [LAW:one-source-of-truth]
+const lerp = (a, b, t) => a * (1 - t) + b * t;
+// Hue into [0, 360). Exact on a hue already there (fmod is exact), and exact
+// on `x - 360` for a representable x (the sum is x itself), which is what
+// `mix` relies on. One spelling for every producer. [LAW:one-source-of-truth]
+const wrapHue = (h) => {
+    const w = h % 360;
+    return w < 0 ? w + 360 : w;
+};
+function inGamut(r, g, b) {
+    return (r >= -GAMUT_EPS && r <= 1 + GAMUT_EPS &&
+        g >= -GAMUT_EPS && g <= 1 + GAMUT_EPS &&
+        b >= -GAMUT_EPS && b <= 1 + GAMUT_EPS);
+}
+// ---------------------------------------------------------------------------
+// Oklch — the value type.
+// ---------------------------------------------------------------------------
+/**
+ * Immutable OKLCH color. `l` ∈ [0, 1] (lightness), `c` ≥ 0 (chroma; typical
+ * sRGB-representable colors top out near 0.32), `h` ∈ [0, 360) (hue
+ * degrees), `alpha` ∈ [0, 1].
+ *
+ * [LAW:single-enforcer] Constructor is the only validation site, matching
+ * the `ColorRgba` pattern. Out-of-range `alpha` throws. l/c/h must be
+ * finite but are *not* clamped at construction — they're clamped during
+ * `toRgba` instead, so transforms can pass through intermediate
+ * representations (e.g. h = 720°, c = -0.1 mid-pipeline) before the final
+ * sRGB-quantization step normalizes them.
+ */
+export class Oklch {
+    l;
+    c;
+    h;
+    alpha;
+    constructor(l, c, h, alpha = 1) {
+        this.l = l;
+        this.c = c;
+        this.h = h;
+        this.alpha = alpha;
+        if (!Number.isFinite(l))
+            throw new RangeError(`Oklch.l must be finite; got ${l}`);
+        if (!Number.isFinite(c))
+            throw new RangeError(`Oklch.c must be finite; got ${c}`);
+        if (!Number.isFinite(h))
+            throw new RangeError(`Oklch.h must be finite; got ${h}`);
+        if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
+            throw new RangeError(`Oklch.alpha must be a finite number in [0,1]; got ${alpha}`);
+        }
+    }
+    /** sRGB → linear → OKLab → polar. Pure; no I/O, no allocation beyond the result. */
+    static fromRgba(color) {
+        const [r, g, b, a] = color.normalized;
+        const lr = srgbToLinear(r);
+        const lg = srgbToLinear(g);
+        const lb = srgbToLinear(b);
+        const lLong = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb;
+        const mLong = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb;
+        const sLong = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb;
+        const lCube = Math.cbrt(lLong);
+        const mCube = Math.cbrt(mLong);
+        const sCube = Math.cbrt(sLong);
+        const L = 0.2104542553 * lCube + 0.7936177850 * mCube - 0.0040720468 * sCube;
+        const aLab = 1.9779984951 * lCube - 2.4285922050 * mCube + 0.4505937099 * sCube;
+        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 _a(L, C, hueOf(C, H), a);
+    }
+    /**
+     * Polar → OKLab → linear → sRGB (with chroma-bisection gamut clamping).
+     *
+     * [LAW:single-enforcer] All sRGB-gamut clamping for OKLCH happens here.
+     * Callers don't see intermediate float channels; they get a valid
+     * `ColorRgba` or a thrown error.
+     */
+    toRgba() {
+        // The normalization boundary the constructor promises: clamp L into [0,1]
+        // and C to non-negative here, so out-of-range intermediates (e.g. c = -0.1
+        // from a mid-pipeline transform) canonicalize to a valid color rather than
+        // flipping hue through a negative chroma. H needs no wrap — the cos/sin in
+        // the conversion are periodic. [LAW:single-enforcer]
+        const l = clamp01(this.l);
+        const c = Math.max(0, this.c);
+        const cInGamut = this.findInGamutChroma(l, c, this.h);
+        const { r, g, b } = this.toLinearRgb(l, cInGamut, this.h);
+        const sR = Math.round(clamp01(linearToSrgb(r)) * 255);
+        const sG = Math.round(clamp01(linearToSrgb(g)) * 255);
+        const sB = Math.round(clamp01(linearToSrgb(b)) * 255);
+        return new ColorRgba(sR, sG, sB, this.alpha);
+    }
+    /**
+     * Apply a `ThemeKey`. Returns a new `Oklch`; pure.
+     *
+     * [LAW:dataflow-not-control-flow] Identity short-circuits to `this` —
+     * same shape as `ColorRgba.compositeOver(bg)` returning `this` when
+     * `alpha === 1`. Callers invoke unconditionally; the data decides.
+     */
+    applyKey(k) {
+        if (isIdentityKey(k))
+            return this;
+        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 _a(newL, newC, hueOf(newC, newH), this.alpha);
+    }
+    /**
+     * The color `t` of the way from this one toward `toward`, in OKLCH.
+     * `t = 0` is this color, `t = 1` is `toward`; pure.
+     *
+     * Lightness, chroma and alpha interpolate linearly. Hue takes the shorter
+     * arc around the wheel, so blue → red passes through magenta rather than
+     * sweeping across green. An achromatic endpoint has no hue of its own —
+     * `fromRgba` pins it to 0, which is red — so it adopts the other
+     * endpoint's hue (CSS Color 4's "powerless" rule): gray → red stays a red
+     * that gains chroma, instead of rotating through the wheel from 0°.
+     *
+     * `t` must lie in [0, 1]: this is interpolation, not extrapolation, and a
+     * `t` outside it (NaN included) is a RangeError, never a colour off the
+     * far end of the segment. [LAW:no-silent-failure]
+     *
+     * [LAW:one-source-of-truth] Achromatic means the same `ACHROMATIC_EPS`
+     * that `fromRgba` and `applyKey` pin hue by, so a gray produced by either
+     * is a gray here — and the result's hue goes through the same `hueOf`, so
+     * a gray produced HERE (t = 0 from a gray, t = 1 toward one) is a gray
+     * there too.
+     */
+    mix(toward, t) {
+        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);
+        const toH = wrapHue(towardHasHue ? toward.h : fromH);
+        // Shorter arc: endpoints more than half a turn apart lerp across 0°, the
+        // larger one taken a turn down. `x - 360` for x ≥ 180 is exact
+        // (Sterbenz), so the endpoints survive the shift and the wrap bit-for-bit
+        // — an addition of 360 would not.
+        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, 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. */
+    toLinearRgb(l, C, h) {
+        const hRad = h * (Math.PI / 180);
+        const aLab = C * Math.cos(hRad);
+        const bLab = C * Math.sin(hRad);
+        const lCube = l + 0.3963377774 * aLab + 0.2158037573 * bLab;
+        const mCube = l - 0.1055613458 * aLab - 0.0638541728 * bLab;
+        const sCube = l - 0.0894841775 * aLab - 1.2914855480 * bLab;
+        const lLong = lCube * lCube * lCube;
+        const mLong = mCube * mCube * mCube;
+        const sLong = sCube * sCube * sCube;
+        return {
+            r: +4.0767416621 * lLong - 3.3077115913 * mLong + 0.2309699292 * sLong,
+            g: -1.2684380046 * lLong + 2.6097574011 * mLong - 0.3413193965 * sLong,
+            b: -0.0041960863 * lLong - 0.7034186147 * mLong + 1.7076147010 * sLong,
+        };
+    }
+    /**
+     * Largest chroma ≤ `c` whose (l, h) projection lies in sRGB.
+     * Standard chroma-reduction-by-bisection: 24 iterations gives ~1e-7
+     * precision, more than enough since the next step quantizes to 1/255.
+     */
+    findInGamutChroma(l, c, h) {
+        const direct = this.toLinearRgb(l, c, h);
+        if (inGamut(direct.r, direct.g, direct.b))
+            return c;
+        let lo = 0;
+        let hi = c;
+        for (let i = 0; i < 24; i++) {
+            const mid = (lo + hi) / 2;
+            const probe = this.toLinearRgb(l, mid, h);
+            if (inGamut(probe.r, probe.g, probe.b))
+                lo = mid;
+            else
+                hi = mid;
+        }
+        return lo;
+    }
+}
+_a = Oklch;

package/dist/core/osc8.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The OSC 8 hyperlink wire grammar — which bytes may not appear inside a
+ * link, how a link becomes bytes, and how bytes are read back as a link.
+ *
+ * [LAW:one-source-of-truth] The producer (`segmentToString`, the one encoder
+ * every link reaches the wire through) opens a link with `osc8Open` and closes
+ * it with `OSC8_CLOSE`; every consumer that reads rendered bytes (a width measure, a
+ * test extracting URLs) matches them with `OSC8`; the data-model boundary
+ * (RichText) cleans URLs with `stripOscTerminators`. All four read the one
+ * terminator set below, so the bytes a sanitizer removes and the bytes a
+ * reader stops at cannot disagree.
+ *
+ * [LAW:locality-or-seam] This module depends only on `fnv1a`; every consumer
+ * imports downward.
+ *
+ * The `id=` parameter is what makes one link hover as one link. A terminal
+ * treats cells as the same hyperlink when they share BOTH the URI and the id
+ * (the OSC 8 spec, and VTE / iTerm2 / kitty / WezTerm alike); without an id,
+ * each open sequence is its own link. The encoder writes one OSC 8 pair per
+ * segment, as the reference does, so a link whose text spans several segments
+ * — a bold glyph beside plain text, a padded cell — is emitted as several
+ * pairs, and would highlight piecewise on hover.
+ *
+ * [LAW:types-are-the-program] The id is a pure function of the URI, so the
+ * byte stream stays a pure function of (style, text, destination): no counter,
+ * no construction-order dependence. The consequence is deliberate: two spans
+ * with the same URI hover as one link wherever they sit on screen, adjacent
+ * or not — a click on either does the same thing, so they ARE one link.
+ * Because terminals key on the (id, URI) PAIR, a hash collision between two
+ * different URIs merges nothing — the URIs still differ — so a 32-bit hash is
+ * exact, not approximate.
+ */
+/** Remove every byte that could break a URL out of its OSC 8 wrap. */
+export declare function stripOscTerminators(url: string): string;
+/**
+ * The bytes that open a hyperlink to `url`.
+ *
+ * [LAW:single-enforcer] Wire-byte trust boundary — the URL is sanitized at
+ * the one place it becomes an OSC 8 sequence, whichever upstream API attached
+ * it to the Style (RichText sanitizes at its data-model boundary too; a Style
+ * built directly with `new Style({ link })` reaches here unsanitized).
+ */
+export declare function osc8Open(url: string): string;
+/** The bytes that close the current hyperlink. */
+export declare const OSC8_CLOSE = "\u001B]8;;\u001B\\";
+/**
+ * Matches one OSC 8 sequence — an open or a close — terminated by `ESC \`,
+ * BEL, or the 8-bit ST. Group 1 is the params, group 2 the URI; both are empty
+ * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
+ * for composing into a larger one (a width measure's zero-width alternation).
+ */
+export declare const OSC8: RegExp;
+/** One OSC 8 sequence found in rendered bytes. A close has `uri === ""`. */
+export interface Osc8Sequence {
+    /** Offset of the sequence in the scanned string. */
+    readonly index: number;
+    /** Length of the whole sequence, terminator included. */
+    readonly length: number;
+    /** The params field (`id=…`); empty on a close. */
+    readonly params: string;
+    /** The URI; empty on a close. */
+    readonly uri: string;
+}
+/**
+ * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
+ * bytes back.
+ */
+export declare function osc8Sequences(text: string): Osc8Sequence[];