@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/text.js

@@ -2,74 +2,56 @@
  * RichText — styled text with spans. The primary text type for the library.
  */
 import { cellLen, cellCount, cellFit, cellFitEnd, asCellCol, expandTabs, parseTabSize } from "./cells.js";
+import { closed, closing } from "./bidi.js";
+import { controlClass, dispositionOf, pictureOf } from "./control-codes.js";
+import { reorder, drawnTail, edges, hangingWhitespace, measured } from "./orient.js";
 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 { stripUrlControls } from "./osc8.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 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.
+const STRIPPED = pattern(new RegExp(controlClass((disposition) => disposition === "strip"), "u"));
+const STOOD_IN_FOR = pattern(new RegExp(controlClass((disposition) => disposition === "line-break" || disposition === "pictured"), "u"));
+/** What content holds in place of a `line-break` or `pictured` code point. */
+function standIn(character) {
+    const codePoint = character.codePointAt(0);
+    return dispositionOf(codePoint) === "pictured" ? pictureOf(codePoint) : "\n";
+}
+// `text` without its `strip` code points, all that `sanitized` deletes.
 // [LAW:single-enforcer] Single place where control chars are sanitized: every
-// string that becomes part of a Text's characters passes here.
+// string that becomes part of a Text's characters passes through `sanitized`.
+// Which ones, and why, is `CONTROL_CODES`. A code point at a time and never by its
+// neighbours, because it runs again on every slice and fragment: what depends on
+// context is `wireText`'s. `match` and `split` need no cursor, so `STRIPPED` can
+// be held. `match` first because nearly every string is clean, and not `test`,
+// which coerces: a template's unlifted scope value reaches here typed as a
+// string, and has to throw rather than read as `[object Object]`.
 export function stripControlChars(text) {
-    return text.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F\u202A-\u202E\u2066-\u206F]/g, "");
-}
-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
- * are cell offsets into this string. [LAW:one-source-of-truth] for that
- * correspondence — the offsets are found in this text and applied to the
- * segments it came from.
- */
-function plainOf(line) {
-    return line.map((segment) => segment.text).join("");
+    return text.match(STRIPPED) === null ? text : text.split(STRIPPED).join("");
 }
 /**
- * The cells of trailing whitespace on a wrapped line.
- *
- * A wrap cuts before a word, so the line it closes ends with the whitespace
- * that followed *its* last word — padding the break created, not content the
- * author wrote. Measuring it is what lets the overflow method tell "this line
- * was cut" from "this line ends in spaces" and stamp an ellipsis only on the
- * first, and what keeps a centred line from drifting half a space off true.
- *
- * Asked of the line's text rather than walked back through its segments,
- * because where a line ends is a fact about the characters and not about how
- * they were split. Walking the segments made it a fact about both: it read a
- * segment with no trailing whitespace as content and stopped there, which an
- * empty segment also looks like — and a crop leaves one behind. A styled line
- * whose last cells were cropped therefore reported no hanging whitespace at
- * all and was centred as though it were content to the edge, so a span landing
- * anywhere in a wrap's whitespace un-centred the line it closed.
+ * `text` as a Text's characters hold it: stripped, every line ending an LF, and
+ * every control its picture. One code unit for one, so an offset into stripped
+ * text holds, and every reader of a Text finds one line break without having to
+ * know the others.
  */
-function hangingWhitespace(line) {
-    return cellLen(TRAILING_WHITESPACE_RE.exec(plainOf(line))?.[0] ?? "");
+export function sanitized(text) {
+    const stripped = stripControlChars(text);
+    return stripped.match(STOOD_IN_FOR) === null ? stripped : stripped.replace(new RegExp(STOOD_IN_FOR.source, "gu"), standIn);
 }
 // [LAW:single-enforcer] RichText is the data-model trust boundary for link
 // URLs: a `Style` is sanitized as it enters (`admitStyle`), and the `Style` a
 // stored string resolves to is sanitized as it leaves for a render
 // (`resolveStyle`). Wire-byte safety is enforced separately by `osc8Open`
 // (core/osc8.ts), which every link producer calls and which applies the same
-// `stripOscTerminators`.
+// `stripUrlControls`.
 function sanitizeStyleLink(style) {
     const link = style.link;
     if (!link)
         return style;
-    const cleaned = stripOscTerminators(link);
+    const cleaned = stripUrlControls(link);
     if (cleaned === link)
         return style;
     return style.withLink(cleaned);
@@ -85,7 +67,7 @@ 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
- * hold stays — `lastChange` and `nextChange`: when a span's cells began and
+ * hold stays — `validFrom` and `validUntil`: 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.
  */
@@ -173,14 +155,18 @@ 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
+    // something is drawn throws. Four holders rather than one per field: a
     // `RichText` is the most-made object in the library.
     _text;
     _spans = new ListState();
+    // What `append` has added to `text` since it last closed it, so closing reads
+    // no more than that. Any other write leaves `text` naming an older string, and
+    // the whole is read instead.
+    _closure = new State({ text: "", tail: "" });
     _format;
     _tabSize;
     constructor(text, options) {
-        this._text = new State(text ? stripControlChars(text) : "");
+        this._text = new State(text ? sanitized(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.
@@ -192,6 +178,12 @@ export class RichText {
         });
         this._tabSize = parseTabSize(options?.tabSize ?? 8);
     }
+    /** The part of the text whose direction state nothing has closed. */
+    _unclosed() {
+        const text = this._text.get();
+        const closure = this._closure.get();
+        return closure.text === text ? closure.tail : text;
+    }
     _reformat(change) {
         this._format.set({ ...this._format.get(), ...change });
     }
@@ -200,10 +192,10 @@ export class RichText {
         return this._text.get();
     }
     set plain(value) {
-        const sanitized = stripControlChars(value);
-        this._text.set(sanitized);
+        const clean = sanitized(value);
+        this._text.set(clean);
         // Trim spans that extend beyond new length
-        const len = sanitized.length;
+        const len = clean.length;
         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));
@@ -272,8 +264,8 @@ export class RichText {
      * any spans covering the leftmost (side="left") or rightmost (side="right")
      * character.
      *
-     * [LAW:locality-or-seam] Used by `Joiner`s to paint the transition between
-     * adjacent `Strip` items. Joiners only ever need the column adjacent to
+     * [LAW:locality-or-seam] Used by `Separator`s to paint the transition between
+     * adjacent `Strip` items. Separators only ever need the column adjacent to
      * them, so the cell type exposes that column rather than constraining its
      * interior to be uniform. For RichText with uniform styling, both edges
      * return the same style; for RichText with edge variation, each edge
@@ -291,7 +283,8 @@ export class RichText {
         const base = this.resolvedStyle(options);
         if (this._text.get().length === 0)
             return base;
-        const pos = side === "left" ? 0 : this._text.get().length - 1;
+        const shown = edges(this._text.get(), options.textOrder ?? "plain");
+        const pos = side === "left" ? shown.left : shown.right;
         let result = base;
         for (const span of this._spans.get()) {
             if (span.start <= pos && pos < span.end) {
@@ -306,10 +299,15 @@ export class RichText {
             if (style !== undefined) {
                 throw new Error("Style argument must not be provided when appending RichText");
             }
-            const offset = this._text.get().length;
+            // [LAW:single-enforcer] Reached only when separate Texts are set on one
+            // line, so here direction state ends with the content holding it. The
+            // string arm below builds one content, and an embedding spans it.
+            const own = this._text.get() + closing(this._unclosed());
+            const offset = own.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());
+            this._text.set(own + closed(content._text.get()));
+            this._closure.set({ text: this._text.get(), tail: "" });
             // 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.get().length, content._format.get().style);
@@ -317,9 +315,11 @@ export class RichText {
                 this._spans.push(span);
             return this;
         }
-        const sanitized = stripControlChars(content);
+        const clean = sanitized(content);
         const start = this._text.get().length;
-        this._text.set(this._text.get() + sanitized);
+        const tail = this._unclosed() + clean;
+        this._text.set(this._text.get() + clean);
+        this._closure.set({ text: this._text.get(), tail });
         this._addSpan(start, this._text.get().length, style ?? "");
         return this;
     }
@@ -475,7 +475,7 @@ export class RichText {
         return this;
     }
     pad(count, char) {
-        const padding = stripControlChars(char ?? " ").repeat(count);
+        const padding = sanitized(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);
@@ -493,13 +493,13 @@ export class RichText {
         return this;
     }
     padLeft(count, char) {
-        const padding = stripControlChars(char ?? " ").repeat(count);
+        const padding = sanitized(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) {
-        this._text.set(this._text.get() + stripControlChars(char ?? " ").repeat(count));
+        this._text.set(this._text.get() + sanitized(char ?? " ").repeat(count));
         return this;
     }
     setLength(length) {
@@ -558,7 +558,7 @@ 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(stripControlChars(options?.marker ?? "\u2026"), cells);
+        const marker = cellFit(sanitized(options?.marker ?? "\u2026"), cells);
         const budget = asCellCol(cells - cellLen(marker));
         if (mode === "right") {
             this._cropRightTo(budget);
@@ -662,25 +662,24 @@ export class RichText {
     }
     // --- Token Appending ---
     appendTokens(tokens) {
+        // Each token is its own content, as `assemble`'s parts are.
         for (const [text, style] of tokens) {
-            this.append(text, style);
+            this.append(new RichText(text, { style }));
         }
         return this;
     }
     // --- Static Factories ---
     static assemble(parts, options) {
         const result = new RichText("", { style: options?.style });
+        // Each part is its own content, a string's included, so each takes
+        // `append`'s RichText arm.
         for (const part of parts) {
-            if (typeof part === "string") {
-                result.append(part);
-            }
-            else if (part instanceof RichText) {
+            if (part instanceof RichText)
                 result.append(part);
-            }
-            else {
-                const [text, style] = part;
-                result.append(text, style);
-            }
+            else if (typeof part === "string")
+                result.append(new RichText(part));
+            else
+                result.append(new RichText(part[0], { style: part[1] }));
         }
         return result;
     }
@@ -754,19 +753,32 @@ export class RichText {
         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", ".");
+        const order = options.textOrder ?? "plain";
         for (let index = 0; index < logicalLines.length; index += 1) {
-            const line = logicalLines[index];
+            // [LAW:dataflow-not-control-flow] Every line runs the same steps; the
+            // order is the value `directed` and `orient` take.
+            const { line, oriented, orient } = reorder(logicalLines[index], order);
             const free = spanFree[index];
             const terminateLine = index < logicalLines.length - 1;
             // Wrap first, overflow last — the reference's order, and the reason a
             // long sentence grows a table row while an unbreakable word in the same
             // column still ellipsizes.
-            const cuts = divideLine(plainOf(line), wrapAt, { fold: overflow === "fold" });
-            const wrapped = Segment.divide(line, cuts);
-            const placed = this._justifyLines(wrapped.map((piece, at) => ({
-                segments: [...this._fitLine(piece, edge, overflow, ellipsis)],
-                free: (cell) => free(at === 0 ? cell : cuts[at - 1] + cell),
-            })), maxWidth, base, justify);
+            const breaks = divideLine(Segment.plainOf(line), wrapAt, { fold: overflow === "fold" });
+            const wrapped = Segment.divide(hyphenated(line, breaks), drawnCuts(breaks));
+            let start = 0;
+            const placed = this._justifyLines(wrapped.map((piece, at) => {
+                const source = Segment.plainOf(piece);
+                const from = start;
+                start += source.length;
+                return {
+                    segments: [...this._fitLine(piece, edge, overflow, ellipsis)],
+                    // An oriented row's cells are not where `free` counted them, and a
+                    // pad joined to one would land inside its isolate. A hyphen's cell
+                    // was counted by nobody.
+                    free: oriented || breaks[at]?.hyphen !== undefined ? NEVER_FREE : (cell) => free(at === 0 ? cell : breaks[at - 1].cell + cell),
+                    orient: (segments) => orient(segments, from, source),
+                };
+            }), maxWidth, base, justify);
             for (let piece = 0; piece < placed.length; piece += 1) {
                 yield* placed[piece];
                 if (piece < placed.length - 1 || terminateLine) {
@@ -785,7 +797,7 @@ export class RichText {
     }
     // --- Measurable ---
     measure(options) {
-        const lines = expandTabs(this._text.get(), this._tabSize).text.split("\n");
+        const lines = measured(expandTabs(this._text.get(), this._tabSize).text, options.textOrder ?? "plain").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
@@ -882,7 +894,7 @@ export class RichText {
         if (justify !== "full") {
             return lines.map((line) => [...this._justifyLine(line, maxWidth, base, justify)]);
         }
-        return lines.map(({ segments }, index) => index === lines.length - 1 ? segments : this._fillLine(segments, maxWidth, base));
+        return lines.map(({ segments, orient }, index) => orient(index === lines.length - 1 ? segments : this._fillLine(segments, maxWidth, base)));
     }
     /**
      * One line placed in a canvas `maxWidth` wide.
@@ -901,7 +913,7 @@ export class RichText {
      * The padding is drawn in the text's base style, as the reference pads
      * inside the `Text` it justifies: a title "on red" fills its row in red.
      */
-    *_justifyLine({ segments: line, free }, maxWidth, base, 
+    *_justifyLine({ segments: line, free, orient }, maxWidth, base, 
     // [LAW:types-are-the-program] `full` is absent rather than ignored: it
     // needs the lines either side of this one, so the type refuses it here
     // instead of a branch quietly rendering it as `left`, which is the bug
@@ -914,14 +926,16 @@ export class RichText {
                 const body = Segment.adjustLineLength(line, Segment.getLineLength(line) - hangingWhitespace(line), undefined, false);
                 const gap = Math.max(maxWidth - Segment.getLineLength(body), 0);
                 const leftPad = justify === "center" ? Math.floor(gap / 2) : gap;
-                yield* padded(body, free, leftPad, gap - leftPad, padStyle);
+                yield* padded(orient(body), free, leftPad, gap - leftPad, padStyle);
                 break;
             }
-            case "left":
-                yield* padded(line, free, 0, Math.max(maxWidth - Segment.getLineLength(line), 0), padStyle);
+            case "left": {
+                const row = orient(line);
+                yield* padded(row, free, 0, Math.max(maxWidth - Segment.getLineLength(row), 0), padStyle);
                 break;
+            }
             default:
-                yield* line;
+                yield* orient(line);
                 break;
         }
     }
@@ -946,9 +960,9 @@ export class RichText {
      * blocks respectively.
      */
     _fillLine(line, maxWidth, base) {
-        const plain = plainOf(line);
+        const plain = Segment.plainOf(line);
         const words = plain.split(" ");
-        if (plain.endsWith(" "))
+        if (drawnTail(plain).endsWith(" "))
             words.pop();
         const gaps = words.length - 1;
         const spaces = new Array(gaps).fill(1);
@@ -1030,6 +1044,38 @@ export class RichText {
         yield* Segment.adjustLineLength(line, maxWidth, undefined, false);
     }
 }
+const NEVER_FREE = () => false;
+/**
+ * `line` with the soft hyphen each of `breaks` took turned into `-`, in its own
+ * segment and so its own style. One code unit for one, so an offset into the line
+ * still reads the logical line `orient` was built from.
+ */
+function hyphenated(line, breaks) {
+    const taken = breaks.flatMap(({ hyphen }) => hyphen ?? []);
+    let next = 0;
+    let end = 0;
+    return line.map((segment) => {
+        const start = end;
+        end += segment.text.length;
+        let text = "";
+        let from = 0;
+        for (; next < taken.length && taken[next] < end; next += 1) {
+            const at = taken[next] - start;
+            text += segment.text.slice(from, at) + "-";
+            from = at + 1;
+        }
+        text += segment.text.slice(from);
+        return text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    });
+}
+/** Where `breaks` cut once `hyphenated` has given each hyphen its cell, which the line above it ends in. */
+function drawnCuts(breaks) {
+    let hyphens = 0;
+    return breaks.map(({ cell, hyphen }) => {
+        hyphens += hyphen === undefined ? 0 : 1;
+        return asCellCol(cell + hyphens);
+    });
+}
 /**
  * For each logical line of a render, whether the cell at an offset is covered
  * by no span. `covered` is `_buildSegments`'s answer per piece; a piece split

package/dist/core/timeline.d.ts

@@ -15,13 +15,13 @@
  * 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
+ * `run` is an animation on host time. Its `validUntil` 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,
+ * `validFrom` — 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
@@ -50,7 +50,7 @@
  * 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";
+import { Animation, type Behavior } 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
@@ -95,7 +95,7 @@ export declare const Timeline: {
      * 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>;
+    run<T>(timeline: Timeline, animation: Behavior<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
@@ -105,5 +105,5 @@ export declare const Timeline: {
      * 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[]>;
+    stagger<T>(animations: readonly Behavior<T>[], delay: number): Animation<readonly T[]>;
 };

package/dist/core/timeline.js

@@ -15,13 +15,13 @@
  * 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
+ * `run` is an animation on host time. Its `validUntil` 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,
+ * `validFrom` — 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
@@ -82,10 +82,10 @@ function played(animation, { origin, time, rate }) {
     // Forwards, the host next sees the animation's own next change, and the
     // value began when the animation says it did; backwards, it next sees a
     // change where the value began, and the value began where the animation
-    // says it ends. A hold is `[lastChange, nextChange)`, so the far side of
+    // says it ends. A hold is `[validFrom, validUntil)`, so the far side of
     // an edge is at it going up and strictly under it coming down.
-    const ahead = forward ? (t) => animation.nextChange(t) : (t) => animation.lastChange(t);
-    const behind = forward ? (t) => animation.lastChange(t) : (t) => animation.nextChange(t);
+    const ahead = forward ? (t, moves) => animation.validUntil(t, moves) : (t, moves) => animation.validFrom(t, moves);
+    const behind = forward ? (t, moves) => animation.validFrom(t, moves) : (t, moves) => animation.validUntil(t, moves);
     const past = forward ? (t, edge) => t >= edge : (t, edge) => t < edge;
     // The first host moment the map carries past `edge`, an animation time.
     // An edge at infinity, or one so far off at this rate that no host float
@@ -97,16 +97,16 @@ function played(animation, { origin, time, rate }) {
     };
     return Animation.of({
         at: (host) => animation.at(mapped(hostTime(host))),
-        nextChange(host) {
+        validUntil(host, moves) {
             const h = hostTime(host);
             const t = mapped(h);
-            const edge = ahead(t);
+            const edge = ahead(t, moves);
             return edge === t ? h : Math.max(h, hostOf(edge));
         },
-        lastChange(host) {
+        validFrom(host, moves) {
             const h = hostTime(host);
             const t = mapped(h);
-            const edge = behind(t);
+            const edge = behind(t, moves);
             return edge === t ? h : Math.min(h, hostOf(edge));
         },
         reduced: () => played(animation.reduced(), { playing: true, origin, time, rate }),
@@ -154,8 +154,8 @@ export const Timeline = {
             return played(animation, timeline);
         return Animation.of({
             at: (host) => animation.at(Timeline.at(timeline, host)),
-            nextChange: (host) => (hostTime(host), Number.POSITIVE_INFINITY),
-            lastChange: (host) => (hostTime(host), Number.NEGATIVE_INFINITY),
+            validUntil: (host) => (hostTime(host), Number.POSITIVE_INFINITY),
+            validFrom: (host) => (hostTime(host), Number.NEGATIVE_INFINITY),
             reduced: () => Timeline.run(timeline, animation.reduced()),
         });
     },

package/dist/core/tween.d.ts

@@ -2,11 +2,11 @@
  * Tween — a value eased from one number to another over seconds, then held:
  * the animation a progress bar's fill, a counter or a width is handed so it
  * moves to its new value instead of jumping. The first `Animation` of a
- * value that is never drawn as cells, so its `nextChange` is its only way of
+ * value that is never drawn as cells, so its `validUntil` is its only way of
  * saying when to look again (`./animation.ts`).
  *
  * The value at `t` is the `Timing`'s ease of the way from `from` to `to`
- * through `Phase.once(0, seconds)`: `from` at `t ≤ 0` whenever the ease
+ * through `WrapMode.once(0, seconds)`: `from` at `t ≤ 0` whenever the ease
  * starts at 0, as every built-in does but `step-start` and the steps that
  * jump at the start of their interval, which show their first jump before
  * the tween begins, as `ColorRamp.at` does; `to` from `seconds` on. It is
@@ -25,9 +25,9 @@
  * tween(old.at(t₁), to, timing))` — and starts from where it is because
  * that is where it was built from. [LAW:no-ambient-temporal-coupling]
  *
- * Over colours it is a `ColorRamp` read over time (`../themes/ramp.ts`,
- * `over`): the ramp is already the one place two colours are blended, in
- * OKLCH, and a colour tween is a two-stop ramp over its seconds, not a
+ * Over colors it is a `ColorRamp` read over time (`../themes/ramp.ts`,
+ * `over`): the ramp is already the one place two colors are blended, in
+ * OKLCH, and a color tween is a two-stop ramp over its seconds, not a
  * second blender. [LAW:one-source-of-truth]
  *
  * Tier 6 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
@@ -41,7 +41,7 @@ import { type Timing } from "./easing.js";
  * every ease that starts at 0), `to` after, and so
  * seen at its end, never mid-way, by a host whose frames are further apart
  * than it is long. `from` and `to` must be finite; the seconds are checked
- * where every one-shot's are, in `Phase.once`. A tween to where it already
+ * where every one-shot's are, in `WrapMode.once`. A tween to where it already
  * is is `Animation.constant(from)`, decided here once: the blend would land
  * one ulp off `from` at some `p`, and a value that never moves is one that
  * never changes, so a host is told not to look again. [LAW:parse-dont-validate]

package/dist/core/tween.js

@@ -2,11 +2,11 @@
  * Tween — a value eased from one number to another over seconds, then held:
  * the animation a progress bar's fill, a counter or a width is handed so it
  * moves to its new value instead of jumping. The first `Animation` of a
- * value that is never drawn as cells, so its `nextChange` is its only way of
+ * value that is never drawn as cells, so its `validUntil` is its only way of
  * saying when to look again (`./animation.ts`).
  *
  * The value at `t` is the `Timing`'s ease of the way from `from` to `to`
- * through `Phase.once(0, seconds)`: `from` at `t ≤ 0` whenever the ease
+ * through `WrapMode.once(0, seconds)`: `from` at `t ≤ 0` whenever the ease
  * starts at 0, as every built-in does but `step-start` and the steps that
  * jump at the start of their interval, which show their first jump before
  * the tween begins, as `ColorRamp.at` does; `to` from `seconds` on. It is
@@ -25,23 +25,23 @@
  * tween(old.at(t₁), to, timing))` — and starts from where it is because
  * that is where it was built from. [LAW:no-ambient-temporal-coupling]
  *
- * Over colours it is a `ColorRamp` read over time (`../themes/ramp.ts`,
- * `over`): the ramp is already the one place two colours are blended, in
- * OKLCH, and a colour tween is a two-stop ramp over its seconds, not a
+ * Over colors it is a `ColorRamp` read over time (`../themes/ramp.ts`,
+ * `over`): the ramp is already the one place two colors are blended, in
+ * OKLCH, and a color tween is a two-stop ramp over its seconds, not a
  * second blender. [LAW:one-source-of-truth]
  *
  * Tier 6 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
  * [LAW:one-way-deps]
  */
 import { Animation } from "./animation.js";
-import { Phase } from "./easing.js";
+import { WrapMode } from "./easing.js";
 /**
  * `from` eased to `to` over `timing`, as an `Animation<number>`: moving from
  * 0 to `timing.seconds` on its own clock, the ease of 0 before (`from`, for
  * every ease that starts at 0), `to` after, and so
  * seen at its end, never mid-way, by a host whose frames are further apart
  * than it is long. `from` and `to` must be finite; the seconds are checked
- * where every one-shot's are, in `Phase.once`. A tween to where it already
+ * where every one-shot's are, in `WrapMode.once`. A tween to where it already
  * is is `Animation.constant(from)`, decided here once: the blend would land
  * one ulp off `from` at some `p`, and a value that never moves is one that
  * never changes, so a host is told not to look again. [LAW:parse-dont-validate]
@@ -52,7 +52,7 @@ export function tween(from, to, timing) {
             throw new RangeError(`tween ${name} must be finite, got ${v}`);
     }
     const { ease, seconds } = timing;
-    const phase = Phase.once(0, seconds);
+    const phase = WrapMode.once(0, seconds);
     if (from === to)
         return Animation.constant(from);
     return Animation.of({
@@ -63,8 +63,8 @@ export function tween(from, to, timing) {
         // Before it begins the value is held until 0; while it moves, every
         // frame; from `seconds` on, never again — and it became what it is at
         // `seconds`, or always was before it began.
-        nextChange: (t) => (t < 0 ? 0 : t < seconds ? t : Number.POSITIVE_INFINITY),
-        lastChange: (t) => (t < 0 ? Number.NEGATIVE_INFINITY : t < seconds ? t : seconds),
+        validUntil: (t) => (t < 0 ? 0 : t < seconds ? t : Number.POSITIVE_INFINITY),
+        validFrom: (t) => (t < 0 ? Number.NEGATIVE_INFINITY : t < seconds ? t : seconds),
         // A one-shot, reduced, cuts from where it starts to where it arrives.
         reduced: () => Animation.cut(from, to),
     });