pmx-canvas 0.4.7 → 0.4.8

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -18,6 +18,38 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
+/**
+ * Finding N (0.4.7 report): the GitHub Copilot panel's WKWebView reports
+ * `document.visibilityState === 'hidden'` CONTINUOUSLY — the workbench document
+ * never transitions to 'visible' even with the panel open and on-screen. Two
+ * things break as a result: the `visibilitychange` re-arm below can never fire
+ * (there is no transition to listen for), and `paint-ok` becomes a false green —
+ * the app document happily answers the double-rAF paint probe while the
+ * compositor still shows black. The instrumented trail from that session carries
+ * `visibility: "hidden"` on essentially every recovery event.
+ *
+ * So: when the document CLAIMS hidden but the frame is demonstrably on-screen,
+ * do not trust the claim — spend one more recovery round as if visible. A host
+ * that ever reports 'visible' has a working signal and is left to the
+ * visibilitychange path, which keeps a genuinely backgrounded panel quiet.
+ */
+export declare function shouldAssumeVisibleRearm(options: {
+    userAgent: string;
+    visibilityState: string;
+    rect: {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    alreadyRearmed: boolean;
+}): boolean;
 export declare const WEBKIT_REMOUNT_SETTLE_MS = 1000;
 export interface WebkitRemountTask {
     /** Perform the remount. Return false if the node no longer needs it (skips the boot wait). */

package/dist/types/server/canvas-db.d.ts

@@ -22,6 +22,20 @@ export interface PersistedCanvasState {
 }
 export declare function openCanvasDb(dbPath: string): Database;
 export declare function checkpointCanvasDb(db: Database): void;
+/**
+ * Delete blob rows nothing references any more. Blobs are content-addressed and
+ * written with INSERT OR IGNORE, so editing a node's html supersedes its old blob
+ * and leaves it orphaned — without this, `canvas.db` (which is git-committable)
+ * would grow without bound once externalization applies to ordinary html nodes.
+ *
+ * References are collected by scanning the raw persisted JSON for sha256 fields
+ * rather than parsing every node. That deliberately OVER-approximates: a stray
+ * 64-hex string keeps a blob alive that could have been dropped, which wastes a
+ * little space. The opposite error would delete live content, so the scan is
+ * biased to the safe side on purpose. Snapshot rows are scanned too — a snapshot
+ * restore must still find its blobs.
+ */
+export declare function gcBlobsInDB(db: Database): number;
 export declare function finalizeCanvasDbForClose(db: Database): void;
 export declare function saveStateToDB(db: Database, state: PersistedCanvasState): void;
 /** Check if the DB has been populated with canvas state at least once. */

package/docs/RELEASE.md

@@ -44,6 +44,25 @@ discovery with a `.esm.preflight` loader error (ERR-20260508-001).
 and exercises the CLI flows from
 [`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).
 
+**Bump the pinned version examples.** `Readme.md` pins an exact version in
+its install/orb-setup snippets *because* it tells readers to pin. Three
+releases in a row shipped pointing at the previous version — twice the
+surrounding prose described features that pin does not have, so a reader
+following it copy-pasted a broken setup.
+
+```bash
+grep -rn "pmx-canvas@0\." Readme.md docs/    # every hit must be the version you are about to ship
+```
+
+**If this release touches CI or the release workflows, review that as
+release content.** A changed gate gets its first real run *on this
+release*: `e2e-cli` once launched Playwright without installing the
+browser, the publish gate once queried `GITHUB_SHA` (the tag object, not
+the commit) so it would have blocked every annotated tag, and
+`test:coverage` once lacked `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` so it
+failed *and* opened a real browser. Ask what happens on a fresh runner
+and on a tag event, not just on your machine.
+
 ## Versioning
 
 Semantic versioning, in 0.x semver honestly (see `docs/api-stability.md`).
@@ -87,6 +106,23 @@ Don't ship a release without a CHANGELOG entry. The GitHub release
 notes file (`/tmp/pmx-canvas-vX.Y.Z-release-notes.md` by convention)
 expands on the CHANGELOG with examples and migration notes.
 
+**Check the entries are under a NEW heading.** Feature commits land bullets
+at the top of the file, and three times in the 0.3.x–0.4.x cycles they were
+appended under the *already-published* section instead — so the release
+notes shipped empty while the previous release's published history claimed
+features it never had. Before tagging:
+
+```bash
+# every bullet added since the last tag must sit above the last released heading
+git diff v<PREVIOUS>..HEAD -- CHANGELOG.md | grep '^+' | head -40
+grep -n '^## \[' CHANGELOG.md | head -3
+```
+
+Same rule in reverse: never retro-edit a published section to describe new
+behavior (a theme's colour was changed in place once, so the released notes
+described a build that never shipped it). Correct it forward under the new
+version instead.
+
 **Release-blocker gate:** a breaking change without a `### Breaking`
 CHANGELOG entry blocks the release (`docs/api-stability.md`). Check the
 diff against the previous tag for removed/renamed public surface — MCP
@@ -95,6 +131,18 @@ anything broke and isn't named under `### Breaking`, add the entry first.
 
 ## Tag → publish
 
+**Immediately before tagging, re-read the Test CI conclusion — never assert it
+from memory.** v0.3.2 was tagged and published while its Test run had concluded
+*failure*: an interruption landed between the watch finishing and the tag step,
+and "CI was green" was recalled rather than checked. A `gh run watch` exiting 0
+is only evidence if you actually read its output.
+
+```bash
+gh run view <run-id> --json status,conclusion -q '.status + " / " + .conclusion'
+gh run view <run-id> --json jobs -q '.jobs[] | .name + ": " + .conclusion'
+# every job must read `success` — a matrix job added in THIS release has never run green before
+```
+
 The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))
 triggers on tags matching `v*`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -356,8 +356,12 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   affordance. The connecting overlay stays up until paint is confirmed, so a black layer is
   never presented as ready. The recovery trail
   (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
-  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, and `recovery-exhausted` — when
-  diagnosing, trust `paint-ok`/`paint-fail`, and never assert health from `settled` alone. If a
+  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, `recovery-exhausted`, and
+  `assume-visible-rearm` — when diagnosing, trust `paint-ok`/`paint-fail`, and never assert
+  health from `settled` alone. Exception: in a host that reports the document hidden (the
+  GitHub Copilot panel does so continuously), `paint-ok` is recorded as
+  `paint-ok (unverified: host hidden)` — the app answered the paint probe, but nothing is
+  proven composited, so do not treat it as a verified paint. If a
   tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;
   attach the recovery trail when reporting.
 - Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon

package/skills/pmx-canvas-testing/SKILL.md

@@ -30,6 +30,16 @@ bun run test:web-canvas     # Browser smoke against a real running app
 bun run test:all            # Bun suite + browser smoke
 ```
 
+**Direct `bun test` is side-effect-guarded by `tests/preload.ts`** (wired via `bunfig.toml`
+`[test].preload`): it defaults `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` so the suite's open-as-site
+tests cannot launch the developer's real browser, whichever way the tests are invoked. The
+preload covers `bun test` only — when you boot a server yourself (`bun run src/cli/index.ts`),
+pass `--no-open` and set `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` explicitly.
+
+**Never pipe a gating command through `tail`, `head`, or `grep`.** The pipeline reports the exit
+code of the LAST command, so `bun run test | tail -5` exits 0 on a red suite. Redirect to a file
+and check `$?`, then read the file.
+
 ## Which Command To Run
 
 - Server/state/API-only changes: run `bun run test`
@@ -79,6 +89,30 @@ Prefer extending the existing suites before inventing a one-off script.
   `pmx-canvas skills sync --yes` to refresh them (whole trees, whatever agent layout owns them) before
   trusting skill-guided results
 
+## Tests That Cannot Fail
+
+A test that passes against the broken code is worse than no test — it certifies the bug. Every
+regression test must be shown to discriminate: run it against the unfixed code (or hard-code the
+broken value) and watch it go red BEFORE you trust the green.
+
+Four ways a test silently stops discriminating in this repo:
+
+- **Polled assertions pass on the first sample.** `expect.poll(fn).toBeGreaterThanOrEqual(180)`
+  succeeds the instant one sample qualifies, so it never observes the failure window. Wait for the
+  settle condition, then assert once.
+- **Committed fixtures embed generated output.** `src/server/demo-state.json` carries each
+  primitive's generated markup; count and coverage assertions are satisfied by stale markup just
+  as well as fresh. Guard generated fixtures by rebuilding from the generator's INPUT and
+  byte-comparing against the current renderer.
+- **Absolute assertions about globally-wired side effects are order-dependent.** Anything flowing
+  through a single-slot listener (architecture rule 8 in `CLAUDE.md`) is wired or not depending on
+  whether an earlier test file booted a server — so the test passes alone and fails in the suite,
+  or vice versa. Assert DIFFERENTIALLY: run the action disarmed and armed, require the deltas to
+  match. Always run the full suite before trusting a new test; a single-file run hides this.
+- **A new node type passes every test and renders nothing.** Server, API, and client-unit
+  assertions all pass while `isCanvasNodeType` drops the type during layout apply. Only a DOM
+  census on a live board catches it.
+
 ## Layout And Embedded Content Checks
 
 - For seeded or generated boards, add API-level geometry assertions: expected node/edge counts,
@@ -95,6 +129,12 @@ Prefer extending the existing suites before inventing a one-off script.
 - When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
   and inspect the actual iframe document in a browser. Server dimensions can look correct while the
   embedded content is still clipped.
+- **A node's stored content is not render evidence.** An html/primitive node's stored HTML holds
+  every conditional branch — hidden banners, error states, empty states — so a content-level read
+  (search hit, pinned context, `node get`, any text summary) quotes strings the user never saw.
+  The 0.4.7 report filed an "AX bridge unavailable" banner as a live product gap on exactly this
+  basis; the served surface had the bridge injected ahead of the check and the banner was `hidden`
+  in the document. Before filing a rendering bug, fetch the served surface or inspect the DOM.
 - User-facing creation flows must end with the new nodes visible: after the create (plus the
   skill-mandated focus/fit), a screenshot must show them without any manual pan. A `panned: true`
   API result alone is not proof — verify the frame is on-screen and unobscured.

package/src/client/nodes/ExtAppFrame.tsx

@@ -65,6 +65,36 @@ export function isWebKitOnlyHost(userAgent: string): boolean {
   return /AppleWebKit/.test(userAgent) && !/Chrome|Chromium|CriOS|Edg|Android/.test(userAgent);
 }
 
+/**
+ * Finding N (0.4.7 report): the GitHub Copilot panel's WKWebView reports
+ * `document.visibilityState === 'hidden'` CONTINUOUSLY — the workbench document
+ * never transitions to 'visible' even with the panel open and on-screen. Two
+ * things break as a result: the `visibilitychange` re-arm below can never fire
+ * (there is no transition to listen for), and `paint-ok` becomes a false green —
+ * the app document happily answers the double-rAF paint probe while the
+ * compositor still shows black. The instrumented trail from that session carries
+ * `visibility: "hidden"` on essentially every recovery event.
+ *
+ * So: when the document CLAIMS hidden but the frame is demonstrably on-screen,
+ * do not trust the claim — spend one more recovery round as if visible. A host
+ * that ever reports 'visible' has a working signal and is left to the
+ * visibilitychange path, which keeps a genuinely backgrounded panel quiet.
+ */
+export function shouldAssumeVisibleRearm(options: {
+  userAgent: string;
+  visibilityState: string;
+  rect: { top: number; left: number; bottom: number; right: number; width: number; height: number };
+  viewport: { width: number; height: number };
+  alreadyRearmed: boolean;
+}): boolean {
+  const { userAgent, visibilityState, rect, viewport, alreadyRearmed } = options;
+  if (alreadyRearmed) return false;
+  if (!isWebKitOnlyHost(userAgent)) return false;
+  if (visibilityState !== 'hidden') return false;
+  if (rect.width <= 0 || rect.height <= 0) return false;
+  return rect.bottom > 0 && rect.right > 0 && rect.top < viewport.height && rect.left < viewport.width;
+}
+
 // Finding F (0.2.5, reworked 0.3.1): BOOT-AWARE serialized WebKit remount queue.
 // The black tile is a cold-hydration BURST problem — a single ext-app repaints fine
 // into an idle panel (like a live-created node, or expand+close), but several
@@ -352,6 +382,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // Recovery ran while the document was hidden (compositing suppressed) — re-arm
   // one fresh remount round when the panel becomes visible (Finding N).
   const bootedWhileHiddenRef = useRef(false);
+  // Finding N (0.4.7): at most one "assume visible" round per frame lifetime, so
+  // a host that is hidden forever cannot turn the re-arm into a remount loop.
+  const assumeVisibleRearmDoneRef = useRef(false);
   const unmountedRef = useRef(false);
   const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
@@ -567,21 +600,64 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
       });
     });
 
+  // Finding N (0.4.7): the Copilot WKWebView never reports 'visible', so the
+  // visibilitychange re-arm below is dead code there and the ladder's own
+  // paint-ok cannot be trusted. When the document claims hidden but this frame
+  // is on-screen, spend one more full recovery round with a fresh budget —
+  // the same round the visibilitychange path would have run.
+  const ASSUME_VISIBLE_REARM_DELAY_MS = 600;
+  const maybeAssumeVisibleRearm = (): void => {
+    if (typeof document === 'undefined' || typeof navigator === 'undefined' || typeof window === 'undefined') return;
+    const frame = iframeRef.current;
+    if (!frame || unmountedRef.current) return;
+    if (
+      !shouldAssumeVisibleRearm({
+        userAgent: navigator.userAgent,
+        visibilityState: document.visibilityState,
+        rect: frame.getBoundingClientRect(),
+        viewport: { width: window.innerWidth, height: window.innerHeight },
+        alreadyRearmed: assumeVisibleRearmDoneRef.current,
+      })
+    )
+      return;
+    assumeVisibleRearmDoneRef.current = true;
+    // Re-check after a beat: a host whose visibility signal merely lagged the
+    // panel opening resolves itself here, and the visibilitychange path owns it.
+    window.setTimeout(() => {
+      if (unmountedRef.current || document.visibilityState === 'visible') return;
+      webkitRemountAttemptsRef.current = 0;
+      setRecoveryExhausted(false);
+      bootedWhileHiddenRef.current = false;
+      extAppRecoveryLog(nodeId, 'assume-visible-rearm');
+      scheduleWebkitRemount('assume-visible');
+    }, ASSUME_VISIBLE_REARM_DELAY_MS);
+  };
+
+  // A paint-ok collected while the document claims hidden proves only that the
+  // app's rAF pipeline is alive — NOT that anything composited (Finding N,
+  // 0.4.7). Say so in the trail instead of recording an unqualified success.
+  const paintOkLabel = (suffix = ''): string =>
+    typeof document !== 'undefined' && document.visibilityState === 'hidden'
+      ? `paint-ok${suffix} (unverified: host hidden)`
+      : `paint-ok${suffix}`;
+
   const runPaintLadder = async (): Promise<void> => {
     if (expanded) return;
     if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     setPaintPending(true);
     if (await probePaint()) {
-      extAppRecoveryLog(nodeId, 'paint-ok');
+      extAppRecoveryLog(nodeId, paintOkLabel());
       setPaintPending(false);
+      maybeAssumeVisibleRearm();
       return;
     }
     extAppRecoveryLog(nodeId, 'paint-fail');
     await runSoftExpandCycle();
     if (await probePaint()) {
-      extAppRecoveryLog(nodeId, 'paint-ok (after soft-expand)');
+      extAppRecoveryLog(nodeId, paintOkLabel(' (after soft-expand)'));
       setPaintPending(false);
+      maybeAssumeVisibleRearm();
       return;
     }
     if (unmountedRef.current) return;
@@ -590,6 +666,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
       extAppRecoveryLog(nodeId, 'recovery-exhausted');
       setPaintPending(false);
       setRecoveryExhausted(true);
+      maybeAssumeVisibleRearm();
     }
   };
 

package/src/server/canvas-db.ts

@@ -273,7 +273,13 @@ export function openCanvasDb(dbPath: string): Database {
 
   const db = new Database(dbPath);
   db.exec('PRAGMA journal_mode=WAL');
-  db.exec('PRAGMA synchronous=NORMAL');
+  // FULL, not NORMAL: under WAL, NORMAL lets a host/OS-level crash lose the most
+  // recent commits (a clean process exit loses nothing either way). The reporter of
+  // issue #22 declined FULL specifically because a save rewrote the whole board, so
+  // an fsync per commit scaled with board size. Saves are incremental now — a
+  // typical save is a row or two — so that objection is gone and the durability is
+  // worth the fsync.
+  db.exec('PRAGMA synchronous=FULL');
   db.exec('PRAGMA busy_timeout=5000');
   db.exec(SCHEMA_SQL);
 
@@ -295,38 +301,117 @@ export function checkpointCanvasDb(db: Database): void {
   db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
 }
 
+/**
+ * Delete blob rows nothing references any more. Blobs are content-addressed and
+ * written with INSERT OR IGNORE, so editing a node's html supersedes its old blob
+ * and leaves it orphaned — without this, `canvas.db` (which is git-committable)
+ * would grow without bound once externalization applies to ordinary html nodes.
+ *
+ * References are collected by scanning the raw persisted JSON for sha256 fields
+ * rather than parsing every node. That deliberately OVER-approximates: a stray
+ * 64-hex string keeps a blob alive that could have been dropped, which wastes a
+ * little space. The opposite error would delete live content, so the scan is
+ * biased to the safe side on purpose. Snapshot rows are scanned too — a snapshot
+ * restore must still find its blobs.
+ */
+export function gcBlobsInDB(db: Database): number {
+  const referenced = new Set<string>();
+  const collect = (sql: string): void => {
+    for (const row of db.query<{ data: string }, []>(sql).all()) {
+      if (!row.data) continue;
+      for (const match of row.data.matchAll(/"sha256"\s*:\s*"([0-9a-f]{64})"/g)) referenced.add(match[1]);
+    }
+  };
+  collect('SELECT data FROM nodes');
+  collect('SELECT data FROM snapshot_nodes');
+
+  const all = db.query<{ sha256: string }, []>('SELECT sha256 FROM blobs').all();
+  const orphans = all.filter((row) => !referenced.has(row.sha256));
+  if (orphans.length === 0) return 0;
+  const remove = db.prepare('DELETE FROM blobs WHERE sha256 = ?');
+  const transaction = db.transaction(() => {
+    for (const row of orphans) remove.run(row.sha256);
+  });
+  transaction();
+  return orphans.length;
+}
+
 export function finalizeCanvasDbForClose(db: Database): void {
   checkpointCanvasDb(db);
-  db.exec('PRAGMA journal_mode=DELETE');
+  // The WAL→DELETE switch takes an exclusive lock, so it succeeds only when no
+  // other connection has the DB open — and that makes it the GC gate. GC deletes
+  // blob rows a second live process may still depend on: its in-memory nodes
+  // hold content-addressed refs, not content, so a GC'd blob is unrecoverable
+  // once that process re-saves (review of #22, reproduced). Locked ⇒ someone
+  // else is on this canvas: leave WAL in place and keep every blob.
+  try {
+    db.exec('PRAGMA journal_mode=DELETE');
+  } catch {
+    return;
+  }
+  gcBlobsInDB(db);
 }
 
 // ── State Persistence ───────────────────────────────────────────
 
+/**
+ * Drop rows whose id is no longer in the live state. Reads only the id column
+ * (index-only scan) so it stays cheap on large boards.
+ */
+function deleteMissingRows(
+  db: Database,
+  table: 'nodes' | 'edges' | 'annotations' | 'context_pins',
+  idColumn: 'id' | 'node_id',
+  keep: Set<string>,
+): void {
+  const rows = db.query<{ id: string }, []>(`SELECT ${idColumn} AS id FROM ${table}`).all();
+  if (rows.length === 0) return;
+  const remove = db.prepare(`DELETE FROM ${table} WHERE ${idColumn} = ?`);
+  for (const row of rows) {
+    if (!keep.has(row.id)) remove.run(row.id);
+  }
+}
+
 export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
   const transaction = db.transaction(() => {
-    // Clear current state tables
-    db.run('DELETE FROM nodes');
-    db.run('DELETE FROM edges');
-    db.run('DELETE FROM annotations');
-    db.run('DELETE FROM context_pins');
-    db.run('DELETE FROM ax_state');
-
-    // Save viewport and UI preferences
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['theme', normalizeCanvasTheme(state.theme)]);
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['viewport_x', String(state.viewport.x)]);
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['viewport_y', String(state.viewport.y)]);
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['viewport_scale', String(state.viewport.scale)]);
-
+    // Rows are upserted only when a column actually differs, and rows that are
+    // gone are deleted by id. This used to be DELETE-all + INSERT-all, which
+    // rewrote every row on every debounced save: dragging one node rewrote the
+    // whole board, multi-MB html payloads included, so the write cost scaled
+    // with board size instead of change size (issue #22). The
+    // `WHERE ... IS NOT excluded....` guard makes an unchanged row a true
+    // no-op — SQLite performs no update, so no page is written. The comparison
+    // is against the DB itself rather than an in-memory cache, so nothing can
+    // go stale and silently skip a write that was actually needed.
+    const upsertMeta = db.prepare(
+      `INSERT INTO meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value
+       WHERE value IS NOT excluded.value`,
+    );
+    upsertMeta.run('theme', normalizeCanvasTheme(state.theme));
+    upsertMeta.run('viewport_x', String(state.viewport.x));
+    upsertMeta.run('viewport_y', String(state.viewport.y));
+    upsertMeta.run('viewport_scale', String(state.viewport.scale));
     // Mark DB as populated (for migration detection)
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['state_populated', '1']);
+    upsertMeta.run('state_populated', '1');
 
     // Save nodes
-    const insertNode = db.prepare(
+    const upsertNode = db.prepare(
       `INSERT INTO nodes (id, type, pos_x, pos_y, width, height, z_index, collapsed, pinned, dock_position, data)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         type = excluded.type, pos_x = excluded.pos_x, pos_y = excluded.pos_y,
+         width = excluded.width, height = excluded.height, z_index = excluded.z_index,
+         collapsed = excluded.collapsed, pinned = excluded.pinned,
+         dock_position = excluded.dock_position, data = excluded.data
+       WHERE type IS NOT excluded.type OR pos_x IS NOT excluded.pos_x
+          OR pos_y IS NOT excluded.pos_y OR width IS NOT excluded.width
+          OR height IS NOT excluded.height OR z_index IS NOT excluded.z_index
+          OR collapsed IS NOT excluded.collapsed OR pinned IS NOT excluded.pinned
+          OR dock_position IS NOT excluded.dock_position OR data IS NOT excluded.data`,
     );
     for (const node of state.nodes) {
-      insertNode.run(
+      upsertNode.run(
         node.id,
         node.type,
         node.position.x,
@@ -340,14 +425,21 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
         JSON.stringify(node.data),
       );
     }
+    deleteMissingRows(db, 'nodes', 'id', new Set(state.nodes.map((node) => node.id)));
 
     // Save edges
-    const insertEdge = db.prepare(
+    const upsertEdge = db.prepare(
       `INSERT INTO edges (id, from_node, to_node, type, label, style, animated)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         from_node = excluded.from_node, to_node = excluded.to_node, type = excluded.type,
+         label = excluded.label, style = excluded.style, animated = excluded.animated
+       WHERE from_node IS NOT excluded.from_node OR to_node IS NOT excluded.to_node
+          OR type IS NOT excluded.type OR label IS NOT excluded.label
+          OR style IS NOT excluded.style OR animated IS NOT excluded.animated`,
     );
     for (const edge of state.edges) {
-      insertEdge.run(
+      upsertEdge.run(
         edge.id,
         edge.from,
         edge.to,
@@ -357,14 +449,24 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
         edge.animated ? 1 : 0,
       );
     }
+    deleteMissingRows(db, 'edges', 'id', new Set(state.edges.map((edge) => edge.id)));
 
     // Save annotations
-    const insertAnnotation = db.prepare(
+    const annotations = state.annotations ?? [];
+    const upsertAnnotation = db.prepare(
       `INSERT INTO annotations (id, type, points, bounds, color, width, text, label, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         type = excluded.type, points = excluded.points, bounds = excluded.bounds,
+         color = excluded.color, width = excluded.width, text = excluded.text,
+         label = excluded.label, created_at = excluded.created_at
+       WHERE type IS NOT excluded.type OR points IS NOT excluded.points
+          OR bounds IS NOT excluded.bounds OR color IS NOT excluded.color
+          OR width IS NOT excluded.width OR text IS NOT excluded.text
+          OR label IS NOT excluded.label OR created_at IS NOT excluded.created_at`,
     );
-    for (const annotation of state.annotations ?? []) {
-      insertAnnotation.run(
+    for (const annotation of annotations) {
+      upsertAnnotation.run(
         annotation.id,
         annotation.type,
         JSON.stringify(annotation.points),
@@ -376,17 +478,21 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
         annotation.createdAt,
       );
     }
+    deleteMissingRows(db, 'annotations', 'id', new Set(annotations.map((annotation) => annotation.id)));
 
-    // Save context pins
-    const insertPin = db.prepare('INSERT INTO context_pins (node_id) VALUES (?)');
+    // Save context pins (node_id is the whole row — nothing to update)
+    const insertPin = db.prepare('INSERT OR IGNORE INTO context_pins (node_id) VALUES (?)');
     for (const pinId of state.contextPins) {
       insertPin.run(pinId);
     }
+    deleteMissingRows(db, 'context_pins', 'node_id', new Set(state.contextPins));
 
-    db.run('INSERT INTO ax_state (key, value) VALUES (?, ?)', [
-      'state',
-      JSON.stringify(state.ax ?? createEmptyAxState()),
-    ]);
+    db.run(
+      `INSERT INTO ax_state (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value
+       WHERE value IS NOT excluded.value`,
+      ['state', JSON.stringify(state.ax ?? createEmptyAxState())],
+    );
   });
 
   transaction();