@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/renderables/group.d.ts

@@ -4,12 +4,11 @@
  */
 import type { Segment } from "../core/segment.js";
 import { type Measurement } from "../core/measure.js";
-import type { Composite, Measurable, Renderable, RenderOptions } from "../core/protocol.js";
-export declare class Group implements Renderable, Measurable, Composite {
-    readonly renderables: Renderable[];
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+export declare class Group implements Renderable, Measurable {
+    readonly renderables: readonly Renderable[];
     constructor(...renderables: Renderable[]);
     render(options: RenderOptions): Iterable<Segment>;
     /** As wide as its widest member: the reference's `measure_renderables`. */
     measure(options: RenderOptions): Measurement;
-    contents(): Iterable<Renderable>;
 }

package/dist/renderables/group.js

@@ -19,7 +19,4 @@ export class Group {
     measure(options) {
         return measureRenderables(options, this.renderables);
     }
-    contents() {
-        return this.renderables;
-    }
 }

package/dist/renderables/layout.d.ts

@@ -2,7 +2,7 @@
  * Layout — divides the screen into rectangular regions.
  */
 import { Segment } from "../core/segment.js";
-import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import type { CellCol } from "../core/cells.js";
 import type { Weight } from "./ratio.js";
 export interface LayoutOptions {
@@ -12,16 +12,17 @@ export interface LayoutOptions {
     minimumSize?: number;
     visible?: boolean;
 }
-export declare class Layout implements Renderable, Measurable, Composite {
-    name: string | undefined;
-    visible: boolean;
-    private _ratio;
-    private _size;
-    private _minimumSize;
-    private _renderable;
-    private _children;
-    private _splitDirection;
+export declare class Layout implements Renderable, Measurable {
+    readonly name: string | undefined;
+    private readonly _visible;
+    private readonly _ratio;
+    private readonly _size;
+    private readonly _minimumSize;
+    private readonly _renderable;
+    private readonly _split;
     constructor(renderable?: Renderable | string, options?: LayoutOptions);
+    get visible(): boolean;
+    set visible(value: boolean);
     /**
      * The three declared numbers, parsed on assignment rather than at the
      * constructor. All three are public and a caller reaches them long after
@@ -41,7 +42,7 @@ export declare class Layout implements Renderable, Measurable, Composite {
     set size(value: number | undefined);
     get minimumSize(): CellCol;
     set minimumSize(value: number);
-    get children(): Layout[];
+    get children(): readonly Layout[];
     /**
      * Whether this layout draws `_renderable` or its children.
      *
@@ -57,7 +58,6 @@ export declare class Layout implements Renderable, Measurable, Composite {
     update(renderable: Renderable | string): void;
     getByName(name: string): Layout | undefined;
     render(rawOptions: RenderOptions): Iterable<Segment>;
-    contents(): Iterable<Renderable>;
     private _renderColumn;
     private _renderRow;
     /**

package/dist/renderables/layout.js

@@ -8,6 +8,7 @@ import { render } from "../core/protocol.js";
 import { Measurement } from "../core/measure.js";
 import { cellCount } from "../core/cells.js";
 import { ratioBudget, ratioResolve, shareWeight } from "./ratio.js";
+import { State } from "../core/state.js";
 /**
  * A pane rendered into a region of `rows` and held to exactly that many lines,
  * or — with `rows` undefined — rendered under the layout's own budget, as a
@@ -21,26 +22,31 @@ function paneLines(pane, options, rows) {
     const height = rows === undefined ? stackedHeight(options.height) : { rows, exact: true };
     return fitHeight(Segment.splitLines(render(pane, { ...options, height })), height);
 }
+/** A declared size as a cell count; absence stays absence, a flex pane, which `cellCount` would read as zero. */
+const sizeOf = (value) => (value === undefined ? undefined : cellCount(value));
 export class Layout {
     name;
-    visible;
+    // Rich's `Layout` is split, updated, resized and hidden after it is built,
+    // so each of these is state, and a write to one while it is drawn throws.
+    _visible;
     _ratio;
     _size;
     _minimumSize;
     _renderable;
-    _children;
-    _splitDirection;
+    _split = new State({ direction: undefined, children: [] });
     constructor(renderable, options) {
-        if (renderable !== undefined) {
-            this._renderable = embed(renderable);
-        }
+        this._renderable = new State(renderable === undefined ? undefined : embed(renderable));
         this.name = options?.name;
-        this.ratio = options?.ratio ?? 1;
-        this.size = options?.size;
-        this.minimumSize = options?.minimumSize ?? 1;
-        this.visible = options?.visible !== false;
-        this._children = [];
-        this._splitDirection = undefined;
+        this._ratio = new State(shareWeight(options?.ratio ?? 1));
+        this._size = new State(sizeOf(options?.size));
+        this._minimumSize = new State(cellCount(options?.minimumSize ?? 1));
+        this._visible = new State(options?.visible !== false);
+    }
+    get visible() {
+        return this._visible.get();
+    }
+    set visible(value) {
+        this._visible.set(value);
     }
     /**
      * The three declared numbers, parsed on assignment rather than at the
@@ -56,25 +62,25 @@ export class Layout {
      * selects a flex pane, and `cellCount` would read it as a declared zero.
      */
     get ratio() {
-        return this._ratio;
+        return this._ratio.get();
     }
     set ratio(value) {
-        this._ratio = shareWeight(value);
+        this._ratio.set(shareWeight(value));
     }
     get size() {
-        return this._size;
+        return this._size.get();
     }
     set size(value) {
-        this._size = value === undefined ? undefined : cellCount(value);
+        this._size.set(sizeOf(value));
     }
     get minimumSize() {
-        return this._minimumSize;
+        return this._minimumSize.get();
     }
     set minimumSize(value) {
-        this._minimumSize = cellCount(value);
+        this._minimumSize.set(cellCount(value));
     }
     get children() {
-        return this._children;
+        return this._split.get().children;
     }
     /**
      * Whether this layout draws `_renderable` or its children.
@@ -86,23 +92,21 @@ export class Layout {
      * fit-mode `Panel` framed twelve cells of air.
      */
     get _isLeaf() {
-        return this._children.length === 0;
+        return this._split.get().children.length === 0;
     }
     splitColumn(...layouts) {
-        this._children = layouts;
-        this._splitDirection = "column";
+        this._split.set({ direction: "column", children: layouts });
     }
     splitRow(...layouts) {
-        this._children = layouts;
-        this._splitDirection = "row";
+        this._split.set({ direction: "row", children: layouts });
     }
     update(renderable) {
-        this._renderable = embed(renderable);
+        this._renderable.set(embed(renderable));
     }
     getByName(name) {
         if (this.name === name)
             return this;
-        for (const child of this._children) {
+        for (const child of this._split.get().children) {
             const found = child.getByName(name);
             if (found)
                 return found;
@@ -128,8 +132,9 @@ export class Layout {
             // ok\n")` is two lines, and a one-row region cuts the second. Every line
             // ended, as the split paths below end theirs: a leaf stacked in a
             // `Group` is still a region of lines.
-            if (this._renderable) {
-                const lines = fitHeight(Segment.splitLines(render(this._renderable, options)), options.height);
+            const renderable = this._renderable.get();
+            if (renderable) {
+                const lines = fitHeight(Segment.splitLines(render(renderable, options)), options.height);
                 for (const line of lines) {
                     yield* Segment.adjustLineLength(line, options.maxWidth);
                     yield Segment.line();
@@ -137,28 +142,16 @@ export class Layout {
             }
             return;
         }
-        const visibleChildren = this._children.filter((c) => c.visible);
+        const visibleChildren = this._split.get().children.filter((c) => c.visible);
         if (visibleChildren.length === 0)
             return;
-        if (this._splitDirection === "row") {
+        if (this._split.get().direction === "row") {
             yield* this._renderRow(visibleChildren, options);
         }
         else {
             yield* this._renderColumn(visibleChildren, options);
         }
     }
-    // What `render` draws, decided as it decides it: nothing when hidden, a
-    // leaf's content, or the visible panes of a split.
-    *contents() {
-        if (!this.visible)
-            return;
-        if (this._isLeaf) {
-            if (this._renderable)
-                yield this._renderable;
-            return;
-        }
-        yield* this._children.filter((c) => c.visible);
-    }
     *_renderColumn(children, options) {
         // Each pane gets full width and its share of the region. With no region —
         // a ceiling, or no budget at all — a pane's share is its declared `size`,
@@ -200,15 +193,16 @@ export class Layout {
         if (!this.visible)
             return 0;
         if (this._isLeaf) {
-            if (this._renderable === undefined)
+            const renderable = this._renderable.get();
+            if (renderable === undefined)
                 return 0;
-            return Measurement.get(options, this._renderable).maximum;
+            return Measurement.get(options, renderable).maximum;
         }
-        const visible = this._children.filter((c) => c.visible);
+        const visible = this._split.get().children.filter((c) => c.visible);
         if (visible.length === 0)
             return 0;
         const widths = visible.map((c) => c._naturalWidth(options));
-        if (this._splitDirection === "row")
+        if (this._split.get().direction === "row")
             return ratioBudget(visible, widths);
         // Accumulated, not spread: a column split holds as many children as a caller
         // made, and `Math.max(...widths)` passes one argument per child, so a

package/dist/renderables/lifecycle.d.ts

@@ -0,0 +1,77 @@
+/**
+ * An element's lifecycle: it enters, stays, is told to leave, leaves, and is
+ * gone — a row added to a table, a line appended to a log, a panel closing.
+ * Drawn on the host's clock as an `Animation<Renderable>`, so it is a view a
+ * `Live` or an `App` draws as it stands, and a list of them is
+ * `Animation.all` of them mapped to whatever lays them out.
+ *
+ * The two times are handed in, never read: when the element entered, and when
+ * it was told to leave — `Infinity` until it is, a time like any other, so no
+ * 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]
+ *
+ * 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
+ * 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.
+ *
+ * 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
+ * wakes for nothing. Before it entered — asked by a timeline running
+ * backwards — it draws nothing too, but is not gone.
+ */
+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 { 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.
+ */
+export type Veil = (element: Renderable, t: number, key: string) => 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>;
+/** `transition`'s glyphs drawn over an element, at every depth, with no colour too. */
+export declare function throughGlyphs(transition: GlyphTransition): Transition<Veil>;
+/** 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>;
+    /** The half it leaves through — `throughGlyphs(scrambleOut(timing, z))`. */
+    readonly exit: Transition<Veil>;
+    /** Names the element for both halves' seeds, as `Effected`'s and `GlyphEffected`'s key does. */
+    readonly key: string;
+}
+/** An element on the host's clock, from before it entered to after it is gone. */
+export interface Lifecycle extends Animation<Renderable> {
+    /** The host time it entered. */
+    readonly entered: number;
+    /** The host time it was told to leave: `Infinity` until it is. */
+    readonly left: number;
+    /** Whether it has finished leaving by `t`, so a host drops it. */
+    gone(t: number): boolean;
+    /** This element told to leave at host time `at`. Throws if it was already told, or `at` is before it entered. */
+    leave(at: number): Lifecycle;
+}
+/** `element` entering at host time `entered`, through `options.enter`, and staying until it is told to `leave`. */
+export declare function lifecycle(element: Renderable, options: LifecycleOptions, entered: number): Lifecycle;

package/dist/renderables/lifecycle.js

@@ -0,0 +1,132 @@
+/**
+ * An element's lifecycle: it enters, stays, is told to leave, leaves, and is
+ * gone — a row added to a table, a line appended to a log, a panel closing.
+ * Drawn on the host's clock as an `Animation<Renderable>`, so it is a view a
+ * `Live` or an `App` draws as it stands, and a list of them is
+ * `Animation.all` of them mapped to whatever lays them out.
+ *
+ * The two times are handed in, never read: when the element entered, and when
+ * it was told to leave — `Infinity` until it is, a time like any other, so no
+ * 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]
+ *
+ * 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
+ * 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.
+ *
+ * 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
+ * wakes for nothing. Before it entered — asked by a timeline running
+ * backwards — it draws nothing too, but is not gone.
+ */
+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";
+/** `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 }));
+}
+/** `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 }));
+}
+/** [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);
+}
+/** 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 }) };
+/** `element` entering at host time `entered`, through `options.enter`, and staying until it is told to `leave`. */
+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);
+}
+/**
+ * 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.
+ */
+function doneAt(transition, start) {
+    return Number.isFinite(start) ? firstReaching(start, (x) => transition.done(x - start)) : 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);
+    // 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 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.
+    const phase = (t) => {
+        if (t < entered)
+            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.
+        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) };
+        }
+        if (t < arrived)
+            return { frame: shown(t), ...held(arriving, t) };
+        return { frame: element, last: arrived, next: left };
+    };
+    // [LAW:dataflow-not-control-flow] The spans `phase` draws, the transitions gone from them: told to
+    // leave, nothing shows, and the moment it is `gone` is still one a host is woken for, so it drops it on time.
+    const there = (t) => t < entered
+        ? { frame: NOTHING, last: Number.NEGATIVE_INFINITY, next: entered }
+        : t < left
+            ? { frame: element, last: entered, next: left }
+            : { frame: NOTHING, last: left, next: t < goneAt ? goneAt : Number.POSITIVE_INFINITY };
+    const present = Animation.of({
+        at: (t) => there(t).frame,
+        nextChange: (t) => there(t).next,
+        lastChange: (t) => there(t).last,
+        reduced: () => present,
+    });
+    return Animation.of({
+        entered,
+        left,
+        at: (t) => phase(t).frame,
+        nextChange: (t) => phase(t).next,
+        lastChange: (t) => phase(t).last,
+        // Reduced, the element is there from when it entered until it is told to leave: no arrival or exit to show, and the times kept.
+        reduced: () => present,
+        // [LAW:one-source-of-truth] The moment `phase` draws nothing from, so an element not yet told to leave is never asked its exit at -Infinity.
+        gone: (t) => t >= goneAt,
+        leave(at) {
+            if (Number.isFinite(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);
+        },
+    });
+}

package/dist/renderables/list-view.d.ts

@@ -5,8 +5,8 @@
  * An item can wrap, so the lines the selected one covers exist only at the
  * width it is drawn at, which a render is handed and whoever builds the frame
  * is not. So the items are drawn here, at the viewport's content width and
- * with no height — the lines the viewport scrolls — and the viewport is handed
- * those lines and the selected item's range.
+ * with no height — the lines the viewport scrolls — and shown through the
+ * viewport with the selected item's range followed.
  * [LAW:single-enforcer] Where the window sits is the viewport's call; this
  * only says which lines the selection is.
  *
@@ -16,7 +16,7 @@
  * it — so a consumer can take one without the others.
  */
 import { Segment } from "../core/segment.js";
-import type { Composite, Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import type { Viewport } from "./viewport.js";
 export interface ListViewOptions {
     /** Blank lines between one item and the next. Absent, none. */
@@ -27,7 +27,7 @@ export interface ListViewOptions {
      */
     context?: number;
 }
-export declare class ListView implements Renderable, Measurable, Composite {
+export declare class ListView implements Renderable, Measurable {
     readonly viewport: Viewport;
     readonly items: readonly Renderable[];
     readonly selected: number;
@@ -35,7 +35,6 @@ export declare class ListView implements Renderable, Measurable, Composite {
     readonly context: number;
     constructor(viewport: Viewport, items: readonly Renderable[], selected: number, options?: ListViewOptions);
     render(rawOptions: RenderOptions): Iterable<Segment>;
-    contents(): Iterable<Renderable>;
     measure(rawOptions: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/renderables/list-view.js

@@ -5,8 +5,8 @@
  * An item can wrap, so the lines the selected one covers exist only at the
  * width it is drawn at, which a render is handed and whoever builds the frame
  * is not. So the items are drawn here, at the viewport's content width and
- * with no height — the lines the viewport scrolls — and the viewport is handed
- * those lines and the selected item's range.
+ * with no height — the lines the viewport scrolls — and shown through the
+ * viewport with the selected item's range followed.
  * [LAW:single-enforcer] Where the window sits is the viewport's call; this
  * only says which lines the selection is.
  *
@@ -17,7 +17,7 @@
  */
 import { Segment } from "../core/segment.js";
 import { Measurement, measureRenderables } from "../core/measure.js";
-import { drawsNothing, render, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { render, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 function lineCount(name, value) {
     if (!Number.isInteger(value) || value < 0)
         throw new RangeError(`ListView: ${name} ${value} is not a whole number of lines`);
@@ -51,7 +51,7 @@ export class ListView {
         const start = drawn.slice(0, this.selected).reduce((total, item) => total + item.length + this.gap, 0);
         const end = start + (drawn[this.selected]?.length ?? 0);
         const lines = drawn.flatMap((item, i) => (i === 0 ? item : [...gap, ...item]));
-        this.viewport.content = {
+        const content = {
             *render() {
                 for (const line of lines) {
                     yield* line;
@@ -62,15 +62,11 @@ export class ListView {
         // A range reaching past either end is clamped by the viewport, which holds
         // its offset to the lines that exist. Followed, not ensured: the wheel can
         // scroll away from the selection until the selection moves. Items handed
-        // no column are held, not drawn, and cover no lines, so they name no range
-        // and the one last followed stands; followed, it would read as a move.
-        if (!drawsNothing(options))
-            this.viewport.follow(start - this.context, end + this.context);
-        yield* render(this.viewport, bounded);
-    }
-    *contents() {
-        yield* this.items;
-        yield this.viewport;
+        // no column are held, not drawn, and so is the viewport's content, which
+        // keeps nothing it is handed — the range last followed stands.
+        // [LAW:effects-at-boundaries] Shown through the viewport rather than
+        // handed to it: the viewport keeps the lines' range once the frame is drawn.
+        yield* render(this.viewport.showing(content, { start: start - this.context, end: end + this.context }), bounded);
     }
     measure(rawOptions) {
         // Stacked, the items are as wide as the widest of them, plus whatever

package/dist/renderables/live.d.ts

@@ -26,17 +26,9 @@
  */
 import { type Clock } from "../core/clock.js";
 import { Console } from "../core/console.js";
-import { type Renderable } from "../core/protocol.js";
-/**
- * What a Live draws: a renderable, or a view asked for one each frame with
- * the frame's time in seconds on the Live's clock, as an `App`'s view is
- * (`host/app.ts`). A renderable is the view that is the same at every `t` —
- * a table mutated in place between frames — and a function is what a frame
- * drawn for a time needs: `(t) => spinner.at(t)`.
- * [LAW:no-ambient-temporal-coupling] The Live reads its clock once a frame
- * and hands the time down as data, so nothing it draws reads one.
- */
-export type LiveView = Renderable | ((t: number) => Renderable);
+import { type FrameHost } from "../core/protocol.js";
+import { Timeline } from "../core/timeline.js";
+import { type View } from "../core/view.js";
 export interface LiveOptions {
     /**
      * How often the auto-refresh draws on its own, in frames a second:
@@ -48,6 +40,13 @@ export interface LiveOptions {
     refreshPerSecond?: number;
     /** What the auto-refresh waits on. The platform's, unless given. */
     clock?: Clock;
+    /**
+     * The map from the clock to the time the view is drawn for (`Timeline`).
+     * Playing from 0 when the host is made, at the clock's pace, unless given
+     * — so a tween in the view starts when the host is made, not when the clock
+     * began; `live.timeline` reads and replaces it.
+     */
+    timeline?: Timeline;
     autoRefresh?: boolean;
     transient?: boolean;
     console?: Console;
@@ -57,26 +56,42 @@ export interface LiveOptions {
      *  a full-screen layout fills it. */
     altScreen?: boolean;
 }
-export declare class Live {
-    private _view;
-    private _console;
+export declare class Live implements FrameHost {
+    private readonly _view;
+    private readonly _console;
     private readonly _rate;
     private readonly _clock;
-    private _autoRefresh;
-    private _transient;
-    private _verticalOverflow;
+    private readonly _epoch;
+    private readonly _timeline;
+    private readonly _autoRefresh;
+    private readonly _transient;
+    private readonly _verticalOverflow;
     private readonly _painter;
-    private _waking;
-    private _held;
-    constructor(view?: LiveView, options?: LiveOptions);
+    private readonly _waking;
+    private readonly _held;
+    constructor(view?: View, options?: LiveOptions);
     /**
      * The console to print through while this Live runs: what it prints lands
      * above an inline frame. The alternate screen is all frame, and paints over it.
      */
     get console(): Console;
+    /** The clock the auto-refresh waits on: where the host time a `Timeline` operation takes is read. */
+    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;
+    private _time;
+    /**
+     * Replace the timeline and draw the frame for the time it now maps the
+     * clock's now to, so a seek shows where it sought, once. Paused, the frame
+     * then holds — the auto-refresh waits on nothing until the timeline plays
+     * again — while `refresh()` and `update(…, { refresh: true })` still draw.
+     */
+    set timeline(timeline: Timeline);
     start(): void;
     stop(): void;
-    update(view?: LiveView, options?: {
+    update(view?: View, options?: {
         refresh?: boolean;
     }): void;
     refresh(): void;