@dfosco/storyboard 1.0.0-beta.2 → 1.0.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dfosco/storyboard",
-    "version": "1.0.0-beta.2",
+    "version": "1.0.0-beta.3",
     "type": "module",
     "license": "MIT",
     "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/src/core/canvas/compact.js

@@ -12,6 +12,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { materializeFromText, serializeEvent } from './materializer.js'
+import { contentDir } from '../paths/resolvePaths.js'
 
 const COMPACT_THRESHOLD_BYTES = 500 * 1024
 
@@ -21,7 +22,7 @@ const COMPACT_THRESHOLD_BYTES = 500 * 1024
  * @returns {{ name: string, filePath: string, size: number }[]}
  */
 export function findCanvasFiles(root) {
-  const canvasDir = path.join(root, 'src', 'canvas')
+  const canvasDir = contentDir(root, 'canvas')
   if (!fs.existsSync(canvasDir)) return []
 
   const results = []

package/src/core/canvas/selectedWidgets.js

@@ -19,6 +19,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { toCanvasId } from './identity.js'
+import { findSystemRoot } from '../paths/resolvePaths.js'
 import { devLog } from '../logger/devLogger.js'
 
 const DIR_NAME = '.storyboard'
@@ -29,12 +30,16 @@ const CLEANUP_INTERVAL_MS = 10_000
  * Find a canvas JSONL file by canonical ID (cached).
  */
 function createPathResolver(root) {
+  // Canvas files live at the content root, which differs from the Vite/system
+  // `root` in the `.backstage` layout. Walk the content root so canvas IDs
+  // resolve to real files (and stored paths are content-root relative).
+  const scanRoot = findSystemRoot(root).contentRoot
   const cache = new Map()
   let lastScanFiles = null
 
   function scanFiles() {
     const results = []
-    const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees', 'worktrees', 'workleafs'])
+    const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees', 'worktrees', 'workleafs', '.backstage'])
     function walk(dir, rel) {
       let entries
       try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
@@ -46,7 +51,7 @@ function createPathResolver(root) {
         else if (entry.name.endsWith('.canvas.jsonl')) results.push(relPath)
       }
     }
-    walk(root, '')
+    walk(scanRoot, '')
     return results
   }
 

package/src/core/canvas/server.js

@@ -224,11 +224,17 @@ function parseExportNames(filePath) {
  */
 function findCanvasPath(root, canvasId) {
   const files = findCanvasFiles(root)
+  // `findCanvasFiles` walks the content root and returns content-relative
+  // paths. In the `.backstage` layout the Vite `root` is the system root
+  // (`.backstage`), which is a sibling of the content root — resolving the
+  // returned paths against `root` would point at a non-existent
+  // `.backstage/canvas/...` file. Resolve against the content root instead.
+  const { contentRoot } = findSystemRoot(root)
 
   for (const file of files) {
     const id = toCanvasId(file)
     if (id === canvasId) {
-      return path.resolve(root, file)
+      return path.resolve(contentRoot, file)
     }
   }
 
@@ -1025,13 +1031,14 @@ export function createCanvasHandler(ctx) {
     // GET /list — list all canvases
     if (routePath === '/list' && method === 'GET') {
       const files = findCanvasFiles(root)
+      const { contentRoot } = findSystemRoot(root)
       const canvases = files.map((file) => {
         const id = toCanvasId(file)
         if (!id) return null
         const { segments } = parseCanvasId(id)
         const group = segments.length > 1 ? segments.slice(0, -1).join('/') : null
         try {
-          const data = readCanvas(path.resolve(root, file))
+          const data = readCanvas(path.resolve(contentRoot, file))
           return {
             name: id,
             title: data.title || segments[segments.length - 1],
@@ -3127,8 +3134,9 @@ export function Default() {
 
     // ── Image routes ──────────────────────────────────────────────────
 
-    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
-    const snapshotsDir = path.join(root, 'assets', 'canvas', 'snapshots')
+    const assetsDir = contentDir(root, 'assets')
+    const imagesDir = path.join(assetsDir, 'canvas', 'images')
+    const snapshotsDir = path.join(assetsDir, 'canvas', 'snapshots')
 
     const MIME_TO_EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' }
     const EXT_TO_MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }

package/src/core/canvas/server.test.js

@@ -847,3 +847,67 @@ describe('GET /folders and POST /create with folderKind', () => {
     expect(fs.existsSync(path.join(canvasDir, 'tour.folder'))).toBe(false)
   })
 })
+
+describe('.backstage layout — content paths anchored at the content root', () => {
+  let root, systemRoot, canvasDir, invoke, lastResponse
+
+  // In the backstage layout the Vite `root` handed to the canvas handler is the
+  // `.backstage` system root, but the user's canvas/asset content lives one
+  // level up at the content root. Regression coverage for the paste/add bug
+  // where widget writes resolved against `.backstage/...` and 500'd (ENOENT).
+  beforeEach(() => {
+    const contentRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sb-backstage-test-'))
+    systemRoot = path.join(contentRoot, '.backstage')
+    fs.mkdirSync(systemRoot, { recursive: true })
+    // Backstage content layout: canvas/ at the content root (no src/ segment).
+    canvasDir = path.join(contentRoot, 'canvas')
+    fs.mkdirSync(canvasDir, { recursive: true })
+    root = contentRoot
+
+    const lr = { status: null, body: null, bytes: null, headers: null }
+    const handler = createCanvasHandler({
+      // Hand the handler the system root, exactly like vite (root === .backstage)
+      root: systemRoot,
+      sendJson: (_res, status, body) => { lr.status = status; lr.body = body },
+    })
+    const makeRes = () => ({ writeHead() {}, end() {} })
+    invoke = (routePath, method, body = {}) =>
+      handler(null, makeRes(), { path: routePath, method, body })
+    lastResponse = lr
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  it('POST /widget writes to the content-root canvas file (not under .backstage)', async () => {
+    writeCanvas(canvasDir, 'design-system', { title: 'Design System' })
+
+    await invoke('/widget', 'POST', {
+      name: 'design-system',
+      type: 'sticky-note',
+      props: { text: '# hello' },
+      position: { x: 120, y: 80 },
+    })
+
+    expect(lastResponse.status).toBe(201)
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.widget.type).toBe('sticky-note')
+
+    // The event must land in the content-root file, and NOT create a stray
+    // `.backstage/canvas/...` file.
+    const contentFile = path.join(canvasDir, 'design-system.canvas.jsonl')
+    expect(fs.readFileSync(contentFile, 'utf-8')).toContain('widget_added')
+    expect(fs.existsSync(path.join(systemRoot, 'canvas', 'design-system.canvas.jsonl'))).toBe(false)
+  })
+
+  it('GET /list resolves canvases from the content root', async () => {
+    writeCanvas(canvasDir, 'design-system', { title: 'Design System' })
+
+    await invoke('/list', 'GET')
+
+    expect(lastResponse.status).toBe(200)
+    const names = lastResponse.body.canvases.map((c) => c.name)
+    expect(names).toContain('design-system')
+  })
+})

package/src/core/file-watcher/watcher.js

@@ -519,7 +519,7 @@ function processDraftsFlipImages(root, flip, canvasFiles) {
   }
   if (!state.widgets || state.widgets.length === 0) return null
 
-  const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+  const imagesDir = path.join(contentDir(root, 'assets'), 'canvas', 'images')
   const draftsDir = path.join(imagesDir, 'drafts')
   const sharedRefs = collectImageRefs(canvasFiles, newAbsPath)
 

package/src/core/vite/docs-handler.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { execSync } from 'node:child_process'
+import { findSystemRoot, resolvePaths } from '../paths/resolvePaths.js'
 
 const README_CANDIDATES = ['README.md', 'readme.md', 'Readme.md']
 const SOURCE_EXTENSIONS = new Set(['.jsx', '.tsx', '.js', '.ts'])
@@ -61,6 +62,11 @@ export async function collectFiles(dir, rootDir) {
  * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, opts: { path: string, method: string }) => Promise<void>}
  */
 export function docsHandler({ root, sendJson }) {
+  // Content (README, prototypes, components, config, git) lives at the content
+  // root, which equals `root` in the legacy layout but is the parent of the
+  // Vite/system root in the `.backstage` layout.
+  const { contentRoot } = findSystemRoot(root)
+  root = contentRoot
   return async (req, res, { path: routePath, method }) => {
     // --- GET /readme ---
     if (routePath === '/readme' && method === 'GET') {
@@ -96,10 +102,17 @@ export function docsHandler({ root, sendJson }) {
         return
       }
 
-      // Security: only allow files within src/
+      // Security: restrict to content directories (prototypes, components,
+      // canvas, assets). In the legacy layout these all live under `src/`; in
+      // the `.backstage` layout they sit directly at the content root.
       const relative = path.relative(root, resolved)
-      if (!relative.startsWith('src' + path.sep)) {
-        sendJson(res, 403, { error: 'Only files within src/ are accessible' })
+      const { dirs } = resolvePaths(findSystemRoot(root))
+      const allowedRoots = [dirs.prototypes, dirs.components, dirs.canvas]
+      const isAllowed = allowedRoots.some(
+        (d) => resolved === d || resolved.startsWith(d + path.sep),
+      )
+      if (!isAllowed) {
+        sendJson(res, 403, { error: 'Only files within content directories are accessible' })
         return
       }
 
@@ -114,8 +127,8 @@ export function docsHandler({ root, sendJson }) {
 
     // --- GET /files ---
     if (routePath === '/files' && method === 'GET') {
-      const prototypesDir = path.join(root, 'src', 'prototypes')
-      const files = await collectFiles(prototypesDir, root)
+      const { dirs } = resolvePaths(findSystemRoot(root))
+      const files = await collectFiles(dirs.prototypes, root)
       sendJson(res, 200, { files: files.sort() })
       return
     }

package/src/core/vite/server-plugin.js

@@ -38,6 +38,7 @@ import { startMaintenance, stopMaintenance } from '../messaging/hub-maintenance.
 import { createArtifactRoutes } from '../artifact/routes.js'
 import { createFileHandler } from '../file/server.js'
 import { buildArtifactManifest, resolveManifestEnv } from '../data/artifactManifest.js'
+import { findSystemRoot, contentDir } from '../paths/resolvePaths.js'
 import { buildDataDiscovery } from '../../internals/vite/data-plugin.js'
 
 const API_PREFIX = '/_storyboard/'
@@ -413,9 +414,10 @@ export default function storyboardServer() {
       }
 
       // Ignore assets/canvas/ so image/snapshot writes don't trigger reloads
-      server.watcher.unwatch(path.join(root, 'assets', 'canvas', 'images'))
-      server.watcher.unwatch(path.join(root, 'assets', 'canvas', 'snapshots'))
-      server.watcher.unwatch(path.join(root, 'assets', '.storyboard-public', 'terminal-snapshots'))
+      const assetsDir = contentDir(root, 'assets')
+      server.watcher.unwatch(path.join(assetsDir, 'canvas', 'images'))
+      server.watcher.unwatch(path.join(assetsDir, 'canvas', 'snapshots'))
+      server.watcher.unwatch(path.join(assetsDir, '.storyboard-public', 'terminal-snapshots'))
       // The entire `.storyboard/` directory is gitignored runtime state
       // (terminal buffers + snapshots, hub messages, selectedwidgets,
       // logs, server registry). None of it should ever feed Vite's
@@ -930,14 +932,26 @@ export default function storyboardServer() {
     // Build-time: emit a static JSON with source files so the inspector
     // works in deployed environments without the dev middleware.
     async generateBundle() {
-      const srcDir = path.join(root, 'src')
-      const prototypesDir = path.join(root, 'src', 'prototypes')
-
-      // Collect file lists (prototypes for the files index, all src/ for sources)
-      const [prototypeFiles, allSrcFiles] = await Promise.all([
-        collectFiles(prototypesDir, root),
-        collectFiles(srcDir, root),
+      // Content (prototypes/components/canvas, README, config, git) lives at the
+      // content root — equal to `root` in legacy, the parent of the Vite/system
+      // root in the `.backstage` layout.
+      const contentRoot = findSystemRoot(root).contentRoot
+      const dirs = {
+        prototypes: contentDir(root, 'prototypes'),
+        components: contentDir(root, 'components'),
+        canvas: contentDir(root, 'canvas'),
+      }
+      const prototypesDir = dirs.prototypes
+
+      // Collect file lists (prototypes for the files index; all content role
+      // dirs for the inspector source map — mirrors the docs /source allowlist).
+      const [prototypeFiles, ...roleFileLists] = await Promise.all([
+        collectFiles(prototypesDir, contentRoot),
+        collectFiles(dirs.prototypes, contentRoot),
+        collectFiles(dirs.components, contentRoot),
+        collectFiles(dirs.canvas, contentRoot),
       ])
+      const allSrcFiles = [...new Set(roleFileLists.flat())]
 
       // Read all source file contents
       const sources = {}
@@ -945,7 +959,7 @@ export default function storyboardServer() {
         allSrcFiles.map(async (relPath) => {
           try {
             sources[relPath] = await fs.promises.readFile(
-              path.join(root, relPath),
+              path.join(contentRoot, relPath),
               'utf-8'
             )
           } catch { /* skip unreadable files */ }
@@ -957,7 +971,7 @@ export default function storyboardServer() {
       try {
         const { execSync } = await import('node:child_process')
         const remote = execSync('git remote get-url origin', {
-          cwd: root,
+          cwd: contentRoot,
           encoding: 'utf-8',
         }).trim()
         const match = remote.match(/github\.com[:/]([^/]+)\/([^/.]+)/)
@@ -965,7 +979,7 @@ export default function storyboardServer() {
       } catch { /* no git or no remote */ }
 
       if (!repo) {
-        const configPath = path.join(root, 'storyboard.config.json')
+        const configPath = path.join(contentRoot, 'storyboard.config.json')
         try {
           const raw = await fs.promises.readFile(configPath, 'utf-8')
           const cfg = JSON.parse(raw)
@@ -990,7 +1004,7 @@ export default function storyboardServer() {
       let readmeContent = null
       for (const candidate of ['README.md', 'readme.md', 'Readme.md']) {
         try {
-          readmeContent = await fs.promises.readFile(path.join(root, candidate), 'utf-8')
+          readmeContent = await fs.promises.readFile(path.join(contentRoot, candidate), 'utf-8')
           break
         } catch { /* try next */ }
       }
@@ -1033,8 +1047,8 @@ export default function storyboardServer() {
       // Dev server serves these dynamically; production needs the static files.
       // Private images (prefixed with ~) are excluded from the build.
       for (const dir of [
-        path.join(root, 'assets', 'canvas', 'images'),
-        path.join(root, 'assets', 'canvas', 'snapshots'),
+        path.join(contentDir(root, 'assets'), 'canvas', 'images'),
+        path.join(contentDir(root, 'assets'), 'canvas', 'snapshots'),
       ]) {
         try {
           const imageFiles = await fs.promises.readdir(dir)

package/src/core/workshop/features/createPrototype/server.js

@@ -22,6 +22,7 @@ import {
   resolveTemplateRecipeEntry,
 } from '../templateIndex.js'
 import { readWorkshopPartials } from '../partialRender.js'
+import { contentDir, contentBase, findSystemRoot } from '../../../paths/resolvePaths.js'
 
 const FLOW_SKELETON = JSON.stringify({ $global: [] }, null, 2) + '\n'
 
@@ -74,7 +75,7 @@ function validatePrototypeName(name) {
 }
 
 function listFolders(root) {
-  const prototypesDir = path.join(root, 'src', 'prototypes')
+  const prototypesDir = contentDir(root, 'prototypes')
   if (!fs.existsSync(prototypesDir)) return []
 
   return fs.readdirSync(prototypesDir, { withFileTypes: true })
@@ -237,7 +238,7 @@ export function createPrototypesHandler(ctx) {
       const isExternal = Boolean(url)
 
       // Determine target directory
-      const prototypesDir = path.join(root, 'src', 'prototypes')
+      const prototypesDir = contentDir(root, 'prototypes')
       let targetDir
 
       if (folder) {
@@ -266,7 +267,7 @@ export function createPrototypesHandler(ctx) {
         generatePrototypeJson({ title, author, description, partialEntry: null, url: isExternal ? url : undefined }),
       )
 
-      const relDir = targetDir.replace(root + '/', '')
+      const relDir = targetDir.replace(findSystemRoot(root).contentRoot + '/', '')
       const result = {
         success: true,
         path: relDir,
@@ -306,7 +307,7 @@ export function createPrototypesHandler(ctx) {
       if (!partialEntry) {
         content = generateBlankIndexJsx(componentName, title)
       } else {
-        const partialDir = path.join(root, 'src', partialEntry.baseDir, partialEntry.name)
+        const partialDir = contentBase(root, partialEntry.baseDir, partialEntry.name)
         const componentFile = findComponentFile(partialDir)
         if (!componentFile) {
           sendJson(res, 400, { error: `No .jsx or .tsx file found in src/${partialEntry.baseDir}/${partialEntry.name}/` })
@@ -343,7 +344,7 @@ export function createPrototypesHandler(ctx) {
         return
       }
 
-      const prototypesDir = path.join(root, 'src', 'prototypes')
+      const prototypesDir = contentDir(root, 'prototypes')
       let targetDir
 
       if (folder) {
@@ -385,7 +386,7 @@ export function createPrototypesHandler(ctx) {
         return
       }
 
-      const prototypesDir = path.join(root, 'src', 'prototypes')
+      const prototypesDir = contentDir(root, 'prototypes')
       let targetDir
 
       if (folder) {

package/src/core/workshop/features/templateIndex.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { parse as parseJsonc } from 'jsonc-parser'
+import { contentDir, contentBase } from '../../paths/resolvePaths.js'
 
 const TEMPLATE_DIR_NAMES = new Set(['template', 'templates'])
 const RECIPE_DIR_NAMES = new Set(['recipe', 'recipes'])
@@ -31,7 +32,7 @@ function toPartialKind(directory) {
 }
 
 function listPrototypeDirs(root) {
-  const prototypesDir = path.join(root, 'src', 'prototypes')
+  const prototypesDir = contentDir(root, 'prototypes')
   if (!fs.existsSync(prototypesDir)) return []
 
   const results = []
@@ -91,7 +92,7 @@ function resolveGlobalPartialBaseDir(srcRoot, configDirectory, name) {
 }
 
 export function buildTemplateRecipeIndex(root, configPartials = []) {
-  const srcRoot = path.join(root, 'src')
+  const srcRoot = contentBase(root)
   const results = []
   const seenIds = new Set()