@dfosco/storyboard 0.6.13 → 0.6.15

package/package.json

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

package/src/core/mountStoryboardCore.js

@@ -399,12 +399,7 @@ export async function mountStoryboardCore(config = {}, options = {}) {
         if (currentHref !== lastHref) {
           lastHref = currentHref
           const basePath = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
-          const pathname = window.location.pathname
-          const hash = window.location.hash
-          const stripped = basePath && pathname.startsWith(basePath)
-            ? pathname.slice(basePath.length) || '/'
-            : pathname.replace(/^\/branch--[^/]+/, '') || '/'
-          const src = stripped + hash
+          const src = computeEmbedNavigationSrc(window.location.pathname, window.location.hash, basePath)
           window.parent.postMessage({ type: 'storyboard:embed:navigate', src }, '*')
         }
       }
@@ -462,6 +457,48 @@ export async function mountStoryboardCore(config = {}, options = {}) {
   handlePendingNavigation()
 }
 
+/**
+ * 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` 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
+ * the base path (and any `/branch--xxx/` deploy prefix) and append the hash.
+ *
+ * Exported for tests.
+ */
+export function computeEmbedNavigationSrc(pathname, hash, basePath = '') {
+  const cleanBase = (basePath || '').replace(/\/$/, '')
+  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 '/'
+    return inner.startsWith('/') ? inner : `/${inner}`
+  }
+  return stripped + (hash || '')
+}
+
 /**
  * Check sessionStorage for a pending navigation target.
  * Used by PageSelector when creating a new canvas page — Vite does a full-reload

package/src/core/mountStoryboardCore.test.js

@@ -0,0 +1,174 @@
+import { computeEmbedNavigationSrc } from './mountStoryboardCore.js'
+
+describe('computeEmbedNavigationSrc', () => {
+  describe('prod mode (direct route in pathname)', () => {
+    it('strips basePath and appends hash', () => {
+      expect(computeEmbedNavigationSrc('/cq-org-enablement', '#sectionA', '/')).toBe(
+        '/cq-org-enablement#sectionA',
+      )
+    })
+
+    it('handles non-root basePath', () => {
+      expect(
+        computeEmbedNavigationSrc('/storyboard/cq-org-enablement', '#x', '/storyboard/'),
+      ).toBe('/cq-org-enablement#x')
+    })
+
+    it('strips /branch--xxx/ deploy prefix', () => {
+      expect(
+        computeEmbedNavigationSrc('/branch--my-feature/cq-org-enablement', '#x', '/'),
+      ).toBe('/cq-org-enablement#x')
+    })
+
+    it('returns "/" when pathname equals basePath', () => {
+      expect(computeEmbedNavigationSrc('/storyboard', '', '/storyboard/')).toBe('/')
+    })
+
+    it('handles missing hash', () => {
+      expect(computeEmbedNavigationSrc('/MyProto', '', '/')).toBe('/MyProto')
+    })
+  })
+
+  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', '/'),
+      ).toBe('/cq-org-enablement')
+    })
+
+    it('preserves query string inside hash', () => {
+      expect(
+        computeEmbedNavigationSrc(
+          '/prototypes.html',
+          '#/cq-org-enablement?flow=cq-org-enablement/default&cqConfirmOpen=true',
+          '/',
+        ),
+      ).toBe('/cq-org-enablement?flow=cq-org-enablement/default&cqConfirmOpen=true')
+    })
+
+    it('handles non-root basePath', () => {
+      expect(
+        computeEmbedNavigationSrc('/storyboard/prototypes.html', '#/MyProto', '/storyboard/'),
+      ).toBe('/MyProto')
+    })
+
+    it('handles branch deploy basePath', () => {
+      expect(
+        computeEmbedNavigationSrc(
+          '/branch--feature-x/prototypes.html',
+          '#/MyProto',
+          '/branch--feature-x/',
+        ),
+      ).toBe('/MyProto')
+    })
+
+    it('prefixes inner hash with "/" if missing', () => {
+      expect(
+        computeEmbedNavigationSrc('/prototypes.html', '#MyProto', '/'),
+      ).toBe('/MyProto')
+    })
+
+    it('returns "/" for empty hash', () => {
+      expect(computeEmbedNavigationSrc('/prototypes.html', '', '/')).toBe('/')
+    })
+
+    it('returns "/" for hash that is just "#"', () => {
+      expect(computeEmbedNavigationSrc('/prototypes.html', '#', '/')).toBe('/')
+    })
+  })
+
+  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.
+    //
+    // 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.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,6 +27,33 @@ function formatName(name) {
     .replace(/\b\w/g, (c) => c.toUpperCase())
 }
 
+// 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
+  // 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() {
   if (typeof localStorage === 'undefined') return 'light'
   let sync = { prototype: true, toolbar: false, codeBoxes: true, canvas: false }
@@ -46,7 +73,7 @@ function resolveCanvasThemeFromStorage() {
 const HEADER_HEIGHT = 37
 
 export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdate, resizable }, ref) {
-  const src = readProp(props, 'src', prototypeEmbedSchema)
+  const src = normalizeLegacyEmbedSrc(readProp(props, 'src', prototypeEmbedSchema))
   const width = readProp(props, 'width', prototypeEmbedSchema) || 800
   const height = readProp(props, 'height', prototypeEmbedSchema) || 600
   const zoom = readProp(props, 'zoom', prototypeEmbedSchema) || 100
@@ -58,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
@@ -94,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])
 
@@ -309,7 +339,10 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     function handleMessage(e) {
       if (e.source !== iframeRef.current?.contentWindow) return
       if (e.data?.type !== 'storyboard:embed:navigate') return
-      const newSrc = e.data.src
+      // Defensive: older consumer embeds reported `/prototypes.html#/route`
+      // here (loader path + hash). Normalize to the inner route so we never
+      // persist the broken form.
+      const newSrc = normalizeLegacyEmbedSrc(e.data.src)
       if (newSrc && newSrc !== src) {
         const originalSrc = readProp(props, 'originalSrc', prototypeEmbedSchema)
         onUpdate?.({ src: newSrc, originalSrc: originalSrc || 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