@syntrologie/runtime-sdk 2.8.0-canary.13 → 2.8.0-canary.130

package/dist/actions/schema.js

@@ -31,9 +31,9 @@ import {
   WaitZ,
   WidgetConfigZ,
   coreActionStepSchemas
-} from "../chunk-NBFQGKSV.js";
-import "../chunk-37TTQRH5.js";
-import "../chunk-Q77NT67W.js";
+} from "../chunk-XVRDKBYF.js";
+import "../chunk-GX7BBYX6.js";
+import "../chunk-4HXPGXUC.js";
 import "../chunk-JMHRHAEL.js";
 export {
   AddClassZ,

package/dist/actions/types.d.ts

@@ -181,7 +181,7 @@ export interface TourStep {
 }
 /** Orchestrate sequential steps with cross-page state */
 export interface TourAction extends BaseAction {
-    kind: 'core:tour';
+    kind: 'overlays:tour';
     tourId: string;
     steps: TourStep[];
     startStep?: string;
@@ -341,6 +341,12 @@ export interface ActionEngineOptions {
         accumulator?: {
             subscribe: (cb: () => void) => () => void;
         };
+        sessionMetrics?: {
+            subscribe: (cb: () => void) => () => void;
+        };
+        events?: {
+            subscribe: (cb: () => void) => () => void;
+        };
     };
 }
 /** The ActionEngine interface */
@@ -353,8 +359,8 @@ export interface ActionEngine {
     validate: (action: ActionStep) => ValidationResult;
     /** Get all currently active actions */
     getActive: () => ActiveAction[];
-    /** Clean up all active actions and resources */
-    destroy: () => void;
+    /** Clean up all active actions and resources. Awaits async cleanup (animated reverts). */
+    destroy: () => Promise<void>;
 }
 /** Renderable content types for surfaces */
 export type RenderableContent = {

package/dist/actions/validation-core.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Action Validation — Core
+ *
+ * Main validate dispatch function, anchor validation, dangerous attrs constants,
+ * and common validation helpers.
+ */
+import type { ActionStep, AnchorId, ValidationError, ValidationResult, ValidationWarning } from './types';
+/** Dangerous attribute names that should not be set */
+export declare const DANGEROUS_ATTRS: Set<string>;
+/** Maximum HTML content length */
+export declare const MAX_HTML_LENGTH = 50000;
+/** Maximum style count */
+export declare const MAX_STYLE_COUNT = 50;
+/**
+ * Validate an action step.
+ */
+export declare function validateAction(action: ActionStep): ValidationResult;
+export declare function validateAnchorAction(action: {
+    anchorId: AnchorId;
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;
+/**
+ * Validate a batch of actions.
+ */
+export declare function validateActions(actions: ActionStep[]): ValidationResult;

package/dist/actions/validation-rules.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Action Validation — Rules
+ *
+ * Specific validators by action kind: badge, tooltip, modal, content
+ * (text/attrs/classes/styles/HTML), tour, sequence, parallel, wait,
+ * navigate, mountWidget, and warning detection.
+ */
+import type { ActionStep, ValidationError, ValidationWarning } from './types';
+export declare function validateBadgeAction(action: {
+    content: string;
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;
+export declare function validateTooltipAction(action: {
+    content: {
+        title?: string;
+        body: string;
+    };
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateInsertHtmlAction(action: {
+    html: string;
+    position: string;
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateSetTextAction(action: {
+    text: string;
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateSetAttrAction(action: {
+    attr: string;
+    value: string;
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateClassAction(action: {
+    className: string;
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;
+export declare function validateSetStyleAction(action: {
+    styles: Record<string, string>;
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateMountWidgetAction(action: {
+    slot: string;
+    widget: {
+        widgetId: string;
+    };
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateWaitAction(action: {
+    durationMs?: number;
+    event?: string;
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateSequenceAction(action: {
+    actions: ActionStep[];
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;
+export declare function validateParallelAction(action: {
+    actions: ActionStep[];
+    waitFor?: string;
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;
+export declare function validateNavigateAction(action: {
+    url: string;
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;
+export declare function validateModalAction(action: {
+    content: {
+        title?: string;
+        body: string;
+    };
+    size?: string;
+    ctaButtons?: {
+        label: string;
+        actionId: string;
+    }[];
+}, errors: ValidationError[], _warnings: ValidationWarning[]): void;
+export declare function validateTourAction(action: {
+    tourId: string;
+    steps: {
+        id: string;
+        action: ActionStep;
+        route?: string;
+        onAction?: Record<string, string>;
+    }[];
+}, errors: ValidationError[], warnings: ValidationWarning[]): void;

package/dist/actions/validation.d.ts

@@ -1,14 +1,8 @@
 /**
- * Action Validation
+ * Action Validation — Barrel re-export
  *
- * Validates action steps before execution.
+ * Re-exports from validation-core and validation-rules so that existing
+ * imports from './validation' continue to work unchanged.
  */
-import type { ActionStep, ValidationResult } from './types';
-/**
- * Validate an action step.
- */
-export declare function validateAction(action: ActionStep): ValidationResult;
-/**
- * Validate a batch of actions.
- */
-export declare function validateActions(actions: ActionStep[]): ValidationResult;
+export { DANGEROUS_ATTRS, MAX_HTML_LENGTH, MAX_STYLE_COUNT, validateAction, validateActions, validateAnchorAction, } from './validation-core';
+export { validateBadgeAction, validateClassAction, validateInsertHtmlAction, validateModalAction, validateMountWidgetAction, validateNavigateAction, validateParallelAction, validateSequenceAction, validateSetAttrAction, validateSetStyleAction, validateSetTextAction, validateTooltipAction, validateTourAction, validateWaitAction, } from './validation-rules';

package/dist/anchor/AnchorResolver.d.ts

@@ -11,6 +11,7 @@ export interface AnchorResolverOptions {
 export interface AnchorResolver {
     resolve(selector: string): HTMLElement | null;
     waitFor(selector: string, timeoutMs?: number): Promise<HTMLElement>;
+    /** One-shot: fires callback once when element appears, then auto-removes the watcher. */
     onAppear(selector: string, cb: (el: HTMLElement) => void): () => void;
     pendingCount(): number;
     destroy(): void;

package/dist/api-lit.d.ts

@@ -0,0 +1,84 @@
+/**
+ * SmartCanvas API (Lit variant)
+ *
+ * Entry point for the SmartCanvas SDK using LitElement instead of React.
+ * Creates and manages the canvas element, handles configuration, and
+ * coordinates between the ActionEngine and UI.
+ *
+ * The public API (SmartCanvasHandle, SmartCanvasConfig, createSmartCanvas)
+ * is identical to api.tsx — only the internal mounting uses mountLitApp()
+ * instead of mountReactApp().
+ */
+import type { ExperimentClient } from './experiments/types';
+import type { OverlayRecipeFetcher } from './overlays/fetcher';
+import type { ActionHandler, AppearanceConfig, RenderProps } from './render/types';
+import type { SmartCanvasRuntime } from './runtime';
+import { type SmartCanvasElementLit } from './SmartCanvasElementLit';
+import type { TelemetryClient } from './telemetry/types';
+import type { CanvasThemeConfig } from './theme';
+import type { CanvasConfigFetcher, CanvasConfigResponse } from './types';
+export interface SmartCanvasIntegrations {
+    experiments?: ExperimentClient;
+    telemetry?: TelemetryClient;
+}
+export interface SmartCanvasConfig {
+    target?: HTMLElement;
+    defaultOpen?: boolean;
+    tokens?: Record<string, string>;
+    fetcher?: CanvasConfigFetcher;
+    configUri?: string;
+    configUriFeatureKey?: string;
+    fetchCredentials?: RequestCredentials;
+    overlayFetcher?: OverlayRecipeFetcher;
+    overlayConfigUri?: string;
+    overlayConfigFeatureKey?: string;
+    overlayFetchCredentials?: RequestCredentials;
+    pollIntervalMs?: number;
+    integrations?: SmartCanvasIntegrations;
+    antiFlicker?: boolean | {
+        timeout?: number;
+        className?: string;
+    };
+    editorUrl?: string;
+    /**
+     * v2 Runtime instance.
+     * Required for action execution. If not provided, actions will not be applied.
+     */
+    runtime?: SmartCanvasRuntime;
+    appearance?: AppearanceConfig;
+    renderProps?: RenderProps;
+    actionHandlers?: ActionHandler;
+    /** Workspace-level theme for 3-layer inheritance (defaults → workspace → config) */
+    workspaceTheme?: CanvasThemeConfig;
+}
+/**
+ * Handle for interacting with a SmartCanvas instance.
+ */
+export interface SmartCanvasHandle {
+    el: SmartCanvasElementLit;
+    open(): void;
+    close(): void;
+    destroy(): void;
+    setTokens(tokens: Record<string, string>): void;
+    /**
+     * Get the current config.
+     */
+    getConfig(): Promise<CanvasConfigResponse>;
+    /**
+     * Enable or disable the canvas.
+     * When disabled, all actions are reverted.
+     */
+    setEnabled(enabled: boolean): Promise<void>;
+    setOverrideFetcher(fetcher: CanvasConfigFetcher): void;
+    registerTelemetryProperties(properties: Record<string, unknown>): void;
+    getSessionId(): string | undefined;
+    startSessionRecording(): void;
+    /** Track a custom event. Returns true if telemetry is available and event was sent. */
+    track(eventName: string, properties?: Record<string, unknown>): boolean;
+    /**
+     * v2 Runtime instance for context, events, state, and decisions.
+     */
+    runtime?: SmartCanvasRuntime;
+}
+export declare const createSmartCanvas: (config?: SmartCanvasConfig) => Promise<SmartCanvasHandle>;
+export { getAntiFlickerSnippet } from './antiFlicker';

package/dist/api.d.ts

@@ -6,6 +6,7 @@
  */
 import type { ExperimentClient } from './experiments/types';
 import type { OverlayRecipeFetcher } from './overlays/fetcher';
+import type { PlatformAdapter } from './platform/PlatformAdapter';
 import type { ActionHandler, AppearanceConfig, RenderProps } from './render/types';
 import type { SmartCanvasRuntime } from './runtime';
 import { type SmartCanvasElement } from './SmartCanvasElement';
@@ -45,6 +46,8 @@ export interface SmartCanvasConfig {
     actionHandlers?: ActionHandler;
     /** Workspace-level theme for 3-layer inheritance (defaults → workspace → config) */
     workspaceTheme?: CanvasThemeConfig;
+    /** Platform adapter for host-platform-specific integrations (Shopify, WordPress, etc.) */
+    platformAdapter?: PlatformAdapter;
 }
 /**
  * Handle for interacting with a SmartCanvas instance.

package/dist/apps/builtinRuntimeModules-lit.d.ts

@@ -0,0 +1,20 @@
+export declare const builtinAdaptiveManifestsLit: {
+    id: any;
+    version: any;
+    name: any;
+    description: any;
+    runtime: {
+        actions: any;
+        widgets: any;
+        notifyWatchers: any;
+        events: any;
+    };
+    editor: undefined;
+    metadata: {
+        isBuiltIn: boolean;
+    };
+}[];
+export declare function registerBuiltinRuntimeModulesLit(registry: {
+    has: (id: string) => boolean;
+    register: (manifest: any) => void;
+}): void;

package/dist/bootstrap-init.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bootstrap init helpers — token decode, host resolution, browser metadata
+ * collection, env var resolution, segment cache, and geo data fetching.
+ */
+/**
+ * Get environment variable, supporting both Vite and Next.js patterns.
+ * CSP-safe: no eval() is used. Vite env access is resolved at build time
+ * via the __VITE_IMPORT_META_ENV__ define.
+ */
+export declare function getEnvVar(name: string): string | undefined;
+/**
+ * Load cached segment attributes from localStorage.
+ * Returns cached values for instant Phase 1 evaluation.
+ */
+export declare function loadCachedSegmentAttributes(): Record<string, boolean>;
+/**
+ * Save segment attributes to localStorage for faster future loads.
+ */
+export declare function cacheSegmentAttributes(attrs: Record<string, boolean>): void;
+/**
+ * Extract segment flags (in_segment_*) from PostHog feature flags.
+ */
+export declare function extractSegmentFlags(allFlags: Record<string, boolean | string> | undefined): Record<string, boolean>;
+/**
+ * Collect browser metadata for instant GrowthBook targeting.
+ * This data is available synchronously from browser APIs — no network call needed.
+ * Only non-empty values are included.
+ */
+export declare function collectBrowserMetadata(): Record<string, string | string[]>;
+export declare const GEO_DEFAULT_HOST = "https://geo.syntrologie.com";
+/**
+ * Fetch geo data from the Cloudflare Worker, with localStorage caching.
+ * Returns cached data immediately on subsequent visits. Best-effort — never blocks init.
+ */
+export declare function fetchGeo(geoHost: string): Promise<Record<string, string>>;

package/dist/bootstrap-runtime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Bootstrap runtime phase — EventBus creation, event processor, experiment client,
+ * telemetry, runtime factory, canvas initialization, app loader, and cleanup.
+ */
+import type { SyntroInitOptions, SyntroInitResult } from './bootstrap-types';
+/** Internal init implementation — all errors propagate to the outer init() try/catch. */
+export declare function _initCore(options: SyntroInitOptions): Promise<SyntroInitResult>;

package/dist/bootstrap-types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Bootstrap type definitions — interfaces, enums, and type exports
+ * for the Syntro SDK initialization flow.
+ */
+import type { SmartCanvasConfig, SmartCanvasHandle } from './api';
+import type { AppLoader } from './apps/AppLoader';
+import type { ExperimentClient } from './experiments/types';
+import type { SessionMetricTracker } from './metrics';
+import type { SmartCanvasRuntime } from './runtime';
+import type { TelemetryClient } from './telemetry/types';
+import type { CanvasConfigFetcher } from './types';
+export interface SyntroInitOptions {
+    /**
+     * The Syntro token containing all credentials.
+     * Generated from your admin dashboard.
+     *
+     * Optional in editor mode (when editor_token is present in URL params).
+     */
+    token?: string;
+    /**
+     * Optional canvas configuration overrides.
+     */
+    canvas?: Partial<Omit<SmartCanvasConfig, 'integrations' | 'fetcher'>>;
+    /**
+     * Custom config fetcher to override the default experiment-based fetcher.
+     * Use this for local development or when bypassing the experiment server.
+     *
+     * When provided, this fetcher is used instead of the experiments-based config lookup.
+     * The token's telemetry credentials (t field) are still used if present.
+     */
+    fetcher?: CanvasConfigFetcher;
+    /**
+     * @deprecated Session metrics are always enabled. This flag has no effect.
+     */
+    enableSessionMetrics?: boolean;
+    /**
+     * CDN base URL for loading adaptive bundles.
+     * Adaptives are loaded from: {cdnBase}/adaptives/{appId}/index.js
+     *
+     * @default "https://cdn.syntrologie.com"
+     */
+    cdnBase?: string;
+    /**
+     * @deprecated Core app executors are now registered synchronously.
+     * This option has no effect and will be removed in a future version.
+     */
+    registerBuiltInApps?: boolean;
+    /**
+     * Enable debug mode. emit() returns EmitResult, all events logged to console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Enable test mode. PostHog capture skipped, toasts not rendered,
+     * full event history retained (uncapped).
+     * @default false
+     */
+    testMode?: boolean;
+    /**
+     * App-provided signal values set at init time. Merged into SDK attributes
+     * alongside auto-collected browser/geo signals for local flag evaluation.
+     *
+     * Use this when the host environment (MCP server, agent, etc.) provides
+     * signal values that the SDK can't auto-collect from the browser.
+     *
+     * Tracked as a discrete PostHog event (app_signals_init) on init.
+     */
+    appSignalsInit?: Record<string, string>;
+}
+export interface SyntroInitResult {
+    /**
+     * The SmartCanvas handle for controlling the canvas.
+     */
+    canvas: SmartCanvasHandle;
+    /**
+     * The unified v2 runtime with all providers.
+     * Use this to access telemetry, context, events, and state.
+     */
+    runtime: SmartCanvasRuntime;
+    /**
+     * The experiment client, if experiments are configured in the token.
+     * @deprecated Access via runtime.telemetry or use DecisionStrategy instead
+     */
+    experiments?: ExperimentClient;
+    /**
+     * The telemetry client, if telemetry is configured in the token.
+     * @deprecated Access via runtime.telemetry instead
+     */
+    telemetry?: TelemetryClient;
+    /**
+     * The session metric tracker, if enableSessionMetrics is true.
+     * @deprecated Access via runtime.sessionMetrics instead
+     */
+    sessionMetrics?: SessionMetricTracker;
+    /**
+     * App loader for loading external apps from CDN.
+     * Exposed for manual app loading if needed.
+     */
+    appLoader: AppLoader;
+}

package/dist/bootstrap.d.ts

@@ -16,89 +16,12 @@
  * runtime.state.dismissals.mark('my-tile');
  * ```
  */
-import { type SmartCanvasConfig, type SmartCanvasHandle } from './api';
 import type { appRegistry } from './apps';
-import { type AppLoader } from './apps/AppLoader';
-import type { ExperimentClient } from './experiments/types';
-import { type SessionMetricTracker } from './metrics';
-import { type SmartCanvasRuntime } from './runtime';
-import type { TelemetryClient } from './telemetry/types';
+import type { SmartCanvasRuntime } from './runtime';
+import type { InterventionTracker } from './telemetry/InterventionTracker';
 import { decodeToken, encodeToken } from './token';
-import type { CanvasConfigFetcher } from './types';
-export interface SyntroInitOptions {
-    /**
-     * The Syntro token containing all credentials.
-     * Generated from your admin dashboard.
-     *
-     * Optional in editor mode (when editor_token is present in URL params).
-     */
-    token?: string;
-    /**
-     * Optional canvas configuration overrides.
-     */
-    canvas?: Partial<Omit<SmartCanvasConfig, 'integrations' | 'fetcher'>>;
-    /**
-     * Custom config fetcher to override the default experiment-based fetcher.
-     * Use this for local development or when bypassing the experiment server.
-     *
-     * When provided, this fetcher is used instead of the experiments-based config lookup.
-     * The token's telemetry credentials (t field) are still used if present.
-     */
-    fetcher?: CanvasConfigFetcher;
-    /**
-     * @deprecated Session metrics are always enabled. This flag has no effect.
-     */
-    enableSessionMetrics?: boolean;
-    /**
-     * CDN base URL for loading adaptive bundles.
-     * Adaptives are loaded from: {cdnBase}/adaptives/{appId}/index.js
-     *
-     * @default "https://cdn.syntrologie.com"
-     */
-    cdnBase?: string;
-    /**
-     * @deprecated Core app executors are now registered synchronously.
-     * This option has no effect and will be removed in a future version.
-     */
-    registerBuiltInApps?: boolean;
-}
-export interface SyntroInitResult {
-    /**
-     * The SmartCanvas handle for controlling the canvas.
-     */
-    canvas: SmartCanvasHandle;
-    /**
-     * The unified v2 runtime with all providers.
-     * Use this to access telemetry, context, events, and state.
-     */
-    runtime: SmartCanvasRuntime;
-    /**
-     * The experiment client, if experiments are configured in the token.
-     * @deprecated Access via runtime.telemetry or use DecisionStrategy instead
-     */
-    experiments?: ExperimentClient;
-    /**
-     * The telemetry client, if telemetry is configured in the token.
-     * @deprecated Access via runtime.telemetry instead
-     */
-    telemetry?: TelemetryClient;
-    /**
-     * The session metric tracker, if enableSessionMetrics is true.
-     * @deprecated Access via runtime.sessionMetrics instead
-     */
-    sessionMetrics?: SessionMetricTracker;
-    /**
-     * App loader for loading external apps from CDN.
-     * Exposed for manual app loading if needed.
-     */
-    appLoader: AppLoader;
-}
-/**
- * Collect browser metadata for instant GrowthBook targeting.
- * This data is available synchronously from browser APIs — no network call needed.
- * Only non-empty values are included.
- */
-export declare function collectBrowserMetadata(): Record<string, string | string[]>;
+export { collectBrowserMetadata, fetchGeo } from './bootstrap-init';
+export type { SyntroInitOptions, SyntroInitResult } from './bootstrap-types';
 /**
  * Initialize the Syntro SDK with a single token.
  *
@@ -112,7 +35,17 @@ export declare function collectBrowserMetadata(): Record<string, string | string
  * @param options - Initialization options
  * @returns The initialized SDK components
  */
-declare function init(options: SyntroInitOptions): Promise<SyntroInitResult>;
+declare function init(options: import('./bootstrap-types').SyntroInitOptions): Promise<import('./bootstrap-types').SyntroInitResult | undefined>;
+/**
+ * Emit a custom event through the SDK.
+ *
+ * Events flow through the EventBus (tile notification rule matching)
+ * and PostHog (analytics). Event names must use the `app:` prefix.
+ *
+ * @param eventName - Event name (e.g., 'app:setup:sdk_connected')
+ * @param props - Optional event properties
+ */
+declare function emit(eventName: string, props?: Record<string, unknown>): void;
 /**
  * The Syntro namespace for single-token initialization.
  */
@@ -120,6 +53,9 @@ export declare const Syntro: {
     init: typeof init;
     encodeToken: typeof encodeToken;
     decodeToken: typeof decodeToken;
+    events: {
+        emit: typeof emit;
+    };
 };
 declare global {
     interface Window {
@@ -128,7 +64,7 @@ declare global {
             appRegistry: typeof appRegistry;
             runtime: SmartCanvasRuntime;
             version: string;
+            interventionTracker?: InterventionTracker;
         };
     }
 }
-export {};