@dfosco/storyboard-react 4.2.0-beta.4 → 4.2.1

package/src/vite/data-plugin.js

@@ -5,7 +5,9 @@ import { globSync } from 'glob'
 import { parse as parseJsonc } from 'jsonc-parser'
 import { materializeFromText } from '@dfosco/storyboard-core/canvas/materializer'
 import { toCanvasId } from '@dfosco/storyboard-core/canvas/identity'
+import { isCanvasWriteInFlight } from '@dfosco/storyboard-core/canvas/writeGuard'
 import { getConfig } from '@dfosco/storyboard-core/config'
+import { list as listRunningServers } from '@dfosco/storyboard-core/worktree/serverRegistry'
 
 const VIRTUAL_MODULE_ID = 'virtual:storyboard-data-index'
 const RESOLVED_ID = '\0' + VIRTUAL_MODULE_ID
@@ -47,10 +49,6 @@ function parseDataFile(filePath) {
     const canvasCheck = normalized.match(/(?:^|\/)src\/canvas\//)
     if (canvasCheck) {
       const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
-      const routeBase = (dirPath + '/')
-        .replace(/^.*?src\/canvas\//, '')
-        .replace(/[^/]*\.folder\/?/g, '')
-        .replace(/\/$/, '')
       // Path-based ID: include folder context for uniqueness.
       // .folder dirs contribute their name (sans .folder suffix) to the ID.
       const idBase = (dirPath + '/')
@@ -190,39 +188,6 @@ function parseDataFile(filePath) {
   return { name, suffix, ext: match[3], inferredRoute }
 }
 
-/**
- * Look up the git author who first created a file.
- * Used to auto-fill the author field in .prototype.json when missing.
- */
-function getGitAuthor(root, filePath) {
-  try {
-    const result = execSync(
-      `git log --follow --diff-filter=A --format="%aN" -- "${filePath}"`,
-      { cwd: root, encoding: 'utf-8', timeout: 5000 },
-    ).trim()
-    const lines = result.split('\n').filter(Boolean)
-    return lines.length > 0 ? lines[lines.length - 1] : null
-  } catch {
-    return null
-  }
-}
-
-/**
- * Look up the most recent commit date for any file in a directory.
- * Returns an ISO 8601 timestamp, or null if unavailable.
- */
-function getLastModified(root, dirPath) {
-  try {
-    const result = execSync(
-      `git log -1 --format="%aI" -- "${dirPath}"`,
-      { cwd: root, encoding: 'utf-8', timeout: 5000 },
-    ).trim()
-    return result || null
-  } catch {
-    return null
-  }
-}
-
 /**
  * Batch-fetch git metadata (author + lastModified) for multiple files in a
  * single subprocess, avoiding per-file git overhead during startup.
@@ -526,6 +491,188 @@ function readModesConfig(root) {
   return fallback
 }
 
+/**
+ * Read a JSON/JSONC file, returning null on failure.
+ */
+function readJsonFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8')
+    const errors = []
+    const parsed = parseJsonc(raw, errors)
+    return errors.length === 0 ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Find a core config file from either the monorepo workspace or node_modules.
+ */
+function readCoreConfigFile(root, filename) {
+  const candidates = [
+    path.resolve(root, `packages/core/${filename}`),
+    path.resolve(root, `node_modules/@dfosco/storyboard-core/${filename}`),
+  ]
+  for (const p of candidates) {
+    const parsed = readJsonFile(p)
+    if (parsed) return parsed
+  }
+  return null
+}
+
+/**
+ * Deep-merge helper (same as loader.js deepMerge but available at build time).
+ * Arrays are replaced, not concatenated. Objects are recursively merged.
+ */
+function deepMergeBuild(target, source) {
+  if (!source || typeof source !== 'object') return target
+  if (!target || typeof target !== 'object') return source
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    const sv = source[key]
+    const tv = target[key]
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      result[key] = deepMergeBuild(tv, sv)
+    } else if (Array.isArray(sv) && Array.isArray(tv) && sv.length > 0 && tv.length > 0 && sv[0]?.id && tv[0]?.id) {
+      // Id-based array merge: override matching entries by id, keep the rest, append new ones
+      const targetMap = new Map(tv.map(item => [item.id, item]))
+      for (const item of sv) {
+        targetMap.set(item.id, item.id && targetMap.has(item.id)
+          ? deepMergeBuild(targetMap.get(item.id), item)
+          : item)
+      }
+      result[key] = [...targetMap.values()]
+    } else {
+      result[key] = sv
+    }
+  }
+  return result
+}
+
+/**
+ * Build the unified config object by reading and merging all config sources.
+ *
+ * Priority (lowest → highest):
+ *   configSchema defaults → core domain configs → storyboard.config.json → user domain configs
+ *
+ * Domain-specific config files (toolbar.config.json, commandpalette.config.json, etc.)
+ * always win over storyboard.config.json — specificity beats generality.
+ * Deep merge is used at every layer: objects are recursively merged (keys append),
+ * arrays and scalars are replaced.
+ *
+ * Returns { unified, warnings } where warnings is an array of overlap messages.
+ */
+function buildUnifiedConfig(root) {
+  const warnings = []
+
+  // 1. Read core defaults (lowest priority domain configs)
+  const coreToolbar = readCoreConfigFile(root, 'toolbar.config.json') || {}
+  const coreCommandPalette = readCoreConfigFile(root, 'commandpalette.config.json') || {}
+  const corePaste = readCoreConfigFile(root, 'paste.config.json') || {}
+  const coreWidgets = readCoreConfigFile(root, 'widgets.config.json') || {}
+
+  // 2. Read storyboard.config.json (middle priority)
+  // Use the schema-defaulted config for most things, but also read
+  // the raw file to know which keys were explicitly set by the user.
+  const { config: sbConfig } = readConfig(root)
+  const rawSbConfig = readJsonFile(path.resolve(root, 'storyboard.config.json')) || {}
+
+  // 3. Apply storyboard.config.json overrides on top of core domain configs.
+  // Only merge when the user explicitly defined the key in storyboard.config.json
+  // (not from configSchema defaults, which would overwrite core config with empty arrays).
+  const afterSbToolbar = rawSbConfig.toolbar
+    ? deepMergeBuild(coreToolbar, sbConfig.toolbar)
+    : coreToolbar
+  const afterSbCommandPalette = rawSbConfig.commandPalette
+    ? deepMergeBuild(coreCommandPalette, sbConfig.commandPalette)
+    : coreCommandPalette
+  const afterSbPaste = rawSbConfig.paste
+    ? deepMergeBuild(corePaste, sbConfig.paste || {})
+    : corePaste
+  const afterSbWidgets = rawSbConfig.widgets
+    ? deepMergeBuild(coreWidgets, sbConfig.widgets || {})
+    : coreWidgets
+
+  // 4. Read user domain config files (highest priority)
+  const userFiles = [
+    { domain: 'widgets', filename: 'widgets.config.json' },
+    { domain: 'paste', filename: 'paste.config.json' },
+    { domain: 'toolbar', filename: 'toolbar.config.json' },
+    { domain: 'commandPalette', filename: 'commandpalette.config.json' },
+  ]
+
+  const userConfigs = {}
+  for (const { domain, filename } of userFiles) {
+    const filePath = path.resolve(root, filename)
+    const parsed = readJsonFile(filePath)
+    if (parsed) userConfigs[domain] = { data: parsed, filename }
+  }
+
+  // 5. Apply user domain configs on top of everything (highest priority)
+  const finalToolbar = userConfigs.toolbar
+    ? deepMergeBuild(afterSbToolbar, userConfigs.toolbar.data)
+    : afterSbToolbar
+  const finalCommandPalette = userConfigs.commandPalette
+    ? deepMergeBuild(afterSbCommandPalette, userConfigs.commandPalette.data)
+    : afterSbCommandPalette
+  const finalPaste = userConfigs.paste
+    ? deepMergeBuild(afterSbPaste, userConfigs.paste.data)
+    : afterSbPaste
+  const finalWidgets = userConfigs.widgets
+    ? deepMergeBuild(afterSbWidgets, userConfigs.widgets.data)
+    : afterSbWidgets
+
+  // 6. Detect overlaps between storyboard.config.json and user domain configs
+  const domainOverlapChecks = [
+    { sbKey: 'toolbar', domain: 'toolbar', label: 'toolbar.config.json' },
+    { sbKey: 'commandPalette', domain: 'commandPalette', label: 'commandpalette.config.json' },
+    { sbKey: 'paste', domain: 'paste', label: 'paste.config.json' },
+    { sbKey: 'widgets', domain: 'widgets', label: 'widgets.config.json' },
+  ]
+  for (const { sbKey, domain, label } of domainOverlapChecks) {
+    if (rawSbConfig[sbKey] && userConfigs[domain]) {
+      const overlaps = findOverlappingKeys(rawSbConfig[sbKey], userConfigs[domain].data)
+      for (const key of overlaps) {
+        warnings.push(`Config overlap: "${key}" is defined in both storyboard.config.json.${sbKey} and ${label} — ${label} wins.`)
+      }
+    }
+  }
+
+  // 7. Build the unified config object
+  const unified = {
+    toolbar: finalToolbar,
+    commandPalette: finalCommandPalette,
+    paste: finalPaste,
+    widgets: finalWidgets,
+    featureFlags: sbConfig?.featureFlags || {},
+    modes: sbConfig?.modes || {},
+    ui: sbConfig?.ui || {},
+    canvas: sbConfig?.canvas || {},
+    comments: sbConfig?.comments || {},
+    customerMode: sbConfig?.customerMode || {},
+    plugins: sbConfig?.plugins || {},
+    repository: sbConfig?.repository || {},
+    workshop: sbConfig?.workshop || {},
+  }
+
+  return { unified, warnings }
+}
+
+/**
+ * Find top-level keys that exist in both objects (overlap detection).
+ */
+function findOverlappingKeys(a, b, prefix = '') {
+  const overlaps = []
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return overlaps
+  for (const key of Object.keys(a)) {
+    if (key in b) {
+      const path = prefix ? `${prefix}.${key}` : key
+      overlaps.push(path)
+    }
+  }
+  return overlaps
+}
+
 function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasAliases, canvasGroups, storyRoutes }, root) {
   const declarations = []
   const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder', 'canvas']
@@ -585,18 +732,28 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasA
         parsed = { ...parsed, folder: protoFolders[name] }
       }
 
-      // Load toolbar.config.json from prototype directory if present
+      // Load prototype-level config overrides from the prototype directory.
+      // Any config file placed alongside the .prototype.json becomes an override
+      // for that domain when the prototype is active.
       if (suffix === 'prototype') {
         const protoDir = path.dirname(absPath)
-        const toolbarConfigPath = path.join(protoDir, 'toolbar.config.json')
-        if (fs.existsSync(toolbarConfigPath)) {
-          try {
-            const toolbarRaw = fs.readFileSync(toolbarConfigPath, 'utf-8')
-            const toolbarConfig = parseJsonc(toolbarRaw)
-            if (toolbarConfig) {
-              parsed = { ...parsed, toolbarConfig }
-            }
-          } catch { /* skip invalid toolbar config */ }
+        const protoConfigFiles = [
+          { filename: 'toolbar.config.json', key: 'toolbarConfig' },
+          { filename: 'commandpalette.config.json', key: 'commandPaletteConfig' },
+          { filename: 'widgets.config.json', key: 'widgetsConfig' },
+          { filename: 'paste.config.json', key: 'pasteConfig' },
+        ]
+        for (const { filename, key } of protoConfigFiles) {
+          const cfgPath = path.join(protoDir, filename)
+          if (fs.existsSync(cfgPath)) {
+            try {
+              const raw = fs.readFileSync(cfgPath, 'utf-8')
+              const cfg = parseJsonc(raw)
+              if (cfg) {
+                parsed = { ...parsed, [key]: cfg }
+              }
+            } catch { /* skip invalid config */ }
+          }
         }
       }
 
@@ -694,6 +851,14 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasA
   const imports = [`import { init } from '@dfosco/storyboard-core'`]
   const initCalls = [`init({ flows, objects, records, prototypes, folders, canvases, stories })`]
 
+  // Build unified config from all sources
+  const { unified: unifiedConfig, warnings: configWarnings } = buildUnifiedConfig(root)
+  for (const w of configWarnings) {
+    console.warn(`[storyboard] ⚠ ${w}`)
+  }
+  imports.push(`import { initConfig } from '@dfosco/storyboard-core'`)
+  initCalls.push(`initConfig(${JSON.stringify(unifiedConfig)})`)
+
   // Feature flags from storyboard.config.json
   const { config } = readConfig(root)
   if (config?.featureFlags && Object.keys(config.featureFlags).length > 0) {
@@ -737,6 +902,20 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasA
     initCalls.push(`initCustomerModeConfig(${JSON.stringify(config.customerMode)})`)
   }
 
+  // Client toolbar overrides from root toolbar.config.json
+  const clientToolbarPath = path.resolve(root, 'toolbar.config.json')
+  try {
+    if (fs.existsSync(clientToolbarPath)) {
+      const raw = fs.readFileSync(clientToolbarPath, 'utf-8')
+      const errors = []
+      const parsed = parseJsonc(raw, errors)
+      if (parsed && errors.length === 0) {
+        imports.push(`import { setClientToolbarOverrides } from '@dfosco/storyboard-core'`)
+        initCalls.push(`setClientToolbarOverrides(${JSON.stringify(parsed)})`)
+      }
+    }
+  } catch { /* skip if unreadable */ }
+
   // Log info when multiple flows target the same route
   const routeGroups = {}
   for (const [name, { route, isDefault }] of Object.entries(resolvedFlowRoutes)) {
@@ -833,7 +1012,7 @@ export default function storyboardDataPlugin() {
           // can't trace into its deps. Include the remark entry points so
           // Vite pre-bundles the full chain — covers all transitive CJS
           // packages (debug, extend, etc.) without whack-a-mole.
-          include: ['react-cmdk', 'remark', 'remark-gfm', 'remark-html', 'use-sync-external-store/shim', 'use-sync-external-store/shim/with-selector'],
+          include: ['cmdk', 'remark', 'remark-gfm', 'remark-html', 'use-sync-external-store/shim', 'use-sync-external-store/shim/with-selector'],
           exclude: ['@dfosco/storyboard-react'],
         },
       }
@@ -961,21 +1140,40 @@ export default function storyboardDataPlugin() {
         // custom HMR event with updated metadata so the canvas page and
         // viewfinder can react in place.
         if (/\.canvas\.jsonl$/.test(normalized)) {
-          const parsed = parseDataFile(filePath)
-          if (parsed?.suffix === 'canvas' && parsed?.id) {
-            const metadata = readCanvasMetadata(filePath, parsed)
-            server.ws.send({
-              type: 'custom',
-              event: 'storyboard:canvas-file-changed',
-              data: { canvasId: parsed.id, name: parsed.id, ...(metadata ? { metadata } : {}) },
-            })
+          // If this file change was caused by the canvas server API, it has
+          // already pushed an HMR event via pushCanvasUpdate(). Skip the
+          // duplicate watcher-triggered event to prevent stale-data rollbacks.
+          const absPath = path.resolve(root, filePath)
+          if (!isCanvasWriteInFlight(absPath)) {
+            const parsed = parseDataFile(filePath)
+            if (parsed?.suffix === 'canvas' && parsed?.id) {
+              const metadata = readCanvasMetadata(filePath, parsed)
+              server.ws.send({
+                type: 'custom',
+                event: 'storyboard:canvas-file-changed',
+                data: { canvasId: parsed.id, name: parsed.id, ...(metadata ? { metadata } : {}) },
+              })
+            }
           }
           softInvalidate()
           return
         }
 
-        // Invalidate when toolbar.config.json inside a prototype changes
-        if (normalized.endsWith('/toolbar.config.json') && normalized.includes('/prototypes/')) {
+        // Invalidate when any config file inside a prototype changes
+        const protoConfigPattern = /\/(toolbar|commandpalette|widgets|paste)\.config\.json$/
+        if (protoConfigPattern.test(normalized) && normalized.includes('/prototypes/')) {
+          buildResult = null
+          const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
+          if (mod) {
+            server.moduleGraph.invalidateModule(mod)
+            server.ws.send({ type: 'full-reload' })
+          }
+          return
+        }
+
+        // Invalidate when root toolbar.config.json changes
+        if (normalized === path.resolve(root, 'toolbar.config.json').split(path.sep).join('/') ||
+            normalized === path.resolve(root, 'toolbar.config.json')) {
           buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
           if (mod) {
@@ -989,6 +1187,20 @@ export default function storyboardDataPlugin() {
         // Also invalidate when files are added/removed inside .folder/ directories
         const inFolder = normalized.includes('.folder/')
         if (!parsed && !inFolder) return
+        // Source files inside .folder/ dirs (jsx, css, etc.) are handled by
+        // Vite's built-in HMR / React Fast Refresh — don't full-reload for them.
+        if (!parsed && inFolder) return
+
+        // Story file content changes are handled by Vite's built-in HMR
+        // (React Fast Refresh). Only soft-invalidate the virtual module so
+        // the next page load picks up updated metadata — don't full-reload,
+        // which would destroy canvas state and cause embedded iframes to
+        // reload unnecessarily.
+        if (parsed?.suffix === 'story') {
+          softInvalidate()
+          return
+        }
+
         // Rebuild index and invalidate virtual module
         buildResult = null
         const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
@@ -1002,6 +1214,9 @@ export default function storyboardDataPlugin() {
         const parsed = parseDataFile(filePath)
         const inFolder = filePath.replace(/\\/g, '/').includes('.folder/')
         if (!parsed && !inFolder) return
+        // Source files (jsx, css, etc.) inside .folder/ dirs are handled by
+        // Vite's built-in HMR — don't trigger a full-reload for them.
+        if (!parsed && inFolder) return
 
         // Canvas writers/editors can emit unlink+add for an in-place save.
         // Treat canvas add/unlink as runtime data updates and never full-reload
@@ -1097,8 +1312,20 @@ export default function storyboardDataPlugin() {
       // Watch storyboard.config.json for changes
       const { configPath } = readConfig(root)
       watcher.add(configPath)
+
+      // Watch all root domain config files for changes
+      const domainConfigFiles = [
+        'toolbar.config.json',
+        'commandpalette.config.json',
+        'paste.config.json',
+        'widgets.config.json',
+      ].map(f => path.resolve(root, f))
+      const watchedConfigPaths = new Set([configPath, ...domainConfigFiles])
+      for (const p of domainConfigFiles) watcher.add(p)
+
       const invalidateConfig = (filePath) => {
-        if (path.resolve(filePath) === configPath) {
+        const resolved = path.resolve(filePath)
+        if (watchedConfigPaths.has(resolved)) {
           buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
           if (mod) {
@@ -1128,19 +1355,16 @@ export default function storyboardDataPlugin() {
     },
 
     // Inject __SB_BRANCHES__ into HTML so the Viewfinder branch selector works.
-    // Reads .worktrees/ports.json to enumerate active worktree dev servers.
+    // Uses server registry (live running processes) instead of stale ports.json.
     transformIndexHtml(html, ctx) {
       // Only inject in dev mode
       if (!ctx.server) return html
 
       try {
-        const portsJsonPath = path.resolve(root, '.worktrees', 'ports.json')
-        if (!fs.existsSync(portsJsonPath)) return html
-
-        const ports = JSON.parse(fs.readFileSync(portsJsonPath, 'utf-8'))
-        const branches = Object.entries(ports)
-          .filter(([name]) => name !== 'main')
-          .map(([name, port]) => ({ branch: name, folder: `branch--${name}`, port }))
+        const servers = listRunningServers()
+        const branches = servers
+          .filter(srv => srv.worktree !== 'main')
+          .map(srv => ({ branch: srv.worktree, folder: `branch--${srv.worktree}`, port: srv.port }))
 
         if (branches.length === 0) return html
 
@@ -1155,6 +1379,122 @@ export default function storyboardDataPlugin() {
     buildStart() {
       buildResult = null
     },
+
+    // Emit terminal snapshots into the build so TerminalReadWidget can
+    // fetch them as static files in production (no dev-server API).
+    generateBundle() {
+      const emittedIds = new Set()
+
+      // 1. New public snapshots (flat structure) — .json and .txt
+      const publicDir = path.resolve('assets/.storyboard-public/terminal-snapshots')
+      if (fs.existsSync(publicDir)) {
+        for (const file of fs.readdirSync(publicDir)) {
+          if (file.startsWith('~') || file.startsWith('.')) continue
+          const isJson = file.endsWith('.snapshot.json')
+          const isTxt = file.endsWith('.snapshot.txt')
+          if (!isJson && !isTxt) continue
+          if (isJson) {
+            const widgetId = file.replace(/\.snapshot\.json$/, '')
+            if (widgetId) emittedIds.add(widgetId)
+          }
+          this.emitFile({
+            type: 'asset',
+            fileName: `_storyboard/terminal-snapshots/${file}`,
+            source: fs.readFileSync(path.join(publicDir, file), 'utf-8'),
+          })
+        }
+      }
+
+      // 2. Legacy snapshots (nested by canvas dir) — skip if already emitted
+      const legacyDir = path.resolve('.storyboard/terminal-snapshots')
+      if (fs.existsSync(legacyDir)) {
+        const walk = (dir) => {
+          const entries = fs.readdirSync(dir, { withFileTypes: true })
+          for (const entry of entries) {
+            const full = path.join(dir, entry.name)
+            if (entry.isDirectory()) {
+              walk(full)
+            } else if (entry.name.endsWith('.json') && !entry.name.startsWith('~')) {
+              const widgetId = entry.name.replace(/\.json$/, '')
+              if (emittedIds.has(widgetId)) continue
+              const rel = path.relative(legacyDir, full).replace(/\\/g, '/')
+              this.emitFile({
+                type: 'asset',
+                fileName: `_storyboard/terminal-snapshots/${rel}`,
+                source: fs.readFileSync(full, 'utf-8'),
+              })
+            }
+          }
+        }
+        walk(legacyDir)
+      }
+    },
+  }
+}
+
+/**
+ * Vite plugin that copies terminal snapshots into the build output
+ * so TerminalReadWidget can fetch them as static files in production.
+ *
+ * Sources (in priority order):
+ *   1. assets/.storyboard-public/terminal-snapshots/<widgetId>.snapshot.json (new, flat)
+ *   2. assets/.storyboard-public/terminal-snapshots/<widgetId>.snapshot.txt  (human-readable companion)
+ *   3. .storyboard/terminal-snapshots/<canvasDir>/<widgetId>.json (legacy, nested)
+ *
+ * All are emitted to `_storyboard/terminal-snapshots/` in the build.
+ * Tilde-prefixed files (~) are excluded (private).
+ */
+export function terminalSnapshotPlugin() {
+  return {
+    name: 'storyboard-terminal-snapshots',
+
+    generateBundle() {
+      const emittedIds = new Set()
+
+      // 1. New public snapshots (flat structure) — .json and .txt
+      const publicDir = path.resolve('assets/.storyboard-public/terminal-snapshots')
+      if (fs.existsSync(publicDir)) {
+        for (const file of fs.readdirSync(publicDir)) {
+          if (file.startsWith('~') || file.startsWith('.')) continue
+          const isJson = file.endsWith('.snapshot.json')
+          const isTxt = file.endsWith('.snapshot.txt')
+          if (!isJson && !isTxt) continue
+          if (isJson) {
+            const widgetId = file.replace(/\.snapshot\.json$/, '')
+            if (widgetId) emittedIds.add(widgetId)
+          }
+          this.emitFile({
+            type: 'asset',
+            fileName: `_storyboard/terminal-snapshots/${file}`,
+            source: fs.readFileSync(path.join(publicDir, file), 'utf-8'),
+          })
+        }
+      }
+
+      // 2. Legacy snapshots (nested by canvas dir) — skip if already emitted
+      const legacyDir = path.resolve('.storyboard/terminal-snapshots')
+      if (fs.existsSync(legacyDir)) {
+        const walk = (dir) => {
+          const entries = fs.readdirSync(dir, { withFileTypes: true })
+          for (const entry of entries) {
+            const full = path.join(dir, entry.name)
+            if (entry.isDirectory()) {
+              walk(full)
+            } else if (entry.name.endsWith('.json') && !entry.name.startsWith('~')) {
+              const widgetId = entry.name.replace(/\.json$/, '')
+              if (emittedIds.has(widgetId)) continue // new format takes priority
+              const rel = path.relative(legacyDir, full).replace(/\\/g, '/')
+              this.emitFile({
+                type: 'asset',
+                fileName: `_storyboard/terminal-snapshots/${rel}`,
+                source: fs.readFileSync(full, 'utf-8'),
+              })
+            }
+          }
+        }
+        walk(legacyDir)
+      }
+    },
   }
 }
 

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

@@ -1,4 +1,4 @@
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync, readFileSync } from 'node:fs'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import storyboardDataPlugin, { resolveTemplateVars, computeTemplateVars, parseDataFile } from './data-plugin.js'