@promptctl/rich-js 0.24.1 → 0.25.1

package/dist/renderables/effect.js

@@ -1,20 +1,33 @@
 /**
- * Effected — a renderable whose finished cells' colours pass through an
- * effect at a moment `t`.
+ * Effected — a renderable whose finished cells' looks — colours and text
+ * attributes — pass through an effect at a moment `t`.
  *
  * 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
+ * function from a cell's look and where the cell is to the cell's new look
+ * (`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`
+ * 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,
+ * seeing them all — and for a strip's join cells painted from the items beside
+ * them, which are no one's to paint: a seam's colours are its neighbours'
+ * edges, so once the effect has painted every other cell, each such cell is
+ * resolved again from the cells beside it as the effect left them
+ * (`JoinedCell`, `../core/strip.ts`), the way the joiner drew it. Shimmer,
+ * pulse, fade, dissolve and a blinking attribute 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.
+ * [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.
+ *
+ * A cell's look is one value, its colours and its attributes together
+ * (`CellLook`), rather than an attribute stage beside the colour one, so
+ * everything that takes an `Effect` — `confined`, `onBeat`,
+ * `Animation.all`, nesting over a glyph effect — takes one that moves
+ * attributes with no second copy of itself. `reverse` is the one attribute
+ * a look leaves out (`CellAttributes`): it decides which of a style's slots
+ * a colour on screen is in, and a swap of the two is already a colour move.
  *
  * 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
@@ -23,10 +36,12 @@
  * 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
- * the same `t` always draws the same bytes, at 30 frames a second or one
- * every two seconds.
+ * An `Effected` is the element under its effect over time: an
+ * `Animation<Renderable>`, placed wherever a renderable goes and drawn at
+ * the time of the frame it is drawn in. Its value at `t` is the element
+ * through the effect at `t` (`Recolored`). [LAW:no-ambient-temporal-coupling]
+ * The time is the frame's, never a clock read, so the same time always draws
+ * the same bytes, at 30 frames a second or one every two seconds.
  *
  * What an effect may not do is the contract this module holds:
  *
@@ -36,31 +51,44 @@
  *   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 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.
+ *   one whose attributes come back as its style set them keeps them, and a
+ *   segment whose every cell is unchanged is yielded with its look as
+ *   it was, so the identity effect is byte-identical; what an `Effected` gains is when
+ *   the frame next changes (`Style.hold`), 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.
+ *   colours or the attributes change, so two colours that land on one index
+ *   are one run.
  * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
  *   string, so no frame adds an entry to a parse cache.
- * - With no colour output (`colorSystem: null`) there is nothing for an
- *   effect to change, and the child's segments pass through untouched.
+ * - With no colour output (`colorSystem: null`) no style is written at all,
+ *   attributes included, so there is nothing for an effect to change, and
+ *   the child's segments pass through untouched.
  *
  * Positions are the child's own: row and column count from the top-left of
  * 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 { Animation, frameTimeOf, holdOf, shownAt, stampFrame } 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";
-export class Effected {
+import { JOIN, joinedCell } from "../core/strip.js";
+import { ATTRIBUTE_NAMES, Style } from "../core/style.js";
+import { finiteTime } from "../core/easing.js";
+/** What drew nothing the effect can change: held forever, as far as the effect says. */
+const UNMOVED = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+/**
+ * An `Effected` at `t`, or an element through an effect at a time an
+ * animation's `at` was handed — a lifecycle's time since it entered: `renderable`
+ * with its cells' looks passed through `effect` at `t`, saying nothing of
+ * when that changes, since whatever placed the animation stamps its hold.
+ * [LAW:one-type-per-behavior]
+ */
+export class Recolored {
     renderable;
     effect;
     t;
@@ -69,25 +97,20 @@ export class Effected {
     constructor(renderable, effect, options) {
         this.renderable = renderable;
         this.effect = effect;
-        if (!Number.isFinite(options.t)) {
-            throw new RangeError(`Effected needs a finite t, got ${options.t}`);
-        }
-        this.t = options.t;
+        this.t = finiteTime("Effected", options.t);
         this.key = options.key;
         this.theme = options.theme;
     }
     render(options) {
+        return this.moved(options).segments;
+    }
+    /** The frame the effect draws at `t`, and the hold it says that is in. */
+    moved(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) {
+            return { segments, hold: UNMOVED };
         // 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
@@ -96,50 +119,213 @@ export class Effected {
         const looked = looks(segments, depth, this.theme);
         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) }));
+        const shown = shownAt(animation, this.t, options);
+        return { segments: this._recolored(walked, shown.value, depth), hold: holdOf(shown, this.t) };
     }
     *_recolored(walked, frame, depth) {
-        for (const { segment, look, glyphs } of walked) {
-            if (look === undefined) {
-                yield segment;
-                continue;
-            }
-            const { style: base, wire, slots, pair } = look;
-            const { terminal } = pair;
-            const from = { fg: pair.fg, bg: pair.bg };
-            // [LAW:one-source-of-truth] A run is cells the wire writes alike: each
-            // cell is drawn at the output depth first and merged on the colours that
-            // 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 = [];
-            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)) {
-                    last.text += glyph;
-                    last.cells += cellLen(glyph);
-                    last.colors = colors;
-                }
-                else {
-                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn: writes });
-                }
-            }
-            if (runs.every((run) => writesAlike(run.drawn, wire))) {
+        // [LAW:one-source-of-truth] Every cell but a join cell that follows its
+        // neighbours is painted first, so that cell is resolved from the cells
+        // beside it as the effect left them, wherever in the frame they fall.
+        const drawings = walked.map(({ look, glyphs }) => {
+            if (look === undefined)
+                return undefined;
+            const joined = joinedCell(look.style.anchor);
+            if (joined?.follows === true)
+                return { joined };
+            const from = { fg: look.pair.fg, bg: look.pair.bg, attributes: look.attributes };
+            const { terminal, reverse } = look.pair;
+            return { painted: glyphs.map(({ cell }) => (cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), terminal, reverse })))) };
+        });
+        const beside = edgesBeside(walked, drawings);
+        for (const [i, { segment, look, glyphs }] of walked.entries()) {
+            const drawing = drawings[i];
+            if (look === undefined || drawing === undefined)
                 yield segment;
-                continue;
+            else if ("joined" in drawing)
+                yield this._rejoined(segment, look, drawing.joined, glyphs, beside, frame, depth);
+            else
+                yield* this._repainted(segment, look, glyphs, drawing.painted, depth);
+        }
+    }
+    /** `segment`'s cells drawn in the looks the effect painted them. */
+    *_repainted(segment, look, glyphs, moved, depth) {
+        const { style: base, wire, slots, pair, attributes } = look;
+        // [LAW:one-source-of-truth] A run is cells the wire writes alike: each
+        // cell is drawn at the output depth first and merged on the colours that
+        // writes and on its attributes, so two truecolors landing on one index
+        // stay one run. A cell the effect gave its neighbour's look is drawn as
+        // that neighbour was.
+        const runs = [];
+        for (const [k, { glyph }] of glyphs.entries()) {
+            const now = moved[k];
+            // Back from the screen to the style's slots: the same swap undoes itself.
+            const colors = onScreen(now, 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) && sameAttributes(last.attributes, now.attributes)) {
+                last.text += glyph;
+                last.cells += cellLen(glyph);
+                last.colors = colors;
             }
-            let offset = 0;
-            for (const run of runs) {
-                const shifted = base.shiftedBy(offset);
-                const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
-                yield new Segment(run.text, style);
-                offset += run.cells;
+            else {
+                runs.push({ text: glyph, cells: cellLen(glyph), colors, attributes: now.attributes, drawn: writes });
             }
         }
+        if (runs.every((run) => writesAlike(run.drawn, wire) && sameAttributes(run.attributes, attributes))) {
+            yield segment;
+            return;
+        }
+        let offset = 0;
+        for (const run of runs) {
+            const placed = base.shiftedBy(offset);
+            const shifted = sameAttributes(run.attributes, attributes) ? placed : placed.withAttributes(cellAttributes(run.attributes));
+            const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
+            yield new Segment(run.text, style);
+            offset += run.cells;
+        }
+    }
+    /**
+     * A join cell's `segment` resolved again from the edges beside it, as the
+     * effect left them: each neighbour's nearest cell to the join on its row,
+     * its slots as the depth writes them. A side whose neighbour the effect moved
+     * nothing of keeps the edge the cell was drawn from, so with neither moved
+     * the cell is as it was drawn.
+     */
+    _rejoined(segment, look, joined, glyphs, beside, frame, depth) {
+        const cells = glyphs.flatMap(({ cell }) => (cell === undefined ? [] : [cell]));
+        // A join cell that draws no cell shows nothing an effect could move.
+        const [at] = cells;
+        if (at === undefined)
+            return segment;
+        const { theme } = this;
+        // [LAW:one-source-of-truth] A moved edge is the spec the depth writes its
+        // slot in, the spec the joiner reads of an item drawn so: a palette slot
+        // stays that slot, which the lift tells apart by number, never an RGB read
+        // back through a palette the writer did not use. Only the terminal's own
+        // colour names none, and the terminal the effect draws on says what it is.
+        // Each such spec is kept, so the writer below knows it by identity: an
+        // RGB a blend or another colour lands on is not the terminal's own.
+        const terminals = new Set();
+        const edgeOf = (spec, foreground) => {
+            if (!spec?.isDefault)
+                return spec;
+            const own = ColorSpec.fromRgba(spec.getTruecolor(theme, foreground));
+            terminals.add(own);
+            return own;
+        };
+        const moved = (from, to) => {
+            const specs = movedSpecs(from, to, depth, theme);
+            return specs.fg === undefined && specs.bg === undefined ? undefined : { color: edgeOf(specs.fg, true), bgcolor: edgeOf(specs.bg, false) };
+        };
+        // [LAW:one-source-of-truth] A neighbour the frame shows no cell of beside
+        // the join (cut off by a narrower container, scrolled out of a `Viewport`,
+        // covered, or an item that draws nothing) is painted by the effect where
+        // the seam shows it: its edge, as the seam drew it, handed to the frame at
+        // the seam's own cell. An effect over the whole element moves it as it
+        // moves everything there; one confined to some owners leaves it, since no
+        // owner drew the seam. Where the frame is whole and every item draws, each
+        // neighbour a seam reads has a cell on its row, so only a partial frame
+        // comes here [LAW:no-silent-failure].
+        const unseen = (edge) => {
+            const wire = edge.drawnColors(depth);
+            const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
+            const terminal = { fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true };
+            return moved(slots, returned(frame({ ...slots, attributes: cellAttributes(edge) }, { ...at, seed: cellSeed(this.key, at.row, at.col), terminal, reverse: false })));
+        };
+        const moveOf = (side) => {
+            const read = joined.reads[side];
+            if (read === null)
+                return undefined;
+            const cell = beside(cells, side, read.owner);
+            return cell === undefined ? unseen(read.edge) : moved(cell.look.slots, onScreen(cell.moved, cell.look.pair.reverse));
+        };
+        const rederived = joined.rederived({ left: moveOf("left"), right: moveOf("right") }, look.style, depth);
+        if (rederived === undefined)
+            return segment;
+        const { colors, style } = rederived;
+        // [LAW:one-source-of-truth] Each slot is written as the depth writes what
+        // it resolved to, by the writer the lift measured it with
+        // (`Style.drawnColors`), so a lifted ink stands off its ground in the bytes
+        // as it did when measured. A slot resolved to the colour it was before
+        // keeps the spec it was written in, as a painted cell's unmoved slot does.
+        // The terminal's own colours, which stand in a moved edge as the spec of
+        // the RGB the effect's terminal gives them and reach a slot unchanged or
+        // not at all, are written by the writer that wrote them on the item
+        // beside, on that terminal, which writes its own ground below truecolor as
+        // `default`.
+        const was = joined.style;
+        const drawn = colors.drawnColors(depth);
+        const { wire, slots } = look;
+        const rounded = this.respec(wire, slots, { fg: colors.color?.getTruecolor(theme, true) ?? slots.fg, bg: colors.bgcolor?.getTruecolor(theme, false) ?? slots.bg }, depth);
+        const written = (now, before, wrote, drew, round) => {
+            if (sameSpec(now, before))
+                return wrote;
+            // [LAW:no-silent-failure] Unreachable: a move only fills an edge in, so
+            // a slot that resolved to a colour when drawn resolves to one after.
+            if (now === undefined)
+                throw new Error(`a seam cell resolved to ${before?.name ?? "nothing"} when drawn and to nothing after an effect moved its neighbours`);
+            return terminals.has(now) ? round : drew;
+        };
+        const writes = {
+            color: written(colors.color, was.color, wire.color, drawn.color, rounded.color),
+            bgcolor: written(colors.bgcolor, was.bgcolor, wire.bgcolor, drawn.bgcolor, rounded.bgcolor),
+        };
+        return new Segment(segment.text, writesAlike(writes, wire) ? style : style.add(Style.fromColor(writes.color, writes.bgcolor)));
+    }
+    measure(options) {
+        return Measurement.get(options, this.renderable);
+    }
+    /**
+     * The specs that draw a cell's slot colours `to` where the segment drew
+     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
+     * in, the rest as `wire` wrote them.
+     */
+    respec(wire, from, to, depth) {
+        const moved = movedSpecs(from, to, depth, this.theme);
+        return { color: moved.fg ?? wire.color, bgcolor: moved.bg ?? wire.bgcolor };
+    }
+}
+/**
+ * `renderable` under `effect` over time: an `Animation<Renderable>` whose
+ * value at `t` is the element through the effect at `t`, placed wherever a
+ * renderable goes. Its own answer to when it changes is `t`, at every time:
+ * an `Effect` is made from what the element draws, so with nothing drawn
+ * nothing can say more — early, never false. Placed, it says exactly: its
+ * cells carry the effect's own hold at the frame's time and the output's
+ * depth (`stampFrame`), under whatever the element already said, so at a
+ * depth that shows no motion a loop says it never changes there and the
+ * host sleeps.
+ */
+export class Effected {
+    renderable;
+    effect;
+    key;
+    theme;
+    constructor(renderable, effect, options) {
+        this.renderable = renderable;
+        this.effect = effect;
+        this.key = options.key;
+        this.theme = options.theme;
+    }
+    /** The element through the effect at `t`, unstamped. */
+    at(t) {
+        return new Recolored(this.renderable, this.effect, { t, key: this.key, theme: this.theme });
+    }
+    nextChange(t) {
+        return t;
+    }
+    lastChange(t) {
+        return t;
+    }
+    /** The element under the effect with its motion taken out. */
+    reduced() {
+        const { effect } = this;
+        return new Effected(this.renderable, (drawn) => effect(drawn).reduced(), this);
+    }
+    /** Drawn at the frame's time, its cells stamped with the effect's exact hold there. */
+    render(options) {
+        const { segments, hold } = this.at(frameTimeOf(options)).moved(options);
+        return stampFrame(segments, hold);
     }
     measure(options) {
         return Measurement.get(options, this.renderable);
@@ -156,19 +342,14 @@ export class Effected {
         const moved = movedSpecs(from, onScreen(to, pair.reverse), depth, theme);
         return onScreen({ fg: moved.fg?.getTruecolor(theme, true) ?? from.fg, bg: moved.bg?.getTruecolor(theme, false) ?? from.bg }, pair.reverse);
     }
-    /**
-     * The specs that draw a cell's slot colours `to` where the segment drew
-     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
-     * in, the rest as `wire` wrote them.
-     */
-    respec(wire, from, to, depth) {
-        const moved = movedSpecs(from, to, depth, this.theme);
-        return { color: moved.fg ?? wire.color, bgcolor: moved.bg ?? wire.bgcolor };
-    }
-    /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
-    seed(row, col) {
-        return Number.parseInt(fnv1a(`${this.key}:${row}:${col}`), 16) / 0x1_0000_0000;
-    }
+}
+/**
+ * A cell's seed: FNV-1a of the element's key and the cell's position, scaled
+ * into [0, 1). [LAW:one-source-of-truth] One rule for a colour effect's seeds
+ * and a glyph effect's, so one element under both twinkles from one seed.
+ */
+export function cellSeed(key, row, col) {
+    return Number.parseInt(fnv1a(`${key}:${row}:${col}`), 16) / 0x1_0000_0000;
 }
 const DEFAULT = ColorSpec.default();
 /** Each of `segments` with how it is drawn at `depth` on `theme`; a control segment draws nothing. */
@@ -181,34 +362,87 @@ function looks(segments, depth, theme) {
         const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
         const reverse = style.reverse === true;
         const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, reverse);
-        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal, reverse } } };
+        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal, reverse }, attributes: cellAttributes(style) } };
     });
 }
 /**
- * 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.
+ * Each glyph of each of `segments`, 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. A control segment draws nothing and has none.
+ * [LAW:one-source-of-truth] The one walk: what `Drawn.cells` lists, what the
+ * render hands a colour effect, and what a glyph effect (`./glyph-effect.ts`)
+ * is handed are all read off it.
  */
-function walk(looked) {
+export function walkGlyphs(segments) {
     let row = 0;
     let col = 0;
-    return looked.map(({ segment, look }) => {
-        if (look === undefined)
-            return { segment, look, glyphs: [] };
-        const anchor = look.style.anchor;
+    return segments.map((segment) => {
+        if (segment.isControl)
+            return [];
+        const anchor = segment.style?.anchor;
         // Cells into the segment, as `base.shiftedBy` counts them in the render.
         let into = 0;
-        const glyphs = [...graphemes(segment.text)].map((glyph) => {
+        return [...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 `text` draws ink: anything but blanks. [LAW:one-source-of-truth]
+ * The one test, so the words a colour effect lights are the words a glyph
+ * effect (`./glyph-effects.ts`) scrambles and its particles pass behind.
+ */
+export function inked(text) {
+    return text.trim() !== "";
+}
+/** `looked` with each segment's glyphs placed, by the one walk. */
+function walk(looked) {
+    const placed = walkGlyphs(looked.map(({ segment }) => segment));
+    return looked.map((item, i) => ({ ...item, glyphs: placed[i] }));
+}
+/**
+ * Where to find the cells beside a join in `walked`, painted as `painted` says.
+ * Read by owner, never by column alone: a `FlexStrip` can set a gap or a
+ * justified fill between a seam and the items it joins.
+ */
+function edgesBeside(walked, drawings) {
+    let rows;
+    const index = () => {
+        const byRow = new Map();
+        walked.forEach(({ look, glyphs }, i) => {
+            const drawing = drawings[i];
+            if (look === undefined || drawing === undefined || !("painted" in drawing))
+                return;
+            const moved = drawing.painted;
+            glyphs.forEach(({ cell }, k) => {
+                if (cell === undefined)
+                    return;
+                const row = byRow.get(cell.row) ?? [];
+                row.push({ col: cell.col, anchor: cell.anchor, look, moved: moved[k] });
+                byRow.set(cell.row, row);
+            });
+        });
+        return byRow;
+    };
+    return (cells, side, owner) => {
+        // Cells on a row are listed left to right, as the walk places them.
+        const row = (rows ??= index()).get(cells[0].row) ?? [];
+        const first = cells[0].col;
+        const last = cells[cells.length - 1].col;
+        if (side === "right")
+            return row.find((cell) => cell.col > last && drawnBy(cell.anchor, owner));
+        for (let k = row.length - 1; k >= 0; k--) {
+            const cell = row[k];
+            if (cell.col < first && drawnBy(cell.anchor, owner))
+                return cell;
+        }
+        return undefined;
+    };
+}
 /** 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);
@@ -227,9 +461,9 @@ function measured(looked, walked, depth, theme) {
             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] : []));
+        return glyphs.flatMap(({ glyph, cell }) => (cell !== undefined && (inked(glyph) || blankShows) ? [cell] : []));
     });
-    const words = looked.flatMap(({ segment, look }) => (look !== undefined && segment.text.trim() !== "" && !drawnBy(look.style.anchor, JOIN) ? [look.pair] : []));
+    const words = looked.flatMap(({ segment, look }) => (look !== undefined && inked(segment.text) && !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]));
@@ -243,69 +477,28 @@ function measured(looked, walked, 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
- * nested in its output, and every other colour left as it is: one item of a
+ * `effect` on the cells any of `owners` drew, itself or through an owner
+ * nested in its output, and every other cell left as it is: one item of a
  * strip whose items share a fill, the items of a row one other item stands
- * apart from, one widget of a screen. A seam cell shows its two neighbours
- * side by side, a powerline arrow in the fill it points out of over the fill
- * it points into, so each side moves with its own item (`colorsOwnedBy`,
- * `../core/strip.ts`). A cell none of them drew is never handed to the
+ * apart from, one widget of a screen. A strip's join cell is no item's, so it
+ * is never handed; one painted from the items beside it follows them, the
+ * moved ones included (`Recolored`). A cell none of them drew is never handed to the
  * effect, so confining one effect to many owners costs one call a cell, not
  * one for each owner.
  */
 export function confined(effect, ...owners) {
     const confinedTo = new Set(owners);
-    // [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;
+    // [LAW:single-enforcer] One reading of whose a cell is, for the cells listed and the cells handed alike.
+    const owned = (cell) => {
+        for (let level = cell.anchor; level; level = level.inner)
+            if (confinedTo.has(level.owner))
+                return true;
+        return false;
+    };
     // 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))) });
+    const narrowed = (drawn) => ({ ...drawn, cells: () => drawn.cells().filter(owned) });
     // 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 };
-    });
+    return (drawn) => Animation.map(effect(narrowed(drawn)), (frame) => (look, cell) => (owned(cell) ? frame(look, cell) : look));
 }
 /**
  * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
@@ -351,6 +544,36 @@ function slotWritesAlike(a, b, foreground) {
 function written(spec, foreground) {
     return spec?.getAnsiCodes(foreground).join(";") ?? "";
 }
+/**
+ * The look a frame returned, refused at once when it carries no attributes.
+ * [LAW:no-silent-failure] A frame written before an effect moved attributes
+ * returns `{ fg, bg }`, and the effects playground runs a visitor's frame with
+ * its types stripped, not checked; unrefused, it fails as a TypeError in run
+ * merging that names neither the frame nor the contract.
+ */
+function returned(look) {
+    if (look.attributes === undefined) {
+        throw new TypeError("an effect frame returns the look it was handed with its changes, { ...look, fg, bg }: this one returned no attributes");
+    }
+    return look;
+}
+/** The attributes a look carries: `ATTRIBUTE_NAMES` but `reverse`. */
+const MOVED = ATTRIBUTE_NAMES.filter((name) => name !== "reverse");
+/**
+ * The attributes a look carries, read off anything that sets them — a
+ * `Style`, or a look a frame returned with more on it than `CellAttributes`
+ * names. [LAW:one-source-of-truth] The one place `reverse` is left out.
+ */
+export function cellAttributes(of) {
+    return Object.fromEntries(MOVED.map((name) => [name, of[name]]));
+}
+function sameAttributes(a, b) {
+    return a === b || MOVED.every((name) => a[name] === b[name]);
+}
+/** Whether two specs are one colour as written: the same kind, naming the same colour. */
+function sameSpec(a, b) {
+    return a === b || (a !== undefined && b !== undefined && a.type === b.type && a.name === b.name);
+}
 function sameColors(a, b) {
     return sameColor(a.fg, b.fg) && sameColor(a.bg, b.bg);
 }