@syntrologie/runtime-sdk 0.2.21 → 1.0.0

package/dist/actions/ActionEngine.js

@@ -0,0 +1,272 @@
+/**
+ * ActionEngine
+ *
+ * Unified execution layer for interventions. Provides a high-level API for
+ * applying, reverting, and managing action steps.
+ */
+import { executorRegistry as defaultExecutorRegistry } from './executors';
+import { validateAction, validateActions } from './validation';
+/** Counter for generating unique action IDs */
+let actionIdCounter = 0;
+/**
+ * Create an ActionEngine instance.
+ */
+export function createActionEngine(options) {
+    const { overlayRoot, eventBus, surfaces, anchorResolver, adaptiveId, executorRegistry = defaultExecutorRegistry, } = options;
+    /** Map of active actions by ID */
+    const activeActions = new Map();
+    /**
+     * Generate a unique action ID.
+     */
+    function generateId() {
+        return `action-${++actionIdCounter}`;
+    }
+    /**
+     * Publish an event to the EventBus if available.
+     */
+    function publishEvent(name, props) {
+        if (eventBus) {
+            eventBus.publish(name, props);
+        }
+    }
+    /**
+     * Create the executor context.
+     */
+    function createExecutorContext() {
+        return {
+            overlayRoot,
+            resolveAnchor: anchorResolver,
+            generateId,
+            publishEvent,
+            adaptiveId,
+            // Allow composite executors (like tours) to execute nested actions
+            applyAction: apply,
+            // Allow composite executors to subscribe to events
+            subscribeEvent: eventBus
+                ? (name, callback) => eventBus.subscribe({ names: [name] }, (event) => callback(event.props))
+                : undefined,
+        };
+    }
+    /**
+     * Execute a mountWidget action via Surfaces.
+     */
+    async function executeMountWidget(action, context) {
+        if (!surfaces) {
+            throw new Error('Surfaces provider required for core:mountWidget actions');
+        }
+        const handle = surfaces.mount(action.slot, {
+            type: 'widget',
+            widgetId: action.widget.widgetId,
+            config: action.widget.props,
+        }, {
+            priority: action.widget.priority,
+        });
+        context.publishEvent('action.applied', {
+            id: context.generateId(),
+            kind: 'core:mountWidget',
+            slot: action.slot,
+            widgetId: action.widget.widgetId,
+        });
+        return {
+            cleanup: () => {
+                handle.unmount();
+            },
+            updateFn: (changes) => {
+                if ('widget' in changes && changes.widget) {
+                    const w = changes.widget;
+                    if (w.props) {
+                        handle.update({
+                            type: 'widget',
+                            widgetId: action.widget.widgetId,
+                            config: w.props,
+                        });
+                    }
+                }
+            },
+        };
+    }
+    /**
+     * Apply a single action.
+     */
+    async function apply(action) {
+        const validation = validateAction(action);
+        if (!validation.valid) {
+            const errorMessages = validation.errors.map((e) => e.message).join('; ');
+            throw new Error(`Action validation failed: ${errorMessages}`);
+        }
+        const id = generateId();
+        const context = createExecutorContext();
+        let result;
+        // Special handling for mountWidget
+        if (action.kind === 'core:mountWidget') {
+            result = await executeMountWidget(action, context);
+        }
+        else {
+            const executor = executorRegistry.get(action.kind);
+            if (!executor) {
+                throw new Error(`No executor for action kind: ${action.kind}`);
+            }
+            result = await executor(action, context);
+        }
+        // Track active action
+        const entry = {
+            id,
+            action,
+            adaptiveId,
+            appliedTs: Date.now(),
+            state: 'applied',
+            cleanup: result.cleanup,
+            updateFn: result.updateFn,
+        };
+        activeActions.set(id, entry);
+        // Publish applied event
+        publishEvent('action.applied', {
+            id,
+            kind: action.kind,
+            anchorId: 'anchorId' in action ? action.anchorId : undefined,
+        });
+        // Create and return handle
+        const handle = {
+            id,
+            action,
+            async revert() {
+                const entry = activeActions.get(id);
+                if (!entry || entry.state !== 'applied')
+                    return;
+                try {
+                    await entry.cleanup();
+                    entry.state = 'reverted';
+                    publishEvent('action.reverted', { id, kind: action.kind });
+                }
+                catch (error) {
+                    entry.state = 'failed';
+                    publishEvent('action.failed', {
+                        id,
+                        kind: action.kind,
+                        error: String(error),
+                    });
+                    throw error;
+                }
+                finally {
+                    activeActions.delete(id);
+                }
+            },
+            isApplied() {
+                const entry = activeActions.get(id);
+                return (entry === null || entry === void 0 ? void 0 : entry.state) === 'applied';
+            },
+            async update(changes) {
+                const entry = activeActions.get(id);
+                if (!entry || entry.state !== 'applied') {
+                    throw new Error('Cannot update action that is not applied');
+                }
+                if (entry.updateFn) {
+                    await entry.updateFn(changes);
+                }
+                else {
+                    throw new Error(`Action kind ${action.kind} does not support updates`);
+                }
+            },
+            getState() {
+                var _a;
+                const entry = activeActions.get(id);
+                return (_a = entry === null || entry === void 0 ? void 0 : entry.state) !== null && _a !== void 0 ? _a : 'reverted';
+            },
+        };
+        return handle;
+    }
+    /**
+     * Apply multiple actions as a batch.
+     */
+    async function applyBatch(actions) {
+        const validation = validateActions(actions);
+        if (!validation.valid) {
+            const errorMessages = validation.errors.map((e) => e.message).join('; ');
+            throw new Error(`Batch validation failed: ${errorMessages}`);
+        }
+        const batchId = generateId();
+        const handles = [];
+        const appliedHandles = [];
+        try {
+            for (const action of actions) {
+                const handle = await apply(action);
+                handles.push(handle);
+                appliedHandles.push(handle);
+            }
+        }
+        catch (error) {
+            // Rollback on failure
+            for (const handle of appliedHandles) {
+                try {
+                    await handle.revert();
+                }
+                catch {
+                    // Ignore cleanup errors during rollback
+                }
+            }
+            throw error;
+        }
+        const batchHandle = {
+            id: batchId,
+            handles,
+            async revertAll() {
+                // Revert in reverse order
+                for (let i = handles.length - 1; i >= 0; i--) {
+                    try {
+                        await handles[i].revert();
+                    }
+                    catch (error) {
+                        console.error(`[ActionEngine] Error reverting action ${handles[i].id}:`, error);
+                    }
+                }
+            },
+            isApplied() {
+                return handles.every((h) => h.isApplied());
+            },
+        };
+        return batchHandle;
+    }
+    /**
+     * Validate an action without applying it.
+     */
+    function validate(action) {
+        return validateAction(action);
+    }
+    /**
+     * Get all currently active actions.
+     */
+    function getActive() {
+        return Array.from(activeActions.values()).map((entry) => ({
+            id: entry.id,
+            action: entry.action,
+            adaptiveId: entry.adaptiveId,
+            appliedTs: entry.appliedTs,
+            state: entry.state,
+        }));
+    }
+    /**
+     * Clean up all active actions.
+     */
+    function destroy() {
+        // Revert all active actions
+        for (const entry of activeActions.values()) {
+            if (entry.state === 'applied') {
+                try {
+                    entry.cleanup();
+                }
+                catch (error) {
+                    console.error(`[ActionEngine] Error during cleanup:`, error);
+                }
+            }
+        }
+        activeActions.clear();
+    }
+    return {
+        apply,
+        applyBatch,
+        validate,
+        getActive,
+        destroy,
+    };
+}
+//# sourceMappingURL=ActionEngine.js.map

package/dist/actions/ActionEngine.js.map

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

package/dist/actions/executors/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Action Executor Registry
+ *
+ * Extensible registry that maps action kinds to their executor functions.
+ * Apps can register custom executors at runtime.
+ *
+ * Core app executors are imported from their respective app packages.
+ */
+import type { ZodSchema } from 'zod';
+import type { ActionStep, ActionKind, ActionExecutor, ValidationResult } from '../types';
+/**
+ * Registration entry for an executor.
+ */
+export interface ExecutorRegistration {
+    kind: string;
+    executor: ActionExecutor<any>;
+    schema?: ZodSchema;
+    source: string;
+    isBuiltIn: boolean;
+}
+/**
+ * Extensible registry for action executors.
+ *
+ * Core executors (setText, highlight, etc.) are registered synchronously
+ * at construction time for immediate availability - no async loading.
+ *
+ * External app executors are registered when apps activate.
+ */
+export declare class ExecutorRegistry {
+    private executors;
+    /**
+     * Constructor - registers core executors synchronously.
+     * These are available IMMEDIATELY when the module loads,
+     * enabling instant action execution without waiting for app activation.
+     */
+    constructor();
+    /**
+     * Register a core executor (synchronous, built-in, cannot be overridden).
+     */
+    private registerCore;
+    /**
+     * Register an executor for an action kind.
+     *
+     * @param kind - The action kind (e.g., "gamification:awardBadge")
+     * @param executor - The executor function
+     * @param schema - Optional Zod schema for validation
+     * @param source - The source app ID (for tracking)
+     * @param isBuiltIn - Whether this is from a built-in app (prevents override)
+     */
+    register(kind: string, executor: ActionExecutor<any>, schema?: ZodSchema, source?: string, isBuiltIn?: boolean): void;
+    /**
+     * Unregister an executor.
+     *
+     * @param kind - The action kind to unregister
+     * @returns true if the executor was unregistered, false if not found or built-in
+     */
+    unregister(kind: string): boolean;
+    /**
+     * Unregister all executors from a specific source.
+     *
+     * @param source - The source app ID
+     */
+    unregisterBySource(source: string): void;
+    /**
+     * Get the executor for an action kind.
+     */
+    get(kind: string): ActionExecutor<ActionStep> | undefined;
+    /**
+     * Get the full registration for an action kind.
+     */
+    getRegistration(kind: string): ExecutorRegistration | undefined;
+    /**
+     * Check if an executor exists for a given action kind.
+     */
+    has(kind: string): boolean;
+    /**
+     * Validate an action using its registered schema.
+     *
+     * @param action - The action to validate
+     * @returns Validation result
+     */
+    validate(action: unknown): ValidationResult;
+    /**
+     * List all registered action kinds.
+     */
+    list(): string[];
+    /**
+     * List all registrations.
+     */
+    listRegistrations(): ExecutorRegistration[];
+    /**
+     * Get all built-in action kinds.
+     */
+    getBuiltInKinds(): string[];
+    /**
+     * Get all custom action kinds.
+     */
+    getCustomKinds(): string[];
+}
+/**
+ * Default singleton instance of ExecutorRegistry.
+ */
+export declare const executorRegistry: ExecutorRegistry;
+/**
+ * Get the executor for an action kind.
+ * @deprecated Use executorRegistry.get() instead
+ */
+export declare function getExecutor(kind: ActionKind | string): ActionExecutor<ActionStep> | undefined;
+/**
+ * Check if an executor exists for a given action kind.
+ * @deprecated Use executorRegistry.has() instead
+ */
+export declare function hasExecutor(kind: ActionKind | string): boolean;
+export { executeInsertHtml, executeSetText, executeSetAttr, executeAddClass, executeRemoveClass, executeSetStyle, } from '@syntrologie/adapt-content/runtime';
+export { executeHighlight, executePulse, executeBadge, executeTooltip, executeModal, } from '@syntrologie/adapt-overlays/runtime';
+export { executeTour } from './tour';

package/dist/actions/executors/index.js

@@ -0,0 +1,240 @@
+/**
+ * Action Executor Registry
+ *
+ * Extensible registry that maps action kinds to their executor functions.
+ * Apps can register custom executors at runtime.
+ *
+ * Core app executors are imported from their respective app packages.
+ */
+// Import executors from CORE app packages only (bundled with runtime)
+// Lazy apps (gamification, faq, nav) are loaded dynamically from CDN
+import { executors as contentExecutors } from '@syntrologie/adapt-content/runtime';
+import { executors as overlayExecutors } from '@syntrologie/adapt-overlays/runtime';
+import { executeTour } from './tour';
+/**
+ * Extensible registry for action executors.
+ *
+ * Core executors (setText, highlight, etc.) are registered synchronously
+ * at construction time for immediate availability - no async loading.
+ *
+ * External app executors are registered when apps activate.
+ */
+export class ExecutorRegistry {
+    /**
+     * Constructor - registers core executors synchronously.
+     * These are available IMMEDIATELY when the module loads,
+     * enabling instant action execution without waiting for app activation.
+     */
+    constructor() {
+        this.executors = new Map();
+        // Register all executors from core app packages
+        for (const { kind, executor } of contentExecutors) {
+            this.registerCore(kind, executor);
+        }
+        for (const { kind, executor } of overlayExecutors) {
+            this.registerCore(kind, executor);
+        }
+        // NOTE: Lazy apps (gamification, faq, nav) are NOT registered here.
+        // They are loaded dynamically from CDN via AppLoader when config requires them.
+        // core:mountWidget is handled specially in ActionEngine since it delegates to Surfaces
+        this.registerCore('core:mountWidget', async () => {
+            throw new Error('core:mountWidget must be handled by ActionEngine');
+        });
+        // Register core:tour executor
+        this.registerCore('core:tour', executeTour);
+    }
+    /**
+     * Register a core executor (synchronous, built-in, cannot be overridden).
+     */
+    registerCore(kind, executor, schema) {
+        this.executors.set(kind, {
+            kind,
+            executor,
+            schema,
+            source: 'core',
+            isBuiltIn: true,
+        });
+    }
+    /**
+     * Register an executor for an action kind.
+     *
+     * @param kind - The action kind (e.g., "gamification:awardBadge")
+     * @param executor - The executor function
+     * @param schema - Optional Zod schema for validation
+     * @param source - The source app ID (for tracking)
+     * @param isBuiltIn - Whether this is from a built-in app (prevents override)
+     */
+    register(kind, executor, schema, source = 'custom', isBuiltIn = false) {
+        if (this.executors.has(kind)) {
+            const existing = this.executors.get(kind);
+            if (existing.isBuiltIn) {
+                // Silently skip — app is re-registering an executor already bundled
+                // with the runtime. This happens when adaptive CDN bundles activate
+                // for apps whose executors are also compiled into the core bundle.
+                return;
+            }
+            console.warn(`[ExecutorRegistry] Overriding executor for kind: ${kind}`);
+        }
+        this.executors.set(kind, {
+            kind,
+            executor,
+            schema,
+            source,
+            isBuiltIn,
+        });
+    }
+    /**
+     * Unregister an executor.
+     *
+     * @param kind - The action kind to unregister
+     * @returns true if the executor was unregistered, false if not found or built-in
+     */
+    unregister(kind) {
+        const existing = this.executors.get(kind);
+        if (!existing) {
+            return false;
+        }
+        if (existing.isBuiltIn) {
+            console.warn(`[ExecutorRegistry] Cannot unregister built-in executor: ${kind}`);
+            return false;
+        }
+        this.executors.delete(kind);
+        return true;
+    }
+    /**
+     * Unregister all executors from a specific source.
+     *
+     * @param source - The source app ID
+     */
+    unregisterBySource(source) {
+        for (const [kind, registration] of this.executors.entries()) {
+            if (registration.source === source) {
+                this.executors.delete(kind);
+            }
+        }
+    }
+    /**
+     * Get the executor for an action kind.
+     */
+    get(kind) {
+        var _a;
+        return (_a = this.executors.get(kind)) === null || _a === void 0 ? void 0 : _a.executor;
+    }
+    /**
+     * Get the full registration for an action kind.
+     */
+    getRegistration(kind) {
+        return this.executors.get(kind);
+    }
+    /**
+     * Check if an executor exists for a given action kind.
+     */
+    has(kind) {
+        return this.executors.has(kind);
+    }
+    /**
+     * Validate an action using its registered schema.
+     *
+     * @param action - The action to validate
+     * @returns Validation result
+     */
+    validate(action) {
+        const errors = [];
+        if (!action || typeof action !== 'object') {
+            errors.push({
+                code: 'INVALID_ACTION',
+                message: 'Action must be an object',
+            });
+            return { valid: false, errors, warnings: [] };
+        }
+        const { kind } = action;
+        if (!kind || typeof kind !== 'string') {
+            errors.push({
+                code: 'MISSING_KIND',
+                message: "Action must have a 'kind' property",
+            });
+            return { valid: false, errors, warnings: [] };
+        }
+        const registration = this.executors.get(kind);
+        if (!registration) {
+            errors.push({
+                code: 'UNKNOWN_KIND',
+                message: `Unknown action kind: ${kind}`,
+                field: 'kind',
+            });
+            return { valid: false, errors, warnings: [] };
+        }
+        // If schema is provided, validate against it
+        if (registration.schema) {
+            const result = registration.schema.safeParse(action);
+            if (!result.success) {
+                for (const issue of result.error.issues) {
+                    errors.push({
+                        code: 'SCHEMA_VALIDATION_ERROR',
+                        message: issue.message,
+                        field: issue.path.join('.'),
+                    });
+                }
+                return { valid: false, errors, warnings: [] };
+            }
+        }
+        return { valid: true, errors: [], warnings: [] };
+    }
+    /**
+     * List all registered action kinds.
+     */
+    list() {
+        return Array.from(this.executors.keys());
+    }
+    /**
+     * List all registrations.
+     */
+    listRegistrations() {
+        return Array.from(this.executors.values());
+    }
+    /**
+     * Get all built-in action kinds.
+     */
+    getBuiltInKinds() {
+        return Array.from(this.executors.entries())
+            .filter(([, reg]) => reg.isBuiltIn)
+            .map(([kind]) => kind);
+    }
+    /**
+     * Get all custom action kinds.
+     */
+    getCustomKinds() {
+        return Array.from(this.executors.entries())
+            .filter(([, reg]) => !reg.isBuiltIn)
+            .map(([kind]) => kind);
+    }
+}
+// ============================================================================
+// Singleton and backwards-compatible exports
+// ============================================================================
+/**
+ * Default singleton instance of ExecutorRegistry.
+ */
+export const executorRegistry = new ExecutorRegistry();
+/**
+ * Get the executor for an action kind.
+ * @deprecated Use executorRegistry.get() instead
+ */
+export function getExecutor(kind) {
+    return executorRegistry.get(kind);
+}
+/**
+ * Check if an executor exists for a given action kind.
+ * @deprecated Use executorRegistry.has() instead
+ */
+export function hasExecutor(kind) {
+    return executorRegistry.has(kind);
+}
+// Re-export individual executors from app packages for backwards compatibility
+export { executeInsertHtml, executeSetText, executeSetAttr, executeAddClass, executeRemoveClass, executeSetStyle, } from '@syntrologie/adapt-content/runtime';
+export { executeHighlight, executePulse, executeBadge, executeTooltip, executeModal, } from '@syntrologie/adapt-overlays/runtime';
+// NOTE: Lazy app executors (gamification, faq, nav) are NOT re-exported here.
+// They are loaded dynamically from CDN via AppLoader when config requires them.
+// Core executors
+export { executeTour } from './tour';
+//# sourceMappingURL=index.js.map

package/dist/actions/executors/index.js.map

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

package/dist/actions/executors/tour.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tour Executor
+ *
+ * Orchestrates sequential tour steps with cross-page state persistence.
+ * Tours can span multiple pages and resume after navigation.
+ *
+ * Each step contains an inner action (modal, tooltip) that gets executed.
+ * The tour listens for CTA click events to advance to the next step.
+ */
+import type { TourAction, ActionExecutor } from '../types';
+/**
+ * Execute a tour action
+ *
+ * Tours orchestrate a sequence of steps, persisting state to localStorage
+ * to support cross-page navigation. Each step contains an action to execute
+ * and optionally defines transitions based on action events.
+ */
+export declare const executeTour: ActionExecutor<TourAction>;