@promptctl/rich-js 0.18.0 → 0.19.0

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

@@ -0,0 +1,119 @@
+/**
+ * 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 type { RenderOptions } from "../core/protocol.js";
+import { type DrawnAt } from "./color-funcs.js";
+export { paletteFuncs } from "./palette-funcs.js";
+export { colorFuncs, readableOnFunc, type DrawnAt } 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?: () => DrawnAt): 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>;
+export interface RenderTemplateOptions extends Partial<RenderOptions> {
+    /**
+     * Defaults to 400 — large enough that downstream `splitLines` /
+     * `adjustLineLength` clipping decides actual width, matching the typical
+     * "render wide, fit on output" pipeline. The error line is fitted to it too,
+     * so only a caller that passes the width it draws at sees a cut error end in
+     * `…` rather than be cropped by whatever draws it.
+     */
+    maxWidth?: number;
+    /** The error line's style, a `Style.parse` spec (default `"red dim"`). */
+    errorStyle?: string;
+}
+/**
+ * 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[]` with the given render options — `maxWidth`,
+ *   `theme`, `onStyleError` and the rest — as a terminal unless they say not.
+ * - On a parse/evaluate failure, emits a single dim styled
+ *   `[error: <message>]` segment, one line fitted to `maxWidth`, the caller
+ *   can drop into their layout. No bespoke fallback wiring required at every
+ *   call site.
+ *
+ * Only compile, evaluate and flatten are inside the `try`: the error line reports a
+ * template that failed, nothing else. Whatever the render throws — a style
+ * error an `onStyleError` handler rethrew, or a fault in the render itself —
+ * leaves this function rather than being folded into an `[error: …]` line.
+ *
+ * [LAW:single-enforcer] One place owns "render a template to segments,
+ * degrade gracefully when the template fails" — 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.
+
+ */
+export declare function renderTemplate(engine: Engine<RichText>, source: string, scope?: unknown, options?: RenderTemplateOptions): Segment[];

package/dist/template-bindings/index.js

@@ -0,0 +1,162 @@
+/**
+ * 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[]` with the given render options — `maxWidth`,
+ *   `theme`, `onStyleError` and the rest — as a terminal unless they say not.
+ * - On a parse/evaluate failure, emits a single dim styled
+ *   `[error: <message>]` segment, one line fitted to `maxWidth`, the caller
+ *   can drop into their layout. No bespoke fallback wiring required at every
+ *   call site.
+ *
+ * Only compile, evaluate and flatten are inside the `try`: the error line reports a
+ * template that failed, nothing else. Whatever the render throws — a style
+ * error an `onStyleError` handler rethrew, or a fault in the render itself —
+ * leaves this function rather than being folded into an `[error: …]` line.
+ *
+ * [LAW:single-enforcer] One place owns "render a template to segments,
+ * degrade gracefully when the template fails" — 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.
+
+ */
+export function renderTemplate(engine, source, scope = {}, options) {
+    const { errorStyle, ...renderOptions } = options ?? {};
+    const maxWidth = renderOptions.maxWidth ?? 400;
+    // Flattening belongs to the template: a scope value the engine passes
+    // through unlifted fails here, and that is a template that failed.
+    let text;
+    try {
+        text = RichText.fromFragments(engine.compile(source)(scope));
+    }
+    catch (e) {
+        return [new Segment(errorLine(e, maxWidth), safeErrorStyle(errorStyle))];
+    }
+    return Array.from(text.render({ isTerminal: true, ...renderOptions, maxWidth }));
+}
+/**
+ * A caught error as the one line `renderTemplate` promises. The summary is the
+ * error's `message` — `String(e)` on an engine error appends a multi-line code
+ * frame — and even a `message` can carry the character it is complaining about
+ * (`bad escape sequence \⏎`). Any whitespace that is not a plain space — a line
+ * break, or a tab, whose stop depends on the column the line is set at and so
+ * cannot be measured here — folds, with the spaces around it, to one space.
+ *
+ * [LAW:one-source-of-truth] The line fits the same `maxWidth` the success path
+ * draws at, not a width of its own, and a cut ends in an ellipsis so it never
+ * reads as the whole message.
+ */
+function errorLine(e, maxWidth) {
+    const summary = (e instanceof Error ? e.message : String(e)).replace(/\s*[^\S ]\s*/g, " ");
+    return new RichText(`[error: ${summary}]`).truncate(maxWidth).plain;
+}
+// [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;
+    }
+}

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

@@ -0,0 +1,96 @@
+/**
+ * The palette-dependent template functions: `color`, and `ramp` whose stops
+ * are color references.
+ *
+ * ### Why `color` is the one name resolver
+ *
+ * This module used to register four kinds of thing: one function per
+ * identifier-safe palette variable (`{{ primary child }}`, `{{ accent child }}`,
+ * …), a general `palette "spec" child`, a `paletteOver "spec" "#bg" child` for
+ * specs needing a background, and an `auto "#bg" child` sugar. That surface had
+ * two defects worth recording, because both are easy to reintroduce.
+ *
+ * **The name family could not cover its own domain.** A themed palette carries
+ * ~150 variables; roughly 14 of them are legal Go-template identifiers. So the
+ * generated functions reached under a tenth of the palette, and the other nine
+ * tenths needed `palette "text-primary" child` — a *different expression shape*
+ * for the same intent. An author who learned `{{ primary x }}` and reasonably
+ * tried `{{ text_primary x }}` got a FuncNotFound. [LAW:composability] — the
+ * `filterByStatus`/`filterByOwner` shape: names cannot enumerate a domain, and
+ * the N+1 case always needs a form you have to learn separately.
+ *
+ * **Resolution and application were fused.** Every one of those functions
+ * consumed its color instantly into a styled fragment, so a color could never
+ * be held or passed. Composition therefore had to happen inside the spec
+ * *string* — hence the old `name-darken-N alpha%` grammar. See
+ * `color-funcs.ts` for the full argument; the short version is that a string
+ * grammar is function application with the function calls spelled as
+ * punctuation, and it grows a new production for every operation.
+ *
+ * What replaces all of it: `color "name-or-hex"` produces a color value, the
+ * functions in `color-funcs.ts` transform colors, and `fg`/`bg` in
+ * `style-funcs.ts` paint them. One shape, total over the palette, open to
+ * arbitrary composition. [LAW:one-type-per-behavior]
+ *
+ * ### Why `ramp` lives here and not with the color math
+ *
+ * `ramp` is the one function whose input is a *number*, and its stops are
+ * spelled as color references — `ramp .pct "step" 0 "panel" 50 "warning" 80
+ * "error"` — resolved through the same `resolveColorRef` that `color` crosses.
+ * Requiring `(color "panel")` around every stop would put the boilerplate
+ * back that this binding exists to remove, and an author who writes a hex
+ * literal loses nothing: the resolver is idempotent on hex. The arithmetic
+ * itself is `ColorRamp` in `themes/ramp.ts`, palette-free; only the
+ * reference resolution is here. [LAW:one-way-deps]
+ *
+ * ### Why a getter, not a palette
+ *
+ * `paletteFuncs` takes `() => Palette` rather than a `Palette`. A consumer
+ * whose theme can change at runtime (a live preview, a theme picker, a
+ * status-line that recolors on click) would otherwise be frozen to whichever
+ * palette happened to be current when the engine was constructed — and since
+ * templates are parsed once and evaluated many times, that freeze outlives
+ * every subsequent theme change while the *rest* of the consumer's colors move
+ * on. Two palettes, one render: [LAW:one-source-of-truth] violated by a
+ * captured reference.
+ *
+ * The getter costs nothing structurally. `FuncMap` entries are data in the
+ * engine and their bodies run at *evaluate* time, so reading the palette
+ * through a getter leaves parse-once/evaluate-many completely intact. What the
+ * getter must not change is *which functions exist* — and it cannot, because
+ * the two names here do not depend on the palette's contents. That was not
+ * true of the generated per-variable functions, which is the second reason
+ * they are gone.
+ */
+import type { FuncMap } from "@promptctl/go-template-js";
+import type { Palette } from "../themes/palette.js";
+/**
+ * Register `color "name-or-hex"` against a live palette.
+ *
+ * `color` resolves a palette variable name to its hex string — `#RRGGBB`, or
+ * `#00000000` for a theme's "no background", which `bg` paints as no
+ * background and the colour functions refuse — and passes
+ * an already-literal color through unchanged. That second half is not a
+ * convenience — it makes `color` **idempotent**, which is what lets consumers
+ * apply it unconditionally to any author-written color string without first
+ * asking whether it is a name or already a color. [LAW:dataflow-not-control-flow]
+ *
+ * An unknown name throws, carrying near-miss suggestions from the live
+ * palette. In a template that surfaces as an evaluation error at the exact
+ * call site, which is the signal an author (or an agent editing a config) needs
+ * to fix it. [LAW:no-silent-failure]
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine({
+ *   fromString: (s) => new RichText(s),
+ *   toString: (rt) => rt.plain,
+ *   funcs: {
+ *     ...richTextFuncs(),
+ *     ...colorFuncs(),
+ *     ...paletteFuncs(() => currentTheme.palette),
+ *   },
+ * });
+ * ```
+ */
+export declare function paletteFuncs(getPalette: () => Palette): FuncMap;

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

@@ -0,0 +1,145 @@
+/**
+ * The palette-dependent template functions: `color`, and `ramp` whose stops
+ * are color references.
+ *
+ * ### Why `color` is the one name resolver
+ *
+ * This module used to register four kinds of thing: one function per
+ * identifier-safe palette variable (`{{ primary child }}`, `{{ accent child }}`,
+ * …), a general `palette "spec" child`, a `paletteOver "spec" "#bg" child` for
+ * specs needing a background, and an `auto "#bg" child` sugar. That surface had
+ * two defects worth recording, because both are easy to reintroduce.
+ *
+ * **The name family could not cover its own domain.** A themed palette carries
+ * ~150 variables; roughly 14 of them are legal Go-template identifiers. So the
+ * generated functions reached under a tenth of the palette, and the other nine
+ * tenths needed `palette "text-primary" child` — a *different expression shape*
+ * for the same intent. An author who learned `{{ primary x }}` and reasonably
+ * tried `{{ text_primary x }}` got a FuncNotFound. [LAW:composability] — the
+ * `filterByStatus`/`filterByOwner` shape: names cannot enumerate a domain, and
+ * the N+1 case always needs a form you have to learn separately.
+ *
+ * **Resolution and application were fused.** Every one of those functions
+ * consumed its color instantly into a styled fragment, so a color could never
+ * be held or passed. Composition therefore had to happen inside the spec
+ * *string* — hence the old `name-darken-N alpha%` grammar. See
+ * `color-funcs.ts` for the full argument; the short version is that a string
+ * grammar is function application with the function calls spelled as
+ * punctuation, and it grows a new production for every operation.
+ *
+ * What replaces all of it: `color "name-or-hex"` produces a color value, the
+ * functions in `color-funcs.ts` transform colors, and `fg`/`bg` in
+ * `style-funcs.ts` paint them. One shape, total over the palette, open to
+ * arbitrary composition. [LAW:one-type-per-behavior]
+ *
+ * ### Why `ramp` lives here and not with the color math
+ *
+ * `ramp` is the one function whose input is a *number*, and its stops are
+ * spelled as color references — `ramp .pct "step" 0 "panel" 50 "warning" 80
+ * "error"` — resolved through the same `resolveColorRef` that `color` crosses.
+ * Requiring `(color "panel")` around every stop would put the boilerplate
+ * back that this binding exists to remove, and an author who writes a hex
+ * literal loses nothing: the resolver is idempotent on hex. The arithmetic
+ * itself is `ColorRamp` in `themes/ramp.ts`, palette-free; only the
+ * reference resolution is here. [LAW:one-way-deps]
+ *
+ * ### Why a getter, not a palette
+ *
+ * `paletteFuncs` takes `() => Palette` rather than a `Palette`. A consumer
+ * whose theme can change at runtime (a live preview, a theme picker, a
+ * status-line that recolors on click) would otherwise be frozen to whichever
+ * palette happened to be current when the engine was constructed — and since
+ * templates are parsed once and evaluated many times, that freeze outlives
+ * every subsequent theme change while the *rest* of the consumer's colors move
+ * on. Two palettes, one render: [LAW:one-source-of-truth] violated by a
+ * captured reference.
+ *
+ * The getter costs nothing structurally. `FuncMap` entries are data in the
+ * engine and their bodies run at *evaluate* time, so reading the palette
+ * through a getter leaves parse-once/evaluate-many completely intact. What the
+ * getter must not change is *which functions exist* — and it cannot, because
+ * the two names here do not depend on the palette's contents. That was not
+ * true of the generated per-variable functions, which is the second reason
+ * they are gone.
+ */
+import { resolveColorRef } from "../themes/colorRef.js";
+import { parseEase } from "../core/easing.js";
+import { ColorRamp } from "../themes/ramp.js";
+import { computable } from "./color-funcs.js";
+/**
+ * The `(position, color-ref)` pairs a `ramp` call's tail spells, as stops.
+ *
+ * The engine's `alternating` gate has already typed every even slot as a
+ * float and every odd slot as a string; what it cannot see is the *pairing*
+ * — a trailing position with no color — nor that the string is a color
+ * reference. Both are settled here, once, and `ColorRamp` receives resolved
+ * stops it never re-checks. [LAW:parse-dont-validate]
+ *
+ * Each reference resolves against the palette of *this* evaluation, so a
+ * ramp over palette names follows the theme exactly as `color` does.
+ */
+function colorStops(tail, palette) {
+    if (tail.length % 2 !== 0) {
+        throw new RangeError(`ramp's last stop (position ${String(tail[tail.length - 1])}) has no color — ` +
+            `stops are <position> <color> pairs`);
+    }
+    const stops = [];
+    for (let i = 0; i < tail.length; i += 2) {
+        stops.push({
+            at: tail[i],
+            color: computable(resolveColorRef(palette, tail[i + 1]), "ramp", JSON.stringify(tail[i + 1])),
+        });
+    }
+    return stops;
+}
+/**
+ * Register `color "name-or-hex"` against a live palette.
+ *
+ * `color` resolves a palette variable name to its hex string — `#RRGGBB`, or
+ * `#00000000` for a theme's "no background", which `bg` paints as no
+ * background and the colour functions refuse — and passes
+ * an already-literal color through unchanged. That second half is not a
+ * convenience — it makes `color` **idempotent**, which is what lets consumers
+ * apply it unconditionally to any author-written color string without first
+ * asking whether it is a name or already a color. [LAW:dataflow-not-control-flow]
+ *
+ * An unknown name throws, carrying near-miss suggestions from the live
+ * palette. In a template that surfaces as an evaluation error at the exact
+ * call site, which is the signal an author (or an agent editing a config) needs
+ * to fix it. [LAW:no-silent-failure]
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine({
+ *   fromString: (s) => new RichText(s),
+ *   toString: (rt) => rt.plain,
+ *   funcs: {
+ *     ...richTextFuncs(),
+ *     ...colorFuncs(),
+ *     ...paletteFuncs(() => currentTheme.palette),
+ *   },
+ * });
+ * ```
+ */
+export function paletteFuncs(getPalette) {
+    const colorFunc = {
+        fn: ((ref) => resolveColorRef(getPalette(), ref).hex),
+        argTypes: ["string"],
+        arity: { kind: "exact" },
+        returnType: "string",
+    };
+    // `ramp <value> <ease> <position> <color> …` — the argument list is one
+    // float/string cycle end to end (value, ease, then each stop's position
+    // and color), so the engine's `alternating` gate types every slot; the
+    // pairing and the references are parsed in `colorStops`. Its minimum is the
+    // value, the ease, and one stop, so the gate refuses a stopless call.
+    // [LAW:types-are-the-program]
+    const rampFunc = {
+        fn: ((value, ease, ...tail) => new ColorRamp(parseEase(ease), colorStops(tail, getPalette())).at(value)
+            .hex),
+        argTypes: ["float", "string"],
+        arity: { kind: "alternating", minimum: 4 },
+        returnType: "string",
+    };
+    return { color: colorFunc, ramp: rampFunc };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Style-function registrations for the rich-js template binding.
+ *
+ * [LAW:one-source-of-truth] The function inventory below mirrors the
+ * string-syntax style vocabulary documented in `docs/style.md` — the two
+ * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * aliases, and the hyperlink. Each registration is a templating-time analogue
+ * of a piece of `Style.parse`, so a template fragment composed by these
+ * functions round-trips through `Style` without semantic drift.
+ *
+ * [LAW:dataflow-not-control-flow] Every function follows the same
+ * shape: child `RichText` in, `RichText` out. The styling difference
+ * lives in a captured `Style` value (or constructor closure), not in
+ * branches inside a single dispatch. That is why this file is mostly
+ * factories — the data (the colour, the attribute name) is the
+ * variability; the operation is fixed.
+ */
+import type { FuncMap } from "@promptctl/go-template-js";
+/**
+ * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * attributes (canonical names, short aliases, and `not_*` negations), the
+ * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
+ *
+ * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * [LAW:one-way-deps] — nothing here imports a palette.
+ */
+export declare function richTextStyleFuncs(): FuncMap;