@dfosco/storyboard 0.6.15 → 0.6.16

package/package.json

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

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,33 +28,6 @@ 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 }
@@ -73,12 +47,23 @@ 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`:

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
+}