canvas/TODO.md

@blinksgg/canvas — TODO

Known Gaps

(None currently)

v3.x Roadmap

• React Compiler integration ✅ (v3.0.0)
• v3.1 — Remaining Phase 1 cleanup — remove useMemo/useCallback from Minimap.tsx, db/provider.tsx, useSplitGesture.ts (see plan-react19-canvas-optimization.md)
• v3.2 — Ref cleanup callbacks — adopt React 19 ref cleanup in Viewport.tsx
• v3.3 — Dev Overlay — floating debug panel with graph stats, event log, perf metrics
• v3.4 — Multi-user Cursors — realtime cursor presence for collaborative editing

Open Issues

(None currently)

Completed in v3.0.0

• React Compiler — integrated babel-plugin-react-compiler + @vitejs/plugin-react
• Removed all manual memoization — 6 useCallback + 3 useMemo across 5 files
• Peer deps — react/react-dom ^19.0.0 → ^19.2.0
• Version — 1.0.0 → 3.0.0

Completed in v2.5.0

• First React hook integration tests — renderHook from @testing-library/react
• 4 new test suites — animated-layout (9), useActionExecutor-hook (6), usePlugin-hook (5), useLayout-hook (4)
• Exported easeInOutCubic from useAnimatedLayout.ts for independent testing

Completed in v2.4.0

• 4 new test suites — drag-state-machine (11), action-types-enums (9), event-types-enums (10), gesture-rules-types (6)

Completed in v2.3.0

• 5 new test suites — actions-node, actions-viewport, modifier-helpers, pointer-bindings-v2, plugin-types (34 tests)

Completed in v2.2.0

• Split built-in-actions.ts (342L → 44L barrel) into actions-node.ts + actions-viewport.ts
• 6 new test suites — keyboard-bindings, gesture-classification, viewport-commands, serialization-commands, store-atoms, command-executor (38 tests)

Completed in v2.1.0

• 2 new test suites — command-line-store (11), storage-adapter (10)

Completed in v2.0.0

• Renamed gesturesV2 → gestures — clean namespace
• Removed deprecated re-exports — action-executor, settings-store test suites added

Completed in v1.2.0

• Plugin system — unified CanvasPlugin manifest with dependency resolution, conflict detection, atomic registration/rollback, and lifecycle hooks
• 4 new files — plugin-types.ts, plugin-registry.ts, edge-path-registry.ts, usePlugin.ts
• Canvas auto-routing — renderNode now optional; node type registry resolves components by node_type
• unregisterNodeType() — per-type removal for clean plugin teardown
• 2 new test suites — plugin-registry (28 tests), edge-path-registry (8 tests)

Completed in v1.1.0

• Split useRegisterInputActions.ts (528L → 259L) — extracted input-action-helpers.ts with pure store helpers for navigation, selection, mutation, and escape logic
• Split useCanvasGestures.ts (667L → 518L) — extracted useGuardContext.ts and useInertia.ts for guard context and inertia management
• 2 new test suites — input-action-helpers (28 tests), useInertia (5 tests)
• 8 bug fixes — WeakMap cache isolation, mutation queue clearing, balanced startMutation counts, config threading, localStorage namespacing, and more

Completed in v1.0.0

• API Stability audit — all 219+ atoms verified for {noun}{Verb}Atom naming; docs/api-stability.md classifying all 8 entry points
• Migration guide — docs/migration-v1.md covering breaking changes from v0.x → v1.0
• Peer dep cleanup — peerDependenciesMeta marking d3-force, @blocknote/*, @tanstack/react-query as optional
• Hook test coverage — 3 new test suites for useNodeDrag, useNodeResize, useForceLayout atoms
• Version bump — package.json, index.ts, CHANGELOG.md, README.md all at 1.0.0

Completed in v0.36.0

• Split contexts.ts (614L → 100L) into keyboard-contexts.ts + pointer-contexts.ts
• 3 new test suites — gesture-specificity, gesture-mapper, gesture-dispatcher (~30 tests)

Completed in v0.35.0

• 3 new test suites — gesture-inertia, timed-state, gesture-normalize (+26 tests)
• Covers VelocitySampler, PanInertia, ZoomInertia, timed state machine, modifier extraction

Completed in v0.34.0

• Split useNodeDrag.ts — extracted drag types into hooks/drag-types.ts
• 2 new test suites — gesture-rules-defaults, keyboard-shortcuts (+13 tests)

Completed in v0.33.0

• Split settings-store.ts — extracted presets + utility into settings-presets.ts
• 1 new test suite — settings-presets (+9 tests)

Completed in v0.32.0

• Split history-store.ts — extracted pure delta functions into history-actions.ts
• 2 new test suites — history-actions, group-store-utils (+21 tests)

Completed in v0.31.0

• Split commands/store.ts into state atoms + action atoms
• 3 new test suites — commands-registry, commands-executor, commands-store (+31 tests, 670 total)

Completed in v0.30.0

• Split gesture-rules.ts into types + defaults + resolver
• 3 new test suites — sync-store, gesture-rule-store, gesture-configs (+32 tests, 639 total)

Completed in v0.29.0

• Split action-registry.ts into registry + built-in-actions
• 4 new test suites — graph-mutations-edges, graph-mutations-advanced, debug, component-registry (+32 tests, 607 total)

Completed in v0.28.0

• Split graph-mutations.ts into 3 modules (node, edge, advanced)
• 4 new test suites — layout, hit-test, action-executor, mutation-queue (+33 tests, 575 total)

Completed in v0.27.0

• 4 new test suites — settings-store, edge-path-calculators, snap-store, locked-node-store (+53 tests, 542 total)
• history-types.ts — modularized history type definitions

Completed in v0.26.0

• Minimap edges — draw edge lines between node centers
• Fuzzy search — multi-token, edge labels/types, EdgeRenderer integration
• Smart alignment guides — node-to-node snapping with AlignmentGuides component
• Clipboard cut — now deletes nodes with undo support (489 tests, 36 files)

Completed in v0.25.0

• 8 new test suites — graph-mutations, graph-derived, graph-position, action-registry, interaction-store, reduced-motion, external-keyboard, toast (474 total across 35 files)
• Split TouchActionButton — 559 → 3 files (icons, RadialMenu, index)

Completed in v0.24.0

• prefers-reduced-motion — atom + CSS + 3 JS consumers (inertia, layout, edge fade)
• Undo/redo in FAB — primary actions with UndoIcon/RedoIcon
• Safe-area margins — ViewportControls + TouchActionButton
• Cursor hiding — @media (pointer: coarse) + data-canvas-root
• External keyboard detection — hides FAB when modifier keys available

Completed in v0.23.0

• Slimmed barrel — core/index.ts 458 → 85 lines (export * for all modules)
• Removed deprecated — findPortAtPosition, resolveGestureIntent, isBackgroundGesture

Completed in v0.22.0

• Split graph-store.ts — 914 → 68 lines, 3 new modules (graph-position, graph-derived, graph-mutations)

Completed in v0.21.0

• Unified logging — 33 console.* → createDebug with .warn()/.error() sub-loggers

Completed in v0.20.0

• atomFamily migration — jotai/utils → jotai-family (jotai v3 ready)
• Dead CanvasConfig type removed — stale Supabase fields
• hitTestNode / hitTestPort — testable hit-test utilities replacing DOM coupling

Completed in v0.17.0

• EdgePreviewLine — animated SVG bezier preview during drag
• Drag-from-port — click port to start edge creation
• Port snap visual — glow + scale on compatible ports during drag
• canConnect validation — callback to reject invalid connections

Completed in v0.16.0

• Deprecated export removal — resolveGestureIntent, legacy gesture configs, useSupabaseClient, Supabase provider props
• README refresh — Gesture System v2, Performance, updated architecture
• TODO cleanup — removed shipped items, added real roadmap

Completed in v0.15.0

• Spatial grid index — SpatialGrid for O(visible) node culling in virtualization
• Edge structural equality — _edgeCache prevents re-renders when data hasn't changed
• uiNodesAtom structural equality — previous array reuse when entries match
• Performance instrumentation — canvasMark/canvasWrap with opt-in setPerfEnabled
• Gestures subpath export — @blinksgg/canvas/gestures for code splitting
• 17 new tests — spatial-index (12), perf (5)

Completed in v0.14.0

• Gesture System v2 — unified pointer + keyboard input pipeline with 4-layer architecture
• Specificity-scored binding resolution — patterns scored by type, key, subjectKind, modifier, source, button
• Built-in mapping contexts — palm rejection, active interaction, search, keyboard navigate/manipulate, default
• Held keys + custom modifiers — HeldKeysState, Modifiers.custom for non-keyboard flags
• Phase-aware action handlers — PhaseHandler with onStart/onMove/onEnd/onInstant/onCancel
• 5 new test suites — specificity, mapper, timed-state, palm-rejection, inertia

Completed in v0.13.0

• Undo/redo for structural operations — split, merge, nest, group, ungroup all push history snapshots
• Undo/redo toast — CanvasToast shows operation label on Ctrl+Z/Y
• Tree layout — useTreeLayout hook + treeLayout/horizontalLayout commands
• Grid layout — useGridLayout hook + gridLayout command
• Animated layout transitions — useAnimatedLayout shared hook with cubic easing
• Zoom inertia — momentum after pinch-to-zoom lifts
• Snap-to-100% zoom — detent at 1.0x zoom
• Simultaneous pan during pinch — fluid two-finger gestures
• Tap pulse on controls — canvas-tap-pulse CSS animation
• 19 new tests — 404 total

Completed in v0.12.0

• Drag-to-nest — drag a node over another to nest; dropTargetNodeIdAtom, nestNodesOnDropAtom, drop-target highlight CSS
• Two-finger split — diverging fingers split a node into two copies with duplicated edges; splitNodeAtom, useSplitGesture
• Merge nodes — Ctrl+M merges selected nodes; edges re-routed, internal edges discarded; mergeNodesAtom, mergeNodesCommand
• split-node gesture intent — pinch-on-node now maps to split instead of zoom
• 18 new tests — 385 total

Completed in v0.11.0

• Nested group drag — getNodeDescendants helper + useNodeDrag expands initialPositions to include all descendants
• Edge creation/deletion animations — departingEdgesAtom + removeEdgeWithAnimationAtom for fade-out; CSS fade-in for new edges
• Edge label editing — editingEdgeLabelAtom + updateEdgeLabelAtom + EdgeLabelEditor component with inline HTML input
• edgeFamilyAtom reactivity fix — now depends on graphUpdateVersionAtom for non-position attribute changes
• 14 new tests — 367 total

Completed in v0.10.0

• Edge re-routing — collapsedEdgeRemapAtom maps collapsed children to outermost collapsed ancestor; edges re-route to group node
• Group auto-resize — autoResizeGroupAtom recomputes group bounding box on drag end
• Search keyboard shortcuts — Ctrl+F, Enter/Shift+Enter, Ctrl+G, Escape
• Edge search dimming — edges dim with 150ms transition when neither endpoint matches
• Search highlight pulse — amber box-shadow animation on highlighted result
• CanvasAnimations component — CSS keyframe injection
• 11 new tests — 353 total

Completed in v0.9.0

• Abstract persistence — CanvasStorageAdapter interface, SupabaseStorageAdapter, InMemoryStorageAdapter, storageAdapterAtom
• Node grouping — parentId on nodes, GroupNode component, collapse/expand, group commands
• Search & filter — searchQueryAtom, searchResultsAtom, node dimming, search commands
• Component tests — 39 React component tests (Canvas, Node, Viewport, Minimap, SelectionOverlay, GroupNode)
• 89 new tests — 342 total

Completed in v0.8.0

• Minimap — <canvas>-based overview with draggable viewport rectangle
• Lasso selection — pencil freeform selection with point-in-polygon test
• Rect selection — Shift+drag rectangle selection with AABB intersection
• Zoom animations — animateZoomToNodeAtom, animateFitToBoundsAtom with cubic easing
• useZoomTransition — rAF-based animation hook
• 39 new tests — selection-path-store + zoom-transition

Completed in v0.7.0

• Arrow key navigation — spatial navigation between nodes with Tab cycling and focus ring
• Edge re-render optimization — O(connected edges) per drag frame instead of O(all edges)
• Test coverage — 47 → 214 tests covering all core stores + headless API
• Headless API — createCanvasAPI(store) for full programmatic control without React
• Doc consolidation — PRINCIPLES.md + single README.md + TODO.md