226 lines
8.8 KiB
Markdown
226 lines
8.8 KiB
Markdown
# @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) |
|