@dfosco/storyboard 0.7.1 → 0.9.0

package/src/internals/canvas/canvasApi.js

@@ -20,6 +20,23 @@ async function request(path, method, body) {
   return res.json()
 }
 
+/**
+ * Like `request` but also returns the HTTP status code so callers can
+ * distinguish between "endpoint succeeded but logical no-op" and "the
+ * target resource is gone" (which undo/redo handle differently after
+ * compaction wipes event ids).
+ */
+async function requestWithStatus(path, method, body) {
+  const url = getApiBase() + path
+  const res = await fetch(url, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  const data = await res.json().catch(() => ({}))
+  return { status: res.status, ok: res.ok, data }
+}
+
 export function listCanvases() {
   return request('/list', 'GET')
 }
@@ -32,6 +49,18 @@ export function updateCanvas(canvasId, { widgets, sources, settings, connectors
   return request('/update', 'PUT', { name: canvasId, widgets, sources, settings, connectors })
 }
 
+export function patchWidget(canvasId, widgetId, { props, position } = {}) {
+  return request('/widget', 'PATCH', { name: canvasId, widgetId, props, position })
+}
+
+export function undoEvent(canvasId, eventId) {
+  return requestWithStatus('/undo', 'POST', { name: canvasId, eventId })
+}
+
+export function redoEvent(canvasId, eventId) {
+  return requestWithStatus('/redo', 'POST', { name: canvasId, eventId })
+}
+
 export function addWidget(canvasId, { type, props, position }) {
   return request('/widget', 'POST', { name: canvasId, type, props, position })
 }
@@ -56,9 +85,10 @@ export function duplicateImage(filename) {
 
 /**
  * Crop an image client-side and upload the result.
- * @param {string} imageSrc — current image filename (e.g. "canvas--2026-01-01--12-00-00.png")
+ * @param {string} imageSrc — current image filename, possibly prefixed with `drafts/` and/or `~`
+ *   (e.g. "drafts/~canvas--2026-01-01--12-00-00.png")
  * @param {{ x: number, y: number, width: number, height: number }} cropRect — crop region in natural image pixels
- * @param {string} canvasId — canvas name for directory resolution
+ * @param {string} canvasId — canvas name for directory resolution (server uses this to decide drafts/ vs public)
  * @returns {Promise<{ success: boolean, filename: string }>}
  */
 export async function cropAndUpload(imageSrc, cropRect, canvasId) {
@@ -89,15 +119,20 @@ export async function cropAndUpload(imageSrc, cropRect, canvasId) {
     canvas.width, canvas.height,
   )
 
+  // Strip optional `drafts/` directory prefix — the server re-adds it based
+  // on canvasId. We only pass the basename through the cropped-filename
+  // pipeline (the server validates `--cropped--` filenames as basenames).
+  const srcBase = imageSrc.includes('/') ? imageSrc.slice(imageSrc.lastIndexOf('/') + 1) : imageSrc
+
   // Determine output format from original filename
-  const ext = imageSrc.split('.').pop()?.toLowerCase() || 'png'
+  const ext = srcBase.split('.').pop()?.toLowerCase() || 'png'
   const mimeMap = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }
   const mime = mimeMap[ext] || 'image/png'
   const dataUrl = canvas.toDataURL(mime, 0.92)
 
   // Build cropped filename: strip any previous --cropped-- suffix, append new one
-  const privacyPrefix = imageSrc.startsWith('~') ? '~' : ''
-  const baseName = imageSrc.replace(/^~/, '')
+  const privacyPrefix = srcBase.startsWith('~') ? '~' : ''
+  const baseName = srcBase.replace(/^~/, '')
   const withoutCrop = baseName.replace(/--cropped--\d{4}-\d{2}-\d{2}--\d{2}-\d{2}-\d{2}/, '')
   const nameWithoutExt = withoutCrop.replace(/\.\w+$/, '')
   const now = new Date()

package/src/internals/canvas/canvasTheme.js

@@ -1,118 +1,29 @@
+/**
+ * canvasTheme.js — DEPRECATED COMPATIBILITY SHIM.
+ *
+ * Color variables previously written here as inline styles now live in
+ * `core/styles/tailwind.css` and cascade automatically from
+ * `[data-sb-canvas-theme^="dark"]` (set by CanvasPage on the canvas root).
+ *
+ * `getCanvasPrimerAttrs` is preserved as a no-op to keep external consumers
+ * (Primer React inside prototypes) functional via `data-color-mode` — but
+ * storyboard core no longer depends on this attribute internally.
+ *
+ * Both exports return empty objects so existing call sites continue to
+ * destructure/spread without errors. Remove the call sites in a follow-up
+ * sweep, then delete this file.
+ */
+
 export function getCanvasPrimerAttrs(theme) {
   const value = String(theme || 'light')
-  if (value.startsWith('dark')) {
-    return {
-      'data-color-mode': 'dark',
-      'data-dark-theme': value,
-      'data-light-theme': 'light',
-    }
-  }
+  const isDark = value.startsWith('dark')
   return {
-    'data-color-mode': 'light',
-    'data-dark-theme': 'dark',
-    'data-light-theme': value.startsWith('light') ? value : 'light',
+    'data-color-mode': isDark ? 'dark' : 'light',
+    'data-light-theme': isDark ? 'light' : (value.startsWith('light') ? value : 'light'),
+    'data-dark-theme': isDark ? value : 'dark',
   }
 }
 
-/**
- * Per-theme canvas CSS custom properties sourced from @primer/primitives.
- * Each theme gets its own entry so high-contrast, colorblind, and dimmed
- * variants all render with the correct background, dot, and text colors.
- */
-const THEME_VARS = {
-  light: {
-    '--sb--canvas-bg': '#f6f8fa',
-    '--bgColor-default': '#ffffff',
-    '--bgColor-muted': '#f6f8fa',
-    '--bgColor-neutral-muted': '#818b981f',
-    '--bgColor-accent-emphasis': '#0969da',
-    '--tc-bg-muted': '#f6f8fa',
-    '--tc-dot-color': 'rgba(0, 0, 0, 0.08)',
-    '--overlay-backdrop-bgColor': 'rgba(0, 0, 0, 0.08)',
-    '--fgColor-muted': '#59636e',
-    '--fgColor-default': '#1f2328',
-    '--fgColor-onEmphasis': '#ffffff',
-    '--borderColor-default': '#d1d9e0',
-    '--borderColor-muted': '#d1d9e0b3',
-  },
-  light_colorblind: {
-    '--sb--canvas-bg': '#f6f8fa',
-    '--bgColor-default': '#ffffff',
-    '--bgColor-muted': '#f6f8fa',
-    '--bgColor-neutral-muted': '#818b981f',
-    '--bgColor-accent-emphasis': '#0969da',
-    '--tc-bg-muted': '#f6f8fa',
-    '--tc-dot-color': 'rgba(0, 0, 0, 0.08)',
-    '--overlay-backdrop-bgColor': 'rgba(0, 0, 0, 0.08)',
-    '--fgColor-muted': '#59636e',
-    '--fgColor-default': '#1f2328',
-    '--fgColor-onEmphasis': '#ffffff',
-    '--borderColor-default': '#d1d9e0',
-    '--borderColor-muted': '#d1d9e0b3',
-  },
-  dark: {
-    '--sb--canvas-bg': '#151b23',
-    '--bgColor-default': '#0d1117',
-    '--bgColor-muted': '#151b23',
-    '--bgColor-neutral-muted': '#656c7633',
-    '--bgColor-accent-emphasis': '#1f6feb',
-    '--tc-bg-muted': '#151b23',
-    '--tc-dot-color': 'rgba(255, 255, 255, 0.1)',
-    '--overlay-backdrop-bgColor': 'rgba(255, 255, 255, 0.1)',
-    '--fgColor-muted': '#9198a1',
-    '--fgColor-default': '#f0f6fc',
-    '--fgColor-onEmphasis': '#ffffff',
-    '--borderColor-default': '#3d444d',
-    '--borderColor-muted': '#3d444db3',
-  },
-  dark_dimmed: {
-    '--sb--canvas-bg': '#262c36',
-    '--bgColor-default': '#212830',
-    '--bgColor-muted': '#262c36',
-    '--bgColor-neutral-muted': '#656c7633',
-    '--bgColor-accent-emphasis': '#316dca',
-    '--tc-bg-muted': '#262c36',
-    '--tc-dot-color': 'rgba(209, 215, 224, 0.18)',
-    '--overlay-backdrop-bgColor': 'rgba(209, 215, 224, 0.18)',
-    '--fgColor-muted': '#9198a1',
-    '--fgColor-default': '#d1d7e0',
-    '--fgColor-onEmphasis': '#f0f6fc',
-    '--borderColor-default': '#3d444d',
-    '--borderColor-muted': '#3d444db3',
-  },
-  dark_colorblind: {
-    '--sb--canvas-bg': '#151b23',
-    '--bgColor-default': '#0d1117',
-    '--bgColor-muted': '#151b23',
-    '--bgColor-neutral-muted': '#656c7633',
-    '--bgColor-accent-emphasis': '#1f6feb',
-    '--tc-bg-muted': '#151b23',
-    '--tc-dot-color': 'rgba(255, 255, 255, 0.1)',
-    '--overlay-backdrop-bgColor': 'rgba(255, 255, 255, 0.1)',
-    '--fgColor-muted': '#9198a1',
-    '--fgColor-default': '#f0f6fc',
-    '--fgColor-onEmphasis': '#ffffff',
-    '--borderColor-default': '#3d444d',
-    '--borderColor-muted': '#3d444db3',
-  },
-  dark_high_contrast: {
-    '--sb--canvas-bg': '#151b23',
-    '--bgColor-default': '#010409',
-    '--bgColor-muted': '#151b23',
-    '--bgColor-neutral-muted': '#212830',
-    '--bgColor-accent-emphasis': '#194fb1',
-    '--tc-bg-muted': '#151b23',
-    '--tc-dot-color': 'rgba(183, 189, 200, 0.25)',
-    '--overlay-backdrop-bgColor': 'rgba(183, 189, 200, 0.25)',
-    '--fgColor-muted': '#b7bdc8',
-    '--fgColor-default': '#ffffff',
-    '--fgColor-onEmphasis': '#ffffff',
-    '--borderColor-default': '#b7bdc8',
-    '--borderColor-muted': '#b7bdc8',
-  },
-}
-
-export function getCanvasThemeVars(theme) {
-  const value = String(theme || 'light')
-  return THEME_VARS[value] || THEME_VARS.light
+export function getCanvasThemeVars() {
+  return {}
 }

package/src/internals/canvas/isolation/createIsolationMiddleware.js

@@ -0,0 +1,68 @@
+/**
+ * Vite middleware factory for iframe-isolation entries.
+ *
+ * Both `prototypes.html` (prototype embeds) and `stories.html` (story /
+ * component-set widgets) follow the same recipe: serve a minimal HTML shell
+ * that boots a library-side React entry, with a theme bootstrap inlined so
+ * first paint matches the active theme. This factory captures that recipe
+ * so the two surfaces can't drift apart.
+ *
+ * Returns a Connect middleware that matches `/${name}` and `/${name}/*`
+ * (after the configured Vite base path is stripped). Non-matching URLs are
+ * passed through to `next()`.
+ *
+ * @param {object} opts
+ * @param {string} opts.name        — entry name, including extension, e.g. 'prototypes.html'
+ * @param {string} opts.entryPath   — absolute on-disk path to the JS entry to /@fs-load
+ * @param {string} opts.surface     — value for `data-sb-surface` attribute on <body>
+ * @param {string} opts.title       — document <title>
+ * @param {() => object|undefined} opts.getThemes — read live themes config; called per request
+ * @returns {(req, res, next) => void}
+ */
+export function createIsolationMiddleware({ name, entryPath, surface, title, getThemes }, { renderInlineBootstrapScript, server }) {
+  const matchPath = `/${name}`
+  return async function isolationMiddleware(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) || '/'
+    }
+    const cleanUrl = url.split('?')[0].split('#')[0]
+    if (cleanUrl !== matchPath && !cleanUrl.startsWith(`${matchPath}/`)) return next()
+
+    const themes = getThemes?.()
+    const themeBootstrap = themes ? renderInlineBootstrapScript(themes) : ''
+
+    const rawHtml = [
+      '<!DOCTYPE html>',
+      '<html lang="en"><head>',
+      '<meta charset="UTF-8" />',
+      '<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />',
+      `<title>${escapeHtml(title)}</title>`,
+      themeBootstrap,
+      `</head><body data-sb-surface="${escapeAttr(surface)}">`,
+      '<div id="root"></div>',
+      `<script type="module" src="/@fs${entryPath}"></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] ${name} transform failed:`, err)
+      res.writeHead(500, { 'Content-Type': 'text/plain' })
+      res.end(`${name} failed`)
+    }
+  }
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]))
+}
+
+function escapeAttr(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))
+}

package/src/internals/canvas/isolation/mountIsolationApp.jsx

@@ -0,0 +1,88 @@
+/**
+ * Shared mount helper for isolated iframe entries.
+ *
+ * Used by `prototypesEntry.jsx` and `storiesEntry.jsx` — they both:
+ *   1. Read `storyboard.config.json` via import.meta.glob
+ *   2. Call `mountStoryboardCore` so the embed gets ui-runtime CSS, theme
+ *      sync, and the iframe→parent postMessage bridge
+ *   3. Mount a React tree with `createBrowserRouter` scoped to the entry
+ *      page (basename = `${BASE_URL}/${name}`)
+ *
+ * Centralizing this here means bug fixes / iterations land in one place
+ * for both surfaces. Each surface entry shrinks to a few lines:
+ *
+ *   import { routes, getRoutesForProto } from './prototypeRoutes.jsx'
+ *   import { mountIsolationApp } from './mountIsolationApp.jsx'
+ *   mountIsolationApp({
+ *     name: 'prototypes.html',
+ *     wrapperKind: 'prototype',
+ *     resolveRoutes: ({ firstSegment, search }) => {
+ *       const proto = firstSegment || search.get('proto') || ''
+ *       return proto ? getRoutesForProto(proto) : routes
+ *     },
+ *   })
+ *
+ * Provider chain: the consumer's `src/_prototype.jsx` (or `src/_story.jsx`)
+ * wraps the routes. When absent, both wrappers degrade to a Fragment
+ * pass-through — prototypes render with no shared providers (blank slate).
+ *
+ * @param {object} opts
+ * @param {string} opts.name                          — entry name, e.g. 'prototypes.html'
+ * @param {'prototype' | 'story'} [opts.wrapperKind='prototype']
+ *        — which consumer wrapper to mount around the router. Prototype
+ *          uses `src/_prototype.jsx`, story uses `src/_story.jsx`.
+ * @param {RouteObject[]} [opts.routes]               — fixed route table (used when resolveRoutes is omitted)
+ * @param {(ctx) => RouteObject[]} [opts.resolveRoutes]
+ *        — callback that returns the route table to mount, given
+ *          `{ basename, pathname, search, firstSegment }`. Use this when a
+ *          surface needs to narrow routes per-request (e.g. prototypes
+ *          isolate a broken sibling proto from the matched lazy() chain).
+ */
+import { StrictMode, Suspense } from 'react'
+import { createRoot } from 'react-dom/client'
+import { RouterProvider, createBrowserRouter } from 'react-router-dom'
+import { mountStoryboardCore } from '../../../core/index.js'
+import { getPrototypeWrapper, getStoryWrapper } from '../../loadConsumerWrapper.js'
+import '../../../core/comments/ui/comment-layout.css'
+
+const configModules = import.meta.glob('/storyboard.config.json', { eager: true })
+
+export function mountIsolationApp({ name, wrapperKind = 'prototype', routes, resolveRoutes }) {
+  const storyboardConfig = Object.values(configModules)[0]?.default || {}
+
+  // Mount storyboard core. In embed mode (`_sb_embed` in the URL — always true
+  // for canvas iframes) this short-circuits past UI mounting and only:
+  //   - applies the canvas-aware theme (_sb_theme_target, _sb_canvas_theme)
+  //   - sets up the iframe→parent postMessage navigation/wheel bridge
+  mountStoryboardCore(storyboardConfig, { basePath: import.meta.env.BASE_URL })
+
+  const basePathNoTrail = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
+  const basename = `${basePathNoTrail}/${name}`
+
+  const pathname = window.location.pathname
+  const search = new URLSearchParams(window.location.search)
+  const afterBasename = pathname.startsWith(basename) ? pathname.slice(basename.length) : ''
+  const firstSegment = (afterBasename.match(/^\/([^/?#]+)/) || [])[1] || ''
+
+  const activeRoutes = resolveRoutes
+    ? resolveRoutes({ basename, pathname, search, firstSegment })
+    : routes
+
+  const router = createBrowserRouter(activeRoutes, { basename })
+
+  const Wrapper = wrapperKind === 'story' ? getStoryWrapper() : getPrototypeWrapper()
+
+  const rootElement = document.getElementById('root')
+  const root = createRoot(rootElement)
+
+  root.render(
+    <StrictMode>
+      <Suspense fallback={null}>
+        <Wrapper>
+          <RouterProvider router={router} />
+        </Wrapper>
+      </Suspense>
+    </StrictMode>,
+  )
+}
+

package/src/internals/canvas/isolation/prototypeRoutes.jsx

@@ -0,0 +1,140 @@
+/**
+ * Library-side prototype routes builder for the isolated prototypes iframe.
+ *
+ * Mirrors the consumer-scaffold convention (src/routes.jsx) but lives inside
+ * the library so consumers no longer need to maintain their own
+ * prototypes-entry plumbing. Uses absolute globs (`/src/prototypes/...`),
+ * which Vite resolves against the *consumer's* project root regardless of
+ * where this file physically lives.
+ *
+ * Used by `prototypesEntry.jsx`, which is the iframe entry served by the
+ * `prototypes.html` middleware in `data-plugin.js`.
+ */
+import { Fragment, Suspense } from 'react'
+import { Outlet, useLocation } from 'react-router-dom'
+import {
+  generatePreservedRoutes,
+  generateRegularRoutes,
+  generateModalRoutes,
+  patterns,
+} from '@generouted/react-router/core'
+import PrototypeErrorBoundary, { ImportErrorFallback } from '../../PrototypeErrorBoundary.jsx'
+
+// Strip src/library/, src/prototypes/, .folder/, and `drafts/` segments
+// from route paths. `_app.jsx` lives in src/library/ (since
+// b144dace5); user-authored prototype routes live in src/prototypes/.
+// Both prefixes are stripped so the generated route paths (and the
+// preservedRoutes _app key) come out clean.
+//
+// A `drafts/` dir is a gitignored scratch root — prototypes inside route at
+// the same URL as a non-prefixed sibling. The lookbehind ensures we only
+// match `drafts/` as a directory segment, not as part of a filename.
+patterns.route = [/^.*\/src\/(library|prototypes)\/|^\/(library|prototypes)\/|[^/]*\.folder\/|(?<=^|\/)drafts\/|\.(jsx|tsx|mdx)$/g, '']
+
+// `_app.jsx` lives in src/library/ — it's the consumer's SPA shell that
+// wraps every route in <StoryboardProvider>. Without this glob hitting
+// the right path, the iframe entry would render prototypes with no
+// provider and any useFlowData / useObject / useRecord call would crash.
+const PRESERVED = import.meta.glob('/src/library/(_app|404).{jsx,tsx}', { eager: true })
+const MODALS = import.meta.glob('/src/prototypes/**/[+]*.{jsx,tsx}', { eager: true })
+
+// 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 ROUTES = import.meta.glob(
+  ['/src/prototypes/**/[\\w[-]*.{jsx,tsx,mdx}', '!/src/prototypes/**/(_!(layout)*(/*)?|_app|404)*'],
+)
+
+const preservedRoutes = generatePreservedRoutes(PRESERVED)
+const modalRoutes = generateModalRoutes(MODALS)
+
+const regularRoutes = generateRegularRoutes(ROUTES, (importFn, key) => {
+  const index = /index\.(jsx|tsx|mdx)$/.test(key) && !key.includes('prototypes/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) {
+        return {
+          Component: () => <ImportErrorFallback error={err} route={key} />,
+        }
+      }
+    },
+  }
+})
+
+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 }
+
+export const routes = [{ ...app, children: [...regularRoutes, fallback] }]
+
+/**
+ * Return a routes tree filtered to a single prototype subtree. Used by the
+ * per-prototype iframe entry — 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).
+ */
+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: filter(routes[0].children || []) }]
+}

package/src/internals/canvas/isolation/prototypesEntry.jsx

@@ -0,0 +1,28 @@
+/**
+ * Library-provided entry for the isolated prototypes iframe.
+ *
+ * Loaded by the prototypes.html middleware in `data-plugin.js`. All the
+ * mount plumbing (consumer stylesheet pull-in, storyboard.config.json read,
+ * mountStoryboardCore, basename derivation, React tree) lives in the shared
+ * `mountIsolationApp` helper so this file and `storiesEntry.jsx` stay in
+ * sync. See `.agents/plans/vite-isolation.md` for the isolation pattern.
+ *
+ * The `resolveRoutes` callback narrows the route table to a single
+ * prototype subtree based on the first path segment after the basename
+ * (e.g. `/prototypes.html/MyProto/SignupForm` → narrow to MyProto). This
+ * keeps a broken sibling prototype from ever appearing in the matched
+ * route's lazy() chain — module-graph isolation.
+ *
+ * The legacy `?proto=` query param is preserved as a fallback for older
+ * canvases / older builds.
+ */
+import { routes, getRoutesForProto } from './prototypeRoutes.jsx'
+import { mountIsolationApp } from './mountIsolationApp.jsx'
+
+mountIsolationApp({
+  name: 'prototypes.html',
+  resolveRoutes: ({ firstSegment, search }) => {
+    const proto = firstSegment || search.get('proto') || ''
+    return proto ? getRoutesForProto(proto) : routes
+  },
+})

package/src/internals/canvas/isolation/storiesEntry.jsx

@@ -0,0 +1,20 @@
+/**
+ * Library-provided entry for the isolated stories iframe.
+ *
+ * Loaded by the stories.html middleware in `data-plugin.js`. All the mount
+ * plumbing lives in the shared `mountIsolationApp` helper so this file
+ * and `prototypesEntry.jsx` stay in sync. See `.agents/plans/vite-isolation.md`
+ * for the isolation pattern.
+ *
+ * No `resolveRoutes` callback — stories don't need per-segment narrowing
+ * because each `.story.jsx` is dynamic-imported inside StoryPage, so the
+ * route module graph never eagerly pulls in sibling stories.
+ */
+import { storyRoutes } from './storyRoutes.jsx'
+import { mountIsolationApp } from './mountIsolationApp.jsx'
+
+mountIsolationApp({
+  name: 'stories.html',
+  wrapperKind: 'story',
+  routes: storyRoutes,
+})

package/src/internals/canvas/isolation/storyRoutes.jsx

@@ -0,0 +1,55 @@
+/**
+ * Route table for the isolated stories iframe (`/stories.html/components/...`).
+ *
+ * Mirrors the canvas SPA's story-route matching but built as a real react-router
+ * route table so the route lives in the URL (deep-linkable, "open in new tab"
+ * works) and a broken `.story.jsx` only crashes the matched story — not the
+ * canvas chrome (module-graph isolation: each .story.jsx is dynamic-imported
+ * by StoryPage._storyImport, not eagerly globbed).
+ *
+ * Uses a single splat route — the story name is derived at render time by
+ * matching the full route path against the stories index (`_route` field).
+ * Falls back to a friendly "story not found" message when no match.
+ */
+import { lazy, Suspense } from 'react'
+import { useLocation } from 'react-router-dom'
+import { stories } from 'virtual:storyboard-data-index'
+
+const StoryPageLazy = lazy(() => import('../../story/StoryPage.jsx'))
+
+function resolveStoryName(pathname) {
+  const normalized = pathname.replace(/\/+$/, '') || '/'
+  for (const [name, data] of Object.entries(stories || {})) {
+    if (data?._route && data._route.replace(/\/+$/, '') === normalized) {
+      return name
+    }
+  }
+  return null
+}
+
+function StoryRouteComponent() {
+  const location = useLocation()
+  const storyName = resolveStoryName(location.pathname)
+
+  if (!storyName) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'system-ui, sans-serif', color: 'var(--color-foreground-muted, #57606a)' }}>
+        <strong>Story not found</strong>
+        <br />
+        <code>{location.pathname}</code>
+      </div>
+    )
+  }
+
+  return (
+    <Suspense fallback={null}>
+      <StoryPageLazy name={storyName} />
+    </Suspense>
+  )
+}
+
+export const storyRoutes = [
+  { path: '/components', element: <StoryRouteComponent /> },
+  { path: '/components/*', element: <StoryRouteComponent /> },
+  { path: '*', element: <StoryRouteComponent /> },
+]