@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/viewport.js

@@ -0,0 +1,196 @@
+/**
+ * Viewport — a fixed number of rows onto a taller renderable, scrolled by an
+ * offset that cannot leave the content.
+ *
+ * Its rows, under the `Height` contract in `../core/protocol.ts`: the region's
+ * when it is given one; otherwise its own configured rows, or the content's
+ * full length when it has none, capped by any ceiling. It renders its content
+ * with no height, because the content's natural length is the scroll extent,
+ * and pads or crops what comes back to its rows — its rows are its own height,
+ * not a region someone else will shape.
+ *
+ * Its width is the width it is given, in both directions: each row is cropped
+ * or padded to it, so content that ignores its width cannot spill past the
+ * viewport's edge and the scrollbar, drawn in a gutter at that edge, lines up
+ * down every row. [LAW:dataflow-not-control-flow] A viewport with no scrollbar
+ * has a gutter zero cells wide, and every row takes the same path either way.
+ *
+ * [LAW:no-ambient-temporal-coupling] Neither half of what an offset is clamped
+ * against exists before a render: the rows come from the budget the render is
+ * handed, and the content's length from rendering it at the width it is handed.
+ * So `scrollTo`, `scrollBy` and `ensureVisible` do not move anything when they
+ * are called. Each queues a move, and the next render resolves the queue in
+ * call order, clamping after every move, against the rows and length that
+ * render found. Calling an operation before the first render, or three of them
+ * between two renders, is the same code path as calling one.
+ *
+ * Every cell of its rows, gutter included, is stamped as its own
+ * (`Segment.anchorLines`), around whatever anchors its content drew. So the
+ * composed frame names the viewport under any of its cells however deep it is
+ * nested, and a cell of a widget inside it names both: that is how the wheel
+ * finds the viewport to scroll. `canScrollBy` is how it passes over one that
+ * cannot move that way, to the viewport around it.
+ */
+import { Segment } from "../core/segment.js";
+import { Measurement } from "../core/measure.js";
+import { cellCount, cellLen } from "../core/cells.js";
+import { NULL_STYLE } from "../core/style.js";
+import { drawable, fitHeight, getStyle, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+/** A heavy line for the thumb on a light line for the track. */
+export const SCROLLBAR = {
+    thumb: { glyph: "┃", style: "scrollbar.thumb" },
+    track: { glyph: "│", style: "scrollbar.track" },
+};
+/** The absence of a scrollbar, as a gutter zero cells wide. */
+const NO_SCROLLBAR = {
+    thumb: { glyph: "", style: NULL_STYLE },
+    track: { glyph: "", style: NULL_STYLE },
+};
+export class Viewport {
+    /**
+     * What the viewport shows. Replace it to show new content from the same
+     * scroll position — a view rebuilt every frame keeps one `Viewport`.
+     */
+    content;
+    rows;
+    scrollbar;
+    _offset = 0;
+    // Nothing rendered, nothing shown: no move can take until the first render.
+    _extent = { rows: 0, lines: 0 };
+    _moves = [];
+    constructor(content, options = {}) {
+        this.content = content;
+        this.rows = options.rows;
+        this.scrollbar = options.scrollbar ?? NO_SCROLLBAR;
+    }
+    /**
+     * The first content line the last render showed. A move requested since is
+     * not reflected until the next render resolves it.
+     */
+    get offset() {
+        return this._offset;
+    }
+    /** Scroll so `line` is the first line shown. */
+    scrollTo(line) {
+        this._moves.push(() => line);
+    }
+    /** Scroll by `lines`: down when positive, up when negative. */
+    scrollBy(lines) {
+        this._moves.push((offset) => offset + lines);
+    }
+    /**
+     * Whether `scrollBy(lines)` would move the viewport from where the moves
+     * queued so far leave it, against the rows and length the last render
+     * found.
+     */
+    canScrollBy(lines) {
+        const offset = this.resolve(this._extent);
+        return clampOffset(offset + lines, this._extent) !== offset;
+    }
+    /**
+     * Scroll the least distance that shows lines `start` up to but not
+     * including `end` — lines of the content as it renders at the viewport's
+     * width, so an item that wraps spans more than one. A range already in view does not move; one taller than
+     * the viewport shows its first line at the top.
+     */
+    ensureVisible(start, end) {
+        this._moves.push((offset, { rows }) => Math.min(start, Math.max(offset, end - rows)));
+    }
+    /**
+     * The width its content renders at, out of `width`: what the scrollbar's
+     * gutter leaves. Lines handed to `ensureVisible` are lines at this width.
+     */
+    contentWidth(width) {
+        return cellCount(width - gutterWidth(this.scrollbar));
+    }
+    *render(rawOptions) {
+        const { height, ...options } = withBoundedWidth(rawOptions, this);
+        const gutter = gutterWidth(this.scrollbar);
+        const contentWidth = this.contentWidth(options.maxWidth);
+        const lines = Segment.splitLines(this.content.render({ ...options, maxWidth: contentWidth }));
+        const extent = { rows: viewRows(height, this.rows, lines.length), lines: lines.length };
+        this._extent = extent;
+        this._offset = this.resolve(extent);
+        this._moves = [];
+        const shown = fitHeight(lines.slice(this._offset, this._offset + extent.rows), { rows: extent.rows, exact: true });
+        // [LAW:no-ambient-temporal-coupling] The thumb is drawn from the offset
+        // this render just resolved, not from `offset` as it stood before it.
+        const thumb = thumbRows(extent, this._offset);
+        // The content's cells and the gutter's drawn cells sum to the offer: a
+        // gutter wider than the whole offer is drawn cropped to it.
+        const drawn = Math.min(gutter, options.maxWidth);
+        // The style reaches the padding too, so a glyph narrower than the gutter
+        // still fills its cell with its part's background.
+        const cell = ({ glyph, style }) => {
+            const resolved = getStyle(options, style);
+            return Segment.adjustLineLength([new Segment(glyph, resolved)], drawn, resolved);
+        };
+        // The gutter keeps the chosen scrollbar's width, so an ASCII stand-in
+        // padded into it leaves the content where `contentWidth` said it would be.
+        const bar = drawable(options, this.scrollbar, asciiScrollbar(this.scrollbar), scrollbarGlyphs);
+        const thumbCell = cell(bar.thumb);
+        const trackCell = cell(bar.track);
+        const rows = shown.map((line, row) => [
+            ...Segment.adjustLineLength(line, contentWidth),
+            ...(row >= thumb.start && row < thumb.end ? thumbCell : trackCell),
+        ]);
+        for (const line of Segment.anchorLines(rows, this)) {
+            yield* line;
+            yield Segment.line();
+        }
+    }
+    /**
+     * [LAW:one-source-of-truth] Where the queued moves leave the offset against
+     * `extent`: what a render commits, and what `canScrollBy` asks from.
+     * [LAW:dataflow-not-control-flow] The offset is re-clamped with or without
+     * queued moves: content that shrank since the last render pulls it back.
+     */
+    resolve(extent) {
+        return this._moves.reduce((offset, move) => clampOffset(move(offset, extent), extent), clampOffset(this._offset, extent));
+    }
+    measure(rawOptions) {
+        // Its width is its content's and its gutter's. `withCellWidth` and not
+        // `withBoundedWidth`: the bounded parse asks this very method for the
+        // natural width.
+        const options = withCellWidth(rawOptions);
+        const gutter = gutterWidth(this.scrollbar);
+        const inner = { ...options, maxWidth: this.contentWidth(options.maxWidth) };
+        const content = Measurement.get(inner, this.content);
+        return new Measurement(content.minimum + gutter, content.maximum + gutter).withMaximum(options.maxWidth);
+    }
+}
+const scrollbarGlyphs = ({ thumb, track }) => thumb.glyph + track.glyph;
+/** `scrollbar` in its own styles, drawn in ASCII. */
+function asciiScrollbar({ thumb, track }) {
+    return { thumb: { ...thumb, glyph: "#" }, track: { ...track, glyph: "|" } };
+}
+/** The cells a scrollbar's gutter takes from the content: its wider glyph. */
+function gutterWidth({ thumb, track }) {
+    return Math.max(cellLen(thumb.glyph), cellLen(track.glyph));
+}
+/**
+ * The rows of the track the thumb covers, from `start` up to but not including
+ * `end`: its length is the share of the content in view, and its position the
+ * share of the scroll travelled. Content that fits fills the track.
+ *
+ * An end of the track means an end of the content. Rounded alone, the position
+ * reached the bottom while lines were still hidden below — at 10 rows of 20
+ * lines, offset 9 rounds onto the last position. So an offset short of an end
+ * is held one row off it, wherever the track has a row between its ends.
+ */
+function thumbRows({ rows, lines }, offset) {
+    const size = Math.min(rows, Math.max(1, Math.round((rows * rows) / Math.max(lines, rows, 1))));
+    const travel = rows - size;
+    const last = Math.max(1, lines - rows);
+    const proportional = Math.round((offset * travel) / last);
+    const start = Math.max(Math.min(proportional, travel - Math.min(last - offset, 1)), Math.min(offset, 1, travel));
+    return { start, end: start + size };
+}
+/** The rows a viewport shows, from its budget, its own configured rows, and its content's length. */
+function viewRows(height, rows, lines) {
+    return regionRows(height) ?? cellCount(Math.min(rows ?? lines, height?.rows ?? Infinity));
+}
+/** An offset held to the lines that exist: never above the first, never past the last full view. */
+function clampOffset(offset, { rows, lines }) {
+    return cellCount(Math.min(offset, lines - rows));
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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` (or `#RRGGBBAA`), 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, type ColorRgba, type TerminalTheme } from "../core/color.js";
+/**
+ * A colour the colour functions can compute with. A fully transparent one — a
+ * theme's "no background", `#00000000` — has no colour of its own: what shows
+ * through it is whatever surface it lands on, which a template cannot know.
+ * Darkening, mixing or contrasting it would answer for a surface nobody named,
+ * so it is refused here, for every colour function and every `ramp` stop.
+ * [LAW:single-enforcer]
+ */
+export declare function computable(colour: ColorRgba, func: string, written: string): ColorRgba;
+/**
+ * Where `readableOn`'s text will be drawn: the depth the output is encoded at,
+ * and the terminal that draws it when that is known. At sixteen colours a
+ * terminal paints each slot in its own theme's colour, so the floor is measured
+ * in `terminal`'s sixteen; without one, in the VGA defaults (the Windows
+ * console's at `WINDOWS`). Both are facts about the one place the text lands,
+ * so they arrive together.
+ */
+export interface DrawnAt {
+    readonly depth: ColorDepth;
+    readonly terminal?: TerminalTheme;
+}
+/**
+ * The `readableOn` binding, measuring where `drawnAt` says the text lands when
+ * it is evaluated — a consumer that renders to a per-call destination
+ * registers its own.
+ */
+export declare const readableOnFunc: (drawnAt: () => DrawnAt) => 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 where the text will be drawn — the depth, and the terminal
+ *   when known — read on every `readableOn` evaluation so a host that learns
+ *   its destination per render passes one getter; defaults to truecolor.
+ */
+export declare function colorFuncs(drawnAt?: () => DrawnAt): FuncMap;

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

@@ -0,0 +1,243 @@
+/**
+ * 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` (or `#RRGGBBAA`), 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, ColorParseError, parseHexColor } from "../core/color.js";
+import { Oklch, IDENTITY } from "../core/oklch.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. What it parses
+ * must then be a colour these functions can compute with (`computable`).
+ * [LAW:no-silent-failure]
+ */
+function asColor(value, func) {
+    let colour;
+    try {
+        colour = parseHexColor(value.trim());
+    }
+    catch (cause) {
+        if (!(cause instanceof ColorParseError))
+            throw cause;
+        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)}) …`, { cause });
+    }
+    return computable(colour, func, JSON.stringify(value));
+}
+/**
+ * A colour the colour functions can compute with. A fully transparent one — a
+ * theme's "no background", `#00000000` — has no colour of its own: what shows
+ * through it is whatever surface it lands on, which a template cannot know.
+ * Darkening, mixing or contrasting it would answer for a surface nobody named,
+ * so it is refused here, for every colour function and every `ramp` stop.
+ * [LAW:single-enforcer]
+ */
+export function computable(colour, func, written) {
+    if (colour.alpha === 0) {
+        throw new RangeError(`${func} got ${written}, which is fully transparent: it draws no colour of its own, ` +
+            `so there is nothing to compute with — use the colour of the surface it sits on, e.g. (color "background")`);
+    }
+    return colour;
+}
+// [LAW:single-enforcer] Every colour function is fixed-arity, so the engine's
+// arity gate refuses a missing or surplus argument before the body runs.
+function colorFunc(argTypes, fn) {
+    return { fn, argTypes, arity: { kind: "exact" }, returnType: "string" };
+}
+/**
+ * The gate every *numeric* argument crosses, with an optional inclusive range.
+ *
+ * [LAW:single-enforcer] One check for every `"float"` slot. An `"int"` slot is
+ * a safe integer by the engine's gate and needs none, but a `"float"` slot admits
+ * NaN and Infinity (legitimate IEEE-754 values), which would otherwise surface
+ * as `ColorRgba.red must be an integer in [0, 255]; got NaN` — loud, but
+ * pointing at a channel the author never wrote. [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}`);
+    }
+    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"), levels).hex));
+const lightenFunc = colorFunc(["string", "int"], ((hex, levels) => darken(asColor(hex, "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));
+const TRUECOLOR = { depth: ColorDepth.TRUECOLOR };
+/**
+ * The `readableOn` binding, measuring where `drawnAt` says the text lands when
+ * it is evaluated — a consumer that renders to a per-call destination
+ * registers its own.
+ */
+export const readableOnFunc = (drawnAt) => colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => {
+    const { depth, terminal } = drawnAt();
+    return ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE), depth, undefined, terminal).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 where the text will be drawn — the depth, and the terminal
+ *   when known — read on every `readableOn` evaluation so a host that learns
+ *   its destination per render passes one getter; defaults to truecolor.
+ */
+export function colorFuncs(drawnAt = () => TRUECOLOR) {
+    return {
+        darken: darkenFunc,
+        lighten: lightenFunc,
+        mix: mixFunc,
+        contrastOn: contrastOnFunc,
+        readableOn: readableOnFunc(drawnAt),
+        ...oklchAxisFuncs(),
+    };
+}

package/dist/template-bindings/helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared internal helpers for the rich-js template binding layer.
+ *
+ * [LAW:one-source-of-truth] `applyStyleToFragment` is the single implementation
+ * of "apply a Style to an existing RichText fragment." Both the style-function
+ * registrations and the palette-function registrations use this same operation;
+ * keeping one copy prevents the two from drifting.
+ */
+import { type Style } from "../core/style.js";
+import { RichText } from "../core/text.js";
+/**
+ * Apply a style on top of an already-styled RichText fragment.
+ *
+ * [LAW:single-enforcer] Type validation lives here; callers trust the result.
+ * The `"liftable"` arg type lifts string literals to `RichText` via the
+ * engine's `fromString` before the body runs, so `child` is always a
+ * `RichText` by the time this runs. The instanceof check exists because
+ * `"liftable"` admits any non-primitive — the engine cannot prove the object
+ * is the binding's own `T`. Misuse (`{{ red someMap }}`) fails loudly here
+ * rather than producing a malformed fragment.
+ *
+ * Conflict resolution: `Style.add` — the outer (newly applied) style wins. A
+ * base style that is a name is layered under, not resolved: a template runs
+ * before the render whose theme says what the name stands for.
+ */
+export declare function applyStyleToFragment(child: unknown, style: Style): RichText;

package/dist/template-bindings/helpers.js

@@ -0,0 +1,33 @@
+/**
+ * Shared internal helpers for the rich-js template binding layer.
+ *
+ * [LAW:one-source-of-truth] `applyStyleToFragment` is the single implementation
+ * of "apply a Style to an existing RichText fragment." Both the style-function
+ * registrations and the palette-function registrations use this same operation;
+ * keeping one copy prevents the two from drifting.
+ */
+import { layerStyle } from "../core/style.js";
+import { RichText } from "../core/text.js";
+/**
+ * Apply a style on top of an already-styled RichText fragment.
+ *
+ * [LAW:single-enforcer] Type validation lives here; callers trust the result.
+ * The `"liftable"` arg type lifts string literals to `RichText` via the
+ * engine's `fromString` before the body runs, so `child` is always a
+ * `RichText` by the time this runs. The instanceof check exists because
+ * `"liftable"` admits any non-primitive — the engine cannot prove the object
+ * is the binding's own `T`. Misuse (`{{ red someMap }}`) fails loudly here
+ * rather than producing a malformed fragment.
+ *
+ * Conflict resolution: `Style.add` — the outer (newly applied) style wins. A
+ * base style that is a name is layered under, not resolved: a template runs
+ * before the render whose theme says what the name stands for.
+ */
+export function applyStyleToFragment(child, style) {
+    if (!(child instanceof RichText)) {
+        throw new TypeError(`template function expected a RichText fragment, got ${typeof child === "object" ? Object.prototype.toString.call(child) : typeof child}`);
+    }
+    const result = child.copy();
+    result.style = layerStyle(child.style, style);
+    return result;
+}