@react-spa-scaffold/mcp 2.1.0 → 2.2.0

package/templates/src/hooks/useSyncedState.test.ts

@@ -0,0 +1,119 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { useSyncedState } from './useSyncedState';
+
+describe('useSyncedState', () => {
+  it('returns external value initially', () => {
+    const { result } = renderHook(() => useSyncedState('initial', false));
+    expect(result.current[0]).toBe('initial');
+  });
+
+  it('updates local value via setter', () => {
+    const { result } = renderHook(() => useSyncedState('initial', false));
+
+    act(() => {
+      result.current[1]('local-change');
+    });
+
+    expect(result.current[0]).toBe('local-change');
+  });
+
+  it('syncs with external value when not active', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: 'v1', isActive: false },
+    });
+
+    expect(result.current[0]).toBe('v1');
+
+    // External value changes while not active - should sync
+    rerender({ externalValue: 'v2', isActive: false });
+    expect(result.current[0]).toBe('v2');
+  });
+
+  it('does not sync with external value while active', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: 'v1', isActive: true },
+    });
+
+    // Initial sync when becoming active
+    expect(result.current[0]).toBe('v1');
+
+    // User makes local edit while active
+    act(() => {
+      result.current[1]('local-edit');
+    });
+    expect(result.current[0]).toBe('local-edit');
+
+    // External value changes while still active - should NOT sync (preserve user edit)
+    rerender({ externalValue: 'v2', isActive: true });
+    expect(result.current[0]).toBe('local-edit');
+  });
+
+  it('syncs when switching from active to inactive', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: 'v1', isActive: true },
+    });
+
+    // Make local edit while active
+    act(() => {
+      result.current[1]('local-edit');
+    });
+    expect(result.current[0]).toBe('local-edit');
+
+    // External value changed while we were editing
+    rerender({ externalValue: 'v2', isActive: true });
+    expect(result.current[0]).toBe('local-edit');
+
+    // Switch to inactive - should sync with new external value
+    rerender({ externalValue: 'v2', isActive: false });
+    expect(result.current[0]).toBe('v2');
+  });
+
+  it('syncs when switching from inactive to active (e.g., opening drawer)', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: '', isActive: false },
+    });
+
+    expect(result.current[0]).toBe('');
+
+    // Simulate opening a drawer with new content - external value and isActive change together
+    rerender({ externalValue: 'section content', isActive: true });
+
+    // Should sync with the new external value when becoming active
+    expect(result.current[0]).toBe('section content');
+  });
+
+  it('preserves local edits while active after initial sync', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: '', isActive: false },
+    });
+
+    // Open drawer with content
+    rerender({ externalValue: 'initial content', isActive: true });
+    expect(result.current[0]).toBe('initial content');
+
+    // User edits locally
+    act(() => {
+      result.current[1]('user edited content');
+    });
+    expect(result.current[0]).toBe('user edited content');
+
+    // External value changes (e.g., from another source) - should NOT overwrite user edit
+    rerender({ externalValue: 'different content', isActive: true });
+    expect(result.current[0]).toBe('user edited content');
+  });
+
+  it('works with complex objects', () => {
+    const initial = { name: 'test', value: 1 };
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: initial, isActive: false },
+    });
+
+    expect(result.current[0]).toEqual(initial);
+
+    const updated = { name: 'updated', value: 2 };
+    rerender({ externalValue: updated, isActive: false });
+    expect(result.current[0]).toEqual(updated);
+  });
+});

package/templates/src/hooks/useSyncedState.ts

@@ -0,0 +1,30 @@
+import { useEffect, useRef, useState, type Dispatch, type SetStateAction } from 'react';
+
+/**
+ * Syncs local state with an external value, but only when not actively editing.
+ * Prevents external updates from overwriting user input mid-edit.
+ *
+ * @param externalValue - The external/server value to sync from
+ * @param isActive - Whether the user is currently editing (blocks sync)
+ */
+export function useSyncedState<T>(externalValue: T, isActive: boolean): [T, Dispatch<SetStateAction<T>>] {
+  const [localValue, setLocalValue] = useState<T>(externalValue);
+  const prevIsActiveRef = useRef(isActive);
+
+  // Sync external value to local state when:
+  // 1. Not active (external updates flow through)
+  // 2. Activity state changed (sync on open/close transitions)
+  // This is an intentional pattern for synchronizing external props to local state
+  useEffect(() => {
+    const activityChanged = prevIsActiveRef.current !== isActive;
+
+    if (!isActive || activityChanged) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- Intentional sync pattern
+      setLocalValue(externalValue);
+    }
+
+    prevIsActiveRef.current = isActive;
+  }, [externalValue, isActive]);
+
+  return [localValue, setLocalValue];
+}

package/templates/src/index.css

@@ -1,6 +1,7 @@
 @import 'tailwindcss';
 @import 'tw-animate-css';
 @import 'shadcn/tailwind.css';
+@import '@clerk/themes/shadcn.css';
 @import '@fontsource-variable/inter';
 
 @custom-variant dark (&:is(.dark *));

package/templates/src/lib/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Centralized timing constants for consistent UX across the application.
+ * Use these instead of magic numbers to ensure consistency.
+ */
+export const TIMING = {
+  /** Debounce delay for user input in milliseconds */
+  DEBOUNCE_DELAY: 300,
+  /** Duration to show "Copied!" feedback in milliseconds */
+  COPY_FEEDBACK_DURATION: 2000,
+} as const;

package/templates/src/lib/createSelectors.test.ts

@@ -0,0 +1,136 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { create } from 'zustand';
+
+import { createSelectors } from './createSelectors';
+
+interface TestState {
+  count: number;
+  name: string;
+  increment: () => void;
+  setName: (name: string) => void;
+}
+
+describe('createSelectors', () => {
+  it('creates auto-generated selectors for all state properties', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'test',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    // Verify .use namespace exists
+    expect(useStore.use).toBeDefined();
+    expect(typeof useStore.use.count).toBe('function');
+    expect(typeof useStore.use.name).toBe('function');
+    expect(typeof useStore.use.increment).toBe('function');
+    expect(typeof useStore.use.setName).toBe('function');
+  });
+
+  it('selectors return correct state values', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 42,
+      name: 'hello',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    const { result: countResult } = renderHook(() => useStore.use.count());
+    const { result: nameResult } = renderHook(() => useStore.use.name());
+
+    expect(countResult.current).toBe(42);
+    expect(nameResult.current).toBe('hello');
+  });
+
+  it('selectors return action functions', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'test',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    const { result: incrementResult } = renderHook(() => useStore.use.increment());
+    const { result: setNameResult } = renderHook(() => useStore.use.setName());
+
+    expect(typeof incrementResult.current).toBe('function');
+    expect(typeof setNameResult.current).toBe('function');
+  });
+
+  it('actions from selectors update state correctly', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'initial',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    // Get initial state
+    expect(useStore.getState().count).toBe(0);
+    expect(useStore.getState().name).toBe('initial');
+
+    // Use action from selector
+    const { result: incrementResult } = renderHook(() => useStore.use.increment());
+
+    act(() => {
+      incrementResult.current();
+    });
+
+    expect(useStore.getState().count).toBe(1);
+
+    // Use another action
+    const { result: setNameResult } = renderHook(() => useStore.use.setName());
+
+    act(() => {
+      setNameResult.current('updated');
+    });
+
+    expect(useStore.getState().name).toBe('updated');
+  });
+
+  it('preserves original store functionality', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'test',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    // Original hook still works
+    const { result } = renderHook(() => useStore((state) => state.count));
+    expect(result.current).toBe(0);
+
+    // getState still works
+    expect(useStore.getState().count).toBe(0);
+
+    // setState still works
+    act(() => {
+      useStore.setState({ count: 100 });
+    });
+    expect(useStore.getState().count).toBe(100);
+
+    // subscribe still works
+    let subscribedValue = 0;
+    const unsub = useStore.subscribe((state) => {
+      subscribedValue = state.count;
+    });
+
+    act(() => {
+      useStore.setState({ count: 200 });
+    });
+    expect(subscribedValue).toBe(200);
+
+    unsub();
+  });
+});

package/templates/src/lib/createSelectors.ts

@@ -0,0 +1,31 @@
+import type { StoreApi, UseBoundStore } from 'zustand';
+
+/**
+ * Type that extends a Zustand store with auto-generated selectors.
+ * Adds a `use` namespace with selector functions for each store property.
+ */
+type WithSelectors<S> = S extends { getState: () => infer T } ? S & { use: { [K in keyof T]: () => T[K] } } : never;
+
+/**
+ * Wraps a Zustand store and automatically generates selector hooks for all properties.
+ *
+ * @example
+ * ```tsx
+ * const useStoreBase = create<State>()((set) => ({ count: 0 }));
+ * export const useStore = createSelectors(useStoreBase);
+ *
+ * // Usage in components:
+ * const count = useStore.use.count();
+ * const increment = useStore.use.increment();
+ * ```
+ */
+export function createSelectors<S extends UseBoundStore<StoreApi<object>>>(_store: S): WithSelectors<S> {
+  const store = _store as WithSelectors<typeof _store>;
+  store.use = {} as WithSelectors<S>['use'];
+
+  for (const key of Object.keys(store.getState())) {
+    (store.use as Record<string, () => unknown>)[key] = () => store((state) => state[key as keyof typeof state]);
+  }
+
+  return store;
+}

package/templates/src/lib/index.ts

@@ -12,3 +12,4 @@ export { env, validateEnv, type Env } from './env';
 export { api, ApiClientError } from './api';
 export { getStorageItem, setStorageItem, removeStorageItem, clearAppStorage } from './storage';
 export { registerFormSchema, type RegisterFormData } from './validations';
+export { createSelectors } from './createSelectors';

package/templates/src/lib/sentry.ts

@@ -0,0 +1,55 @@
+import type * as SentryType from '@sentry/react';
+
+let sentryInstance: typeof SentryType | null = null;
+
+/**
+ * Initialize Sentry error tracking.
+ * Only runs in production when VITE_SENTRY_DSN is configured.
+ */
+export async function initSentry(): Promise<void> {
+  // Skip in development or if already initialized
+  if (import.meta.env.DEV || sentryInstance) return;
+
+  const dsn = import.meta.env.VITE_SENTRY_DSN;
+  if (!dsn) return;
+
+  const sentry = await import('@sentry/react');
+
+  sentry.init({
+    dsn,
+    environment: import.meta.env.MODE,
+    sendDefaultPii: true,
+    integrations: [sentry.browserTracingIntegration()],
+    tracesSampleRate: 0.1,
+  });
+
+  sentryInstance = sentry;
+}
+
+/**
+ * Lazily initialize Sentry after the app is interactive.
+ * Uses requestIdleCallback with fallback for older browsers.
+ */
+export function lazySentryInit(): void {
+  const init = () => void initSentry();
+
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(init, { timeout: 2000 });
+  } else {
+    setTimeout(init, 1000);
+  }
+}
+
+interface CaptureContext {
+  componentStack?: string;
+}
+
+/**
+ * Capture an exception to Sentry.
+ * No-op if Sentry is not initialized.
+ */
+export function captureException(error: unknown, context?: CaptureContext): void {
+  sentryInstance?.captureException(error, {
+    extra: context?.componentStack ? { componentStack: context.componentStack } : undefined,
+  });
+}

package/templates/src/lib/storage.ts

@@ -4,7 +4,8 @@
 
 import { STORAGE_KEYS } from './storageKeys';
 
-type StorageKey = (typeof STORAGE_KEYS)[keyof typeof STORAGE_KEYS];
+// Extract only string keys (exclude functions if any are added later)
+type StorageKey = Extract<(typeof STORAGE_KEYS)[keyof typeof STORAGE_KEYS], string>;
 
 /**
  * Check if we're in a browser environment
@@ -81,7 +82,10 @@ export function clearAppStorage(): boolean {
 
   try {
     Object.values(STORAGE_KEYS).forEach((key) => {
-      localStorage.removeItem(key);
+      // Skip function keys (like prompt()) if any exist
+      if (typeof key === 'string') {
+        localStorage.removeItem(key);
+      }
     });
     return true;
   } catch (error) {

package/templates/src/main.tsx

@@ -6,6 +6,7 @@ import { BrowserRouter } from 'react-router';
 import './index.css';
 import { ErrorBoundary } from '@/components/shared';
 import { Toaster } from '@/components/ui/sonner';
+import { ClerkThemeProvider } from '@/contexts/clerkContext';
 import { MobileProvider } from '@/contexts/mobileContext';
 import { PerformanceProviderWrapper } from '@/contexts/performanceContext';
 import { QueryProvider } from '@/contexts/queryContext';
@@ -15,6 +16,13 @@ import { initPreferencesSync } from '@/stores/preferencesStore';
 
 import App from './App';
 
+// Import Clerk Publishable Key (per official docs)
+const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
+
+if (!PUBLISHABLE_KEY) {
+  throw new Error('Add your Clerk Publishable Key to the .env.local file');
+}
+
 /**
  * Lazy load Sentry after initial render to avoid blocking web vitals.
  * Returns the Sentry module for use in global error handlers.
@@ -74,14 +82,16 @@ initI18n().then(() => {
       <QueryProvider>
         <I18nProvider i18n={i18n}>
           <BrowserRouter>
-            <MobileProvider>
-              <ErrorBoundary>
-                <PerformanceProviderWrapper>
-                  <App />
-                  <Toaster />
-                </PerformanceProviderWrapper>
-              </ErrorBoundary>
-            </MobileProvider>
+            <ClerkThemeProvider publishableKey={PUBLISHABLE_KEY}>
+              <MobileProvider>
+                <ErrorBoundary>
+                  <PerformanceProviderWrapper>
+                    <App />
+                    <Toaster />
+                  </PerformanceProviderWrapper>
+                </ErrorBoundary>
+              </MobileProvider>
+            </ClerkThemeProvider>
           </BrowserRouter>
         </I18nProvider>
       </QueryProvider>

package/templates/src/stores/preferencesStore.ts

@@ -1,6 +1,7 @@
 import { create } from 'zustand';
 import { devtools, persist } from 'zustand/middleware';
 
+import { createSelectors } from '@/lib/createSelectors';
 import { STORAGE_KEYS } from '@/lib/storageKeys';
 
 export type Theme = 'light' | 'dark' | 'system';
@@ -31,18 +32,25 @@ function getSystemTheme(): 'light' | 'dark' {
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 }
 
-export const usePreferencesStore = create<PreferencesState>()(
+/** Current schema version for preferences store persistence */
+const PREFERENCES_STORE_VERSION = 1;
+
+const usePreferencesStoreBase = create<PreferencesState>()(
   devtools(
     persist(
       (set, get) => ({
         ...initialState,
-        setTheme: (theme) => set({ theme }),
+        setTheme: (theme) => set({ theme }, undefined, 'preferences/setTheme'),
         toggleTheme: () =>
-          set((state) => {
-            const resolved = state.theme === 'system' ? getSystemTheme() : state.theme;
-            return { theme: resolved === 'light' ? 'dark' : 'light' };
-          }),
-        reset: () => set(initialState),
+          set(
+            (state) => {
+              const resolved = state.theme === 'system' ? getSystemTheme() : state.theme;
+              return { theme: resolved === 'light' ? 'dark' : 'light' };
+            },
+            undefined,
+            'preferences/toggleTheme',
+          ),
+        reset: () => set(initialState, undefined, 'preferences/reset'),
         getResolvedTheme: () => {
           const { theme } = get();
           return theme === 'system' ? getSystemTheme() : theme;
@@ -50,13 +58,30 @@ export const usePreferencesStore = create<PreferencesState>()(
       }),
       {
         name: STORAGE_KEYS.preferences,
-        partialize: (state) => ({ theme: state.theme }),
+        version: PREFERENCES_STORE_VERSION,
+        partialize: (state): Preferences => ({ theme: state.theme }),
+        migrate: (persisted, version) => {
+          const state = persisted as Preferences;
+          if (version === 0) {
+            // v0 → v1: No changes needed, establishes baseline for future migrations
+            return state;
+          }
+          return state;
+        },
+        onRehydrateStorage: () => (_state, error) => {
+          if (error) {
+            console.error('Failed to hydrate preferences store:', error);
+          }
+        },
       },
     ),
-    { name: 'preferences' },
+    { name: 'preferences', enabled: process.env.NODE_ENV === 'development' },
   ),
 );
 
+/** Preferences store with auto-generated selectors */
+export const usePreferencesStore = createSelectors(usePreferencesStoreBase);
+
 /**
  * Initialize multi-tab sync for preferences.
  * Call this once at app startup.

package/templates/src/test/clerkMock.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react';
+
+// =============================================================================
+// Mock State
+// =============================================================================
+
+interface ClerkMockState {
+  isSignedIn: boolean;
+  isLoaded: boolean;
+}
+
+const defaultState: ClerkMockState = {
+  isSignedIn: true,
+  isLoaded: true,
+};
+
+let mockState: ClerkMockState = { ...defaultState };
+
+// =============================================================================
+// Test Utilities
+// =============================================================================
+
+export function setMockSignedIn(value: boolean) {
+  mockState.isSignedIn = value;
+}
+
+export function setMockLoaded(value: boolean) {
+  mockState.isLoaded = value;
+}
+
+export function setMockClerkState(state: Partial<ClerkMockState>) {
+  mockState = { ...mockState, ...state };
+}
+
+export function resetClerkMocks() {
+  mockState = { ...defaultState };
+}
+
+// =============================================================================
+// Mock Components
+// =============================================================================
+
+export function SignedIn({ children }: { children: ReactNode }) {
+  return mockState.isLoaded && mockState.isSignedIn ? <>{children}</> : null;
+}
+
+export function SignedOut({ children }: { children: ReactNode }) {
+  return mockState.isLoaded && !mockState.isSignedIn ? <>{children}</> : null;
+}
+
+export function SignInButton({ children }: { children?: ReactNode; mode?: string }) {
+  return <div data-testid="sign-in-button">{children}</div>;
+}
+
+export function SignUpButton({ children }: { children?: ReactNode; mode?: string }) {
+  return <div data-testid="sign-up-button">{children}</div>;
+}
+
+export function UserButton() {
+  return <button data-testid="user-button">User</button>;
+}
+
+export function RedirectToSignIn() {
+  return <div data-testid="redirect-to-sign-in" />;
+}
+
+export function ClerkProvider({
+  children,
+}: {
+  children: ReactNode;
+  publishableKey?: string;
+  afterSignOutUrl?: string;
+  appearance?: unknown;
+}) {
+  return <>{children}</>;
+}
+
+// =============================================================================
+// Mock Hooks
+// =============================================================================
+
+export function useAuth() {
+  return {
+    isLoaded: mockState.isLoaded,
+    isSignedIn: mockState.isSignedIn,
+    userId: mockState.isSignedIn ? 'user_123' : null,
+    sessionId: mockState.isSignedIn ? 'sess_123' : null,
+    getToken: async () => (mockState.isSignedIn ? 'mock-token' : null),
+  };
+}
+
+export function useUser() {
+  return {
+    isLoaded: mockState.isLoaded,
+    user: mockState.isSignedIn ? { id: 'user_123', firstName: 'Test', lastName: 'User' } : null,
+  };
+}

package/templates/src/test/index.ts

@@ -4,5 +4,8 @@ export { createTestQueryClient, render } from './providers';
 // Mock utilities
 export { mockMatchMedia } from './mocks';
 
+// Clerk test utilities
+export { resetClerkMocks, setMockClerkState, setMockLoaded, setMockSignedIn } from './clerkMock';
+
 // MSW server instance
 export { server } from '@/mocks/node';

package/templates/src/test/providers.tsx

@@ -5,6 +5,7 @@ import { render, type RenderOptions } from '@testing-library/react';
 import { type ReactElement, type ReactNode } from 'react';
 import { MemoryRouter } from 'react-router';
 
+import { ClerkThemeProvider } from '@/contexts/clerkContext';
 import { MobileProvider } from '@/contexts/mobileContext';
 import { PerformanceProviderWrapper } from '@/contexts/performanceContext';
 
@@ -37,14 +38,16 @@ interface WrapperProps {
 function AllProviders({ children }: WrapperProps) {
   const queryClient = createTestQueryClient();
 
-  // Provider order matches main.tsx: Query > I18n > Router > Mobile > Performance
+  // Provider order matches main.tsx: Query > I18n > Router > Clerk > Mobile > Performance
   return (
     <QueryClientProvider client={queryClient}>
       <I18nProvider i18n={i18n}>
         <MemoryRouter>
-          <MobileProvider>
-            <PerformanceProviderWrapper>{children}</PerformanceProviderWrapper>
-          </MobileProvider>
+          <ClerkThemeProvider publishableKey="test_key">
+            <MobileProvider>
+              <PerformanceProviderWrapper>{children}</PerformanceProviderWrapper>
+            </MobileProvider>
+          </ClerkThemeProvider>
         </MemoryRouter>
       </I18nProvider>
     </QueryClientProvider>