@affectively/aeon-pages 1.3.0

package/packages/react/src/hooks/usePilotNavigation.ts

@@ -0,0 +1,254 @@
+/**
+ * Pilot Navigation Hook
+ *
+ * AI-driven navigation with user consent.
+ * Cyrano acts as the "pilot" - suggesting navigation destinations,
+ * but always with user consent before actually navigating.
+ *
+ * The pilot metaphor:
+ * - User is the captain
+ * - AI (Cyrano) is the pilot suggesting routes
+ * - Navigation only happens with captain's approval
+ *
+ * Features:
+ * - Pending navigation queue
+ * - Consent confirmation UI
+ * - History API integration (smooth client-side navigation)
+ * - Navigation analytics/tracking
+ */
+
+import { useState, useCallback, useEffect, useMemo } from 'react';
+import { useAeonNavigation } from './useAeonNavigation';
+import type { NavigationOptions } from '@affectively/aeon-pages-runtime/navigation';
+
+export interface PilotNavigationIntent {
+  id: string;
+  destination: string;
+  reason?: string;
+  source: 'cyrano' | 'esi' | 'user' | 'system';
+  confidence?: number;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PilotNavigationOptions extends NavigationOptions {
+  /** Whether to require explicit consent (default: true for AI sources) */
+  requireConsent?: boolean;
+  /** Reason for navigation (shown to user) */
+  reason?: string;
+  /** Source of navigation intent */
+  source?: PilotNavigationIntent['source'];
+  /** Confidence level (0-1) for AI-driven navigation */
+  confidence?: number;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+  /** Auto-navigate after delay (ms) if consent not required */
+  autoNavigateDelay?: number;
+}
+
+export interface PilotNavigationState {
+  /** Current pending navigation intent awaiting consent */
+  pendingIntent: PilotNavigationIntent | null;
+  /** History of navigation intents */
+  intentHistory: PilotNavigationIntent[];
+  /** Whether navigation is in progress */
+  isNavigating: boolean;
+}
+
+type NavigationConsentCallback = (
+  intent: PilotNavigationIntent,
+) => Promise<boolean> | boolean;
+
+/**
+ * Hook for AI-piloted navigation with user consent
+ */
+export function usePilotNavigation(options?: {
+  /** Custom consent handler (if not provided, uses built-in pending state) */
+  onConsentRequired?: NavigationConsentCallback;
+  /** Maximum intent history to keep */
+  maxHistory?: number;
+}) {
+  const { onConsentRequired, maxHistory = 50 } = options ?? {};
+
+  const navigation = useAeonNavigation();
+  const [pendingIntent, setPendingIntent] =
+    useState<PilotNavigationIntent | null>(null);
+  const [intentHistory, setIntentHistory] = useState<PilotNavigationIntent[]>(
+    [],
+  );
+
+  /**
+   * Request navigation with optional consent
+   */
+  const pilot = useCallback(
+    async (
+      destination: string,
+      pilotOptions?: PilotNavigationOptions,
+    ): Promise<boolean> => {
+      const {
+        requireConsent = true,
+        reason,
+        source = 'user',
+        confidence,
+        metadata,
+        autoNavigateDelay,
+        ...navOptions
+      } = pilotOptions ?? {};
+
+      // Create intent
+      const intent: PilotNavigationIntent = {
+        id: `nav-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+        destination,
+        reason,
+        source,
+        confidence,
+        timestamp: Date.now(),
+        metadata,
+      };
+
+      // Add to history
+      setIntentHistory((prev) => [...prev.slice(-maxHistory + 1), intent]);
+
+      // Check if consent is required
+      const needsConsent =
+        requireConsent && (source === 'cyrano' || source === 'esi');
+
+      if (!needsConsent) {
+        // Navigate immediately
+        await navigation.navigate(destination, navOptions);
+        return true;
+      }
+
+      // If custom consent handler provided, use it
+      if (onConsentRequired) {
+        const consented = await onConsentRequired(intent);
+        if (consented) {
+          await navigation.navigate(destination, navOptions);
+          return true;
+        }
+        return false;
+      }
+
+      // Otherwise, set pending intent for UI to handle
+      setPendingIntent(intent);
+
+      // Auto-navigate after delay if specified
+      if (autoNavigateDelay && autoNavigateDelay > 0) {
+        setTimeout(async () => {
+          // Only navigate if this intent is still pending
+          setPendingIntent((current) => {
+            if (current?.id === intent.id) {
+              navigation.navigate(destination, navOptions);
+              return null;
+            }
+            return current;
+          });
+        }, autoNavigateDelay);
+      }
+
+      return false; // Pending consent
+    },
+    [navigation, onConsentRequired, maxHistory],
+  );
+
+  /**
+   * Approve pending navigation
+   */
+  const approve = useCallback(async () => {
+    if (!pendingIntent) return false;
+
+    const destination = pendingIntent.destination;
+    setPendingIntent(null);
+    await navigation.navigate(destination);
+    return true;
+  }, [pendingIntent, navigation]);
+
+  /**
+   * Reject pending navigation
+   */
+  const reject = useCallback(() => {
+    if (!pendingIntent) return;
+    setPendingIntent(null);
+  }, [pendingIntent]);
+
+  /**
+   * Clear all pending intents
+   */
+  const clearPending = useCallback(() => {
+    setPendingIntent(null);
+  }, []);
+
+  /**
+   * Navigate without consent (for user-initiated navigation)
+   */
+  const navigateDirect = useCallback(
+    async (destination: string, navOptions?: NavigationOptions) => {
+      await navigation.navigate(destination, navOptions);
+    },
+    [navigation],
+  );
+
+  return useMemo(
+    () => ({
+      // State
+      pendingIntent,
+      intentHistory,
+      isNavigating: navigation.isNavigating,
+      current: navigation.current,
+
+      // Actions
+      pilot, // AI-driven navigation with consent
+      approve, // Approve pending navigation
+      reject, // Reject pending navigation
+      clearPending, // Clear pending intent
+      navigateDirect, // Navigate without consent (user-initiated)
+
+      // Pass through navigation utilities
+      prefetch: navigation.prefetch,
+      back: navigation.back,
+      isPreloaded: navigation.isPreloaded,
+    }),
+    [
+      pendingIntent,
+      intentHistory,
+      navigation.isNavigating,
+      navigation.current,
+      pilot,
+      approve,
+      reject,
+      clearPending,
+      navigateDirect,
+      navigation.prefetch,
+      navigation.back,
+      navigation.isPreloaded,
+    ],
+  );
+}
+
+/**
+ * Parse navigation tags from AI response
+ * Returns array of destinations extracted from [navigate:/path] tags
+ */
+export function parseNavigationTags(
+  text: string,
+): { destination: string; fullMatch: string }[] {
+  const regex = /\[navigate:([^\]]+)\]/g;
+  const matches: { destination: string; fullMatch: string }[] = [];
+
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    matches.push({
+      destination: match[1],
+      fullMatch: match[0],
+    });
+  }
+
+  return matches;
+}
+
+/**
+ * Remove navigation tags from text for display
+ */
+export function stripNavigationTags(text: string): string {
+  return text.replace(/\[navigate:[^\]]+\]/g, '').trim();
+}

package/packages/react/src/hooks/useServiceWorker.ts

@@ -0,0 +1,278 @@
+/**
+ * Service Worker Hooks - Client communication with Aeon SW
+ *
+ * Provides React hooks for:
+ * - Total preload progress tracking
+ * - Cache status monitoring
+ * - Manual preload triggers
+ */
+
+import { useEffect, useState, useCallback, useRef } from 'react';
+
+export interface PreloadProgress {
+  loaded: number;
+  total: number;
+  percentage: number;
+  isComplete: boolean;
+  cachedRoutes: string[];
+}
+
+export interface CacheStatus {
+  cached: number;
+  total: number;
+  routes: string[];
+  isReady: boolean;
+}
+
+/**
+ * Hook to register and track the Aeon service worker
+ */
+export function useAeonServiceWorker() {
+  const [isRegistered, setIsRegistered] = useState(false);
+  const [isActive, setIsActive] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const registrationRef = useRef<ServiceWorkerRegistration | null>(null);
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const registerSW = async () => {
+      try {
+        const registration = await navigator.serviceWorker.register(
+          '/.aeon/sw.js',
+          { scope: '/' },
+        );
+
+        registrationRef.current = registration;
+        setIsRegistered(true);
+
+        // Check if active
+        if (registration.active) {
+          setIsActive(true);
+        }
+
+        // Listen for state changes
+        registration.addEventListener('updatefound', () => {
+          const newWorker = registration.installing;
+          if (newWorker) {
+            newWorker.addEventListener('statechange', () => {
+              if (newWorker.state === 'activated') {
+                setIsActive(true);
+              }
+            });
+          }
+        });
+      } catch (err) {
+        setError(
+          err instanceof Error ? err : new Error('Failed to register SW'),
+        );
+      }
+    };
+
+    registerSW();
+  }, []);
+
+  const update = useCallback(async () => {
+    if (registrationRef.current) {
+      await registrationRef.current.update();
+    }
+  }, []);
+
+  const unregister = useCallback(async () => {
+    if (registrationRef.current) {
+      await registrationRef.current.unregister();
+      setIsRegistered(false);
+      setIsActive(false);
+    }
+  }, []);
+
+  return {
+    isRegistered,
+    isActive,
+    error,
+    update,
+    unregister,
+  };
+}
+
+/**
+ * Hook to track total preload progress
+ */
+export function usePreloadProgress(): PreloadProgress {
+  const [progress, setProgress] = useState<PreloadProgress>({
+    loaded: 0,
+    total: 0,
+    percentage: 0,
+    isComplete: false,
+    cachedRoutes: [],
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const handleMessage = (event: MessageEvent) => {
+      const data = event.data;
+
+      if (data.type === 'PRELOAD_PROGRESS') {
+        setProgress({
+          loaded: data.loaded,
+          total: data.total,
+          percentage: data.percentage,
+          isComplete: false,
+          cachedRoutes: [],
+        });
+      } else if (data.type === 'PRELOAD_COMPLETE') {
+        setProgress({
+          loaded: data.loaded,
+          total: data.total,
+          percentage: 100,
+          isComplete: true,
+          cachedRoutes: data.cachedRoutes || [],
+        });
+      }
+    };
+
+    navigator.serviceWorker.addEventListener('message', handleMessage);
+
+    return () => {
+      navigator.serviceWorker.removeEventListener('message', handleMessage);
+    };
+  }, []);
+
+  return progress;
+}
+
+/**
+ * Hook to get current cache status
+ */
+export function useCacheStatus(): CacheStatus & { refresh: () => void } {
+  const [status, setStatus] = useState<CacheStatus>({
+    cached: 0,
+    total: 0,
+    routes: [],
+    isReady: false,
+  });
+
+  const refresh = useCallback(async () => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const controller = navigator.serviceWorker.controller;
+    if (!controller) {
+      return;
+    }
+
+    // Use MessageChannel for request/response
+    const channel = new MessageChannel();
+
+    channel.port1.onmessage = (event: MessageEvent) => {
+      const data = event.data;
+      setStatus({
+        cached: data.cached,
+        total: data.total,
+        routes: data.routes,
+        isReady: data.cached === data.total && data.total > 0,
+      });
+    };
+
+    controller.postMessage({ type: 'GET_CACHE_STATUS' }, [channel.port2]);
+  }, []);
+
+  useEffect(() => {
+    // Initial fetch
+    refresh();
+
+    // Refresh periodically
+    const interval = setInterval(refresh, 5000);
+    return () => clearInterval(interval);
+  }, [refresh]);
+
+  return { ...status, refresh };
+}
+
+/**
+ * Hook to trigger manual preload
+ */
+export function useManualPreload() {
+  const [isPreloading, setIsPreloading] = useState(false);
+  const progress = usePreloadProgress();
+
+  const triggerPreload = useCallback(() => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const controller = navigator.serviceWorker.controller;
+    if (!controller) {
+      return;
+    }
+
+    setIsPreloading(true);
+    controller.postMessage({ type: 'TRIGGER_PRELOAD' });
+  }, []);
+
+  // Reset isPreloading when complete
+  useEffect(() => {
+    if (progress.isComplete) {
+      setIsPreloading(false);
+    }
+  }, [progress.isComplete]);
+
+  return {
+    triggerPreload,
+    isPreloading,
+    progress,
+  };
+}
+
+/**
+ * Hook to prefetch a specific route
+ */
+export function usePrefetchRoute() {
+  const prefetch = useCallback((route: string) => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const controller = navigator.serviceWorker.controller;
+    if (!controller) {
+      return;
+    }
+
+    controller.postMessage({ type: 'PREFETCH_ROUTE', route });
+  }, []);
+
+  return prefetch;
+}
+
+/**
+ * Hook to clear the cache
+ */
+export function useClearCache() {
+  const [isClearing, setIsClearing] = useState(false);
+
+  const clearCache = useCallback(async () => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const controller = navigator.serviceWorker.controller;
+    if (!controller) {
+      return;
+    }
+
+    setIsClearing(true);
+    controller.postMessage({ type: 'CLEAR_CACHE' });
+
+    // Wait a bit for cache to clear
+    await new Promise((r) => setTimeout(r, 100));
+    setIsClearing(false);
+  }, []);
+
+  return { clearCache, isClearing };
+}

package/packages/react/src/hooks.ts

@@ -0,0 +1,195 @@
+/**
+ * Additional React hooks for Aeon Pages
+ */
+
+import { useEffect, useRef, useCallback, useState } from 'react';
+import { useAeonPage, type PresenceUser } from './provider';
+
+/**
+ * useAeonVersion - Access version and migration tools
+ */
+export function useAeonVersion() {
+  const { version, migrate } = useAeonPage();
+  return { ...version, migrate };
+}
+
+/**
+ * useAeonTree - Access the component tree for advanced manipulation
+ */
+export function useAeonTree() {
+  const { tree, updateTree } = useAeonPage();
+  return { tree, updateTree };
+}
+
+/**
+ * useCursorTracking - Automatically track cursor movement
+ */
+export function useCursorTracking(enabled = true) {
+  const { updateCursor } = useAeonPage();
+  const throttleRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleMouseMove = (e: MouseEvent) => {
+      // Throttle to ~60fps
+      if (throttleRef.current) return;
+
+      throttleRef.current = window.requestAnimationFrame(() => {
+        updateCursor({ x: e.clientX, y: e.clientY });
+        throttleRef.current = null;
+      });
+    };
+
+    window.addEventListener('mousemove', handleMouseMove);
+    return () => {
+      window.removeEventListener('mousemove', handleMouseMove);
+      if (throttleRef.current) {
+        window.cancelAnimationFrame(throttleRef.current);
+      }
+    };
+  }, [enabled, updateCursor]);
+}
+
+/**
+ * useEditableElement - Make an element collaboratively editable
+ */
+export function useEditableElement(elementPath: string) {
+  const { updateEditing, updateTree, localUser } = useAeonPage();
+  const [isFocused, setIsFocused] = useState(false);
+
+  const onFocus = useCallback(() => {
+    setIsFocused(true);
+    updateEditing(elementPath);
+  }, [elementPath, updateEditing]);
+
+  const onBlur = useCallback(() => {
+    setIsFocused(false);
+    updateEditing(null);
+  }, [updateEditing]);
+
+  const onChange = useCallback(
+    (value: unknown) => {
+      updateTree(elementPath, value);
+    },
+    [elementPath, updateTree],
+  );
+
+  return {
+    isFocused,
+    isBeingEditedByOther: false, // Would check presence
+    onFocus,
+    onBlur,
+    onChange,
+  };
+}
+
+/**
+ * useOtherCursors - Get cursors of other users (excluding self)
+ */
+export function useOtherCursors(): PresenceUser[] {
+  const { presence, localUser } = useAeonPage();
+  return presence.filter((user) => user.userId !== localUser?.userId);
+}
+
+/**
+ * useOfflineStatus - Track offline status and pending operations
+ */
+export function useOfflineStatus() {
+  const { sync } = useAeonPage();
+  return {
+    isOffline: !sync.isOnline,
+    isSyncing: sync.isSyncing,
+    pendingOperations: sync.pendingOperations,
+    lastSyncAt: sync.lastSyncAt,
+  };
+}
+
+/**
+ * useCollaborativeInput - Hook for collaborative text input
+ *
+ * @example
+ * ```tsx
+ * function EditableTitle() {
+ *   const { value, onChange, onFocus, onBlur, isEditing, editingBy } = useCollaborativeInput('title');
+ *
+ *   return (
+ *     <input
+ *       value={value}
+ *       onChange={(e) => onChange(e.target.value)}
+ *       onFocus={onFocus}
+ *       onBlur={onBlur}
+ *       style={{ borderColor: editingBy ? 'blue' : undefined }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useCollaborativeInput(key: string) {
+  const { data, setData, presence, localUser, updateEditing } = useAeonPage();
+  const [isEditing, setIsEditing] = useState(false);
+
+  const value = (data[key] as string) ?? '';
+
+  // Find if someone else is editing this field
+  const editingBy = presence.find(
+    (user) => user.editing === key && user.userId !== localUser?.userId,
+  );
+
+  const onChange = useCallback(
+    (newValue: string) => {
+      setData(key, newValue);
+    },
+    [key, setData],
+  );
+
+  const onFocus = useCallback(() => {
+    setIsEditing(true);
+    updateEditing(key);
+  }, [key, updateEditing]);
+
+  const onBlur = useCallback(() => {
+    setIsEditing(false);
+    updateEditing(null);
+  }, [updateEditing]);
+
+  return {
+    value,
+    onChange,
+    onFocus,
+    onBlur,
+    isEditing,
+    editingBy,
+  };
+}
+
+/**
+ * useAeonEffect - Run effect when Aeon data changes
+ */
+export function useAeonEffect(
+  key: string,
+  effect: (value: unknown) => void | (() => void),
+) {
+  const { data } = useAeonPage();
+  const value = data[key];
+
+  useEffect(() => {
+    return effect(value);
+  }, [value, effect]);
+}
+
+/**
+ * useSessionId - Get the current session ID
+ */
+export function useSessionId(): string {
+  const { sessionId } = useAeonPage();
+  return sessionId;
+}
+
+/**
+ * useRoute - Get the current route
+ */
+export function useRoute(): string {
+  const { route } = useAeonPage();
+  return route;
+}