# Canvas Graph Query Implementation Plan

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

**Goal:** Reduce canvas hot-path Convex query overhead by collapsing `nodes:list` and `edges:list` into one shared graph query and keeping the optimistic client cache aligned with that query.

**Architecture:** Add a new Convex `canvasGraph.get` query that performs auth and canvas authorization once, then returns both node and edge collections together. Update the canvas data hook and optimistic local cache helpers to use this graph query as the primary reactive source while leaving the existing list queries available for other callers.

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

---

### Task 1: Add a shared Convex graph query

**Files:**
- Create: `convex/canvasGraph.ts`
- Test: `tests/convex/canvas-graph-query.test.ts`

**Step 1:** Write a failing test that expects one graph query to return both nodes and edges for an authorized canvas.

**Step 2:** Run the targeted test and verify it fails for the expected missing-module or missing-export reason.

**Step 3:** Implement `canvasGraph.get` with one auth check, one canvas authorization check, and indexed `nodes` + `edges` reads.

**Step 4:** Re-run the targeted test and confirm it passes.

### Task 2: Switch the canvas hook to the graph query

**Files:**
- Modify: `components/canvas/use-canvas-data.ts`
- Test: `tests/use-canvas-data.test.tsx`

**Step 1:** Write a failing hook test that expects `useCanvasData` to subscribe to the graph query and derive `convexNodes` / `convexEdges` from it.

**Step 2:** Run the targeted test and verify it fails for the expected reason.

**Step 3:** Update the hook to use the graph query result as the primary canvas model without changing the public hook return shape.

**Step 4:** Re-run the targeted test and confirm it passes.

### Task 3: Keep optimistic cache updates aligned with the graph query

**Files:**
- Modify: `components/canvas/use-canvas-sync-engine.ts`
- Create: `components/canvas/canvas-graph-query-cache.ts`
- Test: `components/canvas/__tests__/canvas-graph-query-cache.test.ts`

**Step 1:** Write failing tests for small cache helpers that read and update graph query data during optimistic mutations.

**Step 2:** Run the targeted helper tests and verify they fail for the expected missing-helper reason.

**Step 3:** Implement the helpers and update optimistic mutations to use them so online optimistic canvas updates still work with the new graph query.

**Step 4:** Re-run the targeted tests and confirm they pass.

### Task 4: Verify the hot-path refactor

**Files:**
- Verify only

**Step 1:** Run the targeted new tests for the graph query, hook, and cache helpers.

**Step 2:** Run `pnpm test` to confirm the full suite stays green.

**Step 3:** Run `pnpm lint` on the worktree and fix any regressions in touched files.