@promptctl/rich-js 0.26.0 → 0.28.0

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

@@ -20,7 +20,7 @@
  * number the time is turned into first: a frame's stamp says when it changes
  * on the host's clock, which only `Timeline.run` can carry it back onto —
  * paused, never; backwards, at the hold it is about to drop under.
- * [LAW:single-enforcer] `drawing` is the one place the time, the timeline
+ * [LAW:single-enforcer] `drawn` is the one place the time, the timeline
  * and the reader's preference for motion are read, for every function.
  *
  * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
@@ -57,27 +57,62 @@
  * exact arity of typed slots, so a slot of the wrong kind fails at the gate.
  *
  * Every function says when what it drew changes, so a host paints a
- * template while it moves and not after. `frames` and `glyphs` stamp the
- * fragment they draw (`textFrameAt`), covering its own glyphs. A number or a
- * colour carries no cells to stamp, so `tween`, `loop` and `stepped` tell
- * their hold to the frame instead (`TemplateFrame.onHold`), as a placed
- * animation of no cells does (`RenderOptions.onHold`). Nothing here claims
- * a moment it does not know.
+ * template while it moves and not after — and says it only for what the
+ * output depends on. A number or a colour has no cells to carry a hold, and
+ * a fragment's cells lose theirs the moment it is flattened (`printf "%s"`),
+ * so no function stamps cells or tells the frame itself. Each marks its
+ * return with the hold its value is in (`marked`, the engine's evaluation
+ * provenance), and the engine carries the mark beside the value into every
+ * variable, dot and function the value passes through, reporting it where
+ * the output depends on it. `emitted` is where a template's cells take a
+ * hold: every fragment the template emits, stamped with the holds of the
+ * marked values its action read. `decided` is the route for a hold no cell
+ * can carry, told to the frame (`TemplateFrame.onHold`): a mark an
+ * `if`/`with`/`range` consumed, whichever arm it took, because the frame may
+ * show cells for it later and must say when without a cell to say it on, as
+ * a placed animation of no cells does (`placed`) — and, by the same rule, a
+ * mark a writing function or a throwing action read; `EngineConfig.decided`
+ * is the authority on when it is called. A mark bound somewhere nobody reads
+ * is reported nowhere, so a value a template computes and never draws or
+ * decides on tells the frame nothing (rich-animation-27tq.0gd). Early, never
+ * late: an emission may carry a hold it did not strictly need, and a hold
+ * the output depends on is never dropped. [LAW:single-enforcer]
+ *
+ * The functions and the two hooks go into the host's engine config together,
+ * by `withAnimation`: the functions wired without the hooks would compile,
+ * draw and never say they move. [LAW:no-silent-failure]
  */
-import { Animation, frameTimeOf, holdOf, shownAt } from "../core/animation.js";
+import { marked } from "@promptctl/go-template-js";
+import { Animation, frameTimeOf, holdOf, shownAt, stamp } from "../core/animation.js";
 import { Phase, beat, finiteTime, parseEase } from "../core/easing.js";
+import { layerStyle } from "../core/style.js";
 import { Timeline } from "../core/timeline.js";
 import { tween } from "../core/tween.js";
 import { cellSeed } from "../renderables/effect.js";
 import { reglyphText } from "../renderables/glyph-effect.js";
 import { GLYPH_EFFECT_CATALOGUE } from "../renderables/glyph-effects.js";
-import { FrameSequence, textFrameAt } from "../renderables/frames.js";
+import { FrameSequence } from "../renderables/frames.js";
 import { asColor } from "./color-funcs.js";
 import { asFragment } from "./helpers.js";
 /** The frame a renderable is drawn in, as the frame a template it evaluates there is drawn for. */
 export function templateFrame(options) {
     return { time: frameTimeOf(options), onHold: options.onHold, reducedMotion: options.reducedMotion, asciiOnly: options.asciiOnly };
 }
+/**
+ * The mark a function puts on its return: the hold its value is in, and the
+ * frame it was drawn for, which is the one `decided` tells. Only the two
+ * hooks here read one; a consumer's own marks pass through them untouched,
+ * and a foreign token shaped like a `Hold` is not one.
+ * [LAW:types-are-the-program]
+ */
+class HoldMark {
+    hold;
+    frame;
+    constructor(hold, frame) {
+        this.hold = hold;
+        this.frame = frame;
+    }
+}
 /** The host's own clock as a timeline: host time 0 at animation time 0, at rate 1. */
 const HOST_CLOCK = Timeline.play(0);
 /**
@@ -127,36 +162,41 @@ function glyphEffect(name) {
     return GLYPH_EFFECTS[name];
 }
 /**
- * Register `frames`, `stepped`, `tween`, `loop` and `glyphs`, each drawn for
- * the frame `frame` reports when the template is evaluated — its time in
- * seconds, from whatever zero the host counts from — through
- * `options.timeline`, and each telling that frame when what it drew changes.
+ * `config` with `frames`, `stepped`, `tween`, `loop` and `glyphs` registered
+ * beside its own functions, each drawn for the frame `frame` reports when
+ * the template is evaluated — its time in seconds, from whatever zero the
+ * host counts from — through `options.timeline`, and each marking its
+ * return with the hold it is in there; and with the two hooks that carry
+ * those holds to the cells (`emitted`) and the frame (`decided`) installed
+ * over any `config` already has, which still hear everything they did. One
+ * call, so the functions and the hooks that report for them cannot be wired
+ * apart: the functions alone would compile, draw, and never say they move.
+ * [LAW:types-are-the-program] [LAW:no-silent-failure] [LAW:composability]
+ * A `config` that already has one of the five names is refused, which is
+ * also what a second `withAnimation` over its own result meets: its template
+ * calls would otherwise reach these with no word said.
+ *
  * The functions exist whatever `frame` returns, so a template compiles once
  * and is evaluated at every moment the host draws. In a frame that says
  * `reducedMotion` each draws its animation reduced (`Animation.reduced`): a
  * loop at its start, a one-shot cut from where it starts to where it arrives
  * when it starts.
  */
-export function animationFuncs(frame, options = {}) {
+export function withAnimation(config, frame, options = {}) {
     const timeline = options.timeline ?? (() => HOST_CLOCK);
-    // `animation` on this call's timeline, and the time of `at`, the frame it
-    // is drawn in, read once a call so a value and its hold are one frame's.
-    const drawing = (what, animation, at) => [Timeline.run(timeline(), animation), finiteTime(what, at.time)];
-    // What a value animation shows now, under the reader's preference, its
-    // hold told to the frame: a value has no cells to carry it.
-    const now = (what, animation) => {
-        const at = frame();
-        const [drawn, t] = drawing(what, animation, at);
-        const shown = shownAt(drawn, t, at);
-        at.onHold?.(holdOf(shown, t));
-        return shown.value;
+    // What `animation`, on this call's timeline, shows in the frame `at`,
+    // under the reader's preference, marked with how long for: the time is
+    // read once a call so a value and its hold are one frame's.
+    const drawn = (what, animation, at) => {
+        const t = finiteTime(what, at.time);
+        const shown = shownAt(Timeline.run(timeline(), animation), t, at);
+        return marked(shown.value, new HoldMark(holdOf(shown, t), at));
     };
     const startedAt = (start, animation) => Timeline.run(Timeline.play(start), animation);
     const framesFunc = {
         fn: ((...tail) => {
             const frames = pairs("frame", tail, asFragment).map(({ seconds, value }) => ({ seconds, text: value }));
-            const at = frame();
-            return textFrameAt(...drawing("frames", new FrameSequence(frames), at), at);
+            return drawn("frames", new FrameSequence(frames), frame());
         }),
         argTypes: ["float", "liftable"],
         arity: { kind: "alternating", minimum: 2 },
@@ -165,20 +205,20 @@ export function animationFuncs(frame, options = {}) {
     const steppedFunc = {
         fn: ((...tail) => {
             const steps = pairs("color", tail, (v) => asColor(v, "stepped"));
-            return steps[now("stepped", beat(steps.map((step) => step.seconds)))].value.hex;
+            return drawn("stepped", Animation.map(beat(steps.map((s) => s.seconds)), (step) => steps[step].value.hex), frame());
         }),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 2 },
         returnType: "string",
     };
     const tweenFunc = {
-        fn: ((seconds, ease, start, from, to) => now("tween", startedAt(start, tween(from, to, { seconds, ease: parseEase(ease) })))),
+        fn: ((seconds, ease, start, from, to) => drawn("tween", startedAt(start, tween(from, to, { seconds, ease: parseEase(ease) })), frame())),
         argTypes: ["float", "string", "float", "float", "float"],
         arity: { kind: "exact" },
         returnType: "float",
     };
     const loopFunc = {
-        fn: ((seconds, start) => now("loop", startedAt(start, Animation.continuous(Phase.loop(seconds))))),
+        fn: ((seconds, start) => drawn("loop", startedAt(start, Animation.continuous(Phase.loop(seconds))), frame())),
         argTypes: ["float", "float"],
         arity: { kind: "exact" },
         returnType: "float",
@@ -191,11 +231,54 @@ export function animationFuncs(frame, options = {}) {
             const key = fragment.plain;
             const at = frame();
             const reglyphed = reglyphText(fragment, make({ z: cellSeed(key, 0, 0) }), { key, asciiOnly: at.asciiOnly === true });
-            return textFrameAt(...drawing("glyphs", startedAt(start, reglyphed), at), at);
+            return drawn("glyphs", startedAt(start, reglyphed), at);
         }),
         argTypes: ["string", "float", "liftable"],
         arity: { kind: "exact" },
         returnType: "T",
     };
-    return { frames: framesFunc, stepped: steppedFunc, tween: tweenFunc, loop: loopFunc, glyphs: glyphsFunc };
+    const funcs = { frames: framesFunc, stepped: steppedFunc, tween: tweenFunc, loop: loopFunc, glyphs: glyphsFunc };
+    const taken = Object.keys(funcs).filter((name) => Object.hasOwn(config.funcs ?? {}, name));
+    if (taken.length > 0) {
+        throw new RangeError(`withAnimation registers ${taken.join(", ")}, already in config.funcs`);
+    }
+    const holdMarks = (marks) => [...marks].filter((mark) => mark instanceof HoldMark);
+    // The holds among `marks` layered onto the fragment's base style, which an
+    // empty text still draws as its one piece of no width: `Style.add` keeps
+    // the later `lastChange` and the sooner `nextChange`, so cells that read
+    // two animated values are in the intersection of their holds, as two
+    // styles laid together are anywhere. A fragment no hold reaches is handed
+    // back as it came — the engine calls this for every emission — and one a
+    // hold reaches is a copy, since the engine may hand the one fragment a
+    // scope holds to more than one emission.
+    const held = (fragment, marks) => {
+        const holds = holdMarks(marks);
+        if (holds.length === 0)
+            return fragment;
+        const result = fragment.copy();
+        result.style = holds.reduce((style, mark) => layerStyle(style, stamp(mark.hold)), fragment.style);
+        return result;
+    };
+    const told = (marks) => {
+        for (const mark of holdMarks(marks))
+            mark.frame.onHold?.(mark.hold);
+    };
+    // The hooks `config` brought run first and hear everything they did; a
+    // consumer that stamps or listens on its own loses nothing to this binding.
+    const emitted = config.emitted ?? ((fragment) => fragment);
+    const decided = config.decided ?? (() => { });
+    return {
+        ...config,
+        funcs: { ...config.funcs, ...funcs },
+        emitted: (fragment, marks) => held(emitted(fragment, marks), marks),
+        // `finally`: a consumer hook that throws still leaves the frame told its holds.
+        decided: (marks) => {
+            try {
+                decided(marks);
+            }
+            finally {
+                told(marks);
+            }
+        },
+    };
 }

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

@@ -14,10 +14,12 @@
  * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
  *   resolve a palette name. This is the *only* registration that knows a
  *   palette exists. [LAW:one-way-deps]
- * - `animationFuncs(frame)` — `frames`, `stepped`, `tween`, `loop` and
- *   `glyphs`, drawn for a moment on a timeline. It is the only registration
- *   that knows the template is evaluated at a time, and the time and the
- *   timeline are the host's to hand in (`./animation-funcs.ts`).
+ * - `withAnimation(config, frame)` — the engine config with `frames`,
+ *   `stepped`, `tween`, `loop` and `glyphs` registered, drawn for a moment on
+ *   a timeline, and the two engine hooks their holds reach the frame through
+ *   installed beside them. It is the only registration that knows the
+ *   template is evaluated at a time, and the time and the timeline are the
+ *   host's to hand in (`./animation-funcs.ts`).
  *
  * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
  * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
@@ -43,7 +45,7 @@ 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";
-export { animationFuncs, templateFrame, type AnimationFuncsOptions, type TemplateFrame } from "./animation-funcs.js";
+export { withAnimation, templateFrame, type AnimationOptions, type TemplateFrame } from "./animation-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

package/dist/template-bindings/index.js

@@ -14,10 +14,12 @@
  * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
  *   resolve a palette name. This is the *only* registration that knows a
  *   palette exists. [LAW:one-way-deps]
- * - `animationFuncs(frame)` — `frames`, `stepped`, `tween`, `loop` and
- *   `glyphs`, drawn for a moment on a timeline. It is the only registration
- *   that knows the template is evaluated at a time, and the time and the
- *   timeline are the host's to hand in (`./animation-funcs.ts`).
+ * - `withAnimation(config, frame)` — the engine config with `frames`,
+ *   `stepped`, `tween`, `loop` and `glyphs` registered, drawn for a moment on
+ *   a timeline, and the two engine hooks their holds reach the frame through
+ *   installed beside them. It is the only registration that knows the
+ *   template is evaluated at a time, and the time and the timeline are the
+ *   host's to hand in (`./animation-funcs.ts`).
  *
  * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
  * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
@@ -45,7 +47,7 @@ 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";
-export { animationFuncs, templateFrame } from "./animation-funcs.js";
+export { withAnimation, templateFrame } from "./animation-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
@@ -84,6 +86,7 @@ export function richTextFuncs(drawnAt) {
 export function createRichTextEngine() {
     return createEngine({
         fromString: (s) => new RichText(s),
+        isT: (v) => v instanceof RichText,
         toString: (rt) => rt.plain,
         funcs: richTextFuncs(),
     });

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

@@ -83,7 +83,7 @@ import type { Palette } from "../themes/palette.js";
  * @example
  * ```ts
  * const engine = createEngine({
- *   fromString: (s) => new RichText(s),
+ *   fromString: (s) => new RichText(s), isT: (v) => v instanceof RichText,
  *   toString: (rt) => rt.plain,
  *   funcs: {
  *     ...richTextFuncs(),

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

@@ -111,7 +111,7 @@ function colorStops(tail, palette) {
  * @example
  * ```ts
  * const engine = createEngine({
- *   fromString: (s) => new RichText(s),
+ *   fromString: (s) => new RichText(s), isT: (v) => v instanceof RichText,
  *   toString: (rt) => rt.plain,
  *   funcs: {
  *     ...richTextFuncs(),

package/dist/themes/buildPalette.d.ts

@@ -1,5 +1,5 @@
 import { ColorRgba } from "../core/color.js";
-import { Palette } from "./palette.js";
+import { Palette, type BaseRole, type PaletteRole, type PaletteRoles } from "./palette.js";
 /**
  * Base colors required to build a full semantic palette.
  * All are ColorRgba — callers construct from whatever source (hex, HSL, etc.).
@@ -14,44 +14,20 @@ export interface BaseColors {
     background: ColorRgba;
     foreground: ColorRgba;
 }
-type AccentKey = "primary" | "secondary" | "accent" | "success" | "warning" | "error";
-export declare const ACCENT_KEYS: readonly AccentKey[];
+/** The eight roles every palette is given, and every role it may also state. */
+export type StatedRoles = BaseColors & Partial<PaletteRoles>;
+export declare const BASE_KEYS: readonly BaseRole[];
+/** Every role of every palette, read off the rules. */
+export declare const PALETTE_ROLES: readonly PaletteRole[];
 /**
- * Build a full semantic palette from base colors.
+ * Build a full semantic palette from its base colors and any other role it
+ * states: a stated role keeps its colour, and everything derived from it
+ * follows it, but for `text-*`, which is held to read on its `*-muted`. An
+ * authored theme is this with roles stated; see `RULES` for what a role
+ * not stated becomes.
  *
- * Derived entries follow Textual's formulas:
- * - `*-muted` = color blended 70% toward its opposite base role. Defined for
- *              every accent AND for the two base roles themselves
- *              (`foreground-muted` blends toward `background`,
- *              `background-muted` blends toward `foreground`) — a caller
- *              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, 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.
+ * A translucent colour is drawn onto `background` before anything is derived
+ * from it, so `on-*` is chosen against the colour the accent is drawn as.
+ * `boost` alone stays a layer: it is what `panel` composites.
  */
-export declare function accentText(tint: ColorRgba, muted: ColorRgba, background: ColorRgba): ColorRgba;
-export {};
+export declare function buildPalette(name: string, dark: boolean, given: StatedRoles): Palette;