@syntrologie/runtime-sdk 1.0.1 → 2.0.0-canary.1

package/dist/api.d.ts

@@ -1,9 +1,16 @@
+/**
+ * SmartCanvas API
+ *
+ * Entry point for the SmartCanvas SDK. Creates and manages the canvas element,
+ * handles configuration, and coordinates between the ActionEngine and UI.
+ */
 import { SmartCanvasElement } from "./SmartCanvasElement";
 import type { ExperimentClient } from "./experiments/types";
 import type { TelemetryClient } from "./telemetry/types";
-import type { CanvasConfigFetcher } from "./types";
+import type { CanvasConfigFetcher, CanvasConfigResponse } from "./types";
 import type { OverlayRecipeFetcher } from "./overlays/fetcher";
 import type { CanvasTheme } from "./components/ShadowCanvasOverlay";
+import type { SmartCanvasRuntime } from "./runtime";
 import type { RenderProps, ActionHandler, AppearanceConfig } from "./render/types";
 export interface SmartCanvasIntegrations {
     experiments?: ExperimentClient;
@@ -27,16 +34,16 @@ export interface SmartCanvasConfig {
         timeout?: number;
         className?: string;
     };
-    earlyPatching?: boolean;
     editorUrl?: string;
     theme?: Partial<CanvasTheme>;
-    /** Enable automatic theme extraction from host page CSS variables */
+    /**
+     * v2 Runtime instance.
+     * Required for action execution. If not provided, actions will not be applied.
+     */
+    runtime?: SmartCanvasRuntime;
     autoDetectTheme?: boolean;
-    /** Theme appearance overrides (CSS variables, base theme) */
     appearance?: AppearanceConfig;
-    /** Render props for customizing tile/block rendering */
     renderProps?: RenderProps;
-    /** Action handlers for interactive blocks */
     actionHandlers?: ActionHandler;
 }
 /**
@@ -46,31 +53,38 @@ export interface MountableComponent {
     mount(container: HTMLElement, props: any): void | (() => void);
 }
 export type { TileComponent, TileComponentProps } from "./types";
+/**
+ * Handle for interacting with a SmartCanvas instance.
+ */
 export interface SmartCanvasHandle {
     el: SmartCanvasElement;
     open(): void;
     close(): void;
     destroy(): void;
     setTokens(tokens: Record<string, string>): void;
-    getConfig(): Promise<any>;
-    updateConfig(newConfig: any): void;
-    setEnabled(enabled: boolean): void;
-    registerComponent(key: string, component: MountableComponent): void;
-    setOverrideFetcher(fetcher: any): void;
     /**
-     * Register properties on the telemetry client (e.g., for session tagging).
-     * Used by editor SDK to tag crawler sessions with canonical IDs.
+     * Get the current config.
      */
-    registerTelemetryProperties(properties: Record<string, unknown>): void;
+    getConfig(): Promise<CanvasConfigResponse>;
     /**
-     * Get the current PostHog session ID.
+     * Update the config and re-apply actions.
+     * This is the primary way to modify what the canvas displays.
      */
-    getSessionId(): string | undefined;
+    updateConfig(newConfig: CanvasConfigResponse): Promise<void>;
     /**
-     * Force start session recording.
-     * Used by editor SDK to bypass bot detection for crawler sessions.
+     * Enable or disable the canvas.
+     * When disabled, all actions are reverted.
      */
+    setEnabled(enabled: boolean): Promise<void>;
+    registerComponent(key: string, component: MountableComponent): void;
+    setOverrideFetcher(fetcher: CanvasConfigFetcher): void;
+    registerTelemetryProperties(properties: Record<string, unknown>): void;
+    getSessionId(): string | undefined;
     startSessionRecording(): void;
+    /**
+     * v2 Runtime instance for context, events, state, and decisions.
+     */
+    runtime?: SmartCanvasRuntime;
 }
 export declare const createSmartCanvas: (config?: SmartCanvasConfig) => Promise<SmartCanvasHandle>;
 declare global {

package/dist/api.js

@@ -1,7 +1,12 @@
+/**
+ * SmartCanvas API
+ *
+ * Entry point for the SmartCanvas SDK. Creates and manages the canvas element,
+ * handles configuration, and coordinates between the ActionEngine and UI.
+ */
 import { registerSmartCanvasElement } from "./SmartCanvasElement";
 import { createCanvasConfigFetcher } from "./configFetcher";
 import { initAntiFlicker } from "./antiFlicker";
-import { applyPatchesEarly, extractPatchesFromConfig, revertAllPatches } from "./earlyPatcher";
 import { loadEditorSdk, getActiveSdkMode } from "./editorLoader";
 export const createSmartCanvas = async (config = {}) => {
     var _a, _b, _c;
@@ -14,44 +19,60 @@ export const createSmartCanvas = async (config = {}) => {
         const antiFlickerConfig = typeof config.antiFlicker === 'object' ? config.antiFlicker : {};
         removeAntiFlicker = initAntiFlicker(antiFlickerConfig);
     }
-    // Store current config and fetcher to expose to editor
+    // State
     let currentConfig = null;
     let currentFetcher = null;
-    // Apply patches early if enabled and we have a fetcher
-    if (config.earlyPatching !== false && config.fetcher) {
+    let currentBatchHandle = null;
+    let isEnabled = true;
+    const runtime = config.runtime;
+    /**
+     * Apply actions from config via ActionEngine.
+     */
+    async function applyActions(actions) {
+        if (!(runtime === null || runtime === void 0 ? void 0 : runtime.actions) || actions.length === 0) {
+            return;
+        }
+        // Revert previous actions
+        if (currentBatchHandle === null || currentBatchHandle === void 0 ? void 0 : currentBatchHandle.isApplied()) {
+            await currentBatchHandle.revertAll();
+        }
+        // Apply new actions
+        currentBatchHandle = await runtime.actions.applyBatch(actions);
+    }
+    /**
+     * Revert all current actions.
+     */
+    async function revertActions() {
+        if (currentBatchHandle === null || currentBatchHandle === void 0 ? void 0 : currentBatchHandle.isApplied()) {
+            await currentBatchHandle.revertAll();
+            currentBatchHandle = null;
+        }
+    }
+    // Apply initial config if fetcher provided
+    if (config.fetcher) {
         try {
             currentFetcher = config.fetcher;
             const canvasConfig = await config.fetcher();
-            currentConfig = canvasConfig; // Save for editor
-            const patches = extractPatchesFromConfig(canvasConfig);
-            if (patches.length > 0) {
-                applyPatchesEarly({
-                    patches,
-                    onComplete: () => {
-                        // Remove anti-flicker after patches are applied
-                        if (removeAntiFlicker) {
-                            removeAntiFlicker();
-                            removeAntiFlicker = null;
-                        }
-                    }
-                });
+            currentConfig = canvasConfig;
+            if (canvasConfig.actions.length > 0 && (runtime === null || runtime === void 0 ? void 0 : runtime.actions)) {
+                await applyActions(canvasConfig.actions);
             }
         }
         catch (error) {
-            console.error('[SmartCanvas] Error applying early patches:', error);
+            console.error('[SmartCanvas] Error fetching/applying initial config:', error);
         }
     }
-    // Remove anti-flicker if not already removed
+    // Remove anti-flicker
     if (removeAntiFlicker) {
         removeAntiFlicker();
     }
-    // Check if we should load the editor (for editor mode or audit mode)
+    // Load editor SDK if in editor/audit mode
     const sdkMode = getActiveSdkMode();
     if (sdkMode) {
         console.log(`[SmartCanvas] Loading editor SDK for ${sdkMode} mode`);
-        // We don't await this so the runtime SDK can continue initializing
         loadEditorSdk(config.editorUrl).catch(console.error);
     }
+    // Create the canvas element
     registerSmartCanvasElement();
     const host = document.createElement("smart-canvas");
     if (config.tokens) {
@@ -82,7 +103,6 @@ export const createSmartCanvas = async (config = {}) => {
         featureKey: config.configUriFeatureKey,
         credentials: config.fetchCredentials,
     });
-    // Store the initial fetcher if not already set
     if (!currentFetcher) {
         currentFetcher = fetcher;
     }
@@ -91,6 +111,7 @@ export const createSmartCanvas = async (config = {}) => {
         pollIntervalMs: config.pollIntervalMs,
         experiments,
         telemetry,
+        runtime,
         overlayFetcher: config.overlayFetcher,
         overlayConfigUri: config.overlayConfigUri,
         overlayConfigFeatureKey: config.overlayConfigFeatureKey,
@@ -108,14 +129,16 @@ export const createSmartCanvas = async (config = {}) => {
         el: host,
         open: () => host.open(),
         close: () => host.close(),
-        destroy: () => host.remove(),
+        destroy: () => {
+            revertActions();
+            host.remove();
+        },
         setTokens: (tokens) => {
             for (const [key, value] of Object.entries(tokens)) {
                 host.style.setProperty(key, value);
             }
         },
         getConfig: async () => {
-            // Use current fetcher to get fresh config
             if (currentFetcher) {
                 try {
                     const freshConfig = await currentFetcher();
@@ -128,25 +151,21 @@ export const createSmartCanvas = async (config = {}) => {
             }
             return currentConfig;
         },
-        updateConfig: (newConfig) => {
+        updateConfig: async (newConfig) => {
             currentConfig = newConfig;
-            // Re-apply patches
-            const patches = extractPatchesFromConfig(newConfig);
-            if (patches.length > 0) {
-                applyPatchesEarly({ patches });
+            if (isEnabled) {
+                await applyActions(newConfig.actions);
             }
         },
-        setEnabled: (enabled) => {
+        setEnabled: async (enabled) => {
+            isEnabled = enabled;
             if (enabled) {
                 if (currentConfig) {
-                    const patches = extractPatchesFromConfig(currentConfig);
-                    if (patches.length > 0) {
-                        applyPatchesEarly({ patches });
-                    }
+                    await applyActions(currentConfig.actions);
                 }
             }
             else {
-                revertAllPatches();
+                await revertActions();
             }
         },
         registerComponent: (key, Component) => host.registerComponent(key, Component),
@@ -166,11 +185,9 @@ export const createSmartCanvas = async (config = {}) => {
             var _a;
             (_a = telemetry === null || telemetry === void 0 ? void 0 : telemetry.startSessionRecording) === null || _a === void 0 ? void 0 : _a.call(telemetry);
         },
+        runtime,
     };
-    // Expose handle for editor SDK access
-    // In editor/audit mode: always expose (editor needs it to inject tiles and save config)
-    // In dev mode: always expose (for debugging)
-    // In production: never expose (security)
+    // Expose handle for editor SDK access (only in editor/dev mode)
     if (typeof window !== "undefined") {
         const isDev = process.env.NODE_ENV === 'development';
         if (sdkMode || isDev) {

package/dist/api.js.map

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

package/dist/apps/AppContext.d.ts

@@ -0,0 +1,31 @@
+/**
+ * App Context
+ *
+ * Provides a sandboxed runtime context for apps.
+ * Apps receive an AppContext when they activate, giving them controlled
+ * access to runtime functionality.
+ */
+import type { SmartCanvasRuntime } from "../runtime";
+import type { AppContext } from "./types";
+/**
+ * Options for creating an AppContext.
+ */
+export interface CreateAppContextOptions {
+    /** The app ID */
+    appId: string;
+    /** The runtime instance */
+    runtime: SmartCanvasRuntime;
+    /** Whether this is a built-in app (prevents executor override) */
+    isBuiltIn?: boolean;
+}
+/**
+ * Create a sandboxed AppContext for an app.
+ *
+ * The context provides controlled access to runtime functionality,
+ * with state namespaced to the app.
+ */
+export declare function createAppContext(options: CreateAppContextOptions): AppContext;
+/**
+ * Clean up all resources registered by an app context.
+ */
+export declare function cleanupAppContext(appId: string, runtime: SmartCanvasRuntime): void;

package/dist/apps/AppContext.js

@@ -0,0 +1,93 @@
+/**
+ * App Context
+ *
+ * Provides a sandboxed runtime context for apps.
+ * Apps receive an AppContext when they activate, giving them controlled
+ * access to runtime functionality.
+ */
+/**
+ * Create a sandboxed AppContext for an app.
+ *
+ * The context provides controlled access to runtime functionality,
+ * with state namespaced to the app.
+ */
+export function createAppContext(options) {
+    const { appId, runtime, isBuiltIn = false } = options;
+    const statePrefix = `app:${appId}:`;
+    // Track registered actions and widgets for cleanup
+    const registeredActions = [];
+    const registeredWidgets = [];
+    // Get or create namespaced storage for this app
+    const appStorage = runtime.state.ns(`app:${appId}`);
+    const context = {
+        appId,
+        // Namespaced state access (using session storage scoped to this app)
+        state: {
+            get: (key) => appStorage.get(key),
+            set: (key, value) => appStorage.set(key, value),
+            remove: (key) => appStorage.remove(key),
+        },
+        // Telemetry access (if available) - using EventBus for custom events
+        telemetry: runtime.telemetry
+            ? {
+                emit: (eventName, props) => {
+                    // Use EventBus to emit custom events since TelemetryClient doesn't have generic emit
+                    runtime.events.publish(eventName, {
+                        ...props,
+                        _appId: appId,
+                    });
+                },
+                getSessionId: () => { var _a, _b; return (_b = (_a = runtime.telemetry) === null || _a === void 0 ? void 0 : _a.getSessionId) === null || _b === void 0 ? void 0 : _b.call(_a); },
+            }
+            : undefined,
+        // Surfaces access
+        surfaces: {
+            mount: (slot, content, opts) => {
+                const handle = runtime.surfaces.mount(slot, content, {
+                    ...opts,
+                    adaptiveId: appId,
+                });
+                return {
+                    unmount: () => handle.unmount(),
+                    update: (newContent) => handle.update(newContent),
+                };
+            },
+            canMount: (slot, priority) => runtime.surfaces.canMount(slot, priority),
+        },
+        // Events access
+        events: {
+            subscribe: (callback) => {
+                return runtime.events.subscribe((event) => {
+                    callback(event);
+                });
+            },
+            publish: (name, props) => {
+                runtime.events.publish(name, {
+                    ...props,
+                    _appId: appId,
+                });
+            },
+        },
+        // Action registration
+        registerAction: (definition) => {
+            runtime.executors.register(definition.kind, definition.executor, definition.schema, appId, isBuiltIn);
+            registeredActions.push(definition.kind);
+        },
+        // Widget registration
+        registerWidget: (definition) => {
+            runtime.widgets.register(definition.id, definition.component, appId, definition.metadata);
+            registeredWidgets.push(definition.id);
+        },
+    };
+    return context;
+}
+/**
+ * Clean up all resources registered by an app context.
+ */
+export function cleanupAppContext(appId, runtime) {
+    // Unregister all executors from this app
+    runtime.executors.unregisterBySource(appId);
+    // Unregister all widgets from this app
+    runtime.widgets.unregisterBySource(appId);
+}
+//# sourceMappingURL=AppContext.js.map

package/dist/apps/AppContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppContext.js","sourceRoot":"","sources":["../../src/apps/AppContext.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACtD,MAAM,WAAW,GAAG,OAAO,KAAK,GAAG,CAAC;IAEpC,mDAAmD;IACnD,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,MAAM,iBAAiB,GAAa,EAAE,CAAC;IAEvC,gDAAgD;IAChD,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAe;QAC1B,KAAK;QAEL,qEAAqE;QACrE,KAAK,EAAE;YACL,GAAG,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;YACzC,GAAG,EAAE,CAAC,GAAW,EAAE,KAAc,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC;YAChE,MAAM,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC;SAChD;QAED,qEAAqE;QACrE,SAAS,EAAE,OAAO,CAAC,SAAS;YAC1B,CAAC,CAAC;gBACE,IAAI,EAAE,CAAC,SAAiB,EAAE,KAA+B,EAAE,EAAE;oBAC3D,qFAAqF;oBACrF,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE;wBAChC,GAAG,KAAK;wBACR,MAAM,EAAE,KAAK;qBACd,CAAC,CAAC;gBACL,CAAC;gBACD,YAAY,EAAE,GAAG,EAAE,eAAC,OAAA,MAAA,MAAA,OAAO,CAAC,SAAS,0CAAE,YAAY,kDAAI,CAAA,EAAA;aACxD;YACH,CAAC,CAAC,SAAS;QAEb,kBAAkB;QAClB,QAAQ,EAAE;YACR,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;gBAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAW,EAAE,OAAc,EAAE;oBACjE,GAAI,IAAY;oBAChB,UAAU,EAAE,KAAK;iBAClB,CAAC,CAAC;gBACH,OAAO;oBACL,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE;oBAC/B,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,UAAiB,CAAC;iBACzD,CAAC;YACJ,CAAC;YACD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAW,EAAE,QAAQ,CAAC;SAC/E;QAED,gBAAgB;QAChB,MAAM,EAAE;YACN,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE;gBACtB,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;oBACxC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClB,CAAC,CAAC,CAAC;YACL,CAAC;YACD,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBACvB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;oBAC3B,GAAG,KAAK;oBACR,MAAM,EAAE,KAAK;iBACd,CAAC,CAAC;YACL,CAAC;SACF;QAED,sBAAsB;QACtB,cAAc,EAAE,CAAC,UAA+B,EAAE,EAAE;YAClD,OAAO,CAAC,SAAS,CAAC,QAAQ,CACxB,UAAU,CAAC,IAAI,EACf,UAAU,CAAC,QAAQ,EACnB,UAAU,CAAC,MAAM,EACjB,KAAK,EACL,SAAS,CACV,CAAC;YACF,iBAAiB,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,sBAAsB;QACtB,cAAc,EAAE,CAAC,UAA+B,EAAE,EAAE;YAClD,OAAO,CAAC,OAAO,CAAC,QAAQ,CACtB,UAAU,CAAC,EAAE,EACb,UAAU,CAAC,SAAS,EACpB,KAAK,EACL,UAAU,CAAC,QAAQ,CACpB,CAAC;YACF,iBAAiB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACxC,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,OAA2B;IAC1E,yCAAyC;IACzC,OAAO,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAE5C,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC"}

package/dist/apps/AppLoader.d.ts

@@ -0,0 +1,84 @@
+/**
+ * App Loader
+ *
+ * Handles loading apps from CDN based on canvas config requirements.
+ *
+ * Loading Strategy:
+ * 1. Core apps (built-in actions) are bundled with runtime - no loading needed
+ * 2. External apps are loaded from CDN when config references them
+ *
+ * The loader determines which apps are needed by scanning the canvas config for:
+ * - Action kinds with namespaces (e.g., "gamification:awardBadge")
+ * - Widget IDs with namespaces (e.g., "gamification:leaderboard")
+ * - Explicit app references in config
+ */
+import type { AppManifest } from "./types";
+import type { AppRegistry } from "./AppRegistry";
+/**
+ * App loading options.
+ */
+export interface AppLoaderOptions {
+    /** Base URL for CDN app bundles */
+    cdnBase: string;
+    /** App registry to register loaded apps */
+    registry: AppRegistry;
+    /** Timeout for loading apps (ms) */
+    timeout?: number;
+    /** Callback when an app starts loading */
+    onLoadStart?: (appId: string) => void;
+    /** Callback when an app finishes loading */
+    onLoadEnd?: (appId: string, success: boolean, error?: string) => void;
+}
+/**
+ * App load result.
+ */
+export interface AppLoadResult {
+    appId: string;
+    success: boolean;
+    error?: string;
+    manifest?: AppManifest;
+}
+/**
+ * Canvas config for determining which apps to load.
+ */
+export interface CanvasConfigForLoader {
+    /** Actions in the config */
+    actions?: Array<{
+        kind: string;
+        [key: string]: unknown;
+    }>;
+    /** Explicit app IDs to load */
+    apps?: string[];
+    /** Widgets referenced in actions */
+    widgets?: Array<{
+        widgetId?: string;
+        widget?: {
+            widgetId: string;
+        };
+    }>;
+}
+/**
+ * Check if an action kind is a core action.
+ */
+export declare function isCoreActionKind(kind: string): boolean;
+/**
+ * Extract app ID from a namespaced action kind.
+ * e.g., "gamification:awardBadge" → "gamification"
+ */
+export declare function getAppIdFromActionKind(kind: string): string | null;
+/**
+ * Extract app ID from a namespaced widget ID.
+ * e.g., "gamification:leaderboard" → "gamification"
+ */
+export declare function getAppIdFromWidgetId(widgetId: string): string | null;
+/**
+ * Create an app loader instance.
+ */
+export declare function createAppLoader(options: AppLoaderOptions): {
+    loadApp: (appId: string) => Promise<AppLoadResult>;
+    loadAppsForConfig: (config: CanvasConfigForLoader) => Promise<AppLoadResult[]>;
+    preloadApps: (appIds: string[]) => Promise<AppLoadResult[]>;
+    getRequiredApps: (config: CanvasConfigForLoader) => string[];
+    getAppUrl: (appId: string) => string;
+};
+export type AppLoader = ReturnType<typeof createAppLoader>;