@dfosco/storyboard 0.7.0 → 0.8.1

package/src/internals/canvas/CanvasPage.jsx

@@ -12,6 +12,7 @@ import { getPasteRules } from '../../core/index.js'
 import { isTerminalResizable, getTerminalDimensions } from '../../core/index.js'
 import { getFlag, subscribeToStorage } from '../../core/index.js'
 import { getCanvasZoom } from '../../core/index.js'
+import { trackRecent as trackRecentArtifact } from '../../core/index.js'
 import { registerSmoothCorners } from '../../core/utils/smoothCorners.js'
 import { registerHotPoolDevLogs } from './hotPoolDevLogs.js'
 import { isGitHubEmbedUrl } from './widgets/githubUrl.js'
@@ -28,7 +29,10 @@ import {
   duplicateImage,
   fetchGitHubEmbed,
   getCanvas as getCanvasApi,
+  patchWidget as patchWidgetApi,
   removeWidget as removeWidgetApi,
+  redoEvent as redoEventApi,
+  undoEvent as undoEventApi,
   updateCanvas,
   updateFolderMeta,
   uploadImage,
@@ -732,6 +736,15 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     return () => { cancelled = true }
   }, [canvasId])
 
+  // Track this canvas as a recent visit so it appears in the workspace
+  // Recent tab and the command palette regardless of how the user arrived
+  // (card click, command palette, direct URL, link from another canvas, …).
+  useEffect(() => {
+    if (!canvasId) return
+    const label = canvasMeta?.title || canvas?.title || name || canvasId.split('/').pop() || canvasId
+    trackRecentArtifact('canvas', canvasId, label)
+  }, [canvasId, canvasMeta, canvas, name])
+
   // Centralized list of component export names.
   // When jsxExports is available, use it (discovers new exports not yet in sources).
   // When jsxExports is null (module import failed), fall back to sources so iframes
@@ -950,27 +963,66 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
   }
 
-  // Debounced save to server — routed through queueWrite to serialize
-  // with deletes and other writes, preventing stale data from overwriting.
-  const debouncedSave = useRef(
-    debounce((canvasId, widgets) => {
-      // De-duplicate widgets by ID — race conditions between HMR pushes
-      // and optimistic adds can introduce duplicates in localWidgets.
-      const seen = new Set()
-      const deduped = widgets.filter((w) => {
-        if (seen.has(w.id)) return false
-        seen.add(w.id)
-        return true
-      })
-      queueWrite(() =>
-        updateCanvas(canvasId, { widgets: deduped })
-          .catch((err) => console.error('[canvas] Failed to save:', err))
-      )
-    }, 2000)
-  ).current
+  // Per-widget debounced PATCH. Each widget gets its own pending props
+  // accumulator + timer so concurrent edits to different widgets don't stomp
+  // on one another. Successful patches return event ids — we push them onto
+  // the undo stack via undoRedo.trackMany so the toolbar Undo button targets
+  // exactly the right granular events.
+  const widgetPatchDebouncersRef = useRef(new Map())
+  const flushAllPendingWidgetPatches = useCallback(() => {
+    for (const entry of widgetPatchDebouncersRef.current.values()) {
+      if (entry.timer) {
+        clearTimeout(entry.timer)
+        entry.timer = null
+        entry.flushNow()
+      }
+    }
+  }, [])
+  const cancelAllPendingWidgetPatches = useCallback(() => {
+    for (const entry of widgetPatchDebouncersRef.current.values()) {
+      if (entry.timer) {
+        clearTimeout(entry.timer)
+        entry.timer = null
+        entry.pendingProps = {}
+      }
+    }
+  }, [])
+  // patchWidgetDebounced(canvasId, widgetId, propsDelta) — coalesces multiple
+  // PATCHes per widget within DEBOUNCE_MS into a single request.
+  const patchWidgetDebounced = useCallback((targetCanvasId, widgetId, propsDelta) => {
+    if (!widgetId || !propsDelta) return
+    const map = widgetPatchDebouncersRef.current
+    let entry = map.get(widgetId)
+    if (!entry) {
+      entry = {
+        pendingProps: {},
+        timer: null,
+        flushNow: () => {
+          const props = entry.pendingProps
+          entry.pendingProps = {}
+          if (Object.keys(props).length === 0) return
+          dirtyRef.current = true
+          queueWrite(async () => {
+            try {
+              const res = await patchWidgetApi(targetCanvasId, widgetId, { props })
+              if (Array.isArray(res?.eventIds)) undoRedo.trackMany(res.eventIds)
+            } catch (err) {
+              console.error('[canvas] Failed to patch widget:', err)
+            }
+          })
+        },
+      }
+      map.set(widgetId, entry)
+    }
+    Object.assign(entry.pendingProps, propsDelta)
+    if (entry.timer) clearTimeout(entry.timer)
+    entry.timer = setTimeout(() => {
+      entry.timer = null
+      entry.flushNow()
+    }, 500)
+  }, [undoRedo])
 
   const handleWidgetUpdate = useCallback((widgetId, updates) => {
-    undoRedo.snapshot(stateRef.current, 'edit', widgetId)
     // Snap width/height to grid when snap is enabled
     const snapped = { ...updates }
     if (snapEnabled && snapGridSize) {
@@ -985,11 +1037,11 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       const next = prev.map((w) =>
         w.id === widgetId ? { ...w, props: { ...w.props, ...snapped } } : w
       )
-      dirtyRef.current = true
-      debouncedSave(canvasId, next)
       return next
     })
-  }, [canvasId, debouncedSave, undoRedo, snapEnabled, snapGridSize])
+    dirtyRef.current = true
+    patchWidgetDebounced(canvasId, widgetId, snapped)
+  }, [canvasId, patchWidgetDebounced, snapEnabled, snapGridSize])
 
   // Stable ref so handleWidgetSelect can flip a "done" agent back to
   // "running" without re-creating itself on every widget update.
@@ -1002,35 +1054,60 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     const defaultMeta = hubRoleOptions.find((r) => r.id === defaultHubRole) || null
     const fallbackRoleId = defaultMeta?.id || 'member'
 
-    undoRedo.snapshot(stateRef.current, 'edit-role', widgetId)
     setLocalWidgets((prev) => {
       if (!prev) return prev
 
       const componentIds = getConnectedComponent(widgetId, localConnectors)
       const scopeHas = (id) => componentIds.has(id)
+      const roleChanges = []  // { widgetId, role }
       const next = prev.map((widget) => {
         if (widget.id === widgetId) {
+          roleChanges.push({ widgetId: widget.id, role: targetRole })
           return { ...widget, props: { ...widget.props, role: targetRole } }
         }
         if (!roleMeta || roleMeta.type !== 'unique') return widget
         if (widget.type !== 'agent' && widget.type !== 'prompt') return widget
         if (!scopeHas(widget.id)) return widget
         if ((widget.props?.role || fallbackRoleId) !== targetRole) return widget
+        roleChanges.push({ widgetId: widget.id, role: fallbackRoleId })
         return { ...widget, props: { ...widget.props, role: fallbackRoleId } }
       })
 
       dirtyRef.current = true
-      debouncedSave(canvasId, next)
+      // Persist as a single batch so undo restores all role flips atomically.
+      if (roleChanges.length > 0) {
+        const operations = roleChanges.map((c) => ({
+          op: 'update-widget',
+          widgetId: c.widgetId,
+          props: { role: c.role },
+        }))
+        queueWrite(async () => {
+          try {
+            const res = await batchOperations(canvasId, operations)
+            const ids = (res?.results || [])
+              .map((r) => r?.eventId)
+              .filter(Boolean)
+            if (ids.length > 0) undoRedo.trackMany(ids)
+          } catch (err) {
+            console.error('[canvas] Failed to persist role change:', err)
+          }
+        })
+      }
       return next
     })
-  }, [canvasId, debouncedSave, undoRedo, defaultHubRole, hubRoleOptions, localConnectors])
+  }, [canvasId, undoRedo, defaultHubRole, hubRoleOptions, localConnectors])
 
   const handleWidgetRemove = useCallback((widgetId) => {
-    // Cancel any pending debounced save — it may contain stale data
-    // that includes the widget we're about to delete
-    debouncedSave.cancel()
+    // Cancel any pending widget patches that target this widget — they
+    // would race against the delete and leave a stale widget_updated event
+    // in the JSONL.
+    const debouncer = widgetPatchDebouncersRef.current.get(widgetId)
+    if (debouncer?.timer) {
+      clearTimeout(debouncer.timer)
+      debouncer.timer = null
+      debouncer.pendingProps = {}
+    }
 
-    undoRedo.snapshot(stateRef.current, 'remove', widgetId)
     markWidgetDeleted(widgetId)
     setLocalWidgets((prev) => prev ? prev.filter((w) => w.id !== widgetId) : prev)
     // Cascade: remove connectors referencing this widget
@@ -1039,27 +1116,34 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       if (orphaned.length === 0) return prev
       for (const c of orphaned) {
         markConnectorDeleted(c.id)
-        queueWrite(() =>
-          removeConnectorApi(canvasId, c.id).catch((err) =>
+        queueWrite(async () => {
+          try {
+            const res = await removeConnectorApi(canvasId, c.id)
+            if (res?.eventId) undoRedo.track(res.eventId)
+          } catch (err) {
             console.error('[canvas] Failed to remove orphaned connector:', err)
-          )
-        )
+          }
+        })
       }
       return prev.filter((c) => c.start.widgetId !== widgetId && c.end.widgetId !== widgetId)
     })
     dirtyRef.current = true
-    queueWrite(() =>
-      removeWidgetApi(canvasId, widgetId)
-        .catch((err) => console.error('[canvas] Failed to remove widget:', err))
-    )
-  }, [canvasId, undoRedo, debouncedSave, markWidgetDeleted, markConnectorDeleted])
+    queueWrite(async () => {
+      try {
+        const res = await removeWidgetApi(canvasId, widgetId)
+        if (res?.eventId) undoRedo.track(res.eventId)
+      } catch (err) {
+        console.error('[canvas] Failed to remove widget:', err)
+      }
+    })
+  }, [canvasId, undoRedo, markWidgetDeleted, markConnectorDeleted])
 
   const handleConnectorAdd = useCallback(async ({ startWidgetId, startAnchor, endWidgetId, endAnchor }) => {
     try {
-      undoRedo.snapshot(stateRef.current, 'connector-add')
       const result = await addConnectorApi(canvasId, { startWidgetId, startAnchor, endWidgetId, endAnchor })
       if (result.success && result.connector) {
         setLocalConnectors((prev) => [...prev, result.connector])
+        if (result.eventId) undoRedo.track(result.eventId)
       }
     } catch (err) {
       console.error('[canvas] Failed to add connector:', err)
@@ -1099,15 +1183,17 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   }, [handleConnectorAdd])
 
   const handleConnectorRemove = useCallback((connectorId) => {
-    undoRedo.snapshot(stateRef.current, 'connector-remove')
     markConnectorDeleted(connectorId)
     setLocalConnectors((prev) => prev.filter((c) => c.id !== connectorId))
     dirtyRef.current = true
-    queueWrite(() =>
-      removeConnectorApi(canvasId, connectorId).catch((err) =>
+    queueWrite(async () => {
+      try {
+        const res = await removeConnectorApi(canvasId, connectorId)
+        if (res?.eventId) undoRedo.track(res.eventId)
+      } catch (err) {
         console.error('[canvas] Failed to remove connector:', err)
-      )
-    )
+      }
+    })
   }, [canvasId, undoRedo, markConnectorDeleted])
 
   // Connector drag state
@@ -1293,7 +1379,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         if (dupResult.success) copyProps.src = dupResult.filename
       }
 
-      undoRedo.snapshot(stateRef.current, 'add')
       const result = await addWidgetApi(canvasId, {
         type: widget.type,
         props: copyProps,
@@ -1305,6 +1390,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         }
         setLocalWidgets((prev) => [...(prev || []), result.widget])
         setSelectedWidgetIds(new Set([result.widget.id]))
+        if (result.eventId) undoRedo.track(result.eventId)
       }
     } catch (err) {
       console.error('[canvas] Failed to copy widget:', err)
@@ -1316,8 +1402,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     if (!widget) return
     const widgets = [widget]
 
-    undoRedo.snapshot(stateRef.current, 'add')
-
     const occupied = new Set(
       (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
     )
@@ -1378,8 +1462,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       const newWidgets = []
       const newConnectors = []
       const refMap = response.refs || {}
+      const eventIds = []
 
       for (const result of response.results) {
+        if (result.eventId) eventIds.push(result.eventId)
         if (result.op === 'create-widget' && result.widget) {
           newWidgets.push(result.widget)
         }
@@ -1409,6 +1495,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       if (newConnectors.length > 0) {
         setLocalConnectors((prev) => [...prev, ...newConnectors])
       }
+      if (eventIds.length > 0) undoRedo.trackMany(eventIds)
     } catch (err) {
       console.error('[canvas] Failed to duplicate with connectors:', err)
     }
@@ -1419,9 +1506,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     const widgets = (localWidgets ?? []).filter((w) => selectedWidgetIds.has(w.id))
     if (widgets.length === 0) return
 
-    // Single undo snapshot for the entire batch
-    undoRedo.snapshot(stateRef.current, 'add')
-
     // Compute occupied positions to find free offset
     const occupied = new Set(
       (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
@@ -1435,6 +1519,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     while (anyOccupied()) offset++
 
     const newWidgets = []
+    const eventIds = []
     for (const widget of widgets) {
       const position = {
         x: (widget.position?.x ?? 0) + offset * 40,
@@ -1460,6 +1545,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
             result.widget.props = { ...result.widget.props, webglReady: true }
           }
           newWidgets.push(result.widget)
+          if (result.eventId) eventIds.push(result.eventId)
         }
       } catch (err) {
         console.error('[canvas] Failed to duplicate widget:', err)
@@ -1470,6 +1556,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       setLocalWidgets((prev) => [...(prev || []), ...newWidgets])
       setSelectedWidgetIds(new Set(newWidgets.map((w) => w.id)))
     }
+    if (eventIds.length > 0) undoRedo.trackMany(eventIds)
   }, [canvasId, localWidgets, selectedWidgetIds, undoRedo])
 
   // Duplicate selected widgets WITH connectors (Cmd+Shift+D)
@@ -1479,8 +1566,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     const widgets = (localWidgets ?? []).filter((w) => selectedWidgetIds.has(w.id))
     if (widgets.length === 0) return
 
-    undoRedo.snapshot(stateRef.current, 'add')
-
     // Compute offset — same logic as handleDuplicateSelected
     const occupied = new Set(
       (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
@@ -1558,8 +1643,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       const newWidgets = []
       const newConnectors = []
       const refMap = response.refs || {}
+      const eventIds = []
 
       for (const result of response.results) {
+        if (result.eventId) eventIds.push(result.eventId)
         if (result.op === 'create-widget' && result.widget) {
           newWidgets.push(result.widget)
         }
@@ -1590,6 +1677,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       if (newConnectors.length > 0) {
         setLocalConnectors((prev) => [...prev, ...newConnectors])
       }
+      if (eventIds.length > 0) undoRedo.trackMany(eventIds)
     } catch (err) {
       console.error('[canvas] Failed to duplicate with connectors:', err)
     }
@@ -1636,6 +1724,15 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
             : [],
           createdAt: snapshot.createdAt ?? null,
           updatedAt: snapshot.updatedAt ?? null,
+          // PR-specific metadata (state, branches, diff stats)
+          state: snapshot.state ?? null,
+          merged: typeof snapshot.merged === 'boolean' ? snapshot.merged : null,
+          draft: typeof snapshot.draft === 'boolean' ? snapshot.draft : null,
+          baseRef: typeof snapshot.baseRef === 'string' ? snapshot.baseRef : null,
+          headRef: typeof snapshot.headRef === 'string' ? snapshot.headRef : null,
+          additions: typeof snapshot.additions === 'number' ? snapshot.additions : null,
+          deletions: typeof snapshot.deletions === 'number' ? snapshot.deletions : null,
+          changedFiles: typeof snapshot.changedFiles === 'number' ? snapshot.changedFiles : null,
           fetchedAt: new Date().toISOString(),
         },
       }
@@ -1654,17 +1751,19 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   }, [buildGitHubPreviewUpdates, handleWidgetUpdate])
 
   const debouncedSourceSave = useRef(
-    debounce((canvasId, sources) => {
-      queueWrite(() =>
-        updateCanvas(canvasId, { sources }).catch((err) =>
+    debounce((canvasId, sources, onResult) => {
+      queueWrite(async () => {
+        try {
+          const res = await updateCanvas(canvasId, { sources })
+          if (typeof onResult === 'function') onResult(res)
+        } catch (err) {
           console.error('[canvas] Failed to save sources:', err)
-        )
-      )
+        }
+      })
     }, 2000)
   ).current
 
   const handleSourceUpdate = useCallback((exportName, updates) => {
-    undoRedo.snapshot(stateRef.current, 'edit', `jsx-${exportName}`)
     const snapped = { ...updates }
     if (snapEnabled && snapGridSize) {
       if (snapped.width != null) snapped.width = snapDimension(snapped.width, snapGridSize, true, 100)
@@ -1679,7 +1778,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       debouncedSourceSave(canvasId, next)
       return next
     })
-  }, [canvasId, debouncedSourceSave, undoRedo, snapEnabled, snapGridSize])
+  }, [canvasId, debouncedSourceSave, snapEnabled, snapGridSize])
 
   const handleItemDragEnd = useCallback((dragId, position) => {
     setWidgetDragging(false)
@@ -1697,7 +1796,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       // Suppress the click-based selection reset that fires after pointerup
       justDraggedRef.current = true // eslint-disable-line react-hooks/immutability
       requestAnimationFrame(() => { justDraggedRef.current = false })
-      undoRedo.snapshot(stateRef.current, 'multi-move')
 
       // Compute delta from the dragged widget's old position
       const isJsx = dragId.startsWith('jsx-')
@@ -1713,33 +1811,46 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       const dx = rounded.x - oldPos.x
       const dy = rounded.y - oldPos.y
 
-      debouncedSave.cancel()
+      cancelAllPendingWidgetPatches()
 
-      // Update JSON widget positions
+      // Update JSON widget positions. We collect move ops inside the setState
+      // updater (which runs during commit) and fire the batch from there to
+      // avoid the "set before commit" timing trap.
       setLocalWidgets((prev) => {
         if (!prev) return prev
+        const widgetMoveOps = []
         const next = prev.map((w) => {
-          if (w.id === dragId) return { ...w, position: rounded }
+          if (w.id === dragId) {
+            widgetMoveOps.push({ op: 'move-widget', widgetId: w.id, position: rounded })
+            return { ...w, position: rounded }
+          }
           if (ids.has(w.id)) {
-            return {
-              ...w,
-              position: {
-                x: Math.max(0, roundPosition((w.position?.x ?? 0) + dx)),
-                y: Math.max(0, roundPosition((w.position?.y ?? 0) + dy)),
-              },
+            const newPos = {
+              x: Math.max(0, roundPosition((w.position?.x ?? 0) + dx)),
+              y: Math.max(0, roundPosition((w.position?.y ?? 0) + dy)),
             }
+            widgetMoveOps.push({ op: 'move-widget', widgetId: w.id, position: newPos })
+            return { ...w, position: newPos }
           }
           return w
         })
         dirtyRef.current = true
-        queueWrite(() =>
-          updateCanvas(canvasId, { widgets: next })
-            .catch((err) => console.error('[canvas] Failed to save multi-move:', err))
-        )
+        if (widgetMoveOps.length > 0) {
+          queueWrite(async () => {
+            try {
+              const res = await batchOperations(canvasId, widgetMoveOps)
+              const evIds = (res?.results || []).map((r) => r?.eventId).filter(Boolean)
+              if (evIds.length > 0) undoRedo.trackMany(evIds)
+            } catch (err) {
+              console.error('[canvas] Failed to save multi-move:', err)
+            }
+          })
+        }
         return next
       })
 
-      // Update JSX source positions
+      // Update JSX source positions — still a single source_updated event;
+      // not yet wired to per-source undo tracking.
       setLocalSources((prev) => {
         const current = Array.isArray(prev) ? prev : []
         let changed = false
@@ -1775,7 +1886,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
 
     if (dragId.startsWith('jsx-')) {
-      undoRedo.snapshot(stateRef.current, 'move', dragId)
       const sourceExport = dragId.replace(/^jsx-/, '')
       setLocalSources((prev) => {
         const current = Array.isArray(prev) ? prev : []
@@ -1792,21 +1902,26 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       return
     }
 
-    undoRedo.snapshot(stateRef.current, 'move', dragId)
-    debouncedSave.cancel()
+    // Single-widget move — granular PATCH /widget so the move is its own
+    // undoable event.
+    cancelAllPendingWidgetPatches()
     setLocalWidgets((prev) => {
       if (!prev) return prev
       const next = prev.map((w) =>
         w.id === dragId ? { ...w, position: rounded } : w
       )
       dirtyRef.current = true
-      queueWrite(() =>
-        updateCanvas(canvasId, { widgets: next })
-          .catch((err) => console.error('[canvas] Failed to save widget position:', err))
-      )
       return next
     })
-  }, [canvasId, undoRedo, debouncedSave, transitionPeers, clearDragPreview])
+    queueWrite(async () => {
+      try {
+        const res = await patchWidgetApi(canvasId, dragId, { position: rounded })
+        if (Array.isArray(res?.eventIds)) undoRedo.trackMany(res.eventIds)
+      } catch (err) {
+        console.error('[canvas] Failed to save widget position:', err)
+      }
+    })
+  }, [canvasId, undoRedo, cancelAllPendingWidgetPatches, transitionPeers, clearDragPreview])
 
   // Keep zoomRef in sync when React state is set (e.g. by toolbar or zoom-to-fit)
   useEffect(() => {
@@ -2241,7 +2356,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         if (result.hotSession?.webglReady) {
           result.widget.props = { ...result.widget.props, webglReady: true }
         }
-        undoRedo.snapshot(stateRef.current, 'add')
         // Guard against duplicates: HMR may have already pushed the new widget
         // into localWidgets before the API response returns (race condition).
         setLocalWidgets((prev) => {
@@ -2250,6 +2364,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           return [...arr, result.widget]
         })
         setSelectedWidgetIds(new Set([result.widget.id]))
+        if (result.eventId) undoRedo.track(result.eventId)
       }
     } catch (err) {
       console.error('[canvas] Failed to add widget:', err)
@@ -2268,13 +2383,13 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         position: pos,
       })
       if (result.success && result.widget) {
-        undoRedo.snapshot(stateRef.current, 'add')
         setLocalWidgets((prev) => {
           const arr = prev || []
           if (arr.some((w) => w.id === result.widget.id)) return arr
           return [...arr, result.widget]
         })
         setSelectedWidgetIds(new Set([result.widget.id]))
+        if (result.eventId) undoRedo.track(result.eventId)
       }
     } catch (err) {
       console.error('[canvas] Failed to add story widget:', err)
@@ -2718,11 +2833,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       if (e.key === 'Delete' || e.key === 'Backspace') {
         e.preventDefault()
         if (selectedWidgetIds.size > 1) {
-          // Multi-delete — snapshot once, remove all via individual widget_removed
-          // events (not widgets_replaced) to avoid the server's wipe guard and
+          // Multi-delete — remove all via individual widget_removed events
+          // (not widgets_replaced) to avoid the server's wipe guard and
           // ensure terminal sessions are properly orphaned per widget.
-          undoRedo.snapshot(stateRef.current, 'multi-remove')
-          debouncedSave.cancel()
+          cancelAllPendingWidgetPatches()
           const idsToRemove = new Set(selectedWidgetIds)
           // Mark deletions before mutating local state so the HMR merge
           // doesn't re-add them mid-flight.
@@ -2733,22 +2847,28 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
             const orphaned = prev.filter((c) => idsToRemove.has(c.start.widgetId) || idsToRemove.has(c.end.widgetId))
             for (const c of orphaned) {
               markConnectorDeleted(c.id)
-              queueWrite(() =>
-                removeConnectorApi(canvasId, c.id).catch((err) =>
+              queueWrite(async () => {
+                try {
+                  const res = await removeConnectorApi(canvasId, c.id)
+                  if (res?.eventId) undoRedo.track(res.eventId)
+                } catch (err) {
                   console.error('[canvas] Failed to remove orphaned connector:', err)
-                )
-              )
+                }
+              })
             }
             return prev.filter((c) => !idsToRemove.has(c.start.widgetId) && !idsToRemove.has(c.end.widgetId))
           })
           dirtyRef.current = true
           // Queue individual delete API calls
           for (const widgetId of idsToRemove) {
-            queueWrite(() =>
-              removeWidgetApi(canvasId, widgetId).catch(err =>
+            queueWrite(async () => {
+              try {
+                const res = await removeWidgetApi(canvasId, widgetId)
+                if (res?.eventId) undoRedo.track(res.eventId)
+              } catch (err) {
                 console.error('[canvas] Failed to remove widget in multi-delete:', err)
-              )
-            )
+              }
+            })
           }
         } else {
           const widgetId = [...selectedWidgetIds][0]
@@ -2759,7 +2879,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
     document.addEventListener('keydown', handleKeyDown)
     return () => document.removeEventListener('keydown', handleKeyDown)
-  }, [selectedWidgetIds, localWidgets, handleWidgetRemove, undoRedo, canvasId, debouncedSave, markWidgetDeleted, markConnectorDeleted])
+  }, [selectedWidgetIds, localWidgets, handleWidgetRemove, undoRedo, canvasId, cancelAllPendingWidgetPatches, markWidgetDeleted, markConnectorDeleted])
 
   // Ref to store processImageFile for use by drop effect
   const processImageFileRef = useRef(null)
@@ -2829,10 +2949,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           position: pos,
         })
         if (result.success && result.widget) {
-          undoRedo.snapshot(stateRef.current, 'add')
           setLocalWidgets((prev) => [...(prev || []), result.widget])
           setSelectedWidgetIds(new Set([result.widget.id]))
           navigator.clipboard?.writeText(result.widget.id).catch(() => {})
+          if (result.eventId) undoRedo.track(result.eventId)
         }
         return true
       } catch (err) {
@@ -2916,11 +3036,9 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           const baseX = Math.round(center.x - groupW / 2)
           const baseY = Math.round(center.y - groupH / 2)
 
-          // Single undo snapshot for the entire paste
-          undoRedo.snapshot(stateRef.current, 'add')
-
           // Paste all widgets, collecting new IDs for selection
           const newWidgets = []
+          const eventIds = []
           for (const w of sourceWidgets) {
             const relX = (w.position?.x ?? 0) - minX
             const relY = (w.position?.y ?? 0) - minY
@@ -2943,6 +3061,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
                 result.widget.props = { ...result.widget.props, webglReady: true }
               }
               newWidgets.push(result.widget)
+              if (result.eventId) eventIds.push(result.eventId)
             }
           }
 
@@ -2950,6 +3069,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
             setLocalWidgets((prev) => [...(prev || []), ...newWidgets])
             setSelectedWidgetIds(new Set(newWidgets.map(w => w.id)))
           }
+          if (eventIds.length > 0) undoRedo.trackMany(eventIds)
         } catch (err) {
           console.error('[canvas] Failed to paste widget reference:', err)
         }
@@ -3000,9 +3120,9 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           position: pos,
         })
         if (result.success && result.widget) {
-          undoRedo.snapshot(stateRef.current, 'add')
           setLocalWidgets((prev) => [...(prev || []), result.widget])
           setSelectedWidgetIds(new Set([result.widget.id]))
+          if (result.eventId) undoRedo.track(result.eventId)
         }
       } catch (err) {
         console.error('[canvas] Failed to add widget from paste:', err)
@@ -3090,35 +3210,57 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   }, [loading])
 
   // --- Undo / Redo ---
+  // Server-authoritative: POST /undo / POST /redo append an inverse event
+  // to the JSONL. The HMR push from that write flows back through useCanvas
+  // → setLocalWidgets, so we don't optimistically mutate local state here.
+  //
+  // 404 handling: if the server can't find the target event, it was almost
+  // certainly compacted away (compaction collapses history into a single
+  // canvas_created baseline). We clear the per-tab stack so the toolbar
+  // button greys out instead of silently no-op'ing on every click.
   const handleUndo = useCallback(() => {
-    const previous = undoRedo.undo(stateRef.current)
-    if (!previous) return
-    debouncedSave.cancel()
+    const eventId = undoRedo.popUndo()
+    if (!eventId) return
+    flushAllPendingWidgetPatches()
     debouncedSourceSave.cancel()
     dirtyRef.current = true
-    setLocalWidgets(previous.widgets)
-    setLocalSources(previous.sources)
-    setLocalConnectors(previous.connectors ?? [])
-    queueWrite(() =>
-      updateCanvas(canvasId, { widgets: previous.widgets, sources: previous.sources, connectors: previous.connectors })
-        .catch((err) => console.error('[canvas] Failed to persist undo:', err))
-    )
-  }, [canvasId, debouncedSave, debouncedSourceSave, undoRedo])
+    queueWrite(async () => {
+      try {
+        const { status, data } = await undoEventApi(canvasId, eventId)
+        if (status === 404) {
+          console.warn('[canvas] Undo target was compacted away — resetting undo stack')
+          undoRedo.reset()
+          return
+        }
+        if (data?.eventId) undoRedo.pushRedo(data.eventId)
+        else if (data?.error) console.error('[canvas] Undo rejected:', data.error)
+      } catch (err) {
+        console.error('[canvas] Failed to persist undo:', err)
+      }
+    })
+  }, [canvasId, debouncedSourceSave, flushAllPendingWidgetPatches, undoRedo])
 
   const handleRedo = useCallback(() => {
-    const next = undoRedo.redo(stateRef.current)
-    if (!next) return
-    debouncedSave.cancel()
+    const eventId = undoRedo.popRedo()
+    if (!eventId) return
+    flushAllPendingWidgetPatches()
     debouncedSourceSave.cancel()
     dirtyRef.current = true
-    setLocalWidgets(next.widgets)
-    setLocalSources(next.sources)
-    setLocalConnectors(next.connectors ?? [])
-    queueWrite(() =>
-      updateCanvas(canvasId, { widgets: next.widgets, sources: next.sources, connectors: next.connectors })
-        .catch((err) => console.error('[canvas] Failed to persist redo:', err))
-    )
-  }, [canvasId, debouncedSave, debouncedSourceSave, undoRedo])
+    queueWrite(async () => {
+      try {
+        const { status, data } = await redoEventApi(canvasId, eventId)
+        if (status === 404) {
+          console.warn('[canvas] Redo target was compacted away — resetting redo stack')
+          undoRedo.reset()
+          return
+        }
+        if (data?.eventId) undoRedo.pushUndo(data.eventId)
+        else if (data?.error) console.error('[canvas] Redo rejected:', data.error)
+      } catch (err) {
+        console.error('[canvas] Failed to persist redo:', err)
+      }
+    })
+  }, [canvasId, debouncedSourceSave, flushAllPendingWidgetPatches, undoRedo])
 
   // Keyboard shortcuts — dev-only (Cmd+Z / Cmd+Shift+Z / Cmd+D / Cmd+A)
   useEffect(() => {
@@ -3493,6 +3635,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       <div
         ref={scrollRef}
         data-storyboard-canvas-scroll
+        data-sb-surface="canvas"
         data-sb-canvas-theme={canvasTheme}
         {...canvasPrimerAttrs}
         className={styles.canvasScroll}