@dfosco/storyboard 0.7.1 → 0.9.0

package/src/core/canvas/server.js

@@ -12,6 +12,8 @@
  *   GET    /list     — list all canvases
  *   GET    /folders  — list canvas folders
  *   PUT    /update   — append update events (widgets, sources, settings)
+ *   POST   /undo     — append the inverse of a previously-applied event
+ *   POST   /redo     — re-apply an undone event (mirror of /undo)
  *   PUT    /rename-page — rename a canvas page file
  *   PUT    /reorder-pages — save page order for a canvas folder
  *   GET    /page-order — read page order for a folder
@@ -38,7 +40,9 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { Buffer } from 'node:buffer'
 import { createHash } from 'node:crypto'
-import { materializeFromText, serializeEvent } from './materializer.js'
+import { materializeFromText, parseCanvasJsonl, serializeEvent } from './materializer.js'
+import { buildInverseEvent } from './undoRedo.js'
+import { compactCanvas } from './compact.js'
 import { toCanvasId, parseCanvasId } from './identity.js'
 import {
   GH_INSTALL_URL,
@@ -137,7 +141,7 @@ function writeFolderMeta(folderDir, meta) {
  */
 function findCanvasFiles(root) {
   const results = []
-  const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees'])
+  const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees', 'worktrees', 'workleafs'])
 
   function walk(dir, rel) {
     let entries
@@ -164,7 +168,7 @@ function findCanvasFiles(root) {
  */
 function findStoryFiles(root) {
   const results = []
-  const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees'])
+  const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees', 'worktrees', 'workleafs'])
   const ROUTABLE_DIRS = ['src/canvas', 'src/components']
 
   function walk(dir, rel) {
@@ -240,6 +244,53 @@ function appendEventRaw(filePath, event) {
   fs.appendFileSync(filePath, serializeEvent(event) + '\n', 'utf-8')
 }
 
+/**
+ * Generate a short random event id. Stamped on every canvas event so
+ * undo/redo can reference the inverse target by id alone.
+ */
+function generateEventId() {
+  return `evt_${Math.random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * Hard ceiling for runaway sessions: when a JSONL file grows past this size,
+ * compact it once (collapses history into a single `canvas_created` baseline).
+ * Set above the normal startup-compaction threshold (500 KB) so most files
+ * never hit it — only marathon sessions that don't restart the dev server.
+ */
+const SOFT_COMPACT_THRESHOLD_BYTES = 2 * 1024 * 1024
+
+/** Per-file lock to avoid compacting the same file repeatedly on bursts. */
+const inFlightCompactions = new Set()
+
+/**
+ * Check the file size after a write; if past the runaway threshold, kick off
+ * a one-shot compaction. Best-effort — failures are swallowed and logged.
+ */
+function maybeCompactRunawayFile(filePath) {
+  if (inFlightCompactions.has(filePath)) return
+  let size
+  try { size = fs.statSync(filePath).size } catch { return }
+  if (size < SOFT_COMPACT_THRESHOLD_BYTES) return
+  inFlightCompactions.add(filePath)
+  // Run on the next tick so this append's HMR push fires first and the
+  // compaction's HMR push lands after — the client treats both consistently
+  // (compaction's push is a single canvas_created event that reconciles).
+  setImmediate(() => {
+    try {
+      const result = compactCanvas(filePath, { force: true })
+      devLog().logEvent('info', `[canvas] runaway compaction ${path.basename(filePath)}`, {
+        before: result.before,
+        after: result.after,
+      })
+    } catch (err) {
+      devLog().logEvent('warn', `[canvas] runaway compaction failed for ${filePath}`, { error: err.message })
+    } finally {
+      inFlightCompactions.delete(filePath)
+    }
+  })
+}
+
 /**
  * Generate a unique widget ID.
  */
@@ -702,13 +753,25 @@ export function createCanvasHandler(ctx) {
   // Append an event to an existing canvas file.
   // Marks the file in the write guard so the data plugin's watcher handler
   // skips sending a duplicate HMR event (the server pushes its own via
-  // pushCanvasUpdate after the write).
+  // pushCanvasUpdate after the write). Stamps a stable random `id` so
+  // undo/redo markers can target events by id.
+  //
+  // Also runs the runaway-session hard ceiling: if the file grows past
+  // SOFT_COMPACT_THRESHOLD after writing, kick off a one-shot compaction
+  // to keep the JSONL → HMR → React pipeline responsive. The user's per-tab
+  // undo stack will lose pre-compaction targets (post-compaction undo calls
+  // return 404 which the client interprets as "clear the stack").
   function appendEvent(filePath, event) {
+    if (event && typeof event === 'object' && !event.id) {
+      event.id = generateEventId()
+    }
     markCanvasWrite(filePath)
     appendEventRaw(filePath, event)
+    maybeCompactRunawayFile(filePath)
     // Unmark after enough time for the watcher to fire and be suppressed.
     // macOS FSEvents latency is typically 100-500ms; 1s covers edge cases.
     setTimeout(() => unmarkCanvasWrite(filePath), 1000)
+    return event.id
   }
 
   /**
@@ -783,18 +846,18 @@ export function createCanvasHandler(ctx) {
   }
 
   /**
-   * Non-mutating probe of a hot pool — returns webgl-readiness without
-   * claiming a slot. Use this when the canvas API just needs to tell the
-   * client whether to render in webgl-ready mode; the actual session claim
-   * happens later in terminal-server when the WebSocket connects.
+   * Non-mutating probe of a hot pool — returns readiness without claiming
+   * a slot. Use this when the canvas API just needs to tell the client
+   * whether a hot session is available; the actual session claim happens
+   * later in terminal-server when the WebSocket connects.
    * @param {Object|null} hotPool — HotPoolManager instance
    * @param {string} poolId — pool to peek at
    * @param {string} [mode] — 'auto' (default), 'hot', or 'cold'
-   * @returns {{ ready: boolean, webglReady: boolean }}
+   * @returns {{ ready: boolean }}
    */
   function peekPool(hotPool, poolId, mode) {
-    if (!hotPool || mode === 'cold') return { ready: false, webglReady: false }
-    if (!hotPool.has(poolId)) return { ready: false, webglReady: false }
+    if (!hotPool || mode === 'cold') return { ready: false }
+    if (!hotPool.has(poolId)) return { ready: false }
     return hotPool.peek(poolId)
   }
 
@@ -879,15 +942,20 @@ export function createCanvasHandler(ctx) {
     if (routePath === '/folders' && method === 'GET') {
       const canvasDir = path.join(root, 'src', 'canvas')
       let folders = []
+      let entries = []
       try {
         if (fs.existsSync(canvasDir)) {
-          const entries = fs.readdirSync(canvasDir, { withFileTypes: true })
-          // .folder directories (existing behavior)
-          const folderDirs = entries
+          const dirEntries = fs.readdirSync(canvasDir, { withFileTypes: true })
+          // .folder directories — workspace grouping (sibling canvases shown
+          // under a folder header in the workspace, each addressable on its
+          // own /canvas/<folder>/<name> route).
+          const folderDirs = dirEntries
             .filter((d) => d.isDirectory() && d.name.endsWith('.folder'))
             .map((d) => d.name.replace('.folder', ''))
-          // Plain directories containing .canvas.jsonl files
-          const plainDirs = entries
+          // Plain directories containing .canvas.jsonl files — multi-page
+          // canvas grouping (each .canvas.jsonl is a "page" of the parent
+          // group, surfaced via PageSelector inside the canvas).
+          const plainDirs = dirEntries
             .filter((d) => {
               if (!d.isDirectory() || d.name.endsWith('.folder') || d.name.startsWith('_')) return false
               const files = fs.readdirSync(path.join(canvasDir, d.name))
@@ -895,9 +963,16 @@ export function createCanvasHandler(ctx) {
             })
             .map((d) => d.name)
           folders = [...folderDirs, ...plainDirs]
+          entries = [
+            ...folderDirs.map((name) => ({ name, kind: 'workspace' })),
+            ...plainDirs.map((name) => ({ name, kind: 'pages' })),
+          ]
         }
       } catch { /* empty */ }
-      sendJson(res, 200, { folders })
+      // `folders` is the legacy flat name list; `entries` is the new tagged
+      // list. Clients can prefer `entries` when they need to know whether a
+      // folder is a `.folder/` (workspace) or plain (multi-page) dir.
+      sendJson(res, 200, { folders, entries })
       return
     }
 
@@ -1007,6 +1082,9 @@ export function createCanvasHandler(ctx) {
 
       try {
         const ts = new Date().toISOString()
+        // Snapshot of pre-update state so we can stamp prev* payloads on
+        // source_updated and settings_updated events without re-reading.
+        const current = readCanvas(filePath)
 
         if (widgets) {
           // Guard against accidental canvas wipes. Any widget IDs present in
@@ -1015,7 +1093,6 @@ export function createCanvasHandler(ctx) {
           // This protects against stale-state writers (e.g. a debounced client
           // save fired before an HMR push containing newly-added widgets was
           // reconciled) silently wiping freshly-created widgets.
-          const current = readCanvas(filePath)
           const currentWidgets = current.widgets || []
           if (body.replaceAll !== true) {
             const incomingIds = new Set(widgets.map((w) => w && w.id).filter(Boolean))
@@ -1032,14 +1109,23 @@ export function createCanvasHandler(ctx) {
             }
           }
           const stamped = stampBoundsAll(widgets)
+          // widgets_replaced is not undoable — emitted only by compaction or
+          // explicit replaceAll. The client should use PATCH/POST/DELETE for
+          // granular, undoable changes.
           appendEvent(filePath, { event: 'widgets_replaced', timestamp: ts, widgets: stamped })
         }
 
         if (sources) {
-          appendEvent(filePath, { event: 'source_updated', timestamp: ts, sources })
+          appendEvent(filePath, {
+            event: 'source_updated',
+            timestamp: ts,
+            sources,
+            prevSources: Array.isArray(current.sources) ? current.sources : [],
+          })
         }
 
         if (connectors) {
+          // connectors_replaced is not undoable — emitted only by compaction.
           appendEvent(filePath, { event: 'connectors_replaced', timestamp: ts, connectors })
         }
 
@@ -1051,7 +1137,17 @@ export function createCanvasHandler(ctx) {
             }
           }
           if (Object.keys(filtered).length > 0) {
-            appendEvent(filePath, { event: 'settings_updated', timestamp: ts, settings: filtered })
+            // Capture prior values for the keys being changed.
+            const prevSettings = {}
+            for (const key of Object.keys(filtered)) {
+              prevSettings[key] = current[key]
+            }
+            appendEvent(filePath, {
+              event: 'settings_updated',
+              timestamp: ts,
+              settings: filtered,
+              prevSettings,
+            })
           }
         }
 
@@ -1063,6 +1159,61 @@ export function createCanvasHandler(ctx) {
       return
     }
 
+    // POST /undo — append the inverse of a previously-applied event, tagged
+    // with meta.kind = 'undo' / meta.of = <targetEventId>. Body:
+    //   { name, eventId }
+    // Returns { success, eventId, inverseEvent: {...} }.
+    //
+    // POST /redo behaves identically but stamps meta.kind = 'redo'. Per
+    // convention the client passes the id of the *undo* event when redoing
+    // (so the redo cancels the undo and brings back the original change).
+    if ((routePath === '/undo' || routePath === '/redo') && method === 'POST') {
+      const { name, eventId } = body
+      const kind = routePath === '/undo' ? 'undo' : 'redo'
+
+      if (!name || !eventId) {
+        sendJson(res, 400, { error: 'Canvas name and eventId are required' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        const text = fs.readFileSync(filePath, 'utf-8')
+        const events = parseCanvasJsonl(text)
+        const target = events.find((evt) => evt && evt.id === eventId)
+        if (!target) {
+          sendJson(res, 404, { error: `Event "${eventId}" not found in canvas "${name}"` })
+          return
+        }
+
+        const inverse = buildInverseEvent(target, kind)
+        if (!inverse) {
+          sendJson(res, 400, {
+            error: `Event "${eventId}" (type "${target.event}") cannot be ${kind === 'undo' ? 'undone' : 'redone'}: missing inverse payload or unsupported event type`,
+          })
+          return
+        }
+
+        inverse.timestamp = new Date().toISOString()
+        const inverseId = appendEvent(filePath, inverse)
+
+        sendJson(res, 200, {
+          success: true,
+          eventId: inverseId,
+          inverseEvent: { ...inverse, id: inverseId },
+        })
+        pushCanvasUpdate(name, filePath, __viteWs)
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to ${kind} event: ${err.message}` })
+      }
+      return
+    }
+
     // POST /widget — append a widget_added event
     if (routePath === '/widget' && method === 'POST') {
       const { name, type, props = {}, pool, near, direction, resolve, source, gap } = body
@@ -1134,11 +1285,11 @@ export function createCanvasHandler(ctx) {
 
         // Hot pool readiness probe for terminal/agent widgets — non-mutating.
         // The actual session claim happens later in terminal-server when the
-        // WS connects. Probing here only tells the client whether to render
-        // in webgl-ready mode immediately. (Previously this called
-        // acquireFromPool, which leaked a #acquired slot per widget creation
-        // because no consume/release ever fired against this acquisition.)
-        let hotProbe = { ready: false, webglReady: false }
+        // WS connects. Probing here only tells the client whether a hot
+        // session is available. (Previously this called acquireFromPool,
+        // which leaked a #acquired slot per widget creation because no
+        // consume/release ever fired against this acquisition.)
+        let hotProbe = { ready: false }
         if ((type === 'terminal' || type === 'agent') && pool !== 'cold') {
           const poolId = resolvePoolId(type, props)
           hotProbe = peekPool(hotPool, poolId, pool)
@@ -1150,14 +1301,14 @@ export function createCanvasHandler(ctx) {
 
         const widget = stampBounds({ id: widgetId, type, position, props })
 
-        appendEvent(filePath, {
+        const eventId = appendEvent(filePath, {
           event: 'widget_added',
           timestamp: new Date().toISOString(),
           widget,
         })
 
-        const response = { success: true, widget }
-        if (hotProbe.ready) response.hotSession = { id: null, tmuxName: null, webglReady: hotProbe.webglReady }
+        const response = { success: true, widget, eventId }
+        if (hotProbe.ready) response.hotSession = { id: null, tmuxName: null }
         sendJson(res, 201, response)
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
@@ -1190,10 +1341,13 @@ export function createCanvasHandler(ctx) {
           return
         }
 
-        appendEvent(filePath, {
+        const eventId = appendEvent(filePath, {
           event: 'widget_removed',
           timestamp: new Date().toISOString(),
           widgetId,
+          // Carry the full removed widget so undo can re-add it without
+          // walking history. Symmetric to widget_added.widget.
+          widget,
         })
 
         // Orphan terminal session when a terminal widget is deleted (not killed)
@@ -1206,7 +1360,7 @@ export function createCanvasHandler(ctx) {
           }
         }
 
-        sendJson(res, 200, { success: true, removed: 1 })
+        sendJson(res, 200, { success: true, removed: 1, eventId })
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to remove widget: ${err.message}` })
@@ -1242,25 +1396,34 @@ export function createCanvasHandler(ctx) {
         }
 
         const ts = new Date().toISOString()
+        const eventIds = []
 
         if (props) {
-          appendEvent(filePath, {
+          // Capture only the keys being changed so undo restores them
+          // precisely. Missing keys mean "this prop didn't exist before".
+          const prevProps = {}
+          for (const key of Object.keys(props)) {
+            prevProps[key] = widget.props ? widget.props[key] : undefined
+          }
+          eventIds.push(appendEvent(filePath, {
             event: 'widget_updated',
             timestamp: ts,
             widgetId,
             props,
-          })
+            prevProps,
+          }))
         }
 
         if (position) {
           // Merge with existing position so partial updates (only --x or --y) are safe
           const mergedPosition = { ...widget.position, ...position }
-          appendEvent(filePath, {
+          eventIds.push(appendEvent(filePath, {
             event: 'widget_moved',
             timestamp: ts,
             widgetId,
             position: mergedPosition,
-          })
+            prevPosition: widget.position || { x: 0, y: 0 },
+          }))
         }
 
         // Return the merged widget for convenience
@@ -1269,7 +1432,7 @@ export function createCanvasHandler(ctx) {
           props: { ...widget.props, ...(props || {}) },
           position: position ? { ...widget.position, ...position } : widget.position,
         }
-        sendJson(res, 200, { success: true, widget: merged })
+        sendJson(res, 200, { success: true, widget: merged, eventIds })
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to update widget: ${err.message}` })
@@ -1417,13 +1580,13 @@ export function createCanvasHandler(ctx) {
           meta: meta && typeof meta === 'object' ? { ...meta } : {},
         }
 
-        appendEvent(filePath, {
+        const eventId = appendEvent(filePath, {
           event: 'connector_added',
           timestamp: new Date().toISOString(),
           connector,
         })
 
-        sendJson(res, 201, { success: true, connector })
+        sendJson(res, 201, { success: true, connector, eventId })
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to add connector: ${err.message}` })
@@ -1469,14 +1632,28 @@ export function createCanvasHandler(ctx) {
         if (startAnchor) updates.startAnchor = startAnchor
         if (endAnchor) updates.endAnchor = endAnchor
 
-        appendEvent(filePath, {
+        // Capture the previous values for the keys we're changing so undo
+        // can restore them precisely.
+        const prevUpdates = {}
+        if (meta) {
+          const prevMeta = {}
+          for (const key of Object.keys(meta)) {
+            prevMeta[key] = connector.meta ? connector.meta[key] : undefined
+          }
+          prevUpdates.meta = prevMeta
+        }
+        if (startAnchor) prevUpdates.startAnchor = connector.start?.anchor
+        if (endAnchor) prevUpdates.endAnchor = connector.end?.anchor
+
+        const eventId = appendEvent(filePath, {
           event: 'connector_updated',
           timestamp: new Date().toISOString(),
           connectorId,
           updates,
+          prevUpdates,
         })
 
-        sendJson(res, 200, { success: true })
+        sendJson(res, 200, { success: true, eventId })
         pushCanvasUpdate(name, filePath, __viteWs)
 
         // Inject messaging skill into both terminals when mode changes
@@ -1562,8 +1739,8 @@ export function createCanvasHandler(ctx) {
 
       try {
         const data = readCanvas(filePath)
-        const exists = (data.connectors || []).some((c) => c.id === connectorId)
-        if (!exists) {
+        const existing = (data.connectors || []).find((c) => c.id === connectorId)
+        if (!existing) {
           sendJson(res, 404, { error: `Connector "${connectorId}" not found in canvas "${name}"` })
           return
         }
@@ -1576,14 +1753,17 @@ export function createCanvasHandler(ctx) {
           return out
         })
 
-        appendEvent(filePath, {
+        const eventId = appendEvent(filePath, {
           event: 'connector_waypoints_set',
           timestamp: new Date().toISOString(),
           connectorId,
           waypoints: normalized,
+          // null prevWaypoints means "this connector had no manual routing
+          // before"; undo emits connector_waypoints_cleared in that case.
+          prevWaypoints: Array.isArray(existing.waypoints) ? existing.waypoints : null,
         })
 
-        sendJson(res, 200, { success: true, waypoints: normalized })
+        sendJson(res, 200, { success: true, waypoints: normalized, eventId })
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to set waypoints: ${err.message}` })
@@ -1608,19 +1788,20 @@ export function createCanvasHandler(ctx) {
 
       try {
         const data = readCanvas(filePath)
-        const exists = (data.connectors || []).some((c) => c.id === connectorId)
-        if (!exists) {
+        const existing = (data.connectors || []).find((c) => c.id === connectorId)
+        if (!existing) {
           sendJson(res, 404, { error: `Connector "${connectorId}" not found in canvas "${name}"` })
           return
         }
 
-        appendEvent(filePath, {
+        const eventId = appendEvent(filePath, {
           event: 'connector_waypoints_cleared',
           timestamp: new Date().toISOString(),
           connectorId,
+          prevWaypoints: Array.isArray(existing.waypoints) ? existing.waypoints : null,
         })
 
-        sendJson(res, 200, { success: true })
+        sendJson(res, 200, { success: true, eventId })
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to clear waypoints: ${err.message}` })
@@ -1645,19 +1826,22 @@ export function createCanvasHandler(ctx) {
 
       try {
         const data = readCanvas(filePath)
-        const exists = (data.connectors || []).some((c) => c.id === connectorId)
-        if (!exists) {
+        const connector = (data.connectors || []).find((c) => c.id === connectorId)
+        if (!connector) {
           sendJson(res, 404, { error: `Connector "${connectorId}" not found in canvas "${name}"` })
           return
         }
 
-        appendEvent(filePath, {
+        const eventId = appendEvent(filePath, {
           event: 'connector_removed',
           timestamp: new Date().toISOString(),
           connectorId,
+          // Carry the full removed connector so undo can re-add it without
+          // walking history. Symmetric to connector_added.connector.
+          connector,
         })
 
-        sendJson(res, 200, { success: true, removed: 1 })
+        sendJson(res, 200, { success: true, removed: 1, eventId })
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to remove connector: ${err.message}` })
@@ -1892,7 +2076,7 @@ export function createCanvasHandler(ctx) {
                 const widgetId = generateWidgetId(type)
                 await prepareTerminalWidget({ type, props, widgetId, canvasName: name, req })
 
-                let hotProbe = { ready: false, webglReady: false }
+                let hotProbe = { ready: false }
                 if ((type === 'terminal' || type === 'agent') && pool !== 'cold') {
                   const poolId = resolvePoolId(type, props)
                   hotProbe = peekPool(hotPool, poolId, pool)
@@ -1901,15 +2085,15 @@ export function createCanvasHandler(ctx) {
 
                 const widget = stampBounds({ id: widgetId, type, position, props })
 
-                appendEvent(filePath, { event: 'widget_added', timestamp: ts, widget })
+                const eventId = appendEvent(filePath, { event: 'widget_added', timestamp: ts, widget })
 
                 widgetIds.add(widgetId)
                 widgetMap.set(widgetId, widget)
                 refs[String(i)] = widgetId
                 if (ref) refs[ref] = widgetId
 
-                const result = { index: i, op: 'create-widget', ref: ref || undefined, widgetId, widget }
-                if (hotProbe.ready) result.hotSession = { id: null, tmuxName: null, webglReady: hotProbe.webglReady }
+                const result = { index: i, op: 'create-widget', ref: ref || undefined, widgetId, widget, eventId }
+                if (hotProbe.ready) result.hotSession = { id: null, tmuxName: null }
                 results.push(result)
                 break
               }
@@ -1921,12 +2105,16 @@ export function createCanvasHandler(ctx) {
                 if (!props) throw new Error('props is required')
                 if (!widgetIds.has(widgetId)) throw new Error(`Widget "${widgetId}" not found`)
 
-                appendEvent(filePath, { event: 'widget_updated', timestamp: ts, widgetId, props })
-
                 const existing = widgetMap.get(widgetId)
+                const prevProps = {}
+                for (const key of Object.keys(props)) {
+                  prevProps[key] = existing?.props ? existing.props[key] : undefined
+                }
+                const eventId = appendEvent(filePath, { event: 'widget_updated', timestamp: ts, widgetId, props, prevProps })
+
                 if (existing) existing.props = { ...existing.props, ...props }
 
-                results.push({ index: i, op: 'update-widget', widgetId, success: true })
+                results.push({ index: i, op: 'update-widget', widgetId, success: true, eventId })
                 break
               }
 
@@ -1939,12 +2127,13 @@ export function createCanvasHandler(ctx) {
 
                 const existing = widgetMap.get(widgetId)
                 const mergedPosition = { ...(existing?.position || {}), ...position }
+                const prevPosition = existing?.position || { x: 0, y: 0 }
 
-                appendEvent(filePath, { event: 'widget_moved', timestamp: ts, widgetId, position: mergedPosition })
+                const eventId = appendEvent(filePath, { event: 'widget_moved', timestamp: ts, widgetId, position: mergedPosition, prevPosition })
 
                 if (existing) existing.position = mergedPosition
 
-                results.push({ index: i, op: 'move-widget', widgetId, success: true })
+                results.push({ index: i, op: 'move-widget', widgetId, success: true, eventId })
                 break
               }
 
@@ -1953,12 +2142,18 @@ export function createCanvasHandler(ctx) {
                 if (!widgetId) throw new Error('widgetId is required')
                 if (!widgetIds.has(widgetId)) throw new Error(`Widget "${widgetId}" not found`)
 
-                appendEvent(filePath, { event: 'widget_removed', timestamp: ts, widgetId })
+                const existing = widgetMap.get(widgetId)
+                const eventId = appendEvent(filePath, {
+                  event: 'widget_removed',
+                  timestamp: ts,
+                  widgetId,
+                  widget: existing,
+                })
 
                 widgetIds.delete(widgetId)
                 widgetMap.delete(widgetId)
 
-                results.push({ index: i, op: 'delete-widget', widgetId, success: true })
+                results.push({ index: i, op: 'delete-widget', widgetId, success: true, eventId })
                 break
               }
 
@@ -1993,14 +2188,14 @@ export function createCanvasHandler(ctx) {
                   meta: op.meta && typeof op.meta === 'object' ? { ...op.meta } : {},
                 }
 
-                appendEvent(filePath, { event: 'connector_added', timestamp: ts, connector })
+                const eventId = appendEvent(filePath, { event: 'connector_added', timestamp: ts, connector })
 
                 connectorIds.add(connectorId)
                 connectorMap.set(connectorId, connector)
                 refs[String(i)] = connectorId
                 if (ref) refs[ref] = connectorId
 
-                results.push({ index: i, op: 'create-connector', ref: ref || undefined, connectorId, success: true })
+                results.push({ index: i, op: 'create-connector', ref: ref || undefined, connectorId, success: true, eventId })
                 break
               }
 
@@ -2009,11 +2204,17 @@ export function createCanvasHandler(ctx) {
                 if (!connectorId) throw new Error('connectorId is required')
                 if (!connectorIds.has(connectorId)) throw new Error(`Connector "${connectorId}" not found`)
 
-                appendEvent(filePath, { event: 'connector_removed', timestamp: ts, connectorId })
+                const existing = connectorMap.get(connectorId)
+                const eventId = appendEvent(filePath, {
+                  event: 'connector_removed',
+                  timestamp: ts,
+                  connectorId,
+                  connector: existing,
+                })
                 connectorIds.delete(connectorId)
                 connectorMap.delete(connectorId)
 
-                results.push({ index: i, op: 'delete-connector', connectorId, success: true })
+                results.push({ index: i, op: 'delete-connector', connectorId, success: true, eventId })
                 break
               }
 
@@ -2024,12 +2225,22 @@ export function createCanvasHandler(ctx) {
                 if (!meta) throw new Error('meta is required')
                 if (!connectorIds.has(connectorId)) throw new Error(`Connector "${connectorId}" not found`)
 
-                appendEvent(filePath, { event: 'connector_updated', timestamp: ts, connectorId, updates: { meta } })
-
                 const existing = connectorMap.get(connectorId)
+                const prevMeta = {}
+                for (const key of Object.keys(meta)) {
+                  prevMeta[key] = existing?.meta ? existing.meta[key] : undefined
+                }
+                const eventId = appendEvent(filePath, {
+                  event: 'connector_updated',
+                  timestamp: ts,
+                  connectorId,
+                  updates: { meta },
+                  prevUpdates: { meta: prevMeta },
+                })
+
                 if (existing) existing.meta = { ...(existing.meta || {}), ...meta }
 
-                results.push({ index: i, op: 'update-connector', connectorId, success: true })
+                results.push({ index: i, op: 'update-connector', connectorId, success: true, eventId })
                 break
               }
 
@@ -2397,6 +2608,7 @@ export function createCanvasHandler(ctx) {
         name,
         title,
         folder,
+        folderKind,
         convertFrom,
         author,
         description,
@@ -2531,7 +2743,12 @@ export function createCanvasHandler(ctx) {
       }
 
       // ── Standard canvas creation ─────────────────────────────────────
-      // Determine target directory
+      // Determine target directory. When `folder` is set:
+      //   - existing `<folder>.folder/` wins → workspace grouping
+      //   - existing `<folder>/` wins → multi-page canvas grouping
+      //   - otherwise: create a new dir; `folderKind` controls which kind.
+      //     Default kind is "pages" for backward compatibility (the legacy
+      //     behavior). Pass `"workspace"` to create `<folder>.folder/`.
       const canvasDir = path.join(root, 'src', 'canvas')
       let targetDir = canvasDir
 
@@ -2540,25 +2757,28 @@ export function createCanvasHandler(ctx) {
         const plainDir = path.join(canvasDir, folder)
 
         if (fs.existsSync(dotFolderDir)) {
-          // Existing .folder/ directory
+          // Existing .folder/ directory (workspace grouping)
           targetDir = dotFolderDir
         } else if (fs.existsSync(plainDir) && fs.statSync(plainDir).isDirectory()) {
-          // Existing plain directory
+          // Existing plain directory (multi-page grouping)
           targetDir = plainDir
         } else {
-          // Create new plain directory
+          // Create a new directory according to the requested kind.
+          const useWorkspace = folderKind === 'workspace'
+          const newDir = useWorkspace ? dotFolderDir : plainDir
           try {
-            fs.mkdirSync(plainDir, { recursive: true })
-            // Write .meta.json if meta was provided
+            fs.mkdirSync(newDir, { recursive: true })
+            // Write .meta.json if meta was provided (only meaningful for
+            // multi-page groups today; harmless inside a .folder/).
             if (meta && typeof meta === 'object') {
-              const metaPath = path.join(plainDir, `${folder}.meta.json`)
+              const metaPath = path.join(newDir, `${folder}.meta.json`)
               fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n', 'utf-8')
             }
           } catch (err) {
             sendJson(res, 500, { error: `Failed to create directory: ${err.message}` })
             return
           }
-          targetDir = plainDir
+          targetDir = newDir
         }
       }
 
@@ -2763,16 +2983,56 @@ export function Default() {
     const EXT_TO_MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }
     const MAX_IMAGE_SIZE = 5 * 1024 * 1024 // 5 MB
 
-    // Route snapshot uploads (snapshot-* prefix) to the snapshots directory
+    // Route snapshot uploads (snapshot-* prefix) to the snapshots directory.
+    // Canvases inside a `drafts/` segment go to images/drafts/ (gitignored)
+    // so draft-only images don't leak into git via assets/canvas/images/.
+    function isDraftCanvasId(canvasName) {
+      if (!canvasName || typeof canvasName !== 'string') return false
+      return canvasName.split('/').some((seg) => seg === 'drafts')
+    }
     function resolveWriteDir(canvasName) {
-      return canvasName?.startsWith('snapshot-') ? snapshotsDir : imagesDir
+      if (canvasName?.startsWith('snapshot-')) return snapshotsDir
+      if (isDraftCanvasId(canvasName)) return path.join(imagesDir, 'drafts')
+      return imagesDir
+    }
+
+    // Validate a filename coming from the client. Accepts a bare basename
+    // (`foo.png`) or one optional `drafts/` segment (`drafts/foo.png`).
+    // Returns { dirSegment: '' | 'drafts', basename } or null if invalid.
+    function parseValidFilename(filename) {
+      if (!filename || typeof filename !== 'string') return null
+      if (filename.includes('..') || filename.includes('\\')) return null
+      const segments = filename.split('/')
+      if (segments.length === 1) {
+        return segments[0] ? { dirSegment: '', basename: segments[0] } : null
+      }
+      if (segments.length === 2 && segments[0] === 'drafts' && segments[1]) {
+        return { dirSegment: 'drafts', basename: segments[1] }
+      }
+      return null
     }
 
+    // Resolve a stored filename to an absolute path on disk.
+    //
+    // `filename` may be either a bare basename (`foo.png`) or one optional
+    // `drafts/` segment followed by a basename (`drafts/foo.png`). The
+    // `drafts/` form is reserved for images that belong to draft canvases
+    // and resolves only into images/drafts/. Bare basenames intentionally
+    // do NOT fall back to images/drafts/ — that would let a public canvas
+    // serve a draft-only asset just by sharing a basename.
+    //
+    // Returns null when the filename is malformed or the file is not found.
     function resolveImagePath(filename) {
-      // Check snapshots dir first, then images
-      const snapshotPath = path.join(snapshotsDir, filename)
+      const parsed = parseValidFilename(filename)
+      if (!parsed) return null
+      if (parsed.dirSegment === 'drafts') {
+        const draftPath = path.join(imagesDir, 'drafts', parsed.basename)
+        if (fs.existsSync(draftPath)) return draftPath
+        return null
+      }
+      const snapshotPath = path.join(snapshotsDir, parsed.basename)
       if (fs.existsSync(snapshotPath)) return snapshotPath
-      const imagePath = path.join(imagesDir, filename)
+      const imagePath = path.join(imagesDir, parsed.basename)
       if (fs.existsSync(imagePath)) return imagePath
       return null
     }
@@ -2831,26 +3091,33 @@ export function Default() {
         filename = `${prefix}${dateStr}${suffix}.${ext}`
       }
       const targetDir = resolveWriteDir(canvasName || '')
+      // Return the filename with a `drafts/` prefix when the write went to
+      // the drafts subdirectory, so widget `props.src` includes the
+      // directory and the GET route can locate the file unambiguously.
+      const responseFilename =
+        targetDir === path.join(imagesDir, 'drafts') ? `drafts/${filename}` : filename
 
       try {
         fs.mkdirSync(targetDir, { recursive: true })
         fs.writeFileSync(path.join(targetDir, filename), buffer)
-        sendJson(res, 201, { success: true, filename })
+        sendJson(res, 201, { success: true, filename: responseFilename })
       } catch (err) {
         sendJson(res, 500, { error: `Failed to save image: ${err.message}` })
       }
       return
     }
 
-    // GET /images/<filename> — serve an image file
+    // GET /images/<filename> — serve an image file. Filename may include
+    // an optional `drafts/` directory segment (e.g. `drafts/foo.png`).
     if (routePath.startsWith('/images/') && method === 'GET') {
       // Strip query string (e.g. ?v=123 cache busters) from filename
       let filename = routePath.slice('/images/'.length)
       const qIdx = filename.indexOf('?')
       if (qIdx !== -1) filename = filename.slice(0, qIdx)
 
-      // Block path traversal
-      if (!filename || filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+      // Validate (allows optional `drafts/` segment, rejects deeper paths
+      // and path traversal)
+      if (!parseValidFilename(filename)) {
         sendJson(res, 400, { error: 'Invalid filename' })
         return
       }
@@ -2878,7 +3145,8 @@ export function Default() {
       return
     }
 
-    // POST /image/duplicate — copy an image file with a new timestamped name
+    // POST /image/duplicate — copy an image file with a new timestamped name.
+    // Accepts a bare basename or one optional `drafts/` segment.
     if (routePath === '/image/duplicate' && method === 'POST') {
       const { filename } = body
 
@@ -2887,7 +3155,8 @@ export function Default() {
         return
       }
 
-      if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+      const parsed = parseValidFilename(filename)
+      if (!parsed) {
         sendJson(res, 400, { error: 'Invalid filename' })
         return
       }
@@ -2899,20 +3168,23 @@ export function Default() {
       }
 
       try {
-        const ext = path.extname(filename)
+        const base = parsed.basename
+        const ext = path.extname(base)
         const now = new Date()
         const pad = (n) => String(n).padStart(2, '0')
         const dateStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}--${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
-        // Preserve privacy prefix
-        const prefix = filename.startsWith('~') ? '~' : ''
-        const baseName = filename.replace(/^~/, '').replace(ext, '')
+        // Preserve privacy prefix on the basename
+        const prefix = base.startsWith('~') ? '~' : ''
+        const baseName = base.replace(/^~/, '').replace(ext, '')
         // Extract canvas prefix (everything before the date pattern or the full base)
         const canvasMatch = baseName.match(/^(.+?--)\d{4}-/)
         const canvasPrefix = canvasMatch ? canvasMatch[1] : ''
-        const newFilename = `${prefix}${canvasPrefix}${dateStr}${ext}`
+        const newBase = `${prefix}${canvasPrefix}${dateStr}${ext}`
         const targetDir = path.dirname(sourcePath)
-        fs.copyFileSync(sourcePath, path.join(targetDir, newFilename))
-        sendJson(res, 201, { success: true, filename: newFilename })
+        fs.copyFileSync(sourcePath, path.join(targetDir, newBase))
+        // Return the filename with the same drafts/ prefix as the source
+        const responseFilename = parsed.dirSegment === 'drafts' ? `drafts/${newBase}` : newBase
+        sendJson(res, 201, { success: true, filename: responseFilename })
       } catch (err) {
         sendJson(res, 500, { error: `Failed to duplicate image: ${err.message}` })
       }
@@ -2928,24 +3200,28 @@ export function Default() {
         return
       }
 
-      if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+      const parsed = parseValidFilename(filename)
+      if (!parsed) {
         sendJson(res, 400, { error: 'Invalid filename' })
         return
       }
 
-      const isPrivate = filename.startsWith('~')
-      const newFilename = isPrivate ? filename.slice(1) : `~${filename}`
+      const base = parsed.basename
+      const isPrivate = base.startsWith('~')
+      const newBase = isPrivate ? base.slice(1) : `~${base}`
       const oldPath = resolveImagePath(filename)
       if (!oldPath) {
         sendJson(res, 404, { error: 'Image not found' })
         return
       }
       const parentDir = path.dirname(oldPath)
-      const newPath = path.join(parentDir, newFilename)
+      const newPath = path.join(parentDir, newBase)
+      // Preserve the `drafts/` segment on the returned filename
+      const responseFilename = parsed.dirSegment === 'drafts' ? `drafts/${newBase}` : newBase
 
       try {
         fs.renameSync(oldPath, newPath)
-        sendJson(res, 200, { success: true, filename: newFilename, private: !isPrivate })
+        sendJson(res, 200, { success: true, filename: responseFilename, private: !isPrivate })
       } catch (err) {
         sendJson(res, 500, { error: `Failed to toggle private: ${err.message}` })
       }