@geminilight/mindos 0.5.28 → 0.5.30

package/app/components/walkthrough/WalkthroughOverlay.tsx

@@ -0,0 +1,224 @@
+'use client';
+
+import { useState, useEffect, useCallback, useId } from 'react';
+import { useLocale } from '@/lib/LocaleContext';
+import { useWalkthrough } from './WalkthroughProvider';
+import { walkthroughSteps } from './steps';
+import WalkthroughTooltip from './WalkthroughTooltip';
+
+/**
+ * Full-screen overlay with SVG spotlight mask.
+ * Finds the target element via data-walkthrough attribute, measures it,
+ * and cuts a transparent rect into the semi-transparent overlay.
+ */
+export default function WalkthroughOverlay() {
+  const wt = useWalkthrough();
+  const [targetRect, setTargetRect] = useState<DOMRect | null>(null);
+  const [isMobile, setIsMobile] = useState(false);
+  const maskId = useId();
+
+  const step = wt ? walkthroughSteps[wt.currentStep] : null;
+
+  const measureTarget = useCallback(() => {
+    if (!step) return;
+    const el = document.querySelector(`[data-walkthrough="${step.anchor}"]`);
+    if (el) {
+      setTargetRect(el.getBoundingClientRect());
+    } else {
+      setTargetRect(null);
+    }
+  }, [step]);
+
+  useEffect(() => {
+    setIsMobile(window.innerWidth < 768);
+    measureTarget();
+
+    const handleResize = () => {
+      setIsMobile(window.innerWidth < 768);
+      measureTarget();
+    };
+
+    window.addEventListener('resize', handleResize);
+    window.addEventListener('scroll', measureTarget, true);
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      window.removeEventListener('scroll', measureTarget, true);
+    };
+  }, [measureTarget]);
+
+  // Re-measure when step changes
+  useEffect(() => {
+    measureTarget();
+    // Slight delay to account for animations
+    const timer = setTimeout(measureTarget, 100);
+    return () => clearTimeout(timer);
+  }, [wt?.currentStep, measureTarget]);
+
+  // ESC to dismiss — depend on skip only, not the entire context object
+  const skipFn = wt?.skip;
+  useEffect(() => {
+    if (!skipFn) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        skipFn();
+      }
+    };
+    window.addEventListener('keydown', handler, true);
+    return () => window.removeEventListener('keydown', handler, true);
+  }, [skipFn]);
+
+  if (!wt || !step) return null;
+
+  // Mobile: bottom sheet instead of spotlight
+  if (isMobile) {
+    return <MobileWalkthroughSheet />;
+  }
+
+  const PAD = 6; // padding around spotlight rect
+  const RADIUS = 8;
+
+  return (
+    <>
+      {/* SVG overlay with spotlight hole */}
+      <svg
+        className="fixed inset-0 z-[100] pointer-events-auto"
+        width="100%"
+        height="100%"
+        onClick={(e) => {
+          // Click outside spotlight → skip
+          if (targetRect) {
+            const x = e.clientX;
+            const y = e.clientY;
+            const inSpotlight =
+              x >= targetRect.left - PAD &&
+              x <= targetRect.right + PAD &&
+              y >= targetRect.top - PAD &&
+              y <= targetRect.bottom + PAD;
+            if (!inSpotlight) {
+              wt.skip();
+            }
+          }
+        }}
+      >
+        <defs>
+          <mask id={maskId}>
+            <rect width="100%" height="100%" fill="white" />
+            {targetRect && (
+              <rect
+                x={targetRect.left - PAD}
+                y={targetRect.top - PAD}
+                width={targetRect.width + PAD * 2}
+                height={targetRect.height + PAD * 2}
+                rx={RADIUS}
+                ry={RADIUS}
+                fill="black"
+              />
+            )}
+          </mask>
+        </defs>
+        <rect
+          width="100%"
+          height="100%"
+          fill="rgba(0, 0, 0, 0.5)"
+          mask={`url(#${maskId})`}
+        />
+      </svg>
+
+      {/* Tooltip */}
+      {targetRect && (
+        <WalkthroughTooltip
+          stepIndex={wt.currentStep}
+          rect={targetRect}
+          position={step.position}
+        />
+      )}
+    </>
+  );
+}
+
+/** Mobile fallback: bottom sheet card */
+function MobileWalkthroughSheet() {
+  const wt = useWalkthrough();
+  const { t } = useLocale();
+
+  if (!wt) return null;
+
+  const stepData = t.walkthrough.steps[wt.currentStep] as { title: string; body: string } | undefined;
+  if (!stepData) return null;
+
+  return (
+    <>
+      {/* Backdrop */}
+      <div
+        className="fixed inset-0 z-[100] bg-black/40 backdrop-blur-sm"
+        onClick={wt.skip}
+      />
+      {/* Bottom sheet */}
+      <div
+        className="fixed bottom-0 left-0 right-0 z-[101] rounded-t-2xl border-t shadow-lg p-5 pb-8 animate-in slide-in-from-bottom duration-300"
+        style={{ background: 'var(--card)', borderColor: 'var(--border)' }}
+      >
+        {/* Step counter */}
+        <div className="flex items-center gap-2 mb-3">
+          <span
+            className="text-2xs font-mono px-1.5 py-0.5 rounded-full"
+            style={{ background: 'var(--amber-dim)', color: 'var(--amber)' }}
+          >
+            {t.walkthrough.step(wt.currentStep + 1, wt.totalSteps)}
+          </span>
+          {/* Progress dots */}
+          <div className="flex items-center gap-1 ml-auto">
+            {Array.from({ length: wt.totalSteps }, (_, i) => (
+              <div
+                key={i}
+                className="w-1.5 h-1.5 rounded-full"
+                style={{
+                  background: i === wt.currentStep ? 'var(--amber)' : 'var(--border)',
+                }}
+              />
+            ))}
+          </div>
+        </div>
+
+        <h3
+          className="text-base font-semibold font-display mb-1"
+          style={{ color: 'var(--foreground)' }}
+        >
+          {stepData.title}
+        </h3>
+        <p className="text-sm leading-relaxed mb-5" style={{ color: 'var(--muted-foreground)' }}>
+          {stepData.body}
+        </p>
+
+        <div className="flex items-center justify-between">
+          <button
+            onClick={wt.skip}
+            className="text-sm transition-colors hover:opacity-80"
+            style={{ color: 'var(--muted-foreground)' }}
+          >
+            {t.walkthrough.skip}
+          </button>
+          <div className="flex items-center gap-2">
+            {wt.currentStep > 0 && (
+              <button
+                onClick={wt.back}
+                className="text-sm px-3 py-2 rounded-lg transition-colors hover:bg-muted"
+                style={{ color: 'var(--muted-foreground)' }}
+              >
+                {t.walkthrough.back}
+              </button>
+            )}
+            <button
+              onClick={wt.next}
+              className="text-sm px-4 py-2 rounded-lg font-medium transition-all hover:opacity-90"
+              style={{ background: 'var(--amber)', color: 'var(--amber-foreground)' }}
+            >
+              {wt.currentStep === wt.totalSteps - 1 ? t.walkthrough.done : t.walkthrough.next}
+            </button>
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}

package/app/components/walkthrough/WalkthroughProvider.tsx

@@ -0,0 +1,133 @@
+'use client';
+
+import { createContext, useContext, useState, useCallback, useEffect, type ReactNode } from 'react';
+import { walkthroughSteps } from './steps';
+import WalkthroughOverlay from './WalkthroughOverlay';
+
+type WalkthroughStatus = 'idle' | 'active' | 'completed' | 'dismissed';
+
+interface WalkthroughContextValue {
+  status: WalkthroughStatus;
+  currentStep: number;
+  totalSteps: number;
+  start: () => void;
+  next: () => void;
+  back: () => void;
+  skip: () => void;
+}
+
+const WalkthroughContext = createContext<WalkthroughContextValue | null>(null);
+
+export function useWalkthrough() {
+  return useContext(WalkthroughContext);
+}
+
+interface WalkthroughProviderProps {
+  children: ReactNode;
+}
+
+export default function WalkthroughProvider({ children }: WalkthroughProviderProps) {
+  const [status, setStatus] = useState<WalkthroughStatus>('idle');
+  const [currentStep, setCurrentStep] = useState(0);
+  const totalSteps = walkthroughSteps.length;
+
+  // Persist to backend
+  const persistStep = useCallback((step: number, dismissed: boolean) => {
+    fetch('/api/setup', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        guideState: {
+          walkthroughStep: step,
+          walkthroughDismissed: dismissed,
+        },
+      }),
+    }).catch(() => {});
+  }, []);
+
+  // Check for auto-start via ?welcome=1 or guideState
+  useEffect(() => {
+    // Handle ?welcome=1 URL param — single owner, clean up immediately
+    const params = new URLSearchParams(window.location.search);
+    const isWelcome = params.get('welcome') === '1';
+    if (isWelcome) {
+      const url = new URL(window.location.href);
+      url.searchParams.delete('welcome');
+      window.history.replaceState({}, '', url.pathname + (url.search || ''));
+      // Notify GuideCard about first visit
+      window.dispatchEvent(new Event('mindos:first-visit'));
+    }
+
+    // Only auto-start walkthrough on desktop
+    if (window.innerWidth < 768) return;
+
+    fetch('/api/setup')
+      .then(r => r.json())
+      .then(data => {
+        const gs = data.guideState;
+        if (!gs) return;
+        // Already dismissed or completed
+        if (gs.walkthroughDismissed) return;
+        // Check if walkthrough should start
+        if (gs.active && !gs.dismissed && gs.walkthroughStep === undefined) {
+          // First time — only start if ?welcome=1 was present
+          if (isWelcome) {
+            setStatus('active');
+            setCurrentStep(0);
+          }
+        } else if (typeof gs.walkthroughStep === 'number' && gs.walkthroughStep >= 0 && gs.walkthroughStep < totalSteps && !gs.walkthroughDismissed) {
+          // Resume walkthrough
+          setStatus('active');
+          setCurrentStep(gs.walkthroughStep);
+        }
+      })
+      .catch(() => {});
+  }, [totalSteps]);
+
+  const start = useCallback(() => {
+    setCurrentStep(0);
+    setStatus('active');
+    persistStep(0, false);
+  }, [persistStep]);
+
+  const next = useCallback(() => {
+    const nextStep = currentStep + 1;
+    if (nextStep >= totalSteps) {
+      setStatus('completed');
+      persistStep(totalSteps, false);
+    } else {
+      setCurrentStep(nextStep);
+      persistStep(nextStep, false);
+    }
+  }, [currentStep, totalSteps, persistStep]);
+
+  const back = useCallback(() => {
+    if (currentStep > 0) {
+      const prevStep = currentStep - 1;
+      setCurrentStep(prevStep);
+      persistStep(prevStep, false);
+    }
+  }, [currentStep, persistStep]);
+
+  const skip = useCallback(() => {
+    setStatus('dismissed');
+    persistStep(currentStep, true);
+  }, [currentStep, persistStep]);
+
+  const value: WalkthroughContextValue = {
+    status,
+    currentStep,
+    totalSteps,
+    start,
+    next,
+    back,
+    skip,
+  };
+
+  return (
+    <WalkthroughContext.Provider value={value}>
+      {children}
+      {status === 'active' && <WalkthroughOverlay />}
+    </WalkthroughContext.Provider>
+  );
+}

package/app/components/walkthrough/WalkthroughTooltip.tsx

@@ -0,0 +1,129 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useLocale } from '@/lib/LocaleContext';
+import { useWalkthrough } from './WalkthroughProvider';
+
+interface WalkthroughTooltipProps {
+  stepIndex: number;
+  rect: DOMRect;
+  position: 'right' | 'bottom';
+}
+
+export default function WalkthroughTooltip({ stepIndex, rect, position }: WalkthroughTooltipProps) {
+  const wt = useWalkthrough();
+  const { t } = useLocale();
+
+  // Track viewport dimensions in state to avoid stale values and SSR hazard
+  const [viewport, setViewport] = useState({ width: 1024, height: 768 });
+  useEffect(() => {
+    const update = () => setViewport({ width: window.innerWidth, height: window.innerHeight });
+    update();
+    window.addEventListener('resize', update);
+    return () => window.removeEventListener('resize', update);
+  }, []);
+
+  if (!wt) return null;
+
+  const stepData = t.walkthrough.steps[stepIndex] as { title: string; body: string } | undefined;
+  if (!stepData) return null;
+
+  // Calculate tooltip position
+  const GAP = 12;
+  let top: number;
+  let left: number;
+
+  if (position === 'right') {
+    top = rect.top + rect.height / 2;
+    left = rect.right + GAP;
+  } else {
+    top = rect.bottom + GAP;
+    left = rect.left + rect.width / 2;
+  }
+
+  // Clamp to viewport
+  const maxLeft = viewport.width - 320;
+  const maxTop = viewport.height - 200;
+  left = Math.min(left, maxLeft);
+  top = Math.min(top, maxTop);
+  top = Math.max(top, 8);
+
+  return (
+    <div
+      className="fixed z-[102] w-[280px] rounded-xl border shadow-lg animate-in fade-in slide-in-from-left-2 duration-200"
+      style={{
+        top: `${top}px`,
+        left: `${left}px`,
+        transform: position === 'right' ? 'translateY(-50%)' : 'translateX(-50%)',
+        background: 'var(--card)',
+        borderColor: 'var(--amber)',
+      }}
+    >
+      <div className="p-4">
+        {/* Step indicator */}
+        <div className="flex items-center gap-2 mb-2">
+          <span
+            className="text-2xs font-mono px-1.5 py-0.5 rounded-full"
+            style={{ background: 'var(--amber-dim)', color: 'var(--amber)' }}
+          >
+            {t.walkthrough.step(stepIndex + 1, wt.totalSteps)}
+          </span>
+        </div>
+
+        {/* Content */}
+        <h3
+          className="text-sm font-semibold font-display mb-1"
+          style={{ color: 'var(--foreground)' }}
+        >
+          {stepData.title}
+        </h3>
+        <p className="text-xs leading-relaxed" style={{ color: 'var(--muted-foreground)' }}>
+          {stepData.body}
+        </p>
+
+        {/* Actions */}
+        <div className="flex items-center justify-between mt-4 pt-3" style={{ borderTop: '1px solid var(--border)' }}>
+          <button
+            onClick={wt.skip}
+            className="text-xs transition-colors hover:opacity-80"
+            style={{ color: 'var(--muted-foreground)' }}
+          >
+            {t.walkthrough.skip}
+          </button>
+          <div className="flex items-center gap-2">
+            {stepIndex > 0 && (
+              <button
+                onClick={wt.back}
+                className="text-xs px-2.5 py-1 rounded-lg transition-colors hover:bg-muted"
+                style={{ color: 'var(--muted-foreground)' }}
+              >
+                {t.walkthrough.back}
+              </button>
+            )}
+            <button
+              onClick={wt.next}
+              className="text-xs px-3 py-1.5 rounded-lg font-medium transition-all hover:opacity-90"
+              style={{ background: 'var(--amber)', color: 'var(--amber-foreground)' }}
+            >
+              {stepIndex === wt.totalSteps - 1 ? t.walkthrough.done : t.walkthrough.next}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Progress dots */}
+      <div className="flex items-center justify-center gap-1.5 pb-3">
+        {Array.from({ length: wt.totalSteps }, (_, i) => (
+          <div
+            key={i}
+            className="w-1.5 h-1.5 rounded-full transition-all duration-200"
+            style={{
+              background: i === stepIndex ? 'var(--amber)' : 'var(--border)',
+              transform: i === stepIndex ? 'scale(1.3)' : undefined,
+            }}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/app/components/walkthrough/index.ts

@@ -0,0 +1,3 @@
+export { default as WalkthroughProvider, useWalkthrough } from './WalkthroughProvider';
+export { walkthroughSteps } from './steps';
+export type { WalkthroughAnchor } from './steps';

package/app/components/walkthrough/steps.ts

@@ -0,0 +1,21 @@
+/** Walkthrough step anchors — these data-walkthrough attributes are added to target components */
+export type WalkthroughAnchor =
+  | 'activity-bar'
+  | 'files-panel'
+  | 'ask-button'
+  | 'search-button'
+  | 'settings-button';
+
+export interface WalkthroughStep {
+  anchor: WalkthroughAnchor;
+  /** Preferred tooltip position relative to anchor */
+  position: 'right' | 'bottom';
+}
+
+export const walkthroughSteps: WalkthroughStep[] = [
+  { anchor: 'activity-bar', position: 'right' },
+  { anchor: 'files-panel', position: 'right' },
+  { anchor: 'ask-button', position: 'right' },
+  { anchor: 'search-button', position: 'right' },
+  { anchor: 'settings-button', position: 'right' },
+];

package/app/hooks/useMcpData.tsx

@@ -0,0 +1,166 @@
+'use client';
+
+import { createContext, useContext, useState, useCallback, useEffect, useMemo, useRef, type ReactNode } from 'react';
+import { apiFetch } from '@/lib/api';
+import type { McpStatus, AgentInfo, SkillInfo } from '@/components/settings/types';
+
+/* ── Context shape ── */
+
+export interface McpContextValue {
+  status: McpStatus | null;
+  agents: AgentInfo[];
+  skills: SkillInfo[];
+  loading: boolean;
+  refresh: () => Promise<void>;
+  toggleSkill: (name: string, enabled: boolean) => Promise<void>;
+  installAgent: (key: string, opts?: { scope?: string; transport?: string }) => Promise<boolean>;
+}
+
+const McpContext = createContext<McpContextValue | null>(null);
+
+export function useMcpData(): McpContextValue {
+  const ctx = useContext(McpContext);
+  if (!ctx) throw new Error('useMcpData must be used within McpProvider');
+  return ctx;
+}
+
+/** Optional hook that returns null outside provider (for components that may or may not be wrapped) */
+export function useMcpDataOptional(): McpContextValue | null {
+  return useContext(McpContext);
+}
+
+/* ── Provider ── */
+
+const POLL_INTERVAL = 30_000;
+
+export default function McpProvider({ children }: { children: ReactNode }) {
+  const [status, setStatus] = useState<McpStatus | null>(null);
+  const [agents, setAgents] = useState<AgentInfo[]>([]);
+  const [skills, setSkills] = useState<SkillInfo[]>([]);
+  const [loading, setLoading] = useState(true);
+  const abortRef = useRef<AbortController | null>(null);
+  // Ref for agents to avoid stale closure in installAgent
+  const agentsRef = useRef(agents);
+  agentsRef.current = agents;
+
+  const fetchAll = useCallback(async () => {
+    // Abort any in-flight request to prevent race conditions
+    abortRef.current?.abort();
+    const ac = new AbortController();
+    abortRef.current = ac;
+
+    try {
+      const [statusData, agentsData, skillsData] = await Promise.all([
+        apiFetch<McpStatus>('/api/mcp/status', { signal: ac.signal }),
+        apiFetch<{ agents: AgentInfo[] }>('/api/mcp/agents', { signal: ac.signal }),
+        apiFetch<{ skills: SkillInfo[] }>('/api/skills', { signal: ac.signal }),
+      ]);
+      if (!ac.signal.aborted) {
+        setStatus(statusData);
+        setAgents(agentsData.agents);
+        setSkills(skillsData.skills);
+      }
+    } catch (err: unknown) {
+      // Ignore abort errors
+      if (err instanceof DOMException && err.name === 'AbortError') return;
+      // On error, keep existing data
+    } finally {
+      if (!ac.signal.aborted) setLoading(false);
+    }
+  }, []);
+
+  // Initial fetch
+  useEffect(() => {
+    fetchAll();
+    return () => abortRef.current?.abort();
+  }, [fetchAll]);
+
+  // Listen for skill changes from SkillsSection (settings CRUD — create/delete/edit)
+  // Debounce to coalesce rapid mutations into a single refresh
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const handler = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => fetchAll(), 500);
+    };
+    window.addEventListener('mindos:skills-changed', handler);
+    return () => {
+      clearTimeout(timer);
+      window.removeEventListener('mindos:skills-changed', handler);
+    };
+  }, [fetchAll]);
+
+  // 30s polling when visible
+  useEffect(() => {
+    let timer: ReturnType<typeof setInterval> | undefined;
+
+    const startPolling = () => {
+      timer = setInterval(() => {
+        if (document.visibilityState === 'visible') fetchAll();
+      }, POLL_INTERVAL);
+    };
+
+    startPolling();
+    return () => clearInterval(timer);
+  }, [fetchAll]);
+
+  const refresh = useCallback(async () => {
+    await fetchAll();
+  }, [fetchAll]);
+
+  const toggleSkill = useCallback(async (name: string, enabled: boolean) => {
+    // Optimistic update
+    setSkills(prev => prev.map(s => s.name === name ? { ...s, enabled } : s));
+    try {
+      await apiFetch('/api/skills', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action: 'toggle', name, enabled }),
+      });
+    } catch {
+      // Revert on failure
+      setSkills(prev => prev.map(s => s.name === name ? { ...s, enabled: !enabled } : s));
+    }
+  }, []);
+
+  const installAgent = useCallback(async (key: string, opts?: { scope?: string; transport?: string }): Promise<boolean> => {
+    const agent = agentsRef.current.find(a => a.key === key);
+    if (!agent) return false;
+
+    try {
+      const res = await apiFetch<{ results: Array<{ key: string; ok: boolean; error?: string }> }>('/api/mcp/install', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          agents: [{
+            key,
+            scope: opts?.scope ?? (agent.hasProjectScope ? 'project' : 'global'),
+            transport: opts?.transport ?? agent.preferredTransport,
+          }],
+          transport: 'auto',
+        }),
+      });
+
+      const ok = res.results?.[0]?.ok ?? false;
+      if (ok) {
+        // Refresh to pick up newly installed agent
+        await fetchAll();
+      }
+      return ok;
+    } catch {
+      return false;
+    }
+  }, [fetchAll]);
+
+  const value = useMemo<McpContextValue>(() => ({
+    status,
+    agents,
+    skills,
+    loading,
+    refresh,
+    toggleSkill,
+    installAgent,
+  }), [status, agents, skills, loading, refresh, toggleSkill, installAgent]);
+
+  return <McpContext.Provider value={value}>{children}</McpContext.Provider>;
+}