@geminilight/mindos 0.6.52 → 0.6.53

package/_standalone/components/walkthrough/WalkthroughOverlay.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useEffect, useCallback, useId } from 'react';
 import { useLocale } from '@/lib/stores/locale-store';
-import { useWalkthrough } from '@/lib/stores/walkthrough-store';
+import { useWalkthrough, useWalkthroughStore } from '@/lib/stores/walkthrough-store';
 import { walkthroughSteps } from './steps';
 import WalkthroughTooltip from './WalkthroughTooltip';
 
@@ -68,16 +68,31 @@ export default function WalkthroughOverlay() {
     return () => window.removeEventListener('keydown', handler, true);
   }, [skipFn]);
 
-  // If target element doesn't exist (e.g. Echo not enabled), auto-skip this step
+  // If target element doesn't exist (e.g. panel not enabled), auto-skip
+  // after a grace period. Use stable store ref to avoid re-triggering on
+  // every store change (which caused spurious skips during step transitions).
+  const currentStep = wt?.currentStep ?? 0;
   useEffect(() => {
     if (!step) return;
-    const el = document.querySelector(`[data-walkthrough="${step.anchor}"]`);
-    if (!el) {
-      // Target not in DOM — skip to next step after a brief delay
-      const timer = setTimeout(() => wt?.next(), 100);
-      return () => clearTimeout(timer);
-    }
-  }, [step, wt]);
+    // Wait 500ms for DOM to settle (sidebar animations, lazy rendering)
+    const timer = setTimeout(() => {
+      const el = document.querySelector(`[data-walkthrough="${step.anchor}"]`);
+      if (!el) {
+        useWalkthroughStore.getState().next();
+      }
+    }, 500);
+    return () => clearTimeout(timer);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentStep]); // Only re-run when step index changes, not on every store update
+
+  // Safety timeout: if overlay stays for 60s without user interaction, auto-dismiss.
+  // Prevents permanently stuck overlay from any unforeseen edge case.
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      useWalkthroughStore.getState().skip();
+    }, 60_000);
+    return () => clearTimeout(timer);
+  }, [currentStep]); // Reset on each step change
 
   if (!wt || !step) return null;
 
@@ -138,7 +153,7 @@ export default function WalkthroughOverlay() {
         />
       </svg>
 
-      {/* Tooltip */}
+      {/* Tooltip — shown when target element found */}
       {targetRect && (
         <WalkthroughTooltip
           stepIndex={wt.currentStep}
@@ -146,6 +161,20 @@ export default function WalkthroughOverlay() {
           position={step.position}
         />
       )}
+
+      {/* Fallback dismiss button — shown when target element NOT found.
+          Without this, user sees dark overlay but no visible UI to dismiss it. */}
+      {!targetRect && (
+        <div className="fixed inset-0 z-[101] flex items-center justify-center pointer-events-none">
+          <button
+            onClick={wt.skip}
+            className="pointer-events-auto px-4 py-2 text-sm rounded-lg font-medium transition-all hover:opacity-90"
+            style={{ background: 'var(--amber)', color: 'var(--amber-foreground)' }}
+          >
+            {wt.currentStep === wt.totalSteps - 1 ? '✓' : '→'}
+          </button>
+        </div>
+      )}
     </>
   );
 }

package/_standalone/lib/stores/walkthrough-store.ts

@@ -21,7 +21,20 @@ export interface WalkthroughStoreState {
 
 /* ── Helpers ── */
 
+const LS_KEY = 'mindos_walkthrough_done';
+
+/**
+ * Persist walkthrough state to server AND localStorage.
+ * localStorage acts as a safety net: even if the server persist fails
+ * (e.g. during update restart, network blip), the completion state
+ * survives page reload and prevents the "stuck overlay" bug.
+ */
 function persistStep(step: number, dismissed: boolean) {
+  // Local safety net — instant, survives server outage
+  if (step >= walkthroughSteps.length || dismissed) {
+    try { localStorage.setItem(LS_KEY, '1'); } catch {}
+  }
+  // Server persist — fire-and-forget (localStorage is the safety net)
   fetch('/api/setup', {
     method: 'PATCH',
     headers: { 'Content-Type': 'application/json' },
@@ -31,6 +44,11 @@ function persistStep(step: number, dismissed: boolean) {
   }).catch((err) => { console.warn('[walkthrough-store] persist failed:', err); });
 }
 
+/** Check if walkthrough was completed/dismissed (fast, sync, local) */
+function isLocallyDone(): boolean {
+  try { return localStorage.getItem(LS_KEY) === '1'; } catch { return false; }
+}
+
 /* ── Store ── */
 
 export const useWalkthroughStore = create<WalkthroughStoreState>((set, get) => {
@@ -84,12 +102,26 @@ export const useWalkthroughStore = create<WalkthroughStoreState>((set, get) => {
       // Only auto-start on desktop
       if (window.innerWidth < 768) return () => {};
 
+      // Fast local check: if walkthrough was completed/dismissed, never reactivate.
+      // This prevents the "stuck overlay" bug where server persist failed during
+      // update restart but localStorage recorded the completion.
+      if (isLocallyDone()) return () => {};
+
       fetch('/api/setup')
         .then(r => r.json())
         .then(data => {
           const gs = data.guideState;
           if (!gs) return;
-          if (gs.walkthroughDismissed) return;
+          if (gs.walkthroughDismissed) {
+            try { localStorage.setItem(LS_KEY, '1'); } catch {} // sync local
+            return;
+          }
+
+          // If server says completed (step >= totalSteps), mark locally done
+          if (typeof gs.walkthroughStep === 'number' && gs.walkthroughStep >= totalSteps) {
+            try { localStorage.setItem(LS_KEY, '1'); } catch {};
+            return;
+          }
 
           if (gs.active && !gs.dismissed && gs.walkthroughStep === undefined) {
             if (isWelcome) {