@eventop/sdk 1.2.15 → 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};
@@ -1006,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';
 
@@ -1026,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 ────────────────────────────────────────────────────────
 
 /**
@@ -1059,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
@@ -1082,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;
       }
     }
@@ -1091,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');
+    }
   })();
 }
 
@@ -1139,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;
@@ -1156,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 => {
@@ -1224,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);
@@ -1240,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};
@@ -1004,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';
 
@@ -1024,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 ────────────────────────────────────────────────────────
 
 /**
@@ -1057,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
@@ -1080,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;
       }
     }
@@ -1089,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');
+    }
   })();
 }
 
@@ -1137,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;
@@ -1154,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 => {
@@ -1222,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);
@@ -1238,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};
@@ -1006,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';
 
@@ -1026,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 ────────────────────────────────────────────────────────
 
 /**
@@ -1059,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
@@ -1082,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;
       }
     }
@@ -1091,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');
+    }
   })();
 }
 
@@ -1139,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;
@@ -1156,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 => {
@@ -1224,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);
@@ -1240,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};
@@ -1004,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';
 
@@ -1024,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 ────────────────────────────────────────────────────────
 
 /**
@@ -1057,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
@@ -1080,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;
       }
     }
@@ -1089,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');
+    }
   })();
 }
 
@@ -1137,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;
@@ -1154,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 => {
@@ -1222,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);
@@ -1238,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.15",
+  "version": "1.3.0",
   "description": "AI-powered guided tours for any web app. Drop-in, themeable, provider-agnostic.",
   "keywords": [
     "onboarding",