@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/core/markup.js

@@ -21,6 +21,8 @@ import { cellLen } from "./cells.js";
 import { Style, StyleSyntaxError } from "./style.js";
 import { RichText, stripControlChars } from "./text.js";
 import { emojiReplace } from "./emoji.js";
+import { pattern } from "./pattern.js";
+import { State } from "./state.js";
 // --- Tag ---
 export class Tag {
     name;
@@ -159,7 +161,7 @@ function excerpt(text, index) {
  */
 export function escape(text) {
     return text
-        .replace(ESCAPE_RE, (_, run, live) => live === undefined ? `${run}\\[` : `${run}${run}\\[`)
+        .replace(new RegExp(ESCAPE_RE.source, "g"), (_, run, live) => live === undefined ? `${run}\\[` : `${run}${run}\\[`)
         .replace(TRAILING_RUN_RE, "$&$&");
 }
 // --- render ---
@@ -188,18 +190,18 @@ export function escape(text) {
 // run, on exactly the untrusted text `escape` is for.
 const TAG_BODY = String.raw `[a-z#/@][^[]*?\]`;
 const RUN = String.raw `(?<!\\)(\\*)`;
-const TAG_RE = new RegExp(String.raw `${RUN}(\[${TAG_BODY})`, "g");
+const TAG_RE = pattern(new RegExp(String.raw `${RUN}(\[${TAG_BODY})`));
 /**
  * Every bracket and the run in front of it; the empty second group is set when
  * a tag starts there or could, once more text is joined after the end. It is an
  * alternation rather than `(…)?` because a quantified group may not match empty.
  */
-const ESCAPE_RE = new RegExp(String.raw `${RUN}\[(?:(?=${TAG_BODY}|(?:[a-z#/@][^[\]]*)?$)()|)`, "g");
-const TRAILING_RUN_RE = /(?<!\\)\\+$/;
+const ESCAPE_RE = pattern(new RegExp(String.raw `${RUN}\[(?:(?=${TAG_BODY}|(?:[a-z#/@][^[\]]*)?$)()|)`));
+const TRAILING_RUN_RE = pattern(/(?<!\\)\\+$/);
 function tokenize(markup) {
     const tokens = [];
     let position = 0;
-    for (const match of markup.matchAll(TAG_RE)) {
+    for (const match of markup.matchAll(new RegExp(TAG_RE.source, "g"))) {
         const run = match[1];
         const captured = match[2];
         let start = match.index;
@@ -292,9 +294,9 @@ function findLastIndex(items, match) {
 // could never fire. This tracked `[A-Za-z]` while `TAG_RE` wrongly admitted
 // uppercase, which is the same drift, one subset down (rich-markup-sec).
 const PLUGIN_TAG_NAME_SRC = "[a-z][A-Za-z0-9_-]*";
-const LEGAL_PLUGIN_TAG_NAME = new RegExp(`^${PLUGIN_TAG_NAME_SRC}$`);
+const LEGAL_PLUGIN_TAG_NAME = pattern(new RegExp(`^${PLUGIN_TAG_NAME_SRC}$`));
 export class MarkupRegistry {
-    _handlers = new Map();
+    _handlers = new State(new Map());
     register(name, handler) {
         // [LAW:no-silent-failure] Registration used to accept any string, including
         // names markup can never address (`a.b` stops the tag scan at the dot), and
@@ -305,16 +307,18 @@ export class MarkupRegistry {
         if (isReservedTagName(name)) {
             throw new MarkupError(`Cannot register markup tag "${name}": name is reserved by a built-in style.`);
         }
-        this._handlers.set(name, handler);
+        this._handlers.set(new Map(this._handlers.get()).set(name, handler));
     }
     unregister(name) {
-        this._handlers.delete(name);
+        const handlers = new Map(this._handlers.get());
+        handlers.delete(name);
+        this._handlers.set(handlers);
     }
     has(name) {
-        return this._handlers.has(name);
+        return this._handlers.get().has(name);
     }
     get(name) {
-        return this._handlers.get(name);
+        return this._handlers.get().get(name);
     }
 }
 // [LAW:one-source-of-truth] Reserved-name detection delegates to Style.parse —
@@ -356,7 +360,7 @@ function isSpace(c) {
 // continues with the whitespace that introduces attributes. Anything else —
 // `[table.header]`, `[table=x]` — is the built-in dialect's, and falls through
 // exactly as an unregistered name would.
-const PLUGIN_TAG_HEAD = new RegExp(`^(${PLUGIN_TAG_NAME_SRC})(?=$|[ \\t])`);
+const PLUGIN_TAG_HEAD = pattern(new RegExp(`^(${PLUGIN_TAG_NAME_SRC})(?=$|[ \\t])`));
 function parsePluginAttrs(after) {
     // Hand-written tokenizer. Walks `key=value` pairs separated by whitespace;
     // values may be bare, single-quoted, or double-quoted. Matches the syntax

package/dist/core/measure.js

@@ -1,7 +1,7 @@
 /**
  * Measurement — min/max cell width calculation for renderables.
  */
-import { isMeasurable, measuring } from "./protocol.js";
+import { drawsNothing, isMeasurable, measure } from "./protocol.js";
 export class Measurement {
     minimum;
     maximum;
@@ -45,11 +45,11 @@ export class Measurement {
     // `Measurement.get` answers for it — so under an unbounded offer it asks for
     // `Infinity`, and `withBoundedWidth` refuses rather than guessing a width.
     static get(options, renderable) {
-        if (options.maxWidth < 1)
+        if (drawsNothing(options))
             return new Measurement(0, 0);
         if (!isMeasurable(renderable))
             return new Measurement(0, options.maxWidth);
-        const { minimum, maximum } = renderable.measure(measuring(options));
+        const { minimum, maximum } = measure(renderable, options);
         return new Measurement(minimum, Math.min(maximum, options.maxWidth)).normalize();
     }
 }

package/dist/core/memo.d.ts

@@ -12,8 +12,17 @@ export declare const MEMO_MAX = 4096;
  * be a pure function of `key`, so a value recomputed after a clear is the one
  * that was dropped.
  */
-export declare class Memo<V extends NonNullable<unknown>> {
+export declare class Memo<V extends NonNullable<unknown>, K extends string = string> {
     private readonly entries;
     get size(): number;
-    get(key: string, compute: (key: string) => V): V;
+    get(key: K, compute: (key: K) => V): V;
+}
+/**
+ * `Memo`'s contract for a key that is an object rather than a string: a
+ * value computed once per key, for as long as the key lives. Held weakly, so
+ * it needs no bound — a key a host stops holding takes its entry with it.
+ */
+export declare class WeakMemo<V extends NonNullable<unknown>, K extends object> {
+    private readonly entries;
+    get(key: K, compute: (key: K) => V): V;
 }

package/dist/core/memo.js

@@ -32,3 +32,19 @@ export class Memo {
         return value;
     }
 }
+/**
+ * `Memo`'s contract for a key that is an object rather than a string: a
+ * value computed once per key, for as long as the key lives. Held weakly, so
+ * it needs no bound — a key a host stops holding takes its entry with it.
+ */
+export class WeakMemo {
+    entries = new WeakMap();
+    get(key, compute) {
+        const remembered = this.entries.get(key);
+        if (remembered !== undefined)
+            return remembered;
+        const value = compute(key);
+        this.entries.set(key, value);
+        return value;
+    }
+}

package/dist/core/oklch.js

@@ -96,6 +96,11 @@ function inGamut(r, g, b) {
         g >= -GAMUT_EPS && g <= 1 + GAMUT_EPS &&
         b >= -GAMUT_EPS && b <= 1 + GAMUT_EPS);
 }
+/** Polar (C, h°) → OKLab (a, b): the one spelling `deltaE` measures by and `toRgba` draws by. */
+function labOf(c, h) {
+    const hRad = h * (Math.PI / 180);
+    return [c * Math.cos(hRad), c * Math.sin(hRad)];
+}
 // ---------------------------------------------------------------------------
 // Oklch — the value type.
 // ---------------------------------------------------------------------------
@@ -130,6 +135,7 @@ export class Oklch {
         if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
             throw new RangeError(`Oklch.alpha must be a finite number in [0,1]; got ${alpha}`);
         }
+        this.#lab = labOf(c, h);
     }
     /** sRGB → linear → OKLab → polar. Pure; no I/O, no allocation beyond the result. */
     static fromRgba(color) {
@@ -265,16 +271,21 @@ export class Oklch {
      * Symmetric and pure.
      */
     deltaE(other) {
-        const a = (this.h * Math.PI) / 180;
-        const b = (other.h * Math.PI) / 180;
-        return Math.hypot(this.l - other.l, this.c * Math.cos(a) - other.c * Math.cos(b), this.c * Math.sin(a) - other.c * Math.sin(b));
+        const [a, b] = this.#lab;
+        const [otherA, otherB] = other.#lab;
+        return Math.hypot(this.l - other.l, a - otherA, b - otherB);
     }
+    /**
+     * This colour's OKLab a and b, kept with it: a colour matched against a
+     * palette is measured against every entry, and each entry against every
+     * colour it is matched with, so the trigonometry is paid once a colour
+     * rather than once a comparison.
+     */
+    #lab;
     /** Linear-sRGB coordinates for an explicit (l, C, h). Pure; `toRgba` passes
      * already-normalized values so this never sees out-of-range inputs. */
     toLinearRgb(l, C, h) {
-        const hRad = h * (Math.PI / 180);
-        const aLab = C * Math.cos(hRad);
-        const bLab = C * Math.sin(hRad);
+        const [aLab, bLab] = labOf(C, h);
         const lCube = l + 0.3963377774 * aLab + 0.2158037573 * bLab;
         const mCube = l - 0.1055613458 * aLab - 0.0638541728 * bLab;
         const sCube = l - 0.0894841775 * aLab - 1.2914855480 * bLab;

package/dist/core/osc8.d.ts

@@ -49,7 +49,7 @@ export declare const OSC8_CLOSE = "\u001B]8;;\u001B\\";
  * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
  * for composing into a larger one (a width measure's zero-width alternation).
  */
-export declare const OSC8: RegExp;
+export declare const OSC8: import("./pattern.js").Pattern;
 /** One OSC 8 sequence found in rendered bytes. A close has `uri === ""`. */
 export interface Osc8Sequence {
     /** Offset of the sequence in the scanned string. */

package/dist/core/osc8.js

@@ -31,15 +31,15 @@
  * exact, not approximate.
  */
 import { fnv1a } from "./fnv1a.js";
+import { pattern } from "./pattern.js";
 /**
  * The bytes that prematurely terminate an OSC 8 sequence: ESC (`\x1b`, which
  * begins ST `ESC \`), BEL (`\x07`), and the 8-bit ST (`\x9c`).
  */
 const TERMINATORS = "\\x1b\\x07\\x9c";
-const TERMINATOR_RE = new RegExp(`[${TERMINATORS}]`, "g");
 /** Remove every byte that could break a URL out of its OSC 8 wrap. */
 export function stripOscTerminators(url) {
-    return url.replace(TERMINATOR_RE, "");
+    return url.replace(new RegExp(`[${TERMINATORS}]`, "g"), "");
 }
 /**
  * The bytes that open a hyperlink to `url`.
@@ -62,14 +62,13 @@ export const OSC8_CLOSE = "\x1b]8;;\x1b\\";
  * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
  * for composing into a larger one (a width measure's zero-width alternation).
  */
-export const OSC8 = new RegExp(`\\x1b\\]8;([^;${TERMINATORS}]*);([^${TERMINATORS}]*)(?:\\x1b\\\\|\\x07|\\x9c)`);
-const OSC8_SCAN = new RegExp(OSC8.source, "g");
+export const OSC8 = pattern(new RegExp(`\\x1b\\]8;([^;${TERMINATORS}]*);([^${TERMINATORS}]*)(?:\\x1b\\\\|\\x07|\\x9c)`));
 /**
  * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
  * bytes back.
  */
 export function osc8Sequences(text) {
-    return [...text.matchAll(OSC8_SCAN)].map((m) => ({
+    return [...text.matchAll(new RegExp(OSC8.source, "g"))].map((m) => ({
         index: m.index,
         length: m[0].length,
         params: m[1],

package/dist/core/paint.d.ts

@@ -71,7 +71,8 @@ export declare class SurfacePainter implements Painter {
      * Paint `frame` over the last frame, leaving the cursor on its last row,
      * and return it as painted. No row is wider than the screen, since one that
      * soft-wrapped would push every row below it down a row the next paint does
-     * not go back over.
+     * not go back over. The rows returned are what `destination` shows
+     * (`shownOn`): under reduced motion, nothing in them blinks.
      */
     paint(frame: FrameSource, screen: Screen, destination: Destination): Segment[][];
     /**

package/dist/core/paint.js

@@ -13,7 +13,7 @@
  * the last row, and the newline that ends it is written once, when the frame
  * is handed back.
  */
-import { segmentsToString } from "./render.js";
+import { segmentsToString, shownOn } from "./render.js";
 import { Segment } from "./segment.js";
 const GEOMETRY = {
     alternate: {
@@ -84,10 +84,11 @@ export class SurfacePainter {
      * Paint `frame` over the last frame, leaving the cursor on its last row,
      * and return it as painted. No row is wider than the screen, since one that
      * soft-wrapped would push every row below it down a row the next paint does
-     * not go back over.
+     * not go back over. The rows returned are what `destination` shows
+     * (`shownOn`): under reduced motion, nothing in them blinks.
      */
     paint(frame, screen, destination) {
-        const rows = fitRows(frame(), screen);
+        const rows = fitRows(frame(), screen).map((row) => row.map((segment) => shownOn(segment, destination)));
         this.write(SYNC_START + this.over(rows, screen, destination) + SYNC_END);
         return rows;
     }

package/dist/core/pattern.d.ts

@@ -0,0 +1,21 @@
+/**
+ * pattern — `Pattern`: a regular expression held where every caller reaches
+ * it — module scope, a class static, a renderable's field — with no cursor
+ * for them to share.
+ *
+ * A `RegExp` carries `lastIndex`, and the `exec`, `test` and `replace` of a
+ * global or sticky one write it, so a global regex held at module scope is
+ * state that every caller moves. A regex with neither flag has a `lastIndex`
+ * that `exec`, `test`, `match`, `replace` and `split` never write. `pattern`
+ * is where that is checked: it refuses `g` and `y`, and hands back only
+ * those, with `source` and `flags` to compose it into another. A cursor — a
+ * sticky scan, a global replace — is made in the function that runs it, so
+ * each call owns its own.
+ */
+declare const PATTERN: unique symbol;
+/** A regex with no cursor: only `pattern` makes one. */
+export type Pattern = Pick<RegExp, "exec" | "test" | "source" | "flags" | typeof Symbol.match | typeof Symbol.replace | typeof Symbol.split> & {
+    readonly [PATTERN]: true;
+};
+export declare function pattern(re: RegExp): Pattern;
+export {};

package/dist/core/pattern.js

@@ -0,0 +1,21 @@
+/**
+ * pattern — `Pattern`: a regular expression held where every caller reaches
+ * it — module scope, a class static, a renderable's field — with no cursor
+ * for them to share.
+ *
+ * A `RegExp` carries `lastIndex`, and the `exec`, `test` and `replace` of a
+ * global or sticky one write it, so a global regex held at module scope is
+ * state that every caller moves. A regex with neither flag has a `lastIndex`
+ * that `exec`, `test`, `match`, `replace` and `split` never write. `pattern`
+ * is where that is checked: it refuses `g` and `y`, and hands back only
+ * those, with `source` and `flags` to compose it into another. A cursor — a
+ * sticky scan, a global replace — is made in the function that runs it, so
+ * each call owns its own.
+ */
+export function pattern(re) {
+    // [LAW:no-silent-failure] A held cursor is refused where it is made, not found later as a match that began mid-string.
+    if (re.global || re.sticky) {
+        throw new TypeError(`/${re.source}/${re.flags} keeps a cursor in lastIndex; make it in the function that runs it`);
+    }
+    return re;
+}

package/dist/core/place.js

@@ -19,6 +19,7 @@
  */
 import { Segment } from "./segment.js";
 import { Measurement } from "./measure.js";
+import { render } from "./protocol.js";
 // The share of the spare cells that goes on the left; the rest go on the right.
 // Right-alignment pads no right side at all, which is the reference's choice
 // and not a zero: a line that ends at the edge carries no trailing blanks.
@@ -39,7 +40,7 @@ export function placeBlock(renderable, align, options) {
     // (`Measurement.get` answers for it), and the block is then only as wide as
     // what it actually drew.
     const width = Measurement.get(options, renderable).maximum;
-    const drawn = Segment.splitLines(renderable.render({ ...options, maxWidth: width, height: undefined }));
+    const drawn = Segment.splitLines(render(renderable, { ...options, maxWidth: width, height: undefined }));
     const [blockWidth, height] = Segment.getShape(drawn);
     const [left, right] = PADS[align](Math.max(0, options.maxWidth - blockWidth));
     return Segment.setShape(drawn, blockWidth, height).map((line) => [...pad(left), ...line, ...pad(right)]);

package/dist/core/pretty.js

@@ -18,10 +18,12 @@
  */
 import { asCellCol, cellColToCodeUnitOffset, cellLen, graphemes, splitAtCells } from "./cells.js";
 import { divideLine } from "./wrap.js";
+import { Memo } from "./memo.js";
 import { Segment } from "./segment.js";
 import { RichText, stripControlChars } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
-import { drawable } from "./protocol.js";
+import { drawable, render } from "./protocol.js";
+import { pattern } from "./pattern.js";
 const reprHighlighter = new ReprHighlighter();
 /**
  * What a value is bounded by when whoever formats it has not seen it:
@@ -453,7 +455,7 @@ const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, join: "",
  * An index is at most 15 digits: every such literal is a safe integer and
  * names itself, where `99999999999999999999` would name `1e20`'s key.
  */
-const BARE_KEY = /^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\p{ID_Continue}$]*|0|[1-9]\d{0,14})$/u;
+const BARE_KEY = pattern(/^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\p{ID_Continue}$]*|0|[1-9]\d{0,14})$/u);
 /**
  * What Python's `str.isprintable` refuses \u2014 control, format, private-use,
  * unassigned, and every separator but the space \u2014 which Rich's repr escapes
@@ -461,9 +463,9 @@ const BARE_KEY = /^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\
  * byte reaches the terminal as a control, and a format character hides or
  * reorders what is around it.
  */
-const UNPRINTABLE = /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
+const unprintable = () => /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
 /** `value` in double quotes, every character that does not print escaped. */
-const quoted = (value) => JSON.stringify(value).replace(UNPRINTABLE, (c) => {
+const quoted = (value) => JSON.stringify(value).replace(unprintable(), (c) => {
     const hex = c.codePointAt(0).toString(16).padStart(4, "0");
     return hex.length > 4 ? `\\u{${hex}}` : `\\u${hex}`;
 });
@@ -477,7 +479,7 @@ export class Pretty {
     indentGuides;
     highlighter;
     // [LAW:no-shared-mutable-globals] A private memo, written only by `_cutString`.
-    cutStrings = new Map();
+    cutStrings = new Memo();
     constructor(data, options) {
         this.data = data;
         this.indent = options?.indent ?? 4;
@@ -491,7 +493,7 @@ export class Pretty {
     *render(options) {
         // `toText` has no `end`, for callers that set it inside a line; rendered,
         // a `Pretty` is a block of its own, as the reference's is.
-        yield* this.toText(options).render(options);
+        yield* render(this.toText(options), options);
         yield Segment.line();
     }
     /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */
@@ -595,15 +597,12 @@ export class Pretty {
      * memoised per value.
      */
     _cutString(value, max) {
-        let cut = this.cutStrings.get(value);
-        if (cut === undefined) {
+        return this.cutStrings.get(value, () => {
             const clusters = graphemes(value);
-            cut = clusters.length <= max
+            return clusters.length <= max
                 ? quoted(value)
                 : quoted(clusters.slice(0, max).join("")) + `+${clusters.length - max}`;
-            this.cutStrings.set(value, cut);
-        }
-        return cut;
+        });
     }
     /**
      * A container, or the text standing in for one that is empty or past the

package/dist/core/protocol.d.ts

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import type { Segment } from "./segment.js";
-import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
+import { Style, type Hold, type StyleSyntaxError, type Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
 import type { Highlighter } from "./highlighter.js";
 /**
@@ -17,6 +17,15 @@ import type { Highlighter } from "./highlighter.js";
  * wrapping and leaves the edge, so a line too wide is cut by the method here.
  */
 export type OverflowMethod = "fold" | "crop" | "ellipsis" | "ignore";
+/**
+ * What draws frames — a `Live`, an `App` — as what draws in them sees it:
+ * the time a frame drawn now is drawn for, the host's clock read through its
+ * timeline for a view on it (`frameTime`, `./view.ts`). Not a `Clock`: under
+ * a paused timeline it holds, and under a reversed one it runs backwards.
+ */
+export interface FrameHost {
+    readonly frameTime: number;
+}
 export interface RenderOptions {
     /**
      * The cells this renderable may occupy. A count of cells, so a non-negative
@@ -68,8 +77,8 @@ export interface RenderOptions {
     highlighter?: Highlighter;
     /**
      * The depth the output will be encoded at, `null` when it carries no colour.
-     * A renderable choosing between two ways of drawing something — the strip's
-     * arrow or its divider — decides on the colours the terminal will draw at
+     * A renderable that measures what it draws — the strip's joiner, holding a
+     * seam's ink off its ground — measures the colours the terminal will draw at
      * this depth, which at 256 colours or fewer are not the colours it was
      * handed. Absent means truecolor.
      */
@@ -87,15 +96,56 @@ export interface RenderOptions {
      */
     onStyleError?: StyleErrorHandler;
     /**
-     * Told of each owner that stamps its output (`core/anchor`) as it starts to
-     * render, so the calls arrive in document order: a container's children in
-     * the order it renders them, an owner before the owners nested in it. A
-     * container forwards it by passing its options on, which every container
-     * does. An owner rendered twice is told twice. A render made to measure is
-     * not drawing and is not told (`measuring`).
+     * The reader asked for reduced motion — CSS's `prefers-reduced-motion`,
+     * which a terminal has no way to report, so a host is told. A renderable
+     * built for the time the host draws at draws every animation reduced, its
+     * motion taken out and its content kept on time (`shownAt`,
+     * `./view.ts`; `Animation.reduced`, `./animation.ts`). Absent,
+     * everything moves. Nothing here reads it from the environment.
+     */
+    reducedMotion?: boolean;
+    /**
+     * The frame being drawn: `time`, the moment it is drawn for, in seconds, on
+     * the clock its cells' `nextChange` stamps are read on, and `host`, the
+     * host drawing it, whose `frameTime` that moment was. It is how a
+     * renderable that lives across frames — a widget, a `Progress` — draws for
+     * the time without being rebuilt each frame with one, and without reading
+     * a clock. Absent, the frame is drawn for no moment — a `print` — and
+     * nothing drawn from it moves.
+     */
+    frame?: {
+        readonly time: number;
+        readonly host: FrameHost;
+    };
+    /**
+     * Told of every renderable `render` is asked for, as it is asked, so the
+     * calls arrive in document order: a container before what it holds, what
+     * it holds in the order it renders it. `"drawn"` is a renderable drawn at
+     * the width it was handed; `"held"` is one handed no column, which is still
+     * in the view but has nothing drawn for it (`render`). A renderable rendered
+     * twice is told twice. A render made to measure is not drawing and is not
+     * told (`measuring`).
      */
-    onDraw?: (owner: object) => void;
+    onPresent?: (renderable: Renderable, presence: Presence) => void;
+    /**
+     * Told of a hold the frame is in that no cell of it may carry: an animation
+     * placed in the view reports its own, whether or not it drew a cell — one
+     * not yet entered draws none — and one a container crops away is still
+     * reported. It reaches whatever `frame` reaches, so a container that hands
+     * its child the frame's time hands back the child's hold with no word about
+     * either. [LAW:composability] Absent, nobody is listening. A measurement
+     * (`measuring`) and a held render (`holding`) tell too: what they find
+     * decides the frame's layout, so when it changes, the frame may.
+     */
+    onHold?: (hold: Hold) => void;
 }
+/** The one field of the render options that says whether the reader wants motion. */
+export type Motion = Pick<RenderOptions, "reducedMotion">;
+/**
+ * Whether a renderable the view holds was drawn, or held: in the view, handed
+ * no column, and so not drawn (`render`).
+ */
+export type Presence = "drawn" | "held";
 /** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
 export declare const isAscii: (text: string) => boolean;
 /**
@@ -210,7 +260,10 @@ export declare function getStyle(options: RenderOptions, style: string | Style):
  * every bundled theme. So where the depth would turn a fixed colour of the
  * pair into a slot, the pair is dropped and the run is drawn on the
  * terminal's own foreground and background, which its theme does make
- * readable; its attributes still set it apart. A style whose colours are
+ * readable; its attributes still set it apart. Both are named, not left
+ * unset, so the colour of whatever the run sits in — a quote, a link — does
+ * not show through: Rich's code keeps its own colours inside a quote, and the
+ * terminal's are the ones it keeps here. A style whose colours are
  * slots already (`white on blue`), or that paints no ground (`bold magenta`),
  * was written for the terminal's own colours and is drawn as written. Rich
  * draws a highlighted line number the same way below 256 colours
@@ -238,6 +291,78 @@ export declare function groundedStyle(options: RenderOptions, style: Style): Sty
  * ignored the request and emitted its full natural width.
  */
 export declare function withCellWidth(options: RenderOptions): RenderOptions;
+/** Under one column there is nothing to draw, or to measure. */
+export declare function drawsNothing(options: {
+    readonly maxWidth: number;
+}): boolean;
+/**
+ * One render pass: the outermost `render` or `measure` call — a host's frame,
+ * a print — and every `next()` of what it returned, at any depth. Opaque: it
+ * is only an identity, which a `State` compares to say whether this pass made
+ * it.
+ */
+export interface Pass {
+    readonly __pass: unique symbol;
+}
+/**
+ * `handler` run as if between passes: a callback a render makes to user code to
+ * report something it met, such as `onStyleError`, is an event handler, and may
+ * write what one may — print to a console, set a `State` — as React lets an
+ * event handler set state.
+ */
+export declare function betweenPasses<T>(handler: () => T): T;
+/** The pass a render or measure in progress belongs to, or `undefined` between passes. */
+export declare function activePass(): Pass | undefined;
+/**
+ * `effect` run once the render pass in progress has drawn its last segment,
+ * between passes, where it may write what an event handler may: React's commit
+ * phase. A render that learns something only drawing can tell it — the lines
+ * content shown through a `Viewport` runs to at the width it was handed —
+ * draws from what it learned and hands the commit here, rather than writing it
+ * as it draws.
+ *
+ * Effects run in the order they were handed over, which is document order. A
+ * measurement commits nothing, and neither does a pass that throws or whose
+ * caller stops iterating it early: nobody saw what it drew. Outside a pass — a
+ * renderable's `render` called directly — there is nothing to wait for, and
+ * `effect` runs now.
+ */
+export declare function afterPass(effect: () => void): void;
+/**
+ * `renderable` drawn under `options`: Rich's `Console.render`, which every
+ * renderable there is drawn through, so under one column nothing is.
+ *
+ * [LAW:single-enforcer] The one place that rule is kept. Every call of a
+ * `Renderable`'s `render` in `src/` goes through here — a container drawing
+ * its child, a renderable drawing the text it built, a host drawing a frame —
+ * and `test/seam/render-calls.test.ts` fails on one that does not. Before
+ * this, each container asked `drawsNothing` itself, and the ones that forgot
+ * drew a child handed no column anyway.
+ *
+ * It is where a render pass is entered (`Pass`), so it is the one place a
+ * write during render is refused at: a `State` set in a pass that did not make
+ * it throws (`./state.ts`).
+ *
+ * It is also the one reporter of what the view holds (`onPresent`). Under one
+ * column a renderable is held: in the view, with nothing of it on the frame.
+ * It is drawn all the same and what it drew dropped (`holding`), so what a held
+ * container is reported holding is what it draws, under the options it hands
+ * each child — one description of a container's traversal, not a second
+ * kept beside it.
+ */
+export declare function render(renderable: Renderable, options: RenderOptions): Iterable<Segment>;
+/**
+ * What `measurable` reports under `options`: asked in a render pass, as
+ * `render` draws in one, with `measuring`'s options.
+ *
+ * [LAW:single-enforcer] Every call of a `Measurable`'s `measure` in `src/`
+ * goes through here, as every `render` goes through `render`;
+ * `test/seam/render-calls.test.ts` holds both.
+ */
+export declare function measure(measurable: Measurable, options: RenderOptions): {
+    minimum: number;
+    maximum: number;
+};
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an
  * unbounded offer resolved to the renderable's own natural width.
@@ -273,16 +398,6 @@ export declare function withCellWidth(options: RenderOptions): RenderOptions;
  * rather than zero, and saying so names the cause — where `String.repeat` and
  * `new Array` only ever name their own argument.
  */
-/**
- * `options` as a measurement is asked with. A `measure` that renders to learn
- * its shape draws nothing on the frame, so it reports no owner to `onDraw` —
- * one that did would put a widget in document order at the moment a
- * container measured it, and keep one the frame then cropped away.
- *
- * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
- * `withBoundedWidth` ask through it, and each `measure` passes it on.
- */
-export declare function measuring(options: RenderOptions): RenderOptions;
 export declare function withBoundedWidth(options: RenderOptions, self: Measurable): RenderOptions;
 export interface Renderable {
     render(options: RenderOptions): Iterable<Segment>;