@dfosco/storyboard 0.6.14 → 0.6.16

package/package.json

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

package/src/core/mountStoryboardCore.js

@@ -461,12 +461,17 @@ export async function mountStoryboardCore(config = {}, options = {}) {
  * Compute the route src to broadcast to the parent canvas from a prototype embed iframe.
  *
  * In **dev mode**, the embed iframe is loaded via the isolation entry
- * (`/prototypes.html#/<route>`), so `pathname` is `/prototypes.html` and the
- * actual route lives in the hash. We strip the loader path and report the
- * hash content as the src. Otherwise, the parent canvas would persist
- * `/prototypes.html#/<route>` as the widget src — and then re-build the
- * iframe URL as `/prototypes.html?proto=prototypes.html#/...`, which loads
- * a blank page. Duplicating that widget (cmd+D) inherits the broken src.
+ * (`/prototypes.html/<route>`), so `pathname` includes the `/prototypes.html`
+ * loader prefix. We strip that prefix and report the remaining route + hash
+ * as the src. The hash is preserved verbatim because storyboard URL state
+ * (`#key=value` overrides) writes to the hash and the canvas needs the full
+ * navigated URL state to round-trip cleanly.
+ *
+ * Legacy dev shape (0.6.13 and older) put the route in the hash
+ * (`/prototypes.html#/<route>`). We still recognize that shape and unwrap
+ * the inner hash so canvases never persist `/prototypes.html#/...` as a src
+ * (which the canvas-side URL builder would mis-interpret, producing a blank
+ * iframe — and cmd+D would duplicate the broken src to every clone).
  *
  * In **prod mode**, the iframe loads the prototype route directly through
  * the canvas SPA, so `pathname` already contains the route — we just strip
@@ -479,6 +484,13 @@ export function computeEmbedNavigationSrc(pathname, hash, basePath = '') {
   const stripped = cleanBase && pathname.startsWith(cleanBase)
     ? pathname.slice(cleanBase.length) || '/'
     : pathname.replace(/^\/branch--[^/]+/, '') || '/'
+  // New dev shape: `/prototypes.html/<route>` — strip loader prefix and
+  // append hash (storyboard URL state).
+  if (stripped.startsWith('/prototypes.html/')) {
+    const route = stripped.slice('/prototypes.html'.length) || '/'
+    return route + (hash || '')
+  }
+  // Legacy dev shape (0.6.13 and older): `/prototypes.html` + `#/<route>`.
   if (stripped === '/prototypes.html' || stripped.endsWith('/prototypes.html')) {
     const inner = (hash || '').startsWith('#') ? hash.slice(1) : (hash || '')
     if (!inner) return '/'

package/src/core/mountStoryboardCore.test.js

@@ -29,7 +29,61 @@ describe('computeEmbedNavigationSrc', () => {
     })
   })
 
-  describe('dev mode (prototypes.html isolation entry)', () => {
+  describe('dev mode (new shape: /prototypes.html/<route>)', () => {
+    it('strips /prototypes.html prefix from pathname and keeps hash', () => {
+      expect(
+        computeEmbedNavigationSrc('/prototypes.html/cq-org-enablement', '#cqConfirmOpen=true', '/'),
+      ).toBe('/cq-org-enablement#cqConfirmOpen=true')
+    })
+
+    it('preserves multi-key storyboard hash state', () => {
+      expect(
+        computeEmbedNavigationSrc(
+          '/prototypes.html/cq-org-enablement',
+          '#cqEnabled=null&cqFlashDismissed=null&cqConfirmOpen=true&cqSettingUp=null',
+          '/',
+        ),
+      ).toBe('/cq-org-enablement#cqEnabled=null&cqFlashDismissed=null&cqConfirmOpen=true&cqSettingUp=null')
+    })
+
+    it('preserves search params (e.g. ?flow=name)', () => {
+      expect(
+        computeEmbedNavigationSrc(
+          '/prototypes.html/cq-org-enablement',
+          '',
+          '/',
+        ),
+      ).toBe('/cq-org-enablement')
+    })
+
+    it('handles nested route segments', () => {
+      expect(
+        computeEmbedNavigationSrc('/prototypes.html/MyProto/SignupForm', '', '/'),
+      ).toBe('/MyProto/SignupForm')
+    })
+
+    it('handles non-root basePath', () => {
+      expect(
+        computeEmbedNavigationSrc(
+          '/storyboard/prototypes.html/MyProto',
+          '#x=1',
+          '/storyboard/',
+        ),
+      ).toBe('/MyProto#x=1')
+    })
+
+    it('handles branch deploy basePath', () => {
+      expect(
+        computeEmbedNavigationSrc(
+          '/branch--feature-x/prototypes.html/MyProto',
+          '#x=1',
+          '/branch--feature-x/',
+        ),
+      ).toBe('/MyProto#x=1')
+    })
+  })
+
+  describe('dev mode legacy shape (0.6.13 and older: /prototypes.html + #/<route>)', () => {
     it('uses hash content as src when pathname is /prototypes.html', () => {
       expect(
         computeEmbedNavigationSrc('/prototypes.html', '#/cq-org-enablement', '/'),
@@ -77,22 +131,41 @@ describe('computeEmbedNavigationSrc', () => {
     })
   })
 
-  describe('cmd+D regression — must never produce /prototypes.html#... as src', () => {
-    // The original bug: dev embed broadcast pathname+hash, so the parent
-    // canvas persisted `/prototypes.html#/route` as the widget src. The
-    // URL builder then rebuilt the iframe URL as
+  describe('regression — must never produce /prototypes.html prefix as src', () => {
+    // 0.6.13 bug: dev embed broadcast pathname+hash, so the parent canvas
+    // persisted `/prototypes.html#/route` as the widget src. The URL builder
+    // then rebuilt the iframe URL as
     // `/prototypes.html?proto=prototypes.html#/prototypes.html#/route`,
     // which loaded a blank page. Duplicating that widget (cmd+D) carried
     // the broken src to every clone.
-    it('never returns a string starting with /prototypes.html#', () => {
+    //
+    // 0.6.14 bug: hash-based routing in createHashRouter collided with
+    // storyboard URL state (which also writes to the hash). Navigating
+    // inside the iframe blanked the page because the route part of the
+    // hash got URL-encoded into a single nonsense fragment.
+    //
+    // 0.6.15 (this fix): pathname-based routing — both shapes must
+    // round-trip to a clean canvas-app route.
+    it('never returns a string starting with /prototypes.html', () => {
       const cases = [
+        // legacy hash-form (0.6.13 bug)
         ['/prototypes.html', '#/foo'],
         ['/prototypes.html', '#/foo?bar=1'],
         ['/storyboard/prototypes.html', '#/bar'],
         ['/branch--x/prototypes.html', '#/baz'],
+        // new path-form (0.6.15)
+        ['/prototypes.html/foo', ''],
+        ['/prototypes.html/foo', '#key=value'],
+        ['/prototypes.html/foo/bar', '#a=1&b=2'],
+        ['/storyboard/prototypes.html/foo', '#x=y'],
+        ['/branch--x/prototypes.html/foo', '#x=y'],
       ]
       for (const [pathname, hash] of cases) {
-        const basePath = pathname.replace(/\/prototypes\.html$/, '/') || '/'
+        const basePath = pathname.startsWith('/branch--x')
+          ? '/branch--x/'
+          : pathname.startsWith('/storyboard')
+            ? '/storyboard/'
+            : '/'
         const result = computeEmbedNavigationSrc(pathname, hash, basePath)
         expect(result.startsWith('/prototypes.html')).toBe(false)
       }

package/src/internals/canvas/prototypesEntry.jsx

@@ -5,10 +5,15 @@
  * the consumer-side `src/prototypes-entry.jsx` so consumers don't need to
  * maintain the iframe entry themselves.
  *
- * Uses `createHashRouter` so prototype routes live in the URL hash
- * (`prototypes.html#/MyProto/SignupForm`). Filters routes by `?proto=` so a
- * broken sibling prototype never appears in the matched route's lazy()
- * chain (module-graph isolation — see .agents/plans/vite-isolation.md).
+ * Uses `createBrowserRouter` with `/prototypes.html` as the basename so
+ * prototype routes live in the URL path (`prototypes.html/MyProto/SignupForm`),
+ * leaving the hash and search free for storyboard URL state (which writes
+ * `#key=value` for overrides and `?flow=name` for the active flow).
+ *
+ * The first path segment after `prototypes.html` is the prototype name —
+ * used by `getRoutesForProto()` to filter routes so a broken sibling
+ * prototype never appears in the matched route's lazy() chain
+ * (module-graph isolation — see .agents/plans/vite-isolation.md).
  *
  * CSS chain: relies on `mountStoryboardCore` to inject the compiled
  * ui-runtime stylesheet (matches index.jsx's mount) — this restores stock
@@ -19,7 +24,7 @@
  */
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
-import { RouterProvider, createHashRouter } from 'react-router-dom'
+import { RouterProvider, createBrowserRouter } from 'react-router-dom'
 import { ThemeProvider, BaseStyles } from '@primer/react'
 import { routes, getRoutesForProto } from './prototypeRoutes.jsx'
 import ThemeSync from '../../primer/ThemeSync.jsx'
@@ -46,10 +51,20 @@ const storyboardConfig = Object.values(configModules)[0]?.default || {}
 //   - sets up the iframe→parent postMessage navigation/wheel bridge
 mountStoryboardCore(storyboardConfig, { basePath: import.meta.env.BASE_URL })
 
-const protoParam = new URLSearchParams(window.location.search).get('proto')
+// Derive the prototype name for narrowing. Prefer the first pathname segment
+// after `prototypes.html` (the new browser-router layout); fall back to the
+// legacy `?proto=` query param so old canvases or older builds keep working.
+const basePathNoTrail = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
+const prototypesBasename = `${basePathNoTrail}/prototypes.html`
+const afterBasename = window.location.pathname.startsWith(prototypesBasename)
+  ? window.location.pathname.slice(prototypesBasename.length)
+  : ''
+const pathProto = (afterBasename.match(/^\/([^/?#]+)/) || [])[1] || ''
+const queryProto = new URLSearchParams(window.location.search).get('proto') || ''
+const protoParam = pathProto || queryProto
 const activeRoutes = protoParam ? getRoutesForProto(protoParam) : routes
 
-const router = createHashRouter(activeRoutes)
+const router = createBrowserRouter(activeRoutes, { basename: prototypesBasename })
 
 const rootElement = document.getElementById('root')
 const root = createRoot(rootElement)

package/src/internals/canvas/widgets/PrototypeEmbed.jsx

@@ -7,6 +7,7 @@ import { readProp, prototypeEmbedSchema } from './widgetProps.js'
 import { getEmbedChromeVars } from './embedTheme.js'
 import { useIframeDevLogs } from './iframeDevLogs.js'
 import { findAllConnectedSplitTargets, getSplitPaneLabel, buildPaneForWidget, buildSplitLayout } from './expandUtils.js'
+import { normalizeLegacyEmbedSrc } from './normalizeLegacyEmbedSrc.js'
 import ExpandedPane from './ExpandedPane.jsx'
 import styles from './PrototypeEmbed.module.css'
 import overlayStyles from './embedOverlay.module.css'
@@ -27,21 +28,6 @@ function formatName(name) {
     .replace(/\b\w/g, (c) => c.toUpperCase())
 }
 
-// Self-heal canvases that persisted a dev-isolation src like
-// `/prototypes.html#/MyProto?...` (caused by an older broadcastNavigation
-// that reported pathname+hash, treating the loader path as the route).
-// Without this normalization, the URL builder treats "prototypes.html" as
-// the prototype name and produces a blank iframe — and cmd+D duplicates
-// inherit the broken src. Pure, deterministic, safe to call on every render.
-function normalizeLegacyEmbedSrc(src) {
-  if (typeof src !== 'string' || !src) return src
-  const m = src.match(/^\/?(?:[^#]*\/)?prototypes\.html#(.*)$/)
-  if (!m) return src
-  const inner = m[1] || ''
-  if (!inner) return '/'
-  return inner.startsWith('/') ? inner : `/${inner}`
-}
-
 function resolveCanvasThemeFromStorage() {
   if (typeof localStorage === 'undefined') return 'light'
   let sync = { prototype: true, toolbar: false, codeBoxes: true, canvas: false }
@@ -61,25 +47,38 @@ function resolveCanvasThemeFromStorage() {
 const HEADER_HEIGHT = 37
 
 export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdate, resizable }, ref) {
-  const src = normalizeLegacyEmbedSrc(readProp(props, 'src', prototypeEmbedSchema))
+  const rawStoredSrc = readProp(props, 'src', prototypeEmbedSchema)
+  const src = normalizeLegacyEmbedSrc(rawStoredSrc)
   const width = readProp(props, 'width', prototypeEmbedSchema) || 800
   const height = readProp(props, 'height', prototypeEmbedSchema) || 600
   const zoom = readProp(props, 'zoom', prototypeEmbedSchema) || 100
   const label = readProp(props, 'label', prototypeEmbedSchema) || src
 
+  // Self-healing write-back: if normalization changed the src, persist the
+  // clean form so the canvas JSONL stops carrying the broken URL. Without
+  // this, every render keeps recovering at runtime but the file stays
+  // poisoned and any consumer on an older library still sees the bug.
+  useEffect(() => {
+    if (!onUpdate) return
+    if (typeof rawStoredSrc !== 'string' || rawStoredSrc === src) return
+    onUpdate({ src })
+  }, [rawStoredSrc, src, onUpdate])
+
   const basePath = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
   const baseSegment = basePath.replace(/^\//, '')
   // Two URLs are derived from `src`:
   //   - rawSrc — the iframe URL. In DEV this routes through the isolated
   //     prototypes.html entry so a broken prototype's transform/HMR errors
   //     stay inside the iframe (see .agents/plans/vite-isolation.md):
-  //     /MyProto/SignupForm becomes prototypes.html?proto=MyProto#/MyProto/SignupForm.
-  //     In PROD it loads the prototype path directly through the canvas SPA
-  //     (prototypes.html is a build-time isolation artifact that must not
-  //     leak into deployed URLs).
+  //     /MyProto/SignupForm becomes prototypes.html/MyProto/SignupForm.
+  //     Routing happens in the *pathname* (createBrowserRouter), not in the
+  //     hash, so the hash and search stay free for storyboard URL state
+  //     (`?flow=...` and `#key=value` overrides). In PROD it loads the
+  //     prototype path directly through the canvas SPA (prototypes.html is
+  //     a build-time isolation artifact that must not leak into deployed URLs).
   //   - externalSrc — the URL used by "Open in new tab". Always direct
   //     (`${basePath}/<protoPath>`), never prototypes.html, even in dev —
-  //     opening prototypes.html#/... in a fresh tab is a leaky surprise
+  //     opening prototypes.html/... in a fresh tab is a leaky surprise
   //     for users navigating from the canvas.
   // External http(s) URLs are left alone in both cases. basePath already
   // carries the /branch--xxx/ prefix on branch deploys, so both work for
@@ -109,13 +108,14 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     if (import.meta.env.PROD) {
       return { rawSrc: directUrl, externalSrc: directUrl }
     }
-    // Dev iframe: prototypes.html with ?proto= narrowing. The consumer's
-    // prototypes-entry.jsx reads ?proto= and calls getRoutesForProto();
-    // older scaffolds harmlessly ignore the param and load the full tree.
-    const pathOnly = pathAndQuery.split('?')[0]
-    const protoName = pathOnly.split('/').filter(Boolean)[0] || ''
-    const queryStr = protoName ? `?proto=${encodeURIComponent(protoName)}` : ''
-    const iframeUrl = `${basePath}/prototypes.html${queryStr}#${routePath}${suffix}`
+    // Dev iframe: prototypes.html with the route as a sub-path. The library
+    // middleware (`data-plugin.js`) serves the same HTML shell for
+    // `/prototypes.html/*` so a hard reload / open-in-new-tab works. The
+    // prototype name (first path segment) narrows getRoutesForProto so a
+    // broken sibling prototype can't poison the lazy() chain. Hash and
+    // search stay attached so storyboard URL state (`#key=value` overrides,
+    // `?flow=name`) survives the redirect through the isolation entry.
+    const iframeUrl = `${basePath}/prototypes.html${routePath}${suffix}`
     return { rawSrc: iframeUrl, externalSrc: directUrl }
   }, [src, basePath, baseSegment])
 

package/src/internals/canvas/widgets/PrototypeEmbed.test.jsx

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { getEmbedChromeVars } from './embedTheme.js'
+import { normalizeLegacyEmbedSrc } from './normalizeLegacyEmbedSrc.js'
 
 describe('getEmbedChromeVars', () => {
   it('follows toolbar theme variants for embed edit chrome', () => {
@@ -8,3 +9,116 @@ describe('getEmbedChromeVars', () => {
     expect(getEmbedChromeVars('dark_dimmed')['--bgColor-default']).toBe('#212830')
   })
 })
+
+describe('normalizeLegacyEmbedSrc', () => {
+  it('passes through clean canvas-app routes unchanged', () => {
+    expect(normalizeLegacyEmbedSrc('/cq-org-enablement')).toBe('/cq-org-enablement')
+    expect(normalizeLegacyEmbedSrc('/MyProto/SignupForm')).toBe('/MyProto/SignupForm')
+    expect(normalizeLegacyEmbedSrc('/cq-org-enablement#x=1')).toBe('/cq-org-enablement#x=1')
+  })
+
+  it('passes through external http(s) URLs unchanged', () => {
+    expect(normalizeLegacyEmbedSrc('https://example.com/foo')).toBe('https://example.com/foo')
+  })
+
+  it('passes through empty/falsy values', () => {
+    expect(normalizeLegacyEmbedSrc('')).toBe('')
+    expect(normalizeLegacyEmbedSrc(null)).toBe(null)
+    expect(normalizeLegacyEmbedSrc(undefined)).toBe(undefined)
+  })
+
+  describe('legacy hash-form: /prototypes.html#/<route>', () => {
+    it('strips loader prefix and keeps inner route', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html#/cq-org-enablement')).toBe('/cq-org-enablement')
+    })
+
+    it('keeps query strings inside inner', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html#/cq-org-enablement?cqConfirmOpen=true'))
+        .toBe('/cq-org-enablement?cqConfirmOpen=true')
+    })
+
+    it('handles non-root basePath', () => {
+      expect(normalizeLegacyEmbedSrc('/storyboard/prototypes.html#/MyProto')).toBe('/MyProto')
+    })
+
+    it('returns "/" for empty inner', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html#')).toBe('/')
+    })
+
+    it('prefixes "/" if inner missing leading slash', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html#MyProto')).toBe('/MyProto')
+    })
+  })
+
+  describe('legacy URLSearchParams-clobbered form (real-world 0.6.13/0.6.14 bug)', () => {
+    // Real bug: storyboard's session.writeHash did URLSearchParams.toString()
+    // on the entire hash, which URL-encoded the route slash to %2F and turned
+    // /MyProto into a key with an empty value. Real persisted srcs from the
+    // wild look like /prototypes.html#%2Fcq-org-enablement=&cqConfirmOpen=true
+    it('recovers route from URLSearchParams-mangled hash', () => {
+      expect(
+        normalizeLegacyEmbedSrc('/prototypes.html#%2Fcq-org-enablement=&cqConfirmOpen=true'),
+      ).toBe('/cq-org-enablement#cqConfirmOpen=true')
+    })
+
+    it('recovers route with no surviving storyboard state', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html#%2Fcq-org-enablement=')).toBe('/cq-org-enablement')
+    })
+
+    it('recovers route with multiple storyboard params', () => {
+      expect(
+        normalizeLegacyEmbedSrc(
+          '/prototypes.html#%2Fcq-org-enablement=&cqEnabled=null&cqFlashDismissed=null&cqConfirmOpen=true',
+        ),
+      ).toBe('/cq-org-enablement#cqEnabled=null&cqFlashDismissed=null&cqConfirmOpen=true')
+    })
+
+    it('recovers nested route', () => {
+      expect(
+        normalizeLegacyEmbedSrc('/prototypes.html#%2FMyProto%2FSignupForm=&x=1'),
+      ).toBe('/MyProto/SignupForm#x=1')
+    })
+
+    it('handles non-root basePath', () => {
+      expect(
+        normalizeLegacyEmbedSrc('/storyboard/prototypes.html#%2FMyProto=&x=1'),
+      ).toBe('/MyProto#x=1')
+    })
+  })
+
+  describe('defensive path-form: /prototypes.html/<route>', () => {
+    it('strips loader prefix', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html/MyProto')).toBe('/MyProto')
+    })
+
+    it('handles nested routes', () => {
+      expect(normalizeLegacyEmbedSrc('/prototypes.html/MyProto/SignupForm')).toBe('/MyProto/SignupForm')
+    })
+
+    it('handles non-root basePath', () => {
+      expect(normalizeLegacyEmbedSrc('/storyboard/prototypes.html/MyProto')).toBe('/MyProto')
+    })
+  })
+
+  describe('all-encompassing regression — no legacy shape can produce a /prototypes.html src', () => {
+    const cases = [
+      '/prototypes.html#/foo',
+      '/prototypes.html#/foo?bar=1',
+      '/prototypes.html#',
+      '/prototypes.html#%2Ffoo=&bar=1',
+      '/prototypes.html#%2Ffoo%2Fbar=&x=1',
+      '/prototypes.html/foo',
+      '/prototypes.html/foo/bar',
+      '/storyboard/prototypes.html#/foo',
+      '/storyboard/prototypes.html#%2Ffoo=&x=1',
+      '/storyboard/prototypes.html/foo',
+    ]
+    for (const input of cases) {
+      it(`recovers ${input}`, () => {
+        const result = normalizeLegacyEmbedSrc(input)
+        expect(result).not.toMatch(/prototypes\.html/)
+        expect(result.startsWith('/')).toBe(true)
+      })
+    }
+  })
+})

package/src/internals/canvas/widgets/normalizeLegacyEmbedSrc.js

@@ -0,0 +1,74 @@
+/**
+ * Self-heal canvases that persisted a dev-isolation loader URL as the prototype
+ * widget src. Three legacy shapes exist (all caused by older bugs in the embed
+ * iframe broadcaster — see commit history of PrototypeEmbed.jsx + mountStoryboardCore.js):
+ *
+ *   1. `/prototypes.html#/MyProto?...`
+ *      — 0.6.13 and older, when the iframe broadcast pathname+hash and
+ *        routing lived in the hash. Inner is a clean path.
+ *
+ *   2. `/prototypes.html#%2FMyProto=&cqOpen=true&...`
+ *      — 0.6.13/0.6.14 with storyboard URL state. The iframe's hash was
+ *        `#/MyProto` (router route), then storyboard's session.writeHash
+ *        did `URLSearchParams.toString()` on the entire hash, which
+ *        URL-encoded `/` to `%2F` and turned `/MyProto` into a key with
+ *        an empty value. This is the most common shape seen in the wild.
+ *
+ *   3. `/prototypes.html/MyProto...`
+ *      — defensive: if a future broadcaster ever forwards the loader
+ *        path verbatim with the path-based router layout (0.6.15+).
+ *
+ * Without normalization the URL builder in PrototypeEmbed treats
+ * "prototypes.html" as the prototype name and produces a blank iframe — and
+ * cmd+D duplicates inherit the broken src.
+ *
+ * Pure, deterministic, safe to call on every render. The PrototypeEmbed
+ * component also writes the normalized form back to the canvas via onUpdate
+ * so the persisted JSONL stops carrying the broken URL forever.
+ *
+ * @param {unknown} src
+ * @returns {unknown} normalized src, or the original value when not a string
+ */
+export function normalizeLegacyEmbedSrc(src) {
+  if (typeof src !== 'string' || !src) return src
+  // Hash-form (legacy 0.6.13 router-in-hash). Match both clean and
+  // URLSearchParams-mangled inner contents.
+  const hashMatch = src.match(/^\/?(?:[^#]*\/)?prototypes\.html#(.*)$/)
+  if (hashMatch) {
+    const inner = hashMatch[1] || ''
+    if (!inner) return '/'
+    // Clean form: `#/MyProto?...` — inner already starts with `/`.
+    if (inner.startsWith('/')) return inner
+    // URLSearchParams-mangled form: parse and find the key whose decoded
+    // name starts with `/` (that's the route). Surviving params become
+    // the storyboard URL state on the recovered hash.
+    try {
+      const params = new URLSearchParams(inner)
+      let route = ''
+      const restPairs = []
+      for (const [key, value] of params) {
+        if (!route && key.startsWith('/')) {
+          // Storyboard never persists state with `/`-prefixed keys, and the
+          // mangled form always puts the route first — so first match wins.
+          // The route had no `=` in the original URL, so value is empty.
+          // If a `?query=...` survived alongside, append it back.
+          route = value ? `${key}?${key}=${value}` : key
+        } else {
+          restPairs.push(`${key}=${value}`)
+        }
+      }
+      if (route) {
+        return restPairs.length > 0 ? `${route}#${restPairs.join('&')}` : route
+      }
+    } catch { /* fall through */ }
+    // Last-resort: prefix `/` so we at least produce a routable path.
+    return `/${inner}`
+  }
+  // Path-form: `/prototypes.html/inner...` — defensive.
+  const pathMatch = src.match(/^\/?(?:[^#?]*\/)?prototypes\.html(\/[^]*)$/)
+  if (pathMatch) {
+    const inner = pathMatch[1] || ''
+    return inner || '/'
+  }
+  return src
+}

package/src/internals/vite/data-plugin.js

@@ -1248,7 +1248,7 @@ export default function storyboardDataPlugin() {
           url = url.slice(baseNoTrail.length) || '/'
         }
         const cleanUrl = url.split('?')[0].split('#')[0]
-        if (cleanUrl !== '/prototypes.html') return next()
+        if (cleanUrl !== '/prototypes.html' && !cleanUrl.startsWith('/prototypes.html/')) return next()
 
         // Theme bootstrap mirrors index.html so the iframe paints with the
         // correct color mode on first frame (before mountStoryboardCore