@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/renderables/effect.js

@@ -1,5 +1,5 @@
 /**
- * Effected — a renderable whose finished cells' looks — colours and text
+ * Effected — a renderable whose finished cells' looks — colors and text
  * attributes — pass through an effect at a moment `t`.
  *
  * An effect is, for what an element draws in a frame, an `Animation`
@@ -11,26 +11,27 @@
  * 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 — 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'
+ * them, which are no one's to paint: a seam's colors 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 as layers of one effect
+ * (`layered`, `./effects.ts`), each moving what the last left and recognising
+ * a cell by what the element drew (`EffectCell.pair`), or by nesting one
+ * wrapper in another, which measures the inner one's output instead.
  *
- * 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`,
+ * A cell's look is one value, its colors and its attributes together
+ * (`CellLook`), rather than an attribute stage beside the color one, so
+ * everything that takes an `Effect` — `confined`, `sampleAndHold`,
  * `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.
+ * a color on screen is in, and a swap of the two is already a color 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
+ * and the colors 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 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
@@ -50,18 +51,18 @@
  *   to the effect and is never cut, and a run cut out of a segment keeps that
  *   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`,
+ * - A cell whose colors come back unchanged keeps its original `ColorSpec`,
  *   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 or the attributes change, so two colours that land on one index
+ *   colors or the attributes change, so two colors that land on one index
  *   are one run.
- * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
+ * - New colors 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`) no style is written at all,
+ * - With no color 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.
  *
@@ -69,60 +70,67 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { drawnBy, shiftAnchor } from "../core/anchor.js";
-import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { Animation, validityOf, placedRender, shownAt } from "../core/animation.js";
 import { cellLen, graphemes } from "../core/cells.js";
-import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
+import { ColorDepth, ColorSpec, resolveTerminal, 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, joinedCell } from "../core/strip.js";
-import { ATTRIBUTE_NAMES, Style } from "../core/style.js";
+import { ATTRIBUTE_NAMES, NEVER_CHANGES, 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 };
+/**
+ * The hold an effect drawn at `t` tells: its animation's there, or held for
+ * good over no cell, since it changes how cells look and never which exist.
+ * What drew none says for itself when it will (a lifecycle not yet entered).
+ */
+export function validityOver(anyCell, shown, t) {
+    return anyCell ? validityOf(shown, t) : NEVER_CHANGES;
+}
 /**
  * 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]
+ * with its cells' looks passed through `effect` at `t`. Its cells say nothing
+ * of when that changes, since `t` is not the frame's clock: it tells the hold
+ * it drew in (`RenderOptions.onReads`), and whatever placed the animation
+ * carries that onto the frame's and stamps it. [LAW:one-type-per-behavior]
  */
 export class Recolored {
     renderable;
     effect;
-    t;
+    _t;
     key;
-    theme;
     constructor(renderable, effect, options) {
         this.renderable = renderable;
         this.effect = effect;
-        this.t = finiteTime("Effected", 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
+        // With no color 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, hold: UNMOVED };
+        if (options.colorSystem === null) {
+            options.onReads?.(this._t, this.key, NEVER_CHANGES);
+            return segments;
+        }
         // No depth named is no downgrade, as `drawnColors` reads it.
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        // [LAW:one-source-of-truth] Every color below resolves on the frame's
+        // terminal, so two effects in a frame cannot disagree.
+        const terminal = resolveTerminal(options.terminal, depth);
         // [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, and
         // the one measure is what the effect's animation is made from.
-        const looked = looks(segments, depth, this.theme);
+        const looked = looks(segments, depth, terminal);
         const walked = walk(looked);
-        const animation = this.effect(measured(looked, () => walked, depth, this.theme));
-        const shown = shownAt(animation, this.t, options);
-        return { segments: this._recolored(walked, shown.value, depth), hold: holdOf(shown, this.t) };
+        const drawn = measured(looked, () => walked, depth, terminal);
+        const shown = shownAt(this.effect(drawn), this._t, options);
+        options.onReads?.(this._t, this.key, validityOver(walked.some(({ glyphs }) => glyphs.some(({ cell }) => cell !== undefined)), shown, this._t));
+        return this._recolored(walked, shown.value, drawn);
     }
-    *_recolored(walked, frame, depth) {
+    *_recolored(walked, frame, drawn) {
         // [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.
@@ -133,8 +141,7 @@ export class Recolored {
             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 })))) };
+            return { painted: glyphs.map(({ cell }) => (cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), pair: look.pair })))) };
         });
         const beside = edgesBeside(walked, drawings);
         for (const [i, { segment, look, glyphs }] of walked.entries()) {
@@ -142,16 +149,16 @@ export class Recolored {
             if (look === undefined || drawing === undefined)
                 yield segment;
             else if ("joined" in drawing)
-                yield this._rejoined(segment, look, drawing.joined, glyphs, beside, frame, depth);
+                yield this._rejoined(segment, look, drawing.joined, glyphs, beside, frame, drawn);
             else
-                yield* this._repainted(segment, look, glyphs, drawing.painted, depth);
+                yield* this._repainted(segment, look, glyphs, drawing.painted, drawn);
         }
     }
     /** `segment`'s cells drawn in the looks the effect painted them. */
-    *_repainted(segment, look, glyphs, moved, depth) {
+    *_repainted(segment, look, glyphs, moved, drawn) {
         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
+        // cell is drawn at the output depth first and merged on the colors 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.
@@ -161,7 +168,7 @@ export class Recolored {
             // 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);
+            const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, drawn);
             if (last !== undefined && writesAlike(last.drawn, writes) && sameAttributes(last.attributes, now.attributes)) {
                 last.text += glyph;
                 last.cells += cellLen(glyph);
@@ -191,30 +198,30 @@ export class Recolored {
      * 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) {
+    _rejoined(segment, look, joined, glyphs, beside, frame, measure) {
+        const { depth, terminal } = measure;
         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.
+        // color 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.
+        // RGB a blend or another color 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));
+            const own = ColorSpec.fromRgba(spec.getTruecolor(terminal, foreground));
             terminals.add(own);
             return own;
         };
         const moved = (from, to) => {
-            const specs = movedSpecs(from, to, depth, theme);
+            const specs = movedSpecs(from, to, depth, terminal);
             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
@@ -228,9 +235,9 @@ export class Recolored {
         // 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 slots = { fg: (wire.color ?? DEFAULT).getTruecolor(terminal, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(terminal, false) };
+            const own = { 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), pair: { ...slots, terminal: own, reverse: false } })));
         };
         const moveOf = (side) => {
             const read = joined.reads[side];
@@ -246,9 +253,9 @@ export class Recolored {
         // [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
+        // as it did when measured. A slot resolved to the color 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 terminal's own colors, 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
@@ -256,12 +263,12 @@ export class Recolored {
         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 rounded = this.respec(wire, slots, { fg: colors.color?.getTruecolor(terminal, true) ?? slots.fg, bg: colors.bgcolor?.getTruecolor(terminal, false) ?? slots.bg }, measure);
         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.
+            // a slot that resolved to a color 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;
@@ -276,46 +283,43 @@ export class Recolored {
         return Measurement.get(options, this.renderable);
     }
     /**
-     * The specs that draw a cell's slot colours `to` where the segment drew
+     * The specs that draw a cell's slot colors `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);
+    respec(wire, from, to, { depth, terminal }) {
+        const moved = movedSpecs(from, to, depth, terminal);
         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.
+ * renderable goes. An `Effect` is made from what the element draws, so with
+ * nothing drawn its answer to when it changes is `t`, at every time: early,
+ * never false. Placed, on its own or as a part of any combinator, it says
+ * exactly: the frame's drawing told the effect's hold at that time and the
+ * output's depth (`Reads`), 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 });
+        return new Recolored(this.renderable, this.effect, { t, key: this.key });
     }
-    nextChange(t) {
-        return t;
+    validUntil(t, moves) {
+        return moves?.(t, this.key)?.validUntil ?? t;
     }
-    lastChange(t) {
-        return t;
+    validFrom(t, moves) {
+        return moves?.(t, this.key)?.validFrom ?? t;
     }
     /** The element under the effect with its motion taken out. */
     reduced() {
@@ -324,45 +328,44 @@ export class Effected {
     }
     /** 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);
+        return placedRender(this, options);
     }
     measure(options) {
         return Measurement.get(options, this.renderable);
     }
     /**
-     * The colours the screen shows for `pair` once it is drawn moved to `to`,
-     * both as the screen shows them, at `depth` on `theme`: what an effect
-     * moving a pair's colours leaves its words reading in.
+     * The colors the screen shows for `pair` once it is drawn moved to `to`,
+     * both as the screen shows them, at `depth` on `terminal`: what an effect
+     * moving a pair's colors leaves its words reading in.
      * [LAW:one-source-of-truth] Read through `movedSpecs`, the one writer a
      * moved slot is written with.
      */
-    static shows(pair, to, depth, theme) {
+    static shows(pair, to, depth, terminal) {
         const from = onScreen(pair, pair.reverse);
-        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);
+        const moved = movedSpecs(from, onScreen(to, pair.reverse), depth, terminal);
+        return onScreen({ fg: moved.fg?.getTruecolor(terminal, true) ?? from.fg, bg: moved.bg?.getTruecolor(terminal, false) ?? from.bg }, pair.reverse);
     }
 }
 /**
  * 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
+ * into [0, 1). [LAW:one-source-of-truth] One rule for a color 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. */
-function looks(segments, depth, theme) {
+/** Each of `segments` with how it is drawn at `depth` on `terminal`; a control segment draws nothing. */
+function looks(segments, depth, terminal) {
     return [...segments].map((segment) => {
         if (segment.isControl)
             return { segment, look: undefined };
         const style = segment.style ?? Style.null();
         const wire = style.drawnColors(depth);
-        const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
+        const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(terminal, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(terminal, 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 }, attributes: cellAttributes(style), seam: drawnBy(style.anchor, JOIN) } };
+        const own = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, reverse);
+        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal: own, reverse }, attributes: cellAttributes(style), seam: drawnBy(style.anchor, JOIN) } };
     });
 }
 /**
@@ -371,7 +374,7 @@ function looks(segments, depth, theme) {
  * 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`)
+ * render hands a color effect, and what a glyph effect (`./glyph-effect.ts`)
  * is handed are all read off it.
  */
 export function walkGlyphs(segments) {
@@ -381,10 +384,11 @@ export function walkGlyphs(segments) {
         if (segment.isControl)
             return [];
         const anchor = segment.style?.anchor;
+        const boxFrame = segment.style?.boxFrame;
         // Cells into the segment, as `base.shiftedBy` counts them in the render.
         let into = 0;
         return [...graphemes(segment.text)].map((glyph) => {
-            const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into) };
+            const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into), boxFrame };
             const width = cellLen(glyph);
             [row, col] = glyph === "\n" ? [row + 1, 0] : [row, col + width];
             into += width;
@@ -394,7 +398,7 @@ export function walkGlyphs(segments) {
 }
 /**
  * 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
+ * The one test, so the words a color effect lights are the words a glyph
  * effect (`./glyph-effects.ts`) scrambles and its particles pass behind.
  */
 export function inked(text) {
@@ -446,17 +450,17 @@ function edgesBeside(walked, drawings) {
 }
 /** 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);
+    return [style.underline, style.doubleUnderline, style.strike, style.overline, style.frame, style.encircle].some((on) => on === true);
 }
 /**
  * What `looked` draws: `Drawn`'s measure, taken once per frame. Its `all`
  * and `cells` are listed off `walked` the first time either is asked for,
- * since only an effect spread over the element or turning its runs asks, and
+ * since an effect on attributes alone never 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;
+function measured(looked, walked, depth, terminal) {
+    const ground = terminal.backgroundColor.hex;
     // [LAW:one-source-of-truth] One listing, each cell with whether it shows; `all` and `cells` are read off it.
     let everything;
     const list = () => walked().flatMap(({ look, glyphs }) => {
@@ -471,7 +475,7 @@ function measured(looked, walked, depth, theme) {
     let shown;
     const words = looked.flatMap(({ segment, look }) => (look !== undefined && inked(segment.text) && !look.seam ? [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.
+    // [LAW:one-source-of-truth] A slot the terminal fills is no color of the element's, whatever its hex.
     const own = (slot) => pairs.flatMap((pair) => (pair.terminal[slot] ? [] : [pair[slot].hex]));
     return {
         all: () => (all ??= listed().map(({ cell }) => cell)),
@@ -480,7 +484,7 @@ function measured(looked, walked, depth, theme) {
         colors: new Set([...own("fg"), ...own("bg")]),
         fills: new Set(own("bg")),
         depth,
-        theme,
+        terminal,
     };
 }
 /**
@@ -503,43 +507,49 @@ export function confined(effect, ...owners) {
         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 narrowed = (drawn) => ({ ...drawn, all: () => drawn.all().filter(owned), cells: () => drawn.cells().filter(owned) });
+    const narrowed = (drawn) => {
+        let all;
+        let cells;
+        return { ...drawn, all: () => (all ??= drawn.all().filter(owned)), cells: () => (cells ??= drawn.cells().filter(owned)) };
+    };
     // The owners' cells change when the effect's frame does.
     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
- * as `Effected` measures its child for every frame. Measure an element's
- * output under an effect to read the contrast its words are left at.
+ * What `segments`, drawn at `depth` on `terminal`, draw their words in, measured
+ * as `Effected` measures its child for every frame, so `options.terminal` means
+ * here what it means on a frame. Measure an element's output under an effect to
+ * read the contrast its words are left at.
  */
-export function drawnOf(segments, depth, theme) {
-    const looked = looks(segments, depth, theme);
-    return measured(looked, () => walk(looked), depth, theme);
+export function drawnOf(segments, depth, terminal) {
+    const on = resolveTerminal(terminal, depth);
+    const looked = looks(segments, depth, on);
+    return measured(looked, () => walk(looked), depth, on);
 }
 /**
- * A style's colour slots as the screen shows them, or the reverse: `reverse`
+ * A style's color slots as the screen shows them, or the reverse: `reverse`
  * swaps glyph and ground, and swapping twice is where you started.
  */
 function onScreen(slots, reverse) {
     return reverse ? { fg: slots.bg, bg: slots.fg } : slots;
 }
 /**
- * The specs a cell's slots are written in once their colours move from
+ * The specs a cell's slots are written in once their colors move from
  * `from`, what the written specs draw, to `to`: each laid on what is beneath
  * it — the ground on `SURFACE_BLACK`, the glyph on that ground, as the writer
- * lays any translucent colour (`Style.drawnColors`) — then matched at `depth`
+ * lays any translucent color (`Style.drawnColors`) — then matched at `depth`
  * (`ColorSpec.matchMove`). A slot the depth shows no move in has none, and
  * keeps the spec it was written in.
  */
-function movedSpecs(from, to, depth, theme) {
-    // [LAW:one-source-of-truth] The writer's surface, so one translucent colour draws one way in a frame.
+function movedSpecs(from, to, depth, terminal) {
+    // [LAW:one-source-of-truth] The writer's surface, so one translucent color draws one way in a frame.
     const ground = to.bg.compositeOver(SURFACE_BLACK);
     const glyph = to.fg.compositeOver(ground);
-    return { fg: ColorSpec.matchMove(from.fg, glyph, depth, theme, true), bg: ColorSpec.matchMove(from.bg, ground, depth, theme, false) };
+    return { fg: ColorSpec.matchMove(from.fg, glyph, depth, terminal, true), bg: ColorSpec.matchMove(from.bg, ground, depth, terminal, false) };
 }
 /**
- * Whether two cells' colours are written alike. A slot with no colour is not
- * the default colour: it writes nothing, so a style a container lays beneath
+ * Whether two cells' colors are written alike. A slot with no color is not
+ * the default color: it writes nothing, so a style a container lays beneath
  * (`Segment.applyStyle`) still shows through it, where `39`/`49` would not.
  */
 function writesAlike(a, b) {
@@ -577,7 +587,7 @@ export function cellAttributes(of) {
 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. */
+/** Whether two specs are one color as written: the same kind, naming the same color. */
 function sameSpec(a, b) {
     return a === b || (a !== undefined && b !== undefined && a.type === b.type && a.name === b.name);
 }