@eventop/sdk 1.2.10 → 1.2.12

package/README.md

@@ -304,6 +304,33 @@ that lives on a different page.
 Features that share the page where tours are typically started don't need `route`.
 Only add it to features on other pages.
 
+### How the registry stays aware of every page
+
+When you navigate away from a page, its `EventopTarget` components unmount. Rather
+than removing them from the registry entirely, the SDK downgrades them to **ghost
+entries** — the metadata (`id`, `name`, `description`, `route`) is kept, only the
+live DOM selector is nulled out.
+
+```
+EventopTarget mounts   → full entry  { id, name, description, route, selector }
+EventopTarget unmounts → ghost entry { id, name, description, route, selector: null }
+EventopTarget remounts → full entry  (selector restored)
+```
+
+This means the AI system prompt always contains every feature the app has ever
+rendered, regardless of which page you're currently on. The AI can plan cross-page
+tours from any starting point without you doing anything extra.
+
+The selector is resolved lazily — after navigation completes and the target page's
+components remount, the ghost upgrades back to a full entry and the tour picks up
+the correct selector just before showing the step.
+
+> **Note on `id` stability** — ghost entries accumulate for the lifetime of the
+> session, so `id` should identify a **UI capability**, not a data record.
+> Wrapping dynamic list items with unique ids (e.g. `` `project-${p.id}` ``)
+> will create an unbounded number of ghosts. Use a single `EventopTarget` for
+> the repeating pattern instead.
+
 ---
 
 ## Multi-step flows

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,14 +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) {
-    features.delete(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, {
+      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();
   }
@@ -124,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);

package/dist/index.js

@@ -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,14 +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) {
-    features.delete(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, {
+      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();
   }
@@ -122,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);

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,14 +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) {
-    features.delete(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, {
+      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();
   }
@@ -124,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);

package/dist/react/index.js

@@ -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,14 +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) {
-    features.delete(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, {
+      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();
   }
@@ -122,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);

package/package.json

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