@promptctl/rich-js 0.17.0 → 0.18.0

package/dist/renderables/traceback.d.ts

@@ -1,31 +0,0 @@
-/**
- * Traceback — renders error tracebacks with formatting.
- *
- * [LAW:effects-at-boundaries] Pure rendering: an `Error` in, `Segment`s out.
- * Installing this as the process-wide crash handler touches `process.on` and
- * `process.exit`, so that lives behind the node seam as `installTraceback` in
- * `src/node/traceback.ts` — which is what keeps this module, and therefore the
- * main barrel, importable in a browser.
- *
- * [LAW:types-are-the-program] `TracebackOptions` names only what the renderer
- * reads. There is no `showLocals`: an `Error` carries a stack of locations and
- * nothing of the values in scope at them. The one way to get those in node —
- * an inspector session pausing on exceptions — would have to pause on every
- * throw, caught ones included, to serve `new Traceback(caughtError)`, and it
- * cannot exist in a browser at all. Nor is there a `width` or `theme`: those
- * sized and coloured a source-code excerpt this renderer does not produce.
- */
-import { Segment } from "../core/segment.js";
-import type { Renderable, RenderOptions } from "../core/protocol.js";
-export interface TracebackOptions {
-    suppress?: string[];
-    maxFrames?: number;
-}
-export declare class Traceback implements Renderable {
-    readonly error: Error;
-    readonly maxFrames: number;
-    readonly suppress: string[];
-    constructor(error: Error, options?: TracebackOptions);
-    render(options: RenderOptions): Iterable<Segment>;
-    private _renderFrame;
-}

package/dist/renderables/traceback.js

@@ -1,109 +0,0 @@
-/**
- * Traceback — renders error tracebacks with formatting.
- *
- * [LAW:effects-at-boundaries] Pure rendering: an `Error` in, `Segment`s out.
- * Installing this as the process-wide crash handler touches `process.on` and
- * `process.exit`, so that lives behind the node seam as `installTraceback` in
- * `src/node/traceback.ts` — which is what keeps this module, and therefore the
- * main barrel, importable in a browser.
- *
- * [LAW:types-are-the-program] `TracebackOptions` names only what the renderer
- * reads. There is no `showLocals`: an `Error` carries a stack of locations and
- * nothing of the values in scope at them. The one way to get those in node —
- * an inspector session pausing on exceptions — would have to pause on every
- * throw, caught ones included, to serve `new Traceback(caughtError)`, and it
- * cannot exist in a browser at all. Nor is there a `width` or `theme`: those
- * sized and coloured a source-code excerpt this renderer does not produce.
- */
-import { Segment } from "../core/segment.js";
-import { Style } from "../core/style.js";
-import { getStyle } from "../core/protocol.js";
-function parseStack(error) {
-    const stack = error.stack ?? "";
-    const lines = stack.split("\n");
-    const frames = [];
-    for (const line of lines) {
-        const trimmed = line.trim();
-        // Node.js format: "    at functionName (file:line:column)"
-        // or:            "    at file:line:column"
-        const match = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?/.exec(trimmed);
-        if (match) {
-            frames.push({
-                function: match[1] || undefined,
-                file: match[2],
-                line: parseInt(match[3], 10),
-                column: parseInt(match[4], 10),
-            });
-        }
-    }
-    return frames;
-}
-export class Traceback {
-    error;
-    maxFrames;
-    suppress;
-    constructor(error, options) {
-        this.error = error;
-        this.maxFrames = options?.maxFrames ?? 100;
-        this.suppress = options?.suppress ?? [];
-    }
-    *render(options) {
-        const excTypeStyle = getStyle(options, "traceback.exc_type");
-        const textStyle = getStyle(options, "traceback.text");
-        // Error type and message
-        const errorName = this.error.name || "Error";
-        const errorMessage = this.error.message || "";
-        yield new Segment(errorName, excTypeStyle);
-        yield new Segment(": ");
-        yield new Segment(errorMessage, textStyle);
-        yield Segment.line();
-        yield Segment.line();
-        // Stack frames — suppressed frames show file/line only (not removed)
-        const frames = parseStack(this.error);
-        const filteredFrames = this.suppress.length > 0
-            ? frames.map((f) => ({
-                ...f,
-                suppressed: this.suppress.some((s) => f.file.includes(s)),
-            }))
-            : frames;
-        let displayFrames = filteredFrames;
-        if (this.maxFrames > 0 && displayFrames.length > this.maxFrames) {
-            // Spend the budget exactly: the tail takes `maxFrames - head` rather than
-            // a second `head`, so an odd budget shows every frame it counts, and it
-            // slices from an index because `slice(-0)` is the whole array.
-            const head = Math.floor(this.maxFrames / 2);
-            const first = displayFrames.slice(0, head);
-            const last = displayFrames.slice(displayFrames.length - (this.maxFrames - head));
-            const omitted = displayFrames.length - this.maxFrames;
-            for (const frame of first) {
-                yield* this._renderFrame(frame, options);
-            }
-            yield new Segment(`  ... ${omitted} frames omitted ...`, textStyle);
-            yield Segment.line();
-            for (const frame of last) {
-                yield* this._renderFrame(frame, options);
-            }
-        }
-        else {
-            for (const frame of displayFrames) {
-                yield* this._renderFrame(frame, options);
-            }
-        }
-    }
-    *_renderFrame(frame, options) {
-        const pathStyle = Style.parse("dim");
-        const lineNoStyle = getStyle(options, "traceback.offset");
-        yield new Segment("  ");
-        // Spec: suppressed frames show file and line only — no function name
-        if (frame.function && !frame.suppressed) {
-            yield new Segment(frame.function, Style.parse("bold"));
-            yield new Segment(" ");
-        }
-        yield new Segment(frame.file, pathStyle);
-        if (frame.line !== undefined) {
-            yield new Segment(":");
-            yield new Segment(String(frame.line), lineNoStyle);
-        }
-        yield Segment.line();
-    }
-}

package/dist/renderables/tree.d.ts

@@ -1,54 +0,0 @@
-/**
- * Tree — hierarchical view with guide lines.
- */
-import { Segment } from "../core/segment.js";
-import { Style } from "../core/style.js";
-import { RichText } from "../core/text.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-export interface TreeOptions {
-    expanded?: boolean;
-    hideRoot?: boolean;
-    guide_style?: string | Style;
-    style?: string | Style;
-}
-export declare class Tree implements Renderable, Measurable {
-    readonly label: Renderable;
-    readonly children: Tree[];
-    expanded: boolean;
-    readonly hideRoot: boolean;
-    readonly guideStyle: string | Style;
-    readonly style: string | Style;
-    constructor(label: string | RichText | Renderable, options?: TreeOptions);
-    add(label: string | RichText | Renderable, options?: TreeOptions): Tree;
-    render(rawOptions: RenderOptions): Iterable<Segment>;
-    /**
-     * The tree walked into the rows it emits, one row per label, guides first.
-     *
-     * [LAW:one-source-of-truth] The walk that decides which rows exist and what
-     * leads them is here and only here. `render` turns each row into segments and
-     * `measure` reads each row's width off the same sequence, so the two cannot
-     * come to disagree about how many rows there are or how wide the guides on
-     * them run — which they would the moment a second walk existed.
-     */
-    private _rows;
-    /**
-     * One row of the tree: its guides, then its label in whatever width the
-     * guides left.
-     *
-     * [LAW:single-enforcer] The row's width is divided in exactly one place, here.
-     * Before this, each call site emitted its guides and then handed the label
-     * `options` unchanged — the label was told it had the whole outer width while
-     * the guides had already spent four cells of it, so a tree at maxWidth 5
-     * emitted rows of 9. That is the same defect Panel and Table were fixed for,
-     * and the same fix: divide the requested width once and let every part read
-     * its share off the division. `options` arrives parsed from `render`.
-     *
-     * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
-     * depending on label renderables to invent trailing newlines.
-     */
-    private _renderRow;
-    measure(options: RenderOptions): {
-        minimum: number;
-        maximum: number;
-    };
-}

package/dist/renderables/tree.js

@@ -1,159 +0,0 @@
-/**
- * Tree — hierarchical view with guide lines.
- */
-import { Segment } from "../core/segment.js";
-import { cellFit, cellLen, asCellCol } from "../core/cells.js";
-import { NULL_STYLE } from "../core/style.js";
-import { RichText } from "../core/text.js";
-import { getStyle, isMeasurable, withBoundedWidth, withCellWidth } from "../core/protocol.js";
-import { Measurement } from "../core/measure.js";
-// Guide characters
-const GUIDE_BRANCH = "├── ";
-const GUIDE_LAST = "└── ";
-const GUIDE_VERT = "│   ";
-const GUIDE_SPACE = "    ";
-// ASCII fallback
-const GUIDE_BRANCH_ASCII = "+-- ";
-const GUIDE_LAST_ASCII = "+-- ";
-const GUIDE_VERT_ASCII = "|   ";
-function toRenderable(label) {
-    if (typeof label === "string")
-        return new RichText(label, { end: "" });
-    if (label instanceof RichText) {
-        // Ensure no trailing newline in tree labels
-        const copy = label.copy();
-        copy.end = "";
-        return copy;
-    }
-    return label;
-}
-/**
- * How wide a label wants to be. A label with no `measure` cannot say, and the
- * offer is the honest stand-in — including when the offer is unbounded, which
- * is where `withBoundedWidth` reports it rather than guessing a number.
- */
-function labelWidth(options, label) {
-    if (!isMeasurable(label))
-        return options.maxWidth;
-    return Measurement.get(options, label).maximum;
-}
-export class Tree {
-    label;
-    children;
-    expanded;
-    hideRoot;
-    guideStyle;
-    style;
-    constructor(label, options) {
-        this.label = toRenderable(label);
-        this.children = [];
-        this.expanded = options?.expanded !== false;
-        this.hideRoot = options?.hideRoot ?? false;
-        this.guideStyle = options?.guide_style ?? NULL_STYLE;
-        this.style = options?.style ?? NULL_STYLE;
-    }
-    add(label, options) {
-        const child = new Tree(label, {
-            guide_style: options?.guide_style,
-            style: options?.style,
-            expanded: options?.expanded,
-        });
-        this.children.push(child);
-        return child;
-    }
-    *render(rawOptions) {
-        const options = withBoundedWidth(rawOptions, this);
-        for (const row of this._rows(options, [], !this.hideRoot)) {
-            yield* this._renderRow(options, row);
-        }
-    }
-    /**
-     * The tree walked into the rows it emits, one row per label, guides first.
-     *
-     * [LAW:one-source-of-truth] The walk that decides which rows exist and what
-     * leads them is here and only here. `render` turns each row into segments and
-     * `measure` reads each row's width off the same sequence, so the two cannot
-     * come to disagree about how many rows there are or how wide the guides on
-     * them run — which they would the moment a second walk existed.
-     */
-    *_rows(options, prefixes, showLabel) {
-        const ascii = options.asciiOnly ?? false;
-        if (showLabel) {
-            yield { guides: prefixes, guideStyles: [this.guideStyle], label: this.label };
-        }
-        if (!this.expanded)
-            return;
-        for (let i = 0; i < this.children.length; i++) {
-            const child = this.children[i];
-            const isLast = i === this.children.length - 1;
-            const branch = ascii
-                ? (isLast ? GUIDE_LAST_ASCII : GUIDE_BRANCH_ASCII)
-                : (isLast ? GUIDE_LAST : GUIDE_BRANCH);
-            const continuation = ascii
-                ? (isLast ? GUIDE_SPACE : GUIDE_VERT_ASCII)
-                : (isLast ? GUIDE_SPACE : GUIDE_VERT);
-            // Child label with branch guide
-            yield {
-                guides: [...prefixes, branch],
-                guideStyles: [child.guideStyle, this.guideStyle],
-                label: child.label,
-            };
-            // Grandchildren with continuation prefix
-            if (child.expanded && child.children.length > 0) {
-                const grandPrefixes = [...prefixes, continuation];
-                for (let j = 0; j < child.children.length; j++) {
-                    yield* child.children[j]._rows(options, grandPrefixes, true);
-                }
-            }
-        }
-    }
-    /**
-     * One row of the tree: its guides, then its label in whatever width the
-     * guides left.
-     *
-     * [LAW:single-enforcer] The row's width is divided in exactly one place, here.
-     * Before this, each call site emitted its guides and then handed the label
-     * `options` unchanged — the label was told it had the whole outer width while
-     * the guides had already spent four cells of it, so a tree at maxWidth 5
-     * emitted rows of 9. That is the same defect Panel and Table were fixed for,
-     * and the same fix: divide the requested width once and let every part read
-     * its share off the division. `options` arrives parsed from `render`.
-     *
-     * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
-     * depending on label renderables to invent trailing newlines.
-     */
-    *_renderRow(options, row) {
-        const guideStyle = row.guideStyles.map((style) => getStyle(options, style)).find((style) => !style.isNull);
-        let left = options.maxWidth;
-        for (const text of row.guides) {
-            const piece = cellFit(text, asCellCol(left));
-            if (piece.length > 0)
-                yield new Segment(piece, guideStyle);
-            left -= cellLen(piece);
-        }
-        // The guides above are cropped by `cellFit`; the label was not, so a label
-        // that ignores the width it is handed pushed the row past the offer the
-        // guides had just been fitted into.
-        yield* Segment.cropLines(row.label.render({ ...options, maxWidth: left }), left);
-        yield Segment.line();
-    }
-    measure(options) {
-        // The ceiling is parsed for the same reason the rows are: an unparsed NaN
-        // ceiling yields a range no parent layout can divide.
-        const parsed = withCellWidth(options);
-        const ceiling = parsed.maxWidth;
-        // The widest row the walk emits, not the offer. Reported as the offer, a
-        // tree told any parent that asked "I want all of it" — so `Panel` in fit
-        // mode drew a 40-cell frame around nine cells of tree, and an unbounded
-        // offer came back unbounded.
-        let natural = 0;
-        for (const row of this._rows(parsed, [], !this.hideRoot)) {
-            const guideWidth = row.guides.reduce((sum, text) => sum + cellLen(text), 0);
-            natural = Math.max(natural, guideWidth + labelWidth(parsed, row.label));
-        }
-        const maximum = Math.min(natural, ceiling);
-        // A row is its guides plus at least one cell of label — but never more than
-        // this tree turned out to want, or the floor would sit above its own ceiling.
-        return { minimum: Math.min(4, maximum), maximum };
-    }
-}

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

@@ -1,87 +0,0 @@
-/**
- * Color *values* for the rich-js template binding.
- *
- * ### Why colors are values
- *
- * Every other function in this binding layer takes a child fragment and
- * returns a styled fragment. These do not: they take colors and return a
- * color. That is the whole point. Before this module existed, a color could
- * not survive between two operations — every color function resolved and
- * applied in one breath — so composing two color operations had to be spelled
- * as a *string grammar* (`"primary-darken-3 50%"`), a second language
- * reimplementing function application inside a string literal. Every new color
- * operation meant a new grammar production. [LAW:no-mode-explosion]
- *
- * With colors as values the surface is one shape that grows by nesting:
- *
- * ```
- * {{ fg (color "primary") .branch }}
- * {{ fg (darken (color "primary") 2) .branch }}
- * {{ fg (mix (color "foreground") (color "surface") 65) .label }}
- * ```
- *
- * The simple case is a literal prefix of the composed case — an author adding
- * a `darken` to working code wraps it, rather than rewriting it into an
- * unfamiliar form. [LAW:composability]
- *
- * ### The carrier is a hex string, deliberately
- *
- * A color crosses the template seam as `#RRGGBB`, not as an opaque object,
- * for three reasons:
- *
- * 1. **The type separates.** `"string"` is the strictest arg slot the template
- *    engine has — it *refuses* typed `T`. So a color slot cannot silently
- *    accept a text fragment. An opaque object would land in `"T"`/`"liftable"`,
- *    both of which admit any non-primitive, and `{{ bold (color "primary") }}`
- *    would type-check its way into nonsense. [LAW:types-are-the-program]
- * 2. **It flows through the language.** `{{ $muted := mix … }}` holds it,
- *    `printf` prints it, `eq` compares it — no engine changes required. Naming
- *    a color once and using it ten times is the ergonomic payoff.
- * 3. **Misuse is visible.** A color that lands in text position renders as
- *    `#7aa2f7` — wrong in a way an author immediately sees, never a silently
- *    dropped style. [LAW:no-silent-failure]
- *
- * No precision is given up: `darken`, `blendRgb`, and `contrastFor` already
- * take and return 8-bit `ColorRgba`. The one caveat is OKLCH: each of the
- * axis functions below round-trips sRGB→OKLCH→sRGB, so chaining three or more
- * of them quantizes visibly. Compose two, or reach for `transposePalette` when
- * a whole palette needs adapting — the same caveat that already applies to
- * chained transpositions.
- *
- * ### Palette-free on purpose
- *
- * Nothing here knows what a palette is. `color` and `ramp` (the two
- * palette-dependent functions, in `palette-funcs.ts`) turn names into hex;
- * 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, 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.
- *
- * | function | meaning |
- * |---|---|
- * | `darken c n` / `lighten c n` | slide HSL lightness by N 10% levels |
- * | `mix a b pct` | blend `a` toward `b` by `pct`% (0 → `a`, 100 → `b`) |
- * | `contrastOn bg` | black or white, whichever is readable on `bg` |
- * | `readableOn fg bg ratio` | `fg` nudged in OKLCH lightness until it clears `ratio` on `bg`, hue preserved |
- * | `shiftHue c deg` | rotate hue in OKLCH |
- * | `scaleChroma c f` | multiply chroma (0 → gray, 1 → identity) |
- * | `scaleLightness c f` | multiply lightness (1 → identity, -1 → invert) |
- * | `shiftLightness c d` | add to lightness, after any scale |
- *
- * 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(drawnAt?: () => ColorDepth): FuncMap;

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

@@ -1,219 +0,0 @@
-/**
- * Color *values* for the rich-js template binding.
- *
- * ### Why colors are values
- *
- * Every other function in this binding layer takes a child fragment and
- * returns a styled fragment. These do not: they take colors and return a
- * color. That is the whole point. Before this module existed, a color could
- * not survive between two operations — every color function resolved and
- * applied in one breath — so composing two color operations had to be spelled
- * as a *string grammar* (`"primary-darken-3 50%"`), a second language
- * reimplementing function application inside a string literal. Every new color
- * operation meant a new grammar production. [LAW:no-mode-explosion]
- *
- * With colors as values the surface is one shape that grows by nesting:
- *
- * ```
- * {{ fg (color "primary") .branch }}
- * {{ fg (darken (color "primary") 2) .branch }}
- * {{ fg (mix (color "foreground") (color "surface") 65) .label }}
- * ```
- *
- * The simple case is a literal prefix of the composed case — an author adding
- * a `darken` to working code wraps it, rather than rewriting it into an
- * unfamiliar form. [LAW:composability]
- *
- * ### The carrier is a hex string, deliberately
- *
- * A color crosses the template seam as `#RRGGBB`, not as an opaque object,
- * for three reasons:
- *
- * 1. **The type separates.** `"string"` is the strictest arg slot the template
- *    engine has — it *refuses* typed `T`. So a color slot cannot silently
- *    accept a text fragment. An opaque object would land in `"T"`/`"liftable"`,
- *    both of which admit any non-primitive, and `{{ bold (color "primary") }}`
- *    would type-check its way into nonsense. [LAW:types-are-the-program]
- * 2. **It flows through the language.** `{{ $muted := mix … }}` holds it,
- *    `printf` prints it, `eq` compares it — no engine changes required. Naming
- *    a color once and using it ten times is the ergonomic payoff.
- * 3. **Misuse is visible.** A color that lands in text position renders as
- *    `#7aa2f7` — wrong in a way an author immediately sees, never a silently
- *    dropped style. [LAW:no-silent-failure]
- *
- * No precision is given up: `darken`, `blendRgb`, and `contrastFor` already
- * take and return 8-bit `ColorRgba`. The one caveat is OKLCH: each of the
- * axis functions below round-trips sRGB→OKLCH→sRGB, so chaining three or more
- * of them quantizes visibly. Compose two, or reach for `transposePalette` when
- * a whole palette needs adapting — the same caveat that already applies to
- * chained transpositions.
- *
- * ### Palette-free on purpose
- *
- * Nothing here knows what a palette is. `color` and `ramp` (the two
- * palette-dependent functions, in `palette-funcs.ts`) turn names into hex;
- * 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, 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";
-/**
- * The gate every color argument crosses. [LAW:parse-dont-validate] — the
- * function bodies below receive `ColorRgba` and never re-check.
- *
- * Parsing itself is `parseHexColor`'s job; this wrapper exists only to replace
- * its error *wording*, because the mistake it catches is almost always the
- * same one — a palette name passed where a color belongs (`darken "primary" 2`)
- * — and an author who reads "wrap it: darken (color "primary")" is corrected in
- * one step, where "expected #RRGGBB" leaves them guessing.
- * [LAW:no-silent-failure]
- */
-function asColor(value, func) {
-    if (!HEX_COLOR_RE.test(value.trim())) {
-        throw new TypeError(`${func} expected a color (#RRGGBB or #RRGGBBAA), got ${JSON.stringify(value)}` +
-            ` — to use a palette name here, wrap it: ${func} (color ${JSON.stringify(value)}) …`);
-    }
-    return parseHexColor(value);
-}
-function colorFunc(argTypes, fn) {
-    return { fn, argTypes, returnType: "string" };
-}
-/**
- * The gate every *numeric* argument crosses, with an optional inclusive range.
- *
- * [LAW:single-enforcer] One check for the whole family. The template engine
- * treats a trailing slot as variadic, so an under-supplied call
- * (`{{ darken "#102030" }}`) reaches the body with `undefined` rather than
- * failing at the gate. Without this, that `undefined` propagated into the color
- * math and surfaced as `ColorRgba.red must be an integer in [0, 255]; got NaN`
- * — loud, but pointing at a channel the author never wrote, three layers from
- * the missing argument. An error that does not locate its cause is barely
- * better than a silent one. [LAW:no-silent-failure]
- */
-function asAmount(value, func, param, range) {
-    const inRange = range === undefined || (value >= range.min && value <= range.max);
-    if (!Number.isFinite(value) || !inRange) {
-        const bound = range === undefined
-            ? "a finite number"
-            : `within ${range.min}..${range.max} (${range.note})`;
-        throw new RangeError(`${func}'s ${param} must be ${bound}, got ${value}` +
-            (value === undefined ? ` — ${func} takes it as its last argument` : ""));
-    }
-    return value;
-}
-// --- HSL lightness ---
-//
-// `lighten` is `darken` with the sign flipped — the same operation, not a
-// second one (colorMath's `lighten` is literally `darken(c, -levels)`). Both
-// names ship because "lighten by 2" and "darken by -2" are not equally
-// readable at a call site, and the operation is genuinely bidirectional.
-const darkenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "darken"), asAmount(levels, "darken", "levels")).hex));
-const lightenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "lighten"), -asAmount(levels, "lighten", "levels")).hex));
-// --- Blending ---
-//
-// [LAW:one-type-per-behavior] There is no separate `alphaBlend` binding.
-// `alphaBlend(fg, bg, a)` in colorMath is *defined* as `blendRgb(bg, fg, a)` —
-// one operation wearing two names. Compositing a translucent color over a
-// background and mixing two colors by a percentage are the same arithmetic,
-// so they get one function. Terminals have no alpha channel, which is also why
-// no function here *produces* a translucent color: it could not be rendered,
-// and a color that silently does nothing in the sink is worse than no
-// function at all.
-const MIX_PCT_MAX = 100;
-const MIX_RANGE = { min: 0, max: MIX_PCT_MAX, note: "0 = from, 100 = toward" };
-const mixFunc = colorFunc(["string", "string", "float"], ((fromHex, towardHex, pct) => blendRgb(asColor(fromHex, "mix"), asColor(towardHex, "mix"), asAmount(pct, "mix", "percentage", MIX_RANGE) / MIX_PCT_MAX).hex));
-// --- Readability ---
-//
-// Two different questions, so two functions rather than one with a flag:
-// `contrastOn` asks "what is maximally readable here" (black or white, WCAG
-// relative-luminance cutoff); `readableOn` asks "keep this color recognizably
-// itself, but guarantee it clears `ratio`" — it slides OKLCH lightness and
-// preserves hue, so a blue on dark blue becomes a lighter blue rather than
-// white.
-//
-// [LAW:no-silent-failure] `ratio` is required, not defaulted to WCAG AA's 4.5.
-// The threshold is the whole decision this function makes, and the right value
-// genuinely differs by intent — 4.5 for body text, 3.0 for large or
-// deliberately recessive text. A hidden default would silently govern an
-// accessibility outcome the author never saw, and would quietly over-correct a
-// caller whose *point* was to be quiet: de-emphasized text floored at 4.5 is no
-// longer de-emphasized.
-// WCAG 2.x contrast ratios live in [1, 21] — 1 is a color on itself.
-const RATIO_RANGE = {
-    min: 1,
-    max: 21,
-    note: "4.5 = AA body text, 3 = AA large text",
-};
-const contrastOnFunc = colorFunc(["string"], ((bgHex) => contrastFor(asColor(bgHex, "contrastOn")).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
-// keyed BY the axis so the compiler proves it total: add a field to `ThemeKey`
-// and this object stops satisfying `Record<keyof ThemeKey, string>` until a
-// binding name is chosen for it. The same derive-registrations-from-the-real-
-// inventory trick `attributeFuncs()` uses over `ATTRIBUTE_NAMES`.
-//
-// Naming follows the axis semantics rather than the field spelling: `shift`
-// for the additive axes, `scale` for the multiplicative ones, so a reader can
-// tell from the call site whether `1` means "no change" or "one unit".
-const OKLCH_AXIS_FUNCS = {
-    hueShift: "shiftHue",
-    chromaScale: "scaleChroma",
-    lightnessScale: "scaleLightness",
-    lightnessShift: "shiftLightness",
-};
-function oklchAxisFuncs() {
-    const out = {};
-    for (const [axis, funcName] of Object.entries(OKLCH_AXIS_FUNCS)) {
-        // [LAW:dataflow-not-control-flow] Every axis takes the identical path —
-        // splice one value into the identity key and apply it. The axis is data.
-        const key = axis;
-        out[funcName] = colorFunc(["string", "float"], ((hex, amount) => {
-            const themeKey = {
-                ...IDENTITY,
-                [key]: asAmount(amount, funcName, "amount"),
-            };
-            return Oklch.fromRgba(asColor(hex, funcName)).applyKey(themeKey).toRgba().hex;
-        }));
-    }
-    return out;
-}
-/**
- * The palette-free color vocabulary: every function takes colors and returns a
- * color, so they compose by nesting.
- *
- * | function | meaning |
- * |---|---|
- * | `darken c n` / `lighten c n` | slide HSL lightness by N 10% levels |
- * | `mix a b pct` | blend `a` toward `b` by `pct`% (0 → `a`, 100 → `b`) |
- * | `contrastOn bg` | black or white, whichever is readable on `bg` |
- * | `readableOn fg bg ratio` | `fg` nudged in OKLCH lightness until it clears `ratio` on `bg`, hue preserved |
- * | `shiftHue c deg` | rotate hue in OKLCH |
- * | `scaleChroma c f` | multiply chroma (0 → gray, 1 → identity) |
- * | `scaleLightness c f` | multiply lightness (1 → identity, -1 → invert) |
- * | `shiftLightness c d` | add to lightness, after any scale |
- *
- * 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(drawnAt = () => ColorDepth.TRUECOLOR) {
-    return {
-        darken: darkenFunc,
-        lighten: lightenFunc,
-        mix: mixFunc,
-        contrastOn: contrastOnFunc,
-        readableOn: readableOnFunc(drawnAt),
-        ...oklchAxisFuncs(),
-    };
-}