@eventop/sdk 1.2.14 → 1.3.0

package/dist/core.cjs

@@ -221,6 +221,71 @@ function injectStyles(theme, pos) {
   style.textContent = `
     #sai-trigger, #sai-panel { ${buildCSSVars(theme)} }
 
+    /* ── Ring Light Animation ── */
+    @keyframes sai-ring-pulse {
+      0% {
+        box-shadow: 
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.7),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.5),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.3);
+      }
+      50% {
+        box-shadow: 
+          0 0 0 8px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0.3),
+          0 0 0 24px rgba(var(--sai-accent-rgb), 0);
+      }
+      100% {
+        box-shadow: 
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 32px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 48px rgba(var(--sai-accent-rgb), 0);
+      }
+    }
+
+    @keyframes sai-ring-pulse-hard {
+      0% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      50% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 8px var(--sai-accent),
+          0 0 40px var(--sai-accent);
+      }
+      100% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      }
+
+    @keyframes sai-element-highlight {
+      0% { filter: brightness(1); }
+      50% { filter: brightness(1.15); }
+      100% { filter: brightness(1); }
+    }
+
+    /* Highlighted element styles */
+    .sai-highlighted {
+      position: relative !important;
+      animation: sai-ring-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+      z-index: 99997 !important;
+    }
+
+    .sai-highlighted.sai-highlight-hard {
+      animation: sai-ring-pulse-hard 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+    }
+
+    .sai-highlighted.sai-highlight-subtle {
+      animation: sai-element-highlight 2s ease-in-out infinite !important;
+      filter: drop-shadow(0 0 8px var(--sai-accent)) !important;
+    }
+
     /* ── Trigger ── */
     #sai-trigger {
       position: fixed; ${triggerCSS};
@@ -486,13 +551,7 @@ function buildSystemPrompt(config) {
     var _f$screen;
     return (_f$screen = f.screen) === null || _f$screen === void 0 ? void 0 : _f$screen.id;
   }).map(f => f.screen.id))];
-
-  // Split features into live (current page) and ghost (other pages).
-  // This lets the AI understand what's immediately available vs reachable
-  // via navigation, and craft the right message when something isn't found.
-  const liveFeatures = (config.features || []).filter(f => !f._ghost);
-  const ghostFeatures = (config.features || []).filter(f => f._ghost);
-  const summarise = f => {
+  const featureSummary = (config.features || []).map(f => {
     var _f$screen2, _f$flow;
     const entry = {
       id: f.id,
@@ -507,18 +566,15 @@ function buildSystemPrompt(config) {
       entry.note = `This feature has ${f.flow.length} sequential sub-steps. Include ONE step per flow entry.`;
     }
     return entry;
-  };
-  const liveSection = liveFeatures.length ? `CURRENT PAGE FEATURES (user is here now):\n${JSON.stringify(liveFeatures.map(summarise), null, 2)}` : `CURRENT PAGE FEATURES: none registered yet.`;
-  const ghostSection = ghostFeatures.length ? `OTHER PAGE FEATURES (reachable via navigation — SDK handles it automatically):\n${JSON.stringify(ghostFeatures.map(summarise), null, 2)}` : '';
+  });
   return `
 You are an in-app assistant called "${config.assistantName || 'AI Guide'}" for "${config.appName}".
 Your ONLY job: guide users step-by-step through tasks using the feature map below.
 
-${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. The SDK navigates automatically — just pick the right feature id.` : ''}
-
-${liveSection}
+${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. Features are screen-specific. The SDK handles navigation — just pick the right features.` : ''}
 
-${ghostSection}
+FEATURE MAP (only reference IDs from this list):
+${JSON.stringify(featureSummary, null, 2)}
 
 RESPOND ONLY with this exact JSON — no markdown, no extra text:
 {
@@ -535,26 +591,16 @@ RESPOND ONLY with this exact JSON — no markdown, no extra text:
 }
 
 RULES:
-1. The step "id" MUST match a feature id from the current page or other page features above.
+1. The step "id" MUST match a feature id from the feature map.
 2. Only use selectors and IDs from the feature map. Never invent them.
-3. position values: top | bottom | left | right | auto only.
-4. Order steps logically. For multi-step flows, order as the user encounters them.
-5. For forms: ALWAYS include a step for the form section or first input BEFORE the
+3. No matching feature → steps: [], explain kindly in message.
+4. position values: top | bottom | left | right | auto only.
+5. Order steps logically. For multi-step flows, order as the user encounters them.
+6. For forms: ALWAYS include a step for the form section or first input BEFORE the
    continue/submit button. The button step must always be LAST in its section.
-6. If a feature has a flow, include one step per flow entry using the same feature id —
+7. If a feature has a flow, include one step per flow entry using the same feature id —
    the SDK expands them automatically.
-7. Never skip features in a required sequence. Include every step end-to-end.
-
-WHEN THE USER'S REQUEST DOESN'T MATCH ANY FEATURE:
-- If it partially matches something (e.g. they said "create template" and there's a
-  "template-gallery" feature): guide them to the closest matching feature and explain
-  what it does. Don't say you can't help.
-- If it matches a feature on another page (ghost): include that feature's steps normally.
-  The SDK will navigate there automatically. Do NOT tell the user to navigate manually.
-- If there is genuinely no match anywhere in the feature map: set steps to [] and say
-  something like "That doesn't seem to be a feature in ${config.appName} yet. Here's
-  what I can help you with:" then list 2-3 relevant features from the map by name.
-  Never say you "can only guide through available features" — always offer alternatives.
+8. Never skip features in a required sequence. Include every step end-to-end.
 `.trim();
 }
 
@@ -1025,6 +1071,7 @@ function expandFlowSteps(aiStep, feature) {
 
 // Loads Shepherd.js, builds + runs tours, wires up advanceOn listeners,
 // progress indicators, pause/resume, and step-level error display.
+// ENHANCED: Adds animated ring light effect to highlighted elements.
 
 const SHEPHERD_JS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/js/shepherd.min.js';
 
@@ -1045,6 +1092,61 @@ async function ensureShepherd() {
   await loadScript(SHEPHERD_JS);
 }
 
+// ─── Highlight management ────────────────────────────────────────────────────
+
+/**
+ * Applies the ring light animation to an element.
+ * 
+ * @param {HTMLElement} el 
+ * @param {string} [style='default'] - 'default' | 'hard' | 'subtle'
+ */
+function applyHighlight(el, style = 'default') {
+  if (!el) return;
+
+  // Set CSS variables for accent color parsing in RGB format
+  const accentColor = getComputedStyle(el).getPropertyValue('--sai-accent') || '#e94560';
+  const rgb = hexToRgb(accentColor.trim());
+  if (rgb) {
+    el.style.setProperty('--sai-accent-rgb', `${rgb.r}, ${rgb.g}, ${rgb.b}`);
+  }
+  el.classList.add('sai-highlighted');
+  if (style === 'hard') {
+    el.classList.add('sai-highlight-hard');
+  } else if (style === 'subtle') {
+    el.classList.add('sai-highlight-subtle');
+  }
+
+  // Scroll into view with extra padding
+  if (el.scrollIntoView) {
+    el.scrollIntoView({
+      behavior: 'smooth',
+      block: 'center'
+    });
+  }
+}
+
+/**
+ * Removes the ring light animation from an element.
+ */
+function removeHighlight(el) {
+  if (!el) return;
+  el.classList.remove('sai-highlighted', 'sai-highlight-hard', 'sai-highlight-subtle');
+}
+
+/**
+ * Converts hex color to RGB object.
+ * @param {string} hex 
+ * @returns {object|null}
+ */
+function hexToRgb(hex) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16)
+  } : null;
+}
+
 // ─── Feature-map merge ────────────────────────────────────────────────────────
 
 /**
@@ -1078,6 +1180,7 @@ function mergeWithFeature(step) {
  *   1. Cross-page navigation (route prop) with automatic waiting
  *   2. Legacy screen navigation (screen.navigate)
  *   3. Element waiting (waitFor prop)
+ *   4. Ring light animation application
  *
  * @param {object} step
  * @param {number} waitTimeout
@@ -1101,6 +1204,10 @@ function makeBeforeShowPromise(step, waitTimeout) {
           });
         } catch (_) {/* non-fatal */}
         await waitForElement(postNavMerge.selector, waitTimeout);
+
+        // Apply ring light animation to the element
+        const el = document.querySelector(postNavMerge.selector);
+        if (el) applyHighlight(el, step._highlightStyle || 'default');
         return;
       }
     }
@@ -1110,6 +1217,12 @@ function makeBeforeShowPromise(step, waitTimeout) {
     if (freshMerged.waitFor) {
       await waitForElement(freshMerged.waitFor, waitTimeout);
     }
+
+    // Apply ring light animation to the main selector
+    if (freshMerged.selector) {
+      const el = document.querySelector(freshMerged.selector);
+      if (el) applyHighlight(el, step._highlightStyle || 'default');
+    }
   })();
 }
 
@@ -1158,11 +1271,13 @@ function addProgressIndicator(shepherdStep, index, total) {
 
 /**
  * Starts a Shepherd tour from the given steps array.
+ * ENHANCED: Applies ring light animations to highlighted elements.
  *
  * @param {Array}  steps
  * @param {object} [options]
  * @param {boolean} [options.showProgress=true]
  * @param {number}  [options.waitTimeout=8000]
+ * @param {string}  [options.highlightStyle='default'] - 'default' | 'hard' | 'subtle'
  */
 async function runTour(steps, options = {}) {
   var _state$config2;
@@ -1175,9 +1290,13 @@ async function runTour(steps, options = {}) {
   if (!(steps !== null && steps !== void 0 && steps.length)) return;
   const {
     showProgress = true,
-    waitTimeout = 8000
+    waitTimeout = 8000,
+    highlightStyle = 'default'
   } = options;
-  const mergedSteps = steps.map(mergeWithFeature);
+  const mergedSteps = steps.map(step => ({
+    ...mergeWithFeature(step),
+    _highlightStyle: highlightStyle
+  }));
 
   // Legacy: navigate to the correct screen for the first step
   const firstFeature = (_state$config2 = config) === null || _state$config2 === void 0 || (_state$config2 = _state$config2.features) === null || _state$config2 === void 0 ? void 0 : _state$config2.find(f => {
@@ -1243,12 +1362,24 @@ async function runTour(steps, options = {}) {
     });
     step._shepherdRef = shepherdStep;
     shepherdStep._isLast = isLast;
+
+    // Clean up highlight on hide
+    shepherdStep.on('hide', () => {
+      if (step.selector) {
+        const el = document.querySelector(step.selector);
+        if (el) removeHighlight(el);
+      }
+    });
     if (hasAuto) wireAdvanceOn(shepherdStep, step.advanceOn, tour$1);
     if (showProgress && expandedSteps.length > 1) {
       addProgressIndicator(shepherdStep, i, expandedSteps.length);
     }
   });
   tour$1.on('complete', () => {
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(null);
     setPausedIndex(0);
@@ -1259,6 +1390,11 @@ async function runTour(steps, options = {}) {
   tour$1.on('cancel', () => {
     const currentStepEl = tour$1.getCurrentStep();
     const currentIdx = currentStepEl ? expandedSteps.findIndex(s => s.id === currentStepEl.id) : 0;
+
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(expandedSteps);
     setPausedIndex(Math.max(0, currentIdx));

package/dist/core.js

@@ -219,6 +219,71 @@ function injectStyles(theme, pos) {
   style.textContent = `
     #sai-trigger, #sai-panel { ${buildCSSVars(theme)} }
 
+    /* ── Ring Light Animation ── */
+    @keyframes sai-ring-pulse {
+      0% {
+        box-shadow: 
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.7),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.5),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.3);
+      }
+      50% {
+        box-shadow: 
+          0 0 0 8px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0.3),
+          0 0 0 24px rgba(var(--sai-accent-rgb), 0);
+      }
+      100% {
+        box-shadow: 
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 32px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 48px rgba(var(--sai-accent-rgb), 0);
+      }
+    }
+
+    @keyframes sai-ring-pulse-hard {
+      0% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      50% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 8px var(--sai-accent),
+          0 0 40px var(--sai-accent);
+      }
+      100% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      }
+
+    @keyframes sai-element-highlight {
+      0% { filter: brightness(1); }
+      50% { filter: brightness(1.15); }
+      100% { filter: brightness(1); }
+    }
+
+    /* Highlighted element styles */
+    .sai-highlighted {
+      position: relative !important;
+      animation: sai-ring-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+      z-index: 99997 !important;
+    }
+
+    .sai-highlighted.sai-highlight-hard {
+      animation: sai-ring-pulse-hard 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+    }
+
+    .sai-highlighted.sai-highlight-subtle {
+      animation: sai-element-highlight 2s ease-in-out infinite !important;
+      filter: drop-shadow(0 0 8px var(--sai-accent)) !important;
+    }
+
     /* ── Trigger ── */
     #sai-trigger {
       position: fixed; ${triggerCSS};
@@ -484,13 +549,7 @@ function buildSystemPrompt(config) {
     var _f$screen;
     return (_f$screen = f.screen) === null || _f$screen === void 0 ? void 0 : _f$screen.id;
   }).map(f => f.screen.id))];
-
-  // Split features into live (current page) and ghost (other pages).
-  // This lets the AI understand what's immediately available vs reachable
-  // via navigation, and craft the right message when something isn't found.
-  const liveFeatures = (config.features || []).filter(f => !f._ghost);
-  const ghostFeatures = (config.features || []).filter(f => f._ghost);
-  const summarise = f => {
+  const featureSummary = (config.features || []).map(f => {
     var _f$screen2, _f$flow;
     const entry = {
       id: f.id,
@@ -505,18 +564,15 @@ function buildSystemPrompt(config) {
       entry.note = `This feature has ${f.flow.length} sequential sub-steps. Include ONE step per flow entry.`;
     }
     return entry;
-  };
-  const liveSection = liveFeatures.length ? `CURRENT PAGE FEATURES (user is here now):\n${JSON.stringify(liveFeatures.map(summarise), null, 2)}` : `CURRENT PAGE FEATURES: none registered yet.`;
-  const ghostSection = ghostFeatures.length ? `OTHER PAGE FEATURES (reachable via navigation — SDK handles it automatically):\n${JSON.stringify(ghostFeatures.map(summarise), null, 2)}` : '';
+  });
   return `
 You are an in-app assistant called "${config.assistantName || 'AI Guide'}" for "${config.appName}".
 Your ONLY job: guide users step-by-step through tasks using the feature map below.
 
-${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. The SDK navigates automatically — just pick the right feature id.` : ''}
-
-${liveSection}
+${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. Features are screen-specific. The SDK handles navigation — just pick the right features.` : ''}
 
-${ghostSection}
+FEATURE MAP (only reference IDs from this list):
+${JSON.stringify(featureSummary, null, 2)}
 
 RESPOND ONLY with this exact JSON — no markdown, no extra text:
 {
@@ -533,26 +589,16 @@ RESPOND ONLY with this exact JSON — no markdown, no extra text:
 }
 
 RULES:
-1. The step "id" MUST match a feature id from the current page or other page features above.
+1. The step "id" MUST match a feature id from the feature map.
 2. Only use selectors and IDs from the feature map. Never invent them.
-3. position values: top | bottom | left | right | auto only.
-4. Order steps logically. For multi-step flows, order as the user encounters them.
-5. For forms: ALWAYS include a step for the form section or first input BEFORE the
+3. No matching feature → steps: [], explain kindly in message.
+4. position values: top | bottom | left | right | auto only.
+5. Order steps logically. For multi-step flows, order as the user encounters them.
+6. For forms: ALWAYS include a step for the form section or first input BEFORE the
    continue/submit button. The button step must always be LAST in its section.
-6. If a feature has a flow, include one step per flow entry using the same feature id —
+7. If a feature has a flow, include one step per flow entry using the same feature id —
    the SDK expands them automatically.
-7. Never skip features in a required sequence. Include every step end-to-end.
-
-WHEN THE USER'S REQUEST DOESN'T MATCH ANY FEATURE:
-- If it partially matches something (e.g. they said "create template" and there's a
-  "template-gallery" feature): guide them to the closest matching feature and explain
-  what it does. Don't say you can't help.
-- If it matches a feature on another page (ghost): include that feature's steps normally.
-  The SDK will navigate there automatically. Do NOT tell the user to navigate manually.
-- If there is genuinely no match anywhere in the feature map: set steps to [] and say
-  something like "That doesn't seem to be a feature in ${config.appName} yet. Here's
-  what I can help you with:" then list 2-3 relevant features from the map by name.
-  Never say you "can only guide through available features" — always offer alternatives.
+8. Never skip features in a required sequence. Include every step end-to-end.
 `.trim();
 }
 
@@ -1023,6 +1069,7 @@ function expandFlowSteps(aiStep, feature) {
 
 // Loads Shepherd.js, builds + runs tours, wires up advanceOn listeners,
 // progress indicators, pause/resume, and step-level error display.
+// ENHANCED: Adds animated ring light effect to highlighted elements.
 
 const SHEPHERD_JS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/js/shepherd.min.js';
 
@@ -1043,6 +1090,61 @@ async function ensureShepherd() {
   await loadScript(SHEPHERD_JS);
 }
 
+// ─── Highlight management ────────────────────────────────────────────────────
+
+/**
+ * Applies the ring light animation to an element.
+ * 
+ * @param {HTMLElement} el 
+ * @param {string} [style='default'] - 'default' | 'hard' | 'subtle'
+ */
+function applyHighlight(el, style = 'default') {
+  if (!el) return;
+
+  // Set CSS variables for accent color parsing in RGB format
+  const accentColor = getComputedStyle(el).getPropertyValue('--sai-accent') || '#e94560';
+  const rgb = hexToRgb(accentColor.trim());
+  if (rgb) {
+    el.style.setProperty('--sai-accent-rgb', `${rgb.r}, ${rgb.g}, ${rgb.b}`);
+  }
+  el.classList.add('sai-highlighted');
+  if (style === 'hard') {
+    el.classList.add('sai-highlight-hard');
+  } else if (style === 'subtle') {
+    el.classList.add('sai-highlight-subtle');
+  }
+
+  // Scroll into view with extra padding
+  if (el.scrollIntoView) {
+    el.scrollIntoView({
+      behavior: 'smooth',
+      block: 'center'
+    });
+  }
+}
+
+/**
+ * Removes the ring light animation from an element.
+ */
+function removeHighlight(el) {
+  if (!el) return;
+  el.classList.remove('sai-highlighted', 'sai-highlight-hard', 'sai-highlight-subtle');
+}
+
+/**
+ * Converts hex color to RGB object.
+ * @param {string} hex 
+ * @returns {object|null}
+ */
+function hexToRgb(hex) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16)
+  } : null;
+}
+
 // ─── Feature-map merge ────────────────────────────────────────────────────────
 
 /**
@@ -1076,6 +1178,7 @@ function mergeWithFeature(step) {
  *   1. Cross-page navigation (route prop) with automatic waiting
  *   2. Legacy screen navigation (screen.navigate)
  *   3. Element waiting (waitFor prop)
+ *   4. Ring light animation application
  *
  * @param {object} step
  * @param {number} waitTimeout
@@ -1099,6 +1202,10 @@ function makeBeforeShowPromise(step, waitTimeout) {
           });
         } catch (_) {/* non-fatal */}
         await waitForElement(postNavMerge.selector, waitTimeout);
+
+        // Apply ring light animation to the element
+        const el = document.querySelector(postNavMerge.selector);
+        if (el) applyHighlight(el, step._highlightStyle || 'default');
         return;
       }
     }
@@ -1108,6 +1215,12 @@ function makeBeforeShowPromise(step, waitTimeout) {
     if (freshMerged.waitFor) {
       await waitForElement(freshMerged.waitFor, waitTimeout);
     }
+
+    // Apply ring light animation to the main selector
+    if (freshMerged.selector) {
+      const el = document.querySelector(freshMerged.selector);
+      if (el) applyHighlight(el, step._highlightStyle || 'default');
+    }
   })();
 }
 
@@ -1156,11 +1269,13 @@ function addProgressIndicator(shepherdStep, index, total) {
 
 /**
  * Starts a Shepherd tour from the given steps array.
+ * ENHANCED: Applies ring light animations to highlighted elements.
  *
  * @param {Array}  steps
  * @param {object} [options]
  * @param {boolean} [options.showProgress=true]
  * @param {number}  [options.waitTimeout=8000]
+ * @param {string}  [options.highlightStyle='default'] - 'default' | 'hard' | 'subtle'
  */
 async function runTour(steps, options = {}) {
   var _state$config2;
@@ -1173,9 +1288,13 @@ async function runTour(steps, options = {}) {
   if (!(steps !== null && steps !== void 0 && steps.length)) return;
   const {
     showProgress = true,
-    waitTimeout = 8000
+    waitTimeout = 8000,
+    highlightStyle = 'default'
   } = options;
-  const mergedSteps = steps.map(mergeWithFeature);
+  const mergedSteps = steps.map(step => ({
+    ...mergeWithFeature(step),
+    _highlightStyle: highlightStyle
+  }));
 
   // Legacy: navigate to the correct screen for the first step
   const firstFeature = (_state$config2 = config) === null || _state$config2 === void 0 || (_state$config2 = _state$config2.features) === null || _state$config2 === void 0 ? void 0 : _state$config2.find(f => {
@@ -1241,12 +1360,24 @@ async function runTour(steps, options = {}) {
     });
     step._shepherdRef = shepherdStep;
     shepherdStep._isLast = isLast;
+
+    // Clean up highlight on hide
+    shepherdStep.on('hide', () => {
+      if (step.selector) {
+        const el = document.querySelector(step.selector);
+        if (el) removeHighlight(el);
+      }
+    });
     if (hasAuto) wireAdvanceOn(shepherdStep, step.advanceOn, tour$1);
     if (showProgress && expandedSteps.length > 1) {
       addProgressIndicator(shepherdStep, i, expandedSteps.length);
     }
   });
   tour$1.on('complete', () => {
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(null);
     setPausedIndex(0);
@@ -1257,6 +1388,11 @@ async function runTour(steps, options = {}) {
   tour$1.on('cancel', () => {
     const currentStepEl = tour$1.getCurrentStep();
     const currentIdx = currentStepEl ? expandedSteps.findIndex(s => s.id === currentStepEl.id) : 0;
+
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(expandedSteps);
     setPausedIndex(Math.max(0, currentIdx));

package/dist/react/core.cjs

@@ -221,6 +221,71 @@ function injectStyles(theme, pos) {
   style.textContent = `
     #sai-trigger, #sai-panel { ${buildCSSVars(theme)} }
 
+    /* ── Ring Light Animation ── */
+    @keyframes sai-ring-pulse {
+      0% {
+        box-shadow: 
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.7),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.5),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.3);
+      }
+      50% {
+        box-shadow: 
+          0 0 0 8px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0.3),
+          0 0 0 24px rgba(var(--sai-accent-rgb), 0);
+      }
+      100% {
+        box-shadow: 
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 32px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 48px rgba(var(--sai-accent-rgb), 0);
+      }
+    }
+
+    @keyframes sai-ring-pulse-hard {
+      0% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      50% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 8px var(--sai-accent),
+          0 0 40px var(--sai-accent);
+      }
+      100% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      }
+
+    @keyframes sai-element-highlight {
+      0% { filter: brightness(1); }
+      50% { filter: brightness(1.15); }
+      100% { filter: brightness(1); }
+    }
+
+    /* Highlighted element styles */
+    .sai-highlighted {
+      position: relative !important;
+      animation: sai-ring-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+      z-index: 99997 !important;
+    }
+
+    .sai-highlighted.sai-highlight-hard {
+      animation: sai-ring-pulse-hard 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+    }
+
+    .sai-highlighted.sai-highlight-subtle {
+      animation: sai-element-highlight 2s ease-in-out infinite !important;
+      filter: drop-shadow(0 0 8px var(--sai-accent)) !important;
+    }
+
     /* ── Trigger ── */
     #sai-trigger {
       position: fixed; ${triggerCSS};
@@ -486,13 +551,7 @@ function buildSystemPrompt(config) {
     var _f$screen;
     return (_f$screen = f.screen) === null || _f$screen === void 0 ? void 0 : _f$screen.id;
   }).map(f => f.screen.id))];
-
-  // Split features into live (current page) and ghost (other pages).
-  // This lets the AI understand what's immediately available vs reachable
-  // via navigation, and craft the right message when something isn't found.
-  const liveFeatures = (config.features || []).filter(f => !f._ghost);
-  const ghostFeatures = (config.features || []).filter(f => f._ghost);
-  const summarise = f => {
+  const featureSummary = (config.features || []).map(f => {
     var _f$screen2, _f$flow;
     const entry = {
       id: f.id,
@@ -507,18 +566,15 @@ function buildSystemPrompt(config) {
       entry.note = `This feature has ${f.flow.length} sequential sub-steps. Include ONE step per flow entry.`;
     }
     return entry;
-  };
-  const liveSection = liveFeatures.length ? `CURRENT PAGE FEATURES (user is here now):\n${JSON.stringify(liveFeatures.map(summarise), null, 2)}` : `CURRENT PAGE FEATURES: none registered yet.`;
-  const ghostSection = ghostFeatures.length ? `OTHER PAGE FEATURES (reachable via navigation — SDK handles it automatically):\n${JSON.stringify(ghostFeatures.map(summarise), null, 2)}` : '';
+  });
   return `
 You are an in-app assistant called "${config.assistantName || 'AI Guide'}" for "${config.appName}".
 Your ONLY job: guide users step-by-step through tasks using the feature map below.
 
-${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. The SDK navigates automatically — just pick the right feature id.` : ''}
-
-${liveSection}
+${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. Features are screen-specific. The SDK handles navigation — just pick the right features.` : ''}
 
-${ghostSection}
+FEATURE MAP (only reference IDs from this list):
+${JSON.stringify(featureSummary, null, 2)}
 
 RESPOND ONLY with this exact JSON — no markdown, no extra text:
 {
@@ -535,26 +591,16 @@ RESPOND ONLY with this exact JSON — no markdown, no extra text:
 }
 
 RULES:
-1. The step "id" MUST match a feature id from the current page or other page features above.
+1. The step "id" MUST match a feature id from the feature map.
 2. Only use selectors and IDs from the feature map. Never invent them.
-3. position values: top | bottom | left | right | auto only.
-4. Order steps logically. For multi-step flows, order as the user encounters them.
-5. For forms: ALWAYS include a step for the form section or first input BEFORE the
+3. No matching feature → steps: [], explain kindly in message.
+4. position values: top | bottom | left | right | auto only.
+5. Order steps logically. For multi-step flows, order as the user encounters them.
+6. For forms: ALWAYS include a step for the form section or first input BEFORE the
    continue/submit button. The button step must always be LAST in its section.
-6. If a feature has a flow, include one step per flow entry using the same feature id —
+7. If a feature has a flow, include one step per flow entry using the same feature id —
    the SDK expands them automatically.
-7. Never skip features in a required sequence. Include every step end-to-end.
-
-WHEN THE USER'S REQUEST DOESN'T MATCH ANY FEATURE:
-- If it partially matches something (e.g. they said "create template" and there's a
-  "template-gallery" feature): guide them to the closest matching feature and explain
-  what it does. Don't say you can't help.
-- If it matches a feature on another page (ghost): include that feature's steps normally.
-  The SDK will navigate there automatically. Do NOT tell the user to navigate manually.
-- If there is genuinely no match anywhere in the feature map: set steps to [] and say
-  something like "That doesn't seem to be a feature in ${config.appName} yet. Here's
-  what I can help you with:" then list 2-3 relevant features from the map by name.
-  Never say you "can only guide through available features" — always offer alternatives.
+8. Never skip features in a required sequence. Include every step end-to-end.
 `.trim();
 }
 
@@ -1025,6 +1071,7 @@ function expandFlowSteps(aiStep, feature) {
 
 // Loads Shepherd.js, builds + runs tours, wires up advanceOn listeners,
 // progress indicators, pause/resume, and step-level error display.
+// ENHANCED: Adds animated ring light effect to highlighted elements.
 
 const SHEPHERD_JS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/js/shepherd.min.js';
 
@@ -1045,6 +1092,61 @@ async function ensureShepherd() {
   await loadScript(SHEPHERD_JS);
 }
 
+// ─── Highlight management ────────────────────────────────────────────────────
+
+/**
+ * Applies the ring light animation to an element.
+ * 
+ * @param {HTMLElement} el 
+ * @param {string} [style='default'] - 'default' | 'hard' | 'subtle'
+ */
+function applyHighlight(el, style = 'default') {
+  if (!el) return;
+
+  // Set CSS variables for accent color parsing in RGB format
+  const accentColor = getComputedStyle(el).getPropertyValue('--sai-accent') || '#e94560';
+  const rgb = hexToRgb(accentColor.trim());
+  if (rgb) {
+    el.style.setProperty('--sai-accent-rgb', `${rgb.r}, ${rgb.g}, ${rgb.b}`);
+  }
+  el.classList.add('sai-highlighted');
+  if (style === 'hard') {
+    el.classList.add('sai-highlight-hard');
+  } else if (style === 'subtle') {
+    el.classList.add('sai-highlight-subtle');
+  }
+
+  // Scroll into view with extra padding
+  if (el.scrollIntoView) {
+    el.scrollIntoView({
+      behavior: 'smooth',
+      block: 'center'
+    });
+  }
+}
+
+/**
+ * Removes the ring light animation from an element.
+ */
+function removeHighlight(el) {
+  if (!el) return;
+  el.classList.remove('sai-highlighted', 'sai-highlight-hard', 'sai-highlight-subtle');
+}
+
+/**
+ * Converts hex color to RGB object.
+ * @param {string} hex 
+ * @returns {object|null}
+ */
+function hexToRgb(hex) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16)
+  } : null;
+}
+
 // ─── Feature-map merge ────────────────────────────────────────────────────────
 
 /**
@@ -1078,6 +1180,7 @@ function mergeWithFeature(step) {
  *   1. Cross-page navigation (route prop) with automatic waiting
  *   2. Legacy screen navigation (screen.navigate)
  *   3. Element waiting (waitFor prop)
+ *   4. Ring light animation application
  *
  * @param {object} step
  * @param {number} waitTimeout
@@ -1101,6 +1204,10 @@ function makeBeforeShowPromise(step, waitTimeout) {
           });
         } catch (_) {/* non-fatal */}
         await waitForElement(postNavMerge.selector, waitTimeout);
+
+        // Apply ring light animation to the element
+        const el = document.querySelector(postNavMerge.selector);
+        if (el) applyHighlight(el, step._highlightStyle || 'default');
         return;
       }
     }
@@ -1110,6 +1217,12 @@ function makeBeforeShowPromise(step, waitTimeout) {
     if (freshMerged.waitFor) {
       await waitForElement(freshMerged.waitFor, waitTimeout);
     }
+
+    // Apply ring light animation to the main selector
+    if (freshMerged.selector) {
+      const el = document.querySelector(freshMerged.selector);
+      if (el) applyHighlight(el, step._highlightStyle || 'default');
+    }
   })();
 }
 
@@ -1158,11 +1271,13 @@ function addProgressIndicator(shepherdStep, index, total) {
 
 /**
  * Starts a Shepherd tour from the given steps array.
+ * ENHANCED: Applies ring light animations to highlighted elements.
  *
  * @param {Array}  steps
  * @param {object} [options]
  * @param {boolean} [options.showProgress=true]
  * @param {number}  [options.waitTimeout=8000]
+ * @param {string}  [options.highlightStyle='default'] - 'default' | 'hard' | 'subtle'
  */
 async function runTour(steps, options = {}) {
   var _state$config2;
@@ -1175,9 +1290,13 @@ async function runTour(steps, options = {}) {
   if (!(steps !== null && steps !== void 0 && steps.length)) return;
   const {
     showProgress = true,
-    waitTimeout = 8000
+    waitTimeout = 8000,
+    highlightStyle = 'default'
   } = options;
-  const mergedSteps = steps.map(mergeWithFeature);
+  const mergedSteps = steps.map(step => ({
+    ...mergeWithFeature(step),
+    _highlightStyle: highlightStyle
+  }));
 
   // Legacy: navigate to the correct screen for the first step
   const firstFeature = (_state$config2 = config) === null || _state$config2 === void 0 || (_state$config2 = _state$config2.features) === null || _state$config2 === void 0 ? void 0 : _state$config2.find(f => {
@@ -1243,12 +1362,24 @@ async function runTour(steps, options = {}) {
     });
     step._shepherdRef = shepherdStep;
     shepherdStep._isLast = isLast;
+
+    // Clean up highlight on hide
+    shepherdStep.on('hide', () => {
+      if (step.selector) {
+        const el = document.querySelector(step.selector);
+        if (el) removeHighlight(el);
+      }
+    });
     if (hasAuto) wireAdvanceOn(shepherdStep, step.advanceOn, tour$1);
     if (showProgress && expandedSteps.length > 1) {
       addProgressIndicator(shepherdStep, i, expandedSteps.length);
     }
   });
   tour$1.on('complete', () => {
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(null);
     setPausedIndex(0);
@@ -1259,6 +1390,11 @@ async function runTour(steps, options = {}) {
   tour$1.on('cancel', () => {
     const currentStepEl = tour$1.getCurrentStep();
     const currentIdx = currentStepEl ? expandedSteps.findIndex(s => s.id === currentStepEl.id) : 0;
+
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(expandedSteps);
     setPausedIndex(Math.max(0, currentIdx));

package/dist/react/core.js

@@ -219,6 +219,71 @@ function injectStyles(theme, pos) {
   style.textContent = `
     #sai-trigger, #sai-panel { ${buildCSSVars(theme)} }
 
+    /* ── Ring Light Animation ── */
+    @keyframes sai-ring-pulse {
+      0% {
+        box-shadow: 
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.7),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.5),
+          0 0 0 0 rgba(var(--sai-accent-rgb), 0.3);
+      }
+      50% {
+        box-shadow: 
+          0 0 0 8px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0.3),
+          0 0 0 24px rgba(var(--sai-accent-rgb), 0);
+      }
+      100% {
+        box-shadow: 
+          0 0 0 16px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 32px rgba(var(--sai-accent-rgb), 0),
+          0 0 0 48px rgba(var(--sai-accent-rgb), 0);
+      }
+    }
+
+    @keyframes sai-ring-pulse-hard {
+      0% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      50% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 8px var(--sai-accent),
+          0 0 40px var(--sai-accent);
+      }
+      100% {
+        box-shadow: 
+          inset 0 0 0 2px var(--sai-accent),
+          0 0 0 3px var(--sai-accent),
+          0 0 20px var(--sai-accent);
+      }
+      }
+
+    @keyframes sai-element-highlight {
+      0% { filter: brightness(1); }
+      50% { filter: brightness(1.15); }
+      100% { filter: brightness(1); }
+    }
+
+    /* Highlighted element styles */
+    .sai-highlighted {
+      position: relative !important;
+      animation: sai-ring-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+      z-index: 99997 !important;
+    }
+
+    .sai-highlighted.sai-highlight-hard {
+      animation: sai-ring-pulse-hard 2s cubic-bezier(0.4, 0, 0.6, 1) infinite !important;
+    }
+
+    .sai-highlighted.sai-highlight-subtle {
+      animation: sai-element-highlight 2s ease-in-out infinite !important;
+      filter: drop-shadow(0 0 8px var(--sai-accent)) !important;
+    }
+
     /* ── Trigger ── */
     #sai-trigger {
       position: fixed; ${triggerCSS};
@@ -484,13 +549,7 @@ function buildSystemPrompt(config) {
     var _f$screen;
     return (_f$screen = f.screen) === null || _f$screen === void 0 ? void 0 : _f$screen.id;
   }).map(f => f.screen.id))];
-
-  // Split features into live (current page) and ghost (other pages).
-  // This lets the AI understand what's immediately available vs reachable
-  // via navigation, and craft the right message when something isn't found.
-  const liveFeatures = (config.features || []).filter(f => !f._ghost);
-  const ghostFeatures = (config.features || []).filter(f => f._ghost);
-  const summarise = f => {
+  const featureSummary = (config.features || []).map(f => {
     var _f$screen2, _f$flow;
     const entry = {
       id: f.id,
@@ -505,18 +564,15 @@ function buildSystemPrompt(config) {
       entry.note = `This feature has ${f.flow.length} sequential sub-steps. Include ONE step per flow entry.`;
     }
     return entry;
-  };
-  const liveSection = liveFeatures.length ? `CURRENT PAGE FEATURES (user is here now):\n${JSON.stringify(liveFeatures.map(summarise), null, 2)}` : `CURRENT PAGE FEATURES: none registered yet.`;
-  const ghostSection = ghostFeatures.length ? `OTHER PAGE FEATURES (reachable via navigation — SDK handles it automatically):\n${JSON.stringify(ghostFeatures.map(summarise), null, 2)}` : '';
+  });
   return `
 You are an in-app assistant called "${config.assistantName || 'AI Guide'}" for "${config.appName}".
 Your ONLY job: guide users step-by-step through tasks using the feature map below.
 
-${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. The SDK navigates automatically — just pick the right feature id.` : ''}
-
-${liveSection}
+${screens.length > 1 ? `SCREENS: This app has multiple screens: ${screens.join(', ')}. Features are screen-specific. The SDK handles navigation — just pick the right features.` : ''}
 
-${ghostSection}
+FEATURE MAP (only reference IDs from this list):
+${JSON.stringify(featureSummary, null, 2)}
 
 RESPOND ONLY with this exact JSON — no markdown, no extra text:
 {
@@ -533,26 +589,16 @@ RESPOND ONLY with this exact JSON — no markdown, no extra text:
 }
 
 RULES:
-1. The step "id" MUST match a feature id from the current page or other page features above.
+1. The step "id" MUST match a feature id from the feature map.
 2. Only use selectors and IDs from the feature map. Never invent them.
-3. position values: top | bottom | left | right | auto only.
-4. Order steps logically. For multi-step flows, order as the user encounters them.
-5. For forms: ALWAYS include a step for the form section or first input BEFORE the
+3. No matching feature → steps: [], explain kindly in message.
+4. position values: top | bottom | left | right | auto only.
+5. Order steps logically. For multi-step flows, order as the user encounters them.
+6. For forms: ALWAYS include a step for the form section or first input BEFORE the
    continue/submit button. The button step must always be LAST in its section.
-6. If a feature has a flow, include one step per flow entry using the same feature id —
+7. If a feature has a flow, include one step per flow entry using the same feature id —
    the SDK expands them automatically.
-7. Never skip features in a required sequence. Include every step end-to-end.
-
-WHEN THE USER'S REQUEST DOESN'T MATCH ANY FEATURE:
-- If it partially matches something (e.g. they said "create template" and there's a
-  "template-gallery" feature): guide them to the closest matching feature and explain
-  what it does. Don't say you can't help.
-- If it matches a feature on another page (ghost): include that feature's steps normally.
-  The SDK will navigate there automatically. Do NOT tell the user to navigate manually.
-- If there is genuinely no match anywhere in the feature map: set steps to [] and say
-  something like "That doesn't seem to be a feature in ${config.appName} yet. Here's
-  what I can help you with:" then list 2-3 relevant features from the map by name.
-  Never say you "can only guide through available features" — always offer alternatives.
+8. Never skip features in a required sequence. Include every step end-to-end.
 `.trim();
 }
 
@@ -1023,6 +1069,7 @@ function expandFlowSteps(aiStep, feature) {
 
 // Loads Shepherd.js, builds + runs tours, wires up advanceOn listeners,
 // progress indicators, pause/resume, and step-level error display.
+// ENHANCED: Adds animated ring light effect to highlighted elements.
 
 const SHEPHERD_JS = 'https://cdn.jsdelivr.net/npm/shepherd.js@11.2.0/dist/js/shepherd.min.js';
 
@@ -1043,6 +1090,61 @@ async function ensureShepherd() {
   await loadScript(SHEPHERD_JS);
 }
 
+// ─── Highlight management ────────────────────────────────────────────────────
+
+/**
+ * Applies the ring light animation to an element.
+ * 
+ * @param {HTMLElement} el 
+ * @param {string} [style='default'] - 'default' | 'hard' | 'subtle'
+ */
+function applyHighlight(el, style = 'default') {
+  if (!el) return;
+
+  // Set CSS variables for accent color parsing in RGB format
+  const accentColor = getComputedStyle(el).getPropertyValue('--sai-accent') || '#e94560';
+  const rgb = hexToRgb(accentColor.trim());
+  if (rgb) {
+    el.style.setProperty('--sai-accent-rgb', `${rgb.r}, ${rgb.g}, ${rgb.b}`);
+  }
+  el.classList.add('sai-highlighted');
+  if (style === 'hard') {
+    el.classList.add('sai-highlight-hard');
+  } else if (style === 'subtle') {
+    el.classList.add('sai-highlight-subtle');
+  }
+
+  // Scroll into view with extra padding
+  if (el.scrollIntoView) {
+    el.scrollIntoView({
+      behavior: 'smooth',
+      block: 'center'
+    });
+  }
+}
+
+/**
+ * Removes the ring light animation from an element.
+ */
+function removeHighlight(el) {
+  if (!el) return;
+  el.classList.remove('sai-highlighted', 'sai-highlight-hard', 'sai-highlight-subtle');
+}
+
+/**
+ * Converts hex color to RGB object.
+ * @param {string} hex 
+ * @returns {object|null}
+ */
+function hexToRgb(hex) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16)
+  } : null;
+}
+
 // ─── Feature-map merge ────────────────────────────────────────────────────────
 
 /**
@@ -1076,6 +1178,7 @@ function mergeWithFeature(step) {
  *   1. Cross-page navigation (route prop) with automatic waiting
  *   2. Legacy screen navigation (screen.navigate)
  *   3. Element waiting (waitFor prop)
+ *   4. Ring light animation application
  *
  * @param {object} step
  * @param {number} waitTimeout
@@ -1099,6 +1202,10 @@ function makeBeforeShowPromise(step, waitTimeout) {
           });
         } catch (_) {/* non-fatal */}
         await waitForElement(postNavMerge.selector, waitTimeout);
+
+        // Apply ring light animation to the element
+        const el = document.querySelector(postNavMerge.selector);
+        if (el) applyHighlight(el, step._highlightStyle || 'default');
         return;
       }
     }
@@ -1108,6 +1215,12 @@ function makeBeforeShowPromise(step, waitTimeout) {
     if (freshMerged.waitFor) {
       await waitForElement(freshMerged.waitFor, waitTimeout);
     }
+
+    // Apply ring light animation to the main selector
+    if (freshMerged.selector) {
+      const el = document.querySelector(freshMerged.selector);
+      if (el) applyHighlight(el, step._highlightStyle || 'default');
+    }
   })();
 }
 
@@ -1156,11 +1269,13 @@ function addProgressIndicator(shepherdStep, index, total) {
 
 /**
  * Starts a Shepherd tour from the given steps array.
+ * ENHANCED: Applies ring light animations to highlighted elements.
  *
  * @param {Array}  steps
  * @param {object} [options]
  * @param {boolean} [options.showProgress=true]
  * @param {number}  [options.waitTimeout=8000]
+ * @param {string}  [options.highlightStyle='default'] - 'default' | 'hard' | 'subtle'
  */
 async function runTour(steps, options = {}) {
   var _state$config2;
@@ -1173,9 +1288,13 @@ async function runTour(steps, options = {}) {
   if (!(steps !== null && steps !== void 0 && steps.length)) return;
   const {
     showProgress = true,
-    waitTimeout = 8000
+    waitTimeout = 8000,
+    highlightStyle = 'default'
   } = options;
-  const mergedSteps = steps.map(mergeWithFeature);
+  const mergedSteps = steps.map(step => ({
+    ...mergeWithFeature(step),
+    _highlightStyle: highlightStyle
+  }));
 
   // Legacy: navigate to the correct screen for the first step
   const firstFeature = (_state$config2 = config) === null || _state$config2 === void 0 || (_state$config2 = _state$config2.features) === null || _state$config2 === void 0 ? void 0 : _state$config2.find(f => {
@@ -1241,12 +1360,24 @@ async function runTour(steps, options = {}) {
     });
     step._shepherdRef = shepherdStep;
     shepherdStep._isLast = isLast;
+
+    // Clean up highlight on hide
+    shepherdStep.on('hide', () => {
+      if (step.selector) {
+        const el = document.querySelector(step.selector);
+        if (el) removeHighlight(el);
+      }
+    });
     if (hasAuto) wireAdvanceOn(shepherdStep, step.advanceOn, tour$1);
     if (showProgress && expandedSteps.length > 1) {
       addProgressIndicator(shepherdStep, i, expandedSteps.length);
     }
   });
   tour$1.on('complete', () => {
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(null);
     setPausedIndex(0);
@@ -1257,6 +1388,11 @@ async function runTour(steps, options = {}) {
   tour$1.on('cancel', () => {
     const currentStepEl = tour$1.getCurrentStep();
     const currentIdx = currentStepEl ? expandedSteps.findIndex(s => s.id === currentStepEl.id) : 0;
+
+    // Clean up all highlights
+    document.querySelectorAll('.sai-highlighted').forEach(el => {
+      removeHighlight(el);
+    });
     runAndClearCleanups();
     setPausedSteps(expandedSteps);
     setPausedIndex(Math.max(0, currentIdx));

package/package.json

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