@dfosco/storyboard-react 4.2.0-beta.2 → 4.2.0-beta.20

package/src/story/ComponentSetPage.module.css

@@ -0,0 +1,121 @@
+/* ComponentSetPage — grid layout for all exports of a story */
+
+.grid {
+  background-color: var(--bgColor-muted, #f6f8fa);
+  display: flex;
+  flex-wrap: nowrap;
+  gap: 12px;
+  padding: 12px;
+  min-height: 100vh;
+  width: max-content;
+  min-width: 100%;
+  box-sizing: border-box;
+}
+
+.grid[data-layout="horizontal"] {
+  flex-direction: row;
+}
+
+.grid[data-layout="vertical"] {
+  flex-direction: column;
+}
+
+.cell {
+  flex: 0 0 auto;
+  display: flex;
+  flex-direction: column;
+  border: 2px solid var(--borderColor-muted, #d8dee4);
+  border-radius: 2px;
+  overflow: hidden;
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+  position: relative;
+  background: var(--bgColor-default, #ffffff);
+}
+
+/* In horizontal layout, each cell snaps to the widest component */
+.grid[data-layout="horizontal"] .cell {
+  min-width: var(--cell-snap-w, 200px);
+}
+
+/* In vertical layout, each cell snaps to the tallest component */
+.grid[data-layout="vertical"] .cell {
+  min-height: var(--cell-snap-h, 120px);
+  min-width: 100%;
+}
+
+.cell[data-selected] {
+  border-color: var(--fgColor-accent, #0969da);
+  box-shadow: 0 0 0 1px var(--fgColor-accent, #0969da);
+}
+
+.cellLabel {
+  all: unset;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--fgColor-muted, #656d76);
+  background: var(--bgColor-muted, #f6f8fa);
+  border-bottom: 1px solid var(--borderColor-muted, #d8dee4);
+  cursor: pointer;
+  user-select: none;
+  transition: background 100ms ease, color 100ms ease;
+  flex-shrink: 0;
+  /* Round top corners to match cell */
+  border-radius: 6px 6px 0 0;
+}
+
+.cellLabel:hover {
+  background: var(--bgColor-neutral-muted, #eaeef2);
+  color: var(--fgColor-default, #1f2328);
+}
+
+.cellLabel[data-selected] {
+  color: var(--fgColor-accent, #0969da);
+  background: var(--bgColor-accent-muted, #ddf4ff);
+}
+
+.cellRadio {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  border: 2px solid var(--borderColor-accent, #d8dee4);
+  flex-shrink: 0;
+  transition: border-color 100ms ease, background 100ms ease;
+}
+
+.cellRadio[data-selected] {
+  border-color: var(--fgColor-accent, #0969da);
+  background: var(--fgColor-accent, #0969da);
+}
+
+.cellContent {
+  flex: 1;
+  overflow: visible;
+  position: relative;
+}
+
+.error {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 1rem;
+  color: var(--fgColor-danger, #cf222e);
+  font-size: 0.875rem;
+  line-height: 1.5;
+}
+
+.loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 3rem;
+  color: var(--fgColor-muted, #656d76);
+  font-size: 0.875rem;
+}

package/src/story/StoryPage.jsx

@@ -5,12 +5,14 @@
  * When ?export=ExportName is present, renders that single export.
  * Without ?export, renders all named exports stacked.
  */
-import { useState, useEffect, useMemo } from 'react'
+import { useState, useEffect, useMemo, lazy, Suspense } from 'react'
 import { useLocation } from 'react-router-dom'
 import { getStoryData } from '@dfosco/storyboard-core'
 import { ThemeProvider, BaseStyles } from '@primer/react'
 import styles from './StoryPage.module.css'
 
+const ComponentSetPageLazy = lazy(() => import('./ComponentSetPage.jsx'))
+
 function StoryErrorFallback({ name, error }) {
   return (
     <div className={styles.error}>
@@ -25,12 +27,31 @@ export default function StoryPage({ name }) {
   const searchParams = new URLSearchParams(location.search)
   const exportFilter = searchParams.get('export')
   const isEmbed = searchParams.has('_sb_embed')
+  const isComponentSet = searchParams.has('_sb_component_set')
+
+  // When embedded as a canvas iframe, suppress HMR full-reloads.
+  // Story content updates via React Fast Refresh; a full-reload
+  // causes a visible flash and can create a reload loop when
+  // multiple story iframes are on the same canvas.
+  useEffect(() => {
+    if (!isEmbed || !import.meta.hot) return
+    const msg = { active: true }
+    import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+    const interval = setInterval(() => {
+      import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+    }, 3000)
+    return () => {
+      clearInterval(interval)
+      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false })
+    }
+  }, [isEmbed])
 
   const story = useMemo(() => getStoryData(name), [name])
   const [exports, setExports] = useState(null)
   const [error, setError] = useState(null)
 
   useEffect(() => {
+    if (isComponentSet) return
     if (!story?._storyImport) {
       Promise.resolve().then(() => setError(`Story "${name}" not found or missing import`))
       return
@@ -55,7 +76,7 @@ export default function StoryPage({ name }) {
       })
 
     return () => { cancelled = true }
-  }, [name, story])
+  }, [name, story, isComponentSet])
 
   // Signal snapshot-ready after story renders in embed mode.
   useEffect(() => {
@@ -67,6 +88,15 @@ export default function StoryPage({ name }) {
     })
   }, [isEmbed, exports])
 
+  // Delegate to ComponentSetPage for grid view (after all hooks)
+  if (isComponentSet) {
+    return (
+      <Suspense fallback={isEmbed ? null : <div className={styles.loading}>Loading component set…</div>}>
+        <ComponentSetPageLazy name={name} />
+      </Suspense>
+    )
+  }
+
   if (error) {
     return (
       <StoryErrorFallback name={name} error={error} />

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
@@ -526,6 +528,166 @@ 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 {
+      result[key] = sv
+    }
+  }
+  return result
+}
+
+/**
+ * Build the unified config object by reading and merging all config sources.
+ *
+ * Priority (lowest → highest):
+ *   core defaults → user widgets → user paste → user toolbar → user commandpalette → storyboard.config.json
+ *
+ * Returns { unified, warnings } where warnings is an array of overlap messages.
+ */
+function buildUnifiedConfig(root) {
+  const warnings = []
+
+  // 1. Read core defaults
+  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 user config files (priority order)
+  const userFiles = [
+    { domain: 'widgets', filename: 'widgets.config.json', priority: 1 },
+    { domain: 'paste', filename: 'paste.config.json', priority: 2 },
+    { domain: 'toolbar', filename: 'toolbar.config.json', priority: 3 },
+    { domain: 'commandPalette', filename: 'commandpalette.config.json', priority: 4 },
+  ]
+
+  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 }
+  }
+
+  // 3. Read storyboard.config.json (highest 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')) || {}
+
+  // 4. Merge core defaults with user overrides per domain
+  const toolbar = userConfigs.toolbar
+    ? deepMergeBuild(coreToolbar, userConfigs.toolbar.data)
+    : coreToolbar
+  const commandPalette = userConfigs.commandPalette
+    ? deepMergeBuild(coreCommandPalette, userConfigs.commandPalette.data)
+    : coreCommandPalette
+  const paste = userConfigs.paste
+    ? deepMergeBuild(corePaste, userConfigs.paste.data)
+    : corePaste
+  const widgets = userConfigs.widgets
+    ? deepMergeBuild(coreWidgets, userConfigs.widgets.data)
+    : coreWidgets
+
+  // 5. Apply storyboard.config.json overrides (highest priority for all domains)
+  // 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 finalToolbar = rawSbConfig.toolbar
+    ? deepMergeBuild(toolbar, sbConfig.toolbar)
+    : toolbar
+  const finalCommandPalette = rawSbConfig.commandPalette
+    ? deepMergeBuild(commandPalette, sbConfig.commandPalette)
+    : commandPalette
+
+  // 6. Detect overlaps between user config files and storyboard.config.json
+  if (rawSbConfig.toolbar && userConfigs.toolbar) {
+    const overlaps = findOverlappingKeys(userConfigs.toolbar.data, rawSbConfig.toolbar)
+    for (const key of overlaps) {
+      warnings.push(`Config overlap: "${key}" is defined in both toolbar.config.json and storyboard.config.json.toolbar — storyboard.config.json wins.`)
+    }
+  }
+  if (rawSbConfig.commandPalette && userConfigs.commandPalette) {
+    const overlaps = findOverlappingKeys(userConfigs.commandPalette.data, rawSbConfig.commandPalette)
+    for (const key of overlaps) {
+      warnings.push(`Config overlap: "${key}" is defined in both commandpalette.config.json and storyboard.config.json.commandPalette — storyboard.config.json wins.`)
+    }
+  }
+
+  // 7. Build the unified config object
+  const unified = {
+    toolbar: finalToolbar,
+    commandPalette: finalCommandPalette,
+    paste,
+    widgets,
+    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 +747,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 +866,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 +917,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 +1027,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 +1155,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 +1202,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 +1229,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 +1327,14 @@ export default function storyboardDataPlugin() {
       // Watch storyboard.config.json for changes
       const { configPath } = readConfig(root)
       watcher.add(configPath)
+
+      // Watch root toolbar.config.json for changes
+      const clientToolbarConfigPath = path.resolve(root, 'toolbar.config.json')
+      watcher.add(clientToolbarConfigPath)
+
       const invalidateConfig = (filePath) => {
-        if (path.resolve(filePath) === configPath) {
+        const resolved = path.resolve(filePath)
+        if (resolved === configPath || resolved === clientToolbarConfigPath) {
           buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
           if (mod) {
@@ -1128,19 +1364,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
 
@@ -1158,5 +1391,66 @@ export default function storyboardDataPlugin() {
   }
 }
 
+/**
+ * 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. .storyboard/terminal-snapshots/<canvasDir>/<widgetId>.json (legacy, nested)
+ *
+ * Both 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)
+      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('.') || !file.endsWith('.json')) continue
+          // Extract widgetId from filename: <widgetId>.snapshot.json
+          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)
+      }
+    },
+  }
+}
+
 // Exported for testing
 export { resolveTemplateVars, computeTemplateVars, parseDataFile }