Fix preview-mode walkthrough after recent dashboard refactors

The 7-step walkthrough tour shown in preview mode (NEXT_PUBLIC_STACK_IS_PREVIEW)
had several silently-skipping steps after recent dashboard changes:

- Overview revamp (#1238) dropped the data-walkthrough hooks for the globe and
  metrics widgets — re-attach them to the new GlobeSectionWithData column and
  the AnalyticsChartWidget column in metrics-page.tsx.
- Session-replays/data-grid PR (#1424) renamed the anchor to "analytics-replays"
  and the sidebar nav was relabeled from "Session Replays" to "Replays" (under
  a collapsed Analytics group) — update the step id and sidebarNavLabel.
- The sidebar's collapsible-group expand button is now a <button aria-expanded>
  *nested inside* the prev-sibling header div, not the prev sibling itself —
  navigateViaSidebar's expansion logic only matched the prevSibling directly,
  so step 7 silently skipped. Look inside prevSibling for the chevron too.
- The cmdkSearch strings "Authentication" / "Emails" / "Payments" were
  matching the wrong CmdK result first (auth-methods / email-themes /
  payments/products/new) — tighten them to "Users" / "Emails sent" /
  "Products" so they land on the pages that actually have the spotlight
  anchors.
- Loop the walkthrough back to step 1 after step 7 instead of stopping; add
  sidebarNavLabel "Overview" to step 1 so the loop can navigate back from
  /session-replays.

Verified end-to-end in a real browser: all 7 spotlights render and the loop
continues indefinitely across iterations.

Author: BilalG1

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/(overview)/metrics-page.tsx

@@ -1234,7 +1234,7 @@ function MetricsContent({
         )}
       >
         {shouldShowGlobe && (
-          <div className={cn(
+          <div data-walkthrough="overview-globe" className={cn(
             "hidden lg:flex lg:col-span-5 h-full relative items-center justify-center overflow-hidden",
             "rounded-2xl bg-white/90 backdrop-blur-xl ring-1 ring-black/[0.06] shadow-sm",
             "dark:bg-transparent dark:backdrop-blur-none dark:ring-0 dark:shadow-none dark:rounded-none",
@@ -1256,7 +1256,7 @@ function MetricsContent({
           </div>
         )}
 
-        <div className={cn(
+        <div data-walkthrough="overview-metrics" className={cn(
           "h-full",
           shouldShowGlobe ? "lg:col-span-7" : "lg:col-span-12",
         )}>

apps/dashboard/src/components/walkthrough/walkthrough-provider.tsx

@@ -240,9 +240,17 @@ function WalkthroughEngine() {
             let el = link.parentElement;
             while (el && el.tagName !== 'ASIDE') {
               const prevSibling = el.previousElementSibling;
-              if (prevSibling?.tagName === 'BUTTON' && prevSibling.getAttribute('aria-expanded') === 'false') {
-                (prevSibling as HTMLElement).click();
-                break;
+              if (prevSibling) {
+                // The expand button may be the prevSibling itself, or nested
+                // inside it (the sidebar wraps the chevron toggle in a header
+                // div that also contains the section's main <a>).
+                const expandButton = (prevSibling.tagName === 'BUTTON' && prevSibling.getAttribute('aria-expanded') === 'false')
+                  ? prevSibling as HTMLElement
+                  : prevSibling.querySelector('button[aria-expanded="false"]') as HTMLElement | null;
+                if (expandButton) {
+                  expandButton.click();
+                  break;
+                }
               }
               el = el.parentElement;
             }
@@ -283,80 +291,78 @@ function WalkthroughEngine() {
     };
 
     const runWalkthrough = async () => {
-      for (let i = 0; i < WALKTHROUGH_STEPS.length; i++) {
-        if (isCancelled()) return;
-
-        const step = WALKTHROUGH_STEPS[i];
-        setStepIndex(i);
-        setShowSpotlight(false);
-
-        const needsNavigation = currentPathRef.current !== step.path;
-
-        // Phase 1: Navigate if needed
-        if (needsNavigation) {
-          let success = false;
-          if (step.cmdkSearch) {
-            success = await navigateViaCmdK(step.cmdkSearch);
-          } else if (step.sidebarNavLabel) {
-            success = await navigateViaSidebar(step.sidebarNavLabel);
-          }
+      while (!isCancelled()) {
+        for (let i = 0; i < WALKTHROUGH_STEPS.length; i++) {
           if (isCancelled()) return;
-          if (success) {
-            currentPathRef.current = step.path;
-            await sleep(300);
-            if (isCancelled()) return;
-          }
-        }
 
-        // Phase 2: Wait for target element
-        const targetEl = await waitForElement(`[data-walkthrough="${step.id}"]`);
-        if (isCancelled()) return;
-        if (!targetEl) continue;
+          const step = WALKTHROUGH_STEPS[i];
+          setStepIndex(i);
+          setShowSpotlight(false);
 
-        // Phase 3: Animate mouse to target element
-        const targetRect = targetEl.getBoundingClientRect();
-        setCursorPosition({
-          x: targetRect.left + targetRect.width / 2,
-          y: targetRect.top + targetRect.height / 2,
-        });
-        await sleep(600);
-        if (isCancelled()) return;
-
-        // Phase 4: Show spotlight
-        setSpotlightRect({
-          top: targetRect.top,
-          left: targetRect.left,
-          width: targetRect.width,
-          height: targetRect.height,
-        });
-        setShowSpotlight(true);
+          const needsNavigation = currentPathRef.current !== step.path;
 
-        // Continuously track element position
-        const trackElement = () => {
-          if (isCancelled()) return;
-          const el = document.querySelector(`[data-walkthrough="${step.id}"]`);
-          if (el) {
-            const rect = el.getBoundingClientRect();
-            setSpotlightRect({
-              top: rect.top,
-              left: rect.left,
-              width: rect.width,
-              height: rect.height,
-            });
+          // Phase 1: Navigate if needed
+          if (needsNavigation) {
+            let success = false;
+            if (step.cmdkSearch) {
+              success = await navigateViaCmdK(step.cmdkSearch);
+            } else if (step.sidebarNavLabel) {
+              success = await navigateViaSidebar(step.sidebarNavLabel);
+            }
+            if (isCancelled()) return;
+            if (success) {
+              currentPathRef.current = step.path;
+              await sleep(300);
+              if (isCancelled()) return;
+            }
           }
+
+          // Phase 2: Wait for target element
+          const targetEl = await waitForElement(`[data-walkthrough="${step.id}"]`);
+          if (isCancelled()) return;
+          if (!targetEl) continue;
+
+          // Phase 3: Animate mouse to target element
+          const targetRect = targetEl.getBoundingClientRect();
+          setCursorPosition({
+            x: targetRect.left + targetRect.width / 2,
+            y: targetRect.top + targetRect.height / 2,
+          });
+          await sleep(600);
+          if (isCancelled()) return;
+
+          // Phase 4: Show spotlight
+          setSpotlightRect({
+            top: targetRect.top,
+            left: targetRect.left,
+            width: targetRect.width,
+            height: targetRect.height,
+          });
+          setShowSpotlight(true);
+
+          // Continuously track element position
+          const trackElement = () => {
+            if (isCancelled()) return;
+            const el = document.querySelector(`[data-walkthrough="${step.id}"]`);
+            if (el) {
+              const rect = el.getBoundingClientRect();
+              setSpotlightRect({
+                top: rect.top,
+                left: rect.left,
+                width: rect.width,
+                height: rect.height,
+              });
+            }
+            rafRef.current = requestAnimationFrame(trackElement);
+          };
           rafRef.current = requestAnimationFrame(trackElement);
-        };
-        rafRef.current = requestAnimationFrame(trackElement);
 
-        // Phase 5: Wait at this step
-        await sleep(8000);
-        cancelAnimationFrame(rafRef.current);
-        if (isCancelled()) return;
+          // Phase 5: Wait at this step
+          await sleep(8000);
+          cancelAnimationFrame(rafRef.current);
+          if (isCancelled()) return;
+        }
       }
-
-      // Walkthrough complete
-      setShowSpotlight(false);
-      setIsRunning(false);
     };
 
     // eslint-disable-next-line @typescript-eslint/no-floating-promises

apps/dashboard/src/components/walkthrough/walkthrough-steps.ts

@@ -19,6 +19,7 @@ export const WALKTHROUGH_STEPS: WalkthroughStep[] = [
   {
     id: 'overview-globe',
     path: '/',
+    sidebarNavLabel: 'Overview',
     title: 'Global User Map',
     description: 'See where your users are around the world.',
     spotlightPadding: 12,
@@ -33,7 +34,7 @@ export const WALKTHROUGH_STEPS: WalkthroughStep[] = [
   {
     id: 'users-table',
     path: '/users',
-    cmdkSearch: 'Authentication',
+    cmdkSearch: 'Users',
     title: 'User Management',
     description: 'Manage all your users — search, export, or create new ones.',
   },
@@ -47,21 +48,21 @@ export const WALKTHROUGH_STEPS: WalkthroughStep[] = [
   {
     id: 'emails-sent',
     path: '/email-sent',
-    cmdkSearch: 'Emails',
+    cmdkSearch: 'Emails sent',
     title: 'Email Logs',
     description: 'Monitor sent emails, delivery status, and domain reputation.',
   },
   {
     id: 'payments-products',
     path: '/payments/products',
-    cmdkSearch: 'Payments',
+    cmdkSearch: 'Products',
     title: 'Products & Pricing',
     description: 'Define products, pricing, and subscriptions.',
   },
   {
-    id: 'session-replays',
+    id: 'analytics-replays',
     path: '/session-replays',
-    sidebarNavLabel: 'Session Replays',
+    sidebarNavLabel: 'Replays',
     title: 'Session Replays',
     description: 'Watch real user sessions to understand how people use your app.',
   },