@sparkletree/core 0.1.0

package/dist/audio.js

@@ -0,0 +1,465 @@
+/**
+ * Audio engine — W3, plan v1.1 decision (b): audio is CORE-ONLY.
+ *
+ * `window.__squidAudio` was an inline IIFE in the shell template. Moving it
+ * here makes it versioned and patchable: a provider changes their embed API
+ * and one package bump reaches every consumer, instead of every customer
+ * needing to re-copy a component.
+ *
+ * The accepted trade-off is that consumers cannot customise playback
+ * behaviour without forking. The mitigation is the shape of this module: what
+ * moves into core is the ENGINE — adapters, gesture wiring, the listen clock,
+ * media session — and NOT the chrome. `getState()` and `on()` expose
+ * everything a copied component needs to render its own player UI against an
+ * engine it does not own. Moving the shell's markup in here as well would have
+ * been "just moving the file", and would have made every consumer's player
+ * look like signage.
+ *
+ * Two invariants worth stating because both are load-bearing:
+ *
+ *   - AUTOPLAY IS NEVER USED. Tap to play, always. Autoplaying audio in
+ *     someone else's page is the single fastest way for a customer to remove
+ *     the SDK.
+ *   - ONE PLAYER AT A TIME. Mounting a second destroys the first, so a page
+ *     that cycles variants cannot end up with two tracks over each other.
+ */
+// --- listen clock -------------------------------------------------------------
+/**
+ * Accumulates audible time.
+ *
+ * Capped at ten times the track duration (six hours when the duration is
+ * unknown). A tab left open for a week on a looping track would otherwise
+ * report a listen time that is technically true and analytically useless —
+ * and, since listen time feeds CVG, one such session can dominate a campaign's
+ * engagement numbers on its own.
+ */
+function createListenClock(getDurationMs) {
+    let accumulatedMs = 0;
+    let startedAt = null;
+    const capMs = () => {
+        const total = getDurationMs() || 0;
+        return total > 0 ? total * 10 : 21_600_000;
+    };
+    const fold = () => {
+        if (startedAt === null)
+            return;
+        const now = Date.now();
+        accumulatedMs = Math.min(accumulatedMs + (now - startedAt), capMs());
+        startedAt = now;
+    };
+    return {
+        start: () => {
+            if (startedAt === null)
+                startedAt = Date.now();
+        },
+        stop: () => {
+            fold();
+            startedAt = null;
+        },
+        valueMs: () => {
+            fold();
+            return accumulatedMs;
+        },
+    };
+}
+function createEmitter() {
+    const listeners = new Map();
+    return {
+        on(event, listener) {
+            const set = listeners.get(event) ?? new Set();
+            set.add(listener);
+            listeners.set(event, set);
+            return () => set.delete(listener);
+        },
+        emit(event, state) {
+            for (const listener of listeners.get(event) ?? []) {
+                try {
+                    listener(state);
+                }
+                catch {
+                    // A consumer's listener throwing must not stop playback or the
+                    // other listeners.
+                }
+            }
+        },
+        clear() {
+            listeners.clear();
+        },
+    };
+}
+// --- media session ------------------------------------------------------------
+/**
+ * Publish lock-screen metadata and point the OS transport controls at the
+ * handle (not the raw element), so custom chrome stays in sync with the
+ * Dynamic Island.
+ *
+ * Best-effort throughout: every touch is wrapped, because an OS metadata
+ * failure must never break playback. The Spotify adapter deliberately never
+ * calls this — its iframe owns its own media session, and two sessions fight.
+ */
+function armMediaSession(block, handle) {
+    try {
+        const nav = typeof navigator !== "undefined" ? navigator : undefined;
+        const session = nav?.mediaSession;
+        if (!session || typeof MediaMetadata === "undefined")
+            return;
+        const init = { title: block.title || "" };
+        // Suno ingestion often leaves artist empty — omit rather than pass "",
+        // which renders as a blank line on the lock screen.
+        if (block.artist)
+            init.artist = block.artist;
+        if (block.artwork?.url) {
+            init.artwork = [{ src: block.artwork.url, sizes: "512x512" }];
+        }
+        session.metadata = new MediaMetadata(init);
+        session.setActionHandler("play", () => handle.play());
+        session.setActionHandler("pause", () => handle.pause());
+    }
+    catch {
+        // No media session, or a browser that rejects one of the handlers.
+    }
+}
+function setPlaybackState(state) {
+    try {
+        const nav = typeof navigator !== "undefined" ? navigator : undefined;
+        if (nav?.mediaSession)
+            nav.mediaSession.playbackState = state;
+    }
+    catch {
+        // Best-effort.
+    }
+}
+// --- suno adapter -------------------------------------------------------------
+const PROGRESS_INTERVAL_MS = 500;
+function mountSuno(block, host) {
+    if (!block.audioUrl)
+        return null;
+    const emitter = createEmitter();
+    const audio = document.createElement("audio");
+    audio.preload = "metadata";
+    audio.loop = Boolean(block.loop);
+    audio.src = block.audioUrl;
+    // Hidden: the engine owns playback, the consumer owns the chrome.
+    audio.style.display = "none";
+    host.appendChild(audio);
+    let destroyed = false;
+    let lastProgressAt = 0;
+    const durationMs = () => audio.duration && Number.isFinite(audio.duration)
+        ? audio.duration * 1000
+        : block.durationMs || 0;
+    const positionMs = () => (audio.currentTime || 0) * 1000;
+    const clock = createListenClock(durationMs);
+    const getState = () => {
+        const duration = durationMs();
+        const position = positionMs();
+        return {
+            provider: "suno",
+            playing: !audio.paused && !audio.ended,
+            positionMs: position,
+            durationMs: duration,
+            percent: duration > 0 ? Math.max(0, Math.min(1, position / duration)) : 0,
+            listenedMs: clock.valueMs(),
+            ended: audio.ended,
+            errored: false,
+        };
+    };
+    const handle = {
+        provider: "suno",
+        caps: { customChrome: true, anonymousPlayback: true },
+        getState,
+        play() {
+            try {
+                // play() rejects when the browser blocks it; that is a normal outcome
+                // of a gesture policy, not an error worth surfacing.
+                void audio.play()?.catch(() => { });
+            }
+            catch {
+                /* element torn down */
+            }
+        },
+        pause() {
+            try {
+                audio.pause();
+            }
+            catch {
+                /* element torn down */
+            }
+        },
+        toggle() {
+            if (getState().playing)
+                handle.pause();
+            else
+                handle.play();
+        },
+        seek(target) {
+            try {
+                audio.currentTime = Math.max(0, target) / 1000;
+            }
+            catch {
+                /* not seekable yet */
+            }
+        },
+        on: emitter.on,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            clock.stop();
+            try {
+                audio.pause();
+                audio.removeAttribute("src");
+                audio.load();
+                audio.remove();
+            }
+            catch {
+                /* already gone */
+            }
+            setPlaybackState("none");
+            emitter.clear();
+        },
+    };
+    audio.addEventListener("playing", () => {
+        clock.start();
+        armMediaSession(block, handle);
+        setPlaybackState("playing");
+        emitter.emit("play", getState());
+    });
+    audio.addEventListener("pause", () => {
+        clock.stop();
+        setPlaybackState("paused");
+        emitter.emit("pause", getState());
+    });
+    audio.addEventListener("timeupdate", () => {
+        const now = Date.now();
+        if (now - lastProgressAt < PROGRESS_INTERVAL_MS)
+            return;
+        lastProgressAt = now;
+        emitter.emit("progress", getState());
+    });
+    audio.addEventListener("ended", () => {
+        clock.stop();
+        setPlaybackState("paused");
+        emitter.emit("complete", getState());
+    });
+    audio.addEventListener("error", () => {
+        clock.stop();
+        emitter.emit("error", { ...getState(), errored: true });
+    });
+    audio.addEventListener("loadedmetadata", () => emitter.emit("ready", getState()));
+    return handle;
+}
+const SPOTIFY_API_SRC = "https://open.spotify.com/embed/iframe-api/v1";
+let spotifyApiPromise = null;
+/** Lazy-load the Spotify iFrame API, once per page. */
+function loadSpotifyIframeApi() {
+    if (spotifyApiPromise)
+        return spotifyApiPromise;
+    spotifyApiPromise = new Promise((resolve, reject) => {
+        const global = window;
+        // Chain rather than clobber: this global is THE handoff point for the
+        // iFrame API, so any other Spotify embed on the customer's page registers
+        // the same callback — overwriting it would silently kill their player.
+        const previous = global.onSpotifyIframeApiReady;
+        global.onSpotifyIframeApiReady = (api) => {
+            try {
+                previous?.(api);
+            }
+            catch {
+                // The other embed's handler throwing must not cost us the API.
+            }
+            resolve(api);
+        };
+        const script = document.createElement("script");
+        script.src = SPOTIFY_API_SRC;
+        script.async = true;
+        script.onerror = () => {
+            // Reset so a later mount can retry — a blocked third-party script is
+            // often a transient network or extension condition, and caching the
+            // failure forever would mean audio never recovers in that tab.
+            spotifyApiPromise = null;
+            reject(new Error("SparkleTree: Spotify iFrame API failed to load"));
+        };
+        document.head.appendChild(script);
+    });
+    return spotifyApiPromise;
+}
+function mountSpotify(block, host) {
+    if (!block.trackRef)
+        return null;
+    const emitter = createEmitter();
+    let controller = null;
+    let destroyed = false;
+    let pendingPlay = false;
+    let paused = true;
+    let position = 0;
+    let duration = block.durationMs || 0;
+    let ended = false;
+    let lastProgressAt = 0;
+    const clock = createListenClock(() => duration);
+    const getState = () => ({
+        provider: "spotify",
+        playing: !paused,
+        positionMs: position,
+        durationMs: duration,
+        percent: duration > 0 ? Math.max(0, Math.min(1, position / duration)) : 0,
+        listenedMs: clock.valueMs(),
+        ended,
+        errored: false,
+    });
+    const handle = {
+        provider: "spotify",
+        // The Spotify embed must remain visible and unmodified, so a consumer
+        // cannot legitimately render its own transport over it.
+        caps: { customChrome: false, anonymousPlayback: false },
+        getState,
+        play() {
+            if (!controller) {
+                // Arm rather than drop: a tap before the iframe is ready is the
+                // common case on a cold load, and losing it reads as a dead button.
+                pendingPlay = true;
+                return;
+            }
+            try {
+                controller.play();
+            }
+            catch {
+                /* controller torn down */
+            }
+        },
+        pause() {
+            try {
+                controller?.pause();
+            }
+            catch {
+                /* controller torn down */
+            }
+        },
+        toggle() {
+            if (!paused)
+                handle.pause();
+            else
+                handle.play();
+        },
+        seek(target) {
+            try {
+                controller?.seek(Math.max(0, target) / 1000);
+            }
+            catch {
+                /* not seekable */
+            }
+        },
+        on: emitter.on,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            clock.stop();
+            try {
+                controller?.destroy();
+            }
+            catch {
+                /* already gone */
+            }
+            controller = null;
+            emitter.clear();
+        },
+    };
+    void loadSpotifyIframeApi()
+        .then((api) => {
+        if (destroyed)
+            return;
+        api.createController(host, { uri: block.trackRef, width: "100%", height: 80 }, (ctrl) => {
+            if (destroyed) {
+                try {
+                    ctrl.destroy();
+                }
+                catch {
+                    /* already gone */
+                }
+                return;
+            }
+            controller = ctrl;
+            ctrl.addListener("ready", () => {
+                emitter.emit("ready", getState());
+                if (pendingPlay && !destroyed) {
+                    pendingPlay = false;
+                    try {
+                        ctrl.play();
+                    }
+                    catch {
+                        /* controller torn down */
+                    }
+                }
+            });
+            // Spotify has no play/pause/ended events — everything is derived from
+            // playback_update transitions.
+            ctrl.addListener("playback_update", (event) => {
+                const data = event?.data ?? {};
+                if (typeof data.position === "number")
+                    position = data.position;
+                if (typeof data.duration === "number" && data.duration > 0)
+                    duration = data.duration;
+                const nowPaused = Boolean(data.isPaused);
+                if (!nowPaused && paused) {
+                    paused = false;
+                    ended = false;
+                    clock.start();
+                    emitter.emit("play", getState());
+                }
+                else if (nowPaused && !paused) {
+                    paused = true;
+                    clock.stop();
+                    // Within half a second of the end counts as completion: the
+                    // provider stops reporting before position reaches duration
+                    // exactly, so an equality test would never fire.
+                    if (duration > 0 && position >= duration - 500) {
+                        ended = true;
+                        emitter.emit("complete", getState());
+                    }
+                    else {
+                        emitter.emit("pause", getState());
+                    }
+                }
+                const now = Date.now();
+                if (now - lastProgressAt >= PROGRESS_INTERVAL_MS) {
+                    lastProgressAt = now;
+                    emitter.emit("progress", getState());
+                }
+            });
+        });
+    })
+        .catch(() => {
+        emitter.emit("error", { ...getState(), errored: true });
+    });
+    return handle;
+}
+// --- single-player registry ---------------------------------------------------
+let activeHandle = null;
+/** The currently mounted player, if any. */
+export function activePlayer() {
+    return activeHandle;
+}
+/**
+ * Mount a player for `block` inside `host`.
+ *
+ * Destroys any existing player first — the single-player invariant. A page
+ * cycling variants would otherwise stack tracks on top of each other, and the
+ * viewer has no way to stop one they can no longer see.
+ */
+export function mountAudio(block, host) {
+    destroyActiveAudio();
+    const handle = block.provider === "suno"
+        ? mountSuno(block, host)
+        : block.provider === "spotify"
+            ? mountSpotify(block, host)
+            : null;
+    activeHandle = handle;
+    return handle;
+}
+export function destroyActiveAudio() {
+    if (!activeHandle)
+        return;
+    activeHandle.destroy();
+    activeHandle = null;
+}
+//# sourceMappingURL=audio.js.map

package/dist/audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.js","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The client: fetch `/content` for first paint, then open the stream and feed
+ * every event into the choreographer.
+ *
+ * The event dispatch below is the ONLY place in the SDK that knows event
+ * names, and every name it knows comes from the generated contract. A server
+ * that starts emitting something newer than this build is not an error — it is
+ * an older client, which the protocol explicitly supports — so unknown events
+ * are ignored rather than warned about.
+ */
+import { type StreamTarget } from "./protocol.js";
+import { CopyChoreographer, type ChoreographerOptions, type CreativeState } from "./state.js";
+export interface ContentSnapshot {
+    campaignId: string;
+    variantId: string;
+    content: {
+        headline?: string;
+        body?: string;
+        cta?: string | {
+            text?: string;
+        };
+        image?: string;
+        experienceManifest?: unknown;
+    };
+    theme?: {
+        colors: Record<string, string>;
+        sources: Record<string, string>;
+    };
+    products?: unknown[];
+    meta?: Record<string, unknown>;
+}
+export interface StreamOptions extends ChoreographerOptions {
+    target: StreamTarget;
+    signal?: AbortSignal;
+    /** Swap the transport (SSR, tests, a customer's instrumented fetch). */
+    fetchImpl?: typeof fetch;
+    /** Called on every state change. */
+    onState?: (state: CreativeState) => void;
+    /**
+     * Called when the server cannot speak the version this build requested. The
+     * SDK has already kept its own first paint by the time this fires; the hook
+     * exists so a consumer can log it once, not so it can retry.
+     */
+    onProtocolUnsupported?: (info: {
+        requested: number;
+        supported: number[];
+    }) => void;
+}
+export interface StreamHandle {
+    /** The live choreographer. Subscribe for updates. */
+    choreographer: CopyChoreographer;
+    /** Resolves when the stream ends, however it ends. Never rejects. */
+    finished: Promise<CreativeState>;
+    /** Stop early. Idempotent. */
+    close: () => void;
+}
+/**
+ * Fetch the first-paint content.
+ *
+ * Content-first, rewrite-once: this is what the SDK paints BEFORE any stream
+ * exists, so there is never a skeleton on screen. If it fails, the consumer's
+ * `fallback` prop is what stands in — which is why that prop is required
+ * rather than optional.
+ */
+export declare function fetchContent(target: StreamTarget, options?: {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}): Promise<ContentSnapshot | null>;
+/**
+ * Open an island stream and choreograph it.
+ *
+ * Returns immediately with a handle; `finished` resolves with the terminal
+ * state. It never rejects — a broken stream leaves whatever was painted on
+ * screen and reports `phase: "failed"`, because throwing from inside a
+ * customer's render tree is a worse outcome than a creative that stopped
+ * adapting.
+ */
+export declare function openStream(options: StreamOptions): StreamHandle;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iBAAiB,EACjB,KAAK,oBAAoB,EAEzB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,GAAG;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACjC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,CAAC;IACF,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAc,SAAQ,oBAAoB;IACzD,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;CACpF;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,aAAa,EAAE,iBAAiB,CAAC;IACjC,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,8BAA8B;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAwBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAC/D,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAwBjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAwG/D"}