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:

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