@eventop/sdk 1.2.2 → 1.2.10

package/dist/index.cjs

@@ -52,12 +52,16 @@ function useFeatureScope() {
  *
  *   In practice most flows are flat (index 0, 1, 2, 3...) but the
  *   registry supports nested depth for complex interactions.
+ *
+ * Route awareness:
+ *   Features can declare the pathname they live on via `route`.
+ *   The snapshot() includes this so the SDK core can navigate
+ *   automatically when a tour step targets a feature on a different page.
  */
 function createFeatureRegistry() {
   // Map<featureId, featureData>
   const features = new Map();
   // Map<featureId, Map<stepKey, stepData>>
-  // stepKey is either a number (flat) or "parentIndex.childIndex" (nested)
   const flowSteps = new Map();
   const listeners = new Set();
   function notify() {
@@ -81,14 +85,6 @@ function createFeatureRegistry() {
 
   // ── Step registration ────────────────────────────────────────────────────
 
-  /**
-   * Register a flow step.
-   *
-   * @param {string} featureId      - Parent feature id
-   * @param {number} index          - Position in the flat flow (0, 1, 2…)
-   * @param {number|null} parentStep - If set, this is a sub-step of parentStep
-   * @param {object} stepData       - { selector, waitFor, advanceOn, ... }
-   */
   function registerStep(featureId, index, parentStep, stepData) {
     if (!flowSteps.has(featureId)) {
       flowSteps.set(featureId, new Map());
@@ -113,35 +109,14 @@ function createFeatureRegistry() {
 
   // ── Snapshot ─────────────────────────────────────────────────────────────
 
-  /**
-   * Build the flat flow array the SDK core expects.
-   *
-   * For nested steps we inline sub-steps after their parent step,
-   * in index order. This means a flow like:
-   *
-   *   Step 0 (flat)
-   *   Step 1 (flat)
-   *     Step 1.0 (sub-step of 1)
-   *     Step 1.1 (sub-step of 1)
-   *   Step 2 (flat)
-   *
-   * becomes the SDK flow: [step0, step1, step1.0, step1.1, step2]
-   *
-   * The AI writes titles/text for the parent feature.
-   * Sub-steps inherit the parent step's text with a "(N/M)" suffix added
-   * by the SDK's expandFlowSteps() function.
-   */
   function buildFlow(featureId) {
     const map = flowSteps.get(featureId);
     if (!map || map.size === 0) return null;
     const allSteps = Array.from(map.values());
-
-    // Separate top-level and nested steps
     const topLevel = allSteps.filter(s => s.parentStep == null).sort((a, b) => a.index - b.index);
     const result = [];
     topLevel.forEach(step => {
       result.push(step);
-      // Inline any sub-steps after the parent
       const children = allSteps.filter(s => s.parentStep === step.index).sort((a, b) => a.index - b.index);
       result.push(...children);
     });
@@ -150,7 +125,9 @@ function createFeatureRegistry() {
 
   /**
    * Returns the live feature array in the format the SDK core expects.
-   * screen.check() is automatic — mounted = available.
+   *
+   * `route` is now included in every feature entry so the core can detect
+   * when navigation is needed before showing a step.
    */
   function snapshot() {
     return Array.from(features.values()).map(feature => {
@@ -160,6 +137,7 @@ function createFeatureRegistry() {
         name: feature.name,
         description: feature.description,
         selector: feature.selector,
+        route: feature.route || null,
         advanceOn: feature.advanceOn || null,
         waitFor: feature.waitFor || null,
         ...(flow ? {
@@ -195,7 +173,8 @@ function EventopProvider({
   assistantName,
   suggestions,
   theme,
-  position
+  position,
+  router
 }) {
   if (!provider) throw new Error('[Eventop] <EventopProvider> requires a provider prop.');
   if (!appName) throw new Error('[Eventop] <EventopProvider> requires an appName prop.');
@@ -209,10 +188,9 @@ function EventopProvider({
     });
   }, [registry]);
   react.useEffect(() => {
-    // Dynamically import core.js only in the browser
     async function boot() {
-      // Import the core SDK (this only runs on client)
-      await Promise.resolve().then(function () { return require('./core.cjs'); }).then(function (n) { return n.core; });
+      await Promise.resolve().then(function () { return require('./core.cjs'); }); // Ensure the UMD bundle is loaded (for Shepherd and global Eventop)
+
       window.Eventop.init({
         provider,
         config: {
@@ -221,6 +199,7 @@ function EventopProvider({
           suggestions,
           theme,
           position,
+          router,
           features: registry.snapshot(),
           _providerName: 'custom'
         }
@@ -238,6 +217,22 @@ function EventopProvider({
       }
     };
   }, [provider, appName, assistantName, suggestions, theme, position, registry, syncToSDK]);
+  // Note: `router` is intentionally omitted from the deps array above.
+  // Router instances from useNavigate / useRouter are stable references —
+  // including them would re-boot the SDK on every render.
+  // Instead, we sync router updates via a separate effect below.
+
+  // ── Keep the router reference fresh without re-booting the SDK ─────────────
+  // When the router instance changes (rare, but can happen in Next.js during
+  // hydration), we push the new reference into the already-running SDK core.
+  react.useEffect(() => {
+    if (sdkReady.current && window.Eventop) {
+      var _window$Eventop$_upda2, _window$Eventop3;
+      (_window$Eventop$_upda2 = (_window$Eventop3 = window.Eventop)._updateConfig) === null || _window$Eventop$_upda2 === void 0 || _window$Eventop$_upda2.call(_window$Eventop3, {
+        router
+      });
+    }
+  }, [router]);
   const ctx = {
     registerFeature: registry.registerFeature,
     unregisterFeature: registry.unregisterFeature,
@@ -256,6 +251,7 @@ function EventopTarget({
   id,
   name,
   description,
+  route,
   navigate,
   navigateWaitFor,
   advanceOn,
@@ -275,6 +271,7 @@ function EventopTarget({
       id,
       name,
       description,
+      route,
       selector,
       navigate,
       navigateWaitFor,
@@ -285,7 +282,7 @@ function EventopTarget({
       } : null
     });
     return () => registry.unregisterFeature(id);
-  }, [id, name, description]);
+  }, [id, name, description, route]);
   const child = react.Children.only(children);
   let wrapped;
   try {

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 // ─── Step ────────────────────────────────────────────────────────────────────
 
+import { JSX } from "react";
+
 export interface Step {
   id?:       string;
   title:     string;
@@ -54,6 +56,19 @@ export interface Feature {
   description?:        string;
   /** CSS selector for the feature's primary DOM element */
   selector:            string;
+  /**
+   * The pathname where this feature lives (e.g. "/settings/billing").
+   *
+   * When a tour step targets this feature and the user is on a different
+   * page, the SDK will:
+   *   1. Tell the user it's navigating and why
+   *   2. Call the `router` function passed to EventopAIProvider / init()
+   *   3. Wait for the feature element to appear before showing the step
+   *
+   * Prefer `route` over the legacy `screen` API for React Router and
+   * Next.js apps.
+   */
+  route?:              string;
   /** Additional related selectors for context */
   relatedSelectors?:   Record<string, string>;
   /** Auto-advance when this event fires */
@@ -67,7 +82,8 @@ export interface Feature {
   flow?:               FlowStep[];
   /**
    * Screen this feature lives on.
-   * SDK navigates to the correct screen before showing the step.
+   * @deprecated Prefer `route` + the `router` prop on EventopAIProvider.
+   *             `screen` is still supported for backward compatibility.
    */
   screen?:             Screen;
 }
@@ -119,6 +135,27 @@ export interface Config {
   suggestions?:   string[];
   theme?:         Theme;
   position?:      Position;
+  /**
+   * Navigation function the SDK calls when a tour step lives on a different page.
+   *
+   * Pass your framework's navigate/push function here:
+   *
+   * React Router v6:
+   *   const navigate = useNavigate();
+   *   <EventopAIProvider router={navigate} ...>
+   *
+   * Next.js App Router:
+   *   const router = useRouter();
+   *   <EventopAIProvider router={(path) => router.push(path)} ...>
+   *
+   * Next.js Pages Router:
+   *   const router = useRouter();
+   *   <EventopAIProvider router={(path) => router.push(path)} ...>
+   *
+   * If omitted, the SDK falls back to window.history.pushState + popstate
+   * (best-effort; works for simple SPAs that listen to popstate).
+   */
+  router?:        (path: string) => void | Promise<void>;
   /** @internal — set by provider factories */
   _providerName?: string;
 }
@@ -174,16 +211,6 @@ export interface Providers {
   /**
    * Custom provider — proxy through your own server.
    * Recommended for production. Keeps API keys off the browser.
-   *
-   * @example
-   * 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();
-   * })
    */
   custom(fn: ProviderFn): ProviderFn;
 }
@@ -215,40 +242,22 @@ export interface EventopSDK {
    */
   runTour(steps: Step[], options?: { showProgress?: boolean; waitTimeout?: number }): Promise<void>;
 
-  /**
-   * Hard cancel the active tour.
-   * Clears all pause state — no resume available after this.
-   */
+  /** Hard cancel the active tour. */
   cancelTour(): void;
 
-  /**
-   * Resume a paused tour from where the user left off.
-   * Called automatically by the resume button in the chat panel.
-   */
+  /** Resume a paused tour from where the user left off. */
   resumeTour(): void;
 
-  /**
-   * Advance the current tour step programmatically.
-   * Call after async validation succeeds.
-   *
-   * @example
-   * const ok = await validateEmail(email);
-   * if (ok) EventopAI.stepComplete();
-   */
+  /** Advance the current tour step programmatically. */
   stepComplete(): void;
 
-  /**
-   * Block tour advancement and show an inline error in the current step tooltip.
-   *
-   * @example
-   * EventopAI.stepFail('Please enter a valid email address.');
-   */
+  /** Block tour advancement and show an inline error. */
   stepFail(message: string): void;
 
   /** Returns true if a tour is currently running */
   isActive(): boolean;
 
-  /** Returns true if a tour is paused (cancelled but resumable) */
+  /** Returns true if a tour is paused */
   isPaused(): boolean;
 
   /** @internal — used by the React/Vue packages to sync live feature registry */
@@ -256,4 +265,78 @@ export interface EventopSDK {
 }
 
 declare const EventopAI: EventopSDK;
-export default EventopAI;
+export default EventopAI;
+
+
+// ─── React bindings ───────────────────────────────────────────────────────────
+
+export interface EventopAIProviderProps {
+  children:        React.ReactNode;
+  provider:        ProviderFn;
+  appName:         string;
+  assistantName?:  string;
+  suggestions?:    string[];
+  theme?:          Theme;
+  position?:       Position;
+  /**
+   * Navigation function for cross-page tours.
+   *
+   * React Router v6:   pass `useNavigate()` directly
+   * Next.js App Router: pass `(path) => useRouter().push(path)`
+   * Next.js Pages Router: pass `(path) => useRouter().push(path)`
+   */
+  router?:         (path: string) => void | Promise<void>;
+}
+
+export interface EventopTargetProps {
+  children:         React.ReactElement;
+  id:               string;
+  name:             string;
+  description?:     string;
+  /**
+   * The pathname where this feature lives (e.g. "/settings/billing").
+   * The SDK auto-navigates here when a tour step targets this feature
+   * and the user is on a different page.
+   */
+  route?:           string;
+  navigate?:        () => void | Promise<void>;
+  navigateWaitFor?: string;
+  advanceOn?:       Omit<AdvanceOn, 'selector'>;
+  waitFor?:         string;
+}
+
+export interface EventopStepProps {
+  children:    React.ReactElement;
+  feature?:    string;
+  index:       number;
+  parentStep?: number;
+  waitFor?:    string;
+  advanceOn?:  Omit<AdvanceOn, 'selector'>;
+}
+
+export interface UseEventopAIReturn {
+  open():              void;
+  close():             void;
+  cancelTour():        void;
+  resumeTour():        void;
+  isActive():          boolean;
+  isPaused():          boolean;
+  stepComplete():      void;
+  stepFail(msg: string): void;
+  runTour(steps: Step[]): Promise<void>;
+}
+
+export interface UseEventopTourReturn {
+  isActive: boolean;
+  isPaused: boolean;
+  resume():  void;
+  cancel():  void;
+  open():    void;
+  close():   void;
+}
+
+export declare function EventopAIProvider(props: EventopAIProviderProps): JSX.Element;
+export declare function EventopTarget(props: EventopTargetProps): JSX.Element;
+export declare function EventopStep(props: EventopStepProps): JSX.Element;
+export declare function useEventopAI(): UseEventopAIReturn;
+export declare function useEventopTour(): UseEventopTourReturn;

package/dist/index.js

@@ -50,12 +50,16 @@ function useFeatureScope() {
  *
  *   In practice most flows are flat (index 0, 1, 2, 3...) but the
  *   registry supports nested depth for complex interactions.
+ *
+ * Route awareness:
+ *   Features can declare the pathname they live on via `route`.
+ *   The snapshot() includes this so the SDK core can navigate
+ *   automatically when a tour step targets a feature on a different page.
  */
 function createFeatureRegistry() {
   // Map<featureId, featureData>
   const features = new Map();
   // Map<featureId, Map<stepKey, stepData>>
-  // stepKey is either a number (flat) or "parentIndex.childIndex" (nested)
   const flowSteps = new Map();
   const listeners = new Set();
   function notify() {
@@ -79,14 +83,6 @@ function createFeatureRegistry() {
 
   // ── Step registration ────────────────────────────────────────────────────
 
-  /**
-   * Register a flow step.
-   *
-   * @param {string} featureId      - Parent feature id
-   * @param {number} index          - Position in the flat flow (0, 1, 2…)
-   * @param {number|null} parentStep - If set, this is a sub-step of parentStep
-   * @param {object} stepData       - { selector, waitFor, advanceOn, ... }
-   */
   function registerStep(featureId, index, parentStep, stepData) {
     if (!flowSteps.has(featureId)) {
       flowSteps.set(featureId, new Map());
@@ -111,35 +107,14 @@ function createFeatureRegistry() {
 
   // ── Snapshot ─────────────────────────────────────────────────────────────
 
-  /**
-   * Build the flat flow array the SDK core expects.
-   *
-   * For nested steps we inline sub-steps after their parent step,
-   * in index order. This means a flow like:
-   *
-   *   Step 0 (flat)
-   *   Step 1 (flat)
-   *     Step 1.0 (sub-step of 1)
-   *     Step 1.1 (sub-step of 1)
-   *   Step 2 (flat)
-   *
-   * becomes the SDK flow: [step0, step1, step1.0, step1.1, step2]
-   *
-   * The AI writes titles/text for the parent feature.
-   * Sub-steps inherit the parent step's text with a "(N/M)" suffix added
-   * by the SDK's expandFlowSteps() function.
-   */
   function buildFlow(featureId) {
     const map = flowSteps.get(featureId);
     if (!map || map.size === 0) return null;
     const allSteps = Array.from(map.values());
-
-    // Separate top-level and nested steps
     const topLevel = allSteps.filter(s => s.parentStep == null).sort((a, b) => a.index - b.index);
     const result = [];
     topLevel.forEach(step => {
       result.push(step);
-      // Inline any sub-steps after the parent
       const children = allSteps.filter(s => s.parentStep === step.index).sort((a, b) => a.index - b.index);
       result.push(...children);
     });
@@ -148,7 +123,9 @@ function createFeatureRegistry() {
 
   /**
    * Returns the live feature array in the format the SDK core expects.
-   * screen.check() is automatic — mounted = available.
+   *
+   * `route` is now included in every feature entry so the core can detect
+   * when navigation is needed before showing a step.
    */
   function snapshot() {
     return Array.from(features.values()).map(feature => {
@@ -158,6 +135,7 @@ function createFeatureRegistry() {
         name: feature.name,
         description: feature.description,
         selector: feature.selector,
+        route: feature.route || null,
         advanceOn: feature.advanceOn || null,
         waitFor: feature.waitFor || null,
         ...(flow ? {
@@ -193,7 +171,8 @@ function EventopProvider({
   assistantName,
   suggestions,
   theme,
-  position
+  position,
+  router
 }) {
   if (!provider) throw new Error('[Eventop] <EventopProvider> requires a provider prop.');
   if (!appName) throw new Error('[Eventop] <EventopProvider> requires an appName prop.');
@@ -207,10 +186,9 @@ function EventopProvider({
     });
   }, [registry]);
   useEffect(() => {
-    // Dynamically import core.js only in the browser
     async function boot() {
-      // Import the core SDK (this only runs on client)
-      await import('./core.js').then(function (n) { return n.c; });
+      await import('./core.js'); // Ensure the UMD bundle is loaded (for Shepherd and global Eventop)
+
       window.Eventop.init({
         provider,
         config: {
@@ -219,6 +197,7 @@ function EventopProvider({
           suggestions,
           theme,
           position,
+          router,
           features: registry.snapshot(),
           _providerName: 'custom'
         }
@@ -236,6 +215,22 @@ function EventopProvider({
       }
     };
   }, [provider, appName, assistantName, suggestions, theme, position, registry, syncToSDK]);
+  // Note: `router` is intentionally omitted from the deps array above.
+  // Router instances from useNavigate / useRouter are stable references —
+  // including them would re-boot the SDK on every render.
+  // Instead, we sync router updates via a separate effect below.
+
+  // ── Keep the router reference fresh without re-booting the SDK ─────────────
+  // When the router instance changes (rare, but can happen in Next.js during
+  // hydration), we push the new reference into the already-running SDK core.
+  useEffect(() => {
+    if (sdkReady.current && window.Eventop) {
+      var _window$Eventop$_upda2, _window$Eventop3;
+      (_window$Eventop$_upda2 = (_window$Eventop3 = window.Eventop)._updateConfig) === null || _window$Eventop$_upda2 === void 0 || _window$Eventop$_upda2.call(_window$Eventop3, {
+        router
+      });
+    }
+  }, [router]);
   const ctx = {
     registerFeature: registry.registerFeature,
     unregisterFeature: registry.unregisterFeature,
@@ -254,6 +249,7 @@ function EventopTarget({
   id,
   name,
   description,
+  route,
   navigate,
   navigateWaitFor,
   advanceOn,
@@ -273,6 +269,7 @@ function EventopTarget({
       id,
       name,
       description,
+      route,
       selector,
       navigate,
       navigateWaitFor,
@@ -283,7 +280,7 @@ function EventopTarget({
       } : null
     });
     return () => registry.unregisterFeature(id);
-  }, [id, name, description]);
+  }, [id, name, description, route]);
   const child = Children.only(children);
   let wrapped;
   try {