@dfosco/storyboard 0.7.0 → 0.8.1

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/context.jsx

@@ -70,6 +70,7 @@ function getCanvasGroupMap() {
       name,
       route,
       title: data?.title || name.split('/').pop(),
+      isPrivate: !!data?._isPrivate,
       _canvasMeta: data?._canvasMeta || null,
     })
   }
@@ -131,6 +132,14 @@ function matchStoryRoute(pathname) {
  * Strip the app's sub-path prefix (e.g. /storyboard) from the pathname.
  * React Router's basename strips the branch prefix but not the app name prefix
  * when the app runs under a nested base path.
+ *
+ * Two prefixing scenarios are handled:
+ *   1. Branch deploys — BASE_URL is `/branch--xxx/{devDomain}/`, so we strip
+ *      whatever app sub-path remains after the branch prefix.
+ *   2. Local dev via Caddy proxy — BASE_URL is `/` (Caddy strips `/{devDomain}/`
+ *      before forwarding to the dev server), but window.location.pathname is
+ *      still `/{devDomain}/...`. React Router's basename `/` doesn't strip it,
+ *      so we rely on the injected `__SB_DEV_DOMAIN__` global instead.
  */
 function stripBasePath(pathname) {
   let p = pathname.replace(/\/+$/, '') || '/'
@@ -145,6 +154,18 @@ function stripBasePath(pathname) {
       p = p.slice(subPath.length) || '/'
     }
   }
+  // Local dev via Caddy proxy: window.location.pathname includes the
+  // /{devDomain}/ prefix that Caddy strips before reaching the dev server.
+  // BASE_URL is `/` in this scenario, so the block above is a no-op.
+  if (typeof window !== 'undefined' && window.__SB_LOCAL_DEV__ && window.__SB_DEV_DOMAIN__) {
+    const devDomain = String(window.__SB_DEV_DOMAIN__).replace(/^\/+|\/+$/g, '')
+    if (devDomain) {
+      const devPrefix = '/' + devDomain
+      if (p === devPrefix || p.startsWith(devPrefix + '/')) {
+        p = p.slice(devPrefix.length) || '/'
+      }
+    }
+  }
   return p
 }
 
@@ -428,7 +449,7 @@ function StoryboardProviderInner({ flowName, sceneName, recordName, recordParam,
     const _hmrTick = canvasIndexKey
     const siblingPages = group
       ? getCanvasGroupMap().get(group) || []
-      : [{ name: canvasId, route: canvasData?._route || `/canvas/${canvasId}`, title: canvasData?.title || canvasId.split('/').pop() }]
+      : [{ name: canvasId, route: canvasData?._route || `/canvas/${canvasId}`, title: canvasData?.title || canvasId.split('/').pop(), isPrivate: !!canvasData?._isPrivate }]
     const canvasMeta = canvasData?._canvasMeta || null
     const canvasValue = {
       data: null,

package/src/internals/context.test.jsx

@@ -293,4 +293,51 @@ describe('StoryboardProvider', () => {
     expect(screen.getByText('Canvas not found')).toBeInTheDocument()
     expect(screen.getByRole('link', { name: /go to index page/i })).toHaveAttribute('href', '/')
   })
+
+  it('strips dev-domain prefix in local dev (Caddy proxy) so canvas routes resolve', () => {
+    // Local dev via Caddy: window.location.pathname includes the /{devDomain}/
+    // prefix even though BASE_URL is `/` (the proxy strips it before forwarding
+    // to the dev server). Without stripping, isCanvasPath returns false and the
+    // 404 never renders — the canvas page just stays blank.
+    const origLocalDev = window.__SB_LOCAL_DEV__
+    const origDomain = window.__SB_DEV_DOMAIN__
+    window.__SB_LOCAL_DEV__ = true
+    window.__SB_DEV_DOMAIN__ = 'storyboard'
+    try {
+      mockUseLocation.mockReturnValue({ pathname: '/storyboard/canvas/unknown-board', search: '', hash: '' })
+
+      render(
+        <StoryboardProvider>
+          <ContextReader />
+        </StoryboardProvider>,
+      )
+
+      expect(screen.getByText('Canvas not found')).toBeInTheDocument()
+    } finally {
+      window.__SB_LOCAL_DEV__ = origLocalDev
+      window.__SB_DEV_DOMAIN__ = origDomain
+    }
+  })
+
+  it('does not strip dev-domain prefix when __SB_LOCAL_DEV__ is not set', () => {
+    // Same URL shape, but production-like: prefix should be left alone so it
+    // doesn't accidentally match canvas routes for unrelated path segments.
+    const origDomain = window.__SB_DEV_DOMAIN__
+    window.__SB_DEV_DOMAIN__ = 'storyboard'
+    try {
+      mockUseLocation.mockReturnValue({ pathname: '/storyboard/canvas/unknown-board', search: '', hash: '' })
+
+      render(
+        <StoryboardProvider>
+          <ContextReader />
+        </StoryboardProvider>,
+      )
+
+      // isCanvasPath sees `/storyboard/canvas/...` → does NOT start with `/canvas/`
+      // → no 404, just renders flow context
+      expect(screen.queryByText('Canvas not found')).not.toBeInTheDocument()
+    } finally {
+      window.__SB_DEV_DOMAIN__ = origDomain
+    }
+  })
 })

package/src/internals/hooks/useArtifactIndex.js

@@ -0,0 +1,31 @@
+import { useEffect, useMemo, useState } from 'react'
+import { fetchArtifactIndex } from '../../core/data/artifactIndex.js'
+
+function isLocalDev() {
+  return typeof window !== 'undefined' && window.__SB_LOCAL_DEV__ === true
+}
+
+export function useArtifactIndex(basePath) {
+  const normalizedBasePath = useMemo(() => basePath || '/', [basePath])
+  const localDev = isLocalDev()
+  const [state, setState] = useState(() => ({ artifactIndex: null, loading: !localDev }))
+
+  useEffect(() => {
+    if (localDev) return undefined
+
+    let cancelled = false
+
+    fetchArtifactIndex(normalizedBasePath)
+      .then(index => {
+        if (!cancelled) setState({ artifactIndex: index, loading: false })
+      })
+      .catch(() => {
+        if (!cancelled) setState({ artifactIndex: null, loading: false })
+      })
+
+    return () => { cancelled = true }
+  }, [localDev, normalizedBasePath])
+
+  if (localDev) return { artifactIndex: null, loading: false }
+  return state
+}

package/src/internals/hooks/useArtifactIndex.test.js

@@ -0,0 +1,45 @@
+import { renderHook, waitFor } from '@testing-library/react'
+import { useArtifactIndex } from './useArtifactIndex.js'
+
+describe('useArtifactIndex', () => {
+  afterEach(() => {
+    delete window.__SB_LOCAL_DEV__
+    vi.unstubAllGlobals()
+  })
+
+  it('short-circuits in local dev without fetching', () => {
+    window.__SB_LOCAL_DEV__ = true
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    const { result } = renderHook(() => useArtifactIndex('/storyboard/'))
+
+    expect(result.current).toEqual({ artifactIndex: null, loading: false })
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('returns the parsed index after fetching', async () => {
+    const index = { schemaVersion: 1, branches: [], prototypes: {}, canvases: {} }
+    const fetchMock = vi.fn(async () => ({ ok: true, json: async () => index }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const { result } = renderHook(() => useArtifactIndex('/storyboard/branch--feature-foo/'))
+
+    await waitFor(() => {
+      expect(result.current.artifactIndex).toBe(index)
+      expect(result.current.loading).toBe(false)
+    })
+    expect(fetchMock).toHaveBeenCalledWith('/storyboard/artifacts.index.json')
+  })
+
+  it('returns null on fetch failure without throwing', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => { throw new Error('offline') }))
+
+    const { result } = renderHook(() => useArtifactIndex('/storyboard/'))
+
+    await waitFor(() => {
+      expect(result.current.loading).toBe(false)
+    })
+    expect(result.current.artifactIndex).toBeNull()
+  })
+})

package/src/internals/hooks/usePrototypeReloadGuard.js

@@ -1,19 +1,24 @@
 /**
- * Prototype reload guard — suppresses Vite HMR full-reloads for non-canvas pages.
+ * Embed reload guard — suppresses Vite HMR full-reloads for iframe-embedded
+ * pages (prototypes and stories alike).
  *
  * Controlled by the "prototype-auto-reload" feature flag (default: false).
+ * The flag name predates story-widget support; it now toggles the guard
+ * for both prototypes AND stories, which share the policy: drop
+ * `full-reload` payloads so in-page state survives unrelated file edits,
+ * but let `update` payloads through so React Fast Refresh works.
  *
  * The default is false (guard ON) because the dev server emits frequent
  * full-reload broadcasts from data-plugin watchers; without the guard,
- * prototype pages get stuck in a reload loop. Users can opt in via the
+ * embedded pages get stuck in a reload loop. Users can opt in via the
  * devtools menu.
- * When the flag is false (user opted out), sends heartbeat messages to the
- * Vite dev server which suppresses full-reload and update payloads for this
- * client. Custom storyboard events (canvas file changes, story changes, etc.)
- * always pass through.
  *
  * Heartbeats are sent every 3s and auto-expire server-side after 5s, so
  * closed tabs never leave the guard stuck.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.enabled=true] — when false, no heartbeats are sent
+ *        (used by pages that only want to guard when in embed mode).
  */
 import { useEffect } from 'react'
 import { getFlag, subscribeToStorage } from '../../core/index.js'
@@ -21,8 +26,9 @@ import { getFlag, subscribeToStorage } from '../../core/index.js'
 const FLAG_KEY = 'prototype-auto-reload'
 const HEARTBEAT_MS = 3000
 
-export default function usePrototypeReloadGuard() {
+export default function usePrototypeReloadGuard({ enabled = true } = {}) {
   useEffect(() => {
+    if (!enabled) return
     if (!import.meta.hot) return
 
     let interval = null
@@ -64,5 +70,5 @@ export default function usePrototypeReloadGuard() {
       stop()
       unsub()
     }
-  }, [])
+  }, [enabled])
 }

package/src/internals/index.js

@@ -41,9 +41,15 @@ export { default as Workspace } from './Workspace.jsx'
 // Deprecated alias — use Workspace instead
 export { default as Viewfinder } from './Workspace.jsx'
 
+// Simplified workspace — dev-only "old index" view, falls back to Workspace in prod
+export { default as SimpleWorkspace } from './SimpleWorkspace/SimpleWorkspace.jsx'
+
 // Command Palette (includes BranchBar automatically)
 export { default as StoryboardCommandPalette } from './CommandPalette/CommandPalette.jsx'
 
+// Create-only page (used by `storyboard create --ui`)
+export { default as CreatePage } from './CreatePage/CreatePage.jsx'
+
 // Branch Bar (standalone, for consumers who don't use CommandPalette)
 export { default as BranchBar } from './BranchBar/BranchBar.jsx'
 

package/src/internals/loadConsumerWrapper.js

@@ -0,0 +1,60 @@
+/**
+ * loadConsumerWrapper — resolves the consumer's `src/_prototype.jsx` or
+ * `src/_story.jsx` at runtime so storyboard internals (prototype routes,
+ * story page, inline story renderer, isolate iframes) can wrap rendered
+ * content with the consumer's design-system providers.
+ *
+ * These two files are documented as **the** seam between storyboard
+ * scaffolding and consumer source code. See plan
+ * `.github/plans/style-separation.md`.
+ *
+ * Falls back to a Fragment pass-through when the wrapper file is absent —
+ * which corresponds to "blank slate", the new default.
+ *
+ * Why a glob: `import.meta.glob` resolves paths against the *consumer*
+ * Vite project root, so the same code path works in source-repo dev and in
+ * published-package consumers.
+ *
+ * Why lazy (no eager): we want to defer wrapper-file evaluation until
+ * something actually needs to render. Eager evaluation would pull every
+ * wrapper module into the test environment (the wrappers typically import
+ * design-system code that doesn't mock cleanly), and would inflate the
+ * initial bundle even when no story/prototype is visible.
+ */
+import { Fragment, lazy, createElement } from 'react'
+
+const PROTOTYPE_MODULES = import.meta.glob(
+  ['/src/_prototype.jsx', '/src/_prototype.tsx'],
+)
+const STORY_MODULES = import.meta.glob(
+  ['/src/_story.jsx', '/src/_story.tsx'],
+)
+
+function PassThrough({ children }) {
+  return createElement(Fragment, null, children)
+}
+
+function makeLazyWrapper(modules) {
+  const keys = Object.keys(modules)
+  if (keys.length === 0) return PassThrough
+  return lazy(async () => {
+    const mod = await modules[keys[0]]()
+    if (typeof mod?.default === 'function') return { default: mod.default }
+    return { default: PassThrough }
+  })
+}
+
+let _protoCache
+let _storyCache
+
+/** Wrapper for prototype routes (workspace SPA + iframe entries). */
+export function getPrototypeWrapper() {
+  if (!_protoCache) _protoCache = makeLazyWrapper(PROTOTYPE_MODULES)
+  return _protoCache
+}
+
+/** Wrapper for story renders (StoryPage, ComponentSetPage, isolates, inline renderer). */
+export function getStoryWrapper() {
+  if (!_storyCache) _storyCache = makeLazyWrapper(STORY_MODULES)
+  return _storyCache
+}

package/src/internals/story/ComponentSetPage.jsx

@@ -12,12 +12,15 @@
  * `storyboard:component-set:select` to the parent window so the
  * canvas widget can track which export the user picked.
  */
-import { useState, useEffect, useLayoutEffect, useMemo, useCallback, useRef } from 'react'
+import { useState, useEffect, useLayoutEffect, useMemo, useCallback, useRef, Suspense } from 'react'
 import { useLocation, useNavigate } from 'react-router-dom'
 import { getStoryData } from '../../core/index.js'
-import { ThemeProvider, BaseStyles } from '@primer/react'
+import { getStoryWrapper } from '../loadConsumerWrapper.js'
+import usePrototypeReloadGuard from '../hooks/usePrototypeReloadGuard.js'
 import styles from './ComponentSetPage.module.css'
 
+const StoryWrapper = getStoryWrapper()
+
 export default function ComponentSetPage({ name }) {
   const location = useLocation()
   const navigate = useNavigate()
@@ -28,19 +31,8 @@ export default function ComponentSetPage({ name }) {
   const selected = searchParams.get('selected') || ''
   const isEmbed = searchParams.has('_sb_embed')
 
-  // Suppress HMR full-reloads when embedded as a canvas iframe
-  useEffect(() => {
-    if (!isEmbed || !import.meta.hot) return
-    const msg = { active: true }
-    import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-    const interval = setInterval(() => {
-      import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-    }, 3000)
-    return () => {
-      clearInterval(interval)
-      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false })
-    }
-  }, [isEmbed])
+  // Same reload-guard policy as StoryPage / prototype embeds.
+  usePrototypeReloadGuard({ enabled: isEmbed })
 
   const story = useMemo(() => getStoryData(name), [name])
   const [exports, setExports] = useState(null)
@@ -89,28 +81,77 @@ export default function ComponentSetPage({ name }) {
 
   const gridRef = useRef(null)
 
-  // Post total grid size to parent widget so the canvas can auto-fit.
-  // No snap-to-max: each cell sizes to its own content.
+  // Post size info to parent widget so the canvas can auto-fit on first
+  // render AND snap-to-content on resize end.
+  //
+  // Two messages, mirrored from the legacy componentSetIsolate.jsx:
+  //   - :initial-size — squarish layout hint computed from the *max* cell
+  //     dimensions, used by StorySetWidget when the widget has no width/height
+  //     set yet.
+  //   - :content-size — live cell-bounding-box extent, used by StorySetWidget
+  //     to snap width/height down to fit after a user resize. Measured from
+  //     bounding boxes (not scrollWidth/scrollHeight) so the reported size
+  //     reflects the *natural* cell extent — scrollWidth always matches the
+  //     container width when the widget is wider than needed, which would
+  //     defeat width-snapping.
   useLayoutEffect(() => {
     const grid = gridRef.current
     if (!grid || !exports) return
+    if (!isEmbed || window.parent === window) return
+
+    let postedInitial = false
+    function postInitialSize() {
+      if (postedInitial) return
+      const cells = grid.querySelectorAll(`.${styles.cell}`)
+      if (cells.length === 0) return
+      let maxW = 0
+      let maxH = 0
+      cells.forEach((cell) => {
+        const r = cell.getBoundingClientRect()
+        if (r.width > maxW) maxW = r.width
+        if (r.height > maxH) maxH = r.height
+      })
+      if (maxW < 10 || maxH < 10) return
+      const count = cells.length
+      const cols = Math.max(1, Math.min(count, Math.ceil(Math.sqrt(count))))
+      const rows = Math.ceil(count / cols)
+      const gap = 16
+      const pad = 32 // 16px padding on both sides
+      const width = Math.ceil(maxW * cols + gap * (cols - 1) + pad)
+      const height = Math.ceil(maxH * rows + gap * (rows - 1) + pad)
+      postedInitial = true
+      window.parent.postMessage({
+        type: 'storyboard:component-set:initial-size',
+        width,
+        height,
+      }, '*')
+    }
 
-    function measure() {
-      if (isEmbed && window.parent !== window) {
-        requestAnimationFrame(() => {
-          window.parent.postMessage({
-            type: 'storyboard:component-set:resize',
-            width: grid.scrollWidth,
-            height: grid.scrollHeight,
-          }, '*')
-        })
-      }
+    function postContentSize() {
+      const cells = grid.querySelectorAll(`.${styles.cell}`)
+      if (!cells.length) return
+      const gridRect = grid.getBoundingClientRect()
+      let maxRight = 0
+      let maxBottom = 0
+      cells.forEach((cell) => {
+        const r = cell.getBoundingClientRect()
+        const right = r.right - gridRect.left
+        const bottom = r.bottom - gridRect.top
+        if (right > maxRight) maxRight = right
+        if (bottom > maxBottom) maxBottom = bottom
+      })
+      const pad = 16 // mirror grid padding
+      window.parent.postMessage({
+        type: 'storyboard:component-set:content-size',
+        width: Math.ceil(maxRight + pad),
+        height: Math.ceil(maxBottom + pad),
+      }, '*')
     }
 
-    measure()
-    document.fonts.ready.then(() => requestAnimationFrame(measure))
+    requestAnimationFrame(() => requestAnimationFrame(postInitialSize))
+    document.fonts.ready.then(() => requestAnimationFrame(postInitialSize))
 
-    const ro = new ResizeObserver(measure)
+    const ro = new ResizeObserver(postContentSize)
     ro.observe(grid)
     return () => ro.disconnect()
   }, [exports, layout, density, isEmbed])
@@ -151,8 +192,8 @@ export default function ComponentSetPage({ name }) {
   const exportNames = Object.keys(exports)
 
   return (
-    <ThemeProvider colorMode="day">
-      <BaseStyles>
+    <Suspense fallback={null}>
+      <StoryWrapper>
         <div
           ref={gridRef}
           className={styles.grid}
@@ -188,7 +229,7 @@ export default function ComponentSetPage({ name }) {
             )
           })}
         </div>
-      </BaseStyles>
-    </ThemeProvider>
+      </StoryWrapper>
+    </Suspense>
   )
 }

package/src/internals/story/StoryPage.jsx

@@ -8,9 +8,12 @@
 import { useState, useEffect, useMemo, lazy, Suspense } from 'react'
 import { useLocation } from 'react-router-dom'
 import { getStoryData } from '../../core/index.js'
-import { ThemeProvider, BaseStyles } from '@primer/react'
+import { getStoryWrapper } from '../loadConsumerWrapper.js'
+import usePrototypeReloadGuard from '../hooks/usePrototypeReloadGuard.js'
 import styles from './StoryPage.module.css'
 
+const StoryWrapper = getStoryWrapper()
+
 const ComponentSetPageLazy = lazy(() => import('./ComponentSetPage.jsx'))
 
 function StoryErrorFallback({ name, error }) {
@@ -29,22 +32,10 @@ export default function StoryPage({ name }) {
   const isEmbed = searchParams.has('_sb_embed')
   const isComponentSet = searchParams.has('_sb_component_set')
 
-  // When embedded as a canvas iframe, suppress HMR full-reloads.
-  // Story content updates via React Fast Refresh; a full-reload
-  // causes a visible flash and can create a reload loop when
-  // multiple story iframes are on the same canvas.
-  useEffect(() => {
-    if (!isEmbed || !import.meta.hot) return
-    const msg = { active: true }
-    import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-    const interval = setInterval(() => {
-      import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-    }, 3000)
-    return () => {
-      clearInterval(interval)
-      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false })
-    }
-  }, [isEmbed])
+  // Share the same reload-guard policy as prototypes: drop full-reloads so
+  // the embedding canvas's data-file edits don't flash the story iframe,
+  // but let `update` payloads through so React Fast Refresh works.
+  usePrototypeReloadGuard({ enabled: isEmbed })
 
   const story = useMemo(() => getStoryData(name), [name])
   const [exports, setExports] = useState(null)
@@ -123,11 +114,11 @@ export default function StoryPage({ name }) {
     }
 
     return (
-      <ThemeProvider colorMode="day">
-        <BaseStyles>
+      <Suspense fallback={null}>
+        <StoryWrapper>
           <Component />
-        </BaseStyles>
-      </ThemeProvider>
+        </StoryWrapper>
+      </Suspense>
     )
   }
 
@@ -135,13 +126,13 @@ export default function StoryPage({ name }) {
   const exportNames = Object.keys(exports)
 
   return (
-    <ThemeProvider colorMode="day">
-      <BaseStyles>
+    <Suspense fallback={null}>
+      <StoryWrapper>
         {exportNames.map((exportName) => {
           const Component = exports[exportName]
           return <Component key={exportName} />
         })}
-      </BaseStyles>
-    </ThemeProvider>
+      </StoryWrapper>
+    </Suspense>
   )
 }