@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/core/text.js

@@ -6,17 +6,28 @@ import { divideLine, wordWidths } from "./wrap.js";
 import { Segment } from "./segment.js";
 import { Style, NULL_STYLE, StyleSyntaxError } from "./style.js";
 import { stripOscTerminators } from "./osc8.js";
-import { drawable, getStyle, withBoundedWidth } from "./protocol.js";
+import { betweenPasses, drawable, getStyle, withBoundedWidth } from "./protocol.js";
+import { pattern } from "./pattern.js";
+import { ListState, State } from "./state.js";
 // Every C0 control and DEL except \t and \n. Rich's `Text` strips only
 // `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR); the rest of the set is the
-// port's extension, so no C0 byte of content can start an escape sequence or
-// move the cursor on the wire. C1 controls (U+0080–U+009F) pass, as in Rich.
-// [LAW:single-enforcer] Single place where control chars are sanitized
-const CONTROL_CHARS_RE = /[\x00-\x08\x0B-\x1F\x7F]/g;
+// port's extension, so no byte of content can start an escape sequence or move
+// the cursor on the wire: the C1 controls (U+0080–U+009F) go as well, since a
+// terminal reads U+009B as CSI and U+009D as OSC (TextInput refuses them for
+// the same reason). So do the format controls that hold state past the text,
+// also the port's extension: the bidi embeddings and overrides with their
+// closer PDF (U+202A–U+202E), the isolates with their closer PDI
+// (U+2066–U+2069), and the deprecated shaping and swapping switches
+// (U+206A–U+206F). An opener left unclosed in content reverses whatever is
+// drawn after it on the line, and a closer whose opener is gone closes
+// nothing of the text's own. The bidi marks (LRM, RLM, ALM) hold no state and
+// pass, since right-to-left text needs them.
+// [LAW:single-enforcer] Single place where control chars are sanitized: every
+// string that becomes part of a Text's characters passes here.
 export function stripControlChars(text) {
-    return text.replace(CONTROL_CHARS_RE, "");
+    return text.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F\u202A-\u202E\u2066-\u206F]/g, "");
 }
-const TRAILING_WHITESPACE_RE = /\s+$/;
+const TRAILING_WHITESPACE_RE = pattern(/\s+$/);
 /**
  * The plain text of one line of segments, in the coordinate system
  * `divideLine` and `Segment.divide` share: cell offsets into the styled line
@@ -74,9 +85,9 @@ function sanitizeStyleLink(style) {
  * lays its text out anew, so a stamp naming where a cell sat in the output it
  * came from would name the wrong cell once it wraps, slices or overlaps; the
  * owner that renders the RichText is the one that stamps its cells. A
- * `nextChange` stays: when a span's cells next change is true of them
- * wherever the text lays them, so a frame appended into a line still says
- * when it turns.
+ * hold stays — `lastChange` and `nextChange`: when a span's cells began and
+ * next change is true of them wherever the text lays them, so a frame
+ * appended into a line still says when it turns.
  */
 function admitStyle(style) {
     if (typeof style === "string")
@@ -119,7 +130,7 @@ function resolveDefinition(options, style) {
     catch (err) {
         if (!(err instanceof StyleSyntaxError))
             throw err;
-        options.onStyleError?.(err, style);
+        betweenPasses(() => options.onStyleError?.(err, style));
         return NULL_STYLE;
     }
 }
@@ -160,41 +171,45 @@ export class Span {
     }
 }
 export class RichText {
+    // Rich's `Text` is changed in place — appended to, stylized, padded — so its
+    // characters, spans and format are state, and a write to one while
+    // something is drawn throws. Three holders rather than one per field: a
+    // `RichText` is the most-made object in the library.
     _text;
-    _spans;
-    _style;
-    _justify;
-    _overflow;
-    _end;
+    _spans = new ListState();
+    _format;
     _tabSize;
-    _noWrap;
     constructor(text, options) {
-        this._text = text ? stripControlChars(text) : "";
-        this._spans = [];
-        // [LAW:single-enforcer] `admitStyle` is the boundary that sanitizes
-        // any link URL crossing into a RichText; downstream trusts the invariant.
-        this._style = admitStyle(options?.style ?? NULL_STYLE);
-        this._justify = options?.justify;
-        this._overflow = options?.overflow;
-        this._end = options?.end ?? "\n";
+        this._text = new State(text ? stripControlChars(text) : "");
+        this._format = new State({
+            // [LAW:single-enforcer] `admitStyle` is the boundary that sanitizes
+            // any link URL crossing into a RichText; downstream trusts the invariant.
+            style: admitStyle(options?.style ?? NULL_STYLE),
+            justify: options?.justify,
+            overflow: options?.overflow,
+            end: options?.end ?? "\n",
+            noWrap: options?.noWrap ?? false,
+        });
         this._tabSize = parseTabSize(options?.tabSize ?? 8);
-        this._noWrap = options?.noWrap ?? false;
+    }
+    _reformat(change) {
+        this._format.set({ ...this._format.get(), ...change });
     }
     // --- Properties ---
     get plain() {
-        return this._text;
+        return this._text.get();
     }
     set plain(value) {
         const sanitized = stripControlChars(value);
-        this._text = sanitized;
+        this._text.set(sanitized);
         // Trim spans that extend beyond new length
         const len = sanitized.length;
-        this._spans = this._spans
+        this._spans.set(this._spans.get()
             .map((s) => (s.end > len ? new Span(s.start, Math.min(s.end, len), s.style) : s))
-            .filter((s) => s.start < len);
+            .filter((s) => s.start < len));
     }
     get length() {
-        return this._text.length;
+        return this._text.get().length;
     }
     /**
      * The cells of the plain text with each tab widened to its stop counted from
@@ -205,44 +220,44 @@ export class RichText {
      * no render draws.
      */
     get cellLength() {
-        return cellLen(expandTabs(this._text, this._tabSize).text);
+        return cellLen(expandTabs(this._text.get(), this._tabSize).text);
     }
     get hasContent() {
-        return this._text.length > 0;
+        return this._text.get().length > 0;
     }
     /** The base style every span layers over, resolved at render unless it is a `Style`. */
     get style() {
-        return this._style;
+        return this._format.get().style;
     }
     set style(value) {
-        this._style = admitStyle(value);
+        this._reformat({ style: admitStyle(value) });
     }
     get justify() {
-        return this._justify;
+        return this._format.get().justify;
     }
     set justify(value) {
-        this._justify = value;
+        this._reformat({ justify: value });
     }
     get overflow() {
-        return this._overflow;
+        return this._format.get().overflow;
     }
     set overflow(value) {
-        this._overflow = value;
+        this._reformat({ overflow: value });
     }
     get end() {
-        return this._end;
+        return this._format.get().end;
     }
     set end(value) {
-        this._end = value;
+        this._reformat({ end: value });
     }
     get noWrap() {
-        return this._noWrap;
+        return this._format.get().noWrap;
     }
     set noWrap(value) {
-        this._noWrap = value;
+        this._reformat({ noWrap: value });
     }
     get spans() {
-        return this._spans;
+        return this._spans.get();
     }
     /**
      * This text's own style, spans aside, as the render drawing it resolves it.
@@ -250,7 +265,7 @@ export class RichText {
      * text forgives a missing name.
      */
     resolvedStyle(options) {
-        return resolveStyle(options, this._style);
+        return resolveStyle(options, this._format.get().style);
     }
     /**
      * The style of the cell-column at the named edge — base style merged with
@@ -274,11 +289,11 @@ export class RichText {
      */
     edgeStyle(side, options) {
         const base = this.resolvedStyle(options);
-        if (this._text.length === 0)
+        if (this._text.get().length === 0)
             return base;
-        const pos = side === "left" ? 0 : this._text.length - 1;
+        const pos = side === "left" ? 0 : this._text.get().length - 1;
         let result = base;
-        for (const span of this._spans) {
+        for (const span of this._spans.get()) {
             if (span.start <= pos && pos < span.end) {
                 result = result.add(resolveStyle(options, span.style));
             }
@@ -291,35 +306,36 @@ export class RichText {
             if (style !== undefined) {
                 throw new Error("Style argument must not be provided when appending RichText");
             }
-            const offset = this._text.length;
-            this._text += content._text;
+            const offset = this._text.get().length;
+            // Read before anything is appended, so a text appended to itself takes its spans as they were.
+            const moved = content._spans.get().map((span) => span.move(offset));
+            this._text.set(this._text.get() + content._text.get());
             // Its base style becomes a span under its own spans, as the reference's
             // `append` does, so appended text looks as it did alone.
-            this._addSpan(offset, this._text.length, content._style);
-            for (const span of content._spans) {
-                this._spans.push(span.move(offset));
-            }
+            this._addSpan(offset, this._text.get().length, content._format.get().style);
+            for (const span of moved)
+                this._spans.push(span);
             return this;
         }
         const sanitized = stripControlChars(content);
-        const start = this._text.length;
-        this._text += sanitized;
-        this._addSpan(start, this._text.length, style ?? "");
+        const start = this._text.get().length;
+        this._text.set(this._text.get() + sanitized);
+        this._addSpan(start, this._text.get().length, style ?? "");
         return this;
     }
     contains(needle) {
-        const searchText = needle instanceof RichText ? needle._text : needle;
-        return this._text.includes(searchText);
+        const searchText = needle instanceof RichText ? needle._text.get() : needle;
+        return this._text.get().includes(searchText);
     }
     at(index) {
-        const resolved = index < 0 ? this._text.length + index : index;
-        const char = this._text[resolved];
+        const resolved = index < 0 ? this._text.get().length + index : index;
+        const char = this._text.get()[resolved];
         if (char === undefined)
             return new RichText("");
         return this.slice(resolved, resolved + 1);
     }
     slice(start, end) {
-        const text = this._text;
+        const text = this._text.get();
         const len = text.length;
         const s = start ?? 0;
         const e = end ?? len;
@@ -330,7 +346,7 @@ export class RichText {
         }
         const slicedText = text.slice(resolvedStart, resolvedEnd);
         const result = this.blankCopy(slicedText);
-        for (const span of this._spans) {
+        for (const span of this._spans.get()) {
             const spanStart = Math.max(span.start, resolvedStart) - resolvedStart;
             const spanEnd = Math.min(span.end, resolvedEnd) - resolvedStart;
             if (spanStart < spanEnd) {
@@ -352,7 +368,7 @@ export class RichText {
         this._spans.push(new Span(start, end, admitted));
     }
     stylize(style, start, end) {
-        const len = this._text.length;
+        const len = this._text.get().length;
         const s = start !== undefined ? (start < 0 ? len + start : start) : 0;
         const e = end !== undefined ? (end < 0 ? len + end : end) : len;
         if (s >= e || s >= len || e <= 0)
@@ -363,7 +379,7 @@ export class RichText {
         return this;
     }
     highlightRegex(pattern, style) {
-        const text = this._text;
+        const text = this._text.get();
         let count = 0;
         // Ensure global flag
         const flags = pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g";
@@ -405,7 +421,7 @@ export class RichText {
             const flags = caseSensitive ? "g" : "gi";
             const re = new RegExp(`\\b${escaped}\\b`, flags);
             let match;
-            while ((match = re.exec(this._text)) !== null) {
+            while ((match = re.exec(this._text.get())) !== null) {
                 this._addSpan(match.index, match.index + match[0].length, style);
                 count++;
             }
@@ -414,31 +430,17 @@ export class RichText {
     }
     // --- Copy Operations ---
     copy() {
-        const result = new RichText(this._text, {
-            style: this._style,
-            justify: this._justify,
-            overflow: this._overflow,
-            end: this._end,
-            tabSize: this._tabSize,
-            noWrap: this._noWrap,
-        });
-        result._spans = this._spans.slice();
+        const result = this.blankCopy(this._text.get());
+        result._spans.set(this._spans.get());
         return result;
     }
     blankCopy(text) {
-        return new RichText(text ?? "", {
-            style: this._style,
-            justify: this._justify,
-            overflow: this._overflow,
-            end: this._end,
-            tabSize: this._tabSize,
-            noWrap: this._noWrap,
-        });
+        return new RichText(text ?? "", { ...this._format.get(), tabSize: this._tabSize });
     }
     // --- Splitting ---
     split(separator) {
         const sep = separator ?? "\n";
-        const text = this._text;
+        const text = this._text.get();
         const parts = [];
         let start = 0;
         while (true) {
@@ -466,18 +468,17 @@ export class RichText {
     }
     // --- Whitespace Operations ---
     rstrip() {
-        const trimmed = this._text.replace(/\s+$/, "");
-        if (trimmed.length < this._text.length) {
+        const trimmed = this._text.get().replace(/\s+$/, "");
+        if (trimmed.length < this._text.get().length) {
             this.plain = trimmed;
         }
         return this;
     }
     pad(count, char) {
-        const c = char ?? " ";
-        const padding = c.repeat(count);
-        // Shift all spans to the right
-        this._spans = this._spans.map((s) => s.move(count));
-        this._text = padding + this._text + padding;
+        const padding = stripControlChars(char ?? " ").repeat(count);
+        // Shift all spans right by what the left side gained.
+        this._spans.set(this._spans.get().map((s) => s.move(padding.length)));
+        this._text.set(padding + this._text.get() + padding);
         return this;
     }
     /**
@@ -486,36 +487,35 @@ export class RichText {
      * the text measures what it will draw.
      */
     expandTabs() {
-        const expanded = expandTabs(this._text, this._tabSize);
-        this._spans = this._spans.map((s) => new Span(expanded.offsetOf(s.start), expanded.offsetOf(s.end), s.style));
-        this._text = expanded.text;
+        const expanded = expandTabs(this._text.get(), this._tabSize);
+        this._spans.set(this._spans.get().map((s) => new Span(expanded.offsetOf(s.start), expanded.offsetOf(s.end), s.style)));
+        this._text.set(expanded.text);
         return this;
     }
     padLeft(count, char) {
-        const c = char ?? " ";
-        this._spans = this._spans.map((s) => s.move(count));
-        this._text = c.repeat(count) + this._text;
+        const padding = stripControlChars(char ?? " ").repeat(count);
+        this._spans.set(this._spans.get().map((s) => s.move(padding.length)));
+        this._text.set(padding + this._text.get());
         return this;
     }
     padRight(count, char) {
-        const c = char ?? " ";
-        this._text += c.repeat(count);
+        this._text.set(this._text.get() + stripControlChars(char ?? " ").repeat(count));
         return this;
     }
     setLength(length) {
-        if (this._text.length < length) {
-            this._text += " ".repeat(length - this._text.length);
+        if (this._text.get().length < length) {
+            this._text.set(this._text.get() + " ".repeat(length - this._text.get().length));
         }
-        else if (this._text.length > length) {
-            this.plain = this._text.slice(0, length);
+        else if (this._text.get().length > length) {
+            this.plain = this._text.get().slice(0, length);
         }
         return this;
     }
     extendStyle(count) {
-        const oldLen = this._text.length;
-        this._text += " ".repeat(count);
+        const oldLen = this._text.get().length;
+        this._text.set(this._text.get() + " ".repeat(count));
         // Extend existing spans to cover new spaces
-        this._spans = this._spans.map((s) => s.end === oldLen ? s.extend(count) : s);
+        this._spans.set(this._spans.get().map((s) => s.end === oldLen ? s.extend(count) : s));
         return this;
     }
     // --- Truncation ---
@@ -558,19 +558,19 @@ export class RichText {
         // value, so width 0 and a marker wider than the width run the same walk
         // as every other call: what is drawn plus what is kept is `cells` wide.
         const cells = cellCount(width);
-        const marker = cellFit(options?.marker ?? "\u2026", cells);
+        const marker = cellFit(stripControlChars(options?.marker ?? "\u2026"), cells);
         const budget = asCellCol(cells - cellLen(marker));
         if (mode === "right") {
             this._cropRightTo(budget);
             if (marker)
-                this._text += marker;
+                this._text.set(this._text.get() + marker);
             return this;
         }
         if (mode === "left") {
             this._cropLeftTo(budget);
             if (marker) {
-                this._spans = this._spans.map((s) => s.move(marker.length));
-                this._text = marker + this._text;
+                this._spans.set(this._spans.get().map((s) => s.move(marker.length)));
+                this._text.set(marker + this._text.get());
             }
             return this;
         }
@@ -578,17 +578,17 @@ export class RichText {
         const leftBudget = asCellCol(Math.floor(budget / 2));
         const rightBudget = asCellCol(budget - leftBudget);
         // Find the char-index ranges to keep from each side.
-        const leftEndCharIdx = cellFit(this._text, leftBudget).length;
-        const rightStartCharIdx = this._text.length - cellFitEnd(this._text, rightBudget).length;
-        const leftText = this._text.slice(0, leftEndCharIdx);
-        const rightText = this._text.slice(rightStartCharIdx);
+        const leftEndCharIdx = cellFit(this._text.get(), leftBudget).length;
+        const rightStartCharIdx = this._text.get().length - cellFitEnd(this._text.get(), rightBudget).length;
+        const leftText = this._text.get().slice(0, leftEndCharIdx);
+        const rightText = this._text.get().slice(rightStartCharIdx);
         const droppedStart = leftEndCharIdx;
         const droppedEnd = rightStartCharIdx;
         const shift = marker.length - (droppedEnd - droppedStart);
         // Spans falling entirely before the drop stay; entirely after shift by
         // (marker.length - dropped chars); spans crossing the drop are clipped.
         const newSpans = [];
-        for (const s of this._spans) {
+        for (const s of this._spans.get()) {
             if (s.end <= droppedStart) {
                 newSpans.push(s);
             }
@@ -605,18 +605,18 @@ export class RichText {
                 }
             }
         }
-        this._text = leftText + marker + rightText;
-        this._spans = newSpans;
+        this._text.set(leftText + marker + rightText);
+        this._spans.set(newSpans);
         return this;
     }
     _cropRightTo(targetWidth) {
-        this.plain = cellFit(this._text, targetWidth);
+        this.plain = cellFit(this._text.get(), targetWidth);
     }
     _cropLeftTo(targetWidth) {
-        const charIdx = this._text.length - cellFitEnd(this._text, targetWidth).length;
+        const charIdx = this._text.get().length - cellFitEnd(this._text.get(), targetWidth).length;
         // Shift spans left by charIdx; clip spans that started before.
         const shift = -charIdx;
-        this._spans = this._spans
+        this._spans.set(this._spans.get()
             .map((s) => {
             if (s.end <= charIdx)
                 return undefined;
@@ -624,8 +624,8 @@ export class RichText {
             const newEnd = s.end + shift;
             return new Span(newStart, newEnd, s.style);
         })
-            .filter((s) => s !== undefined);
-        this._text = this._text.slice(charIdx);
+            .filter((s) => s !== undefined));
+        this._text.set(this._text.get().slice(charIdx));
     }
     // --- Alignment ---
     align(justify, width) {
@@ -655,8 +655,8 @@ export class RichText {
     }
     // --- Suffix Removal ---
     removeSuffix(suffix) {
-        if (this._text.endsWith(suffix)) {
-            this.plain = this._text.slice(0, -suffix.length);
+        if (this._text.get().endsWith(suffix)) {
+            this.plain = this._text.get().slice(0, -suffix.length);
         }
         return this;
     }
@@ -713,7 +713,7 @@ export class RichText {
     }
     // --- Renderable ---
     *render(options) {
-        const expanded = expandTabs(this._text, this._tabSize);
+        const expanded = expandTabs(this._text.get(), this._tabSize);
         const base = this.resolvedStyle(options);
         const { segments: allSegments, covered } = this._buildSegments(expanded, base, options);
         const spanFree = spanFreeLines(allSegments, covered);
@@ -731,8 +731,8 @@ export class RichText {
         // overflow arm a no-op, but passed an unbounded one through to `justify`,
         // which pads — and `" ".repeat(Infinity)` throws.
         const maxWidth = cellCount(withBoundedWidth(options, this).maxWidth);
-        const overflow = this._overflow ?? options.overflow ?? "fold";
-        const noWrap = this._noWrap || (options.noWrap ?? false);
+        const overflow = this._format.get().overflow ?? options.overflow ?? "fold";
+        const noWrap = this._format.get().noWrap || (options.noWrap ?? false);
         // Two widths, and they are the reference's `no_wrap` and `"ignore"` told
         // apart. `edge` is where a line is cut: gone under `"ignore"`, so the line
         // leaves at its natural width and whatever drew it decides about the
@@ -751,7 +751,7 @@ export class RichText {
         // A line with no edge has no width to be justified in, so under `"ignore"`
         // it is not justified — the reference's `Text.wrap` returns that arm before
         // `justify`. `undefined` is the placement that leaves a line as it is.
-        const justify = overflow === "ignore" ? undefined : this._justify ?? options.justify;
+        const justify = overflow === "ignore" ? undefined : this._format.get().justify ?? options.justify;
         // One cell either way, so the marker's stand-in leaves the cut where it was.
         const ellipsis = drawable(options, "\u2026", ".");
         for (let index = 0; index < logicalLines.length; index += 1) {
@@ -779,13 +779,13 @@ export class RichText {
         // (truthy) and again for non-empty text (truthy and not the default
         // "\n"), which gave `end` two meanings depending on whether the text was
         // empty (rich-text-5ai).
-        if (this._end) {
-            yield new Segment(this._end);
+        if (this._format.get().end) {
+            yield new Segment(this._format.get().end);
         }
     }
     // --- Measurable ---
     measure(options) {
-        const lines = expandTabs(this._text, this._tabSize).text.split("\n");
+        const lines = expandTabs(this._text.get(), this._tabSize).text.split("\n");
         const maxLineWidth = lines.reduce((widest, line) => Math.max(widest, cellLen(line)), 0);
         // [LAW:one-source-of-truth] The minimum is the widest piece the wrapper
         // never breaks, asked of the wrapper — so a line's indent, which wraps
@@ -840,7 +840,7 @@ export class RichText {
         // and it is what makes empty text one line to everything that splits a
         // render into lines — a panel's body, a table cell — where Rich draws one.
         const inner = new Set();
-        for (const span of this._spans) {
+        for (const span of this._spans.get()) {
             inner.add(clamp(span.start));
             inner.add(clamp(span.end));
         }
@@ -854,7 +854,7 @@ export class RichText {
         const pieceAt = new Map(boundaries.map((position, piece) => [position, piece]).reverse());
         const styles = boundaries.slice(0, -1).map(() => base);
         const covered = styles.map(() => false);
-        for (const span of this._spans) {
+        for (const span of this._spans.get()) {
             const end = clamp(span.end);
             const style = resolveStyle(options, span.style);
             const opensAt = pieceAt.get(clamp(span.start));

package/dist/core/timeline.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Timeline — the map from the host's clock to the time an animation is
+ * asked for: playback control, and nothing else.
+ *
+ * Every animation is a pure function of its time (`./animation.ts`), so
+ * pausing, reversing, scrubbing and speeding one up are not things done to
+ * it but a change in which time it is asked for. A timeline is that map, as
+ * a value: an animation time at a host time, a rate — animation seconds per
+ * host second, negative running it backwards — and whether it is held. Each
+ * operation is a value in and a value out, so a paused timeline resumed at a
+ * new host time is one that maps that host time to the time it froze at, and
+ * two hosts holding equal timelines ask every animation for the same time.
+ *
+ * A paused timeline carries no host anchor: it maps every host time to the
+ * one time it holds, so there is no origin for it to be wrong about.
+ * [LAW:types-are-the-program]
+ *
+ * `run` is an animation on host time. Its `nextChange` is the host moment
+ * the mapped time reaches the animation's own answer, which is what
+ * `Spinner`'s speed scaled its holds for before this existed: an answer a
+ * host reads is on the host's timeline, and a beat over scaled time answers
+ * on the scaled one. Run backwards, the host next sees a change when the
+ * mapped time drops under where the value began — the animation's
+ * `lastChange` — so a reversed loop turns exactly at its hold boundaries,
+ * and a reversed one-shot changes at its switch and never before its start.
+ * Paused, nothing changes: never, and never did. The host moment is the
+ * first host float the map carries past the edge, searched out from the sum
+ * `origin + (edge - time) / rate` (`firstReaching`): a host float is a step
+ * of `rate` on the animation's clock, so the floats between that sum and
+ * the first one past the edge are as many as the two clocks' resolutions
+ * are apart — unbounded, far from the origin or at a slow rate — which is
+ * why it is a search and not the ulp walk a sum on one clock takes. A value
+ * moving at the mapped time changes at the host time itself.
+ *
+ * A stagger — a Group's children pulsing in sequence, a light walking down
+ * a Table's rows — is the same map once per child: `stagger` runs each
+ * child's animation on a timeline playing from its index times the delay,
+ * and the group changes when the soonest child does, each child's answer
+ * carried onto the group's clock by `run`. Before its turn a child is asked
+ * for a time before 0, which is its own business: a loop is shifted in
+ * phase. Tree, Table, Group and Layout take the children's frames as they
+ * take any renderables, through `Animation.map`, so none of them knows a
+ * stagger exists. [LAW:composability] A lifecycle is not staggered here: it
+ * carries its turn as `entered`, on the host's clock its `leave` and `gone`
+ * take, so moving it onto a shifted clock would lose them
+ * ([LAW:one-source-of-truth] for when it arrives).
+ *
+ * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. The host
+ * time is an argument everywhere, and a timeline is built from one the host
+ * hands in, so the same host time maps to the same animation time at one
+ * sample a second or sixty.
+ */
+import { Animation, type Timed } from "./animation.js";
+/**
+ * A map from host time to animation time. Playing, it is `time` at `origin`
+ * moving `rate` animation seconds a host second; paused, it is `time` at
+ * every host time, with the rate it resumes at.
+ */
+export type Timeline = {
+    readonly playing: true;
+    /** The host time, in seconds, at which the animation time is `time`. */
+    readonly origin: number;
+    /** The animation time, in seconds, at `origin`. */
+    readonly time: number;
+    /** Animation seconds per host second; negative runs the animation backwards. Never zero: a held timeline is paused. */
+    readonly rate: number;
+} | {
+    readonly playing: false;
+    /** The animation time, in seconds, held at every host time. */
+    readonly time: number;
+    /** The rate the timeline resumes at. */
+    readonly rate: number;
+};
+export declare const Timeline: {
+    /** Playing from host time `origin`, at which the animation time is 0, at `rate` animation seconds a host second. */
+    play(origin: number, rate?: number): Timeline;
+    /** The animation time at host time `host`. */
+    at(timeline: Timeline, host: number): number;
+    /** `timeline` held at the animation time it maps `host` to. Pausing a paused timeline holds the same time. */
+    pause(timeline: Timeline, host: number): Timeline;
+    /** `timeline` playing from `host` at the animation time it maps `host` to, at its rate. Resuming a playing timeline is the same map. */
+    resume(timeline: Timeline, host: number): Timeline;
+    /** `timeline` with the animation at `time` at host time `host`, playing or held as it was. */
+    seek(timeline: Timeline, host: number, time: number): Timeline;
+    /** `timeline` at `rate` from host time `host` on, with no jump: the animation time at `host` is what it was. */
+    withRate(timeline: Timeline, host: number, rate: number): Timeline;
+    /**
+     * `animation` on host time: its value at the time `timeline` maps each
+     * host time to, changing at the host moment the mapped time reaches the
+     * animation's own answer — backwards, when it drops under where the value
+     * began. Paused, the value never changes and never did. The value is the
+     * animation's own, on no clock: placed, it is stamped at the frame's time
+     * (`placedRender`, `./animation.ts`) with this animation's answers, so a
+     * value's contents follow the frame's clock and not this map.
+     * Reduced, it is the animation reduced on the same timeline: what shows
+     * still follows the timeline, and only the motion is gone.
+     */
+    run<T>(timeline: Timeline, animation: Timed<T>): Animation<T>;
+    /**
+     * Every one of `animations` at once, each on a timeline playing from its
+     * index times `delay` seconds after the earliest, their values in order, on
+     * a clock of the stagger's own from 0. It changes when the soonest of them
+     * does, on that clock (`Animation.all` of `run`s). A delay of 0 starts them
+     * together and a negative one starts the last at 0 and the first last.
+     * Reduced, the offsets are the cascade's choreography, which is motion: every
+     * child reduced at once, so from 0 everyone has arrived.
+     */
+    stagger<T>(animations: readonly Timed<T>[], delay: number): Animation<readonly T[]>;
+};