flock-core 0.4.542__py3-none-any.whl → 0.5.0__py3-none-any.whl

flock/frontend/src/hooks/useModulePersistence.ts

@@ -0,0 +1,154 @@
+import { useEffect, useRef, useCallback } from 'react';
+import { useModuleStore } from '../store/moduleStore';
+import { indexedDBService } from '../services/indexeddb';
+import type { ModuleInstance } from '../types/modules';
+
+/**
+ * Hook to persist module instances to IndexedDB
+ *
+ * Features:
+ * - Loads all module instances on mount
+ * - Saves instances when added/updated (with debouncing for drag/resize)
+ * - Deletes instances when removed
+ * - Debounce: 300ms (same as node position persistence)
+ */
+export const useModulePersistence = () => {
+  const instances = useModuleStore((state) => state.instances);
+  const addModule = useModuleStore((state) => state.addModule);
+
+  // Track previous instances to detect changes
+  const previousInstancesRef = useRef<Map<string, ModuleInstance>>(new Map());
+
+  // Debounce timer for saves
+  const saveTimerRef = useRef<{ [key: string]: number }>({});
+
+  // Load module instances on mount
+  useEffect(() => {
+    const loadModuleInstances = async () => {
+      try {
+        const savedInstances = await indexedDBService.getAllModuleInstances();
+
+        // Restore each module instance to the store
+        savedInstances.forEach((record) => {
+          const instance: ModuleInstance = {
+            id: record.instance_id,
+            type: record.type,
+            position: record.position,
+            size: record.size,
+            visible: record.visible,
+          };
+          addModule(instance);
+        });
+
+        console.log(`[ModulePersistence] Restored ${savedInstances.length} module instances`);
+      } catch (error) {
+        console.error('[ModulePersistence] Failed to load module instances:', error);
+      }
+    };
+
+    loadModuleInstances();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []); // Only run on mount
+
+  // Save module instances when they change (debounced)
+  const saveModuleInstance = useCallback(async (instance: ModuleInstance) => {
+    // Clear existing timer for this instance
+    if (saveTimerRef.current[instance.id]) {
+      clearTimeout(saveTimerRef.current[instance.id]);
+    }
+
+    // Debounce: wait 300ms before saving (handles rapid drag/resize updates)
+    saveTimerRef.current[instance.id] = setTimeout(async () => {
+      try {
+        const now = new Date().toISOString();
+        const record = {
+          instance_id: instance.id,
+          type: instance.type,
+          position: instance.position,
+          size: instance.size,
+          visible: instance.visible,
+          created_at: now, // Will be overwritten if updating existing
+          updated_at: now,
+        };
+
+        await indexedDBService.saveModuleInstance(record);
+        console.log(`[ModulePersistence] Saved instance: ${instance.id}`);
+      } catch (error) {
+        console.error(`[ModulePersistence] Failed to save instance ${instance.id}:`, error);
+      }
+
+      delete saveTimerRef.current[instance.id];
+    }, 300);
+  }, []);
+
+  // Delete module instance from IndexedDB
+  const deleteModuleInstance = useCallback(async (instanceId: string) => {
+    // Clear any pending save timer
+    if (saveTimerRef.current[instanceId]) {
+      clearTimeout(saveTimerRef.current[instanceId]);
+      delete saveTimerRef.current[instanceId];
+    }
+
+    try {
+      await indexedDBService.deleteModuleInstance(instanceId);
+      console.log(`[ModulePersistence] Deleted instance: ${instanceId}`);
+    } catch (error) {
+      console.error(`[ModulePersistence] Failed to delete instance ${instanceId}:`, error);
+    }
+  }, []);
+
+  // Detect changes in module instances
+  useEffect(() => {
+    const currentIds = new Set(instances.keys());
+    const previousIds = new Set(previousInstancesRef.current.keys());
+
+    // Detect added instances
+    currentIds.forEach((id) => {
+      if (!previousIds.has(id)) {
+        const instance = instances.get(id);
+        if (instance) {
+          console.log(`[ModulePersistence] Detected new instance: ${id}`);
+          saveModuleInstance(instance);
+        }
+      }
+    });
+
+    // Detect updated instances
+    instances.forEach((instance, id) => {
+      const previous = previousInstancesRef.current.get(id);
+      if (previous) {
+        // Check if position, size, or visibility changed
+        const positionChanged =
+          previous.position.x !== instance.position.x ||
+          previous.position.y !== instance.position.y;
+        const sizeChanged =
+          previous.size.width !== instance.size.width ||
+          previous.size.height !== instance.size.height;
+        const visibilityChanged = previous.visible !== instance.visible;
+
+        if (positionChanged || sizeChanged || visibilityChanged) {
+          console.log(`[ModulePersistence] Detected update to instance: ${id}`);
+          saveModuleInstance(instance);
+        }
+      }
+    });
+
+    // Detect removed instances
+    previousIds.forEach((id) => {
+      if (!currentIds.has(id)) {
+        console.log(`[ModulePersistence] Detected removed instance: ${id}`);
+        deleteModuleInstance(id);
+      }
+    });
+
+    // Update ref for next comparison
+    previousInstancesRef.current = new Map(instances);
+  }, [instances, saveModuleInstance, deleteModuleInstance]);
+
+  // Cleanup timers on unmount
+  useEffect(() => {
+    return () => {
+      Object.values(saveTimerRef.current).forEach(clearTimeout);
+    };
+  }, []);
+};

flock/frontend/src/hooks/useModules.ts

@@ -0,0 +1,157 @@
+/**
+ * useModules Hook - Module Lifecycle Management
+ *
+ * Provides ModuleContext to modules and manages lifecycle hooks.
+ * Aggregates data from multiple stores into a unified context.
+ * Calls module onMount/onUnmount lifecycle hooks when instances change.
+ *
+ * SPECIFICATION: docs/specs/003-real-time-dashboard/FRONTEND_ARCHITECTURE.md Section 7.4
+ * - Build ModuleContext from store data (events, filters)
+ * - Call module onMount lifecycle hooks when instances added
+ * - Call module onUnmount lifecycle hooks when instances removed
+ * - Provide publish and invoke actions in context
+ *
+ * UI Optimization Migration (Phase 4.1 - Spec 002):
+ * - agents/messages Maps are DEPRECATED (Phase 1 architecture)
+ * - Modules should use events array instead
+ * - Empty Maps provided for backward compatibility
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useModuleStore } from '../store/moduleStore';
+import { useGraphStore } from '../store/graphStore';
+import { useFilterStore } from '../store/filterStore';
+import { moduleRegistry, type ModuleContext } from '../components/modules/ModuleRegistry';
+
+/**
+ * Custom hook for module lifecycle management
+ *
+ * Features:
+ * - Builds ModuleContext from graphStore, filterStore
+ * - Tracks module instances and calls lifecycle hooks
+ * - Calls onMount when new instances are added
+ * - Calls onUnmount when instances are removed
+ * - Provides publish/invoke actions (placeholder for now)
+ *
+ * @returns {Object} Hook return value
+ * @returns {ModuleContext} context - The module context object
+ */
+export function useModules() {
+  // Subscribe to store state
+  const instances = useModuleStore((state) => state.instances);
+  const events = useGraphStore((state) => state.events);
+
+  // UI Optimization Migration (Phase 4.1): Provide empty Maps for deprecated fields
+  const agents = useMemo(() => new Map(), []);
+  const messages = useMemo(() => new Map(), []);
+  const correlationId = useFilterStore((state) => state.correlationId);
+  const timeRange = useFilterStore((state) => state.timeRange);
+  const artifactTypes = useFilterStore((state) => state.selectedArtifactTypes);
+  const producers = useFilterStore((state) => state.selectedProducers);
+  const tags = useFilterStore((state) => state.selectedTags);
+  const visibility = useFilterStore((state) => state.selectedVisibility);
+  const summary = useFilterStore((state) => state.summary);
+
+  // Track previous instances to detect changes
+  const prevInstancesRef = useRef<Map<string, any>>(new Map());
+
+  // Build ModuleContext
+  const context: ModuleContext = useMemo(
+    () => ({
+      agents,
+      messages,
+      events,
+      filters: {
+        correlationId,
+        timeRange,
+        artifactTypes,
+        producers,
+        tags,
+        visibility,
+      },
+      summary,
+      publish: (artifact: any) => {
+        // Placeholder: In production, this would dispatch to WebSocket
+        console.log('[Module Context] Publish artifact:', artifact);
+      },
+      invoke: (agentName: string, inputs: any[]) => {
+        // Placeholder: In production, this would dispatch to WebSocket
+        console.log('[Module Context] Invoke agent:', agentName, 'with inputs:', inputs);
+      },
+    }),
+    // Note: agents and messages are stable empty Maps, so excluded from deps
+    [events, correlationId, timeRange, artifactTypes, producers, tags, visibility, summary]
+  );
+
+  /**
+   * Lifecycle effect: Call onMount/onUnmount hooks when instances change
+   */
+  useEffect(() => {
+    const currentInstances = instances;
+    const prevInstances = prevInstancesRef.current;
+
+    // Detect added instances (in current but not in previous)
+    const addedInstances = new Map<string, any>();
+    currentInstances.forEach((instance, id) => {
+      if (!prevInstances.has(id)) {
+        addedInstances.set(id, instance);
+      }
+    });
+
+    // Detect removed instances (in previous but not in current)
+    const removedInstances = new Map<string, any>();
+    prevInstances.forEach((instance, id) => {
+      if (!currentInstances.has(id)) {
+        removedInstances.set(id, instance);
+      }
+    });
+
+    // Call onMount for added instances
+    addedInstances.forEach((instance) => {
+      const module = moduleRegistry.get(instance.type);
+      if (module?.onMount) {
+        console.log(`[useModules] Calling onMount for module: ${module.name} (${instance.id})`);
+        try {
+          module.onMount(context);
+        } catch (error) {
+          console.error(`[useModules] Error in onMount for module ${module.name}:`, error);
+        }
+      }
+    });
+
+    // Call onUnmount for removed instances
+    removedInstances.forEach((instance) => {
+      const module = moduleRegistry.get(instance.type);
+      if (module?.onUnmount) {
+        console.log(`[useModules] Calling onUnmount for module: ${module.name} (${instance.id})`);
+        try {
+          module.onUnmount();
+        } catch (error) {
+          console.error(`[useModules] Error in onUnmount for module ${module.name}:`, error);
+        }
+      }
+    });
+
+    // Update previous instances ref for next comparison
+    prevInstancesRef.current = new Map(currentInstances);
+
+    // Cleanup: Call onUnmount for all instances when hook unmounts
+    return () => {
+      currentInstances.forEach((instance) => {
+        const module = moduleRegistry.get(instance.type);
+        if (module?.onUnmount) {
+          console.log(`[useModules] Cleanup: Calling onUnmount for module: ${module.name} (${instance.id})`);
+          try {
+            module.onUnmount();
+          } catch (error) {
+            console.error(`[useModules] Error in cleanup onUnmount for module ${module.name}:`, error);
+          }
+        }
+      });
+    };
+  }, [instances, context]);
+
+  return {
+    context,
+  };
+}

flock/frontend/src/hooks/usePersistence.ts

@@ -0,0 +1,141 @@
+/**
+ * usePersistence Hook - Node Position Persistence
+ *
+ * Provides position persistence for graph nodes using IndexedDB.
+ * Manages loading and saving of node positions with debouncing.
+ * Handles separate layouts for Agent View and Blackboard View.
+ *
+ * SPECIFICATION: docs/specs/003-real-time-dashboard/FRONTEND_ARCHITECTURE.md
+ * - Debounce: 300ms delay on drag stop
+ * - Performance: Position save <50ms (after debounce)
+ * - Separate layouts for Agent View vs Blackboard View
+ */
+
+import { useEffect, useCallback, useRef } from 'react';
+import { useGraphStore } from '../store/graphStore';
+import { useUIStore, VisualizationMode } from '../store/uiStore';
+import { indexedDBService } from '../services/indexeddb';
+
+interface Position {
+  x: number;
+  y: number;
+}
+
+/**
+ * Custom debounce implementation
+ * Creates a debounced function that delays invoking func until after delay milliseconds
+ */
+function debounce<T extends (...args: any[]) => void>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  return (...args: Parameters<T>) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      func(...args);
+      timeoutId = null;
+    }, delay);
+  };
+}
+
+/**
+ * React hook for node position persistence
+ *
+ * Features:
+ * - Loads node positions from IndexedDB on mount
+ * - Applies loaded positions to graphStore
+ * - Returns debounced saveNodePosition function (300ms delay)
+ * - Handles mode switching (reloads positions for new mode)
+ *
+ * @returns {Object} Hook return value
+ * @returns {Function} saveNodePosition - Debounced function to save node position
+ */
+export function usePersistence() {
+  const mode = useUIStore((state) => state.mode);
+
+  // Use ref to maintain debounced function identity across renders
+  const debouncedSaveRef = useRef<((nodeId: string, mode: VisualizationMode, position: Position) => void) | null>(null);
+
+  // Initialize debounced save function once
+  if (!debouncedSaveRef.current) {
+    debouncedSaveRef.current = debounce(
+      async (nodeId: string, mode: VisualizationMode, position: Position) => {
+        try {
+          console.log(`[usePersistence] Saving position for ${nodeId} in ${mode} view:`, position);
+          const layoutRecord = {
+            node_id: nodeId,
+            x: position.x,
+            y: position.y,
+            last_updated: new Date().toISOString(),
+          };
+
+          if (mode === 'agent') {
+            await indexedDBService.saveAgentViewLayout(layoutRecord);
+            console.log(`[usePersistence] ✓ Saved to agent view layout`);
+          } else {
+            await indexedDBService.saveBlackboardViewLayout(layoutRecord);
+            console.log(`[usePersistence] ✓ Saved to blackboard view layout`);
+          }
+        } catch (error) {
+          console.error(`[usePersistence] Failed to save node position for ${nodeId}:`, error);
+        }
+      },
+      300 // 300ms debounce delay as per specification
+    );
+  }
+
+  /**
+   * Load node positions from IndexedDB for current mode
+   * Note: Deliberately excludes updateNodePosition from dependencies to prevent infinite loops
+   * The function is stable from zustand, so we can safely use it without re-creating the callback
+   */
+  const loadNodePositions = useCallback(async (currentMode: VisualizationMode) => {
+    try {
+      let layouts: Array<{ node_id: string; x: number; y: number; last_updated: string }> = [];
+
+      if (currentMode === 'agent') {
+        layouts = await indexedDBService.getAllAgentViewLayouts();
+      } else {
+        layouts = await indexedDBService.getAllBlackboardViewLayouts();
+      }
+
+      // Apply loaded positions to graph store
+      // Use graphStore directly to avoid dependency on updateNodePosition selector
+      layouts.forEach((layout) => {
+        useGraphStore.getState().updateNodePosition(layout.node_id, { x: layout.x, y: layout.y });
+      });
+
+      console.log(`[usePersistence] Loaded ${layouts.length} node positions for ${currentMode} view`);
+    } catch (error) {
+      console.error(`[usePersistence] Failed to load node positions for ${currentMode} view:`, error);
+    }
+  }, []); // Empty deps - function is now stable!
+
+  /**
+   * Load positions on mount and when mode changes
+   */
+  useEffect(() => {
+    loadNodePositions(mode);
+  }, [mode, loadNodePositions]);
+
+  /**
+   * Public API: Save node position with debouncing
+   */
+  const saveNodePosition = useCallback(
+    (nodeId: string, position: Position) => {
+      if (debouncedSaveRef.current) {
+        debouncedSaveRef.current(nodeId, mode, position);
+      }
+    },
+    [mode]
+  );
+
+  return {
+    saveNodePosition,
+  };
+}

flock/frontend/src/main.tsx

@@ -0,0 +1,13 @@
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './styles/index.css';
+
+// Mock data removed - dashboard now starts empty and shows only real WebSocket data
+
+const rootElement = document.getElementById('root');
+
+if (!rootElement) {
+  throw new Error('Root element not found');
+}
+
+ReactDOM.createRoot(rootElement).render(<App />);