@eventop/sdk 1.2.2 → 1.2.10

package/dist/core.cjs

@@ -1,231 +1,509 @@
 'use strict';
 
-function _mergeNamespaces(n, m) {
-	m.forEach(function (e) {
-		e && typeof e !== 'string' && !Array.isArray(e) && Object.keys(e).forEach(function (k) {
-			if (k !== 'default' && !(k in n)) {
-				var d = Object.getOwnPropertyDescriptor(e, k);
-				Object.defineProperty(n, k, d.get ? d : {
-					enumerable: true,
-					get: function () { return e[k]; }
-				});
-			}
-		});
-	});
-	return Object.freeze(n);
+// Single source of truth for all mutable SDK state.
+// Every module imports from here so there is no circular dependency on core.js.
+//
+// NOTE: modules should mutate these properties directly, e.g.
+//   import * as state from './state.js';
+//   state.tour = new Shepherd.Tour(...);
+
+/** @type {Function|null} The resolved AI provider function */
+let provider = null;
+
+/** @type {object|null} The merged SDK config object */
+let config = null;
+
+/** @type {Function|null} Framework router function (e.g. React Router's navigate) */
+let router = null;
+
+/** @type {object|null} Active Shepherd.Tour instance */
+let tour = null;
+
+/** @type {boolean} Whether the chat panel is currently visible */
+let isOpen = false;
+
+/** @type {Array<{role:string,content:string}>} AI conversation history */
+let messages = [];
+
+/** @type {Array<object>|null} Steps saved when a tour is paused */
+let pausedSteps = null;
+
+/** @type {number} Step index to resume from after a pause */
+let pausedIndex = 0;
+
+/** @type {Array<Function>} Cleanup callbacks — called when tour ends or is paused */
+let cleanups = [];
+
+// ─── Setters ─────────────────────────────────────────────────────────────────
+// Using setter functions keeps mutations explicit and grep-friendly.
+
+function setProvider(v) {
+  provider = v;
+}
+function setConfig(v) {
+  config = v;
+}
+function setRouter(v) {
+  router = v;
+}
+function setTour(v) {
+  tour = v;
+}
+function setIsOpen(v) {
+  isOpen = v;
+}
+function setMessages(v) {
+  messages = v;
+}
+function setPausedSteps(v) {
+  pausedSteps = v;
+}
+function setPausedIndex(v) {
+  pausedIndex = v;
+}
+function pushCleanup(fn) {
+  cleanups.push(fn);
+}
+function runAndClearCleanups() {
+  cleanups.forEach(fn => fn());
+  cleanups = [];
 }
 
-var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
+// Factory helpers for creating AI provider functions.
+// Extend this file to add new built-in providers (OpenAI, Gemini, etc.).
 
-var core$1 = {exports: {}};
+const providers = {
+  custom(fn) {
+    if (typeof fn !== 'function') {
+      throw new Error('[Eventop] providers.custom() requires a function');
+    }
+    return fn;
+  }
+};
+
+// Resolves design tokens from user config and builds CSS variable strings.
+
+const DARK_TOKENS = {
+  accent: '#e94560',
+  accentSecondary: '#a855f7',
+  bg: '#0f0f1a',
+  surface: '#1a1a2e',
+  border: '#2a2a4a',
+  text: '#e0e0f0',
+  textDim: '#6060a0',
+  radius: '16px',
+  fontFamily: "system-ui, -apple-system, 'Segoe UI', sans-serif"
+};
+const LIGHT_TOKENS = {
+  accent: '#e94560',
+  accentSecondary: '#7c3aed',
+  bg: '#ffffff',
+  surface: '#f8f8fc',
+  border: '#e4e4f0',
+  text: '#1a1a2e',
+  textDim: '#888899',
+  radius: '16px',
+  fontFamily: "system-ui, -apple-system, 'Segoe UI', sans-serif"
+};
+const PRESETS = {
+  default: {},
+  minimal: {
+    accent: '#000000',
+    accentSecondary: '#333333',
+    radius: '8px'
+  },
+  soft: {
+    accent: '#6366f1',
+    accentSecondary: '#8b5cf6',
+    radius: '20px'
+  },
+  glass: {
+    radius: '14px'
+  }
+};
+function resolveTheme(themeConfig = {}) {
+  var _window$matchMedia, _window;
+  const {
+    mode = 'auto',
+    preset = 'default',
+    tokens = {}
+  } = themeConfig;
+  const isDark = mode === 'auto' ? ((_window$matchMedia = (_window = window).matchMedia) === null || _window$matchMedia === void 0 ? void 0 : _window$matchMedia.call(_window, '(prefers-color-scheme: dark)').matches) ?? true : mode === 'dark';
+  const base = isDark ? {
+    ...DARK_TOKENS
+  } : {
+    ...LIGHT_TOKENS
+  };
+  return {
+    ...base,
+    ...(PRESETS[preset] || {}),
+    ...tokens,
+    _isDark: isDark
+  };
+}
+function buildCSSVars(t) {
+  return `
+    --sai-accent:   ${t.accent};
+    --sai-accent2:  ${t.accentSecondary};
+    --sai-bg:       ${t.bg};
+    --sai-surface:  ${t.surface};
+    --sai-border:   ${t.border};
+    --sai-text:     ${t.text};
+    --sai-text-dim: ${t.textDim};
+    --sai-radius:   ${t.radius};
+    --sai-font:     ${t.fontFamily};
+  `;
+}
+function applyTheme(t) {
+  const panel = document.getElementById('sai-panel');
+  const trigger = document.getElementById('sai-trigger');
+  if (panel) panel.style.cssText += buildCSSVars(t);
+  if (trigger) trigger.style.cssText += buildCSSVars(t);
+}
+
+// Converts a corner/offset config into CSS position values for the
+// trigger button and the chat panel.
+
+function resolvePosition(posConfig = {}) {
+  const {
+    corner = 'bottom-right',
+    offsetX = 28,
+    offsetY = 28
+  } = posConfig;
+  const isLeft = corner.includes('left');
+  const isTop = corner.includes('top');
+  return {
+    trigger: {
+      [isLeft ? 'left' : 'right']: `${offsetX}px`,
+      [isTop ? 'top' : 'bottom']: `${offsetY}px`
+    },
+    panel: {
+      [isLeft ? 'left' : 'right']: `${offsetX}px`,
+      [isTop ? 'top' : 'bottom']: `${offsetY + 56 + 12}px`,
+      transformOrigin: isTop ? 'top center' : 'bottom center'
+    }
+  };
+}
+function positionToCSS(obj) {
+  return Object.entries(obj).map(([k, v]) => `${k}:${v}`).join(';');
+}
+
+// Injects the single <style> block that themes both the chat panel and the
+// Shepherd step overlays. Split from the UI builder so styles can be refreshed
+// independently on theme changes.
+
+const SHEPHERD_CSS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/css/shepherd.css';
+function loadShepherdCSS() {
+  if (document.querySelector(`link[href="${SHEPHERD_CSS}"]`)) return;
+  const l = document.createElement('link');
+  l.rel = 'stylesheet';
+  l.href = SHEPHERD_CSS;
+  document.head.appendChild(l);
+}
 
 /**
- * ╔══════════════════════════════════════════════════════════════╗
- * ║   @eventop/sdk  v1.1.0                                       ║
- * ║   AI-powered guided tours — themeable, provider-agnostic     ║
- * ║                                                              ║
- * ║   Provider: always proxy through your own server.            ║
- * ║   Never expose API keys in client-side code.                 ║
- * ╚══════════════════════════════════════════════════════════════╝
+ * Injects (or replaces) the #sai-styles <style> element.
+ *
+ * @param {object} theme  — resolved theme token object
+ * @param {object} pos    — resolved position object from resolvePosition()
  */
-(function (module) {
-  (function (global, factory) {
-    const Eventop = factory();
-    if (module.exports) {
-      module.exports = Eventop;
+function injectStyles(theme, pos) {
+  if (document.getElementById('sai-styles')) return;
+  const triggerCSS = positionToCSS(pos.trigger);
+  const panelCSS = positionToCSS(pos.panel);
+  const isDark = theme._isDark;
+  const stepBg = isDark ? 'var(--sai-bg)' : '#ffffff';
+  const stepSurf = isDark ? 'var(--sai-surface)' : '#f8f8fc';
+  const stepText = isDark ? 'var(--sai-text)' : '#1a1a2e';
+  const stepBorder = isDark ? 'var(--sai-border)' : '#e4e4f0';
+  const style = document.createElement('style');
+  style.id = 'sai-styles';
+  style.textContent = `
+    #sai-trigger, #sai-panel { ${buildCSSVars(theme)} }
+
+    /* ── Trigger ── */
+    #sai-trigger {
+      position: fixed; ${triggerCSS};
+      width: 54px; height: 54px; border-radius: 50%;
+      background: var(--sai-surface); border: 2px solid var(--sai-accent);
+      color: var(--sai-text); font-size: 20px; cursor: pointer; z-index: 99998;
+      display: flex; align-items: center; justify-content: center;
+      box-shadow: 0 4px 20px color-mix(in srgb, var(--sai-accent) 40%, transparent);
+      transition: transform .2s ease, box-shadow .2s ease;
+      font-family: var(--sai-font); padding: 0;
     }
-    // Always set on global in browser environments
-    if (typeof window !== 'undefined') {
-      window.Eventop = Eventop;
-    } else if (typeof global !== 'undefined') {
-      global.Eventop = Eventop;
+    #sai-trigger:hover {
+      transform: scale(1.08);
+      box-shadow: 0 6px 28px color-mix(in srgb, var(--sai-accent) 55%, transparent);
     }
-  })(typeof globalThis !== 'undefined' ? globalThis : commonjsGlobal, function () {
-
-    const SHEPHERD_CSS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/css/shepherd.css';
-    const SHEPHERD_JS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/js/shepherd.min.js';
-
-    // ─── Internal state ──────────────────────────────────────────────────────────
-    let _provider = null;
-    let _config = null;
-    let _tour = null;
-    let _isOpen = false;
-    let _messages = [];
-    let _mediaQuery = null;
-
-    // Pause/resume state
-    let _pausedSteps = null;
-    let _pausedIndex = 0;
-
-    // Active cleanup callbacks — cleared when tour ends or is paused
-    let _cleanups = [];
-
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  THEME ENGINE
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    const DARK_TOKENS = {
-      accent: '#e94560',
-      accentSecondary: '#a855f7',
-      bg: '#0f0f1a',
-      surface: '#1a1a2e',
-      border: '#2a2a4a',
-      text: '#e0e0f0',
-      textDim: '#6060a0',
-      radius: '16px',
-      fontFamily: "system-ui, -apple-system, 'Segoe UI', sans-serif"
-    };
-    const LIGHT_TOKENS = {
-      accent: '#e94560',
-      accentSecondary: '#7c3aed',
-      bg: '#ffffff',
-      surface: '#f8f8fc',
-      border: '#e4e4f0',
-      text: '#1a1a2e',
-      textDim: '#888899',
-      radius: '16px',
-      fontFamily: "system-ui, -apple-system, 'Segoe UI', sans-serif"
-    };
-    const PRESETS = {
-      default: {},
-      minimal: {
-        accent: '#000000',
-        accentSecondary: '#333333',
-        radius: '8px'
-      },
-      soft: {
-        accent: '#6366f1',
-        accentSecondary: '#8b5cf6',
-        radius: '20px'
-      },
-      glass: {
-        radius: '14px'
-      }
-    };
-    function resolveTheme(themeConfig = {}) {
-      var _window$matchMedia, _window;
-      const {
-        mode = 'auto',
-        preset = 'default',
-        tokens = {}
-      } = themeConfig;
-      const isDark = mode === 'auto' ? ((_window$matchMedia = (_window = window).matchMedia) === null || _window$matchMedia === void 0 ? void 0 : _window$matchMedia.call(_window, '(prefers-color-scheme: dark)').matches) ?? true : mode === 'dark';
-      const base = isDark ? {
-        ...DARK_TOKENS
-      } : {
-        ...LIGHT_TOKENS
-      };
-      return {
-        ...base,
-        ...(PRESETS[preset] || {}),
-        ...tokens,
-        _isDark: isDark
-      };
+    #sai-trigger .sai-pulse {
+      position: absolute; width: 100%; height: 100%; border-radius: 50%;
+      background: color-mix(in srgb, var(--sai-accent) 30%, transparent);
+      animation: sai-pulse 2.2s ease-out infinite; pointer-events: none;
     }
-    function buildCSSVars(t) {
-      return `
-      --sai-accent:   ${t.accent};
-      --sai-accent2:  ${t.accentSecondary};
-      --sai-bg:       ${t.bg};
-      --sai-surface:  ${t.surface};
-      --sai-border:   ${t.border};
-      --sai-text:     ${t.text};
-      --sai-text-dim: ${t.textDim};
-      --sai-radius:   ${t.radius};
-      --sai-font:     ${t.fontFamily};
-    `;
+    #sai-trigger.sai-paused .sai-pulse { animation: none; }
+    #sai-trigger.sai-paused::after {
+      content: '⏸'; position: absolute; bottom: -2px; right: -2px;
+      font-size: 12px; background: var(--sai-accent); border-radius: 50%;
+      width: 18px; height: 18px; display: flex; align-items: center;
+      justify-content: center; color: #fff; line-height: 1;
     }
-    function applyTheme(t) {
-      const panel = document.getElementById('sai-panel');
-      const trigger = document.getElementById('sai-trigger');
-      if (panel) {
-        panel.style.cssText += buildCSSVars(t);
-      }
-      if (trigger) {
-        trigger.style.cssText += buildCSSVars(t);
-      }
+    @keyframes sai-pulse {
+      0%   { transform: scale(1);    opacity: .8; }
+      100% { transform: scale(1.75); opacity: 0;  }
+    }
+
+    /* ── Panel ── */
+    #sai-panel {
+      position: fixed; ${panelCSS};
+      width: 340px; background: var(--sai-bg);
+      border: 1px solid var(--sai-border); border-radius: var(--sai-radius);
+      display: flex; flex-direction: column; z-index: 99999; overflow: hidden;
+      box-shadow: 0 16px 48px rgba(0,0,0,.18); font-family: var(--sai-font);
+      transform: translateY(12px) scale(.97); opacity: 0; pointer-events: none;
+      transition: transform .25s cubic-bezier(.34,1.56,.64,1), opacity .2s ease;
+      max-height: 520px;
     }
+    #sai-panel.sai-open { transform: translateY(0) scale(1); opacity: 1; pointer-events: all; }
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  POSITIONING
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    function resolvePosition(posConfig = {}) {
-      const {
-        corner = 'bottom-right',
-        offsetX = 28,
-        offsetY = 28
-      } = posConfig;
-      const isLeft = corner.includes('left');
-      const isTop = corner.includes('top');
-      return {
-        trigger: {
-          [isLeft ? 'left' : 'right']: `${offsetX}px`,
-          [isTop ? 'top' : 'bottom']: `${offsetY}px`
-        },
-        panel: {
-          [isLeft ? 'left' : 'right']: `${offsetX}px`,
-          [isTop ? 'top' : 'bottom']: `${offsetY + 56 + 12}px`,
-          transformOrigin: isTop ? 'top center' : 'bottom center'
-        }
-      };
+    /* ── Header ── */
+    #sai-header {
+      display: flex; align-items: center; gap: 10px; padding: 13px 15px;
+      background: var(--sai-surface); border-bottom: 1px solid var(--sai-border);
     }
-    function positionToCSS(obj) {
-      return Object.entries(obj).map(([k, v]) => `${k}:${v}`).join(';');
+    #sai-avatar {
+      width: 30px; height: 30px; border-radius: 50%;
+      background: linear-gradient(135deg, var(--sai-accent), var(--sai-accent2));
+      display: flex; align-items: center; justify-content: center;
+      font-size: 14px; flex-shrink: 0; color: #fff;
     }
+    #sai-header-info { flex: 1; min-width: 0; }
+    #sai-header-info h4 {
+      margin: 0; font-size: 13px; font-weight: 600; color: var(--sai-text);
+      white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    }
+    #sai-header-info p {
+      margin: 0; font-size: 11px; color: var(--sai-text-dim);
+      white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    }
+    #sai-close {
+      background: none; border: none; color: var(--sai-text-dim); cursor: pointer;
+      font-size: 18px; line-height: 1; padding: 0; flex-shrink: 0; transition: color .15s;
+    }
+    #sai-close:hover { color: var(--sai-text); }
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  PROVIDER
-    //  Only custom() is supported — route AI calls through your own server.
-    //
-    //  Your endpoint receives:  POST { systemPrompt, messages }
-    //  Your endpoint must return: { message: string, steps: Step[] }
-    //
-    //  @example
-    //  Eventop.init({
-    //    provider: Eventop.providers.custom(async ({ systemPrompt, messages }) => {
-    //      const res = await fetch('/api/guide', {
-    //        method:  'POST',
-    //        headers: { 'Content-Type': 'application/json' },
-    //        body:    JSON.stringify({ systemPrompt, messages }),
-    //      });
-    //      return res.json();
-    //    }),
-    //    config: { ... },
-    //  });
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    const providers = {
-      custom(fn) {
-        if (typeof fn !== 'function') throw new Error('[Eventop] providers.custom() requires a function');
-        return fn;
-      }
-    };
+    /* ── Messages ── */
+    #sai-messages {
+      flex: 1; overflow-y: auto; padding: 12px;
+      display: flex; flex-direction: column; gap: 9px;
+      min-height: 160px; max-height: 280px;
+      scrollbar-width: thin; scrollbar-color: var(--sai-border) transparent;
+    }
+    #sai-messages::-webkit-scrollbar { width: 4px; }
+    #sai-messages::-webkit-scrollbar-thumb { background: var(--sai-border); border-radius: 2px; }
+    .sai-msg {
+      max-width: 86%; padding: 8px 11px; border-radius: 11px;
+      font-size: 13px; line-height: 1.55; animation: sai-in .18s ease both;
+    }
+    @keyframes sai-in {
+      from { opacity: 0; transform: translateY(5px); }
+      to   { opacity: 1; transform: translateY(0); }
+    }
+    .sai-msg.sai-ai {
+      background: var(--sai-surface); color: var(--sai-text);
+      border-bottom-left-radius: 3px; align-self: flex-start;
+      border: 1px solid var(--sai-border);
+    }
+    .sai-msg.sai-user {
+      background: var(--sai-accent); color: #fff;
+      border-bottom-right-radius: 3px; align-self: flex-end;
+    }
+    .sai-msg.sai-error {
+      background: color-mix(in srgb, #ef4444 10%, var(--sai-bg));
+      color: #ef4444;
+      border: 1px solid color-mix(in srgb, #ef4444 25%, var(--sai-bg));
+      align-self: flex-start;
+    }
+    .sai-msg.sai-nav {
+      background: color-mix(in srgb, var(--sai-accent2) 8%, var(--sai-surface));
+      color: var(--sai-text);
+      border: 1px solid color-mix(in srgb, var(--sai-accent2) 20%, var(--sai-border));
+      border-bottom-left-radius: 3px; align-self: flex-start;
+      font-size: 12px;
+    }
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  SYSTEM PROMPT
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    function buildSystemPrompt() {
-      const screens = [...new Set((_config.features || []).filter(f => {
-        var _f$screen;
-        return (_f$screen = f.screen) === null || _f$screen === void 0 ? void 0 : _f$screen.id;
-      }).map(f => f.screen.id))];
-      const featureSummary = (_config.features || []).map(f => {
-        var _f$screen2, _f$flow;
-        const entry = {
-          id: f.id,
-          name: f.name,
-          description: f.description,
-          screen: ((_f$screen2 = f.screen) === null || _f$screen2 === void 0 ? void 0 : _f$screen2.id) || 'default'
-        };
-        if ((_f$flow = f.flow) !== null && _f$flow !== void 0 && _f$flow.length) {
-          entry.note = `This feature has ${f.flow.length} sequential sub-steps. Include ONE step per flow entry.`;
-        }
-        return entry;
-      });
-      return `
-You are an in-app assistant called "${_config.assistantName || 'AI Guide'}" for "${_config.appName}".
+    /* ── Typing indicator ── */
+    .sai-typing {
+      display: flex; gap: 4px; padding: 9px 12px; align-self: flex-start;
+      background: var(--sai-surface); border: 1px solid var(--sai-border);
+      border-radius: 11px; border-bottom-left-radius: 3px;
+    }
+    .sai-typing span {
+      width: 5px; height: 5px; border-radius: 50%;
+      background: var(--sai-text-dim); animation: sai-bounce 1.2s infinite;
+    }
+    .sai-typing span:nth-child(2) { animation-delay: .15s; }
+    .sai-typing span:nth-child(3) { animation-delay: .3s; }
+    @keyframes sai-bounce {
+      0%,80%,100% { transform: translateY(0); }
+      40%          { transform: translateY(-5px); }
+    }
+
+    /* ── Suggestions ── */
+    #sai-suggestions { display: flex; flex-wrap: wrap; gap: 6px; padding: 0 12px 10px; }
+    .sai-chip {
+      font-size: 11px; padding: 5px 10px; border-radius: 20px;
+      background: transparent; border: 1px solid var(--sai-border);
+      color: var(--sai-text-dim); cursor: pointer; font-family: inherit; transition: all .15s;
+    }
+    .sai-chip:hover {
+      border-color: var(--sai-accent); color: var(--sai-accent);
+      background: color-mix(in srgb, var(--sai-accent) 6%, transparent);
+    }
+
+    /* ── Input row ── */
+    #sai-inputrow {
+      display: flex; align-items: center; gap: 7px; padding: 9px 11px;
+      border-top: 1px solid var(--sai-border); background: var(--sai-bg);
+    }
+    #sai-input {
+      flex: 1; background: var(--sai-surface); border: 1px solid var(--sai-border);
+      border-radius: 8px; padding: 7px 11px; color: var(--sai-text);
+      font-size: 13px; outline: none; transition: border-color .15s; font-family: inherit;
+    }
+    #sai-input::placeholder { color: var(--sai-text-dim); }
+    #sai-input:focus { border-color: var(--sai-accent); }
+    #sai-send {
+      width: 32px; height: 32px; flex-shrink: 0; border-radius: 8px;
+      background: var(--sai-accent); border: none; color: #fff; font-size: 14px;
+      cursor: pointer; display: flex; align-items: center; justify-content: center;
+      transition: filter .15s, transform .1s; line-height: 1;
+    }
+    #sai-send:hover  { filter: brightness(1.1); }
+    #sai-send:active { transform: scale(.93); }
+    #sai-send:disabled { background: var(--sai-border); cursor: not-allowed; }
+
+    /* ── Shepherd step overrides ── */
+    .sai-shepherd-step {
+      background: ${stepBg} !important;
+      border: 1px solid ${stepBorder} !important;
+      border-radius: 12px !important;
+      box-shadow: 0 8px 36px rgba(0,0,0,.18) !important;
+      max-width: 290px !important;
+      font-family: var(--sai-font, system-ui) !important;
+    }
+    .sai-shepherd-step.shepherd-has-title .shepherd-content .shepherd-header {
+      background: ${stepSurf} !important; padding: 11px 15px 8px !important;
+      border-bottom: 1px solid ${stepBorder} !important;
+    }
+    .sai-shepherd-step .shepherd-title {
+      color: var(--sai-accent, #e94560) !important;
+      font-size: 13px !important; font-weight: 700 !important;
+    }
+    .sai-shepherd-step .shepherd-text {
+      color: ${stepText} !important; font-size: 13px !important;
+      line-height: 1.6 !important; padding: 10px 15px !important;
+    }
+    .sai-shepherd-step .shepherd-footer {
+      border-top: 1px solid ${stepBorder} !important; padding: 8px 11px !important;
+      background: ${stepBg} !important; display: flex; gap: 5px; flex-wrap: wrap;
+    }
+    .sai-shepherd-step .shepherd-button {
+      background: var(--sai-accent, #e94560) !important; color: #fff !important;
+      border: none !important; border-radius: 6px !important; padding: 6px 13px !important;
+      font-size: 12px !important; font-weight: 600 !important; cursor: pointer !important;
+      transition: filter .15s !important; font-family: var(--sai-font, system-ui) !important;
+    }
+    .sai-shepherd-step .shepherd-button:hover { filter: brightness(1.1) !important; }
+    .sai-shepherd-step .shepherd-button-secondary {
+      background: transparent !important; color: var(--sai-text-dim, #888) !important;
+      border: 1px solid ${stepBorder} !important;
+    }
+    .sai-shepherd-step .shepherd-button-secondary:hover {
+      background: ${stepSurf} !important; color: ${stepText} !important;
+    }
+    .sai-shepherd-step .shepherd-cancel-icon { color: var(--sai-text-dim, #888) !important; }
+    .sai-shepherd-step .shepherd-cancel-icon:hover { color: ${stepText} !important; }
+    .sai-shepherd-step[data-popper-placement] > .shepherd-arrow::before {
+      background: ${stepBorder} !important;
+    }
+
+    /* ── Progress bar ── */
+    .sai-progress { display: flex; align-items: center; gap: 8px; margin-left: auto; flex-shrink: 0; }
+    .sai-progress-bar {
+      width: 60px; height: 3px; border-radius: 2px; background: ${stepBorder}; overflow: hidden;
+    }
+    .sai-progress-fill {
+      height: 100%; border-radius: 2px;
+      background: var(--sai-accent, #e94560); transition: width .3s ease;
+    }
+    .sai-progress-label {
+      font-size: 10px; color: var(--sai-text-dim, #888);
+      white-space: nowrap; font-family: var(--sai-font, system-ui);
+    }
+
+    /* ── Step error ── */
+    .sai-step-error {
+      margin-top: 8px; padding: 6px 10px;
+      background: color-mix(in srgb, #ef4444 12%, ${stepBg});
+      border: 1px solid color-mix(in srgb, #ef4444 25%, ${stepBorder});
+      border-radius: 6px; color: #ef4444; font-size: 12px; line-height: 1.5;
+      animation: sai-in .18s ease;
+    }
+
+    /* ── Glass preset ── */
+    .sai-glass-preset .sai-shepherd-step {
+      background: rgba(255, 255, 255, 0.10) !important;
+      backdrop-filter: blur(18px) saturate(180%) !important;
+      -webkit-backdrop-filter: blur(18px) saturate(180%) !important;
+      border: 1px solid rgba(255, 255, 255, 0.22) !important;
+      box-shadow: 0 8px 36px rgba(0,0,0,.12) !important;
+    }
+    .sai-glass-preset .sai-shepherd-step .shepherd-text,
+    .sai-glass-preset .sai-shepherd-step .shepherd-title {
+      color: #ffffff !important;
+      text-shadow: 0 1px 3px rgba(0,0,0,.35);
+    }
+    .sai-glass-preset .sai-shepherd-step .shepherd-footer,
+    .sai-glass-preset .sai-shepherd-step .shepherd-header {
+      background: transparent !important;
+      border-color: rgba(255,255,255,0.15) !important;
+    }
+  `;
+  document.head.appendChild(style);
+}
+
+// Builds the system prompt that is sent to the AI on every request.
+// Keeping this separate makes it easy to iterate on prompt engineering
+// without touching tour or UI logic.
+
+/**
+ * @param {object} config  — the live _config object from state.js
+ * @returns {string}
+ */
+function buildSystemPrompt(config) {
+  const screens = [...new Set((config.features || []).filter(f => {
+    var _f$screen;
+    return (_f$screen = f.screen) === null || _f$screen === void 0 ? void 0 : _f$screen.id;
+  }).map(f => f.screen.id))];
+  const featureSummary = (config.features || []).map(f => {
+    var _f$screen2, _f$flow;
+    const entry = {
+      id: f.id,
+      name: f.name,
+      description: f.description,
+      screen: ((_f$screen2 = f.screen) === null || _f$screen2 === void 0 ? void 0 : _f$screen2.id) || 'default',
+      ...(f.route ? {
+        route: f.route
+      } : {})
+    };
+    if ((_f$flow = f.flow) !== null && _f$flow !== void 0 && _f$flow.length) {
+      entry.note = `This feature has ${f.flow.length} sequential sub-steps. Include ONE step per flow entry.`;
+    }
+    return entry;
+  });
+  return `
+You are an in-app assistant called "${config.assistantName || 'AI Guide'}" for "${config.appName}".
 Your ONLY job: guide users step-by-step through tasks using the feature map below.
 
 ${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. Features are screen-specific. The SDK handles navigation — just pick the right features.` : ''}
@@ -259,816 +537,902 @@ RULES:
    the SDK expands them automatically.
 8. Never skip features in a required sequence. Include every step end-to-end.
 `.trim();
-    }
-    async function callAI(userMessage) {
-      const systemPrompt = buildSystemPrompt();
-      const messagesWithNew = [..._messages, {
-        role: 'user',
-        content: userMessage
-      }];
-      const result = await _provider({
-        systemPrompt,
-        messages: messagesWithNew
-      });
-      _messages.push({
-        role: 'user',
-        content: userMessage
-      });
-      _messages.push({
-        role: 'assistant',
-        content: result.message
-      });
-      return result;
-    }
+}
+
+// Handles the request/response cycle with the AI provider.
+// Parses the structured JSON the AI must return and maintains conversation history.
+
+
+/**
+ * Sends the user's message to the provider, updates conversation history,
+ * and returns the parsed AI result.
+ *
+ * @param {string} userMessage
+ * @returns {Promise<{ message: string, steps: Array }>}
+ */
+async function callAI(userMessage) {
+  const systemPrompt = buildSystemPrompt(config);
+  const messagesWithNew = [...messages, {
+    role: 'user',
+    content: userMessage
+  }];
+  const result = await provider({
+    systemPrompt,
+    messages: messagesWithNew
+  });
+  setMessages([...messages, {
+    role: 'user',
+    content: userMessage
+  }, {
+    role: 'assistant',
+    content: result.message
+  }]);
+  return result;
+}
+
+// Handles all navigation concerns:
+//   • Route-based navigation (new, preferred)
+//   • Legacy screen-based navigation (backward-compat)
+//   • Pre-tour route announcement
+//   • Waiting for DOM elements and URL changes
+
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the current pathname. Centralised so it's easy to mock in tests.
+ */
+function getCurrentRoute() {
+  return typeof window !== 'undefined' ? window.location.pathname : '/';
+}
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  SCREEN NAVIGATION
-    // ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Polls until `window.location.pathname === targetRoute` or timeout.
+ * Resolves (never rejects) so a slow router doesn't blow up the tour.
+ *
+ * @param {string} targetRoute
+ * @param {number} [timeout=8000]
+ * @returns {Promise<void>}
+ */
+function waitForRouteChange(targetRoute, timeout = 8000) {
+  return new Promise(resolve => {
+    if (window.location.pathname === targetRoute) return resolve();
+    const interval = setInterval(() => {
+      if (window.location.pathname === targetRoute) {
+        clearInterval(interval);
+        clearTimeout(timer);
+        resolve();
+      }
+    }, 50);
+    const timer = setTimeout(() => {
+      clearInterval(interval);
+      console.warn(`[Eventop] Route change to "${targetRoute}" timed out — continuing`);
+      resolve();
+    }, timeout);
+    pushCleanup(() => {
+      clearInterval(interval);
+      clearTimeout(timer);
+    });
+  });
+}
 
-    async function ensureOnCorrectScreen(feature) {
-      if (!feature.screen) return;
-      if (typeof feature.screen.check === 'function' && feature.screen.check()) return;
-      addMsg('ai', 'Taking you to the right screen first…');
-      if (typeof feature.screen.navigate === 'function') {
-        feature.screen.navigate();
+/**
+ * Waits for a CSS selector to appear in the DOM (up to `timeout` ms).
+ * Resolves without throwing so a missing element doesn't crash the tour.
+ *
+ * @param {string} selector
+ * @param {number} [timeout=8000]
+ * @returns {Promise<void>}
+ */
+function waitForElement(selector, timeout = 8000) {
+  return new Promise(resolve => {
+    if (document.querySelector(selector)) return resolve();
+    const timer = setTimeout(() => {
+      observer.disconnect();
+      console.warn(`[Eventop] waitFor("${selector}") timed out — continuing`);
+      resolve();
+    }, timeout);
+    const observer = new MutationObserver(() => {
+      if (document.querySelector(selector)) {
+        clearTimeout(timer);
+        observer.disconnect();
+        resolve();
       }
-      const waitSelector = feature.screen.waitFor || feature.selector;
-      if (waitSelector) await waitForElement(waitSelector, 10000);
-    }
+    });
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+    pushCleanup(() => {
+      clearTimeout(timer);
+      observer.disconnect();
+    });
+  });
+}
+
+// ─── Route navigation ─────────────────────────────────────────────────────────
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  FLOW EXPANSION
-    //  A feature with flow[] gets expanded into multiple Shepherd steps.
-    //  Developer supplies selectors; AI supplies copy for the parent step.
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    function expandFlowSteps(aiStep, feature) {
-      var _feature$flow;
-      if (!((_feature$flow = feature.flow) !== null && _feature$flow !== void 0 && _feature$flow.length)) return [aiStep];
-      return feature.flow.map((entry, i) => ({
-        id: `${aiStep.id}-flow-${i}`,
-        title: i === 0 ? aiStep.title : `${aiStep.title} (${i + 1}/${feature.flow.length})`,
-        text: i === 0 ? aiStep.text : `Step ${i + 1} of ${feature.flow.length}: continue with the action highlighted below.`,
-        position: aiStep.position || 'bottom',
-        selector: entry.selector || null,
-        waitFor: entry.waitFor || null,
-        advanceOn: entry.advanceOn || null,
-        _parentId: aiStep.id
+/**
+ * Navigate to `route` using (in priority order):
+ *   1. state.router — the function passed by the developer
+ *   2. window.history.pushState + popstate — best-effort fallback for SPAs
+ *
+ * Shows a friendly chat message, then waits for the URL to confirm the change.
+ *
+ * @param {string} route
+ * @param {string} [featureName]
+ * @returns {Promise<void>}
+ */
+async function navigateToRoute(route, featureName) {
+  if (!route || getCurrentRoute() === route) return;
+  addMsg('ai', `↗ Taking you to ${featureName ? `the ${featureName} area` : route}…`);
+  try {
+    if (router) {
+      await Promise.resolve(router(route));
+    } else {
+      window.history.pushState({}, '', route);
+      window.dispatchEvent(new PopStateEvent('popstate', {
+        state: {}
       }));
     }
+  } catch (err) {
+    console.warn('[Eventop] Navigation error:', err);
+  }
+  await waitForRouteChange(route, 8000);
+  await new Promise(r => setTimeout(r, 80));
+}
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  SHEPHERD RUNNER
-    // ═══════════════════════════════════════════════════════════════════════════
+// ─── Route preview / announcement ────────────────────────────────────────────
 
-    function loadCSS(href) {
-      if (document.querySelector(`link[href="${href}"]`)) return;
-      const l = document.createElement('link');
-      l.rel = 'stylesheet';
-      l.href = href;
-      document.head.appendChild(l);
-    }
-    function loadScript(src) {
-      return new Promise((res, rej) => {
-        if (document.querySelector(`script[src="${src}"]`)) return res();
-        const s = document.createElement('script');
-        s.src = src;
-        s.onload = res;
-        s.onerror = rej;
-        document.head.appendChild(s);
-      });
-    }
-    async function ensureShepherd() {
-      if (typeof Shepherd !== 'undefined') return;
-      loadCSS(SHEPHERD_CSS);
-      await loadScript(SHEPHERD_JS);
-    }
-    function waitForElement(selector, timeout = 8000) {
-      return new Promise(resolve => {
-        if (document.querySelector(selector)) return resolve();
-        const timer = setTimeout(() => {
-          observer.disconnect();
-          console.warn(`[Eventop] waitFor("${selector}") timed out — continuing`);
-          resolve();
-        }, timeout);
-        const observer = new MutationObserver(() => {
-          if (document.querySelector(selector)) {
-            clearTimeout(timer);
-            observer.disconnect();
-            resolve();
-          }
-        });
-        observer.observe(document.body, {
-          childList: true,
-          subtree: true
-        });
-        _cleanups.push(() => {
-          clearTimeout(timer);
-          observer.disconnect();
-        });
-      });
-    }
-    function mergeWithFeature(step) {
-      var _config2;
-      if (!((_config2 = _config) !== null && _config2 !== void 0 && _config2.features)) return step;
-      const feature = _config.features.find(f => f.id === step.id);
-      if (!feature) return step;
-      return {
-        waitFor: feature.waitFor || null,
-        advanceOn: feature.advanceOn || null,
-        validate: feature.validate || null,
-        screen: feature.screen || null,
-        flow: feature.flow || null,
-        ...step,
-        selector: feature.selector || step.selector // feature map always wins
-      };
-    }
-    function wireAdvanceOn(shepherdStep, advanceOn, tour) {
-      if (!(advanceOn !== null && advanceOn !== void 0 && advanceOn.selector) || !(advanceOn !== null && advanceOn !== void 0 && advanceOn.event)) return;
-      function handler(e) {
-        if (e.target.matches(advanceOn.selector) || e.target.closest(advanceOn.selector)) {
-          setTimeout(() => {
-            if (tour && !tour.isActive()) return;
-            tour.next();
-          }, advanceOn.delay || 300);
-        }
-      }
-      document.addEventListener(advanceOn.event, handler, true);
-      _cleanups.push(() => document.removeEventListener(advanceOn.event, handler, true));
-      shepherdStep.on('show', () => {
-        var _shepherdStep$getElem;
-        const nextBtn = (_shepherdStep$getElem = shepherdStep.getElement()) === null || _shepherdStep$getElem === void 0 ? void 0 : _shepherdStep$getElem.querySelector('.shepherd-footer .shepherd-button:not(.shepherd-button-secondary)');
-        if (nextBtn && !shepherdStep._isLast) {
-          nextBtn.style.opacity = '0.4';
-          nextBtn.title = 'Complete the action above to continue';
-        }
-      });
-    }
-    function addProgressIndicator(shepherdStep, index, total) {
-      shepherdStep.on('show', () => {
-        var _shepherdStep$getElem2;
-        const header = (_shepherdStep$getElem2 = shepherdStep.getElement()) === null || _shepherdStep$getElem2 === void 0 ? void 0 : _shepherdStep$getElem2.querySelector('.shepherd-header');
-        if (!header || header.querySelector('.sai-progress')) return;
-        const pct = Math.round((index + 1) / total * 100);
-        const wrapper = document.createElement('div');
-        wrapper.className = 'sai-progress';
-        wrapper.innerHTML = `
-        <div class="sai-progress-bar">
-          <div class="sai-progress-fill" style="width:${pct}%"></div>
-        </div>
-        <span class="sai-progress-label">${index + 1} / ${total}</span>
-      `;
-        header.appendChild(wrapper);
-      });
-    }
-    function showResumeButton(fromIndex) {
-      var _document$getElementB, _document$getElementB2;
-      const msgs = document.getElementById('sai-messages');
-      if (!msgs) return;
-      (_document$getElementB = document.getElementById('sai-resume-prompt')) === null || _document$getElementB === void 0 || _document$getElementB.remove();
-      const div = document.createElement('div');
-      div.id = 'sai-resume-prompt';
-      div.className = 'sai-msg sai-ai';
-      div.innerHTML = `
-      Tour paused. Ready when you are.
-      <br/>
-      <button class="sai-chip" id="sai-resume-btn" style="display:inline-block;margin-top:8px;">
-        ▶ Resume from step ${fromIndex + 1}
-      </button>
-    `;
-      msgs.appendChild(div);
-      msgs.scrollTop = msgs.scrollHeight;
-      (_document$getElementB2 = document.getElementById('sai-resume-btn')) === null || _document$getElementB2 === void 0 || _document$getElementB2.addEventListener('click', () => {
-        div.remove();
-        if (!_pausedSteps) return;
-        const steps = _pausedSteps;
-        const idx = _pausedIndex;
-        _pausedSteps = null;
-        _pausedIndex = 0;
-        if (_isOpen) togglePanel();
-        runTour(steps.slice(idx));
+/**
+ * Inspects the AI's step list and returns which routes will be visited
+ * that the user isn't already on — in visit order, deduplicated.
+ *
+ * @param {Array}  aiSteps
+ * @returns {Array<{ route: string, featureName: string }>}
+ */
+function previewRoutesNeeded(aiSteps) {
+  const currentRoute = getCurrentRoute();
+  const seen = new Set([currentRoute]);
+  const ordered = [];
+  aiSteps.forEach(step => {
+    var _state$config;
+    const feature = (_state$config = config) === null || _state$config === void 0 || (_state$config = _state$config.features) === null || _state$config === void 0 ? void 0 : _state$config.find(f => f.id === step.id);
+    if (feature !== null && feature !== void 0 && feature.route && !seen.has(feature.route)) {
+      seen.add(feature.route);
+      ordered.push({
+        route: feature.route,
+        featureName: feature.name
       });
-      if (!_isOpen) togglePanel();
     }
-    async function runTour(steps, options = {}) {
-      var _config3;
-      await ensureShepherd();
-      if (_tour) {
-        _tour.cancel();
-      }
-      _cleanups.forEach(fn => fn());
-      _cleanups = [];
-      _tour = null;
-      if (!(steps !== null && steps !== void 0 && steps.length)) return;
-      const {
-        showProgress = true,
-        waitTimeout = 8000
-      } = options;
-
-      // Merge AI steps with feature map
-      const mergedSteps = steps.map(mergeWithFeature);
-
-      // Navigate to the correct screen for the first step if needed
-      const firstFeature = (_config3 = _config) === null || _config3 === void 0 || (_config3 = _config3.features) === null || _config3 === void 0 ? void 0 : _config3.find(f => {
-        var _mergedSteps$;
-        return f.id === ((_mergedSteps$ = mergedSteps[0]) === null || _mergedSteps$ === void 0 ? void 0 : _mergedSteps$.id);
-      });
-      if (firstFeature) await ensureOnCorrectScreen(firstFeature);
+  });
+  return ordered;
+}
 
-      // Expand flow[] features into individual Shepherd steps
-      const expandedSteps = mergedSteps.flatMap(step => {
-        var _config4;
-        const feature = (_config4 = _config) === null || _config4 === void 0 || (_config4 = _config4.features) === null || _config4 === void 0 ? void 0 : _config4.find(f => f.id === step.id);
-        return feature ? expandFlowSteps(step, feature) : [step];
-      });
-      const ShepherdClass = typeof Shepherd !== 'undefined' ? Shepherd : window.Shepherd;
-      _tour = new ShepherdClass.Tour({
-        useModalOverlay: true,
-        defaultStepOptions: {
-          scrollTo: {
-            behavior: 'smooth',
-            block: 'center'
-          },
-          cancelIcon: {
-            enabled: true
-          },
-          classes: 'sai-shepherd-step'
-        }
-      });
-      expandedSteps.forEach((step, i) => {
-        var _step$advanceOn, _step$advanceOn2;
-        const isLast = i === expandedSteps.length - 1;
-        const hasAuto = !!((_step$advanceOn = step.advanceOn) !== null && _step$advanceOn !== void 0 && _step$advanceOn.selector && (_step$advanceOn2 = step.advanceOn) !== null && _step$advanceOn2 !== void 0 && _step$advanceOn2.event);
-        const buttons = [];
-        if (i > 0) {
-          buttons.push({
-            text: '← Back',
-            action: _tour.back,
-            secondary: true
-          });
-        }
-        buttons.push({
-          text: isLast ? 'Done ✓' : 'Next →',
-          action: isLast ? _tour.complete : _tour.next
-        });
-        buttons.push({
-          text: '⏸ Pause',
-          secondary: true,
-          action: function () {
-            _tour.cancel();
-          }
-        });
-        const shepherdStep = _tour.addStep({
-          id: step.id || `sai-step-${i}`,
-          title: step.title,
-          text: step.text,
-          attachTo: step.selector ? {
-            element: step.selector,
-            on: step.position || 'bottom'
-          } : undefined,
-          beforeShowPromise: step.waitFor ? () => waitForElement(step.waitFor, waitTimeout) : undefined,
-          buttons
-        });
-        shepherdStep._isLast = isLast;
-        if (hasAuto) wireAdvanceOn(shepherdStep, step.advanceOn, _tour);
-        if (showProgress && expandedSteps.length > 1) {
-          addProgressIndicator(shepherdStep, i, expandedSteps.length);
-        }
-      });
-      _tour.on('complete', () => {
-        _cleanups.forEach(fn => fn());
-        _cleanups = [];
-        _pausedSteps = null;
-        _pausedIndex = 0;
-        _tour = null;
-      });
+/**
+ * Adds a human-readable pre-tour navigation announcement to the chat.
+ *
+ * @param {Array<{ route: string, featureName: string }>} routesNeeded
+ */
+function announceNavigationPlan(routesNeeded) {
+  if (!routesNeeded.length) return;
+  const names = routesNeeded.map(r => r.featureName || r.route);
+  let msg;
+  if (names.length === 1) {
+    msg = `🗺 I'll navigate you to the ${names[0]} area automatically — no need to go there yourself.`;
+  } else {
+    const list = names.slice(0, -1).join(', ') + ' and ' + names[names.length - 1];
+    msg = `🗺 This tour visits ${names.length} areas: ${list}. I'll navigate between them automatically.`;
+  }
+  addMsg('ai', msg);
+}
 
-      // Cancel → pause instead of hard destroy
-      _tour.on('cancel', () => {
-        const currentStepEl = _tour.getCurrentStep();
-        const currentIdx = currentStepEl ? expandedSteps.findIndex(s => s.id === currentStepEl.id) : 0;
-        _cleanups.forEach(fn => fn());
-        _cleanups = [];
-        _pausedSteps = expandedSteps;
-        _pausedIndex = Math.max(0, currentIdx);
-        _tour = null;
-        showResumeButton(_pausedIndex);
-      });
-      _tour.start();
-    }
-    function stepComplete() {
-      var _tour2;
-      if ((_tour2 = _tour) !== null && _tour2 !== void 0 && _tour2.isActive()) _tour.next();
-    }
-    function stepFail(message) {
-      var _tour3, _el$querySelector;
-      if (!((_tour3 = _tour) !== null && _tour3 !== void 0 && _tour3.isActive())) return;
-      const current = _tour.getCurrentStep();
-      if (!current) return;
-      const el = current.getElement();
-      el === null || el === void 0 || (_el$querySelector = el.querySelector('.sai-step-error')) === null || _el$querySelector === void 0 || _el$querySelector.remove();
-      if (message) {
-        var _el$querySelector2;
-        const err = document.createElement('div');
-        err.className = 'sai-step-error';
-        err.textContent = '⚠ ' + message;
-        el === null || el === void 0 || (_el$querySelector2 = el.querySelector('.shepherd-text')) === null || _el$querySelector2 === void 0 || _el$querySelector2.appendChild(err);
-      }
-    }
+// ─── Legacy screen navigation ─────────────────────────────────────────────────
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  STYLES
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    function injectStyles(theme, pos) {
-      if (document.getElementById('sai-styles')) return;
-      const triggerCSS = positionToCSS(pos.trigger);
-      const panelCSS = positionToCSS(pos.panel);
-      const isDark = theme._isDark;
-      const stepBg = isDark ? 'var(--sai-bg)' : '#ffffff';
-      const stepSurf = isDark ? 'var(--sai-surface)' : '#f8f8fc';
-      const stepText = isDark ? 'var(--sai-text)' : '#1a1a2e';
-      const stepBorder = isDark ? 'var(--sai-border)' : '#e4e4f0';
-      const style = document.createElement('style');
-      style.id = 'sai-styles';
-      style.textContent = `
-      #sai-trigger, #sai-panel { ${buildCSSVars(theme)} }
-
-      /* ── Trigger ── */
-      #sai-trigger {
-        position: fixed; ${triggerCSS};
-        width: 54px; height: 54px; border-radius: 50%;
-        background: var(--sai-surface); border: 2px solid var(--sai-accent);
-        color: var(--sai-text); font-size: 20px; cursor: pointer; z-index: 99998;
-        display: flex; align-items: center; justify-content: center;
-        box-shadow: 0 4px 20px color-mix(in srgb, var(--sai-accent) 40%, transparent);
-        transition: transform .2s ease, box-shadow .2s ease;
-        font-family: var(--sai-font); padding: 0;
-      }
-      #sai-trigger:hover {
-        transform: scale(1.08);
-        box-shadow: 0 6px 28px color-mix(in srgb, var(--sai-accent) 55%, transparent);
-      }
-      #sai-trigger .sai-pulse {
-        position: absolute; width: 100%; height: 100%; border-radius: 50%;
-        background: color-mix(in srgb, var(--sai-accent) 30%, transparent);
-        animation: sai-pulse 2.2s ease-out infinite; pointer-events: none;
-      }
-      #sai-trigger.sai-paused .sai-pulse { animation: none; }
-      #sai-trigger.sai-paused::after {
-        content: '⏸'; position: absolute; bottom: -2px; right: -2px;
-        font-size: 12px; background: var(--sai-accent); border-radius: 50%;
-        width: 18px; height: 18px; display: flex; align-items: center;
-        justify-content: center; color: #fff; line-height: 1;
-      }
-      @keyframes sai-pulse {
-        0%   { transform: scale(1);    opacity: .8; }
-        100% { transform: scale(1.75); opacity: 0;  }
-      }
+/**
+ * Handles the legacy `screen` prop on features (backward-compat).
+ * Checks `screen.check()` and calls `screen.navigate()` if needed,
+ * then waits for `screen.waitFor` or `feature.selector` to appear.
+ *
+ * @param {object} feature — a feature config object
+ * @returns {Promise<void>}
+ */
+async function ensureOnCorrectScreen(feature) {
+  if (!feature.screen) return;
+  if (typeof feature.screen.check === 'function' && feature.screen.check()) return;
+  addMsg('ai', 'Taking you to the right screen first…');
+  if (typeof feature.screen.navigate === 'function') {
+    feature.screen.navigate();
+  }
+  const waitSelector = feature.screen.waitFor || feature.selector;
+  if (waitSelector) await waitForElement(waitSelector, 10000);
+}
 
-      /* ── Panel ── */
-      #sai-panel {
-        position: fixed; ${panelCSS};
-        width: 340px; background: var(--sai-bg);
-        border: 1px solid var(--sai-border); border-radius: var(--sai-radius);
-        display: flex; flex-direction: column; z-index: 99999; overflow: hidden;
-        box-shadow: 0 16px 48px rgba(0,0,0,.18); font-family: var(--sai-font);
-        transform: translateY(12px) scale(.97); opacity: 0; pointer-events: none;
-        transition: transform .25s cubic-bezier(.34,1.56,.64,1), opacity .2s ease;
-        max-height: 520px;
-      }
-      #sai-panel.sai-open { transform: translateY(0) scale(1); opacity: 1; pointer-events: all; }
+// Builds and manages the chat panel DOM.
+// Also exports the low-level message helpers used by navigation.js and tour.js
+// so they can surface status messages without importing the full chat module.
 
-      /* ── Header ── */
-      #sai-header {
-        display: flex; align-items: center; gap: 10px; padding: 13px 15px;
-        background: var(--sai-surface); border-bottom: 1px solid var(--sai-border);
-      }
-      #sai-avatar {
-        width: 30px; height: 30px; border-radius: 50%;
-        background: linear-gradient(135deg, var(--sai-accent), var(--sai-accent2));
-        display: flex; align-items: center; justify-content: center;
-        font-size: 14px; flex-shrink: 0; color: #fff;
-      }
-      #sai-header-info { flex: 1; min-width: 0; }
-      #sai-header-info h4 {
-        margin: 0; font-size: 13px; font-weight: 600; color: var(--sai-text);
-        white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
-      }
-      #sai-header-info p {
-        margin: 0; font-size: 11px; color: var(--sai-text-dim);
-        white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
-      }
-      #sai-close {
-        background: none; border: none; color: var(--sai-text-dim); cursor: pointer;
-        font-size: 18px; line-height: 1; padding: 0; flex-shrink: 0; transition: color .15s;
-      }
-      #sai-close:hover { color: var(--sai-text); }
-
-      /* ── Messages ── */
-      #sai-messages {
-        flex: 1; overflow-y: auto; padding: 12px;
-        display: flex; flex-direction: column; gap: 9px;
-        min-height: 160px; max-height: 280px;
-        scrollbar-width: thin; scrollbar-color: var(--sai-border) transparent;
-      }
-      #sai-messages::-webkit-scrollbar { width: 4px; }
-      #sai-messages::-webkit-scrollbar-thumb { background: var(--sai-border); border-radius: 2px; }
-      .sai-msg {
-        max-width: 86%; padding: 8px 11px; border-radius: 11px;
-        font-size: 13px; line-height: 1.55; animation: sai-in .18s ease both;
-      }
-      @keyframes sai-in {
-        from { opacity: 0; transform: translateY(5px); }
-        to   { opacity: 1; transform: translateY(0); }
-      }
-      .sai-msg.sai-ai {
-        background: var(--sai-surface); color: var(--sai-text);
-        border-bottom-left-radius: 3px; align-self: flex-start;
-        border: 1px solid var(--sai-border);
-      }
-      .sai-msg.sai-user {
-        background: var(--sai-accent); color: #fff;
-        border-bottom-right-radius: 3px; align-self: flex-end;
-      }
-      .sai-msg.sai-error {
-        background: color-mix(in srgb, #ef4444 10%, var(--sai-bg));
-        color: #ef4444;
-        border: 1px solid color-mix(in srgb, #ef4444 25%, var(--sai-bg));
-        align-self: flex-start;
-      }
 
-      /* ── Typing indicator ── */
-      .sai-typing {
-        display: flex; gap: 4px; padding: 9px 12px; align-self: flex-start;
-        background: var(--sai-surface); border: 1px solid var(--sai-border);
-        border-radius: 11px; border-bottom-left-radius: 3px;
-      }
-      .sai-typing span {
-        width: 5px; height: 5px; border-radius: 50%;
-        background: var(--sai-text-dim); animation: sai-bounce 1.2s infinite;
-      }
-      .sai-typing span:nth-child(2) { animation-delay: .15s; }
-      .sai-typing span:nth-child(3) { animation-delay: .3s; }
-      @keyframes sai-bounce {
-        0%,80%,100% { transform: translateY(0); }
-        40%          { transform: translateY(-5px); }
-      }
+// Imported lazily inside handleSend to avoid a circular dep at module parse time.
+// (chat → tour → chat would otherwise cycle.)
+let _runTour = null;
+function setRunTour(fn) {
+  _runTour = fn;
+}
 
-      /* ── Suggestions ── */
-      #sai-suggestions { display: flex; flex-wrap: wrap; gap: 6px; padding: 0 12px 10px; }
-      .sai-chip {
-        font-size: 11px; padding: 5px 10px; border-radius: 20px;
-        background: transparent; border: 1px solid var(--sai-border);
-        color: var(--sai-text-dim); cursor: pointer; font-family: inherit; transition: all .15s;
-      }
-      .sai-chip:hover {
-        border-color: var(--sai-accent); color: var(--sai-accent);
-        background: color-mix(in srgb, var(--sai-accent) 6%, transparent);
-      }
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 
-      /* ── Input row ── */
-      #sai-inputrow {
-        display: flex; align-items: center; gap: 7px; padding: 9px 11px;
-        border-top: 1px solid var(--sai-border); background: var(--sai-bg);
-      }
-      #sai-input {
-        flex: 1; background: var(--sai-surface); border: 1px solid var(--sai-border);
-        border-radius: 8px; padding: 7px 11px; color: var(--sai-text);
-        font-size: 13px; outline: none; transition: border-color .15s; font-family: inherit;
-      }
-      #sai-input::placeholder { color: var(--sai-text-dim); }
-      #sai-input:focus { border-color: var(--sai-accent); }
-      #sai-send {
-        width: 32px; height: 32px; flex-shrink: 0; border-radius: 8px;
-        background: var(--sai-accent); border: none; color: #fff; font-size: 14px;
-        cursor: pointer; display: flex; align-items: center; justify-content: center;
-        transition: filter .15s, transform .1s; line-height: 1;
-      }
-      #sai-send:hover  { filter: brightness(1.1); }
-      #sai-send:active { transform: scale(.93); }
-      #sai-send:disabled { background: var(--sai-border); cursor: not-allowed; }
-
-      /* ── Shepherd step overrides ── */
-      .sai-shepherd-step {
-        background: ${stepBg} !important;
-        border: 1px solid ${stepBorder} !important;
-        border-radius: 12px !important;
-        box-shadow: 0 8px 36px rgba(0,0,0,.18) !important;
-        max-width: 290px !important;
-        font-family: var(--sai-font, system-ui) !important;
-      }
-      .sai-shepherd-step.shepherd-has-title .shepherd-content .shepherd-header {
-        background: ${stepSurf} !important; padding: 11px 15px 8px !important;
-        border-bottom: 1px solid ${stepBorder} !important;
-      }
-      .sai-shepherd-step .shepherd-title {
-        color: var(--sai-accent, #e94560) !important;
-        font-size: 13px !important; font-weight: 700 !important;
-      }
-      .sai-shepherd-step .shepherd-text {
-        color: ${stepText} !important; font-size: 13px !important;
-        line-height: 1.6 !important; padding: 10px 15px !important;
-      }
-      .sai-shepherd-step .shepherd-footer {
-        border-top: 1px solid ${stepBorder} !important; padding: 8px 11px !important;
-        background: ${stepBg} !important; display: flex; gap: 5px; flex-wrap: wrap;
-      }
-      .sai-shepherd-step .shepherd-button {
-        background: var(--sai-accent, #e94560) !important; color: #fff !important;
-        border: none !important; border-radius: 6px !important; padding: 6px 13px !important;
-        font-size: 12px !important; font-weight: 600 !important; cursor: pointer !important;
-        transition: filter .15s !important; font-family: var(--sai-font, system-ui) !important;
-      }
-      .sai-shepherd-step .shepherd-button:hover { filter: brightness(1.1) !important; }
-      .sai-shepherd-step .shepherd-button-secondary {
-        background: transparent !important; color: var(--sai-text-dim, #888) !important;
-        border: 1px solid ${stepBorder} !important;
-      }
-      .sai-shepherd-step .shepherd-button-secondary:hover {
-        background: ${stepSurf} !important; color: ${stepText} !important;
-      }
-      .sai-shepherd-step .shepherd-cancel-icon { color: var(--sai-text-dim, #888) !important; }
-      .sai-shepherd-step .shepherd-cancel-icon:hover { color: ${stepText} !important; }
-      .sai-shepherd-step[data-popper-placement] > .shepherd-arrow::before {
-        background: ${stepBorder} !important;
-      }
+function escHTML(str) {
+  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
 
-      /* ── Progress bar ── */
-      .sai-progress { display: flex; align-items: center; gap: 8px; margin-left: auto; flex-shrink: 0; }
-      .sai-progress-bar {
-        width: 60px; height: 3px; border-radius: 2px; background: ${stepBorder}; overflow: hidden;
-      }
-      .sai-progress-fill {
-        height: 100%; border-radius: 2px;
-        background: var(--sai-accent, #e94560); transition: width .3s ease;
-      }
-      .sai-progress-label {
-        font-size: 10px; color: var(--sai-text-dim, #888);
-        white-space: nowrap; font-family: var(--sai-font, system-ui);
-      }
+// ─── Panel visibility ─────────────────────────────────────────────────────────
 
-      /* ── Step error ── */
-      .sai-step-error {
-        margin-top: 8px; padding: 6px 10px;
-        background: color-mix(in srgb, #ef4444 12%, ${stepBg});
-        border: 1px solid color-mix(in srgb, #ef4444 25%, ${stepBorder});
-        border-radius: 6px; color: #ef4444; font-size: 12px; line-height: 1.5;
-        animation: sai-in .18s ease;
-      }
+function togglePanel() {
+  var _document$getElementB, _document$getElementB2, _document$getElementB3;
+  setIsOpen(!isOpen);
+  (_document$getElementB = document.getElementById('sai-panel')) === null || _document$getElementB === void 0 || _document$getElementB.classList.toggle('sai-open', isOpen);
+  (_document$getElementB2 = document.getElementById('sai-trigger')) === null || _document$getElementB2 === void 0 || _document$getElementB2.classList.toggle('sai-paused', !!pausedSteps);
+  if (isOpen) (_document$getElementB3 = document.getElementById('sai-input')) === null || _document$getElementB3 === void 0 || _document$getElementB3.focus();
+}
 
-      /* ── Glass preset ── */
-      .sai-glass-preset .sai-shepherd-step {
-        background: rgba(255, 255, 255, 0.10) !important;
-        backdrop-filter: blur(18px) saturate(180%) !important;
-        -webkit-backdrop-filter: blur(18px) saturate(180%) !important;
-        border: 1px solid rgba(255, 255, 255, 0.22) !important;
-        box-shadow: 0 8px 36px rgba(0,0,0,.12) !important;
-      }
-      .sai-glass-preset .sai-shepherd-step .shepherd-text,
-      .sai-glass-preset .sai-shepherd-step .shepherd-title {
-        color: #ffffff !important;
-        text-shadow: 0 1px 3px rgba(0,0,0,.35);
-      }
-      .sai-glass-preset .sai-shepherd-step .shepherd-footer,
-      .sai-glass-preset .sai-shepherd-step .shepherd-header {
-        background: transparent !important;
-        border-color: rgba(255,255,255,0.15) !important;
+// ─── Message helpers (also used by navigation.js / tour.js) ──────────────────
+
+function addMsg(type, text) {
+  const msgs = document.getElementById('sai-messages');
+  if (!msgs) return;
+  const div = document.createElement('div');
+  div.className = `sai-msg sai-${type}`;
+  div.textContent = text;
+  msgs.appendChild(div);
+  msgs.scrollTop = msgs.scrollHeight;
+}
+function showTyping() {
+  const msgs = document.getElementById('sai-messages');
+  const el = document.createElement('div');
+  el.className = 'sai-typing';
+  el.id = 'sai-typing';
+  el.innerHTML = '<span></span><span></span><span></span>';
+  msgs.appendChild(el);
+  msgs.scrollTop = msgs.scrollHeight;
+}
+function hideTyping() {
+  var _document$getElementB4;
+  (_document$getElementB4 = document.getElementById('sai-typing')) === null || _document$getElementB4 === void 0 || _document$getElementB4.remove();
+}
+function setDisabled(d) {
+  ['sai-input', 'sai-send'].forEach(id => {
+    const el = document.getElementById(id);
+    if (el) el.disabled = d;
+  });
+}
+
+// ─── Pause/resume UI ──────────────────────────────────────────────────────────
+
+/**
+ * Renders the "Tour paused — Resume from step N" bubble in the chat.
+ * Also opens the panel if it's currently closed.
+ *
+ * @param {number} fromIndex  — zero-based step index to resume from
+ */
+function showResumeButton(fromIndex) {
+  var _document$getElementB5, _document$getElementB6;
+  const msgs = document.getElementById('sai-messages');
+  if (!msgs) return;
+  (_document$getElementB5 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB5 === void 0 || _document$getElementB5.remove();
+  const div = document.createElement('div');
+  div.id = 'sai-resume-prompt';
+  div.className = 'sai-msg sai-ai';
+  div.innerHTML = `
+    Tour paused. Ready when you are.
+    <br/>
+    <button class="sai-chip" id="sai-resume-btn" style="display:inline-block;margin-top:8px;">
+      ▶ Resume from step ${fromIndex + 1}
+    </button>
+  `;
+  msgs.appendChild(div);
+  msgs.scrollTop = msgs.scrollHeight;
+  (_document$getElementB6 = document.getElementById('sai-resume-btn')) === null || _document$getElementB6 === void 0 || _document$getElementB6.addEventListener('click', () => {
+    var _runTour2;
+    div.remove();
+    if (!pausedSteps) return;
+    const steps = pausedSteps;
+    const idx = pausedIndex;
+    setPausedSteps(null);
+    setPausedIndex(0);
+    if (isOpen) togglePanel();
+    (_runTour2 = _runTour) === null || _runTour2 === void 0 || _runTour2(steps.slice(idx));
+  });
+  if (!isOpen) togglePanel();
+}
+
+// ─── Send / AI round-trip ─────────────────────────────────────────────────────
+
+async function handleSend(text) {
+  var _document$getElementB7, _document$getElementB8;
+  const input = document.getElementById('sai-input');
+  if (input) input.value = '';
+  document.getElementById('sai-suggestions').style.display = 'none';
+
+  // New message clears any existing pause state
+  setPausedSteps(null);
+  setPausedIndex(0);
+  (_document$getElementB7 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB7 === void 0 || _document$getElementB7.remove();
+  (_document$getElementB8 = document.getElementById('sai-trigger')) === null || _document$getElementB8 === void 0 || _document$getElementB8.classList.remove('sai-paused');
+  addMsg('user', text);
+  setDisabled(true);
+  showTyping();
+  try {
+    var _result$steps;
+    const result = await callAI(text);
+    hideTyping();
+    addMsg('ai', result.message);
+    if ((_result$steps = result.steps) !== null && _result$steps !== void 0 && _result$steps.length) {
+      const routesNeeded = previewRoutesNeeded(result.steps);
+      if (routesNeeded.length > 0) {
+        announceNavigationPlan(routesNeeded);
       }
-    `;
-      document.head.appendChild(style);
+      const delay = routesNeeded.length > 0 ? 1200 : 600;
+      setTimeout(() => {
+        var _runTour3;
+        togglePanel();
+        (_runTour3 = _runTour) === null || _runTour3 === void 0 || _runTour3(result.steps);
+      }, delay);
     }
+  } catch (err) {
+    hideTyping();
+    addMsg('error', err.message || 'Something went wrong. Please try again.');
+    console.error('[Eventop]', err);
+  } finally {
+    var _document$getElementB9;
+    setDisabled(false);
+    (_document$getElementB9 = document.getElementById('sai-input')) === null || _document$getElementB9 === void 0 || _document$getElementB9.focus();
+  }
+}
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  CHAT UI
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    function buildChat(theme, positionCSS) {
-      var _config$theme, _config$suggestions, _config$theme2, _config$theme3;
-      if (document.getElementById('sai-trigger')) return;
-      injectStyles(theme, positionCSS);
-      const trigger = document.createElement('button');
-      trigger.id = 'sai-trigger';
-      trigger.title = 'Need help?';
-      trigger.setAttribute('aria-label', 'Open help assistant');
-      trigger.innerHTML = '<span class="sai-pulse" aria-hidden="true"></span>✦';
-      document.body.appendChild(trigger);
-      const panel = document.createElement('div');
-      panel.id = 'sai-panel';
-      panel.setAttribute('role', 'dialog');
-      panel.setAttribute('aria-label', `${_config.assistantName || 'AI Guide'} chat`);
-      panel.innerHTML = `
-      <div id="sai-header">
-        <div id="sai-avatar" aria-hidden="true">✦</div>
-        <div id="sai-header-info">
-          <h4>${escHTML(_config.assistantName || 'AI Guide')}</h4>
-          <p>Ask me anything about ${escHTML(_config.appName)}</p>
-        </div>
-        <button id="sai-close" aria-label="Close help assistant">×</button>
-      </div>
-      <div id="sai-messages" role="log" aria-live="polite"></div>
-      <div id="sai-suggestions" aria-label="Suggested questions"></div>
-      <div id="sai-inputrow">
-        <input id="sai-input" type="text" placeholder="What do you need help with?"
-               autocomplete="off" aria-label="Ask a question"/>
-        <button id="sai-send" aria-label="Send message">➤</button>
+// ─── DOM builder ─────────────────────────────────────────────────────────────
+
+/**
+ * Mounts the trigger button and chat panel into document.body.
+ * Idempotent — safe to call multiple times (exits early if already mounted).
+ *
+ * @param {object} theme   — resolved theme tokens
+ * @param {object} posCSS  — resolved position object from resolvePosition()
+ */
+function buildChat(theme, posCSS) {
+  var _state$config$theme, _state$config$suggest, _state$config$theme2, _state$config$theme3;
+  if (document.getElementById('sai-trigger')) return;
+  loadShepherdCSS();
+  injectStyles(theme, posCSS);
+
+  // ── Trigger button ──
+  const trigger = document.createElement('button');
+  trigger.id = 'sai-trigger';
+  trigger.title = 'Need help?';
+  trigger.setAttribute('aria-label', 'Open help assistant');
+  trigger.innerHTML = '<span class="sai-pulse" aria-hidden="true"></span>✦';
+  document.body.appendChild(trigger);
+
+  // ── Panel ──
+  const panel = document.createElement('div');
+  panel.id = 'sai-panel';
+  panel.setAttribute('role', 'dialog');
+  panel.setAttribute('aria-label', `${config.assistantName || 'AI Guide'} chat`);
+  panel.innerHTML = `
+    <div id="sai-header">
+      <div id="sai-avatar" aria-hidden="true">✦</div>
+      <div id="sai-header-info">
+        <h4>${escHTML(config.assistantName || 'AI Guide')}</h4>
+        <p>Ask me anything about ${escHTML(config.appName)}</p>
       </div>
-    `;
-      document.body.appendChild(panel);
-      if (((_config$theme = _config.theme) === null || _config$theme === void 0 ? void 0 : _config$theme.preset) === 'glass') {
-        document.body.classList.add('sai-glass-preset');
-      }
-      if ((_config$suggestions = _config.suggestions) !== null && _config$suggestions !== void 0 && _config$suggestions.length) {
-        const container = panel.querySelector('#sai-suggestions');
-        _config.suggestions.forEach(s => {
-          const btn = document.createElement('button');
-          btn.className = 'sai-chip';
-          btn.textContent = s;
-          btn.addEventListener('click', () => handleSend(s));
-          container.appendChild(btn);
-        });
-      }
-      trigger.addEventListener('click', togglePanel);
-      panel.querySelector('#sai-close').addEventListener('click', togglePanel);
-      panel.querySelector('#sai-send').addEventListener('click', () => {
-        const v = panel.querySelector('#sai-input').value.trim();
-        if (v) handleSend(v);
-      });
-      panel.querySelector('#sai-input').addEventListener('keydown', e => {
-        if (e.key === 'Enter' && !e.shiftKey) {
-          e.preventDefault();
-          const v = e.target.value.trim();
-          if (v) handleSend(v);
-        }
-      });
-      addMsg('ai', `Hey! 👋 I can guide you through ${_config.appName}. What would you like to do?`);
-
-      // Auto theme switching
-      if (((_config$theme2 = _config.theme) === null || _config$theme2 === void 0 ? void 0 : _config$theme2.mode) === 'auto' || !((_config$theme3 = _config.theme) !== null && _config$theme3 !== void 0 && _config$theme3.mode)) {
-        _mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-        _mediaQuery.addEventListener('change', () => {
-          var _document$getElementB3;
-          const newTheme = resolveTheme(_config.theme);
-          applyTheme(newTheme);
-          (_document$getElementB3 = document.getElementById('sai-styles')) === null || _document$getElementB3 === void 0 || _document$getElementB3.remove();
-          injectStyles(newTheme, positionCSS);
-        });
+      <button id="sai-close" aria-label="Close help assistant">×</button>
+    </div>
+    <div id="sai-messages" role="log" aria-live="polite"></div>
+    <div id="sai-suggestions" aria-label="Suggested questions"></div>
+    <div id="sai-inputrow">
+      <input id="sai-input" type="text" placeholder="What do you need help with?"
+             autocomplete="off" aria-label="Ask a question"/>
+      <button id="sai-send" aria-label="Send message">➤</button>
+    </div>
+  `;
+  document.body.appendChild(panel);
+  if (((_state$config$theme = config.theme) === null || _state$config$theme === void 0 ? void 0 : _state$config$theme.preset) === 'glass') {
+    document.body.classList.add('sai-glass-preset');
+  }
+
+  // ── Suggestion chips ──
+  if ((_state$config$suggest = config.suggestions) !== null && _state$config$suggest !== void 0 && _state$config$suggest.length) {
+    const container = panel.querySelector('#sai-suggestions');
+    config.suggestions.forEach(s => {
+      const btn = document.createElement('button');
+      btn.className = 'sai-chip';
+      btn.textContent = s;
+      btn.addEventListener('click', () => handleSend(s));
+      container.appendChild(btn);
+    });
+  }
+
+  // ── Event listeners ──
+  trigger.addEventListener('click', togglePanel);
+  panel.querySelector('#sai-close').addEventListener('click', togglePanel);
+  panel.querySelector('#sai-send').addEventListener('click', () => {
+    const v = panel.querySelector('#sai-input').value.trim();
+    if (v) handleSend(v);
+  });
+  panel.querySelector('#sai-input').addEventListener('keydown', e => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      const v = e.target.value.trim();
+      if (v) handleSend(v);
+    }
+  });
+  addMsg('ai', `Hey! 👋 I can guide you through ${config.appName}. What would you like to do?`);
+
+  // ── Auto theme switching ──
+  if (((_state$config$theme2 = config.theme) === null || _state$config$theme2 === void 0 ? void 0 : _state$config$theme2.mode) === 'auto' || !((_state$config$theme3 = config.theme) !== null && _state$config$theme3 !== void 0 && _state$config$theme3.mode)) {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    mq.addEventListener('change', () => {
+      var _document$getElementB0;
+      const newTheme = resolveTheme(config.theme);
+      applyTheme(newTheme);
+      (_document$getElementB0 = document.getElementById('sai-styles')) === null || _document$getElementB0 === void 0 || _document$getElementB0.remove();
+      injectStyles(newTheme, posCSS);
+    });
+  }
+}
+
+// Expands a feature's `flow[]` array into individual Shepherd-ready step objects.
+// A feature with no `flow` is returned as-is (wrapped in an array).
+
+/**
+ * @param {object} aiStep   — the step object returned by the AI
+ * @param {object} feature  — the matching feature config (may have a .flow array)
+ * @returns {Array<object>} one or more expanded step objects
+ */
+function expandFlowSteps(aiStep, feature) {
+  var _feature$flow;
+  if (!((_feature$flow = feature.flow) !== null && _feature$flow !== void 0 && _feature$flow.length)) return [aiStep];
+  return feature.flow.map((entry, i) => ({
+    id: `${aiStep.id}-flow-${i}`,
+    title: i === 0 ? aiStep.title : `${aiStep.title} (${i + 1}/${feature.flow.length})`,
+    text: i === 0 ? aiStep.text : `Step ${i + 1} of ${feature.flow.length}: continue with the action highlighted below.`,
+    position: aiStep.position || 'bottom',
+    selector: entry.selector || null,
+    waitFor: entry.waitFor || null,
+    advanceOn: entry.advanceOn || null,
+    _parentId: aiStep.id
+  }));
+}
+
+// Loads Shepherd.js, builds + runs tours, wires up advanceOn listeners,
+// progress indicators, pause/resume, and step-level error display.
+
+const SHEPHERD_JS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/js/shepherd.min.js';
+
+// ─── Shepherd loader ──────────────────────────────────────────────────────────
+
+function loadScript(src) {
+  return new Promise((res, rej) => {
+    if (document.querySelector(`script[src="${src}"]`)) return res();
+    const s = document.createElement('script');
+    s.src = src;
+    s.onload = res;
+    s.onerror = rej;
+    document.head.appendChild(s);
+  });
+}
+async function ensureShepherd() {
+  if (typeof Shepherd !== 'undefined') return;
+  await loadScript(SHEPHERD_JS);
+}
+
+// ─── Feature-map merge ────────────────────────────────────────────────────────
+
+/**
+ * Merges an AI step with its matching entry from the live feature map.
+ * The feature map always wins for `selector` so mismatches are impossible.
+ *
+ * @param {object} step
+ * @returns {object}
+ */
+function mergeWithFeature(step) {
+  var _state$config;
+  if (!((_state$config = config) !== null && _state$config !== void 0 && _state$config.features)) return step;
+  const feature = config.features.find(f => f.id === (step._parentId || step.id));
+  if (!feature) return step;
+  return {
+    waitFor: feature.waitFor || null,
+    advanceOn: feature.advanceOn || null,
+    validate: feature.validate || null,
+    screen: feature.screen || null,
+    flow: feature.flow || null,
+    route: feature.route || null,
+    ...step,
+    selector: feature.selector || step.selector // feature map always wins
+  };
+}
+
+// ─── Step orchestration ───────────────────────────────────────────────────────
+
+/**
+ * Builds a `beforeShowPromise` for a Shepherd step that handles:
+ *   1. Cross-page navigation (route prop) with automatic waiting
+ *   2. Legacy screen navigation (screen.navigate)
+ *   3. Element waiting (waitFor prop)
+ *
+ * @param {object} step
+ * @param {number} waitTimeout
+ * @returns {() => Promise<void>}
+ */
+function makeBeforeShowPromise(step, waitTimeout) {
+  return () => (async () => {
+    const freshMerged = mergeWithFeature(step);
+    const targetRoute = freshMerged.route;
+    if (targetRoute && getCurrentRoute() !== targetRoute) {
+      await navigateToRoute(targetRoute, freshMerged.name || step.title);
+      const postNavMerge = mergeWithFeature(step);
+      if (postNavMerge.selector) {
+        try {
+          var _step$_shepherdRef, _step$_shepherdRef$up;
+          (_step$_shepherdRef = step._shepherdRef) === null || _step$_shepherdRef === void 0 || (_step$_shepherdRef$up = _step$_shepherdRef.updateStepOptions) === null || _step$_shepherdRef$up === void 0 || _step$_shepherdRef$up.call(_step$_shepherdRef, {
+            attachTo: {
+              element: postNavMerge.selector,
+              on: step.position || 'bottom'
+            }
+          });
+        } catch (_) {/* non-fatal */}
+        await waitForElement(postNavMerge.selector, waitTimeout);
+        return;
       }
     }
-    function escHTML(str) {
-      return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    if (freshMerged.screen) {
+      await ensureOnCorrectScreen(freshMerged);
     }
-    function togglePanel() {
-      var _document$getElementB4, _document$getElementB5, _document$getElementB6;
-      _isOpen = !_isOpen;
-      (_document$getElementB4 = document.getElementById('sai-panel')) === null || _document$getElementB4 === void 0 || _document$getElementB4.classList.toggle('sai-open', _isOpen);
-      (_document$getElementB5 = document.getElementById('sai-trigger')) === null || _document$getElementB5 === void 0 || _document$getElementB5.classList.toggle('sai-paused', !!_pausedSteps);
-      if (_isOpen) (_document$getElementB6 = document.getElementById('sai-input')) === null || _document$getElementB6 === void 0 || _document$getElementB6.focus();
+    if (freshMerged.waitFor) {
+      await waitForElement(freshMerged.waitFor, waitTimeout);
     }
-    function addMsg(type, text) {
-      const msgs = document.getElementById('sai-messages');
-      if (!msgs) return;
-      const div = document.createElement('div');
-      div.className = `sai-msg sai-${type}`;
-      div.textContent = text;
-      msgs.appendChild(div);
-      msgs.scrollTop = msgs.scrollHeight;
+  })();
+}
+
+// ─── Event wiring ─────────────────────────────────────────────────────────────
+
+function wireAdvanceOn(shepherdStep, advanceOn, tour) {
+  if (!(advanceOn !== null && advanceOn !== void 0 && advanceOn.selector) || !(advanceOn !== null && advanceOn !== void 0 && advanceOn.event)) return;
+  function handler(e) {
+    if (e.target.matches(advanceOn.selector) || e.target.closest(advanceOn.selector)) {
+      setTimeout(() => {
+        if (tour && !tour.isActive()) return;
+        tour.next();
+      }, advanceOn.delay || 300);
     }
-    function showTyping() {
-      const msgs = document.getElementById('sai-messages');
-      const el = document.createElement('div');
-      el.className = 'sai-typing';
-      el.id = 'sai-typing';
-      el.innerHTML = '<span></span><span></span><span></span>';
-      msgs.appendChild(el);
-      msgs.scrollTop = msgs.scrollHeight;
+  }
+  document.addEventListener(advanceOn.event, handler, true);
+  pushCleanup(() => document.removeEventListener(advanceOn.event, handler, true));
+  shepherdStep.on('show', () => {
+    var _shepherdStep$getElem;
+    const nextBtn = (_shepherdStep$getElem = shepherdStep.getElement()) === null || _shepherdStep$getElem === void 0 ? void 0 : _shepherdStep$getElem.querySelector('.shepherd-footer .shepherd-button:not(.shepherd-button-secondary)');
+    if (nextBtn && !shepherdStep._isLast) {
+      nextBtn.style.opacity = '0.4';
+      nextBtn.title = 'Complete the action above to continue';
     }
-    function hideTyping() {
-      var _document$getElementB7;
-      (_document$getElementB7 = document.getElementById('sai-typing')) === null || _document$getElementB7 === void 0 || _document$getElementB7.remove();
+  });
+}
+function addProgressIndicator(shepherdStep, index, total) {
+  shepherdStep.on('show', () => {
+    var _shepherdStep$getElem2;
+    const header = (_shepherdStep$getElem2 = shepherdStep.getElement()) === null || _shepherdStep$getElem2 === void 0 ? void 0 : _shepherdStep$getElem2.querySelector('.shepherd-header');
+    if (!header || header.querySelector('.sai-progress')) return;
+    const pct = Math.round((index + 1) / total * 100);
+    const wrapper = document.createElement('div');
+    wrapper.className = 'sai-progress';
+    wrapper.innerHTML = `
+      <div class="sai-progress-bar">
+        <div class="sai-progress-fill" style="width:${pct}%"></div>
+      </div>
+      <span class="sai-progress-label">${index + 1} / ${total}</span>
+    `;
+    header.appendChild(wrapper);
+  });
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Starts a Shepherd tour from the given steps array.
+ *
+ * @param {Array}  steps
+ * @param {object} [options]
+ * @param {boolean} [options.showProgress=true]
+ * @param {number}  [options.waitTimeout=8000]
+ */
+async function runTour(steps, options = {}) {
+  var _state$config2;
+  await ensureShepherd();
+  if (tour) {
+    tour.cancel();
+  }
+  runAndClearCleanups();
+  setTour(null);
+  if (!(steps !== null && steps !== void 0 && steps.length)) return;
+  const {
+    showProgress = true,
+    waitTimeout = 8000
+  } = options;
+  const mergedSteps = steps.map(mergeWithFeature);
+
+  // Legacy: navigate to the correct screen for the first step
+  const firstFeature = (_state$config2 = config) === null || _state$config2 === void 0 || (_state$config2 = _state$config2.features) === null || _state$config2 === void 0 ? void 0 : _state$config2.find(f => {
+    var _mergedSteps$;
+    return f.id === ((_mergedSteps$ = mergedSteps[0]) === null || _mergedSteps$ === void 0 ? void 0 : _mergedSteps$.id);
+  });
+  if (firstFeature !== null && firstFeature !== void 0 && firstFeature.screen) await ensureOnCorrectScreen(firstFeature);
+
+  // Expand flow[] into individual Shepherd steps
+  const expandedSteps = mergedSteps.flatMap(step => {
+    var _state$config3;
+    const feature = (_state$config3 = config) === null || _state$config3 === void 0 || (_state$config3 = _state$config3.features) === null || _state$config3 === void 0 ? void 0 : _state$config3.find(f => f.id === step.id);
+    return feature ? expandFlowSteps(step, feature) : [step];
+  });
+  const ShepherdClass = typeof Shepherd !== 'undefined' ? Shepherd : window.Shepherd;
+  const tour$1 = new ShepherdClass.Tour({
+    useModalOverlay: true,
+    defaultStepOptions: {
+      scrollTo: {
+        behavior: 'smooth',
+        block: 'center'
+      },
+      cancelIcon: {
+        enabled: true
+      },
+      classes: 'sai-shepherd-step'
     }
-    function setDisabled(d) {
-      ['sai-input', 'sai-send'].forEach(id => {
-        const el = document.getElementById(id);
-        if (el) el.disabled = d;
+  });
+  setTour(tour$1);
+  expandedSteps.forEach((step, i) => {
+    var _step$advanceOn, _step$advanceOn2;
+    const isLast = i === expandedSteps.length - 1;
+    const hasAuto = !!((_step$advanceOn = step.advanceOn) !== null && _step$advanceOn !== void 0 && _step$advanceOn.selector && (_step$advanceOn2 = step.advanceOn) !== null && _step$advanceOn2 !== void 0 && _step$advanceOn2.event);
+    const buttons = [];
+    if (i > 0) {
+      buttons.push({
+        text: '← Back',
+        action: tour$1.back,
+        secondary: true
       });
     }
-    async function handleSend(text) {
-      var _document$getElementB8, _document$getElementB9;
-      const input = document.getElementById('sai-input');
-      if (input) input.value = '';
-      document.getElementById('sai-suggestions').style.display = 'none';
-
-      // New message clears any existing pause state
-      _pausedSteps = null;
-      _pausedIndex = 0;
-      (_document$getElementB8 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB8 === void 0 || _document$getElementB8.remove();
-      (_document$getElementB9 = document.getElementById('sai-trigger')) === null || _document$getElementB9 === void 0 || _document$getElementB9.classList.remove('sai-paused');
-      addMsg('user', text);
-      setDisabled(true);
-      showTyping();
-      try {
-        var _result$steps;
-        const result = await callAI(text);
-        hideTyping();
-        addMsg('ai', result.message);
-        if ((_result$steps = result.steps) !== null && _result$steps !== void 0 && _result$steps.length) {
-          setTimeout(() => {
-            togglePanel();
-            runTour(result.steps);
-          }, 600);
-        }
-      } catch (err) {
-        hideTyping();
-        addMsg('error', err.message || 'Something went wrong. Please try again.');
-        console.error('[Eventop]', err);
-      } finally {
-        var _document$getElementB0;
-        setDisabled(false);
-        (_document$getElementB0 = document.getElementById('sai-input')) === null || _document$getElementB0 === void 0 || _document$getElementB0.focus();
+    buttons.push({
+      text: isLast ? 'Done ✓' : 'Next →',
+      action: isLast ? tour$1.complete : tour$1.next
+    });
+    buttons.push({
+      text: '⏸ Pause',
+      secondary: true,
+      action: function () {
+        tour$1.cancel();
       }
+    });
+    const shepherdStep = tour$1.addStep({
+      id: step.id || `sai-step-${i}`,
+      title: step.title,
+      text: step.text,
+      attachTo: step.selector ? {
+        element: step.selector,
+        on: step.position || 'bottom'
+      } : undefined,
+      beforeShowPromise: makeBeforeShowPromise(step, waitTimeout),
+      buttons
+    });
+    step._shepherdRef = shepherdStep;
+    shepherdStep._isLast = isLast;
+    if (hasAuto) wireAdvanceOn(shepherdStep, step.advanceOn, tour$1);
+    if (showProgress && expandedSteps.length > 1) {
+      addProgressIndicator(shepherdStep, i, expandedSteps.length);
     }
+  });
+  tour$1.on('complete', () => {
+    runAndClearCleanups();
+    setPausedSteps(null);
+    setPausedIndex(0);
+    setTour(null);
+  });
 
-    // ═══════════════════════════════════════════════════════════════════════════
-    //  PUBLIC API
-    // ═══════════════════════════════════════════════════════════════════════════
-
-    const Eventop = {
-      providers,
-      init(opts = {}) {
-        var _opts$config, _opts$config2;
-        if (!opts.provider) throw new Error('[Eventop] provider is required');
-        if (!((_opts$config = opts.config) !== null && _opts$config !== void 0 && _opts$config.appName)) throw new Error('[Eventop] config.appName is required');
-        if (!((_opts$config2 = opts.config) !== null && _opts$config2 !== void 0 && _opts$config2.features)) throw new Error('[Eventop] config.features is required');
-        _provider = opts.provider;
-        _config = opts.config;
-        const theme = resolveTheme(_config.theme);
-        const posCSS = resolvePosition(_config.position);
-        if (document.readyState === 'loading') {
-          document.addEventListener('DOMContentLoaded', () => buildChat(theme, posCSS));
-        } else {
-          buildChat(theme, posCSS);
-        }
-        ensureShepherd();
-      },
-      open() {
-        if (!_isOpen) togglePanel();
-      },
-      close() {
-        if (_isOpen) togglePanel();
-      },
-      runTour,
-      cancelTour() {
-        var _document$getElementB1, _document$getElementB10;
-        _pausedSteps = null;
-        _pausedIndex = 0;
-        if (_tour) {
-          _tour.cancel();
-        }
-        _cleanups.forEach(fn => fn());
-        _cleanups = [];
-        _tour = null;
-        (_document$getElementB1 = document.getElementById('sai-trigger')) === null || _document$getElementB1 === void 0 || _document$getElementB1.classList.remove('sai-paused');
-        (_document$getElementB10 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB10 === void 0 || _document$getElementB10.remove();
-        document.body.classList.remove('sai-glass-preset');
-      },
-      resumeTour() {
-        var _document$getElementB11, _document$getElementB12;
-        if (!_pausedSteps) return;
-        const steps = _pausedSteps;
-        const idx = _pausedIndex;
-        _pausedSteps = null;
-        _pausedIndex = 0;
-        (_document$getElementB11 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB11 === void 0 || _document$getElementB11.remove();
-        (_document$getElementB12 = document.getElementById('sai-trigger')) === null || _document$getElementB12 === void 0 || _document$getElementB12.classList.remove('sai-paused');
-        if (_isOpen) togglePanel();
-        runTour(steps.slice(idx));
-      },
-      isPaused() {
-        return !!_pausedSteps;
-      },
-      isActive() {
-        var _tour4;
-        return !!((_tour4 = _tour) !== null && _tour4 !== void 0 && _tour4.isActive());
-      },
-      stepComplete,
-      stepFail,
-      /** @internal — used by the React package to sync the live feature registry */
-      _updateConfig(partial) {
-        if (!_config) return;
-        _config = {
-          ..._config,
-          ...partial
-        };
-      }
-    };
-    return Eventop;
+  // Cancel → pause (not hard destroy)
+  tour$1.on('cancel', () => {
+    const currentStepEl = tour$1.getCurrentStep();
+    const currentIdx = currentStepEl ? expandedSteps.findIndex(s => s.id === currentStepEl.id) : 0;
+    runAndClearCleanups();
+    setPausedSteps(expandedSteps);
+    setPausedIndex(Math.max(0, currentIdx));
+    setTour(null);
+    showResumeButton(pausedIndex);
   });
-})(core$1);
-var coreExports = core$1.exports;
+  tour$1.start();
+}
 
-var core = /*#__PURE__*/_mergeNamespaces({
-	__proto__: null
-}, [coreExports]);
+/**
+ * Advances the active tour to the next step programmatically.
+ * Useful when your own UI signals step completion.
+ */
+function stepComplete() {
+  var _state$tour;
+  if ((_state$tour = tour) !== null && _state$tour !== void 0 && _state$tour.isActive()) tour.next();
+}
 
-exports.core = core;
+/**
+ * Injects an error message into the current Shepherd step's text area.
+ *
+ * @param {string} [message]
+ */
+function stepFail(message) {
+  var _state$tour2, _el$querySelector;
+  if (!((_state$tour2 = tour) !== null && _state$tour2 !== void 0 && _state$tour2.isActive())) return;
+  const current = tour.getCurrentStep();
+  if (!current) return;
+  const el = current.getElement();
+  el === null || el === void 0 || (_el$querySelector = el.querySelector('.sai-step-error')) === null || _el$querySelector === void 0 || _el$querySelector.remove();
+  if (message) {
+    var _el$querySelector2;
+    const err = document.createElement('div');
+    err.className = 'sai-step-error';
+    err.textContent = '⚠ ' + message;
+    el === null || el === void 0 || (_el$querySelector2 = el.querySelector('.shepherd-text')) === null || _el$querySelector2 === void 0 || _el$querySelector2.appendChild(err);
+  }
+}
+
+// Break the navigation.js ↔ chat.js circular dependency:
+// chat.js needs runTour but can't import tour.js (tour imports chat).
+// We inject runTour into chat after both modules are loaded.
+setRunTour(runTour);
+
+/**
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║   @eventop/sdk  v1.3.0                                       ║
+ * ║   AI-powered guided tours — themeable, provider-agnostic     ║
+ * ║                                                              ║
+ * ║   Provider: always proxy through your own server.            ║
+ * ║   Never expose API keys in client-side code.                 ║
+ * ╚══════════════════════════════════════════════════════════════╝
+ *
+ * Module map
+ * ──────────────────────────────────────────────────────────────
+ *  state.js       Shared mutable state — single source of truth
+ *  theme.js       Design tokens + CSS variable builder
+ *  positioning.js Corner/offset → CSS position values
+ *  providers.js   AI provider factory helpers
+ *  prompt.js      System prompt builder
+ *  ai.js          Provider request/response + conversation history
+ *  navigation.js  Route navigation, element waiting, announcements
+ *  flow.js        Expands feature flow[] into step arrays
+ *  tour.js        Shepherd.js runner, pause/resume, step helpers
+ *  styles.js      <style> injection (chat panel + Shepherd overrides)
+ *  chat.js        Chat panel DOM, messaging, send handler
+ *  core.js        ← YOU ARE HERE — public API + UMD wrapper
+ */
+
+(function (global, factory) {
+  const Eventop = factory();
+  if (typeof module === 'object' && module.exports) {
+    module.exports = Eventop;
+  }
+  if (typeof window !== 'undefined') {
+    window.Eventop = Eventop;
+  } else if (typeof global !== 'undefined') {
+    global.Eventop = Eventop;
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : undefined, function
+  // Dependencies are injected by the bundler (Rollup / esbuild / Vite).
+  // When building for the browser, run: rollup -i core.js -o dist/eventop.umd.js -f umd -n Eventop
+  //
+  // The factory receives nothing — all imports are resolved at bundle time
+  // because static `import` statements are hoisted above the UMD wrapper by
+  // modern bundlers. This file must be processed by a bundler before use in
+  // a plain <script> tag.
+() {
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  PUBLIC API
+  // ═══════════════════════════════════════════════════════════════════════════
+  const Eventop = {
+    providers,
+    /**
+     * Initialise the SDK. Must be called once before anything else.
+     *
+     * @param {object} opts
+     * @param {Function}  opts.provider        — AI provider function
+     * @param {object}    opts.config           — app config
+     * @param {string}    opts.config.appName
+     * @param {Array}     opts.config.features
+     * @param {Function}  [opts.config.router]  — framework navigate fn
+     * @param {object}    [opts.config.theme]
+     * @param {object}    [opts.config.position]
+     * @param {string[]}  [opts.config.suggestions]
+     * @param {string}    [opts.config.assistantName]
+     */
+    init(opts = {}) {
+      var _opts$config, _opts$config2;
+      if (!opts.provider) throw new Error('[Eventop] provider is required');
+      if (!((_opts$config = opts.config) !== null && _opts$config !== void 0 && _opts$config.appName)) throw new Error('[Eventop] config.appName is required');
+      if (!((_opts$config2 = opts.config) !== null && _opts$config2 !== void 0 && _opts$config2.features)) throw new Error('[Eventop] config.features is required');
+      setProvider(opts.provider);
+      setConfig(opts.config);
+      setRouter(opts.config.router || null);
+      const theme = resolveTheme(opts.config.theme);
+      const posCSS = resolvePosition(opts.config.position);
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => buildChat(theme, posCSS));
+      } else {
+        buildChat(theme, posCSS);
+      }
+      ensureShepherd();
+    },
+    /** Programmatically open the chat panel. */
+    open() {
+      if (!isOpen) togglePanel();
+    },
+    /** Programmatically close the chat panel. */
+    close() {
+      if (isOpen) togglePanel();
+    },
+    /** Start a tour directly with a pre-built step array. */
+    runTour,
+    /** Cancel any active or paused tour and clean up completely. */
+    cancelTour() {
+      var _document$getElementB, _document$getElementB2;
+      setPausedSteps(null);
+      setPausedIndex(0);
+      if (tour) {
+        tour.cancel();
+      }
+      runAndClearCleanups();
+      setTour(null);
+      (_document$getElementB = document.getElementById('sai-trigger')) === null || _document$getElementB === void 0 || _document$getElementB.classList.remove('sai-paused');
+      (_document$getElementB2 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB2 === void 0 || _document$getElementB2.remove();
+      document.body.classList.remove('sai-glass-preset');
+    },
+    /** Resume a paused tour from where it was cancelled. */
+    resumeTour() {
+      var _document$getElementB3, _document$getElementB4;
+      if (!pausedSteps) return;
+      const steps = pausedSteps;
+      const idx = pausedIndex;
+      setPausedSteps(null);
+      setPausedIndex(0);
+      (_document$getElementB3 = document.getElementById('sai-resume-prompt')) === null || _document$getElementB3 === void 0 || _document$getElementB3.remove();
+      (_document$getElementB4 = document.getElementById('sai-trigger')) === null || _document$getElementB4 === void 0 || _document$getElementB4.classList.remove('sai-paused');
+      if (isOpen) togglePanel();
+      runTour(steps.slice(idx));
+    },
+    /** @returns {boolean} true if a tour is currently paused */
+    isPaused() {
+      return !!pausedSteps;
+    },
+    /** @returns {boolean} true if a Shepherd tour is actively running */
+    isActive() {
+      var _state$tour;
+      return !!((_state$tour = tour) !== null && _state$tour !== void 0 && _state$tour.isActive());
+    },
+    /**
+     * Advance the active tour step programmatically.
+     * Call this from your own UI when you want to signal step completion.
+     */
+    stepComplete,
+    /**
+     * Inject an error message into the current tour step.
+     * @param {string} message
+     */
+    stepFail,
+    /**
+     * @internal — used by the React package to sync the live feature registry.
+     * @param {object} partial — partial config to merge
+     */
+    _updateConfig(partial) {
+      if (!config) return;
+      setConfig({
+        ...config,
+        ...partial
+      });
+      if (partial.router !== undefined) setRouter(partial.router);
+    }
+  };
+  return Eventop;
+});