@dfosco/storyboard-core 4.0.0-beta.6 → 4.0.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.0.0-beta.6",
+  "version": "4.0.0-beta.8",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -48,7 +48,8 @@
     "./ui/viewfinder": "./src/ui/viewfinder.ts",
     "./svelte-plugin-ui/styles/base.css": "./dist/tailwind.css",
     "./styles/tailwind.css": "./dist/tailwind.css",
-    "./worktree/port": "./src/worktree/port.js"
+    "./worktree/port": "./src/worktree/port.js",
+    "./canvas/collision": "./src/canvas/collision.js"
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",

package/src/canvas/collision.js

@@ -0,0 +1,206 @@
+/**
+ * Canvas Collision Detection — Find collision-free positions for widgets.
+ *
+ * When placing or moving widgets, this module checks for overlaps with
+ * existing widgets and adjusts the position until no collisions remain.
+ */
+
+/**
+ * Default widget sizes by type (from widgets.config.json).
+ */
+export const DEFAULT_SIZES = {
+  'sticky-note': { width: 270, height: 170 },
+  '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 },
+  'component': { width: 300, height: 200 },
+}
+
+/**
+ * Get the bounding box of a widget.
+ * @param {object} widget - Widget with position and props
+ * @returns {{ x: number, y: number, width: number, height: number }}
+ */
+export function getWidgetBounds(widget) {
+  const { position = { x: 0, y: 0 }, props = {}, type } = widget
+  const defaults = DEFAULT_SIZES[type] || { width: 270, height: 170 }
+  return {
+    x: position.x,
+    y: position.y,
+    width: props.width ?? defaults.width,
+    height: props.height ?? defaults.height,
+  }
+}
+
+/**
+ * Check if two rectangles overlap.
+ * @param {{ x: number, y: number, width: number, height: number }} a
+ * @param {{ x: number, y: number, width: number, height: number }} b
+ * @returns {boolean}
+ */
+export function rectsOverlap(a, b) {
+  return !(
+    a.x + a.width <= b.x ||  // a is to the left of b
+    b.x + b.width <= a.x ||  // b is to the left of a
+    a.y + a.height <= b.y || // a is above b
+    b.y + b.height <= a.y    // b is above a
+  )
+}
+
+/**
+ * Check if a proposed position collides with any existing widget.
+ * @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) {
+  for (const widget of widgets) {
+    if (excludeId && widget.id === excludeId) continue
+    const bounds = getWidgetBounds(widget)
+    if (rectsOverlap(rect, bounds)) {
+      return widget
+    }
+  }
+  return null
+}
+
+/**
+ * Snap a value to grid.
+ * @param {number} value
+ * @param {number} gridSize
+ * @returns {number}
+ */
+export function snapToGrid(value, gridSize) {
+  return Math.round(value / gridSize) * gridSize
+}
+
+/**
+ * Find a collision-free position for a widget.
+ *
+ * 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
+ *
+ * @param {object} options
+ * @param {number} options.x - Initial X position
+ * @param {number} options.y - Initial Y position
+ * @param {number} options.width - Widget width
+ * @param {number} options.height - Widget height
+ * @param {object[]} options.widgets - Existing widgets array
+ * @param {string} [options.excludeId] - Widget ID to exclude (for move operations)
+ * @param {number} [options.gridSize=24] - Grid size for snapping
+ * @param {number} [options.gap] - Gap between widgets (defaults to gridSize)
+ * @param {number} [options.maxIterations=50] - Max collision resolution attempts
+ * @returns {{ x: number, y: number, adjusted: boolean }}
+ */
+export function findFreePosition({
+  x,
+  y,
+  width,
+  height,
+  widgets,
+  excludeId = null,
+  gridSize = 24,
+  gap = null,
+  maxIterations = 50,
+}) {
+  const spacing = gap ?? gridSize
+  let currentX = x
+  let currentY = y
+  let adjusted = false
+  let iteration = 0
+
+  // Phase 1: Try moving right
+  while (iteration < maxIterations) {
+    const rect = { x: currentX, y: currentY, width, height }
+    const collider = findCollision(rect, widgets, excludeId)
+
+    if (!collider) {
+      // No collision — snap and return
+      return {
+        x: snapToGrid(currentX, gridSize),
+        y: snapToGrid(currentY, gridSize),
+        adjusted,
+      }
+    }
+
+    // Move right past the collider
+    const colliderBounds = getWidgetBounds(collider)
+    currentX = colliderBounds.x + colliderBounds.width + spacing
+    adjusted = true
+    iteration++
+  }
+
+  // Phase 2: Reset X, try moving down
+  currentX = x
+  iteration = 0
+
+  while (iteration < maxIterations) {
+    const rect = { x: currentX, y: currentY, width, height }
+    const collider = findCollision(rect, widgets, excludeId)
+
+    if (!collider) {
+      return {
+        x: snapToGrid(currentX, gridSize),
+        y: snapToGrid(currentY, gridSize),
+        adjusted,
+      }
+    }
+
+    // Move down past the collider
+    const colliderBounds = getWidgetBounds(collider)
+    currentY = colliderBounds.y + colliderBounds.height + spacing
+    adjusted = true
+    iteration++
+  }
+
+  // Fallback: return the last attempted position (snapped)
+  return {
+    x: snapToGrid(currentX, gridSize),
+    y: snapToGrid(currentY, gridSize),
+    adjusted,
+  }
+}
+
+/**
+ * Resolve collision for a widget being placed or moved.
+ * Convenience wrapper that extracts size from widget type/props.
+ *
+ * @param {object} options
+ * @param {number} options.x - Target X position
+ * @param {number} options.y - Target Y position
+ * @param {string} options.type - Widget type
+ * @param {object} [options.props={}] - Widget props (may contain width/height)
+ * @param {object[]} options.widgets - Existing widgets array
+ * @param {string} [options.excludeId] - Widget ID to exclude
+ * @param {number} [options.gridSize=24] - Grid size
+ * @returns {{ x: number, y: number, adjusted: boolean }}
+ */
+export function resolvePosition({
+  x,
+  y,
+  type,
+  props = {},
+  widgets,
+  excludeId = null,
+  gridSize = 24,
+}) {
+  const defaults = DEFAULT_SIZES[type] || { width: 270, height: 170 }
+  const width = props.width ?? defaults.width
+  const height = props.height ?? defaults.height
+
+  return findFreePosition({
+    x,
+    y,
+    width,
+    height,
+    widgets,
+    excludeId,
+    gridSize,
+  })
+}

package/src/canvas/collision.test.js

@@ -0,0 +1,271 @@
+import { describe, it, expect } from 'vitest'
+import {
+  getWidgetBounds,
+  rectsOverlap,
+  findCollision,
+  snapToGrid,
+  findFreePosition,
+  resolvePosition,
+  DEFAULT_SIZES,
+} from './collision.js'
+
+describe('getWidgetBounds', () => {
+  it('uses position and props dimensions', () => {
+    const widget = {
+      type: 'sticky-note',
+      position: { x: 100, y: 200 },
+      props: { width: 300, height: 180 },
+    }
+    expect(getWidgetBounds(widget)).toEqual({
+      x: 100,
+      y: 200,
+      width: 300,
+      height: 180,
+    })
+  })
+
+  it('falls back to default sizes when props missing', () => {
+    const widget = {
+      type: 'sticky-note',
+      position: { x: 50, y: 50 },
+      props: {},
+    }
+    expect(getWidgetBounds(widget)).toEqual({
+      x: 50,
+      y: 50,
+      width: DEFAULT_SIZES['sticky-note'].width,
+      height: DEFAULT_SIZES['sticky-note'].height,
+    })
+  })
+
+  it('handles missing position and props', () => {
+    const widget = { type: 'markdown' }
+    expect(getWidgetBounds(widget)).toEqual({
+      x: 0,
+      y: 0,
+      width: DEFAULT_SIZES['markdown'].width,
+      height: DEFAULT_SIZES['markdown'].height,
+    })
+  })
+
+  it('uses generic fallback for unknown widget types', () => {
+    const widget = { type: 'unknown-type', position: { x: 10, y: 20 } }
+    expect(getWidgetBounds(widget)).toEqual({
+      x: 10,
+      y: 20,
+      width: 270,
+      height: 170,
+    })
+  })
+})
+
+describe('rectsOverlap', () => {
+  it('returns true for overlapping rects', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 50, y: 50, width: 100, height: 100 }
+    expect(rectsOverlap(a, b)).toBe(true)
+  })
+
+  it('returns false for non-overlapping rects (side by side)', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 100, y: 0, width: 100, height: 100 }
+    expect(rectsOverlap(a, b)).toBe(false)
+  })
+
+  it('returns false for non-overlapping rects (stacked)', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 0, y: 100, width: 100, height: 100 }
+    expect(rectsOverlap(a, b)).toBe(false)
+  })
+
+  it('returns true when one rect contains another', () => {
+    const a = { x: 0, y: 0, width: 200, height: 200 }
+    const b = { x: 50, y: 50, width: 50, height: 50 }
+    expect(rectsOverlap(a, b)).toBe(true)
+  })
+
+  it('returns true for rects that share an edge partially', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 50, y: 0, width: 100, height: 100 }
+    expect(rectsOverlap(a, b)).toBe(true)
+  })
+})
+
+describe('findCollision', () => {
+  const widgets = [
+    { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 270, height: 170 } },
+    { id: 'w2', type: 'sticky-note', position: { x: 300, y: 0 }, props: { width: 270, height: 170 } },
+  ]
+
+  it('returns colliding widget', () => {
+    const rect = { x: 100, y: 50, width: 270, height: 170 }
+    const collision = findCollision(rect, widgets)
+    expect(collision?.id).toBe('w1')
+  })
+
+  it('returns null when no collision', () => {
+    const rect = { x: 0, y: 200, width: 270, height: 170 }
+    const collision = findCollision(rect, widgets)
+    expect(collision).toBeNull()
+  })
+
+  it('excludes specified widget ID', () => {
+    // This rect only overlaps w1, not w2 — so excluding w1 means no collision
+    const rect = { x: 50, y: 50, width: 200, height: 100 }
+    const collision = findCollision(rect, widgets, 'w1')
+    expect(collision).toBeNull()
+  })
+})
+
+describe('snapToGrid', () => {
+  it('snaps to nearest grid line', () => {
+    expect(snapToGrid(25, 24)).toBe(24)
+    expect(snapToGrid(36, 24)).toBe(48)
+    expect(snapToGrid(12, 24)).toBe(24) // 12 rounds to 24 (0.5 → 1)
+    expect(snapToGrid(11, 24)).toBe(0)  // 11 rounds to 0
+    expect(snapToGrid(48, 24)).toBe(48)
+  })
+
+  it('works with different grid sizes', () => {
+    expect(snapToGrid(15, 10)).toBe(20)
+    expect(snapToGrid(14, 10)).toBe(10)
+  })
+})
+
+describe('findFreePosition', () => {
+  it('returns original position when no collision', () => {
+    const widgets = []
+    const result = findFreePosition({
+      x: 100,
+      y: 100,
+      width: 270,
+      height: 170,
+      widgets,
+      gridSize: 24,
+    })
+    expect(result).toEqual({ x: 96, y: 96, adjusted: false })
+  })
+
+  it('moves right to avoid collision', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 270, height: 170 } },
+    ]
+    const result = findFreePosition({
+      x: 0,
+      y: 0,
+      width: 270,
+      height: 170,
+      widgets,
+      gridSize: 24,
+    })
+    // Should move right: 270 (width) + 24 (gap) = 294, snapped to 288 or 312
+    expect(result.x).toBeGreaterThanOrEqual(288)
+    expect(result.y).toBe(0)
+    expect(result.adjusted).toBe(true)
+  })
+
+  it('moves down when rightward movement exhausted', () => {
+    // Create a row of widgets that blocks rightward movement
+    const widgets = []
+    for (let i = 0; i < 10; i++) {
+      widgets.push({
+        id: `w${i}`,
+        type: 'sticky-note',
+        position: { x: i * 300, y: 0 },
+        props: { width: 270, height: 170 },
+      })
+    }
+    const result = findFreePosition({
+      x: 0,
+      y: 0,
+      width: 270,
+      height: 170,
+      widgets,
+      gridSize: 24,
+      maxIterations: 5, // Force early switch to vertical
+    })
+    // After exhausting horizontal, should move down
+    expect(result.adjusted).toBe(true)
+  })
+
+  it('respects excludeId parameter', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 270, height: 170 } },
+    ]
+    const result = findFreePosition({
+      x: 0,
+      y: 0,
+      width: 270,
+      height: 170,
+      widgets,
+      excludeId: 'w1',
+      gridSize: 24,
+    })
+    // Should stay at original position since w1 is excluded
+    expect(result).toEqual({ x: 0, y: 0, adjusted: false })
+  })
+
+  it('handles chain of collisions', () => {
+    // Two widgets next to each other
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 270, height: 170 } },
+      { id: 'w2', type: 'sticky-note', position: { x: 294, y: 0 }, props: { width: 270, height: 170 } },
+    ]
+    const result = findFreePosition({
+      x: 0,
+      y: 0,
+      width: 270,
+      height: 170,
+      widgets,
+      gridSize: 24,
+    })
+    // Should move past both widgets
+    expect(result.x).toBeGreaterThan(294 + 270)
+    expect(result.adjusted).toBe(true)
+  })
+})
+
+describe('resolvePosition', () => {
+  it('uses widget type defaults', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: {} },
+    ]
+    const result = resolvePosition({
+      x: 0,
+      y: 0,
+      type: 'sticky-note',
+      widgets,
+      gridSize: 24,
+    })
+    // Should detect collision and move
+    expect(result.adjusted).toBe(true)
+    expect(result.x).toBeGreaterThan(0)
+  })
+
+  it('uses custom props dimensions', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 100, height: 100 } },
+    ]
+    const result = resolvePosition({
+      x: 0,
+      y: 0,
+      type: 'sticky-note',
+      props: { width: 50, height: 50 },
+      widgets,
+      gridSize: 24,
+    })
+    // Should collide with w1 at (0,0) even though new widget is smaller
+    expect(result.adjusted).toBe(true)
+  })
+
+  it('returns snapped position when no collision', () => {
+    const result = resolvePosition({
+      x: 500,
+      y: 500,
+      type: 'markdown',
+      widgets: [],
+      gridSize: 24,
+    })
+    expect(result).toEqual({ x: 504, y: 504, adjusted: false })
+  })
+})

package/src/cli/canvasRead.js

@@ -15,18 +15,12 @@
  */
 
 import * as p from '@clack/prompts'
-import { detectWorktreeName, getPort } from '../worktree/port.js'
+import { getServerUrl } from './serverUrl.js'
 
 const dim = (s) => `\x1b[2m${s}\x1b[0m`
 const bold = (s) => `\x1b[1m${s}\x1b[0m`
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`
 
-function getServerUrl() {
-  const name = detectWorktreeName()
-  const port = getPort(name)
-  return `http://localhost:${port}`
-}
-
 async function checkServer() {
   try {
     await fetch(getServerUrl(), { signal: AbortSignal.timeout(2000) })

package/src/cli/create.js

@@ -15,9 +15,9 @@
  */
 
 import * as p from '@clack/prompts'
-import { detectWorktreeName, getPort } from '../worktree/port.js'
 import { parseFlags, hasFlags, formatFlagHelp } from './flags.js'
 import { prototypeSchema, canvasSchema, flowSchema, pageSchema } from './schemas.js'
+import { getServerUrl } from './serverUrl.js'
 
 const dim = (s) => `\x1b[2m${s}\x1b[0m`
 const green = (s) => `\x1b[32m${s}\x1b[0m`
@@ -37,12 +37,6 @@ function showHelp(type, schema) {
   process.exit(0)
 }
 
-function getServerUrl() {
-  const name = detectWorktreeName()
-  const port = getPort(name)
-  return `http://localhost:${port}`
-}
-
 async function serverGet(path) {
   const base = getServerUrl()
   const res = await fetch(`${base}${path}`)

package/src/cli/serverUrl.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve the dev server URL for the current worktree.
+ *
+ * Checks the Caddy admin API first to find the actual port mapped to
+ * this branch's route, since ports.json can drift from the running
+ * dev server. Falls back to ports.json if Caddy isn't reachable.
+ */
+
+import { detectWorktreeName, getPort } from '../worktree/port.js'
+import { readDevDomain } from './proxy.js'
+import { execSync } from 'child_process'
+
+export function getServerUrl() {
+  const name = detectWorktreeName()
+
+  // Try Caddy admin API for the real port
+  try {
+    const raw = execSync(
+      'curl -sf http://localhost:2019/config/apps/http/servers/srv0/routes',
+      { encoding: 'utf8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'] }
+    )
+    const routes = JSON.parse(raw)
+    const domain = readDevDomain()
+
+    for (const route of routes) {
+      const hosts = route.match?.[0]?.host || []
+      if (!hosts.includes(domain)) continue
+      const subroutes = route.handle?.[0]?.routes || []
+
+      if (name === 'main') {
+        // Main is the fallback route (no match path)
+        const fallback = subroutes.find(r => !r.match)
+        if (fallback) {
+          const dial = fallback.handle?.[0]?.upstreams?.[0]?.dial
+          if (dial) return `http://${dial}`
+        }
+      } else {
+        // Branch route matches /branch--<name>/*
+        const branchRoute = subroutes.find(r => {
+          const paths = r.match?.[0]?.path || []
+          return paths.some(p => p === `/branch--${name}/*`)
+        })
+        if (branchRoute) {
+          const dial = branchRoute.handle?.[0]?.upstreams?.[0]?.dial
+          if (dial) return `http://${dial}`
+        }
+      }
+    }
+  } catch {
+    // Caddy not running or not reachable — fall through
+  }
+
+  // Fallback to ports.json
+  const port = getPort(name)
+  return `http://localhost:${port}`
+}