@jmruthers/pace-core 0.5.120 → 0.5.123

package/docs/troubleshooting/debugging.md

@@ -0,0 +1,1117 @@
+# Debugging Guide
+
+Effective debugging is essential for maintaining and troubleshooting `@jmruthers/pace-core` applications. This guide provides comprehensive debugging techniques and tools.
+
+## Overview
+
+Debugging in `@jmruthers/pace-core` covers multiple areas:
+
+- **Component Debugging**: React component issues and rendering problems
+- **Hook Debugging**: Custom hook behavior and state management
+- **Authentication Debugging**: User authentication and session issues
+- **Permission Debugging**: RBAC and access control problems
+- **API Debugging**: Supabase and external API issues
+- **Performance Debugging**: Performance bottlenecks and memory leaks
+
+## Debugging Tools
+
+### 1. React Developer Tools
+
+```typescript
+// Enable React DevTools in development
+if (process.env.NODE_ENV === 'development') {
+  // React DevTools will automatically connect
+  console.log('React DevTools enabled');
+}
+
+// Custom hook for debugging component renders
+function useDebugRender(componentName: string, props?: any) {
+  useEffect(() => {
+    console.log(`${componentName} rendered with props:`, props);
+  });
+  
+  useEffect(() => {
+    console.log(`${componentName} mounted`);
+    return () => console.log(`${componentName} unmounted`);
+  }, []);
+}
+
+// Usage in components
+function MyComponent({ data, loading }) {
+  useDebugRender('MyComponent', { data, loading });
+  
+  if (loading) return <div>Loading...</div>;
+  return <div>{data}</div>;
+}
+```
+
+### 2. Custom Debug Hooks
+
+```typescript
+// hooks/useDebug.ts
+import { useEffect, useRef } from 'react';
+
+export function useDebugValue<T>(value: T, label: string) {
+  const prevValue = useRef<T>();
+  
+  useEffect(() => {
+    if (prevValue.current !== value) {
+      console.log(`${label} changed:`, {
+        previous: prevValue.current,
+        current: value,
+      });
+      prevValue.current = value;
+    }
+  }, [value, label]);
+}
+
+export function useDebugEffect(effect: () => void, deps: any[], label: string) {
+  useEffect(() => {
+    console.log(`${label} effect triggered with deps:`, deps);
+    effect();
+  }, deps);
+}
+
+export function useDebugCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  deps: any[],
+  label: string
+): T {
+  const prevDeps = useRef<any[]>();
+  
+  useEffect(() => {
+    if (JSON.stringify(prevDeps.current) !== JSON.stringify(deps)) {
+      console.log(`${label} callback dependencies changed:`, deps);
+      prevDeps.current = deps;
+    }
+  }, [deps, label]);
+  
+  return callback;
+}
+
+// Usage
+function MyComponent({ userId }) {
+  useDebugValue(userId, 'userId');
+  
+  const handleClick = useDebugCallback(() => {
+    console.log('Button clicked');
+  }, [userId], 'handleClick');
+  
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+### 3. Error Boundary with Debugging
+
+```typescript
+// components/DebugErrorBoundary.tsx
+import React from 'react';
+import { ErrorBoundary } from '@jmruthers/pace-core';
+
+interface DebugErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback?: React.ComponentType<{ error: Error; resetError: () => void }>;
+}
+
+export function DebugErrorBoundary({ children, fallback }: DebugErrorBoundaryProps) {
+  const handleError = (error: Error, errorInfo: React.ErrorInfo) => {
+    console.error('Error caught by boundary:', error);
+    console.error('Error info:', errorInfo);
+    
+    // Send to error tracking service
+    if (typeof Sentry !== 'undefined') {
+      Sentry.captureException(error, {
+        extra: {
+          componentStack: errorInfo.componentStack,
+        },
+      });
+    }
+  };
+
+  const FallbackComponent = fallback || DefaultFallback;
+
+  return (
+    <ErrorBoundary onError={handleError} fallback={FallbackComponent}>
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+function DefaultFallback({ error, resetError }: { error: Error; resetError: () => void }) {
+  return (
+    <div className="error-boundary">
+      <h2>Something went wrong</h2>
+      <details>
+        <summary>Error details</summary>
+        <pre>{error.message}</pre>
+        <pre>{error.stack}</pre>
+      </details>
+      <button onClick={resetError}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Component Debugging
+
+### 1. Component State Debugging
+
+```typescript
+// utils/componentDebugger.ts
+export function debugComponentState<T>(
+  componentName: string,
+  state: T,
+  prevState?: T
+) {
+  if (process.env.NODE_ENV === 'development') {
+    console.group(`${componentName} State Change`);
+    console.log('Previous State:', prevState);
+    console.log('Current State:', state);
+    console.log('Changes:', getStateChanges(prevState, state));
+    console.groupEnd();
+  }
+}
+
+function getStateChanges(prev: any, current: any): Record<string, any> {
+  if (!prev) return { initial: current };
+  
+  const changes: Record<string, any> = {};
+  
+  for (const key in current) {
+    if (prev[key] !== current[key]) {
+      changes[key] = {
+        from: prev[key],
+        to: current[key],
+      };
+    }
+  }
+  
+  return changes;
+}
+
+// Usage in components
+function MyComponent() {
+  const [state, setState] = useState({ count: 0, loading: false });
+  const prevState = useRef(state);
+  
+  useEffect(() => {
+    debugComponentState('MyComponent', state, prevState.current);
+    prevState.current = state;
+  }, [state]);
+  
+  return <div>{state.count}</div>;
+}
+```
+
+### 2. Props Debugging
+
+```typescript
+// utils/propsDebugger.ts
+export function debugProps<T>(componentName: string, props: T) {
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`${componentName} props:`, props);
+  }
+}
+
+// Higher-order component for automatic props debugging
+export function withPropsDebug<P extends object>(
+  Component: React.ComponentType<P>,
+  componentName?: string
+) {
+  const WrappedComponent = (props: P) => {
+    const name = componentName || Component.displayName || Component.name;
+    debugProps(name, props);
+    return <Component {...props} />;
+  };
+  
+  WrappedComponent.displayName = `withPropsDebug(${Component.displayName || Component.name})`;
+  return WrappedComponent;
+}
+
+// Usage
+const DebuggedButton = withPropsDebug(Button, 'Button');
+```
+
+### 3. Render Performance Debugging
+
+```typescript
+// utils/renderDebugger.ts
+import { useComponentPerformance } from '@jmruthers/pace-core';
+
+export function useRenderDebug(componentName: string) {
+  const { renderCount, averageRenderTime, lastRenderTime } = useComponentPerformance();
+  
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log(`${componentName} render stats:`, {
+        renderCount,
+        averageRenderTime: averageRenderTime.toFixed(2),
+        lastRenderTime: lastRenderTime.toFixed(2),
+      });
+    }
+  }, [renderCount, averageRenderTime, lastRenderTime, componentName]);
+  
+  // Warn if component is rendering too frequently
+  useEffect(() => {
+    if (renderCount > 10 && averageRenderTime > 16) {
+      console.warn(`${componentName} is rendering frequently and slowly:`, {
+        renderCount,
+        averageRenderTime: averageRenderTime.toFixed(2),
+      });
+    }
+  }, [renderCount, averageRenderTime, componentName]);
+}
+
+// Usage
+function ExpensiveComponent() {
+  useRenderDebug('ExpensiveComponent');
+  
+  // Component logic here
+  return <div>Expensive content</div>;
+}
+```
+
+## Hook Debugging
+
+### 1. Authentication Hook Debugging
+
+```typescript
+// hooks/useAuthDebug.ts
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+export function useAuthDebug() {
+  const auth = useUnifiedAuth();
+  
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log('Auth state changed:', {
+        user: auth.user,
+        loading: auth.loading,
+        error: auth.error,
+        isAuthenticated: !!auth.user,
+      });
+    }
+  }, [auth.user, auth.loading, auth.error]);
+  
+  // Debug authentication errors
+  useEffect(() => {
+    if (auth.error) {
+      console.error('Authentication error:', auth.error);
+      
+      // Log additional context
+      console.log('Auth error context:', {
+        timestamp: new Date().toISOString(),
+        userAgent: navigator.userAgent,
+        url: window.location.href,
+      });
+    }
+  }, [auth.error]);
+  
+  return auth;
+}
+
+// Usage
+function AuthDebugger() {
+  const auth = useAuthDebug();
+  
+  if (auth.loading) return <div>Loading auth...</div>;
+  if (auth.error) return <div>Auth error: {auth.error}</div>;
+  if (!auth.user) return <div>Not authenticated</div>;
+  
+  return <div>Authenticated as: {auth.user.email}</div>;
+}
+```
+
+### 2. RBAC Hook Debugging
+
+```typescript
+// hooks/useRBACDebug.ts
+import { useRBAC } from '@jmruthers/pace-core';
+
+export function useRBACDebug() {
+  const rbac = useRBAC();
+  
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log('RBAC state:', {
+        permissions: rbac.permissions,
+        roles: rbac.roles,
+        loading: rbac.loading,
+        error: rbac.error,
+      });
+    }
+  }, [rbac.permissions, rbac.roles, rbac.loading, rbac.error]);
+  
+  // Debug permission checks
+  const debugHasPermission = useCallback((permission: string) => {
+    const hasPermission = rbac.hasPermission(permission);
+    
+    if (process.env.NODE_ENV === 'development') {
+      console.log(`Permission check: ${permission} = ${hasPermission}`, {
+        userPermissions: rbac.permissions,
+        userRoles: rbac.roles,
+      });
+    }
+    
+    return hasPermission;
+  }, [rbac]);
+  
+  return {
+    ...rbac,
+    hasPermission: debugHasPermission,
+  };
+}
+
+// Usage
+function PermissionDebugger() {
+  const rbac = useRBACDebug();
+  
+  const canReadUsers = rbac.hasPermission('read:users');
+  const canWriteEvents = rbac.hasPermission('write:events');
+  
+  return (
+    <div>
+      <div>Can read users: {canReadUsers ? 'Yes' : 'No'}</div>
+      <div>Can write events: {canWriteEvents ? 'Yes' : 'No'}</div>
+    </div>
+  );
+}
+```
+
+### 3. Event Hook Debugging
+
+```typescript
+// hooks/useEventDebug.ts
+import { useEvents } from '@jmruthers/pace-core';
+
+export function useEventDebug() {
+  const events = useEvents();
+  
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log('Events state:', {
+        events: events.events,
+        loading: events.loading,
+        error: events.error,
+        selectedEvent: events.selectedEvent,
+        count: events.events?.length || 0,
+      });
+    }
+  }, [events.events, events.loading, events.error, events.selectedEvent]);
+  
+  // Debug event operations
+  const debugSetSelectedEvent = useCallback((event: any) => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log('Setting selected event:', event);
+    }
+    events.setSelectedEvent(event);
+  }, [events.setSelectedEvent]);
+  
+  const debugRefreshEvents = useCallback(async () => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log('Refreshing events...');
+    }
+    
+    try {
+      await events.refreshEvents();
+      console.log('Events refreshed successfully');
+    } catch (error) {
+      console.error('Failed to refresh events:', error);
+    }
+  }, [events.refreshEvents]);
+  
+  return {
+    ...events,
+    setSelectedEvent: debugSetSelectedEvent,
+    refreshEvents: debugRefreshEvents,
+  };
+}
+```
+
+## API Debugging
+
+### 1. Supabase Debugging
+
+```typescript
+// utils/supabaseDebugger.ts
+import { useSupabase } from '@jmruthers/pace-core';
+
+export function useSupabaseDebug() {
+  const { supabase } = useSupabase();
+  
+  // Debug Supabase queries
+  const debugQuery = useCallback(async (table: string, query: any) => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log(`Supabase query to ${table}:`, query);
+    }
+    
+    try {
+      const result = await supabase.from(table).select('*');
+      
+      if (process.env.NODE_ENV === 'development') {
+        console.log(`Query result for ${table}:`, result);
+      }
+      
+      return result;
+    } catch (error) {
+      console.error(`Query error for ${table}:`, error);
+      throw error;
+    }
+  }, [supabase]);
+  
+  // Debug authentication
+  const debugAuth = useCallback(async (action: string, credentials: any) => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log(`Auth action: ${action}`, credentials);
+    }
+    
+    try {
+      let result;
+      
+      switch (action) {
+        case 'signIn':
+          result = await supabase.auth.signInWithPassword(credentials);
+          break;
+        case 'signUp':
+          result = await supabase.auth.signUp(credentials);
+          break;
+        case 'signOut':
+          result = await supabase.auth.signOut();
+          break;
+        default:
+          throw new Error(`Unknown auth action: ${action}`);
+      }
+      
+      if (process.env.NODE_ENV === 'development') {
+        console.log(`Auth result for ${action}:`, result);
+      }
+      
+      return result;
+    } catch (error) {
+      console.error(`Auth error for ${action}:`, error);
+      throw error;
+    }
+  }, [supabase]);
+  
+  return {
+    supabase,
+    debugQuery,
+    debugAuth,
+  };
+}
+```
+
+### 2. Network Request Debugging
+
+```typescript
+// utils/networkDebugger.ts
+export function debugNetworkRequest(url: string, options: RequestInit) {
+  if (process.env.NODE_ENV === 'development') {
+    console.log('Network request:', {
+      url,
+      method: options.method || 'GET',
+      headers: options.headers,
+      body: options.body,
+    });
+  }
+}
+
+export function debugNetworkResponse(url: string, response: Response, data?: any) {
+  if (process.env.NODE_ENV === 'development') {
+    console.log('Network response:', {
+      url,
+      status: response.status,
+      statusText: response.statusText,
+      headers: Object.fromEntries(response.headers.entries()),
+      data,
+    });
+  }
+}
+
+// Custom fetch with debugging
+export async function debugFetch(url: string, options: RequestInit = {}) {
+  debugNetworkRequest(url, options);
+  
+  try {
+    const response = await fetch(url, options);
+    const data = await response.json();
+    
+    debugNetworkResponse(url, response, data);
+    
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    
+    return { response, data };
+  } catch (error) {
+    console.error('Network request failed:', {
+      url,
+      error: error.message,
+    });
+    throw error;
+  }
+}
+```
+
+## Performance Debugging
+
+### 1. Memory Leak Detection
+
+```typescript
+// utils/memoryDebugger.ts
+export function useMemoryLeakDetection(componentName: string) {
+  useEffect(() => {
+    const initialMemory = performance.memory?.usedJSHeapSize || 0;
+    
+    return () => {
+      const finalMemory = performance.memory?.usedJSHeapSize || 0;
+      const memoryIncrease = finalMemory - initialMemory;
+      
+      if (memoryIncrease > 1024 * 1024) { // 1MB threshold
+        console.warn(`${componentName} may have a memory leak:`, {
+          memoryIncrease: `${(memoryIncrease / 1024 / 1024).toFixed(2)}MB`,
+          initialMemory: `${(initialMemory / 1024 / 1024).toFixed(2)}MB`,
+          finalMemory: `${(finalMemory / 1024 / 1024).toFixed(2)}MB`,
+        });
+      }
+    };
+  }, [componentName]);
+}
+
+// Usage
+function MyComponent() {
+  useMemoryLeakDetection('MyComponent');
+  
+  // Component logic
+  return <div>Content</div>;
+}
+```
+
+### 2. Performance Monitoring
+
+```typescript
+// utils/performanceDebugger.ts
+export function usePerformanceDebug(componentName: string) {
+  const renderStartTime = useRef<number>();
+  
+  useEffect(() => {
+    renderStartTime.current = performance.now();
+    
+    return () => {
+      if (renderStartTime.current) {
+        const renderTime = performance.now() - renderStartTime.current;
+        
+        if (renderTime > 16) { // 60fps threshold
+          console.warn(`${componentName} took ${renderTime.toFixed(2)}ms to render`);
+        }
+      }
+    };
+  });
+  
+  // Track re-renders
+  const renderCount = useRef(0);
+  useEffect(() => {
+    renderCount.current += 1;
+    
+    if (renderCount.current > 10) {
+      console.warn(`${componentName} has rendered ${renderCount.current} times`);
+    }
+  });
+}
+
+// Performance observer for custom metrics
+export function setupPerformanceObserver() {
+  if (typeof PerformanceObserver !== 'undefined') {
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.entryType === 'measure') {
+          console.log('Performance measure:', {
+            name: entry.name,
+            duration: entry.duration,
+            startTime: entry.startTime,
+          });
+        }
+      }
+    });
+    
+    observer.observe({ entryTypes: ['measure'] });
+  }
+}
+```
+
+## Error Debugging
+
+### 1. Error Tracking and Analysis
+
+```typescript
+// utils/errorDebugger.ts
+export class ErrorDebugger {
+  private static errors: Error[] = [];
+  private static maxErrors = 100;
+  
+  static trackError(error: Error, context?: Record<string, any>) {
+    const errorInfo = {
+      error,
+      context,
+      timestamp: new Date().toISOString(),
+      stack: error.stack,
+      userAgent: navigator.userAgent,
+      url: window.location.href,
+    };
+    
+    this.errors.push(error);
+    
+    // Keep only the last maxErrors
+    if (this.errors.length > this.maxErrors) {
+      this.errors.shift();
+    }
+    
+    if (process.env.NODE_ENV === 'development') {
+      console.error('Error tracked:', errorInfo);
+    }
+    
+    return errorInfo;
+  }
+  
+  static getErrors() {
+    return this.errors;
+  }
+  
+  static clearErrors() {
+    this.errors = [];
+  }
+  
+  static getErrorStats() {
+    const errorTypes = this.errors.reduce((acc, error) => {
+      const type = error.constructor.name;
+      acc[type] = (acc[type] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+    
+    return {
+      totalErrors: this.errors.length,
+      errorTypes,
+      recentErrors: this.errors.slice(-10),
+    };
+  }
+}
+
+// Global error handler
+export function setupGlobalErrorHandler() {
+  window.addEventListener('error', (event) => {
+    ErrorDebugger.trackError(event.error, {
+      filename: event.filename,
+      lineno: event.lineno,
+      colno: event.colno,
+    });
+  });
+  
+  window.addEventListener('unhandledrejection', (event) => {
+    ErrorDebugger.trackError(new Error(event.reason), {
+      type: 'unhandledrejection',
+    });
+  });
+}
+```
+
+### 2. Debug Console
+
+```typescript
+// utils/debugConsole.ts
+export class DebugConsole {
+  private static logs: any[] = [];
+  private static maxLogs = 1000;
+  
+  static log(message: string, data?: any) {
+    const logEntry = {
+      message,
+      data,
+      timestamp: new Date().toISOString(),
+      level: 'log',
+    };
+    
+    this.logs.push(logEntry);
+    
+    if (this.logs.length > this.maxLogs) {
+      this.logs.shift();
+    }
+    
+    if (process.env.NODE_ENV === 'development') {
+      console.log(message, data);
+    }
+  }
+  
+  static warn(message: string, data?: any) {
+    const logEntry = {
+      message,
+      data,
+      timestamp: new Date().toISOString(),
+      level: 'warn',
+    };
+    
+    this.logs.push(logEntry);
+    
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(message, data);
+    }
+  }
+  
+  static error(message: string, error?: Error, data?: any) {
+    const logEntry = {
+      message,
+      error,
+      data,
+      timestamp: new Date().toISOString(),
+      level: 'error',
+    };
+    
+    this.logs.push(logEntry);
+    
+    if (process.env.NODE_ENV === 'development') {
+      console.error(message, error, data);
+    }
+  }
+  
+  static getLogs() {
+    return this.logs;
+  }
+  
+  static clearLogs() {
+    this.logs = [];
+  }
+  
+  static exportLogs() {
+    return {
+      logs: this.logs,
+      errorStats: ErrorDebugger.getErrorStats(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+
+// Make debug console available globally in development
+if (process.env.NODE_ENV === 'development') {
+  (window as any).debugConsole = DebugConsole;
+  (window as any).errorDebugger = ErrorDebugger;
+}
+```
+
+## Debugging Tools and Utilities
+
+### 1. Debug Panel Component
+
+```typescript
+// components/DebugPanel.tsx
+import { useState } from 'react';
+import { DebugConsole, ErrorDebugger } from '../utils';
+
+export function DebugPanel() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeTab, setActiveTab] = useState('logs');
+  
+  if (process.env.NODE_ENV !== 'development') {
+    return null;
+  }
+  
+  const logs = DebugConsole.getLogs();
+  const errorStats = ErrorDebugger.getErrorStats();
+  
+  return (
+    <div className="debug-panel">
+      <button onClick={() => setIsOpen(!isOpen)}>
+        Debug Panel {isOpen ? '▼' : '▲'}
+      </button>
+      
+      {isOpen && (
+        <div className="debug-content">
+          <div className="debug-tabs">
+            <button
+              className={activeTab === 'logs' ? 'active' : ''}
+              onClick={() => setActiveTab('logs')}
+            >
+              Logs ({logs.length})
+            </button>
+            <button
+              className={activeTab === 'errors' ? 'active' : ''}
+              onClick={() => setActiveTab('errors')}
+            >
+              Errors ({errorStats.totalErrors})
+            </button>
+            <button
+              className={activeTab === 'performance' ? 'active' : ''}
+              onClick={() => setActiveTab('performance')}
+            >
+              Performance
+            </button>
+          </div>
+          
+          <div className="debug-content-area">
+            {activeTab === 'logs' && (
+              <div className="logs-tab">
+                {logs.slice(-20).map((log, index) => (
+                  <div key={index} className={`log-entry ${log.level}`}>
+                    <span className="timestamp">{log.timestamp}</span>
+                    <span className="message">{log.message}</span>
+                    {log.data && (
+                      <pre className="data">{JSON.stringify(log.data, null, 2)}</pre>
+                    )}
+                  </div>
+                ))}
+              </div>
+            )}
+            
+            {activeTab === 'errors' && (
+              <div className="errors-tab">
+                <h3>Error Statistics</h3>
+                <pre>{JSON.stringify(errorStats, null, 2)}</pre>
+                
+                <h3>Recent Errors</h3>
+                {errorStats.recentErrors.map((error, index) => (
+                  <div key={index} className="error-entry">
+                    <div className="error-message">{error.message}</div>
+                    <div className="error-stack">{error.stack}</div>
+                  </div>
+                ))}
+              </div>
+            )}
+            
+            {activeTab === 'performance' && (
+              <div className="performance-tab">
+                <h3>Memory Usage</h3>
+                <div>
+                  Used: {(performance.memory?.usedJSHeapSize || 0) / 1024 / 1024}MB
+                </div>
+                <div>
+                  Total: {(performance.memory?.totalJSHeapSize || 0) / 1024 / 1024}MB
+                </div>
+                <div>
+                  Limit: {(performance.memory?.jsHeapSizeLimit || 0) / 1024 / 1024}MB
+                </div>
+              </div>
+            )}
+          </div>
+          
+          <div className="debug-actions">
+            <button onClick={() => DebugConsole.clearLogs()}>Clear Logs</button>
+            <button onClick={() => ErrorDebugger.clearErrors()}>Clear Errors</button>
+            <button onClick={() => {
+              const data = DebugConsole.exportLogs();
+              const blob = new Blob([JSON.stringify(data, null, 2)], {
+                type: 'application/json',
+              });
+              const url = URL.createObjectURL(blob);
+              const a = document.createElement('a');
+              a.href = url;
+              a.download = `debug-logs-${new Date().toISOString()}.json`;
+              a.click();
+            }}>Export Logs</button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. Debug Styles
+
+```css
+/* styles/debug.css */
+.debug-panel {
+  position: fixed;
+  bottom: 0;
+  right: 0;
+  width: 400px;
+  max-height: 500px;
+  background: #1a1a1a;
+  color: #fff;
+  border: 1px solid #333;
+  z-index: 9999;
+  font-family: monospace;
+  font-size: 12px;
+}
+
+.debug-content {
+  max-height: 400px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.debug-tabs {
+  display: flex;
+  border-bottom: 1px solid #333;
+}
+
+.debug-tabs button {
+  flex: 1;
+  padding: 8px;
+  background: #2a2a2a;
+  border: none;
+  color: #fff;
+  cursor: pointer;
+}
+
+.debug-tabs button.active {
+  background: #444;
+}
+
+.debug-content-area {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px;
+}
+
+.log-entry {
+  margin-bottom: 4px;
+  padding: 4px;
+  border-radius: 2px;
+}
+
+.log-entry.error {
+  background: #4a1a1a;
+  color: #ff6b6b;
+}
+
+.log-entry.warn {
+  background: #4a3a1a;
+  color: #ffd93d;
+}
+
+.log-entry.log {
+  background: #1a4a1a;
+  color: #6bff6b;
+}
+
+.timestamp {
+  color: #888;
+  margin-right: 8px;
+}
+
+.data {
+  margin-top: 4px;
+  padding: 4px;
+  background: #2a2a2a;
+  border-radius: 2px;
+  font-size: 10px;
+}
+
+.error-entry {
+  margin-bottom: 8px;
+  padding: 8px;
+  background: #4a1a1a;
+  border-radius: 4px;
+}
+
+.error-message {
+  color: #ff6b6b;
+  font-weight: bold;
+}
+
+.error-stack {
+  margin-top: 4px;
+  font-size: 10px;
+  color: #ccc;
+}
+
+.debug-actions {
+  padding: 8px;
+  border-top: 1px solid #333;
+  display: flex;
+  gap: 8px;
+}
+
+.debug-actions button {
+  padding: 4px 8px;
+  background: #444;
+  border: none;
+  color: #fff;
+  cursor: pointer;
+  border-radius: 2px;
+}
+
+.debug-actions button:hover {
+  background: #555;
+}
+```
+
+## Debugging Best Practices
+
+### 1. Debugging Checklist
+
+- [ ] Enable React DevTools
+- [ ] Use console.log strategically
+- [ ] Implement error boundaries
+- [ ] Track component renders
+- [ ] Monitor hook dependencies
+- [ ] Debug authentication flow
+- [ ] Check permission logic
+- [ ] Monitor API calls
+- [ ] Track performance metrics
+- [ ] Use debug panels in development
+
+### 2. Common Debugging Scenarios
+
+```typescript
+// Debugging authentication issues
+function debugAuthFlow() {
+  const auth = useUnifiedAuth();
+  
+  useEffect(() => {
+    console.log('Auth state:', {
+      user: auth.user,
+      loading: auth.loading,
+      error: auth.error,
+    });
+  }, [auth.user, auth.loading, auth.error]);
+  
+  // Debug specific auth actions
+  const debugSignIn = async (credentials: any) => {
+    console.log('Attempting sign in with:', credentials);
+    try {
+      const result = await auth.signIn(credentials);
+      console.log('Sign in result:', result);
+    } catch (error) {
+      console.error('Sign in failed:', error);
+    }
+  };
+}
+
+// Debugging permission issues
+function debugPermissions() {
+  const rbac = useRBAC();
+  
+  useEffect(() => {
+    console.log('RBAC state:', {
+      permissions: rbac.permissions,
+      roles: rbac.roles,
+    });
+  }, [rbac.permissions, rbac.roles]);
+  
+  // Test specific permissions
+  const testPermission = (permission: string) => {
+    const hasPermission = rbac.hasPermission(permission);
+    console.log(`Permission test: ${permission} = ${hasPermission}`);
+    return hasPermission;
+  };
+}
+
+// Debugging API issues
+function debugAPI() {
+  const { supabase } = useSupabase();
+  
+  const debugQuery = async (table: string) => {
+    console.log(`Querying ${table}...`);
+    try {
+      const { data, error } = await supabase.from(table).select('*');
+      console.log(`${table} query result:`, { data, error });
+      return { data, error };
+    } catch (error) {
+      console.error(`${table} query failed:`, error);
+      throw error;
+    }
+  };
+}
+```
+
+For more information about debugging your application, see the [Common Issues Guide](./common-issues.md) and [Migration Guide](./migration.md).