@promptctl/rich-js 0.27.0 → 0.28.0

package/dist/host/input.js

@@ -13,8 +13,9 @@
  * "are we mid-sequence" mode flag — the buffer head carries that state, so on
  * a host whose chunks can split a key, a UTF-8 character or an escape
  * sequence split across two chunks is completed by the second. What a chunk
- * end means is the host's `InputChunks`, the one input to the parser that is
- * not a byte, and it decides only what becomes of an unfinished ESC.
+ * end means is the host's `InputChunks`, and whether an ask awaits a reply is
+ * what its owner last told `awaitReplies`: the two inputs to the parser that
+ * are not bytes, and both decide only what becomes of an unfinished ESC.
  *
  * An unfinished escape sequence is ambiguous: `ESC` alone is the Escape key
  * or the start of a sequence, and `ESC [` is Alt+[ or the start of a CSI.
@@ -29,6 +30,15 @@
  * lone ESC is also settled early by a next chunk that opens with anything but
  * `[` or `O`, because a busy worker can queue the next key behind it.
  * `flush()` settles the hold synchronously.
+ *
+ * `ESC ]`, `ESC P` and `ESC _` open the control strings a terminal replies
+ * in, and are also Alt+], Alt+P and Alt+_. A reply can arrive split only on
+ * a split host while an ask awaits one (`replyMayArrive`), and only then is an
+ * unterminated one, or a lone ESC that may open one, held — past the escape
+ * delay, until `awaitReplies(false)` arms the delay afresh. Otherwise it is Alt
+ * on its key at once. A terminated one is a reply either way, and one cut off
+ * by an ESC that is not ST was never a reply, and is Alt on its key, as with
+ * none awaited.
  */
 /**
  * The one name a key goes by — what a keymap is keyed by and what
@@ -136,6 +146,12 @@ const LANGLE = 0x3c; // <
 const O_BYTE = 0x4f; // O
 const M_UPPER = 0x4d; // M
 const M_LOWER = 0x6d; // m
+const BEL = 0x07;
+const BACKSLASH = 0x5c;
+// The control strings a terminal answers in, by the byte after ESC: OSC, DCS, APC.
+const STRING_REPLIES = { 0x5d: "osc", 0x50: "dcs", 0x5f: "apc" };
+// A CSI whose parameters open with one of these is a report, never a key.
+const PRIVATE_PREFIXES = new Set(["?", ">"]);
 // [LAW:single-enforcer] Shared encode/decode singletons. The parser
 // receives `Uint8Array | string` from the host and walks bytes through
 // its state machine; conversion happens at the two boundaries (string
@@ -198,6 +214,7 @@ export class InputParser {
     // [LAW:types-are-the-program] `setTimeout`/`clearTimeout` are universal
     // across node and browser; `setImmediate` is node-only.
     escTimer;
+    awaiting = false;
     constructor(sink, chunks) {
         this.sink = sink;
         this.chunks = chunks;
@@ -213,7 +230,9 @@ export class InputParser {
         // 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;
+        // While a reply is awaited, a next chunk opening one of its control strings
+        // continues it too: a reply split right after its ESC.
+        const escaped = this.holdingEscape() && next.length > 0 && !this.continuesEscape(next[0]);
         this.cancelEscape();
         // 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.
@@ -242,14 +261,41 @@ export class InputParser {
     // timer before it reads input queued behind a long frame, so the delay's end
     // settles the hold only after one more turn of the event loop has read what
     // was waiting. The parser holds one timer, so arming it replaces any other.
+    // While a reply may arrive the delay settles no hold that may open one: a
+    // reply split over a slow link may take longer than it. The wait's end arms
+    // it afresh (`awaitReplies`), so what is held then gets the whole delay.
     hold() {
         this.cancelEscape();
         if (this.buffer[0] !== ESC)
             return;
         this.escTimer = setTimeout(() => {
-            this.escTimer = setTimeout(() => this.flush(), 0);
+            this.escTimer = setTimeout(() => {
+                if (!this.replyMayArrive() || !opensString(this.buffer))
+                    this.flush();
+            }, 0);
         }, ESCAPE_DELAY_MS);
     }
+    /**
+     * Whether an ask is awaiting the terminal's replies, told by whoever asks
+     * at the ask's start and end. Only while one is does an unfinished
+     * `ESC ]`, `ESC P` or `ESC _` open a reply still arriving; otherwise it is
+     * Alt on that key. The wait's end restarts the escape delay for what is
+     * held, on a split host, the only one that holds.
+     */
+    awaitReplies(awaiting) {
+        this.awaiting = awaiting;
+        if (!awaiting && this.chunks === "split")
+            this.hold();
+    }
+    // [LAW:single-enforcer] The one reading of whether an unfinished control
+    // string may be a reply still arriving: only a split host splits one, and
+    // only an ask awaits one.
+    replyMayArrive() {
+        return this.chunks === "split" && this.awaiting;
+    }
+    continuesEscape(byte) {
+        return byte === LBRACKET || byte === O_BYTE || (STRING_REPLIES[byte] !== undefined && this.replyMayArrive());
+    }
     // A whole-key chunk has ended, so an ESC still at the buffer head opens no
     // sequence, and is read as `reissue` reads it. Each key is taken off the
     // buffer before the sink hears it, so no byte of one chunk outlives it.
@@ -311,6 +357,8 @@ export class InputParser {
                 this.sink.key(result.event);
             else if (result.kind === "mouse")
                 this.sink.mouse(result.event);
+            else if (result.kind === "reply")
+                this.sink.reply(result.event);
             // skip → drop bytes silently
         }
     }
@@ -377,6 +425,15 @@ export class InputParser {
         // ESC [ ... → CSI
         if (b1 === LBRACKET)
             return this.consumeCSI(buf);
+        const string = STRING_REPLIES[b1];
+        if (string !== undefined) {
+            const result = consumeString(buf, string);
+            // Unterminated where no reply may arrive, it was never a reply: Alt on
+            // its key, and what followed is read on its own.
+            if (result.kind === "incomplete" && !this.replyMayArrive())
+                return { kind: "key", bytes: 2, event: altKey(b1) };
+            return result;
+        }
         // ESC O X → SS3 (F1–F4 / arrows on some terms)
         if (b1 === O_BYTE)
             return this.consumeSS3(buf);
@@ -555,7 +612,34 @@ function decodeMouseFromCb(cb, x, y, isPress) {
         ctrl,
     };
 }
+// A lone ESC, or one opening a control string: the holds a reply may be.
+function opensString(buf) {
+    return buf.length === 1 || STRING_REPLIES[buf[1]] !== undefined;
+}
+// A control string runs to its terminator, ST (`ESC \\`) or BEL, and holds
+// any byte but ESC before it. Terminated, it is a reply whether or not one was
+// awaited. Unterminated, it is unfinished, and `consumeEscape` decides by
+// whether a reply may arrive if that means held or Alt on its key. An ESC that
+// is not ST ends it before it closed: it was never a reply, so it is Alt on
+// its key and what followed is read on its own, as with none awaited.
+function consumeString(buf, kind) {
+    for (let i = 2; i < buf.length; i++) {
+        const b = buf[i];
+        if (b === BEL)
+            return { kind: "reply", bytes: i + 1, event: { kind, body: UTF8_DECODER.decode(buf.subarray(2, i)) } };
+        if (b !== ESC)
+            continue;
+        if (i + 1 === buf.length)
+            return { kind: "incomplete" };
+        if (buf[i + 1] !== BACKSLASH)
+            return { kind: "key", bytes: 2, event: altKey(buf[1]) };
+        return { kind: "reply", bytes: i + 2, event: { kind, body: UTF8_DECODER.decode(buf.subarray(2, i)) } };
+    }
+    return { kind: "incomplete" };
+}
 function decodeCSI(params, final, bytes) {
+    if (PRIVATE_PREFIXES.has(params[0] ?? ""))
+        return { kind: "reply", bytes, event: { kind: "csi", body: params + final } };
     // Handle modifier suffixes like `1;2A` (shift+up). We split params on `;`.
     const parts = params.split(";");
     const first = parts[0] ?? "";

package/dist/host/terminal-colors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The terminal's own foreground and background, asked of it with OSC 10 and
+ * OSC 11 — the colours every contrast decision is measured against, which the
+ * library otherwise has to assume.
+ *
+ * [LAW:effects-at-boundaries] The ask is `App`'s, the one reader of its
+ * terminal's input; what is here is the query bytes and the parse of their
+ * replies, which stays pure.
+ */
+import { TerminalColors } from "../core/color.js";
+import type { App } from "./app.js";
+/**
+ * Ask the terminal `app` runs on for its foreground and background, and return
+ * the terminal `app` draws on with them in place — its sixteen ANSI colours
+ * kept, since nothing asks for those. `undefined` when the terminal did not
+ * answer both, so the caller keeps what it had. Set it as `app.terminal`.
+ */
+export declare function terminalColors(app: App): Promise<TerminalColors | undefined>;

package/dist/host/terminal-colors.js

@@ -0,0 +1,46 @@
+/**
+ * The terminal's own foreground and background, asked of it with OSC 10 and
+ * OSC 11 — the colours every contrast decision is measured against, which the
+ * library otherwise has to assume.
+ *
+ * [LAW:effects-at-boundaries] The ask is `App`'s, the one reader of its
+ * terminal's input; what is here is the query bytes and the parse of their
+ * replies, which stays pure.
+ */
+import { ColorRgba, TerminalColors } from "../core/color.js";
+import { pattern } from "../core/pattern.js";
+// OSC 10 and OSC 11 with `?` ask for the dynamic foreground and background.
+const QUERIES = ["\x1b]10;?\x1b\\", "\x1b]11;?\x1b\\"];
+// XParseColor's `rgb:` form, 1–4 hex digits a channel, as xterm and every
+// terminal that copies it answers, or `rgba:`, as urxvt answers with
+// transparency on; the alpha says nothing about the colour a cell is drawn in.
+const RGB = pattern(/^rgba?:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})(?:\/[0-9a-f]{1,4})?$/i);
+// A channel of n hex digits is a fraction of 16ⁿ − 1, scaled to 8 bits.
+const channel = (hex) => Math.round((parseInt(hex, 16) / (16 ** hex.length - 1)) * 255);
+/**
+ * The colour an OSC 10 or OSC 11 reply reports, or `undefined` when `reply`
+ * is not that answer to `slot`.
+ */
+function parseColorReply(reply, slot) {
+    if (reply.kind !== "osc")
+        return undefined;
+    const prefix = `${slot};`;
+    if (!reply.body.startsWith(prefix))
+        return undefined;
+    const match = RGB.exec(reply.body.slice(prefix.length));
+    return match === null ? undefined : new ColorRgba(channel(match[1]), channel(match[2]), channel(match[3]));
+}
+/**
+ * Ask the terminal `app` runs on for its foreground and background, and return
+ * the terminal `app` draws on with them in place — its sixteen ANSI colours
+ * kept, since nothing asks for those. `undefined` when the terminal did not
+ * answer both, so the caller keeps what it had. Set it as `app.terminal`.
+ */
+export async function terminalColors(app) {
+    const { replies } = await app.ask(QUERIES);
+    const foreground = replies.map((reply) => parseColorReply(reply, 10)).find((color) => color !== undefined);
+    const background = replies.map((reply) => parseColorReply(reply, 11)).find((color) => color !== undefined);
+    if (foreground === undefined || background === undefined)
+        return undefined;
+    return new TerminalColors(background, foreground, app.terminal.ansiColors);
+}

package/dist/host/terminal-host.d.ts

@@ -69,7 +69,8 @@ export interface TerminalHost {
     onData(handler: DataHandler): Unsubscribe;
     /**
      * Where `onData`'s chunks may end. The parser holds an unfinished escape
-     * sequence open for its rest, for the escape delay, only on a host whose
+     * sequence open for its rest — for the escape delay, or a control string
+     * for as long as an ask awaits its reply — only on a host whose
      * chunks can split one; a whole-keys host settles each chunk as it arrives,
      * because a busy worker there reads a queued next key before any timer
      * runs (rich-host-input-ab9n).

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { cellLen, setCellSize, splitText, chopCells, cellFit, graphemes, asCellC
 export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
 export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, type TerminalColors, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
 export type { ColorSystemName, DetectColorOptions, Destination, DestinationOptions } from "./core/color.js";
+export type { TextOrder } from "./core/text-order.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 export type { ThemeKey, OklchWeights } from "./core/oklch.js";
 export { Palette } from "./themes/palette.js";
@@ -19,7 +20,7 @@ export type { ColorStop, RampMotion } from "./themes/ramp.js";
 export { EASES, Phase, beat, cubicBezier, parseEase, spring, steps } from "./core/easing.js";
 export type { Beat, Ease, SpringOptions, StepPosition, Timing } from "./core/easing.js";
 export { Animation } from "./core/animation.js";
-export type { Timed } from "./core/animation.js";
+export type { Moves, Timed } from "./core/animation.js";
 export { tween } from "./core/tween.js";
 export { Timeline } from "./core/timeline.js";
 export type { View } from "./core/view.js";
@@ -63,7 +64,7 @@ export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
 export { Effected, confined, drawnOf } from "./renderables/effect.js";
 export type { CellAttributes, CellColors, CellLook, Drawn, Effect, EffectCell, EffectedOptions, EffectFrame, ListedCell, Pair, Placed } from "./renderables/effect.js";
-export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, layered, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
 export type { AttributeLoopName, Blink, ColorStep, Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.js";
 export { crossfade, wipe } from "./renderables/change.js";
 export type { Between, Change } from "./renderables/change.js";
@@ -73,8 +74,8 @@ export { scroll } from "./renderables/scroll.js";
 export type { ScrollOptions } from "./renderables/scroll.js";
 export { GlyphEffected } from "./renderables/glyph-effect.js";
 export type { DrawnGlyphs, GlyphCell, GlyphEffect, GlyphEffectedOptions, GlyphFrame } from "./renderables/glyph-effect.js";
-export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
-export type { CaseWave, GlyphLoopName, GlyphTransition, GlyphTransitionName, Particles } from "./renderables/glyph-effects.js";
+export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, marchingAnts, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
+export type { CaseWave, GlyphLoopName, GlyphTransition, GlyphTransitionName, MarchingAnts, Particles } from "./renderables/glyph-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

@@ -79,12 +79,12 @@ export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
 export { Effected, confined, drawnOf } from "./renderables/effect.js";
-export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, layered, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
 export { crossfade, wipe } from "./renderables/change.js";
 export { lifecycle, throughColors, throughGlyphs } from "./renderables/lifecycle.js";
 export { scroll } from "./renderables/scroll.js";
 export { GlyphEffected } from "./renderables/glyph-effect.js";
-export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
+export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, marchingAnts, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-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/change.d.ts

@@ -21,14 +21,12 @@
  * frame to the next, so the same `t` draws the same bytes at any frame rate.
  */
 import { Animation } from "../core/animation.js";
-import type { TerminalTheme } from "../core/color.js";
 import type { Renderable } from "../core/protocol.js";
 import { type Curve, type Transition } from "./effects.js";
-/** What a change is between: the renderable drawn until now, the one drawn from now on, and the terminal whose ground the change passes through. */
+/** What a change is between: the renderable drawn until now and the one drawn from now on. */
 export interface Between {
     readonly from: Renderable;
     readonly to: Renderable;
-    readonly theme: TerminalTheme;
 }
 /** A change from one renderable to another: what it draws at each moment, from `t = 0` on its own clock. */
 export type Change = (between: Between) => Animation<Renderable>;

package/dist/renderables/change.js

@@ -32,7 +32,7 @@ const shows = (p) => Math.abs(2 * p - 1);
 /** The change over `curve`, each cell as far through it as `progress` says. */
 function change(curve, progress) {
     requireCurve(curve);
-    return transition(curve.seconds, ({ from, to, theme }) => Animation.sequence(Animation.continuous((t) => new ChangeFrame(from, to, theme, progress, t, curve.swing)), curve.seconds, Animation.constant(to)));
+    return transition(curve.seconds, ({ from, to }) => Animation.sequence(Animation.continuous((t) => new ChangeFrame(from, to, progress, t, curve.swing)), curve.seconds, Animation.constant(to)));
 }
 /** A crossfade: the old renderable fades to the terminal's ground and the new one rises from it, every cell together, over `curve`. */
 export function crossfade(curve) {
@@ -61,14 +61,12 @@ export function wipe(curve, edge = WIPE_EDGE) {
 class ChangeFrame {
     from;
     to;
-    theme;
     progress;
     t;
     swing;
-    constructor(from, to, theme, progress, t, swing) {
+    constructor(from, to, progress, t, swing) {
         this.from = from;
         this.to = to;
-        this.theme = theme;
         this.progress = progress;
         this.t = t;
         this.swing = swing;
@@ -86,9 +84,9 @@ class ChangeFrame {
             ...splice(Segment.adjustLineLength(before[row] ?? [], lengths[row]), line, (col) => at(row, col) >= 0.5),
             ...(row < after.length - 1 || ended ? [Segment.line()] : []),
         ]);
-        // The frame says nothing of when it changes: the change's own animation says it moves every frame.
+        // The change's own animation says it moves every frame, and reads nothing this frame tells.
         const veil = veiled(() => (cell) => shows(at(cell.row, cell.col)), this.swing);
-        return render(new Recolored({ render: () => rows }, veil, { t: this.t, key: "change", theme: this.theme }), options);
+        return render(new Recolored({ render: () => rows }, veil, { t: this.t, key: "change" }), options);
     }
     measure(options) {
         return Measurement.get(options, this.to);

package/dist/renderables/effect.d.ts

@@ -17,9 +17,10 @@
  * (`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
@@ -69,12 +70,11 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { type Anchor } from "../core/anchor.js";
-import { Animation } from "../core/animation.js";
-import type { Hold } from "../core/style.js";
+import { Animation, type Moves, type Shown } from "../core/animation.js";
 import { ColorDepth, type ColorRgba, type TerminalColors } from "../core/color.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
-import { type Attributes } from "../core/style.js";
+import { type Attributes, type Hold } from "../core/style.js";
 /**
  * A cell's foreground and background as they appear on screen — the glyph's
  * colour and the colour behind it — which are the colours an effect moves.
@@ -98,33 +98,32 @@ export interface CellLook extends CellColors {
  * Where a cell is in the output of the renderable an effect wraps, its seed:
  * a number in [0, 1) that is the same for that cell on every frame, for an
  * effect that varies cell by cell (a per-cell offset in time, a sparkle) —
- * and which of its on-screen colours are the terminal's.
+ * and what the element drew it in.
  */
 export interface EffectCell {
     readonly row: number;
     readonly col: number;
     readonly seed: number;
     /**
-     * Whether the glyph's colour and the colour behind it, as the screen shows
-     * them, are the terminal's own: a slot the element's style leaves unset or
-     * sets to `default`. Such a colour is resolved through the theme, so its
-     * hex can equal one the element wrote; this is what tells them apart.
+     * The ink and ground the element drew the cell in: what the cell is, where
+     * the `CellLook` beside it is what is there now. Under one effect they are
+     * the same colours; under `layered` (`./effects.ts`) the look is what the
+     * layers beneath left, so an effect recognises a cell by its pair and moves
+     * its look. [LAW:one-source-of-truth] A pair's `terminal` is what tells a
+     * colour the terminal resolved from one the element wrote at the same hex.
      */
-    readonly terminal: {
-        readonly fg: boolean;
-        readonly bg: boolean;
-    };
-    /** Whether the cell's style swaps its two slots, as `Pair.reverse` says: with `colors` and `terminal`, the cell's `Pair`. */
-    readonly reverse: boolean;
+    readonly pair: Pair;
     /**
      * 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;
+    /** The drawing of a box the cell is the frame of (`Style.boxFrame`), or none. */
+    readonly boxFrame: object | undefined;
 }
 /** Where a cell sits and who drew it: an `EffectCell` before it has a seed or colours. */
-export type Placed = Pick<EffectCell, "row" | "col" | "anchor">;
+export type Placed = Pick<EffectCell, "row" | "col" | "anchor" | "boxFrame">;
 /**
  * A cell as `Drawn.all` lists it: where it sits and who drew it, the
  * columns its glyph takes, its ink and ground as the screen shows them, and
@@ -145,7 +144,16 @@ export interface ListedCell extends Placed {
  * is handed for that cell.
  */
 export interface Pair extends CellColors {
-    readonly terminal: EffectCell["terminal"];
+    /**
+     * Whether the glyph's colour and the colour behind it, as the screen shows
+     * them, are the terminal's own: a slot the element's style leaves unset or
+     * sets to `default`. Such a colour is resolved through the terminal, so its
+     * hex can equal one the element wrote; this is what tells them apart.
+     */
+    readonly terminal: {
+        readonly fg: boolean;
+        readonly bg: boolean;
+    };
     /**
      * 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
@@ -194,7 +202,7 @@ export interface Drawn {
     /** 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: TerminalColors;
+    readonly terminal: TerminalColors;
 }
 /** What an effect does to the cells of one frame: each cell's look and where it is in, its look out. Return `look` to leave a cell be. */
 export type EffectFrame = (look: CellLook, cell: EffectCell) => CellLook;
@@ -206,11 +214,12 @@ export type EffectFrame = (look: CellLook, cell: EffectCell) => CellLook;
  *
  * Its `nextChange` is when the frame next changes: a stepped effect its next
  * step's start, a transition `t` until it is done and `Infinity` after, a
- * loop that holds every cell still at the frame's depth `Infinity` there, and
- * a loop that moves `t` (`Animation.continuous`). [LAW:types-are-the-program]
- * The answer is a fact about the frame, so the animation is made from
- * everything the frame is drawn from; one made from `t` alone could not say
- * that a frame is still because of its depth.
+ * loop that holds every cell still, at the frame's depth or with nothing in
+ * it to move, `Infinity` there, and a loop that moves `t`
+ * (`Animation.continuous`). [LAW:types-are-the-program] The answer is a fact
+ * about the frame, so the animation is made from everything the frame is drawn
+ * from; one made from `t` alone could not say that a frame is still because of
+ * its depth.
  */
 export type Effect = (drawn: Drawn) => Animation<EffectFrame>;
 export interface EffectedOptions {
@@ -219,37 +228,30 @@ export interface EffectedOptions {
      * not twinkle in lockstep. The same key gives the same seeds on every frame.
      */
     readonly key: string;
-    /**
-     * The terminal the frame is drawn on: the colours a cell that sets none is
-     * drawn in, and the sixteen an ANSI colour names. The terminal's own palette
-     * is never queried, so the caller says what it is.
-     */
-    readonly theme: TerminalColors;
-}
-/** A frame an effect drew at a moment, and the hold the effect says it is in there. */
-export interface Moved {
-    readonly segments: Iterable<Segment>;
-    readonly hold: Hold;
 }
+/**
+ * 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 declare function holdOver(anyCell: boolean, shown: Shown<unknown>, t: number): Hold;
 /**
  * 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.onMoved`), and whatever placed the animation
+ * carries that onto the frame's and stamps it. [LAW:one-type-per-behavior]
  */
 export declare class Recolored implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly effect: Effect;
-    readonly t: number;
+    private readonly _t;
     readonly key: string;
-    readonly theme: TerminalColors;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions & {
         readonly t: number;
     });
     render(options: RenderOptions): Iterable<Segment>;
-    /** The frame the effect draws at `t`, and the hold it says that is in. */
-    moved(options: RenderOptions): Moved;
     private _recolored;
     /** `segment`'s cells drawn in the looks the effect painted them. */
     private _repainted;
@@ -275,24 +277,22 @@ export declare class Recolored implements Renderable, Measurable {
 /**
  * `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 (`Moves`), so at a depth that shows no motion a loop says it
+ * never changes there and the host sleeps.
  */
 export declare class Effected implements Animation<Renderable> {
     readonly renderable: Renderable;
     readonly effect: Effect;
     readonly key: string;
-    readonly theme: TerminalColors;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
     /** The element through the effect at `t`, unstamped. */
     at(t: number): Recolored;
-    nextChange(t: number): number;
-    lastChange(t: number): number;
+    nextChange(t: number, moves?: Moves): number;
+    lastChange(t: number, moves?: Moves): number;
     /** The element under the effect with its motion taken out. */
     reduced(): Effected;
     /** Drawn at the frame's time, its cells stamped with the effect's exact hold there. */
@@ -303,12 +303,12 @@ export declare class Effected implements Animation<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
+     * both as the screen shows them, at `depth` on `terminal`: 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: TerminalColors): CellColors;
+    static shows(pair: Pair, to: CellColors, depth: ColorDepth, terminal: TerminalColors): CellColors;
 }
 /**
  * A cell's seed: FNV-1a of the element's key and the cell's position, scaled
@@ -351,11 +351,12 @@ export declare function inked(text: string): boolean;
  */
 export declare function confined(effect: Effect, ...owners: readonly 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.
+ * 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 declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalColors): Drawn;
+export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, terminal?: TerminalColors): Drawn;
 /**
  * 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`