@affectively/aeon-pages 1.3.0

package/packages/runtime/src/predictor.ts

@@ -0,0 +1,371 @@
+/**
+ * Aeon Navigation Predictor
+ *
+ * Predicts where users will navigate next based on:
+ * 1. Personal navigation history (Markov chain)
+ * 2. Collaborative signals (where is the community going?)
+ * 3. Time-based patterns (Monday morning vs Friday afternoon)
+ * 4. Content signals (came from search → exploring)
+ *
+ * The predictor itself is an Aeon entity - it syncs across nodes
+ * to build community navigation patterns.
+ */
+
+export interface PredictedRoute {
+  route: string;
+  probability: number;
+  reason: 'history' | 'hover' | 'visibility' | 'community' | 'time' | 'content';
+  confidence: number;
+}
+
+export interface NavigationRecord {
+  from: string;
+  to: string;
+  timestamp: number;
+  duration: number; // How long they stayed on 'from'
+  source?: 'click' | 'back' | 'forward' | 'direct';
+}
+
+export interface CommunityPattern {
+  route: string;
+  popularity: number; // How many users visited
+  avgTimeSpent: number;
+  nextRoutes: { route: string; count: number }[];
+}
+
+export interface PredictorConfig {
+  historyWeight: number; // 0-1, weight for personal history
+  communityWeight: number; // 0-1, weight for community patterns
+  timeWeight: number; // 0-1, weight for time-based patterns
+  decayFactor: number; // How quickly old history decays (0-1)
+  minProbability: number; // Minimum probability to include in predictions
+  maxPredictions: number; // Maximum predictions to return
+}
+
+const DEFAULT_CONFIG: PredictorConfig = {
+  historyWeight: 0.5,
+  communityWeight: 0.3,
+  timeWeight: 0.2,
+  decayFactor: 0.95,
+  minProbability: 0.1,
+  maxPredictions: 5,
+};
+
+export class NavigationPredictor {
+  private config: PredictorConfig;
+  private history: NavigationRecord[] = [];
+  private transitionMatrix: Map<string, Map<string, number>> = new Map();
+  private communityPatterns: Map<string, CommunityPattern> = new Map();
+  private timePatterns: Map<string, Map<number, number>> = new Map(); // route -> hour -> count
+
+  constructor(config: Partial<PredictorConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Record a navigation event
+   */
+  record(record: NavigationRecord): void {
+    this.history.push(record);
+
+    // Update transition matrix
+    if (!this.transitionMatrix.has(record.from)) {
+      this.transitionMatrix.set(record.from, new Map());
+    }
+    const fromMap = this.transitionMatrix.get(record.from)!;
+    fromMap.set(record.to, (fromMap.get(record.to) ?? 0) + 1);
+
+    // Update time patterns
+    const hour = new Date(record.timestamp).getHours();
+    if (!this.timePatterns.has(record.to)) {
+      this.timePatterns.set(record.to, new Map());
+    }
+    const hourMap = this.timePatterns.get(record.to)!;
+    hourMap.set(hour, (hourMap.get(hour) ?? 0) + 1);
+
+    // Apply decay to old records
+    this.applyDecay();
+  }
+
+  /**
+   * Predict next navigation destinations from current route
+   */
+  predict(currentRoute: string): PredictedRoute[] {
+    const predictions: Map<string, PredictedRoute> = new Map();
+
+    // 1. Personal history predictions (Markov chain)
+    const historyPredictions = this.predictFromHistory(currentRoute);
+    for (const pred of historyPredictions) {
+      this.mergePrediction(predictions, pred, this.config.historyWeight);
+    }
+
+    // 2. Community predictions
+    const communityPredictions = this.predictFromCommunity(currentRoute);
+    for (const pred of communityPredictions) {
+      this.mergePrediction(predictions, pred, this.config.communityWeight);
+    }
+
+    // 3. Time-based predictions
+    const timePredictions = this.predictFromTime();
+    for (const pred of timePredictions) {
+      this.mergePrediction(predictions, pred, this.config.timeWeight);
+    }
+
+    // Sort by probability and filter
+    return Array.from(predictions.values())
+      .filter((p) => p.probability >= this.config.minProbability)
+      .sort((a, b) => b.probability - a.probability)
+      .slice(0, this.config.maxPredictions);
+  }
+
+  /**
+   * Predict from personal navigation history (Markov chain)
+   */
+  private predictFromHistory(currentRoute: string): PredictedRoute[] {
+    const fromMap = this.transitionMatrix.get(currentRoute);
+    if (!fromMap) return [];
+
+    const total = Array.from(fromMap.values()).reduce((a, b) => a + b, 0);
+    if (total === 0) return [];
+
+    return Array.from(fromMap.entries()).map(([route, count]) => ({
+      route,
+      probability: count / total,
+      reason: 'history' as const,
+      confidence: Math.min(1, total / 10), // Higher confidence with more data
+    }));
+  }
+
+  /**
+   * Predict from community patterns
+   */
+  private predictFromCommunity(currentRoute: string): PredictedRoute[] {
+    const pattern = this.communityPatterns.get(currentRoute);
+    if (!pattern || pattern.nextRoutes.length === 0) return [];
+
+    const total = pattern.nextRoutes.reduce((a, b) => a + b.count, 0);
+    if (total === 0) return [];
+
+    return pattern.nextRoutes.map(({ route, count }) => ({
+      route,
+      probability: count / total,
+      reason: 'community' as const,
+      confidence: Math.min(1, pattern.popularity / 100),
+    }));
+  }
+
+  /**
+   * Predict from time-based patterns
+   */
+  private predictFromTime(): PredictedRoute[] {
+    const currentHour = new Date().getHours();
+    const predictions: PredictedRoute[] = [];
+
+    let maxCount = 0;
+    for (const [route, hourMap] of this.timePatterns) {
+      const count = hourMap.get(currentHour) ?? 0;
+      if (count > maxCount) maxCount = count;
+    }
+
+    if (maxCount === 0) return [];
+
+    for (const [route, hourMap] of this.timePatterns) {
+      const count = hourMap.get(currentHour) ?? 0;
+      if (count > 0) {
+        predictions.push({
+          route,
+          probability: count / maxCount,
+          reason: 'time' as const,
+          confidence: Math.min(1, count / 5),
+        });
+      }
+    }
+
+    return predictions;
+  }
+
+  /**
+   * Merge a prediction into the predictions map
+   */
+  private mergePrediction(
+    predictions: Map<string, PredictedRoute>,
+    prediction: PredictedRoute,
+    weight: number,
+  ): void {
+    const existing = predictions.get(prediction.route);
+    if (existing) {
+      // Combine probabilities (weighted average)
+      const totalWeight =
+        (existing.confidence ?? 1) + (prediction.confidence ?? 1) * weight;
+      existing.probability =
+        (existing.probability * (existing.confidence ?? 1) +
+          prediction.probability * (prediction.confidence ?? 1) * weight) /
+        totalWeight;
+      existing.confidence = Math.max(
+        existing.confidence,
+        prediction.confidence,
+      );
+      // Keep the higher-confidence reason
+      if (prediction.confidence > (existing.confidence ?? 0)) {
+        existing.reason = prediction.reason;
+      }
+    } else {
+      predictions.set(prediction.route, {
+        ...prediction,
+        probability: prediction.probability * weight,
+      });
+    }
+  }
+
+  /**
+   * Apply decay to old history records
+   */
+  private applyDecay(): void {
+    // Decay transition matrix
+    for (const [from, toMap] of this.transitionMatrix) {
+      for (const [to, count] of toMap) {
+        const decayed = count * this.config.decayFactor;
+        if (decayed < 0.1) {
+          toMap.delete(to);
+        } else {
+          toMap.set(to, decayed);
+        }
+      }
+      if (toMap.size === 0) {
+        this.transitionMatrix.delete(from);
+      }
+    }
+
+    // Trim old history
+    const maxHistory = 1000;
+    if (this.history.length > maxHistory) {
+      this.history = this.history.slice(-maxHistory);
+    }
+  }
+
+  /**
+   * Update community patterns from external sync
+   */
+  updateCommunityPatterns(patterns: Map<string, CommunityPattern>): void {
+    this.communityPatterns = patterns;
+  }
+
+  /**
+   * Get current transition matrix (for syncing)
+   */
+  getTransitionMatrix(): Map<string, Map<string, number>> {
+    return this.transitionMatrix;
+  }
+
+  /**
+   * Import transition matrix from sync
+   */
+  importTransitionMatrix(matrix: Map<string, Map<string, number>>): void {
+    // Merge with existing
+    for (const [from, toMap] of matrix) {
+      if (!this.transitionMatrix.has(from)) {
+        this.transitionMatrix.set(from, new Map());
+      }
+      const existingMap = this.transitionMatrix.get(from)!;
+      for (const [to, count] of toMap) {
+        existingMap.set(to, (existingMap.get(to) ?? 0) + count);
+      }
+    }
+  }
+
+  /**
+   * Get statistics about the predictor
+   */
+  getStats(): {
+    totalRecords: number;
+    uniqueRoutes: number;
+    transitionPairs: number;
+    communityPatterns: number;
+  } {
+    let transitionPairs = 0;
+    for (const toMap of this.transitionMatrix.values()) {
+      transitionPairs += toMap.size;
+    }
+
+    return {
+      totalRecords: this.history.length,
+      uniqueRoutes: this.transitionMatrix.size,
+      transitionPairs,
+      communityPatterns: this.communityPatterns.size,
+    };
+  }
+
+  /**
+   * Clear all data
+   */
+  clear(): void {
+    this.history = [];
+    this.transitionMatrix.clear();
+    this.communityPatterns.clear();
+    this.timePatterns.clear();
+  }
+
+  /**
+   * Export for persistence
+   */
+  export(): {
+    history: NavigationRecord[];
+    transitionMatrix: [string, [string, number][]][];
+    timePatterns: [string, [number, number][]][];
+  } {
+    return {
+      history: this.history,
+      transitionMatrix: Array.from(this.transitionMatrix.entries()).map(
+        ([from, toMap]) => [from, Array.from(toMap.entries())],
+      ),
+      timePatterns: Array.from(this.timePatterns.entries()).map(
+        ([route, hourMap]) => [route, Array.from(hourMap.entries())],
+      ),
+    };
+  }
+
+  /**
+   * Import from persistence
+   */
+  import(data: {
+    history?: NavigationRecord[];
+    transitionMatrix?: [string, [string, number][]][];
+    timePatterns?: [string, [number, number][]][];
+  }): void {
+    if (data.history) {
+      this.history = data.history;
+    }
+
+    if (data.transitionMatrix) {
+      this.transitionMatrix = new Map(
+        data.transitionMatrix.map(([from, toEntries]) => [
+          from,
+          new Map(toEntries),
+        ]),
+      );
+    }
+
+    if (data.timePatterns) {
+      this.timePatterns = new Map(
+        data.timePatterns.map(([route, hourEntries]) => [
+          route,
+          new Map(hourEntries),
+        ]),
+      );
+    }
+  }
+}
+
+// Singleton instance
+let globalPredictor: NavigationPredictor | null = null;
+
+export function getPredictor(): NavigationPredictor {
+  if (!globalPredictor) {
+    globalPredictor = new NavigationPredictor();
+  }
+  return globalPredictor;
+}
+
+export function setPredictor(predictor: NavigationPredictor): void {
+  globalPredictor = predictor;
+}

package/packages/runtime/src/registry.ts

@@ -0,0 +1,351 @@
+/**
+ * Aeon Route Registry - Collaborative route management
+ *
+ * Routes are stored as Aeon entities, enabling:
+ * - Distributed sync across nodes
+ * - Conflict resolution for concurrent route mutations
+ * - Schema versioning for route structure changes
+ */
+
+import type { RouteDefinition, RouteMetadata, RouteOperation } from './types';
+
+// Import Aeon modules (these would come from @affectively/aeon)
+// For now, we'll define minimal interfaces to compile
+interface SyncCoordinatorLike {
+  getLocalNodeId(): string;
+  getOnlineNodes(): { id: string }[];
+  createSyncSession(initiator: string, participants: string[]): Promise<void>;
+  on(event: string, callback: (data: unknown) => void): void;
+}
+
+interface StateReconcilerLike {
+  recordVersion(nodeId: string, state: unknown, timestamp: number): void;
+  reconcile(): { state: unknown } | null;
+}
+
+interface SchemaVersionManagerLike {
+  getCurrentVersion(): Promise<string>;
+  registerVersion(version: string, metadata: { description: string }): void;
+}
+
+interface RegistryOptions {
+  syncMode: 'distributed' | 'local';
+  versioningEnabled: boolean;
+}
+
+interface AeonRoute {
+  path: string;
+  component: string;
+  metadata: RouteMetadata;
+  version: string;
+}
+
+/**
+ * Collaborative route registry using Aeon distributed sync
+ */
+export class AeonRouteRegistry {
+  private routes: Map<string, AeonRoute> = new Map();
+  private coordinator: SyncCoordinatorLike | null = null;
+  private reconciler: StateReconcilerLike | null = null;
+  private versions: SchemaVersionManagerLike | null = null;
+  private syncMode: 'distributed' | 'local';
+  private versioningEnabled: boolean;
+  private mutationCallbacks: ((operation: RouteOperation) => void)[] = [];
+  private connectedSockets: Set<unknown> = new Set();
+
+  constructor(options: RegistryOptions) {
+    this.syncMode = options.syncMode;
+    this.versioningEnabled = options.versioningEnabled;
+
+    // Initialize Aeon modules (lazy loading to avoid circular deps)
+    this.initializeAeonModules();
+  }
+
+  private async initializeAeonModules(): Promise<void> {
+    try {
+      // Try to import Aeon modules
+      const aeon = await import('@affectively/aeon');
+
+      if (this.syncMode === 'distributed') {
+        this.coordinator =
+          new aeon.SyncCoordinator() as unknown as SyncCoordinatorLike;
+        this.reconciler =
+          new aeon.StateReconciler() as unknown as StateReconcilerLike;
+
+        // Subscribe to sync events
+        this.coordinator.on('sync-completed', (session: unknown) => {
+          this.handleSyncCompleted(session);
+        });
+      }
+
+      if (this.versioningEnabled) {
+        this.versions =
+          new aeon.SchemaVersionManager() as unknown as SchemaVersionManagerLike;
+        this.versions.registerVersion('1.0.0', {
+          description: 'Initial route schema',
+        });
+      }
+    } catch (error) {
+      console.warn(
+        '[aeon-registry] Aeon modules not available, running in standalone mode',
+      );
+    }
+  }
+
+  /**
+   * Add a new route collaboratively
+   */
+  async addRoute(
+    path: string,
+    component: string,
+    metadata: RouteMetadata,
+  ): Promise<void> {
+    const operation: RouteOperation = {
+      type: 'route-add',
+      path,
+      component,
+      metadata,
+      timestamp: new Date().toISOString(),
+      nodeId: this.coordinator?.getLocalNodeId() ?? 'local',
+    };
+
+    // Sync with other nodes if in distributed mode
+    if (this.syncMode === 'distributed' && this.coordinator) {
+      const participants = this.coordinator.getOnlineNodes().map((n) => n.id);
+      if (participants.length > 0) {
+        await this.coordinator.createSyncSession(
+          this.coordinator.getLocalNodeId(),
+          participants,
+        );
+      }
+    }
+
+    // Apply locally
+    const version =
+      this.versioningEnabled && this.versions
+        ? await this.versions.getCurrentVersion()
+        : '1.0.0';
+
+    this.routes.set(path, {
+      path,
+      component,
+      metadata,
+      version,
+    });
+
+    // Notify listeners
+    this.notifyMutation(operation);
+
+    // Persist to file system
+    await this.persistRoute(path, component);
+  }
+
+  /**
+   * Update an existing route
+   */
+  async updateRoute(path: string, updates: Partial<AeonRoute>): Promise<void> {
+    const existing = this.routes.get(path);
+    if (!existing) {
+      throw new Error(`Route not found: ${path}`);
+    }
+
+    const operation: RouteOperation = {
+      type: 'route-update',
+      path,
+      component: updates.component,
+      metadata: {
+        ...existing.metadata,
+        updatedAt: new Date().toISOString(),
+        updatedBy: this.coordinator?.getLocalNodeId() ?? 'local',
+      },
+      timestamp: new Date().toISOString(),
+      nodeId: this.coordinator?.getLocalNodeId() ?? 'local',
+    };
+
+    this.routes.set(path, {
+      ...existing,
+      ...updates,
+      metadata: operation.metadata!,
+    });
+
+    this.notifyMutation(operation);
+  }
+
+  /**
+   * Remove a route
+   */
+  async removeRoute(path: string): Promise<void> {
+    const operation: RouteOperation = {
+      type: 'route-remove',
+      path,
+      timestamp: new Date().toISOString(),
+      nodeId: this.coordinator?.getLocalNodeId() ?? 'local',
+    };
+
+    this.routes.delete(path);
+    this.notifyMutation(operation);
+  }
+
+  /**
+   * Get a route by path
+   */
+  getRoute(path: string): AeonRoute | undefined {
+    return this.routes.get(path);
+  }
+
+  /**
+   * Get session ID for a path
+   */
+  getSessionId(path: string): string {
+    return path.replace(/^\/|\/$/g, '').replace(/\//g, '-') || 'index';
+  }
+
+  /**
+   * Get all routes
+   */
+  getAllRoutes(): AeonRoute[] {
+    return Array.from(this.routes.values());
+  }
+
+  /**
+   * Subscribe to route mutations
+   */
+  subscribeToMutations(
+    callback: (operation: RouteOperation) => void,
+  ): () => void {
+    this.mutationCallbacks.push(callback);
+    return () => {
+      const idx = this.mutationCallbacks.indexOf(callback);
+      if (idx >= 0) {
+        this.mutationCallbacks.splice(idx, 1);
+      }
+    };
+  }
+
+  /**
+   * Handle WebSocket connection for Aeon sync
+   */
+  handleConnect(ws: unknown): void {
+    this.connectedSockets.add(ws);
+  }
+
+  /**
+   * Handle WebSocket disconnection
+   */
+  handleDisconnect(ws: unknown): void {
+    this.connectedSockets.delete(ws);
+  }
+
+  /**
+   * Handle incoming sync message
+   */
+  handleSyncMessage(ws: unknown, message: unknown): void {
+    // Parse and apply sync message
+    try {
+      const data = typeof message === 'string' ? JSON.parse(message) : message;
+
+      if (data.type === 'route-operation') {
+        this.applyRemoteOperation(data.operation as RouteOperation);
+      }
+    } catch (error) {
+      console.error('[aeon-registry] Error handling sync message:', error);
+    }
+  }
+
+  // Private methods
+
+  private notifyMutation(operation: RouteOperation): void {
+    for (const callback of this.mutationCallbacks) {
+      try {
+        callback(operation);
+      } catch (error) {
+        console.error('[aeon-registry] Error in mutation callback:', error);
+      }
+    }
+
+    // Broadcast to connected sockets
+    const message = JSON.stringify({ type: 'route-operation', operation });
+    for (const ws of this.connectedSockets) {
+      try {
+        // @ts-expect-error - WebSocket send method
+        ws.send?.(message);
+      } catch {
+        // Ignore send errors
+      }
+    }
+  }
+
+  private handleSyncCompleted(session: unknown): void {
+    // Apply reconciled state from sync session
+    if (this.reconciler) {
+      const result = this.reconciler.reconcile();
+      if (result?.state) {
+        // Apply reconciled routes
+        const routes = result.state as Map<string, AeonRoute>;
+        for (const [path, route] of routes) {
+          this.routes.set(path, route);
+        }
+      }
+    }
+  }
+
+  private applyRemoteOperation(operation: RouteOperation): void {
+    switch (operation.type) {
+      case 'route-add':
+        if (operation.component && operation.metadata) {
+          this.routes.set(operation.path, {
+            path: operation.path,
+            component: operation.component,
+            metadata: operation.metadata,
+            version: '1.0.0',
+          });
+        }
+        break;
+
+      case 'route-update':
+        const existing = this.routes.get(operation.path);
+        if (existing && operation.component) {
+          this.routes.set(operation.path, {
+            ...existing,
+            component: operation.component,
+            metadata: operation.metadata ?? existing.metadata,
+          });
+        }
+        break;
+
+      case 'route-remove':
+        this.routes.delete(operation.path);
+        break;
+    }
+
+    // Notify local listeners
+    for (const callback of this.mutationCallbacks) {
+      try {
+        callback(operation);
+      } catch (error) {
+        console.error('[aeon-registry] Error in mutation callback:', error);
+      }
+    }
+  }
+
+  private async persistRoute(path: string, component: string): Promise<void> {
+    // Convert path to file path
+    const filePath = path === '/' ? 'page.tsx' : `${path.slice(1)}/page.tsx`;
+
+    // Generate minimal page content
+    const content = `'use aeon';
+
+export default function Page() {
+  return <${component} />;
+}
+`;
+
+    try {
+      // This would write to the file system
+      // In production, this would be gated by permissions
+      console.log(`[aeon-registry] Would persist route to: ${filePath}`);
+    } catch (error) {
+      console.error(`[aeon-registry] Error persisting route:`, error);
+    }
+  }
+}