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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-beta.6",
   "type": "module",
   "license": "MIT",
   "bin": {

package/src/autosync/server.js

@@ -81,7 +81,7 @@ function hasScopedStagedChanges(root, files) {
 function listChangedFiles(root) {
   const tracked = git(['diff', '--name-only'], root)
   const untracked = git(['ls-files', '--others', '--exclude-standard'], root)
-  return [...tracked, ...untracked]
+  return [tracked, untracked]
     .flatMap((raw) => raw.split('\n'))
     .map((file) => file.trim())
     .filter(Boolean)

package/src/cli/canvasRead.js

@@ -0,0 +1,212 @@
+/**
+ * storyboard canvas read — Read canvas state and list widgets with their IDs, URLs, and content.
+ *
+ * Usage:
+ *   storyboard canvas read my-canvas             List all widgets
+ *   storyboard canvas read my-canvas --json      Output as JSON
+ *   storyboard canvas read my-canvas --id abc    Get a specific widget by ID
+ *
+ * Output includes:
+ *   - Widget ID
+ *   - Widget type
+ *   - Position (x, y)
+ *   - Content (text, url, src depending on type)
+ *   - File path (for images)
+ */
+
+import * as p from '@clack/prompts'
+import { detectWorktreeName, getPort } from '../worktree/port.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) })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Extract the primary content from a widget based on its type.
+ */
+function getWidgetContent(widget) {
+  const { type, props = {} } = widget
+  switch (type) {
+    case 'sticky-note':
+      return { content: props.text || '', contentType: 'text' }
+    case 'markdown':
+      return { content: props.content || '', contentType: 'markdown' }
+    case 'prototype':
+      return { content: props.src || '', contentType: 'url', url: props.src }
+    case 'figma-embed':
+      return { content: props.url || '', contentType: 'url', url: props.url }
+    case 'link-preview':
+      return { content: props.url || '', contentType: 'url', url: props.url }
+    case 'image':
+      return {
+        content: props.src || '',
+        contentType: 'image',
+        url: props.src ? `/_storyboard/canvas/images/${props.src}` : '',
+        filePath: props.src ? `src/canvas/images/${props.src}` : '',
+      }
+    default:
+      return { content: JSON.stringify(props), contentType: 'props' }
+  }
+}
+
+/**
+ * Format a widget for human-readable output.
+ */
+function formatWidget(widget) {
+  const { id, type, position = {} } = widget
+  const { content, contentType, url, filePath } = getWidgetContent(widget)
+
+  const lines = []
+  lines.push(`${bold(id)} ${dim(`(${type})`)}`)
+  lines.push(`  Position: ${position.x ?? 0}, ${position.y ?? 0}`)
+
+  if (contentType === 'image') {
+    lines.push(`  File: ${cyan(filePath)}`)
+    if (content) lines.push(`  Filename: ${content}`)
+  } else if (contentType === 'url') {
+    lines.push(`  URL: ${cyan(url || content)}`)
+  } else if (content) {
+    const preview = content.length > 80 ? content.slice(0, 77) + '...' : content
+    lines.push(`  Content: ${preview}`)
+  }
+
+  return lines.join('\n')
+}
+
+async function canvasRead() {
+  const args = process.argv.slice(4)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  canvas read — Read canvas state and list widgets
+
+  Usage:
+    storyboard canvas read <canvas-name>          List all widgets
+    storyboard canvas read <canvas-name> --json   Output as JSON
+    storyboard canvas read <canvas-name> --id <widget-id>  Get specific widget
+
+  Output includes widget ID, type, position, content, URLs, and file paths.
+`)
+    process.exit(0)
+  }
+
+  // Parse args
+  let canvasName = ''
+  let outputJson = false
+  let widgetId = ''
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--json') {
+      outputJson = true
+    } else if (arg === '--id' && args[i + 1]) {
+      widgetId = args[++i]
+    } else if (!arg.startsWith('-') && !canvasName) {
+      canvasName = arg
+    }
+  }
+
+  // Check server
+  const serverUp = await checkServer()
+  if (!serverUp) {
+    p.log.error('Dev server is not running. Start it with: storyboard dev')
+    process.exit(1)
+  }
+
+  const base = getServerUrl()
+
+  // If no canvas name, list available canvases
+  if (!canvasName) {
+    try {
+      const res = await fetch(`${base}/_storyboard/canvas/list`)
+      if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
+      const data = await res.json()
+      const canvases = data.canvases || []
+
+      if (outputJson) {
+        console.log(JSON.stringify(canvases, null, 2))
+      } else {
+        if (canvases.length === 0) {
+          p.log.info('No canvases found')
+        } else {
+          console.log('\nAvailable canvases:\n')
+          for (const c of canvases) {
+            console.log(`  ${bold(c.name)} ${dim(`(${c.widgetCount} widgets)`)}`)
+          }
+          console.log('')
+        }
+      }
+    } catch (err) {
+      p.log.error(`Failed to list canvases: ${err.message}`)
+      process.exit(1)
+    }
+    return
+  }
+
+  // Read canvas state
+  try {
+    const res = await fetch(`${base}/_storyboard/canvas/read?name=${encodeURIComponent(canvasName)}`)
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`${res.status} ${res.statusText}${text ? ': ' + text : ''}`)
+    }
+    const data = await res.json()
+    const widgets = data.widgets || []
+
+    // If filtering by widget ID
+    if (widgetId) {
+      const widget = widgets.find((w) => w.id === widgetId)
+      if (!widget) {
+        p.log.error(`Widget "${widgetId}" not found in canvas "${canvasName}"`)
+        process.exit(1)
+      }
+
+      if (outputJson) {
+        const enriched = { ...widget, ...getWidgetContent(widget) }
+        console.log(JSON.stringify(enriched, null, 2))
+      } else {
+        console.log('')
+        console.log(formatWidget(widget))
+        console.log('')
+      }
+      return
+    }
+
+    // List all widgets
+    if (outputJson) {
+      const enriched = widgets.map((w) => ({ ...w, ...getWidgetContent(w) }))
+      console.log(JSON.stringify({ ...data, widgets: enriched }, null, 2))
+    } else {
+      console.log(`\n${bold(data.title || canvasName)} ${dim(`(${widgets.length} widgets)`)}\n`)
+
+      if (widgets.length === 0) {
+        console.log('  No widgets on this canvas.\n')
+      } else {
+        for (const widget of widgets) {
+          console.log(formatWidget(widget))
+          console.log('')
+        }
+      }
+    }
+  } catch (err) {
+    p.log.error(`Failed to read canvas: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+canvasRead()

package/src/cli/code.js

@@ -0,0 +1,67 @@
+/**
+ * storyboard code [branch] — Open a worktree in VS Code.
+ *
+ * Usage:
+ *   storyboard code              # open current worktree or repo root
+ *   storyboard code main         # open repo root
+ *   storyboard code <branch>     # open .worktrees/<branch>/
+ */
+
+import * as p from '@clack/prompts'
+import { execFileSync } from 'child_process'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+import { detectWorktreeName, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
+
+const branch = process.argv[3] || undefined
+
+p.intro('storyboard code')
+
+function openInCode(dir) {
+  try {
+    execFileSync('code', [dir], { stdio: 'inherit' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const root = repoRoot()
+
+if (!branch) {
+  // No argument — open current directory
+  const name = detectWorktreeName()
+  const dir = name === 'main' ? root : worktreeDir(name)
+  if (openInCode(dir)) {
+    p.outro(`Opened ${name === 'main' ? 'repo root' : `.worktrees/${name}/`}`)
+  } else {
+    p.log.error('Could not open VS Code. Is the `code` CLI installed?')
+    p.log.info('Run `npx storyboard setup` to install it, or open VS Code and run:')
+    p.log.info('  Cmd+Shift+P → "Shell Command: Install \'code\' command in PATH"')
+    process.exit(1)
+  }
+} else if (branch === 'main') {
+  if (openInCode(root)) {
+    p.outro('Opened repo root')
+  } else {
+    p.log.error('Could not open VS Code.')
+    process.exit(1)
+  }
+} else {
+  const dir = worktreeDir(branch)
+  if (!existsSync(resolve(dir, '.git'))) {
+    // List available worktrees as a hint
+    const available = listWorktrees()
+    p.log.error(`Worktree "${branch}" does not exist.`)
+    if (available.length > 0) {
+      p.log.info(`Available worktrees: ${available.join(', ')}`)
+    }
+    process.exit(1)
+  }
+  if (openInCode(dir)) {
+    p.outro(`Opened .worktrees/${branch}/`)
+  } else {
+    p.log.error('Could not open VS Code.')
+    process.exit(1)
+  }
+}

package/src/cli/dev-helpers.js

@@ -0,0 +1,47 @@
+/**
+ * Git helpers for storyboard dev CLI.
+ * Extracted for testability — no side effects on import.
+ */
+
+import { execFileSync } from 'child_process'
+
+/**
+ * Check if the working tree has uncommitted changes (staged or unstaged).
+ */
+export function hasUncommittedChanges(cwd) {
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim()
+    return status.length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a local branch exists.
+ */
+export function localBranchExists(name, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', `refs/heads/${name}`], { cwd, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Resolve the default branch for the repo root (main, master, or origin/HEAD target).
+ * Returns null if none can be determined.
+ */
+export function resolveDefaultBranch(cwd) {
+  for (const candidate of ['main', 'master']) {
+    if (localBranchExists(candidate, cwd)) return candidate
+  }
+  // Try origin/HEAD
+  try {
+    const ref = execFileSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], { cwd, encoding: 'utf8' }).trim()
+    const name = ref.replace('refs/remotes/origin/', '')
+    if (name && localBranchExists(name, cwd)) return name
+  } catch { /* no origin/HEAD */ }
+  return null
+}

package/src/cli/dev-helpers.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+import { hasUncommittedChanges, localBranchExists, resolveDefaultBranch } from './dev-helpers.js'
+import { execSync } from 'child_process'
+
+// These tests run against the real git repo — they verify the helpers
+// work correctly with actual git state.
+
+const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim()
+
+describe('hasUncommittedChanges', () => {
+  it('returns a boolean', () => {
+    const result = hasUncommittedChanges(repoRoot)
+    expect(typeof result).toBe('boolean')
+  })
+
+  it('returns false for non-existent directory', () => {
+    expect(hasUncommittedChanges('/tmp/nonexistent-repo-12345')).toBe(false)
+  })
+})
+
+describe('localBranchExists', () => {
+  it('returns true for a branch that exists', () => {
+    // The current branch must exist
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: repoRoot, encoding: 'utf8' }).trim()
+    expect(localBranchExists(branch, repoRoot)).toBe(true)
+  })
+
+  it('returns false for a branch that does not exist', () => {
+    expect(localBranchExists('__nonexistent-branch-xyz-99999__', repoRoot)).toBe(false)
+  })
+
+  it('returns false for invalid cwd', () => {
+    expect(localBranchExists('main', '/tmp/nonexistent-repo-12345')).toBe(false)
+  })
+})
+
+describe('resolveDefaultBranch', () => {
+  it('returns a string or null', () => {
+    const result = resolveDefaultBranch(repoRoot)
+    expect(result === null || typeof result === 'string').toBe(true)
+  })
+
+  it('prefers main over master when main exists', () => {
+    // If main exists in this repo, it should be the default
+    if (localBranchExists('main', repoRoot)) {
+      expect(resolveDefaultBranch(repoRoot)).toBe('main')
+    }
+  })
+
+  it('returns null for non-git directory', () => {
+    expect(resolveDefaultBranch('/tmp')).toBe(null)
+  })
+})

package/src/cli/dev.js

@@ -1,20 +1,219 @@
 /**
- * storyboard dev — Start Vite with correct base path for the current worktree.
+ * storyboard dev [branch] — Start Vite with correct base path.
+ *
+ * Usage:
+ *   storyboard dev                 # detect worktree from cwd
+ *   storyboard dev main            # start dev for repo root
+ *   storyboard dev <worktree>      # start dev for existing worktree
+ *   storyboard dev <branch>        # auto-create worktree + start dev
  *
  * Main:   http://<devDomain>.localhost/
  * Branch: http://<devDomain>.localhost/branch--<name>/
  */
 
 import * as p from '@clack/prompts'
-import { spawn } from 'child_process'
+import { spawn, execFileSync } from 'child_process'
 import { existsSync } from 'fs'
 import { resolve } from 'path'
-import { detectWorktreeName, getPort } from '../worktree/port.js'
+import { detectWorktreeName, getPort, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
 import { generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning, reloadCaddy, readDevDomain } from './proxy.js'
 import { startRenameWatcher } from '../rename-watcher/watcher.js'
+import { parseFlags } from './flags.js'
+import { hasUncommittedChanges, localBranchExists, resolveDefaultBranch } from './dev-helpers.js'
+
+const flagSchema = {
+  port: { type: 'number', description: 'Override dev server port' },
+  create: { type: 'boolean', default: true, description: 'Allow creating worktrees/branches (disable with --no-create)' },
+}
+
+/**
+ * Check if a remote branch exists on origin.
+ * @param {string} name
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+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
+  }
+}
+
+/**
+ * Create a git worktree and install dependencies.
+ * @param {string} name — worktree/branch name
+ * @param {string} root — repo root path
+ * @param {object} opts
+ * @param {boolean} opts.newBranch — create a new branch from HEAD
+ * @returns {string} path to the new worktree directory
+ */
+function createWorktree(name, root, { newBranch = false } = {}) {
+  const targetDir = resolve(root, '.worktrees', name)
+
+  const gitArgs = newBranch
+    ? ['worktree', 'add', targetDir, '-b', name]
+    : ['worktree', 'add', targetDir, name]
+
+  p.log.step(`Creating worktree: .worktrees/${name}`)
+  execFileSync('git', gitArgs, { cwd: root, stdio: 'inherit' })
+
+  p.log.step('Installing dependencies…')
+  const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  execFileSync(npmBin, ['install'], { cwd: targetDir, stdio: 'inherit' })
+
+  getPort(name)
+  return targetDir
+}
+
+/**
+ * Resolve the target worktree for `storyboard dev [branch]`.
+ *
+ * When no argument is given and the repo root is on a non-main branch,
+ * prompts the user to convert it to a proper worktree.
+ *
+ * @param {string|undefined} branchArg — positional branch argument
+ * @param {object} opts
+ * @param {boolean} opts.allowCreate — whether creation is allowed
+ * @returns {Promise<{ worktreeName: string, targetCwd: string, created: boolean }>}
+ */
+async function resolveDevTarget(branchArg, { allowCreate = true } = {}) {
+  // No argument — detect from cwd
+  if (!branchArg) {
+    const detectedName = detectWorktreeName()
+
+    // Already in a worktree or on main — use cwd as-is
+    const root = repoRoot()
+    const realCwd = resolve(process.cwd())
+    const isAtRoot = realCwd === resolve(root)
+    if (detectedName === 'main' || !isAtRoot) {
+      return { worktreeName: detectedName, targetCwd: process.cwd(), created: false }
+    }
+
+    // Root is on a non-main branch — check for existing worktree first
+    const branch = detectedName
+    const existingDir = worktreeDir(branch)
+    if (existsSync(resolve(existingDir, '.git'))) {
+      p.log.info(`Root is on branch "${branch}" — using existing worktree`)
+      return { worktreeName: branch, targetCwd: existingDir, created: false }
+    }
+
+    // No worktree exists — prompt the user to convert
+    p.log.warning(`Root is on branch "${branch}" instead of main.`)
+    const shouldConvert = await p.confirm({
+      message: `Convert "${branch}" to a worktree? (moves branch to .worktrees/${branch}/)`,
+      initialValue: true,
+    })
+
+    if (p.isCancel(shouldConvert) || !shouldConvert) {
+      // User declined — proceed with root as-is (legacy behavior)
+      return { worktreeName: detectedName, targetCwd: process.cwd(), created: false }
+    }
+
+    // User accepted — validate and convert
+    if (!allowCreate) {
+      p.log.error('Cannot convert — --no-create flag is set.')
+      process.exit(1)
+    }
+
+    if (hasUncommittedChanges(root)) {
+      p.log.error('Cannot convert — uncommitted changes in working tree.')
+      p.log.info('Commit or stash your changes first, then run `sb dev` again.')
+      process.exit(1)
+    }
+
+    const defaultBranch = resolveDefaultBranch(root)
+    if (!defaultBranch) {
+      p.log.error('Cannot determine default branch (main/master). Switch root manually.')
+      process.exit(1)
+    }
+
+    p.log.step(`Switching root to "${defaultBranch}"`)
+    execFileSync('git', ['checkout', defaultBranch], { cwd: root, stdio: 'inherit' })
+
+    const targetDir = createWorktree(branch, root, { newBranch: false })
+
+    // Offer to open the new worktree in VS Code
+    const shouldOpen = await p.confirm({
+      message: 'Open this worktree in VS Code?',
+      initialValue: true,
+    })
+    if (shouldOpen && !p.isCancel(shouldOpen)) {
+      try {
+        execFileSync('code', [targetDir], { stdio: 'inherit' })
+      } catch {
+        p.log.warning(`Could not open VS Code. Run: code ${targetDir}`)
+      }
+    }
+
+    return { worktreeName: branch, targetCwd: targetDir, created: true }
+  }
+
+  const root = repoRoot()
+
+  // "main" → repo root
+  if (branchArg === 'main') {
+    return { worktreeName: 'main', targetCwd: root, created: false }
+  }
+
+  // Existing worktree directory
+  const existingDir = worktreeDir(branchArg)
+  if (existsSync(resolve(existingDir, '.git'))) {
+    return { worktreeName: branchArg, targetCwd: existingDir, created: false }
+  }
+
+  // From here on we need to create — check if allowed
+  if (!allowCreate) {
+    p.log.error(`Worktree "${branchArg}" does not exist. Use without --no-create to auto-create.`)
+    process.exit(1)
+  }
+
+  // Branch exists (local or remote) — create worktree from it
+  const hasLocal = localBranchExists(branchArg, root)
+  const hasRemote = !hasLocal && remoteBranchExists(branchArg, root)
+
+  if (hasLocal || hasRemote) {
+    const targetDir = createWorktree(branchArg, root, { newBranch: false })
+    return { worktreeName: branchArg, targetCwd: targetDir, created: true }
+  }
+
+  // Branch doesn't exist — interactive TTY gets a prompt, non-interactive auto-creates
+  const isTTY = process.stdin.isTTY
+
+  if (isTTY) {
+    const confirmed = await p.confirm({
+      message: `Branch "${branchArg}" doesn't exist. Create it from HEAD?`,
+    })
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.cancel('Cancelled.')
+      process.exit(0)
+    }
+  } else {
+    p.log.step(`Branch "${branchArg}" not found — creating from HEAD`)
+  }
+
+  const targetDir = createWorktree(branchArg, root, { newBranch: true })
+  return { worktreeName: branchArg, targetCwd: targetDir, created: true }
+}
 
 async function main() {
-  const worktreeName = detectWorktreeName()
+  const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+
+  const branchArg = positional[0] || undefined
+  const overridePort = flags.port || null
+  const allowCreate = flags.create
+
+  p.intro('storyboard dev')
+
+  const { worktreeName, targetCwd, created } = await resolveDevTarget(branchArg, { allowCreate })
+
+  if (created) {
+    p.log.success(`Worktree ready: .worktrees/${worktreeName}`)
+  } else if (branchArg) {
+    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `.worktrees/${worktreeName}`}`)
+  }
+
   const port = getPort(worktreeName)
   const isMain = worktreeName === 'main'
 
@@ -22,42 +221,31 @@ async function main() {
     ? '/'
     : `/branch--${worktreeName}/`
 
-  const domain = readDevDomain()
+  const domain = readDevDomain(targetCwd)
   const proxyUrl = `http://${domain}${basePath}`
   const directUrl = `http://localhost:${port}${basePath}`
 
-  p.intro('storyboard dev')
-
-  // Parse --port override from argv (skip 'dev' subcommand)
-  const args = process.argv.slice(3)
-  const portFlagIdx = args.indexOf('--port')
-  const overridePort = portFlagIdx >= 0 ? Number(args[portFlagIdx + 1]) : null
-
-  const extraArgs = args.filter((arg, i, arr) => {
-    if (arg === '--port') return false
-    if (i > 0 && arr[i - 1] === '--port') return false
-    return true
-  })
-
-  // Resolve Vite binary directly to skip npx overhead (~5s)
-  const localVite = resolve(process.cwd(), 'node_modules', '.bin', 'vite')
+  // Resolve Vite binary relative to target worktree
+  const localVite = resolve(targetCwd, 'node_modules', '.bin', 'vite')
   const useLocalVite = existsSync(localVite)
 
   // Start Vite — let it find a free port if assigned one is busy.
   // Capture stdout to detect actual port and update Caddy.
-  const viteArgs = ['--port', String(overridePort || port), ...extraArgs]
+  const viteArgs = ['--port', String(overridePort || port)]
   const child = useLocalVite
     ? spawn(localVite, viteArgs, {
+        cwd: targetCwd,
         env: { ...process.env, VITE_BASE_PATH: basePath },
         stdio: ['inherit', 'pipe', 'pipe'],
       })
     : spawn('npx', ['vite', ...viteArgs], {
+        cwd: targetCwd,
         env: { ...process.env, VITE_BASE_PATH: basePath },
         stdio: ['inherit', 'pipe', 'pipe'],
       })
 
-  // Start rename watcher after Vite spawn (no need to block startup)
-  const renameWatcher = startRenameWatcher(process.cwd())
+  // Start rename watcher in target directory
+  const renameWatcher = startRenameWatcher(targetCwd)
 
   let caddyUpdated = false
   let ready = false

package/src/cli/index.js

@@ -70,6 +70,8 @@ function helpScreen(version) {
     '',
     `  ${bold(cyan('Development'))}`,
     cmd('dev', 'Start Vite dev server + update proxy'),
+    cmd('dev [branch]', 'Start dev for a specific worktree/branch'),
+    cmd('code [branch]', 'Open a worktree in VS Code'),
     cmd('exit', 'Stop all dev servers and proxy'),
     '',
     `  ${bold(cyan('Create'))}`,
@@ -82,6 +84,7 @@ function helpScreen(version) {
     `  ${bold(cyan('Canvas'))}`,
     cmd('canvas add <type>', 'Add widget to a canvas'),
     `                              ${dim('types: sticky-note, markdown, prototype')}`,
+    cmd('canvas read [name]', 'Read canvas state and list widgets'),
     '',
     `  ${bold(cyan('Setup'))}`,
     cmd('setup', 'Install deps, Caddy proxy, start proxy'),
@@ -119,6 +122,8 @@ switch (command) {
   case 'canvas':
     if (process.argv[3] === 'add') {
       import('./canvasAdd.js')
+    } else if (process.argv[3] === 'read' || !process.argv[3]) {
+      import('./canvasRead.js')
     } else {
       const version = getVersion()
       console.log(helpScreen(version))
@@ -129,6 +134,9 @@ switch (command) {
   case 'exit':
     import('./exit.js')
     break
+  case 'code':
+    import('./code.js')
+    break
   default: {
     if (command === 'update' || (command && command.startsWith('update:'))) {
       import('./updateVersion.js')

package/src/cli/proxy.js

@@ -14,9 +14,9 @@ import { execSync } from 'child_process'
 import { dirname, resolve } from 'path'
 import { portsFilePath } from '../worktree/port.js'
 
-export function readDevDomain() {
+export function readDevDomain(cwd) {
   try {
-    const configPath = resolve(process.cwd(), 'storyboard.config.json')
+    const configPath = resolve(cwd || process.cwd(), 'storyboard.config.json')
     const config = JSON.parse(readFileSync(configPath, 'utf8'))
     return `${config.devDomain || 'storyboard'}.localhost`
   } catch {
@@ -130,21 +130,73 @@ export function generateRouteConfig(portOverrides = {}) {
   }
 }
 
+/**
+ * Find indices of stale routes that match the same host but lack an @id.
+ * Returns indices sorted descending (highest first) for safe deletion.
+ * Exported for testing.
+ */
+export function findStaleRouteIndices(routes, keepId, host) {
+  const indices = []
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i]
+    if (route['@id'] === keepId) continue
+    if (route['@id']) continue // different intentional route — leave it
+    const routeHosts = route.match?.[0]?.host || []
+    if (routeHosts.includes(host)) {
+      indices.push(i)
+    }
+  }
+  return indices.reverse()
+}
+
+/**
+ * Remove stale routes that match the same host but lack an @id.
+ * These are leftovers from Caddyfile reloads that shadow admin-API routes.
+ * Deletes from highest index to lowest to preserve indices during removal.
+ * Best-effort — warns on failure but does not throw.
+ */
+function cleanupDuplicateRoutes(keepId, host) {
+  try {
+    const config = execSync(
+      `curl -sf '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes'`,
+      { encoding: 'utf-8', timeout: 5000 },
+    )
+    const routes = JSON.parse(config)
+    const staleIndices = findStaleRouteIndices(routes, keepId, host)
+    for (const idx of staleIndices) {
+      try {
+        execSync(
+          `curl -sf -X DELETE '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes/${idx}'`,
+          { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
+        )
+      } catch {
+        console.warn(`[storyboard] failed to remove stale proxy route at index ${idx}`)
+      }
+    }
+  } catch {
+    console.warn('[storyboard] failed to clean up stale proxy routes — branch URLs may not work via proxy')
+  }
+}
+
 /**
  * Upsert this repo's route in the running Caddy instance via admin API.
  * Uses PATCH if the @id exists, POST if it doesn't.
+ * After a successful upsert, removes any stale non-@id routes for the
+ * same host (leftovers from prior Caddyfile reloads).
  * Returns true on success, false on failure.
  */
 export function upsertCaddyRoute(routeConfig) {
   const id = routeConfig['@id']
+  const host = routeConfig.match?.[0]?.host?.[0]
   const payload = JSON.stringify(routeConfig)
 
   // Try PATCH first (update existing route by @id)
   try {
-    const patchResult = execSync(
+    execSync(
       `curl -sf -X PATCH '${CADDY_ADMIN}/id/${id}' -H 'Content-Type: application/json' -d '${payload.replace(/'/g, "'\\''")}'`,
       { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
     )
+    if (host) cleanupDuplicateRoutes(id, host)
     return true
   } catch {
     // @id doesn't exist yet — POST a new route
@@ -153,6 +205,7 @@ export function upsertCaddyRoute(routeConfig) {
         `curl -sf -X POST '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes' -H 'Content-Type: application/json' -d '${payload.replace(/'/g, "'\\''")}'`,
         { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
       )
+      if (host) cleanupDuplicateRoutes(id, host)
       return true
     } catch {
       return false

package/src/cli/proxy.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import { findStaleRouteIndices } from './proxy.js'
+
+describe('findStaleRouteIndices', () => {
+  it('identifies stale non-@id routes matching the same host', () => {
+    const routes = [
+      { match: [{ host: ['storyboard.localhost'] }], terminal: true }, // index 0: stale
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] }, // index 1: ours
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([0])
+  })
+
+  it('preserves routes with a different @id for the same host', () => {
+    const routes = [
+      { '@id': 'other-app', match: [{ host: ['storyboard.localhost'] }] },
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('returns multiple stale indices in descending order', () => {
+    const routes = [
+      { match: [{ host: ['storyboard.localhost'] }] }, // index 0: stale
+      { '@id': 'storyboard-core', match: [{ host: ['storyboard-core.localhost'] }] }, // index 1: different host
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] }, // index 2: ours
+      { match: [{ host: ['storyboard.localhost'] }] }, // index 3: stale
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([3, 0]) // descending for safe deletion
+  })
+
+  it('ignores routes for a different host', () => {
+    const routes = [
+      { match: [{ host: ['other.localhost'] }] },
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('handles routes with no match field', () => {
+    const routes = [
+      { handle: [{ handler: 'reverse_proxy' }] }, // no match
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('returns empty array when no stale routes exist', () => {
+    const routes = [
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('handles empty routes array', () => {
+    expect(findStaleRouteIndices([], 'storyboard', 'storyboard.localhost')).toEqual([])
+  })
+})

package/src/cli/setup.js

@@ -114,7 +114,47 @@ if (hasBrew) {
   }
 }
 
-// 5. Proxy
+// 5. VS Code CLI
+if (isInstalled('code')) {
+  p.log.success('VS Code CLI installed')
+} else {
+  // Try to install the `code` CLI from VS Code's known locations
+  const codePaths = [
+    '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+    '/usr/local/bin/code',
+  ]
+  let installed = false
+  for (const codePath of codePaths) {
+    if (existsSync(codePath)) {
+      p.log.success('VS Code CLI available (symlink exists)')
+      installed = true
+      break
+    }
+  }
+  if (!installed) {
+    // Try the VS Code shell command installer
+    const vsCodeApp = '/Applications/Visual Studio Code.app'
+    if (existsSync(vsCodeApp)) {
+      const shellScript = `${vsCodeApp}/Contents/Resources/app/bin/code`
+      if (existsSync(shellScript)) {
+        try {
+          // Create symlink in /usr/local/bin
+          run(`ln -sf "${shellScript}" /usr/local/bin/code`)
+          p.log.success('VS Code CLI installed (symlinked to /usr/local/bin/code)')
+          installed = true
+        } catch {
+          // Fall through to manual instructions
+        }
+      }
+    }
+    if (!installed) {
+      p.log.warning('VS Code CLI not found. Open VS Code and run:')
+      p.log.info('  Cmd+Shift+P → "Shell Command: Install \'code\' command in PATH"')
+    }
+  }
+}
+
+// 6. Proxy
 if (isCaddyInstalled()) {
   const proxySpin = p.spinner()
   const caddyfilePath = generateCaddyfile()

package/src/cli/updateVersion.js

@@ -79,18 +79,28 @@ try {
   p.log.warn('Scaffold sync failed — run `npx storyboard-scaffold` manually')
 }
 
-// Auto-commit the version update
+// Auto-commit the version update (only if package.json or lock file changed)
 try {
   // Read the installed version from the core package
   const corePkg = JSON.parse(readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard-core', 'package.json'), 'utf8'))
   const installedVersion = corePkg.version || suffix.slice(1)
   const commitMsg = `[storyboard-update] Update storyboard to ${installedVersion}`
 
-  execSync('git add -A', { cwd: process.cwd(), stdio: 'pipe' })
+  // Only stage update-related files (package.json, lock files, scaffold outputs)
+  const filesToStage = [
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    '.github/skills',
+    'scripts',
+  ]
+  execSync(`git add ${filesToStage.join(' ')} 2>/dev/null || true`, { cwd: process.cwd(), stdio: 'pipe' })
+
   // Only commit if there are staged changes
   try {
     execSync('git diff --cached --quiet', { cwd: process.cwd(), stdio: 'pipe' })
-    p.log.message('No changes to commit')
+    p.log.message('No changes to commit — already up to date')
   } catch {
     execSync(`git commit -m "${commitMsg}"`, { cwd: process.cwd(), stdio: 'pipe' })
     p.log.success(`Committed: ${commitMsg}`)

package/src/worktree/port.js

@@ -11,7 +11,7 @@
  *   import { getPort, detectWorktreeName, resolvePort } from '@dfosco/storyboard-core/worktree/port'
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, realpathSync } from 'fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from 'fs'
 import { join, dirname, basename } from 'path'
 import { execSync } from 'child_process'
 
@@ -60,6 +60,10 @@ export function detectWorktreeName() {
     const worktreeMatch = realCwd.match(/\.worktrees[/\\]([^/\\]+)/)
     if (worktreeMatch) return worktreeMatch[1]
 
+    // Not a worktree — check the current branch name
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim()
+    if (branch && branch !== 'main' && branch !== 'master') return branch
+
     return 'main'
   } catch {
     return 'main'
@@ -138,3 +142,55 @@ export function slugify(name) {
     .map((s) => s.replace(/^-+|-+$/g, ''))
     .join('/')
 }
+
+/**
+ * Resolve the repo root — the directory that contains `.worktrees/`.
+ *
+ * Works whether cwd is the repo root itself or inside `.worktrees/<name>/`.
+ *
+ * @param {string} [cwd]
+ * @returns {string} absolute path to repo root
+ */
+export function repoRoot(cwd = process.cwd()) {
+  const realCwd = realpathSync(cwd)
+
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  if (worktreeMatch) return worktreeMatch[1]
+
+  return realCwd
+}
+
+/**
+ * Resolve the full path to a worktree directory.
+ *
+ * Returns repo root for 'main', `.worktrees/<name>` otherwise.
+ *
+ * @param {string} name — worktree name
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function worktreeDir(name, cwd) {
+  const root = repoRoot(cwd)
+  if (name === 'main') return root
+  return join(root, '.worktrees', name)
+}
+
+/**
+ * List existing worktree directory names from `.worktrees/`.
+ *
+ * Only returns directories that look like real worktrees (contain a `.git` file).
+ * Does not include 'main'.
+ *
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function listWorktrees(cwd) {
+  const root = repoRoot(cwd)
+  const worktreesDir = join(root, '.worktrees')
+
+  if (!existsSync(worktreesDir)) return []
+
+  return readdirSync(worktreesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(worktreesDir, d.name, '.git')))
+    .map((d) => d.name)
+}

package/src/worktree/port.test.js

@@ -4,7 +4,7 @@ import { join } from 'path'
 import { tmpdir } from 'os'
 
 // We test the pure functions by importing and overriding cwd
-import { portsFilePath, getPort, resolvePort, slugify } from './port.js'
+import { portsFilePath, getPort, resolvePort, slugify, repoRoot, worktreeDir, listWorktrees } from './port.js'
 
 describe('slugify', () => {
   it('lowercases and replaces dots with hyphens', () => {
@@ -130,3 +130,93 @@ describe('getPort / resolvePort', () => {
     expect(port).toBe(1235)
   })
 })
+
+describe('repoRoot', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-root-test-')))
+    mkdirSync(join(tempRoot, '.worktrees', 'my-branch'), { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns cwd when at repo root', () => {
+    expect(repoRoot(tempRoot)).toBe(tempRoot)
+  })
+
+  it('returns parent of .worktrees when inside a worktree', () => {
+    const wt = join(tempRoot, '.worktrees', 'my-branch')
+    expect(repoRoot(wt)).toBe(tempRoot)
+  })
+})
+
+describe('worktreeDir', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-wtdir-test-')))
+    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns repo root for main', () => {
+    expect(worktreeDir('main', tempRoot)).toBe(tempRoot)
+  })
+
+  it('returns .worktrees/<name> for branches', () => {
+    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, '.worktrees', 'my-feature'))
+  })
+})
+
+describe('listWorktrees', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-list-test-')))
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns empty array when .worktrees does not exist', () => {
+    expect(listWorktrees(tempRoot)).toEqual([])
+  })
+
+  it('returns only directories with a .git file', () => {
+    const wtDir = join(tempRoot, '.worktrees')
+    mkdirSync(wtDir)
+
+    // Valid worktree — has .git file
+    mkdirSync(join(wtDir, 'valid'))
+    writeFileSync(join(wtDir, 'valid', '.git'), 'gitdir: /some/path')
+
+    // Not a worktree — no .git file
+    mkdirSync(join(wtDir, 'no-git'))
+
+    // Not a directory — file
+    writeFileSync(join(wtDir, 'ports.json'), '{}')
+
+    const result = listWorktrees(tempRoot)
+    expect(result).toEqual(['valid'])
+  })
+
+  it('returns multiple worktrees', () => {
+    const wtDir = join(tempRoot, '.worktrees')
+    mkdirSync(wtDir)
+
+    for (const name of ['alpha', 'beta', 'gamma']) {
+      mkdirSync(join(wtDir, name))
+      writeFileSync(join(wtDir, name, '.git'), 'gitdir: /some/path')
+    }
+
+    const result = listWorktrees(tempRoot)
+    expect(result.sort()).toEqual(['alpha', 'beta', 'gamma'])
+  })
+})

package/widgets.config.json

@@ -495,12 +495,11 @@
             {
               "action": "copy-as-png",
               "label": "$label:copy-png",
-              "icon": "copy"
-            },
-            {
-              "action": "copy-file-path",
-              "label": "$label:copy-path",
-              "icon": "link"
+              "icon": "copy",
+              "alt": {
+                "label": "$label:copy-path",
+                "action": "copy-file-path"
+              }
             }
           ]
         },