canvas/docs/api-stability.md

@blinksgg/canvas — API Stability

This document defines the stability level of each export entry point. Stable APIs follow semver — breaking changes only in major versions.

Stability Levels

• Stable — Safe for production. Breaking changes only in major versions.
• Beta — API may change in minor versions. Use with awareness.
• Experimental — API may change in any release. Not recommended for production.

Entry Points

@blinksgg/canvas (root) — Stable

The main barrel export. Re-exports from all subpackages.

Export	Stability	Notes
Canvas component	Stable	Main orchestrator
canvasVersion	Stable	Version info object
All components	Stable	See components section below
All hooks	Stable	See hooks section below
All core atoms	Stable	219+ atoms, consistent *Atom naming

@blinksgg/canvas/core — Stable

Headless state management. All Jotai atoms, types, and pure functions.

Module	Stability	Notes
graph-store	Stable	Graph state, graphId, edge creation
graph-position	Stable	Node position atoms and families
graph-derived	Stable	Computed atoms (uiNodes, nodeKeys, edgeKeys)
graph-mutations	Stable	Node/edge CRUD operations
viewport-store	Stable	Zoom, pan, viewport transforms
selection-store	Stable	Node/edge selection management
history-store	Stable	Delta-based undo/redo
clipboard-store	Stable	Copy/cut/paste/duplicate
snap-store	Stable	Grid snapping, alignment guides
group-store	Stable	Node grouping/nesting
search-store	Stable	Node/edge search and filter
toast-store	Stable	Toast notifications
interaction-store	Stable	Input modes, picking
settings-store	Stable	Event-action mappings, presets
action-registry	Stable	Action handler registration
virtualization-store	Stable	Viewport culling metrics
locked-node-store	Stable	Detail view lock/unlock
sync-store	Stable	Mutation queue, online status
input-store	Stable	Pointer tracking, input classification
port-types	Stable	Port definition types
types	Stable	Core type definitions
canvas-api	Stable	Headless programmatic API
spatial-index	Stable	O(visible) spatial grid
perf	Stable	Performance instrumentation
gesture-rules	Stable	Composable gesture rule system
gesture-resolver	Stable	Intent resolution types
reduced-motion-store	Stable	prefers-reduced-motion support
external-keyboard-store	Stable	External keyboard detection
input-classifier	Stable	Pointer source classification
node-type-registry	Stable	Custom node type registration

@blinksgg/canvas/hooks — Stable

React hooks for canvas interaction.

Hook	Stability	Notes
useCanvasSelection	Stable	Selection state subscription
useCanvasViewport	Stable	Viewport state subscription
useCanvasDrag	Stable	Drag state subscription
useCanvasHistory	Stable	Undo/redo with keyboard shortcuts
useNodeSelection	Stable	Per-node selection
useNodeDrag	Stable	Per-node drag mechanics
useNodeResize	Stable	Per-node resize mechanics
useFitToBounds	Stable	Fit viewport to selection/graph
useLayout	Stable	Layout engine base
useTreeLayout	Stable	Hierarchical tree layout
useGridLayout	Stable	Grid layout
useAnimatedLayout	Stable	Shared animation interpolation
useForceLayout	Stable	D3 force-directed layout (requires d3-force)
useCanvasSettings	Stable	Settings/preset management
useActionExecutor	Stable	Action execution
useVirtualization	Stable	Virtualization toggle/metrics
useCanvasGraph	Stable	Graph structure access
useCommandLine	Stable	Command palette state
useGestureResolver	Stable	Gesture resolution
useArrowKeyNavigation	Stable	Arrow key navigation
useZoomTransition	Stable	Animated zoom state
useTapGesture	Stable	Cross-input tap detection
useSplitGesture	Stable	Two-finger node split
usePlugin	Stable	Single plugin registration/lifecycle
usePlugins	Stable	Multi-plugin registration/lifecycle

@blinksgg/canvas/components — Stable

All React components.

Component	Stability	Notes
Canvas	Stable	Main component with gesture pipeline
Viewport	Stable	Pan/zoom container
NodeRenderer	Stable	Renders nodes with virtualization
Node	Stable	Individual node wrapper
EdgeRenderer	Stable	Renders edges with animations
SelectionOverlay	Stable	Lasso/rect selection
Minimap	Stable	Canvas overview
ViewportControls	Stable	Pan/zoom UI
GroupNode	Stable	Group container
CommandLine	Stable	Command palette UI
CommandFeedbackOverlay	Stable	Command input feedback
NodeContextMenu	Stable	Right-click context menu
NodePorts	Stable	Connection port bars
EdgeOverlay	Stable	Edge creation via drag
EdgePreviewLine	Stable	Edge drag preview
EdgeLabelEditor	Stable	Inline edge label editing
ResizeHandle	Stable	Node resize handles
Grid, Crosshairs	Stable	Background grid
AlignmentGuides	Stable	Snap alignment lines
CanvasAnimations	Stable	CSS animation injection
CanvasToast	Stable	Toast notifications
TouchActionButton	Stable	Mobile FAB radial menu
SettingsPanel	Stable	Headless settings UI
NodeTypeCombobox	Stable	Node type selector
LockedNodeOverlay	Stable	Full-screen node detail
NodeErrorBoundary	Stable	Per-node error isolation
ConnectedNode	Beta	Supabase-connected wrapper
ConnectedNodeRenderer	Beta	Supabase-connected renderer

@blinksgg/canvas/commands — Stable

Command palette system.

Export	Stability	Notes
CommandProvider	Stable	Context provider
commandRegistry	Stable	Command registration
registerBuiltinCommands	Stable	Register all defaults
All command atoms	Stable	State management
useGlobalKeyboard	Stable	Keyboard shortcut handling
Built-in commands	Stable	Viewport, selection, history, layout, clipboard, grouping

@blinksgg/canvas/gestures — Stable

Gesture system v2. Exported from @blinksgg/canvas/gestures.

Export	Stability	Notes
Types (InputEvent, ResolvedAction, etc.)	Stable	Core gesture types
resolve, dispatch	Stable	Resolution and dispatch functions
InputProvider, GestureProvider	Stable	React providers
useCanvasGestures	Stable	Canvas-level gesture handling
useNodeGestures	Stable	Node-level gesture handling
useGestureSystem	Stable	Full gesture system access
useInputSystem	Stable	Input pipeline access
Built-in contexts	Stable	DEFAULT, PALM_REJECTION, etc.

@blinksgg/canvas/db — Stable

Database integration layer. The storage adapter interface is settling but may evolve.

Export	Stability	Notes
CanvasStorageAdapter interface	Beta	Abstract persistence interface
SupabaseStorageAdapter	Beta	Supabase implementation
InMemoryStorageAdapter	Stable	Test/demo adapter
CanvasDbProvider	Beta	Database provider component
DB hooks (useCreateNode, etc.)	Beta	React Query integration

@blinksgg/canvas/nodes — Beta

Pre-built node types.

Export	Stability	Notes
NoteNode	Beta	Rich text node (requires @blocknote)

@blinksgg/canvas/utils — Stable

Utility functions.

Export	Stability	Notes
Layout utilities	Stable	Bounds calculation, overlap detection
Edge path calculators	Stable	8 path types (bezier, straight, step, etc.)
Hit-test utilities	Stable	Node/port hit detection
Debug utilities	Stable	Namespaced logging
Gesture config utilities	Stable	Input-source-aware thresholds

Naming Conventions

All 219+ public atoms follow consistent naming:

• State atoms: {nounPhrase}Atom — e.g., graphAtom, selectedNodeIdsAtom
• Derived atoms: {is|has|can}{Phrase}Atom — e.g., canUndoAtom, hasSelectionAtom
• Action atoms: {verb}{Noun}Atom — e.g., pushHistoryAtom, clearSelectionAtom
• Family atoms: {noun}FamilyAtom or {noun}AtomFamily — e.g., nodePositionAtomFamily

onAction Callback Type

The Canvas component's onAction prop accepts (event: InputEvent, resolution: ResolvedAction) => void.

InputEvent is a union of PointerGestureEvent | KeyInputEvent. To handle pointer-only events:

onAction={(event, resolution) => {
  if (event.kind === 'key') return;
  const { subject, worldPosition } = event; // narrowed to PointerGestureEvent
  // ...
}}