System Architecture

The Input-Output engine is structured with a clear separation of concerns between its Core Engine (Logic), Sensory Hooks (Interaction), and UI Layer (Manifestation). This decoupling ensures high-cadence performance while maintaining strict mathematical consistency.

The Brain (src/engine/Brain.ts) is the central source of truth for the system.

• State Management: Orchestrates the GraphState and provides the primary API for all graph mutations.
• Calculation Orchestration: Manages the dependency graph and triggers evaluation cycles.
• Transaction Handling: Interacts with the TransactionManager to apply atomic graph changes and manage serialization.
• Offloading: Communicates with Web Workers via the BrainWorkerProxy for asynchronous evaluation.

These components act as the interface between user events and the Core Engine.

• Input Hooks: Specialized hooks (located in src/hooks/nerves/) that translate raw browser events (mouse, keyboard, touches) into engine commands.
• Context Awareness: They monitor the current viewport and project screen coordinates into the engine's coordinate space.
• Detailed Docs: See the System Hooks Catalog for individual specifications.

Located at src/hooks/, these provide specialized graph operations:

• Layout Management: Direct interface with the elkjs engine via layoutEngine.ts.
• Manipulation Tools: Including useKnife.ts for edge deletion and useClipboard.ts for state serialization and cloning.

• Source: src/components/Body.tsx
• Role: The visual implementation of the engine. It performs a "Pull" of computed results from the Brain and renders them onto the canvas. It is responsible for the final presentation of calculation node outputs and visual states.

---

To guarantee a 120 FPS experience, the system separates transient input from persistent state updates:

• Context: Continuous user actions such as dragging a node or adjusting a slider.
• Behavior: The Interaction Layer updates the UI state immediately. These high-frequency updates are not committed to the TransactionManager to avoid unnecessary processing cycles.

• Context: Finalized actions like onDragStop or onSliderRelease.
• Behavior: The final state of the interaction is committed as an Atomic Transaction to the Brain, triggering graph synchronization.

This separation allows for zero-latency interactions while maintaining persistent, engineer-grade graph modifications.

System Hooks

The Input-Output engine utilizes a structured set of React hooks to interface between the Core Engine (Brain) and the UI Layer. These hooks are categorized by their functional role in the system lifecycle.

Location: src/hooks/nerves/

These hooks handle raw browser events and translate them into engine-compatible coordinates and commands.

• useHand: Orchestrates manual node manipulation including dragging, scaling, and rotating.
• useEye: Manages viewport state, camera movement, and spatial focus (React Flow integration).
• useEar: Global keyboard event listener for dispatching system-wide commands (Delete, Select All, etc.).
• useMouth: Handles Data I/O, including IOGL blueprint imports and project exports.
• useNose: Validates port types and edge connectivity during interactive linking.

Location: src/hooks/

Hooks responsible for keeping the UI and the Core Engine in sync.

• useBrainSync: Sync-to-Engine. Propagates physical canvas updates (e.g., node movement) back to the Brain state.
• useBrainUpdates: Engine-to-UI. Streams calculation results, specific node state changes, and evaluation errors from the Brain to the UI components.

Location: src/hooks/

Utility hooks for structural graph operations.

• useRelink: Handles edge remapping and port connectivity updates.
• useNodeSpawner: Logic for instantiating and placing new nodes on the canvas.
• useNodeParam: Interface for nodes to read and write internal parameters to the global state.
• useKnife: Collision-based tool for deleting multiple edges in a single gesture.
• useHandleMagnet: Implementation of logical and visual snapping for edge creation.

Location: src/hooks/

• useAutoLayout: Interface for the high-performance ELK layout engine to organize graph topology.
• useAutoInsert: Logic for automatically inserting and connecting a node between two existing linked nodes.

Location: src/hooks/

• useProjectSave: Manages project serialization, compression, and persistence (Local/Cloud).
• useClipboard: Handles node/subgraph cloning and duplication logic.
• useSelection: Orchestrates batch operations (Swapping, Cascading, Grouping) on multiple selected nodes.
• usePerformanceMonitor: Telemetry for engine execution metrics, including FPS and calculation latency.

---

Any action that modifies the graph topology or node values must be committed as a Committed Transactionto the Brain to ensure data consistency and system integrity.