@dfosco/storyboard-react 4.0.0-beta.2 → 4.0.0-beta.21

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,81 @@ 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)
+    return { name, suffix: 'canvas', ext: 'jsonl', folder: canvasFolderName || folderName, inferredRoute, id: toCanvasId(filePath), 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?)$/)
@@ -155,13 +221,103 @@ function getLastModified(root, dirPath) {
   }
 }
 
+/**
+ * Batch-fetch git metadata (author + lastModified) for multiple files in a
+ * single subprocess, avoiding per-file git overhead during startup.
+ *
+ * Returns a Map<absPath, { gitAuthor: string|null, lastModified: string|null }>
+ */
+function batchGitMetadata(root, filePaths) {
+  const result = new Map()
+  if (filePaths.length === 0) return result
+
+  // Initialize all entries
+  for (const fp of filePaths) {
+    result.set(fp, { gitAuthor: null, lastModified: null })
+  }
+
+  try {
+    // Batch lastModified: one git log call with all paths
+    // git log -1 gives the most recent commit touching any of these paths,
+    // but we need per-path data. Use --name-only to correlate.
+    // For efficiency, use a single git log with --format and --name-only
+    // that outputs one record per commit touching these files.
+    const allDirs = [...new Set(filePaths.map(fp => path.dirname(fp)))]
+    const dirsArg = allDirs.map(d => `"${d}"`).join(' ')
+
+    // Get lastModified per directory in one call using git log --format
+    // We output "MARKER<sep>dir<sep>date" per commit, then take the latest per dir.
+    const logResult = execSync(
+      `git log --format="%aI" --name-only -- ${dirsArg}`,
+      { cwd: root, encoding: 'utf-8', timeout: 10000, maxBuffer: 1024 * 1024 },
+    ).trim()
+
+    if (logResult) {
+      // Parse: alternating date lines and filename lines separated by blank lines
+      const blocks = logResult.split('\n\n')
+      const dirDates = new Map() // dir → most recent date
+      for (const block of blocks) {
+        const lines = block.split('\n').filter(Boolean)
+        if (lines.length < 2) continue
+        const date = lines[0]
+        for (let li = 1; li < lines.length; li++) {
+          const fileLine = lines[li].trim()
+          if (!fileLine) continue
+          const dir = path.dirname(path.resolve(root, fileLine))
+          if (!dirDates.has(dir)) {
+            dirDates.set(dir, date)
+          }
+        }
+      }
+      for (const fp of filePaths) {
+        const dir = path.dirname(fp)
+        const entry = result.get(fp)
+        if (dirDates.has(dir) && entry) {
+          entry.lastModified = dirDates.get(dir)
+        }
+      }
+    }
+  } catch { /* git not available or failed — leave nulls */ }
+
+  // Batch gitAuthor: use git log for each file's creation author.
+  // Unfortunately --follow --diff-filter=A doesn't combine well with multiple
+  // paths, so batch them in a single shell invocation using a for loop.
+  try {
+    const relPaths = filePaths.map(fp => path.relative(root, fp))
+    // Build a shell script that outputs "PATH<tab>AUTHOR" per file
+    const cmds = relPaths.map(rp =>
+      `echo -n "${rp}\\t"; git log --follow --diff-filter=A --format="%aN" -- "${rp}" | tail -1`
+    ).join('; ')
+    const authorResult = execSync(cmds, {
+      cwd: root, encoding: 'utf-8', timeout: 10000, shell: true, maxBuffer: 1024 * 1024,
+    }).trim()
+
+    if (authorResult) {
+      for (const line of authorResult.split('\n')) {
+        const tabIdx = line.indexOf('\t')
+        if (tabIdx < 0) continue
+        const relPath = line.slice(0, tabIdx)
+        const author = line.slice(tabIdx + 1).trim()
+        if (!author) continue
+        const absPath2 = path.resolve(root, relPath)
+        const entry = result.get(absPath2)
+        if (entry) entry.gitAuthor = author
+      }
+    }
+  } catch { /* git not available */ }
+
+  return result
+}
+
 /**
  * Scan the repo for all data files, validate uniqueness, return the index.
  */
 function buildIndex(root) {
-  const ignore = ['node_modules/**', 'dist/**', '.git/**']
+  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
@@ -178,35 +334,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) {
@@ -218,13 +397,24 @@ 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)
+    if (parsed.suffix === 'canvas' && parsed.group) {
+      canvasGroups[parsed.name] = 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 }
 }
 
 /**
@@ -278,7 +468,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')
@@ -288,7 +478,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 }
   }
@@ -332,13 +522,36 @@ 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
 
+  // Batch-fetch git metadata for all prototype + canvas files in 1-2 subprocesses
+  const gitPaths = [
+    ...Object.values(index.prototype || {}),
+    ...Object.values(index.canvas || {}),
+  ]
+  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++}`
@@ -349,18 +562,17 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
 
       // Auto-fill gitAuthor for prototype metadata from git history
       if (suffix === 'prototype' && parsed && !parsed.gitAuthor) {
-        const gitAuthor = getGitAuthor(root, absPath)
-        if (gitAuthor) {
-          parsed = { ...parsed, gitAuthor }
+        const meta = gitMeta.get(absPath)
+        if (meta?.gitAuthor) {
+          parsed = { ...parsed, gitAuthor: meta.gitAuthor }
         }
       }
 
       // Auto-fill lastModified from git history for prototypes
       if (suffix === 'prototype' && parsed) {
-        const protoDir = path.dirname(absPath)
-        const lastModified = getLastModified(root, protoDir)
-        if (lastModified) {
-          parsed = { ...parsed, lastModified }
+        const meta = gitMeta.get(absPath)
+        if (meta?.lastModified) {
+          parsed = { ...parsed, lastModified: meta.lastModified }
         }
       }
 
@@ -399,17 +611,24 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
 
       // Auto-fill gitAuthor for canvas metadata from git history
       if (suffix === 'canvas' && parsed && !parsed.gitAuthor) {
-        const gitAuthor = getGitAuthor(root, absPath)
-        if (gitAuthor) {
-          parsed = { ...parsed, gitAuthor }
+        const meta = gitMeta.get(absPath)
+        if (meta?.gitAuthor) {
+          parsed = { ...parsed, gitAuthor: meta.gitAuthor }
         }
       }
 
-      // 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) {
@@ -461,8 +680,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)
@@ -530,22 +763,53 @@ 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',
+    '    if (data.removed) {',
+    '      delete canvases[data.name]',
+    '    } else if (data.metadata) {',
+    '      // Merge into existing entry to preserve build-time fields (_jsxModule, _jsxImport, etc.)',
+    '      canvases[data.name] = canvases[data.name]',
+    '        ? Object.assign({}, canvases[data.name], 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
@@ -561,6 +825,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'],
           exclude: ['@dfosco/storyboard-react'],
         },
       }
@@ -581,6 +850,64 @@ 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)
@@ -596,22 +923,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) {
+            const metadata = readCanvasMetadata(filePath, parsed)
             server.ws.send({
               type: 'custom',
               event: 'storyboard:canvas-file-changed',
-              data: { name: parsed.name },
+              data: { name: parsed.name, ...(metadata ? { metadata } : {}) },
             })
           }
+          softInvalidate()
           return
         }
 
@@ -656,23 +1011,27 @@ export default function storyboardDataPlugin() {
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { name, removed: true },
               })
+              softInvalidate()
             }, 1500)
             pendingCanvasUnlinks.set(name, timer)
             return
           }
 
           if (eventType === 'add') {
+            const metadata = readCanvasMetadata(filePath, parsed)
             const pending = pendingCanvasUnlinks.get(name)
             if (pending) {
+              // unlink+add pair = in-place save (atomic write), not a real remove
               clearTimeout(pending)
               pendingCanvasUnlinks.delete(name)
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { name, ...(metadata ? { metadata } : {}) },
               })
+              softInvalidate()
               return
             }
 
@@ -680,8 +1039,9 @@ export default function storyboardDataPlugin() {
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { name, ...(metadata ? { metadata } : {}) },
               })
+              softInvalidate()
               return
             }
 
@@ -689,12 +1049,43 @@ export default function storyboardDataPlugin() {
             server.ws.send({
               type: 'custom',
               event: 'storyboard:canvas-file-changed',
-              data: { name },
+              data: { name, ...(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()
       }
@@ -725,18 +1116,10 @@ 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 []
     },
 
@@ -748,4 +1131,4 @@ export default function storyboardDataPlugin() {
 }
 
 // Exported for testing
-export { resolveTemplateVars, computeTemplateVars }
+export { resolveTemplateVars, computeTemplateVars, parseDataFile }