5.9 KiB
Design Document: Spatial Workspace Architecture Refactor Status: Draft Target System: Desk/Workspace (Canvas, Dragging, Physics) Primary Goal: Decompose "God Objects" into a composable, layered architecture to improve performance, maintainability, and testability.
- Executive Summary The current implementation relies on a monolithic class (WorkspaceEngine) and an overloaded hook (useDeskPointer). This coupling forces React to handle high-frequency logic (physics/drag), resulting in brittle code and potential performance bottlenecks.
The Proposal: Transition to a Layered Architecture. We will separate "Pure Math" (Physics/Geometry), "Mutable State" (Performance), and "React Interaction" (Events/Business Logic).
- Architectural Overview We will adopt a unidirectional, event-driven flow for interactions, bypassing React's render cycle for high-frequency updates (dragging/animating), while using React for low-frequency updates (selection/mounting).
The Four Layers
The Physics Layer (Core): Stateless, pure functions for geometry and kinetics.
The Scene Layer (Store): A lightweight, mutable registry that holds the "truth" of layout (x, y, rotation) and manages direct DOM updates.
The Interaction Layer (Hooks): React hooks that bind DOM events to the Scene Layer.
The Persistence Layer: An asynchronous observer that syncs the Scene Layer to the Backend/DB.
Code-Snippet graph TD User[User Input] -->|Pointer Events| Interaction[Interaction Layer Hooks] Interaction -->|Calculate| Physics[Physics Layer Pure Math] Interaction -->|Update| Scene[Scene Layer Mutable Store] Scene -->|Direct Manipulation| DOM[DOM Elements 60fps] Scene -.->|Debounced Snapshot| DB[Persistence Layer] 3. Detailed Component Design Layer 1: Physics & Geometry (lib/spatial)
Responsibility: Pure math. No side effects. No DOM references.
Key Modules:
geometry.ts: Hit testing, polygon intersection, coordinate projection (Screen <-> Canvas).
kinetics.ts: Inertia decay, angular velocity calculation, clamping.
Benefit: 100% Unit testable without mocking the DOM.
Layer 2: The Scene Store (lib/scene)
Responsibility: High-performance state management. It acts as the bridge between React and the DOM.
Structure:
TypeScript class SceneStore { // Fast lookups items: Map<string, SceneItem>;
// Updates DOM style immediately, skips React render updateItem(id, transform) { ... }
// Used by Persistence Layer getSnapshot() { ... } } Why: React State is too slow for 60fps drag interactions on complex DOM trees. We need direct manipulation.
Layer 3: Interaction Hooks (hooks/)
We split the "God Hook" (useDeskPointer) into specific responsibilities.
usePointerGesture:
Role: The "driver." Handles down, move, up, cancel.
Logic: Manages drag thresholds, long-press timers, and distinguishing taps from drags.
Output: Emits high-level events: onTap, onDragStart, onDrag, onDragEnd.
useSpatialQuery:
Role: The "eyes."
Logic: Wraps lib/spatial. Given an event (x, y), returns [DocID, StackInfo].
useDragController:
Role: The "business logic."
Logic: Listens to usePointerGesture. When a drag starts:
Locks the React View (prevents re-renders).
Calculates physics via lib/spatial.
Pushes updates to SceneStore.
On release, triggers inertia animation loop.
Layer 4: Persistence (Observer)
Role: Syncs the mutable SceneStore back to the database.
Mechanism:
Subscribes to onDragEnd or an internal dirty flag in the Store.
Uses a debounce strategy (e.g., wait 500ms after last movement) to save to the backend.
- Data Flow Scenarios Scenario A: Selecting a Card
User: Clicks on a card.
usePointerGesture: Detects pointerDown + pointerUp (no movement). Fires onTap.
useDeskSelection: Receives onTap. Checks event.metaKey. Updates React State (setSelectedIds).
React: Re-renders to show selection border.
Scenario B: Dragging a Card (The Performance Path)
User: Presses and moves mouse > 5px.
usePointerGesture: Fires onDragStart.
useDragController:
Calculates initialOffsets.
While moving:
Calculates new x, y, rotation (using Physics Layer).
Calls SceneStore.updateItem().
Result: The DOM element moves via CSS Transform. React does not re-render.
User: Releases mouse.
useDragController: Fires onDragEnd. Starts Inertia Animation loop (updating SceneStore via requestAnimationFrame).
Persistence: Detects end of movement, saves new coordinates.
- Migration Strategy We will apply the Strangler Fig Pattern: replacing pieces of the monolith gradually.
Phase 1: Math Extraction (Safe)
Extract geometry/physics logic from WorkspaceEngine and pointerUtils into pure functions in lib/spatial.
Risk: Low.
Phase 2: The Gesture Hook (Cleanup)
Implement usePointerGesture. Replace the event listeners in useDeskPointer with this hook.
Risk: Low.
Phase 3: The Scene Store (Core Replacement)
Build SceneStore.
Modify useDocumentDrag to write to SceneStore instead of WorkspaceEngine.
Risk: Medium. Visual synchronization bugs might occur during transition.
Phase 4: Persistence Decoupling
Move loadPersistedLayout and upsertLayoutRecords out of the Engine and into a specialized React Effect or standard async function triggered by the Store.
- Comparison: Old vs. New Feature Old Architecture New Architecture State Monolithic Class (WorkspaceEngine) Mutable Store (SceneStore) + React State Dragging Mixed into Engine & Hooks Isolated Controller Hook Physics Hardcoded in Engine Pure Functional Module DOM Access Cached Refs inside Engine Direct management via Store Testing Difficult (Mocking Engine required) Easy (Test Physics/Store in isolation)
- Open Questions / Risks Z-Index Management: Currently handled by zCounter in the Engine. The SceneStore must maintain a global Z-index counter to ensure "Bring to Front" works reliably.
** React Context vs. Global Singleton:** Should SceneStore be a global singleton or provided via Context?
Decision: Context. This allows multiple independent Workspaces on one screen if needed in the future.