@dfosco/storyboard 0.6.14 → 0.6.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "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

@@ -27,19 +27,31 @@ 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.
+// Self-heal canvases that persisted a dev-isolation loader URL as the widget src.
+// Two legacy shapes exist:
+//   - `/prototypes.html#/MyProto?...` — 0.6.13 and older, when the iframe
+//     broadcast pathname+hash and routing lived in the hash
+//   - `/prototypes.html/MyProto?...` — could appear if a future broadcaster
+//     ever forwards the loader path verbatim with the new browser-router layout
+// Without 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}`
+  // Hash-form: `/prototypes.html#/inner` or `/storyboard/prototypes.html#/inner`
+  const hashMatch = src.match(/^\/?(?:[^#]*\/)?prototypes\.html#(.*)$/)
+  if (hashMatch) {
+    const inner = hashMatch[1] || ''
+    if (!inner) return '/'
+    return inner.startsWith('/') ? inner : `/${inner}`
+  }
+  // Path-form: `/prototypes.html/inner...` or `/storyboard/prototypes.html/inner...`
+  const pathMatch = src.match(/^\/?(?:[^#?]*\/)?prototypes\.html(\/[^]*)$/)
+  if (pathMatch) {
+    const inner = pathMatch[1] || ''
+    return inner || '/'
+  }
+  return src
 }
 
 function resolveCanvasThemeFromStorage() {
@@ -73,13 +85,15 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   //   - 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 +123,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/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