@dfosco/storyboard 0.6.12 → 0.6.13

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,
@@ -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
   }
 
   /**
@@ -1007,6 +1070,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 +1081,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 +1097,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 +1125,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 +1147,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
@@ -1150,13 +1289,13 @@ 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 }
+        const response = { success: true, widget, eventId }
         if (hotProbe.ready) response.hotSession = { id: null, tmuxName: null, webglReady: hotProbe.webglReady }
         sendJson(res, 201, response)
         pushCanvasUpdate(name, filePath, __viteWs)
@@ -1190,10 +1329,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 +1348,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 +1384,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 +1420,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 +1568,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 +1620,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 +1727,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 +1741,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 +1776,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 +1814,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}` })
@@ -1901,14 +2073,14 @@ 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 }
+                const result = { index: i, op: 'create-widget', ref: ref || undefined, widgetId, widget, eventId }
                 if (hotProbe.ready) result.hotSession = { id: null, tmuxName: null, webglReady: hotProbe.webglReady }
                 results.push(result)
                 break
@@ -1921,12 +2093,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 +2115,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 +2130,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 +2176,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 +2192,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 +2213,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
               }