@promptctl/rich-js 0.20.0 → 0.22.0

package/dist/host/input.js

@@ -16,8 +16,9 @@
  *
  * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
  * CSI sequence). When the buffer is drained but ends with a lone ESC, the
- * parser defers emission via setTimeout(0). The next chunk cancels the timer
- * if it extends the sequence. `flush()` drains it synchronously.
+ * parser defers emission via setTimeout(0). A next chunk opening with `[` or
+ * `O` extends the sequence; any other next chunk emits the ESC as Escape
+ * first. `flush()` drains it synchronously.
  */
 /**
  * The one name a key goes by — what a keymap is keyed by and what
@@ -164,12 +165,26 @@ export class InputParser {
     /** Feed a chunk of bytes (or a string of them) into the parser. */
     feed(chunk) {
         const next = typeof chunk === "string" ? UTF8_ENCODER.encode(chunk) : chunk;
-        this.buffer = concatBytes(this.buffer, next);
+        // A held lone ESC waits only for the rest of a split CSI/SS3 introducer.
+        // Any other next chunk means Escape was its own key, even when the hold
+        // timer has not run yet: a busy worker can queue the next key ahead of it,
+        // and joining them would read Escape then G as Alt+G (rich-host-input-0c4f).
+        const escaped = this.holdingEscape() && next.length > 0 && next[0] !== LBRACKET && next[0] !== O_BYTE;
         this.cancelEscape();
-        this.drain();
+        // The buffer is settled before the sink hears Escape, so a sink that
+        // resets the parser on it (an app stopping) leaves nothing to drain.
+        this.buffer = concatBytes(escaped ? EMPTY_BYTES : this.buffer, next);
+        try {
+            if (escaped)
+                this.sink.key(ESCAPE);
+        }
+        finally {
+            this.drain();
+        }
         // [LAW:dataflow-not-control-flow] If a lone ESC remains, defer emission
-        // until the next macrotask so a follow-up chunk can extend it.
-        if (this.buffer.length === 1 && this.buffer[0] === ESC) {
+        // until the next macrotask so a follow-up chunk can extend it. Only a lone
+        // one: a sequence split after `ESC [` waits for its rest, however late.
+        if (this.holdingEscape()) {
             this.escTimer = setTimeout(() => {
                 this.escTimer = undefined;
                 this.flush();
@@ -179,9 +194,9 @@ export class InputParser {
     /** Force any pending lone ESC out of the buffer. */
     flush() {
         this.cancelEscape();
-        if (this.buffer.length === 1 && this.buffer[0] === ESC) {
+        if (this.holdingEscape()) {
             this.buffer = EMPTY_BYTES;
-            this.sink.key(({ key: "escape", character: "", shift: false, ctrl: false, meta: false }));
+            this.sink.key(ESCAPE);
         }
     }
     /** Drop what is buffered and any pending lone ESC: the parser as constructed. */
@@ -189,6 +204,10 @@ export class InputParser {
         this.cancelEscape();
         this.buffer = EMPTY_BYTES;
     }
+    /** The parser's one hold: a lone ESC that may yet open a sequence. */
+    holdingEscape() {
+        return this.buffer.length === 1 && this.buffer[0] === ESC;
+    }
     cancelEscape() {
         clearTimeout(this.escTimer);
         this.escTimer = undefined;
@@ -294,7 +313,7 @@ export class InputParser {
             return {
                 kind: "key",
                 bytes: 2,
-                event: ({ key: "escape", character: "", shift: false, ctrl: false, meta: false }),
+                event: ESCAPE,
             };
         }
         // ESC <named> / ESC <printable> → Alt-modified key.
@@ -347,7 +366,7 @@ export class InputParser {
         return {
             kind: "key",
             bytes: 1,
-            event: ({ key: "escape", character: "", shift: false, ctrl: false, meta: false }),
+            event: ESCAPE,
         };
     }
     consumeSS3(buf) {

package/dist/index.d.ts

@@ -33,8 +33,8 @@ export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
 export type { RichTextOptions } from "./core/text.js";
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER, CAPSULE_JOINER, PLAIN_JOINER, gradientJoiner, } from "./core/strip.js";
-export type { StyledRenderable, Joiner, JoinShape, JoinCell, CellColor, Paint } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, JOINERS, joinerNamed, gradientJoiner, } from "./core/strip.js";
+export type { StyledRenderable, Joiner, JoinContext, JoinShape, JoinCell, CellColor, Paint } from "./core/strip.js";
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 export type { RenderToStringOptions } from "./core/render.js";
 export { OSC8, osc8Sequences } from "./core/osc8.js";
@@ -55,10 +55,10 @@ export { Console } from "./core/console.js";
 export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, LiveRegion, PrintOptions, } from "./core/console.js";
 export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
-export { Effected } from "./renderables/effect.js";
-export type { CellColors, Effect, EffectCell, EffectedOptions } from "./renderables/effect.js";
-export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shares, shimmer, sparkle, wheel, } from "./renderables/effects.js";
-export type { Curve, Field, Loop, Pair, Touch, Transition } from "./renderables/effects.js";
+export { Effected, confined, drawnOf } from "./renderables/effect.js";
+export type { CellColors, Drawn, Effect, EffectCell, EffectedOptions, Pair } from "./renderables/effect.js";
+export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
+export type { Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";

package/dist/index.js

@@ -44,7 +44,7 @@ export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
 export { Span, RichText } from "./core/text.js";
 // Strip + Joiner
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER, CAPSULE_JOINER, PLAIN_JOINER, gradientJoiner, } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, JOINERS, joinerNamed, gradientJoiner, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
@@ -69,8 +69,8 @@ export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
 export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
-export { Effected } from "./renderables/effect.js";
-export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shares, shimmer, sparkle, wheel, } from "./renderables/effects.js";
+export { Effected, confined, drawnOf } from "./renderables/effect.js";
+export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
 export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";

package/dist/renderables/effect.d.ts

@@ -2,11 +2,21 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function: a cell's colours, where the cell is, and a
- * time in, the cell's new colours out. 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.
+ * 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. 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
+ * 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.
  *
  * [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,7 +43,8 @@
  * 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 { type ColorRgba, type TerminalTheme } from "../core/color.js";
+import { type Anchor } from "../core/anchor.js";
+import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 /**
@@ -65,9 +76,55 @@ export interface EffectCell {
         readonly fg: boolean;
         readonly bg: 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
+     * from another's when their colours are alike (`confined`).
+     */
+    readonly anchor: Anchor | undefined;
+}
+/**
+ * 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`
+ * is handed for that cell.
+ */
+export interface Pair extends CellColors {
+    readonly terminal: EffectCell["terminal"];
+    /**
+     * Whether the ink is written in the style's ground slot and the ground in
+     * its ink slot. Below truecolor the slot decides what a moved colour can
+     * land on: a slot set to `default` draws the terminal's foreground in one
+     * and its background in the other.
+     */
+    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.
+ */
+export interface Drawn {
+    /** 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. */
+    readonly colors: ReadonlySet<string>;
+    /** Of `colors`, the ones a word cell has for its ground. */
+    readonly fills: ReadonlySet<string>;
+    /** The depth the frame is written at: below truecolor a moved colour lands on a palette colour. */
+    readonly depth: ColorDepth;
+    /** The terminal the frame is drawn on. */
+    readonly theme: TerminalTheme;
 }
-/** A cell's colours at time `t`, in seconds. Return `colors` to leave it be. */
-export type Effect = (colors: CellColors, cell: EffectCell, t: number) => 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.
+ */
+export type Effect = (t: number, drawn: Drawn) => (colors: CellColors, cell: EffectCell) => CellColors;
 export interface EffectedOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;
@@ -95,19 +152,35 @@ export declare class Effected implements Renderable, Measurable {
         minimum: number;
         maximum: number;
     };
+    /**
+     * 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.
+     * [LAW:one-source-of-truth] Read through `movedSpecs`, the one writer a
+     * moved slot is written with.
+     */
+    static shows(pair: Pair, to: CellColors, depth: ColorDepth, theme: TerminalTheme): CellColors;
     /**
      * The specs that draw a cell's slot colours `to` where the segment drew
-     * `from` with `wire`: a slot the effect left alone keeps its written spec,
-     * and a moved one is 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 drawn in the colour nearest it at `depth`
-     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
-     * show is no move: where the written spec is as near the moved colour as
-     * that match, the slot keeps it, so below truecolor a colour moved a little
-     * off any colour it can write — a theme slot, the default colour, the cube —
-     * is still drawn as that one.
+     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
+     * in, the rest as `wire` wrote them.
      */
     private respec;
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     private seed;
 }
+/**
+ * `effect` on the colours `owner` drew, itself or through an owner nested in
+ * its output, and every other colour left as it is: one item of a strip whose
+ * items share a fill, 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`).
+ */
+export declare function confined(effect: Effect, owner: object): Effect;
+/**
+ * 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.
+ */
+export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalTheme): Drawn;

package/dist/renderables/effect.js

@@ -2,11 +2,21 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function: a cell's colours, where the cell is, and a
- * time in, the cell's new colours out. 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.
+ * 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. 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
+ * 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.
  *
  * [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,11 +43,13 @@
  * 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 { cellLen, graphemes } from "../core/cells.js";
-import { ColorDepth, ColorSpec, SURFACE_BLACK, rgbDistance } from "../core/color.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { Segment } from "../core/segment.js";
+import { JOIN, colorsOwnedBy } from "../core/strip.js";
 import { Style } from "../core/style.js";
 export class Effected {
     renderable;
@@ -63,30 +75,27 @@ export class Effected {
         }
         // 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.
+        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 of segments) {
-            if (segment.isControl) {
+        for (const { segment, look } of looked) {
+            if (look === undefined) {
                 yield segment;
                 continue;
             }
-            const base = segment.style ?? Style.null();
-            // [LAW:single-enforcer] `drawnColors` is what the wire writes at this
-            // depth — alpha flattened, downgraded — and the theme resolves what it
-            // leaves to the terminal. A slot the effect leaves alone keeps the
-            // written spec, so it stays what the screen showed whatever moves
-            // beside it.
-            const wire = base.drawnColors(options.colorSystem ?? undefined);
-            const ink = (wire.color ?? DEFAULT).getTruecolor(this.theme, true);
-            const paper = (wire.bgcolor ?? DEFAULT).getTruecolor(this.theme, false);
-            const slots = { fg: ink, bg: paper };
-            const from = onScreen(slots, base);
-            const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, base);
+            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 = [];
+            // 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") {
@@ -94,19 +103,21 @@ export class Effected {
                     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(this.effect(from, { row, col, seed: this.seed(row, col), terminal }, this.t), base);
+                    colors = onScreen(frame(from, { row, col, seed: this.seed(row, col), terminal, anchor }), pair.reverse);
                     col += cellLen(glyph);
                 }
+                into += cellLen(glyph);
                 const last = runs[runs.length - 1];
-                const drawn = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
-                if (last !== undefined && writesAlike(last.drawn, drawn)) {
+                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 });
+                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn: writes });
                 }
             }
             if (runs.every((run) => writesAlike(run.drawn, wire))) {
@@ -125,27 +136,26 @@ export class Effected {
     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.
+     * [LAW:one-source-of-truth] Read through `movedSpecs`, the one writer a
+     * moved slot is written with.
+     */
+    static shows(pair, to, depth, theme) {
+        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);
+    }
     /**
      * The specs that draw a cell's slot colours `to` where the segment drew
-     * `from` with `wire`: a slot the effect left alone keeps its written spec,
-     * and a moved one is 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 drawn in the colour nearest it at `depth`
-     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
-     * show is no move: where the written spec is as near the moved colour as
-     * that match, the slot keeps it, so below truecolor a colour moved a little
-     * off any colour it can write — a theme slot, the default colour, the cube —
-     * is still drawn as that one.
+     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
+     * in, the rest as `wire` wrote them.
      */
     respec(wire, from, to, depth) {
-        // [LAW:one-source-of-truth] The writer's surface, so one translucent colour draws one way in a frame.
-        const ground = to.bg.compositeOver(SURFACE_BLACK);
-        const glyph = to.fg.compositeOver(ground);
-        const drawn = (spec, was, now, foreground) => {
-            const match = ColorSpec.matchOn(now, depth, this.theme, foreground);
-            return rgbDistance(was, now) <= rgbDistance(match.getTruecolor(this.theme, foreground), now) ? spec : match;
-        };
-        return { color: drawn(wire.color, from.fg, glyph, true), bgcolor: drawn(wire.bgcolor, from.bg, ground, false) };
+        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) {
@@ -153,12 +163,73 @@ export class Effected {
     }
 }
 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) {
+    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 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 } } };
+    });
+}
+/** What `looked` draws its words in: `Drawn`'s measure, taken once per frame. */
+function measured(looked, depth, theme) {
+    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 };
+}
+/**
+ * `effect` on the colours `owner` drew, itself or through an owner nested in
+ * its output, and every other colour left as it is: one item of a strip whose
+ * items share a fill, 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`).
+ */
+export function confined(effect, owner) {
+    return (t, drawn) => {
+        const frame = effect(t, drawn);
+        return (colors, cell) => {
+            const owned = colorsOwnedBy(cell.anchor, owner);
+            const moved = frame(colors, cell);
+            return { fg: owned.fg ? moved.fg : colors.fg, bg: owned.bg ? moved.bg : colors.bg };
+        };
+    };
+}
+/**
+ * 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.
+ */
+export function drawnOf(segments, depth, theme) {
+    return measured(looks(segments, depth, theme), depth, theme);
+}
 /**
  * A style's colour slots as the screen shows them, or the reverse: `reverse`
  * swaps glyph and ground, and swapping twice is where you started.
  */
-function onScreen(slots, style) {
-    return style.reverse === true ? { fg: slots.bg, bg: slots.fg } : slots;
+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
+ * `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`
+ * (`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.
+    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) };
 }
 /**
  * Whether two cells' colours are written alike. A slot with no colour is not