@dfosco/storyboard 0.6.0-beta.4 → 0.6.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard",
-  "version": "0.6.0-beta.4",
+  "version": "0.6.0-beta.5",
   "type": "module",
   "license": "MIT",
   "description": "Storyboard prototyping framework — core engine, React integration, and canvas",
@@ -21,7 +21,8 @@
     "toolbar.config.json",
     "widgets.config.json",
     "paste.config.json",
-    "commandpalette.config.json"
+    "commandpalette.config.json",
+    "terminal.config.json"
   ],
   "scripts": {
     "build:css": "tailwindcss -i src/core/styles/tailwind.css -o dist/tailwind.css --minify",

package/scaffold/skills/migrate/SKILL.md

@@ -37,65 +37,81 @@ The storyboard homepage URL changed from `/viewfinder` to `/workspace`. The old
 
 #### 2. Canvas config — terminal + agents + hot pool
 
-Clients on 4.1.x likely have no `canvas` block at all. The full canvas config is required for terminal widgets, agent widgets, and prompt widgets to work on canvases.
+**As of `0.6.0-beta.4`, terminal + agent config has its own dedicated file: `terminal.config.json` at the project root.** The library ships full defaults in `node_modules/@dfosco/storyboard/terminal.config.json` and a copy is auto-scaffolded to `.storyboard/scaffold/terminal.config.json` on every dev-server boot. Most clients won't need any project-level config — the defaults already cover Copilot/Claude/Codex with auto-resume.
 
-**Read the client's `storyboard.config.json`.** If the `canvas` key is missing or incomplete, merge the missing sections. Here is the complete reference config — adapt values to the client's environment:
+**Only create a root `terminal.config.json`** if you want to override specific keys. Leaf-level merge means you set only what you change; everything else inherits the library defaults (so future agents and tweaks reach you automatically). Example minimal override:
 
 ```jsonc
 {
-  "canvas": {
-    // Terminal widget settings (the plain terminal, not agents)
-    "terminal": {
-      "fontSize": 18,
-      "fontFamily": "'SF Mono', 'Menlo', 'Monaco', 'Courier New', monospace",
-      "prompt": "❯ ",
-      "startupCommand": null,
-      "defaultStartupSequence": null,
-      "resizable": true,
-      "defaultWidth": 1000,
-      "defaultHeight": 600
-    },
+  "terminal": {
+    "fontSize": 18,
+    "fontFamily": "'Ghostty', 'SF Mono', monospace"
+  },
+  "agents": {
+    "copilot": {
+      "startupCommand": "copilot --remote --agent terminal-agent"
+    }
+  }
+}
+```
+
+**Legacy back-compat.** Existing clients with `canvas.terminal` and `canvas.agents` blocks under `storyboard.config.json` continue to work — the loader merges them with the new file (with `terminal.config.json` winning on overlap, and a warning logged). New clients should prefer `terminal.config.json` and keep `storyboard.config.json` lean.
 
-    // Agent widgets — each key becomes an entry in the "Add Agent" menu
-    // Remove any agents the client doesn't have installed
-    "agents": {
-      "copilot": {
-        "label": "Copilot CLI",
-        "default": true,
-        "icon": "primer/copilot",
-        "startupCommand": "copilot --agent terminal-agent",
-        "resumeCommand": "copilot --resume={id} --agent terminal-agent",
-        "sessionIdEnv": "COPILOT_AGENT_SESSION_ID",
-        "postStartup": "/allow-all on",
-        "readinessSignal": "Environment loaded:",
-        "resizable": true
-      },
-      "claude": {
-        "label": "Claude Code",
-        "icon": "claude",
-        "startupCommand": "claude --agent terminal-agent --dangerously-skip-permissions",
-        "resumeCommand": "claude --resume {id} --agent terminal-agent --dangerously-skip-permissions",
-        "sessionIdEnv": "CLAUDE_SESSION_ID",
-        "sessionStateGlob": "~/.claude/projects/*/{id}.jsonl",
-        "resizable": true,
-        "readinessSignal": "bypass permissions"
-      },
-      "codex": {
-        "label": "Codex CLI",
-        "icon": "codex",
-        "startupCommand": "codex --full-auto",
-        "resumeCommand": "codex resume {id}",
-        "sessionIdEnv": "CODEX_SESSION_ID",
-        "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
-        "configFiles": [".codex/config.toml"],
-        "resizable": true
-      }
+**Full reference for what `terminal.config.json` accepts** (don't copy this into a new project unless you actually need to override every key — the library ships these as defaults):
+
+```jsonc
+{
+  // Terminal widget settings (the plain terminal, not agents)
+  "terminal": {
+    "fontSize": 18,
+    "fontFamily": "'SF Mono', 'Menlo', 'Monaco', 'Courier New', monospace",
+    "prompt": "❯ ",
+    "startupCommand": null,
+    "defaultStartupSequence": null,
+    "resizable": true,
+    "defaultWidth": 1000,
+    "defaultHeight": 600
+  },
+
+  // Agent widgets — each key becomes an entry in the "Add Agent" menu
+  // Remove any agents the client doesn't have installed
+  "agents": {
+    "copilot": {
+      "label": "Copilot CLI",
+      "default": true,
+      "icon": "primer/copilot",
+      "startupCommand": "copilot --agent terminal-agent",
+      "resumeCommand": "copilot --resume={id} --agent terminal-agent",
+      "sessionIdEnv": "COPILOT_AGENT_SESSION_ID",
+      "postStartup": "/allow-all on",
+      "readinessSignal": "Environment loaded:",
+      "resizable": true
     },
+    "claude": {
+      "label": "Claude Code",
+      "icon": "claude",
+      "startupCommand": "claude --agent terminal-agent --dangerously-skip-permissions",
+      "resumeCommand": "claude --resume {id} --agent terminal-agent --dangerously-skip-permissions",
+      "sessionIdEnv": "CLAUDE_SESSION_ID",
+      "sessionStateGlob": "~/.claude/projects/*/{id}.jsonl",
+      "resizable": true,
+      "readinessSignal": "bypass permissions"
+    },
+    "codex": {
+      "label": "Codex CLI",
+      "icon": "codex",
+      "startupCommand": "codex --full-auto",
+      "resumeCommand": "codex resume {id}",
+      "sessionIdEnv": "CODEX_SESSION_ID",
+      "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
+      "configFiles": [".codex/config.toml"],
+      "resizable": true
+    }
+  },
 
-    // Set to true to show agent entries in the canvas "+" add menu
-    // Set to false to only show them in the command palette
-    "showAgentsInAddMenu": false
-  }
+  // Set to true to show agent entries in the canvas "+" add menu
+  // Set to false to only show them in the command palette
+  "showAgentsInAddMenu": false
 }
 ```
 

package/scaffold/storyboard.config.json

@@ -33,39 +33,6 @@
       "resizable": false,
       "defaultWidth": 800,
       "defaultHeight": 450
-    },
-    "agents": {
-      "copilot": {
-        "label": "Copilot CLI",
-        "default": true,
-        "icon": "primer/copilot",
-        "startupCommand": "copilot --agent terminal-agent",
-        "resumeCommand": "copilot --resume={id} --agent terminal-agent",
-        "sessionIdEnv": "COPILOT_AGENT_SESSION_ID",
-        "postStartup": "/allow-all on",
-        "readinessSignal": "Environment loaded:",
-        "resizable": true
-      },
-      "claude": {
-        "label": "Claude Code",
-        "icon": "claude",
-        "startupCommand": "claude --agent terminal-agent --dangerously-skip-permissions",
-        "resumeCommand": "claude --resume {id} --agent terminal-agent --dangerously-skip-permissions",
-        "sessionIdEnv": "CLAUDE_SESSION_ID",
-        "sessionStateGlob": "~/.claude/projects/*/{id}.jsonl",
-        "readinessSignal": "bypass permissions",
-        "resizable": true
-      },
-      "codex": {
-        "label": "Codex CLI",
-        "icon": "codex",
-        "startupCommand": "codex --ask-for-approval never",
-        "resumeCommand": "codex resume {id}",
-        "sessionIdEnv": "CODEX_SESSION_ID",
-        "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
-        "configFiles": [".codex/config.toml"],
-        "resizable": true
-      }
     }
   },
   "customerMode": {

package/src/core/canvas/agent-session.js

@@ -11,11 +11,11 @@
  *
  * A watcher on the per-widget capture file persists the captured id onto
  * the widget's terminal config as `lastAgentSessionId`. On the next cold
- * restart, the launch is rewritten to `copilot --resume=<id> --agent ...`,
- * with a pre-flight check that the session-state directory still exists
- * (copilot exits non-interactively when `--resume=<id>` doesn't match an
- * existing session, so we can't rely on `||` shell fallback — we have to
- * pre-validate).
+ * restart, the launch is rewritten to `copilot --resume=<id> --agent ...`
+ * (with a pre-flight check that the on-disk session still exists), and is
+ * shell-chained with a `|| <fresh-startup>` fallback so that if the agent
+ * CLI rejects the id at runtime the widget still ends up with a working
+ * fresh session instead of a dead terminal.
  */
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, watch as fsWatch, readdirSync, statSync } from 'node:fs'
@@ -220,7 +220,16 @@ export function buildResumeStartupCommand({ startupCommand, sessionId, agentCfg
   const template = agentCfg?.resumeCommand
   if (!template || !template.includes('{id}')) return startupCommand
 
-  return template.replace('{id}', sessionId)
+  const resumeCmd = template.replace('{id}', sessionId)
+
+  // Graceful fallback: if the resume command exits non-zero (e.g. the agent
+  // CLI rejected the id, the on-disk session is corrupt, or the binary
+  // doesn't actually support resume the way we expect), fall through to a
+  // fresh session instead of leaving the widget with a dead terminal.
+  // A clean exit (user `/exit`s) returns 0 and skips the fallback.
+  if (agentCfg?.resumeFallback === false) return resumeCmd
+  const notice = `printf '\\n\\033[33m[storyboard] resume failed; starting fresh session...\\033[0m\\n'`
+  return `${resumeCmd} || { ${notice}; ${startupCommand}; }`
 }
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i

package/src/core/canvas/agent-session.test.js

@@ -82,7 +82,7 @@ describe('agent-session', () => {
       expect(out).toBe('copilot --agent terminal-agent')
     })
 
-    it('substitutes {id} into resumeCommand when valid', () => {
+    it('substitutes {id} into resumeCommand and chains a fresh-session fallback', () => {
       const out = buildResumeStartupCommand({
         startupCommand: 'copilot --agent terminal-agent',
         sessionId: '11111111-2222-4333-8444-555555555555',
@@ -91,6 +91,21 @@ describe('agent-session', () => {
           resumeCommand: 'copilot --resume={id} --agent terminal-agent',
         },
       })
+      expect(out).toContain('copilot --resume=11111111-2222-4333-8444-555555555555 --agent terminal-agent')
+      expect(out).toContain('|| {')
+      expect(out).toContain('copilot --agent terminal-agent')
+    })
+
+    it('skips the fallback when resumeFallback: false', () => {
+      const out = buildResumeStartupCommand({
+        startupCommand: 'copilot --agent terminal-agent',
+        sessionId: '11111111-2222-4333-8444-555555555555',
+        agentCfg: {
+          sessionStateDir: null,
+          resumeCommand: 'copilot --resume={id} --agent terminal-agent',
+          resumeFallback: false,
+        },
+      })
       expect(out).toBe('copilot --resume=11111111-2222-4333-8444-555555555555 --agent terminal-agent')
     })
 

package/src/core/stores/configSchema.js

@@ -65,6 +65,7 @@
  * @property {string}  [sessionIdEnv]   — env var exposed in the agent's SessionStart hook payload that holds its session id (e.g. "COPILOT_AGENT_SESSION_ID"). When set, the server captures the id per-widget so cold restarts can auto-resume.
  * @property {string}  [sessionStateDir] — directory where the agent stores per-session state, used to pre-flight `--resume` (e.g. "~/.copilot/session-state"). Pass `null` to skip the fs check (UUID-only validation).
  * @property {string}  [sessionStateGlob] — alternative to sessionStateDir for agents that store sessions under a per-project subdir, with `{id}` placeholder (e.g. "~/.claude/projects/*‍/{id}.jsonl").
+ * @property {boolean} [resumeFallback]  — when true (default), the resume command is shell-chained with `|| <startupCommand>` so a runtime resume failure falls through to a fresh session instead of leaving the widget with a dead terminal. Set false to opt out.
  * @property {boolean} [resizable]     — override terminal resizability for this agent
  * @property {number}  [defaultWidth]  — override default width
  * @property {number}  [defaultHeight] — override default height

package/src/internals/vite/data-plugin.js

@@ -547,6 +547,90 @@ function readCoreConfigFile(root, filename) {
   return null
 }
 
+/**
+ * Resolve the absolute path of a library config file (returns the first
+ * candidate that exists, or null). Used by syncScaffoldDir to copy raw
+ * file contents (including comments) rather than re-serializing parsed JSON.
+ */
+function resolveCoreConfigFilePath(root, filename) {
+  const candidates = [
+    path.resolve(root, `packages/storyboard/${filename}`),
+    path.resolve(root, `node_modules/@dfosco/storyboard/${filename}`),
+  ]
+  for (const p of candidates) {
+    try { fs.accessSync(p); return p } catch { /* try next */ }
+  }
+  return null
+}
+
+const SCAFFOLD_README = `# .storyboard/scaffold/
+
+This directory is **always rewritten on dev-server boot** to reflect the
+library's current default config files. The Storyboard server **never reads
+config from this directory** — these files are reference copies for you to
+customize.
+
+## How to customize
+
+1. Pick the config file you want to override (e.g. \`terminal.config.json\`).
+2. **Copy it to your project root** (next to \`storyboard.config.json\`).
+3. Edit only the keys you care about — leaf-level merge means everything
+   else continues to inherit the library defaults, so future updates
+   (new agents, new readiness signals, etc.) reach you automatically.
+
+## Why a separate directory?
+
+- Customers who don't want to customize don't see config clutter at the root.
+- Customers who do want to customize have all the defaults available as a
+  living reference, version-bumped with every storyboard release.
+- Files at the root override the defaults; missing files mean "use library
+  defaults". No empty placeholder files cluttering the project.
+
+## What's in here
+
+| File | What it covers |
+|------|----------------|
+| \`terminal.config.json\` | Terminal widgets + canvas agent CLIs (copilot/claude/codex) |
+| \`toolbar.config.json\` | Toolbar tool registry + visibility |
+| \`commandpalette.config.json\` | Command palette entries |
+| \`paste.config.json\` | URL → widget paste rules |
+| \`widgets.config.json\` | Widget defaults (size, behavior) |
+
+Don't edit files in this directory — your changes will be overwritten on
+the next dev-server boot. Always copy to the project root first.
+`
+
+const SCAFFOLD_FILES = [
+  'terminal.config.json',
+  'toolbar.config.json',
+  'commandpalette.config.json',
+  'paste.config.json',
+  'widgets.config.json',
+]
+
+/**
+ * Sync `.storyboard/scaffold/` with the library's current default config
+ * files. Always overwrites — users must copy to the project root to
+ * customize. Idempotent and best-effort.
+ */
+function syncScaffoldDir(root) {
+  const scaffoldDir = path.resolve(root, '.storyboard', 'scaffold')
+  try { fs.mkdirSync(scaffoldDir, { recursive: true }) } catch { /* empty */ }
+
+  const readmePath = path.resolve(scaffoldDir, 'README.md')
+  try { fs.writeFileSync(readmePath, SCAFFOLD_README) } catch { /* empty */ }
+
+  for (const filename of SCAFFOLD_FILES) {
+    const src = resolveCoreConfigFilePath(root, filename)
+    if (!src) continue
+    const dest = path.resolve(scaffoldDir, filename)
+    try {
+      const raw = fs.readFileSync(src, 'utf-8')
+      fs.writeFileSync(dest, raw)
+    } catch { /* skip on error */ }
+  }
+}
+
 /**
  * Deep-merge helper (same as loader.js deepMerge but available at build time).
  * Arrays are replaced, not concatenated. Objects are recursively merged.
@@ -597,6 +681,7 @@ function buildUnifiedConfig(root) {
   const coreCommandPalette = readCoreConfigFile(root, 'commandpalette.config.json') || {}
   const corePaste = readCoreConfigFile(root, 'paste.config.json') || {}
   const coreWidgets = readCoreConfigFile(root, 'widgets.config.json') || {}
+  const coreTerminal = readCoreConfigFile(root, 'terminal.config.json') || {}
 
   // 2. Read storyboard.config.json (middle priority)
   // Use the schema-defaulted config for most things, but also read
@@ -619,6 +704,17 @@ function buildUnifiedConfig(root) {
   const afterSbWidgets = rawSbConfig.widgets
     ? deepMergeBuild(coreWidgets, sbConfig.widgets || {})
     : coreWidgets
+  // For terminal/agents, slot canvas.terminal + canvas.agents from storyboard.config.json
+  // into the same shape as terminal.config.json so the merge is uniform.
+  const sbTerminalLike = (rawSbConfig.canvas && (rawSbConfig.canvas.terminal || rawSbConfig.canvas.agents))
+    ? {
+        ...(rawSbConfig.canvas.terminal ? { terminal: sbConfig.canvas.terminal } : {}),
+        ...(rawSbConfig.canvas.agents ? { agents: sbConfig.canvas.agents } : {}),
+      }
+    : null
+  const afterSbTerminal = sbTerminalLike
+    ? deepMergeBuild(coreTerminal, sbTerminalLike)
+    : coreTerminal
 
   // 4. Read user domain config files (highest priority)
   const userFiles = [
@@ -626,6 +722,7 @@ function buildUnifiedConfig(root) {
     { domain: 'paste', filename: 'paste.config.json' },
     { domain: 'toolbar', filename: 'toolbar.config.json' },
     { domain: 'commandPalette', filename: 'commandpalette.config.json' },
+    { domain: 'terminal', filename: 'terminal.config.json' },
   ]
 
   const userConfigs = {}
@@ -648,6 +745,9 @@ function buildUnifiedConfig(root) {
   const finalWidgets = userConfigs.widgets
     ? deepMergeBuild(afterSbWidgets, userConfigs.widgets.data)
     : afterSbWidgets
+  const finalTerminal = userConfigs.terminal
+    ? deepMergeBuild(afterSbTerminal, userConfigs.terminal.data)
+    : afterSbTerminal
 
   // 6. Detect overlaps between storyboard.config.json and user domain configs
   const domainOverlapChecks = [
@@ -664,18 +764,32 @@ function buildUnifiedConfig(root) {
       }
     }
   }
+  // Terminal overlap check: storyboard.config.json.canvas.{terminal,agents} vs terminal.config.json
+  if (sbTerminalLike && userConfigs.terminal) {
+    const overlaps = findOverlappingKeys(sbTerminalLike, userConfigs.terminal.data)
+    for (const key of overlaps) {
+      warnings.push(`Config overlap: "${key}" is defined in both storyboard.config.json.canvas and terminal.config.json — terminal.config.json wins.`)
+    }
+  }
 
   // 7. Build the unified config object.
   // Start from the schema-defaulted sbConfig so every top-level key from
   // storyboard.config.json (and every schema default) flows to initConfig().
   // Then override the domain-specific slices that have their own dedicated
-  // config files merged above (toolbar/commandPalette/paste/widgets).
+  // config files merged above (toolbar/commandPalette/paste/widgets/terminal).
+  const sbCanvas = sbConfig?.canvas || {}
   const unified = {
-    ...sbConfig,
+    ...(sbConfig || {}),
     toolbar: finalToolbar,
     commandPalette: finalCommandPalette,
     paste: finalPaste,
     widgets: finalWidgets,
+    canvas: {
+      ...sbCanvas,
+      terminal: deepMergeBuild(sbCanvas.terminal || {}, finalTerminal.terminal || {}),
+      agents: deepMergeBuild(sbCanvas.agents || {}, finalTerminal.agents || {}),
+      ...(finalTerminal.showAgentsInAddMenu !== undefined ? { showAgentsInAddMenu: finalTerminal.showAgentsInAddMenu } : {}),
+    },
   }
 
   return { unified, warnings }
@@ -1063,6 +1177,14 @@ export default function storyboardDataPlugin() {
       // dev so users can hit their routes, excluded from production builds
       // so private experiments don't ship.
       includeTilde = config.command === 'serve'
+
+      // On dev boot, sync .storyboard/scaffold/ with the library's current
+      // default config files so users always have an up-to-date copy-source
+      // for customizations. Files in .storyboard/scaffold/ are NEVER read by
+      // the server — only files at the project root are. Always overwrites.
+      if (config.command === 'serve') {
+        try { syncScaffoldDir(root) } catch { /* best-effort */ }
+      }
     },
 
     resolveId(id) {
@@ -1209,7 +1331,7 @@ export default function storyboardDataPlugin() {
         }
 
         // Invalidate when any config file inside a prototype changes
-        const protoConfigPattern = /\/(toolbar|commandpalette|widgets|paste)\.config\.json$/
+        const protoConfigPattern = /\/(toolbar|commandpalette|widgets|paste|terminal)\.config\.json$/
         if (protoConfigPattern.test(normalized) && normalized.includes('/prototypes/')) {
           buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
@@ -1368,6 +1490,7 @@ export default function storyboardDataPlugin() {
         'commandpalette.config.json',
         'paste.config.json',
         'widgets.config.json',
+        'terminal.config.json',
       ].map(f => path.resolve(root, f))
       const watchedConfigPaths = new Set([configPath, ...domainConfigFiles])
       for (const p of domainConfigFiles) watcher.add(p)

package/terminal.config.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "./terminal.schema.json",
+  "$comment": "Defaults for terminal widgets and canvas agents. Users can override at the project root by copying this file from .storyboard/scaffold/terminal.config.json. Leaf-level merge: only the specific keys you set are overridden, everything else inherits the library defaults — so future agent additions or readinessSignal tweaks reach you automatically.",
+  "terminal": {
+    "resizable": true,
+    "defaultWidth": 1000,
+    "defaultHeight": 800,
+    "fontSize": 14,
+    "fontFamily": "'SF Mono', 'Menlo', 'Monaco', 'Courier New', monospace",
+    "prompt": "❯ ",
+    "startupCommand": null,
+    "defaultStartupSequence": null
+  },
+  "agents": {
+    "copilot": {
+      "label": "Copilot CLI",
+      "default": true,
+      "icon": "primer/copilot",
+      "startupCommand": "copilot --agent terminal-agent",
+      "resumeCommand": "copilot --resume={id} --agent terminal-agent",
+      "sessionIdEnv": "COPILOT_AGENT_SESSION_ID",
+      "postStartup": "/allow-all on",
+      "readinessSignal": "Environment loaded:",
+      "resizable": true
+    },
+    "claude": {
+      "label": "Claude Code",
+      "icon": "claude",
+      "startupCommand": "claude --agent terminal-agent --dangerously-skip-permissions",
+      "resumeCommand": "claude --resume {id} --agent terminal-agent --dangerously-skip-permissions",
+      "sessionIdEnv": "CLAUDE_SESSION_ID",
+      "sessionStateGlob": "~/.claude/projects/*/{id}.jsonl",
+      "readinessSignal": "bypass permissions",
+      "resizable": true
+    },
+    "codex": {
+      "label": "Codex CLI",
+      "icon": "codex",
+      "startupCommand": "codex --ask-for-approval never",
+      "resumeCommand": "codex resume {id}",
+      "sessionIdEnv": "CODEX_SESSION_ID",
+      "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
+      "configFiles": [".codex/config.toml"],
+      "resizable": true
+    }
+  },
+  "showAgentsInAddMenu": false
+}