@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/renderables/columns.js

@@ -10,7 +10,7 @@
  */
 import { Measurement } from "../core/measure.js";
 import { normalizePadding } from "./padding.js";
-import { withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { render, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { cellCount } from "../core/cells.js";
 import { EmbeddedText, embed } from "./embed.js";
 import { Constrain } from "./constrain.js";
@@ -68,7 +68,12 @@ export class Columns {
         // single column is laid out. An unbounded width reaches the same place by
         // the same route, which is why the parse here is the bounded one.
         const options = withBoundedWidth(rawOptions, this);
-        yield* this._grid(options).render(options);
+        yield* render(this._grid(options), options);
+    }
+    // The items, in the order they were given. Laid out column-first, the grid
+    // draws them in an order its width decides, and handed no column it has none.
+    contents() {
+        return this.renderables;
     }
     measure(rawOptions) {
         // The maximum is the grid's, which reports its width before `expand`: a

package/dist/renderables/constrain.d.ts

@@ -2,12 +2,13 @@
  * Constrain — wraps a renderable and constrains its maximum width.
  */
 import { Segment } from "../core/segment.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-export declare class Constrain implements Renderable, Measurable {
+import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export declare class Constrain implements Renderable, Measurable, Composite {
     readonly renderable: Renderable;
     readonly width: number | undefined;
     constructor(renderable: Renderable, width?: number);
     render(options: RenderOptions): Iterable<Segment>;
+    contents(): Iterable<Renderable>;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/renderables/constrain.js

@@ -2,6 +2,7 @@
  * Constrain — wraps a renderable and constrains its maximum width.
  */
 import { Measurement } from "../core/measure.js";
+import { render } from "../core/protocol.js";
 export class Constrain {
     renderable;
     width;
@@ -18,7 +19,10 @@ export class Constrain {
             ...options,
             maxWidth: constrainedWidth,
         };
-        yield* this.renderable.render(innerOptions);
+        yield* render(this.renderable, innerOptions);
+    }
+    *contents() {
+        yield this.renderable;
     }
     measure(options) {
         // Measured at the width it will be drawn at, as Rich's `update_width` does;

package/dist/renderables/effect.d.ts

@@ -2,23 +2,26 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function in two stages: a time and what the element
- * draws in that frame in, a function of the frame out; and into that, a
- * cell's colours and where the cell is, the cell's new colours out. Whatever
- * holds for the whole frame is worked out in the first stage, once, and every
- * cell of the frame is handed to the second, but for those a wrapper keeps
- * back: `confined` hands over only the cells its owners drew, so a second
- * stage never counts on seeing them all. Shimmer, pulse, fade and
- * dissolve are all this one shape, differing by what the function does with
- * its inputs [LAW:one-type-per-behavior]; two effects stack by nesting one
- * wrapper in another, which is the same as calling one after the other but
- * for what the outer one measures: the inner one's output.
+ * An effect is, for what an element draws in a frame, an `Animation`
+ * (`core/animation.ts`) of what is done to its cells: its value at `t` is a
+ * function from a cell's colours and where the cell is to the cell's new
+ * colours (`EffectFrame`), and it says when that next changes as every
+ * animation does. Whatever holds for the whole frame is worked out once, in
+ * the effect and its `at(t)`, and every cell of the frame is handed to the
+ * function `at(t)` returns, but for those a wrapper keeps back: `confined`
+ * hands over only the cells its owners drew, so an effect never counts on
+ * seeing them all. Shimmer, pulse, fade and dissolve are all this one shape,
+ * differing by what the function does with its inputs
+ * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
+ * another, which is the same as calling one after the other but for what the
+ * outer one measures: the inner one's output.
  *
- * What the element draws (`Drawn`) is measured here, in the render, off the
+ * What the element draws (`Drawn`) — the cells the effect will be handed,
+ * and the colours of its words — is measured here, in the render, off the
  * same reading of each segment its cells are drawn from, and handed to the
- * effect's first stage, once a frame. It is what an effect keeping words legible is
- * settled against (`onColors`, `./effects.ts`), so no caller derives it a
- * second time from a render of its own.
+ * effect once a frame. It is what an effect keeping words legible is settled
+ * against (`onColors`, `./effects.ts`), so no caller derives it a second time
+ * from a render of its own.
  *
  * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
  * clock read. Whoever draws frames builds the view for each frame's `t`, so
@@ -33,8 +36,10 @@
  *   segment's link and meta and carries its anchor shifted to the run's first
  *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
  * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
- *   and a segment whose every cell is unchanged is yielded as it was, so the
- *   identity effect is byte-identical. Neighbouring cells the output depth
+ *   and a segment whose every cell is unchanged is yielded with its look as
+ *   it was, so the identity effect is byte-identical; what it gains is when
+ *   the frame next changes (`Style.nextChange`), which writes no byte.
+ *   Neighbouring cells the output depth
  *   writes alike stay one segment: a segment is cut only where the written
  *   colours change, so two colours that land on one index are one run.
  * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
@@ -46,8 +51,10 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { type Anchor } from "../core/anchor.js";
+import { Animation } from "../core/animation.js";
 import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
-import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Beat } from "../core/easing.js";
+import type { Composite, Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 /**
  * A cell's foreground and background as they appear on screen — the glyph's
@@ -78,6 +85,8 @@ export interface EffectCell {
         readonly fg: boolean;
         readonly bg: boolean;
     };
+    /** Whether the cell's style swaps its two slots, as `Pair.reverse` says: with `colors` and `terminal`, the cell's `Pair`. */
+    readonly reverse: boolean;
     /**
      * Who drew the cell, and where it sits in their output, as
      * `Segment.anchorAt` reads it off a frame: what tells one owner's cells
@@ -85,6 +94,8 @@ export interface EffectCell {
      */
     readonly anchor: Anchor | undefined;
 }
+/** Where a cell sits and who drew it: an `EffectCell` before it has a seed or colours. */
+export type Placed = Pick<EffectCell, "row" | "col" | "anchor">;
 /**
  * A cell's ink and ground as the screen shows them, which of the two are the
  * terminal's, and whether its style swaps them (`reverse`): what an `Effect`
@@ -101,13 +112,24 @@ export interface Pair extends CellColors {
     readonly reverse: boolean;
 }
 /**
- * The colours the element an effect wraps draws its words in, in one frame,
- * as the screen shows them: what an effect that must keep the words legible
- * is measured against. A word cell is one whose glyph is not blank and that a
- * strip's joiner did not draw (`JOIN`): a seam's ink is the fill beside it,
- * not words.
+ * What the element an effect wraps draws in one frame: the cells the effect
+ * is handed, and the colours the element draws its words in, as the screen
+ * shows them — what an effect that must keep the words legible is measured
+ * against. A word cell is one whose glyph is not blank and that a strip's
+ * joiner did not draw (`JOIN`): a seam's ink is the fill beside it, not words.
  */
 export interface Drawn {
+    /**
+     * Every cell the element shows something in this frame — a glyph, a
+     * ground that is not the terminal's, or a line its style draws — where it
+     * sits and who drew it, listed before the effect is handed any: what
+     * an effect spread over the element — a transition, which has its last cell
+     * settle as it ends — is spread over. A blank cell on the terminal's ground
+     * that draws no line is handed but not listed, since nothing in it shows.
+     * `confined` narrows it to the cells its owners drew. A call, so a frame
+     * whose effect does not ask lists none.
+     */
+    cells(): readonly Placed[];
     /** Every distinct ink and ground of a word cell. */
     readonly pairs: readonly Pair[];
     /** The colours the element sets itself in its word cells, by hex: never the terminal's, whatever its hex. */
@@ -119,14 +141,23 @@ export interface Drawn {
     /** The terminal the frame is drawn on. */
     readonly theme: TerminalTheme;
 }
+/** What an effect does to the cells of one frame: each cell's colours and where it is in, its colours out. Return `colors` to leave a cell be. */
+export type EffectFrame = (colors: CellColors, cell: EffectCell) => CellColors;
 /**
- * The frame at time `t`, in seconds, whose element draws `drawn`: each cell's
- * colours in that frame. Return `colors` to leave a cell be.
- * [LAW:types-are-the-program] Per-frame work is the outer stage, so it runs
- * once a frame by the shape of the call, never by a cache asking whether this
- * cell's frame is the last one's.
+ * For an element drawing `drawn`, the animation of what is done to its cells.
+ * [LAW:types-are-the-program] Per-frame work is `at(t)`, so it runs once a
+ * frame by the shape of the call, never by a cache asking whether this cell's
+ * frame is the last one's.
+ *
+ * Its `nextChange` is when the frame next changes: a stepped effect its next
+ * step's start, a transition `t` until it is done and `Infinity` after, a
+ * loop that holds every cell still at the frame's depth `Infinity` there, and
+ * a loop that moves `t` (`Animation.continuous`). [LAW:types-are-the-program]
+ * The answer is a fact about the frame, so the animation is made from
+ * everything the frame is drawn from; one made from `t` alone could not say
+ * that a frame is still because of its depth.
  */
-export type Effect = (t: number, drawn: Drawn) => (colors: CellColors, cell: EffectCell) => CellColors;
+export type Effect = (drawn: Drawn) => Animation<EffectFrame>;
 export interface EffectedOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;
@@ -142,7 +173,7 @@ export interface EffectedOptions {
      */
     readonly theme: TerminalTheme;
 }
-export declare class Effected implements Renderable, Measurable {
+export declare class Effected implements Renderable, Measurable, Composite {
     readonly renderable: Renderable;
     readonly effect: Effect;
     readonly t: number;
@@ -150,6 +181,9 @@ export declare class Effected implements Renderable, Measurable {
     readonly theme: TerminalTheme;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
     render(options: RenderOptions): Iterable<Segment>;
+    contents(): Iterable<Renderable>;
+    private _moved;
+    private _recolored;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
@@ -171,6 +205,25 @@ export declare class Effected implements Renderable, Measurable {
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     private seed;
 }
+/**
+ * `effect` sampled and held on `beat`: drawn at the moment the hold in
+ * progress began (`Beat.lastChange`), so within a hold every frame is the frame
+ * at its start, and at each hold's start it moves on. A continuous effect
+ * given a short curve becomes one that steps — a `wheel` turning a sixth of
+ * a turn once a second — and at one redraw a second a hold shorter than a
+ * second is skipped, as frames are. [LAW:no-ambient-temporal-coupling] The
+ * held time is a function of `t`, so the same `t` draws the same bytes at
+ * any rate. The frame next changes at a hold's start, and only one the
+ * sampled effect has moved by: the first hold start at or after what it
+ * answers for the frame held now (`Beat.nextChange`). An effect that moves
+ * every frame makes the beat's own answer, the end of this hold; one that is
+ * done and says never leaves the beat saying never too, since the hold after
+ * this one would draw the same frame. The answer is read off what the effect
+ * says, never off a comparison of frames: an effect that steps and is back
+ * on the same colour by the next hold still turns the beat there, an early
+ * answer the contract allows.
+ */
+export declare function onBeat(effect: Effect, beat: Beat): Effect;
 /**
  * `effect` on the colours any of `owners` drew, itself or through an owner
  * nested in its output, and every other colour left as it is: one item of a

package/dist/renderables/effect.js

@@ -2,23 +2,26 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function in two stages: a time and what the element
- * draws in that frame in, a function of the frame out; and into that, a
- * cell's colours and where the cell is, the cell's new colours out. Whatever
- * holds for the whole frame is worked out in the first stage, once, and every
- * cell of the frame is handed to the second, but for those a wrapper keeps
- * back: `confined` hands over only the cells its owners drew, so a second
- * stage never counts on seeing them all. Shimmer, pulse, fade and
- * dissolve are all this one shape, differing by what the function does with
- * its inputs [LAW:one-type-per-behavior]; two effects stack by nesting one
- * wrapper in another, which is the same as calling one after the other but
- * for what the outer one measures: the inner one's output.
+ * An effect is, for what an element draws in a frame, an `Animation`
+ * (`core/animation.ts`) of what is done to its cells: its value at `t` is a
+ * function from a cell's colours and where the cell is to the cell's new
+ * colours (`EffectFrame`), and it says when that next changes as every
+ * animation does. Whatever holds for the whole frame is worked out once, in
+ * the effect and its `at(t)`, and every cell of the frame is handed to the
+ * function `at(t)` returns, but for those a wrapper keeps back: `confined`
+ * hands over only the cells its owners drew, so an effect never counts on
+ * seeing them all. Shimmer, pulse, fade and dissolve are all this one shape,
+ * differing by what the function does with its inputs
+ * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
+ * another, which is the same as calling one after the other but for what the
+ * outer one measures: the inner one's output.
  *
- * What the element draws (`Drawn`) is measured here, in the render, off the
+ * What the element draws (`Drawn`) — the cells the effect will be handed,
+ * and the colours of its words — is measured here, in the render, off the
  * same reading of each segment its cells are drawn from, and handed to the
- * effect's first stage, once a frame. It is what an effect keeping words legible is
- * settled against (`onColors`, `./effects.ts`), so no caller derives it a
- * second time from a render of its own.
+ * effect once a frame. It is what an effect keeping words legible is settled
+ * against (`onColors`, `./effects.ts`), so no caller derives it a second time
+ * from a render of its own.
  *
  * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
  * clock read. Whoever draws frames builds the view for each frame's `t`, so
@@ -33,8 +36,10 @@
  *   segment's link and meta and carries its anchor shifted to the run's first
  *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
  * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
- *   and a segment whose every cell is unchanged is yielded as it was, so the
- *   identity effect is byte-identical. Neighbouring cells the output depth
+ *   and a segment whose every cell is unchanged is yielded with its look as
+ *   it was, so the identity effect is byte-identical; what it gains is when
+ *   the frame next changes (`Style.nextChange`), which writes no byte.
+ *   Neighbouring cells the output depth
  *   writes alike stay one segment: a segment is cut only where the written
  *   colours change, so two colours that land on one index are one run.
  * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
@@ -46,10 +51,12 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { drawnBy, shiftAnchor } from "../core/anchor.js";
+import { Animation } from "../core/animation.js";
 import { cellLen, graphemes } from "../core/cells.js";
 import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
+import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { JOIN, colorsOwnedBy } from "../core/strip.js";
 import { Style } from "../core/style.js";
@@ -69,21 +76,32 @@ export class Effected {
         this.key = options.key;
         this.theme = options.theme;
     }
-    *render(options) {
-        const segments = this.renderable.render(options);
-        if (options.colorSystem === null) {
-            yield* segments;
-            return;
-        }
+    render(options) {
+        const segments = render(this.renderable, options);
+        // With no colour output nothing the effect does is written, so the child
+        // is what is shown, and it changes when the child says it does.
+        if (options.colorSystem === null)
+            return segments;
+        return this._moved(segments, options);
+    }
+    *contents() {
+        yield this.renderable;
+    }
+    *_moved(segments, options) {
         // No depth named is no downgrade, as `drawnColors` reads it.
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
         // [LAW:one-source-of-truth] The frame is measured before any cell is
-        // handed to the effect, off the same looks its cells are drawn from.
+        // handed to the effect, off the same looks its cells are drawn from, and
+        // the one measure is what the effect's animation is made from.
         const looked = looks(segments, depth, this.theme);
-        const frame = this.effect(this.t, measured(looked, depth, this.theme));
-        let row = 0;
-        let col = 0;
-        for (const { segment, look } of looked) {
+        const walked = walk(looked);
+        const animation = this.effect(measured(looked, () => walked, depth, this.theme));
+        // What the effect draws at `t` is drawn until its next change, and the
+        // cells say so, under whatever the child already said (the sooner wins).
+        yield* Segment.applyStyle(this._recolored(walked, animation.at(this.t), depth), new Style({ nextChange: animation.nextChange(this.t) }));
+    }
+    *_recolored(walked, frame, depth) {
+        for (const { segment, look, glyphs } of walked) {
             if (look === undefined) {
                 yield segment;
                 continue;
@@ -96,21 +114,9 @@ export class Effected {
             // writes, so two truecolors landing on one index stay one run. A cell
             // the effect gave its neighbour's colours is drawn as that neighbour was.
             const runs = [];
-            // Cells into the segment, as `base.shiftedBy` counts them below.
-            let into = 0;
-            for (const glyph of graphemes(segment.text)) {
-                let colors = slots;
-                if (glyph === "\n") {
-                    row++;
-                    col = 0;
-                }
-                else {
-                    const anchor = base.anchor && shiftAnchor(base.anchor, into);
-                    // Back from the screen to the style's slots: the same swap undoes itself.
-                    colors = onScreen(frame(from, { row, col, seed: this.seed(row, col), terminal, anchor }), pair.reverse);
-                    col += cellLen(glyph);
-                }
-                into += cellLen(glyph);
+            for (const { glyph, cell } of glyphs) {
+                // Back from the screen to the style's slots: the same swap undoes itself.
+                const colors = cell === undefined ? slots : onScreen(frame(from, { ...cell, seed: this.seed(cell.row, cell.col), terminal, reverse: pair.reverse }), pair.reverse);
                 const last = runs[runs.length - 1];
                 const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
                 if (last !== undefined && writesAlike(last.drawn, writes)) {
@@ -178,13 +184,101 @@ function looks(segments, depth, theme) {
         return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal, reverse } } };
     });
 }
-/** What `looked` draws its words in: `Drawn`'s measure, taken once per frame. */
-function measured(looked, depth, theme) {
+/**
+ * Each glyph of `looked`, where its cell sits: rows and columns from the
+ * top-left of the output, a wide glyph one cell at its first column, and its
+ * anchor shifted to that column as `Style.shiftedBy` shifts a run's.
+ * [LAW:one-source-of-truth] The one walk: what `Drawn.cells` lists and what
+ * the render hands the effect are read off it.
+ */
+function walk(looked) {
+    let row = 0;
+    let col = 0;
+    return looked.map(({ segment, look }) => {
+        if (look === undefined)
+            return { segment, look, glyphs: [] };
+        const anchor = look.style.anchor;
+        // Cells into the segment, as `base.shiftedBy` counts them in the render.
+        let into = 0;
+        const glyphs = [...graphemes(segment.text)].map((glyph) => {
+            const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into) };
+            [row, col] = glyph === "\n" ? [row + 1, 0] : [row, col + cellLen(glyph)];
+            into += cellLen(glyph);
+            return { glyph, cell };
+        });
+        return { segment, look, glyphs };
+    });
+}
+/** Whether `style` draws in its ink on a blank glyph: a line under, through or over it, or a frame round it. */
+function drawsLines(style) {
+    return [style.underline, style.underline2, style.strike, style.overline, style.frame, style.encircle].some((on) => on === true);
+}
+/**
+ * What `looked` draws: `Drawn`'s measure, taken once per frame. Its `cells`
+ * are listed off `walked` the first time they are asked for, since only an
+ * effect spread over the element asks, and a glyph walk is what measuring the
+ * words alone, a segment at a time, is spared (`drawnOf`).
+ */
+function measured(looked, walked, depth, theme) {
+    const ground = theme.backgroundColor.hex;
+    let listed;
+    const list = () => walked().flatMap(({ look, glyphs }) => {
+        if (look === undefined)
+            return [];
+        // A blank glyph shows its ground, and any line its style draws in its ink.
+        const blankShows = look.pair.bg.hex !== ground || drawsLines(look.style);
+        return glyphs.flatMap(({ glyph, cell }) => (cell !== undefined && (glyph.trim() !== "" || blankShows) ? [cell] : []));
+    });
     const words = looked.flatMap(({ segment, look }) => (look !== undefined && segment.text.trim() !== "" && !drawnBy(look.style.anchor, JOIN) ? [look.pair] : []));
     const pairs = [...new Map(words.map((pair) => [`${pair.fg.hex}/${pair.bg.hex}/${pair.terminal.fg}/${pair.terminal.bg}/${pair.reverse}`, pair])).values()];
     // [LAW:one-source-of-truth] A slot the terminal fills is no colour of the element's, whatever its hex.
     const own = (slot) => pairs.flatMap((pair) => (pair.terminal[slot] ? [] : [pair[slot].hex]));
-    return { pairs, colors: new Set([...own("fg"), ...own("bg")]), fills: new Set(own("bg")), depth, theme };
+    return {
+        cells: () => (listed ??= list()),
+        pairs,
+        colors: new Set([...own("fg"), ...own("bg")]),
+        fills: new Set(own("bg")),
+        depth,
+        theme,
+    };
+}
+/**
+ * `effect` sampled and held on `beat`: drawn at the moment the hold in
+ * progress began (`Beat.lastChange`), so within a hold every frame is the frame
+ * at its start, and at each hold's start it moves on. A continuous effect
+ * given a short curve becomes one that steps — a `wheel` turning a sixth of
+ * a turn once a second — and at one redraw a second a hold shorter than a
+ * second is skipped, as frames are. [LAW:no-ambient-temporal-coupling] The
+ * held time is a function of `t`, so the same `t` draws the same bytes at
+ * any rate. The frame next changes at a hold's start, and only one the
+ * sampled effect has moved by: the first hold start at or after what it
+ * answers for the frame held now (`Beat.nextChange`). An effect that moves
+ * every frame makes the beat's own answer, the end of this hold; one that is
+ * done and says never leaves the beat saying never too, since the hold after
+ * this one would draw the same frame. The answer is read off what the effect
+ * says, never off a comparison of frames: an effect that steps and is back
+ * on the same colour by the next hold still turns the beat there, an early
+ * answer the contract allows.
+ */
+export function onBeat(effect, beat) {
+    return (drawn) => {
+        const sampled = effect(drawn);
+        return {
+            at: (t) => sampled.at(beat.lastChange(t)),
+            nextChange(t) {
+                const moved = sampled.nextChange(beat.lastChange(t));
+                if (moved === Number.POSITIVE_INFINITY)
+                    return moved;
+                const end = beat.nextChange(t);
+                // The hold boundaries after `t` are `end`, then each hold's end in turn;
+                // the frame turns at the first one the effect has moved by.
+                return moved <= end ? end : beat.lastChange(moved) === moved ? moved : beat.nextChange(moved);
+            },
+            // The frame held now began at this hold's start at the latest: an early
+            // answer where the effect had not moved by it, which the contract allows.
+            lastChange: (t) => beat.lastChange(t),
+        };
+    };
 }
 /**
  * `effect` on the colours any of `owners` drew, itself or through an owner
@@ -199,16 +293,19 @@ function measured(looked, depth, theme) {
  */
 export function confined(effect, ...owners) {
     const confinedTo = new Set(owners);
-    return (t, drawn) => {
-        const frame = effect(t, drawn);
-        return (colors, cell) => {
-            const owned = colorsOwnedBy(cell.anchor, confinedTo);
-            if (!owned.fg && !owned.bg)
-                return colors;
-            const moved = frame(colors, cell);
-            return { fg: owned.fg ? moved.fg : colors.fg, bg: owned.bg ? moved.bg : colors.bg };
-        };
-    };
+    // [LAW:single-enforcer] One reading of which slots are owned, for the cells listed and the cells handed alike.
+    const ownedOf = (cell) => colorsOwnedBy(cell.anchor, confinedTo);
+    const any = ({ fg, bg }) => fg || bg;
+    // The frame as the effect sees it: the owners' cells alone. [LAW:one-source-of-truth] One narrowing, handed to both stages.
+    const owned = (drawn) => ({ ...drawn, cells: () => drawn.cells().filter((cell) => any(ownedOf(cell))) });
+    // The owners' cells change when the effect's frame does.
+    return (drawn) => Animation.map(effect(owned(drawn)), (frame) => (colors, cell) => {
+        const owns = ownedOf(cell);
+        if (!any(owns))
+            return colors;
+        const moved = frame(colors, cell);
+        return { fg: owns.fg ? moved.fg : colors.fg, bg: owns.bg ? moved.bg : colors.bg };
+    });
 }
 /**
  * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
@@ -216,7 +313,8 @@ export function confined(effect, ...owners) {
  * output under an effect to read the contrast its words are left at.
  */
 export function drawnOf(segments, depth, theme) {
-    return measured(looks(segments, depth, theme), depth, theme);
+    const looked = looks(segments, depth, theme);
+    return measured(looked, () => walk(looked), depth, theme);
 }
 /**
  * A style's colour slots as the screen shows them, or the reverse: `reverse`