@sparkletree/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SparkleTree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @sparkletree/core
+
+The framework-agnostic half of the SparkleTree SDK. Wire protocol, copy
+choreography, theme, trust chrome, analytics, variant pinning, audio.
+
+**This is the only thing that speaks the wire.** If you are building a React
+app, install [`@sparkletree/react`](https://www.npmjs.com/package/@sparkletree/react)
+instead — it depends on this. Reach for `core` directly when you are wiring up
+Vue, Svelte, Solid, or plain DOM.
+
+```bash
+npm install @sparkletree/core
+```
+
+## The shortest useful example
+
+```ts
+import { openStream, decideChrome } from "@sparkletree/core";
+
+const handle = openStream({
+  target: {
+    apiBase: "https://your-embed-api.example",
+    organizationId: "org_123",
+    campaignId: "camp_123",
+    island: "hero",
+  },
+  // Required. This is what the visitor reads if the network is slow, the
+  // campaign is paused, or generation fails. Write it as the only version.
+  initial: { headline: "Software that meets the moment" },
+  // True when that copy is ALREADY on screen (SSR, or carried across a
+  // navigation). It changes the choreography: copy a reader can see is never
+  // typed over.
+  initialIsOnScreen: false,
+  onState: (state) => {
+    const { marked } = decideChrome(state.contentSource, false);
+    render(state.fields.headline.text, marked);
+  },
+});
+
+const final = await handle.finished;
+handle.close();
+```
+
+`openStream` returns `{ choreographer, finished, close }`. `choreographer.getState()`
+is the current state; `finished` resolves with the terminal state; `close()`
+aborts the request and releases timers.
+
+## What you get
+
+| Export | |
+|---|---|
+| `openStream` | The client. Opens the SSE stream and drives the choreographer. |
+| `fetchContent` | Fetches `/content`. **Nothing calls it** — `openStream` does not, and the React path does not. Exported for consumers who want a first-paint fetch of their own. |
+| `CopyChoreographer`, `COPY_FIELDS`, `COPY_HOLD_MS` | The state machine, if you want to drive it yourself. |
+| `SseParser`, `readSseStream` | SSE parsing, usable standalone. |
+| `decideChrome`, `viewerPrefersStandard`, `setViewerPrefersStandard`, `STANDARD_MODE_KEY` | Trust chrome decisions. |
+| `applyTheme`, `themeStyle`, `tokenName`, `tokenSource`, `TOKEN_PREFIX` | Theme tokens. |
+| `track`, `ImpressionRecorder`, `observeVisibility`, `sessionId` | Analytics. |
+| `pageVariants`, `VariantRegistry`, `RESERVATION_TIMEOUT_MS` | Variant pinning — one page view, one variant. |
+| `mountAudio`, `activePlayer`, `destroyActiveAudio` | Audio engine (no chrome). |
+| `buildStreamUrl`, `buildContentUrl`, `negotiatedProtocol`, `PROTOCOL_*`, `SDK_PARAM`, `VARIANT_PARAM` | Protocol. |
+
+## Copy state
+
+`state.fields.{greeting,headline,body,cta}` each carry
+`{ text, source, mode, typing, settled }`, already choreographed — you render
+`text` and honour `typing`/`settled` for presentation only. Alongside them:
+`phase`, `error`, `rewrites`, `contentSource`, `degraded`, `variantId`,
+`theme`, `layout`, `backgroundImage`, `videoUrl`, `sequence`, `ctaStyle`,
+`ctaAction`, `meta`.
+
+`phase` moves `idle → holding? → live → settled | failed`. Nothing throws and
+nothing blanks: on `failed`, whatever was painted stays painted and undelivered
+fields fall back to your `initial` text.
+
+## The rules this enforces for you
+
+1. **First paint is real copy.** No skeleton, and no option for one.
+2. **Copy changes at most once.** Text a reader may be mid-sentence on is never
+   wiped and retyped. Deltas aimed at copy already on screen buffer off-canvas
+   and land once, composed.
+3. **The server declares delivery mode**; the client never guesses from timing.
+4. **Adapted copy is marked.** `decideChrome` returns `marked` for `generated`
+   and `cached`, never for `static`. Marking authored copy as adapted is a
+   worse failure than not marking adapted copy.
+
+Full documentation, including the React quickstart and the reasoning behind
+each rule, is in the [SDK README](https://gitlab.com/sparkletree/sparkletree-sdk/-/blob/main/README.md).
+
+## Requirements
+
+ES2022, **ESM only**, Node >= 18. `fetch`, `ReadableStream` and
+`AbortController` must exist — inject `fetchImpl` if you need to substitute
+them. No dependencies.
+
+There is no `require` export condition, which is worth knowing in two places:
+
+- **From CommonJS**, `require("@sparkletree/core")` fails on Node 18 with
+  `ERR_REQUIRE_ESM`. Use `await import("@sparkletree/core")`. (Node 26 loads it
+  either way, so this depends on your runtime, not your code.)
+- **In TypeScript**, `moduleResolution: "bundler"` resolves cleanly. So does
+  `"node16"`/`"nodenext"` *if your own package.json has `"type": "module"`*.
+  Without it you get `TS1479` telling you to use a dynamic import — accurate,
+  not a false positive, and the most likely way a Node backend meets this
+  package.

package/dist/analytics.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Analytics: session, impression, click.
+ *
+ * Impression ownership (plan v1.1 §3.4) is the load-bearing idea. The SDK
+ * renders inside the customer's page, so it is the only party that knows an
+ * impression actually happened — the server knows only that bytes were
+ * requested, which is not the same thing and is spectacularly not the same
+ * thing behind a CDN. So every SDK request carries `sdk=1`, the server
+ * suppresses its own impression, and this module owns the count.
+ *
+ * Which means the rules here are not conveniences, they are the integrity of
+ * CVG:
+ *
+ *   - ONE impression per island per page view. Not per render, not per state
+ *     change, not per React strict-mode double-invoke.
+ *   - VISIBILITY, not mount. A component rendered below the fold, or in a
+ *     background tab, has not been seen.
+ *   - the impression carries what the viewer was actually shown, including
+ *     whether the trust chrome was on.
+ */
+import type { ContentSource } from "./wire.js";
+export type EventType = "impression" | "click" | "conversion" | "custom";
+export interface AnalyticsContext {
+    apiBase: string;
+    organizationId: string;
+    campaignId: string;
+    variantId?: string;
+    surfaceId?: string;
+}
+export interface ImpressionDetail {
+    contentSource: ContentSource;
+    /** Was the adaptation mark rendered? Reported so chrome state is measurable. */
+    chromeMarked: boolean;
+    /** W8 — set when the server served a deterministic winner. */
+    degraded?: string | null;
+    island?: string;
+}
+export declare function sessionId(): string;
+/** POST an event. Fire-and-forget: telemetry never blocks or breaks a render. */
+export declare function track(context: AnalyticsContext, eventType: EventType, eventData?: Record<string, unknown>): Promise<void>;
+/**
+ * Records at most one impression per island per page view.
+ *
+ * The guard is an instance, not a module global, so two islands on one page
+ * each get their own — while a single island being re-rendered, re-subscribed
+ * or double-invoked by React strict mode gets exactly one.
+ */
+export declare class ImpressionRecorder {
+    private readonly context;
+    private fired;
+    constructor(context: AnalyticsContext);
+    get hasFired(): boolean;
+    /** Idempotent. Returns true only for the call that actually recorded. */
+    record(detail: ImpressionDetail): boolean;
+}
+export interface VisibilityOptions {
+    /** Fraction of the element that must be visible. */
+    threshold?: number;
+    /**
+     * How long it must stay that visible before it counts. A creative that
+     * scrolled past during a fling was not seen by anybody.
+     */
+    dwellMs?: number;
+}
+/**
+ * Fire `onVisible` once, when the element has been meaningfully on screen.
+ *
+ * Where IntersectionObserver does not exist, this fires immediately rather
+ * than never: under-counting every impression in older browsers would be a
+ * silent, systematic bias in the numbers a customer is billed and optimised
+ * against. Over-counting there is the lesser wrong, and it is at least
+ * visible.
+ */
+export declare function observeVisibility(element: Element, onVisible: () => void, options?: VisibilityOptions): () => void;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,gFAAgF;IAChF,YAAY,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAgB,SAAS,IAAI,MAAM,CAclC;AAcD,iFAAiF;AACjF,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,SAAS,EACpB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,KAAK,CAAS;gBAEO,OAAO,EAAE,gBAAgB;IAEtD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,yEAAyE;IACzE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;CAW1C;AAED,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,IAAI,EACrB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,IAAI,CA0CZ"}

package/dist/analytics.js

@@ -0,0 +1,170 @@
+/**
+ * Analytics: session, impression, click.
+ *
+ * Impression ownership (plan v1.1 §3.4) is the load-bearing idea. The SDK
+ * renders inside the customer's page, so it is the only party that knows an
+ * impression actually happened — the server knows only that bytes were
+ * requested, which is not the same thing and is spectacularly not the same
+ * thing behind a CDN. So every SDK request carries `sdk=1`, the server
+ * suppresses its own impression, and this module owns the count.
+ *
+ * Which means the rules here are not conveniences, they are the integrity of
+ * CVG:
+ *
+ *   - ONE impression per island per page view. Not per render, not per state
+ *     change, not per React strict-mode double-invoke.
+ *   - VISIBILITY, not mount. A component rendered below the fold, or in a
+ *     background tab, has not been seen.
+ *   - the impression carries what the viewer was actually shown, including
+ *     whether the trust chrome was on.
+ */
+const SESSION_KEY = "st:session";
+/**
+ * Stable per-tab session id.
+ *
+ * sessionStorage, not localStorage: a session is a visit, and a
+ * localStorage-backed id would make one visitor's return look like a
+ * continuation of a visit that ended days ago. Falls back to a memory-only id
+ * where storage is unavailable, which degrades attribution rather than
+ * breaking rendering.
+ */
+let memorySessionId = null;
+export function sessionId() {
+    try {
+        if (typeof sessionStorage !== "undefined") {
+            const existing = sessionStorage.getItem(SESSION_KEY);
+            if (existing)
+                return existing;
+            const created = randomId();
+            sessionStorage.setItem(SESSION_KEY, created);
+            return created;
+        }
+    }
+    catch {
+        // Storage disabled or partitioned — fall through.
+    }
+    memorySessionId ??= randomId();
+    return memorySessionId;
+}
+function randomId() {
+    const globalCrypto = typeof crypto !== "undefined" ? crypto : undefined;
+    if (globalCrypto?.randomUUID)
+        return globalCrypto.randomUUID();
+    if (globalCrypto?.getRandomValues) {
+        const bytes = globalCrypto.getRandomValues(new Uint8Array(16));
+        return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    // Last resort. Only reached in environments with no crypto at all, where
+    // the id's only job is to group one tab's events with each other.
+    return `st-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`;
+}
+/** POST an event. Fire-and-forget: telemetry never blocks or breaks a render. */
+export async function track(context, eventType, eventData = {}) {
+    try {
+        // URL building and serialisation live INSIDE the try: a bad apiBase or an
+        // unserialisable payload (a BigInt, a cycle) throws synchronously, and
+        // callers fire this as `void track(...)` — an escape here is an
+        // unhandled rejection in the customer's page.
+        const url = new URL("/api/embed/v1/track", context.apiBase).toString();
+        const body = JSON.stringify({
+            organizationId: context.organizationId,
+            campaignId: context.campaignId,
+            variantId: context.variantId,
+            surfaceId: context.surfaceId,
+            eventType,
+            eventData: { ...eventData, sessionId: sessionId(), sdk: true },
+        });
+        // keepalive so an impression recorded as the viewer navigates away still
+        // makes it out; without it the last impression of every visit is lost,
+        // which biases CVG toward pages people stayed on.
+        await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            keepalive: true,
+            credentials: "omit",
+        });
+    }
+    catch {
+        // Swallowed on purpose. A failed beacon is a lost data point; a thrown
+        // beacon inside a render tree is a broken customer page.
+    }
+}
+/**
+ * Records at most one impression per island per page view.
+ *
+ * The guard is an instance, not a module global, so two islands on one page
+ * each get their own — while a single island being re-rendered, re-subscribed
+ * or double-invoked by React strict mode gets exactly one.
+ */
+export class ImpressionRecorder {
+    context;
+    fired = false;
+    constructor(context) {
+        this.context = context;
+    }
+    get hasFired() {
+        return this.fired;
+    }
+    /** Idempotent. Returns true only for the call that actually recorded. */
+    record(detail) {
+        if (this.fired)
+            return false;
+        this.fired = true;
+        void track(this.context, "impression", {
+            contentSource: detail.contentSource,
+            chromeMarked: detail.chromeMarked,
+            ...(detail.degraded ? { degraded: detail.degraded } : {}),
+            ...(detail.island ? { island: detail.island } : {}),
+        });
+        return true;
+    }
+}
+/**
+ * Fire `onVisible` once, when the element has been meaningfully on screen.
+ *
+ * Where IntersectionObserver does not exist, this fires immediately rather
+ * than never: under-counting every impression in older browsers would be a
+ * silent, systematic bias in the numbers a customer is billed and optimised
+ * against. Over-counting there is the lesser wrong, and it is at least
+ * visible.
+ */
+export function observeVisibility(element, onVisible, options = {}) {
+    // IntersectionObserver THROWS on a threshold outside [0,1], and this is
+    // caller-supplied — clamping turns a render-tree crash into a slightly
+    // eager or slightly strict impression.
+    const threshold = Math.min(1, Math.max(0, options.threshold ?? 0.5));
+    const dwellMs = options.dwellMs ?? 300;
+    if (typeof IntersectionObserver === "undefined") {
+        onVisible();
+        return () => { };
+    }
+    let dwellTimer = null;
+    let done = false;
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (done)
+                return;
+            if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+                dwellTimer ??= setTimeout(() => {
+                    done = true;
+                    observer.disconnect();
+                    onVisible();
+                }, dwellMs);
+            }
+            else if (dwellTimer) {
+                // Left the viewport before the dwell elapsed: it does not count, and
+                // the clock restarts rather than resuming.
+                clearTimeout(dwellTimer);
+                dwellTimer = null;
+            }
+        }
+    }, { threshold: [0, threshold, 1] });
+    observer.observe(element);
+    return () => {
+        if (dwellTimer)
+            clearTimeout(dwellTimer);
+        observer.disconnect();
+    };
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuBH,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC;;;;;;;;GAQG;AACH,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC;QACH,IAAI,OAAO,cAAc,KAAK,WAAW,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;YACrD,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC;YAC9B,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC;YAC3B,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;IACD,eAAe,KAAK,QAAQ,EAAE,CAAC;IAC/B,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,SAAS,QAAQ;IACf,MAAM,YAAY,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACxE,IAAI,YAAY,EAAE,UAAU;QAAE,OAAO,YAAY,CAAC,UAAU,EAAE,CAAC;IAC/D,IAAI,YAAY,EAAE,eAAe,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,YAAY,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/D,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,yEAAyE;IACzE,kEAAkE;IAClE,OAAO,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AACzF,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,OAAyB,EACzB,SAAoB,EACpB,YAAqC,EAAE;IAEvC,IAAI,CAAC;QACH,0EAA0E;QAC1E,uEAAuE;QACvE,gEAAgE;QAChE,8CAA8C;QAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,qBAAqB,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;QACvE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS;YACT,SAAS,EAAE,EAAE,GAAG,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;SAC/D,CAAC,CAAC;QAEH,yEAAyE;QACzE,uEAAuE;QACvE,kDAAkD;QAClD,MAAM,KAAK,CAAC,GAAG,EAAE;YACf,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI;YACJ,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,yDAAyD;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IAGA;IAFrB,KAAK,GAAG,KAAK,CAAC;IAEtB,YAA6B,OAAyB;QAAzB,YAAO,GAAP,OAAO,CAAkB;IAAG,CAAC;IAE1D,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,MAAwB;QAC7B,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,KAAK,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE;YACrC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpD,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAYD;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAgB,EAChB,SAAqB,EACrB,UAA6B,EAAE;IAE/B,wEAAwE;IACxE,uEAAuE;IACvE,uCAAuC;IACvC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;IAEvC,IAAI,OAAO,oBAAoB,KAAK,WAAW,EAAE,CAAC;QAChD,SAAS,EAAE,CAAC;QACZ,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,UAAU,GAAyC,IAAI,CAAC;IAC5D,IAAI,IAAI,GAAG,KAAK,CAAC;IAEjB,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CACvC,CAAC,OAAO,EAAE,EAAE;QACV,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,iBAAiB,IAAI,SAAS,EAAE,CAAC;gBACjE,UAAU,KAAK,UAAU,CAAC,GAAG,EAAE;oBAC7B,IAAI,GAAG,IAAI,CAAC;oBACZ,QAAQ,CAAC,UAAU,EAAE,CAAC;oBACtB,SAAS,EAAE,CAAC;gBACd,CAAC,EAAE,OAAO,CAAC,CAAC;YACd,CAAC;iBAAM,IAAI,UAAU,EAAE,CAAC;gBACtB,qEAAqE;gBACrE,2CAA2C;gBAC3C,YAAY,CAAC,UAAU,CAAC,CAAC;gBACzB,UAAU,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC,EACD,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CACjC,CAAC;IAEF,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1B,OAAO,GAAG,EAAE;QACV,IAAI,UAAU;YAAE,YAAY,CAAC,UAAU,CAAC,CAAC;QACzC,QAAQ,CAAC,UAAU,EAAE,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC"}

package/dist/audio.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+export type AudioProvider = "suno" | "spotify";
+export interface AudioBlock {
+    provider: AudioProvider;
+    /** Direct media URL (suno) or provider URI (spotify). */
+    audioUrl?: string;
+    trackRef?: string;
+    title?: string;
+    artist?: string;
+    durationMs?: number;
+    loop?: boolean;
+    artwork?: {
+        url: string;
+    };
+}
+export type AudioEvent = "play" | "pause" | "progress" | "complete" | "error" | "ready";
+export interface AudioState {
+    provider: AudioProvider;
+    playing: boolean;
+    positionMs: number;
+    durationMs: number;
+    /** 0..1. Zero when the duration is not yet known — never NaN. */
+    percent: number;
+    /** Wall-clock time this track was actually audible. Drives listen analytics. */
+    listenedMs: number;
+    ended: boolean;
+    errored: boolean;
+}
+export interface AudioCapabilities {
+    /**
+     * May the consumer render its own transport UI? False for providers whose
+     * embed is a fixed iframe we are not permitted to hide or reskin.
+     */
+    customChrome: boolean;
+    /** Does playback work without the viewer holding a provider account? */
+    anonymousPlayback: boolean;
+}
+export interface AudioHandle {
+    provider: AudioProvider;
+    caps: AudioCapabilities;
+    getState(): AudioState;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** No-op on providers that do not expose seeking. */
+    seek(positionMs: number): void;
+    on(event: AudioEvent, listener: (state: AudioState) => void): () => void;
+    destroy(): void;
+}
+/** The currently mounted player, if any. */
+export declare function activePlayer(): AudioHandle | null;
+/**
+ * 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 declare function mountAudio(block: AudioBlock, host: HTMLElement): AudioHandle | null;
+export declare function destroyActiveAudio(): void;
+//# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3B;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;AAExF,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,IAAI,UAAU,CAAC;IACvB,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,qDAAqD;IACrD,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzE,OAAO,IAAI,IAAI,CAAC;CACjB;AAkbD,4CAA4C;AAC5C,wBAAgB,YAAY,IAAI,WAAW,GAAG,IAAI,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAYnF;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC"}