@dfosco/storyboard 0.6.11 → 0.6.13

package/src/core/canvas/server.test.js

@@ -377,3 +377,229 @@ describe('POST /batch', () => {
     expect(refs['1']).toMatch(/^connector-/)
   })
 })
+
+describe('POST /undo and POST /redo (event-id targeting)', () => {
+  let root, canvasDir, invoke, lastResponse
+
+  beforeEach(() => {
+    ({ invoke, root, canvasDir, lastResponse } = setup())
+    writeCanvas(canvasDir, 'undo-canvas', { title: 'Undo Canvas' })
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  async function addSticky(text) {
+    await invoke('/widget', 'POST', {
+      name: 'undo-canvas',
+      type: 'sticky-note',
+      props: { text },
+      position: { x: 0, y: 0 },
+    })
+    return { widgetId: lastResponse.body.widget.id, eventId: lastResponse.body.eventId }
+  }
+
+  async function readState() {
+    await invoke('/read?name=undo-canvas', 'GET', {})
+    return lastResponse.body
+  }
+
+  it('appends an event id on every mutation', async () => {
+    const { eventId } = await addSticky('a')
+    expect(eventId).toMatch(/^evt_/)
+  })
+
+  it('reproduces the cq-enablement scenario: 3 deletes + undo restores only the most recent', async () => {
+    const a = await addSticky('a')
+    const b = await addSticky('b')
+    const c = await addSticky('c')
+
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId: a.widgetId })
+    const delAEventId = lastResponse.body.eventId
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId: b.widgetId })
+    const delBEventId = lastResponse.body.eventId
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId: c.widgetId })
+    const delCEventId = lastResponse.body.eventId
+
+    expect((await readState()).widgets).toEqual([])
+
+    // Undo only the LAST delete (c).
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: delCEventId })
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body.inverseEvent.event).toBe('widget_added')
+    expect(lastResponse.body.inverseEvent.meta).toEqual({ kind: 'undo', of: delCEventId })
+
+    const after = await readState()
+    expect(after.widgets).toHaveLength(1)
+    expect(after.widgets[0].id).toBe(c.widgetId)
+    // a and b stay deleted — the bug class would have resurrected them too.
+    expect(after.widgets.map((w) => w.id)).not.toContain(a.widgetId)
+    expect(after.widgets.map((w) => w.id)).not.toContain(b.widgetId)
+
+    // Tracking that we don't leave delAEventId / delBEventId mentioned.
+    void delAEventId
+    void delBEventId
+  })
+
+  it('undo of widget_updated reverts the props using prevProps', async () => {
+    const { widgetId } = await addSticky('original')
+
+    await invoke('/widget', 'PATCH', {
+      name: 'undo-canvas',
+      widgetId,
+      props: { text: 'edited' },
+    })
+    const editEventId = lastResponse.body.eventIds[0]
+
+    let state = await readState()
+    expect(state.widgets[0].props.text).toBe('edited')
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: editEventId })
+    state = await readState()
+    expect(state.widgets[0].props.text).toBe('original')
+  })
+
+  it('undo of widget_moved reverts the position using prevPosition', async () => {
+    const { widgetId } = await addSticky('a')
+
+    await invoke('/widget', 'PATCH', {
+      name: 'undo-canvas',
+      widgetId,
+      position: { x: 500, y: 600 },
+    })
+    const moveEventId = lastResponse.body.eventIds[0]
+
+    let state = await readState()
+    expect(state.widgets[0].position).toEqual({ x: 500, y: 600 })
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: moveEventId })
+    state = await readState()
+    expect(state.widgets[0].position).toEqual({ x: 0, y: 0 })
+  })
+
+  it('redo of an undone delete re-removes the widget', async () => {
+    const { widgetId } = await addSticky('a')
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId })
+    const delEventId = lastResponse.body.eventId
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: delEventId })
+    const undoEventId = lastResponse.body.eventId
+    expect((await readState()).widgets).toHaveLength(1)
+
+    // Redo with the undo event id — server emits the inverse of the undo,
+    // which is a fresh widget_removed.
+    await invoke('/redo', 'POST', { name: 'undo-canvas', eventId: undoEventId })
+    expect(lastResponse.body.inverseEvent.event).toBe('widget_removed')
+    expect(lastResponse.body.inverseEvent.meta).toEqual({ kind: 'redo', of: undoEventId })
+
+    expect((await readState()).widgets).toEqual([])
+  })
+
+  it('rejects undo on an unknown event id with 404', async () => {
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: 'evt_does_not_exist' })
+    expect(lastResponse.status).toBe(404)
+  })
+
+  it('rejects undo on a non-undoable event (widgets_replaced) with 400', async () => {
+    // Trigger a widgets_replaced via PUT /update with replaceAll
+    await invoke('/update', 'PUT', {
+      name: 'undo-canvas',
+      widgets: [],
+      replaceAll: true,
+    })
+    // Read the file to get the event id of the widgets_replaced event.
+    const filePath = path.join(canvasDir, 'undo-canvas.canvas.jsonl')
+    const lines = fs.readFileSync(filePath, 'utf-8').trim().split('\n').map((l) => JSON.parse(l))
+    const replacedEvt = lines.find((l) => l.event === 'widgets_replaced')
+    expect(replacedEvt?.id).toBeTruthy()
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: replacedEvt.id })
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.error).toMatch(/cannot be undone/i)
+  })
+})
+
+describe('runaway-session hard ceiling compaction', () => {
+  let root, canvasDir, invoke, lastResponse
+
+  beforeEach(() => {
+    ({ invoke, root, canvasDir, lastResponse } = setup())
+    writeCanvas(canvasDir, 'big-canvas', { title: 'Big Canvas' })
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  // setImmediate-based test helper
+  function flushSetImmediate() {
+    return new Promise((resolve) => setImmediate(resolve))
+  }
+
+  it('does not compact a small file (under the 2 MB threshold)', async () => {
+    const filePath = path.join(canvasDir, 'big-canvas.canvas.jsonl')
+    await invoke('/widget', 'POST', {
+      name: 'big-canvas',
+      type: 'sticky-note',
+      props: { text: 'hello' },
+      position: { x: 0, y: 0 },
+    })
+    await flushSetImmediate()
+    const sizeAfter = fs.statSync(filePath).size
+    expect(sizeAfter).toBeLessThan(2 * 1024 * 1024)
+    // File should still contain both canvas_created + widget_added events.
+    const events = fs.readFileSync(filePath, 'utf-8').trim().split('\n').map((l) => JSON.parse(l))
+    expect(events.length).toBe(2)
+    expect(events[0].event).toBe('canvas_created')
+    expect(events[1].event).toBe('widget_added')
+  })
+
+  it('compacts the file once it exceeds the runaway threshold', async () => {
+    const filePath = path.join(canvasDir, 'big-canvas.canvas.jsonl')
+
+    // Pre-bloat the file past 2 MB by appending raw garbage events. Each
+    // event has a unique id so the materializer treats it as valid.
+    const padding = 'x'.repeat(4000)
+    const bloatLines = []
+    for (let i = 0; i < 600; i++) {
+      bloatLines.push(JSON.stringify({
+        id: `evt_bloat_${i}`,
+        event: 'widget_added',
+        timestamp: '2026-01-01',
+        widget: { id: `bloat-${i}`, type: 'sticky-note', position: { x: 0, y: 0 }, props: { text: padding } },
+      }))
+    }
+    fs.appendFileSync(filePath, bloatLines.join('\n') + '\n')
+    const sizeBefore = fs.statSync(filePath).size
+    expect(sizeBefore).toBeGreaterThan(2 * 1024 * 1024)
+
+    // Trigger appendEvent — this should detect the runaway size and kick
+    // off a compaction.
+    await invoke('/widget', 'POST', {
+      name: 'big-canvas',
+      type: 'sticky-note',
+      props: { text: 'trigger' },
+      position: { x: 0, y: 0 },
+    })
+    // Compaction runs on setImmediate; flush it.
+    await flushSetImmediate()
+    await flushSetImmediate()
+
+    const sizeAfter = fs.statSync(filePath).size
+    expect(sizeAfter).toBeLessThan(sizeBefore)
+
+    // After compaction, file should be a single canvas_created event
+    // containing all the materialized widgets.
+    const lines = fs.readFileSync(filePath, 'utf-8').trim().split('\n')
+    expect(lines.length).toBe(1)
+    const baseline = JSON.parse(lines[0])
+    expect(baseline.event).toBe('canvas_created')
+    // 600 bloat widgets + 1 from the triggering append = 601.
+    expect(baseline.widgets.length).toBe(601)
+    // Sanity: state still reads cleanly via the normal /read endpoint.
+    await invoke('/read?name=big-canvas', 'GET', {})
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body.widgets.length).toBe(601)
+  })
+})

package/src/core/canvas/undoRedo.js

@@ -0,0 +1,174 @@
+/**
+ * Canvas undo/redo: build inverse forward events.
+ *
+ * Pure module — given a target canvas event (with inverse payload `prev*`
+ * fields or full `widget`/`connector` objects on removes), returns the
+ * inverse event that, when appended to the JSONL and materialized, restores
+ * the state to what it was before the target event was applied.
+ *
+ * The inverse events are real, valid forward events (widget_added,
+ * widget_removed, widget_updated, etc.) — the materializer folds them with
+ * no special handling. We tag them with `meta.kind = 'undo' | 'redo'` and
+ * `meta.of = <targetEventId>` purely for human readability and DX.
+ */
+
+/**
+ * Compute the inverse forward event for a given canvas event.
+ *
+ * @param {object} targetEvent — the event being undone/redone (must have id)
+ * @param {'undo'|'redo'} kind — meta.kind to stamp on the returned event
+ * @returns {object|null} the inverse event (without timestamp/id — the
+ *   caller stamps those via appendEvent), or null if the event is not
+ *   undoable (legacy events without inverse payloads, widgets_replaced,
+ *   connectors_replaced, canvas_created, etc.).
+ */
+export function buildInverseEvent(targetEvent, kind) {
+  if (!targetEvent || typeof targetEvent !== 'object') return null
+  if (!targetEvent.id) return null
+
+  const meta = { kind, of: targetEvent.id }
+
+  switch (targetEvent.event) {
+    case 'widget_added': {
+      const widgetId = targetEvent.widget?.id
+      if (!widgetId) return null
+      // Inverse of add is remove. Carry the full widget so the inverse
+      // event itself is undoable (redo-of-undo brings it back).
+      return {
+        event: 'widget_removed',
+        widgetId,
+        widget: targetEvent.widget,
+        meta,
+      }
+    }
+
+    case 'widget_removed': {
+      // Inverse of remove is add. Requires the full widget payload.
+      const widget = targetEvent.widget
+      if (!widget || !widget.id) return null
+      return {
+        event: 'widget_added',
+        widget,
+        meta,
+      }
+    }
+
+    case 'widget_updated': {
+      if (!targetEvent.widgetId || !targetEvent.prevProps) return null
+      return {
+        event: 'widget_updated',
+        widgetId: targetEvent.widgetId,
+        props: targetEvent.prevProps,
+        // The inverse of the inverse is the original — capture so redo works.
+        prevProps: targetEvent.props,
+        meta,
+      }
+    }
+
+    case 'widget_moved': {
+      if (!targetEvent.widgetId || !targetEvent.prevPosition) return null
+      return {
+        event: 'widget_moved',
+        widgetId: targetEvent.widgetId,
+        position: targetEvent.prevPosition,
+        prevPosition: targetEvent.position,
+        meta,
+      }
+    }
+
+    case 'connector_added': {
+      const connectorId = targetEvent.connector?.id
+      if (!connectorId) return null
+      return {
+        event: 'connector_removed',
+        connectorId,
+        connector: targetEvent.connector,
+        meta,
+      }
+    }
+
+    case 'connector_removed': {
+      const connector = targetEvent.connector
+      if (!connector || !connector.id) return null
+      return {
+        event: 'connector_added',
+        connector,
+        meta,
+      }
+    }
+
+    case 'connector_updated': {
+      if (!targetEvent.connectorId || !targetEvent.prevUpdates) return null
+      return {
+        event: 'connector_updated',
+        connectorId: targetEvent.connectorId,
+        updates: targetEvent.prevUpdates,
+        prevUpdates: targetEvent.updates,
+        meta,
+      }
+    }
+
+    case 'connector_waypoints_set': {
+      if (!targetEvent.connectorId) return null
+      const prev = targetEvent.prevWaypoints
+      // prevWaypoints null means there were no manual waypoints before —
+      // inverse is `cleared` (which itself carries the current waypoints
+      // as prevWaypoints so redo can re-set them).
+      if (prev === null) {
+        return {
+          event: 'connector_waypoints_cleared',
+          connectorId: targetEvent.connectorId,
+          prevWaypoints: targetEvent.waypoints,
+          meta,
+        }
+      }
+      if (!Array.isArray(prev)) return null
+      return {
+        event: 'connector_waypoints_set',
+        connectorId: targetEvent.connectorId,
+        waypoints: prev,
+        prevWaypoints: targetEvent.waypoints,
+        meta,
+      }
+    }
+
+    case 'connector_waypoints_cleared': {
+      if (!targetEvent.connectorId) return null
+      // Clearing had no prior manual routing: there's nothing to restore.
+      const prev = targetEvent.prevWaypoints
+      if (!Array.isArray(prev)) return null
+      return {
+        event: 'connector_waypoints_set',
+        connectorId: targetEvent.connectorId,
+        waypoints: prev,
+        prevWaypoints: null,
+        meta,
+      }
+    }
+
+    case 'source_updated': {
+      if (!Array.isArray(targetEvent.prevSources)) return null
+      return {
+        event: 'source_updated',
+        sources: targetEvent.prevSources,
+        prevSources: targetEvent.sources,
+        meta,
+      }
+    }
+
+    case 'settings_updated': {
+      if (!targetEvent.prevSettings || typeof targetEvent.prevSettings !== 'object') return null
+      return {
+        event: 'settings_updated',
+        settings: targetEvent.prevSettings,
+        prevSettings: targetEvent.settings,
+        meta,
+      }
+    }
+
+    // widgets_replaced, connectors_replaced, canvas_created are compaction
+    // / baseline events and intentionally not undoable.
+    default:
+      return null
+  }
+}

package/src/core/canvas/undoRedo.test.js

@@ -0,0 +1,250 @@
+import { describe, it, expect } from 'vitest'
+import { buildInverseEvent } from './undoRedo.js'
+import { materialize } from './materializer.js'
+
+const widget = (overrides = {}) => ({
+  id: 'sticky-1',
+  type: 'sticky-note',
+  position: { x: 10, y: 20 },
+  props: { text: 'hello' },
+  ...overrides,
+})
+
+describe('buildInverseEvent', () => {
+  it('returns null for events without an id', () => {
+    expect(buildInverseEvent({ event: 'widget_added', widget: widget() }, 'undo')).toBeNull()
+  })
+
+  it('returns null for non-undoable event types', () => {
+    expect(buildInverseEvent({ id: 'x', event: 'widgets_replaced', widgets: [] }, 'undo')).toBeNull()
+    expect(buildInverseEvent({ id: 'x', event: 'connectors_replaced', connectors: [] }, 'undo')).toBeNull()
+    expect(buildInverseEvent({ id: 'x', event: 'canvas_created', widgets: [] }, 'undo')).toBeNull()
+  })
+
+  it('inverts widget_added into widget_removed carrying the widget', () => {
+    const target = { id: 'evt_1', event: 'widget_added', widget: widget() }
+    const inv = buildInverseEvent(target, 'undo')
+    expect(inv).toEqual({
+      event: 'widget_removed',
+      widgetId: 'sticky-1',
+      widget: widget(),
+      meta: { kind: 'undo', of: 'evt_1' },
+    })
+  })
+
+  it('inverts widget_removed into widget_added when the widget payload is present', () => {
+    const target = { id: 'evt_2', event: 'widget_removed', widgetId: 'sticky-1', widget: widget() }
+    const inv = buildInverseEvent(target, 'undo')
+    expect(inv).toEqual({
+      event: 'widget_added',
+      widget: widget(),
+      meta: { kind: 'undo', of: 'evt_2' },
+    })
+  })
+
+  it('returns null for legacy widget_removed events that lack the full widget payload', () => {
+    const target = { id: 'evt_old', event: 'widget_removed', widgetId: 'sticky-1' }
+    expect(buildInverseEvent(target, 'undo')).toBeNull()
+  })
+
+  it('inverts widget_updated using prevProps and mirrors current props for redo', () => {
+    const target = {
+      id: 'evt_3',
+      event: 'widget_updated',
+      widgetId: 'sticky-1',
+      props: { text: 'new', color: 'red' },
+      prevProps: { text: 'old', color: undefined },
+    }
+    const inv = buildInverseEvent(target, 'undo')
+    expect(inv).toEqual({
+      event: 'widget_updated',
+      widgetId: 'sticky-1',
+      props: { text: 'old', color: undefined },
+      prevProps: { text: 'new', color: 'red' },
+      meta: { kind: 'undo', of: 'evt_3' },
+    })
+  })
+
+  it('inverts widget_moved using prevPosition', () => {
+    const target = {
+      id: 'evt_4',
+      event: 'widget_moved',
+      widgetId: 'sticky-1',
+      position: { x: 200, y: 200 },
+      prevPosition: { x: 10, y: 20 },
+    }
+    const inv = buildInverseEvent(target, 'undo')
+    expect(inv).toEqual({
+      event: 'widget_moved',
+      widgetId: 'sticky-1',
+      position: { x: 10, y: 20 },
+      prevPosition: { x: 200, y: 200 },
+      meta: { kind: 'undo', of: 'evt_4' },
+    })
+  })
+
+  it('inverts connector_added into connector_removed', () => {
+    const connector = {
+      id: 'connector-1',
+      type: 'connector',
+      connectorType: 'default',
+      start: { widgetId: 'sticky-1', anchor: 'right' },
+      end: { widgetId: 'sticky-2', anchor: 'left' },
+      meta: {},
+    }
+    const inv = buildInverseEvent({ id: 'evt_5', event: 'connector_added', connector }, 'undo')
+    expect(inv).toEqual({
+      event: 'connector_removed',
+      connectorId: 'connector-1',
+      connector,
+      meta: { kind: 'undo', of: 'evt_5' },
+    })
+  })
+
+  it('inverts connector_removed into connector_added', () => {
+    const connector = {
+      id: 'connector-1',
+      type: 'connector',
+      connectorType: 'default',
+      start: { widgetId: 'sticky-1', anchor: 'right' },
+      end: { widgetId: 'sticky-2', anchor: 'left' },
+      meta: {},
+    }
+    const inv = buildInverseEvent({ id: 'evt_6', event: 'connector_removed', connectorId: 'connector-1', connector }, 'undo')
+    expect(inv).toEqual({
+      event: 'connector_added',
+      connector,
+      meta: { kind: 'undo', of: 'evt_6' },
+    })
+  })
+
+  it('inverts connector_waypoints_set into connector_waypoints_cleared when there were no prior waypoints', () => {
+    const target = {
+      id: 'evt_7',
+      event: 'connector_waypoints_set',
+      connectorId: 'connector-1',
+      waypoints: [{ dx: 10, dy: 10 }],
+      prevWaypoints: null,
+    }
+    const inv = buildInverseEvent(target, 'undo')
+    expect(inv).toEqual({
+      event: 'connector_waypoints_cleared',
+      connectorId: 'connector-1',
+      prevWaypoints: [{ dx: 10, dy: 10 }],
+      meta: { kind: 'undo', of: 'evt_7' },
+    })
+  })
+
+  it('inverts source_updated using prevSources', () => {
+    const target = {
+      id: 'evt_8',
+      event: 'source_updated',
+      sources: [{ export: 'B', position: { x: 0, y: 0 } }],
+      prevSources: [{ export: 'A', position: { x: 1, y: 1 } }],
+    }
+    const inv = buildInverseEvent(target, 'undo')
+    expect(inv).toEqual({
+      event: 'source_updated',
+      sources: [{ export: 'A', position: { x: 1, y: 1 } }],
+      prevSources: [{ export: 'B', position: { x: 0, y: 0 } }],
+      meta: { kind: 'undo', of: 'evt_8' },
+    })
+  })
+
+  it('tags redo emissions with meta.kind="redo"', () => {
+    const target = { id: 'evt_9', event: 'widget_added', widget: widget() }
+    const inv = buildInverseEvent(target, 'redo')
+    expect(inv?.meta).toEqual({ kind: 'redo', of: 'evt_9' })
+  })
+})
+
+describe('materialize folds undo events like normal forward events', () => {
+  it('a widget_removed undo emission as widget_added re-introduces the widget', () => {
+    const w = widget()
+    const events = [
+      { event: 'canvas_created', timestamp: '1', widgets: [] },
+      { id: 'evt_add', event: 'widget_added', timestamp: '2', widget: w },
+      { id: 'evt_del', event: 'widget_removed', timestamp: '3', widgetId: w.id, widget: w },
+      {
+        id: 'evt_undo',
+        event: 'widget_added',
+        timestamp: '4',
+        widget: w,
+        meta: { kind: 'undo', of: 'evt_del' },
+      },
+    ]
+    const state = materialize(events)
+    expect(state.widgets).toHaveLength(1)
+    expect(state.widgets[0].id).toBe(w.id)
+  })
+
+  it('back-compat: legacy widget_removed event with only widgetId still removes', () => {
+    const w = widget()
+    const events = [
+      { event: 'canvas_created', timestamp: '1', widgets: [w] },
+      { event: 'widget_removed', timestamp: '2', widgetId: w.id },
+    ]
+    const state = materialize(events)
+    expect(state.widgets).toEqual([])
+  })
+
+  it('back-compat: legacy connector_removed event with only connectorId still removes', () => {
+    const connector = {
+      id: 'connector-1',
+      type: 'connector',
+      connectorType: 'default',
+      start: { widgetId: 'a', anchor: 'right' },
+      end: { widgetId: 'b', anchor: 'left' },
+    }
+    const events = [
+      { event: 'canvas_created', timestamp: '1', widgets: [], connectors: [connector] },
+      { event: 'connector_removed', timestamp: '2', connectorId: connector.id },
+    ]
+    const state = materialize(events)
+    expect(state.connectors).toEqual([])
+  })
+})
+
+describe('end-to-end: cq-enablement bug scenario', () => {
+  it('deleting 5 widgets then undoing once only restores the most recent delete', () => {
+    // Reproduces the rollback bug. In the old model an undo emitted a
+    // widgets_replaced event that resurrected ALL deleted widgets. In the
+    // new model the undo targets the most recent widget_removed event and
+    // re-adds only that widget.
+    const widgets = [
+      widget({ id: 'a' }),
+      widget({ id: 'b' }),
+      widget({ id: 'c' }),
+      widget({ id: 'd' }),
+      widget({ id: 'e' }),
+    ]
+    const removeEvents = widgets.map((w, i) => ({
+      id: `evt_del_${i}`,
+      event: 'widget_removed',
+      timestamp: `${10 + i}`,
+      widgetId: w.id,
+      widget: w,
+    }))
+
+    const events = [
+      { event: 'canvas_created', timestamp: '1', widgets },
+      ...removeEvents,
+    ]
+
+    // Sanity: after all 5 deletes, the canvas is empty.
+    expect(materialize(events).widgets).toEqual([])
+
+    // Undo the LAST delete only (evt_del_4).
+    const inverse = buildInverseEvent(removeEvents[4], 'undo')
+    expect(inverse?.event).toBe('widget_added')
+    expect(inverse?.widget?.id).toBe('e')
+
+    const undoneEvents = [...events, { ...inverse, id: 'evt_undo_1', timestamp: '20' }]
+    const undoneState = materialize(undoneEvents)
+
+    // Only widget 'e' is restored — a, b, c, d remain deleted.
+    expect(undoneState.widgets).toHaveLength(1)
+    expect(undoneState.widgets[0].id).toBe('e')
+  })
+})
+

package/src/core/cli/canvasRedo.js

@@ -0,0 +1,44 @@
+/**
+ * storyboard canvas redo — re-apply a previously-undone event.
+ *
+ * Usage:
+ *   storyboard canvas redo --canvas my-canvas --event evt_xxx
+ *
+ * The --event is the id of the *undo event* (the one with meta.kind = 'undo')
+ * that you want to cancel — the server emits the inverse of that, restoring
+ * the original change.
+ *
+ * Flags:
+ *   -c, --canvas             Canvas name (required)
+ *   -e, --event              Event ID (the undo event) to redo (required)
+ *   --json                   Output as JSON
+ */
+
+import { post, parseSimpleArgs, jsonOut, die } from './cliHelpers.js'
+
+const args = process.argv.slice(4) // skip: node, sb, canvas, redo
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+  canvas redo flags:
+
+    -c, --canvas             Canvas name (required)
+    -e, --event              Event ID (the undo event) to redo (required)
+    --json                   Output as JSON
+`)
+  process.exit(0)
+}
+
+const { flags } = parseSimpleArgs(args)
+const canvas = flags.canvas || flags.c
+const eventId = flags.event || flags.e
+
+if (!canvas) die('--canvas is required')
+if (!eventId) die('--event is required')
+
+try {
+  const result = await post('/_storyboard/canvas/redo', { name: canvas, eventId })
+  if (flags.json) { jsonOut(result) } else {
+    console.log(`Redid event ${eventId} → appended ${result.eventId} (${result.inverseEvent?.event})`)
+  }
+} catch (err) { die(err.message) }