@promptctl/rich-js 0.18.0 → 0.18.1

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

@@ -0,0 +1,87 @@
+/**
+ * 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

@@ -0,0 +1,217 @@
+/**
+ * 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);
+}
+// [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));
+/**
+ * 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(),
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 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 { 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.
+ */
+export declare function applyStyleToFragment(child: unknown, style: Style): RichText;

package/dist/template-bindings/helpers.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { Style, StyleSyntaxError } 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.
+ */
+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 = baseStyleOf(child.style).add(style);
+    return result;
+}
+/**
+ * A fragment's base style as a `Style`. A string must parse as a definition: a
+ * name resolves only against the theme of the render that draws it, and a
+ * template runs before any render exists.
+ */
+function baseStyleOf(style) {
+    if (style instanceof Style)
+        return style;
+    try {
+        return Style.parse(style);
+    }
+    catch (err) {
+        if (!(err instanceof StyleSyntaxError))
+            throw err;
+        throw new TypeError(`template function cannot style a fragment whose base style "${style}" is not a style definition: a style name resolves only against the theme of a render`, { cause: err });
+    }
+}

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

@@ -0,0 +1,107 @@
+/**
+ * rich-js template bindings — public entry point.
+ *
+ * [LAW:one-source-of-truth] This module is the public entry point for
+ * rich-js's styling vocabulary as `@promptctl/go-template-js` template
+ * functions. The split between the two exported registrations is exactly the
+ * split between what needs a theme and what does not:
+ *
+ * - `richTextFuncs()` — the colour sinks (`fg`/`bg`), the palette-free colour
+ *   math (`darken`, `mix`, `contrastOn`, the OKLCH axes …), text attributes,
+ *   and `link`. Needs no configuration; safe to register unconditionally. A
+ *   consumer with no theme system still gets the complete colour vocabulary by
+ *   feeding it hex literals.
+ * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
+ *   resolve a palette name. This is the *only* registration that knows a
+ *   palette exists, which is why it is the only one that takes an argument.
+ *   [LAW:one-way-deps]
+ *
+ * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
+ * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
+ * and merge it into their own engine config.
+ *
+ * Colours compose by nesting, like every other function:
+ * `{{ fg (darken (color "primary") 2) (bold "x") }}`. There is no second
+ * markup grammar and no colour-spec mini-language — the template *is* the
+ * composition mechanism.
+ *
+ * Fragment type: `RichText`. Chosen because it is the library's primary
+ * text type (implements `Renderable` + `Measurable`), composes via
+ * `append`, and flows directly into the existing render pipeline with no
+ * adapter. Top-level template expressions emit as `RichText[]` — natural
+ * for cases where a single template produces multiple independently
+ * addressable fragments (e.g. multiple top-level `link` calls, each
+ * carrying its own URL).
+ */
+import { type Engine, type FuncMap } from "@promptctl/go-template-js";
+import { RichText } from "../core/text.js";
+import { Segment } from "../core/segment.js";
+import { ColorDepth } from "../core/color.js";
+export { paletteFuncs } from "./palette-funcs.js";
+export { colorFuncs, readableOnFunc } from "./color-funcs.js";
+/**
+ * Funcs registered by the rich-js binding — the colour sinks, the palette-free
+ * colour math, text attributes, and the `link` cell-splitter. Nothing here
+ * needs a theme; the two that do (`color`, `ramp`) ship separately via
+ * `paletteFuncs(getPalette)`, merged consumer-side. `drawnAt` is forwarded to
+ * `colorFuncs` — the depth `readableOn` measures at, truecolor when omitted.
+ *
+ * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
+ * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output
+ * types are carried as runtime `argTypes` on each `TemplateFunc`. The map
+ * therefore *type-checks* against any `EngineConfig<T>.funcs`, but the
+ * functions returned here are only *runtime-compatible* with
+ * `Engine<RichText>`: each style function returns a `RichText` and
+ * requires its lifted child to be a `RichText` (enforced by an
+ * `instanceof` check that throws on misuse). Consumers merging this map
+ * into a wider engine must keep `T = RichText`; merging into an engine
+ * whose `T` is something else will compile but fail at evaluation time.
+ */
+export declare function richTextFuncs(drawnAt?: () => ColorDepth): FuncMap;
+/**
+ * Construct an `Engine<RichText>` with the rich-js style-function set
+ * registered. Consumers that already manage their own engine should call
+ * `richTextFuncs()` and merge the result into their own `createEngine`
+ * configuration; consumers that just want rich-js styling can use this
+ * factory directly.
+ *
+ * `fromString` lifts text literals into `RichText`. `toString` flattens a
+ * `RichText` to its plain text — the engine's no-silent-flatten guard uses
+ * this only for `printf "%s"` / `"%q"` and `print*` slots, where ANSI is
+ * not desired anyway.
+ */
+export declare function createRichTextEngine(): Engine<RichText>;
+/**
+ * Compile a template source against `engine` and render the result to a
+ * flat `Segment[]`. The 90%-case convenience over chaining `engine.compile`,
+ * `RichText.fromFragments`, and `.render` by hand:
+ *
+ * - Runs `engine.compile(source)(scope)` to get the engine's `RichText[]`.
+ * - Flattens that fragment list into a single styled `RichText` via
+ *   `RichText.fromFragments` so every fragment's wrapping style survives.
+ * - Renders to a `Segment[]` at the requested `maxWidth`.
+ * - Wraps the whole flow in a try/catch — on parse/evaluate failure,
+ *   emits a single dim styled `[error: <message>]` segment the caller can
+ *   drop into their layout. No bespoke fallback wiring required at every
+ *   call site.
+ *
+ * [LAW:single-enforcer] One place owns "render a template to segments,
+ * degrade gracefully on errors" — every consumer that wants this exact
+ * shape reads from here rather than re-implementing the same try/catch +
+ * error-formatting glue.
+ *
+ * For the 10% — custom error UX, intermediate access to the `RichText`,
+ * pre-compiled templates re-used many times — call the engine directly
+ * and use `RichText.fromFragments` to flatten. This helper is sugar for
+ * the live-render case (e.g. a preview pane), not a replacement for the
+ * compile-once-evaluate-many pattern.
+ *
+ * @param maxWidth defaults to 400 — large enough that downstream `splitLines`
+ * / `adjustLineLength` clipping decides actual width, matching the typical
+ * "render wide, fit on output" pipeline.
+ * @param errorStyle is a `Style.parse` spec (default `"red dim"`).
+ */
+export declare function renderTemplate(engine: Engine<RichText>, source: string, scope?: unknown, options?: {
+    maxWidth?: number;
+    errorStyle?: string;
+}): Segment[];

package/dist/template-bindings/index.js

@@ -0,0 +1,146 @@
+/**
+ * rich-js template bindings — public entry point.
+ *
+ * [LAW:one-source-of-truth] This module is the public entry point for
+ * rich-js's styling vocabulary as `@promptctl/go-template-js` template
+ * functions. The split between the two exported registrations is exactly the
+ * split between what needs a theme and what does not:
+ *
+ * - `richTextFuncs()` — the colour sinks (`fg`/`bg`), the palette-free colour
+ *   math (`darken`, `mix`, `contrastOn`, the OKLCH axes …), text attributes,
+ *   and `link`. Needs no configuration; safe to register unconditionally. A
+ *   consumer with no theme system still gets the complete colour vocabulary by
+ *   feeding it hex literals.
+ * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
+ *   resolve a palette name. This is the *only* registration that knows a
+ *   palette exists, which is why it is the only one that takes an argument.
+ *   [LAW:one-way-deps]
+ *
+ * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
+ * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
+ * and merge it into their own engine config.
+ *
+ * Colours compose by nesting, like every other function:
+ * `{{ fg (darken (color "primary") 2) (bold "x") }}`. There is no second
+ * markup grammar and no colour-spec mini-language — the template *is* the
+ * composition mechanism.
+ *
+ * Fragment type: `RichText`. Chosen because it is the library's primary
+ * text type (implements `Renderable` + `Measurable`), composes via
+ * `append`, and flows directly into the existing render pipeline with no
+ * adapter. Top-level template expressions emit as `RichText[]` — natural
+ * for cases where a single template produces multiple independently
+ * addressable fragments (e.g. multiple top-level `link` calls, each
+ * carrying its own URL).
+ */
+import { createEngine } from "@promptctl/go-template-js";
+import { RichText } from "../core/text.js";
+import { Style } from "../core/style.js";
+import { Segment } from "../core/segment.js";
+import { richTextStyleFuncs } from "./style-funcs.js";
+import { colorFuncs } from "./color-funcs.js";
+export { paletteFuncs } from "./palette-funcs.js";
+export { colorFuncs, readableOnFunc } from "./color-funcs.js";
+/**
+ * Funcs registered by the rich-js binding — the colour sinks, the palette-free
+ * colour math, text attributes, and the `link` cell-splitter. Nothing here
+ * needs a theme; the two that do (`color`, `ramp`) ship separately via
+ * `paletteFuncs(getPalette)`, merged consumer-side. `drawnAt` is forwarded to
+ * `colorFuncs` — the depth `readableOn` measures at, truecolor when omitted.
+ *
+ * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
+ * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output
+ * types are carried as runtime `argTypes` on each `TemplateFunc`. The map
+ * therefore *type-checks* against any `EngineConfig<T>.funcs`, but the
+ * functions returned here are only *runtime-compatible* with
+ * `Engine<RichText>`: each style function returns a `RichText` and
+ * requires its lifted child to be a `RichText` (enforced by an
+ * `instanceof` check that throws on misuse). Consumers merging this map
+ * into a wider engine must keep `T = RichText`; merging into an engine
+ * whose `T` is something else will compile but fail at evaluation time.
+ */
+// [LAW:one-source-of-truth] The truecolor default lives on `colorFuncs` alone;
+// an omitted `drawnAt` is forwarded as omitted.
+export function richTextFuncs(drawnAt) {
+    return { ...richTextStyleFuncs(), ...colorFuncs(drawnAt) };
+}
+/**
+ * Construct an `Engine<RichText>` with the rich-js style-function set
+ * registered. Consumers that already manage their own engine should call
+ * `richTextFuncs()` and merge the result into their own `createEngine`
+ * configuration; consumers that just want rich-js styling can use this
+ * factory directly.
+ *
+ * `fromString` lifts text literals into `RichText`. `toString` flattens a
+ * `RichText` to its plain text — the engine's no-silent-flatten guard uses
+ * this only for `printf "%s"` / `"%q"` and `print*` slots, where ANSI is
+ * not desired anyway.
+ */
+export function createRichTextEngine() {
+    return createEngine({
+        fromString: (s) => new RichText(s),
+        toString: (rt) => rt.plain,
+        funcs: richTextFuncs(),
+    });
+}
+/**
+ * Compile a template source against `engine` and render the result to a
+ * flat `Segment[]`. The 90%-case convenience over chaining `engine.compile`,
+ * `RichText.fromFragments`, and `.render` by hand:
+ *
+ * - Runs `engine.compile(source)(scope)` to get the engine's `RichText[]`.
+ * - Flattens that fragment list into a single styled `RichText` via
+ *   `RichText.fromFragments` so every fragment's wrapping style survives.
+ * - Renders to a `Segment[]` at the requested `maxWidth`.
+ * - Wraps the whole flow in a try/catch — on parse/evaluate failure,
+ *   emits a single dim styled `[error: <message>]` segment the caller can
+ *   drop into their layout. No bespoke fallback wiring required at every
+ *   call site.
+ *
+ * [LAW:single-enforcer] One place owns "render a template to segments,
+ * degrade gracefully on errors" — every consumer that wants this exact
+ * shape reads from here rather than re-implementing the same try/catch +
+ * error-formatting glue.
+ *
+ * For the 10% — custom error UX, intermediate access to the `RichText`,
+ * pre-compiled templates re-used many times — call the engine directly
+ * and use `RichText.fromFragments` to flatten. This helper is sugar for
+ * the live-render case (e.g. a preview pane), not a replacement for the
+ * compile-once-evaluate-many pattern.
+ *
+ * @param maxWidth defaults to 400 — large enough that downstream `splitLines`
+ * / `adjustLineLength` clipping decides actual width, matching the typical
+ * "render wide, fit on output" pipeline.
+ * @param errorStyle is a `Style.parse` spec (default `"red dim"`).
+ */
+export function renderTemplate(engine, source, scope = {}, options) {
+    try {
+        const frags = engine.compile(source)(scope);
+        const rt = RichText.fromFragments(frags);
+        return Array.from(rt.render({
+            maxWidth: options?.maxWidth ?? 400,
+            isTerminal: true,
+        }));
+    }
+    catch (e) {
+        // An engine error's `message` is its one-line summary; `String(e)` adds a
+        // multi-line code frame, which would break this single segment across lines.
+        const summary = e instanceof Error ? e.message : String(e);
+        return [new Segment(`[error: ${summary.slice(0, 80)}]`, safeErrorStyle(options?.errorStyle))];
+    }
+}
+// [LAW:single-enforcer] The error-path Style must not itself throw, or
+// the whole "degrade gracefully" promise of renderTemplate is broken. A
+// bogus user-supplied `errorStyle` spec falls back to a hard-coded safe
+// Style — never propagates the parse failure to the caller.
+const FALLBACK_ERROR_STYLE = new Style({ color: "red", dim: true });
+function safeErrorStyle(spec) {
+    if (spec === undefined)
+        return FALLBACK_ERROR_STYLE;
+    try {
+        return Style.parse(spec);
+    }
+    catch {
+        return FALLBACK_ERROR_STYLE;
+    }
+}