@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/renderables/tree.js

@@ -5,7 +5,7 @@ import { Segment } from "../core/segment.js";
 import { cellFit, cellLen, asCellCol } from "../core/cells.js";
 import { Style, NULL_STYLE } from "../core/style.js";
 import { embed } from "./embed.js";
-import { drawable, getStyle, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { drawable, getStyle, render, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { Measurement } from "../core/measure.js";
 /** Every glyph of every set is this wide, so a row's guides are as wide however they are drawn. */
 const GUIDE_CELLS = 4;
@@ -62,6 +62,12 @@ export class Tree {
             yield* this._renderRow(options, row);
         }
     }
+    // Every label `render` draws, from the same walk. Not `children`, which is
+    // the subtrees, as Rich names them.
+    *contents() {
+        for (const row of this._walk())
+            yield row.label;
+    }
     /**
      * The rows `render` and `measure` both read, entered in exactly one place so
      * the two cannot start the walk differently. A hidden root takes its own row
@@ -115,9 +121,9 @@ export class Tree {
      * [LAW:single-enforcer] Tree also owns its row boundaries here rather than
      * depending on label renderables to invent trailing newlines: the label's
      * output is cut into lines and every line ends where Tree ends it. A label
-     * that emits nothing still holds its row, and one that ends in a newline of
-     * its own gets the blank row that line is, as in Rich — padded to the label's
-     * width when the label is justified.
+     * that emits nothing — one left no column, say — has no row, and one
+     * that ends in a newline of its own gets the blank row that line is, as in
+     * Rich — padded to the label's width when the label is justified.
      *
      * The node's style sits under the label's own, as Rich's `Styled` puts it, so
      * markup in the label still wins; its background alone reaches under the
@@ -140,9 +146,7 @@ export class Tree {
         // guides were fitted into. No highlighter: a label is drawn plain, as
         // Rich's `Tree` hands its labels `highlight=False`.
         const labelOptions = { ...options, highlight: false, maxWidth: width, height: stackedHeight(options.height) };
-        const lines = Segment.splitLines(Segment.applyStyle(Segment.cropLines(row.label.render(labelOptions), width), style));
-        if (lines.length === 0)
-            lines.push([]);
+        const lines = Segment.splitLines(Segment.applyStyle(Segment.cropLines(render(row.label, labelOptions), width), style));
         for (let i = 0; i < lines.length; i++) {
             let left = options.maxWidth;
             for (let g = 0; g < row.guides.length; g++) {

package/dist/renderables/viewport.d.ts

@@ -19,9 +19,9 @@
  * against exists before a render: the rows come from the budget the render is
  * handed, and the content's length from rendering it at the width it is handed.
  * So `scrollTo`, `scrollBy` and `ensureVisible` do not move anything when they
- * are called. Each queues a move, and the next render resolves the queue in
- * call order, clamping after every move, against the rows and length that
- * render found. Calling an operation before the first render, or three of them
+ * are called. Each queues a move, and the next render that draws the content
+ * resolves the queue in call order, clamping after every move, against the
+ * rows and length that render found. Calling an operation before the first render, or three of them
  * between two renders, is the same code path as calling one.
  *
  * Every cell of its rows, gutter included, is stamped as its own
@@ -33,7 +33,7 @@
  */
 import { Segment } from "../core/segment.js";
 import type { Style } from "../core/style.js";
-import type { Measurable, Renderable, RenderOptions, Scrollable } from "../core/protocol.js";
+import type { Composite, Measurable, Renderable, RenderOptions, Scrollable } from "../core/protocol.js";
 /** How one part of a scrollbar draws each row it covers. */
 export interface ScrollbarPart {
     readonly glyph: string;
@@ -60,7 +60,7 @@ export interface ViewportOptions {
     /** A scrollbar down the right edge. Absent, the content has the full width. */
     scrollbar?: Scrollbar;
 }
-export declare class Viewport implements Renderable, Measurable, Scrollable {
+export declare class Viewport implements Renderable, Measurable, Scrollable, Composite {
     /**
      * What the viewport shows. Replace it to show new content from the same
      * scroll position — a view rebuilt every frame keeps one `Viewport`.
@@ -113,7 +113,15 @@ export declare class Viewport implements Renderable, Measurable, Scrollable {
     contentWidth(width: number): number;
     /** The cells the scrollbar's gutter takes beside the content. */
     get gutter(): number;
+    contents(): Iterable<Renderable>;
     render(rawOptions: RenderOptions): Iterable<Segment>;
+    /**
+     * What a render that drew the content found, made the viewport's: `extent`
+     * is the rows and length the next move is clamped against, a followed range
+     * that was in view is kept in view if the rows changed, and the queued moves
+     * resolve into the offset this returns.
+     */
+    private commit;
     /**
      * [LAW:one-source-of-truth] Where the queued moves leave the offset against
      * `extent`: what a render commits, and what `canScrollBy` asks from.

package/dist/renderables/viewport.js

@@ -19,9 +19,9 @@
  * against exists before a render: the rows come from the budget the render is
  * handed, and the content's length from rendering it at the width it is handed.
  * So `scrollTo`, `scrollBy` and `ensureVisible` do not move anything when they
- * are called. Each queues a move, and the next render resolves the queue in
- * call order, clamping after every move, against the rows and length that
- * render found. Calling an operation before the first render, or three of them
+ * are called. Each queues a move, and the next render that draws the content
+ * resolves the queue in call order, clamping after every move, against the
+ * rows and length that render found. Calling an operation before the first render, or three of them
  * between two renders, is the same code path as calling one.
  *
  * Every cell of its rows, gutter included, is stamped as its own
@@ -35,7 +35,8 @@ 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, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { drawable, drawsNothing, fitHeight, getStyle, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { render } 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" },
@@ -125,26 +126,27 @@ export class Viewport {
     get gutter() {
         return gutterWidth(this.scrollbar);
     }
+    *contents() {
+        yield this.content;
+    }
     *render(rawOptions) {
         const { height, ...options } = withBoundedWidth(rawOptions, this);
         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 });
-        // [LAW:no-ambient-temporal-coupling] The thumb is drawn from the offset
-        // this render just resolved, not from `offset` as it stood before it.
-        const thumb = thumbRows(extent, this._offset);
+        const lines = Segment.splitLines(render(this.content, { ...options, maxWidth: contentWidth }));
+        // [LAW:no-ambient-temporal-coupling] Content handed no column is held, not
+        // drawn, so this render learns its budget but not the content's length. It
+        // commits nothing: the offset, the followed range and the queued moves wait
+        // for a render that draws, and this one draws the scrollbar against the
+        // length the last one found.
+        const held = drawsNothing({ maxWidth: contentWidth });
+        const length = held ? this._extent.lines : lines.length;
+        const extent = { rows: viewRows(height, this.rows, length), lines: length };
+        const offset = held ? clampOffset(this._offset, extent) : this.commit(extent);
+        const shown = fitHeight(lines.slice(offset, offset + extent.rows), { rows: extent.rows, exact: true });
+        // The thumb is drawn from the offset this render resolved, not from
+        // `offset` as it stood before it.
+        const thumb = thumbRows(extent, offset);
         // The content's cells and the gutter's drawn cells sum to the offer: a
         // gutter wider than the whole offer is drawn cropped to it.
         const drawn = Math.min(gutter, options.maxWidth);
@@ -168,6 +170,25 @@ export class Viewport {
             yield Segment.line();
         }
     }
+    /**
+     * What a render that drew the content found, made the viewport's: `extent`
+     * is the rows and length the next move is clamped against, a followed range
+     * that was in view is kept in view if the rows changed, and the queued moves
+     * resolve into the offset this returns.
+     */
+    commit(extent) {
+        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 = [];
+        return this._offset;
+    }
     /**
      * [LAW:one-source-of-truth] Where the queued moves leave the offset against
      * `extent`: what a render commits, and what `canScrollBy` asks from.

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, frameAt } 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 frameAt(new FrameSequence(frames), 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)`
@@ -37,10 +40,12 @@ import { createEngine } from "@promptctl/go-template-js";
 import { RichText } from "../core/text.js";
 import { Style } from "../core/style.js";
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
 import { richTextStyleFuncs } from "./style-funcs.js";
 import { colorFuncs } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
 export { colorFuncs, readableOnFunc } from "./color-funcs.js";
+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
@@ -127,7 +132,7 @@ export function renderTemplate(engine, source, scope = {}, options) {
     catch (e) {
         return [new Segment(errorLine(e, maxWidth), safeErrorStyle(errorStyle))];
     }
-    return Array.from(text.render({ isTerminal: true, ...renderOptions, maxWidth }));
+    return Array.from(render(text, { isTerminal: true, ...renderOptions, maxWidth }));
 }
 /**
  * A caught error as the one line `renderTemplate` promises. The summary is the

package/dist/themes/ramp.d.ts

@@ -20,12 +20,14 @@
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
- * [LAW:one-way-deps] Imports `core/color`, `core/easing` and `core/oklch`
- * only; nothing here knows what a palette is. Resolving stop *names* is the template binding's
+ * [LAW:one-way-deps] Imports `core/color`, `core/easing`, `core/oklch`,
+ * and for `over`, `core/animation` and `core/tween`; nothing here knows
+ * what a palette is. Resolving stop *names* is the template binding's
  * job (`paletteFuncs`), which hands this module resolved colors.
  */
+import { Animation } from "../core/animation.js";
 import type { ColorRgba } from "../core/color.js";
-import type { Ease } from "../core/easing.js";
+import { type Ease } from "../core/easing.js";
 /** One stop: the color the ramp is exactly `color` at position `at`. */
 export interface ColorStop {
     readonly at: number;
@@ -67,4 +69,17 @@ export declare class ColorRamp {
      * where it does: a ramp never paints outside its stops.
      */
     at(value: number): ColorRgba;
+    /**
+     * This ramp read over time: its span of positions, from the first stop's
+     * to the last's, crossed at a steady rate in `seconds` and held at the last
+     * stop from then on, each colour along the way the ramp's own. A colour
+     * tween is a two-stop ramp over its seconds — the ramp's ease shaping the
+     * move, so `new ColorRamp(ease, [{ at: 0, color: a }, { at: 1, color: b
+     * }]).over(seconds)` is `a` eased to `b` — and a ramp of more stops over
+     * time is a sweep through all of them. [LAW:one-source-of-truth] The
+     * blending is `at`'s; what time adds is `tween`'s (`core/tween.ts`), so a
+     * host sampling once a second or sixty times reads the stop colours byte
+     * for byte where `at` paints them.
+     */
+    over(seconds: number): Animation<ColorRgba>;
 }

package/dist/themes/ramp.js

@@ -20,11 +20,15 @@
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
- * [LAW:one-way-deps] Imports `core/color`, `core/easing` and `core/oklch`
- * only; nothing here knows what a palette is. Resolving stop *names* is the template binding's
+ * [LAW:one-way-deps] Imports `core/color`, `core/easing`, `core/oklch`,
+ * and for `over`, `core/animation` and `core/tween`; nothing here knows
+ * what a palette is. Resolving stop *names* is the template binding's
  * job (`paletteFuncs`), which hands this module resolved colors.
  */
+import { Animation } from "../core/animation.js";
+import { EASES } from "../core/easing.js";
 import { Oklch } from "../core/oklch.js";
+import { tween } from "../core/tween.js";
 /**
  * An immutable ramp over stops sorted by position.
  *
@@ -100,4 +104,21 @@ export class ColorRamp {
             return to.color;
         return Oklch.fromRgba(from.color).mix(Oklch.fromRgba(to.color), t).toRgba();
     }
+    /**
+     * This ramp read over time: its span of positions, from the first stop's
+     * to the last's, crossed at a steady rate in `seconds` and held at the last
+     * stop from then on, each colour along the way the ramp's own. A colour
+     * tween is a two-stop ramp over its seconds — the ramp's ease shaping the
+     * move, so `new ColorRamp(ease, [{ at: 0, color: a }, { at: 1, color: b
+     * }]).over(seconds)` is `a` eased to `b` — and a ramp of more stops over
+     * time is a sweep through all of them. [LAW:one-source-of-truth] The
+     * blending is `at`'s; what time adds is `tween`'s (`core/tween.ts`), so a
+     * host sampling once a second or sixty times reads the stop colours byte
+     * for byte where `at` paints them.
+     */
+    over(seconds) {
+        const first = this.stops[0].at;
+        const last = this.stops[this.stops.length - 1].at;
+        return Animation.map(tween(first, last, { seconds, ease: EASES.linear }), (value) => this.at(value));
+    }
 }

package/dist/widgets/focus-manager.d.ts

@@ -6,18 +6,23 @@
  */
 import type { InteractiveWidget, FocusManager, KeyEvent } from "./types.js";
 import type { Unsubscribe } from "../core/subscription.js";
+/** What focus follows: the frame a `WidgetApp` just painted. */
+export interface FocusView {
+    /** Every widget the view holds, in document order, whether or not it has a cell on screen. */
+    present(): readonly InteractiveWidget[];
+    /** The widgets with a cell on the frame on screen, in document order. */
+    onScreen(): readonly InteractiveWidget[];
+}
 export declare class DefaultFocusManager implements FocusManager {
-    private readonly onScreen;
+    private readonly view;
     accessor currentWidget: InteractiveWidget | null;
     private readonly changeHandlers;
     /**
-     * `onScreen` is the widgets on the frame on screen, in document order.
-     *
-     * [LAW:one-source-of-truth] It is asked every time rather than kept: a list
-     * of the widgets held here would be a second picture of the frame, and
-     * wrong from the next paint.
+     * [LAW:one-source-of-truth] The view is asked every time rather than kept:
+     * a list of the widgets held here would be a second picture of the frame,
+     * and wrong from the next paint.
      */
-    constructor(onScreen: () => readonly InteractiveWidget[]);
+    constructor(view: FocusView);
     get current(): InteractiveWidget | null;
     get widgets(): readonly InteractiveWidget[];
     next(): void;
@@ -25,20 +30,22 @@ export declare class DefaultFocusManager implements FocusManager {
     focus(widget: InteractiveWidget): void;
     /**
      * Put focus where the frame just painted lets it rest: it stays on a widget
-     * the view drew (`drawn`) that can take it, and otherwise moves to the first
-     * one on screen that can, or to none.
+     * the view holds (`present`) that can take it, and otherwise moves to the
+     * first one on screen that can, or to none.
      *
-     * Drawn, not on screen: a widget cropped for the moment — the terminal
-     * shrank, a viewport scrolled, an overlay covers it — is still in the view,
-     * and keeps focus and whatever focus holds, like a half-typed filter.
+     * In the view, not on screen: a widget cropped for the moment — the
+     * terminal shrank, a viewport scrolled, an overlay covers it, its container
+     * handed it no column — is still in the view, and keeps focus and whatever
+     * focus holds, like a half-typed filter.
      *
      * [LAW:single-enforcer] The one place focus follows the frame — onto the
-     * first widget when the app starts, off a widget that stopped being drawn
+     * first widget when the app starts, off a widget that left the view
      * or was disabled.
      */
-    settle(drawn: readonly InteractiveWidget[]): void;
+    settle(): void;
     onChange(handler: (current: InteractiveWidget | null) => void): Unsubscribe;
     handleKey(event: KeyEvent): void;
+    private step;
     private clear;
     private setFocus;
     private emitChange;