@syntrologie/adapt-overlays 2.4.1 → 2.5.1

package/dist/WorkflowTracker.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowEntry } from './workflow-types';
+interface WorkflowTrackerProps {
+    workflows: WorkflowEntry[];
+    expanded?: boolean;
+    onStepClick: (tourId: string, stepId: string) => void;
+    onDismiss: (tourId: string) => void;
+}
+export declare function WorkflowTracker({ workflows, expanded, onStepClick, onDismiss, }: WorkflowTrackerProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=WorkflowTracker.d.ts.map

package/dist/WorkflowTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowTracker.d.ts","sourceRoot":"","sources":["../src/WorkflowTracker.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,UAAU,oBAAoB;IAC5B,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAkID,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,QAAQ,EACR,WAAW,EACX,SAAS,GACV,EAAE,oBAAoB,2CAsBtB"}

package/dist/WorkflowTracker.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function ProgressBar({ completed, total }) {
+    const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
+    return (_jsx("div", { className: "se-w-full se-h-1.5 se-rounded-full se-bg-white/[0.08] se-overflow-hidden", children: _jsx("div", { role: "progressbar", "aria-valuenow": percent, "aria-valuemin": 0, "aria-valuemax": 100, className: "se-h-full se-rounded-full se-bg-blue-5 se-transition-all se-duration-300", style: { width: `${percent}%` } }) }));
+}
+function StepItem({ step, isCompleted, isCurrent, tourId, onStepClick, }) {
+    return (_jsxs("button", { type: "button", "data-testid": `step-${step.id}`, "data-current": isCurrent ? 'true' : undefined, "data-completed": isCompleted ? 'true' : undefined, "aria-current": isCurrent ? 'step' : undefined, className: `se-flex se-items-center se-gap-2 se-w-full se-py-1.5 se-px-2 se-rounded se-border-none se-bg-transparent se-cursor-pointer se-text-left se-text-xs ${isCurrent ? 'se-font-semibold se-text-slate-grey-10' : 'se-text-slate-grey-8'}`, onClick: () => onStepClick(tourId, step.id), children: [_jsx("span", { className: "se-shrink-0 se-w-4 se-text-center", children: isCompleted ? (_jsx("span", { role: "img", "aria-label": "completed", className: "se-text-green-5", children: "\u2713" })) : isCurrent ? (_jsx("span", { className: "se-inline-block se-w-1.5 se-h-1.5 se-rounded-full se-bg-blue-5" })) : (_jsx("span", { className: "se-inline-block se-w-1.5 se-h-1.5 se-rounded-full se-bg-white/[0.12]" })) }), _jsx("span", { className: "se-flex-1 se-overflow-hidden se-text-ellipsis se-whitespace-nowrap", children: step.title })] }));
+}
+function WorkflowCard({ workflow, expanded, onStepClick, onDismiss, }) {
+    const completedCount = workflow.completedSteps.length;
+    const totalSteps = workflow.steps.length;
+    return (_jsxs("div", { className: "se-p-3 se-rounded-lg se-border se-border-white/[0.08] se-bg-white/[0.02]", children: [_jsxs("div", { className: "se-flex se-items-center se-gap-2 se-mb-2", children: [workflow.meta.icon && (_jsx("span", { "data-testid": "workflow-icon", className: "se-shrink-0 se-text-sm", children: workflow.meta.icon })), _jsx("span", { className: "se-flex-1 se-text-[13px] se-font-semibold se-text-slate-grey-10 se-overflow-hidden se-text-ellipsis se-whitespace-nowrap", children: workflow.meta.title }), _jsx("button", { type: "button", "data-testid": `dismiss-${workflow.tourId}`, className: "se-shrink-0 se-py-0.5 se-px-1.5 se-rounded se-border-none se-bg-transparent se-text-slate-grey-7 se-text-xs se-cursor-pointer se-leading-none", onClick: () => onDismiss(workflow.tourId), "aria-label": `Dismiss ${workflow.meta.title}`, children: "\u2715" })] }), _jsxs("div", { className: "se-mb-2", children: [_jsx(ProgressBar, { completed: completedCount, total: totalSteps }), _jsxs("div", { className: "se-text-[10px] se-text-slate-grey-7 se-mt-1", children: [completedCount, " of ", totalSteps, " steps"] })] }), _jsx("div", { className: "se-flex se-flex-col", children: workflow.steps.map((step) => (_jsx(StepItem, { step: step, isCompleted: workflow.completedSteps.includes(step.id), isCurrent: workflow.currentStepId === step.id, tourId: workflow.tourId, onStepClick: onStepClick }, step.id))) }), expanded && workflow.meta.description && (_jsx("div", { className: "se-mt-2 se-text-[11px] se-text-slate-grey-7", children: workflow.meta.description }))] }));
+}
+export function WorkflowTracker({ workflows, expanded, onStepClick, onDismiss, }) {
+    if (workflows.length === 0) {
+        return (_jsx("div", { className: "se-flex se-items-center se-justify-center se-py-6 se-text-xs se-text-slate-grey-7", children: "No active workflows" }));
+    }
+    return (_jsx("div", { className: "se-flex se-flex-col se-gap-2", children: workflows.map((workflow) => (_jsx(WorkflowCard, { workflow: workflow, expanded: expanded, onStepClick: onStepClick, onDismiss: onDismiss }, workflow.tourId))) }));
+}

package/dist/WorkflowWidget.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Workflow Widget - MountableWidget for the WorkflowTracker
+ *
+ * Bridges runtime.actions.getActive() (tour actions with workflow metadata),
+ * runtime events (tour.started, tour.step_started, etc.), and the
+ * WorkflowTracker presentational component.
+ *
+ * Responsibilities:
+ * 1. Scan runtime.actions.getActive() for tours with `workflow` field
+ * 2. Re-scan on tour.started events (tiles render before actions are applied)
+ * 3. Load persisted state from runtime.state.user namespace
+ * 4. Subscribe to tour.* events and update workflow entries
+ * 5. Render WorkflowTracker with derived workflow entries
+ * 6. Handle step clicks (publish workflow:jump_to_step)
+ * 7. Handle dismiss (persist and re-render)
+ */
+interface ActiveAction {
+    id: string;
+    action: Record<string, unknown>;
+    adaptiveId?: string;
+    appliedTs: number;
+    state: string;
+}
+interface WorkflowRuntime {
+    events: {
+        subscribe: (filter: {
+            patterns?: string[];
+            names?: string[];
+        }, callback: (event: {
+            name: string;
+            props?: Record<string, unknown>;
+            ts: number;
+        }) => void) => () => void;
+        publish: (name: string, props?: Record<string, unknown>) => void;
+    };
+    actions: {
+        getActive: () => ActiveAction[];
+    };
+    state?: {
+        user?: {
+            ns?: (namespace: string) => {
+                get: (key: string) => unknown;
+                set: (key: string, value: unknown) => void;
+            };
+        };
+    };
+}
+/**
+ * MountableWidget contract — matches the interface from @syntrologie/runtime-sdk
+ * Defined locally to avoid adding runtime-sdk as a dependency (same pattern as other adaptives).
+ */
+export interface MountableWidget {
+    mount(container: HTMLElement, config?: Record<string, unknown>): (() => void) | void;
+    update?(container: HTMLElement, config?: Record<string, unknown>): void;
+}
+interface WorkflowWidgetInnerProps {
+    runtime: WorkflowRuntime | null;
+}
+export declare function WorkflowWidgetInner({ runtime }: WorkflowWidgetInnerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Mountable widget interface for the runtime's WidgetRegistry.
+ *
+ * Follows the MountableWidget contract:
+ *   mount(container, config?) -> cleanup | void
+ *
+ * Config is enriched with `runtime` by WidgetRegistry.bindRuntime().
+ */
+export declare const WorkflowMountableWidget: MountableWidget;
+export {};
+//# sourceMappingURL=WorkflowWidget.d.ts.map

package/dist/WorkflowWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowWidget.d.ts","sourceRoot":"","sources":["../src/WorkflowWidget.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,UAAU,YAAY;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,eAAe;IACvB,MAAM,EAAE;QACN,SAAS,EAAE,CACT,MAAM,EAAE;YAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,EACjD,QAAQ,EAAE,CAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,KACrF,MAAM,IAAI,CAAC;QAChB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KAClE,CAAC;IACF,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,YAAY,EAAE,CAAC;KACjC,CAAC;IACF,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE;YACL,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK;gBAC1B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;gBAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;aAC5C,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IACrF,MAAM,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzE;AAsGD,UAAU,wBAAwB;IAChC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;CACjC;AAED,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,EAAE,wBAAwB,2CA0QxE;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC"}

package/dist/WorkflowWidget.js

@@ -0,0 +1,329 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Workflow Widget - MountableWidget for the WorkflowTracker
+ *
+ * Bridges runtime.actions.getActive() (tour actions with workflow metadata),
+ * runtime events (tour.started, tour.step_started, etc.), and the
+ * WorkflowTracker presentational component.
+ *
+ * Responsibilities:
+ * 1. Scan runtime.actions.getActive() for tours with `workflow` field
+ * 2. Re-scan on tour.started events (tiles render before actions are applied)
+ * 3. Load persisted state from runtime.state.user namespace
+ * 4. Subscribe to tour.* events and update workflow entries
+ * 5. Render WorkflowTracker with derived workflow entries
+ * 6. Handle step clicks (publish workflow:jump_to_step)
+ * 7. Handle dismiss (persist and re-render)
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { WorkflowTracker } from './WorkflowTracker';
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Show a toast notification for a workflow tour.
+ * Creates a DOM element, appends it to the container, and auto-removes after 4 seconds.
+ */
+function showWorkflowToast(container, notification) {
+    const toast = document.createElement('div');
+    toast.setAttribute('data-testid', 'workflow-toast');
+    toast.className = 'se-fixed se-bottom-4 se-right-4 se-z-50';
+    Object.assign(toast.style, {
+        position: 'fixed',
+        bottom: '16px',
+        right: '16px',
+        zIndex: '2147483646',
+        padding: '12px 16px',
+        borderRadius: '8px',
+        backgroundColor: 'var(--se-color-bg-surface, #fff)',
+        color: 'var(--se-color-text-primary, #1a1a1a)',
+        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+        maxWidth: '320px',
+        fontFamily: 'var(--se-font-family, system-ui, sans-serif)',
+        fontSize: '14px',
+        lineHeight: '1.4',
+        transition: 'opacity 0.3s ease',
+    });
+    const titleEl = document.createElement('div');
+    titleEl.className = 'se-font-semibold';
+    titleEl.style.fontWeight = '600';
+    titleEl.textContent = notification.title;
+    toast.appendChild(titleEl);
+    if (notification.body) {
+        const bodyEl = document.createElement('div');
+        bodyEl.className = 'se-mt-1 se-text-sm';
+        bodyEl.style.marginTop = '4px';
+        bodyEl.style.fontSize = '13px';
+        bodyEl.style.color = 'var(--se-color-text-secondary, #666)';
+        bodyEl.textContent = notification.body;
+        toast.appendChild(bodyEl);
+    }
+    container.appendChild(toast);
+    // Auto-remove after 4 seconds
+    let removeTimer;
+    const fadeTimer = setTimeout(() => {
+        toast.style.opacity = '0';
+        removeTimer = setTimeout(() => {
+            toast.remove();
+        }, 300);
+    }, 4000);
+    // Return cleanup function for unmount safety
+    return () => {
+        clearTimeout(fadeTimer);
+        clearTimeout(removeTimer);
+        toast.remove();
+    };
+}
+/**
+ * Extract workflow-enabled tours from active actions (runtime.actions.getActive()).
+ * Only actions with kind 'core:tour', a tourId, and a workflow field are included.
+ */
+function extractWorkflowsFromActive(activeActions) {
+    const workflows = new Map();
+    for (const entry of activeActions) {
+        const action = entry.action;
+        if (action.kind === 'core:tour' && action.workflow && action.tourId) {
+            const meta = action.workflow;
+            const rawSteps = action.steps || [];
+            const steps = rawSteps.map((s) => ({
+                id: s.id,
+                title: meta.stepTitles?.[s.id] || s.id,
+            }));
+            workflows.set(action.tourId, { meta, steps });
+        }
+    }
+    return workflows;
+}
+export function WorkflowWidgetInner({ runtime }) {
+    // Scan active actions for workflow-enabled tours.
+    // Re-scans when actionVersion bumps (triggered by tour.started events).
+    const [actionVersion, setActionVersion] = useState(0);
+    const tourWorkflows = useMemo(() => {
+        const active = runtime?.actions?.getActive?.() || [];
+        return extractWorkflowsFromActive(active);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [runtime, actionVersion]);
+    // Keep a ref so event handlers always see the latest tourWorkflows
+    const tourWorkflowsRef = useRef(tourWorkflows);
+    tourWorkflowsRef.current = tourWorkflows;
+    // Re-scan active actions when a tour starts (handles tile-renders-before-actions timing)
+    useEffect(() => {
+        if (!runtime?.events?.subscribe)
+            return;
+        return runtime.events.subscribe({ names: ['tour.started', 'tour.resumed'] }, () => setActionVersion((v) => v + 1));
+    }, [runtime]);
+    // Load persisted state
+    const stateNs = useMemo(() => runtime?.state?.user?.ns?.('workflows'), [runtime]);
+    // Ref to track which tours have had a toast notification
+    const notifiedRef = useRef(new Set());
+    // Ref to track toast cleanup functions for unmount safety
+    const toastCleanupsRef = useRef([]);
+    // Ref to track the container element for toast rendering
+    const containerRef = useRef(null);
+    // Ref to track completed tour timestamps
+    const completedMapRef = useRef({});
+    // Build workflow entries from discovered tours + persisted state
+    const [workflowEntries, setWorkflowEntries] = useState([]);
+    // Initialize persisted state refs once
+    const persistInitialized = useRef(false);
+    if (!persistInitialized.current && stateNs) {
+        const notified = stateNs.get?.('notified') || [];
+        for (const id of notified) {
+            notifiedRef.current.add(id);
+        }
+        const completed = stateNs.get?.('completed') || {};
+        completedMapRef.current = { ...completed };
+        persistInitialized.current = true;
+    }
+    // Sync workflowEntries when tourWorkflows changes (new tours discovered via getActive)
+    useEffect(() => {
+        if (tourWorkflows.size === 0)
+            return;
+        const dismissed = stateNs?.get?.('dismissed') || [];
+        const completed = stateNs?.get?.('completed') || {};
+        setWorkflowEntries((prev) => {
+            const existingIds = new Set(prev.map((e) => e.tourId));
+            const newEntries = [];
+            for (const [tourId, { meta, steps }] of tourWorkflows) {
+                if (existingIds.has(tourId))
+                    continue; // Already tracked
+                let status = 'active';
+                if (dismissed.includes(tourId)) {
+                    status = 'dismissed';
+                }
+                else if (completed[tourId]) {
+                    status = 'completed';
+                }
+                newEntries.push({
+                    tourId,
+                    meta,
+                    steps,
+                    currentStepId: null,
+                    completedSteps: [],
+                    status,
+                    completedAt: completed[tourId] || undefined,
+                });
+            }
+            return newEntries.length > 0 ? [...prev, ...newEntries] : prev;
+        });
+        // Fire toast for newly discovered active tours.
+        // This handles the race condition where tour.started fires before the
+        // widget discovers the tour via getActive() re-scan.
+        for (const [tourId, { meta }] of tourWorkflows) {
+            if (!notifiedRef.current.has(tourId) &&
+                meta.notification &&
+                containerRef.current &&
+                !dismissed.includes(tourId) &&
+                !completed[tourId]) {
+                notifiedRef.current.add(tourId);
+                stateNs?.set?.('notified', [...notifiedRef.current]);
+                const cleanup = showWorkflowToast(containerRef.current, meta.notification);
+                toastCleanupsRef.current.push(cleanup);
+            }
+        }
+    }, [tourWorkflows, stateNs]);
+    // Subscribe to tour events
+    useEffect(() => {
+        if (!runtime?.events?.subscribe)
+            return;
+        const unsubscribe = runtime.events.subscribe({ patterns: ['^tour\\.'] }, (event) => {
+            const tourId = event.props?.tourId;
+            if (!tourId)
+                return;
+            // Re-scan active actions on tour.started (handles tile-renders-before-actions timing)
+            const currentWorkflows = tourWorkflowsRef.current;
+            if (!currentWorkflows.has(tourId) && event.name === 'tour.started') {
+                // Tour just became active — re-scan will pick it up on next render
+                setActionVersion((v) => v + 1);
+                return;
+            }
+            // Only process events for tours that have workflow metadata
+            if (!currentWorkflows.has(tourId))
+                return;
+            setWorkflowEntries((prev) => {
+                const updated = prev.map((entry) => {
+                    if (entry.tourId !== tourId)
+                        return entry;
+                    switch (event.name) {
+                        case 'tour.started': {
+                            const startStepId = event.props?.startStepId || entry.steps[0]?.id || null;
+                            // Fire toast notification if not already notified
+                            if (!notifiedRef.current.has(tourId)) {
+                                notifiedRef.current.add(tourId);
+                                stateNs?.set?.('notified', [...notifiedRef.current]);
+                                const workflow = currentWorkflows.get(tourId);
+                                if (workflow?.meta.notification && containerRef.current) {
+                                    const cleanup = showWorkflowToast(containerRef.current, workflow.meta.notification);
+                                    toastCleanupsRef.current.push(cleanup);
+                                }
+                            }
+                            // Persist active state
+                            const activeIds = prev
+                                .filter((e) => e.status === 'active' || e.tourId === tourId)
+                                .map((e) => e.tourId);
+                            if (!activeIds.includes(tourId)) {
+                                activeIds.push(tourId);
+                            }
+                            stateNs?.set?.('active', [...new Set(activeIds)]);
+                            return {
+                                ...entry,
+                                status: 'active',
+                                currentStepId: startStepId,
+                                completedSteps: entry.status === 'active' ? entry.completedSteps : [],
+                            };
+                        }
+                        case 'tour.step_started': {
+                            const stepId = event.props?.stepId;
+                            return {
+                                ...entry,
+                                currentStepId: stepId || entry.currentStepId,
+                            };
+                        }
+                        case 'tour.step_changed': {
+                            const previousStepId = event.props?.previousStepId;
+                            const nextStepId = event.props?.nextStepId;
+                            const completedSteps = previousStepId && !entry.completedSteps.includes(previousStepId)
+                                ? [...entry.completedSteps, previousStepId]
+                                : entry.completedSteps;
+                            return {
+                                ...entry,
+                                currentStepId: nextStepId || entry.currentStepId,
+                                completedSteps,
+                            };
+                        }
+                        case 'tour.completed': {
+                            const completedAt = Date.now();
+                            // Persist completed state with timestamp
+                            completedMapRef.current[tourId] = completedAt;
+                            stateNs?.set?.('completed', { ...completedMapRef.current });
+                            return {
+                                ...entry,
+                                status: 'completed',
+                                currentStepId: null,
+                                completedSteps: entry.steps.map((s) => s.id),
+                                completedAt,
+                            };
+                        }
+                        case 'tour.paused': {
+                            // Keep current state, just note it was paused
+                            return entry;
+                        }
+                        default:
+                            return entry;
+                    }
+                });
+                return updated;
+            });
+        });
+        return () => {
+            unsubscribe();
+            // Clean up any pending toast timers
+            for (const cleanup of toastCleanupsRef.current) {
+                cleanup();
+            }
+            toastCleanupsRef.current = [];
+        };
+    }, [runtime, stateNs]);
+    // Handle step click — publish jump event
+    const handleStepClick = useCallback((tourId, stepId) => {
+        runtime?.events?.publish?.('workflow:jump_to_step', { tourId, stepId });
+    }, [runtime]);
+    // Handle dismiss
+    const handleDismiss = useCallback((tourId) => {
+        setWorkflowEntries((prev) => {
+            const updated = prev.map((entry) => entry.tourId === tourId ? { ...entry, status: 'dismissed' } : entry);
+            // Persist dismissed state
+            const dismissedIds = updated.filter((e) => e.status === 'dismissed').map((e) => e.tourId);
+            stateNs?.set?.('dismissed', dismissedIds);
+            return updated;
+        });
+    }, [stateNs]);
+    // Filter to active workflows only for rendering
+    const activeWorkflows = useMemo(() => workflowEntries.filter((w) => w.status === 'active'), [workflowEntries]);
+    return (_jsx("div", { ref: containerRef, children: _jsx(WorkflowTracker, { workflows: activeWorkflows, onStepClick: handleStepClick, onDismiss: handleDismiss }) }));
+}
+// ============================================================================
+// MountableWidget Interface
+// ============================================================================
+/**
+ * Mountable widget interface for the runtime's WidgetRegistry.
+ *
+ * Follows the MountableWidget contract:
+ *   mount(container, config?) -> cleanup | void
+ *
+ * Config is enriched with `runtime` by WidgetRegistry.bindRuntime().
+ */
+export const WorkflowMountableWidget = {
+    mount(container, config) {
+        const runtime = config?.runtime || null;
+        const root = createRoot(container);
+        root.render(React.createElement(WorkflowWidgetInner, {
+            runtime,
+        }));
+        // Return cleanup function
+        return () => {
+            root.unmount();
+        };
+    },
+};

package/dist/cdn.d.ts

@@ -15,8 +15,8 @@ export declare const manifest: {
     description: string;
     runtime: {
         actions: {
-            kind: "overlays:highlight" | "overlays:pulse" | "overlays:badge" | "overlays:tooltip" | "overlays:modal";
-            executor: import("packages/sdk-contracts/dist").ActionExecutor<import("./types").ModalAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").HighlightAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").PulseAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").BadgeAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").TooltipAction>;
+            kind: "core:tour" | "overlays:celebrate" | "overlays:highlight" | "overlays:pulse" | "overlays:badge" | "overlays:tooltip" | "overlays:modal";
+            executor: import("packages/sdk-contracts/dist").ActionExecutor<import("./types").CelebrateAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./tour-types").TourAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").ModalAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").HighlightAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").PulseAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").BadgeAction> | import("packages/sdk-contracts/dist").ActionExecutor<import("./types").TooltipAction>;
         }[];
     };
     editor: {

package/dist/celebrations/__tests__/engine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine.test.d.ts.map

package/dist/celebrations/__tests__/engine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.test.d.ts","sourceRoot":"","sources":["../../../src/celebrations/__tests__/engine.test.ts"],"names":[],"mappings":""}

package/dist/celebrations/__tests__/engine.test.js

@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+/** Stub CanvasRenderingContext2D for jsdom (which lacks canvas support) */
+function stubCanvasContext() {
+    const ctx = {
+        scale: vi.fn(),
+        clearRect: vi.fn(),
+        save: vi.fn(),
+        restore: vi.fn(),
+        translate: vi.fn(),
+        rotate: vi.fn(),
+        fillRect: vi.fn(),
+        beginPath: vi.fn(),
+        arc: vi.fn(),
+        fill: vi.fn(),
+        fillText: vi.fn(),
+        globalAlpha: 1,
+        fillStyle: '',
+        font: '',
+        shadowBlur: 0,
+        shadowColor: '',
+    };
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(ctx);
+    return ctx;
+}
+function mockEffect() {
+    return {
+        init: vi.fn(() => [
+            {
+                x: 100,
+                y: 0,
+                vx: 0,
+                vy: 1,
+                rotation: 0,
+                rotationSpeed: 0,
+                size: 5,
+                color: '#ff0000',
+                opacity: 1,
+            },
+        ]),
+        update: vi.fn(() => true),
+        render: vi.fn(),
+    };
+}
+const defaultConfig = {
+    duration: 3000,
+    intensity: 'medium',
+    colors: ['#ff0000', '#00ff00'],
+};
+describe('CelebrationEngine', () => {
+    let container;
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        stubCanvasContext();
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+        container.remove();
+    });
+    it('creates a canvas element when started', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        engine.start(container, effect, defaultConfig);
+        const canvas = container.querySelector('canvas[data-syntro-celebrate]');
+        expect(canvas).not.toBeNull();
+        expect(canvas?.style.position).toBe('fixed');
+        expect(canvas?.style.pointerEvents).toBe('none');
+        engine.stop();
+    });
+    it('removes canvas when stopped', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        engine.start(container, effect, defaultConfig);
+        expect(container.querySelector('canvas[data-syntro-celebrate]')).not.toBeNull();
+        engine.stop();
+        expect(container.querySelector('canvas[data-syntro-celebrate]')).toBeNull();
+    });
+    it('calls effect.init with canvas dimensions', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        engine.start(container, effect, defaultConfig);
+        expect(effect.init).toHaveBeenCalledWith(expect.any(Number), expect.any(Number), defaultConfig);
+        engine.stop();
+    });
+    it('calls effect.update and effect.render on animation frame', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        engine.start(container, effect, defaultConfig);
+        // Trigger an animation frame
+        vi.advanceTimersByTime(16);
+        expect(effect.update).toHaveBeenCalled();
+        expect(effect.render).toHaveBeenCalled();
+        engine.stop();
+    });
+    it('auto-stops after duration expires', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        engine.start(container, effect, { ...defaultConfig, duration: 1000 });
+        // Advance past duration
+        vi.advanceTimersByTime(1100);
+        expect(container.querySelector('canvas[data-syntro-celebrate]')).toBeNull();
+    });
+    it('auto-stops when effect.update returns false', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        // After first frame, update returns false (all particles done)
+        effect.update.mockReturnValue(false);
+        engine.start(container, effect, defaultConfig);
+        // Trigger animation frame
+        vi.advanceTimersByTime(16);
+        expect(container.querySelector('canvas[data-syntro-celebrate]')).toBeNull();
+    });
+    it('stop() is safe to call multiple times', async () => {
+        const { CelebrationEngine } = await import('../engine');
+        const engine = new CelebrationEngine();
+        const effect = mockEffect();
+        engine.start(container, effect, defaultConfig);
+        engine.stop();
+        engine.stop(); // should not throw
+        expect(container.querySelector('canvas[data-syntro-celebrate]')).toBeNull();
+    });
+});

package/dist/celebrations/__tests__/executor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=executor.test.d.ts.map

package/dist/celebrations/__tests__/executor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.test.d.ts","sourceRoot":"","sources":["../../../src/celebrations/__tests__/executor.test.ts"],"names":[],"mappings":""}