canvas/docs/plan-v1.0.md

# @blinksgg/canvas v1.0 Release Plan

**Current version:** 0.36.0 "Gesture Pipeline"
**Target:** 1.0.0 "Stable Canvas"
**Status:** Pre-release audit complete

---

## Executive Summary

The canvas package is **v1.0-ready in its core**. 72 test suites, zero TODO/FIXME comments, clean TypeScript, comprehensive docs. The remaining work falls into two categories: **API stabilization** (naming/export cleanup before locking semver) and **test coverage for complex hooks** (should-have).

---

## Current State Assessment

### What's Solid (No Work Needed)

| Area | Evidence |
|------|----------|
| Core state management | 100% test coverage, 25+ atom modules |
| Gesture pipeline v2 | 13 test suites, 4-layer architecture, specificity scoring |
| Command system | 4 test suites, 50+ built-in commands, keyboard shortcuts |
| Error handling | Error boundaries, rollback on failed mutations, 6 catch blocks |
| Documentation | 1,050-line README, PRINCIPLES.md, CHANGELOG, architecture docs |
| Performance | React Compiler, virtualization, spatial grid, structural equality |
| Type safety | `tsc --noEmit` clean, zero `@ts-ignore` in production code |
| Code quality | Zero TODO/FIXME/HACK comments |

### What Needs Work

```mermaid
flowchart LR
    subgraph MUST["Must-Have (Phase 1)"]
        API[API Stabilization<br/>naming + export audit]
        HOOK_TESTS[Hook Tests<br/>useNodeDrag, useNodeResize]
    end
    subgraph SHOULD["Should-Have (Phase 2)"]
        COMP_TESTS[Component Tests<br/>CommandLine, NodePorts]
        MIGRATION[Migration Guide<br/>v0.x → v1.0]
        PEERDEP[Peer Dep Cleanup<br/>optional vs required]
    end
    subgraph NICE["Nice-to-Have (Phase 3)"]
        PLUGIN[Plugin API<br/>extensible architecture]
        DEV_OVERLAY[Dev Overlay<br/>debug panel]
        MULTI[Multi-user Cursors<br/>realtime presence]
    end
    MUST --> SHOULD --> NICE
```

---

## Phase 1: Must-Have (Target: v0.37–v0.39)

### 1.1 API Stabilization

**Why:** Once v1.0 ships, every export is a semver contract. Clean up naming inconsistencies and remove anything that shouldn't be public.

**Tasks:**

| Task | Details |
|------|---------|
| Audit atom naming | Ensure all public atoms follow `{noun}{Verb}Atom` pattern (e.g., `selectedNodeIdsAtom`, not mixed styles) |
| Review `core/index.ts` exports | Currently `export *` for 22 modules. Evaluate if any internal atoms leak that shouldn't be public |
| Gesture v2 namespace | Currently `gesturesV2` namespace on root. Decide: keep namespace (safe) or flatten (breaking). Recommend: keep namespace for v1.0, flatten in v2.0 |
| `onAction` callback type | Already fixed: `InputEvent` union. Document the narrowing pattern (`event.kind === 'key'` guard) in README |
| DB layer optionality | Mark `@blinksgg/canvas/db` exports as `@experimental` or document clearly that the storage adapter API may change |
| Component prop stability | Review all component Props interfaces. Add `@public` JSDoc to stable ones, `@beta` to ones that may change |

**Deliverable:** `docs/api-stability.md` documenting what's stable vs experimental.

---

### 1.2 Hook Test Coverage

**Why:** `useNodeDrag` (450 lines) and `useNodeResize` (280 lines) are the two most complex hooks. They're tested indirectly via component tests but have no isolated unit coverage. A regression here breaks the core experience.

**Tasks:**

| Hook | Lines | Priority | What to test |
|------|-------|----------|--------------|
| `useNodeDrag` | 450 | HIGH | Drag start/move/end, snap-to-grid, group drag, history push, persistence callback, cancel |
| `useNodeResize` | 280 | HIGH | Resize all 8 directions, min size enforcement, snap, history push, persistence callback |
| `useForceLayout` | 350 | MEDIUM | Layout converges, cancellation, `onPositionsChanged` callback |
| `useAnimatedLayout` | 180 | MEDIUM | Animation interpolation, cancel mid-animation, reduced-motion skip |
| `useCommandLine` | 80 | LOW | Open/close state, search filtering |

**Test approach:** Use Jotai test store + mock graph. No React rendering needed for most — test via `store.set()` / `store.get()` on the atoms the hooks wrap.

---

## Phase 2: Should-Have (Target: v0.40–v0.42)

### 2.1 Component Test Coverage

Current: 39/50+ components tested (78%). Add tests for:

| Component | Why | Approach |
|-----------|-----|----------|
| `CommandLine` | Complex keyboard-driven UI with state machine | Render test with mock command registry |
| `NodeContextMenu` | Adaptive layout (bottom sheet vs dialog) | Render test with open/close/action |
| `NodePorts` | Port expansion, compatibility checking, hit targets | Render test with port definitions |
| `EdgeRenderer` | Search dimming, animation classes, path calculation | Snapshot test with mock edges |
| `SettingsPanel` | Headless styling, preset management | Render test with className props |

### 2.2 Peer Dependency Cleanup

Split peer deps into required and optional with clear messaging:

```json
{
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "jotai": "^2.6.0"
  },
  "peerDependenciesMeta": {
    "d3-force": { "optional": true },
    "@tanstack/react-query": { "optional": true },
    "jotai-tanstack-query": { "optional": true },
    "@blocknote/core": { "optional": true },
    "@blocknote/react": { "optional": true },
    "@blocknote/shadcn": { "optional": true }
  }
}
```

Document in README which features require which optional deps.

### 2.3 Migration Guide

Create `docs/migration-v1.md`:

- Breaking changes since v0.6 (React 19, gesture v2, removed exports)
- `onAction` type change (`GestureEvent` → `InputEvent`)
- Gesture system v1 → v2 mapping table
- Storage adapter migration (Supabase provider → adapter pattern)
- Import path changes

### 2.4 apps/web Integration Audit

The main app (`apps/web`) uses canvas via 21 import files with clean wrapper patterns:
- Hook wrappers: `useNodeDrag`, `useNodeResize` add React Query persistence
- Component wrappers: `EdgeOverlay`, `NodeContextMenu`, `LockedNodeOverlay` add app-specific behavior
- Provider wrapper: `AppCommandProvider` binds commands to React Query mutations
- Re-export hub: `store.ts` centralizes all canvas atoms

**Action:** Verify none of these wrappers depend on internal/unstable exports. If any do, either promote those exports to public API or refactor the wrappers.

---

## Phase 3: Nice-to-Have (v1.x Roadmap)

These are post-v1.0 features from TODO.md, scoped for minor releases:

### v1.1 — Plugin API

- Standardize `registerAction()` + `registerCommand()` as the plugin surface
- Document custom node type registration (`createComponentRegistry`)
- Export gesture binding builder for third-party gesture definitions
- Example: "How to build a custom node type" tutorial

### v1.2 — Dev Overlay

- Floating debug panel (FPS, graph stats, event log, perf metrics)
- Toggle with keyboard shortcut (`Ctrl+Shift+D`)
- Useful for consumers debugging their canvas integrations
- Currently roughed out in the demo's FPS counter and sidebar stats

### v1.3 — Multi-user Cursors

- Realtime cursor presence via storage adapter subscription
- `CursorOverlay` component showing remote user positions
- Requires extending `CanvasStorageAdapter` with presence methods
- Heaviest lift — new atoms, components, and adapter interface changes

---

## Release Checklist

```
Pre-release:
[ ] Phase 1.1 — API audit (naming, exports, @public/@beta tags)
[ ] Phase 1.2 — Hook tests (useNodeDrag, useNodeResize minimum)
[ ] Phase 2.2 — Peer dep cleanup (peerDependenciesMeta)
[ ] Phase 2.3 — Migration guide

Release:
[ ] Bump version to 1.0.0 in package.json + src/index.ts
[ ] Update CHANGELOG.md with v1.0.0 entry
[ ] Update README.md hero section ("v1.0 — Stable Release")
[ ] Update TODO.md (move completed items, update roadmap)
[ ] Rebuild: pnpm --filter @blinksgg/canvas build
[ ] Run full test suite: pnpm --filter @blinksgg/canvas test
[ ] Type check: pnpm --filter @blinksgg/canvas check-types
[ ] Tag: git tag v1.0.0
[ ] Update canvas-demo to showcase v1.0 features

Post-release:
[ ] Phase 2.4 — apps/web integration audit
[ ] Phase 3.1 — Plugin API (v1.1)
[ ] Phase 3.2 — Dev Overlay (v1.2)
```

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| API audit reveals breaking changes needed | LOW | HIGH | If found, ship as v1.0-rc.1 for consumer testing before final |
| Force layout d3-force peer dep confusion | LOW | LOW | Already optional; document clearly |
| React 19 min version locks out consumers | LOW | MEDIUM | React 19 is stable and widely adopted; acceptable trade-off |

---

## Metrics for Success

| Metric | Target |
|--------|--------|
| Test suites | 80+ (currently 72) |
| TypeScript errors | 0 (currently 0) |
| TODO/FIXME in source | 0 (currently 0) |
| Hook test coverage | useNodeDrag + useNodeResize isolated tests |
| README completeness | Migration guide, perf guide |
| Demo coverage | All exported components wired (done in v0.15 demo) |