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

package/package.json

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

package/scaffold/backstage/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "allowJs": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["../*"]
+    }
+  },
+  "include": ["src", "../components", "../prototypes", "../templates"]
+}

package/scaffold/backstage/vite.config.js

@@ -26,18 +26,44 @@ import postcssGlobalData from '@csstools/postcss-global-data'
 import postcssPresetEnv from 'postcss-preset-env'
 import browsers from '@github/browserslist-config'
 import { globSync } from 'glob'
-import { readFileSync } from 'fs'
+import { copyFileSync, existsSync, readFileSync } from 'fs'
 
 const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
 // The content root is the parent of this `.backstage` Vite root.
 const contentRoot = path.resolve(__dirname, '..')
 
+// Mirror the canonical `storyboard.config.json` (kept at the CONTENT root) into
+// this system root so the library bootstrap's Vite-root-relative imports
+// (`import storyboardConfig from '../../storyboard.config.json'` in
+// src/library/{mount,index,home,prototypes-entry}.jsx) resolve.
+//
+// This runs at Vite config-eval time — before Rollup resolves any module — so
+// EVERY Vite invocation is self-sufficient: `storyboard dev`, and (crucially) a
+// DIRECT `vite build` / `vite preview` used by CI, the deploy/preview workflows,
+// and build-site.mjs. The mirror copy inside `.backstage/` is gitignored, so on
+// a fresh clone it doesn't exist until something creates it; doing it here is
+// what lets a clean CI build resolve the config import. The content-root copy
+// remains the single source of truth the user edits. Legacy layout never loads
+// this config (it ships a different vite.config.js where system === content).
+function mirrorContentConfig() {
+    const src = path.join(contentRoot, 'storyboard.config.json')
+    const dest = path.join(__dirname, 'storyboard.config.json')
+    if (!existsSync(src)) return
+    try {
+        copyFileSync(src, dest)
+    } catch {
+        // Best-effort: a stale/missing mirror surfaces as a clear resolution
+        // error downstream; never crash config evaluation over the copy itself.
+    }
+}
+
+mirrorContentConfig()
+
 // Additional content directories declared by the repo via the `content.dirs`
 // array in storyboard.config.json. These live alongside the role folders at
 // the content root and are watched for add/remove (full-reload) and warmed up
-// like the built-in role folders. The launcher mirrors the canonical config
-// into this system root (see core/paths/resolvePaths.js#mirrorSystemConfig).
+// like the built-in role folders. Reads the mirror created just above.
 function readExtraContentDirs() {
     try {
         const cfg = JSON.parse(readFileSync(path.join(__dirname, 'storyboard.config.json'), 'utf-8'))
@@ -67,8 +93,13 @@ export default defineConfig(() => {
     base,
     resolve: {
         alias: {
-            // Library + system source lives under `.backstage/src`.
-            '@': path.resolve(__dirname, './src'),
+            // `@` is the author-facing content alias (`@/components/...`,
+            // `@/templates/...`). In the legacy layout `@` and `@content` both
+            // resolve to `./src` (where content lives); in the backstage layout
+            // content lives at the content root, so `@` points there too. System
+            // source under `.backstage/src` is loaded via `/src/...` Vite-absolute
+            // paths (see index.html) and the `@dfosco/storyboard` package, never `@`.
+            '@': contentRoot,
             // `@content` is the role-folder base for browser content globs
             // (`@content/prototypes/**`). In the backstage layout it points at
             // the content root, so the globs reach the sibling content folders

package/src/core/cli/dev.js

@@ -20,7 +20,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { detectWorktreeName, getPort, releasePort } from '../worktree/port.js'
 import { startFileWatcher } from '../file-watcher/watcher.js'
 import { compactAll } from '../canvas/compact.js'
-import { findSystemRoot, mirrorSystemConfig, ensureContentNodeModulesLink, ensureLinkedDepsOverlay, ensureContentSystemLinks } from '../paths/resolvePaths.js'
+import { findSystemRoot, ensureContentNodeModulesLink, ensureLinkedDepsOverlay, ensureContentSystemLinks } from '../paths/resolvePaths.js'
 import { parseFlags } from './flags.js'
 import { setupNeeded, writeUserState, getInstalledStoryboardVersion } from './userState.js'
 import { dim, magenta, bold } from './intro.js'
@@ -177,12 +177,13 @@ async function main() {
   // the content root.
   const viteCwd = systemRoot
 
-  // Keep the launcher-owned config mirror inside `.backstage/` fresh so the
-  // library bootstrap's Vite-root-relative config references resolve, and ensure
-  // the content-root `node_modules` symlink exists so content above the Vite
-  // root can resolve its bare imports. Both are no-ops in the legacy layout.
+  // Ensure the content-root `node_modules` symlink exists so content above the
+  // Vite root can resolve its bare imports. The `storyboard.config.json` mirror
+  // into `.backstage/` is handled at Vite config-eval time (see
+  // scaffold/backstage/vite.config.js#mirrorContentConfig) so EVERY Vite
+  // invocation — `storyboard dev` and direct `vite build`/`vite preview` in
+  // CI — stays self-sufficient. All no-ops in the legacy layout.
   if (mode === 'backstage') {
-    mirrorSystemConfig(layout)
     ensureContentNodeModulesLink(layout)
     // When the library is linked from a sibling monorepo (local development),
     // its hoisted deps aren't reachable from the Vite root. Overlay them so

package/src/core/paths/resolvePaths.js

@@ -40,7 +40,6 @@
 
 import { existsSync, lstatSync, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve } from 'node:path'
-import { copyFileSync } from 'node:fs'
 import process from 'node:process'
 
 export const SYSTEM_DIR = '.backstage'
@@ -230,41 +229,13 @@ export function contentBase(root, ...segments) {
   return segments.length ? join(base, ...segments) : base
 }
 
-/**
- * Mirror the canonical `storyboard.config.json` (which the user keeps at the
- * **content root**) into the system root so that the Vite-root-relative config
- * references inside the shipped library bootstrap keep resolving:
- *
- *   - `import storyboardConfig from '../../storyboard.config.json'`
- *     (mount.jsx / prototypes-entry.jsx — relative to `<systemRoot>/src/library`)
- *   - `import.meta.glob('/storyboard.config.json')` (mountIsolationApp — rooted
- *     at the Vite root, i.e. the system root)
- *
- * In the **legacy** layout the system root and content root are the same
- * directory, so this is a no-op (the config is already where those references
- * resolve). In the **backstage** layout it copies
- * `<contentRoot>/storyboard.config.json` → `<systemRoot>/storyboard.config.json`.
- *
- * The mirror is a generated artifact owned by the launcher/CLI — it lives
- * inside `.backstage/` and is gitignored. The content-root copy remains the
- * single source of truth the user edits.
- *
- * @param {{ mode: 'backstage'|'legacy', systemRoot: string, contentRoot: string }} loc
- * @returns {boolean} true if a mirror copy was written.
- */
-export function mirrorSystemConfig(loc) {
-  const { mode, systemRoot, contentRoot } = loc
-  if (mode !== 'backstage') return false
-  const src = join(contentRoot, 'storyboard.config.json')
-  const dest = join(systemRoot, 'storyboard.config.json')
-  if (!existsSync(src)) return false
-  try {
-    copyFileSync(src, dest)
-    return true
-  } catch {
-    return false
-  }
-}
+// NOTE: The `storyboard.config.json` mirror (copying the canonical content-root
+// config into the system root so the library bootstrap's Vite-root-relative
+// imports resolve) lives in the backstage Vite config itself
+// (scaffold/backstage/vite.config.js#mirrorContentConfig). Running it at Vite
+// config-eval time makes EVERY Vite invocation self-sufficient — `storyboard
+// dev` and direct `vite build`/`vite preview` in CI alike — instead of only the
+// `storyboard dev` launcher path.
 
 /**
  * Ensure a `node_modules` symlink exists at the CONTENT root pointing into the

package/src/core/paths/resolvePaths.test.js

@@ -9,7 +9,6 @@ import {
   contentDir,
   contentBase,
   extraContentDirs,
-  mirrorSystemConfig,
   ensureContentNodeModulesLink,
   ensureLinkedDepsOverlay,
   ensureContentSystemLinks,
@@ -183,28 +182,6 @@ describe('core/paths/resolvePaths', () => {
     })
   })
 
-  describe('mirrorSystemConfig', () => {
-    it('is a no-op in the legacy layout', () => {
-      writeFileSync(join(tmp, 'storyboard.config.json'), '{"port":1234}')
-      expect(mirrorSystemConfig(findSystemRoot(tmp))).toBe(false)
-      // No mirror is created (legacy systemRoot === contentRoot, nothing to copy).
-      expect(readFileSync(join(tmp, 'storyboard.config.json'), 'utf8')).toBe('{"port":1234}')
-    })
-
-    it('copies content-root config into the system root in the backstage layout', () => {
-      mkdirSync(join(tmp, SYSTEM_DIR))
-      writeFileSync(join(tmp, 'storyboard.config.json'), '{"port":4321}')
-      const loc = findSystemRoot(tmp)
-      expect(mirrorSystemConfig(loc)).toBe(true)
-      expect(readFileSync(join(tmp, SYSTEM_DIR, 'storyboard.config.json'), 'utf8')).toBe('{"port":4321}')
-    })
-
-    it('returns false when there is no content-root config to mirror', () => {
-      mkdirSync(join(tmp, SYSTEM_DIR))
-      expect(mirrorSystemConfig(findSystemRoot(tmp))).toBe(false)
-    })
-  })
-
   describe('ensureContentNodeModulesLink', () => {
     it('is a no-op in the legacy layout', () => {
       expect(ensureContentNodeModulesLink(findSystemRoot(tmp))).toBe(false)

package/src/core/scaffold/scaffold-integration.test.js

@@ -340,6 +340,22 @@ describe('storyboard-scaffold integration — backstage layout', () => {
     // vitest.config.js has no scaffold/backstage/ variant → canonical is used.
     expect(fs.existsSync(path.join(backstage, 'vitest.config.js'))).toBe(true)
   }, 20000)
+
+  it('aliases `@` to the content root so author imports (@/components/...) resolve', () => {
+    runScaffolder(backstage)
+    const vite = fs.readFileSync(path.join(backstage, 'vite.config.js'), 'utf-8')
+    // In the backstage layout content lives ABOVE the Vite root, so the author
+    // `@` alias must point at the content root — not `.backstage/src` (which
+    // would 500/resolve-fail every `@/components/...` import).
+    expect(vite).toContain("'@': contentRoot,")
+    expect(vite).not.toContain("'@': path.resolve(__dirname, './src')")
+  }, 20000)
+
+  it('writes the backstage tsconfig variant mapping @/* to the content root', () => {
+    runScaffolder(backstage)
+    const ts = JSON.parse(fs.readFileSync(path.join(backstage, 'tsconfig.json'), 'utf-8'))
+    expect(ts.compilerOptions.paths['@/*']).toEqual(['../*'])
+  }, 20000)
 })
 
 // ---------------------------------------------------------------------------