@affectively/aeon-pages-react 0.2.0

package/dist/Link.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Aeon Link Component
+ *
+ * Drop-in replacement for <a> with superpowers:
+ * - Visibility-based prefetch
+ * - Hover prefetch
+ * - Intent detection (cursor trajectory)
+ * - View transitions
+ * - Presence awareness
+ * - Total preload support
+ */
+import React, { type ReactNode, type AnchorHTMLAttributes } from 'react';
+export type TransitionType = 'slide' | 'fade' | 'morph' | 'none';
+export type PrefetchStrategy = 'hover' | 'visible' | 'intent' | 'none';
+export interface PresenceRenderProps {
+    count: number;
+    editing: number;
+    hot: boolean;
+    users?: {
+        userId: string;
+        name?: string;
+    }[];
+}
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children'> {
+    href: string;
+    prefetch?: PrefetchStrategy;
+    transition?: TransitionType;
+    showPresence?: boolean;
+    preloadData?: boolean;
+    replace?: boolean;
+    children?: ReactNode | ((props: {
+        presence: PresenceRenderProps | null;
+    }) => ReactNode);
+    onNavigateStart?: () => void;
+    onNavigateEnd?: () => void;
+}
+export declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;

package/dist/components/InstallPrompt.d.ts

@@ -0,0 +1,59 @@
+/**
+ * InstallPrompt Component
+ *
+ * PWA install prompt component for web applications.
+ * Handles beforeinstallprompt event and iOS-specific instructions.
+ *
+ * Features:
+ * - Cross-browser install prompt handling
+ * - iOS-specific installation instructions
+ * - Standalone mode detection
+ * - Customizable UI via render props
+ * - Headless hook export
+ */
+import { type ReactNode } from 'react';
+interface BeforeInstallPromptEvent extends Event {
+    prompt: () => Promise<void>;
+    userChoice: Promise<{
+        outcome: 'accepted' | 'dismissed';
+    }>;
+}
+export interface InstallPromptState {
+    /** Whether the app can be installed */
+    canInstall: boolean;
+    /** Whether the app is already installed (standalone mode) */
+    isInstalled: boolean;
+    /** Whether on iOS */
+    isIOS: boolean;
+    /** Trigger the install prompt (Chrome/Edge) */
+    install: () => Promise<'accepted' | 'dismissed' | 'unavailable'>;
+    /** Dismiss the install prompt */
+    dismiss: () => void;
+}
+export interface InstallPromptProps {
+    /** Render when app is already installed */
+    renderInstalled?: () => ReactNode;
+    /** Render install prompt (receives install function) */
+    renderPrompt?: (state: InstallPromptState) => ReactNode;
+    /** Render iOS-specific instructions */
+    renderIOSInstructions?: () => ReactNode;
+    /** Only show when install is available */
+    showOnlyWhenInstallable?: boolean;
+    /** CSS class for container */
+    className?: string;
+}
+/**
+ * Hook for managing PWA install prompt
+ */
+export declare function useInstallPrompt(): InstallPromptState;
+/**
+ * PWA install prompt component
+ */
+export declare function InstallPrompt({ renderInstalled, renderPrompt, renderIOSInstructions, showOnlyWhenInstallable, className, }: InstallPromptProps): ReactNode;
+declare global {
+    interface WindowEventMap {
+        beforeinstallprompt: BeforeInstallPromptEvent;
+        appinstalled: Event;
+    }
+}
+export default InstallPrompt;

package/dist/components/OfflineDiagnostics.d.ts

@@ -0,0 +1,78 @@
+/**
+ * OfflineDiagnostics Component
+ *
+ * Comprehensive diagnostics panel for offline-first applications.
+ * Shows network status, service worker state, cache management, and queue stats.
+ *
+ * Features:
+ * - Network status monitoring
+ * - Service worker status display
+ * - Cache management UI
+ * - Queue statistics display
+ * - Conflict resolution UI
+ * - Composable panels
+ */
+import { type ReactNode } from 'react';
+export interface ServiceWorkerState {
+    isSupported: boolean;
+    registration: 'none' | 'installing' | 'waiting' | 'active';
+    updateAvailable: boolean;
+    controller: boolean;
+}
+export interface CacheInfo {
+    name: string;
+    itemCount: number;
+    sampleUrls: string[];
+}
+export interface QueueStats {
+    pending: number;
+    syncing: number;
+    synced: number;
+    failed: number;
+    totalBytes: number;
+}
+export interface OfflineDiagnosticsProps {
+    /** Show network status panel */
+    showNetworkStatus?: boolean;
+    /** Show service worker panel */
+    showServiceWorker?: boolean;
+    /** Show cache management panel */
+    showCacheManagement?: boolean;
+    /** Show queue statistics panel */
+    showQueueStats?: boolean;
+    /** Show conflict resolution panel */
+    showConflicts?: boolean;
+    /** Callback when cache is cleared */
+    onClearCache?: (cacheName?: string) => Promise<void>;
+    /** CSS class for container */
+    className?: string;
+}
+/**
+ * Network Status Panel
+ */
+export declare function NetworkStatusPanel(): ReactNode;
+/**
+ * Service Worker Panel
+ */
+export declare function ServiceWorkerPanel(): ReactNode;
+/**
+ * Cache Management Panel
+ */
+export declare function CacheManagementPanel({ onClearCache, }: {
+    onClearCache?: (cacheName?: string) => Promise<void>;
+}): ReactNode;
+/**
+ * Queue Stats Panel
+ */
+export declare function QueueStatsPanel({ stats, }: {
+    stats?: QueueStats;
+}): ReactNode;
+/**
+ * Conflicts Panel
+ */
+export declare function ConflictsPanel(): ReactNode;
+/**
+ * Comprehensive offline diagnostics panel
+ */
+export declare function OfflineDiagnostics({ showNetworkStatus, showServiceWorker, showCacheManagement, showQueueStats, showConflicts, onClearCache, className, }: OfflineDiagnosticsProps): ReactNode;
+export default OfflineDiagnostics;

package/dist/components/PushNotifications.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PushNotifications Component
+ *
+ * Push notification management component for PWA applications.
+ * Handles subscription, permission, and notification sending.
+ *
+ * Features:
+ * - VAPID-based push subscription
+ * - Permission handling
+ * - Subscription serialization
+ * - Customizable UI via render props
+ * - Headless hook export
+ */
+import { type ReactNode } from 'react';
+export interface PushSubscriptionData {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+export interface PushNotificationState {
+    /** Whether push is supported */
+    isSupported: boolean;
+    /** Current permission state */
+    permission: NotificationPermission | 'unsupported';
+    /** Current subscription (if subscribed) */
+    subscription: PushSubscriptionData | null;
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** Last error message */
+    error: string | null;
+    /** Subscribe to push notifications */
+    subscribe: () => Promise<PushSubscriptionData | null>;
+    /** Unsubscribe from push notifications */
+    unsubscribe: () => Promise<boolean>;
+    /** Request permission */
+    requestPermission: () => Promise<NotificationPermission>;
+    /** Clear error */
+    clearError: () => void;
+}
+export interface PushNotificationsProps {
+    /** VAPID public key */
+    vapidPublicKey?: string;
+    /** Called when subscription changes */
+    onSubscribe?: (subscription: PushSubscriptionData) => Promise<void> | void;
+    /** Called when unsubscribing */
+    onUnsubscribe?: (endpoint: string) => Promise<void> | void;
+    /** Custom render function */
+    render?: (state: PushNotificationState) => ReactNode;
+    /** Show default UI */
+    showUI?: boolean;
+    /** CSS class for container */
+    className?: string;
+}
+export interface UsePushNotificationsConfig {
+    /** VAPID public key */
+    vapidPublicKey?: string;
+    /** Service worker URL */
+    serviceWorkerUrl?: string;
+}
+/**
+ * Hook for managing push notifications
+ */
+export declare function usePushNotifications(config?: UsePushNotificationsConfig): PushNotificationState;
+/**
+ * Push notifications management component
+ */
+export declare function PushNotifications({ vapidPublicKey, onSubscribe, onUnsubscribe, render, showUI, className, }: PushNotificationsProps): ReactNode;
+export default PushNotifications;

package/dist/hooks/useAeonNavigation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Aeon Navigation Hooks
+ *
+ * React hooks for the cutting-edge navigation system.
+ * The navigation state itself is an Aeon - the site is a session.
+ *
+ * Recursive Aeon Architecture:
+ * - Component = Aeon entity
+ * - Page = Aeon session
+ * - Site = Aeon of sessions (routes are collaborative)
+ * - Federation = Aeon of Aeons (cross-site sync)
+ */
+import type { AeonNavigationEngine, NavigationOptions, PrefetchOptions, NavigationState, RoutePresenceInfo } from '@affectively/aeon-pages-runtime';
+export interface NavigationPrediction {
+    route: string;
+    probability: number;
+    reason: 'history' | 'hover' | 'visibility' | 'community';
+}
+export interface AeonNavigationContextValue {
+    navigator: AeonNavigationEngine;
+}
+export declare const AeonNavigationContext: import("react").Context<AeonNavigationContextValue | null>;
+/**
+ * Main navigation hook - provides navigation, prefetch, and state
+ */
+export declare function useAeonNavigation(): {
+    current: string;
+    previous: string | null;
+    history: string[];
+    isNavigating: boolean;
+    navigate: (href: string, options?: NavigationOptions) => Promise<void>;
+    prefetch: (href: string, options?: PrefetchOptions) => Promise<void>;
+    back: () => Promise<void>;
+    preloadAll: (onProgress?: (loaded: number, total: number) => void) => Promise<void>;
+    isPreloaded: (href: string) => boolean;
+    getCacheStats: () => import("@affectively/aeon-pages-runtime").CacheStats;
+};
+/**
+ * Route Presence hook - subscribe to who's viewing/editing routes
+ *
+ * Presence flows upward through the Aeon hierarchy:
+ * - Page presence = users on this page
+ * - Site presence = aggregate of all page presence
+ * - Federation presence = aggregate across sites
+ *
+ * Note: This is different from usePresence in provider.tsx which is for
+ * page-level editing presence. This hook is for navigation-level presence
+ * (who's viewing what routes before you navigate there).
+ */
+export declare function useRoutePresence(): {
+    getPresence: (route: string) => RoutePresenceInfo | null;
+    subscribePresence: (callback: (route: string, presence: RoutePresenceInfo) => void) => (() => void);
+};
+/**
+ * Navigation prediction hook
+ */
+export declare function useNavigationPrediction(): {
+    predict: (fromRoute?: string) => NavigationPrediction[];
+};
+/**
+ * Hook for observing links and auto-prefetching
+ */
+export declare function useLinkObserver(containerRef: React.RefObject<Element>): {
+    observe: () => () => void;
+};
+/**
+ * Hook for total preload progress
+ */
+export declare function useTotalPreload(): {
+    startPreload: (onProgress?: (loaded: number, total: number) => void) => Promise<void>;
+    getStats: () => import("@affectively/aeon-pages-runtime").CacheStats;
+};
+export type { NavigationOptions, PrefetchOptions, NavigationState, RoutePresenceInfo };

package/dist/hooks/useConflicts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * useConflicts Hook
+ *
+ * React hook for managing conflicts in offline-first applications.
+ * Provides access to conflict list, resolution methods, and statistics.
+ */
+export type ResolutionStrategy = 'local-wins' | 'remote-wins' | 'merge' | 'last-modified' | 'manual';
+export interface Conflict {
+    id: string;
+    operationId: string;
+    sessionId: string;
+    localData: Record<string, unknown>;
+    remoteData: Record<string, unknown>;
+    type: 'update_update' | 'delete_update' | 'update_delete' | 'concurrent';
+    severity: 'low' | 'medium' | 'high';
+    detectedAt: number;
+    resolution?: {
+        strategy: ResolutionStrategy;
+        resolvedData: Record<string, unknown>;
+        resolvedAt: number;
+        resolvedBy?: string;
+    };
+}
+export interface ConflictStats {
+    total: number;
+    unresolved: number;
+    highSeverity: number;
+    byType: Record<Conflict['type'], number>;
+    byStrategy: Record<ResolutionStrategy, number>;
+}
+export interface UseConflictsResult {
+    /** All conflicts */
+    conflicts: Conflict[];
+    /** Unresolved conflicts only */
+    unresolvedConflicts: Conflict[];
+    /** High severity conflicts */
+    highSeverityConflicts: Conflict[];
+    /** Conflict statistics */
+    stats: ConflictStats;
+    /** Resolve a conflict */
+    resolveConflict: (conflictId: string, strategy: ResolutionStrategy, customData?: Record<string, unknown>) => Promise<void>;
+    /** Dismiss a conflict (remove without resolution) */
+    dismissConflict: (conflictId: string) => void;
+    /** Clear all resolved conflicts */
+    clearResolved: () => void;
+    /** Refresh conflicts from source */
+    refresh: () => void;
+    /** Whether conflicts are loading */
+    isLoading: boolean;
+}
+/**
+ * Hook to manage conflicts in offline-first applications
+ */
+export declare function useConflicts(sessionId?: string): UseConflictsResult;
+/**
+ * Add a conflict to the store (for testing or external integration)
+ */
+export declare function addConflict(conflict: Conflict): void;
+/**
+ * Get all conflicts from the store
+ */
+export declare function getAllConflicts(): Conflict[];
+/**
+ * Clear all conflicts
+ */
+export declare function clearAllConflicts(): void;
+export default useConflicts;

package/dist/hooks/useNetworkState.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useNetworkState Hook
+ *
+ * React hook for monitoring network state and bandwidth.
+ * Provides real-time updates on connection quality and effective type.
+ */
+export type NetworkState = 'online' | 'offline' | 'poor' | 'unknown';
+export interface BandwidthProfile {
+    /** Estimated bandwidth in Kbps */
+    speedKbps: number;
+    /** Estimated latency in ms */
+    latencyMs: number;
+    /** Reliability score (0-1) */
+    reliability: number;
+    /** Effective connection type */
+    effectiveType: '2g' | '3g' | '4g' | 'slow-2g' | 'unknown';
+}
+export interface NetworkStateResult {
+    /** Current network state */
+    state: NetworkState;
+    /** Whether currently online */
+    isOnline: boolean;
+    /** Whether on poor connection */
+    isPoor: boolean;
+    /** Bandwidth profile */
+    bandwidth: BandwidthProfile;
+    /** Time since last state change */
+    timeSinceChange: number;
+    /** Force refresh network state */
+    refresh: () => void;
+}
+/**
+ * Hook to monitor network state and bandwidth
+ */
+export declare function useNetworkState(): NetworkStateResult;
+export default useNetworkState;

package/dist/hooks/usePilotNavigation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { type NavigationOptions } from './useAeonNavigation';
+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 declare function usePilotNavigation(options?: {
+    /** Custom consent handler (if not provided, uses built-in pending state) */
+    onConsentRequired?: NavigationConsentCallback;
+    /** Maximum intent history to keep */
+    maxHistory?: number;
+}): {
+    pendingIntent: PilotNavigationIntent | null;
+    intentHistory: PilotNavigationIntent[];
+    isNavigating: boolean;
+    current: string;
+    pilot: (destination: string, pilotOptions?: PilotNavigationOptions) => Promise<boolean>;
+    approve: () => Promise<boolean>;
+    reject: () => void;
+    clearPending: () => void;
+    navigateDirect: (destination: string, navOptions?: NavigationOptions) => Promise<void>;
+    prefetch: (href: string, options?: import("@affectively/aeon-pages-runtime").PrefetchOptions) => Promise<void>;
+    back: () => Promise<void>;
+    isPreloaded: (href: string) => boolean;
+};
+/**
+ * Parse navigation tags from AI response
+ * Returns array of destinations extracted from [navigate:/path] tags
+ */
+export declare function parseNavigationTags(text: string): {
+    destination: string;
+    fullMatch: string;
+}[];
+/**
+ * Remove navigation tags from text for display
+ */
+export declare function stripNavigationTags(text: string): string;
+export {};

package/dist/hooks/useServiceWorker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Service Worker Hooks - Client communication with Aeon SW
+ *
+ * Provides React hooks for:
+ * - Total preload progress tracking
+ * - Cache status monitoring
+ * - Manual preload triggers
+ */
+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 declare function useAeonServiceWorker(): {
+    isRegistered: boolean;
+    isActive: boolean;
+    error: Error | null;
+    update: () => Promise<void>;
+    unregister: () => Promise<void>;
+};
+/**
+ * Hook to track total preload progress
+ */
+export declare function usePreloadProgress(): PreloadProgress;
+/**
+ * Hook to get current cache status
+ */
+export declare function useCacheStatus(): CacheStatus & {
+    refresh: () => void;
+};
+/**
+ * Hook to trigger manual preload
+ */
+export declare function useManualPreload(): {
+    triggerPreload: () => void;
+    isPreloading: boolean;
+    progress: PreloadProgress;
+};
+/**
+ * Hook to prefetch a specific route
+ */
+export declare function usePrefetchRoute(): (route: string) => void;
+/**
+ * Hook to clear the cache
+ */
+export declare function useClearCache(): {
+    clearCache: () => Promise<void>;
+    isClearing: boolean;
+};

package/dist/hooks.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Additional React hooks for Aeon Pages
+ */
+import { type PresenceUser } from './provider';
+/**
+ * useAeonVersion - Access version and migration tools
+ */
+export declare function useAeonVersion(): {
+    migrate: (toVersion: string) => Promise<void>;
+    current: string;
+    latest: string;
+    needsMigration: boolean;
+};
+/**
+ * useAeonTree - Access the component tree for advanced manipulation
+ */
+export declare function useAeonTree(): {
+    tree: unknown;
+    updateTree: (path: string, value: unknown) => void;
+};
+/**
+ * useCursorTracking - Automatically track cursor movement
+ */
+export declare function useCursorTracking(enabled?: boolean): void;
+/**
+ * useEditableElement - Make an element collaboratively editable
+ */
+export declare function useEditableElement(elementPath: string): {
+    isFocused: boolean;
+    isBeingEditedByOther: boolean;
+    onFocus: () => void;
+    onBlur: () => void;
+    onChange: (value: unknown) => void;
+};
+/**
+ * useOtherCursors - Get cursors of other users (excluding self)
+ */
+export declare function useOtherCursors(): PresenceUser[];
+/**
+ * useOfflineStatus - Track offline status and pending operations
+ */
+export declare function useOfflineStatus(): {
+    isOffline: boolean;
+    isSyncing: boolean;
+    pendingOperations: number;
+    lastSyncAt: string | undefined;
+};
+/**
+ * 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 declare function useCollaborativeInput(key: string): {
+    value: string;
+    onChange: (newValue: string) => void;
+    onFocus: () => void;
+    onBlur: () => void;
+    isEditing: boolean;
+    editingBy: PresenceUser | undefined;
+};
+/**
+ * useAeonEffect - Run effect when Aeon data changes
+ */
+export declare function useAeonEffect(key: string, effect: (value: unknown) => void | (() => void)): void;
+/**
+ * useSessionId - Get the current session ID
+ */
+export declare function useSessionId(): string;
+/**
+ * useRoute - Get the current route
+ */
+export declare function useRoute(): string;