@dfosco/storyboard-react 4.0.0-beta.35 → 4.0.0-beta.36

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "4.0.0-beta.35",
+  "version": "4.0.0-beta.36",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "4.0.0-beta.35",
-    "@dfosco/tiny-canvas": "4.0.0-beta.35",
+    "@dfosco/storyboard-core": "4.0.0-beta.36",
+    "@dfosco/tiny-canvas": "4.0.0-beta.36",
     "@neodrag/react": "^2.3.1",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1",

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -133,19 +133,22 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
       .filter(Boolean)
   }, [pickerGroups, filter])
 
-  const prototypeName = useMemo(() => {
-    if (!src) return ''
+  const prototypeTitle = useMemo(() => {
+    if (!src) return label || 'Prototype'
+    const cleanSrc = src.replace(/^\/branch--[^/]+/, '')
     for (const group of pickerGroups) {
       for (const item of group.items) {
         const cleanRoute = item.route.replace(/^\/branch--[^/]+/, '')
-        const cleanSrc = src.replace(/^\/branch--[^/]+/, '')
-        if (cleanRoute === cleanSrc) return item.name
+        if (cleanRoute === cleanSrc) {
+          // If the flow name matches the group name, just show the name
+          if (item.name === group.label) return group.label
+          return `${group.label} · ${item.name}`
+        }
       }
     }
-    return ''
-  }, [src, pickerGroups])
+    return label || 'Prototype'
+  }, [src, label, pickerGroups])
 
-  const prototypeTitle = prototypeName || label || 'Prototype'
   const hasPicker = pickerGroups.length > 0
 
   useIframeDevLogs({

package/src/canvas/widgets/StoryWidget.jsx

@@ -1,11 +1,8 @@
 /**
  * Renders a story at its route URL inside an iframe on canvas.
  *
- * Works like PrototypeEmbed: the story has its own route (e.g. /components/button-patterns)
- * and this widget iframes that URL with ?export=ExportName&_sb_embed for single-export mode.
- *
  * Features:
- * - Title bar showing story name + export (like Figma embed)
+ * - Title bar showing story name + export
  * - "Show code" action toggles between iframe and source view
  * - "Copy code" action copies the story source to clipboard
  *
@@ -17,9 +14,6 @@ import { createInspectorHighlighter } from '@dfosco/storyboard-core/inspector/hi
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
 import { useIframeDevLogs } from './iframeDevLogs.js'
-import { useSnapshotCapture } from './useSnapshotCapture.js'
-import { subscribeCanvasTheme } from './embedTheme.js'
-import { enqueueRefresh, cancelRefresh, REVEAL_INTERVAL } from './refreshQueue.js'
 import styles from './StoryWidget.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
@@ -28,58 +22,32 @@ function ComponentIcon({ size = 36 }) {
     <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" aria-hidden="true">
       <path d="M5.21173 15.1113L2.52473 12.4243C2.29041 12.1899 2.29041 11.8101 2.52473 11.5757L5.21173 8.88873C5.44605 8.65442 5.82595 8.65442 6.06026 8.88873L8.74727 11.5757C8.98158 11.8101 8.98158 12.1899 8.74727 12.4243L6.06026 15.1113C5.82595 15.3456 5.44605 15.3456 5.21173 15.1113Z" />
       <path d="M11.5757 21.475L8.88874 18.788C8.65443 18.5537 8.65443 18.1738 8.88874 17.9395L11.5757 15.2525C11.8101 15.0182 12.19 15.0182 12.4243 15.2525L15.1113 17.9395C15.3456 18.1738 15.3456 18.5537 15.1113 18.788L12.4243 21.475C12.19 21.7094 11.8101 21.7094 11.5757 21.475Z" />
-      <path d="M11.5757 8.7475L8.88874 6.06049C8.65443 5.82618 8.65443 5.44628 8.88874 5.21197L11.5757 2.52496C11.8101 2.29065 12.19 2.29065 12.4243 2.52496L15.1113 5.21197C15.3456 5.44628 15.3456 5.82618 15.1113 6.06049L12.4243 8.7475C12.19 8.98181 11.8101 8.98181 11.5757 8.7475Z" />
-      <path d="M17.9396 15.1113L15.2526 12.4243C15.0183 12.1899 15.0183 11.8101 15.2526 11.5757L17.9396 8.88873C18.174 8.65442 18.5539 8.65442 18.7882 8.88873L21.4752 11.5757C21.7095 11.8101 21.7095 12.1899 21.4752 12.4243L18.7882 15.1113C18.5539 15.3456 18.174 15.3456 17.9396 15.1113Z" />
+      <path d="M17.9395 15.1113L15.2525 12.4243C15.0182 12.1899 15.0182 11.8101 15.2525 11.5757L17.9395 8.88873C18.1738 8.65442 18.5537 8.65442 18.788 8.88873L21.475 11.5757C21.7094 11.8101 21.7094 12.1899 21.475 12.4243L18.788 15.1113C18.5537 15.3456 18.1738 15.3456 17.9395 15.1113Z" />
+      <path d="M11.5757 8.74727L8.88874 6.06026C8.65443 5.82595 8.65443 5.44605 8.88874 5.21173L11.5757 2.52473C11.8101 2.29041 12.19 2.29041 12.4243 2.52473L15.1113 5.21173C15.3456 5.44605 15.3456 5.82595 15.1113 6.06026L12.4243 8.74727C12.19 8.98158 11.8101 8.98158 11.5757 8.74727Z" />
     </svg>
   )
 }
 
 function resolveStoryUrl(storyId, exportName) {
   const story = getStoryData(storyId)
-  if (!story?._route) return null
-
+  if (!story?._route) return ''
   const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
-  const route = story._route
-  const params = new URLSearchParams({ _sb_embed: '1', _sb_theme_target: 'prototype' })
+  const params = new URLSearchParams()
   if (exportName) params.set('export', exportName)
-
-  return `${base}${route}?${params}`
-}
-
-/** Resolve a module path with the app base URL for dynamic imports. */
-function resolveModulePath(modulePath) {
-  if (!modulePath || !modulePath.startsWith('/')) return modulePath
-  const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
-  return base ? `${base}${modulePath}` : modulePath
+  params.set('_sb_embed', '')
+  return `${base}${story._route}?${params}`
 }
 
-/** Cache for the static story sources JSON fetched in prod builds. */
-let _storySourcesCache = null
+const _storySourcesCache = {}
 
-/**
- * Fetch story source code. In dev, uses Vite's ?raw dynamic import.
- * In prod, fetches from the build-time _storyboard/stories/sources.json.
- */
 async function fetchStorySource(modulePath) {
-  // Dev: use Vite's ?raw import for live source
-  if (import.meta.env.DEV) {
-    const mod = await import(/* @vite-ignore */ `${resolveModulePath(modulePath)}?raw`)
-    return mod.default || ''
-  }
-
-  // Prod: load from static JSON endpoint (same pattern as inspector.json)
-  if (!_storySourcesCache) {
-    const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
-    const res = await fetch(`${base}/_storyboard/stories/sources.json`)
-    if (!res.ok) throw new Error(`Story sources not available (${res.status})`)
-    _storySourcesCache = await res.json()
-  }
-
-  // _storyModule is like "/src/canvas/stories/foo.story.jsx" — strip leading /
-  const key = modulePath.startsWith('/') ? modulePath.slice(1) : modulePath
-  const source = _storySourcesCache[key]
-  if (source == null) throw new Error(`Source not found for ${key}`)
-  return source
+  if (modulePath in _storySourcesCache) return _storySourcesCache[modulePath]
+  const url = modulePath.startsWith('/') ? modulePath : `/${modulePath}`
+  const res = await fetch(`${url}?raw`)
+  if (!res.ok) throw new Error(`Failed to fetch ${url}`)
+  const code = await res.text()
+  _storySourcesCache[modulePath] = code
+  return code
 }
 
 export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate, resizable }, ref) {
@@ -87,60 +55,17 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const exportName = props?.exportName || ''
   const width = props?.width
   const height = props?.height
-  const snapshot = props?.snapshot || props?.snapshotLight || props?.snapshotDark || ''
 
   const containerRef = useRef(null)
   const iframeRef = useRef(null)
-  const resizeTimerRef = useRef(null)
-  const captureOnReadyRef = useRef(false)
-  const exitSessionRef = useRef(0)
-  const refreshMetaRef = useRef(null)
   const [interactive, setInteractive] = useState(false)
-  const [showIframe, setShowIframe] = useState(false)
-  const [iframeLoaded, setIframeLoaded] = useState(false)
   const [showCode, setShowCode] = useState(!!props?.showCode)
   const [sourceCode, setSourceCode] = useState(null)
   const [highlightedHtml, setHighlightedHtml] = useState(null)
   const [sourceLoading, setSourceLoading] = useState(false)
   const [storyIndexKey, setStoryIndexKey] = useState(0)
-  const [brokenSnaps, setBrokenSnaps] = useState({})
 
-  // Resolve canvas theme — reactive to theme changes
-  const [canvasTheme, setCanvasTheme] = useState('light')
-
-  useEffect(() => subscribeCanvasTheme({
-    anchorRef: containerRef,
-    onTheme: setCanvasTheme,
-  }), [])
-
-  // On canvas theme change, enqueue a background snapshot refresh
-  const canvasThemeInitRef = useRef(true)
-  useEffect(() => {
-    if (canvasThemeInitRef.current) { canvasThemeInitRef.current = false; return }
-    if (!onUpdate || interactive) return
-    const rect = containerRef.current?.getBoundingClientRect()
-    enqueueRefresh(widgetId, ({ revealOrder, batchStart }) => {
-      return new Promise((resolve) => {
-        refreshMetaRef.current = { revealOrder, batchStart, resolve }
-        captureOnReadyRef.current = true
-        setShowIframe(true)
-        setTimeout(() => { refreshMetaRef.current = null; resolve(false) }, 10000)
-      })
-    }, rect ? { x: rect.left, y: rect.top } : undefined)
-  }, [canvasTheme]) // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Snapshot capture hook
-  const { iframeReady, requestCapture } = useSnapshotCapture({
-    iframeRef,
-    widgetId,
-    onUpdate,
-    showIframe,
-  })
-
-  // Single snapshot
-  const hasSnap = !!(snapshot && snapshot.includes(widgetId) && !brokenSnaps[snapshot])
-
-  // Re-resolve story URL when the story index is live-patched (new story added)
+  // Re-resolve story URL when the story index is live-patched
   useEffect(() => {
     const handler = () => setStoryIndexKey((k) => k + 1)
     document.addEventListener('storyboard:story-index-changed', handler)
@@ -150,116 +75,30 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const toggleShowCode = useCallback(() => {
     setShowCode((v) => {
       const next = !v
-      // Persist to canvas JSONL in dev
-      if (onUpdate) {
-        onUpdate({ showCode: next })
-      }
+      if (onUpdate) onUpdate({ showCode: next })
       return next
     })
   }, [onUpdate])
 
-  const enterInteractive = useCallback(() => {
-    exitSessionRef.current++
-    cancelRefresh(widgetId)
-    setShowIframe(true)
-    setInteractive(true)
-  }, [widgetId])
-
-  useEffect(() => {
-    if (!showIframe) setIframeLoaded(false)
-  }, [showIframe])
+  const enterInteractive = useCallback(() => setInteractive(true), [])
 
-  // Exit interactive mode when clicking outside.
-  // Hides iframe immediately for a responsive feel, then captures
-  // snapshots in the background with the iframe hidden but still mounted.
+  // Exit interactive mode when clicking outside
   useEffect(() => {
     if (!interactive) return
     function handlePointerDown(e) {
       if (containerRef.current && !containerRef.current.contains(e.target)) {
         const chromeEl = e.target.closest(`[data-widget-id="${widgetId}"]`)
         if (chromeEl) return
-
         setInteractive(false)
-        if (onUpdate && iframeLoaded && iframeRef.current?.contentWindow) {
-          if (iframeRef.current) iframeRef.current.style.visibility = 'hidden'
-          const session = ++exitSessionRef.current
-          setTimeout(() => {
-            if (exitSessionRef.current !== session) return
-            requestCapture({ force: true }).then((updates) => {
-              if (exitSessionRef.current !== session) return
-              const snap = updates?.snapshot
-              if (snap) {
-                const img = new Image()
-                const done = () => {
-                  if (exitSessionRef.current === session) setShowIframe(false)
-                }
-                img.onload = done
-                img.onerror = done
-                img.src = snap
-                setTimeout(done, 2000)
-              } else {
-                setShowIframe(false)
-              }
-            })
-          }, 0)
-        } else {
-          setShowIframe(false)
-        }
       }
     }
     document.addEventListener('pointerdown', handlePointerDown)
     return () => document.removeEventListener('pointerdown', handlePointerDown)
-  }, [interactive, onUpdate, iframeLoaded, requestCapture])
+  }, [interactive, widgetId])
 
   const handleResize = useCallback((w, h) => {
     onUpdate?.({ width: w, height: h })
-    // Recapture snapshot after resize (debounced)
-    clearTimeout(resizeTimerRef.current)
-    resizeTimerRef.current = setTimeout(() => requestCapture(), 1500)
-  }, [onUpdate, requestCapture])
-
-  // Capture snapshot on first iframe ready (when no existing snapshot)
-  useEffect(() => {
-    if (!iframeReady || !onUpdate) return
-    if (!hasSnap) {
-      requestCapture()
-    }
-  }, [iframeReady]) // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Capture when iframe becomes ready after refresh-thumbnail requested it
-  useEffect(() => {
-    if (iframeReady && captureOnReadyRef.current) {
-      captureOnReadyRef.current = false
-      requestCapture().then((updates) => {
-        const meta = refreshMetaRef.current
-        if (meta) {
-          refreshMetaRef.current = null
-          const snap = updates?.snapshot
-          const reveal = () => {
-            if (snap) {
-              const img = new Image()
-              const done = () => setShowIframe(false)
-              img.onload = done
-              img.onerror = done
-              img.src = snap
-              setTimeout(done, 2000)
-            } else {
-              setShowIframe(false)
-            }
-            meta.resolve(!!snap)
-          }
-          // Wait for our reveal slot in the wave
-          const elapsed = Date.now() - meta.batchStart
-          const targetTime = meta.revealOrder * REVEAL_INTERVAL
-          const wait = Math.max(0, targetTime - elapsed)
-          setTimeout(reveal, wait)
-        }
-      })
-    }
-  }, [iframeReady, requestCapture])
-
-  // Cleanup resize timer on unmount
-  useEffect(() => () => clearTimeout(resizeTimerRef.current), [])
+  }, [onUpdate])
 
   // Load source code when show-code is toggled on
   useEffect(() => {
@@ -269,65 +108,43 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
       setSourceCode('// Source not available')
       return
     }
-
     let cancelled = false
     setSourceLoading(true)
-
     fetchStorySource(story._storyModule)
-      .then((code) => {
-        if (cancelled) return
-        setSourceCode(code || '// Empty file')
-        setSourceLoading(false)
-      })
-      .catch(() => {
-        if (cancelled) return
-        setSourceCode('// Failed to load source')
-        setSourceLoading(false)
-      })
-
-    return () => {
-      cancelled = true
-      setSourceLoading(false)
-    }
+      .then((code) => { if (!cancelled) { setSourceCode(code || '// Empty file'); setSourceLoading(false) } })
+      .catch(() => { if (!cancelled) { setSourceCode('// Failed to load source'); setSourceLoading(false) } })
+    return () => { cancelled = true; setSourceLoading(false) }
   }, [showCode, sourceCode, storyId])
 
-  // Re-highlight when the code-box theme changes (storyboard:theme:changed event).
+  // Re-highlight when theme changes
   const [codeThemeKey, setCodeThemeKey] = useState(0)
   useEffect(() => {
-    function onThemeChanged() {
-      setCodeThemeKey((k) => k + 1)
-    }
+    function onThemeChanged() { setCodeThemeKey((k) => k + 1) }
     document.addEventListener('storyboard:theme:changed', onThemeChanged)
     return () => document.removeEventListener('storyboard:theme:changed', onThemeChanged)
   }, [])
 
-  // Syntax-highlight source code using the inspector highlighter.
-  // Uses the current code-box theme (data-sb-code-theme) set by the theme store.
+  // Syntax-highlight source code
   useEffect(() => {
     if (!sourceCode) return
     let cancelled = false
     createInspectorHighlighter().then((hl) => {
       if (cancelled) return
       const lang = storyId.endsWith('.tsx') ? 'tsx' : 'jsx'
-      const html = hl.codeToHtml(sourceCode, { lang })
-      setHighlightedHtml(html)
+      setHighlightedHtml(hl.codeToHtml(sourceCode, { lang }))
     })
     return () => { cancelled = true }
   }, [sourceCode, storyId, codeThemeKey])
 
   const copyCode = useCallback(async () => {
-    if (sourceCode) {
-      await navigator.clipboard?.writeText(sourceCode)
-      return
-    }
-    // Load source on demand if not already loaded
+    if (sourceCode) { await navigator.clipboard?.writeText(sourceCode); return }
     const story = getStoryData(storyId)
     if (!story?._storyModule) return
     try {
       const code = await fetchStorySource(story._storyModule)
       setSourceCode(code)
       await navigator.clipboard?.writeText(code)
-    } catch { /* ignore */ }
+    } catch { /* */ }
   }, [sourceCode, storyId])
 
   useImperativeHandle(ref, () => ({
@@ -336,26 +153,17 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
       return undefined
     },
     handleAction(actionId) {
-      if (actionId === 'show-code') {
-        toggleShowCode()
-      } else if (actionId === 'copy-code') {
-        copyCode()
-      } else if (actionId === 'open-external') {
+      if (actionId === 'show-code') toggleShowCode()
+      else if (actionId === 'copy-code') copyCode()
+      else if (actionId === 'open-external') {
         const story = getStoryData(storyId)
         if (story?._route) {
           const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
           window.open(`${base}${story._route}`, '_blank', 'noopener')
         }
-      } else if (actionId === 'refresh-thumbnail') {
-        if (iframeReady && iframeRef.current?.contentWindow) {
-          requestCapture()
-        } else {
-          captureOnReadyRef.current = true
-          setShowIframe(true)
-        }
       }
     },
-  }), [storyId, showCode, toggleShowCode, copyCode, iframeReady, requestCapture])
+  }), [storyId, showCode, toggleShowCode, copyCode])
 
   const iframeSrc = useMemo(
     () => resolveStoryUrl(storyId, exportName),
@@ -364,13 +172,12 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
 
   useIframeDevLogs({
     widget: 'StoryWidget',
-    loaded: showIframe && !showCode && Boolean(iframeSrc),
+    loaded: interactive && !showCode && Boolean(iframeSrc),
     src: iframeSrc,
   })
 
   const displayName = exportName ? `${storyId} / ${exportName}` : storyId
 
-  // Error state — missing story or no route
   if (!storyId) {
     return (
       <WidgetWrapper>
@@ -418,61 +225,25 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
           >
             <div className={styles.codeHeader}>
               <span className={styles.codeLabel}>{storyId}.story.jsx</span>
-              <button
-                className={styles.codeCloseBtn}
-                onClick={() => setShowCode(false)}
-                aria-label="Close code view"
-              >×</button>
+              <button className={styles.codeCloseBtn} onClick={() => setShowCode(false)} aria-label="Close code view">×</button>
             </div>
             {sourceLoading ? (
               <div className={styles.codeLoading}>Loading…</div>
             ) : highlightedHtml ? (
-              <div
-                className={styles.codeBlock}
-                dangerouslySetInnerHTML={{ __html: highlightedHtml }}
-              />
+              <div className={styles.codeBlock} dangerouslySetInnerHTML={{ __html: highlightedHtml }} />
             ) : (
-              <pre className={styles.codeBlock}>
-                <code>{sourceCode || ''}</code>
-              </pre>
+              <pre className={styles.codeBlock}><code>{sourceCode || ''}</code></pre>
             )}
           </div>
         ) : (
           <>
             <div className={styles.content}>
-              {/* Snapshot layer — single image */}
-              {hasSnap && (
-                <img
-                  src={snapshot}
-                  className={styles.snapshotImage}
-                  alt={`${displayName} snapshot`}
-                  draggable={false}
-                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshot]: true }))}
-                />
-              )}
-
-              {/* Iframe layer — on top, transparent until loaded */}
-              {showIframe && (
-                <iframe
-                  ref={iframeRef}
-                  src={iframeSrc}
-                  className={styles.iframe}
-                  style={{
-                    ...(iframeLoaded ? undefined : { opacity: 0 }),
-                    transition: 'opacity 150ms ease',
-                  }}
-                  onLoad={() => setIframeLoaded(true)}
-                  title={displayName}
-                />
-              )}
-
-              {/* Placeholder — only when no snapshot and no iframe */}
-              {!hasSnap && !showIframe && (
-                <div className={styles.placeholder}>
-                  <ComponentIcon size={36} />
-                  <span className={styles.placeholderLabel}>{displayName}</span>
-                </div>
-              )}
+              <iframe
+                ref={iframeRef}
+                src={iframeSrc}
+                className={styles.iframe}
+                title={displayName}
+              />
             </div>
 
             {!interactive && (
@@ -491,22 +262,15 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
                     enterInteractive()
                   }
                 }}
-                aria-label={hasSnap ? 'Click to interact with story component' : 'Click to open story component'}
+                aria-label="Click to interact"
               >
-                <span className={overlayStyles.interactHint}>{hasSnap ? 'Click to interact' : 'Click to open'}</span>
+                <span className={overlayStyles.interactHint}>Click to interact</span>
               </div>
             )}
           </>
         )}
-        {resizable && (
-          <ResizeHandle
-            targetRef={containerRef}
-            minWidth={100}
-            minHeight={60}
-            onResize={handleResize}
-          />
-        )}
       </div>
+      {resizable && <ResizeHandle width={width} height={height} onResize={handleResize} />}
     </WidgetWrapper>
   )
 })

package/src/canvas/widgets/refreshQueue.js

@@ -1,111 +0,0 @@
-/**
- * Concurrent refresh queue for bulk snapshot recapture (e.g. on theme change).
- *
- * Captures run in parallel (up to MAX_CONCURRENT) for speed, but REVEALS are
- * staggered on a fixed timeline — widget 0 reveals at 0ms, widget 1 at
- * REVEAL_INTERVAL ms, widget 2 at 2×REVEAL_INTERVAL ms, etc., all relative to
- * batch start. This creates a clean, predictable wave sweep regardless of how
- * fast each capture completes.
- *
- * After a batch completes, any widgets that failed are re-enqueued for a
- * single retry pass.
- *
- * Sorted spatially (top-to-bottom, left-to-right) before assigning reveal slots.
- * Supports cancellation by widget ID.
- */
-const queue = []
-let running = 0
-let drainScheduled = false
-let batchTotal = 0
-let batchDone = 0
-const batchFailed = []
-
-const MAX_CONCURRENT = 4
-export const REVEAL_INTERVAL = 200
-
-/**
- * Enqueue a snapshot refresh task for a widget.
- * @param {string} widgetId — unique widget identifier (for cancellation)
- * @param {(meta: { revealOrder: number, batchStart: number }) => Promise<boolean>} fn
- *   Must resolve to `true` on success, `false` on failure.
- * @param {{ x: number, y: number }} [pos] — spatial position for wave ordering
- */
-export function enqueueRefresh(widgetId, fn, pos) {
-  console.log(`[refreshQueue] enqueue: ${widgetId}, queueLen=${queue.length}`)
-  const existing = queue.findIndex(item => item.widgetId === widgetId)
-  if (existing !== -1) queue.splice(existing, 1)
-
-  queue.push({ widgetId, fn, x: pos?.x ?? 0, y: pos?.y ?? 0 })
-  scheduleDrain()
-}
-
-/**
- * Cancel a pending refresh for a widget (e.g. user activated it manually).
- */
-export function cancelRefresh(widgetId) {
-  const idx = queue.findIndex(item => item.widgetId === widgetId)
-  if (idx !== -1) queue.splice(idx, 1)
-}
-
-function scheduleDrain() {
-  if (drainScheduled) return
-  drainScheduled = true
-  // Batch all enqueueRefresh calls from the same React commit, then sort
-  // spatially and assign reveal slots before starting captures.
-  setTimeout(() => {
-    drainScheduled = false
-    queue.sort((a, b) => a.y - b.y || a.x - b.x)
-    const batchStart = Date.now()
-    batchTotal = queue.length
-    batchDone = 0
-    batchFailed.length = 0
-    queue.forEach((item, i) => {
-      item.revealOrder = i
-      item.batchStart = batchStart
-      item.isRetry = item.isRetry || false
-    })
-    drain()
-  }, 0)
-}
-
-function onTaskDone(success, item) {
-  batchDone++
-  console.log(`[refreshQueue] taskDone: ${item.widgetId}, success=${success}, done=${batchDone}/${batchTotal}, retry=${item.isRetry}`)
-  if (!success && !item.isRetry) {
-    batchFailed.push(item)
-  }
-  // When batch is complete, re-enqueue failures for one retry
-  if (batchDone >= batchTotal && batchFailed.length > 0) {
-    console.log(`[refreshQueue] batch complete, retrying ${batchFailed.length} failed`)
-    const retries = batchFailed.splice(0)
-    for (const failed of retries) {
-      failed.isRetry = true
-      queue.push(failed)
-    }
-    batchTotal = queue.length
-    batchDone = 0
-    const batchStart = Date.now()
-    queue.forEach((item, i) => {
-      item.revealOrder = i
-      item.batchStart = batchStart
-    })
-  }
-  drain()
-}
-
-function drain() {
-  if (running >= MAX_CONCURRENT || queue.length === 0) return
-
-  running++
-  const item = queue.shift()
-  const { fn, revealOrder, batchStart } = item
-  Promise.resolve()
-    .then(() => fn({ revealOrder, batchStart }))
-    .then((success) => { running--; onTaskDone(success !== false, item) })
-    .catch(() => { running--; onTaskDone(false, item) })
-
-  // Start next capture immediately (no stagger on capture start — only reveals are staggered)
-  if (queue.length > 0 && running < MAX_CONCURRENT) {
-    drain()
-  }
-}

package/src/canvas/widgets/useSnapshotCapture.js

@@ -1,161 +0,0 @@
-/**
- * useSnapshotCapture — parent-side capture orchestration hook.
- *
- * Listens for snapshot-ready signals from an embedded iframe and
- * provides a requestCapture() function that triggers a single capture
- * of whatever the iframe is currently showing.
- *
- * Saves a single `snapshot` prop — overwritten every time.
- * Only active in dev mode (when onUpdate is provided).
- */
-import { useState, useEffect, useCallback, useRef } from 'react'
-import { uploadImage } from '../canvasApi.js'
-
-const CAPTURE_TIMEOUT = 3000
-
-/**
- * Run a single capture request against the iframe.
- * Returns the dataUrl or null on failure.
- */
-function captureOnce(iframeContentWindow, requestId, listeners) {
-  return new Promise((resolve) => {
-    const timer = setTimeout(() => {
-      cleanup()
-      resolve(null)
-    }, CAPTURE_TIMEOUT)
-
-    function cleanup() {
-      clearTimeout(timer)
-      const idx = listeners.indexOf(handler)
-      if (idx !== -1) listeners.splice(idx, 1)
-    }
-
-    function handler(data) {
-      if (data.requestId !== requestId) return
-      cleanup()
-      if (data.error || !data.dataUrl) {
-        if (data.error) console.warn('[snapshot] Capture failed:', data.error)
-        resolve(null)
-      } else {
-        resolve(data.dataUrl)
-      }
-    }
-
-    listeners.push(handler)
-    iframeContentWindow.postMessage({
-      type: 'storyboard:embed:capture',
-      requestId,
-    }, '*')
-  })
-}
-
-export function useSnapshotCapture({
-  iframeRef,
-  widgetId,
-  onUpdate,
-  showIframe,
-}) {
-  const [iframeReady, setIframeReady] = useState(false)
-  const iframeReadyRef = useRef(false)
-  const capturingRef = useRef(false)
-  const requestIdCounter = useRef(0)
-  const captureGeneration = useRef(0)
-  const responseHandlers = useRef([])
-  // Track the iframe contentWindow to reset readiness on remount
-  const lastContentWindowRef = useRef(null)
-
-  // Reset ready state when iframe is unmounted/remounted
-  useEffect(() => {
-    setIframeReady(false)
-    iframeReadyRef.current = false
-  }, [widgetId])
-
-  // Reset readiness when iframe is torn down so remount waits for new snapshot-ready
-  useEffect(() => {
-    if (!showIframe) {
-      setIframeReady(false)
-      iframeReadyRef.current = false
-      lastContentWindowRef.current = null
-    }
-  }, [showIframe])
-
-  // Listen for postMessage events from the embedded iframe
-  useEffect(() => {
-    if (!onUpdate) return
-
-    function handler(e) {
-      if (!iframeRef.current) return
-      if (e.source !== iframeRef.current.contentWindow) return
-
-      // Detect new iframe instance → reset readiness
-      if (e.source !== lastContentWindowRef.current) {
-        lastContentWindowRef.current = e.source
-        setIframeReady(false)
-        iframeReadyRef.current = false
-      }
-
-      if (e.data?.type === 'storyboard:embed:snapshot-ready') {
-        console.log(`[snapshot:${widgetId}] iframe ready`)
-        setIframeReady(true)
-        iframeReadyRef.current = true
-      }
-
-      if (e.data?.type === 'storyboard:embed:snapshot') {
-        for (const fn of responseHandlers.current) {
-          fn(e.data)
-        }
-      }
-    }
-
-    window.addEventListener('message', handler)
-    return () => window.removeEventListener('message', handler)
-  }, [iframeRef, onUpdate])
-
-  /**
-   * Capture a single snapshot of the current iframe state.
-   * Uploads and saves as `snapshot` prop, overwriting any previous value.
-   */
-  const requestCapture = useCallback(async ({ force = false } = {}) => {
-    console.log(`[snapshot:${widgetId}] requestCapture: force=${force}, hasContentWindow=${!!iframeRef.current?.contentWindow}, capturing=${capturingRef.current}, ready=${iframeReadyRef.current}`)
-    if (!onUpdate) return {}
-    if (!iframeRef.current?.contentWindow) { console.log(`[snapshot:${widgetId}] requestCapture: no contentWindow`); return {} }
-    if (capturingRef.current) { console.log(`[snapshot:${widgetId}] requestCapture: already capturing`); return {} }
-    if (!force && !iframeReadyRef.current) { console.log(`[snapshot:${widgetId}] requestCapture: not ready`); return {} }
-
-    capturingRef.current = true
-    const gen = ++captureGeneration.current
-    const cw = iframeRef.current.contentWindow
-    const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
-
-    try {
-      const reqId = ++requestIdCounter.current
-      const dataUrl = await captureOnce(cw, reqId, responseHandlers.current)
-
-      if (gen !== captureGeneration.current) { console.log(`[snapshot:${widgetId}] stale gen after capture`); return {} }
-      if (!dataUrl) { console.log(`[snapshot:${widgetId}] captureOnce returned null`); return {} }
-
-      const filename = `snapshot-${widgetId}.webp`
-      console.log(`[snapshot:${widgetId}] uploading ${filename}`)
-      const result = await uploadImage(dataUrl, `snapshot-${widgetId}`, filename)
-
-      if (gen !== captureGeneration.current) { console.log(`[snapshot:${widgetId}] stale gen after upload`); return {} }
-
-      if (result?.filename) {
-        const cacheBust = `?v=${Date.now()}`
-        const url = `${base}/_storyboard/canvas/images/${result.filename}${cacheBust}`
-        const updates = { snapshot: url }
-        console.log(`[snapshot:${widgetId}] saved: ${url.slice(0, 60)}`)
-        onUpdate?.(updates)
-        return updates
-      }
-      return {}
-    } catch (err) {
-      console.warn('[snapshot] Capture failed:', err)
-      return {}
-    } finally {
-      capturingRef.current = false
-    }
-  }, [onUpdate, iframeRef, widgetId])
-
-  return { iframeReady, requestCapture }
-}