@promptctl/rich-js 0.23.0 → 0.24.0

package/dist/renderables/spinner.js

@@ -1,14 +1,65 @@
 /**
- * Spinner — animated terminal spinner with optional text label.
+ * Spinner — a named spinner, asked for its frame at a time, with an optional
+ * label after it.
+ *
+ * A spinner is a `FrameSequence` (`./frames.ts`) over one entry of the named spinner
+ * data (`core/spinnerData.ts`): each frame held for the spinner's interval,
+ * looping, the frame in progress at `t` drawn. The data names the frames and
+ * the interval; the beat, the width every frame draws at and which frame `t`
+ * lands on are the frames primitive's, so a spinner is one more sequence on
+ * it and not a second way of turning frames. Custom frames are a `FrameSequence`
+ * drawn through `Frames` directly. [LAW:one-source-of-truth]
+ *
+ * It is built once and asked for each frame, as Rich's `Spinner` is built
+ * once and has `render(time)` called on it: the name is parsed and the
+ * styled frames are prepared where the spinner is given, and `at(t)` is what
+ * draws, so a `Status` or `SpinnerColumn` holding one pays for the name and
+ * the styling once, and a bad name fails at the call that gave it.
+ * [LAW:parse-dont-validate] What a `FrameSequence` makes of the frames —
+ * the beat, the width, each frame padded to it — is made there too, so a
+ * drawn frame costs only finding which one `t` lands on.
+ *
+ * [LAW:no-ambient-temporal-coupling] A Spinner draws nothing on its own:
+ * only `at(t)` is a renderable, so a spinner cannot be drawn without being
+ * handed its time, and nothing here reads a clock. Whoever draws frames
+ * hands each one its time (`core/clock.ts`) — `SpinnerColumn` the task's
+ * `time`, a `Live` the frame's time on its clock — as Rich's `Spinner.render`
+ * is handed `console.get_time()` or `task.get_time()`. `t` is the clock's
+ * time, as `App` and `Task.time` hand it, where Rich's spinner counts from
+ * its first draw: here nothing is kept between frames, so the same `t` draws
+ * the same bytes at one redraw a second or sixty, two spinners on one clock
+ * agree at every `t`, a `Progress` on a hand-moved clock turns its spinners
+ * on that clock, and a draw costs the same at `t = 0` and `t = 10⁶`.
+ *
+ * `speed` scales the holds, not the time: at speed 2 each frame is held half
+ * the interval, and a negative speed is the frames in reverse order, each held
+ * the interval over the speed's size. [LAW:one-source-of-truth] Rich scales
+ * the time instead, `t × speed` into the beat. At a positive speed the frame
+ * drawn is the same; but when the frame next changes (`Style.nextChange`) is
+ * a time on the host's timeline, and a beat over scaled time answers on the
+ * scaled one — so the sequence is scaled where it is built, and the
+ * `FrameSequence` stamps host time with nothing to map back. Backwards, this is the plain
+ * reversed sequence from `t = 0`, where Rich's `int()` truncation holds
+ * frame 0 for a first interval and then counts down: a departure, made so a
+ * negative speed is one more sequence on the beat and not a second rule
+ * about time. A speed of zero would hold a frame forever, which is not a
+ * beat, and is refused where it is given.
  */
-import { cellLen } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
 import { RichText } from "../core/text.js";
 import { SPINNERS, DEFAULT_SPINNER, LINE_SPINNER } from "../core/spinnerData.js";
 import { drawable } from "../core/protocol.js";
 import { EmbeddedText } from "./embed.js";
-const spinnerGlyphs = ({ frames }) => frames.join("");
+import { FrameSequence } from "./frames.js";
+const sequence = (data, style, speed) => {
+    const frames = data.frames.map((frame) => ({
+        text: new RichText("", { end: "" }).append(frame, style),
+        seconds: data.interval / 1000 / Math.abs(speed),
+    }));
+    return { frames: new FrameSequence(speed < 0 ? frames.reverse() : frames), glyphs: data.frames.join("") };
+};
+const sequenceGlyphs = ({ glyphs }) => glyphs;
 export class Spinner {
     name;
     speed;
@@ -22,82 +73,78 @@ export class Spinner {
      */
     text;
     _data;
-    _frameIndex;
-    _lastUpdate;
+    // The named data's frames, and the `line` spinner's that stand in for them
+    // on an ASCII-only output: prepared once, which is drawn chosen at `at`.
+    _named;
+    _ascii;
     constructor(name, text = "", options) {
         const spinnerName = name ?? DEFAULT_SPINNER;
         const data = SPINNERS[spinnerName];
         if (!data) {
             throw new Error(`Unknown spinner: "${spinnerName}"`);
         }
+        const speed = options?.speed ?? 1;
+        // [LAW:parse-dont-validate] A hold is a positive number of seconds, so the
+        // speed it is divided by is finite and not zero, settled here.
+        if (!Number.isFinite(speed) || speed === 0) {
+            throw new RangeError(`Spinner speed must be finite and not zero, got ${speed}`);
+        }
         this.name = spinnerName;
         this.text = text;
-        this.speed = options?.speed ?? 1;
+        this.speed = speed;
         this.style = options?.style ?? NULL_STYLE;
         this._data = data;
-        this._frameIndex = 0;
-        this._lastUpdate = Date.now();
+        this._named = sequence(data, this.style, speed);
+        this._ascii = sequence(LINE_SPINNER, this.style, speed);
     }
     get frames() {
         return this._data.frames;
     }
+    /** Milliseconds each frame is held, as the spinner data gives it. */
     get interval() {
         return this._data.interval;
     }
-    /** Advance the frame count by the time elapsed, and return it. */
-    _advance() {
-        const now = Date.now();
-        // Whole frames passed at this speed; a negative speed steps backwards, as
-        // Rich's does, so the index wraps with a modulo that is never negative.
-        const steps = Math.trunc(((now - this._lastUpdate) * this.speed) / this.interval);
-        if (steps !== 0) {
-            const count = this._data.frames.length;
-            this._frameIndex = (((this._frameIndex + steps) % count) + count) % count;
-            this._lastUpdate = now;
-        }
-        return this._frameIndex;
-    }
-    /** The frames this output can draw: the `line` spinner stands in for any other on an ASCII-only one. */
-    _drawnFrames(options) {
-        return drawable(options, this._data, LINE_SPINNER, spinnerGlyphs).frames;
-    }
     /**
-     * The current frame and its label as one line wrapped to the width and
-     * ended, as the reference's `Text` is — printed, stacked in a `Group`, or
-     * laid out in a `Progress` cell alike.
+     * The frame in progress at `t` seconds and the label, as one renderable:
+     * the line wrapped to the width and ended, as the reference's `Text` is —
+     * printed, stacked in a `Group`, or laid out in a `Progress` cell alike.
+     * The frames this output can draw are chosen where the output is known.
      */
-    *render(options) {
-        yield* this._currentLine(options).render(options);
-        yield Segment.line();
+    at(t) {
+        if (!Number.isFinite(t)) {
+            throw new RangeError(`Spinner.at needs a finite t, got ${t}`);
+        }
+        const frames = (options) => drawable(options, this._named, this._ascii, sequenceGlyphs).frames;
+        return {
+            render: (options) => this._render(frames(options), t, options),
+            // Measured at the frames' one width, the widest frame's, so a column
+            // holding it never narrows as it turns, and never offered less than
+            // that frame: a frame is one picture, which the reference's `Text`
+            // measure would let wrap apart at its spaces.
+            measure: (options) => {
+                const drawn = frames(options);
+                const { minimum, maximum } = this._line(drawn, t, options).measure(options);
+                return { minimum: Math.max(minimum, Math.min(drawn.width, maximum)), maximum };
+            },
+        };
     }
-    _currentLine(options) {
-        const frames = this._drawnFrames(options);
-        return this._line(frames[this._advance() % frames.length], options);
+    *_render(frames, t, options) {
+        yield* this._line(frames, t, options).render(options);
+        yield Segment.line();
     }
     /**
-     * `frame` and the label as one text, as Rich's `Text.assemble(frame, " ",
-     * text)`: a long label wraps as one line with its frame. A label that draws
-     * nothing — the default `""`, or markup that styles nothing — is no label,
-     * not a trailing space, as an empty `Text` is falsy there.
+     * The frame in progress and the label as one text, as Rich's
+     * `Text.assemble(frame, " ", text)`: a long label wraps as one line with its
+     * frame. A label that draws nothing — the default `""`, or markup that
+     * styles nothing — is no label, not a trailing space, as an empty `Text` is
+     * falsy there.
      */
-    _line(frame, options) {
-        const line = new RichText("", { end: "" }).append(frame, this.style);
+    _line(frames, t, options) {
+        const line = new RichText("", { end: "" }).append(frames.text(t));
         // Unhighlighted: Rich's label is a `Text` from the moment it is handed over, and a `Text` is never highlighted.
         const label = new EmbeddedText(this.text).text({ ...options, highlight: false });
         if (label.plain !== "")
             line.append(" ").append(label);
         return line;
     }
-    /**
-     * Measured at its widest frame, so a column holding it never narrows as it
-     * turns, and never offered less than that frame: a frame is one picture,
-     * which the reference's `Text` measure would let wrap apart at its spaces.
-     */
-    measure(options) {
-        const frames = this._drawnFrames(options);
-        const widths = frames.map((frame) => cellLen(frame));
-        const frameWidth = Math.max(...widths);
-        const { minimum, maximum } = this._line(frames[widths.indexOf(frameWidth)], options).measure(options);
-        return { minimum: Math.max(minimum, Math.min(frameWidth, maximum)), maximum };
-    }
 }

package/dist/renderables/status.d.ts

@@ -1,10 +1,13 @@
 /**
  * Status — displays a spinner animation with a status message.
  *
- * Its renderable is a `Spinner` whose label is the message, as Rich's is, so
- * the message is drawn the way the spinner draws its label: a string is markup
- * under the console that draws it.
+ * Its view is a `Spinner` whose label is the message, as Rich's is, so the
+ * message is drawn the way the spinner draws its label: a string is markup
+ * under the console that draws it. The `Live` hands each frame its time, and
+ * the spinner is asked for its frame at it, so the frame is the clock's, not
+ * the platform's. [LAW:no-ambient-temporal-coupling]
  */
+import type { Clock } from "../core/clock.js";
 import type { Style } from "../core/style.js";
 import type { RichText } from "../core/text.js";
 import { Console } from "../core/console.js";
@@ -14,6 +17,8 @@ export interface StatusOptions {
     /** The spinner's frame style; the message styles itself with its markup. */
     spinnerStyle?: string | Style;
     console?: Console;
+    /** What the frames are timed and drawn on. The platform's, unless given. */
+    clock?: Clock;
 }
 export declare class Status {
     private _live;

package/dist/renderables/status.js

@@ -1,9 +1,11 @@
 /**
  * Status — displays a spinner animation with a status message.
  *
- * Its renderable is a `Spinner` whose label is the message, as Rich's is, so
- * the message is drawn the way the spinner draws its label: a string is markup
- * under the console that draws it.
+ * Its view is a `Spinner` whose label is the message, as Rich's is, so the
+ * message is drawn the way the spinner draws its label: a string is markup
+ * under the console that draws it. The `Live` hands each frame its time, and
+ * the spinner is asked for its frame at it, so the frame is the clock's, not
+ * the platform's. [LAW:no-ambient-temporal-coupling]
  */
 import { Console } from "../core/console.js";
 import { Spinner } from "./spinner.js";
@@ -18,8 +20,9 @@ export class Status {
             speed: options?.speed,
             style: options?.spinnerStyle ?? "status.spinner",
         });
-        this._live = new Live(this._spinner, {
+        this._live = new Live((t) => this._spinner.at(t), {
             console: this._console,
+            clock: options?.clock,
             transient: true,
             refreshPerSecond: 12.5,
         });
@@ -41,6 +44,6 @@ export class Status {
     }
     update(message) {
         this._spinner.text = message;
-        this._live.update(this._spinner, { refresh: true });
+        this._live.refresh();
     }
 }

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

@@ -0,0 +1,37 @@
+/**
+ * Animation registrations for the rich-js template binding: what a template
+ * draws for the moment it is evaluated at.
+ *
+ * A host that builds its cells in templates — cc-candybar's statusline, say —
+ * evaluates each template once per redraw and owns the clock that says when
+ * that is. So the time is a capability the registration takes, the way
+ * `richTextFuncs(drawnAt)` takes the drawn depth: `frameTime()` is read once
+ * per call, when the template is evaluated, and nothing here reads a clock.
+ * [LAW:no-ambient-temporal-coupling] A host hands in the same `t` and gets
+ * the same fragment back; a host that redraws once a second or sixty times
+ * a second registers the same functions.
+ *
+ * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
+ * (`renderables/frames.ts`) in a template: the frame in progress at the
+ * moment, as a fragment at the width of the widest. Its frames arrive as
+ * arguments on every evaluation, so the sequence is prepared on every one:
+ * a template has nowhere to keep it, and keeping it here would be the memo
+ * keyed on the arguments that `FrameSequence` is instead of. `stepped <seconds>
+ * <color> <seconds> <color> …` is the colour in progress at the moment, a
+ * colour value like every colour function's (`./color-funcs.ts`), so it
+ * nests where a colour goes — `fg (stepped …)`, `readableOn (stepped …) $bg
+ * 4.5` — and the ground it must read on is the template's to name, as it
+ * is for any colour. Either argument list is one float/value cycle end to
+ * end, so the engine's `alternating` gate types every slot and lifts each
+ * string frame to a fragment; the pairing — a trailing hold with no frame or
+ * colour — is parsed in `pairs`, once. [LAW:types-are-the-program]
+ */
+import type { FuncMap } from "@promptctl/go-template-js";
+/**
+ * Register `frames` and `stepped`, each drawn for the moment `frameTime`
+ * reports when the template is evaluated: seconds on the host's own
+ * timeline, from whatever zero it counts from. The functions exist whatever
+ * `frameTime` returns, so a template compiles once and is evaluated at every
+ * moment the host draws.
+ */
+export declare function animationFuncs(frameTime: () => number): FuncMap;

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

@@ -0,0 +1,83 @@
+/**
+ * Animation registrations for the rich-js template binding: what a template
+ * draws for the moment it is evaluated at.
+ *
+ * A host that builds its cells in templates — cc-candybar's statusline, say —
+ * evaluates each template once per redraw and owns the clock that says when
+ * that is. So the time is a capability the registration takes, the way
+ * `richTextFuncs(drawnAt)` takes the drawn depth: `frameTime()` is read once
+ * per call, when the template is evaluated, and nothing here reads a clock.
+ * [LAW:no-ambient-temporal-coupling] A host hands in the same `t` and gets
+ * the same fragment back; a host that redraws once a second or sixty times
+ * a second registers the same functions.
+ *
+ * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
+ * (`renderables/frames.ts`) in a template: the frame in progress at the
+ * moment, as a fragment at the width of the widest. Its frames arrive as
+ * arguments on every evaluation, so the sequence is prepared on every one:
+ * a template has nowhere to keep it, and keeping it here would be the memo
+ * keyed on the arguments that `FrameSequence` is instead of. `stepped <seconds>
+ * <color> <seconds> <color> …` is the colour in progress at the moment, a
+ * colour value like every colour function's (`./color-funcs.ts`), so it
+ * nests where a colour goes — `fg (stepped …)`, `readableOn (stepped …) $bg
+ * 4.5` — and the ground it must read on is the template's to name, as it
+ * is for any colour. Either argument list is one float/value cycle end to
+ * end, so the engine's `alternating` gate types every slot and lifts each
+ * string frame to a fragment; the pairing — a trailing hold with no frame or
+ * colour — is parsed in `pairs`, once. [LAW:types-are-the-program]
+ */
+import { beat } from "../core/easing.js";
+import { FrameSequence } from "../renderables/frames.js";
+import { asColor } from "./color-funcs.js";
+import { asFragment } from "./helpers.js";
+/**
+ * The `(seconds, value)` pairs a call spells, each value read through
+ * `value`. The gate has typed every even slot as a float and every odd one
+ * as `value`'s input; what it cannot see is the pairing, or that a hold is
+ * a positive number of seconds: both settled here, under the engine's
+ * "error calling <function>" and nothing else, since a template author
+ * knows neither `FrameSequence` nor `beat`, which refuse the same hold in their
+ * own names. [LAW:parse-dont-validate]
+ */
+function pairs(what, tail, value) {
+    if (tail.length % 2 !== 0) {
+        throw new RangeError(`last hold (${String(tail[tail.length - 1])} s) has no ${what} — the arguments are <seconds> <${what}> pairs`);
+    }
+    const paired = [];
+    for (let i = 0; i < tail.length; i += 2) {
+        const seconds = tail[i];
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+            throw new RangeError(`hold ${i / 2} must be a positive number of seconds, got ${seconds}`);
+        }
+        paired.push({ seconds, value: value(tail[i + 1]) });
+    }
+    return paired;
+}
+/**
+ * Register `frames` and `stepped`, each drawn for the moment `frameTime`
+ * reports when the template is evaluated: seconds on the host's own
+ * timeline, from whatever zero it counts from. The functions exist whatever
+ * `frameTime` returns, so a template compiles once and is evaluated at every
+ * moment the host draws.
+ */
+export function animationFuncs(frameTime) {
+    const framesFunc = {
+        fn: ((...tail) => {
+            const frames = pairs("frame", tail, asFragment).map(({ seconds, value }) => ({ seconds, text: value }));
+            return new FrameSequence(frames).text(frameTime());
+        }),
+        argTypes: ["float", "liftable"],
+        arity: { kind: "alternating", minimum: 2 },
+        returnType: "T",
+    };
+    const steppedFunc = {
+        fn: ((...tail) => {
+            const steps = pairs("color", tail, (v) => asColor(v, "stepped"));
+            return steps[beat(steps.map((step) => step.seconds)).at(frameTime())].value.hex;
+        }),
+        argTypes: ["float", "string"],
+        arity: { kind: "alternating", minimum: 2 },
+        returnType: "string",
+    };
+    return { frames: framesFunc, stepped: steppedFunc };
+}

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

@@ -57,6 +57,19 @@
  */
 import type { FuncMap, TemplateFunc } from "@promptctl/go-template-js";
 import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
+/**
+ * The gate every color argument crosses. [LAW:parse-dont-validate] — the
+ * function bodies below receive `ColorRgba` and never re-check.
+ *
+ * Parsing itself is `parseHexColor`'s job; this wrapper exists only to replace
+ * its error *wording*, because the mistake it catches is almost always the
+ * same one — a palette name passed where a color belongs (`darken "primary" 2`)
+ * — and an author who reads "wrap it: darken (color "primary")" is corrected in
+ * one step, where "expected #RRGGBB" leaves them guessing. What it parses
+ * must then be a colour these functions can compute with (`computable`).
+ * [LAW:no-silent-failure]
+ */
+export declare function asColor(value: string, func: string): ColorRgba;
 /**
  * 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

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

@@ -70,7 +70,7 @@ import { darken, contrastFor, ensureContrast } from "../themes/colorMath.js";
  * must then be a colour these functions can compute with (`computable`).
  * [LAW:no-silent-failure]
  */
-function asColor(value, func) {
+export function asColor(value, func) {
     let colour;
     try {
         colour = parseHexColor(value.trim());

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

@@ -24,3 +24,9 @@ import { RichText } from "../core/text.js";
  * before the render whose theme says what the name stands for.
  */
 export declare function applyStyleToFragment(child: unknown, style: Style): RichText;
+/**
+ * The gate every `"liftable"` slot's value crosses: the binding's own `T`, or
+ * a loud failure. [LAW:parse-dont-validate] What leaves is a `RichText`, so
+ * no body re-checks it.
+ */
+export declare function asFragment(child: unknown): RichText;

package/dist/template-bindings/helpers.js

@@ -24,10 +24,19 @@ import { RichText } from "../core/text.js";
  * before the render whose theme says what the name stands for.
  */
 export function applyStyleToFragment(child, style) {
+    const fragment = asFragment(child);
+    const result = fragment.copy();
+    result.style = layerStyle(fragment.style, style);
+    return result;
+}
+/**
+ * The gate every `"liftable"` slot's value crosses: the binding's own `T`, or
+ * a loud failure. [LAW:parse-dont-validate] What leaves is a `RichText`, so
+ * no body re-checks it.
+ */
+export function asFragment(child) {
     if (!(child instanceof RichText)) {
         throw new TypeError(`template function expected a RichText fragment, got ${typeof child === "object" ? Object.prototype.toString.call(child) : typeof child}`);
     }
-    const result = child.copy();
-    result.style = layerStyle(child.style, style);
-    return result;
+    return child;
 }

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

@@ -13,8 +13,11 @@
  *   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]
+ *   palette exists. [LAW:one-way-deps]
+ * - `animationFuncs(frameTime)` — `frames` and `stepped`, a fragment and a
+ *   colour drawn for a moment. It is the only registration that knows the
+ *   template is evaluated at a time, and the time is 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)`
@@ -40,6 +43,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 } 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

@@ -13,8 +13,11 @@
  *   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]
+ *   palette exists. [LAW:one-way-deps]
+ * - `animationFuncs(frameTime)` — `frames` and `stepped`, a fragment and a
+ *   colour drawn for a moment. It is the only registration that knows the
+ *   template is evaluated at a time, and the time is 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)`
@@ -41,6 +44,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 } 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",