@eventop/sdk 1.1.4 → 1.1.5

package/dist/react/index.js

@@ -1,223 +1,1047 @@
-import { createContext, useContext, useRef, useEffect, Children, cloneElement, useState, useCallback } from 'react';
+import { createContext, useContext, useRef, useCallback, useEffect, Children, cloneElement, useState } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
-/**
- * Root context — holds the global feature registry.
- * Set by EventopAIProvider at the root of the app.
- */
-const EventopRegistryContext = /*#__PURE__*/createContext(null);
+var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
+
+var core = {exports: {}};
 
 /**
- * Feature scope context — set by EventopTarget.
- * Tells any EventopStep inside the tree which feature it belongs to,
- * so you can nest EventopStep inside a EventopTarget without repeating
- * the feature id. Also supports explicit feature="id" on EventopStep
- * for steps that live outside their parent EventopTarget in the tree.
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║   @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.                 ║
+ * ╚══════════════════════════════════════════════════════════════╝
  */
-const EventopFeatureScopeContext = /*#__PURE__*/createContext(null);
-function useRegistry() {
-  const ctx = useContext(EventopRegistryContext);
-  if (!ctx) throw new Error('[EventopAI] Must be used inside <EventopAIProvider>.');
-  return ctx;
-}
-function useFeatureScope() {
-  return useContext(EventopFeatureScopeContext); // null is fine — steps can declare feature explicitly
-}
+(function (module) {
+  (function (global, factory) {
+    if (module.exports) {
+      module.exports = factory();
+    } else {
+      global.Eventop = factory();
+    }
+  })(typeof globalThis !== 'undefined' ? globalThis : commonjsGlobal, function () {
 
-function EventopTarget({
-  children,
-  id,
-  name,
-  description,
-  navigate,
-  navigateWaitFor,
-  advanceOn,
-  waitFor,
-  ...rest
-}) {
-  const registry = useRegistry();
-  const ref = useRef(null);
-  const dataAttr = `data-evtp-${id}`;
-  const selector = `[${dataAttr}]`;
-  useEffect(() => {
-    if (!id || !name) {
-      console.warn('[Eventop] <EventopTarget> requires id and name props.');
-      return;
+    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'
+      }
+    };
+    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
+      };
     }
-    registry.registerFeature({
-      id,
-      name,
-      description,
-      selector,
-      navigate,
-      navigateWaitFor,
-      waitFor,
-      advanceOn: advanceOn ? {
-        selector,
-        ...advanceOn
-      } : null
-    });
-    return () => registry.unregisterFeature(id);
-  }, [id, name, description]);
-  const child = Children.only(children);
-  let wrapped;
-  try {
-    wrapped = /*#__PURE__*/cloneElement(child, {
-      [dataAttr]: '',
-      ref: node => {
-        ref.current = node;
-        const originalRef = child.ref;
-        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+    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);
       }
-    });
-  } catch {
-    wrapped = /*#__PURE__*/jsx("span", {
-      [dataAttr]: '',
-      ref: ref,
-      style: {
-        display: 'contents'
-      },
-      children: child
-    });
-  }
-  return /*#__PURE__*/jsx(EventopFeatureScopeContext.Provider, {
-    value: id,
-    children: wrapped
-  });
-}
+      if (trigger) {
+        trigger.style.cssText += buildCSSVars(t);
+      }
+    }
 
-function EventopStep({
-  children,
-  feature,
-  index,
-  parentStep,
-  waitFor,
-  advanceOn
-}) {
-  const registry = useRegistry();
-  const featureScope = useFeatureScope();
-  const featureId = feature || featureScope;
-  const ref = useRef(null);
-  if (!featureId) {
-    console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
-  }
-  if (index == null) {
-    console.warn('[Eventop] <EventopStep> requires an index prop.');
-  }
-  const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
-  const selector = `[${dataAttr}]`;
-  useEffect(() => {
-    if (!featureId || index == null) return;
-    registry.registerStep(featureId, index, parentStep ?? null, {
-      selector,
-      waitFor: waitFor || null,
-      advanceOn: advanceOn ? {
-        selector,
-        ...advanceOn
-      } : null
-    });
-    return () => registry.unregisterStep(featureId, index, parentStep ?? null);
-  }, [featureId, index, parentStep]);
-  const child = Children.only(children);
-  let wrapped;
-  try {
-    wrapped = /*#__PURE__*/cloneElement(child, {
-      [dataAttr]: '',
-      ref: node => {
-        ref.current = node;
-        const originalRef = child.ref;
-        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  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'
+        }
+      };
+    }
+    function positionToCSS(obj) {
+      return Object.entries(obj).map(([k, v]) => `${k}:${v}`).join(';');
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  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;
       }
-    });
-  } catch {
-    wrapped = /*#__PURE__*/jsx("span", {
-      [dataAttr]: '',
-      ref: ref,
-      style: {
-        display: 'contents'
-      },
-      children: child
-    });
-  }
-  return wrapped;
-}
+    };
 
-// ═══════════════════════════════════════════════════════════════════════════
-//  useEventopAI
-//
-//  Access the SDK programmatic API from inside any component.
-//  Use for stepComplete(), stepFail(), open(), close() etc.
-//
-//  @example
-//  function CheckoutForm() {
-//    const { stepComplete, stepFail } = useEventopAI();
-//
-//    async function handleNext() {
-//      const ok = await validateEmail(email);
-//      if (ok) stepComplete();
-//      else stepFail('Please enter a valid email address.');
-//    }
-//  }
-// ═══════════════════════════════════════════════════════════════════════════
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  SYSTEM PROMPT
+    // ═══════════════════════════════════════════════════════════════════════════
 
-function useEventopAI() {
-  const sdk = () => window.Eventop;
-  return {
-    open: () => sdk()?.open(),
-    close: () => sdk()?.close(),
-    cancelTour: () => sdk()?.cancelTour(),
-    resumeTour: () => sdk()?.resumeTour(),
-    isActive: () => sdk()?.isActive() ?? false,
-    isPaused: () => sdk()?.isPaused() ?? false,
-    stepComplete: () => sdk()?.stepComplete(),
-    stepFail: msg => sdk()?.stepFail(msg),
-    runTour: steps => sdk()?.runTour(steps)
-  };
+    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}".
+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.` : ''}
+
+FEATURE MAP (only reference IDs from this list):
+${JSON.stringify(featureSummary, null, 2)}
+
+RESPOND ONLY with this exact JSON — no markdown, no extra text:
+{
+  "message": "Friendly 1-2 sentence intro about what you are helping with.",
+  "steps": [
+    {
+      "id": "feature-id-from-map",
+      "title": "3-5 word title",
+      "text": "Exact instruction. Max 2 sentences.",
+      "selector": "#selector-from-feature-map",
+      "position": "bottom"
+    }
+  ]
 }
 
-// ═══════════════════════════════════════════════════════════════════════════
-//  useEventopTour
-//
-//  Reactively tracks tour state so you can render your own UI.
-//  Polls at 300ms — lightweight enough for a status indicator.
-//
-//  @example
-//  function TourBar() {
-//    const { isActive, isPaused, resume, cancel } = useEventopTour();
-//    if (!isActive && !isPaused) return null;
-//    return (
-//      <div>
-//        {isPaused && <button onClick={resume}>Resume tour</button>}
-//        <button onClick={cancel}>End</button>
-//      </div>
-//    );
-//  }
-// ═══════════════════════════════════════════════════════════════════════════
+RULES:
+1. The step "id" MUST match a feature id from the feature map.
+2. Only use selectors and IDs from the feature map. Never invent them.
+3. No matching feature → steps: [], explain kindly in message.
+4. position values: top | bottom | left | right | auto only.
+5. Order steps logically. For multi-step flows, order as the user encounters them.
+6. For forms: ALWAYS include a step for the form section or first input BEFORE the
+   continue/submit button. The button step must always be LAST in its section.
+7. If a feature has a flow, include one step per flow entry using the same feature id —
+   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;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  SCREEN NAVIGATION
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    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);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  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
+      }));
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  SHEPHERD RUNNER
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    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));
+      });
+      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);
+
+      // 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;
+      });
+
+      // 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);
+      }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  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;  }
+      }
+
+      /* ── 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; }
+
+      /* ── 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); }
+      }
+
+      /* ── 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;
+      }
+    `;
+      document.head.appendChild(style);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  CHAT UI
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    function buildChat(theme, positionCSS) {
+      var _config$suggestions, _config$theme, _config$theme2;
+      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>
+      </div>
+    `;
+      document.body.appendChild(panel);
+      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$theme = _config.theme) === null || _config$theme === void 0 ? void 0 : _config$theme.mode) === 'auto' || !((_config$theme2 = _config.theme) !== null && _config$theme2 !== void 0 && _config$theme2.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);
+        });
+      }
+    }
+    function escHTML(str) {
+      return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    }
+    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();
+    }
+    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$getElementB7;
+      (_document$getElementB7 = document.getElementById('sai-typing')) === null || _document$getElementB7 === void 0 || _document$getElementB7.remove();
+    }
+    function setDisabled(d) {
+      ['sai-input', 'sai-send'].forEach(id => {
+        const el = document.getElementById(id);
+        if (el) el.disabled = d;
+      });
+    }
+    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();
+      }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    //  PUBLIC API
+    // ═══════════════════════════════════════════════════════════════════════════
 
-function useEventopTour() {
-  const [state, setState] = useState({
-    isActive: false,
-    isPaused: false
+    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();
+      },
+      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;
   });
-  useEffect(() => {
-    const id = setInterval(() => {
-      const sdk = window.Eventop;
-      if (!sdk) return;
-      const next = {
-        isActive: sdk.isActive(),
-        isPaused: sdk.isPaused()
-      };
-      setState(prev => prev.isActive !== next.isActive || prev.isPaused !== next.isPaused ? next : prev);
-    }, 300);
-    return () => clearInterval(id);
-  }, []);
-  return {
-    ...state,
-    resume: useCallback(() => window.Eventop?.resumeTour(), []),
-    cancel: useCallback(() => window.Eventop?.cancelTour(), []),
-    open: useCallback(() => window.Eventop?.open(), []),
-    close: useCallback(() => window.Eventop?.close(), [])
-  };
+})(core);
+
+/**
+ * Root context — holds the global feature registry.
+ * Set by EventopAIProvider at the root of the app.
+ */
+const EventopRegistryContext = /*#__PURE__*/createContext(null);
+
+/**
+ * Feature scope context — set by EventopTarget.
+ * Tells any EventopStep inside the tree which feature it belongs to,
+ * so you can nest EventopStep inside a EventopTarget without repeating
+ * the feature id. Also supports explicit feature="id" on EventopStep
+ * for steps that live outside their parent EventopTarget in the tree.
+ */
+const EventopFeatureScopeContext = /*#__PURE__*/createContext(null);
+function useRegistry() {
+  const ctx = useContext(EventopRegistryContext);
+  if (!ctx) throw new Error('[EventopAI] Must be used inside <EventopAIProvider>.');
+  return ctx;
+}
+function useFeatureScope() {
+  return useContext(EventopFeatureScopeContext); // null is fine — steps can declare feature explicitly
 }
 
 /**
@@ -396,8 +1220,9 @@ function EventopProvider({
   const registry = useRef(createFeatureRegistry()).current;
   const sdkReady = useRef(false);
   const syncToSDK = useCallback(() => {
+    var _window$Eventop$_upda, _window$Eventop;
     if (!sdkReady.current || !window.Eventop) return;
-    window.Eventop._updateConfig?.({
+    (_window$Eventop$_upda = (_window$Eventop = window.Eventop)._updateConfig) === null || _window$Eventop$_upda === void 0 || _window$Eventop$_upda.call(_window$Eventop, {
       features: registry.snapshot()
     });
   }, [registry]);
@@ -421,8 +1246,9 @@ function EventopProvider({
     boot();
     const unsub = registry.subscribe(syncToSDK);
     return () => {
+      var _window$Eventop2;
       unsub();
-      window.Eventop?.cancelTour();
+      (_window$Eventop2 = window.Eventop) === null || _window$Eventop2 === void 0 || _window$Eventop2.cancelTour();
     };
   }, []);
   const ctx = {
@@ -438,6 +1264,241 @@ function EventopProvider({
   });
 }
 
+function EventopTarget({
+  children,
+  id,
+  name,
+  description,
+  navigate,
+  navigateWaitFor,
+  advanceOn,
+  waitFor,
+  ...rest
+}) {
+  const registry = useRegistry();
+  const ref = useRef(null);
+  const dataAttr = `data-evtp-${id}`;
+  const selector = `[${dataAttr}]`;
+  useEffect(() => {
+    if (!id || !name) {
+      console.warn('[Eventop] <EventopTarget> requires id and name props.');
+      return;
+    }
+    registry.registerFeature({
+      id,
+      name,
+      description,
+      selector,
+      navigate,
+      navigateWaitFor,
+      waitFor,
+      advanceOn: advanceOn ? {
+        selector,
+        ...advanceOn
+      } : null
+    });
+    return () => registry.unregisterFeature(id);
+  }, [id, name, description]);
+  const child = Children.only(children);
+  let wrapped;
+  try {
+    wrapped = /*#__PURE__*/cloneElement(child, {
+      [dataAttr]: '',
+      ref: node => {
+        ref.current = node;
+        const originalRef = child.ref;
+        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+      }
+    });
+  } catch {
+    wrapped = /*#__PURE__*/jsx("span", {
+      [dataAttr]: '',
+      ref: ref,
+      style: {
+        display: 'contents'
+      },
+      children: child
+    });
+  }
+  return /*#__PURE__*/jsx(EventopFeatureScopeContext.Provider, {
+    value: id,
+    children: wrapped
+  });
+}
+
+function EventopStep({
+  children,
+  feature,
+  index,
+  parentStep,
+  waitFor,
+  advanceOn
+}) {
+  const registry = useRegistry();
+  const featureScope = useFeatureScope();
+  const featureId = feature || featureScope;
+  const ref = useRef(null);
+  if (!featureId) {
+    console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
+  }
+  if (index == null) {
+    console.warn('[Eventop] <EventopStep> requires an index prop.');
+  }
+  const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
+  const selector = `[${dataAttr}]`;
+  useEffect(() => {
+    if (!featureId || index == null) return;
+    registry.registerStep(featureId, index, parentStep ?? null, {
+      selector,
+      waitFor: waitFor || null,
+      advanceOn: advanceOn ? {
+        selector,
+        ...advanceOn
+      } : null
+    });
+    return () => registry.unregisterStep(featureId, index, parentStep ?? null);
+  }, [featureId, index, parentStep]);
+  const child = Children.only(children);
+  let wrapped;
+  try {
+    wrapped = /*#__PURE__*/cloneElement(child, {
+      [dataAttr]: '',
+      ref: node => {
+        ref.current = node;
+        const originalRef = child.ref;
+        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+      }
+    });
+  } catch {
+    wrapped = /*#__PURE__*/jsx("span", {
+      [dataAttr]: '',
+      ref: ref,
+      style: {
+        display: 'contents'
+      },
+      children: child
+    });
+  }
+  return wrapped;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  useEventopAI
+//
+//  Access the SDK programmatic API from inside any component.
+//  Use for stepComplete(), stepFail(), open(), close() etc.
+//
+//  @example
+//  function CheckoutForm() {
+//    const { stepComplete, stepFail } = useEventopAI();
+//
+//    async function handleNext() {
+//      const ok = await validateEmail(email);
+//      if (ok) stepComplete();
+//      else stepFail('Please enter a valid email address.');
+//    }
+//  }
+// ═══════════════════════════════════════════════════════════════════════════
+
+function useEventopAI() {
+  const sdk = () => window.Eventop;
+  return {
+    open: () => {
+      var _sdk;
+      return (_sdk = sdk()) === null || _sdk === void 0 ? void 0 : _sdk.open();
+    },
+    close: () => {
+      var _sdk2;
+      return (_sdk2 = sdk()) === null || _sdk2 === void 0 ? void 0 : _sdk2.close();
+    },
+    cancelTour: () => {
+      var _sdk3;
+      return (_sdk3 = sdk()) === null || _sdk3 === void 0 ? void 0 : _sdk3.cancelTour();
+    },
+    resumeTour: () => {
+      var _sdk4;
+      return (_sdk4 = sdk()) === null || _sdk4 === void 0 ? void 0 : _sdk4.resumeTour();
+    },
+    isActive: () => {
+      var _sdk5;
+      return ((_sdk5 = sdk()) === null || _sdk5 === void 0 ? void 0 : _sdk5.isActive()) ?? false;
+    },
+    isPaused: () => {
+      var _sdk6;
+      return ((_sdk6 = sdk()) === null || _sdk6 === void 0 ? void 0 : _sdk6.isPaused()) ?? false;
+    },
+    stepComplete: () => {
+      var _sdk7;
+      return (_sdk7 = sdk()) === null || _sdk7 === void 0 ? void 0 : _sdk7.stepComplete();
+    },
+    stepFail: msg => {
+      var _sdk8;
+      return (_sdk8 = sdk()) === null || _sdk8 === void 0 ? void 0 : _sdk8.stepFail(msg);
+    },
+    runTour: steps => {
+      var _sdk9;
+      return (_sdk9 = sdk()) === null || _sdk9 === void 0 ? void 0 : _sdk9.runTour(steps);
+    }
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  useEventopTour
+//
+//  Reactively tracks tour state so you can render your own UI.
+//  Polls at 300ms — lightweight enough for a status indicator.
+//
+//  @example
+//  function TourBar() {
+//    const { isActive, isPaused, resume, cancel } = useEventopTour();
+//    if (!isActive && !isPaused) return null;
+//    return (
+//      <div>
+//        {isPaused && <button onClick={resume}>Resume tour</button>}
+//        <button onClick={cancel}>End</button>
+//      </div>
+//    );
+//  }
+// ═══════════════════════════════════════════════════════════════════════════
+
+function useEventopTour() {
+  const [state, setState] = useState({
+    isActive: false,
+    isPaused: false
+  });
+  useEffect(() => {
+    const id = setInterval(() => {
+      const sdk = window.Eventop;
+      if (!sdk) return;
+      const next = {
+        isActive: sdk.isActive(),
+        isPaused: sdk.isPaused()
+      };
+      setState(prev => prev.isActive !== next.isActive || prev.isPaused !== next.isPaused ? next : prev);
+    }, 300);
+    return () => clearInterval(id);
+  }, []);
+  return {
+    ...state,
+    resume: useCallback(() => {
+      var _window$Eventop;
+      return (_window$Eventop = window.Eventop) === null || _window$Eventop === void 0 ? void 0 : _window$Eventop.resumeTour();
+    }, []),
+    cancel: useCallback(() => {
+      var _window$Eventop2;
+      return (_window$Eventop2 = window.Eventop) === null || _window$Eventop2 === void 0 ? void 0 : _window$Eventop2.cancelTour();
+    }, []),
+    open: useCallback(() => {
+      var _window$Eventop3;
+      return (_window$Eventop3 = window.Eventop) === null || _window$Eventop3 === void 0 ? void 0 : _window$Eventop3.open();
+    }, []),
+    close: useCallback(() => {
+      var _window$Eventop4;
+      return (_window$Eventop4 = window.Eventop) === null || _window$Eventop4 === void 0 ? void 0 : _window$Eventop4.close();
+    }, [])
+  };
+}
+
 window.EventopAI = {
   init,
   open,