@dfosco/storyboard-core 4.1.0 → 4.2.0-beta.0

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-beta.0",
   "type": "module",
   "license": "MIT",
   "bin": {

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
 }
 

package/src/canvas/materializer.test.js

@@ -176,6 +176,110 @@ describe('materialize', () => {
   })
 })
 
+describe('connectors', () => {
+  const baseEvents = [
+    { event: 'canvas_created', timestamp: '1', title: 'Test', widgets: [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: {} },
+      { id: 'w2', type: 'markdown', position: { x: 200, y: 0 }, props: {} },
+      { id: 'w3', type: 'sticky-note', position: { x: 400, y: 0 }, props: {} },
+    ] },
+  ]
+
+  const connector = {
+    id: 'connector-001',
+    type: 'connector',
+    connectorType: 'default',
+    start: { widgetId: 'w1', anchor: 'right' },
+    end: { widgetId: 'w2', anchor: 'left' },
+    meta: {},
+  }
+
+  it('materializes connector_added events into connectors array', () => {
+    const state = materialize([
+      ...baseEvents,
+      { event: 'connector_added', timestamp: '2', connector },
+    ])
+    expect(state.connectors).toHaveLength(1)
+    expect(state.connectors[0].id).toBe('connector-001')
+  })
+
+  it('derives connectorIds on widgets from connectors', () => {
+    const state = materialize([
+      ...baseEvents,
+      { event: 'connector_added', timestamp: '2', connector },
+    ])
+    expect(state.widgets.find((w) => w.id === 'w1').connectorIds).toEqual(['connector-001'])
+    expect(state.widgets.find((w) => w.id === 'w2').connectorIds).toEqual(['connector-001'])
+    expect(state.widgets.find((w) => w.id === 'w3').connectorIds).toBeUndefined()
+  })
+
+  it('removes connectors with connector_removed', () => {
+    const state = materialize([
+      ...baseEvents,
+      { event: 'connector_added', timestamp: '2', connector },
+      { event: 'connector_removed', timestamp: '3', connectorId: 'connector-001' },
+    ])
+    expect(state.connectors).toHaveLength(0)
+    // connectorIds should not appear on widgets when no connectors reference them
+    expect(state.widgets.find((w) => w.id === 'w1').connectorIds).toBeUndefined()
+  })
+
+  it('cascades connector removal when widget is removed', () => {
+    const state = materialize([
+      ...baseEvents,
+      { event: 'connector_added', timestamp: '2', connector },
+      { event: 'widget_removed', timestamp: '3', widgetId: 'w1' },
+    ])
+    expect(state.connectors).toHaveLength(0)
+    expect(state.widgets).toHaveLength(2)
+  })
+
+  it('cleans orphaned connectors on widgets_replaced', () => {
+    const state = materialize([
+      ...baseEvents,
+      { event: 'connector_added', timestamp: '2', connector },
+      { event: 'widgets_replaced', timestamp: '3', widgets: [
+        { id: 'w2', type: 'markdown', position: { x: 200, y: 0 }, props: {} },
+        { id: 'w3', type: 'sticky-note', position: { x: 400, y: 0 }, props: {} },
+      ] },
+    ])
+    // w1 removed by replacement, so connector referencing w1 is orphaned
+    expect(state.connectors).toHaveLength(0)
+  })
+
+  it('supports multiple connectors on the same widget', () => {
+    const conn2 = {
+      id: 'connector-002',
+      type: 'connector',
+      connectorType: 'default',
+      start: { widgetId: 'w2', anchor: 'right' },
+      end: { widgetId: 'w3', anchor: 'left' },
+      meta: {},
+    }
+    const state = materialize([
+      ...baseEvents,
+      { event: 'connector_added', timestamp: '2', connector },
+      { event: 'connector_added', timestamp: '3', connector: conn2 },
+    ])
+    expect(state.connectors).toHaveLength(2)
+    expect(state.widgets.find((w) => w.id === 'w2').connectorIds).toEqual(
+      expect.arrayContaining(['connector-001', 'connector-002']),
+    )
+    expect(state.widgets.find((w) => w.id === 'w2').connectorIds).toHaveLength(2)
+  })
+
+  it('initializes connectors array when none existed', () => {
+    const state = materialize([
+      { event: 'canvas_created', timestamp: '1', title: 'Empty', widgets: [
+        { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: {} },
+        { id: 'w2', type: 'sticky-note', position: { x: 100, y: 0 }, props: {} },
+      ] },
+      { event: 'connector_added', timestamp: '2', connector },
+    ])
+    expect(state.connectors).toHaveLength(1)
+  })
+})
+
 describe('materializeFromText', () => {
   it('parses and materializes in one step', () => {
     const text = '{"event":"canvas_created","timestamp":"2026-01-01","title":"Test","widgets":[]}\n{"event":"widget_added","timestamp":"2026-01-02","widget":{"id":"w1","type":"sticky-note","position":{"x":0,"y":0},"props":{"text":"Hello"}}}\n'