@sparkletree/core 0.1.0

package/dist/state.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Copy choreography — the rewrite/settle state machine.
+ *
+ * This is the part of the SDK that is not a fetch wrapper. The doctrine it
+ * implements (Squid V2, shipped 2026-07-23) is three rules:
+ *
+ *   1. FIRST PAINT IS REAL COPY. Never a skeleton, never an empty frame. The
+ *      client starts from SSR `/content` or a required `fallback`.
+ *   2. COPY CHANGES AT MOST ONCE. Text a reader may already be mid-sentence on
+ *      is never wiped and retyped. The stream lands as ONE deliberate rewrite.
+ *   3. TEXT ON THE WIRE IS TEXT WE CAN SHOW. The first CHUNK takes the canvas,
+ *      whatever the `*-start` called itself. The delivery `mode` is no longer
+ *      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.
+ *
+ * The hold is the mechanism that reconciles rules 1 and 2. When the canvas
+ * already shows copy the stream is about to replace, that copy is a FALLBACK,
+ * not a first draft: showing it and then yanking it is worse than briefly
+ * showing the art alone. So the canvas holds blank on the art for a budget —
+ * a budget for the STORED FALLBACK, not for the stream: the fallback is
+ * allowed on screen only once the stream has failed or run out the budget
+ * without delivering. A fast stream types the real copy straight in; a slow
+ * one gets the fallback back, and any later copy arrives as the single
+ * permitted rewrite.
+ *
+ * Reference implementation (the iframe shell, which must stay behaviourally
+ * identical): `mosaic/services/rendererService.ts`, streamInitialCopyCreative.
+ */
+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, once the stream
+ * has proven it is alive.
+ *
+ * Armed against the STREAM, not the mount: the budget is for the connection
+ * that was just opened. The shell's earlier clock started before the transport
+ * had even connected, so on a slow link it expired mid-connect and painted
+ * stored copy that the live copy then overwrote — fallback churn nobody asked
+ * for, and a rule-2 violation caused by the timer meant to protect rule 2.
+ */
+export declare const COPY_HOLD_MS = 2500;
+export interface FieldState {
+    /** What a consumer should render right now. Never a placeholder. */
+    text: string;
+    /** Provenance of `text`. `generated` and `cached` may carry the adaptation
+     * mark, `static` may not — `decideChrome` is the one place that decides. */
+    source: ContentSource;
+    /** Declared delivery mode, once the field has opened. */
+    mode: CopyMode | null;
+    /** True while live deltas are landing — consumers may animate a caret. */
+    typing: boolean;
+    /** `*-done` seen: `text` is final for this stream. */
+    settled: boolean;
+}
+export type Phase = 
+/** Nothing started. */
+"idle"
+/** Canvas is deliberately blank, waiting out the budget. */
+ | "holding"
+/** Live deltas are landing. */
+ | "live"
+/** `done` received. */
+ | "settled"
+/** `error`, or the transport failed. Whatever was painted STAYS painted. */
+ | "failed";
+export interface CreativeState {
+    phase: Phase;
+    fields: Record<CopyField, FieldState>;
+    theme: {
+        colors: Record<string, string>;
+        sources: Record<string, string>;
+    } | null;
+    layout: string | null;
+    experienceManifest: unknown;
+    backgroundImage: string | null;
+    sequence: {
+        frames: string[];
+        heroIndex: number;
+        fps: number;
+    } | null;
+    videoUrl: string | null;
+    ctaStyle: unknown;
+    ctaAction: string | null;
+    /** Terminal `done.meta`, verbatim. */
+    meta: Record<string, unknown> | null;
+    /** Strongest provenance this stream declared. Drives trust chrome. */
+    contentSource: ContentSource;
+    /** W8 — 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;
+    /**
+     * Rewrite counter. 0 = still showing first paint. 1 = the stream's single
+     * permitted rewrite has landed. Anything above 1 is a doctrine violation
+     * and is asserted against in the tests rather than merely hoped for.
+     */
+    rewrites: number;
+}
+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.
+     */
+    initial?: Partial<Record<CopyField, string>>;
+    /**
+     * True when the initial copy has been on screen since the page's own first
+     * paint (SSR, or carried across a client-side navigation) and is therefore
+     * already being read. Such copy is EXEMPT from the hold: blanking text a
+     * reader has had in front of them is the very thing the hold exists to
+     * prevent, so applying the hold to it would invert the rule.
+     */
+    initialIsOnScreen?: boolean;
+    holdMs?: number;
+    /** Injectable for tests; defaults to the platform timers. */
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+}
+type Listener = (state: CreativeState) => void;
+/**
+ * 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.
+ */
+export declare class CopyChoreographer {
+    private readonly options;
+    private state;
+    private listeners;
+    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 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 pending;
+    /** True once the machine has committed a change to the first paint. */
+    private rewriteCommitted;
+    /**
+     * Fields whose on-canvas text is restored fallback a reader can see. Live
+     * deltas must not type over these — they buffer off-canvas and the field
+     * lands ONCE, composed, at its `*-done`. Typing is an entrance for a blank
+     * field, never a treatment for text someone is reading.
+     */
+    private fallbackOnCanvas;
+    /**
+     * 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 disposed;
+    constructor(options?: ChoreographerOptions);
+    getState(): CreativeState;
+    subscribe(listener: Listener): () => void;
+    private emit;
+    private patch;
+    private patchField;
+    private hasInitialCopy;
+    /**
+     * Call when the stream request has been opened.
+     *
+     * Arms the hold if — and only if — there is fallback copy on the canvas that
+     * has NOT already been read. Copy that has been on screen since first paint
+     * stays put: it is not a placeholder, and hiding it would be the mid-read
+     * wipe this whole machine exists to prevent.
+     */
+    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.
+     *
+     * `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.
+     */
+    private isTerminal;
+    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.
+     */
+    private releaseHoldToLive;
+    /** Budget spent with nothing delivered: the fallback comes back, composed. */
+    private restoreHeld;
+    /**
+     * 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.
+     */
+    private commitRewrite;
+    /**
+     * 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 `StreamText` marks on `field.source`, so
+     * leaving it would stamp "adapted for you" on copy nobody adapted.
+     *
+     * The mark must describe what is on screen, not what the server meant to
+     * send. A missing mark on adapted copy under-claims; a mark on authored copy
+     * is a false claim, 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.
+     */
+    private demoteUndeliveredProvenance;
+    /** True once any field on canvas actually carries adapted copy. */
+    private hasAdaptedCopyOnCanvas;
+    /**
+     * 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.
+     */
+    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 restored fallback copy a reader can
+     * see, deltas still buffer off-canvas — that text changes ONCE, composed,
+     * at `*-done`, never delta by delta.
+     */
+    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.
+     */
+    copyDone(field: CopyField, text: string): 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.
+     *
+     * 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.
+     */
+    backgroundReady(bgImage: string): void;
+    sequenceReady(frames: string[], heroIndex: number, fps: number): void;
+    videoReady(videoUrl: string): void;
+    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.
+     */
+    done(meta: Record<string, unknown>): void;
+    /**
+     * The stream failed.
+     *
+     * Whatever is painted STAYS painted. An error is never a reason to blank
+     * copy a reader is mid-sentence on — the worst honest outcome is that the
+     * creative simply stopped adapting, which looks like a normal page.
+     */
+    failed(message: string): void;
+    /** Release timers. Safe to call twice. */
+    dispose(): void;
+    private promoteContentSource;
+}
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAmB,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG/E,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAEjE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAA4C,CAAC;AAEzF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;gFAC4E;IAC5E,MAAM,EAAE,aAAa,CAAC;IACtB,yDAAyD;IACzD,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,KAAK;AACf,uBAAuB;AACrB,MAAM;AACR,4DAA4D;GAC1D,SAAS;AACX,+BAA+B;GAC7B,MAAM;AACR,uBAAuB;GACrB,SAAS;AACX,4EAA4E;GAC1E,QAAQ,CAAC;AAEb,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACtC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrC,sEAAsE;IACtE,aAAa,EAAE,aAAa,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAED,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/C;;;;;;GAMG;AACH,qBAAa,iBAAiB;IA4ChB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA3CpC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IAEvD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAmD;IACnE,OAAO,CAAC,SAAS,CAAiB;IAClC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAS;IAC9B,iEAAiE;IACjE,OAAO,CAAC,OAAO,CAA0C;IACzD,uEAAuE;IACvE,OAAO,CAAC,gBAAgB,CAAS;IACjC;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB,CAAwB;IAChD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAwB;IACtC,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAS;gBAEI,OAAO,GAAE,oBAAyB;IA8B/D,QAAQ,IAAI,aAAa;IAIzB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI;IAKzC,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,cAAc;IAItB;;;;;;;OAOG;IACH,YAAY,IAAI,IAAI;IAiCpB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAWrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;IAOtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,iBAAiB;IA2BzB,8EAA8E;IAC9E,OAAO,CAAC,WAAW;IAiBnB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAMrB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,2BAA2B;IASnC,mEAAmE;IACnE,OAAO,CAAC,sBAAsB;IAQ9B;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAiB/E;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAgB/C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAiB9C,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIjF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI;IAOrD;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAsBtC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIrE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAInC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ7D;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA4DzC;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAkC7B,0CAA0C;IAC1C,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,oBAAoB;CAM7B"}