@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/core/protocol.js

@@ -113,6 +113,108 @@ export function withCellWidth(options) {
 export function drawsNothing(options) {
     return cellCount(options.maxWidth) < 1;
 }
+// [LAW:no-shared-mutable-globals] The render phase, owned here and nowhere
+// else: only `render` and `measure` below open or enter a pass, and the rest of
+// the library reads it through `activePass` and `afterPass`. Set and restored
+// like a stack, so "not rendering" is `undefined` and needs no counter.
+let active;
+function runIn(phase, run) {
+    const outer = active;
+    active = phase;
+    try {
+        return run();
+    }
+    finally {
+        active = outer;
+    }
+}
+/**
+ * `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 function betweenPasses(handler) {
+    return runIn(undefined, handler);
+}
+/** The pass a render or measure in progress belongs to, or `undefined` between passes. */
+export function activePass() {
+    return active?.pass;
+}
+/**
+ * `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 function afterPass(effect) {
+    if (active === undefined)
+        effect();
+    else
+        active.effects.push(effect);
+}
+/** The pass in progress, or a new one when this call is the outermost. */
+const phaseHere = () => active ?? { pass: {}, effects: [] };
+/**
+ * Every effect `phase`'s renders handed it, run now that it has ended — between
+ * passes even when the iteration that ended it was stepped inside another.
+ */
+function commit(phase) {
+    runIn(undefined, () => {
+        for (const effect of phase.effects.splice(0))
+            effect();
+    });
+}
+/**
+ * `drawn` with every step of its iteration run in `phase`, and its effects
+ * committed when the last step is done. A render is often a generator, whose
+ * body runs as its caller iterates — after `render` has returned — so the pass
+ * is re-entered on each `next()`, however many `yield`s a write sits behind,
+ * and ends only when the iteration does. An array has nothing left to run, so
+ * its pass has already ended.
+ *
+ * Only the call that opens the pass is wrapped. A nested render's steps run
+ * inside its parent's, which are already in the pass; a nested iterable could
+ * only be stepped outside it by being kept somewhere past the render, which
+ * takes a writable location `test/seam/render-purity.test.ts` refuses. Wrapping
+ * every level cost a third of the render time, once per segment per level.
+ */
+function withinPass(phase, drawn) {
+    if (Array.isArray(drawn)) {
+        commit(phase);
+        return drawn;
+    }
+    return {
+        [Symbol.iterator]: () => {
+            const steps = runIn(phase, () => drawn[Symbol.iterator]());
+            // On `%IteratorPrototype%`, as a generator's iterator is: iterable
+            // itself, and carrying the iterator helpers where the engine has them.
+            return Object.assign(Object.create(ITERATOR_PROTOTYPE), {
+                next: () => {
+                    const step = runIn(phase, () => steps.next());
+                    if (step.done === true)
+                        commit(phase);
+                    return step;
+                },
+                return: (value) => runIn(phase, () => steps.return?.(value) ?? { done: true, value: undefined }),
+                throw: (error) => runIn(phase, () => {
+                    if (steps.throw)
+                        return steps.throw(error);
+                    throw error;
+                }),
+            });
+        },
+    };
+}
+const ITERATOR_PROTOTYPE = Object.getPrototypeOf(Object.getPrototypeOf([][Symbol.iterator]()));
 /**
  * `renderable` drawn under `options`: Rich's `Console.render`, which every
  * renderable there is drawn through, so under one column nothing is.
@@ -124,34 +226,81 @@ export function drawsNothing(options) {
  * 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, not drawn: what it holds (`Composite`) is
- * walked and reported held in turn, and nothing renders, so no renderable
- * that keeps state while it renders — a `Viewport`'s offset, a `TextInput`'s
- * scroll window — ever commits it at a width that is not shown. The walk runs
- * whether or not anyone listens. Drawing the squeezed subtree at one column
- * instead, and dropping what it drew, did commit that state.
+ * 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 function render(renderable, options) {
+    const opens = active === undefined;
     const presence = drawsNothing(options) ? "held" : "drawn";
-    options.onPresent?.(renderable, presence);
-    if (presence === "drawn")
-        return renderable.render(options);
-    if (isComposite(renderable))
-        for (const content of renderable.contents())
-            render(content, options);
-    return [];
+    const { phase, drawing } = presence === "drawn" ? { phase: phaseHere(), drawing: options } : holding(options);
+    const drawn = runIn(phase, () => {
+        options.onPresent?.(renderable, presence);
+        return renderable.render(drawing);
+    });
+    if (presence === "held") {
+        runIn(phase, () => {
+            for (const _ of drawn)
+                ;
+        });
+        return [];
+    }
+    return opens ? withinPass(phase, drawn) : drawn;
+}
+/**
+ * Where a held renderable is drawn, and the options it is drawn under: what
+ * it draws is dropped, and everything it draws is reported held, whatever
+ * width it hands it. What it tells of its hold (`onHold`) still reaches the
+ * frame: an element not yet entered is held at no width, and must say when it
+ * enters and takes some. A motion held at no width therefore wakes its host
+ * for frames that look the same: when it next takes room is not a moment its
+ * hold can name, and an early answer costs a frame where a late one hides the
+ * element. It commits nothing, as a measurement commits nothing —
+ * its effects (`afterPass`) are learned at a width nobody sees, so a
+ * `Viewport` it shows content through keeps the scroll the last frame shown
+ * left it.
+ *
+ * [LAW:parse-dont-validate] It is drawn at no column, 0, whatever width under
+ * one its container worked out: `drawsNothing` reads a negative or NaN width
+ * as none, so none reaches a `render`, where it would be a count no string
+ * can repeat.
+ */
+function holding(options) {
+    const { onPresent } = options;
+    return {
+        phase: { pass: phaseHere().pass, effects: [] },
+        drawing: { ...options, maxWidth: 0, onPresent: onPresent && ((content) => onPresent(content, "held")) },
+    };
+}
+/**
+ * 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 function measure(measurable, options) {
+    // The pass's identity, with effects nothing runs: a measurement commits nothing.
+    return runIn({ pass: phaseHere().pass, effects: [] }, () => measurable.measure(measuring(options)));
 }
 /**
  * `options` as a measurement is asked with. A `measure` that renders to learn
  * its shape draws nothing on the frame, so it reports nothing to `onPresent` —
  * one that did would put a widget in the view at the moment a container
- * measured it, and keep one the frame then cropped away.
+ * measured it, and keep one the frame then cropped away. It still tells its
+ * hold (`onHold`): a layout decided by a measurement changes when it does.
  *
- * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
- * `withBoundedWidth` ask through it, and each `measure` passes it on.
+ * [LAW:single-enforcer] Every measurement starts here: `measure` asks with it.
  */
-export function measuring(options) {
+function measuring(options) {
     return { ...options, onPresent: undefined };
 }
 /**
@@ -193,7 +342,7 @@ export function withBoundedWidth(options, self) {
     const parsed = withCellWidth(options);
     if (Number.isFinite(parsed.maxWidth))
         return parsed;
-    const natural = self.measure(measuring(parsed)).maximum;
+    const natural = measure(self, parsed).maximum;
     if (!Number.isFinite(natural)) {
         throw new RangeError("maxWidth is unbounded and this renderable has no natural width to fall " +
             "back on: its content does not implement measure(), or something inside " +
@@ -220,6 +369,3 @@ export function isScrollable(obj) {
         "scrollBy" in obj &&
         typeof obj.scrollBy === "function");
 }
-export function isComposite(obj) {
-    return "contents" in obj && typeof obj.contents === "function";
-}

package/dist/core/render.d.ts

@@ -40,13 +40,16 @@
  * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
  * follows OSC 8. This is where the port departs from the reference, whose
  * `Style.render` returns bare text for a null colour system.
+ *
+ * The third fact, `reducedMotion`, changes the segment rather than its
+ * encoding: `shownOn` takes the style's blink out before it is encoded.
  */
 import { ColorDepth } from "./color.js";
 import type { ColorSystemName, Destination } from "./color.js";
 import type { Env } from "./env.js";
-import type { Segment } from "./segment.js";
+import { Segment } from "./segment.js";
 import type { Renderable, RenderOptions } from "./protocol.js";
-export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
     /** Cell width to render into. Default 80. */
     width?: number;
     /**
@@ -77,6 +80,16 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
      */
     hyperlinks?: boolean;
 }
+/**
+ * `segment` as `destination` shows it: under reduced motion its style
+ * `reduced()`, so the terminal is never asked to blink it.
+ *
+ * [LAW:single-enforcer] The one place reduced motion reaches a style's own
+ * motion. Drawing cannot do it: a console lays its print and base styles over
+ * what was drawn, after `render`. The encoder writes what this returns, and a
+ * recording console records it, so every export replays what was written.
+ */
+export declare function shownOn(segment: Segment, destination: Destination): Segment;
 /**
  * Encodes one segment as ANSI bytes for `destination`: the reference's
  * `Style.render` for that segment, and nothing for a control segment.

package/dist/core/render.js

@@ -40,11 +40,28 @@
  * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
  * follows OSC 8. This is where the port departs from the reference, whose
  * `Style.render` returns bare text for a null colour system.
+ *
+ * The third fact, `reducedMotion`, changes the segment rather than its
+ * encoding: `shownOn` takes the style's blink out before it is encoded.
  */
 import { ColorDepth, resolveDestination } from "./color.js";
+import { Segment } from "./segment.js";
 import { render } from "./protocol.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 const DEFAULT_WIDTH = 80;
+/**
+ * `segment` as `destination` shows it: under reduced motion its style
+ * `reduced()`, so the terminal is never asked to blink it.
+ *
+ * [LAW:single-enforcer] The one place reduced motion reaches a style's own
+ * motion. Drawing cannot do it: a console lays its print and base styles over
+ * what was drawn, after `render`. The encoder writes what this returns, and a
+ * recording console records it, so every export replays what was written.
+ */
+export function shownOn(segment, destination) {
+    const style = destination.reducedMotion ? segment.style?.reduced() : segment.style;
+    return style === segment.style ? segment : new Segment(segment.text, style, segment.control);
+}
 /**
  * Encodes one segment as ANSI bytes for `destination`: the reference's
  * `Style.render` for that segment, and nothing for a control segment.
@@ -52,7 +69,7 @@ const DEFAULT_WIDTH = 80;
 export function segmentToString(segment, destination) {
     if (segment.isControl)
         return "";
-    const { text, style } = segment;
+    const { text, style } = shownOn(segment, destination);
     // As the reference's `if not text` and `if style:` — no pair around nothing.
     if (text.length === 0 || style === undefined)
         return text;
@@ -75,18 +92,19 @@ export function renderToString(renderable, options) {
     // [LAW:dataflow-not-control-flow] An absent spec is truecolor; an explicit
     // `null` stays null (`??` would collapse it).
     // [LAW:single-enforcer] Specs resolve through `resolveDestination`.
-    const detectOptions = {};
+    const destinationOptions = { reducedMotion: options?.reducedMotion };
     if (options?.env !== undefined)
-        detectOptions.env = options.env;
+        destinationOptions.env = options.env;
     if (options?.isTTY !== undefined)
-        detectOptions.isTTY = options.isTTY;
+        destinationOptions.isTTY = options.isTTY;
     const rawSpec = options?.colorSystem;
-    const resolved = resolveDestination(rawSpec === undefined ? ColorDepth.TRUECOLOR : rawSpec, detectOptions);
+    const resolved = resolveDestination(rawSpec === undefined ? ColorDepth.TRUECOLOR : rawSpec, destinationOptions);
     // [LAW:single-enforcer] This call's overrides are applied here, once, to
     // make the one destination everything below is drawn for. `noColor` is a
     // colour choice, so it overrides the depth and leaves hyperlinks to the
     // destination; an explicit `hyperlinks` overrides what the destination takes.
     const destination = {
+        ...resolved,
         colorSystem: options?.noColor ? null : resolved.colorSystem,
         hyperlinks: options?.hyperlinks ?? resolved.hyperlinks,
     };
@@ -94,6 +112,8 @@ export function renderToString(renderable, options) {
         maxWidth: width,
         isTerminal: false,
         asciiOnly: options?.asciiOnly ?? false,
+        // [LAW:one-source-of-truth] What is drawn and how it is encoded take one preference.
+        reducedMotion: destination.reducedMotion,
         theme: options?.theme,
         onStyleError: options?.onStyleError,
         highlight: options?.highlight,

package/dist/core/segment.d.ts

@@ -23,12 +23,12 @@ export declare enum ControlType {
     ERASE_IN_LINE = "erase_in_line",
     SET_WINDOW_TITLE = "set_window_title"
 }
-export type ControlCode = [ControlType, ...unknown[]];
+export type ControlCode = readonly [ControlType, ...unknown[]];
 export declare class Segment {
     readonly text: string;
     readonly style: Style | undefined;
-    readonly control: ControlCode[] | undefined;
-    constructor(text: string, style?: Style, control?: ControlCode[]);
+    readonly control: readonly ControlCode[] | undefined;
+    constructor(text: string, style?: Style, control?: readonly ControlCode[]);
     get cellLength(): number;
     get hasText(): boolean;
     get isControl(): boolean;
@@ -51,7 +51,7 @@ export declare class Segment {
      * further into whatever drew it, and its anchor says so; see `./anchor.ts`.
      */
     private cutAt;
-    private static _line;
+    private static readonly _line;
     static line(): Segment;
     /**
      * `lines`, as drawn by `owner`: every segment stamped with the row and
@@ -62,7 +62,7 @@ export declare class Segment {
     static anchorLines(lines: Segment[][], owner: object, firstRow?: number): Segment[][];
     /**
      * When what `segments` show next changes, in seconds on the timeline of
-     * whoever drew them: the soonest `Style.nextChange` among them, read off
+     * whoever drew them: the soonest `Style.hold` among them, read off
      * the composed frame the way `anchorAt` reads an owner — `t` itself for a
      * frame something in moves every frame, `Infinity` for one that never
      * changes. What a host that drew the frame at `t` asks before drawing
@@ -70,6 +70,14 @@ export declare class Segment {
      * `t` until it is done, still content never.
      */
     static nextChange(segments: Iterable<Segment>): number;
+    /**
+     * Since when what `segments` show has been what it is, on the same
+     * timeline: the latest `Style.hold` among them, the other end of the
+     * hold `nextChange` reads — `t` for a frame something in moves every
+     * frame, `-Infinity` for one that always was. What a host running its
+     * timeline backwards asks before drawing again.
+     */
+    static lastChange(segments: Iterable<Segment>): number;
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.

package/dist/core/segment.js

@@ -65,9 +65,9 @@ export class Segment {
         return cutCells(this.text, positions).map((text, piece) => new Segment(text, piece === 0 ? this.style : this.style?.shiftedBy(positions[piece - 1])));
     }
     // --- Static factories ---
-    static _line;
+    static _line = new Segment("\n");
     static line() {
-        return (Segment._line ??= new Segment("\n"));
+        return Segment._line;
     }
     // --- Static transformations ---
     /**
@@ -92,7 +92,7 @@ export class Segment {
     }
     /**
      * When what `segments` show next changes, in seconds on the timeline of
-     * whoever drew them: the soonest `Style.nextChange` among them, read off
+     * whoever drew them: the soonest `Style.hold` among them, read off
      * the composed frame the way `anchorAt` reads an owner — `t` itself for a
      * frame something in moves every frame, `Infinity` for one that never
      * changes. What a host that drew the frame at `t` asks before drawing
@@ -102,9 +102,22 @@ export class Segment {
     static nextChange(segments) {
         let soonest = Number.POSITIVE_INFINITY;
         for (const segment of segments)
-            soonest = Math.min(soonest, segment.style?.nextChange ?? Number.POSITIVE_INFINITY);
+            soonest = Math.min(soonest, segment.style?.hold.nextChange ?? Number.POSITIVE_INFINITY);
         return soonest;
     }
+    /**
+     * Since when what `segments` show has been what it is, on the same
+     * timeline: the latest `Style.hold` among them, the other end of the
+     * hold `nextChange` reads — `t` for a frame something in moves every
+     * frame, `-Infinity` for one that always was. What a host running its
+     * timeline backwards asks before drawing again.
+     */
+    static lastChange(segments) {
+        let latest = Number.NEGATIVE_INFINITY;
+        for (const segment of segments)
+            latest = Math.max(latest, segment.style?.hold.lastChange ?? Number.NEGATIVE_INFINITY);
+        return latest;
+    }
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.
@@ -186,9 +199,8 @@ export class Segment {
                 }
             }
         }
-        if (currentLine.length > 0) {
+        if (currentLine.length > 0)
             lines.push(currentLine);
-        }
         return lines;
     }
     /**
@@ -203,7 +215,10 @@ export class Segment {
                 return line;
             return [...line, new Segment(" ".repeat(width - currentWidth), style)];
         }
-        // Crop to width
+        // Crop to width: the cells past it go, and every piece of no cells stays —
+        // a control, or an empty piece of text, writes nothing there, and may be
+        // all that says when its frame changes (`Style.hold`). Not the
+        // reference, which stops at the cut.
         const result = [];
         let remaining = width;
         for (const segment of line) {
@@ -216,11 +231,10 @@ export class Segment {
                 result.push(segment);
                 remaining -= segWidth;
             }
-            else {
+            else if (remaining > 0) {
                 const [left] = segment.splitCells(asCellCol(remaining));
                 result.push(left);
                 remaining = 0;
-                break;
             }
         }
         return result;

package/dist/core/spinnerData.d.ts

@@ -8,5 +8,5 @@ export interface SpinnerData {
 }
 /** The spinner an ASCII-only output draws in place of any other. */
 export declare const LINE_SPINNER: SpinnerData;
-export declare const SPINNERS: Record<string, SpinnerData>;
+export declare const SPINNERS: Readonly<Record<string, SpinnerData>>;
 export declare const DEFAULT_SPINNER = "dots";

package/dist/core/state.d.ts

@@ -0,0 +1,53 @@
+/**
+ * state — `State<T>`, the one place a renderable keeps state that changes after
+ * it is built, and the refusal of a write to it while something is drawn.
+ *
+ * A render changes nothing. React refuses a state update during render because
+ * state changes only through a setter, and the setter knows the render phase;
+ * this is that setter. `set` throws while a render or measure is in progress
+ * (`activePass`, owned by `render` and `measure` in `./protocol.ts`).
+ *
+ * Ownership is React's line too: a state made during a pass belongs to that
+ * pass, and the pass may set it. A render that builds a fresh value and fills
+ * it as it draws — a `Table` it adds rows to — changes nothing anyone held
+ * before it began. Only a state that existed before the pass is refused.
+ *
+ * `ListState` is the same for a list a renderable appends to — a table's rows,
+ * a text's spans — which a `State<readonly T[]>` would copy on every append.
+ *
+ * `refuseRenderWrite` is that refusal, written once: a widget's observables
+ * refuse a write through it too (`src/widgets/observable.ts`).
+ *
+ * `test/seam/render-purity.test.ts` is the static half: nothing else reachable
+ * from a renderable, or from module scope, may be writable.
+ */
+import { type Pass } from "./protocol.js";
+/** State was written during a render or measure that did not make it. */
+export declare class RenderWriteError extends Error {
+    constructor();
+}
+export declare class State<T> {
+    #private;
+    constructor(value: T);
+    get(): T;
+    set(value: T): void;
+}
+/**
+ * A list kept as `State` keeps a value, appended to in place: a `State` of a
+ * readonly array copies it on every append, which makes filling a 10,000-row
+ * table quadratic. `get` hands out the list itself, typed readonly, so a
+ * reader that keeps it sees later appends; `set` replaces it, leaving a kept
+ * one as it was.
+ */
+export declare class ListState<T> {
+    #private;
+    constructor(items?: Iterable<T>);
+    get(): readonly T[];
+    push(item: T): void;
+    set(items: Iterable<T>): void;
+}
+/**
+ * Throws unless state made in `owner` — the pass in progress when it was made,
+ * if any — may be written now: between passes, or in the pass that made it.
+ */
+export declare function refuseRenderWrite(owner: Pass | undefined): void;

package/dist/core/state.js

@@ -0,0 +1,82 @@
+/**
+ * state — `State<T>`, the one place a renderable keeps state that changes after
+ * it is built, and the refusal of a write to it while something is drawn.
+ *
+ * A render changes nothing. React refuses a state update during render because
+ * state changes only through a setter, and the setter knows the render phase;
+ * this is that setter. `set` throws while a render or measure is in progress
+ * (`activePass`, owned by `render` and `measure` in `./protocol.ts`).
+ *
+ * Ownership is React's line too: a state made during a pass belongs to that
+ * pass, and the pass may set it. A render that builds a fresh value and fills
+ * it as it draws — a `Table` it adds rows to — changes nothing anyone held
+ * before it began. Only a state that existed before the pass is refused.
+ *
+ * `ListState` is the same for a list a renderable appends to — a table's rows,
+ * a text's spans — which a `State<readonly T[]>` would copy on every append.
+ *
+ * `refuseRenderWrite` is that refusal, written once: a widget's observables
+ * refuse a write through it too (`src/widgets/observable.ts`).
+ *
+ * `test/seam/render-purity.test.ts` is the static half: nothing else reachable
+ * from a renderable, or from module scope, may be writable.
+ */
+import { activePass } from "./protocol.js";
+/** State was written during a render or measure that did not make it. */
+export class RenderWriteError extends Error {
+    constructor() {
+        super("State was written during a render or measure. A render changes nothing: " +
+            "change state in an event handler, an update, or between frames.");
+        this.name = "RenderWriteError";
+    }
+}
+export class State {
+    #value;
+    #owner = activePass();
+    constructor(value) {
+        this.#value = value;
+    }
+    get() {
+        return this.#value;
+    }
+    set(value) {
+        refuseRenderWrite(this.#owner);
+        this.#value = value;
+    }
+}
+/**
+ * A list kept as `State` keeps a value, appended to in place: a `State` of a
+ * readonly array copies it on every append, which makes filling a 10,000-row
+ * table quadratic. `get` hands out the list itself, typed readonly, so a
+ * reader that keeps it sees later appends; `set` replaces it, leaving a kept
+ * one as it was.
+ */
+export class ListState {
+    #items;
+    #owner = activePass();
+    constructor(items = []) {
+        this.#items = [...items];
+    }
+    get() {
+        return this.#items;
+    }
+    // One item, not a rest parameter: a caller spreading a long list into one overflows the call stack.
+    push(item) {
+        refuseRenderWrite(this.#owner);
+        this.#items.push(item);
+    }
+    set(items) {
+        refuseRenderWrite(this.#owner);
+        this.#items = [...items];
+    }
+}
+/**
+ * Throws unless state made in `owner` — the pass in progress when it was made,
+ * if any — may be written now: between passes, or in the pass that made it.
+ */
+export function refuseRenderWrite(owner) {
+    const pass = activePass();
+    // [LAW:no-silent-failure] Refused loudly, as React refuses a setState in render.
+    if (pass !== undefined && pass !== owner)
+        throw new RenderWriteError();
+}