@dfosco/storyboard 0.7.1 → 0.8.1

package/scaffold/src/library/_app.jsx

@@ -0,0 +1,53 @@
+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 useFeatureFlag.
+import StoryboardProvider from '@dfosco/storyboard/context'
+import { useFeatureFlag } from '@dfosco/storyboard/hooks/useFeatureFlag'
+import { AppErrorBoundary } from '@dfosco/storyboard/error-boundary'
+import appStyles from './_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>
+      <FeatureFlagBanner />
+      <Suspense fallback={<PageLoading />}>
+        <Outlet />
+      </Suspense>
+    </StoryboardProvider>
+  )
+}
+
+// Last-resort error boundary — generouted wires this via _app?.Catch
+export const Catch = AppErrorBoundary
+
+function FeatureFlagBanner() {
+  const showBanner = useFeatureFlag('show-banner')
+  if (!showBanner) return null
+  return (
+    <div className={appStyles.banner}>
+      🚩 Feature flag <strong>show-banner</strong> is enabled — toggle it off in the Command Menu on the bottom right.
+    </div>
+  )
+}

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

@@ -0,0 +1,8 @@
+.banner {
+  padding: 18px 16px;
+  background-color: var(--bgColor-accent-emphasis, #1f6feb);
+  color: var(--fgColor-onEmphasis, #ffffff);
+  font-size: 14px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  text-align: center;
+}

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,52 @@
+/**
+ * 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/styles/workspace-chrome.css'
+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}
+    />
+  )
+}