@dfosco/storyboard-core 4.0.0-beta.2 → 4.0.0-beta.21

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/canvas/deriveCanvasId.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { toCanvasId } from './identity.js'
+
+describe('toCanvasId (path-based canvas identity)', () => {
+  it('returns basename for flat canvas in src/canvas/', () => {
+    expect(toCanvasId('src/canvas/design-overview.canvas.jsonl')).toBe('design-overview')
+  })
+
+  it('returns path-based ID for canvas inside a .folder/', () => {
+    expect(toCanvasId('src/canvas/research.folder/interviews.canvas.jsonl')).toBe('research/interviews')
+  })
+
+  it('strips .folder suffix from path', () => {
+    expect(toCanvasId('src/canvas/ux.folder/onboarding.canvas.jsonl')).toBe('ux/onboarding')
+  })
+
+  it('handles nested subdirectories inside a .folder/', () => {
+    expect(toCanvasId('src/canvas/team.folder/sub/deep.canvas.jsonl')).toBe('team/sub/deep')
+  })
+
+  it('returns proto:-prefixed ID for prototype-scoped canvas', () => {
+    expect(toCanvasId('src/prototypes/Dashboard/overview.canvas.jsonl')).toBe('proto:Dashboard/overview')
+  })
+
+  it('handles prototype inside a .folder/', () => {
+    expect(toCanvasId('src/prototypes/main.folder/Dashboard/overview.canvas.jsonl')).toBe('proto:main/Dashboard/overview')
+  })
+
+  it('duplicate basenames in different folders get distinct IDs', () => {
+    const id1 = toCanvasId('src/canvas/alpha.folder/overview.canvas.jsonl')
+    const id2 = toCanvasId('src/canvas/beta.folder/overview.canvas.jsonl')
+    expect(id1).toBe('alpha/overview')
+    expect(id2).toBe('beta/overview')
+    expect(id1).not.toBe(id2)
+  })
+
+  it('normalizes backslashes to forward slashes', () => {
+    expect(toCanvasId('src\\canvas\\research.folder\\interviews.canvas.jsonl')).toBe('research/interviews')
+  })
+})

package/src/canvas/identity.js

@@ -0,0 +1,107 @@
+/**
+ * Canvas Identity — path-based canvas ID utilities.
+ *
+ * Canonical canvas IDs are normalized relative paths derived from the file
+ * location. They uniquely identify a canvas even when two canvases share the
+ * same basename in different folders.
+ *
+ * Format examples:
+ *   src/canvas/overview.canvas.jsonl                  → "overview"
+ *   src/canvas/design.folder/overview.canvas.jsonl    → "design/overview"
+ *   src/canvas/design.folder/sub.folder/a.canvas.jsonl → "design/sub/a"
+ *   src/prototypes/Main/board.canvas.jsonl            → "proto:Main/board"
+ *
+ * Canvases under src/canvas/ get plain IDs; those under src/prototypes/ get
+ * a "proto:" prefix so the two namespaces never collide.
+ *
+ * Legacy IDs (bare names like "overview") remain supported as aliases when
+ * they resolve to exactly one canvas.
+ *
+ * @module canvas/identity
+ */
+
+const CANVAS_SUFFIX_RE = /\.canvas\.jsonl$/
+const FOLDER_SUFFIX_RE = /([^/]+)\.folder\//g
+
+/**
+ * Convert a relative file path to a canonical canvas ID.
+ *
+ * @param {string} relPath — path relative to project root
+ * @returns {string} canonical canvas ID
+ */
+export function toCanvasId(relPath) {
+  let p = relPath.replace(/\\/g, '/')
+
+  let prefix = ''
+  if (p.startsWith('src/canvas/')) {
+    p = p.slice('src/canvas/'.length)
+  } else if (p.startsWith('src/prototypes/')) {
+    p = p.slice('src/prototypes/'.length)
+    prefix = 'proto:'
+  }
+
+  // Strip .canvas.jsonl suffix
+  p = p.replace(CANVAS_SUFFIX_RE, '')
+
+  // Normalize .folder segments: "design.folder/" → "design/"
+  p = p.replace(FOLDER_SUFFIX_RE, '$1/')
+
+  // Clean up double slashes and trailing slash
+  p = p.replace(/\/+/g, '/').replace(/\/$/, '')
+
+  return prefix + (p || 'unknown')
+}
+
+/**
+ * Parse a canvas ID into its segments.
+ *
+ * @param {string} id — canonical canvas ID
+ * @returns {{ namespace: 'canvas' | 'prototype', segments: string[], name: string }}
+ */
+export function parseCanvasId(id) {
+  let namespace = 'canvas'
+  let raw = id
+  if (raw.startsWith('proto:')) {
+    namespace = 'prototype'
+    raw = raw.slice('proto:'.length)
+  }
+  const segments = raw.split('/').filter(Boolean)
+  const name = segments[segments.length - 1] || raw
+  return { namespace, segments, name }
+}
+
+/**
+ * Extract the basename from a canvas ID (the last segment).
+ * Useful for backward-compatible lookups.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function canvasIdBasename(id) {
+  return parseCanvasId(id).name
+}
+
+/**
+ * Check whether an ID is a legacy bare name (no path segments, no namespace prefix).
+ *
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isLegacyCanvasId(id) {
+  return !id.includes('/') && !id.startsWith('proto:')
+}
+
+/**
+ * Known consumers of canvas identity that must be updated when migrating
+ * from basename-only to path-based IDs. This inventory is used by downstream
+ * slices to track migration completeness.
+ */
+export const CANVAS_IDENTITY_CONSUMERS = [
+  'packages/react/src/vite/data-plugin.js — index & HMR payloads',
+  'packages/core/src/canvas/server.js — findCanvasPath() & all API routes',
+  'packages/react/src/context.jsx — canvasRouteMap',
+  'packages/react/src/canvas/CanvasPage.jsx — cross-canvas copy/paste (canvasName/widgetId)',
+  'packages/react/src/canvas/CanvasPage.jsx — viewport persistence keys',
+  'packages/core/src/viewfinder.js — canvas listing',
+  'packages/core/src/rename-watcher/watcher.js — canvas rename route inference',
+]