@eventop/sdk 1.2.11 → 1.2.13

package/dist/index.cjs

@@ -29,18 +29,41 @@ function useFeatureScope() {
 /**
  * FeatureRegistry
  *
- * The live map of everything currently mounted in the React tree.
+ * The live map of everything registered in the React tree — both mounted
+ * (full entries) and unmounted (ghost entries).
  *
- * Features   — registered by EventopTarget
- * Flow steps — registered by EventopStep, attached to a feature by id
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  Full entry  — component is currently mounted                       │
+ * │  { id, name, description, route, selector, ... }                   │
+ * │                                                                     │
+ * │  Ghost entry — component has unmounted (navigated away)             │
+ * │  { id, name, description, route, selector: null, _ghost: true }    │
+ * └─────────────────────────────────────────────────────────────────────┘
  *
- * Both features and steps can live anywhere in the component tree.
- * They don't need to be co-located. An EventopStep just needs to know
- * which feature id it belongs to.
+ * Why ghosts?
+ *
+ *   The AI system prompt is built from the registry snapshot. Without ghosts,
+ *   features on other pages don't exist in the snapshot when the user is
+ *   elsewhere — the AI can't pick them, so cross-page tours never start.
+ *
+ *   With ghosts, every feature the app has ever rendered stays in the
+ *   snapshot permanently. The AI always has the full picture. The tour
+ *   runner already resolves selectors lazily (after navigation), so a
+ *   null selector on a ghost is fine — it gets filled in at show-time
+ *   once the component mounts on the target page.
+ *
+ * Lifecycle:
+ *
+ *   EventopTarget mounts   → registerFeature()  → full entry
+ *   EventopTarget unmounts → unregisterFeature() → ghost entry (metadata kept)
+ *   EventopTarget remounts → registerFeature()  → full entry again (selector restored)
+ *
+ * Flow steps follow the same pattern — they're pruned on unmount but the
+ * parent feature ghost keeps the feature visible to the AI.
  *
  * Nested steps:
- *   Steps can themselves have children steps (sub-steps) by passing
- *   a parentStep prop to EventopStep. This lets you model flows like:
+ *   Steps can have children steps (sub-steps) by passing a parentStep prop.
+ *   This lets you model flows like:
  *
  *   Feature: "Create styled text"
  *     Step 0: Click Add Text
@@ -49,17 +72,10 @@ function useFeatureScope() {
  *       Step 1.1: Open font picker       ← parentStep: 1, index: 1
  *       Step 1.2: Choose a font          ← parentStep: 1, index: 2
  *     Step 2: Click Done
- *
- *   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>
+  // Values are either full entries or ghost entries (_ghost: true)
   const features = new Map();
   // Map<featureId, Map<stepKey, stepData>>
   const flowSteps = new Map();
@@ -71,20 +87,37 @@ function createFeatureRegistry() {
   // ── Feature registration ─────────────────────────────────────────────────
 
   function registerFeature(feature) {
+    // Restore a ghost or create a fresh full entry.
+    // Always overwrite so a remount gets the latest selector.
     features.set(feature.id, {
       ...feature,
+      _ghost: false,
       _registeredAt: Date.now()
     });
     notify();
   }
   function unregisterFeature(id) {
+    if (!features.has(id)) return;
+
+    // Downgrade to ghost — keep all metadata, null out the live selector.
+    // Flow steps are pruned separately (their DOM elements are gone too).
+    const feature = features.get(id);
     features.set(id, {
-      ...existing,
+      id: feature.id,
+      name: feature.name,
+      description: feature.description,
+      route: feature.route || null,
+      navigate: feature.navigate || null,
+      navigateWaitFor: feature.navigateWaitFor || null,
+      _registeredAt: feature._registeredAt,
       selector: null,
       advanceOn: null,
       waitFor: null,
       _ghost: true
     });
+
+    // Prune flow steps — their selectors are dead too.
+    // They'll re-register when the component remounts on the target page.
     flowSteps.delete(id);
     notify();
   }
@@ -130,41 +163,62 @@ function createFeatureRegistry() {
   }
 
   /**
-   * Returns the live feature array in the format the SDK core expects.
+   * Returns the full feature array — both live and ghost entries.
    *
-   * `route` is now included in every feature entry so the core can detect
-   * when navigation is needed before showing a step.
+   * Ghost entries have selector: null. The SDK core handles this correctly:
+   *   - The AI system prompt uses name/description/route (always present)
+   *   - The tour runner resolves the selector lazily after navigation,
+   *     at which point the component has remounted and re-registered
+   *
+   * screen.check() returns false for ghosts so the SDK knows navigation
+   * is needed before showing the step.
    */
   function snapshot() {
     return Array.from(features.values()).map(feature => {
       const flow = buildFlow(feature.id);
+      const isGhost = feature._ghost === true;
       return {
         id: feature.id,
         name: feature.name,
         description: feature.description,
-        selector: feature.selector,
+        selector: feature.selector || null,
         route: feature.route || null,
         advanceOn: feature.advanceOn || null,
         waitFor: feature.waitFor || null,
+        _ghost: isGhost,
         ...(flow ? {
           flow
         } : {}),
         screen: {
           id: feature.id,
-          check: () => features.has(feature.id),
+          // Ghost entries always fail the check → SDK knows to navigate
+          check: () => {
+            var _features$get;
+            return ((_features$get = features.get(feature.id)) === null || _features$get === void 0 ? void 0 : _features$get._ghost) !== true;
+          },
           navigate: feature.navigate || null,
           waitFor: feature.navigateWaitFor || feature.selector || null
         }
       };
     });
   }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  /**
+   * Returns true only for fully mounted (non-ghost) features.
+   */
+  function isRegistered(id) {
+    const f = features.get(id);
+    return !!f && !f._ghost;
+  }
   return {
     registerFeature,
     unregisterFeature,
     registerStep,
     unregisterStep,
     snapshot,
-    isRegistered: id => features.has(id),
+    isRegistered,
     subscribe: fn => {
       listeners.add(fn);
       return () => listeners.delete(fn);
@@ -261,18 +315,28 @@ function EventopTarget({
   navigate,
   navigateWaitFor,
   advanceOn,
-  waitFor,
-  ...rest
+  waitFor
 }) {
   const registry = useRegistry();
-  const ref = react.useRef(null);
+  const wrapperRef = react.useRef(null);
   const dataAttr = `data-evtp-${id}`;
   const selector = `[${dataAttr}]`;
   react.useEffect(() => {
+    var _wrapperRef$current;
     if (!id || !name) {
       console.warn('[Eventop] <EventopTarget> requires id and name props.');
       return;
     }
+
+    // Set the attribute directly on the first real child DOM element.
+    // This bypasses React's prop system entirely — works regardless of whether
+    // the wrapped component forwards unknown props.
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    } else {
+      console.warn(`[Eventop] <EventopTarget id="${id}"> could not find a child DOM element to attach to. ` + `Make sure the wrapped component renders at least one DOM element.`);
+    }
     registry.registerFeature({
       id,
       name,
@@ -287,32 +351,24 @@ function EventopTarget({
         ...advanceOn
       } : null
     });
-    return () => registry.unregisterFeature(id);
-  }, [id, name, description, route]);
-  const child = react.Children.only(children);
-  let wrapped;
-  try {
-    wrapped = /*#__PURE__*/react.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__*/jsxRuntime.jsx("span", {
-      [dataAttr]: '',
-      ref: ref,
+    return () => {
+      var _wrapperRef$current2;
+      // Clean up the injected attribute on unmount
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterFeature(id);
+    };
+  }, [id, name, description, route]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsxRuntime.jsx(EventopFeatureScopeContext.Provider, {
+    value: id,
+    children: /*#__PURE__*/jsxRuntime.jsx("span", {
+      ref: wrapperRef,
       style: {
         display: 'contents'
       },
-      children: child
-    });
-  }
-  return /*#__PURE__*/jsxRuntime.jsx(EventopFeatureScopeContext.Provider, {
-    value: id,
-    children: wrapped
+      children: react.Children.only(children)
+    })
   });
 }
 
@@ -327,7 +383,7 @@ function EventopStep({
   const registry = useRegistry();
   const featureScope = useFeatureScope();
   const featureId = feature || featureScope;
-  const ref = react.useRef(null);
+  const wrapperRef = react.useRef(null);
   if (!featureId) {
     console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
   }
@@ -337,7 +393,14 @@ function EventopStep({
   const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
   const selector = `[${dataAttr}]`;
   react.useEffect(() => {
+    var _wrapperRef$current;
     if (!featureId || index == null) return;
+
+    // Inject attribute directly onto the first real child DOM element
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    }
     registry.registerStep(featureId, index, parentStep ?? null, {
       selector,
       waitFor: waitFor || null,
@@ -346,30 +409,21 @@ function EventopStep({
         ...advanceOn
       } : null
     });
-    return () => registry.unregisterStep(featureId, index, parentStep ?? null);
-  }, [featureId, index, parentStep]);
-  const child = react.Children.only(children);
-  let wrapped;
-  try {
-    wrapped = /*#__PURE__*/react.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__*/jsxRuntime.jsx("span", {
-      [dataAttr]: '',
-      ref: ref,
-      style: {
-        display: 'contents'
-      },
-      children: child
-    });
-  }
-  return wrapped;
+    return () => {
+      var _wrapperRef$current2;
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterStep(featureId, index, parentStep ?? null);
+    };
+  }, [featureId, index, parentStep]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsxRuntime.jsx("span", {
+    ref: wrapperRef,
+    style: {
+      display: 'contents'
+    },
+    children: react.Children.only(children)
+  });
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createContext, useContext, useRef, useCallback, useEffect, Children, cloneElement, useState } from 'react';
+import { createContext, useContext, useRef, useCallback, useEffect, Children, useState } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 /**
@@ -27,18 +27,41 @@ function useFeatureScope() {
 /**
  * FeatureRegistry
  *
- * The live map of everything currently mounted in the React tree.
+ * The live map of everything registered in the React tree — both mounted
+ * (full entries) and unmounted (ghost entries).
  *
- * Features   — registered by EventopTarget
- * Flow steps — registered by EventopStep, attached to a feature by id
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  Full entry  — component is currently mounted                       │
+ * │  { id, name, description, route, selector, ... }                   │
+ * │                                                                     │
+ * │  Ghost entry — component has unmounted (navigated away)             │
+ * │  { id, name, description, route, selector: null, _ghost: true }    │
+ * └─────────────────────────────────────────────────────────────────────┘
  *
- * Both features and steps can live anywhere in the component tree.
- * They don't need to be co-located. An EventopStep just needs to know
- * which feature id it belongs to.
+ * Why ghosts?
+ *
+ *   The AI system prompt is built from the registry snapshot. Without ghosts,
+ *   features on other pages don't exist in the snapshot when the user is
+ *   elsewhere — the AI can't pick them, so cross-page tours never start.
+ *
+ *   With ghosts, every feature the app has ever rendered stays in the
+ *   snapshot permanently. The AI always has the full picture. The tour
+ *   runner already resolves selectors lazily (after navigation), so a
+ *   null selector on a ghost is fine — it gets filled in at show-time
+ *   once the component mounts on the target page.
+ *
+ * Lifecycle:
+ *
+ *   EventopTarget mounts   → registerFeature()  → full entry
+ *   EventopTarget unmounts → unregisterFeature() → ghost entry (metadata kept)
+ *   EventopTarget remounts → registerFeature()  → full entry again (selector restored)
+ *
+ * Flow steps follow the same pattern — they're pruned on unmount but the
+ * parent feature ghost keeps the feature visible to the AI.
  *
  * Nested steps:
- *   Steps can themselves have children steps (sub-steps) by passing
- *   a parentStep prop to EventopStep. This lets you model flows like:
+ *   Steps can have children steps (sub-steps) by passing a parentStep prop.
+ *   This lets you model flows like:
  *
  *   Feature: "Create styled text"
  *     Step 0: Click Add Text
@@ -47,17 +70,10 @@ function useFeatureScope() {
  *       Step 1.1: Open font picker       ← parentStep: 1, index: 1
  *       Step 1.2: Choose a font          ← parentStep: 1, index: 2
  *     Step 2: Click Done
- *
- *   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>
+  // Values are either full entries or ghost entries (_ghost: true)
   const features = new Map();
   // Map<featureId, Map<stepKey, stepData>>
   const flowSteps = new Map();
@@ -69,20 +85,37 @@ function createFeatureRegistry() {
   // ── Feature registration ─────────────────────────────────────────────────
 
   function registerFeature(feature) {
+    // Restore a ghost or create a fresh full entry.
+    // Always overwrite so a remount gets the latest selector.
     features.set(feature.id, {
       ...feature,
+      _ghost: false,
       _registeredAt: Date.now()
     });
     notify();
   }
   function unregisterFeature(id) {
+    if (!features.has(id)) return;
+
+    // Downgrade to ghost — keep all metadata, null out the live selector.
+    // Flow steps are pruned separately (their DOM elements are gone too).
+    const feature = features.get(id);
     features.set(id, {
-      ...existing,
+      id: feature.id,
+      name: feature.name,
+      description: feature.description,
+      route: feature.route || null,
+      navigate: feature.navigate || null,
+      navigateWaitFor: feature.navigateWaitFor || null,
+      _registeredAt: feature._registeredAt,
       selector: null,
       advanceOn: null,
       waitFor: null,
       _ghost: true
     });
+
+    // Prune flow steps — their selectors are dead too.
+    // They'll re-register when the component remounts on the target page.
     flowSteps.delete(id);
     notify();
   }
@@ -128,41 +161,62 @@ function createFeatureRegistry() {
   }
 
   /**
-   * Returns the live feature array in the format the SDK core expects.
+   * Returns the full feature array — both live and ghost entries.
    *
-   * `route` is now included in every feature entry so the core can detect
-   * when navigation is needed before showing a step.
+   * Ghost entries have selector: null. The SDK core handles this correctly:
+   *   - The AI system prompt uses name/description/route (always present)
+   *   - The tour runner resolves the selector lazily after navigation,
+   *     at which point the component has remounted and re-registered
+   *
+   * screen.check() returns false for ghosts so the SDK knows navigation
+   * is needed before showing the step.
    */
   function snapshot() {
     return Array.from(features.values()).map(feature => {
       const flow = buildFlow(feature.id);
+      const isGhost = feature._ghost === true;
       return {
         id: feature.id,
         name: feature.name,
         description: feature.description,
-        selector: feature.selector,
+        selector: feature.selector || null,
         route: feature.route || null,
         advanceOn: feature.advanceOn || null,
         waitFor: feature.waitFor || null,
+        _ghost: isGhost,
         ...(flow ? {
           flow
         } : {}),
         screen: {
           id: feature.id,
-          check: () => features.has(feature.id),
+          // Ghost entries always fail the check → SDK knows to navigate
+          check: () => {
+            var _features$get;
+            return ((_features$get = features.get(feature.id)) === null || _features$get === void 0 ? void 0 : _features$get._ghost) !== true;
+          },
           navigate: feature.navigate || null,
           waitFor: feature.navigateWaitFor || feature.selector || null
         }
       };
     });
   }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  /**
+   * Returns true only for fully mounted (non-ghost) features.
+   */
+  function isRegistered(id) {
+    const f = features.get(id);
+    return !!f && !f._ghost;
+  }
   return {
     registerFeature,
     unregisterFeature,
     registerStep,
     unregisterStep,
     snapshot,
-    isRegistered: id => features.has(id),
+    isRegistered,
     subscribe: fn => {
       listeners.add(fn);
       return () => listeners.delete(fn);
@@ -259,18 +313,28 @@ function EventopTarget({
   navigate,
   navigateWaitFor,
   advanceOn,
-  waitFor,
-  ...rest
+  waitFor
 }) {
   const registry = useRegistry();
-  const ref = useRef(null);
+  const wrapperRef = useRef(null);
   const dataAttr = `data-evtp-${id}`;
   const selector = `[${dataAttr}]`;
   useEffect(() => {
+    var _wrapperRef$current;
     if (!id || !name) {
       console.warn('[Eventop] <EventopTarget> requires id and name props.');
       return;
     }
+
+    // Set the attribute directly on the first real child DOM element.
+    // This bypasses React's prop system entirely — works regardless of whether
+    // the wrapped component forwards unknown props.
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    } else {
+      console.warn(`[Eventop] <EventopTarget id="${id}"> could not find a child DOM element to attach to. ` + `Make sure the wrapped component renders at least one DOM element.`);
+    }
     registry.registerFeature({
       id,
       name,
@@ -285,32 +349,24 @@ function EventopTarget({
         ...advanceOn
       } : null
     });
-    return () => registry.unregisterFeature(id);
-  }, [id, name, description, route]);
-  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,
+    return () => {
+      var _wrapperRef$current2;
+      // Clean up the injected attribute on unmount
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterFeature(id);
+    };
+  }, [id, name, description, route]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsx(EventopFeatureScopeContext.Provider, {
+    value: id,
+    children: /*#__PURE__*/jsx("span", {
+      ref: wrapperRef,
       style: {
         display: 'contents'
       },
-      children: child
-    });
-  }
-  return /*#__PURE__*/jsx(EventopFeatureScopeContext.Provider, {
-    value: id,
-    children: wrapped
+      children: Children.only(children)
+    })
   });
 }
 
@@ -325,7 +381,7 @@ function EventopStep({
   const registry = useRegistry();
   const featureScope = useFeatureScope();
   const featureId = feature || featureScope;
-  const ref = useRef(null);
+  const wrapperRef = useRef(null);
   if (!featureId) {
     console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
   }
@@ -335,7 +391,14 @@ function EventopStep({
   const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
   const selector = `[${dataAttr}]`;
   useEffect(() => {
+    var _wrapperRef$current;
     if (!featureId || index == null) return;
+
+    // Inject attribute directly onto the first real child DOM element
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    }
     registry.registerStep(featureId, index, parentStep ?? null, {
       selector,
       waitFor: waitFor || null,
@@ -344,30 +407,21 @@ function EventopStep({
         ...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;
+    return () => {
+      var _wrapperRef$current2;
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterStep(featureId, index, parentStep ?? null);
+    };
+  }, [featureId, index, parentStep]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsx("span", {
+    ref: wrapperRef,
+    style: {
+      display: 'contents'
+    },
+    children: Children.only(children)
+  });
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

package/dist/react/index.cjs

@@ -29,18 +29,41 @@ function useFeatureScope() {
 /**
  * FeatureRegistry
  *
- * The live map of everything currently mounted in the React tree.
+ * The live map of everything registered in the React tree — both mounted
+ * (full entries) and unmounted (ghost entries).
  *
- * Features   — registered by EventopTarget
- * Flow steps — registered by EventopStep, attached to a feature by id
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  Full entry  — component is currently mounted                       │
+ * │  { id, name, description, route, selector, ... }                   │
+ * │                                                                     │
+ * │  Ghost entry — component has unmounted (navigated away)             │
+ * │  { id, name, description, route, selector: null, _ghost: true }    │
+ * └─────────────────────────────────────────────────────────────────────┘
  *
- * Both features and steps can live anywhere in the component tree.
- * They don't need to be co-located. An EventopStep just needs to know
- * which feature id it belongs to.
+ * Why ghosts?
+ *
+ *   The AI system prompt is built from the registry snapshot. Without ghosts,
+ *   features on other pages don't exist in the snapshot when the user is
+ *   elsewhere — the AI can't pick them, so cross-page tours never start.
+ *
+ *   With ghosts, every feature the app has ever rendered stays in the
+ *   snapshot permanently. The AI always has the full picture. The tour
+ *   runner already resolves selectors lazily (after navigation), so a
+ *   null selector on a ghost is fine — it gets filled in at show-time
+ *   once the component mounts on the target page.
+ *
+ * Lifecycle:
+ *
+ *   EventopTarget mounts   → registerFeature()  → full entry
+ *   EventopTarget unmounts → unregisterFeature() → ghost entry (metadata kept)
+ *   EventopTarget remounts → registerFeature()  → full entry again (selector restored)
+ *
+ * Flow steps follow the same pattern — they're pruned on unmount but the
+ * parent feature ghost keeps the feature visible to the AI.
  *
  * Nested steps:
- *   Steps can themselves have children steps (sub-steps) by passing
- *   a parentStep prop to EventopStep. This lets you model flows like:
+ *   Steps can have children steps (sub-steps) by passing a parentStep prop.
+ *   This lets you model flows like:
  *
  *   Feature: "Create styled text"
  *     Step 0: Click Add Text
@@ -49,17 +72,10 @@ function useFeatureScope() {
  *       Step 1.1: Open font picker       ← parentStep: 1, index: 1
  *       Step 1.2: Choose a font          ← parentStep: 1, index: 2
  *     Step 2: Click Done
- *
- *   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>
+  // Values are either full entries or ghost entries (_ghost: true)
   const features = new Map();
   // Map<featureId, Map<stepKey, stepData>>
   const flowSteps = new Map();
@@ -71,20 +87,37 @@ function createFeatureRegistry() {
   // ── Feature registration ─────────────────────────────────────────────────
 
   function registerFeature(feature) {
+    // Restore a ghost or create a fresh full entry.
+    // Always overwrite so a remount gets the latest selector.
     features.set(feature.id, {
       ...feature,
+      _ghost: false,
       _registeredAt: Date.now()
     });
     notify();
   }
   function unregisterFeature(id) {
+    if (!features.has(id)) return;
+
+    // Downgrade to ghost — keep all metadata, null out the live selector.
+    // Flow steps are pruned separately (their DOM elements are gone too).
+    const feature = features.get(id);
     features.set(id, {
-      ...existing,
+      id: feature.id,
+      name: feature.name,
+      description: feature.description,
+      route: feature.route || null,
+      navigate: feature.navigate || null,
+      navigateWaitFor: feature.navigateWaitFor || null,
+      _registeredAt: feature._registeredAt,
       selector: null,
       advanceOn: null,
       waitFor: null,
       _ghost: true
     });
+
+    // Prune flow steps — their selectors are dead too.
+    // They'll re-register when the component remounts on the target page.
     flowSteps.delete(id);
     notify();
   }
@@ -130,41 +163,62 @@ function createFeatureRegistry() {
   }
 
   /**
-   * Returns the live feature array in the format the SDK core expects.
+   * Returns the full feature array — both live and ghost entries.
    *
-   * `route` is now included in every feature entry so the core can detect
-   * when navigation is needed before showing a step.
+   * Ghost entries have selector: null. The SDK core handles this correctly:
+   *   - The AI system prompt uses name/description/route (always present)
+   *   - The tour runner resolves the selector lazily after navigation,
+   *     at which point the component has remounted and re-registered
+   *
+   * screen.check() returns false for ghosts so the SDK knows navigation
+   * is needed before showing the step.
    */
   function snapshot() {
     return Array.from(features.values()).map(feature => {
       const flow = buildFlow(feature.id);
+      const isGhost = feature._ghost === true;
       return {
         id: feature.id,
         name: feature.name,
         description: feature.description,
-        selector: feature.selector,
+        selector: feature.selector || null,
         route: feature.route || null,
         advanceOn: feature.advanceOn || null,
         waitFor: feature.waitFor || null,
+        _ghost: isGhost,
         ...(flow ? {
           flow
         } : {}),
         screen: {
           id: feature.id,
-          check: () => features.has(feature.id),
+          // Ghost entries always fail the check → SDK knows to navigate
+          check: () => {
+            var _features$get;
+            return ((_features$get = features.get(feature.id)) === null || _features$get === void 0 ? void 0 : _features$get._ghost) !== true;
+          },
           navigate: feature.navigate || null,
           waitFor: feature.navigateWaitFor || feature.selector || null
         }
       };
     });
   }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  /**
+   * Returns true only for fully mounted (non-ghost) features.
+   */
+  function isRegistered(id) {
+    const f = features.get(id);
+    return !!f && !f._ghost;
+  }
   return {
     registerFeature,
     unregisterFeature,
     registerStep,
     unregisterStep,
     snapshot,
-    isRegistered: id => features.has(id),
+    isRegistered,
     subscribe: fn => {
       listeners.add(fn);
       return () => listeners.delete(fn);
@@ -261,18 +315,28 @@ function EventopTarget({
   navigate,
   navigateWaitFor,
   advanceOn,
-  waitFor,
-  ...rest
+  waitFor
 }) {
   const registry = useRegistry();
-  const ref = react.useRef(null);
+  const wrapperRef = react.useRef(null);
   const dataAttr = `data-evtp-${id}`;
   const selector = `[${dataAttr}]`;
   react.useEffect(() => {
+    var _wrapperRef$current;
     if (!id || !name) {
       console.warn('[Eventop] <EventopTarget> requires id and name props.');
       return;
     }
+
+    // Set the attribute directly on the first real child DOM element.
+    // This bypasses React's prop system entirely — works regardless of whether
+    // the wrapped component forwards unknown props.
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    } else {
+      console.warn(`[Eventop] <EventopTarget id="${id}"> could not find a child DOM element to attach to. ` + `Make sure the wrapped component renders at least one DOM element.`);
+    }
     registry.registerFeature({
       id,
       name,
@@ -287,32 +351,24 @@ function EventopTarget({
         ...advanceOn
       } : null
     });
-    return () => registry.unregisterFeature(id);
-  }, [id, name, description, route]);
-  const child = react.Children.only(children);
-  let wrapped;
-  try {
-    wrapped = /*#__PURE__*/react.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__*/jsxRuntime.jsx("span", {
-      [dataAttr]: '',
-      ref: ref,
+    return () => {
+      var _wrapperRef$current2;
+      // Clean up the injected attribute on unmount
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterFeature(id);
+    };
+  }, [id, name, description, route]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsxRuntime.jsx(EventopFeatureScopeContext.Provider, {
+    value: id,
+    children: /*#__PURE__*/jsxRuntime.jsx("span", {
+      ref: wrapperRef,
       style: {
         display: 'contents'
       },
-      children: child
-    });
-  }
-  return /*#__PURE__*/jsxRuntime.jsx(EventopFeatureScopeContext.Provider, {
-    value: id,
-    children: wrapped
+      children: react.Children.only(children)
+    })
   });
 }
 
@@ -327,7 +383,7 @@ function EventopStep({
   const registry = useRegistry();
   const featureScope = useFeatureScope();
   const featureId = feature || featureScope;
-  const ref = react.useRef(null);
+  const wrapperRef = react.useRef(null);
   if (!featureId) {
     console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
   }
@@ -337,7 +393,14 @@ function EventopStep({
   const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
   const selector = `[${dataAttr}]`;
   react.useEffect(() => {
+    var _wrapperRef$current;
     if (!featureId || index == null) return;
+
+    // Inject attribute directly onto the first real child DOM element
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    }
     registry.registerStep(featureId, index, parentStep ?? null, {
       selector,
       waitFor: waitFor || null,
@@ -346,30 +409,21 @@ function EventopStep({
         ...advanceOn
       } : null
     });
-    return () => registry.unregisterStep(featureId, index, parentStep ?? null);
-  }, [featureId, index, parentStep]);
-  const child = react.Children.only(children);
-  let wrapped;
-  try {
-    wrapped = /*#__PURE__*/react.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__*/jsxRuntime.jsx("span", {
-      [dataAttr]: '',
-      ref: ref,
-      style: {
-        display: 'contents'
-      },
-      children: child
-    });
-  }
-  return wrapped;
+    return () => {
+      var _wrapperRef$current2;
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterStep(featureId, index, parentStep ?? null);
+    };
+  }, [featureId, index, parentStep]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsxRuntime.jsx("span", {
+    ref: wrapperRef,
+    style: {
+      display: 'contents'
+    },
+    children: react.Children.only(children)
+  });
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

package/dist/react/index.js

@@ -1,4 +1,4 @@
-import { createContext, useContext, useRef, useCallback, useEffect, Children, cloneElement, useState } from 'react';
+import { createContext, useContext, useRef, useCallback, useEffect, Children, useState } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 /**
@@ -27,18 +27,41 @@ function useFeatureScope() {
 /**
  * FeatureRegistry
  *
- * The live map of everything currently mounted in the React tree.
+ * The live map of everything registered in the React tree — both mounted
+ * (full entries) and unmounted (ghost entries).
  *
- * Features   — registered by EventopTarget
- * Flow steps — registered by EventopStep, attached to a feature by id
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  Full entry  — component is currently mounted                       │
+ * │  { id, name, description, route, selector, ... }                   │
+ * │                                                                     │
+ * │  Ghost entry — component has unmounted (navigated away)             │
+ * │  { id, name, description, route, selector: null, _ghost: true }    │
+ * └─────────────────────────────────────────────────────────────────────┘
  *
- * Both features and steps can live anywhere in the component tree.
- * They don't need to be co-located. An EventopStep just needs to know
- * which feature id it belongs to.
+ * Why ghosts?
+ *
+ *   The AI system prompt is built from the registry snapshot. Without ghosts,
+ *   features on other pages don't exist in the snapshot when the user is
+ *   elsewhere — the AI can't pick them, so cross-page tours never start.
+ *
+ *   With ghosts, every feature the app has ever rendered stays in the
+ *   snapshot permanently. The AI always has the full picture. The tour
+ *   runner already resolves selectors lazily (after navigation), so a
+ *   null selector on a ghost is fine — it gets filled in at show-time
+ *   once the component mounts on the target page.
+ *
+ * Lifecycle:
+ *
+ *   EventopTarget mounts   → registerFeature()  → full entry
+ *   EventopTarget unmounts → unregisterFeature() → ghost entry (metadata kept)
+ *   EventopTarget remounts → registerFeature()  → full entry again (selector restored)
+ *
+ * Flow steps follow the same pattern — they're pruned on unmount but the
+ * parent feature ghost keeps the feature visible to the AI.
  *
  * Nested steps:
- *   Steps can themselves have children steps (sub-steps) by passing
- *   a parentStep prop to EventopStep. This lets you model flows like:
+ *   Steps can have children steps (sub-steps) by passing a parentStep prop.
+ *   This lets you model flows like:
  *
  *   Feature: "Create styled text"
  *     Step 0: Click Add Text
@@ -47,17 +70,10 @@ function useFeatureScope() {
  *       Step 1.1: Open font picker       ← parentStep: 1, index: 1
  *       Step 1.2: Choose a font          ← parentStep: 1, index: 2
  *     Step 2: Click Done
- *
- *   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>
+  // Values are either full entries or ghost entries (_ghost: true)
   const features = new Map();
   // Map<featureId, Map<stepKey, stepData>>
   const flowSteps = new Map();
@@ -69,20 +85,37 @@ function createFeatureRegistry() {
   // ── Feature registration ─────────────────────────────────────────────────
 
   function registerFeature(feature) {
+    // Restore a ghost or create a fresh full entry.
+    // Always overwrite so a remount gets the latest selector.
     features.set(feature.id, {
       ...feature,
+      _ghost: false,
       _registeredAt: Date.now()
     });
     notify();
   }
   function unregisterFeature(id) {
+    if (!features.has(id)) return;
+
+    // Downgrade to ghost — keep all metadata, null out the live selector.
+    // Flow steps are pruned separately (their DOM elements are gone too).
+    const feature = features.get(id);
     features.set(id, {
-      ...existing,
+      id: feature.id,
+      name: feature.name,
+      description: feature.description,
+      route: feature.route || null,
+      navigate: feature.navigate || null,
+      navigateWaitFor: feature.navigateWaitFor || null,
+      _registeredAt: feature._registeredAt,
       selector: null,
       advanceOn: null,
       waitFor: null,
       _ghost: true
     });
+
+    // Prune flow steps — their selectors are dead too.
+    // They'll re-register when the component remounts on the target page.
     flowSteps.delete(id);
     notify();
   }
@@ -128,41 +161,62 @@ function createFeatureRegistry() {
   }
 
   /**
-   * Returns the live feature array in the format the SDK core expects.
+   * Returns the full feature array — both live and ghost entries.
    *
-   * `route` is now included in every feature entry so the core can detect
-   * when navigation is needed before showing a step.
+   * Ghost entries have selector: null. The SDK core handles this correctly:
+   *   - The AI system prompt uses name/description/route (always present)
+   *   - The tour runner resolves the selector lazily after navigation,
+   *     at which point the component has remounted and re-registered
+   *
+   * screen.check() returns false for ghosts so the SDK knows navigation
+   * is needed before showing the step.
    */
   function snapshot() {
     return Array.from(features.values()).map(feature => {
       const flow = buildFlow(feature.id);
+      const isGhost = feature._ghost === true;
       return {
         id: feature.id,
         name: feature.name,
         description: feature.description,
-        selector: feature.selector,
+        selector: feature.selector || null,
         route: feature.route || null,
         advanceOn: feature.advanceOn || null,
         waitFor: feature.waitFor || null,
+        _ghost: isGhost,
         ...(flow ? {
           flow
         } : {}),
         screen: {
           id: feature.id,
-          check: () => features.has(feature.id),
+          // Ghost entries always fail the check → SDK knows to navigate
+          check: () => {
+            var _features$get;
+            return ((_features$get = features.get(feature.id)) === null || _features$get === void 0 ? void 0 : _features$get._ghost) !== true;
+          },
           navigate: feature.navigate || null,
           waitFor: feature.navigateWaitFor || feature.selector || null
         }
       };
     });
   }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  /**
+   * Returns true only for fully mounted (non-ghost) features.
+   */
+  function isRegistered(id) {
+    const f = features.get(id);
+    return !!f && !f._ghost;
+  }
   return {
     registerFeature,
     unregisterFeature,
     registerStep,
     unregisterStep,
     snapshot,
-    isRegistered: id => features.has(id),
+    isRegistered,
     subscribe: fn => {
       listeners.add(fn);
       return () => listeners.delete(fn);
@@ -259,18 +313,28 @@ function EventopTarget({
   navigate,
   navigateWaitFor,
   advanceOn,
-  waitFor,
-  ...rest
+  waitFor
 }) {
   const registry = useRegistry();
-  const ref = useRef(null);
+  const wrapperRef = useRef(null);
   const dataAttr = `data-evtp-${id}`;
   const selector = `[${dataAttr}]`;
   useEffect(() => {
+    var _wrapperRef$current;
     if (!id || !name) {
       console.warn('[Eventop] <EventopTarget> requires id and name props.');
       return;
     }
+
+    // Set the attribute directly on the first real child DOM element.
+    // This bypasses React's prop system entirely — works regardless of whether
+    // the wrapped component forwards unknown props.
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    } else {
+      console.warn(`[Eventop] <EventopTarget id="${id}"> could not find a child DOM element to attach to. ` + `Make sure the wrapped component renders at least one DOM element.`);
+    }
     registry.registerFeature({
       id,
       name,
@@ -285,32 +349,24 @@ function EventopTarget({
         ...advanceOn
       } : null
     });
-    return () => registry.unregisterFeature(id);
-  }, [id, name, description, route]);
-  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,
+    return () => {
+      var _wrapperRef$current2;
+      // Clean up the injected attribute on unmount
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterFeature(id);
+    };
+  }, [id, name, description, route]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsx(EventopFeatureScopeContext.Provider, {
+    value: id,
+    children: /*#__PURE__*/jsx("span", {
+      ref: wrapperRef,
       style: {
         display: 'contents'
       },
-      children: child
-    });
-  }
-  return /*#__PURE__*/jsx(EventopFeatureScopeContext.Provider, {
-    value: id,
-    children: wrapped
+      children: Children.only(children)
+    })
   });
 }
 
@@ -325,7 +381,7 @@ function EventopStep({
   const registry = useRegistry();
   const featureScope = useFeatureScope();
   const featureId = feature || featureScope;
-  const ref = useRef(null);
+  const wrapperRef = useRef(null);
   if (!featureId) {
     console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
   }
@@ -335,7 +391,14 @@ function EventopStep({
   const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
   const selector = `[${dataAttr}]`;
   useEffect(() => {
+    var _wrapperRef$current;
     if (!featureId || index == null) return;
+
+    // Inject attribute directly onto the first real child DOM element
+    const firstChild = (_wrapperRef$current = wrapperRef.current) === null || _wrapperRef$current === void 0 ? void 0 : _wrapperRef$current.firstElementChild;
+    if (firstChild) {
+      firstChild.setAttribute(dataAttr, '');
+    }
     registry.registerStep(featureId, index, parentStep ?? null, {
       selector,
       waitFor: waitFor || null,
@@ -344,30 +407,21 @@ function EventopStep({
         ...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;
+    return () => {
+      var _wrapperRef$current2;
+      const el = (_wrapperRef$current2 = wrapperRef.current) === null || _wrapperRef$current2 === void 0 ? void 0 : _wrapperRef$current2.firstElementChild;
+      if (el) el.removeAttribute(dataAttr);
+      registry.unregisterStep(featureId, index, parentStep ?? null);
+    };
+  }, [featureId, index, parentStep]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/jsx("span", {
+    ref: wrapperRef,
+    style: {
+      display: 'contents'
+    },
+    children: Children.only(children)
+  });
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

package/package.json

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