lemonspace_app/docs/plans/2026-04-03-canvas-modularization.md

# Canvas Modularization Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Split `components/canvas/canvas.tsx` into clear, testable domain hooks while preserving all current canvas behavior and public APIs.

**Architecture:** Keep `components/canvas/canvas.tsx` as the composition root and extract the largest logic clusters into domain-specific hooks. Start with sync and reconciliation because they are the most complex and most reusable, then move connection and drop flows, and only then extract a presentational view if it still adds value.

**Tech Stack:** Next.js 16, React 19, Convex, React Flow, TypeScript

---

### Task 1: Lock in the current modularization seams

**Files:**
- Modify: `components/canvas/canvas.tsx`
- Reference: `components/canvas/CLAUDE.md`
- Reference: `docs/plans/2026-04-03-canvas-modularization-design.md`

**Step 1:** Annotate the major responsibility boundaries inside `components/canvas/canvas.tsx` by grouping the existing code into the future modules: sync engine, reconciliation, interactions, connections, drop, and render.

**Step 2:** List the exact state, refs, callbacks, and mutations owned by each future hook in a scratch note or temporary checklist before moving code.

**Step 3:** Identify cross-cutting refs that must stay shared at the orchestrator level, especially optimistic ID handoff state and React Flow instance access.

**Step 4:** Remove the scratch note once the extraction map is clear.

### Task 2: Extract pure helper logic from effect bodies first

**Files:**
- Modify: `components/canvas/canvas.tsx`
- Modify: `components/canvas/canvas-helpers.ts`
- Create: `components/canvas/canvas-flow-reconciliation-helpers.ts`
- Test: `components/canvas/__tests__/canvas-flow-reconciliation-helpers.test.ts`

**Step 1:** Move deterministic edge reconciliation helpers out of `useLayoutEffect` bodies into `components/canvas/canvas-flow-reconciliation-helpers.ts`.

**Step 2:** Move deterministic node reconciliation helpers out of `useLayoutEffect` bodies into `components/canvas/canvas-flow-reconciliation-helpers.ts`.

**Step 3:** Add tests for optimistic edge carry, endpoint remapping, and position pin cleanup.

**Step 4:** Update `components/canvas/canvas.tsx` to call the extracted helpers without changing behavior.

### Task 3: Extract the sync engine hook

**Files:**
- Create: `components/canvas/use-canvas-sync-engine.ts`
- Modify: `components/canvas/canvas.tsx`
- Reference: `lib/canvas-op-queue.ts`
- Reference: `lib/canvas-local-persistence.ts`
- Test: `components/canvas/__tests__/use-canvas-sync-engine.test.ts`

**Step 1:** Create `useCanvasSyncEngine` with the queue state, online state, and mutation wrappers that are currently centered around `components/canvas/canvas.tsx:258` and `components/canvas/canvas.tsx:984`.

**Step 2:** Move deferred optimistic-node handling into the new hook, including pending resize, pending data, and pending move-after-create behavior.

**Step 3:** Return a clear API from the hook for create, move, resize, update-data, remove-edge, batch-remove, and split-edge flows.

**Step 4:** Replace the local inline sync logic in `components/canvas/canvas.tsx` with the hook.

**Step 5:** Add focused tests for optimistic create handoff and deferred resize/update behavior.

### Task 4: Extract the flow reconciliation hook

**Files:**
- Create: `components/canvas/use-canvas-flow-reconciliation.ts`
- Modify: `components/canvas/canvas.tsx`
- Modify: `components/canvas/canvas-flow-reconciliation-helpers.ts`
- Test: `components/canvas/__tests__/use-canvas-flow-reconciliation.test.ts`

**Step 1:** Create `useCanvasFlowReconciliation` to own the current Convex-to-local `useLayoutEffect` synchronization for nodes and edges.

**Step 2:** Pass in only the data it needs: Convex nodes, Convex edges, storage URLs, theme mode, local setters, and shared optimistic refs.

**Step 3:** Keep drag-lock and resize-lock behavior unchanged while moving the effects.

**Step 4:** Add tests or targeted assertions for the drag-lock and optimistic carry behavior that are hardest to reason about from the UI.

### Task 5: Extract node interaction logic

**Files:**
- Create: `components/canvas/use-canvas-node-interactions.ts`
- Modify: `components/canvas/canvas.tsx`
- Reference: `components/canvas/canvas-node-change-helpers.ts`

**Step 1:** Move `onNodesChange`, edge intersection highlighting, drag start, drag, and drag stop into `useCanvasNodeInteractions`.

**Step 2:** Keep the returned API explicit: handlers plus any local highlight state helpers.

**Step 3:** Preserve all resize side effects and split-edge-on-drop behavior exactly.

**Step 4:** Manually verify drag, resize, and edge split interactions on the canvas page.

### Task 6: Extract connection flows

**Files:**
- Create: `components/canvas/use-canvas-connections.ts`
- Modify: `components/canvas/canvas.tsx`
- Reference: `components/canvas/canvas-reconnect.ts`
- Reference: `components/canvas/canvas-connection-drop-menu.tsx`

**Step 1:** Move `onConnect`, `onConnectEnd`, connection drop menu state, and `handleConnectionDropPick` into `useCanvasConnections`.

**Step 2:** Keep validation centralized around `validateCanvasConnection` and `validateCanvasConnectionByType`.

**Step 3:** Reuse the existing reconnect hook by adapting it through the new connection hook rather than rewriting reconnect behavior.

**Step 4:** Manually verify valid connection creation, invalid connection rejection, reconnect, and connection-drop node creation.

### Task 7: Extract drag-and-drop creation flows

**Files:**
- Create: `components/canvas/use-canvas-drop.ts`
- Modify: `components/canvas/canvas.tsx`
- Reference: `components/canvas/canvas-media-utils.ts`

**Step 1:** Move `onDragOver` and `onDrop` into `useCanvasDrop`.

**Step 2:** Keep support for both sidebar/browser JSON payloads and raw node type strings.

**Step 3:** Preserve file upload drop behavior, including image dimension lookup and upload error toasts.

**Step 4:** Manually verify node drop and image file drop flows.

### Task 8: Decide whether a presentational view extraction is still useful

**Files:**
- Create: `components/canvas/canvas-view.tsx`
- Modify: `components/canvas/canvas.tsx`

**Step 1:** Measure the remaining size and readability of `components/canvas/canvas.tsx` after hook extraction.

**Step 2:** If the file still mixes visual structure with too much prop assembly, move the JSX tree into `components/canvas/canvas-view.tsx`.

**Step 3:** Keep `canvas-view.tsx` presentational only; it should not own data-fetching, queue logic, or reconciliation effects.

**Step 4:** Skip this task entirely if the orchestrator is already clearly readable.

### Task 9: Verify behavior after each extraction phase

**Files:**
- Verify only

**Step 1:** Run `pnpm lint components/canvas/canvas.tsx components/canvas/*.ts components/canvas/*.tsx` or the project-equivalent lint command for touched files.

**Step 2:** Run `pnpm tsc --noEmit` or the project-equivalent type-check command.

**Step 3:** Run the targeted canvas tests added during the refactor.

**Step 4:** Manually verify these flows on the real canvas page: create node, drag node, resize node, connect nodes, reconnect edge, delete node, drop node from sidebar, and drop image file.

### Task 10: Finish with small, reviewable commits

**Files:**
- Commit only

**Step 1:** Commit after Task 3 with a message like `refactor(canvas): extract sync engine hook`.

**Step 2:** Commit after Task 4 with a message like `refactor(canvas): extract flow reconciliation hook`.

**Step 3:** Commit after Tasks 5 to 7 with messages scoped to interactions, connections, and drop handling.

**Step 4:** If Task 8 is done, commit it separately as `refactor(canvas): extract canvas view`.