@syntrologie/runtime-sdk 2.14.0 → 2.16.0

package/dist/interop/LitInReact.d.ts

@@ -0,0 +1,27 @@
+/**
+ * LitInReact — A React wrapper that renders a Lit custom element.
+ *
+ * Used during the React → Lit migration to embed Lit elements within
+ * React-based parent components. Properties are forwarded to the
+ * custom element via ref + direct property assignment.
+ *
+ * Usage:
+ *   const SyntroTileCard = createLitReactWrapper('syntro-tile-card');
+ *   <SyntroTileCard tile={tileData} />
+ *
+ * This is a temporary bridge — delete when all React parents are migrated to Lit.
+ */
+import { type FC } from 'react';
+interface LitWrapperProps {
+    tagName: string;
+    props?: Record<string, unknown>;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const LitWrapper: FC<LitWrapperProps>;
+/**
+ * Creates a React component that wraps a specific Lit custom element.
+ * All props are forwarded as element properties.
+ */
+export declare function createLitReactWrapper(tagName: string): FC<Record<string, unknown>>;
+export {};

package/dist/interop/ReactInLit.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ReactInLit — A Lit element that mounts a React component inside itself.
+ *
+ * Used during the React → Lit migration to embed React subtrees within
+ * Lit-based parent components. The React root is created in firstUpdated()
+ * and re-rendered whenever Lit reactive properties change.
+ *
+ * Usage:
+ *   class MyLitElement extends LitElement {
+ *     render() {
+ *       return html`<react-bridge .component=${MyReactComponent} .props=${{ name: 'Alex' }}></react-bridge>`;
+ *     }
+ *   }
+ *
+ * This is a temporary bridge — delete when all React components are migrated.
+ */
+import type { PropertyValues } from 'lit';
+import { LitElement } from 'lit';
+import type { ComponentType } from 'react';
+export declare class ReactBridge extends LitElement {
+    #private;
+    static properties: {
+        component: {
+            attribute: boolean;
+        };
+        props: {
+            attribute: boolean;
+        };
+    };
+    component: ComponentType<Record<string, unknown>> | null;
+    props: Record<string, unknown>;
+    createRenderRoot(): this;
+    render(): import("lit-html").TemplateResult<1>;
+    firstUpdated(): void;
+    updated(_changed: PropertyValues): void;
+    disconnectedCallback(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'react-bridge': ReactBridge;
+    }
+}

package/dist/interop/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * React ↔ Lit interop bridges for incremental migration.
+ *
+ * These are temporary utilities — delete once all components are migrated to Lit.
+ */
+export { createLitReactWrapper, LitWrapper } from './LitInReact.js';
+export { ReactBridge } from './ReactInLit.js';

package/dist/metrics/sessionMetrics.d.ts

@@ -36,6 +36,7 @@ export interface SessionMetricTrackerOptions {
  */
 export declare class SessionMetricTracker {
     private metrics;
+    private subscribers;
     private experiments?;
     private attributePrefix;
     private onMetricChange?;
@@ -86,12 +87,15 @@ export declare class SessionMetricTracker {
      * Reset all metrics (clear the session).
      */
     resetAll(): void;
+    subscribe(callback: () => void): () => void;
+    destroy(): void;
     /**
      * Update the experiment client (useful if experiments client changes).
      */
     setExperiments(experiments: ExperimentClient): void;
     private updateExperimentAttributes;
     private syncAllToExperiments;
+    private notifySubscribers;
     private loadFromStorage;
     private saveToStorage;
 }

package/dist/notifications/SyntroToastStack.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SyntroToastStack — Lit web component equivalent of NotificationToastStack.tsx.
+ *
+ * Renders a fixed-position stack of notification toasts with:
+ *   - Slide-in entrance animation
+ *   - Progress bar with hover-pause
+ *   - Dismiss button (fires `notification-dismiss` event)
+ *   - Click-to-open (fires `notification-click` event)
+ *   - CSS variable theming (--sc-notification-*)
+ *
+ * Usage:
+ *   <syntro-toast-stack
+ *     .notifications=${activeNotifications}
+ *     .position=${'right'}
+ *   ></syntro-toast-stack>
+ *
+ *   element.addEventListener('notification-dismiss', (e) => dismiss(e.detail.id));
+ *   element.addEventListener('notification-click', (e) => open(e.detail.notification));
+ *
+ * Decorator-free: uses `static override properties` (tsconfig has no experimentalDecorators).
+ */
+import { LitElement } from 'lit';
+import type { ActiveNotification } from './types.js';
+export declare class SyntroToastStack extends LitElement {
+    #private;
+    static properties: {
+        notifications: {
+            attribute: boolean;
+        };
+        position: {
+            type: StringConstructor;
+        };
+    };
+    notifications: ActiveNotification[];
+    position: 'left' | 'right';
+    static styles: import("lit").CSSResult;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'syntro-toast-stack': SyntroToastStack;
+    }
+}

package/dist/platform/PlatformAdapter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * PlatformAdapter — interface for platform-specific integrations.
+ *
+ * Each supported host platform (Shopify, WordPress, etc.) implements this
+ * interface so the runtime can react to platform-specific lifecycle events
+ * (section load/unload, theme changes, etc.) without coupling to any single
+ * platform's API surface.
+ */
+export interface PlatformAdapter {
+    /** Human-readable platform name, e.g. "shopify" */
+    readonly name: string;
+    /**
+     * Synchronously detect whether the current page belongs to this platform.
+     * Must be safe to call in any environment (returns false when unsure).
+     */
+    detect(): boolean;
+    /**
+     * Async initialization hook. Called once after the adapter is selected.
+     * May wait for platform-specific readiness signals (e.g. Shopify sections).
+     */
+    onInit(): Promise<void>;
+    /**
+     * Called by the runtime when a region's DOM has been mutated.
+     */
+    onRegionMutated(regionId: string): void;
+    /**
+     * Returns a CSS-selector scope prefix for the given anchor element,
+     * based on the platform's section/region structure.
+     * Returns empty string when the anchor is not inside a known section.
+     */
+    getAnchorScope(anchor: Element): string;
+    /**
+     * Subscribe to "region is about to unload" events.
+     * Returns an unsubscribe function.
+     */
+    onRegionWillUnload(callback: (regionId: string) => void): () => void;
+    /**
+     * Subscribe to "region finished loading" events.
+     * Returns an unsubscribe function.
+     */
+    onRegionDidLoad(callback: (regionId: string) => void): () => void;
+    /**
+     * Tear down all listeners and internal state.
+     */
+    destroy(): void;
+}

package/dist/platform/ShopifyAdapter.d.ts

@@ -0,0 +1,36 @@
+import type { PlatformAdapter } from './PlatformAdapter';
+/**
+ * Shopify-specific platform adapter.
+ *
+ * Detects Shopify storefronts and hooks into Shopify's section rendering
+ * lifecycle events (`shopify:section:load` / `shopify:section:unload`) so
+ * the runtime can react to dynamic section swaps in Shopify Online Store 2.0.
+ */
+export declare class ShopifyAdapter implements PlatformAdapter {
+    readonly name: "shopify";
+    private loadCallbacks;
+    private unloadCallbacks;
+    private abortController;
+    private antiFlicker;
+    private readonly initTimeoutMs;
+    constructor(options?: {
+        initTimeoutMs?: number;
+    });
+    detect(): boolean;
+    /**
+     * Wait for Shopify sections to be ready, then attach lifecycle listeners.
+     *
+     * Resolution order:
+     * 1. `.shopify-section` already in DOM -> resolve immediately
+     * 2. `shopify:section:load` fires -> resolve
+     * 3. Timeout (default 3000ms) -> resolve anyway (graceful degradation)
+     */
+    onInit(): Promise<void>;
+    onRegionDidLoad(callback: (regionId: string) => void): () => void;
+    onRegionWillUnload(callback: (regionId: string) => void): () => void;
+    onRegionMutated(_regionId: string): void;
+    getAnchorScope(anchor: Element): string;
+    destroy(): void;
+    private attachSectionListeners;
+    private waitForInitialSections;
+}

package/dist/platform/ShopifyAnchorResolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Theme families sharing identical DOM structures.
+ * Dawn family: Dawn, Sense, Craft, Ride, Refresh, Colorblock, Taste, Studio
+ */
+export type ShopifyThemeFamily = 'dawn' | 'prestige' | 'impulse' | 'turbo' | 'trademark' | 'legacy' | 'unknown';
+/**
+ * Detect the Shopify theme family from window.Shopify.theme.name.
+ */
+export declare function detectThemeFamily(): ShopifyThemeFamily;
+export interface AnchorValidation {
+    unique: boolean;
+    matchCount: number;
+}
+/**
+ * ShopifyAnchorResolver — provides Shopify-aware selector scoping and
+ * uniqueness validation for anchor configuration.
+ */
+export declare class ShopifyAnchorResolver {
+    /**
+     * Scope a CSS selector to its containing .shopify-section wrapper.
+     */
+    scopeSelector(selector: string, element: Element): string;
+    /**
+     * Validate that a selector matches exactly one element in the document.
+     */
+    validateUniqueness(selector: string): AnchorValidation;
+    /**
+     * Get the current theme family for diagnostic/logging purposes.
+     */
+    getThemeFamily(): ShopifyThemeFamily;
+}

package/dist/platform/ShopifyAntiFlicker.d.ts

@@ -0,0 +1,21 @@
+import type { PlatformAdapter } from './PlatformAdapter';
+/**
+ * ShopifyAntiFlicker -- prevents visible content flash during section re-renders.
+ *
+ * When Shopify's Section Rendering API replaces a section's innerHTML, our
+ * injected content (identified by [data-syntro-action-id]) disappears momentarily.
+ * This module hooks section:unload to pre-hide our content and section:load to
+ * fade it back in, eliminating the visible flash.
+ */
+export declare class ShopifyAntiFlicker {
+    private readonly adapter;
+    private unsubUnload;
+    private unsubLoad;
+    private destroyed;
+    constructor(adapter: PlatformAdapter);
+    activate(): void;
+    destroy(): void;
+    private hideContentInSection;
+    private revealContentInSection;
+    private sectionSelector;
+}

package/dist/platform/ShopifyPixelBridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ShopifyPixelBridge — storefront-side cookie writer for checkout attribution.
+ *
+ * The SDK can't run in Shopify's sandboxed checkout. This bridge writes a
+ * `syntro_experiments` cookie containing the telemetry context (distinct_id,
+ * telemetry host, public PostHog key). A Shopify Web Pixel extension running
+ * in the checkout sandbox reads the cookie and POSTs
+ * `checkout_completed` / `product_added_to_cart` events to
+ * `{telemetry_host}/t/{telemetry_key}/e/` — the Syntrologie PostHog proxy.
+ *
+ * Experiment attribution is NOT carried in the cookie. PostHog already tracks
+ * each shopper's assignments server-side via `$experiment_started` events
+ * fired from the storefront SDK under the same distinct_id. When the pixel's
+ * checkout event lands with that distinct_id, PostHog auto-attributes the
+ * conversion to the correct variant. The cookie only needs to ferry identity
+ * and destination.
+ *
+ * Max-age: 30 days (covers long shopping sessions).
+ * SameSite: Lax (readable by checkout on the same registrable domain).
+ */
+export interface ShopifyPixelBridgeContext {
+    /** PostHog distinct_id from the storefront telemetry client. */
+    distinctId: string;
+    /** Telemetry proxy host, e.g. `https://telemetry.syntrologie.com`. No trailing slash. */
+    telemetryHost: string;
+    /** Public write-only PostHog key. */
+    telemetryKey: string;
+}
+export declare class ShopifyPixelBridge {
+    private context;
+    constructor(context: ShopifyPixelBridgeContext);
+    /** Update the telemetry context (e.g., after consent is granted and
+     *  PostHog finally initializes and a real distinct_id becomes available). */
+    updateContext(context: ShopifyPixelBridgeContext): void;
+    destroy(): void;
+    private writeCookie;
+}

package/dist/platform/detect.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformAdapter } from './PlatformAdapter';
+/**
+ * Auto-detect the current host platform.
+ *
+ * Iterates registered adapters and returns the first one that detects
+ * its platform signals. Returns `null` if no platform is recognized
+ * (i.e. the page is a generic/unknown site).
+ */
+export declare function detectPlatform(): PlatformAdapter | null;

package/dist/platform/index.d.ts

@@ -0,0 +1,10 @@
+export { detectPlatform } from './detect';
+export type { PlatformAdapter } from './PlatformAdapter';
+export { ShopifyAdapter } from './ShopifyAdapter';
+export type { AnchorValidation, ShopifyThemeFamily } from './ShopifyAnchorResolver';
+export { detectThemeFamily, ShopifyAnchorResolver } from './ShopifyAnchorResolver';
+export { ShopifyAntiFlicker } from './ShopifyAntiFlicker';
+export type { ShopifyPixelBridgeContext } from './ShopifyPixelBridge';
+export { ShopifyPixelBridge } from './ShopifyPixelBridge';
+export type { ShopifyPixelCookie } from './shopify-cookie-contract';
+export { COOKIE_NAME as SHOPIFY_COOKIE_NAME } from './shopify-cookie-contract';

package/dist/platform/shopify-cookie-contract.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared cookie contract between ShopifyPixelBridge (SDK) and the
+ * Shopify Web Pixel extension. Both sides must agree on this format.
+ *
+ * Cookie name: syntro_experiments (legacy name — kept for backward compat;
+ * the cookie carries telemetry identity, not experiment assignments)
+ * Cookie value: JSON-encoded ShopifyPixelCookie
+ *
+ * The storefront SDK writes a snapshot of its telemetry context — the
+ * PostHog distinct_id, the telemetry proxy host, and the public PostHog
+ * project key. The Web Pixel extension runs in Shopify's sandboxed
+ * checkout (which cannot reach the SDK), reads this cookie, and posts
+ * PostHog-shaped checkout events with the same distinct_id so that
+ * checkout events JOIN to the storefront session. PostHog already knows
+ * which experiments that shopper is in (via `$experiment_started` events
+ * fired from the storefront), so attribution happens server-side without
+ * the pixel having to re-transmit assignments.
+ *
+ * Naming note: the fields are `telemetry_host` / `telemetry_key` — not
+ * `api_host` / `api_key` — to disambiguate from the other `apiHost`
+ * fields in the codebase. This cookie is strictly about telemetry.
+ *
+ * Forward compat: pixel code must check `version` and reject unknown
+ * shapes. Bump `version` when fields are removed or semantics change.
+ */
+export interface ShopifyPixelCookie {
+    /** Schema version — pixel rejects unknown versions. Bump on breaking changes. */
+    version: 1;
+    /** PostHog distinct_id from the storefront SDK, used so checkout events
+     * join onto the pre-checkout session. Required — without it the pixel
+     * would create a new anonymous user at checkout and the funnel breaks. */
+    distinct_id: string;
+    /** Telemetry proxy host (e.g., `https://telemetry.syntrologie.com`). No trailing slash. */
+    telemetry_host: string;
+    /** Public write-only PostHog key (embedded in the client). */
+    telemetry_key: string;
+}
+export declare const COOKIE_NAME = "syntro_experiments";
+export declare const COOKIE_VERSION: 1;

package/dist/react-compat.d.ts

@@ -0,0 +1,114 @@
+/**
+ * React compatibility layer for the Syntro SDK.
+ *
+ * Thin wrapper that calls the framework-agnostic Syntro.init() and exposes
+ * the result via React context. This file is the React entry point — it does
+ * NOT import any React UI components from the SDK (no SmartCanvasApp, no
+ * RuntimeProvider). The Lit bundle powers all rendering; this layer only
+ * provides React hooks for customers who embed the SDK in a React app.
+ *
+ * Usage:
+ * ```tsx
+ * import { SyntroProvider, useSyntro } from '@syntrologie/runtime-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <SyntroProvider token="syn_xxx">
+ *       <MyApp />
+ *     </SyntroProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { canvas, experiments, telemetry, isReady } = useSyntro();
+ *   // ...
+ * }
+ * ```
+ */
+import { type ReactNode } from 'react';
+import type { SmartCanvasHandle } from './api';
+import { type SyntroInitOptions, type SyntroInitResult } from './bootstrap';
+import type { ExperimentClient } from './experiments/types';
+import type { TelemetryClient } from './telemetry/types';
+export interface SyntroContextValue {
+    /** The SmartCanvas handle */
+    canvas: SmartCanvasHandle | null;
+    /** The experiment client */
+    experiments: ExperimentClient | null;
+    /** The telemetry client */
+    telemetry: TelemetryClient | null;
+    /** Whether the SDK has finished initializing */
+    isReady: boolean;
+    /** Any error that occurred during initialization */
+    error: Error | null;
+}
+export interface SyntroProviderProps {
+    /**
+     * The Syntro token containing all credentials.
+     */
+    token: string;
+    /**
+     * Optional canvas configuration overrides.
+     */
+    canvasOptions?: SyntroInitOptions['canvas'];
+    /**
+     * Custom config fetcher to override the default experiment-based fetcher.
+     * Use this for local development or when bypassing the experiment server.
+     */
+    fetcher?: SyntroInitOptions['fetcher'];
+    /**
+     * Children to render.
+     */
+    children: ReactNode;
+    /**
+     * Called when initialization completes.
+     */
+    onReady?: (result: SyntroInitResult) => void;
+    /**
+     * Called when initialization fails.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Provider component that initializes the Syntro SDK.
+ *
+ * Calls `Syntro.init()` (framework-agnostic) in a useEffect, stores the
+ * result in React state, and provides it via context. Does NOT render any
+ * SDK UI — the Lit custom element handles all rendering.
+ *
+ * Place this at the root of your app or at the top of any subtree
+ * that needs access to the SDK.
+ */
+export declare function SyntroProvider({ token, canvasOptions, fetcher, children, onReady, onError, }: SyntroProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Syntro SDK.
+ *
+ * Must be used within a SyntroProvider.
+ *
+ * @returns The SDK context containing canvas, experiments, telemetry, and status
+ */
+export declare function useSyntro(): SyntroContextValue;
+/**
+ * Hook to check if the SDK is ready.
+ *
+ * Shorthand for `useSyntro().isReady`.
+ */
+export declare function useSyntroReady(): boolean;
+/**
+ * Hook to access the experiment client.
+ *
+ * @returns The experiment client, or null if not configured
+ */
+export declare function useSyntroExperiments(): ExperimentClient | null;
+/**
+ * Hook to access the telemetry client.
+ *
+ * @returns The telemetry client, or null if not configured
+ */
+export declare function useSyntroTelemetry(): TelemetryClient | null;
+/**
+ * Hook to access the canvas handle.
+ *
+ * @returns The canvas handle, or null if not ready
+ */
+export declare function useSyntroCanvas(): SmartCanvasHandle | null;

package/dist/react.js

@@ -1,9 +1,11 @@
 import {
   Syntro
-} from "./chunk-JCDCANR7.js";
-import "./chunk-77TNZ66J.js";
-import "./chunk-IR6UOR63.js";
-import "./chunk-YLLWLUQX.js";
+} from "./chunk-NVV7IWJC.js";
+import "./chunk-2IQ2PTLJ.js";
+import "./chunk-XVRDKBYF.js";
+import "./chunk-GX7BBYX6.js";
+import "./chunk-4HXPGXUC.js";
+import "./chunk-JMHRHAEL.js";
 
 // src/react.tsx
 import { createContext, useContext, useEffect, useRef, useState } from "react";

package/dist/react.js.map

@@ -2,6 +2,6 @@
   "version": 3,
   "sources": ["../src/react.tsx"],
   "sourcesContent": ["/**\n * React bindings for the Syntro SDK.\n *\n * Usage:\n * ```tsx\n * import { SyntroProvider, useSyntro } from '@syntrologie/runtime-sdk/react';\n *\n * function App() {\n *   return (\n *     <SyntroProvider token=\"syn_xxx\">\n *       <MyApp />\n *     </SyntroProvider>\n *   );\n * }\n *\n * function MyComponent() {\n *   const { canvas, experiments, telemetry, isReady } = useSyntro();\n *   // ...\n * }\n * ```\n */\nimport { createContext, type ReactNode, useContext, useEffect, useRef, useState } from 'react';\n\nimport type { SmartCanvasHandle } from './api';\nimport { Syntro, type SyntroInitOptions, type SyntroInitResult } from './bootstrap';\nimport type { ExperimentClient } from './experiments/types';\nimport type { TelemetryClient } from './telemetry/types';\n\nexport interface SyntroContextValue {\n  /** The SmartCanvas handle */\n  canvas: SmartCanvasHandle | null;\n  /** The experiment client */\n  experiments: ExperimentClient | null;\n  /** The telemetry client */\n  telemetry: TelemetryClient | null;\n  /** Whether the SDK has finished initializing */\n  isReady: boolean;\n  /** Any error that occurred during initialization */\n  error: Error | null;\n}\n\nconst SyntroContext = createContext<SyntroContextValue | null>(null);\n\n// Global tracking to handle React Strict Mode double-mounting\nlet globalInitPromise: Promise<SyntroInitResult | undefined> | null = null;\nlet globalInitToken: string | null = null;\n\nexport interface SyntroProviderProps {\n  /**\n   * The Syntro token containing all credentials.\n   */\n  token: string;\n\n  /**\n   * Optional canvas configuration overrides.\n   */\n  canvasOptions?: SyntroInitOptions['canvas'];\n\n  /**\n   * Custom config fetcher to override the default experiment-based fetcher.\n   * Use this for local development or when bypassing the experiment server.\n   */\n  fetcher?: SyntroInitOptions['fetcher'];\n\n  /**\n   * Children to render.\n   */\n  children: ReactNode;\n\n  /**\n   * Called when initialization completes.\n   */\n  onReady?: (result: SyntroInitResult) => void;\n\n  /**\n   * Called when initialization fails.\n   */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Provider component that initializes the Syntro SDK.\n *\n * Place this at the root of your app or at the top of any subtree\n * that needs access to the SDK.\n */\nexport function SyntroProvider({\n  token,\n  canvasOptions,\n  fetcher,\n  children,\n  onReady,\n  onError,\n}: SyntroProviderProps) {\n  const [state, setState] = useState<SyntroContextValue>({\n    canvas: null,\n    experiments: null,\n    telemetry: null,\n    isReady: false,\n    error: null,\n  });\n\n  const initRef = useRef(false);\n  const handleRef = useRef<SmartCanvasHandle | null>(null);\n\n  useEffect(() => {\n    if (!token) return;\n\n    // Reuse existing init if same token (handles React Strict Mode remounts)\n    if (globalInitPromise && globalInitToken === token) {\n      globalInitPromise.then((result) => {\n        if (!result) return;\n        handleRef.current = result.canvas;\n        setState({\n          canvas: result.canvas,\n          experiments: result.experiments ?? null,\n          telemetry: result.telemetry ?? null,\n          isReady: true,\n          error: null,\n        });\n      });\n      return;\n    }\n\n    // Prevent double init\n    if (initRef.current) return;\n    initRef.current = true;\n\n    globalInitToken = token;\n    globalInitPromise = Syntro.init({ token, canvas: canvasOptions, fetcher });\n\n    globalInitPromise\n      .then((result) => {\n        if (!result) return;\n        handleRef.current = result.canvas;\n        setState({\n          canvas: result.canvas,\n          experiments: result.experiments ?? null,\n          telemetry: result.telemetry ?? null,\n          isReady: true,\n          error: null,\n        });\n        onReady?.(result);\n      })\n      .catch((err) => {\n        const error = err instanceof Error ? err : new Error(String(err));\n        setState((prev) => ({ ...prev, error, isReady: true }));\n        onError?.(error);\n        // Clear global state on error so retry is possible\n        globalInitPromise = null;\n        globalInitToken = null;\n      });\n\n    // Don't destroy on unmount in dev mode - React Strict Mode will remount\n    // The canvas persists and will be reused on remount\n  }, [token, canvasOptions, fetcher, onError, onReady]);\n\n  return <SyntroContext.Provider value={state}>{children}</SyntroContext.Provider>;\n}\n\n/**\n * Hook to access the Syntro SDK.\n *\n * Must be used within a SyntroProvider.\n *\n * @returns The SDK context containing canvas, experiments, telemetry, and status\n */\nexport function useSyntro(): SyntroContextValue {\n  const context = useContext(SyntroContext);\n  if (!context) {\n    throw new Error('useSyntro must be used within a SyntroProvider');\n  }\n  return context;\n}\n\n/**\n * Hook to check if the SDK is ready.\n *\n * Shorthand for `useSyntro().isReady`.\n */\nexport function useSyntroReady(): boolean {\n  return useSyntro().isReady;\n}\n\n/**\n * Hook to access the experiment client.\n *\n * @returns The experiment client, or null if not configured\n */\nexport function useSyntroExperiments(): ExperimentClient | null {\n  return useSyntro().experiments;\n}\n\n/**\n * Hook to access the telemetry client.\n *\n * @returns The telemetry client, or null if not configured\n */\nexport function useSyntroTelemetry(): TelemetryClient | null {\n  return useSyntro().telemetry;\n}\n\n/**\n * Hook to access the canvas handle.\n *\n * @returns The canvas handle, or null if not ready\n */\nexport function useSyntroCanvas(): SmartCanvasHandle | null {\n  return useSyntro().canvas;\n}\n"],
-  "mappings": ";;;;;;;;AAqBA,SAAS,eAA+B,YAAY,WAAW,QAAQ,gBAAgB;AAwI9E;AApHT,IAAM,gBAAgB,cAAyC,IAAI;AAGnE,IAAI,oBAAkE;AACtE,IAAI,kBAAiC;AAyC9B,SAAS,eAAe;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAwB;AACtB,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA6B;AAAA,IACrD,QAAQ;AAAA,IACR,aAAa;AAAA,IACb,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO;AAAA,EACT,CAAC;AAED,QAAM,UAAU,OAAO,KAAK;AAC5B,QAAM,YAAY,OAAiC,IAAI;AAEvD,YAAU,MAAM;AACd,QAAI,CAAC,MAAO;AAGZ,QAAI,qBAAqB,oBAAoB,OAAO;AAClD,wBAAkB,KAAK,CAAC,WAAW;AA9GzC;AA+GQ,YAAI,CAAC,OAAQ;AACb,kBAAU,UAAU,OAAO;AAC3B,iBAAS;AAAA,UACP,QAAQ,OAAO;AAAA,UACf,cAAa,YAAO,gBAAP,YAAsB;AAAA,UACnC,YAAW,YAAO,cAAP,YAAoB;AAAA,UAC/B,SAAS;AAAA,UACT,OAAO;AAAA,QACT,CAAC;AAAA,MACH,CAAC;AACD;AAAA,IACF;AAGA,QAAI,QAAQ,QAAS;AACrB,YAAQ,UAAU;AAElB,sBAAkB;AAClB,wBAAoB,OAAO,KAAK,EAAE,OAAO,QAAQ,eAAe,QAAQ,CAAC;AAEzE,sBACG,KAAK,CAAC,WAAW;AApIxB;AAqIQ,UAAI,CAAC,OAAQ;AACb,gBAAU,UAAU,OAAO;AAC3B,eAAS;AAAA,QACP,QAAQ,OAAO;AAAA,QACf,cAAa,YAAO,gBAAP,YAAsB;AAAA,QACnC,YAAW,YAAO,cAAP,YAAoB;AAAA,QAC/B,SAAS;AAAA,QACT,OAAO;AAAA,MACT,CAAC;AACD,yCAAU;AAAA,IACZ,CAAC,EACA,MAAM,CAAC,QAAQ;AACd,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAChE,eAAS,CAAC,UAAU,EAAE,GAAG,MAAM,OAAO,SAAS,KAAK,EAAE;AACtD,yCAAU;AAEV,0BAAoB;AACpB,wBAAkB;AAAA,IACpB,CAAC;AAAA,EAIL,GAAG,CAAC,OAAO,eAAe,SAAS,SAAS,OAAO,CAAC;AAEpD,SAAO,oBAAC,cAAc,UAAd,EAAuB,OAAO,OAAQ,UAAS;AACzD;AASO,SAAS,YAAgC;AAC9C,QAAM,UAAU,WAAW,aAAa;AACxC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,SAAO;AACT;AAOO,SAAS,iBAA0B;AACxC,SAAO,UAAU,EAAE;AACrB;AAOO,SAAS,uBAAgD;AAC9D,SAAO,UAAU,EAAE;AACrB;AAOO,SAAS,qBAA6C;AAC3D,SAAO,UAAU,EAAE;AACrB;AAOO,SAAS,kBAA4C;AAC1D,SAAO,UAAU,EAAE;AACrB;",
+  "mappings": ";;;;;;;;;;AAqBA,SAAS,eAA+B,YAAY,WAAW,QAAQ,gBAAgB;AAwI9E;AApHT,IAAM,gBAAgB,cAAyC,IAAI;AAGnE,IAAI,oBAAkE;AACtE,IAAI,kBAAiC;AAyC9B,SAAS,eAAe;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAwB;AACtB,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA6B;AAAA,IACrD,QAAQ;AAAA,IACR,aAAa;AAAA,IACb,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO;AAAA,EACT,CAAC;AAED,QAAM,UAAU,OAAO,KAAK;AAC5B,QAAM,YAAY,OAAiC,IAAI;AAEvD,YAAU,MAAM;AACd,QAAI,CAAC,MAAO;AAGZ,QAAI,qBAAqB,oBAAoB,OAAO;AAClD,wBAAkB,KAAK,CAAC,WAAW;AA9GzC;AA+GQ,YAAI,CAAC,OAAQ;AACb,kBAAU,UAAU,OAAO;AAC3B,iBAAS;AAAA,UACP,QAAQ,OAAO;AAAA,UACf,cAAa,YAAO,gBAAP,YAAsB;AAAA,UACnC,YAAW,YAAO,cAAP,YAAoB;AAAA,UAC/B,SAAS;AAAA,UACT,OAAO;AAAA,QACT,CAAC;AAAA,MACH,CAAC;AACD;AAAA,IACF;AAGA,QAAI,QAAQ,QAAS;AACrB,YAAQ,UAAU;AAElB,sBAAkB;AAClB,wBAAoB,OAAO,KAAK,EAAE,OAAO,QAAQ,eAAe,QAAQ,CAAC;AAEzE,sBACG,KAAK,CAAC,WAAW;AApIxB;AAqIQ,UAAI,CAAC,OAAQ;AACb,gBAAU,UAAU,OAAO;AAC3B,eAAS;AAAA,QACP,QAAQ,OAAO;AAAA,QACf,cAAa,YAAO,gBAAP,YAAsB;AAAA,QACnC,YAAW,YAAO,cAAP,YAAoB;AAAA,QAC/B,SAAS;AAAA,QACT,OAAO;AAAA,MACT,CAAC;AACD,yCAAU;AAAA,IACZ,CAAC,EACA,MAAM,CAAC,QAAQ;AACd,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAChE,eAAS,CAAC,UAAU,EAAE,GAAG,MAAM,OAAO,SAAS,KAAK,EAAE;AACtD,yCAAU;AAEV,0BAAoB;AACpB,wBAAkB;AAAA,IACpB,CAAC;AAAA,EAIL,GAAG,CAAC,OAAO,eAAe,SAAS,SAAS,OAAO,CAAC;AAEpD,SAAO,oBAAC,cAAc,UAAd,EAAuB,OAAO,OAAQ,UAAS;AACzD;AASO,SAAS,YAAgC;AAC9C,QAAM,UAAU,WAAW,aAAa;AACxC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,SAAO;AACT;AAOO,SAAS,iBAA0B;AACxC,SAAO,UAAU,EAAE;AACrB;AAOO,SAAS,uBAAgD;AAC9D,SAAO,UAAU,EAAE;AACrB;AAOO,SAAS,qBAA6C;AAC3D,SAAO,UAAU,EAAE;AACrB;AAOO,SAAS,kBAA4C;AAC1D,SAAO,UAAU,EAAE;AACrB;",
   "names": []
 }

package/dist/shopify-pixel-entry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * CDN-hosted Shopify Web Pixel — bundled to `dist/shopify-pixel.min.js` and
+ * served from `cdn.syntrologie.com/runtime-sdk/v2/latest/shopify-pixel.min.js`.
+ *
+ * Merchants install this by pasting a small loader snippet into Shopify admin
+ * under Settings → Customer events → Add custom pixel. The loader dynamically
+ * loads this file, then calls `window.__SyntroShopifyPixel.register({ analytics, browser })`
+ * to wire up subscribers. The indirection means we ship updates to every
+ * merchant's pixel by redeploying the CDN file — merchants never re-paste.
+ *
+ * The pixel's only job is to forward Shopify checkout events to the
+ * Syntrologie PostHog proxy with the shopper's distinct_id attached.
+ * Experiment attribution is handled server-side by PostHog — once the
+ * storefront SDK has fired `$experiment_started` for a distinct_id, PostHog
+ * associates all future events from that user (including checkout events
+ * this pixel posts) with the correct variant.
+ *
+ * Shopify custom pixels run in a "lax sandbox" iframe. Script tag injection
+ * works (verified by PostHog, Sentry, GTM following the same pattern). Cookie
+ * access is via the async `browser.cookie.get()` API which proxies to the
+ * top frame (merchant storefront domain), so the `syntro_experiments` cookie
+ * written by `ShopifyPixelBridge` on the storefront is readable here.
+ *
+ * All errors swallowed — a pixel failure must never disturb checkout.
+ */
+interface ShopifyAnalytics {
+    subscribe(eventName: string, handler: (event: ShopifyPixelEvent) => void | Promise<void>): void;
+}
+interface ShopifyBrowserCookie {
+    get(name: string): Promise<string | undefined>;
+}
+interface ShopifyBrowser {
+    cookie: ShopifyBrowserCookie;
+}
+interface ShopifyPixelEvent {
+    data: {
+        checkout?: {
+            totalPrice: {
+                amount: string | number;
+                currencyCode: string;
+            };
+            order?: {
+                id: string;
+            };
+        };
+        cartLine?: {
+            merchandise: {
+                id: string;
+                product: {
+                    id: string;
+                };
+            };
+            quantity: number;
+        };
+    };
+}
+export declare function register({ analytics, browser, }: {
+    analytics: ShopifyAnalytics;
+    browser: ShopifyBrowser;
+}): void;
+declare global {
+    interface Window {
+        __SyntroShopifyPixel?: {
+            register: typeof register;
+        };
+    }
+}
+export {};