@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/viewport.js

@@ -35,7 +35,7 @@ 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, isMeasurable, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.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" },
@@ -58,6 +58,8 @@ export class Viewport {
     // Nothing rendered, nothing shown: no move can take until the first render.
     _extent = { rows: 0, lines: 0 };
     _moves = [];
+    // No range followed yet: NaN equals nothing, so the first `follow` moves.
+    _followed = { start: NaN, end: NaN, rows: NaN };
     constructor(content, options = {}) {
         this.content = content;
         this.rows = options.rows;
@@ -96,20 +98,47 @@ export class Viewport {
     ensureVisible(start, end) {
         this._moves.push((offset, { rows }) => Math.min(start, Math.max(offset, end - rows)));
     }
+    /**
+     * `ensureVisible(start, end)`, when the range differs from the one the last
+     * `follow` named. A view rebuilt every frame calls this in every frame with
+     * its selection's lines, and the selection is brought into view when it
+     * moves — not on every frame, which would undo on its very render each
+     * scroll the mouse wheel queues. A followed range the last render showed
+     * whole stays shown when the row count changes: the same lines can fall off
+     * the bottom of a viewport that got shorter. One the wheel had scrolled
+     * away from stays away.
+     */
+    follow(start, end) {
+        if (start === this._followed.start && end === this._followed.end)
+            return;
+        this._followed = { start, end, rows: NaN };
+        this.ensureVisible(start, end);
+    }
     /**
      * 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));
+        return cellCount(width - this.gutter);
+    }
+    /** The cells the scrollbar's gutter takes beside the content. */
+    get gutter() {
+        return gutterWidth(this.scrollbar);
     }
     *render(rawOptions) {
         const { height, ...options } = withBoundedWidth(rawOptions, this);
-        const gutter = gutterWidth(this.scrollbar);
+        const gutter = this.gutter;
         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 };
+        const followed = this._followed;
+        const wasShown = followed.start >= this._offset && followed.end <= this._offset + this._extent.rows;
         this._extent = extent;
+        if (!Number.isNaN(followed.rows) && followed.rows !== extent.rows && wasShown) {
+            this.ensureVisible(followed.start, followed.end);
+        }
+        if (!Number.isNaN(followed.start))
+            this._followed = { ...followed, rows: extent.rows };
         this._offset = this.resolve(extent);
         this._moves = [];
         const shown = fitHeight(lines.slice(this._offset, this._offset + extent.rows), { rows: extent.rows, exact: true });
@@ -153,14 +182,39 @@ export class Viewport {
         // `withBoundedWidth`: the bounded parse asks this very method for the
         // natural width.
         const options = withCellWidth(rawOptions);
-        const gutter = gutterWidth(this.scrollbar);
+        const gutter = this.gutter;
         const inner = { ...options, maxWidth: this.contentWidth(options.maxWidth) };
-        const content = isMeasurable(this.content)
-            ? Measurement.get(inner, this.content)
-            : new Measurement(Math.min(1, inner.maxWidth), inner.maxWidth);
+        const content = Measurement.get(inner, this.content);
         return new Measurement(content.minimum + gutter, content.maximum + gutter).withMaximum(options.maxWidth);
     }
 }
+/**
+ * One viewport per thing a pane shows, named by a key. The same viewport comes
+ * back while the key holds, so its scroll position does too; a new key gets a
+ * fresh one, so a new subject opens at its top rather than wherever the last
+ * one was left. A frame is rebuilt on every key press and a scroll position is
+ * a viewport's, so this is what outlives the frame for a pane whose subject
+ * changes under it.
+ */
+export class ViewportPerKey {
+    options;
+    held;
+    constructor(options = {}) {
+        this.options = options;
+        this.held = { key: "", viewport: this.fresh() };
+    }
+    /** The viewport for `key`: the held one while the key holds, a fresh one otherwise. */
+    of(key) {
+        if (key !== this.held.key)
+            this.held = { key, viewport: this.fresh() };
+        return this.held.viewport;
+    }
+    fresh() {
+        // Empty until a view hands it content: the content is built where the frame is.
+        return new Viewport(EMPTY, this.options);
+    }
+}
+const EMPTY = { *render() { } };
 const scrollbarGlyphs = ({ thumb, track }) => thumb.glyph + track.glyph;
 /** `scrollbar` in its own styles, drawn in ASCII. */
 function asciiScrollbar({ thumb, track }) {

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

@@ -26,7 +26,7 @@
  *
  * ### The carrier is a hex string, deliberately
  *
- * A color crosses the template seam as `#RRGGBB`, not as an opaque object,
+ * 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
@@ -56,12 +56,34 @@
  * 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";
+import { ColorDepth, type ColorRgba, type TerminalTheme } 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.
+ * 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 const readableOnFunc: (drawnAt: () => ColorDepth) => TemplateFunc;
+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.
@@ -80,8 +102,8 @@ export declare const readableOnFunc: (drawnAt: () => ColorDepth) => TemplateFunc
  * 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.
+ * @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?: () => ColorDepth): FuncMap;
+export declare function colorFuncs(drawnAt?: () => DrawnAt): FuncMap;

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

@@ -26,7 +26,7 @@
  *
  * ### The carrier is a hex string, deliberately
  *
- * A color crosses the template seam as `#RRGGBB`, not as an opaque object,
+ * 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
@@ -55,9 +55,8 @@
  * 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 { blendRgb, ColorDepth, ColorParseError, parseHexColor } 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
@@ -67,15 +66,37 @@ import { darken, contrastFor, ensureContrast } from "../themes/colorMath.js";
  * 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.
+ * 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) {
-    if (!HEX_COLOR_RE.test(value.trim())) {
+    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)}) …`);
+            ` — 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 parseHexColor(value);
+    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.
@@ -145,11 +166,16 @@ const RATIO_RANGE = {
     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 at the depth `drawnAt` names when it is
- * evaluated — a consumer that renders at a per-call depth registers its own.
+ * 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) => ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE), drawnAt()).hex));
+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
@@ -201,11 +227,11 @@ function oklchAxisFuncs() {
  * 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.
+ * @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 = () => ColorDepth.TRUECOLOR) {
+export function colorFuncs(drawnAt = () => TRUECOLOR) {
     return {
         darken: darkenFunc,
         lighten: lightenFunc,

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

@@ -6,7 +6,7 @@
  * 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 { type Style } from "../core/style.js";
 import { RichText } from "../core/text.js";
 /**
  * Apply a style on top of an already-styled RichText fragment.
@@ -19,6 +19,8 @@ import { RichText } from "../core/text.js";
  * 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.
+ * 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

@@ -6,7 +6,7 @@
  * 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 { layerStyle } from "../core/style.js";
 import { RichText } from "../core/text.js";
 /**
  * Apply a style on top of an already-styled RichText fragment.
@@ -19,30 +19,15 @@ import { RichText } from "../core/text.js";
  * 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.
+ * 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 = baseStyleOf(child.style).add(style);
+    result.style = layerStyle(child.style, 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

@@ -36,9 +36,10 @@
 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";
+import type { RenderOptions } from "../core/protocol.js";
+import { type DrawnAt } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
-export { colorFuncs, readableOnFunc } from "./color-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
@@ -57,7 +58,7 @@ export { colorFuncs, readableOnFunc } from "./color-funcs.js";
  * 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;
+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
@@ -71,6 +72,18 @@ export declare function richTextFuncs(drawnAt?: () => ColorDepth): FuncMap;
  * 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`,
@@ -79,14 +92,20 @@ export declare function createRichTextEngine(): Engine<RichText>;
  * - 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
+ * - 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 on errors" — every consumer that wants this exact
+ * 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.
  *
@@ -95,13 +114,6 @@ export declare function createRichTextEngine(): Engine<RichText>;
  * 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[];
+export declare function renderTemplate(engine: Engine<RichText>, source: string, scope?: unknown, options?: RenderTemplateOptions): Segment[];

package/dist/template-bindings/index.js

@@ -91,14 +91,20 @@ export function createRichTextEngine() {
  * - 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
+ * - 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 on errors" — every consumer that wants this exact
+ * 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.
  *
@@ -107,27 +113,37 @@ export function createRichTextEngine() {
  * 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) {
+    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 {
-        const frags = engine.compile(source)(scope);
-        const rt = RichText.fromFragments(frags);
-        return Array.from(rt.render({
-            maxWidth: options?.maxWidth ?? 400,
-            isTerminal: true,
-        }));
+        text = RichText.fromFragments(engine.compile(source)(scope));
     }
     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))];
+        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

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

@@ -67,7 +67,9 @@ import type { Palette } from "../themes/palette.js";
 /**
  * Register `color "name-or-hex"` against a live palette.
  *
- * `color` resolves a palette variable name to a `#RRGGBB` string, and passes
+ * `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

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

@@ -63,7 +63,9 @@
  * they are gone.
  */
 import { resolveColorRef } from "../themes/colorRef.js";
-import { ColorRamp, parseRampEasing } from "../themes/ramp.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.
  *
@@ -85,7 +87,7 @@ function colorStops(tail, palette) {
     for (let i = 0; i < tail.length; i += 2) {
         stops.push({
             at: tail[i],
-            color: resolveColorRef(palette, tail[i + 1]),
+            color: computable(resolveColorRef(palette, tail[i + 1]), "ramp", JSON.stringify(tail[i + 1])),
         });
     }
     return stops;
@@ -93,7 +95,9 @@ function colorStops(tail, palette) {
 /**
  * Register `color "name-or-hex"` against a live palette.
  *
- * `color` resolves a palette variable name to a `#RRGGBB` string, and passes
+ * `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
@@ -124,14 +128,14 @@ export function paletteFuncs(getPalette) {
         arity: { kind: "exact" },
         returnType: "string",
     };
-    // `ramp <value> <easing> <position> <color> …` — the argument list is one
-    // float/string cycle end to end (value, easing, then each stop's position
+    // `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 easing, and one stop, so the gate refuses a stopless call.
+    // value, the ease, and one stop, so the gate refuses a stopless call.
     // [LAW:types-are-the-program]
     const rampFunc = {
-        fn: ((value, easing, ...tail) => new ColorRamp(parseRampEasing(easing), colorStops(tail, getPalette())).at(value)
+        fn: ((value, ease, ...tail) => new ColorRamp(parseEase(ease), colorStops(tail, getPalette())).at(value)
             .hex),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 4 },

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

@@ -113,11 +113,13 @@ const styleSpecFunc = {
 // `link` is the cell-splitter for the multi-cell consumer contract.
 // Implementation-wise it is the same shape as any other style function:
 // it sets the `link` slot of `Style` exactly as the existing string-form
-// `link URL` does, so a template-built fragment is byte-equivalent to
+// `link URL` does, so `{{ link "u" "x" }}` is byte-equivalent to
 // `RichText("x", { style: Style.parse("link u") })`.
 //
 // The cell-boundary signal that consumers (cc-candybar et al.) walk is
-// `fragment.style.link` being truthy. `Style.add` propagates `link`
+// `theme.resolve(fragment.style).link` being truthy: a fragment whose base
+// style is a string keeps the link in a `LayeredStyle` until a theme says
+// what the string stands for. `Style.add` propagates `link`
 // through any outer wrapping call, so `{{ fg "red" (link "u" "x") }}` and
 // `{{ link "u" "x" }}` produce shapes that both qualify as cells from
 // the consumer's perspective. Outer-wins on nested links comes for free

package/dist/themes/buildPalette.d.ts

@@ -14,6 +14,8 @@ export interface BaseColors {
     background: ColorRgba;
     foreground: ColorRgba;
 }
+type AccentKey = "primary" | "secondary" | "accent" | "success" | "warning" | "error";
+export declare const ACCENT_KEYS: readonly AccentKey[];
 /**
  * Build a full semantic palette from base colors.
  *
@@ -25,12 +27,31 @@ export interface BaseColors {
  *              de-emphasizing body/structural text reaches for
  *              `foreground-muted` the same way it reaches for
  *              `primary-muted` to de-emphasize an accent.
- * - `text-*`  = contrast text tinted 66% with the accent color (use as
- *              foreground in muted/background-tinted contexts)
+ * - `text-*`  = contrast text tinted 66% with the accent color, then held
+ *              to WCAG AA (4.5:1) on `*-muted` — the foreground for a
+ *              `*-muted` ground
  * - `on-*`    = WCAG-correct contrast colour (black or white) for use as
  *              foreground when the FULL accent is the background. Picked
  *              by relative luminance — single source of truth so widgets
  *              never need to invert / reverse fg/bg to get readable text.
  * - `surface` = background blended 5% toward foreground
+ *
+ * A translucent base colour is drawn onto `background` before anything is
+ * derived from it, so `on-*` is chosen against the colour the accent is drawn
+ * as and every derived entry is opaque.
+ */
+export declare function buildPalette(name: string, dark: boolean, given: BaseColors): Palette;
+/**
+ * A palette's `text-*`: its tint held to WCAG AA on `*-muted`, moved toward
+ * the palette's own text side so it also reads on `background`, where widgets
+ * draw it too. The muted floor is the promise: where no lightness on the text
+ * side clears it, the colour that does is on the other side, and the
+ * background pair is the one given up. Every bundled palette clears both
+ * (test/themes/text-on-muted.test.ts).
+ *
+ * [LAW:single-enforcer] The one rule for the pair, for the palettes derived
+ * here and the authored ones the registry hydrates: the tint is the theme's,
+ * whether it reads is decided here.
  */
-export declare function buildPalette(name: string, dark: boolean, base: BaseColors): Palette;
+export declare function accentText(tint: ColorRgba, muted: ColorRgba, background: ColorRgba): ColorRgba;
+export {};