@eventop/sdk 1.2.2 → 1.2.10

package/dist/react/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/react/index.d.ts

@@ -15,6 +15,29 @@ export interface EventopAIProviderProps {
   suggestions?:    string[];
   theme?:          Theme;
   position?:       Position;
+  /**
+   * Navigation function for cross-page tours.
+   *
+   * When a tour step lives on a different route, the SDK calls this function
+   * with the target pathname, shows the user a message explaining the navigation,
+   * then waits for the target element to appear before showing the step.
+   *
+   * If omitted, the SDK falls back to window.history.pushState + popstate
+   * (best-effort; works for simple SPAs but not React Router / Next.js).
+   *
+   * @example — React Router v6
+   * const navigate = useNavigate();
+   * <EventopAIProvider router={navigate} ...>
+   *
+   * @example — Next.js App Router
+   * const router = useRouter(); // from 'next/navigation'
+   * <EventopAIProvider router={(path) => router.push(path)} ...>
+   *
+   * @example — Next.js Pages Router
+   * const router = useRouter(); // from 'next/router'
+   * <EventopAIProvider router={(path) => router.push(path)} ...>
+   */
+  router?:         (path: string) => void | Promise<void>;
 }
 
 /**
@@ -23,13 +46,36 @@ export interface EventopAIProviderProps {
  * register with this provider automatically.
  *
  * @example
- * <EventopAIProvider
- *   provider={myServerFetcher}
- *   appName="My App"
- *   theme={{ mode: 'auto', tokens: { accent: '#6366f1' } }}
- * >
- *   <App />
- * </EventopAIProvider>
+ * // React Router v6
+ * function Root() {
+ *   const navigate = useNavigate();
+ *   return (
+ *     <EventopAIProvider
+ *       router={navigate}
+ *       provider={myServerFetcher}
+ *       appName="My App"
+ *       theme={{ mode: 'auto', tokens: { accent: '#6366f1' } }}
+ *     >
+ *       <App />
+ *     </EventopAIProvider>
+ *   );
+ * }
+ *
+ * @example
+ * // Next.js App Router (must be 'use client')
+ * 'use client';
+ * export function EventopProvider({ children }) {
+ *   const router = useRouter();
+ *   return (
+ *     <EventopAIProvider
+ *       router={(path) => router.push(path)}
+ *       provider={myServerFetcher}
+ *       appName="My App"
+ *     >
+ *       {children}
+ *     </EventopAIProvider>
+ *   );
+ * }
  */
 export const EventopAIProvider: FC<EventopAIProviderProps>;
 
@@ -44,9 +90,34 @@ export interface EventopTargetProps {
   name:              string;
   /** What the feature does — AI uses this to match user intent */
   description?:      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 automatically:
+   *   1. Tell the user which page it's navigating to and why
+   *   2. Call the `router` function passed to EventopAIProvider
+   *   3. Wait for this feature's element to appear before showing the step
+   *
+   * Only required for features that live on a different page than where
+   * the tour is typically started from. Features on the same page don't
+   * need this prop.
+   *
+   * @example
+   * <EventopTarget
+   *   id="billing"
+   *   name="Billing Settings"
+   *   route="/settings/billing"
+   * >
+   *   <BillingSection />
+   * </EventopTarget>
+   */
+  route?:            string;
   /**
    * Navigate to this screen if the component is not currently mounted.
-   * Called when the user asks about this feature from a different screen.
+   * @deprecated Prefer `route` + the `router` prop on EventopAIProvider
+   *             for React Router and Next.js apps. `navigate` is still
+   *             supported for custom or non-URL-based navigation logic.
    */
   navigate?:         () => void | Promise<void>;
   /** CSS selector to wait for after navigating */
@@ -61,20 +132,27 @@ export interface EventopTargetProps {
 }
 
 /**
- * Wraps any component and registers it as a EventopAI feature.
+ * Wraps any component and registers it as an Eventop feature.
  * Registration happens at the CALL SITE — the wrapped component is unchanged.
  *
  * Works with any component: your own, shadcn, MUI, Radix, anything.
- * The wrapped component does not need to accept refs or know about EventopAI.
+ * The wrapped component does not need to accept refs or know about Eventop.
  *
  * @example
- * // Same Button, different features in different parts of the app
+ * // Feature on the same page — no route needed
  * <EventopTarget id="export" name="Export Design" description="Download as PNG or SVG">
  *   <Button onClick={handleExport}>Export</Button>
  * </EventopTarget>
  *
- * <EventopTarget id="share" name="Share Document" description="Share with teammates">
- *   <Button onClick={handleShare}>Share</Button>
+ * @example
+ * // Feature on a different page — add route so the SDK can navigate there
+ * <EventopTarget
+ *   id="billing"
+ *   name="Billing Settings"
+ *   description="Manage your subscription"
+ *   route="/settings/billing"
+ * >
+ *   <BillingSection />
  * </EventopTarget>
  */
 export const EventopTarget: FC<EventopTargetProps>;

package/dist/react/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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventop/sdk",
-  "version": "1.2.2",
+  "version": "1.2.10",
   "description": "AI-powered guided tours for any web app. Drop-in, themeable, provider-agnostic.",
   "keywords": [
     "onboarding",