@dfosco/storyboard 0.5.0-alpha.0

package/src/core/canvas/__tests__/terminal-integration.test.js

@@ -0,0 +1,177 @@
+/**
+ * Terminal Widget — Shell Session Integration Tests (Group 1)
+ *
+ * Tests the core terminal widget lifecycle:
+ * - Widget creation via canvas API
+ * - tmux session startup
+ * - Welcome menu rendering
+ * - Shell session selection and basic command execution
+ * - Browser rendering verification
+ * - Session list API
+ *
+ * Prerequisites: dev server running, tmux installed, agent-browser installed.
+ * Run with: npm run test:integration
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import * as canvasApi from './helpers/canvas-api.js'
+import * as tmux from './helpers/tmux.js'
+import * as browser from './helpers/browser.js'
+import * as transcript from './helpers/transcript.js'
+import * as perf from './helpers/perf.js'
+import { preflight, createTestCanvas, deleteTestCanvas, writeResults } from './helpers/setup.js'
+
+const CANVAS_NAME = '__test__-terminal'
+const BROWSER_SESSION = 'test-terminal'
+
+let serverUrl
+let terminalWidgetId
+let tmuxSessionName
+
+beforeAll(async () => {
+  const { url } = await preflight()
+  serverUrl = url
+  createTestCanvas(CANVAS_NAME)
+
+  // Give the dev server a moment to pick up the new canvas file
+  await new Promise((r) => setTimeout(r, 2000))
+})
+
+afterAll(() => {
+  // Flush transcripts
+  const paths = transcript.flushAll()
+
+  // Write results
+  writeResults(perf.toJSON(), paths)
+  perf.report()
+
+  // Cleanup: kill test tmux sessions
+  if (tmuxSessionName) tmux.killSession(tmuxSessionName)
+
+  // Cleanup: close browser
+  browser.close(BROWSER_SESSION)
+
+  // Cleanup: delete test canvas
+  deleteTestCanvas(CANVAS_NAME)
+})
+
+describe('Group 1: Terminal Widget — Shell Session', () => {
+  it('T1.1 — Create terminal widget via API', async () => {
+    const result = await canvasApi.createWidget(CANVAS_NAME, 'terminal', {}, { x: 100, y: 100 })
+
+    expect(result.success).toBe(true)
+    expect(result.widget).toBeDefined()
+    expect(result.widget.type).toBe('terminal')
+    expect(result.widget.id).toBeTruthy()
+    // Terminal widgets should get an auto-generated prettyName
+    expect(result.widget.props?.prettyName).toBeTruthy()
+
+    terminalWidgetId = result.widget.id
+
+    // Verify it appears in canvas read
+    const canvas = await canvasApi.readCanvas(CANVAS_NAME)
+    const widget = canvas.widgets?.find((w) => w.id === terminalWidgetId)
+    expect(widget).toBeDefined()
+    expect(widget.type).toBe('terminal')
+  })
+
+  it('T1.2 — Terminal session starts in tmux', async () => {
+    // Open the canvas in the browser
+    const canvasUrl = `${serverUrl}/storyboard/canvas/${CANVAS_NAME}`
+    browser.open(BROWSER_SESSION, canvasUrl)
+    browser.waitForLoad(BROWSER_SESSION, 'networkidle')
+
+    // Take a snapshot to find the terminal widget and click it
+    const _snap = browser.snapshot(BROWSER_SESSION, '-i')
+    void _snap
+
+    // The terminal widget should have a "Start" or "Continue" button/area
+    // Try clicking the terminal widget area to start the session
+    try {
+      browser.click(BROWSER_SESSION, `[data-widget-id="${terminalWidgetId}"]`)
+    } catch {
+      // If data-widget-id selector doesn't work, try clicking via snapshot refs
+      // The terminal widget may need a different interaction to start
+    }
+
+    // Wait for a tmux session to appear with the sb- prefix
+    try {
+      tmuxSessionName = await tmux.waitForSession(/^sb-/, 15000)
+      transcript.createTranscript(tmuxSessionName, { widgetId: terminalWidgetId, canvasName: CANVAS_NAME })
+      transcript.logEvent(tmuxSessionName, 'Session started')
+    } catch {
+      // Session may take longer if it's the first terminal
+      tmuxSessionName = await tmux.waitForSession(/^sb-/, 30000)
+      transcript.createTranscript(tmuxSessionName, { widgetId: terminalWidgetId, canvasName: CANVAS_NAME })
+    }
+
+    expect(tmuxSessionName).toBeTruthy()
+    expect(tmuxSessionName).toMatch(/^sb-/)
+  })
+
+  it('T1.3 — Welcome menu appears', async () => {
+    if (!tmuxSessionName) return
+
+    // Wait for the welcome menu to render
+    const output = await tmux.waitForOutput(tmuxSessionName, /shell|choose|workload/i, 15000)
+    transcript.logSection(tmuxSessionName, 'T1.3')
+
+    expect(output).toMatch(/shell/i)
+  })
+
+  it('T1.4 — Select Shell from welcome menu', async () => {
+    if (!tmuxSessionName) return
+    transcript.logSection(tmuxSessionName, 'T1.4')
+
+    // Navigate to Shell option and select it
+    // The welcome menu uses @clack/prompts — Shell is typically one of the options
+    // Send arrow keys to find Shell, then Enter to select
+    // Shell might be the last option before "Browse sessions"
+    tmux.sendKeys(tmuxSessionName, 'Down Down Enter')
+
+    // Wait for shell prompt ($ or % or > or similar)
+    await tmux.waitForOutput(tmuxSessionName, /\$|%|>|#/, 10000)
+
+    const output = tmux.capturePane(tmuxSessionName)
+    // Should no longer show the welcome menu, should show a shell prompt
+    expect(output).toBeTruthy()
+  })
+
+  it('T1.5 — Run basic shell command', async () => {
+    if (!tmuxSessionName) return
+    transcript.logSection(tmuxSessionName, 'T1.5')
+
+    // Send a command with a unique marker
+    tmux.sendText(tmuxSessionName, 'echo STORYBOARD_TEST_MARKER_12345')
+    tmux.sendKeys(tmuxSessionName, 'Enter')
+
+    // Wait for the marker to appear in output
+    const output = await tmux.waitForOutput(tmuxSessionName, /STORYBOARD_TEST_MARKER_12345/, 10000)
+    expect(output).toContain('STORYBOARD_TEST_MARKER_12345')
+
+    // Verify in the browser as well
+    try {
+      const _snap = browser.snapshot(BROWSER_SESSION)
+      void _snap
+      // The terminal output should be visible in the browser's terminal widget
+      // Note: ghostty-web rendering may not expose text in the accessibility tree
+      // This is a best-effort check
+    } catch {
+      // Browser verification is best-effort for terminal content
+    }
+  })
+
+  it('T1.6 — Terminal session appears in session list', async () => {
+    const sessions = await canvasApi.listTerminalSessions()
+
+    // Should have at least one session
+    expect(sessions).toBeDefined()
+
+    // The response format depends on the API — it might be an array or an object
+    if (Array.isArray(sessions)) {
+      expect(sessions.length).toBeGreaterThan(0)
+    } else if (typeof sessions === 'object') {
+      expect(Object.keys(sessions).length).toBeGreaterThan(0)
+    }
+  })
+})

package/src/core/canvas/collision.js

@@ -0,0 +1,292 @@
+/**
+ * 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.
+ */
+
+import widgetsConfig from '../../../widgets.config.json' with { type: 'json' }
+
+const FALLBACK_SIZE = { width: 270, height: 170 }
+
+/**
+ * Hardcoded fallbacks for widget types that don't specify defaults in config.
+ */
+const HARDCODED_DEFAULTS = {
+  'markdown': { width: 530, height: 240 },
+  'image': { width: 400, height: 300 },
+  '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
+}
+
+/**
+ * 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 = getDefaultSize(type)
+  return {
+    x: position.x,
+    y: position.y,
+    width: props.width ?? defaults.width,
+    height: props.height ?? defaults.height,
+  }
+}
+
+/**
+ * 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
+ * @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[]} - All colliding widgets (empty array if none)
+ */
+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)) {
+      colliders.push(widget)
+    }
+  }
+  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
+}
+
+/**
+ * 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, 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
+ * @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
+
+  // Phase 1: Try moving right past all colliders
+  for (let i = 0; i < maxIterations; i++) {
+    const rect = { x: currentX, y: currentY, width, height }
+    const colliders = findCollisions(rect, widgets, excludeId)
+
+    if (colliders.length === 0) {
+      return {
+        x: snapToGrid(currentX, gridSize),
+        y: snapToGrid(currentY, gridSize),
+        adjusted,
+      }
+    }
+
+    // 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
+  }
+
+  // Phase 2: Reset X, try moving down
+  currentX = x
+
+  for (let i = 0; i < maxIterations; i++) {
+    const rect = { x: currentX, y: currentY, width, height }
+    const colliders = findCollisions(rect, widgets, excludeId)
+
+    if (colliders.length === 0) {
+      return {
+        x: snapToGrid(currentX, gridSize),
+        y: snapToGrid(currentY, gridSize),
+        adjusted,
+      }
+    }
+
+    // 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
+  }
+
+  // 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 = getDefaultSize(type)
+  const width = props.width ?? defaults.width
+  const height = props.height ?? defaults.height
+
+  return findFreePosition({
+    x,
+    y,
+    width,
+    height,
+    widgets,
+    excludeId,
+    gridSize,
+  })
+}