@sparkletree/core 0.12.0 → 0.13.0

package/dist/state.d.ts

@@ -1,57 +1,64 @@
 /**
- * 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 { type ContentSource, type CopyMode } from "./wire.js";
 export type CopyField = "greeting" | "headline" | "body" | "cta";
 export declare const COPY_FIELDS: readonly CopyField[];
 /**
- * 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 declare const COPY_HOLD_MS = 2500;
+/** The longest a slot can hold: one budget plus the one restart. */
+export declare const COPY_HOLD_MAX_MS: number;
+/**
+ * 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 declare const RESERVE_FAILSAFE_MS: number;
+/**
+ * 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 declare const COPY_MOTION_MS = 700;
+/** The easing curve for every copy fade and cross-fade. */
+export declare const COPY_MOTION_EASING = "cubic-bezier(0.16, 1, 0.3, 1)";
 export interface FieldState {
     /** What a consumer should render right now. Never a placeholder. */
     text: string;
@@ -62,20 +69,28 @@ export interface FieldState {
     mode: CopyMode | null;
     /** True while live deltas are landing — consumers may animate a caret. */
     typing: boolean;
-    /** `*-done` seen: `text` is final for this stream. */
+    /** `text` is final for this stream: closed by the server, or settled by
+     * the SDK at the end of the stream. */
     settled: boolean;
+    /**
+     * True when `text` deliberately replaces text that may have been visible:
+     * an unfinished sentence withdrawn after a failure (`UnfinishedCopyPolicy`)
+     * or new copy after the campaign or context changed. Renderers cross-fade
+     * once (`COPY_MOTION_MS`, `COPY_MOTION_EASING`) instead of typing. Absent
+     * on every other field — no other change ever replaces visible text.
+     */
+    crossfade?: boolean;
 }
 export type Phase = 
 /** Nothing started. */
 "idle"
-/** Canvas is deliberately blank, waiting out the budget. */
+/** Copy slots are deliberately blank (reserved), waiting for live copy. */
  | "holding"
-/** Live deltas are landing. */
+/** Copy is on the canvas and the stream is still open. */
  | "live"
 /** `done` received. */
  | "settled"
-/** `error`, or the transport failed. Copy that closed stays; anything the
- * stream left unfinished or blank is back on its fallback. */
+/** `error`, or the transport failed. Copy on the canvas stays. */
  | "failed";
 export interface CreativeState {
     phase: Phase;
@@ -97,86 +112,176 @@ export interface CreativeState {
     ctaAction: string | null;
     /** Terminal `done.meta`, verbatim. */
     meta: Record<string, unknown> | null;
-    /** Strongest provenance this stream declared. Drives trust chrome. */
+    /**
+     * Provenance of the copy on the canvas, stream-wide: the strongest any
+     * field declared while live, the server's terminal word once settled, and
+     * `static` whenever no adapted copy actually reached the canvas. Decide a
+     * disclosure mark per field (`field.source`), not from this.
+     */
     contentSource: ContentSource;
-    /** W8 — set when the server served a deterministic winner instead. */
+    /** Set when the server served a deterministic winner instead. */
     degraded: string | null;
     /** Resolved variant, for pinning subsequent calls in this page view. */
     variantId: string | null;
     /** Human-readable failure, if any. Never blanks painted copy. */
     error: string | null;
     /**
-     * What the hold pulled off the canvas, per field — the copy that WAS
-     * painted at first paint (`/content` copy or the consumer's fallback),
-     * exposed so a renderer can reserve its exact geometry while the field
-     * is blank (LAYOUT-DOCTRINE.md layer 1). The choreographer stays
-     * DOM-pure: it reports what was held; drawing the reservation is the
-     * renderer's job. Null when no hold armed this page view.
+     * What the hold reserved, per field: the copy that will land if the hold
+     * runs out. A renderer draws it invisibly so a blank field keeps its exact
+     * geometry. Null when no hold armed in this view.
      *
-     * Optional so a `CreativeState` built by hand — a test mock, a Storybook
-     * fixture — written against 0.3.0 still compiles: every reader goes
-     * through `state.held?.`, so absent and null are the same fact.
+     * Optional so a hand-built `CreativeState` (a test mock, a story fixture)
+     * still compiles: read it as `state.held?.`.
      */
     held?: Partial<Record<CopyField, string>> | null;
     /**
-     * Rewrite counter: how many times the INITIAL copy was replaced by stream
-     * text. Over-reports against the principle in the file header, because it
-     * also counts the held path — initial copy the hold kept invisible, then
-     * stream text typing into the blank — which the visitor experiences as no
-     * replacement at all. A 1 reached after the initial copy was VISIBLE is a
-     * bait and switch (the known bug above). Redefining this to count visible
-     * replacements only is pending. Anything above 1 has always been a
-     * violation and is asserted against in the tests.
+     * How many times text the visitor could see was replaced. Always `0` from
+     * a single stream: the hold, the stream's entrance and the fallback's
+     * landing all write into blank slots. `useIsland` adds one per cross-fade
+     * after a campaign or context change, the only replacement there is.
      */
     rewrites: number;
 }
+/** What `UnfinishedCopyPolicy` decides about. */
+export interface UnfinishedCopy {
+    field: CopyField;
+    /** The text the stream had written when it stopped, possibly mid-word. */
+    typed: string;
+    /** The fallback that would replace it. Never empty when the policy is asked. */
+    fallback: string;
+}
+/**
+ * `"keep"`: the typed text stays and settles where it is.
+ * `"fallback"`: the typed text fades out and the fallback fades in, once.
+ */
+export type UnfinishedCopyDecision = "keep" | "fallback";
+/**
+ * Decides what happens to a field the stream was still writing when it
+ * ended without closing it (an error, a dropped connection, or a `done` that
+ * arrived without the field's own close).
+ *
+ * This is the one place visible text may be replaced, and only when the
+ * policy says so: the default (`keepUnlessClearlyError`) keeps what was
+ * typed unless it is clearly an error. A replacement is a single cross-fade
+ * (`FieldState.crossfade`). A field whose text was finished is never asked
+ * about; a field that never painted simply gets its fallback.
+ */
+export type UnfinishedCopyPolicy = (copy: UnfinishedCopy) => UnfinishedCopyDecision;
+/**
+ * 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 declare function isClearlyErrorText(text: string): boolean;
+/**
+ * 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 declare const keepUnlessClearlyError: UnfinishedCopyPolicy;
 export interface ChoreographerOptions {
     /**
-     * First paint. Real copy from SSR `/content` or the consumer's `fallback`.
-     * Required by doctrine — there is no skeleton mode to fall back to.
+     * The fallback: what lands if live copy does not arrive in time. Required by
+     * doctrine — there is no skeleton mode.
      */
     initial?: Partial<Record<CopyField, string>>;
     /**
-     * True when the initial copy was already in front of the visitor when this
-     * stream opened: copy at rest from an earlier episode in this page view
-     * (an expired hold, a previous stream's copy carried across a re-keyed
-     * identity), or fallback text that server HTML painted before any effect
-     * could hold it. The second should not happen — the fallback is the
-     * failure path and the render path should emit the reservation, not the
-     * text — and is a defect to fix at the server render, not a state to
-     * design for.
+     * True when the initial copy is ALREADY VISIBLE when the stream opens: copy
+     * at rest from earlier in this view, or a fallback the page revealed before
+     * the SDK could hold it. Every non-empty field is then final for this
+     * view: no hold, and the stream's copy events for it are dropped.
      *
-     * What the visitor is looking at is theirs now. It is not blanked and not
-     * typed over; deltas aimed at it buffer off-canvas. (That the buffer still
-     * lands once at `*-done` is one of the known bugs the file header lists.)
+     * Leave it unset for copy that has not been seen yet — the normal case.
+     * The hold then keeps the slot blank until live copy or the fallback lands.
      */
     initialIsOnScreen?: boolean;
     /**
-     * True when the initial copy is genuinely finished, already-presented
-     * CAMPAIGN creative — server-rendered by the platform, not a developer's
-     * `fallback`. This is the SDK analogue of the shell's `[data-baked-creative]`
-     * gate (rendererService.ts streamIsland). It is finished creative, not a
-     * fallback waiting on a stream, so there is nothing to hold and nothing a
-     * stream may replace: live deltas never paint over it. (That their
-     * composed result still lands once at `*-done` is a known bug, file
-     * header.)
+     * True when the initial copy is FINISHED CAMPAIGN CREATIVE rendered by the
+     * platform — not a developer's fallback. It is the copy for this view:
+     * nothing holds, and the stream's copy events for those fields are dropped
+     * (theme, media and the action still apply). Fields left empty may still
+     * be written by the stream.
      *
-     * A developer's fallback must NOT set this: a fallback that has not
-     * painted yet belongs to the hold, whose blank canvas is what keeps the
-     * typed entrance reachable. Setting it from the ordinary client commit
-     * (commit 3dc544913 treated every non-empty first paint this way) made
-     * paced streaming unreachable in every real integration, because
-     * `fallback` is required by doctrine and always paints before the stream
-     * opens.
+     * Do not set it for a `fallback`: a fallback is what lands only when live
+     * copy does not.
      */
     serverRendered?: boolean;
-    /** How long the canvas holds blank waiting for the stream before the initial
-     * copy paints. Defaults to `COPY_HOLD_MS`, and restarts ONCE when the stream
-     * proves it is alive — so the blank can last up to twice this. */
+    /**
+     * The hold budget for this view. Defaults to `COPY_HOLD_MS`; restarts once
+     * when the stream proves alive. However the restart falls, the hold never
+     * lasts longer than twice this in total.
+     */
     holdMs?: number;
-    /** Injectable for tests; defaults to the platform timers. */
+    /**
+     * How long the slot has ALREADY been holding before this choreographer took
+     * over — for example, since a server-rendered reservation first painted.
+     * It is spent from the budget and from the absolute maximum, so the wait
+     * before hydration and the wait after it are one hold. Defaults to 0.
+     */
+    holdElapsedMs?: number;
+    /**
+     * Provenance of the `initial` copy when it is finished creative
+     * (`serverRendered`), for example copy already generated for this view.
+     * Those fields carry it as their `source` and are settled from the start.
+     * Defaults to `static`.
+     */
+    initialSource?: ContentSource;
+    /** The variant the `initial` copy belongs to, if known. Seeds `variantId`. */
+    initialVariantId?: string;
+    /**
+     * With `serverRendered`: the `initial` copy is the WHOLE copy for this
+     * view, so the stream writes no field, empty ones included. Use it for
+     * copy decided before the slot was shown (for example cached copy a
+     * server read for this visitor): a field it left empty stays empty rather
+     * than gaining text later.
+     */
+    initialIsComplete?: boolean;
+    /**
+     * When true, the hold budget does not start until `slotInView()` is called.
+     * The stream may open (and buffer) earlier; a slot that never comes into
+     * view never shows anything changing. When false (the default), the slot
+     * is treated as in view from `streamOpened()`.
+     */
+    holdStartsInView?: boolean;
+    /**
+     * When the held canvas is handed to the stream.
+     *
+     * `"text"` (default): on the first text the stream delivers — live copy
+     * types into the blank slot.
+     *
+     * `"complete"`: only when the stream finishes (`done`), so the whole new
+     * copy lands at once. For a slot whose canvas is showing something else in
+     * the meantime (a campaign or context change); the hold budget still
+     * applies.
+     */
+    releaseOn?: "text" | "complete";
+    /** What happens to a field the stream was still writing when it ended.
+     * Defaults to `keepUnlessClearlyError`. */
+    unfinishedCopy?: UnfinishedCopyPolicy;
+    /**
+     * When true, the fallback decides which fields exist: a field whose
+     * `initial` copy is empty is never shown, and the stream's copy for it is
+     * dropped. A slot sized by its fallback has no room for a field the
+     * fallback does not have. Ignored when `initial` has no copy at all.
+     */
+    fallbackDefinesSlots?: boolean;
+    /**
+     * Per-field provenance of the `initial` copy when it is finished creative
+     * (`serverRendered`). Overrides `initialSource` for the fields it names,
+     * for copy that mixes provenance, such as live copy for one field and the
+     * fallback for another.
+     */
+    initialSources?: Partial<Record<CopyField, ContentSource>>;
+    /**
+     * The authored fallback, when `initial` is other copy (for example copy
+     * already produced for this view). It is what `keepFallback` lands.
+     * Defaults to `initial`.
+     */
+    fallback?: Partial<Record<CopyField, string>>;
+    /** Injectable for tests; defaults to the platform timers and clock. */
     setTimeout?: (fn: () => void, ms: number) => unknown;
     clearTimeout?: (handle: unknown) => void;
+    now?: () => number;
 }
 type Listener = (state: CreativeState) => void;
 /**
@@ -184,7 +289,7 @@ type Listener = (state: CreativeState) => void;
  *
  * 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 declare class CopyChoreographer {
     private readonly options;
@@ -193,59 +298,21 @@ export declare class CopyChoreographer {
     private readonly holdMs;
     private readonly setTimer;
     private readonly 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.
-     */
+    private readonly releaseOn;
+    private readonly unfinishedPolicy;
     private heldCopy;
     private holdTimer;
-    /**
-     * 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.
-     */
     private holdRestarted;
-    /** Text accumulated from the wire while the hold is still on. */
+    private holdStartedAt;
+    private holdDueAt;
+    private readonly now;
+    private inView;
     private pending;
-    /** True once the machine has committed a change to the first paint. */
-    private rewriteCommitted;
-    /**
-     * 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.
-     */
-    private fallbackOnCanvas;
-    /** Fields the stream has opened with a `*-start` (or that received a chunk). */
+    private final;
+    private live;
     private started;
-    /**
-     * 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.
-     */
-    private readonly 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.
-     */
     private closed;
-    /** Set by dispose(): async completions (image decode) must not patch after it. */
+    private readonly initialCopy;
     private disposed;
     constructor(options?: ChoreographerOptions);
     getState(): CreativeState;
@@ -254,125 +321,103 @@ export declare class CopyChoreographer {
     private patch;
     private patchField;
     private hasInitialCopy;
+    private anyPending;
+    private isTerminal;
+    private fallbackFor;
     /**
-     * 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(): void;
     /**
-     * Hold expired without the stream taking the canvas.
-     *
-     * Prefer whatever the stream actually delivered; the stored copy is the last
-     * resort, never a first draft.
-     */
-    private onHoldExpired;
-    /**
-     * The stream is over and the canvas is final.
+     * 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.
      *
-     * `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.
+     * 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.
      */
-    private isTerminal;
+    slotInView(): void;
+    /** Milliseconds left before the hold's absolute maximum (2 × budget). */
+    private absoluteRemaining;
+    private armHold;
+    private startHoldTimer;
     private clearHoldTimer;
     /**
-     * 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.
      */
-    private releaseHoldToLive;
-    /** Budget spent with nothing delivered: the fallback comes back, composed. */
-    private restoreHeld;
+    checkDeadline(): void;
     /**
-     * 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.
+     * 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.
      */
-    private commitRewrite;
+    private onHoldExpired;
     /**
-     * Terminal honesty pass over provenance.
+     * Hand the held canvas to the stream. Delivered fields take their text:
+     * finished ones whole, unfinished ones typing on. `reason` decides the
+     * rest:
      *
-     * 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.
+     *   - "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.
      */
-    private demoteUndeliveredProvenance;
+    private releaseHold;
+    /** Budget spent with nothing delivered: every fallback lands once, final. */
+    private restoreHeld;
     /** True once any field on canvas actually carries adapted copy. */
     private hasAdaptedCopyOnCanvas;
+    /** Copy events that arrive before the stream was opened open it first. */
+    private ensureOpened;
     /**
-     * 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: CopyField, mode: CopyMode | null, source: ContentSource): void;
     /**
-     * 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: CopyField, text: string): void;
     /**
-     * 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: CopyField, text: string): void;
+    /**
+     * 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: CopyField): void;
     themeReady(colors: Record<string, string>, sources: Record<string, string>): void;
     layoutReady(layout: string, manifest?: unknown): void;
     /**
      * 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: string): void;
     sequenceReady(frames: string[], heroIndex: number, fps: number): void;
@@ -380,19 +425,17 @@ export declare class CopyChoreographer {
     ctaStyleReady(style: unknown): void;
     ctaReady(text: string, style: unknown, action?: string): void;
     /**
-     * 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`.
      */
+    private settleFields;
+    /** Terminal, success. */
     done(meta: Record<string, unknown>): void;
     /**
-     * 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: string): void;
     /** Release timers. Safe to call twice. */