@dfosco/storyboard-core 4.1.0 → 4.2.0-alpha.10

package/commandpalette.config.json

@@ -12,6 +12,12 @@
         { "id": "hide-toolbars", "label": "Hide Toolbars" }
       ]
     },
+    { "id": "sep0", "items": [] },
+    {
+      "id": "starred",
+      "title": "Starred",
+      "source": "starred"
+    },    
     { "id": "sep1", "items": [] },
     {
       "id": "tools2",
@@ -31,6 +37,12 @@
       "title": "Create new",
       "source": "create"
     },
+    { "id": "sep3b", "items": [] },
+    {
+      "id": "create-widget",
+      "title": "Add widget to canvas",
+      "source": "create-widget"
+    },
     { "id": "sep3", "items": [] },
     {
       "id": "prototypes",
@@ -46,7 +58,7 @@
     { "id": "sep5", "items": [] },
     {
       "id": "stories",
-      "title": "Stories",
+      "title": "Components",
       "source": "stories"
     },
     { "id": "sep6", "items": [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.1.0",
+  "version": "4.2.0-alpha.10",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -66,7 +66,8 @@
     "highlight.js": "^11.11.1",
     "html-to-image": "^1.11.13",
     "iconoir": "^7.11.0",
-    "jsonc-parser": "^3.3.1"
+    "jsonc-parser": "^3.3.1",
+    "ws": "^8.0.0"
   },
   "devDependencies": {
     "@lucide/svelte": "^1.7.0",
@@ -83,5 +84,8 @@
     "tailwindcss": "^4.2.2",
     "tw-animate-css": "^1.4.0",
     "vite": "^6.0.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.0.0"
   }
-}
+}

package/scaffold/agents/terminal-agent.agent.md

@@ -0,0 +1,144 @@
+---
+name: terminal-agent
+description: "Canvas-aware terminal agent that reads connected widget context and signals completion via the storyboard API."
+tools:
+  - read
+  - edit
+  - shell
+  - search
+---
+
+# Terminal Agent Context
+
+Before processing ANY user prompt, read the terminal config file for this session.
+
+## Step 1: Read terminal config
+
+Your widget ID is available via `$STORYBOARD_WIDGET_ID`. Use it to read your config directly:
+```bash
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json
+```
+
+If the env var is empty, source it from the terminal env file first:
+```bash
+# Find the env file for this tmux session
+ENV_FILE=$(ls -t .storyboard/terminals/*.env 2>/dev/null | head -1)
+if [ -n "$ENV_FILE" ]; then source "$ENV_FILE"; fi
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json
+```
+
+As a last resort, list all configs and pick the most recent non-deleted one with `connectedWidgets`:
+```bash
+cat .storyboard/terminals/*.json
+```
+
+The config file contains everything you need — no additional API calls required:
+
+```json
+{
+  "widgetId": "terminal-abc123",
+  "canvasId": "storyboarding/my-canvas",
+  "branch": "4.2.0--terminal-agents",
+  "worktree": "4.2.0--terminal-agents",
+  "devDomain": "storyboard-core",
+  "serverUrl": "http://localhost:1269",
+  "workingDirectory": "/path/to/worktree",
+  "connectedWidgets": [
+    {
+      "id": "sticky-def456",
+      "type": "sticky-note",
+      "props": { "text": "Build a login form", "color": "yellow" }
+    },
+    {
+      "id": "markdown-ghi789",
+      "type": "markdown",
+      "props": { "content": "# Requirements\n- Email + password\n- OAuth support" }
+    }
+  ]
+}
+```
+
+## Step 2: Use connected widget context
+
+The `connectedWidgets` array contains the FULL props of every widget connected to this terminal. This is your highest priority context:
+
+- **sticky-note**: `props.text` — instructions, notes, or requirements
+- **markdown**: `props.content` — documentation, specs, or prose
+- **image**: `props.src` — image filename at `assets/canvas/images/{props.src}`
+- **story**: `props.storyId` + `props.exportName` — component to work with
+- **link-preview**: `props.url` — external reference
+- **prototype**: `props.src` — prototype path
+
+Interpret the user's prompt in light of these connected widgets.
+
+## Step 3: Prefer CLI commands for canvas operations
+
+**Always prefer `npx storyboard` CLI commands over HTTP API calls.** CLI commands run directly in the worktree and resolve the dev server automatically — no port numbers or URLs needed.
+
+### Reading canvas state
+```bash
+npx storyboard canvas read <canvas-name> --json
+npx storyboard canvas read <canvas-name> --id <widget-id> --json
+```
+
+### Updating a widget
+```bash
+# Update text on a sticky note
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --text "New text"
+
+# Update markdown content
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --content "# New heading"
+
+# Update arbitrary props
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --props '{"key":"value"}'
+
+# Move a widget
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --x 100 --y 200
+
+# Shorthand flags: --text, --content, --src, --url, --color
+```
+
+### Adding a widget
+```bash
+npx storyboard canvas add sticky-note --canvas <canvas-name> --props '{"text":"Hello"}'
+npx storyboard canvas add markdown --canvas <canvas-name> --x 100 --y 200
+```
+
+**Why CLI over API:** The CLI resolves the correct dev server port automatically via the Caddy proxy or ports.json. You never need to know the port number. All commands work from any worktree directory.
+
+## Step 4: Signal completion
+
+When your task is complete:
+```bash
+npx storyboard agent signal --status done --message "Brief summary"
+```
+
+On failure:
+```bash
+npx storyboard agent signal --status error --message "What went wrong"
+```
+
+**IMPORTANT:**
+- NEVER write directly to `.canvas.jsonl` files — use the canvas CLI or server API
+- **Prefer CLI commands** (`npx storyboard canvas ...`) over direct HTTP calls — they resolve ports automatically
+- Only fall back to HTTP API (`{serverUrl}/_storyboard/canvas/`) if the CLI doesn't support the operation
+- Environment variables `$STORYBOARD_WIDGET_ID`, `$STORYBOARD_CANVAS_ID`, `$STORYBOARD_BRANCH`, `$STORYBOARD_SERVER_URL` are also available in the shell
+
+## HTTP API Reference (fallback only)
+
+If the CLI fails, use these endpoints. The `serverUrl` is in your terminal config or `$STORYBOARD_SERVER_URL`.
+
+### Safe: Update a single widget (PATCH)
+```bash
+curl -s -X PATCH "${STORYBOARD_SERVER_URL}/_storyboard/canvas/widget" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"<canvasId>","widgetId":"<widgetId>","props":{"text":"new value"}}'
+```
+
+### Safe: Read canvas state (GET)
+```bash
+curl -s "${STORYBOARD_SERVER_URL}/_storyboard/canvas/<canvasId>"
+```
+
+### ⚠️ NEVER use `PUT /_storyboard/canvas/update` with a `widgets` array
+That endpoint **replaces ALL widgets** in the canvas. Sending one widget = deleting everything else.

package/src/canvas/collision.js

@@ -5,17 +5,47 @@
  * existing widgets and adjusts the position until no collisions remain.
  */
 
+import widgetsConfig from '../../widgets.config.json' with { type: 'json' }
+
+const FALLBACK_SIZE = { width: 270, height: 170 }
+
 /**
- * Default widget sizes by type (from widgets.config.json).
+ * Hardcoded fallbacks for widget types that don't specify defaults in config.
  */
-export const DEFAULT_SIZES = {
-  'sticky-note': { width: 270, height: 170 },
+const HARDCODED_DEFAULTS = {
   'markdown': { width: 530, height: 240 },
-  'prototype': { width: 800, height: 600 },
-  'figma-embed': { width: 800, height: 450 },
   'image': { width: 400, height: 300 },
-  'link-preview': { width: 400, height: 200 },
+  'link-preview': { width: 320, height: 200 },
   'component': { width: 300, height: 200 },
+  'story': { width: 780, height: 420 },
+}
+
+/**
+ * Default widget sizes derived from widgets.config.json prop defaults,
+ * with hardcoded fallbacks for types that don't specify both width+height.
+ */
+export const DEFAULT_SIZES = buildDefaultSizes()
+
+function buildDefaultSizes() {
+  const sizes = {}
+  const widgets = widgetsConfig.widgets || {}
+  for (const [type, config] of Object.entries(widgets)) {
+    const props = config.props || {}
+    const hardcoded = HARDCODED_DEFAULTS[type]
+    const w = props.width?.default ?? hardcoded?.width ?? FALLBACK_SIZE.width
+    const h = props.height?.default ?? hardcoded?.height ?? FALLBACK_SIZE.height
+    sizes[type] = { width: w, height: h }
+  }
+  return sizes
+}
+
+/**
+ * Get the default size for a widget type from widgets.config.json.
+ * @param {string} type - Widget type
+ * @returns {{ width: number, height: number }}
+ */
+export function getDefaultSize(type) {
+  return DEFAULT_SIZES[type] || FALLBACK_SIZE
 }
 
 /**
@@ -25,7 +55,7 @@ export const DEFAULT_SIZES = {
  */
 export function getWidgetBounds(widget) {
   const { position = { x: 0, y: 0 }, props = {}, type } = widget
-  const defaults = DEFAULT_SIZES[type] || { width: 270, height: 170 }
+  const defaults = getDefaultSize(type)
   return {
     x: position.x,
     y: position.y,
@@ -34,6 +64,42 @@ export function getWidgetBounds(widget) {
   }
 }
 
+/**
+ * Compute persistent bounds metadata for a widget.
+ * Returns { width, height, startX, startY, endX, endY }.
+ * @param {object} widget - Widget with position, props, and type
+ * @returns {{ width: number, height: number, startX: number, startY: number, endX: number, endY: number }}
+ */
+export function computeWidgetBounds(widget) {
+  const { x, y, width, height } = getWidgetBounds(widget)
+  return {
+    width,
+    height,
+    startX: x,
+    startY: y,
+    endX: x + width,
+    endY: y + height,
+  }
+}
+
+/**
+ * Stamp bounds metadata onto a widget, returning a new widget object.
+ * @param {object} widget
+ * @returns {object} Widget with `bounds` field
+ */
+export function stampBounds(widget) {
+  return { ...widget, bounds: computeWidgetBounds(widget) }
+}
+
+/**
+ * Stamp bounds on every widget in an array.
+ * @param {object[]} widgets
+ * @returns {object[]}
+ */
+export function stampBoundsAll(widgets) {
+  return widgets.map(stampBounds)
+}
+
 /**
  * Check if two rectangles overlap.
  * @param {{ x: number, y: number, width: number, height: number }} a
@@ -54,17 +120,31 @@ export function rectsOverlap(a, b) {
  * @param {{ x: number, y: number, width: number, height: number }} rect - Proposed bounds
  * @param {object[]} widgets - Existing widgets array
  * @param {string} [excludeId] - Widget ID to exclude (for move operations)
- * @returns {object|null} - The first colliding widget, or null if no collision
+ * @returns {object[]} - All colliding widgets (empty array if none)
  */
-export function findCollision(rect, widgets, excludeId = null) {
+export function findCollisions(rect, widgets, excludeId = null) {
+  const colliders = []
   for (const widget of widgets) {
     if (excludeId && widget.id === excludeId) continue
     const bounds = getWidgetBounds(widget)
     if (rectsOverlap(rect, bounds)) {
-      return widget
+      colliders.push(widget)
     }
   }
-  return null
+  return colliders
+}
+
+/**
+ * Check if a proposed position collides with any existing widget.
+ * Returns the first colliding widget (for backwards compatibility).
+ * @param {{ x: number, y: number, width: number, height: number }} rect - Proposed bounds
+ * @param {object[]} widgets - Existing widgets array
+ * @param {string} [excludeId] - Widget ID to exclude (for move operations)
+ * @returns {object|null} - The first colliding widget, or null if no collision
+ */
+export function findCollision(rect, widgets, excludeId = null) {
+  const colliders = findCollisions(rect, widgets, excludeId)
+  return colliders.length > 0 ? colliders[0] : null
 }
 
 /**
@@ -82,9 +162,10 @@ export function snapToGrid(value, gridSize) {
  *
  * Strategy:
  * 1. Try the initial position
- * 2. If collision, move right by (collider.width + gap)
- * 3. If still colliding after maxIterations, try moving down instead
- * 4. Snap final position to grid
+ * 2. If collision, find the max endX among all colliders and move past it
+ * 3. Repeat until no collisions or maxIterations exhausted
+ * 4. If horizontal resolution exhausted, fall back to moving down
+ * 5. Snap final position to grid
  *
  * @param {object} options
  * @param {number} options.x - Initial X position
@@ -113,15 +194,13 @@ export function findFreePosition({
   let currentX = x
   let currentY = y
   let adjusted = false
-  let iteration = 0
 
-  // Phase 1: Try moving right
-  while (iteration < maxIterations) {
+  // Phase 1: Try moving right past all colliders
+  for (let i = 0; i < maxIterations; i++) {
     const rect = { x: currentX, y: currentY, width, height }
-    const collider = findCollision(rect, widgets, excludeId)
+    const colliders = findCollisions(rect, widgets, excludeId)
 
-    if (!collider) {
-      // No collision — snap and return
+    if (colliders.length === 0) {
       return {
         x: snapToGrid(currentX, gridSize),
         y: snapToGrid(currentY, gridSize),
@@ -129,22 +208,25 @@ export function findFreePosition({
       }
     }
 
-    // Move right past the collider
-    const colliderBounds = getWidgetBounds(collider)
-    currentX = colliderBounds.x + colliderBounds.width + spacing
+    // Jump past the rightmost edge of all colliders
+    let maxEndX = 0
+    for (const c of colliders) {
+      const b = getWidgetBounds(c)
+      const endX = b.x + b.width
+      if (endX > maxEndX) maxEndX = endX
+    }
+    currentX = maxEndX + spacing
     adjusted = true
-    iteration++
   }
 
   // Phase 2: Reset X, try moving down
   currentX = x
-  iteration = 0
 
-  while (iteration < maxIterations) {
+  for (let i = 0; i < maxIterations; i++) {
     const rect = { x: currentX, y: currentY, width, height }
-    const collider = findCollision(rect, widgets, excludeId)
+    const colliders = findCollisions(rect, widgets, excludeId)
 
-    if (!collider) {
+    if (colliders.length === 0) {
       return {
         x: snapToGrid(currentX, gridSize),
         y: snapToGrid(currentY, gridSize),
@@ -152,11 +234,15 @@ export function findFreePosition({
       }
     }
 
-    // Move down past the collider
-    const colliderBounds = getWidgetBounds(collider)
-    currentY = colliderBounds.y + colliderBounds.height + spacing
+    // Jump past the bottommost edge of all colliders
+    let maxEndY = 0
+    for (const c of colliders) {
+      const b = getWidgetBounds(c)
+      const endY = b.y + b.height
+      if (endY > maxEndY) maxEndY = endY
+    }
+    currentY = maxEndY + spacing
     adjusted = true
-    iteration++
   }
 
   // Fallback: return the last attempted position (snapped)
@@ -190,7 +276,7 @@ export function resolvePosition({
   excludeId = null,
   gridSize = 24,
 }) {
-  const defaults = DEFAULT_SIZES[type] || { width: 270, height: 170 }
+  const defaults = getDefaultSize(type)
   const width = props.width ?? defaults.width
   const height = props.height ?? defaults.height
 

package/src/canvas/collision.test.js

@@ -1,8 +1,12 @@
 import { describe, it, expect } from 'vitest'
 import {
   getWidgetBounds,
+  computeWidgetBounds,
+  stampBounds,
+  stampBoundsAll,
   rectsOverlap,
   findCollision,
+  findCollisions,
   snapToGrid,
   findFreePosition,
   resolvePosition,
@@ -57,6 +61,24 @@ describe('getWidgetBounds', () => {
       height: 170,
     })
   })
+
+  it('resolves story widget type from DEFAULT_SIZES', () => {
+    const widget = { type: 'story', position: { x: 0, y: 0 }, props: {} }
+    expect(getWidgetBounds(widget)).toEqual({
+      x: 0, y: 0,
+      width: DEFAULT_SIZES['story'].width,
+      height: DEFAULT_SIZES['story'].height,
+    })
+  })
+
+  it('resolves codepen-embed widget type from DEFAULT_SIZES', () => {
+    const widget = { type: 'codepen-embed', position: { x: 0, y: 0 }, props: {} }
+    expect(getWidgetBounds(widget)).toEqual({
+      x: 0, y: 0,
+      width: DEFAULT_SIZES['codepen-embed'].width,
+      height: DEFAULT_SIZES['codepen-embed'].height,
+    })
+  })
 })
 
 describe('rectsOverlap', () => {
@@ -117,6 +139,32 @@ describe('findCollision', () => {
   })
 })
 
+describe('findCollisions', () => {
+  const widgets = [
+    { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 270, height: 170 } },
+    { id: 'w2', type: 'sticky-note', position: { x: 200, y: 0 }, props: { width: 270, height: 170 } },
+  ]
+
+  it('returns all colliding widgets', () => {
+    const rect = { x: 100, y: 50, width: 270, height: 170 }
+    const colliders = findCollisions(rect, widgets)
+    expect(colliders).toHaveLength(2)
+    expect(colliders.map((w) => w.id).sort()).toEqual(['w1', 'w2'])
+  })
+
+  it('returns empty array when no collision', () => {
+    const rect = { x: 0, y: 200, width: 270, height: 170 }
+    expect(findCollisions(rect, widgets)).toEqual([])
+  })
+
+  it('excludes specified widget ID', () => {
+    const rect = { x: 100, y: 50, width: 270, height: 170 }
+    const colliders = findCollisions(rect, widgets, 'w1')
+    expect(colliders).toHaveLength(1)
+    expect(colliders[0].id).toBe('w2')
+  })
+})
+
 describe('snapToGrid', () => {
   it('snaps to nearest grid line', () => {
     expect(snapToGrid(25, 24)).toBe(24)
@@ -269,3 +317,55 @@ describe('resolvePosition', () => {
     expect(result).toEqual({ x: 504, y: 504, adjusted: false })
   })
 })
+
+describe('computeWidgetBounds', () => {
+  it('computes bounds from position and size', () => {
+    const widget = { type: 'sticky-note', position: { x: 100, y: 200 }, props: { width: 270, height: 170 } }
+    expect(computeWidgetBounds(widget)).toEqual({
+      width: 270, height: 170,
+      startX: 100, startY: 200,
+      endX: 370, endY: 370,
+    })
+  })
+
+  it('uses defaults when props missing', () => {
+    const widget = { type: 'sticky-note', position: { x: 0, y: 0 }, props: {} }
+    expect(computeWidgetBounds(widget)).toEqual({
+      width: 270, height: 170,
+      startX: 0, startY: 0,
+      endX: 270, endY: 170,
+    })
+  })
+})
+
+describe('stampBounds', () => {
+  it('adds bounds field to widget', () => {
+    const widget = { id: 'w1', type: 'sticky-note', position: { x: 48, y: 24 }, props: { width: 270, height: 170 } }
+    const stamped = stampBounds(widget)
+    expect(stamped.bounds).toEqual({
+      width: 270, height: 170,
+      startX: 48, startY: 24,
+      endX: 318, endY: 194,
+    })
+    expect(stamped.id).toBe('w1')
+  })
+
+  it('does not mutate original widget', () => {
+    const widget = { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: {} }
+    stampBounds(widget)
+    expect(widget.bounds).toBeUndefined()
+  })
+})
+
+describe('stampBoundsAll', () => {
+  it('stamps bounds on all widgets', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 270, height: 170 } },
+      { id: 'w2', type: 'markdown', position: { x: 300, y: 0 }, props: { width: 530, height: 240 } },
+    ]
+    const stamped = stampBoundsAll(widgets)
+    expect(stamped).toHaveLength(2)
+    expect(stamped[0].bounds.endX).toBe(270)
+    expect(stamped[1].bounds.endX).toBe(830)
+  })
+})

package/src/canvas/materializer.js

@@ -13,6 +13,8 @@
  *   settings_updated — patch canvas-level settings
  *   source_updated   — replace the sources array
  *   widgets_replaced — replace the entire widgets array (bulk update)
+ *   connector_added  — append a connector between two widgets
+ *   connector_removed — remove a connector by id
  */
 
 /**
@@ -101,6 +103,7 @@ export function materialize(events) {
         const initial = { ...evt }
         delete initial.event
         delete initial.timestamp
+        if (!initial.connectors) initial.connectors = []
         state = initial
         break
       }
@@ -131,6 +134,12 @@ export function materialize(events) {
         state.widgets = (state.widgets || []).filter(
           (w) => w.id !== evt.widgetId,
         )
+        // Cascade: remove connectors referencing the deleted widget
+        if (state.connectors?.length) {
+          state.connectors = state.connectors.filter(
+            (c) => c.start.widgetId !== evt.widgetId && c.end.widgetId !== evt.widgetId,
+          )
+        }
         break
       }
 
@@ -150,6 +159,26 @@ export function materialize(events) {
 
       case 'widgets_replaced': {
         state.widgets = evt.widgets
+        // Orphan cleanup: remove connectors referencing deleted widgets
+        if (state.connectors?.length) {
+          const widgetIds = new Set((state.widgets || []).map((w) => w.id))
+          state.connectors = state.connectors.filter(
+            (c) => widgetIds.has(c.start.widgetId) && widgetIds.has(c.end.widgetId),
+          )
+        }
+        break
+      }
+
+      case 'connector_added': {
+        if (!state.connectors) state.connectors = []
+        state.connectors = [...state.connectors, evt.connector]
+        break
+      }
+
+      case 'connector_removed': {
+        state.connectors = (state.connectors || []).filter(
+          (c) => c.id !== evt.connectorId,
+        )
         break
       }
 
@@ -157,6 +186,24 @@ export function materialize(events) {
     }
   }
 
+  // Derive connectorIds on widgets from the connectors array
+  if (state.connectors?.length && state.widgets?.length) {
+    // Build a map: widgetId → Set of connectorIds
+    const widgetConnMap = new Map()
+    for (const conn of state.connectors) {
+      for (const endpoint of [conn.start, conn.end]) {
+        if (!widgetConnMap.has(endpoint.widgetId)) {
+          widgetConnMap.set(endpoint.widgetId, new Set())
+        }
+        widgetConnMap.get(endpoint.widgetId).add(conn.id)
+      }
+    }
+    state.widgets = state.widgets.map((w) => {
+      const ids = widgetConnMap.get(w.id)
+      return ids ? { ...w, connectorIds: [...ids] } : w
+    })
+  }
+
   return state
 }