@dfosco/storyboard 0.7.1 → 0.9.0

package/scaffold/src/library/_app.jsx

@@ -0,0 +1,41 @@
+import { Suspense } from 'react'
+import { Outlet } from 'react-router-dom'
+// Direct imports bypass the barrel re-export in @dfosco/storyboard/index.js.
+// The barrel eagerly re-exports CanvasPage (3K lines), CommandPalette (1.3K lines),
+// and Viewfinder (1.5K lines) — all resolved by Vite dev even though _app only
+// needs StoryboardProvider and AppErrorBoundary.
+import StoryboardProvider from '@dfosco/storyboard/context'
+import { AppErrorBoundary } from '@dfosco/storyboard/error-boundary'
+import './_app.module.css'
+import '@dfosco/storyboard/canvas/style.css'
+
+function PageLoading() {
+  return (
+    <div style={{
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      minHeight: '100vh',
+      backgroundColor: 'var(--bgColor-default, #0d1117)',
+    }}>
+      <svg width="48" height="48" viewBox="0 0 24 24" fill="none" style={{ animation: 'spin 0.8s linear infinite' }}>
+        <circle cx="12" cy="12" r="10" stroke="var(--fgColor-muted, #484f58)" strokeWidth="2.5" opacity="0.25" />
+        <path d="M12 2a10 10 0 0 1 10 10" stroke="var(--fgColor-default, #e6edf3)" strokeWidth="2.5" strokeLinecap="round" />
+      </svg>
+      <style>{`@keyframes spin { to { transform: rotate(360deg) } }`}</style>
+    </div>
+  )
+}
+
+export default function App() {
+  return (
+    <StoryboardProvider>
+      <Suspense fallback={<PageLoading />}>
+        <Outlet />
+      </Suspense>
+    </StoryboardProvider>
+  )
+}
+
+// Last-resort error boundary — generouted wires this via _app?.Catch
+export const Catch = AppErrorBoundary

package/scaffold/src/library/_app.module.css

@@ -0,0 +1,2 @@
+/* Placeholder — _app.jsx imports this for side effects. Add scoped
+ * classes here as needed. */

package/scaffold/src/library/create.jsx

@@ -0,0 +1,10 @@
+import { CreatePage } from '@dfosco/storyboard'
+
+/**
+ * `/create` route — standalone schema-driven artifact creator.
+ * Opened by `storyboard create --ui` to give a focused creation surface
+ * without the workspace chrome.
+ */
+export default function CreateRoute() {
+  return <CreatePage basePath={import.meta.env.BASE_URL} />
+}

package/scaffold/src/library/index.jsx

@@ -0,0 +1,14 @@
+import { SimpleWorkspace } from '@dfosco/storyboard'
+
+const pageModules = import.meta.glob('/src/prototypes/*/*.jsx')
+
+export default function IndexPage() {
+  return (
+    <SimpleWorkspace
+      title="Storyboard"
+      subtitle="Collaborative workspace for design & code"
+      pageModules={pageModules}
+      basePath={import.meta.env.BASE_URL}
+    />
+  )
+}

package/scaffold/src/library/mount.jsx

@@ -0,0 +1,51 @@
+/**
+ * DO NOT EDIT — storyboard-owned library file.
+ *
+ * Synced from @dfosco/storyboard. Customize via storyboard.config.json,
+ * src/_prototype.jsx, src/_story.jsx, or src/library/_app.jsx.
+ * See src/library/README.md for the full customization surface.
+ *
+ * Workspace SPA entry. Mounts the React Router with the file-based prototype
+ * routes (see ./routes.jsx) and bootstraps storyboard core (devtools, comments,
+ * theming, etc.) via mountStoryboardCore.
+ */
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { RouterProvider, createBrowserRouter } from 'react-router-dom'
+import { routes } from './routes'
+
+import { installHashPreserver } from '@dfosco/storyboard/hash-preserver'
+import { mountStoryboardCore } from '@dfosco/storyboard/core'
+import '@dfosco/storyboard/comments/ui/comment-layout.css'
+import storyboardConfig from '../../storyboard.config.json'
+import { installPrototypeOverlayIsolation } from '../prototypeOverlayIsolation.js'
+
+// Suppress Vite error overlays that originate in /src/prototypes/ so a
+// broken prototype can't take down the canvas surface — see
+// .agents/plans/vite-isolation.md and src/prototypeOverlayIsolation.js.
+installPrototypeOverlayIsolation()
+
+// Redirect after canvas creation — Vite full-reloads when a new
+// .canvas.jsonl is created. The form sets ?redirect=/canvas/name
+// which survives the reload. We navigate once the route is registered.
+const redirectParam = new URLSearchParams(window.location.search).get('redirect')
+if (redirectParam) {
+  const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
+  window.location.replace(base + redirectParam)
+}
+
+const router = createBrowserRouter(routes, {
+    basename: import.meta.env.BASE_URL,
+})
+
+installHashPreserver(router, import.meta.env.BASE_URL)
+mountStoryboardCore(storyboardConfig, { basePath: import.meta.env.BASE_URL })
+
+const rootElement = document.getElementById('root')
+const root = createRoot(rootElement)
+
+root.render(
+    <StrictMode>
+        <RouterProvider router={router} />
+    </StrictMode>
+)

package/scaffold/src/library/prototypes-entry.jsx

@@ -0,0 +1,57 @@
+/**
+ * DO NOT EDIT — storyboard-owned library file.
+ *
+ * Synced from @dfosco/storyboard. Customize via src/_prototype.jsx.
+ * See src/library/README.md for the full customization surface.
+ *
+ * Isolated prototypes entry point (see .agents/plans/vite-isolation.md).
+ *
+ * This is the second Vite HTML entry — prototypes.html loads this file.
+ * Goal: physically separate the prototypes module graph + Rollup chunk graph
+ * from the canvas app so a broken prototype cannot poison canvas surfaces.
+ *
+ * Uses createHashRouter so prototype routes live in the URL hash of
+ * prototypes.html (e.g. prototypes.html#/MyProto/SignupForm). This avoids
+ * needing any server rewrite — every iframe load resolves to the same
+ * prototypes.html document, then the router renders the matched prototype.
+ *
+ * Does NOT install the workspace-level hash preserver — that hook is the
+ * canvas/workshop SPA concern, not relevant inside an isolated prototype.
+ *
+ * The prototype provider chain (Primer / Tailwind / fonts / design tokens)
+ * comes from the consumer's `src/_prototype.jsx` — wired by the route layout
+ * inside ./routes.jsx. When absent, prototypes render with no shared providers.
+ */
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { RouterProvider, createHashRouter } from 'react-router-dom'
+import { routes, getRoutesForProto } from './routes'
+import { mountStoryboardCore } from '@dfosco/storyboard/core'
+import '@dfosco/storyboard/comments/ui/comment-layout.css'
+import storyboardConfig from '../../storyboard.config.json'
+
+// Mount storyboard core. In embed mode (_sb_embed in the URL — always true
+// for canvas iframes) this short-circuits past UI mounting and only:
+//   - honors the canvas-aware theme (_sb_theme_target, _sb_canvas_theme)
+//   - sets up the iframe→parent postMessage navigation bridge
+mountStoryboardCore(storyboardConfig, { basePath: import.meta.env.BASE_URL })
+
+// Per-prototype filtering: when PrototypeEmbed loads us with ?proto=Name in
+// dev, narrow the router to that prototype's subtree. Other prototypes'
+// lazy() entries never appear in the route table, so a broken sibling
+// prototype cannot leak into this iframe's module graph or HMR scope. Falls
+// back to the full route tree when no proto param is set (production builds
+// + direct-load flows).
+const protoParam = new URLSearchParams(window.location.search).get('proto')
+const activeRoutes = protoParam ? getRoutesForProto(protoParam) : routes
+
+const router = createHashRouter(activeRoutes)
+
+const rootElement = document.getElementById('root')
+const root = createRoot(rootElement)
+
+root.render(
+    <StrictMode>
+        <RouterProvider router={router} />
+    </StrictMode>
+)

package/scaffold/src/library/routes.jsx

@@ -0,0 +1,205 @@
+/**
+ * DO NOT EDIT — storyboard-owned library file.
+ *
+ * Synced from @dfosco/storyboard. Customize via src/_prototype.jsx (wraps
+ * every prototype route) or src/library/_app.jsx (workspace SPA shell).
+ * See src/library/README.md for the full customization surface.
+ *
+ * Custom generouted routes entry for storyboard.
+ *
+ * generouted hardcodes /src/pages/ in both its import.meta.glob patterns and
+ * its route-path regex. This module mirrors the generouted runtime but scans
+ * two directories:
+ *   - /src/library/  — storyboard's workspace pages (workspace, viewfinder,
+ *     create, index) plus _app.jsx (SPA shell wrapper).
+ *   - /src/prototypes/  — the consumer's actual prototypes.
+ *
+ * Both directories have their prefix segment stripped from the URL — so
+ * src/library/workspace.jsx mounts at /workspace, and
+ * src/prototypes/MyProto/index.jsx mounts at /MyProto.
+ *
+ * Every PROTOTYPE route (anything originating from /src/prototypes/) is
+ * wrapped in the consumer's src/_prototype.jsx (resolved via
+ * `getPrototypeWrapper`). LIBRARY routes (workspace, viewfinder, create,
+ * index) are NOT wrapped — they own their own provider chain inherited
+ * from _app.jsx.
+ */
+import { Fragment, Suspense } from 'react'
+import { Outlet, useLocation } from 'react-router-dom'
+import PrototypeErrorBoundary, { ImportErrorFallback } from '@dfosco/storyboard/error-boundary'
+import { getPrototypeWrapper } from '@dfosco/storyboard/wrappers'
+import {
+  generatePreservedRoutes,
+  generateRegularRoutes,
+  generateModalRoutes,
+  patterns,
+} from '@generouted/react-router/core'
+
+// Patch the route regex to strip src/library/, src/prototypes/, .folder/,
+// and `drafts/` segments. A `drafts/` dir is a gitignored scratch root —
+// prototypes inside route at the same URL as a non-prefixed sibling (so
+// `prototypes/drafts/Foo/` and `prototypes/Foo/` both resolve at `/Foo`).
+patterns.route = [/^.*\/src\/(library|prototypes)\/|^\/(library|prototypes)\/|[^/]*\.folder\/|(?<=^|\/)drafts\/|\.(jsx|tsx|mdx)$/g, '']
+
+// `_app.jsx` lives in src/library/ — it's storyboard's SPA shell
+// (StoryboardProvider + suspense + error boundary). Consumers can copy
+// it to src/library/_app.jsx and customize freely. `404` is currently a
+// no-op convention, kept for parity with generouted preserved routes.
+const PRESERVED = import.meta.glob('/src/library/(_app|404).{jsx,tsx}', { eager: true })
+const MODALS = import.meta.glob('/src/prototypes/**/[+]*.{jsx,tsx}', { eager: true })
+
+const PrototypeWrapper = getPrototypeWrapper()
+
+// Library workspace pages — non-prototype routes (Workspace, Viewfinder,
+// Create, landing index). Bypasses the PrototypeWrapper.
+const LIBRARY_ROUTES = import.meta.glob(
+  ['/src/library/*.{jsx,tsx}', '!/src/library/(_app|404|mount|prototypes-entry|routes).{jsx,tsx}'],
+)
+
+// Lazy-load prototype routes — only the matched route's module is fetched.
+// This prevents story/canvas URLs from paying for every prototype page's
+// imports (Primer, Reshaped, user components, etc.) on first load.
+const PROTOTYPE_ROUTES = import.meta.glob(
+  ['/src/prototypes/**/[\\w[-]*.{jsx,tsx,mdx}', '!/src/prototypes/**/(_!(layout)*(/*)?|_app|404)*'],
+)
+
+const preservedRoutes = generatePreservedRoutes(PRESERVED)
+const modalRoutes = generateModalRoutes(MODALS)
+
+function makeLazyRoute(importFn, key) {
+  const index = /index\.(jsx|tsx|mdx)$/.test(key) && !key.includes('prototypes/index') && !key.includes('library/index')
+    ? { index: true }
+    : {}
+  return {
+    ...index,
+    lazy: async () => {
+      try {
+        const module = await importFn()
+        const Default = module?.default || Fragment
+        const Page = () =>
+          module?.Pending ? (
+            <Suspense fallback={<module.Pending />}>
+              <Default />
+            </Suspense>
+          ) : (
+            <Default />
+          )
+        return {
+          Component: Page,
+          ErrorBoundary: module?.Catch || PrototypeErrorBoundary,
+          loader: module?.Loader,
+          action: module?.Action,
+        }
+      } catch (err) {
+        // Import itself failed (syntax error, broken dependency, etc.)
+        return {
+          Component: () => <ImportErrorFallback error={err} route={key} />,
+        }
+      }
+    },
+  }
+}
+
+const libraryRoutes = generateRegularRoutes(LIBRARY_ROUTES, makeLazyRoute)
+const prototypeRoutes = generateRegularRoutes(PROTOTYPE_ROUTES, makeLazyRoute)
+
+const _app = preservedRoutes?.['_app']
+const _404 = preservedRoutes?.['404']
+const Default = _app?.default || Outlet
+
+// eslint-disable-next-line react-refresh/only-export-components
+const Modals_ = () => {
+  const Modal = modalRoutes[useLocation().state?.modal] || Fragment
+  return <Modal />
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+const Layout = () => (
+  <>
+    <Default /> <Modals_ />
+  </>
+)
+
+// eslint-disable-next-line react-refresh/only-export-components
+const App = () =>
+  _app?.Pending ? (
+    <Suspense fallback={<_app.Pending />}>
+      <Layout />
+    </Suspense>
+  ) : (
+    <Layout />
+  )
+
+const app = { Component: _app?.default ? App : Layout, ErrorBoundary: _app?.Catch, loader: _app?.Loader }
+const fallback = { path: '*', Component: _404?.default || Fragment }
+
+// Wrap every PROTOTYPE route in <PrototypeWrapper> via a layout route.
+// The wrapper resolves to consumer's src/_prototype.jsx — or a Fragment
+// pass-through when absent (truly blank slate).
+//
+// The wrapping <div data-storyboard-prototype> uses `display: contents` so
+// it never affects layout — it only exposes a CSS-selector hook
+// (`[data-storyboard-prototype] selector`) that consumers can use to scope
+// prototype-side styles.
+//
+// eslint-disable-next-line react-refresh/only-export-components
+function PrototypeLayout() {
+  return (
+    <Suspense fallback={null}>
+      <PrototypeWrapper>
+        <div data-storyboard-prototype style={{ display: 'contents' }}>
+          <Outlet />
+        </div>
+      </PrototypeWrapper>
+    </Suspense>
+  )
+}
+
+const prototypeLayoutRoute = {
+  Component: PrototypeLayout,
+  children: prototypeRoutes,
+}
+
+export const routes = [{
+  ...app,
+  children: [...libraryRoutes, prototypeLayoutRoute, fallback],
+}]
+
+// Return a routes tree filtered to a single prototype subtree. Used by the
+// per-prototype iframe entry (see prototypes-entry.jsx + PrototypeEmbed
+// dev URL builder). Filtering at this layer keeps a broken sibling
+// prototype from ever appearing in the matched route's lazy() chain — only
+// the requested prototype's modules are reachable from the router.
+//
+// Library routes (workspace, viewfinder, create) are NEVER in the iframe
+// path because the iframe entry uses a different routes module
+// (prototypeRoutes.jsx inside the library). So filtering here only needs
+// to walk the prototype subtree.
+export function getRoutesForProto(proto) {
+    if (!proto) return routes
+    const matchesProto = (route) => {
+        const seg = (route.path || '').split('/').filter(Boolean)[0]
+        return seg === proto
+    }
+    const filter = (children) => children
+        .map((r) => {
+            if (r.path === '*') return r
+            if (!r.path) {
+                if (r.children) return { ...r, children: filter(r.children) }
+                return r
+            }
+            if (matchesProto(r)) {
+                return r.children ? { ...r, children: filter(r.children) } : r
+            }
+            return null
+        })
+        .filter(Boolean)
+    return [{
+      ...routes[0],
+      children: routes[0].children.map((child) => {
+        // Only the prototype-layout child has nested children we want to filter.
+        if (child === prototypeLayoutRoute) return { ...child, children: filter(child.children || []) }
+        return child
+      }),
+    }]
+}

package/scaffold/src/library/viewfinder.jsx

@@ -0,0 +1,13 @@
+import { useEffect } from 'react'
+
+/**
+ * Backward-compat redirect: /viewfinder → /workspace
+ * Kept for one release cycle so existing bookmarks and links still work.
+ */
+export default function ViewfinderRedirect() {
+  useEffect(() => {
+    const base = (import.meta.env.BASE_URL || '/').replace(/\/+$/, '')
+    window.location.replace(`${base}/workspace${window.location.hash}`)
+  }, [])
+  return null
+}

package/scaffold/src/library/workspace.jsx

@@ -0,0 +1,17 @@
+import { flows } from 'virtual:storyboard-data-index'
+import { Workspace } from '@dfosco/storyboard'
+
+const pageModules = import.meta.glob('/src/prototypes/*.jsx')
+
+export default function WorkspacePage() {
+  return (
+    <Workspace
+      title="Storyboard"
+      subtitle="Where design work goes"
+      flows={flows}
+      hideDefaultFlow={true}
+      pageModules={pageModules}
+      basePath={import.meta.env.BASE_URL}
+    />
+  )
+}

package/scripts/aggregate-artifacts.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import process from 'process'
+
+const INDEX_FILENAME = 'artifacts.index.json'
+const TMP_FILENAME = '.artifacts.index.json.tmp'
+const SCHEMA_VERSION = 1
+
+function compareBranchNames(a, b) {
+  if (a.branch === 'main' && b.branch !== 'main') return -1
+  if (b.branch === 'main' && a.branch !== 'main') return 1
+  return String(a.branch || '').localeCompare(String(b.branch || ''))
+}
+
+function withTrailingSlash(folder) {
+  if (!folder) return ''
+  return folder.endsWith('/') ? folder : `${folder}/`
+}
+
+function generatedAtMs(manifest) {
+  const value = Date.parse(manifest?.generatedAt || '')
+  return Number.isNaN(value) ? 0 : value
+}
+
+function deriveFolder(manifest, dir, ghPagesDir) {
+  if (dir === ghPagesDir) return ''
+  if (typeof manifest.folder === 'string') return manifest.folder
+  return path.basename(dir)
+}
+
+function deriveBranch(manifest, folder) {
+  if (!folder) return 'main'
+  if (typeof manifest.branch === 'string' && manifest.branch) return manifest.branch
+  return manifest.deployBranch || folder.replace(/^branch--/, '')
+}
+
+function deriveDeployBranch(manifest, branch, folder) {
+  if (!folder || branch === 'main') return 'main'
+  if (typeof manifest.deployBranch === 'string' && manifest.deployBranch) return manifest.deployBranch
+  return folder.replace(/^branch--/, '')
+}
+
+function readManifest(dir) {
+  const manifestPath = path.join(dir, 'artifacts.json')
+  const label = path.basename(dir) || dir
+
+  let raw
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      console.info(`[aggregate-artifacts] Skipping ${label}: artifacts.json not found`)
+      return { manifest: null, readError: false }
+    }
+    console.warn(`[aggregate-artifacts] Skipping ${label}: could not read artifacts.json (${err.message})`)
+    return { manifest: null, readError: true }
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(raw)
+  } catch (err) {
+    console.warn(`[aggregate-artifacts] Skipping ${label}: malformed artifacts.json (${err.message})`)
+    return { manifest: null, readError: false }
+  }
+
+  if (manifest?.schemaVersion !== SCHEMA_VERSION) {
+    console.warn(`[aggregate-artifacts] Skipping ${label}: unsupported schemaVersion ${manifest?.schemaVersion}`)
+    return { manifest: null, readError: false }
+  }
+
+  return { manifest, readError: false }
+}
+
+function listManifestDirs(ghPagesDir) {
+  const entries = fs.readdirSync(ghPagesDir, { withFileTypes: true })
+  const branchDirs = entries
+    .filter(entry => entry.isDirectory() && entry.name.startsWith('branch--'))
+    .map(entry => path.join(ghPagesDir, entry.name))
+    .sort((a, b) => path.basename(a).localeCompare(path.basename(b)))
+
+  return [ghPagesDir, ...branchDirs]
+}
+
+function collectManifests(ghPagesDir) {
+  const manifestsByFolder = new Map()
+  let readErrorCount = 0
+
+  for (const dir of listManifestDirs(ghPagesDir)) {
+    const { manifest, readError } = readManifest(dir)
+    if (readError) readErrorCount += 1
+    if (!manifest) continue
+
+    const folder = deriveFolder(manifest, dir, ghPagesDir)
+    const current = { manifest, dir, folder }
+    const previous = manifestsByFolder.get(folder)
+
+    if (!previous) {
+      manifestsByFolder.set(folder, current)
+      continue
+    }
+
+    const previousBranch = deriveBranch(previous.manifest, previous.folder)
+    const currentBranch = deriveBranch(manifest, folder)
+    const keepCurrent = generatedAtMs(manifest) > generatedAtMs(previous.manifest)
+    const keptBranch = keepCurrent ? currentBranch : previousBranch
+
+    console.warn(
+      `[aggregate-artifacts] Branch folder collision for "${folder || '(root)'}" between "${previousBranch}" and "${currentBranch}"; keeping "${keptBranch}"`,
+    )
+
+    if (keepCurrent) manifestsByFolder.set(folder, current)
+  }
+
+  if (readErrorCount > 1) {
+    throw new Error(`Failed to read ${readErrorCount} artifacts manifests; preserving existing ${INDEX_FILENAME}`)
+  }
+
+  const manifests = [...manifestsByFolder.values()]
+  if (manifests.length === 0) {
+    throw new Error(`No readable artifacts.json manifests found; preserving existing ${INDEX_FILENAME}`)
+  }
+
+  return manifests
+}
+
+function addPrototype(index, manifestInfo, item) {
+  const id = item?.artifactId || item?.id
+  if (!id) return
+
+  const { manifest, folder } = manifestInfo
+  const branch = deriveBranch(manifest, folder)
+  const key = String(id)
+
+  if (!index.prototypes[key]) {
+    index.prototypes[key] = { id: key, branches: [] }
+  }
+
+  index.prototypes[key].branches.push({
+    branch,
+    folder: withTrailingSlash(folder),
+    title: item.title ?? item.id ?? key,
+    route: item.route ?? null,
+    isExternal: Boolean(item.isExternal),
+    externalUrl: item.externalUrl ?? null,
+    folderName: item.folder ?? null,
+    sha: manifest.sha ?? null,
+    lastModified: item.lastModified ?? null,
+  })
+}
+
+function addCanvas(index, manifestInfo, item) {
+  const id = item?.artifactId || item?.id
+  if (!id) return
+
+  const { manifest, folder } = manifestInfo
+  const branch = deriveBranch(manifest, folder)
+  const key = String(id)
+
+  if (!index.canvases[key]) {
+    index.canvases[key] = { id: key, branches: [] }
+  }
+
+  index.canvases[key].branches.push({
+    branch,
+    folder: withTrailingSlash(folder),
+    name: item.name ?? item.id ?? key,
+    route: item.route ?? null,
+    folderName: item.folder ?? null,
+    sha: manifest.sha ?? null,
+    lastModified: item.lastModified ?? null,
+  })
+}
+
+function sortArtifactMap(map) {
+  const sorted = {}
+
+  for (const key of Object.keys(map).sort((a, b) => a.localeCompare(b))) {
+    sorted[key] = {
+      ...map[key],
+      branches: [...map[key].branches].sort(compareBranchNames),
+    }
+  }
+
+  return sorted
+}
+
+function buildIndex(manifests) {
+  const index = {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    branches: [],
+    prototypes: {},
+    canvases: {},
+  }
+
+  for (const manifestInfo of manifests) {
+    const { manifest, folder } = manifestInfo
+    const branch = deriveBranch(manifest, folder)
+    const deployBranch = deriveDeployBranch(manifest, branch, folder)
+
+    index.branches.push({ branch, deployBranch, folder })
+
+    for (const item of Array.isArray(manifest.prototypes) ? manifest.prototypes : []) {
+      addPrototype(index, manifestInfo, item)
+    }
+
+    for (const item of Array.isArray(manifest.canvases) ? manifest.canvases : []) {
+      addCanvas(index, manifestInfo, item)
+    }
+  }
+
+  index.branches = [...index.branches].sort(compareBranchNames)
+  index.prototypes = sortArtifactMap(index.prototypes)
+  index.canvases = sortArtifactMap(index.canvases)
+
+  return index
+}
+
+function writeIndex(ghPagesDir, index) {
+  const targetPath = path.join(ghPagesDir, INDEX_FILENAME)
+  const tmpPath = path.join(ghPagesDir, TMP_FILENAME)
+  const contents = `${JSON.stringify(index, null, 2)}\n`
+
+  fs.writeFileSync(tmpPath, contents, 'utf8')
+  fs.renameSync(tmpPath, targetPath)
+
+  return targetPath
+}
+
+function aggregateArtifacts(ghPagesDir) {
+  const resolvedDir = path.resolve(ghPagesDir)
+  const manifests = collectManifests(resolvedDir)
+  const index = buildIndex(manifests)
+  return writeIndex(resolvedDir, index)
+}
+
+function main() {
+  const ghPagesDir = process.argv[2]
+
+  if (!ghPagesDir) {
+    console.error('Usage: node aggregate-artifacts.mjs <gh-pages-dir>')
+    process.exit(1)
+  }
+
+  try {
+    const targetPath = aggregateArtifacts(ghPagesDir)
+    console.info(`[aggregate-artifacts] Wrote ${targetPath}`)
+  } catch (err) {
+    console.error(`[aggregate-artifacts] ${err.message}`)
+    process.exit(1)
+  }
+}
+
+main()