@syntrologie/runtime-sdk 0.2.1 → 0.2.3

package/dist/overlays/runtime/overlay/root.js

@@ -99,6 +99,40 @@ export function injectBaseStyles() {
   opacity: 1;
 }
 
+/* Tooltip action buttons (for tours) */
+.syntro-tt-actions {
+  display: flex;
+  gap: 8px;
+  margin-top: 12px;
+  justify-content: flex-end;
+}
+
+.syntro-tt-btn {
+  padding: 8px 16px;
+  border-radius: 6px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 150ms;
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  background: transparent;
+  color: inherit;
+}
+
+.syntro-tt-btn:hover {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.syntro-tt-btn-primary {
+  background: var(--syntro-accent, #4f46e5);
+  border-color: transparent;
+}
+
+.syntro-tt-btn-primary:hover {
+  background: var(--syntro-accent, #4338ca);
+  filter: brightness(1.1);
+}
+
 /* Buttons inside tooltips inherit font */
 .syntro-tooltip button {
   font-family: inherit;
@@ -147,6 +181,104 @@ export function injectBaseStyles() {
     transform: scale(1) translateY(0);
   }
 }
+
+/* Modal scrim */
+.syntro-modal-scrim {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(4px);
+  opacity: 0;
+  transition: opacity 200ms ease;
+  pointer-events: auto;
+}
+
+/* Modal container */
+.syntro-modal {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%) scale(0.95);
+  background: var(--syntro-surface, #0f172a);
+  color: var(--syntro-fg, #fff);
+  border-radius: 16px;
+  padding: 24px;
+  box-shadow: 0 24px 48px rgba(0, 0, 0, 0.4);
+  pointer-events: auto;
+  opacity: 0;
+  transition: opacity 200ms ease, transform 200ms ease;
+  z-index: 2147483647;
+}
+
+.syntro-modal-sm { max-width: 320px; width: 90vw; }
+.syntro-modal-md { max-width: 480px; width: 90vw; }
+.syntro-modal-lg { max-width: 640px; width: 90vw; }
+
+/* Modal content */
+.syntro-modal-title {
+  font-size: 20px;
+  font-weight: 600;
+  margin-bottom: 12px;
+}
+
+.syntro-modal-body {
+  font-size: 15px;
+  line-height: 1.6;
+  opacity: 0.9;
+  margin-bottom: 20px;
+}
+
+.syntro-modal-close {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  background: transparent;
+  border: none;
+  color: inherit;
+  font-size: 24px;
+  line-height: 1;
+  cursor: pointer;
+  opacity: 0.6;
+  transition: opacity 150ms;
+  padding: 4px;
+}
+
+.syntro-modal-close:hover {
+  opacity: 1;
+}
+
+/* Modal buttons */
+.syntro-modal-actions {
+  display: flex;
+  gap: 12px;
+  justify-content: flex-end;
+}
+
+.syntro-modal-btn {
+  padding: 10px 20px;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 150ms;
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  background: transparent;
+  color: inherit;
+}
+
+.syntro-modal-btn:hover {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.syntro-modal-btn-primary {
+  background: var(--syntro-accent, #4f46e5);
+  border-color: transparent;
+}
+
+.syntro-modal-btn-primary:hover {
+  background: var(--syntro-accent, #4338ca);
+  filter: brightness(1.1);
+}
 `;
     const style = document.createElement('style');
     style.setAttribute('data-syntro', 'base-overlay');

package/dist/overlays/runtime/overlay/root.js.map

@@ -1 +1 @@
-{"version":3,"file":"root.js","sourceRoot":"","sources":["../../../../src/overlays/runtime/overlay/root.ts"],"names":[],"mappings":"AAAA,IAAI,aAAa,GAAuB,IAAI,CAAC;AAE7C,MAAM,UAAU,iBAAiB;IAC/B,IAAI,aAAa,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IACjF,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,iBAAiB,CAAuB,CAAC;IAC1E,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACnC,EAAE,CAAC,EAAE,GAAG,iBAAiB,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;YACtB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,GAAG;YACV,MAAM,EAAE,YAAY;YACpB,aAAa,EAAE,MAAM;SACtB,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,aAAa,GAAG,EAAE,CAAC;IACnB,gBAAgB,EAAE,CAAC;IACnB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,IAAI,cAAc,GAAG,KAAK,CAAC;AAC3B,MAAM,UAAU,gBAAgB;IAC9B,IAAI,cAAc;QAAE,OAAO;IAC3B,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6Hb,CAAC;IACA,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9C,KAAK,CAAC,YAAY,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAClD,KAAK,CAAC,WAAW,GAAG,GAAG,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACjC,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,sBAAsB,CAAC,MAAmB;IACxD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC;IAChF,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AACD,MAAM,UAAU,kBAAkB;IAChC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;AAClF,CAAC"}
+{"version":3,"file":"root.js","sourceRoot":"","sources":["../../../../src/overlays/runtime/overlay/root.ts"],"names":[],"mappings":"AAAA,IAAI,aAAa,GAAuB,IAAI,CAAC;AAE7C,MAAM,UAAU,iBAAiB;IAC/B,IAAI,aAAa,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IACjF,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,iBAAiB,CAAuB,CAAC;IAC1E,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACnC,EAAE,CAAC,EAAE,GAAG,iBAAiB,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;YACtB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,GAAG;YACV,MAAM,EAAE,YAAY;YACpB,aAAa,EAAE,MAAM;SACtB,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,aAAa,GAAG,EAAE,CAAC;IACnB,gBAAgB,EAAE,CAAC;IACnB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,IAAI,cAAc,GAAG,KAAK,CAAC;AAC3B,MAAM,UAAU,gBAAgB;IAC9B,IAAI,cAAc;QAAE,OAAO;IAC3B,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiQb,CAAC;IACA,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9C,KAAK,CAAC,YAAY,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAClD,KAAK,CAAC,WAAW,GAAG,GAAG,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACjC,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,sBAAsB,CAAC,MAAmB;IACxD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC;IAChF,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AACD,MAAM,UAAU,kBAAkB;IAChC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;AAClF,CAAC"}

package/dist/overlays/runtime/overlay/runner.d.ts

@@ -1,2 +1,4 @@
 import type { CanvasRecipe, OverlayContext } from '../../types';
 export declare function runOverlays(recipe: CanvasRecipe, ctx: OverlayContext): Promise<() => void>;
+/** Start a tour by ID - clears completion state and begins */
+export declare function startTour(tourId: string): void;

package/dist/overlays/runtime/overlay/runner.js

@@ -1,11 +1,112 @@
 import { showTooltip } from './tooltip';
 import { showHighlight } from './highlight';
+import { showModal } from './modal';
+// Storage keys for cross-page tour state
+const ACTIVE_TOUR_KEY = 'syntro_active_tour';
+// Tour state expires after 5 minutes of inactivity
+// This prevents stale tours from resuming after hard refresh hours/days later
+const TOUR_STATE_EXPIRY_MS = 5 * 60 * 1000;
+/** Get active tour state from localStorage (returns null if expired) */
+function getActiveTourState() {
+    try {
+        const state = localStorage.getItem(ACTIVE_TOUR_KEY);
+        if (!state)
+            return null;
+        const parsed = JSON.parse(state);
+        // Check if state has expired
+        if (parsed.timestamp && Date.now() - parsed.timestamp > TOUR_STATE_EXPIRY_MS) {
+            console.log(`[SmartCanvas] Tour state expired (${Math.round((Date.now() - parsed.timestamp) / 1000)}s old), clearing`);
+            localStorage.removeItem(ACTIVE_TOUR_KEY);
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Save active tour state to localStorage with timestamp */
+function setActiveTourState(state) {
+    try {
+        if (state) {
+            const stateWithTimestamp = {
+                ...state,
+                timestamp: Date.now()
+            };
+            localStorage.setItem(ACTIVE_TOUR_KEY, JSON.stringify(stateWithTimestamp));
+        }
+        else {
+            localStorage.removeItem(ACTIVE_TOUR_KEY);
+        }
+    }
+    catch { }
+}
+/** Check if a step's route matches the current page */
+function stepRouteMatches(step, path) {
+    const stepRoute = step.route;
+    if (!stepRoute)
+        return true; // No route restriction = matches any page
+    // Exact match
+    if (stepRoute === path)
+        return true;
+    // Match with trailing path segments (e.g., /dashboard matches /dashboard/settings)
+    // But /dashboard should NOT match /dashboard-other or /login
+    if (path.startsWith(stepRoute + '/'))
+        return true;
+    return false;
+}
+/**
+ * Watch for route changes in SPAs
+ * Handles: popstate (back/forward), pushState, replaceState
+ */
+function watchRouteChanges(callback) {
+    let lastPath = location.pathname;
+    const checkAndNotify = () => {
+        const currentPath = location.pathname;
+        if (currentPath !== lastPath) {
+            lastPath = currentPath;
+            callback(currentPath);
+        }
+    };
+    // Handle back/forward button navigation
+    const onPopState = () => {
+        checkAndNotify();
+    };
+    window.addEventListener('popstate', onPopState);
+    // Patch pushState/replaceState to detect SPA soft navigation
+    // React Router, Next.js, etc. use these for client-side routing
+    const originalPushState = history.pushState.bind(history);
+    const originalReplaceState = history.replaceState.bind(history);
+    history.pushState = function (...args) {
+        originalPushState(...args);
+        checkAndNotify();
+    };
+    history.replaceState = function (...args) {
+        originalReplaceState(...args);
+        checkAndNotify();
+    };
+    return () => {
+        window.removeEventListener('popstate', onPopState);
+        history.pushState = originalPushState;
+        history.replaceState = originalReplaceState;
+    };
+}
 export async function runOverlays(recipe, ctx) {
     var _a;
     if (recipe.routes && !routeMatches(recipe.routes, location.pathname))
         return () => { };
+    // Sequential (tour) mode
+    if (recipe.mode === 'sequential') {
+        return runSequentialOverlays(recipe, ctx);
+    }
+    // Parallel mode (default) - show all steps at once
     const cleanups = [];
     for (const step of recipe.steps) {
+        // Modal steps don't need an anchor
+        if (step.kind === 'modal') {
+            cleanups.push(runModal(step, ctx));
+            continue;
+        }
         const el = await ctx.resolve(step.anchor);
         if (!el) {
             (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_anchor_missing', { stepId: step.id, anchor: step.anchor });
@@ -27,10 +128,260 @@ export async function runOverlays(recipe, ctx) {
         });
     };
 }
+/** Run steps one at a time, advancing based on onAction mappings */
+async function runSequentialOverlays(recipe, ctx) {
+    var _a;
+    const storageKey = `syntro_tour_${recipe.id}`;
+    // Check if user already completed/dismissed this tour
+    try {
+        if (localStorage.getItem(storageKey) === 'done') {
+            return () => { }; // Tour already completed, don't show again
+        }
+    }
+    catch { }
+    // Check for active cross-page tour state
+    const activeState = getActiveTourState();
+    const isResumingTour = (activeState === null || activeState === void 0 ? void 0 : activeState.tourId) === recipe.id;
+    // If autoStart is false and we're not resuming an active tour, don't auto-start
+    // Tours with autoStart: false should only start via explicit user action (e.g., clicking "Start Tour")
+    if (!isResumingTour && recipe.autoStart === false) {
+        return () => { };
+    }
+    const stepMap = new Map();
+    for (const step of recipe.steps) {
+        stepMap.set(step.id, step);
+    }
+    let currentCleanup = null;
+    let isDestroyed = false;
+    const runStep = async (stepId) => {
+        var _a, _b, _c, _d;
+        if (isDestroyed)
+            return;
+        const step = stepMap.get(stepId);
+        if (!step) {
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_tour_end', { recipeId: recipe.id, reason: 'step_not_found', stepId });
+            setActiveTourState(null);
+            return;
+        }
+        // Check if this step should show on current page
+        const currentPath = location.pathname;
+        const stepRoute = step.route;
+        console.log(`[SmartCanvas] runStep: stepId="${stepId}", kind="${step.kind}", stepRoute="${stepRoute}", currentPath="${currentPath}"`);
+        if (!stepRouteMatches(step, currentPath)) {
+            // Step is for a different page - save state but DON'T auto-navigate
+            // Auto-navigation can cause redirect wars with multiple tours
+            // Instead, just pause and wait for user to return to the correct page
+            console.log(`[SmartCanvas] Route mismatch - step "${stepId}" is for "${stepRoute}", currently on "${currentPath}". Pausing tour.`);
+            setActiveTourState({ tourId: recipe.id, stepId });
+            return;
+        }
+        console.log(`[SmartCanvas] Route matches, showing step "${stepId}"`);
+        // Save current step state for cross-page resume
+        setActiveTourState({ tourId: recipe.id, stepId });
+        // Clean up previous step
+        if (currentCleanup) {
+            currentCleanup();
+            currentCleanup = null;
+        }
+        const onStepAction = (actionId) => {
+            var _a, _b, _c, _d, _e;
+            const nextStepId = (_a = step.onAction) === null || _a === void 0 ? void 0 : _a[actionId];
+            (_b = ctx.onEvent) === null || _b === void 0 ? void 0 : _b.call(ctx, 'syntro_tour_action', { recipeId: recipe.id, stepId: step.id, actionId, nextStepId });
+            if (!nextStepId || nextStepId === 'end') {
+                // Tour ends - mark as done
+                try {
+                    localStorage.setItem(storageKey, 'done');
+                }
+                catch { }
+                (_d = (_c = ctx.telemetry) === null || _c === void 0 ? void 0 : _c.setPersonPropertiesOnce) === null || _d === void 0 ? void 0 : _d.call(_c, { [storageKey]: 'done' });
+                setActiveTourState(null);
+                if (currentCleanup) {
+                    currentCleanup();
+                    currentCleanup = null;
+                }
+                (_e = ctx.onEvent) === null || _e === void 0 ? void 0 : _e.call(ctx, 'syntro_tour_end', { recipeId: recipe.id, reason: 'completed' });
+            }
+            else {
+                // Advance to next step
+                const nextStep = stepMap.get(nextStepId);
+                const nextStepRoute = nextStep === null || nextStep === void 0 ? void 0 : nextStep.route;
+                const nowPath = location.pathname; // Get current path at action time
+                // Update tracked step ID
+                currentStepId = nextStepId;
+                // If next step is on a different page, navigate there (user-initiated)
+                if (nextStep && nextStepRoute && !stepRouteMatches(nextStep, nowPath)) {
+                    console.log(`[SmartCanvas] User advancing to step "${nextStepId}" on route "${nextStepRoute}" - navigating...`);
+                    setActiveTourState({ tourId: recipe.id, stepId: nextStepId });
+                    if (currentCleanup) {
+                        currentCleanup();
+                        currentCleanup = null;
+                    }
+                    window.location.href = nextStepRoute;
+                }
+                else {
+                    // Same page - just run the step
+                    runStep(nextStepId);
+                }
+            }
+        };
+        if (step.kind === 'modal') {
+            currentCleanup = runModalWithCallback(step, ctx, onStepAction);
+        }
+        else if (step.kind === 'tooltip') {
+            const el = await ctx.resolve(step.anchor);
+            if (!el) {
+                (_b = ctx.onEvent) === null || _b === void 0 ? void 0 : _b.call(ctx, 'syntro_anchor_missing', { stepId: step.id, anchor: step.anchor });
+                // Don't end tour - element might appear later or on different page
+                console.log(`[SmartCanvas] Anchor not found for step "${stepId}", waiting...`);
+                return;
+            }
+            currentCleanup = runTooltipWithCallback(step, el, ctx, onStepAction);
+        }
+        else if (step.kind === 'highlight') {
+            const el = await ctx.resolve(step.anchor);
+            if (!el) {
+                (_c = ctx.onEvent) === null || _c === void 0 ? void 0 : _c.call(ctx, 'syntro_anchor_missing', { stepId: step.id, anchor: step.anchor });
+                return;
+            }
+            currentCleanup = runHighlight(step, el, ctx);
+        }
+        (_d = ctx.onEvent) === null || _d === void 0 ? void 0 : _d.call(ctx, 'syntro_tour_step', { recipeId: recipe.id, stepId: step.id });
+    };
+    // Track current step for route change handling
+    let currentStepId;
+    // Determine starting step
+    if (isResumingTour && (activeState === null || activeState === void 0 ? void 0 : activeState.stepId)) {
+        // Resume from saved step
+        currentStepId = activeState.stepId;
+        console.log(`[SmartCanvas] Resuming tour "${recipe.id}" from step "${currentStepId}"`);
+    }
+    else {
+        // Start fresh
+        currentStepId = recipe.startStep || ((_a = recipe.steps[0]) === null || _a === void 0 ? void 0 : _a.id);
+    }
+    // Watch for SPA route changes (back/forward, pushState, replaceState)
+    // When route changes, re-evaluate if current step should show
+    const unwatchRoutes = watchRouteChanges((newPath) => {
+        if (isDestroyed || !currentStepId)
+            return;
+        const step = stepMap.get(currentStepId);
+        if (!step)
+            return;
+        const stepRoute = step.route;
+        const wasShowingStep = currentCleanup !== null;
+        const shouldShowStep = stepRouteMatches(step, newPath);
+        console.log(`[SmartCanvas] Route changed to "${newPath}" - step "${currentStepId}" route="${stepRoute}", wasShowing=${wasShowingStep}, shouldShow=${shouldShowStep}`);
+        if (wasShowingStep && !shouldShowStep) {
+            // User navigated away - hide the step
+            console.log(`[SmartCanvas] Hiding step "${currentStepId}" - user navigated away`);
+            if (currentCleanup) {
+                currentCleanup();
+                currentCleanup = null;
+            }
+            // Check if any next step from onAction matches the new route
+            // This handles cases where user clicks the actual app button instead of tour button
+            const currentStep = stepMap.get(currentStepId);
+            if (currentStep) {
+                const onActionMap = currentStep.onAction || {};
+                // Find a next step that matches the new route
+                for (const nextStepId of Object.values(onActionMap)) {
+                    if (nextStepId === 'end' || typeof nextStepId !== 'string')
+                        continue;
+                    const nextStep = stepMap.get(nextStepId);
+                    if (nextStep && stepRouteMatches(nextStep, newPath)) {
+                        console.log(`[SmartCanvas] Auto-advancing to step "${nextStepId}" - matches new route "${newPath}"`);
+                        currentStepId = nextStepId;
+                        setActiveTourState({ tourId: recipe.id, stepId: nextStepId });
+                        runStep(nextStepId);
+                        return;
+                    }
+                }
+                // No matching next step - just pause (save state for later resume)
+                console.log(`[SmartCanvas] No next step matches new route "${newPath}", pausing tour`);
+                setActiveTourState({ tourId: recipe.id, stepId: currentStepId });
+            }
+        }
+        else if (!wasShowingStep && shouldShowStep) {
+            // User navigated back - show the step (resume tour)
+            console.log(`[SmartCanvas] Resuming step "${currentStepId}" - user returned to correct route`);
+            runStep(currentStepId);
+        }
+    });
+    if (currentStepId) {
+        await runStep(currentStepId);
+    }
+    return () => {
+        isDestroyed = true;
+        unwatchRoutes();
+        if (currentCleanup) {
+            currentCleanup();
+            currentCleanup = null;
+        }
+    };
+}
+/** Start a tour by ID - clears completion state and begins */
+export function startTour(tourId) {
+    const storageKey = `syntro_tour_${tourId}`;
+    try {
+        localStorage.removeItem(storageKey);
+        setActiveTourState({ tourId, stepId: '' }); // Will use startStep
+        window.location.reload();
+    }
+    catch { }
+}
 function routeMatches(routes, path) {
     // simple contains/prefix; replace with real matcher as needed
     return routes.some(r => r === path || path.startsWith(r));
 }
+function runModal(step, ctx) {
+    var _a, _b, _c, _d, _e, _f;
+    const html = modalHtml(step);
+    const handle = showModal(ctx.overlayRoot, {
+        html,
+        size: (_a = step.size) !== null && _a !== void 0 ? _a : 'md',
+        blocking: (_b = step.blocking) !== null && _b !== void 0 ? _b : true,
+        scrimOpacity: (_d = (_c = step.scrim) === null || _c === void 0 ? void 0 : _c.opacity) !== null && _d !== void 0 ? _d : 0.6,
+        onAction: (actionId) => {
+            var _a;
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_action', { stepId: step.id, actionId });
+            handle.destroy();
+        }
+    });
+    (_e = ctx.onEvent) === null || _e === void 0 ? void 0 : _e.call(ctx, 'syntro_overlay_exposed', { kind: 'modal', stepId: step.id, recipeId: ctx.recipeId });
+    const timers = [];
+    if ((_f = step.dismiss) === null || _f === void 0 ? void 0 : _f.timeoutMs) {
+        const id = window.setTimeout(() => {
+            var _a;
+            handle.destroy();
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_dismissed', { stepId: step.id, reason: 'timeout' });
+        }, step.dismiss.timeoutMs);
+        timers.push(id);
+    }
+    const closeBtn = handle.el.querySelector('[data-syntro-role="close"]');
+    const onClose = () => {
+        var _a;
+        handle.destroy();
+        (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_dismissed', { stepId: step.id, reason: 'close' });
+    };
+    closeBtn === null || closeBtn === void 0 ? void 0 : closeBtn.addEventListener('click', onClose);
+    return () => {
+        timers.forEach((id) => clearTimeout(id));
+        closeBtn === null || closeBtn === void 0 ? void 0 : closeBtn.removeEventListener('click', onClose);
+        handle.destroy();
+    };
+}
+function modalHtml(step) {
+    var _a, _b, _c;
+    const title = step.content.title ? `<div class="syntro-modal-title">${escapeHtml(step.content.title)}</div>` : '';
+    const body = `<div class="syntro-modal-body">${escapeHtml(step.content.body)}</div>`;
+    const close = ((_b = (_a = step.dismiss) === null || _a === void 0 ? void 0 : _a.closeButton) !== null && _b !== void 0 ? _b : true) ? `<button data-syntro-role="close" class="syntro-modal-close" aria-label="Close">&times;</button>` : '';
+    let actions = '';
+    if ((_c = step.ctaButtons) === null || _c === void 0 ? void 0 : _c.length) {
+        const btns = step.ctaButtons.map(btn => `<button class="syntro-modal-btn${btn.primary ? ' syntro-modal-btn-primary' : ''}" data-syntro-action="${escapeHtml(btn.actionId)}">${escapeHtml(btn.label)}</button>`).join('');
+        actions = `<div class="syntro-modal-actions">${btns}</div>`;
+    }
+    return `${close}${title}${body}${actions}`;
+}
 function runTooltip(step, anchorEl, ctx) {
     var _a, _b, _c, _d;
     const html = tooltipHtml(step);
@@ -89,13 +440,101 @@ function runHighlight(step, anchorEl, ctx) {
     };
 }
 function tooltipHtml(step) {
-    var _a, _b;
+    var _a, _b, _c;
     const title = step.content.title ? `<div class="syntro-tt-title">${escapeHtml(step.content.title)}</div>` : '';
     const body = `<div class="syntro-tt-body">${escapeHtml(step.content.body)}</div>`;
     const close = ((_b = (_a = step.dismiss) === null || _a === void 0 ? void 0 : _a.closeButton) !== null && _b !== void 0 ? _b : true) ? `<button data-syntro-role="close" class="syntro-tt-close" aria-label="Close">×</button>` : '';
-    return `<div class="syntro-tt">${title}${body}${close}</div>`;
+    let actions = '';
+    if ((_c = step.ctaButtons) === null || _c === void 0 ? void 0 : _c.length) {
+        const btns = step.ctaButtons.map(btn => `<button class="syntro-tt-btn${btn.primary ? ' syntro-tt-btn-primary' : ''}" data-syntro-action="${escapeHtml(btn.actionId)}">${escapeHtml(btn.label)}</button>`).join('');
+        actions = `<div class="syntro-tt-actions">${btns}</div>`;
+    }
+    return `<div class="syntro-tt">${close}${title}${body}${actions}</div>`;
 }
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 }
+/** Modal runner for sequential tours with external action callback */
+function runModalWithCallback(step, ctx, onAction) {
+    var _a, _b, _c, _d, _e, _f;
+    const html = modalHtml(step);
+    const handle = showModal(ctx.overlayRoot, {
+        html,
+        size: (_a = step.size) !== null && _a !== void 0 ? _a : 'md',
+        blocking: (_b = step.blocking) !== null && _b !== void 0 ? _b : true,
+        scrimOpacity: (_d = (_c = step.scrim) === null || _c === void 0 ? void 0 : _c.opacity) !== null && _d !== void 0 ? _d : 0.6,
+        onAction: (actionId) => {
+            var _a;
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_action', { stepId: step.id, actionId });
+            handle.destroy();
+            onAction(actionId);
+        }
+    });
+    (_e = ctx.onEvent) === null || _e === void 0 ? void 0 : _e.call(ctx, 'syntro_overlay_exposed', { kind: 'modal', stepId: step.id, recipeId: ctx.recipeId });
+    const timers = [];
+    if ((_f = step.dismiss) === null || _f === void 0 ? void 0 : _f.timeoutMs) {
+        const id = window.setTimeout(() => {
+            var _a;
+            handle.destroy();
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_dismissed', { stepId: step.id, reason: 'timeout' });
+            onAction('dismiss');
+        }, step.dismiss.timeoutMs);
+        timers.push(id);
+    }
+    const closeBtn = handle.el.querySelector('[data-syntro-role="close"]');
+    const onClose = () => {
+        var _a;
+        handle.destroy();
+        (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_dismissed', { stepId: step.id, reason: 'close' });
+        onAction('dismiss');
+    };
+    closeBtn === null || closeBtn === void 0 ? void 0 : closeBtn.addEventListener('click', onClose);
+    return () => {
+        timers.forEach((id) => clearTimeout(id));
+        closeBtn === null || closeBtn === void 0 ? void 0 : closeBtn.removeEventListener('click', onClose);
+        handle.destroy();
+    };
+}
+/** Tooltip runner for sequential tours with CTA buttons and external action callback */
+function runTooltipWithCallback(step, anchorEl, ctx, onAction) {
+    var _a, _b, _c, _d;
+    const html = tooltipHtml(step);
+    const handle = showTooltip(anchorEl, ctx.overlayRoot, {
+        html,
+        placement: (_a = step.placement) !== null && _a !== void 0 ? _a : 'top',
+        offsetPx: (_b = step.offsetPx) !== null && _b !== void 0 ? _b : 8,
+        blocking: !!step.blocking,
+        trigger: step.trigger,
+        onAction: (actionId) => {
+            var _a;
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_action', { stepId: step.id, actionId });
+            handle.destroy();
+            onAction(actionId);
+        }
+    });
+    (_c = ctx.onEvent) === null || _c === void 0 ? void 0 : _c.call(ctx, 'syntro_overlay_exposed', { kind: 'tooltip', stepId: step.id, recipeId: ctx.recipeId });
+    const timers = [];
+    if ((_d = step.dismiss) === null || _d === void 0 ? void 0 : _d.timeoutMs) {
+        const id = window.setTimeout(() => {
+            var _a;
+            handle.destroy();
+            (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_dismissed', { stepId: step.id, reason: 'timeout' });
+            onAction('dismiss');
+        }, step.dismiss.timeoutMs);
+        timers.push(id);
+    }
+    const closeBtn = handle.el.querySelector('[data-syntro-role="close"]');
+    const onClose = () => {
+        var _a;
+        handle.destroy();
+        (_a = ctx.onEvent) === null || _a === void 0 ? void 0 : _a.call(ctx, 'syntro_overlay_dismissed', { stepId: step.id, reason: 'close' });
+        onAction('dismiss');
+    };
+    closeBtn === null || closeBtn === void 0 ? void 0 : closeBtn.addEventListener('click', onClose);
+    return () => {
+        timers.forEach((id) => clearTimeout(id));
+        closeBtn === null || closeBtn === void 0 ? void 0 : closeBtn.removeEventListener('click', onClose);
+        handle.destroy();
+    };
+}
 //# sourceMappingURL=runner.js.map