@affectively/aeon-flux 0.3.0

package/packages/react/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @affectively/aeon-pages/react
+ *
+ * React bindings for Aeon Pages - collaborative editing with hooks.
+ *
+ * The Aeon architecture is recursive (fractal):
+ * - Component = Aeon entity
+ * - Page = Aeon session
+ * - Site = Aeon of sessions (routes are collaborative)
+ * - Federation = Aeon of Aeons (cross-site sync)
+ *
+ * @example
+ * ```tsx
+ * 'use aeon';
+ *
+ * import { Link, useAeonPage, usePresence, useAeonData } from '@affectively/aeon-pages/react';
+ *
+ * export default function Page() {
+ *   const { presence, localUser, updateCursor } = usePresence();
+ *   const [title, setTitle] = useAeonData<string>('title');
+ *
+ *   return (
+ *     <div onMouseMove={(e) => updateCursor({ x: e.clientX, y: e.clientY })}>
+ *       <h1 contentEditable onInput={(e) => setTitle(e.currentTarget.textContent)}>
+ *         {title || 'Untitled'}
+ *       </h1>
+ *
+ *       <Link href="/about" prefetch="visible" showPresence>
+ *         About (3 viewing)
+ *       </Link>
+ *
+ *       {presence.map((user) => (
+ *         <Cursor key={user.userId} user={user} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+// Link component with prefetch/transitions/presence
+export { Link, type LinkProps, type TransitionType, type PrefetchStrategy, type PresenceRenderProps } from './Link';
+
+// Provider and main hook
+export {
+  AeonPageProvider,
+  useAeonPage,
+  type AeonPageProviderProps,
+  type AeonPageContextValue,
+  type PresenceUser,
+  type SyncState,
+  type VersionInfo,
+} from './provider';
+
+// Convenience hooks (page-level editing)
+export { usePresence, useAeonSync, useAeonData } from './provider';
+
+// Navigation hooks (route-level navigation)
+export {
+  useAeonNavigation,
+  useNavigationPrediction,
+  useLinkObserver,
+  useTotalPreload,
+  useRoutePresence,
+  AeonNavigationContext,
+  type AeonNavigationContextValue,
+} from './hooks/useAeonNavigation';
+
+// Service worker hooks (total preload)
+export {
+  useAeonServiceWorker,
+  usePreloadProgress,
+  useCacheStatus,
+  useManualPreload,
+  usePrefetchRoute,
+  useClearCache,
+  type PreloadProgress,
+  type CacheStatus,
+} from './hooks/useServiceWorker';
+
+// Pilot navigation hooks (AI-driven navigation with consent)
+export {
+  usePilotNavigation,
+  parseNavigationTags,
+  stripNavigationTags,
+  type PilotNavigationIntent,
+  type PilotNavigationOptions,
+  type PilotNavigationState,
+} from './hooks/usePilotNavigation';

package/packages/react/src/provider.tsx

@@ -0,0 +1,428 @@
+/**
+ * AeonPageProvider - Context provider for Aeon Pages
+ *
+ * Provides:
+ * - Real-time sync via Aeon SyncCoordinator
+ * - Presence tracking via AgentPresenceManager
+ * - Offline support via OfflineOperationQueue
+ * - Schema versioning via SchemaVersionManager
+ */
+
+import React, { createContext, useContext, useEffect, useState, useCallback, useRef, type ReactNode } from 'react';
+
+// Types
+export interface PresenceUser {
+  userId: string;
+  role: 'user' | 'assistant' | 'monitor' | 'admin';
+  cursor?: { x: number; y: number };
+  editing?: string;
+  status: 'online' | 'away' | 'offline';
+  lastActivity: string;
+}
+
+export interface SyncState {
+  isOnline: boolean;
+  isSyncing: boolean;
+  lastSyncAt?: string;
+  pendingOperations: number;
+}
+
+export interface VersionInfo {
+  current: string;
+  latest: string;
+  needsMigration: boolean;
+}
+
+export interface AeonPageContextValue {
+  // Route info
+  route: string;
+  sessionId: string;
+
+  // Presence
+  presence: PresenceUser[];
+  localUser: PresenceUser | null;
+  updateCursor: (position: { x: number; y: number }) => void;
+  updateEditing: (elementPath: string | null) => void;
+
+  // Sync
+  sync: SyncState;
+  forcSync: () => Promise<void>;
+
+  // Versioning
+  version: VersionInfo;
+  migrate: (toVersion: string) => Promise<void>;
+
+  // Data
+  data: Record<string, unknown>;
+  setData: (key: string, value: unknown) => void;
+
+  // Component tree
+  tree: unknown;
+  updateTree: (path: string, value: unknown) => void;
+}
+
+const AeonPageContext = createContext<AeonPageContextValue | null>(null);
+
+export interface AeonPageProviderProps {
+  route: string;
+  children: ReactNode;
+  initialData?: Record<string, unknown>;
+}
+
+/**
+ * AeonPageProvider - Wraps a page with Aeon collaborative features
+ */
+export function AeonPageProvider({ route, children, initialData = {} }: AeonPageProviderProps) {
+  // Generate session ID from route
+  const sessionId = route.replace(/^\/|\/$/g, '').replace(/\//g, '-') || 'index';
+
+  // State
+  const [presence, setPresence] = useState<PresenceUser[]>([]);
+  const [localUser, setLocalUser] = useState<PresenceUser | null>(null);
+  const [sync, setSync] = useState<SyncState>({
+    isOnline: typeof navigator !== 'undefined' ? navigator.onLine : true,
+    isSyncing: false,
+    pendingOperations: 0,
+  });
+  const [version, setVersion] = useState<VersionInfo>({
+    current: '1.0.0',
+    latest: '1.0.0',
+    needsMigration: false,
+  });
+  const [data, setDataState] = useState<Record<string, unknown>>(initialData);
+  const [tree, setTree] = useState<unknown>(null);
+
+  // Refs for Aeon modules (lazy loaded)
+  const syncCoordinatorRef = useRef<unknown>(null);
+  const presenceManagerRef = useRef<unknown>(null);
+  const offlineQueueRef = useRef<unknown>(null);
+  const versionManagerRef = useRef<unknown>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+
+  // Initialize Aeon modules
+  useEffect(() => {
+    const initAeon = async () => {
+      try {
+        // Dynamic import to avoid SSR issues
+        const aeon = await import('@affectively/aeon');
+
+        // Initialize sync coordinator
+        syncCoordinatorRef.current = new aeon.SyncCoordinator();
+
+        // Initialize presence manager
+        presenceManagerRef.current = aeon.AgentPresenceManager.getInstance(sessionId);
+
+        // Initialize offline queue
+        offlineQueueRef.current = aeon.OfflineOperationQueue.getInstance();
+
+        // Initialize version manager
+        versionManagerRef.current = new aeon.SchemaVersionManager();
+
+        // Set up local user
+        const userId = generateUserId();
+        setLocalUser({
+          userId,
+          role: 'user',
+          status: 'online',
+          lastActivity: new Date().toISOString(),
+        });
+
+        // Connect WebSocket for real-time sync
+        connectWebSocket(sessionId);
+      } catch (error) {
+        console.warn('[aeon-provider] Aeon modules not available:', error);
+      }
+    };
+
+    initAeon();
+
+    // Cleanup
+    return () => {
+      wsRef.current?.close();
+    };
+  }, [sessionId]);
+
+  // Online/offline detection
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleOnline = () => {
+      setSync((prev) => ({ ...prev, isOnline: true }));
+      // Flush offline queue
+      flushOfflineQueue();
+    };
+
+    const handleOffline = () => {
+      setSync((prev) => ({ ...prev, isOnline: false }));
+    };
+
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+
+    return () => {
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+    };
+  }, []);
+
+  // Connect WebSocket
+  const connectWebSocket = useCallback((sessionId: string) => {
+    if (typeof window === 'undefined') return;
+
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${window.location.host}/_aeon/ws?session=${sessionId}`;
+
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+
+    ws.onopen = () => {
+      console.log('[aeon-provider] WebSocket connected');
+      // Join session
+      ws.send(JSON.stringify({ type: 'join', sessionId }));
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const message = JSON.parse(event.data);
+        handleSyncMessage(message);
+      } catch (error) {
+        console.error('[aeon-provider] Error parsing message:', error);
+      }
+    };
+
+    ws.onclose = () => {
+      console.log('[aeon-provider] WebSocket disconnected');
+      // Reconnect after delay
+      setTimeout(() => connectWebSocket(sessionId), 1000);
+    };
+
+    ws.onerror = (error) => {
+      console.error('[aeon-provider] WebSocket error:', error);
+    };
+  }, []);
+
+  // Handle incoming sync messages
+  const handleSyncMessage = useCallback((message: unknown) => {
+    const msg = message as { type: string; [key: string]: unknown };
+
+    switch (msg.type) {
+      case 'presence-update':
+        setPresence(msg.users as PresenceUser[]);
+        break;
+
+      case 'data-update':
+        setDataState((prev) => ({
+          ...prev,
+          ...(msg.data as Record<string, unknown>),
+        }));
+        break;
+
+      case 'tree-update':
+        setTree(msg.tree);
+        break;
+
+      case 'version-info':
+        setVersion(msg.version as VersionInfo);
+        break;
+    }
+  }, []);
+
+  // Flush offline queue when back online
+  const flushOfflineQueue = useCallback(async () => {
+    if (!offlineQueueRef.current) return;
+
+    setSync((prev) => ({ ...prev, isSyncing: true }));
+
+    try {
+      // @ts-expect-error - Aeon module method
+      await offlineQueueRef.current.flush();
+      setSync((prev) => ({
+        ...prev,
+        isSyncing: false,
+        pendingOperations: 0,
+        lastSyncAt: new Date().toISOString(),
+      }));
+    } catch (error) {
+      console.error('[aeon-provider] Error flushing offline queue:', error);
+      setSync((prev) => ({ ...prev, isSyncing: false }));
+    }
+  }, []);
+
+  // Update cursor position
+  const updateCursor = useCallback((position: { x: number; y: number }) => {
+    if (!localUser) return;
+
+    setLocalUser((prev) =>
+      prev ? { ...prev, cursor: position, lastActivity: new Date().toISOString() } : null
+    );
+
+    // Send to WebSocket
+    wsRef.current?.send(
+      JSON.stringify({
+        type: 'cursor-update',
+        position,
+      })
+    );
+  }, [localUser]);
+
+  // Update editing element
+  const updateEditing = useCallback((elementPath: string | null) => {
+    if (!localUser) return;
+
+    setLocalUser((prev) =>
+      prev ? { ...prev, editing: elementPath ?? undefined, lastActivity: new Date().toISOString() } : null
+    );
+
+    // Send to WebSocket
+    wsRef.current?.send(
+      JSON.stringify({
+        type: 'editing-update',
+        elementPath,
+      })
+    );
+  }, [localUser]);
+
+  // Force sync
+  const forceSync = useCallback(async () => {
+    if (!sync.isOnline) {
+      throw new Error('Cannot sync while offline');
+    }
+
+    setSync((prev) => ({ ...prev, isSyncing: true }));
+
+    try {
+      // @ts-expect-error - Aeon module method
+      await syncCoordinatorRef.current?.sync();
+      setSync((prev) => ({
+        ...prev,
+        isSyncing: false,
+        lastSyncAt: new Date().toISOString(),
+      }));
+    } catch (error) {
+      setSync((prev) => ({ ...prev, isSyncing: false }));
+      throw error;
+    }
+  }, [sync.isOnline]);
+
+  // Migrate to new version
+  const migrate = useCallback(async (toVersion: string) => {
+    // @ts-expect-error - Aeon module method
+    await versionManagerRef.current?.migrate(toVersion);
+    setVersion((prev) => ({
+      ...prev,
+      current: toVersion,
+      needsMigration: false,
+    }));
+  }, []);
+
+  // Set data
+  const setData = useCallback((key: string, value: unknown) => {
+    setDataState((prev) => ({ ...prev, [key]: value }));
+
+    // Queue for sync
+    if (sync.isOnline && wsRef.current) {
+      wsRef.current.send(
+        JSON.stringify({
+          type: 'data-set',
+          key,
+          value,
+        })
+      );
+    } else {
+      // Queue offline
+      // @ts-expect-error - Aeon module method
+      offlineQueueRef.current?.enqueue({
+        type: 'data-set',
+        key,
+        value,
+      });
+      setSync((prev) => ({
+        ...prev,
+        pendingOperations: prev.pendingOperations + 1,
+      }));
+    }
+  }, [sync.isOnline]);
+
+  // Update tree
+  const updateTree = useCallback((path: string, value: unknown) => {
+    // This would apply a patch to the tree
+    wsRef.current?.send(
+      JSON.stringify({
+        type: 'tree-patch',
+        path,
+        value,
+      })
+    );
+  }, []);
+
+  // Context value
+  const contextValue: AeonPageContextValue = {
+    route,
+    sessionId,
+    presence,
+    localUser,
+    updateCursor,
+    updateEditing,
+    sync,
+    forcSync: forceSync,
+    version,
+    migrate,
+    data,
+    setData,
+    tree,
+    updateTree,
+  };
+
+  return (
+    <AeonPageContext.Provider value={contextValue}>
+      {children}
+    </AeonPageContext.Provider>
+  );
+}
+
+/**
+ * useAeonPage - Access Aeon page context
+ */
+export function useAeonPage(): AeonPageContextValue {
+  const context = useContext(AeonPageContext);
+  if (!context) {
+    throw new Error('useAeonPage must be used within an AeonPageProvider');
+  }
+  return context;
+}
+
+/**
+ * usePresence - Just the presence data
+ */
+export function usePresence() {
+  const { presence, localUser, updateCursor, updateEditing } = useAeonPage();
+  return { presence, localUser, updateCursor, updateEditing };
+}
+
+/**
+ * useAeonSync - Just the sync state
+ */
+export function useAeonSync() {
+  const { sync, forcSync: forceSync } = useAeonPage();
+  return { ...sync, forceSync };
+}
+
+/**
+ * useAeonData - Just the data store
+ */
+export function useAeonData<T = unknown>(key: string): [T | undefined, (value: T) => void] {
+  const { data, setData } = useAeonPage();
+  const value = data[key] as T | undefined;
+  const setValue = useCallback((newValue: T) => setData(key, newValue), [key, setData]);
+  return [value, setValue];
+}
+
+// Helper to generate user ID
+function generateUserId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `user-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+export default AeonPageProvider;

package/packages/runtime/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@affectively/aeon-pages-runtime",
+  "version": "0.2.0",
+  "description": "Bun/Cloudflare runtime for @affectively/aeon-pages",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    },
+    "./router": {
+      "import": "./dist/router/index.js",
+      "types": "./dist/router/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts ./src/server.ts ./src/router/index.ts --outdir ./dist --target bun && tsc --declaration --emitDeclarationOnly",
+    "dev": "bun --watch ./src/index.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun run build",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "dev:worker": "wrangler dev",
+    "db:create": "wrangler d1 create aeon-pages",
+    "db:migrate": "wrangler d1 execute aeon-pages --file=./schema.sql",
+    "db:migrate:local": "wrangler d1 execute aeon-pages --local --file=./schema.sql",
+    "tail": "wrangler tail"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "bun": ">=1.0.0",
+    "react": ">=18.0.0",
+    "zod": ">=3.0.0",
+    "@affectively/aeon": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@affectively/aeon": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "zod": "^3.24.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/affectively/aeon-pages"
+  },
+  "keywords": [
+    "aeon",
+    "pages",
+    "framework",
+    "collaborative",
+    "bun",
+    "cloudflare"
+  ]
+}

package/packages/runtime/schema.sql

@@ -0,0 +1,40 @@
+-- Aeon Pages D1 Schema
+-- Run with: wrangler d1 execute aeon-pages --file=./schema.sql
+
+-- Sessions table (async propagation from Durable Objects)
+CREATE TABLE IF NOT EXISTS sessions (
+  session_id TEXT PRIMARY KEY,
+  route TEXT NOT NULL,
+  tree TEXT NOT NULL,  -- JSON serialized component tree
+  data TEXT,           -- JSON serialized session data
+  schema_version TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Routes table (backup for route registry)
+CREATE TABLE IF NOT EXISTS routes (
+  pattern TEXT PRIMARY KEY,
+  session_id TEXT,
+  component_id TEXT,
+  is_aeon BOOLEAN DEFAULT FALSE,
+  metadata TEXT,  -- JSON
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Presence snapshots (for analytics)
+CREATE TABLE IF NOT EXISTS presence_snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  user_count INTEGER NOT NULL,
+  users TEXT,  -- JSON array of user IDs
+  snapshot_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_sessions_route ON sessions(route);
+CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at);
+CREATE INDEX IF NOT EXISTS idx_presence_session ON presence_snapshots(session_id);
+CREATE INDEX IF NOT EXISTS idx_presence_time ON presence_snapshots(snapshot_at);