@promptctl/rich-js 0.23.0 → 0.24.0

package/dist/core/clock.d.ts

@@ -42,7 +42,15 @@ export interface Clock {
     now(): number;
     /** Call `tick` once a frame at `rate` until the returned function is called. */
     every(rate: FrameRate, tick: () => void): Unsubscribe;
+    /**
+     * Call `tick` once, when this clock reads `time` — as soon as it can for a
+     * time already past — unless the returned function is called first. What
+     * a host that knows when its frame next changes (`Segment.nextChange`)
+     * waits on. A `time` further off than a timer can wait, about 24.8 days,
+     * throws, as `frameRate` refuses the rate.
+     */
+    at(time: number, tick: () => void): Unsubscribe;
 }
-/** The platform's monotonic clock and its interval timer. */
+/** The platform's monotonic clock and its timers. */
 export declare function systemClock(): Clock;
 export {};

package/dist/core/clock.js

@@ -30,13 +30,33 @@ export function frameRate(perSecond) {
     }
     return { perSecond, interval: 1 / perSecond };
 }
-/** The platform's monotonic clock and its interval timer. */
+/** The platform's monotonic clock and its timers. */
 export function systemClock() {
+    const now = () => performance.now() / 1000;
     return {
-        now: () => performance.now() / 1000,
+        now,
         every: (rate, tick) => {
             const timer = setInterval(tick, rate.interval * 1000);
             return () => clearInterval(timer);
         },
+        at: (time, tick) => {
+            if (!(time - now() <= LONGEST_INTERVAL)) {
+                throw new RangeError(`a clock waits at most ${LONGEST_INTERVAL} s, not until ${time} s from ${now()} s`);
+            }
+            // [LAW:single-enforcer] A platform timer is due by a whole millisecond
+            // of the event loop's own time, truncated, so it can run while this
+            // clock still reads under `time` — by most of a millisecond. The
+            // contract is the clock's reading, and it is held here, once, for every
+            // host: the wait is rounded up, and a timer that runs early is armed
+            // again for what remains, so `tick` runs when `now()` has reached
+            // `time` and not before. A host re-drawing at a frame's end would
+            // otherwise draw the old frame again and wait again, every boundary.
+            let timer;
+            const arm = () => {
+                timer = setTimeout(() => (now() < time ? arm() : tick()), Math.ceil(Math.max(0, time - now()) * 1000));
+            };
+            arm();
+            return () => clearTimeout(timer);
+        },
     };
 }

package/dist/core/color.d.ts

@@ -259,6 +259,16 @@ export declare class ColorSpec {
      * on a ground (`flattenAlpha`).
      */
     static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec;
+    /**
+     * Every colour `depth` writes by index, each with the colour a terminal
+     * known to show `theme` draws it in, lowest index first: the theme's
+     * sixteen, and at 256 colours the cube and grey ramp after them. Each is
+     * drawn alike as glyph and as ground, which the default colour is not, so
+     * it is not among them. Truecolor writes a colour itself and the default
+     * depth only the default, so neither writes any by index. The colours
+     * `matchOn` rounds to, but for the default, read off the same two tables.
+     */
+    static indexed(depth: ColorDepth, theme: TerminalTheme): readonly (readonly [ColorSpec, ColorRgba])[];
     /**
      * The spec a slot is written in once its colour moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or

package/dist/core/color.js

@@ -614,9 +614,11 @@ export class ColorSpec {
             return ColorSpec.fromRgba(value);
         if (depth === ColorDepth.DEFAULT)
             return ColorSpec.default();
-        const slot = theme.ansiColors.match(value);
         // [LAW:dataflow-not-control-flow] Every candidate is scored; the depth
         // only decides whether the cube is among them. Ties go to the earlier.
+        // Each table's nearest stands in for all of it: the tables' `match` is
+        // memoised and ranks by this distance, so the winner is `indexed`'s.
+        const slot = theme.ansiColors.match(value);
         const candidates = [
             [ColorSpec.default(), foreground ? theme.foregroundColor : theme.backgroundColor],
             [new ColorSpec(`color(${slot})`, depth === ColorDepth.WINDOWS ? depth : ColorDepth.STANDARD, slot), theme.ansiColors.get(slot)],
@@ -624,6 +626,22 @@ export class ColorSpec {
         ];
         return candidates.reduce((best, next) => (rgbDistance(next[1], value) < rgbDistance(best[1], value) ? next : best))[0];
     }
+    /**
+     * Every colour `depth` writes by index, each with the colour a terminal
+     * known to show `theme` draws it in, lowest index first: the theme's
+     * sixteen, and at 256 colours the cube and grey ramp after them. Each is
+     * drawn alike as glyph and as ground, which the default colour is not, so
+     * it is not among them. Truecolor writes a colour itself and the default
+     * depth only the default, so neither writes any by index. The colours
+     * `matchOn` rounds to, but for the default, read off the same two tables.
+     */
+    static indexed(depth, theme) {
+        const byDepth = indexedMemo.get(theme) ?? new Map();
+        indexedMemo.set(theme, byDepth);
+        const listed = byDepth.get(depth) ?? listIndexed(depth, theme);
+        byDepth.set(depth, listed);
+        return listed;
+    }
     /**
      * The spec a slot is written in once its colour moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
@@ -670,6 +688,23 @@ function cubeCandidate(value) {
     const index = EIGHT_BIT_DOWNGRADE_TABLE.match(value);
     return [ColorSpec.fromAnsi(index), EIGHT_BIT_DOWNGRADE_TABLE.get(index)];
 }
+/** `ColorSpec.indexed`'s list, made once for each theme and depth. */
+const indexedMemo = new WeakMap();
+function listIndexed(depth, theme) {
+    const slots = () => Array.from({ length: 16 }, (_, slot) => [new ColorSpec(`color(${slot})`, depth === ColorDepth.WINDOWS ? depth : ColorDepth.STANDARD, slot), theme.ansiColors.get(slot)]);
+    switch (depth) {
+        case ColorDepth.TRUECOLOR:
+        case ColorDepth.DEFAULT:
+            return [];
+        case ColorDepth.STANDARD:
+        case ColorDepth.WINDOWS:
+            return slots();
+        case ColorDepth.EIGHT_BIT: {
+            const { firstIndex, size } = EIGHT_BIT_DOWNGRADE_TABLE;
+            return [...slots(), ...Array.from({ length: size }, (_, i) => [ColorSpec.fromAnsi(firstIndex + i), EIGHT_BIT_DOWNGRADE_TABLE.get(firstIndex + i)])];
+        }
+    }
+}
 function mix(from, to, t, theme) {
     return blendRgb(from.getTruecolor(theme), to.getTruecolor(theme), t);
 }

package/dist/core/easing.d.ts

@@ -75,6 +75,37 @@ export type EaseName = keyof typeof EASES;
  * Unknown names throw naming every legal one. [LAW:no-silent-failure]
  */
 export declare function parseEase(name: string): Ease;
+/**
+ * A beat: holds of given lengths in seconds, played in order and looped, the
+ * way the frames of an animation are each held and then replaced. `at(t)` is
+ * the index of the hold in progress at `t`, counted from the first hold at
+ * `t = 0`, and the sequence wraps every `period` seconds, before zero too,
+ * as `Phase.loop` wraps. With equal holds `at` is `steps(n)` read as an
+ * index; the holds here may differ, which `steps` cannot say, so a frame
+ * held for a second and the next for a quarter are one beat.
+ */
+export interface Beat {
+    readonly holds: readonly number[];
+    /** The sum of the holds: how long one pass takes, in seconds. */
+    readonly period: number;
+    /** Which hold is in progress at `t` seconds: an index into `holds`. */
+    at(t: number): number;
+    /**
+     * When the hold in progress at `t` began, in seconds on `t`'s own
+     * timeline: what a sample-and-hold on this beat reads at `t`. Every `t`
+     * inside one hold of one pass answers the same number, to the bit, so an
+     * effect handed it draws the same frame throughout.
+     */
+    start(t: number): number;
+    /**
+     * When the hold in progress at `t` ends, in seconds on `t`'s own timeline:
+     * the start of the next hold, the first moment `at` places in it, so it is
+     * always after `t`. What is drawn on this beat at `t` is drawn until then.
+     */
+    end(t: number): number;
+}
+/** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
+export declare function beat(holds: readonly number[]): Beat;
 /** The three phase shapes. Each takes seconds and returns a `Phase`. */
 export declare const Phase: {
     /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */

package/dist/core/easing.js

@@ -148,6 +148,111 @@ function positiveSeconds(what, seconds) {
         throw new RangeError(`${what} must be a positive number of seconds, got ${seconds}`);
     }
 }
+/**
+ * The seconds into the current pass of a `period` at `t`: `t` taken modulo
+ * the period, into [0, period), before zero too. [LAW:single-enforcer] The
+ * one wrap `Phase.loop` and `beat` both read time through, so a `t` that is
+ * not a finite number of seconds fails here, loudly, and nowhere else. A
+ * `t` at or past zero is `t % period` alone, which is exact; only a negative
+ * `t` is carried up by a period, so a boundary a host samples exactly lands
+ * on the pass that begins there, and the answer is always under the period.
+ */
+function wrapSeconds(what, t, period) {
+    if (!Number.isFinite(t))
+        throw new RangeError(`${what} needs a finite t, got ${t}`);
+    const into = t % period;
+    if (into >= 0)
+        return into;
+    // A negative epsilon carried up rounds to the period itself; that is the
+    // start of the next pass, never a point past the end of this one.
+    const carried = into + period;
+    return carried >= period ? 0 : carried;
+}
+/**
+ * The float after `x`: one ulp up, away from zero for a positive `x` and
+ * toward it for a negative one, read through the bits of the double.
+ */
+function nextUp(x) {
+    if (x === 0)
+        return Number.MIN_VALUE;
+    DOUBLE[0] = x;
+    BITS[0] = BITS[0] + (x > 0 ? 1n : -1n);
+    return DOUBLE[0];
+}
+const DOUBLE = new Float64Array(1);
+const BITS = new BigUint64Array(DOUBLE.buffer);
+/** How many ulps the two roundings in `Beat.start`'s sum can put it under the hold's boundary; a walk past this is a hold too fine for the time. */
+const ULPS_OF_ROUNDING = 8;
+/** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
+export function beat(holds) {
+    if (holds.length === 0)
+        throw new RangeError("a beat needs at least one hold");
+    holds.forEach((hold, i) => positiveSeconds(`beat hold ${i}`, hold));
+    const period = holds.reduce((sum, hold) => sum + hold, 0);
+    // Where each hold begins, in seconds into the period: the unit
+    // `wrapSeconds` answers in, so the sum a boundary sits at is the number
+    // the wrap of a `t` on that boundary produces, and the hold that begins
+    // there is the one in progress, at any rate the host samples.
+    const starts = [];
+    let elapsed = 0;
+    for (const hold of holds) {
+        starts.push(elapsed);
+        elapsed += hold;
+    }
+    // A copy, and the one `at` walks: what `at` and `period` were built from
+    // stays what `holds` says whatever the caller does to its array.
+    const own = [...holds];
+    // The last hold whose start the time has reached. The first starts at
+    // 0, so the walk always stops, and its length is the count of holds,
+    // never a function of `t`.
+    const index = (into) => {
+        let i = own.length - 1;
+        while (starts[i] > into)
+            i--;
+        return i;
+    };
+    // Where hold `i` of pass `pass` begins: the pass's start plus the hold's,
+    // two integers and two constants, so every `t` in the hold builds the one
+    // float. That sum can land an ulp or two under the boundary when the holds
+    // are not exact in binary — a tenth of a second is not — and `at` would
+    // then read it as the hold before, so it is walked up to the first float
+    // `at` places in the hold. The walk is a function of the pass and the hold
+    // alone, so every `t` in the hold still answers one float.
+    const boundary = (what, pass, i, t) => {
+        let began = pass * period + starts[i];
+        for (let walked = 0; index(wrapSeconds(what, began, period)) !== i; walked++) {
+            // The sum is off by the rounding of two operations, under the few
+            // ulps allowed here; a walk that long means the hold is narrower
+            // than the floats around `t` are apart, so no float starts it.
+            if (walked === ULPS_OF_ROUNDING)
+                throw new RangeError(`${what}: hold ${i} (${own[i]} s) is finer than time resolves near t = ${t}`);
+            began = nextUp(began);
+        }
+        return began;
+    };
+    // Which pass `t` is in, as a whole number: `t - into` is a whole number of
+    // periods but for rounding, which `round` takes off; carrying `starts[i]`
+    // out of `t` itself would leave each sample its own rounding.
+    const pass = (t, into) => Math.round((t - into) / period);
+    return {
+        holds: own,
+        period,
+        at(t) {
+            return index(wrapSeconds("Beat.at", t, period));
+        },
+        start(t) {
+            const into = wrapSeconds("Beat.start", t, period);
+            return boundary("Beat.start", pass(t, into), index(into), t);
+        },
+        // The next hold's start, in the next pass when this hold is the last.
+        end(t) {
+            const into = wrapSeconds("Beat.end", t, period);
+            const i = index(into);
+            const last = i === own.length - 1;
+            return boundary("Beat.end", pass(t, into) + (last ? 1 : 0), last ? 0 : i + 1, t);
+        },
+    };
+}
 /** The three phase shapes. Each takes seconds and returns a `Phase`. */
 export const Phase = {
     /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */
@@ -160,7 +265,7 @@ export const Phase = {
     /** 0 → 1 every `period` seconds, wrapping back to 0; negative `t` wraps too. */
     loop(period) {
         positiveSeconds("Phase.loop period", period);
-        return (t) => (((t % period) + period) % period) / period;
+        return (t) => wrapSeconds("Phase.loop", t, period) / period;
     },
     /** 0 → 1 → 0 every `period` seconds: there in the first half, back in the second. */
     pingPong(period) {

package/dist/core/segment.d.ts

@@ -51,6 +51,16 @@ export declare class Segment {
      * the owner's row that `lines[0]` is, for output that arrives in pieces.
      */
     static anchorLines(lines: Segment[][], owner: object, firstRow?: number): Segment[][];
+    /**
+     * When what `segments` show next changes, in seconds on the timeline of
+     * whoever drew them: the soonest `Style.nextChange` among them, read off
+     * the composed frame the way `anchorAt` reads an owner — `t` itself for a
+     * frame something in moves every frame, `Infinity` for one that never
+     * changes. What a host that drew the frame at `t` asks before drawing
+     * again: a frame of frames answers the next frame's start, a transition
+     * `t` until it is done, still content never.
+     */
+    static nextChange(segments: Iterable<Segment>): number;
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.

package/dist/core/segment.js

@@ -91,6 +91,21 @@ export class Segment {
             });
         });
     }
+    /**
+     * When what `segments` show next changes, in seconds on the timeline of
+     * whoever drew them: the soonest `Style.nextChange` among them, read off
+     * the composed frame the way `anchorAt` reads an owner — `t` itself for a
+     * frame something in moves every frame, `Infinity` for one that never
+     * changes. What a host that drew the frame at `t` asks before drawing
+     * again: a frame of frames answers the next frame's start, a transition
+     * `t` until it is done, still content never.
+     */
+    static nextChange(segments) {
+        let soonest = Number.POSITIVE_INFINITY;
+        for (const segment of segments)
+            soonest = Math.min(soonest, segment.style?.nextChange ?? Number.POSITIVE_INFINITY);
+        return soonest;
+    }
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.

package/dist/core/strip.d.ts

@@ -156,22 +156,49 @@ export interface JoinCell {
     readonly bg: CellColor;
 }
 /**
- * The cells a joiner draws at each kind of join:
- *   • `seam` — between two neighbours;
+ * A cell of a seam, or one of the joiner's caps standing in a seam's place:
+ * `{ cap: "tail" }` closes the run the seam leaves, `{ cap: "lead" }` opens the
+ * run it enters, drawn as whatever caps the seam is joined with. That is how
+ * a seam that parts its runs — `capsule`, `metro` — ends each in the caps
+ * picked for it rather than in caps of its own.
+ */
+export type SeamCell = JoinCell | {
+    readonly cap: "lead" | "tail";
+};
+/**
+ * What a joiner draws between two neighbours, in one form:
+ *   • `seam` — the cells between them;
  *   • `divider` — in the seam's place where every seam cell's ink is drawn
  *     indistinct from its own ground (see `SEAM_MIN_DELTA_E`), so the seam
- *     would vanish;
- *     the same width as `seam`;
+ *     would vanish; the same width as `seam`.
+ */
+export interface SeamForm {
+    readonly seam: readonly SeamCell[];
+    readonly divider: readonly SeamCell[];
+}
+/**
+ * What a joiner draws at the ends of a run, in one form:
  *   • `lead` — where a run is entered from nothing: the strip's start, or a
  *     neighbour with no ground for the seam to paint. It cannot name `left`;
  *   • `tail` — where a run leaves into nothing. It cannot name `right`.
  */
-export interface JoinShape {
-    readonly seam: readonly JoinCell[];
-    readonly divider: readonly JoinCell[];
+export interface CapsForm {
     readonly lead: readonly JoinCell[];
     readonly tail: readonly JoinCell[];
 }
+/**
+ * The middle of a joiner: its seam, and the `ascii` seam an ASCII-only output
+ * draws instead. Picked apart from the caps, so any seam ends in any caps.
+ */
+export interface JoinSeam {
+    readonly glyph: SeamForm;
+    readonly ascii: SeamForm;
+}
+/** The ends of a joiner: its caps, and the `ascii` caps an ASCII-only output draws instead. */
+export interface JoinCaps {
+    readonly glyph: CapsForm;
+    readonly ascii: CapsForm;
+}
 /**
  * The least ΔE_OK a seam cell's ink must differ from its own ground by for the
  * seam to be seen. Below it the eye cannot tell the ink from the ground,
@@ -180,28 +207,70 @@ export interface JoinShape {
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
 /**
- * The one joiner: what it draws at each join is the `JoinShape` it is given,
- * so a new joiner is a value, never a class.
+ * The one joiner: what it draws is a `JoinSeam` between neighbours and a
+ * `JoinCaps` at the ends of each run, picked independently, so a new joiner is
+ * a pair of values, never a class.
  *
  * Which part a join draws is read off its two neighbours. A neighbour is
  * missing at the strip's ends, and counts as missing — an endpoint — when the
- * shape paints with its ground anywhere and it has none to paint. With both present the
- * join is the seam, or the divider where every seam cell's ink is drawn
- * indistinct from its ground at `options.colorSystem`; with only the right, the lead; with only
- * the left, the tail; with neither, nothing.
+ * seam paints with its ground anywhere and it has none to paint. With both
+ * present the join is the seam, or the divider where every seam cell's ink is
+ * drawn indistinct from its ground at `options.colorSystem`; with only the
+ * right, the lead; with only the left, the tail; with neither, nothing. A cap
+ * that paints with its neighbour's ground is drawn only beside a neighbour
+ * with one, so caps that need grounds never stop a seam that needs none.
  *
- * `ascii` is the shape an ASCII-only output draws instead, whole.
+ * An ASCII-only output draws the `ascii` form of both, whole.
  */
 export declare class CellJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    readonly shape: JoinShape;
-    readonly ascii: JoinShape;
+    readonly seam: JoinSeam;
+    readonly caps: JoinCaps;
     private readonly _forms;
-    constructor(shape: JoinShape, ascii: JoinShape);
+    constructor(seam: JoinSeam, caps: JoinCaps);
     join(left: T | null, right: T | null, { index }: JoinContext): Renderable;
 }
 /**
- * The bundled joiners, by name. What each draws is `docs/strip.md`'s
- * "Built-in joiners"; a name from config is read with `joinerNamed`.
+ * The bundled seams, by name: what a joiner draws between two neighbours.
+ * What each draws is `docs/strip.md`'s "Seams"; any of them ends in any of
+ * `CAPS`.
+ */
+export declare const SEAMS: Readonly<{
+    powerline: JoinSeam;
+    prism: JoinSeam;
+    slant: JoinSeam;
+    backslant: JoinSeam;
+    flame: JoinSeam;
+    pixel: JoinSeam;
+    ice: JoinSeam;
+    bubble: JoinSeam;
+    capsule: JoinSeam;
+    wrapper: JoinSeam;
+    metro: JoinSeam;
+    stitch: JoinSeam;
+    torn: JoinSeam;
+    plain: JoinSeam;
+}>;
+/**
+ * The bundled caps, by name: what a joiner draws where a run begins and ends.
+ * What each draws is `docs/strip.md`'s "Caps"; any of them ends any of
+ * `SEAMS`.
+ */
+export declare const CAPS: Readonly<{
+    powerline: JoinCaps;
+    slant: JoinCaps;
+    backslant: JoinCaps;
+    flame: JoinCaps;
+    pixel: JoinCaps;
+    ice: JoinCaps;
+    bubble: JoinCaps;
+    capsule: JoinCaps;
+    wrapper: JoinCaps;
+    flat: JoinCaps;
+}>;
+/**
+ * The bundled joiners, by name: each a seam from `SEAMS` ended in caps from
+ * `CAPS`. What each draws is `docs/strip.md`'s "Built-in joiners"; a name from
+ * config is read with `joinerNamed`.
  */
 export declare const JOINERS: Readonly<{
     powerline: CellJoiner<StyledRenderable>;
@@ -220,16 +289,24 @@ export declare const JOINERS: Readonly<{
     plain: CellJoiner<StyledRenderable>;
 }>;
 /**
- * The bundled joiner `name` names — a name read from config, parsed. Throws on
- * any other string, naming the ones there are; an own-key test, so `toString`
- * and the rest of `Object.prototype` are not joiners.
+ * A joiner as config names it: one of `JOINERS`, or a seam from `SEAMS` ended
+ * in caps from `CAPS`, each named apart.
+ */
+export type JoinerSpec = string | {
+    readonly seam: string;
+    readonly caps: string;
+};
+/**
+ * The joiner `spec` names — a joiner read from config, parsed. Throws on a
+ * name its table lacks, naming the ones there are; an own-key test, so
+ * `toString` and the rest of `Object.prototype` are no one's name.
  */
-export declare function joinerNamed(name: string): CellJoiner;
+export declare function joinerNamed(spec: JoinerSpec): CellJoiner;
 /**
  * A ramp of `steps` cells from the left ground to the right. Each cell is the
  * half block U+258C, ink on its left half and ground on its right, so it
- * carries two samples; ASCII draws a space, keeping the grounds alone. Nothing
- * at the ends, or beside a neighbour with no ground — there is no colour to
- * ramp toward.
+ * carries two samples; ASCII draws a space, keeping the grounds alone. Beside
+ * a neighbour with no ground there is no colour to ramp toward, so that join
+ * draws the caps the ramp is ended in.
  */
-export declare function gradientJoiner(steps?: number): CellJoiner;
+export declare function gradientSeam(steps?: number): JoinSeam;