@sparkletree/core 0.1.0

package/dist/fragments.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Fragments — the core client for Declarative Context rung 2 (spec §2.3/§4.3).
+ *
+ * The keys and fallback strings the developer writes ARE the request schema:
+ * there is nothing to create in a dashboard before the first render. The flow
+ * is fixed and deliberately boring:
+ *
+ *   1. The caller's fallbacks are the result shape, synchronously computable.
+ *   2. ctxhash + schemahash are computed locally (declared dims ONLY — env
+ *      signals never enter the fragment identity, so cardinality stays "the
+ *      number of call sites in the org's source").
+ *   3. One cacheable GET. Warm hit → serve those fields; anything else → the
+ *      fallbacks stand.
+ *   4. On a miss with `pending: true`, ONE fire-and-forget POST /mint,
+ *      deduplicated per session. No second GET, no polling, no SSE — twenty
+ *      tokens do not need choreography.
+ *
+ * `fetchFragments` NEVER rejects. Any failure — network, malformed body,
+ * hashing, a hostile response — resolves to fallback-shaped fields with
+ * source "static". The developer's copy is the floor.
+ */
+import { type DeclaredContext } from "./context.js";
+import type { FieldState } from "./state.js";
+import type { ContentSource, FragmentKind, FragmentWarmth } from "./wire.js";
+/** Bare-string shorthand: `"Sign in"` means `{ kind: "body", fallback: "Sign in" }`. */
+export type FragmentFieldSpec = string | {
+    kind?: FragmentKind;
+    fallback: string;
+};
+/**
+ * A signed mint token, or a function producing one.
+ *
+ * The token is minted by the CUSTOMER'S BACKEND (POST /fragments/mint-token
+ * with an org-pinned `st_` key) and is bound to one (org, ctxhash, schemahash)
+ * for 300 seconds. The browser only echoes it. The callback form exists
+ * because of that TTL: a page open longer than five minutes needs a fresh
+ * token at mint time, not the one that shipped with the HTML.
+ */
+export type MintTokenSource = string | (() => string | null | undefined | Promise<string | null | undefined>);
+export interface FetchFragmentsOptions {
+    organizationId: string;
+    apiBase: string;
+    context?: DeclaredContext;
+    fields: Record<string, FragmentFieldSpec>;
+    /** Sent on the mint POST only — never on the GET, which is a shared CDN
+     * object and must be byte-identical for every caller. Optional: without it
+     * the mint goes unsigned and the server admits it or not. */
+    mintToken?: MintTokenSource;
+    /** Where `apiBase` came from. The publishable key is an unsigned address
+     * anyone can hand-encode, so a key-derived apiBase earns content fetches
+     * but NOT the mint POST (which carries the signed token — a real spend
+     * credential — and the declared dims) unless the host is first-party or
+     * loopback (S-2). Defaults to "explicit": a caller passing apiBase
+     * directly has chosen it themselves. */
+    apiBaseProvenance?: "explicit" | "key";
+    /** Test seam; defaults to the platform fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface FragmentsResult {
+    /** One FieldState per requested key — the exact shape islands produce. */
+    fields: Record<string, FieldState>;
+    /** Locally computed declared-context hash. Third leg of the pin key. */
+    contextHash: string;
+    warmth: FragmentWarmth;
+    /** decideChrome over the strongest served provenance (cached counts as
+     * adapted). The group-level Art. 50 disclosure hangs off this. */
+    marked: boolean;
+}
+/** The normalized request schema: what /mint receives, what schemahash covers. */
+export interface NormalizedFragmentField {
+    key: string;
+    kind: FragmentKind;
+    budget: number;
+    fallback: string;
+}
+/** Expand shorthands and derive budgets. Deterministic: same fields object →
+ * same schema → same schemahash. */
+export declare function normalizeFieldSpecs(fields: Record<string, FragmentFieldSpec>): NormalizedFragmentField[];
+/** Strongest provenance across a set of field states (static < cached < generated). */
+export declare function strongestFragmentSource(fields: Iterable<FieldState>): ContentSource;
+/**
+ * Resolve fragments for a declared context. Resolves fast; NEVER rejects;
+ * fallback-shaped on any failure.
+ */
+export declare function fetchFragments(options: FetchFragmentsOptions): Promise<FragmentsResult>;
+export interface CreateClientOptions {
+    /** `st_pk_…` from the dashboard. An address, not a credential (see
+     * publishableKey.ts) — explicit organizationId/apiBase win over it. */
+    publishableKey?: string;
+    organizationId?: string;
+    apiBase?: string;
+    /** Signed mint token (or a function returning one), sent on the mint POST. */
+    mintToken?: MintTokenSource;
+    fetchImpl?: typeof fetch;
+}
+export interface SparkletreeClient {
+    fragments(options: {
+        context?: DeclaredContext;
+        fields: Record<string, FragmentFieldSpec>;
+    }): Promise<FragmentsResult>;
+}
+/**
+ * Vanilla entry point, in core where the wire lives. Throws TypeError on a
+ * malformed key or missing configuration — setup errors surface at setup
+ * time; only the resolved `fragments()` call is the never-rejects path.
+ */
+export declare function createClient(options: CreateClientOptions): SparkletreeClient;
+//# sourceMappingURL=fragments.d.ts.map

package/dist/fragments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.d.ts","sourceRoot":"","sources":["../src/fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EAEf,MAAM,WAAW,CAAC;AAEnB,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;AAE3E,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1C;;iEAE6D;IAC7D,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;4CAKwC;IACxC,iBAAiB,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC;IACvC,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB;sEACkE;IAClE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD;oCACoC;AACpC,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACxC,uBAAuB,EAAE,CAU3B;AAED,uFAAuF;AACvF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAMnF;AAqFD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA+D7F;AAID,MAAM,WAAW,mBAAmB;IAClC;2EACuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,OAAO,EAAE;QACjB,OAAO,CAAC,EAAE,eAAe,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;KAC3C,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CA+B5E"}

package/dist/fragments.js

@@ -0,0 +1,223 @@
+/**
+ * Fragments — the core client for Declarative Context rung 2 (spec §2.3/§4.3).
+ *
+ * The keys and fallback strings the developer writes ARE the request schema:
+ * there is nothing to create in a dashboard before the first render. The flow
+ * is fixed and deliberately boring:
+ *
+ *   1. The caller's fallbacks are the result shape, synchronously computable.
+ *   2. ctxhash + schemahash are computed locally (declared dims ONLY — env
+ *      signals never enter the fragment identity, so cardinality stays "the
+ *      number of call sites in the org's source").
+ *   3. One cacheable GET. Warm hit → serve those fields; anything else → the
+ *      fallbacks stand.
+ *   4. On a miss with `pending: true`, ONE fire-and-forget POST /mint,
+ *      deduplicated per session. No second GET, no polling, no SSE — twenty
+ *      tokens do not need choreography.
+ *
+ * `fetchFragments` NEVER rejects. Any failure — network, malformed body,
+ * hashing, a hostile response — resolves to fallback-shaped fields with
+ * source "static". The developer's copy is the floor.
+ */
+import { computeFieldBudget, computeSchemaHash, declaredToDims, hashDeclaredContext, } from "./context.js";
+import { decodePublishableKey } from "./publishableKey.js";
+import { isFirstPartyApiBase, isSecureApiBase } from "./safeUrl.js";
+import { decideChrome } from "./trust.js";
+import { FRAGMENT_KINDS, FRAGMENT_WARMTHS } from "./wire.js";
+const VALID_SOURCES = new Set(["generated", "cached", "static"]);
+const SOURCE_RANK = { static: 0, cached: 1, generated: 2 };
+/** Expand shorthands and derive budgets. Deterministic: same fields object →
+ * same schema → same schemahash. */
+export function normalizeFieldSpecs(fields) {
+    return Object.entries(fields).map(([key, spec]) => {
+        const expanded = typeof spec === "string" ? { fallback: spec } : spec;
+        const kind = expanded.kind && FRAGMENT_KINDS.includes(expanded.kind)
+            ? expanded.kind
+            : "body";
+        const fallback = expanded.fallback ?? "";
+        return { key, kind, budget: computeFieldBudget(fallback, kind), fallback };
+    });
+}
+/** Strongest provenance across a set of field states (static < cached < generated). */
+export function strongestFragmentSource(fields) {
+    let strongest = "static";
+    for (const field of fields) {
+        if (SOURCE_RANK[field.source] > SOURCE_RANK[strongest])
+            strongest = field.source;
+    }
+    return strongest;
+}
+/** FieldState for fragment copy. Fragments never type: text is set once,
+ * settled, with no caret — the single rewrite, not choreography. */
+function fragmentField(text, source) {
+    return { text, source, mode: null, typing: false, settled: true };
+}
+function fallbackFields(schema) {
+    return Object.fromEntries(schema.map((f) => [f.key, fragmentField(f.fallback, "static")]));
+}
+/** The header the mint POST echoes the signed token on. */
+const MINT_TOKEN_HEADER = "x-st-mint-token";
+/**
+ * Resolve a mint token to a header-ready string, or "" for "send no header".
+ *
+ * Defensive on purpose: the callback reaches into the host app's auth code,
+ * and a token endpoint that is down, slow or throwing must cost a mint at
+ * worst — never a render. The server decides admission; an unsigned mint is a
+ * refusal it can make cheaply, and the fallback copy already shipped.
+ */
+async function resolveMintToken(source) {
+    try {
+        const value = typeof source === "function" ? await source() : source;
+        return typeof value === "string" ? value.trim() : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Fire the one permitted mint for this (ctxhash, schemahash), deduplicated in
+ * sessionStorage. Outside a browser there is no page view to warm — skip
+ * entirely. In a privacy mode where sessionStorage throws, the POST still
+ * fires once per call; the server's queue dedup (SET NX) absorbs repeats.
+ */
+function maybeMint(options, schema, contextHash, schemaHash) {
+    if (typeof window === "undefined")
+        return;
+    // S-2: a key-derived apiBase is an address anyone can hand-encode. The mint
+    // POST carries the signed token (a spend credential) and the declared dims,
+    // so it only follows an apiBase the developer chose explicitly, or one
+    // provably first-party/loopback. Withheld, fragments simply stay cold —
+    // the fallback already shipped, and nothing leaks.
+    if (options.apiBaseProvenance === "key" && !isFirstPartyApiBase(options.apiBase))
+        return;
+    const dedupKey = `st:frag:mint:${contextHash}:${schemaHash}`;
+    try {
+        if (window.sessionStorage.getItem(dedupKey) === "1")
+            return;
+        window.sessionStorage.setItem(dedupKey, "1");
+    }
+    catch {
+        // SSR shims and private modes may throw on ACCESS; dedup is best-effort.
+    }
+    const doFetch = options.fetchImpl ?? fetch;
+    const url = new URL("/api/embed/v1/fragments/mint", options.apiBase);
+    // Fire-and-forget: the response is ignored except in dev, and a failed mint
+    // is indistinguishable from a cold cache — the fallback already shipped.
+    void Promise.resolve()
+        .then(async () => {
+        const token = await resolveMintToken(options.mintToken);
+        return doFetch(url.toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                // Absent, not empty: a blank token is a PRESENT-but-bad token to the
+                // server, which refuses outright rather than falling back to Origin.
+                ...(token ? { [MINT_TOKEN_HEADER]: token } : {}),
+            },
+            body: JSON.stringify({
+                organization: options.organizationId,
+                // Declared dims only, short-keyed — the server re-canonicalizes and
+                // recomputes both hashes; ours are cache hints, never identity.
+                context: declaredToDims(options.context ?? {}),
+                schema,
+            }),
+        });
+    })
+        .catch(() => { });
+}
+/**
+ * Resolve fragments for a declared context. Resolves fast; NEVER rejects;
+ * fallback-shaped on any failure.
+ */
+export async function fetchFragments(options) {
+    const schema = normalizeFieldSpecs(options.fields);
+    // Same apiBase rule as openStream/fetchContent: this path is reached
+    // directly by the React bindings, which never go through createClient —
+    // without the guard here, an http: apiBase would carry context and the
+    // mint token over plaintext from the flagship integration path.
+    if (!isSecureApiBase(options.apiBase)) {
+        return { fields: fallbackFields(schema), contextHash: "", warmth: "cold", marked: false };
+    }
+    let contextHash = "";
+    try {
+        const [context, schemaHash] = await Promise.all([
+            hashDeclaredContext(options.context ?? {}),
+            computeSchemaHash(schema),
+        ]);
+        contextHash = context.hash;
+        const url = new URL("/api/embed/v1/fragments", options.apiBase);
+        // Identity only — no prose, no SDK params: this URL is a shared CDN
+        // object and every extra param would fragment the cache.
+        url.searchParams.set("o", options.organizationId);
+        url.searchParams.set("c", contextHash);
+        url.searchParams.set("s", schemaHash);
+        const doFetch = options.fetchImpl ?? fetch;
+        const response = await doFetch(url.toString());
+        if (!response.ok) {
+            return { fields: fallbackFields(schema), contextHash, warmth: "cold", marked: false };
+        }
+        const body = (await response.json());
+        const served = body && typeof body === "object" && body.fragments && typeof body.fragments === "object"
+            ? body.fragments
+            : {};
+        // Only keys we asked for, only shapes we recognize; everything else —
+        // extras, missing keys, unknown provenance — is the fallback. A response
+        // is a suggestion; the schema is the contract.
+        const fields = {};
+        for (const field of schema) {
+            const candidate = served[field.key];
+            fields[field.key] =
+                candidate &&
+                    typeof candidate.text === "string" &&
+                    candidate.text !== "" &&
+                    VALID_SOURCES.has(candidate.source)
+                    ? fragmentField(candidate.text, candidate.source)
+                    : fragmentField(field.fallback, "static");
+        }
+        const warmth = body?.warmth && FRAGMENT_WARMTHS.includes(body.warmth)
+            ? body.warmth
+            : "cold";
+        if (body?.pending === true)
+            maybeMint(options, schema, contextHash, schemaHash);
+        // Core has no viewer preference to consult; the React layer re-decides
+        // with `prefersStandard`. This is the provenance-honest default.
+        const marked = decideChrome(strongestFragmentSource(Object.values(fields)), false).marked;
+        return { fields, contextHash, warmth, marked };
+    }
+    catch {
+        return { fields: fallbackFields(schema), contextHash, warmth: "cold", marked: false };
+    }
+}
+/**
+ * Vanilla entry point, in core where the wire lives. Throws TypeError on a
+ * malformed key or missing configuration — setup errors surface at setup
+ * time; only the resolved `fragments()` call is the never-rejects path.
+ */
+export function createClient(options) {
+    const decoded = options.publishableKey ? decodePublishableKey(options.publishableKey) : null;
+    const organizationId = options.organizationId ?? decoded?.organizationId;
+    const apiBase = options.apiBase ?? decoded?.apiBase;
+    if (!organizationId || !apiBase) {
+        throw new TypeError("SparkleTree: createClient needs a publishableKey, or organizationId + apiBase.");
+    }
+    // Setup errors surface at setup time: an apiBase that is neither https nor
+    // loopback http would send org configuration over a channel any middlebox
+    // can rewrite. Refuse here, where a throw is the package's documented
+    // contract for misconfiguration, rather than per-request.
+    if (!isSecureApiBase(apiBase)) {
+        throw new TypeError("SparkleTree: createClient apiBase must be https (http is allowed for localhost only).");
+    }
+    return {
+        fragments: (callOptions) => fetchFragments({
+            organizationId,
+            apiBase,
+            // An explicit apiBase is the developer's own choice; a key-derived
+            // one is an unsigned address and earns no mint (see maybeMint, S-2).
+            apiBaseProvenance: options.apiBase ? "explicit" : "key",
+            mintToken: options.mintToken,
+            fetchImpl: options.fetchImpl,
+            ...callOptions,
+        }),
+    };
+}
+//# sourceMappingURL=fragments.js.map

package/dist/fragments.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @sparkletree/core — the framework-agnostic half of the SparkleTree SDK.
+ *
+ * Everything that touches the wire lives here, and ONLY here. Components
+ * distributed by `sparkletree add` are copied into a customer's repo and are
+ * therefore un-patchable by us; they must stay wire-ignorant, rendering state
+ * this package hands them. That split is what lets a protocol change ship as a
+ * version bump instead of a migration guide.
+ *
+ * Wire types are re-exported so consumers never import the generated contract
+ * directly — that path is an implementation detail and would make the
+ * generated artifacts part of the public API.
+ */
+export type { ContentSource, CopyMode, DegradeReason, DoneMeta, FragmentField, FragmentKind, FragmentWarmth, FragmentsResponse, ThemePayload, WireEventName, } from "./wire.js";
+export { FRAGMENT_KINDS, FRAGMENT_WARMTHS } from "./wire.js";
+export { PROTOCOL_CURRENT, PROTOCOL_DEFAULT, PROTOCOL_HEADER, PROTOCOL_PARAM, PROTOCOL_VERSIONS, SDK_PARAM, SDK_PARAM_VALUE, VARIANT_PARAM, buildContentUrl, buildStreamUrl, negotiatedProtocol, type StreamTarget, } from "./protocol.js";
+export { SseParser, readSseStream, type SseMessage } from "./sse.js";
+export { isFirstPartyApiBase, isSecureApiBase, safeActionUrl } from "./safeUrl.js";
+export { CONTEXT_DAYPARTS, CONTEXT_DAY_TYPES, CONTEXT_DEVICES, CONTEXT_INTENTS, CONTEXT_SURFACE_TYPES, CONTEXT_TEMP_BANDS, CONTEXT_WEATHER, FRAGMENT_KIND_FLOORS, MAX_CUSTOM_DIMS, MAX_NOTES_LENGTH, canonicalContextString, computeContextHash, computeFieldBudget, computeSchemaHash, declaredToDims, hashDeclaredContext, normalizeDims, normalizeNotes, type CanonicalDims, type DeclaredContext, type NormalizeResult, } from "./context.js";
+export { COPY_FIELDS, COPY_HOLD_MS, CopyChoreographer, type ChoreographerOptions, type CopyField, type CreativeState, type FieldState, type Phase, } from "./state.js";
+export { fetchContent, openStream, type ContentSnapshot, type StreamHandle, type StreamOptions, } from "./client.js";
+export { TOKEN_PREFIX, applyTheme, themeStyle, tokenName, tokenSource, type ResolvedTheme, } from "./theme.js";
+export { STANDARD_MODE_KEY, decideChrome, setViewerPrefersStandard, viewerPrefersStandard, type ChromeDecision, } from "./trust.js";
+export { ImpressionRecorder, observeVisibility, sessionId, track, type AnalyticsContext, type EventType, type ImpressionDetail, type VisibilityOptions, } from "./analytics.js";
+export { RESERVATION_TIMEOUT_MS, VariantRegistry, pageVariants, type FollowerReservation, type LeaderReservation, type VariantReservation, } from "./variant.js";
+export { activePlayer, destroyActiveAudio, mountAudio, type AudioBlock, type AudioCapabilities, type AudioEvent, type AudioHandle, type AudioProvider, type AudioState, } from "./audio.js";
+export { plainText } from "./text.js";
+export { readableTextColor } from "./theme.js";
+export { decodePublishableKey, encodePublishableKey, type PublishableKeyEnv, type PublishableKeyPayload, } from "./publishableKey.js";
+export { createClient, fetchFragments, normalizeFieldSpecs, strongestFragmentSource, type CreateClientOptions, type FetchFragmentsOptions, type FragmentFieldSpec, type FragmentsResult, type MintTokenSource, type NormalizedFragmentField, type SparkletreeClient, } from "./fragments.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * @sparkletree/core — the framework-agnostic half of the SparkleTree SDK.
+ *
+ * Everything that touches the wire lives here, and ONLY here. Components
+ * distributed by `sparkletree add` are copied into a customer's repo and are
+ * therefore un-patchable by us; they must stay wire-ignorant, rendering state
+ * this package hands them. That split is what lets a protocol change ship as a
+ * version bump instead of a migration guide.
+ *
+ * Wire types are re-exported so consumers never import the generated contract
+ * directly — that path is an implementation detail and would make the
+ * generated artifacts part of the public API.
+ */
+export { FRAGMENT_KINDS, FRAGMENT_WARMTHS } from "./wire.js";
+export { PROTOCOL_CURRENT, PROTOCOL_DEFAULT, PROTOCOL_HEADER, PROTOCOL_PARAM, PROTOCOL_VERSIONS, SDK_PARAM, SDK_PARAM_VALUE, VARIANT_PARAM, buildContentUrl, buildStreamUrl, negotiatedProtocol, } from "./protocol.js";
+export { SseParser, readSseStream } from "./sse.js";
+export { isFirstPartyApiBase, isSecureApiBase, safeActionUrl } from "./safeUrl.js";
+export { CONTEXT_DAYPARTS, CONTEXT_DAY_TYPES, CONTEXT_DEVICES, CONTEXT_INTENTS, CONTEXT_SURFACE_TYPES, CONTEXT_TEMP_BANDS, CONTEXT_WEATHER, FRAGMENT_KIND_FLOORS, MAX_CUSTOM_DIMS, MAX_NOTES_LENGTH, canonicalContextString, computeContextHash, computeFieldBudget, computeSchemaHash, declaredToDims, hashDeclaredContext, normalizeDims, normalizeNotes, } from "./context.js";
+export { COPY_FIELDS, COPY_HOLD_MS, CopyChoreographer, } from "./state.js";
+export { fetchContent, openStream, } from "./client.js";
+export { TOKEN_PREFIX, applyTheme, themeStyle, tokenName, tokenSource, } from "./theme.js";
+export { STANDARD_MODE_KEY, decideChrome, setViewerPrefersStandard, viewerPrefersStandard, } from "./trust.js";
+export { ImpressionRecorder, observeVisibility, sessionId, track, } from "./analytics.js";
+export { RESERVATION_TIMEOUT_MS, VariantRegistry, pageVariants, } from "./variant.js";
+export { activePlayer, destroyActiveAudio, mountAudio, } from "./audio.js";
+export { plainText } from "./text.js";
+export { readableTextColor } from "./theme.js";
+export { decodePublishableKey, encodePublishableKey, } from "./publishableKey.js";
+export { createClient, fetchFragments, normalizeFieldSpecs, strongestFragmentSource, } from "./fragments.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,EACd,kBAAkB,GAEnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAmB,MAAM,UAAU,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,cAAc,GAIf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,iBAAiB,GAMlB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,UAAU,GAIX,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,GAEZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,qBAAqB,GAEtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,EACT,KAAK,GAKN,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,YAAY,GAIb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,UAAU,GAOX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,uBAAuB,GAQxB,MAAM,gBAAgB,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Protocol surface: what the SDK asks for, and what it does when the server
+ * cannot give it.
+ *
+ * Everything here is generated from `shared/sparkletree/wire/contract.ts`, so
+ * the constants below cannot drift from the Go edge or the Next twin. What
+ * this file adds is the CLIENT half of the handshake, which the contract
+ * describes but does not implement.
+ */
+import { PROTOCOL_CURRENT, PROTOCOL_DEFAULT, PROTOCOL_HEADER, PROTOCOL_PARAM, PROTOCOL_RESPONSE_HEADER, PROTOCOL_VERSIONS, SDK_PARAM, SDK_PARAM_VALUE, VARIANT_PARAM } from "./wire.js";
+export { PROTOCOL_CURRENT, PROTOCOL_DEFAULT, PROTOCOL_HEADER, PROTOCOL_PARAM, PROTOCOL_RESPONSE_HEADER, PROTOCOL_VERSIONS, SDK_PARAM, SDK_PARAM_VALUE, VARIANT_PARAM, };
+/** Everything needed to address one island stream. */
+export interface StreamTarget {
+    /** Base URL of the embed API, e.g. `https://api.sparkletree.io`. */
+    apiBase: string;
+    organizationId: string;
+    campaignId?: string;
+    surfaceId?: string;
+    island: "hero" | "cta";
+    /**
+     * Variant pinning (plan v1.1 §3.3). The provider resolves the variant ONCE
+     * per page view and pins it here for every later call. Without it, ε-greedy
+     * runs per request and a single page shows a mixed-variant creative — hero
+     * from one arm, CTA from another — which is not an experiment, it is noise.
+     */
+    variantId?: string;
+    /** Context snapshot (time, geo, weather, device). Serialised as JSON. */
+    context?: Record<string, unknown>;
+    /** Conversation session id for copy continuity. Individual surfaces only. */
+    sessionId?: string;
+    /** Extra params passed through verbatim (preview tokens, etc.). */
+    extra?: Record<string, string | undefined>;
+}
+/**
+ * Build the stream URL.
+ *
+ * `sdk=1` is not optional and not a feature flag: it tells the server to
+ * suppress its own server-side impression for this request. The SDK renders
+ * inside the customer's page, so it is the only party that knows whether the
+ * creative was ever actually on screen — and a server-side impression on top
+ * of the client's own would double-count every view, and would keep counting
+ * from a CDN-cached SSR response that no human ever saw.
+ */
+export declare function buildStreamUrl(target: StreamTarget, protocol?: number): string;
+/**
+ * Build the `/content` URL used for first paint. Same pinning rules as the
+ * stream — but deliberately NOT the same `sdk=1` rule.
+ *
+ * `sdk=1` is a promise: "the SDK will record this impression itself". The
+ * stream path keeps that promise — `useIsland` owns a visibility-gated
+ * recorder. The content path CANNOT: its consumers (CopyCard, ProductCard,
+ * the cookbook's content-only recipes) have no observer and no recorder, so
+ * sending `sdk=1` here told the server to stop counting while nobody else
+ * started — zero impressions for every content-only integration. Omitting it
+ * leaves the server owning the `/content` impression, exactly as it does for
+ * every non-SDK consumer of the endpoint.
+ */
+export declare function buildContentUrl(target: StreamTarget, protocol?: number): string;
+/**
+ * Read the negotiated version off a response.
+ *
+ * An absent header means an older deployment that predates negotiation, which
+ * by contract is protocol 1 — not an error, and specifically not a reason to
+ * refuse the stream. Treating silence as failure here would break every
+ * customer whose traffic happens to land on an edge revision mid-rollout.
+ */
+export declare function negotiatedProtocol(response: {
+    headers: Headers;
+}): number;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,aAAa,EACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,aAAa,GACd,CAAC;AAEF,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAyB,GAAG,MAAM,CAoBhG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAyB,GAAG,MAAM,CAkBjG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAKzE"}

package/dist/protocol.js

@@ -0,0 +1,97 @@
+/**
+ * Protocol surface: what the SDK asks for, and what it does when the server
+ * cannot give it.
+ *
+ * Everything here is generated from `shared/sparkletree/wire/contract.ts`, so
+ * the constants below cannot drift from the Go edge or the Next twin. What
+ * this file adds is the CLIENT half of the handshake, which the contract
+ * describes but does not implement.
+ */
+import { PROTOCOL_CURRENT, PROTOCOL_DEFAULT, PROTOCOL_HEADER, PROTOCOL_PARAM, PROTOCOL_RESPONSE_HEADER, PROTOCOL_VERSIONS, SDK_PARAM, SDK_PARAM_VALUE, VARIANT_PARAM, } from "./wire.js";
+export { PROTOCOL_CURRENT, PROTOCOL_DEFAULT, PROTOCOL_HEADER, PROTOCOL_PARAM, PROTOCOL_RESPONSE_HEADER, PROTOCOL_VERSIONS, SDK_PARAM, SDK_PARAM_VALUE, VARIANT_PARAM, };
+/**
+ * Build the stream URL.
+ *
+ * `sdk=1` is not optional and not a feature flag: it tells the server to
+ * suppress its own server-side impression for this request. The SDK renders
+ * inside the customer's page, so it is the only party that knows whether the
+ * creative was ever actually on screen — and a server-side impression on top
+ * of the client's own would double-count every view, and would keep counting
+ * from a CDN-cached SSR response that no human ever saw.
+ */
+export function buildStreamUrl(target, protocol = PROTOCOL_CURRENT) {
+    const url = new URL("/api/embed/v1/islands/stream", target.apiBase);
+    const params = url.searchParams;
+    params.set("organization", target.organizationId);
+    if (target.surfaceId)
+        params.set("surface", target.surfaceId);
+    else if (target.campaignId)
+        params.set("campaign", target.campaignId);
+    params.set("island", target.island);
+    if (target.context)
+        params.set("context", JSON.stringify(target.context));
+    if (target.variantId)
+        params.set(VARIANT_PARAM, target.variantId);
+    if (target.sessionId)
+        params.set("session", target.sessionId);
+    params.set(SDK_PARAM, SDK_PARAM_VALUE);
+    // Sent as a param as well as a header: EventSource cannot set headers, and
+    // a consumer that swaps our fetch transport for one must still negotiate.
+    params.set(PROTOCOL_PARAM, String(protocol));
+    for (const [key, value] of Object.entries(target.extra ?? {})) {
+        if (value !== undefined)
+            params.set(key, value);
+    }
+    return url.toString();
+}
+/**
+ * Build the `/content` URL used for first paint. Same pinning rules as the
+ * stream — but deliberately NOT the same `sdk=1` rule.
+ *
+ * `sdk=1` is a promise: "the SDK will record this impression itself". The
+ * stream path keeps that promise — `useIsland` owns a visibility-gated
+ * recorder. The content path CANNOT: its consumers (CopyCard, ProductCard,
+ * the cookbook's content-only recipes) have no observer and no recorder, so
+ * sending `sdk=1` here told the server to stop counting while nobody else
+ * started — zero impressions for every content-only integration. Omitting it
+ * leaves the server owning the `/content` impression, exactly as it does for
+ * every non-SDK consumer of the endpoint.
+ */
+export function buildContentUrl(target, protocol = PROTOCOL_CURRENT) {
+    const url = new URL("/api/embed/v1/content", target.apiBase);
+    const params = url.searchParams;
+    // Same param names the stream uses — the Go handler (contentRequest in
+    // mosaic-edge-serve/internal/handler/content.go) reads organization/
+    // campaign/surface; the *Id spellings were never read by any server.
+    params.set("organization", target.organizationId);
+    if (target.surfaceId)
+        params.set("surface", target.surfaceId);
+    if (target.campaignId)
+        params.set("campaign", target.campaignId);
+    if (target.context)
+        params.set("context", JSON.stringify(target.context));
+    if (target.variantId)
+        params.set(VARIANT_PARAM, target.variantId);
+    params.set(PROTOCOL_PARAM, String(protocol));
+    for (const [key, value] of Object.entries(target.extra ?? {})) {
+        if (value !== undefined)
+            params.set(key, value);
+    }
+    return url.toString();
+}
+/**
+ * Read the negotiated version off a response.
+ *
+ * An absent header means an older deployment that predates negotiation, which
+ * by contract is protocol 1 — not an error, and specifically not a reason to
+ * refuse the stream. Treating silence as failure here would break every
+ * customer whose traffic happens to land on an edge revision mid-rollout.
+ */
+export function negotiatedProtocol(response) {
+    const raw = response.headers.get(PROTOCOL_RESPONSE_HEADER);
+    if (!raw)
+        return PROTOCOL_DEFAULT;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : PROTOCOL_DEFAULT;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

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