@promptctl/rich-js 0.25.2 → 0.27.0

package/dist/renderables/lifecycle.d.ts

@@ -10,27 +10,32 @@
  * part of the drawing asks whether it is leaving. Telling it is a new value
  * (`leave`), as every `Timeline` operation is. [LAW:no-ambient-temporal-coupling]
  *
- * Each half is a `Transition` of a `Veil` on its own clock from 0, handed the time since
- * its moment, and its schedule carried onto the host's clock by
- * `Timeline.run` is that half's hold — every frame for a fade, once a hold
- * for one on a beat — so the transition's schedule, and `done` read off it,
- * stays the one rule for where a one-shot ends and when its frame changes,
- * and nothing here measures progress itself. The frames carry no word of
- * their own on when they change: placed, the lifecycle stamps them with its
- * hold at the frame's time (`placedRender`). The exit veils whatever the
- * arrival draws, so an element told to leave while it is still arriving leaves
- * from where it is, never shown whole first — though a colour exit is spread
- * over the cells each frame shows, so a cell the arrival adds can move one
- * already leaving back toward whole (`ownChange`, `./effects.ts`).
- * [LAW:dataflow-not-control-flow]
+ * Each half is a `Half`: handed the element, an `Animation<Renderable>` of
+ * it on the half's own clock from 0, in the shape of the library's other
+ * one-shot from renderables to an animation (`Change`, `./change.ts`). One
+ * value carries the half's frames and its holds, so neither is kept in
+ * agreement with the other by hand, and nothing here measures progress
+ * itself: a half's schedule carried onto the host's clock by `Timeline.run`
+ * is that half's hold — every frame for a fade, once a hold for one on a
+ * beat — and the moment it says it never changes again (`Animation.done`)
+ * is where the arrival ends and where the element is gone. The frames carry
+ * no word of their own on when they change: placed, the lifecycle stamps
+ * them with its hold at the frame's time (`placedRender`). The exit is
+ * drawn over whatever the arrival draws, so an element told to leave while
+ * it is still arriving leaves from where it is, never shown whole first —
+ * though a colour exit is spread over the cells each frame shows, so a cell
+ * the arrival adds can move one already leaving back toward whole
+ * (`ownChange`, `./effects.ts`). [LAW:dataflow-not-control-flow]
  *
  * A half draws the element through a colour transition (`throughColors`, a
- * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each lift binds
- * its transition to the one wrapper that draws it, and to what that wrapper
+ * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each binds its
+ * transition to the one wrapper that draws it, and to what that wrapper
  * needs — a theme for colours, nothing for glyphs — so nothing here asks which
- * kind a half is, and a line can type itself in and dissolve out. An exit is
- * a transition that ends with nothing drawn — `dissolveOut`, `backspace`,
- * `scrambleOut` — so the element has already gone from sight when it is gone.
+ * kind a half is, and a line can type itself in and dissolve out. A half
+ * written by hand is any function of that shape — an arrival that slides the
+ * element in, which no effect draws. An exit is a half that ends with nothing
+ * drawn — `dissolveOut`, `backspace`, `scrambleOut` — so the element has
+ * already gone from sight when it is gone.
  *
  * Gone is a fact the host reads (`gone(t)`) to drop the element, and from then
  * the lifecycle draws nothing and never changes, so a host still holding it
@@ -40,25 +45,30 @@
 import { Animation } from "../core/animation.js";
 import type { TerminalTheme } from "../core/color.js";
 import type { Renderable } from "../core/protocol.js";
-import { Transition } from "./effects.js";
+import type { Transition } from "./effects.js";
 import type { GlyphTransition } from "./glyph-effects.js";
 /**
- * An element drawn through one half of its lifecycle at `t`, the seconds since
- * that half began, its effect's seeds named by `key`, saying nothing of when
- * that changes — the half's schedule does, as a `Recolored`'s and a
- * `Reglyphed`'s frame say nothing.
+ * One half of an element's lifecycle: handed the element and `key`, which
+ * names it for the half's seeds, the element as the half draws it from
+ * `t = 0`, the moment the half began, on its own clock. Its holds are the
+ * half's own, whatever element it is handed, and it is done from the first
+ * moment it says it never changes again (`Animation.done`): an arrival is
+ * the element from then, and an exit is gone. A half that never ends is
+ * refused when the lifecycle is made: an `Effected` or `GlyphEffected`
+ * handed in bare is one, since its own word is "now" at every time;
+ * `throughColors` and `throughGlyphs` lend one the transition's schedule.
  */
-export type Veil = (element: Renderable, t: number, key: string) => Renderable;
+export type Half = (element: Renderable, key: string) => Animation<Renderable>;
 /** `transition`'s colours drawn over an element on `theme`, whose ground it arrives from and leaves to. */
-export declare function throughColors(transition: Transition, theme: TerminalTheme): Transition<Veil>;
+export declare function throughColors(transition: Transition, theme: TerminalTheme): Half;
 /** `transition`'s glyphs drawn over an element, at every depth, with no colour too. */
-export declare function throughGlyphs(transition: GlyphTransition): Transition<Veil>;
+export declare function throughGlyphs(transition: GlyphTransition): Half;
 /** How an element arrives and leaves, and what it is named for their seeds. */
 export interface LifecycleOptions {
     /** The half it arrives through — `throughColors(fadeIn(curve, z), theme)`. */
-    readonly enter: Transition<Veil>;
+    readonly enter: Half;
     /** The half it leaves through — `throughGlyphs(scrambleOut(timing, z))`. */
-    readonly exit: Transition<Veil>;
+    readonly exit: Half;
     /** Names the element for both halves' seeds, as `Effected`'s and `GlyphEffected`'s key does. */
     readonly key: string;
 }

package/dist/renderables/lifecycle.js

@@ -10,27 +10,32 @@
  * part of the drawing asks whether it is leaving. Telling it is a new value
  * (`leave`), as every `Timeline` operation is. [LAW:no-ambient-temporal-coupling]
  *
- * Each half is a `Transition` of a `Veil` on its own clock from 0, handed the time since
- * its moment, and its schedule carried onto the host's clock by
- * `Timeline.run` is that half's hold — every frame for a fade, once a hold
- * for one on a beat — so the transition's schedule, and `done` read off it,
- * stays the one rule for where a one-shot ends and when its frame changes,
- * and nothing here measures progress itself. The frames carry no word of
- * their own on when they change: placed, the lifecycle stamps them with its
- * hold at the frame's time (`placedRender`). The exit veils whatever the
- * arrival draws, so an element told to leave while it is still arriving leaves
- * from where it is, never shown whole first — though a colour exit is spread
- * over the cells each frame shows, so a cell the arrival adds can move one
- * already leaving back toward whole (`ownChange`, `./effects.ts`).
- * [LAW:dataflow-not-control-flow]
+ * Each half is a `Half`: handed the element, an `Animation<Renderable>` of
+ * it on the half's own clock from 0, in the shape of the library's other
+ * one-shot from renderables to an animation (`Change`, `./change.ts`). One
+ * value carries the half's frames and its holds, so neither is kept in
+ * agreement with the other by hand, and nothing here measures progress
+ * itself: a half's schedule carried onto the host's clock by `Timeline.run`
+ * is that half's hold — every frame for a fade, once a hold for one on a
+ * beat — and the moment it says it never changes again (`Animation.done`)
+ * is where the arrival ends and where the element is gone. The frames carry
+ * no word of their own on when they change: placed, the lifecycle stamps
+ * them with its hold at the frame's time (`placedRender`). The exit is
+ * drawn over whatever the arrival draws, so an element told to leave while
+ * it is still arriving leaves from where it is, never shown whole first —
+ * though a colour exit is spread over the cells each frame shows, so a cell
+ * the arrival adds can move one already leaving back toward whole
+ * (`ownChange`, `./effects.ts`). [LAW:dataflow-not-control-flow]
  *
  * A half draws the element through a colour transition (`throughColors`, a
- * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each lift binds
- * its transition to the one wrapper that draws it, and to what that wrapper
+ * `fadeIn`) or a glyph one (`throughGlyphs`, a `typewriter`): each binds its
+ * transition to the one wrapper that draws it, and to what that wrapper
  * needs — a theme for colours, nothing for glyphs — so nothing here asks which
- * kind a half is, and a line can type itself in and dissolve out. An exit is
- * a transition that ends with nothing drawn — `dissolveOut`, `backspace`,
- * `scrambleOut` — so the element has already gone from sight when it is gone.
+ * kind a half is, and a line can type itself in and dissolve out. A half
+ * written by hand is any function of that shape — an arrival that slides the
+ * element in, which no effect draws. An exit is a half that ends with nothing
+ * drawn — `dissolveOut`, `backspace`, `scrambleOut` — so the element has
+ * already gone from sight when it is gone.
  *
  * Gone is a fact the host reads (`gone(t)`) to drop the element, and from then
  * the lifecycle draws nothing and never changes, so a host still holding it
@@ -40,20 +45,31 @@
 import { Animation } from "../core/animation.js";
 import { firstReaching } from "../core/easing.js";
 import { Timeline } from "../core/timeline.js";
-import { Recolored } from "./effect.js";
-import { Transition } from "./effects.js";
-import { Reglyphed } from "./glyph-effect.js";
+import { Effected } from "./effect.js";
+import { GlyphEffected } from "./glyph-effect.js";
 /** `transition`'s colours drawn over an element on `theme`, whose ground it arrives from and leaves to. */
 export function throughColors(transition, theme) {
-    return lift(transition, (element, t, key) => new Recolored(element, transition.effect, { t, key, theme }));
+    return (element, key) => scheduled(new Effected(element, transition.effect, { key, theme }), transition.schedule);
 }
 /** `transition`'s glyphs drawn over an element, at every depth, with no colour too. */
 export function throughGlyphs(transition) {
-    return lift(transition, (element, t, key) => new Reglyphed(element, transition.effect, { t, key }));
+    return (element, key) => scheduled(new GlyphEffected(element, transition.effect, { key }), transition.schedule);
 }
-/** [LAW:one-source-of-truth] A lifted half keeps its transition's schedule, so `done` and every hold are the transition's own. */
-function lift(transition, veil) {
-    return new Transition(veil, transition.schedule);
+/**
+ * `placed` — an element under a transition's effect — changing when
+ * `schedule`, the transition's own, says: its frames with the one word on
+ * when they change that the transition has and the wrapper lacks, whose own
+ * answer is "now" until it is drawn. [LAW:one-source-of-truth] Reduced,
+ * both are reduced together, as `onBeat` steps both: a one-shot's effect
+ * and its schedule each reduce to a cut at 0 (`transition`, `./effects.ts`).
+ */
+function scheduled(placed, schedule) {
+    return Animation.of({
+        at: (t) => placed.at(t),
+        nextChange: (t) => schedule.nextChange(t),
+        lastChange: (t) => schedule.lastChange(t),
+        reduced: () => scheduled(placed.reduced(), schedule.reduced()),
+    });
 }
 /** What an element draws before it entered and once it is gone: no cells, and no width. */
 const NOTHING = { render: () => [], measure: () => ({ minimum: 0, maximum: 0 }) };
@@ -61,26 +77,50 @@ const NOTHING = { render: () => [], measure: () => ({ minimum: 0, maximum: 0 })
 export function lifecycle(element, options, entered) {
     if (!Number.isFinite(entered))
         throw new RangeError(`lifecycle: entered must be a finite time, got ${entered}`);
-    return life(element, options, entered, Number.POSITIVE_INFINITY);
+    const { enter, exit, key } = options;
+    const arrival = ending(enter(element, key), "enter", key);
+    const departure = ending(exit(element, key), "exit", key);
+    return life(element, options, { arrival, arrived: doneAt(arrival, entered), departure }, entered, Number.POSITIVE_INFINITY);
 }
 /**
- * The first host moment `transition`, begun at host time `start`, is done:
- * its own `done` read on host time, never a sum `start + seconds`, which can
- * round to either side of it, as `Animation.sequence` carries its switch.
- * [LAW:single-enforcer] Since `x - start` never falls as `x` rises, a host time
- * is at or past this moment exactly when `done` holds there.
+ * The first host moment `half`, begun at host time `start`, is done: its own
+ * answer read on host time, never a sum `start + seconds`, which can round
+ * to either side of it, as `Animation.sequence` carries its switch.
+ * [LAW:single-enforcer] Since `x - start` never falls as `x` rises, a host
+ * time is at or past this moment exactly when `done` holds there. Done is
+ * for good, so a half done as it begins — the element at once — is done at
+ * `start`, and from a start it is not done at the walk is upward only: no
+ * half is asked about a time before it began.
  */
-function doneAt(transition, start) {
-    return Number.isFinite(start) ? firstReaching(start, (x) => transition.done(x - start)) : start;
+function doneAt(half, start) {
+    if (!Number.isFinite(start) || Animation.done(half, 0))
+        return start;
+    return firstReaching(start, (x) => Animation.done(half, x - start));
 }
-function life(element, options, entered, left) {
-    const { enter, exit, key } = options;
-    const arrived = doneAt(enter, entered);
-    const goneAt = doneAt(exit, left);
-    // The arrival's schedule on the host's clock: when its frame next changes, and since when it has been what it is.
-    const arriving = Timeline.run(Timeline.play(entered), enter.schedule);
+/**
+ * `half` over the element, asked where it ends on its own clock, or refused
+ * by its `role` and the element's `key` when it never does. [LAW:no-silent-failure]
+ * Kept, it would never arrive, or never be gone, and wake the host every frame
+ * for good; asked here, the refusal lands where the options were written and
+ * not at the first `leave`. A half on a beat that never ends is refused by the
+ * beat instead, where the walk asks it past what its holds resolve.
+ */
+function ending(half, role, key) {
+    if (doneAt(half, 0) === Number.POSITIVE_INFINITY) {
+        throw new RangeError(`lifecycle "${key}": the ${role} half never ends: its animation never says it has stopped changing (Animation.done). An Effected or GlyphEffected on its own does not; throughColors(transition, theme) and throughGlyphs(transition) lend one the transition's schedule`);
+    }
+    return half;
+}
+function life(element, options, halves, entered, left) {
+    const { exit, key } = options;
+    const { arrival, arrived, departure } = halves;
+    // Where the exit is gone, and the exit's hold, are read off the exit over the element; the frame while
+    // leaving is the exit over what is shown, whose holds are the same by `Half`'s contract.
+    const goneAt = doneAt(departure, left);
+    // The arrival on the host's clock: when its frame next changes, and since when it has been what it is.
+    const arriving = Timeline.run(Timeline.play(entered), arrival);
     // What the element draws by `t` if it is not leaving: arriving through `enter`, then itself.
-    const shown = (t) => (t < arrived ? enter.effect(element, t - entered, key) : element);
+    const shown = (t) => (t < arrived ? arrival.at(t - entered) : element);
     const held = (schedule, t) => ({ last: schedule.lastChange(t), next: schedule.nextChange(t) });
     // [LAW:one-source-of-truth] Each phase's frame and its hold, side by side, so the two cannot disagree.
     // The frames say nothing of when they change — the hold does, stamped where the lifecycle is placed.
@@ -89,10 +129,10 @@ function life(element, options, entered, left) {
             return { frame: NOTHING, last: Number.NEGATIVE_INFINITY, next: entered };
         if (t >= goneAt)
             return { frame: NOTHING, last: goneAt, next: Number.POSITIVE_INFINITY };
-        // Leaving veils whatever arriving draws, so both schedules count; once arrived, the arrival's never changes again.
+        // Leaving is drawn over whatever arriving draws, so both schedules count; once arrived, the arrival's never changes again.
         if (t >= left) {
-            const leaving = Animation.all([arriving, Timeline.run(Timeline.play(left), exit.schedule)]);
-            return { frame: exit.effect(shown(t), t - left, key), ...held(leaving, t) };
+            const leaving = Animation.all([arriving, Timeline.run(Timeline.play(left), departure)]);
+            return { frame: exit(shown(t), key).at(t - left), ...held(leaving, t) };
         }
         if (t < arrived)
             return { frame: shown(t), ...held(arriving, t) };
@@ -126,7 +166,7 @@ function life(element, options, entered, left) {
                 throw new RangeError(`lifecycle: already told to leave at ${left}, told again at ${at}`);
             if (!(Number.isFinite(at) && at >= entered))
                 throw new RangeError(`lifecycle: leave must be a finite time from entered (${entered}) on, got ${at}`);
-            return life(element, options, entered, at);
+            return life(element, options, halves, entered, at);
         },
     });
 }

package/dist/renderables/live.d.ts

@@ -26,7 +26,7 @@
  */
 import { type Clock } from "../core/clock.js";
 import { Console } from "../core/console.js";
-import { type FrameHost } from "../core/protocol.js";
+import { type HostFrame, type FrameHost } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
 import { type View } from "../core/view.js";
 export interface LiveOptions {
@@ -79,8 +79,8 @@ export declare class Live implements FrameHost {
     get clock(): Clock;
     /** The map from the clock to the time the view is drawn for. */
     get timeline(): Timeline;
-    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
-    get frameTime(): number;
+    /** The frame this Live draws now (`FrameHost`): the clock's now, through the timeline, on a frame it is the host of. */
+    frameNow(): HostFrame;
     private _time;
     /**
      * Replace the timeline and draw the frame for the time it now maps the

package/dist/renderables/live.js

@@ -30,7 +30,7 @@ import { Segment } from "../core/segment.js";
 import { FinalFramePainter, SurfacePainter } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
-import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
+import { drawView, frameNow, hostView, undrawn } from "../core/view.js";
 import { State } from "../core/state.js";
 // Nothing: what a Live made with no view draws until `update` gives it one.
 const NOTHING = { render: () => [] };
@@ -89,9 +89,9 @@ export class Live {
     get timeline() {
         return this._timeline.get();
     }
-    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
-    get frameTime() {
-        return frameTime(this._time());
+    /** The frame this Live draws now (`FrameHost`): the clock's now, through the timeline, on a frame it is the host of. */
+    frameNow() {
+        return frameNow(this, this._time());
     }
     _time() {
         return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline.get() };

package/dist/renderables/progress.d.ts

@@ -7,7 +7,7 @@ import { Console } from "../core/console.js";
 import type { Style } from "../core/style.js";
 import type { Clock } from "../core/clock.js";
 import { type ColumnOptions } from "./table.js";
-import type { FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
+import type { HostFrame, FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
 import { Animation } from "../core/animation.js";
 import type { Timing } from "../core/easing.js";
 export interface TaskOptions {
@@ -156,7 +156,7 @@ export declare class MofNCompleteColumn implements ProgressColumn {
 }
 /**
  * How a `Progress` is set up. It is drawn by one host, and every time it
- * keeps or draws at is that host's `frameTime`: by its own `Live`, which the
+ * keeps or draws at is that host's `frameNow()`: by its own `Live`, which the
  * options for that `Live` configure, or, given `drawnBy`, by another host —
  * which then does all the drawing, so none of them apply.
  */
@@ -185,7 +185,7 @@ interface OwnLiveOptions {
 interface DrawnByOptions {
     /**
      * The host — a `Live`, an `App` — whose frames this `Progress` is drawn in:
-     * tasks are timed by its `frameTime`, so they hold while its timeline is
+     * tasks are timed by its `frameNow()`, so they hold while its timeline is
      * paused and run back while it is reversed. Drawn in any other host's
      * frame, the `Progress` throws.
      */
@@ -207,6 +207,13 @@ export declare class Progress implements Renderable {
     constructor(...columns: (ProgressColumn | ProgressOptions)[]);
     /** The console its own `Live` prints above the bars through. */
     get console(): Console;
+    /**
+     * The frame its host draws now (`FrameHost.frameNow`): what a print of
+     * this display is drawn in — `console.print(progress, { frame:
+     * progress.frameNow() })` — so a still of it is drawn for a moment on the
+     * clock its tasks are timed on, the one the program asked at.
+     */
+    frameNow(): HostFrame;
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished(): boolean;
     static getDefaultColumns(): ProgressColumn[];
@@ -224,7 +231,7 @@ export declare class Progress implements Renderable {
     refresh(): void;
     private _ownLive;
     render(options: RenderOptions): Iterable<Segment>;
-    private _framed;
+    private _ownFrame;
     private _table;
 }
 export declare function track<T>(iterable: Iterable<T>, options?: {

package/dist/renderables/progress.js

@@ -321,9 +321,20 @@ export class Progress {
     get console() {
         return this._ownLive("console").console;
     }
+    /**
+     * The frame its host draws now (`FrameHost.frameNow`): what a print of
+     * this display is drawn in — `console.print(progress, { frame:
+     * progress.frameNow() })` — so a still of it is drawn for a moment on the
+     * clock its tasks are timed on, the one the program asked at.
+     */
+    frameNow() {
+        return this._host.frameNow();
+    }
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished() {
-        return this._tasks.get().every((task) => finished(taskAt(task.get(), this._host.frameTime)));
+        // [LAW:one-source-of-truth] One moment, so every task is judged at it.
+        const now = this._host.frameNow().time;
+        return this._tasks.get().every((task) => finished(taskAt(task.get(), now)));
     }
     static getDefaultColumns() {
         return [
@@ -342,7 +353,7 @@ export class Progress {
             completed: 0,
             fill: Animation.constant(0),
             visible: options?.visible !== false,
-            startTime: options?.start === false ? undefined : this._host.frameTime,
+            startTime: options?.start === false ? undefined : this._host.frameNow().time,
             finishedAt: undefined,
             samples: [],
         }));
@@ -364,7 +375,7 @@ export class Progress {
         const completed = options.completed === undefined
             ? finiteCount("completed + advance", task.completed + advance)
             : finiteCount("completed", options.completed);
-        const now = this._host.frameTime;
+        const now = this._host.frameNow().time;
         const reached = task.startTime !== undefined && task.total !== undefined && completed >= task.total;
         held.set({
             ...task,
@@ -385,7 +396,7 @@ export class Progress {
         const held = this._task(taskId);
         // Rich's `start_task`: a task already running keeps the time it started.
         if (held)
-            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameTime });
+            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameNow().time });
     }
     start() {
         this._ownLive("start").start();
@@ -410,23 +421,24 @@ export class Progress {
         return this._live;
     }
     *render(options) {
-        const framed = this._framed(options);
-        yield* render(this._table(framed.frame.time), framed);
+        yield* render(this._table(this._ownFrame(options).time), options);
     }
-    // Inside a frame, the time its host read for it: a second read here would
-    // land a moving bar's stamp a hair after the frame, a moment the host takes
-    // for one still to come. A frame is only ever this display's host's,
-    // because the tasks were stamped on that host's time and a frame of any
-    // other is drawn for a moment on a different clock. A print is drawn for no
-    // moment, so it is drawn in a frame for the one the program asks at, read
-    // as `updateTask` reads it, and every bar and spinner placed in the table
-    // draws at that moment too. [LAW:one-source-of-truth]
-    _framed(options) {
+    // The frame this display is drawn in, which is only ever its host's: the
+    // tasks were stamped on that host's time, and a frame of any other host is
+    // drawn for a moment on a different clock. A render reads no clock, so a
+    // print names its frame (`frameNow`, `PrintOptions.frame`): drawn for no
+    // moment — 0, as everything else is — every task would read as not yet
+    // started, so that print is refused with the call that draws it right.
+    // [LAW:parse-dont-validate] [LAW:no-silent-failure]
+    _ownFrame(options) {
         const { frame } = options;
-        if (frame !== undefined && frame.host !== this._host) {
+        if (frame === undefined) {
+            throw new Error("a Progress is drawn for a moment on its host's clock, and this print named none; print it in its frame: console.print(progress, { frame: progress.frameNow() })");
+        }
+        if (frame.host !== this._host) {
             throw new Error("a Progress was drawn in a frame of a host other than its own; give it that host as `drawnBy`");
         }
-        return { ...options, frame: frame ?? { time: this._host.frameTime, host: this._host } };
+        return frame;
     }
     // Rich's `make_tasks_table`: each column laid out as it says, at `now` on
     // this display's clock.

package/dist/themes/buildPalette.d.ts

@@ -1,5 +1,5 @@
 import { ColorRgba } from "../core/color.js";
-import { Palette } from "./palette.js";
+import { Palette, 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,19 @@ 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>;
+/** 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 most 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;