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

package/src/canvas/writeGuard.js

@@ -1,5 +1,53 @@
 /**
- * Shared set of file paths currently being written by the canvas server.
- * The data plugin checks this to skip reload for in-flight writes.
+ * Canvas write guard — coordinates the canvas server with Vite's file watcher
+ * to prevent duplicate HMR events.
+ *
+ * When the canvas server writes to a .canvas.jsonl file, it immediately pushes
+ * an HMR event via pushCanvasUpdate(). Vite's file watcher also detects the
+ * change ~100-500ms later and the data plugin sends a second HMR event. This
+ * duplicate event can cause visible rollbacks when the client has made new edits
+ * in the intervening window.
+ *
+ * The guard tracks files currently being written by the canvas server. The data
+ * plugin checks this before sending watcher-triggered HMR events and skips them
+ * if the server has already pushed.
+ *
+ * Uses globalThis with a Symbol key to guarantee the same Map instance is shared
+ * across all import paths (e.g., relative imports from server.js vs package
+ * imports from data-plugin.js).
  */
-export const canvasWritesInFlight = new Set()
+
+const KEY = Symbol.for('sb:canvasWriteGuard')
+if (!globalThis[KEY]) globalThis[KEY] = new Map()
+
+/** @type {Map<string, number>} filePath → active write count */
+const guard = globalThis[KEY]
+
+/**
+ * Mark a file as being written by the canvas server.
+ * Call before appendEvent / writeFileSync.
+ */
+export function markCanvasWrite(filePath) {
+  guard.set(filePath, (guard.get(filePath) || 0) + 1)
+}
+
+/**
+ * Unmark a file after the watcher has had time to fire.
+ * Call via setTimeout after the write + push completes.
+ */
+export function unmarkCanvasWrite(filePath) {
+  const count = (guard.get(filePath) || 1) - 1
+  if (count <= 0) guard.delete(filePath)
+  else guard.set(filePath, count)
+}
+
+/**
+ * Check if a file is currently being written by the canvas server.
+ * The data plugin uses this to skip duplicate watcher-triggered HMR events.
+ */
+export function isCanvasWriteInFlight(filePath) {
+  return guard.has(filePath)
+}
+
+// Legacy export for backward compatibility
+export const canvasWritesInFlight = guard

package/src/canvasConfig.js

@@ -21,6 +21,8 @@
 
 let _pasteRules = []
 let _terminal = {}
+let _agents = {}
+let _zoom = { min: 10, max: 250, step: 10 }
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -30,11 +32,15 @@ let _terminal = {}
  * Initialize canvas config from storyboard.config.json's "canvas" key.
  * Called by mountStoryboardCore.
  *
- * @param {{ pasteRules?: object[], terminal?: object }} [config]
+ * @param {{ pasteRules?: object[], terminal?: object, agents?: object, zoom?: object }} [config]
  */
 export function initCanvasConfig(config = {}) {
   _pasteRules = Array.isArray(config.pasteRules) ? config.pasteRules : []
   _terminal = config.terminal && typeof config.terminal === 'object' ? config.terminal : {}
+  _agents = config.agents && typeof config.agents === 'object' ? config.agents : {}
+  _zoom = config.zoom && typeof config.zoom === 'object'
+    ? { min: config.zoom.min ?? 10, max: config.zoom.max ?? 250, step: config.zoom.step ?? 10 }
+    : { min: 10, max: 250, step: 10 }
 }
 
 /**
@@ -55,6 +61,64 @@ export function getTerminalConfig() {
   return _terminal
 }
 
+/**
+ * Get agent configurations.
+ *
+ * @returns {object}
+ */
+export function getAgentsConfig() {
+  return _agents
+}
+
+/**
+ * Get canvas zoom configuration (min, max, step).
+ *
+ * @returns {{ min: number, max: number, step: number }}
+ */
+export function getCanvasZoom() {
+  return _zoom
+}
+
+/**
+ * Check if a terminal/agent widget should be resizable based on config.
+ * Agent-level `resizable` overrides the base `terminal.resizable`.
+ *
+ * @param {string|null} [agentId] — agent ID to check for overrides
+ * @returns {boolean}
+ */
+export function isTerminalResizable(agentId = null) {
+  if (agentId) {
+    const agentCfg = _agents[agentId]
+    if (agentCfg && agentCfg.resizable !== undefined) return agentCfg.resizable
+  }
+  return _terminal.resizable ?? false
+}
+
+/**
+ * Get effective default dimensions for a terminal/agent widget.
+ * Cascade: agent config > terminal config > provided fallbacks.
+ *
+ * @param {string|null} [agentId] — agent ID to check for overrides
+ * @param {{ width: number, height: number }} [fallback] — schema-level fallbacks
+ * @returns {{ width: number, height: number }}
+ */
+export function getTerminalDimensions(agentId = null, fallback = { width: 800, height: 450 }) {
+  const base = {
+    width: _terminal.defaultWidth ?? fallback.width,
+    height: _terminal.defaultHeight ?? fallback.height,
+  }
+  if (agentId) {
+    const agentCfg = _agents[agentId]
+    if (agentCfg) {
+      return {
+        width: agentCfg.defaultWidth ?? base.width,
+        height: agentCfg.defaultHeight ?? base.height,
+      }
+    }
+  }
+  return base
+}
+
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------
@@ -65,4 +129,6 @@ export function getTerminalConfig() {
 export function _resetCanvasConfig() {
   _pasteRules = []
   _terminal = {}
+  _agents = {}
+  _zoom = { min: 10, max: 250, step: 10 }
 }

package/src/canvasConfig.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest'
-import { initCanvasConfig, getPasteRules, _resetCanvasConfig } from './canvasConfig.js'
+import { initCanvasConfig, getPasteRules, isTerminalResizable, getTerminalDimensions, _resetCanvasConfig } from './canvasConfig.js'
 
 describe('canvasConfig', () => {
   beforeEach(() => {
@@ -40,3 +40,81 @@ describe('canvasConfig', () => {
     expect(getPasteRules()).toEqual([])
   })
 })
+
+describe('isTerminalResizable', () => {
+  beforeEach(() => {
+    _resetCanvasConfig()
+  })
+
+  it('returns false by default', () => {
+    expect(isTerminalResizable()).toBe(false)
+  })
+
+  it('returns terminal.resizable when set', () => {
+    initCanvasConfig({ terminal: { resizable: true } })
+    expect(isTerminalResizable()).toBe(true)
+  })
+
+  it('agent overrides terminal resizable', () => {
+    initCanvasConfig({
+      terminal: { resizable: false },
+      agents: { myAgent: { resizable: true } },
+    })
+    expect(isTerminalResizable('myAgent')).toBe(true)
+    expect(isTerminalResizable()).toBe(false)
+  })
+
+  it('agent can disable resizable even when terminal enables it', () => {
+    initCanvasConfig({
+      terminal: { resizable: true },
+      agents: { fixedAgent: { resizable: false } },
+    })
+    expect(isTerminalResizable('fixedAgent')).toBe(false)
+    expect(isTerminalResizable()).toBe(true)
+  })
+
+  it('falls back to terminal config for unknown agent', () => {
+    initCanvasConfig({ terminal: { resizable: true } })
+    expect(isTerminalResizable('nonexistent')).toBe(true)
+  })
+})
+
+describe('getTerminalDimensions', () => {
+  beforeEach(() => {
+    _resetCanvasConfig()
+  })
+
+  it('returns fallback defaults when no config', () => {
+    expect(getTerminalDimensions()).toEqual({ width: 800, height: 450 })
+  })
+
+  it('returns terminal config dimensions', () => {
+    initCanvasConfig({ terminal: { defaultWidth: 1000, defaultHeight: 600 } })
+    expect(getTerminalDimensions()).toEqual({ width: 1000, height: 600 })
+  })
+
+  it('agent overrides terminal dimensions', () => {
+    initCanvasConfig({
+      terminal: { defaultWidth: 1000, defaultHeight: 600 },
+      agents: { bigAgent: { defaultWidth: 1400, defaultHeight: 800 } },
+    })
+    expect(getTerminalDimensions('bigAgent')).toEqual({ width: 1400, height: 800 })
+  })
+
+  it('agent partial override inherits from terminal for unset dimensions', () => {
+    initCanvasConfig({
+      terminal: { defaultWidth: 1000, defaultHeight: 600 },
+      agents: { wideAgent: { defaultWidth: 1400 } },
+    })
+    expect(getTerminalDimensions('wideAgent')).toEqual({ width: 1400, height: 600 })
+  })
+
+  it('falls back to terminal config for unknown agent', () => {
+    initCanvasConfig({ terminal: { defaultWidth: 900, defaultHeight: 500 } })
+    expect(getTerminalDimensions('nonexistent')).toEqual({ width: 900, height: 500 })
+  })
+
+  it('uses custom fallback when provided', () => {
+    expect(getTerminalDimensions(null, { width: 1200, height: 450 })).toEqual({ width: 1200, height: 450 })
+  })
+})

package/src/cli/agent.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * storyboard agent signal — signal agent status to the canvas server.
+ *
+ * Usage:
+ *   npx storyboard agent signal --widget <id> --canvas <canvasId> --status done|error|running [--message "..."]
+ *
+ * Environment variables (auto-set by terminal server):
+ *   STORYBOARD_WIDGET_ID  — widget ID (fallback if --widget not provided)
+ *   STORYBOARD_CANVAS_ID  — canvas ID (fallback if --canvas not provided)
+ *   STORYBOARD_SERVER_URL — server base URL
+ *   STORYBOARD_BRANCH     — current branch
+ */
+
+import { parseFlags } from './flags.js'
+import { dim, bold, cyan, yellow } from './intro.js'
+
+const subcommand = process.argv[3]
+
+if (subcommand === 'signal') {
+  const flagSchema = {
+    widget: { type: 'string', description: 'Widget ID' },
+    canvas: { type: 'string', description: 'Canvas ID' },
+    status: { type: 'string', required: true, description: 'Status: done, error, or running' },
+    message: { type: 'string', description: 'Optional status message' },
+  }
+
+  const { flags } = parseFlags(process.argv.slice(4), flagSchema)
+
+  const widgetId = flags.widget || process.env.STORYBOARD_WIDGET_ID
+  const canvasId = flags.canvas || process.env.STORYBOARD_CANVAS_ID
+  const status = flags.status
+  const message = flags.message || null
+  const serverUrl = process.env.STORYBOARD_SERVER_URL || 'http://localhost:1234'
+  const branch = process.env.STORYBOARD_BRANCH || 'unknown'
+
+  if (!widgetId || !canvasId || !status) {
+    console.error(`${bold('Usage:')} npx storyboard agent signal --status done|error|running`)
+    console.error(`${dim('Widget and canvas IDs are read from environment if not provided.')}`)
+    process.exit(1)
+  }
+
+  const validStatuses = ['done', 'error', 'running']
+  if (!validStatuses.includes(status)) {
+    console.error(`${bold('Error:')} Status must be one of: ${validStatuses.join(', ')}`)
+    process.exit(1)
+  }
+
+  try {
+    const url = `${serverUrl}/_storyboard/canvas/agent/signal`
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ widgetId, canvasId, branch, status, message }),
+    })
+
+    if (res.ok) {
+      console.log(`${cyan('✓')} Agent status: ${bold(status)}${message ? ` — ${message}` : ''}`)
+    } else {
+      const data = await res.json().catch(() => ({}))
+      console.error(`${yellow('⚠')} Server returned ${res.status}: ${data.error || 'unknown error'}`)
+      // Fallback: write directly to terminal config
+      await fallbackWrite({ branch, canvasId, widgetId, status, message })
+    }
+  } catch {
+    // Server not reachable — write directly to terminal config file
+    await fallbackWrite({ branch, canvasId, widgetId, status, message })
+  }
+} else {
+  console.error(`${bold('Usage:')} npx storyboard agent <signal>`)
+  console.error(`${dim('Subcommands: signal')}`)
+  process.exit(1)
+}
+
+async function fallbackWrite({ branch, canvasId, widgetId, status, message }) {
+  try {
+    const { updateAgentStatus, initTerminalConfig } = await import('../canvas/terminal-config.js')
+    initTerminalConfig(process.cwd())
+    updateAgentStatus({ branch, canvasId, widgetId, status, message })
+    console.log(`${cyan('✓')} Agent status written to config file (server offline): ${bold(status)}`)
+  } catch (err) {
+    console.error(`Failed to write agent status: ${err.message}`)
+    process.exit(1)
+  }
+}

package/src/cli/branch.js

@@ -0,0 +1,232 @@
+/**
+ * storyboard branch — Interactive guide to switch to a branch worktree.
+ *
+ * Deterministic flow (no AI):
+ *   1. Ask which branch to work on
+ *   2. Stash uncommitted work (named stash for safety)
+ *   3. Create worktree if needed (git worktree add + npm install)
+ *   4. Pull --rebase from origin
+ *   5. Apply stash into the new worktree
+ *   6. Confirm to user
+ *
+ * Also available as post-setup prompt in setup.js.
+ *
+ * Usage:
+ *   npx storyboard branch
+ *   npx storyboard branch <name>   # skip the prompt
+ */
+
+import * as p from '@clack/prompts'
+import { execFileSync } from 'child_process'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+import { repoRoot, worktreeDir, listWorktrees, getPort, detectWorktreeName } from '../worktree/port.js'
+import { hasUncommittedChanges, localBranchExists } from './dev-helpers.js'
+import { dim, green, yellow, bold, cyan } from './intro.js'
+
+/** Check if a remote branch exists on origin. */
+function remoteBranchExists(name, cwd) {
+  try {
+    const result = execFileSync('git', ['ls-remote', '--exit-code', '--heads', 'origin', name], { cwd, encoding: 'utf8' })
+    return result.trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+/** Get the current branch name. */
+function currentBranch(cwd) {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+/** Validate a branch name for git. */
+function isValidBranchName(name) {
+  if (!name || name.trim().length === 0) return 'Branch name cannot be empty'
+  const n = name.trim()
+  if (/\s/.test(n)) return 'Branch name cannot contain spaces'
+  if (/\.\./.test(n)) return 'Branch name cannot contain ".."'
+  if (/[~^:\\]/.test(n)) return 'Branch name cannot contain ~, ^, :, or \\'
+  if (n.startsWith('-')) return 'Branch name cannot start with "-"'
+  if (n.endsWith('.lock')) return 'Branch name cannot end with ".lock"'
+  return undefined
+}
+
+export async function runBranchGuide(branchArg) {
+  const root = repoRoot()
+  const existing = listWorktrees()
+  const fromBranch = currentBranch(root)
+  const fromWorktree = detectWorktreeName()
+
+  // 1. Get branch name
+  let targetBranch = branchArg?.trim()
+
+  if (!targetBranch) {
+    if (existing.length > 0) {
+      // Render as columns that fit the terminal width
+      const maxLen = Math.max(...existing.map(w => w.length))
+      const colWidth = maxLen + 2
+      const termWidth = process.stdout.columns || 80
+      const cols = Math.max(1, Math.floor(termWidth / colWidth))
+      const rows = Math.ceil(existing.length / cols)
+      const lines = []
+      for (let r = 0; r < rows; r++) {
+        const parts = []
+        for (let c = 0; c < cols; c++) {
+          const idx = c * rows + r
+          if (idx < existing.length) {
+            parts.push(cyan(existing[idx].padEnd(colWidth)))
+          }
+        }
+        lines.push(`  ${parts.join('')}`)
+      }
+      p.log.info(`${dim('Existing worktrees:')}\n${lines.join('\n')}`)
+    }
+
+    const result = await p.text({
+      message: 'Which branch do you want to work on? Select one from above or type a new one',
+      placeholder: 'e.g. 4.3.0--my-feature',
+      validate: isValidBranchName,
+    })
+
+    if (p.isCancel(result)) {
+      p.cancel('Cancelled')
+      process.exit(0)
+    }
+    targetBranch = result.trim()
+  }
+
+  // 2. Check if worktree already exists
+  const wtDir = worktreeDir(targetBranch)
+  if (existsSync(resolve(wtDir, '.git'))) {
+    p.log.success(`Worktree ${bold(targetBranch)} already exists`)
+    p.note(
+      [
+        `  ${green('cd')} ${dim(`.worktrees/${targetBranch}`)}`,
+        `  ${green('npx storyboard dev')}  ${dim('to start developing')}`,
+      ].join('\n'),
+      'Ready to go'
+    )
+    p.outro('')
+    return
+  }
+
+  // 3. Stash uncommitted work
+  let didStash = false
+  const sourceDir = fromWorktree === 'main' ? root : worktreeDir(fromWorktree)
+
+  if (hasUncommittedChanges(sourceDir)) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+    const stashName = `${fromBranch}→${targetBranch}@${timestamp}`
+
+    p.log.step('Stashing uncommitted work…')
+    try {
+      execFileSync('git', ['stash', 'push', '-m', stashName], { cwd: sourceDir, stdio: 'pipe' })
+      didStash = true
+      p.log.success(`Work stashed: ${dim(stashName)}`)
+    } catch {
+      p.log.warning('Could not stash changes — proceeding anyway')
+    }
+  }
+
+  // 4. Resolve branch and create worktree
+  const hasLocal = localBranchExists(targetBranch, root)
+  const hasRemote = !hasLocal && remoteBranchExists(targetBranch, root)
+  const isNew = !hasLocal && !hasRemote
+
+  if (isNew) {
+    p.log.step(`Creating new branch ${bold(targetBranch)} from HEAD`)
+  } else if (hasRemote) {
+    // Fetch the remote branch so git worktree add can use it
+    p.log.step(`Fetching ${bold(targetBranch)} from origin…`)
+    try {
+      execFileSync('git', ['fetch', 'origin', targetBranch], { cwd: root, stdio: 'pipe' })
+      // Create a local tracking branch
+      try {
+        execFileSync('git', ['branch', targetBranch, `origin/${targetBranch}`], { cwd: root, stdio: 'pipe' })
+      } catch { /* may already exist after fetch */ }
+    } catch {
+      p.log.warning('Could not fetch from origin — using local state')
+    }
+  } else {
+    p.log.step(`Using existing branch ${bold(targetBranch)}`)
+  }
+
+  // Create the worktree
+  const targetDir = resolve(root, '.worktrees', targetBranch)
+  const spin = p.spinner()
+
+  try {
+    const gitArgs = isNew
+      ? ['worktree', 'add', targetDir, '-b', targetBranch]
+      : ['worktree', 'add', targetDir, targetBranch]
+
+    spin.start(`Creating worktree .worktrees/${targetBranch}`)
+    execFileSync('git', gitArgs, { cwd: root, stdio: 'pipe' })
+    spin.stop(`Worktree created: .worktrees/${targetBranch}`)
+  } catch (err) {
+    spin.stop('Failed to create worktree')
+    p.log.error(err.message || 'git worktree add failed')
+    process.exit(1)
+  }
+
+  // Install dependencies
+  try {
+    spin.start('Installing dependencies…')
+    const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+    execFileSync(npmBin, ['install'], { cwd: targetDir, stdio: 'pipe' })
+    spin.stop('Dependencies installed')
+  } catch {
+    spin.stop('npm install failed — you may need to run it manually')
+  }
+
+  // Assign a dev server port
+  getPort(targetBranch)
+
+  // 5. Pull --rebase from origin
+  if (!isNew) {
+    try {
+      spin.start('Pulling latest changes…')
+      execFileSync('git', ['pull', '--rebase', 'origin', targetBranch], { cwd: targetDir, stdio: 'pipe' })
+      spin.stop('Up to date with origin')
+    } catch {
+      spin.stop(dim('No remote changes (or origin not available)'))
+    }
+  }
+
+  // 6. Apply stash (if we stashed earlier)
+  if (didStash) {
+    try {
+      // Apply (not pop) — keeps the backup in stash list
+      execFileSync('git', ['stash', 'apply'], { cwd: targetDir, stdio: 'pipe' })
+      p.log.success('Previous work applied to this branch')
+    } catch {
+      p.log.warning('Stash apply had conflicts — resolve them manually')
+      p.log.info(`  Your work is safe in ${dim('git stash list')}`)
+    }
+  }
+
+  // 7. Summary
+  const lines = [
+    `  Your branch is set up as a worktree in ${green(`.worktrees/${targetBranch}`)}`,
+  ]
+  if (didStash) {
+    lines.push(`  Your uncommitted work has been safely moved`)
+  }
+  lines.push('')
+  lines.push(`  ${green('cd')} ${dim(`.worktrees/${targetBranch}`)}`)
+  lines.push(`  ${green('npx storyboard dev')}  ${dim('to start developing')}`)
+  lines.push('')
+  lines.push(`  ${dim('Tip: ask your AI agent about worktrees — they\'re great!')}`)
+
+  p.note(lines.join('\n'), `Branch ${bold(targetBranch)} is ready`)
+  p.outro('')
+}
+
+// Direct invocation
+const branchArg = process.argv[3] || undefined
+p.intro('storyboard branch')
+runBranchGuide(branchArg)

package/src/cli/canvasAdd.js

@@ -1,10 +1,20 @@
 /**
  * storyboard canvas add <widget-type> — Add a widget to an existing canvas.
  *
+ * Widgets are auto-positioned by default near (in priority order):
+ * 1. The active agent/terminal running the command ($STORYBOARD_WIDGET_ID)
+ * 2. The user's currently selected widget
+ * 3. The center of the user's viewport
+ * 4. The last widget on the canvas
+ *
+ * Use --x/--y for explicit coordinates, or --near <widget-id> to place
+ * relative to a specific widget. Use --near false to opt out entirely.
+ *
  * Usage:
  *   storyboard canvas add sticky-note --canvas my-canvas
- *   storyboard canvas add markdown --canvas my-canvas --x 100 --y 200
- *   storyboard canvas add prototype --canvas my-canvas --props '{"src":"my-proto"}'
+ *   storyboard canvas add markdown --canvas my-canvas --near widget-abc
+ *   storyboard canvas add prototype --canvas my-canvas --x 100 --y 200
+ *   storyboard canvas add sticky-note --canvas my-canvas --near false --x 0 --y 0
  *
  * Known widget types: sticky-note, markdown, prototype
  * The server accepts any type string — new widget types work automatically.
@@ -44,14 +54,15 @@ async function canvasAdd() {
 
   const flagMode = hasFlags(rest) || Boolean(widgetType)
   const { flags, errors } = flagMode ? parseFlags(flagTokens, widgetSchema) : { flags: {}, errors: [] }
+  const jsonOutput = flags.json || false
 
   if (errors.length) {
     for (const e of errors) p.log.error(e)
     process.exit(1)
   }
 
-  p.intro('storyboard canvas add')
-  await ensureDevServer()
+  if (!jsonOutput) p.intro('storyboard canvas add')
+  await ensureDevServer({ quiet: jsonOutput })
 
   // Widget type
   if (!widgetType) {
@@ -93,9 +104,24 @@ async function canvasAdd() {
     return v
   })()
 
+  // Position flags: only send explicit position if user provided --x/--y.
+  // --near=false explicitly opts out of auto-positioning.
+  const hasExplicitX = flags.x !== undefined && flags.x !== null
+  const hasExplicitY = flags.y !== undefined && flags.y !== null
+  const hasExplicitPosition = hasExplicitX || hasExplicitY
   const x = flags.x ?? 0
   const y = flags.y ?? 0
 
+  // --near: string widget ID, or literal "false" to opt out
+  const nearRaw = flags.near
+  const nearOptOut = nearRaw === 'false' || nearRaw === false
+  const near = (nearRaw && !nearOptOut) ? nearRaw : null
+  const direction = flags.direction || 'right'
+  const resolve = flags.resolve || !!near
+
+  // Pass the calling agent/terminal's widget ID so the server can auto-position near it
+  const source = process.env.STORYBOARD_WIDGET_ID || null
+
   let props = {}
   if (flags['props-file']) {
     try {
@@ -167,19 +193,40 @@ async function canvasAdd() {
   }
 
   // Submit
+  if (jsonOutput) {
+    // JSON mode: no spinners/clack UI, just raw JSON output for scripting
+    try {
+      const body = { name: canvasName, type: widgetType, props }
+      if (hasExplicitPosition) body.position = { x, y }
+      if (nearOptOut) body.near = false
+      if (near) { body.near = near; body.direction = direction }
+      if (resolve) body.resolve = true
+      if (source) body.source = source
+      const result = await serverPost('/_storyboard/canvas/widget', body)
+      const widget = result.widget || result
+      console.log(JSON.stringify(widget))
+    } catch (err) {
+      console.error(JSON.stringify({ error: err.message }))
+      process.exit(1)
+    }
+    return
+  }
+
   const s = p.spinner()
   s.start(`Adding ${widgetType} widget...`)
 
   try {
-    const result = await serverPost('/_storyboard/canvas/widget', {
-      name: canvasName,
-      type: widgetType,
-      props,
-      position: { x, y },
-    })
+    const body = { name: canvasName, type: widgetType, props }
+    if (hasExplicitPosition) body.position = { x, y }
+    if (nearOptOut) body.near = false
+    if (near) { body.near = near; body.direction = direction }
+    if (resolve) body.resolve = true
+    if (source) body.source = source
+    const result = await serverPost('/_storyboard/canvas/widget', body)
     s.stop(`Widget added!`)
-    if (result.id) {
-      p.log.success(`  ${widgetType} → ${canvasName} (id: ${result.id})`)
+    const widgetId = result.widget?.id || result.id
+    if (widgetId) {
+      p.log.success(`  ${widgetType} → ${canvasName} (id: ${widgetId})`)
     } else {
       p.log.success(`  ${widgetType} → ${canvasName}`)
     }