@sparkletree/core 0.11.2 → 0.13.0

package/dist/state.js

@@ -1,66 +1,112 @@
 /**
- * Copy choreography — the rewrite/settle state machine.
+ * Copy choreography — the hold/settle state machine.
  *
  * This is the part of the SDK that is not a fetch wrapper. The principle it
  * serves is a user-experience one, and everything else here follows from it:
  *
- *   NO BAIT AND SWITCH. A visitor is never shown something and then has it
- *   replaced, taken away, or pushed around — copy, image, video, layout,
- *   all of it. So the space is reserved blank (sized by the copy it keeps
- *   room for — never a skeleton, never a spinner) until there is something
- *   final to show. If the stream delivers inside the budget, that is what
- *   the visitor gets. If it is too slow or fails, the fallback is what they
- *   get. Either way, that is the content for this page view. A stream that
- *   arrives after the visitor already has something in front of them has
- *   lost its slot: it is discarded from the canvas (it may still inform
- *   provenance and analytics). The fallback is the failure path; it never
- *   shows first and then gets replaced.
+ *   TEXT A VISITOR CAN SEE IS NEVER REPLACED WHILE IT IS ON SCREEN.
  *
- *   TEXT ON THE WIRE IS TEXT WE CAN SHOW. The first CHUNK takes the canvas,
- *   whatever the `*-start` called itself. The delivery `mode` is not
- *   consulted for hold release — an earlier revision released on
- *   `mode: "generate"` and kept holding on `replay`, which re-derived from
- *   a label what the arrival of actual text proves directly. A replay's
- *   single flush still paints once, because one flush is genuinely what
- *   arrived — not because it was held back.
+ *   1. When a copy slot comes into view and live copy is coming, the slot
+ *      holds blank with its geometry reserved for a short budget
+ *      (`COPY_HOLD_MS`), restarting once when the stream proves it is alive.
+ *   2. Stream text arriving inside the hold types into the blank slot (a
+ *      cached replay's single flush lands whole). The fallback is never seen.
+ *   3. If the hold runs out with nothing delivered, the fallback lands once
+ *      and is FINAL for this view: any later stream text for that field is
+ *      dropped — never painted, never composed over it.
+ *   4. Art, background and chrome are never held; only text slots are.
  *
- * The hold is the mechanism: the canvas holds blank on the art for a budget —
- * a budget for the STORED FALLBACK, not for the stream.
+ * Every field is in exactly one of three conditions:
  *
- * KNOWN BUGS AGAINST THE PRINCIPLE, still in this file: a late stream's
- * finished text can land once over a shown fallback (the composed landing at
- * `*-done`; `rewrites` reaching 1), and fallback text that server HTML showed
- * before the hold could arm is tolerated rather than prevented. Neither is a
- * feature. Do not build on them, and do not read them as permission to show
- * something and then replace it.
+ *   - blank: held (reserved) or simply empty, waiting for the stream;
+ *   - live: stream text is on the canvas; later chunks EXTEND it (typing),
+ *     and its `*-done` completes it — never replaces it;
+ *   - final: copy the visitor can read that the stream does not own — the
+ *     fallback after the hold, finished creative the platform rendered, or
+ *     copy that was already on screen when the stream opened. Copy events
+ *     for a final field are dropped.
  *
- * Reference implementation (the iframe shell, which must stay behaviourally
- * identical): `mosaic/services/rendererService.ts`, streamInitialCopyCreative.
+ * There is one exception to "never replaced", and it is isolated in one
+ * function: a sentence the stream was still WRITING when it failed. See
+ * `UnfinishedCopyPolicy`.
  */
 import { CONTENT_SOURCES } from "./wire.js";
+import { warnDev } from "./devwarn.js";
 import { safeActionUrl } from "./safeUrl.js";
 export const COPY_FIELDS = ["greeting", "headline", "body", "cta"];
 /**
- * How long the canvas will hold blank waiting for the stream.
+ * How long a copy slot holds blank, waiting for live copy, before the
+ * fallback lands.
  *
- * Armed when the REQUEST opens (openStream calls streamOpened before the
- * fetch), so the fallback never paints ahead of a stream that is about to
- * replace it. The slow-connect worry that once argued for arming against the
- * connection instead is answered by the restart: `copyStart` restarts the
- * budget ONCE when the stream proves it is alive, so a slow link still gets a
- * full budget for delivery — without the blank window being extended per
- * field.
+ * The budget starts when the slot is in view (or when the stream opens, for
+ * a renderer that does not report visibility), and restarts ONCE when the
+ * stream proves it is alive (its first `*-start`). So the longest a slot can
+ * hold is `COPY_HOLD_MAX_MS`.
  */
 export const COPY_HOLD_MS = 2500;
+/** The longest a slot can hold: one budget plus the one restart. */
+export const COPY_HOLD_MAX_MS = 2 * COPY_HOLD_MS;
+/**
+ * The pure-CSS failsafe for server-rendered reservations: if the page's
+ * JavaScript never takes control, reserved fallback copy becomes visible on
+ * its own after this long. Equal to the longest hold, so the failsafe can
+ * never reveal copy a running hold still owns.
+ */
+export const RESERVE_FAILSAFE_MS = COPY_HOLD_MAX_MS;
+/**
+ * The one motion grammar for copy: every fade and cross-fade runs for this
+ * long on `COPY_MOTION_EASING`. Typing has its own pace; nothing else moves.
+ */
+export const COPY_MOTION_MS = 700;
+/** The easing curve for every copy fade and cross-fade. */
+export const COPY_MOTION_EASING = "cubic-bezier(0.16, 1, 0.3, 1)";
+// Each pattern is something marketing copy does not contain. Deliberately
+// narrow: a false positive replaces real copy the visitor was reading.
+const ERROR_TEXT_PATTERNS = [
+    // An error message opening a line: "Error: …", "TypeError: …".
+    /(?:^|\n)\s*[A-Za-z]*(?:Error|Exception): /,
+    // A stack: a frame like "at fn (file.js:12:3)", or a Python traceback.
+    /\bat \S+ \(\S+:\d+:\d+\)/,
+    /Traceback \(most recent call last\)/,
+    // Status text: an HTTP status line or a 4xx/5xx reason phrase.
+    /\bHTTP\/\d(?:\.\d)? \d{3}\b/,
+    /\b[45]\d\d (?:Bad Request|Unauthorized|Forbidden|Not Found|Method Not Allowed|Request Timeout|Too Many Requests|Internal Server Error|Bad Gateway|Service Unavailable|Gateway Timeout)\b/i,
+    // Raw markup: an HTML/XML tag.
+    /<\/?[a-z][a-z0-9-]*(?:\s[^<>]*)?\/?>/i,
+    // Raw JSON: an object or array opening with a key, or a quoted key/value.
+    /^\s*[[{]\s*["{[]/,
+    /"[A-Za-z_][\w-]*"\s*:\s*["{[\d]/,
+    // A model refusal.
+    /\b(?:I'm sorry|I am sorry|I apologi[sz]e|As an AI\b|I(?:'m| am) unable to|I can(?:'|no)t (?:help|assist|comply|provide|create|write) )/i,
+];
+/**
+ * True when `text` is very clearly not copy: it contains an error message, a
+ * stack or status text, raw markup or JSON, or a model refusal. Conservative
+ * by design — anything that could be ordinary copy returns false.
+ */
+export function isClearlyErrorText(text) {
+    return ERROR_TEXT_PATTERNS.some((pattern) => pattern.test(text));
+}
+/**
+ * The default `UnfinishedCopyPolicy`: keep whatever the stream already typed,
+ * even an unfinished line. Only text that is clearly an error
+ * (`isClearlyErrorText`) is replaced, with one fade to the fallback.
+ */
+export const keepUnlessClearlyError = ({ typed }) => isClearlyErrorText(typed) ? "fallback" : "keep";
 function emptyField(text = "", source = "static") {
     return { text, source, mode: null, typing: false, settled: false };
 }
+/** A field holding copy the stream does not own: authored, static, at rest. */
+function restingField(field, text) {
+    return { ...field, text, source: "static", mode: null, typing: false };
+}
+const SOURCE_RANK = { static: 0, cached: 1, generated: 2 };
 /**
  * Owns one island's copy for one page view. Fed wire events; emits states.
  *
  * Pure with respect to the DOM: it decides WHAT should be on screen and when,
  * and never touches how. That is what lets the same choreography drive React,
- * the iframe shell, and anything else without three copies of these rules.
+ * the iframe shell, and anything else without several copies of these rules.
  */
 export class CopyChoreographer {
     options;
@@ -69,59 +115,37 @@ export class CopyChoreographer {
     holdMs;
     setTimer;
     clearTimer;
-    /**
-     * Copy pulled off the canvas when the hold armed. Alive until the stream
-     * TERMINATES (`done`/`failed`), not merely until the hold releases: any
-     * field the stream never delivers is restored from here, because a field
-     * the stream never took must end on its fallback — never on the blank the
-     * hold itself painted.
-     */
+    releaseOn;
+    unfinishedPolicy;
+    // The fallback for each field as reserved by the hold (null when no hold).
     heldCopy = null;
+    // The hold budget. Runs from view until it expires or the stream ends; it
+    // outlives a chunk-driven release so no slot stays blank past it.
     holdTimer = null;
-    /**
-     * The budget may restart ONCE per hold episode. Without a cap, a server
-     * emitting a `*-start` per field would extend the blank window by a full
-     * budget per field — proof of life is proof once, and a blank canvas is a
-     * cost the visitor pays, so it is not for sale twice.
-     */
+    // One restart per view: proof of life is proof once.
     holdRestarted = false;
-    /** Text accumulated from the wire while the hold is still on. */
+    // When the hold budget started (clock time, minus any time already spent),
+    // so the absolute maximum holds across the restart.
+    holdStartedAt = null;
+    // When the running hold timer is due (clock time), so an expiry a
+    // throttled or frozen timer has not run yet is still honoured.
+    holdDueAt = null;
+    now;
+    // Is the slot in view (has the hold budget been allowed to start)?
+    inView;
+    // Text from the wire, per field. While holding it is a buffer; once live
+    // it mirrors what the field shows.
     pending = {};
-    /** True once the machine has committed a change to the first paint. */
-    rewriteCommitted = false;
-    /**
-     * Fields whose on-canvas text the visitor is already reading: restored
-     * fallback, `serverRendered` creative, or initial copy that was on screen
-     * when the stream opened (`initialIsOnScreen`). Live deltas buffer
-     * off-canvas for these. That the buffer then lands at `*-done` is a known
-     * bug against the file header's principle: shown text should stay.
-     *
-     * Gated on ON-SCREEN, never on non-empty: an earlier revision seeded it
-     * with every non-empty field at first paint, which is every field of
-     * every integration (fallback is required by doctrine), so `typing` was
-     * never true and paced streaming was dead. A held field's canvas is
-     * blank, and typing into blank is the entrance — that path must never
-     * seed here.
-     */
-    fallbackOnCanvas = new Set();
-    /** Fields the stream has opened with a `*-start` (or that received a chunk). */
+    // Fields whose visible text the stream does not own. Copy events dropped.
+    final = new Set();
+    // Fields showing stream text.
+    live = new Set();
+    // Fields the stream opened (`*-start` or a chunk) and closed (`*-done`).
     started = new Set();
-    /**
-     * First-paint copy, kept for the terminal restore: a field the stream
-     * opened but never closed must end on its WHOLE fallback, never on the
-     * half-typed fragment the dead stream left (`"Meet the web that"`). The
-     * hold's `heldCopy` only exists when the hold armed; typing over on-screen
-     * fallback needs this snapshot instead.
-     */
-    initialCopy = {};
-    /**
-     * Fields the stream has closed with a `*-done`, including closes that
-     * arrived while the hold was still on and so never reached the canvas at the
-     * time. Consulted when the copy finally paints, so `settled` describes the
-     * field rather than the route it took.
-     */
     closed = new Set();
-    /** Set by dispose(): async completions (image decode) must not patch after it. */
+    // First-paint copy: the fallback for a field the hold never reserved.
+    initialCopy = {};
+    // Set by dispose(): async completions (image decode) must not patch after it.
     disposed = false;
     constructor(options = {}) {
         this.options = options;
@@ -129,10 +153,25 @@ export class CopyChoreographer {
         this.setTimer = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
         this.clearTimer =
             options.clearTimeout ?? ((handle) => clearTimeout(handle));
+        this.releaseOn = options.releaseOn ?? "text";
+        this.now = options.now ?? (() => Date.now());
+        this.unfinishedPolicy = options.unfinishedCopy ?? keepUnlessClearlyError;
+        this.inView = !options.holdStartsInView;
         const fields = {};
+        const finishedSource = options.serverRendered ? (options.initialSource ?? "static") : "static";
+        let seededSource = "static";
         for (const field of COPY_FIELDS) {
-            fields[field] = emptyField(options.initial?.[field] ?? "");
-            this.initialCopy[field] = options.initial?.[field] ?? "";
+            const text = options.initial?.[field] ?? "";
+            const source = options.serverRendered
+                ? (options.initialSources?.[field] ?? finishedSource)
+                : "static";
+            fields[field] = emptyField(text, text !== "" ? source : "static");
+            if (options.serverRendered && text !== "")
+                fields[field].settled = true;
+            if (SOURCE_RANK[fields[field].source] > SOURCE_RANK[seededSource]) {
+                seededSource = fields[field].source;
+            }
+            this.initialCopy[field] = text;
         }
         this.state = {
             phase: "idle",
@@ -146,9 +185,9 @@ export class CopyChoreographer {
             ctaStyle: null,
             ctaAction: null,
             meta: null,
-            contentSource: "static",
+            contentSource: seededSource,
             degraded: null,
-            variantId: null,
+            variantId: options.initialVariantId ?? null,
             error: null,
             rewrites: 0,
             held: null,
@@ -167,10 +206,8 @@ export class CopyChoreographer {
                 listener(this.state);
             }
             catch {
-                // Swallowed on purpose. A subscriber throwing is the SUBSCRIBER's bug;
-                // letting it propagate would tear down the stream for every other
-                // listener and break the customer's page from inside a render effect.
-                // Same isolation the audio emitter applies (audio.ts createEmitter).
+                // A subscriber throwing is the subscriber's bug; letting it propagate
+                // would tear down the stream for every other listener.
             }
         }
     }
@@ -188,286 +225,331 @@ export class CopyChoreographer {
     hasInitialCopy() {
         return COPY_FIELDS.some((field) => this.state.fields[field].text.trim() !== "");
     }
+    anyPending() {
+        return COPY_FIELDS.some((field) => (this.pending[field] ?? "") !== "");
+    }
+    isTerminal() {
+        return this.state.phase === "settled" || this.state.phase === "failed";
+    }
+    fallbackFor(field) {
+        return this.heldCopy?.[field] ?? this.options.fallback?.[field] ?? this.initialCopy[field] ?? "";
+    }
     /**
-     * Call when the stream request has been opened.
+     * Call when live copy is coming: when the stream request opens, or earlier
+     * when a renderer already knows it will (a stream waiting on a shared
+     * variant). Idempotent.
      *
-     * Arms the hold if — and only if — there is initial copy on the canvas the
-     * visitor has not seen yet. That is the intended path: the hold arms before
-     * the first frame, so the fallback never shows ahead of the stream. Copy
-     * the visitor is already looking at (`initialIsOnScreen`, `serverRendered`)
-     * is left alone — taking it away now would be the bait and switch.
+     * Arms the hold when there is fallback copy the visitor has not seen. Copy
+     * the visitor can already see (`initialIsOnScreen`) or finished creative
+     * (`serverRendered`) is final instead: nothing to hold, nothing to replace.
      */
     streamOpened() {
         if (this.state.phase !== "idle")
             return;
-        const onScreen = this.options.initialIsOnScreen || this.options.serverRendered;
-        if (this.hasInitialCopy() && !onScreen) {
+        // A field the fallback does not have has no slot: it is never shown.
+        if (this.options.fallbackDefinesSlots && this.hasInitialCopy()) {
+            for (const field of COPY_FIELDS) {
+                if (this.state.fields[field].text.trim() === "")
+                    this.final.add(field);
+            }
+        }
+        if (this.options.initialIsOnScreen || this.options.serverRendered) {
+            const whole = this.options.serverRendered === true && this.options.initialIsComplete === true;
+            for (const field of COPY_FIELDS) {
+                if (whole || this.state.fields[field].text.trim() !== "")
+                    this.final.add(field);
+            }
+            this.patch({ phase: "live" });
+            return;
+        }
+        if (this.hasInitialCopy()) {
             this.heldCopy = {};
-            this.holdRestarted = false;
             const blanked = {};
             for (const field of COPY_FIELDS) {
                 this.heldCopy[field] = this.state.fields[field].text;
                 blanked[field] = { ...this.state.fields[field], text: "" };
             }
-            // `held` rides every later state spread untouched: the reservation
-            // stays readable for as long as the hold's snapshot is alive.
             this.state = { ...this.state, phase: "holding", fields: blanked, held: this.heldCopy };
-            this.holdTimer = this.setTimer(() => this.onHoldExpired(), this.holdMs);
+            if (this.inView)
+                this.armHold();
             this.emit();
             return;
         }
-        // Nothing to HOLD: either the canvas is genuinely blank (so live typing IS
-        // the entrance) or the visitor is already reading the copy (so it is not
-        // taken away).
-        //
-        // Copy the visitor is reading is not typed over either: deltas aimed at
-        // it buffer off-canvas, whether the words are campaign creative or the
-        // developer's fallback. If the stream dies mid-field the terminal
-        // handlers keep (or repaint) the WHOLE fallback rather than stranding
-        // the reader on a fragment. That the buffer still lands once at `*-done`
-        // is a known bug (file header), not the intent.
-        //
-        // The seeding is gated on ON-SCREEN, never on non-empty: an earlier
-        // revision seeded every non-empty field here, and since `fallback` is
-        // required by doctrine and paints before the stream opens, that made
-        // `typing` permanently false and killed paced streaming in every real
-        // integration. The held path stays live typing: its canvas is blank,
-        // and typing into blank is the entrance, not churn.
-        if (onScreen) {
-            for (const field of COPY_FIELDS) {
-                if (this.state.fields[field].text.trim() !== "")
-                    this.fallbackOnCanvas.add(field);
-            }
-        }
+        // Nothing to hold: the canvas is genuinely blank, so live typing IS the
+        // entrance.
         this.patch({ phase: "live" });
     }
     /**
-     * Hold expired without the stream taking the canvas.
+     * Call when the slot is in view (already in view at mount counts). Only
+     * meaningful with `holdStartsInView`; otherwise the slot is in view from
+     * the start and this is a no-op.
      *
-     * Prefer whatever the stream actually delivered; the stored copy is the last
-     * resort, never a first draft.
+     * At that moment copy the stream already delivered takes the canvas —
+     * finished fields land whole, unfinished ones type from the buffer — and
+     * with nothing delivered the hold budget starts.
      */
-    onHoldExpired() {
-        this.holdTimer = null;
+    slotInView() {
+        if (this.inView)
+            return;
+        this.inView = true;
         if (this.state.phase !== "holding")
             return;
-        if (COPY_FIELDS.some((field) => (this.pending[field] ?? "") !== "")) {
-            this.releaseHoldToLive(true);
+        if (this.releaseOn === "text" && this.anyPending()) {
+            this.releaseHold("view");
+            this.armHold();
             return;
         }
-        this.restoreHeld();
+        this.armHold();
     }
-    /**
-     * The stream is over and the canvas is final.
-     *
-     * `readSseStream` keeps draining after a terminal event, and the parser's
-     * flush can emit a trailing frame, so late copy events are reachable rather
-     * than theoretical. Without this guard a post-`failed` chunk left
-     * `typing: true` forever — a caret animating on a dead stream — and a
-     * post-`done` chunk+done replaced settled text WITHOUT incrementing
-     * `rewrites`, so the doctrine counter read 1 while the reader saw two
-     * changes. Everything after the terminal event is dropped.
-     */
-    isTerminal() {
-        return this.state.phase === "settled" || this.state.phase === "failed";
+    /** Milliseconds left before the hold's absolute maximum (2 × budget). */
+    absoluteRemaining() {
+        if (this.holdStartedAt === null)
+            return 2 * this.holdMs;
+        return Math.max(0, this.holdStartedAt + 2 * this.holdMs - this.now());
+    }
+    armHold() {
+        if (this.holdTimer !== null || this.disposed)
+            return;
+        if (this.holdStartedAt === null) {
+            // Time already spent holding (a reservation that painted before this
+            // took over) counts against the budget and the maximum.
+            this.holdStartedAt = this.now() - Math.max(0, this.options.holdElapsedMs ?? 0);
+        }
+        const firstBudget = Math.max(0, this.holdStartedAt + this.holdMs - this.now());
+        this.startHoldTimer(firstBudget);
+    }
+    startHoldTimer(ms) {
+        this.holdDueAt = this.now() + ms;
+        this.holdTimer = this.setTimer(() => this.onHoldExpired(), ms);
     }
     clearHoldTimer() {
         if (this.holdTimer !== null) {
             this.clearTimer(this.holdTimer);
             this.holdTimer = null;
         }
+        this.holdDueAt = null;
     }
     /**
-     * Hand the canvas to the live stream: what has accumulated paints at once,
-     * so the rest can stream in behind it.
-     *
-     * `restoreUndelivered` distinguishes the two callers. On a chunk-driven
-     * release the stream is alive and delivering, so undelivered fields stay
-     * blank — typing into a blank canvas is their entrance, and `heldCopy`
-     * outlives the hold so `done`/`failed` restore any field the stream never
-     * takes. On budget EXPIRY the stream has sputtered: whatever it delivered
-     * paints, and every undelivered field gets its fallback back now, because
-     * blank is never the resting state the budget is allowed to buy.
+     * Apply a hold expiry whose time has already passed but whose timer has
+     * not run: a background tab throttles timers, and a page restored from the
+     * back/forward cache resumes with them overdue. Copy events call this
+     * first, so text arriving after the deadline is never shown in place of
+     * the fallback. Renderers call it when the page is shown again. Idempotent.
      */
-    releaseHoldToLive(restoreUndelivered) {
+    checkDeadline() {
+        if (this.holdTimer === null || this.holdDueAt === null || this.disposed)
+            return;
+        if (this.now() < this.holdDueAt)
+            return;
         this.clearHoldTimer();
+        this.onHoldExpired();
+    }
+    /**
+     * The budget ran out. While still holding: delivered copy takes the canvas
+     * and keeps streaming, and every field with nothing delivered gets its
+     * fallback — final. After a chunk already took the canvas: fields still
+     * blank get their fallback, final; fields the stream is writing continue.
+     */
+    onHoldExpired() {
+        this.holdTimer = null;
+        this.holdDueAt = null;
+        if (this.state.phase === "holding") {
+            if (this.anyPending())
+                this.releaseHold("expiry");
+            else
+                this.restoreHeld();
+            return;
+        }
+        if (this.state.phase !== "live" || !this.heldCopy)
+            return;
+        const fields = { ...this.state.fields };
+        let changed = false;
+        for (const field of COPY_FIELDS) {
+            if (this.live.has(field) || this.final.has(field))
+                continue;
+            if (fields[field].text !== "")
+                continue;
+            fields[field] = restingField(fields[field], this.fallbackFor(field));
+            this.final.add(field);
+            changed = true;
+        }
+        if (!changed)
+            return;
+        this.state = { ...this.state, fields };
+        this.emit();
+    }
+    /**
+     * Hand the held canvas to the stream. Delivered fields take their text:
+     * finished ones whole, unfinished ones typing on. `reason` decides the
+     * rest:
+     *
+     *   - "chunk": the first text arrived in time. Undelivered fields stay
+     *     blank and reserved; the budget keeps running for them.
+     *   - "view": the slot just came into view with copy already buffered.
+     *   - "expiry": the budget ran out; undelivered fields get their fallback,
+     *     final.
+     *   - "terminal": the stream ended; the terminal handler settles the rest.
+     */
+    releaseHold(reason) {
+        if (reason !== "chunk" && reason !== "view")
+            this.clearHoldTimer();
         const fields = { ...this.state.fields };
-        let paintedStreamText = false;
         for (const field of COPY_FIELDS) {
             const text = this.pending[field];
             if (text !== undefined && text !== "") {
-                fields[field] = { ...fields[field], text, settled: this.closed.has(field) };
-                this.fallbackOnCanvas.delete(field);
-                if (text !== (this.heldCopy?.[field] ?? ""))
-                    paintedStreamText = true;
+                const closed = this.closed.has(field);
+                fields[field] = {
+                    ...fields[field],
+                    text,
+                    settled: closed,
+                    // A chunk-driven entrance types per its declared mode; buffered
+                    // text that is still being written types on from the buffer.
+                    typing: closed ? false : reason === "chunk" ? fields[field].typing : true,
+                };
+                this.live.add(field);
                 continue;
             }
-            if (!restoreUndelivered)
-                continue;
-            const held = this.heldCopy?.[field];
-            if (held !== undefined && held !== "") {
-                fields[field] = { ...fields[field], text: held };
-                this.fallbackOnCanvas.add(field);
+            if (reason === "expiry") {
+                fields[field] = restingField(fields[field], this.fallbackFor(field));
+                this.final.add(field);
             }
         }
-        // Restoring fallback is not a rewrite — nothing the reader saw changed
-        // versus first paint. Stream text landing is the one rewrite.
-        if (paintedStreamText)
-            this.commitRewrite();
         this.state = { ...this.state, phase: "live", fields };
         this.emit();
     }
-    /** Budget spent with nothing delivered: the fallback comes back, composed. */
+    /** Budget spent with nothing delivered: every fallback lands once, final. */
     restoreHeld() {
         this.clearHoldTimer();
-        if (!this.heldCopy) {
-            this.patch({ phase: "live" });
-            return;
-        }
         const fields = { ...this.state.fields };
         for (const field of COPY_FIELDS) {
-            const text = this.heldCopy[field];
-            if (text !== undefined)
-                fields[field] = { ...fields[field], text };
-            if (text !== undefined && text !== "")
-                this.fallbackOnCanvas.add(field);
+            fields[field] = restingField(fields[field], this.fallbackFor(field));
+            this.final.add(field);
         }
-        this.heldCopy = null;
         this.state = { ...this.state, phase: "live", fields };
         this.emit();
     }
-    /**
-     * Record that the first paint has been replaced. Restoring the SAME fallback
-     * text is not a rewrite — nothing on screen changed — which is why every
-     * caller commits only when STREAM text actually painted, and restoreHeld
-     * never commits at all.
-     */
-    commitRewrite() {
-        if (this.rewriteCommitted)
-            return;
-        this.rewriteCommitted = true;
-        this.state = { ...this.state, rewrites: this.state.rewrites + 1 };
-    }
-    /**
-     * Terminal honesty pass over provenance.
-     *
-     * A field still in `fallbackOnCanvas` when the stream ends is showing the
-     * customer's AUTHORED text: its buffered deltas never landed. Its `source`
-     * still says `generated` because `*-start` declared an intent the stream
-     * then failed to deliver — and `field.source` feeds every provenance
-     * surface: the `data-content-source` stamp, `decideChrome` (and any opt-in
-     * `InlineMark` the integrator renders from it), `$group.marked`, and the
-     * impression beacon's `chromeMarked`. Leaving it would claim "adapted" on
-     * copy nobody adapted, on all of them at once.
-     *
-     * Provenance must describe what is on screen, not what the server meant to
-     * send. Under-claiming adapted copy costs credit; claiming authored copy is
-     * adapted is a false statement, and that is the worse of the two.
-     *
-     * `fallbackOnCanvas` is NOT the whole set. A chunk-driven release leaves
-     * undelivered fields blank — restoring them mid-stream would stage the
-     * wipe-and-retype this machine exists to prevent — so they never enter that
-     * set, and are instead restored from `heldCopy` by the terminal handlers.
-     * That is the likeliest degradation there is: the server opens a field,
-     * then times out. Demoting only `fallbackOnCanvas` left exactly that path
-     * rendering "adapted for you" over the customer's own sentence.
-     *
-     * So callers pass the fields they restored, and both sets are demoted.
-     */
-    demoteUndeliveredProvenance(fields, restoredFromHeld = []) {
-        for (const field of new Set([...this.fallbackOnCanvas, ...restoredFromHeld])) {
-            fields[field] = { ...fields[field], source: "static", mode: null };
-        }
-    }
     /** True once any field on canvas actually carries adapted copy. */
     hasAdaptedCopyOnCanvas(fields) {
         return COPY_FIELDS.some((field) => fields[field].text.trim() !== "" && fields[field].source !== "static");
     }
+    /** Copy events that arrive before the stream was opened open it first. */
+    ensureOpened() {
+        if (this.state.phase === "idle")
+            this.streamOpened();
+    }
     // --- wire events -----------------------------------------------------------
     /**
-     * A field opened. Proof of life, and provenance — nothing more.
-     *
-     * The canvas changes hands on the first CHUNK, not here: the delivery mode
-     * is recorded on the field but no longer consulted for hold release. All a
-     * start does while holding is RESTART the fallback budget, because the
-     * stream has just proven it is alive and the old budget was measuring a
-     * connection that had not connected yet.
+     * A field opened: proof of life, and provenance. Restarts the hold budget
+     * once if it is running. Dropped for a final field.
      */
     copyStart(field, mode, source) {
+        if (this.isTerminal())
+            return;
+        this.ensureOpened();
+        this.checkDeadline();
+        if (this.final.has(field))
+            return;
         this.started.add(field);
-        // A caret is only honest when deltas will actually land on canvas; deltas
-        // aimed at on-screen copy (or restored fallback) buffer off-canvas
-        // instead.
-        const willType = mode === "generate" && !this.fallbackOnCanvas.has(field);
-        this.patchField(field, { mode, source, typing: willType, settled: false });
+        this.patchField(field, { mode, source, typing: mode === "generate", settled: false });
         this.promoteContentSource(source);
-        if (this.state.phase !== "holding")
-            return;
-        // One restart buys the freshly-proven stream a full budget; further
-        // starts do not extend the blank window past that cap.
-        if (this.holdRestarted)
+        if (this.holdTimer === null || this.holdRestarted)
             return;
         this.holdRestarted = true;
         this.clearHoldTimer();
-        this.holdTimer = this.setTimer(() => this.onHoldExpired(), this.holdMs);
+        // A fresh budget, but never past the absolute maximum.
+        this.startHoldTimer(Math.min(this.holdMs, this.absoluteRemaining()));
     }
     /**
-     * A delta landed. Text on the wire is text we can show: the first chunk
-     * takes the canvas away from the pending fallback, whatever the start
-     * called itself. While the field shows fallback copy the visitor can see,
-     * deltas buffer off-canvas and never paint delta by delta. (That the
-     * buffer lands once at `*-done` is a known bug, file header: shown
-     * fallback should be final.)
+     * A delta landed. While holding (and in view) the first text takes the
+     * canvas; on a live field it extends the text. Dropped for a final field.
      */
     copyChunk(field, text) {
         if (this.isTerminal())
             return;
-        // A chunk without its `*-start` is a contract violation, but the terminal
-        // restore must still know this field was taken — a stranded fragment is a
-        // stranded fragment whichever event painted it.
+        this.ensureOpened();
+        this.checkDeadline();
+        if (this.final.has(field))
+            return;
         this.started.add(field);
         this.pending[field] = (this.pending[field] ?? "") + text;
         if (this.state.phase === "holding") {
-            // The release paints everything pending, this chunk included.
-            this.releaseHoldToLive(false);
+            if (this.inView && this.releaseOn === "text")
+                this.releaseHold("chunk");
             return;
         }
-        if (this.fallbackOnCanvas.has(field))
-            return;
-        // Commit BEFORE the emitting patch: subscribers must see the counter and
-        // the text move together, not the counter one event late.
-        this.commitRewrite();
-        this.patchField(field, { text: this.pending[field], typing: true });
+        this.live.add(field);
+        // Live typing for a generate field; a replay's flush lands whole.
+        this.patchField(field, {
+            text: this.pending[field],
+            typing: this.state.fields[field].mode === "generate",
+        });
     }
     /**
-     * A field closed. `text` is authoritative — a client that missed chunks can
-     * paint this alone, which is what makes chunk loss a cosmetic problem
-     * instead of a correctness one.
+     * A field closed. Its text completes what the field shows: it lands whole
+     * on a blank field and finishes a typed one. It never replaces different
+     * visible text — if it does not extend what was typed, the typed text
+     * stands (and development builds warn). For a final field this only marks
+     * it settled.
      */
     copyDone(field, text) {
         if (this.isTerminal())
             return;
-        this.pending[field] = text;
-        // Record the close BEFORE the hold's early return. A replay that lands
-        // entirely inside the hold used to leave `settled: false` forever: this
-        // returned before patching, and the terminal handlers only cleared
-        // `typing`. `settled` is public API and a documented styling hook, so a
-        // field whose text is final must say so however it arrived.
+        this.ensureOpened();
+        this.checkDeadline();
         this.closed.add(field);
-        if (this.state.phase === "holding")
+        if (this.final.has(field)) {
+            this.patchField(field, { settled: true, typing: false });
             return;
-        this.fallbackOnCanvas.delete(field);
-        // Landing text identical to what is on canvas changes nothing a reader
-        // can see, so it spends no rewrite.
-        if (text !== this.state.fields[field].text)
-            this.commitRewrite();
-        this.patchField(field, { text, typing: false, settled: true });
+        }
+        this.started.add(field);
+        if (this.state.phase === "holding") {
+            this.pending[field] = text;
+            if (this.inView && this.releaseOn === "text" && text !== "")
+                this.releaseHold("chunk");
+            return;
+        }
+        const current = this.state.fields[field].text;
+        let next = text;
+        if (current !== "" && !text.startsWith(current)) {
+            next = current;
+            warnDev(`copy:done-diverged:${field}`, `the stream closed "${field}" with text that does not continue what it ` +
+                `typed. The typed text stays on screen: visible copy is never replaced.`);
+        }
+        this.pending[field] = next;
+        if (next !== "")
+            this.live.add(field);
+        this.patchField(field, { text: next, typing: false, settled: true });
+    }
+    /**
+     * The renderer will not show this field's copy: it does not fit the slot
+     * its fallback reserved. The fallback lands instead and is final for the
+     * view; later copy for the field is dropped. Call it before the copy is
+     * painted (a renderer measures before the browser paints), never for text
+     * the visitor has seen.
+     */
+    keepFallback(field) {
+        if (this.disposed)
+            return;
+        const fallback = this.fallbackFor(field);
+        if (this.final.has(field) && this.state.fields[field].text === fallback)
+            return;
+        this.final.add(field);
+        this.live.delete(field);
+        this.pending[field] = "";
+        const fields = { ...this.state.fields };
+        fields[field] = { ...restingField(fields[field], fallback), settled: true };
+        this.state = {
+            ...this.state,
+            fields,
+            contentSource: this.hasAdaptedCopyOnCanvas(fields) ? this.state.contentSource : "static",
+        };
+        this.emit();
     }
     // Terminal is terminal for the ready events too, not just copy: a trailing
-    // cta-ready or theme-ready after `done` (reachable via the parser flush)
-    // must not restyle, re-action, or recolor a settled creative the impression
-    // already recorded. `backgroundReady` gates at ENTRY only — its decode-wait
-    // patch lands after settle by design.
+    // cta-ready or theme-ready after `done` must not restyle, re-action, or
+    // recolor a settled creative the impression already recorded.
+    // `backgroundReady` gates at ENTRY only — its decode-wait patch lands after
+    // settle by design.
     themeReady(colors, sources) {
         if (this.isTerminal())
             return;
@@ -483,22 +565,15 @@ export class CopyChoreographer {
     }
     /**
      * Absence of this event means KEEP THE BAKED THEME WASH. It does not mean
-     * clear the art layer — the server omits it when there is no creative image,
-     * and a client that cleared on absence would blank the hero on exactly the
-     * campaigns that never had a picture.
+     * clear the art layer — the server omits it when there is no creative image.
      *
-     * The patch waits for the browser to DECODE the image first: consumers
-     * render this state directly, and a backgroundImage that lands before
-     * pixels exist paints the already-flipped theme against the old (or blank)
-     * art — the contrast tear. On failure the patch still lands (the consumer's
-     * own loading treatment owns that case); outside a browser it is immediate.
+     * The patch waits for the browser to DECODE the image first, so a new
+     * background never paints before its pixels exist. On failure the patch
+     * still lands; outside a browser it is immediate.
      */
     backgroundReady(bgImage) {
         if (!bgImage || this.isTerminal())
             return;
-        // The decode wait is async: by the time onload fires the consumer may
-        // have disposed this choreographer, and patching then would resurrect
-        // state the owner already tore down.
         const apply = () => {
             if (this.disposed)
                 return;
@@ -546,153 +621,100 @@ export class CopyChoreographer {
             this.copyDone("cta", text);
     }
     /**
-     * Terminal. Anything still held paints now, once, composed — the last
-     * chance for the stream's copy to land as a single deliberate change rather
-     * than being dropped because the budget happened to outlive the stream.
+     * Settle every field at the end of the stream. Final and closed fields stay
+     * as they are; a field that never painted gets its fallback; a field the
+     * stream was still writing goes through the `UnfinishedCopyPolicy`.
      */
-    done(meta) {
-        // Terminal is terminal: a trailing `done` after `error` (or a duplicate
-        // `done` — the parser's flush can re-emit a trailing frame) must not
-        // re-open a settled stream or rebrand a failure as a success.
-        if (this.isTerminal())
-            return;
-        if (this.state.phase === "holding") {
-            if (COPY_FIELDS.some((field) => (this.pending[field] ?? "") !== "")) {
-                // The blank-field restore below handles the undelivered fields.
-                this.releaseHoldToLive(false);
+    settleFields() {
+        if (this.state.phase === "idle") {
+            // Ended before it opened: whatever is on the canvas is the copy.
+            for (const field of COPY_FIELDS) {
+                if (this.state.fields[field].text.trim() !== "")
+                    this.final.add(field);
             }
-            else {
+        }
+        else if (this.state.phase === "holding") {
+            if (this.anyPending())
+                this.releaseHold("terminal");
+            else
                 this.restoreHeld();
-            }
         }
         this.clearHoldTimer();
         const fields = { ...this.state.fields };
-        const restored = [];
         for (const field of COPY_FIELDS) {
-            fields[field] = {
-                ...fields[field],
-                typing: false,
-                settled: fields[field].settled || this.closed.has(field),
-            };
-            // A field the stream never PAINTED ends on its fallback, never on the
-            // blank the hold painted. Not a rewrite: nothing the reader saw
-            // changed versus first paint.
-            //
-            // "Unfinished" is `started && !closed` — the SAME predicate `failed()`
-            // uses, or the two terminal paths disagree about what counts as
-            // delivered. Testing only for blank text missed the case where the
-            // fallback was ALREADY ON SCREEN (the hydrated `"use client"` path,
-            // where server HTML paints the fallback text — a render-path defect
-            // this machine tolerates): the field was neither held nor blank, so it
-            // was neither
-            // restored nor demoted, and ended carrying `source: "generated"` over
-            // the customer's own sentence.
-            //
-            // But an unfinished field with VISIBLE streamed text is different: the
-            // reader is mid-way through real generated copy, and wiping it back to
-            // the fallback at `done` is exactly the mid-read yank the doctrine
-            // forbids. A lost close frame stays cosmetic — the partial text
-            // stands, its provenance true, and the field settles where it is.
-            const held = this.heldCopy?.[field] ?? this.initialCopy[field];
-            const unfinished = this.started.has(field) && !this.closed.has(field);
-            const neverPainted = fields[field].text === "" || (unfinished && fields[field].text === held);
-            if (neverPainted && held !== undefined && held !== "") {
-                // Restored copy is final resting copy: settled, whatever the stream
-                // failed to close.
-                fields[field] = { ...fields[field], text: held, settled: true };
-                restored.push(field);
+            const current = { ...fields[field], typing: false };
+            const fallback = this.fallbackFor(field);
+            if (this.final.has(field)) {
+                fields[field] = { ...current, settled: true };
+                continue;
             }
-            else if (unfinished) {
-                fields[field] = { ...fields[field], settled: true };
+            if (current.text === "") {
+                fields[field] = { ...restingField(current, fallback), settled: true };
+                if (fallback !== "")
+                    this.final.add(field);
+                continue;
             }
+            const unfinished = this.started.has(field) && !this.closed.has(field);
+            if (unfinished && fallback.trim() !== "") {
+                const decision = this.unfinishedPolicy({ field, typed: current.text, fallback });
+                if (decision === "fallback") {
+                    fields[field] = { ...restingField(current, fallback), settled: true, crossfade: true };
+                    this.final.add(field);
+                    continue;
+                }
+            }
+            fields[field] = { ...current, settled: true };
         }
-        this.heldCopy = null;
-        this.demoteUndeliveredProvenance(fields, restored);
-        this.fallbackOnCanvas.clear();
+        return fields;
+    }
+    /** Terminal, success. */
+    done(meta) {
+        // A trailing `done` after `error` (or a duplicate `done`) must not re-open
+        // a settled stream or rebrand a failure as a success.
+        if (this.isTerminal())
+            return;
+        const fields = this.settleFields();
         const declared = typeof meta.contentSource === "string" &&
             CONTENT_SOURCES.includes(meta.contentSource)
             ? meta.contentSource
             : null;
+        // The stream wrote nothing on the canvas: what is there is the seeded
+        // copy, and it keeps its own provenance and variant whatever the stream
+        // says it would have served.
+        const streamWrote = this.live.size > 0;
+        const seededVariant = !streamWrote ? this.options.initialVariantId : undefined;
         this.state = {
             ...this.state,
             phase: "settled",
             fields,
             meta,
-            variantId: typeof meta.variantId === "string" ? meta.variantId : this.state.variantId,
+            variantId: seededVariant ??
+                (typeof meta.variantId === "string" ? meta.variantId : this.state.variantId),
             // The action renders as an <a href>; an unprovable scheme stays out of
             // state and the CTA degrades to a plain button.
             ctaAction: safeActionUrl(typeof meta.ctaAction === "string" ? meta.ctaAction : undefined) ?? this.state.ctaAction,
             degraded: typeof meta.degraded === "string" ? meta.degraded : null,
-            // The server's terminal word on provenance beats the per-field
-            // observation; it is the value the server itself will stand behind.
-            contentSource: declared ?? this.state.contentSource,
+            // The server's terminal word on provenance — but only for copy that
+            // actually reached the canvas. A view that kept its fallback reports
+            // static whatever the server generated.
+            contentSource: !this.hasAdaptedCopyOnCanvas(fields)
+                ? "static"
+                : streamWrote
+                    ? (declared ?? this.state.contentSource)
+                    : this.state.contentSource,
         };
         this.emit();
     }
     /**
-     * The stream failed.
-     *
-     * No failure blanks the canvas. A field that closed keeps its delivered
-     * copy; a field the stream opened but never finished is repainted with its
-     * WHOLE fallback and demoted to `static`; a still-blank field gets its
-     * fallback back. The worst honest outcome is that the creative simply
-     * stopped adapting, which looks like a normal page.
+     * Terminal, failure. No failure blanks the canvas: copy that closed stays,
+     * a blank field gets its fallback, and a field the stream was still writing
+     * goes through the `UnfinishedCopyPolicy`.
      */
     failed(message) {
-        // Terminal is terminal: a late `error` after `done` must not rebrand a
-        // settled stream as a failure — the copy the reader finished with was
-        // real and complete.
+        // A late `error` after `done` must not rebrand a settled stream.
         if (this.isTerminal())
             return;
-        if (this.state.phase === "holding") {
-            // Same fork as `done`: copy delivered during the hold paints, so a
-            // field that closed keeps its delivered text — restoreHeld alone
-            // repainted the fallback over it. Unfinished fields are repainted with
-            // the fallback by the loop below either way.
-            if (COPY_FIELDS.some((field) => (this.pending[field] ?? "") !== "")) {
-                this.releaseHoldToLive(false);
-            }
-            else {
-                this.restoreHeld();
-            }
-        }
-        this.clearHoldTimer();
-        const fields = { ...this.state.fields };
-        const restored = [];
-        for (const field of COPY_FIELDS) {
-            fields[field] = { ...fields[field], typing: false };
-            // Two restores, one rule: a field the stream took but never finished
-            // ends on its WHOLE fallback.
-            //
-            //   - A field that STARTED but never reached its `*-done` may be showing
-            //     a half-typed fragment ("Meet the web that") — the original
-            //     stranding bug. Cancel the entrance and repaint the fallback
-            //     wholesale, exactly as the shell's error path repaints the baked
-            //     copy (rendererService.ts streamIsland 'error' → cancelSmoothText +
-            //     hydrateIsland fallback). An earlier revision restored only fields
-            //     still BLANK, so the fragment survived the stream that died
-            //     mid-sentence.
-            //   - A field still blank when the transport dies (the blank the hold
-            //     itself painted) gets its fallback back, as before.
-            //
-            // A field that DID close (`*-done`) keeps its delivered text: that copy
-            // is final and real, and the failure happened elsewhere.
-            const held = this.heldCopy?.[field] ?? this.initialCopy[field];
-            const unfinished = this.started.has(field) && !this.closed.has(field);
-            if ((unfinished || fields[field].text === "") && held !== undefined && held !== "") {
-                if (fields[field].text !== held)
-                    fields[field] = { ...fields[field], text: held };
-                restored.push(field);
-            }
-        }
-        this.heldCopy = null;
-        this.demoteUndeliveredProvenance(fields, restored);
-        this.fallbackOnCanvas.clear();
-        // No server word to defer to here, so the stream-level value is recomputed
-        // from what actually reached the canvas. A failed stream that delivered
-        // nothing readable leaves a page of authored copy, and the analytics that
-        // reads `contentSource` should say so rather than reporting an adaptation
-        // the visitor never saw.
+        const fields = this.settleFields();
         const contentSource = this.hasAdaptedCopyOnCanvas(fields) ? this.state.contentSource : "static";
         this.state = { ...this.state, phase: "failed", fields, contentSource, error: message };
         this.emit();
@@ -704,8 +726,7 @@ export class CopyChoreographer {
         this.listeners.clear();
     }
     promoteContentSource(source) {
-        const rank = { static: 0, cached: 1, generated: 2 };
-        if (rank[source] > rank[this.state.contentSource]) {
+        if (SOURCE_RANK[source] > SOURCE_RANK[this.state.contentSource]) {
             this.state = { ...this.state, contentSource: source };
         }
     }