@sparkletree/core 0.1.0

package/dist/theme.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Theme engine.
+ *
+ * The server resolves brand/campaign/context colours and sends tokens plus,
+ * for each token, WHERE IT CAME FROM. The client's job is only to put them
+ * somewhere CSS can see them, and to do it as custom properties rather than
+ * inline styles so a copied component can be restyled without forking the
+ * package.
+ *
+ * `sources` is carried alongside deliberately: it is what the Ledger renders,
+ * and a theme that arrives without provenance is a theme nobody can explain
+ * to a brand manager asking why their blue changed.
+ */
+export interface ResolvedTheme {
+    colors: Record<string, string>;
+    sources: Record<string, string>;
+}
+/** CSS custom-property prefix. `--st-` is short enough to type in overrides. */
+export declare const TOKEN_PREFIX = "--st-";
+/** `primaryColor` → `--st-primary-color`. */
+export declare function tokenName(key: string): string;
+/**
+ * Theme tokens as a style object, ready for React's `style` prop or
+ * `Object.assign(el.style, …)`.
+ *
+ * Values are passed through as authored. Sanitising here would mean parsing
+ * CSS colour syntax in the client, which is both a losing game and the wrong
+ * layer — the server owns what a valid resolved colour is.
+ */
+export declare function themeStyle(theme: ResolvedTheme | null): Record<string, string>;
+/**
+ * Write tokens onto an element.
+ *
+ * Returns a function restoring the previous values, so a component that
+ * unmounts mid-stream does not leave a half-applied theme behind on a
+ * long-lived host element.
+ */
+export declare function applyTheme(element: HTMLElement, theme: ResolvedTheme | null): () => void;
+/**
+ * Where a token came from — for the Ledger, and for anyone debugging why a
+ * brand colour did not win.
+ */
+export declare function tokenSource(theme: ResolvedTheme | null, key: string): string | null;
+/**
+ * The ink that reads on a given hex color — the SDK twin of the shell's
+ * ReadableTextColor (mosaic-edge-serve/internal/theme/theme.go) and the TS
+ * resolver's readableTextColor (mosaic/services/themeService.ts). Same
+ * perceived-luminance rule in all three places; change them together.
+ * Non-hex input returns light ink, matching both twins.
+ */
+export declare function readableTextColor(color: string): string;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,gFAAgF;AAChF,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC,6CAA6C;AAC7C,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO9E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,IAAI,CAexF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYvD"}

package/dist/theme.js

@@ -0,0 +1,88 @@
+/**
+ * Theme engine.
+ *
+ * The server resolves brand/campaign/context colours and sends tokens plus,
+ * for each token, WHERE IT CAME FROM. The client's job is only to put them
+ * somewhere CSS can see them, and to do it as custom properties rather than
+ * inline styles so a copied component can be restyled without forking the
+ * package.
+ *
+ * `sources` is carried alongside deliberately: it is what the Ledger renders,
+ * and a theme that arrives without provenance is a theme nobody can explain
+ * to a brand manager asking why their blue changed.
+ */
+/** CSS custom-property prefix. `--st-` is short enough to type in overrides. */
+export const TOKEN_PREFIX = "--st-";
+/** `primaryColor` → `--st-primary-color`. */
+export function tokenName(key) {
+    return TOKEN_PREFIX + key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Theme tokens as a style object, ready for React's `style` prop or
+ * `Object.assign(el.style, …)`.
+ *
+ * Values are passed through as authored. Sanitising here would mean parsing
+ * CSS colour syntax in the client, which is both a losing game and the wrong
+ * layer — the server owns what a valid resolved colour is.
+ */
+export function themeStyle(theme) {
+    if (!theme)
+        return {};
+    const style = {};
+    for (const [key, value] of Object.entries(theme.colors)) {
+        if (typeof value === "string" && value)
+            style[tokenName(key)] = value;
+    }
+    return style;
+}
+/**
+ * Write tokens onto an element.
+ *
+ * Returns a function restoring the previous values, so a component that
+ * unmounts mid-stream does not leave a half-applied theme behind on a
+ * long-lived host element.
+ */
+export function applyTheme(element, theme) {
+    const style = themeStyle(theme);
+    const previous = new Map();
+    for (const [property, value] of Object.entries(style)) {
+        previous.set(property, element.style.getPropertyValue(property));
+        element.style.setProperty(property, value);
+    }
+    return () => {
+        for (const [property, value] of previous) {
+            if (value)
+                element.style.setProperty(property, value);
+            else
+                element.style.removeProperty(property);
+        }
+    };
+}
+/**
+ * Where a token came from — for the Ledger, and for anyone debugging why a
+ * brand colour did not win.
+ */
+export function tokenSource(theme, key) {
+    return theme?.sources?.[key] ?? null;
+}
+/**
+ * The ink that reads on a given hex color — the SDK twin of the shell's
+ * ReadableTextColor (mosaic-edge-serve/internal/theme/theme.go) and the TS
+ * resolver's readableTextColor (mosaic/services/themeService.ts). Same
+ * perceived-luminance rule in all three places; change them together.
+ * Non-hex input returns light ink, matching both twins.
+ */
+export function readableTextColor(color) {
+    const clean = color.startsWith("#") ? color.slice(1) : color;
+    const full = /^[0-9a-fA-F]{3}$/.test(clean)
+        ? clean.split("").map((c) => c + c).join("")
+        : clean;
+    if (!/^[0-9a-fA-F]{6}$/.test(full))
+        return "#fff";
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+    return luminance > 0.6 ? "#000" : "#fff";
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

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

package/dist/trust.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Trust chrome.
+ *
+ * Plan v1.1 decision 6: the adaptation mark is STRUCTURAL. It renders inside
+ * the `StreamText` primitive, in the npm package, when and only when the copy
+ * beside it was genuinely generated for this viewer. Removing it means forking
+ * `@sparkletree/core` — not deleting a line of JSX from a copied component.
+ *
+ * That is the whole design. A mark a consumer can delete is a mark that will
+ * be deleted, and then "marked by default, contractually required" is a
+ * sentence in a contract rather than a property of the product.
+ *
+ * The honesty runs the other way too, and this is the part W5 exists for: the
+ * mark must NOT appear on copy that was merely served. Before content-source
+ * signalling, the silent static-fallback path was indistinguishable on the
+ * wire from live generation — so a client marking "everything that came down a
+ * stream" would have been labelling stored copy as adapted. Marking static
+ * copy as adapted is a worse failure than not marking generated copy, because
+ * one under-claims and the other lies.
+ */
+import type { ContentSource } from "./wire.js";
+/** Where the viewer's "show me the standard version" preference lives. */
+export declare const STANDARD_MODE_KEY = "st:standard";
+export interface ChromeDecision {
+    /** Render the adaptation mark? */
+    marked: boolean;
+    /**
+     * Why, in one machine-readable word. Reported on the impression, so the
+     * chrome state of real traffic is measurable rather than assumed.
+     */
+    reason: "generated" | "cached" | "static" | "viewer-opted-out";
+}
+/**
+ * Should this copy carry the adaptation mark?
+ *
+ * `cached` counts as adapted: the copy WAS generated, for an earlier viewer in
+ * the same variant × context bucket. It is not fresh, but it is not authored
+ * either, and calling it authored would be the same lie in the other
+ * direction.
+ */
+export declare function decideChrome(contentSource: ContentSource, viewerPrefersStandard: boolean): ChromeDecision;
+/**
+ * Read the viewer's preference.
+ *
+ * Any failure — no storage, disabled storage, SSR, a privacy mode that throws
+ * on access — means "no stated preference", which is the marked default. A
+ * storage error must never be a route to an unmarked creative.
+ */
+export declare function viewerPrefersStandard(storage?: Storage): boolean;
+/** Persist the viewer's preference. Silent on failure, for the same reason. */
+export declare function setViewerPrefersStandard(value: boolean, storage?: Storage): void;
+//# sourceMappingURL=trust.d.ts.map

package/dist/trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CAAC;CAChE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,aAAa,EAC5B,qBAAqB,EAAE,OAAO,GAC7B,cAAc,CAKhB;AAwBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAMhE;AAED,+EAA+E;AAC/E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAShF"}

package/dist/trust.js

@@ -0,0 +1,95 @@
+/**
+ * Trust chrome.
+ *
+ * Plan v1.1 decision 6: the adaptation mark is STRUCTURAL. It renders inside
+ * the `StreamText` primitive, in the npm package, when and only when the copy
+ * beside it was genuinely generated for this viewer. Removing it means forking
+ * `@sparkletree/core` — not deleting a line of JSX from a copied component.
+ *
+ * That is the whole design. A mark a consumer can delete is a mark that will
+ * be deleted, and then "marked by default, contractually required" is a
+ * sentence in a contract rather than a property of the product.
+ *
+ * The honesty runs the other way too, and this is the part W5 exists for: the
+ * mark must NOT appear on copy that was merely served. Before content-source
+ * signalling, the silent static-fallback path was indistinguishable on the
+ * wire from live generation — so a client marking "everything that came down a
+ * stream" would have been labelling stored copy as adapted. Marking static
+ * copy as adapted is a worse failure than not marking generated copy, because
+ * one under-claims and the other lies.
+ */
+/** Where the viewer's "show me the standard version" preference lives. */
+export const STANDARD_MODE_KEY = "st:standard";
+/**
+ * Should this copy carry the adaptation mark?
+ *
+ * `cached` counts as adapted: the copy WAS generated, for an earlier viewer in
+ * the same variant × context bucket. It is not fresh, but it is not authored
+ * either, and calling it authored would be the same lie in the other
+ * direction.
+ */
+export function decideChrome(contentSource, viewerPrefersStandard) {
+    if (viewerPrefersStandard)
+        return { marked: false, reason: "viewer-opted-out" };
+    if (contentSource === "generated")
+        return { marked: true, reason: "generated" };
+    if (contentSource === "cached")
+        return { marked: true, reason: "cached" };
+    return { marked: false, reason: "static" };
+}
+/**
+ * Resolve the store.
+ *
+ * `window.localStorage` FIRST, not the bare `localStorage` global: Node 18+
+ * exposes a global of that name which is undefined unless the runtime was
+ * started with `--localstorage-file`, and it shadows the real one in any
+ * DOM-emulating test environment. Reading the bare global there does not
+ * throw — it silently yields undefined, which would make every preference
+ * lookup quietly return the default in exactly the environment where the
+ * behaviour is being verified.
+ */
+function resolveStorage(explicit) {
+    if (explicit)
+        return explicit;
+    try {
+        if (typeof window !== "undefined" && window.localStorage)
+            return window.localStorage;
+        if (typeof localStorage !== "undefined" && localStorage)
+            return localStorage;
+    }
+    catch {
+        // Access itself throws under some privacy modes.
+    }
+    return null;
+}
+/**
+ * Read the viewer's preference.
+ *
+ * Any failure — no storage, disabled storage, SSR, a privacy mode that throws
+ * on access — means "no stated preference", which is the marked default. A
+ * storage error must never be a route to an unmarked creative.
+ */
+export function viewerPrefersStandard(storage) {
+    try {
+        return resolveStorage(storage)?.getItem(STANDARD_MODE_KEY) === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/** Persist the viewer's preference. Silent on failure, for the same reason. */
+export function setViewerPrefersStandard(value, storage) {
+    try {
+        const store = resolveStorage(storage);
+        if (!store)
+            return;
+        if (value)
+            store.setItem(STANDARD_MODE_KEY, "1");
+        else
+            store.removeItem(STANDARD_MODE_KEY);
+    }
+    catch {
+        // Preference is a nicety; failing to store it must not break a render.
+    }
+}
+//# sourceMappingURL=trust.js.map

package/dist/trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.js","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAY/C;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,aAA4B,EAC5B,qBAA8B;IAE9B,IAAI,qBAAqB;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAChF,IAAI,aAAa,KAAK,WAAW;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAChF,IAAI,aAAa,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC1E,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,QAAkB;IACxC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,YAAY;YAAE,OAAO,MAAM,CAAC,YAAY,CAAC;QACrF,IAAI,OAAO,YAAY,KAAK,WAAW,IAAI,YAAY;YAAE,OAAO,YAAY,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAiB;IACrD,IAAI,CAAC;QACH,OAAO,cAAc,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,KAAK,GAAG,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,wBAAwB,CAAC,KAAc,EAAE,OAAiB;IACxE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,IAAI,KAAK;YAAE,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;;YAC5C,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;AACH,CAAC"}

package/dist/variant.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Variant pinning (plan v1.1 §3.3).
+ *
+ * ε-greedy variant selection runs PER REQUEST on the server. A page with a
+ * hero island and a CTA island therefore makes two selections, and without
+ * pinning they are independent draws: the hero can come from arm A and the
+ * button from arm B. That page is not a mixed experience, it is a broken one —
+ * and worse, the impression it generates attributes a blend of two variants to
+ * whichever id happened to be reported, which quietly poisons the very signal
+ * the bandit is learning from.
+ *
+ * So: the FIRST resolution in a page view wins, and every subsequent call
+ * pins it via `variant=`. One page view, one variant, one honest attribution.
+ *
+ * The sync `get()`/`pin()` pair alone is not enough, because sibling islands
+ * mount in the SAME React commit: both read `get()` before either stream has
+ * resolved, both see undefined, and the server draws twice — exactly the
+ * failure described above, reintroduced by a race. `reserve()` closes it: the
+ * first caller per pin key becomes the LEADER and opens its stream unpinned;
+ * every later caller becomes a FOLLOWER and receives a promise that resolves
+ * with the leader's variant once its stream reports one. A leader that fails
+ * before learning a variant aborts the reservation so someone else can lead,
+ * and followers carry a timeout so a hung leader degrades to today's
+ * unpinned behaviour instead of blocking the page.
+ *
+ * Scoped per PIN KEY, not globally: two campaigns on one page are genuinely
+ * separate experiments and must not pin each other. The key is the campaign id
+ * when the island is campaign-addressed, and the SURFACE id when the island is
+ * surface-only — sibling surface islands resolve through the same deployment
+ * and would otherwise each draw independently, the exact mixed page pinning
+ * exists to prevent. (Two different keys that happen to resolve to the same
+ * campaign server-side are treated as separate experiments; addressing is the
+ * caller's statement of intent.)
+ */
+/**
+ * How long a follower waits for the leader's stream before giving up and
+ * requesting unpinned.
+ *
+ * This must cover the SERVER'S stream budget, not a hopeful median: the edge
+ * caps a stream at 30 seconds (context.WithTimeout in
+ * mosaic-edge-serve/internal/handler/stream.go), and the variant id arrives in
+ * the terminal `done` event — so a slow generation can legally take the whole
+ * budget before any follower learns the draw. An earlier 3s value expired
+ * inside that window, sent followers unpinned mid-generation, and painted the
+ * mixed page pinning exists to prevent. Waiting is cheap: followers hold
+ * their first-paint fallback copy the entire time, which is designed
+ * behaviour, not a blank. 30s server budget + 1s margin for transport.
+ */
+export declare const RESERVATION_TIMEOUT_MS = 31000;
+export interface LeaderReservation {
+    kind: "leader";
+    /**
+     * The stream resolved: pin `variantId` and release every follower with it.
+     * Idempotent; calls after `resolve` or `abort` are ignored.
+     */
+    resolve: (variantId: string) => void;
+    /**
+     * The leader failed (or unmounted) before learning a variant. Followers
+     * currently waiting are released unpinned, and the NEXT `reserve()` call
+     * for this pin key leads. Idempotent.
+     */
+    abort: () => void;
+}
+export interface FollowerReservation {
+    kind: "follower";
+    /**
+     * Resolves with the pinned variant, or `undefined` when the leader aborted,
+     * the wait timed out, or the leader finished without a variant — in which
+     * case the follower should request unpinned, exactly as it would have
+     * before reservations existed. Never rejects.
+     */
+    variantId: Promise<string | undefined>;
+}
+export type VariantReservation = LeaderReservation | FollowerReservation;
+export declare class VariantRegistry {
+    private readonly pinned;
+    private readonly pending;
+    /**
+     * The variant to request for this pin key — the campaign id, or the surface
+     * id for surface-only islands — if one is already pinned. Undefined means
+     * "let the server choose" — which it should, exactly once.
+     */
+    get(key: string): string | undefined;
+    /**
+     * Record a resolved variant. First writer wins.
+     *
+     * Later calls are ignored rather than overwriting, because a second
+     * resolution arriving at all means one island raced ahead of the pin — and
+     * in that case the right repair is to keep the value already reported on the
+     * impression, not to adopt the newer one and disagree with our own
+     * analytics.
+     */
+    pin(key: string, variantId: string): string;
+    /**
+     * Claim, or wait for, this page view's variant for a pin key (campaign id,
+     * or surface id for surface-only islands).
+     *
+     * The first caller (per key, per page view) gets a LEADER reservation
+     * and must eventually call `resolve` or `abort` on it. Everyone else gets a
+     * FOLLOWER whose promise resolves with the leader's variant, capped at
+     * `timeoutMs`. A key that is already pinned returns a follower whose
+     * promise is already resolved — awaiting it costs one microtask.
+     */
+    reserve(key: string, timeoutMs?: number): VariantReservation;
+    /** New page view. Call on client-side navigation. */
+    reset(): void;
+}
+/**
+ * The registry for the current page view.
+ *
+ * Module-scoped on purpose: pinning must span every SparkleTree component on
+ * the page regardless of which provider or tree rendered it, and a
+ * per-provider registry would let two providers each pin a different arm of
+ * the same campaign.
+ */
+export declare const pageVariants: VariantRegistry;
+//# sourceMappingURL=variant.d.ts.map

package/dist/variant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant.d.ts","sourceRoot":"","sources":["../src/variant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAOzE,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpC;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAO3C;;;;;;;;;OASG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,kBAAkB;IA8CpF,qDAAqD;IACrD,KAAK,IAAI,IAAI;CAOd;AAoBD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,iBAAwB,CAAC"}

package/dist/variant.js

@@ -0,0 +1,167 @@
+/**
+ * Variant pinning (plan v1.1 §3.3).
+ *
+ * ε-greedy variant selection runs PER REQUEST on the server. A page with a
+ * hero island and a CTA island therefore makes two selections, and without
+ * pinning they are independent draws: the hero can come from arm A and the
+ * button from arm B. That page is not a mixed experience, it is a broken one —
+ * and worse, the impression it generates attributes a blend of two variants to
+ * whichever id happened to be reported, which quietly poisons the very signal
+ * the bandit is learning from.
+ *
+ * So: the FIRST resolution in a page view wins, and every subsequent call
+ * pins it via `variant=`. One page view, one variant, one honest attribution.
+ *
+ * The sync `get()`/`pin()` pair alone is not enough, because sibling islands
+ * mount in the SAME React commit: both read `get()` before either stream has
+ * resolved, both see undefined, and the server draws twice — exactly the
+ * failure described above, reintroduced by a race. `reserve()` closes it: the
+ * first caller per pin key becomes the LEADER and opens its stream unpinned;
+ * every later caller becomes a FOLLOWER and receives a promise that resolves
+ * with the leader's variant once its stream reports one. A leader that fails
+ * before learning a variant aborts the reservation so someone else can lead,
+ * and followers carry a timeout so a hung leader degrades to today's
+ * unpinned behaviour instead of blocking the page.
+ *
+ * Scoped per PIN KEY, not globally: two campaigns on one page are genuinely
+ * separate experiments and must not pin each other. The key is the campaign id
+ * when the island is campaign-addressed, and the SURFACE id when the island is
+ * surface-only — sibling surface islands resolve through the same deployment
+ * and would otherwise each draw independently, the exact mixed page pinning
+ * exists to prevent. (Two different keys that happen to resolve to the same
+ * campaign server-side are treated as separate experiments; addressing is the
+ * caller's statement of intent.)
+ */
+/**
+ * How long a follower waits for the leader's stream before giving up and
+ * requesting unpinned.
+ *
+ * This must cover the SERVER'S stream budget, not a hopeful median: the edge
+ * caps a stream at 30 seconds (context.WithTimeout in
+ * mosaic-edge-serve/internal/handler/stream.go), and the variant id arrives in
+ * the terminal `done` event — so a slow generation can legally take the whole
+ * budget before any follower learns the draw. An earlier 3s value expired
+ * inside that window, sent followers unpinned mid-generation, and painted the
+ * mixed page pinning exists to prevent. Waiting is cheap: followers hold
+ * their first-paint fallback copy the entire time, which is designed
+ * behaviour, not a blank. 30s server budget + 1s margin for transport.
+ */
+export const RESERVATION_TIMEOUT_MS = 31_000;
+export class VariantRegistry {
+    pinned = new Map();
+    pending = new Map();
+    /**
+     * The variant to request for this pin key — the campaign id, or the surface
+     * id for surface-only islands — if one is already pinned. Undefined means
+     * "let the server choose" — which it should, exactly once.
+     */
+    get(key) {
+        return this.pinned.get(key);
+    }
+    /**
+     * Record a resolved variant. First writer wins.
+     *
+     * Later calls are ignored rather than overwriting, because a second
+     * resolution arriving at all means one island raced ahead of the pin — and
+     * in that case the right repair is to keep the value already reported on the
+     * impression, not to adopt the newer one and disagree with our own
+     * analytics.
+     */
+    pin(key, variantId) {
+        const existing = this.pinned.get(key);
+        if (existing)
+            return existing;
+        this.pinned.set(key, variantId);
+        return variantId;
+    }
+    /**
+     * Claim, or wait for, this page view's variant for a pin key (campaign id,
+     * or surface id for surface-only islands).
+     *
+     * The first caller (per key, per page view) gets a LEADER reservation
+     * and must eventually call `resolve` or `abort` on it. Everyone else gets a
+     * FOLLOWER whose promise resolves with the leader's variant, capped at
+     * `timeoutMs`. A key that is already pinned returns a follower whose
+     * promise is already resolved — awaiting it costs one microtask.
+     */
+    reserve(key, timeoutMs = RESERVATION_TIMEOUT_MS) {
+        const existing = this.pinned.get(key);
+        if (existing)
+            return { kind: "follower", variantId: Promise.resolve(existing) };
+        const inFlight = this.pending.get(key);
+        if (inFlight) {
+            return { kind: "follower", variantId: withTimeout(inFlight.promise, timeoutMs) };
+        }
+        let settled = false;
+        let release;
+        const promise = new Promise((res) => {
+            release = res;
+        });
+        const entry = {
+            promise,
+            settle: (variantId) => {
+                if (settled)
+                    return;
+                settled = true;
+                release(variantId);
+            },
+        };
+        this.pending.set(key, entry);
+        const clearIfCurrent = () => {
+            if (this.pending.get(key) === entry)
+                this.pending.delete(key);
+        };
+        return {
+            kind: "leader",
+            resolve: (variantId) => {
+                if (settled)
+                    return;
+                // `pin` first-writer-wins still applies: if something pinned in the
+                // meantime, followers get the value analytics already reported.
+                const winner = this.pin(key, variantId);
+                clearIfCurrent();
+                entry.settle(winner);
+            },
+            abort: () => {
+                if (settled)
+                    return;
+                clearIfCurrent();
+                entry.settle(undefined);
+            },
+        };
+    }
+    /** New page view. Call on client-side navigation. */
+    reset() {
+        this.pinned.clear();
+        // Anyone still waiting belongs to the OLD page view; release them
+        // unpinned rather than leaving promises to dangle past the navigation.
+        for (const entry of this.pending.values())
+            entry.settle(undefined);
+        this.pending.clear();
+    }
+}
+/**
+ * Resolve with `promise`'s value, or `undefined` after `timeoutMs` —
+ * whichever comes first. Never rejects.
+ */
+function withTimeout(promise, timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), timeoutMs);
+        void promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        });
+    });
+}
+/**
+ * The registry for the current page view.
+ *
+ * Module-scoped on purpose: pinning must span every SparkleTree component on
+ * the page regardless of which provider or tree rendered it, and a
+ * per-provider registry would let two providers each pin a different arm of
+ * the same campaign.
+ */
+export const pageVariants = new VariantRegistry();
+//# sourceMappingURL=variant.js.map

package/dist/variant.js.map

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