@dfosco/storyboard-react 4.0.0-beta.4 → 4.0.0-beta.41

package/src/vite/data-plugin.js

@@ -4,12 +4,16 @@ import { execSync } from 'node:child_process'
 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 { getConfig } from '@dfosco/storyboard-core/config'
 
 const VIRTUAL_MODULE_ID = 'virtual:storyboard-data-index'
 const RESOLVED_ID = '\0' + VIRTUAL_MODULE_ID
 
 const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder}.{json,jsonc}'
 const CANVAS_GLOB_PATTERN = '**/*.canvas.jsonl'
+const CANVAS_META_GLOB_PATTERN = '**/*.meta.json'
+const STORY_GLOB_PATTERN = '**/*.story.{jsx,tsx}'
 
 /**
  * Extract the data name and type suffix from a file path.
@@ -32,7 +36,8 @@ function parseDataFile(filePath) {
     const normalized = filePath.replace(/\\/g, '/')
     if (normalized.split('/').some(seg => seg.startsWith('_'))) return null
 
-    const name = canvasJsonlMatch[1]
+    const baseName = canvasJsonlMatch[1]
+    let name = baseName
     let inferredRoute = null
     const canvasFolderMatch = normalized.match(/(?:^|\/)src\/canvas\/([^/]+)\.folder\//)
     const canvasFolderName = canvasFolderMatch ? canvasFolderMatch[1] : null
@@ -46,20 +51,83 @@ function parseDataFile(filePath) {
         .replace(/^.*?src\/canvas\//, '')
         .replace(/[^/]*\.folder\/?/g, '')
         .replace(/\/$/, '')
-      inferredRoute = '/canvas/' + (routeBase ? routeBase + '/' : '') + name
+      // Path-based ID: include folder context for uniqueness.
+      // .folder dirs contribute their name (sans .folder suffix) to the ID.
+      const idBase = (dirPath + '/')
+        .replace(/^.*?src\/canvas\//, '')
+        .replace(/\.folder\/?/g, '/')
+        .replace(/\/+/g, '/')
+        .replace(/\/$/, '')
+      name = idBase ? `${idBase}/${baseName}` : baseName
+      inferredRoute = '/canvas/' + name
       inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/canvas'
     }
     const protoCheck = normalized.match(/(?:^|\/)src\/prototypes\//)
     if (!canvasCheck && protoCheck) {
       const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
-      const routeBase = (dirPath + '/')
+      // For prototypes, .folder is purely organizational — strip entirely
+      const idBase = (dirPath + '/')
         .replace(/^.*?src\/prototypes\//, '')
         .replace(/[^/]*\.folder\/?/g, '')
+        .replace(/\/+/g, '/')
         .replace(/\/$/, '')
-      inferredRoute = '/canvas/' + (routeBase ? routeBase + '/' : '') + name
+      name = idBase ? `${idBase}/${baseName}` : baseName
+      inferredRoute = '/canvas/' + name
       inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/canvas'
     }
-    return { name, suffix: 'canvas', ext: 'jsonl', folder: canvasFolderName || folderName, inferredRoute }
+    // Derive group: canvases sharing a directory form a group
+    const slashIdx = name.lastIndexOf('/')
+    const group = canvasFolderName || (slashIdx > 0 ? name.substring(0, slashIdx) : null)
+    // Extract a relative path for toCanvasId (it expects src/canvas/... or src/prototypes/...)
+    const canvasIdInput = normalized.replace(/^.*?(src\/(?:canvas|prototypes)\/)/, '$1')
+    return { name, suffix: 'canvas', ext: 'jsonl', folder: canvasFolderName || folderName, inferredRoute, id: toCanvasId(canvasIdInput), group }
+  }
+
+  // Handle canvas .meta.json files
+  const metaMatch = base.match(/^(.+)\.meta\.json$/)
+  if (metaMatch) {
+    const normalized = filePath.replace(/\\/g, '/')
+    // Only handle meta files inside src/canvas/ directories
+    const canvasCheck = normalized.match(/(?:^|\/)src\/canvas\//)
+    if (!canvasCheck) return null
+    // Skip _-prefixed
+    if (metaMatch[1].startsWith('_')) return null
+    if (normalized.split('/').some(seg => seg.startsWith('_'))) return null
+    return { name: metaMatch[1], suffix: 'canvas-meta', ext: 'json', inferredRoute: null }
+  }
+
+  // Handle .story.jsx / .story.tsx files
+  const storyMatch = base.match(/^(.+)\.story\.(jsx|tsx)$/)
+  if (storyMatch) {
+    if (storyMatch[1].startsWith('_')) return null
+    const normalized = filePath.replace(/\\/g, '/')
+    if (normalized.split('/').some(seg => seg.startsWith('_'))) return null
+
+    const name = storyMatch[1]
+    let inferredRoute = null
+
+    // All stories route under /components/ regardless of directory location
+    const canvasCheck = normalized.match(/(?:^|\/)src\/canvas\//)
+    const componentsCheck = normalized.match(/(?:^|\/)src\/components\//)
+    if (canvasCheck) {
+      const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
+      const routeBase = (dirPath + '/')
+        .replace(/^.*?src\/canvas\//, '')
+        .replace(/[^/]*\.folder\/?/g, '')
+        .replace(/\/$/, '')
+      inferredRoute = '/components/' + (routeBase ? routeBase + '/' : '') + name
+      inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/components'
+    } else if (componentsCheck) {
+      const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
+      const routeBase = (dirPath + '/')
+        .replace(/^.*?src\/components\//, '')
+        .replace(/[^/]*\.folder\/?/g, '')
+        .replace(/\/$/, '')
+      inferredRoute = '/components/' + (routeBase ? routeBase + '/' : '') + name
+      inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/components'
+    }
+
+    return { name, suffix: 'story', ext: storyMatch[2], inferredRoute }
   }
 
   const match = base.match(/^(.+)\.(flow|scene|object|record|prototype|folder)\.(jsonc?)$/)
@@ -250,6 +318,8 @@ function buildIndex(root) {
   const ignore = ['node_modules/**', 'dist/**', '.git/**', '.worktrees/**', 'public/**']
   const files = globSync(GLOB_PATTERN, { cwd: root, ignore, absolute: false })
   const canvasFiles = globSync(CANVAS_GLOB_PATTERN, { cwd: root, ignore, absolute: false })
+  const canvasMetaFiles = globSync(CANVAS_META_GLOB_PATTERN, { cwd: root, ignore, absolute: false })
+  const storyFiles = globSync(STORY_GLOB_PATTERN, { cwd: root, ignore, absolute: false })
 
   // Detect nested .folder/ directories (not supported)
   // Scan directories directly since empty nested folders have no data files
@@ -266,35 +336,58 @@ function buildIndex(root) {
     }
   }
 
-  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {}, canvas: {} }
-  const seen = {} // "name.suffix" → absolute path (for duplicate detection)
+  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {}, canvas: {}, 'canvas-meta': {}, story: {} }
+  const seen = {} // "name.suffix" or "id.suffix" → absolute path (for duplicate detection)
   const protoFolders = {} // prototype name → folder name (for injection)
   const flowRoutes = {} // flow name → inferred route (for _route injection)
   const canvasRoutes = {} // canvas name → inferred route
+  const canvasAliases = {} // basename → canonical ID (only when unique)
+  const canvasNameCount = {} // canvas basename → count (for ambiguity detection)
+  const canvasGroups = {} // canvas name → group name (shared folder prefix)
+  const storyRoutes = {} // story name → inferred route
 
-  for (const relPath of [...files, ...canvasFiles]) {
+  for (const relPath of [...files, ...canvasFiles, ...canvasMetaFiles, ...storyFiles]) {
     const parsed = parseDataFile(relPath)
     if (!parsed) continue
 
-    const key = `${parsed.name}.${parsed.suffix}`
+    // Canvas files use path-based IDs for dedup; others use basename
+    const dedupKey = parsed.suffix === 'canvas' && parsed.id
+      ? `${parsed.id}.${parsed.suffix}`
+      : `${parsed.name}.${parsed.suffix}`
     const absPath = path.resolve(root, relPath)
 
-    if (seen[key]) {
+    if (seen[dedupKey]) {
       const hint = parsed.suffix === 'folder'
           ? '  Folder names must be unique across the project.'
+          : parsed.suffix === 'canvas'
+          ? '  Canvas IDs must be unique. Move or rename one file to resolve the collision.'
           : '  Flows, records, and objects are scoped to their prototype directory.\n' +
             '  If both files are global (outside src/prototypes/), rename one to avoid the collision.'
 
       throw new Error(
-        `[storyboard-data] Duplicate ${parsed.suffix} "${parsed.name}"\n` +
-        `  Found at: ${seen[key]}\n` +
+        `[storyboard-data] Duplicate ${parsed.suffix} "${parsed.id || parsed.name}"\n` +
+        `  Found at: ${seen[dedupKey]}\n` +
         `  And at:   ${absPath}\n` +
         hint
       )
     }
 
-    seen[key] = absPath
-    index[parsed.suffix][parsed.name] = absPath
+    seen[dedupKey] = absPath
+
+    // Canvas: index only by canonical ID. Basename aliases go in a separate map
+    // so listCanvases() and viewfinder don't show duplicates.
+    if (parsed.suffix === 'canvas' && parsed.id) {
+      index.canvas[parsed.id] = absPath
+      // Track basename for alias resolution (only when unique)
+      canvasNameCount[parsed.name] = (canvasNameCount[parsed.name] || 0) + 1
+      if (canvasNameCount[parsed.name] === 1) {
+        canvasAliases[parsed.name] = parsed.id
+      } else {
+        delete canvasAliases[parsed.name]
+      }
+    } else {
+      index[parsed.suffix][parsed.name] = absPath
+    }
 
     // Track which folder a prototype belongs to
     if (parsed.suffix === 'prototype' && parsed.folder) {
@@ -306,13 +399,26 @@ function buildIndex(root) {
       flowRoutes[parsed.name] = parsed.inferredRoute
     }
 
-    // Track inferred routes for canvases
+    // Track inferred routes for canvases (keyed by canonical ID)
     if (parsed.suffix === 'canvas' && parsed.inferredRoute) {
-      canvasRoutes[parsed.name] = parsed.inferredRoute
+      const canvasKey = parsed.id || parsed.name
+      canvasRoutes[canvasKey] = parsed.inferredRoute
+    }
+
+    // Track canvas groups (canvases sharing a folder prefix)
+    // Use canonical ID as key to match the canvas index
+    if (parsed.suffix === 'canvas' && parsed.group) {
+      const groupKey = parsed.id || parsed.name
+      canvasGroups[groupKey] = parsed.group
+    }
+
+    // Track inferred routes for stories
+    if (parsed.suffix === 'story' && parsed.inferredRoute) {
+      storyRoutes[parsed.name] = parsed.inferredRoute
     }
   }
 
-  return { index, protoFolders, flowRoutes, canvasRoutes }
+  return { index, protoFolders, flowRoutes, canvasRoutes, canvasAliases, canvasGroups, storyRoutes }
 }
 
 /**
@@ -366,7 +472,7 @@ function computeTemplateVars(absPath, root) {
  */
 /**
  * Read storyboard.config.json from the project root (if it exists).
- * Returns the parsed config object, or null if not found.
+ * Returns the parsed and defaulted config object, or null if not found.
  */
 function readConfig(root) {
   const configPath = path.resolve(root, 'storyboard.config.json')
@@ -376,7 +482,7 @@ function readConfig(root) {
     const config = parseJsonc(raw, errors)
     // Treat malformed JSON (e.g. mid-edit partial saves) as missing config
     if (errors.length > 0) return { config: null, configPath }
-    return { config, configPath }
+    return { config: getConfig(config), configPath }
   } catch {
     return { config: null, configPath }
   }
@@ -420,10 +526,11 @@ function readModesConfig(root) {
   return fallback
 }
 
-function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root) {
+function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasAliases, canvasGroups, storyRoutes }, root) {
   const declarations = []
   const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder', 'canvas']
   const entries = { flow: [], object: [], record: [], prototype: [], folder: [], canvas: [] }
+  const storyEntries = [] // handled separately (code modules, not JSON data)
   const resolvedFlowRoutes = {} // flow name → resolved route (for multi-flow logging)
   let i = 0
 
@@ -434,6 +541,21 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
   ]
   const gitMeta = batchGitMetadata(root, gitPaths)
 
+  // Read canvas-meta files and build a directory-based lookup
+  const canvasMetaByDir = {}
+  for (const [, absPath] of Object.entries(index['canvas-meta'] || {})) {
+    try {
+      const raw = fs.readFileSync(absPath, 'utf-8')
+      const parsed = parseJsonc(raw)
+      if (parsed) {
+        // Key by the parent directory path relative to src/canvas/
+        const dirPath = path.dirname(absPath).replace(/\\/g, '/')
+        const canvasRelDir = dirPath.replace(/^.*?src\/canvas\//, '')
+        canvasMetaByDir[canvasRelDir] = parsed
+      }
+    } catch { /* skip invalid meta files */ }
+  }
+
   for (const suffix of INDEX_KEYS) {
     for (const [name, absPath] of Object.entries(index[suffix])) {
       const varName = `_d${i++}`
@@ -499,11 +621,18 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
         }
       }
 
-      // Inject inferred route and resolve JSX companion for canvases
+      // Inject inferred route, group, and resolve JSX companion for canvases
       if (suffix === 'canvas') {
         if (canvasRoutes[name]) {
           parsed = { ...parsed, _route: canvasRoutes[name] }
         }
+        if (canvasGroups[name]) {
+          parsed = { ...parsed, _group: canvasGroups[name] }
+        }
+        // Inject canvas folder metadata from .meta.json
+        if (canvasGroups[name] && canvasMetaByDir[canvasGroups[name]]) {
+          parsed = { ...parsed, _canvasMeta: canvasMetaByDir[canvasGroups[name]] }
+        }
         // Inject folder association
         const folderDirMatch = path.relative(root, absPath).replace(/\\/g, '/').match(/(?:^|\/)src\/(?:prototypes|canvas)\/([^/]+)\.folder\//)
         if (folderDirMatch) {
@@ -555,8 +684,22 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
     }
   }
 
+  // Generate story entries (code modules with dynamic imports, not JSON data)
+  for (const [name, absPath] of Object.entries(index.story || {})) {
+    const varName = `_d${i++}`
+    const relModule = '/' + path.relative(root, absPath).replace(/\\/g, '/')
+    const storyMeta = { _storyModule: relModule }
+    if (storyRoutes[name]) {
+      storyMeta._route = storyRoutes[name]
+    }
+    declarations.push(
+      `const ${varName} = Object.assign(${JSON.stringify(storyMeta)}, { _storyImport: () => import(${JSON.stringify(relModule)}) })`
+    )
+    storyEntries.push(`  ${JSON.stringify(name)}: ${varName}`)
+  }
+
   const imports = [`import { init } from '@dfosco/storyboard-core'`]
-  const initCalls = [`init({ flows, objects, records, prototypes, folders, canvases })`]
+  const initCalls = [`init({ flows, objects, records, prototypes, folders, canvases, stories })`]
 
   // Feature flags from storyboard.config.json
   const { config } = readConfig(root)
@@ -624,22 +767,54 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
     `const prototypes = {\n${entries.prototype.join(',\n')}\n}`,
     `const folders = {\n${entries.folder.join(',\n')}\n}`,
     `const canvases = {\n${entries.canvas.join(',\n')}\n}`,
+    `const stories = {\n${storyEntries.join(',\n')}\n}`,
+    '',
+    `// Legacy basename → canonical ID aliases (only unique basenames)`,
+    `const canvasAliases = ${JSON.stringify(canvasAliases || {})}`,
     '',
     '// Backward-compatible alias',
     'const scenes = flows',
     '',
     initCalls.join('\n'),
     '',
-    `export { flows, scenes, objects, records, prototypes, folders, canvases }`,
-    `export const index = { flows, scenes, objects, records, prototypes, folders, canvases }`,
+    `export { flows, scenes, objects, records, prototypes, folders, canvases, canvasAliases, stories }`,
+    `export const index = { flows, scenes, objects, records, prototypes, folders, canvases, canvasAliases, stories }`,
     `export default index`,
+    '',
+    '// Live-patch canvas data on HMR events so SPA navigation shows fresh state',
+    'if (import.meta.hot) {',
+    '  import.meta.hot.on("storyboard:canvas-file-changed", (data) => {',
+    '    if (!data) return',
+    '    const id = data.canvasId || data.name',
+    '    if (data.removed) {',
+    '      delete canvases[id]',
+    '    } else if (data.metadata) {',
+    '      // Merge into existing entry to preserve build-time fields (_jsxModule, _jsxImport, etc.)',
+    '      canvases[id] = canvases[id]',
+    '        ? Object.assign({}, canvases[id], data.metadata)',
+    '        : data.metadata',
+    '    }',
+    '    init({ flows, objects, records, prototypes, folders, canvases, stories })',
+    '  })',
+    '  import.meta.hot.on("storyboard:story-file-changed", (data) => {',
+    '    if (!data) return',
+    '    if (data.removed) {',
+    '      delete stories[data.name]',
+    '    } else {',
+    '      stories[data.name] = { _storyModule: data._storyModule, _route: data._route,',
+    '        _storyImport: () => import(/* @vite-ignore */ data._storyModule) }',
+    '    }',
+    '    init({ flows, objects, records, prototypes, folders, canvases, stories })',
+    '    document.dispatchEvent(new CustomEvent("storyboard:story-index-changed"))',
+    '  })',
+    '}',
   ].join('\n')
 }
 
 /**
  * Vite plugin for storyboard data discovery.
  *
- * - Scans the repo for *.flow.json, *.scene.json (compat), *.object.json, *.record.json, *.canvas.jsonl
+ * - Scans the repo for *.flow.json, *.scene.json (compat), *.object.json, *.record.json, *.canvas.jsonl, *.story.{jsx,tsx}
  * - Validates no two files share the same name+suffix (hard build error)
  * - Generates a virtual module `virtual:storyboard-data-index`
  * - Watches for file additions/removals in dev mode
@@ -655,6 +830,11 @@ export default function storyboardDataPlugin() {
     config() {
       return {
         optimizeDeps: {
+          // @dfosco/storyboard-react is excluded (virtual module), so Vite
+          // 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: ['remark', 'remark-gfm', 'remark-html', 'use-sync-external-store/shim', 'use-sync-external-store/shim/with-selector'],
           exclude: ['@dfosco/storyboard-react'],
         },
       }
@@ -675,10 +855,68 @@ export default function storyboardDataPlugin() {
     },
 
     configureServer(server) {
+      // ── Component isolate middleware ───────────────────────────────
+      // Serves a minimal HTML shell for iframe-isolated component widgets.
+      // The iframe loads componentIsolate.jsx which reads query params
+      // (module, export, theme) and renders a single canvas.jsx export.
+      const isolateEntryPath = new URL('../canvas/componentIsolate.jsx', import.meta.url).pathname
+      server.middlewares.use(async (req, res, next) => {
+        if (!req.url) return next()
+        let url = req.url
+        const baseNoTrail = (server.config.base || '/').replace(/\/$/, '')
+        if (baseNoTrail && url.startsWith(baseNoTrail)) {
+          url = url.slice(baseNoTrail.length) || '/'
+        }
+        if (!url.startsWith('/_storyboard/canvas/isolate')) return next()
+
+        const rawHtml = [
+          '<!DOCTYPE html>',
+          '<html><head>',
+          '<style>html,body{margin:0;padding:0;width:100%;height:100%;background:var(--bgColor-default,transparent)}#root{width:100%;height:100%}</style>',
+          '</head><body>',
+          '<div id="root"></div>',
+          `<script type="module" src="/@fs${isolateEntryPath}"></script>`,
+          '</body></html>',
+        ].join('\n')
+
+        try {
+          const html = await server.transformIndexHtml(req.url, rawHtml)
+          res.writeHead(200, { 'Content-Type': 'text/html' })
+          res.end(html)
+        } catch (err) {
+          console.error('[storyboard] Component isolate HTML transform failed:', err)
+          res.writeHead(500, { 'Content-Type': 'text/plain' })
+          res.end('Component isolate failed')
+        }
+      })
+
+      // ── Stories list API ──────────────────────────────────────────
+      // Serves the list of discovered stories for the CLI and UI story picker.
+      server.middlewares.use(async (req, res, next) => {
+        if (!req.url) return next()
+        let url = req.url
+        const baseNoTrail = (server.config.base || '/').replace(/\/$/, '')
+        if (baseNoTrail && url.startsWith(baseNoTrail)) {
+          url = url.slice(baseNoTrail.length) || '/'
+        }
+        if (!url.startsWith('/_storyboard/stories/list')) return next()
+
+        if (!buildResult) buildResult = buildIndex(root)
+        const storyEntries = Object.entries(buildResult.index.story || {})
+        const storyRoutes = buildResult.storyRoutes || {}
+        const stories = storyEntries.map(([name]) => ({
+          name,
+          route: storyRoutes[name] || null,
+        }))
+
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ stories }))
+      })
+
       // Watch for data file changes in dev mode
       const watcher = server.watcher
       if (!buildResult) buildResult = buildIndex(root)
-      const knownCanvasNames = new Set(Object.keys(buildResult.index.canvas || {}))
+      const knownCanvasIds = new Set(Object.keys(buildResult.index.canvas || {}))
       const pendingCanvasUnlinks = new Map()
 
       const triggerFullReload = () => {
@@ -690,22 +928,50 @@ export default function storyboardDataPlugin() {
         }
       }
 
+      // Mark the virtual module as stale so the next page load rebuilds it,
+      // but do NOT trigger a full-reload (avoids losing canvas editing state).
+      const softInvalidate = () => {
+        buildResult = null
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
+        if (mod) server.moduleGraph.invalidateModule(mod)
+      }
+
+      // Read a canvas file and build HMR metadata for the client-side listener.
+      const readCanvasMetadata = (filePath, parsed) => {
+        try {
+          const absPath = path.resolve(root, filePath)
+          const raw = fs.readFileSync(absPath, 'utf-8')
+          const materialized = materializeFromText(raw)
+          const result = { ...materialized }
+          // Inject _route and _folder the same way generateModule does
+          if (parsed.inferredRoute) result._route = parsed.inferredRoute
+          const folderDirMatch = path.relative(root, absPath).replace(/\\/g, '/').match(/(?:^|\/)src\/(?:prototypes|canvas)\/([^/]+)\.folder\//)
+          if (folderDirMatch) result._folder = folderDirMatch[1]
+          return result
+        } catch {
+          return null
+        }
+      }
+
       const invalidate = (filePath) => {
         const normalized = filePath.replace(/\\/g, '/')
-        // Skip .canvas.jsonl content changes entirely — these are mutated
-        // at runtime by the canvas server API. A full-reload would create
-        // a feedback loop (save → file change → reload → lose editing state).
-        // Instead, send a custom HMR event so the active canvas page can refetch
-        // file-backed data in place with no navigation or document reload.
+        // Canvas .jsonl content changes are mutated at runtime by the canvas
+        // server API. A full-reload would create a feedback loop (save →
+        // file change → reload → lose editing state). Instead, soft-invalidate
+        // the virtual module (so page refresh picks up changes) and send a
+        // 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?.name) {
+          if (parsed?.suffix === 'canvas' && parsed?.id) {
+            const metadata = readCanvasMetadata(filePath, parsed)
             server.ws.send({
               type: 'custom',
               event: 'storyboard:canvas-file-changed',
-              data: { name: parsed.name },
+              data: { canvasId: parsed.id, name: parsed.id, ...(metadata ? { metadata } : {}) },
             })
           }
+          softInvalidate()
           return
         }
 
@@ -742,53 +1008,89 @@ export default function storyboardDataPlugin() {
         // Treat canvas add/unlink as runtime data updates and never full-reload
         // from watcher events. Canvas pages sync from disk via custom WS events.
         if (parsed?.suffix === 'canvas') {
-          const name = parsed.name
+          const canvasId = parsed.id || parsed.name
           if (eventType === 'unlink') {
             const timer = setTimeout(() => {
-              pendingCanvasUnlinks.delete(name)
-              knownCanvasNames.delete(name)
+              pendingCanvasUnlinks.delete(canvasId)
+              knownCanvasIds.delete(canvasId)
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { canvasId, name: canvasId, removed: true },
               })
+              softInvalidate()
             }, 1500)
-            pendingCanvasUnlinks.set(name, timer)
+            pendingCanvasUnlinks.set(canvasId, timer)
             return
           }
 
           if (eventType === 'add') {
-            const pending = pendingCanvasUnlinks.get(name)
+            const metadata = readCanvasMetadata(filePath, parsed)
+            const pending = pendingCanvasUnlinks.get(canvasId)
             if (pending) {
+              // unlink+add pair = in-place save (atomic write), not a real remove
               clearTimeout(pending)
-              pendingCanvasUnlinks.delete(name)
+              pendingCanvasUnlinks.delete(canvasId)
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { canvasId, name: canvasId, ...(metadata ? { metadata } : {}) },
               })
+              softInvalidate()
               return
             }
 
-            if (knownCanvasNames.has(name)) {
+            if (knownCanvasIds.has(canvasId)) {
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { canvasId, name: canvasId, ...(metadata ? { metadata } : {}) },
               })
+              softInvalidate()
               return
             }
 
-            knownCanvasNames.add(name)
+            knownCanvasIds.add(canvasId)
             server.ws.send({
               type: 'custom',
               event: 'storyboard:canvas-file-changed',
-              data: { name },
+              data: { canvasId, name: canvasId, ...(metadata ? { metadata } : {}) },
             })
+            softInvalidate()
             return
           }
         }
 
+        // Story add/remove: soft-invalidate + custom HMR event (full-reload
+        // is blocked by the canvas reload guard). The virtual module HMR
+        // handler live-patches `stories` and re-runs init().
+        if (parsed?.suffix === 'story') {
+          softInvalidate()
+          if (!buildResult) buildResult = buildIndex(root)
+          const storyRoutes = buildResult.storyRoutes || {}
+          const storyIndex = buildResult.index.story || {}
+          const name = parsed.name
+          if (eventType === 'unlink') {
+            server.ws.send({
+              type: 'custom',
+              event: 'storyboard:story-file-changed',
+              data: { name, removed: true },
+            })
+          } else if (eventType === 'add' && storyIndex[name]) {
+            const relModule = '/' + path.relative(root, storyIndex[name]).replace(/\\/g, '/')
+            server.ws.send({
+              type: 'custom',
+              event: 'storyboard:story-file-changed',
+              data: {
+                name,
+                _storyModule: relModule,
+                _route: storyRoutes[name] || null,
+              },
+            })
+          }
+          return
+        }
+
         // Non-canvas additions/removals and folder changes update the route/data graph.
         triggerFullReload()
       }
@@ -819,21 +1121,37 @@ export default function storyboardDataPlugin() {
       const normalized = ctx.file.replace(/\\/g, '/')
       if (!/\.canvas\.jsonl$/.test(normalized)) return
 
-      const parsed = parseDataFile(ctx.file)
-      if (parsed?.suffix === 'canvas' && parsed?.name) {
-        ctx.server.ws.send({
-          type: 'custom',
-          event: 'storyboard:canvas-file-changed',
-          data: { name: parsed.name },
-        })
-      }
-
       // Prevent Vite's default fallback behavior (full page reload) for
-      // non-module .canvas.jsonl edits. Canvas pages consume these updates
-      // through the custom WS event and in-page refetch.
+      // non-module .canvas.jsonl edits. The watcher 'change' handler
+      // (invalidate) already sends the custom HMR event and soft-invalidates
+      // the virtual module — no duplicate event needed here.
       return []
     },
 
+    // Inject __SB_BRANCHES__ into HTML so the Viewfinder branch selector works.
+    // Reads .worktrees/ports.json to enumerate active worktree dev servers.
+    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 }))
+
+        if (branches.length === 0) return html
+
+        const script = `<script>window.__SB_BRANCHES__ = ${JSON.stringify(branches)};</script>`
+        return html.replace('</head>', `${script}\n</head>`)
+      } catch {
+        return html
+      }
+    },
+
     // Rebuild index on each build start
     buildStart() {
       buildResult = null
@@ -842,4 +1160,4 @@ export default function storyboardDataPlugin() {
 }
 
 // Exported for testing
-export { resolveTemplateVars, computeTemplateVars }
+export { resolveTemplateVars, computeTemplateVars, parseDataFile }