@dfosco/storyboard-react 4.0.0-beta.25 → 4.0.0-beta.26

package/package.json

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

package/src/canvas/CanvasPage.jsx

@@ -1,5 +1,4 @@
-import { createElement, useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { flushSync } from 'react-dom'
+import { createElement, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Canvas } from '@dfosco/tiny-canvas'
 import '@dfosco/tiny-canvas/style.css'
 import { useCanvas } from './useCanvas.js'
@@ -267,8 +266,10 @@ function WidgetRenderer({ widget, onUpdate, widgetRef }) {
 /**
  * Wrapper for each JSON widget that holds its own ref for imperative actions.
  * This allows WidgetChrome to dispatch actions to the widget via ref.
+ *
+ * Memoized to prevent re-renders during zoom and unrelated state changes.
  */
-function ChromeWrappedWidget({
+const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
   widget,
   selected,
   multiSelected,
@@ -293,6 +294,10 @@ function ChromeWrappedWidget({
     }
   }, [widget, onRemove, onCopy])
 
+  const handleWidgetFieldUpdate = useCallback((updates) => {
+    onUpdate?.(widget.id, updates)
+  }, [onUpdate, widget.id])
+
   return (
     <WidgetChrome
       widgetId={widget.id}
@@ -305,17 +310,29 @@ function ChromeWrappedWidget({
       onSelect={onSelect}
       onDeselect={onDeselect}
       onAction={handleAction}
-      onUpdate={onUpdate ? (updates) => onUpdate(widget.id, updates) : undefined}
+      onUpdate={onUpdate ? handleWidgetFieldUpdate : undefined}
       readOnly={readOnly}
     >
       <WidgetRenderer
         widget={widget}
-        onUpdate={onUpdate ? (updates) => onUpdate(widget.id, updates) : undefined}
+        onUpdate={onUpdate ? handleWidgetFieldUpdate : undefined}
         widgetRef={widgetRef}
       />
     </WidgetChrome>
   )
-}
+}, function chromeWidgetAreEqual(prev, next) {
+  return (
+    prev.widget === next.widget &&
+    prev.selected === next.selected &&
+    prev.multiSelected === next.multiSelected &&
+    prev.readOnly === next.readOnly &&
+    prev.onSelect === next.onSelect &&
+    prev.onDeselect === next.onDeselect &&
+    prev.onUpdate === next.onUpdate &&
+    prev.onRemove === next.onRemove &&
+    prev.onCopy === next.onCopy
+  )
+})
 
 /**
  * Generic canvas page component.
@@ -335,6 +352,9 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
   const [zoom, setZoom] = useState(initialViewport?.zoom ?? 100)
   const zoomRef = useRef(initialViewport?.zoom ?? 100)
   const scrollRef = useRef(null)
+  const zoomElRef = useRef(null)
+  const zoomCommitTimer = useRef(null)
+  const zoomEventTimer = useRef(null)
   const pendingScrollRestore = useRef(initialViewport)
   // Gate viewport persistence until initial positioning is complete.
   // Tracks which canvasId was last initialized — save effects only
@@ -704,10 +724,17 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
     })
   }, [canvasId, undoRedo, debouncedSave, transitionPeers, clearDragPreview])
 
+  // Keep zoomRef in sync when React state is set (e.g. by toolbar or zoom-to-fit)
   useEffect(() => {
     zoomRef.current = zoom
   }, [zoom])
 
+  // Cleanup zoom timers on unmount
+  useEffect(() => () => {
+    clearTimeout(zoomCommitTimer.current)
+    clearTimeout(zoomEventTimer.current)
+  }, [])
+
   // Restore scroll position from localStorage after first render.
   // When saved state is fresh (< 15 min), restore it. Otherwise zoom-to-fit
   // all objects so the user sees a useful overview instead of stale coordinates.
@@ -730,7 +757,14 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
         const fitZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Math.round(fitScale * 100)))
         const newScale = fitZoom / 100
         zoomRef.current = fitZoom
-        flushSync(() => setZoom(fitZoom))
+        // Imperative DOM update for initial zoom-to-fit — same path as applyZoom
+        const zoomEl = zoomElRef.current
+        if (zoomEl) {
+          zoomEl.style.transform = `scale(${newScale})`
+          zoomEl.style.width = `${Math.max(10000, 100 / newScale)}vw`
+          zoomEl.style.height = `${Math.max(10000, 100 / newScale)}vh`
+        }
+        setZoom(fitZoom)
         el.scrollLeft = (bounds.minX - FIT_PADDING) * newScale
         el.scrollTop = (bounds.minY - FIT_PADDING) * newScale
       } else {
@@ -846,12 +880,19 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
    * When a cursor position is provided (e.g. from a wheel event), the
    * canvas point under the cursor stays fixed. Otherwise falls back to
    * the viewport center.
+   *
+   * Performs an imperative DOM mutation instead of a React state update
+   * to avoid triggering a full re-render of the widget tree on every
+   * zoom tick. React state is committed after a debounce for toolbar
+   * display updates.
    */
   function applyZoom(newZoom, clientX, clientY) {
     const el = scrollRef.current
+    const zoomEl = zoomElRef.current
     const clampedZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, newZoom))
 
-    if (!el) {
+    if (!el || !zoomEl) {
+      zoomRef.current = clampedZoom
       setZoom(clampedZoom)
       return
     }
@@ -869,23 +910,36 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
     const canvasX = (el.scrollLeft + anchorX) / oldScale
     const canvasY = (el.scrollTop + anchorY) / oldScale
 
-    // Synchronous render so the DOM has the new transform before we adjust scroll
+    // Imperative DOM update — no React re-render
     zoomRef.current = clampedZoom
-    flushSync(() => setZoom(clampedZoom))
+    zoomEl.style.transform = `scale(${newScale})`
+    zoomEl.style.width = `${Math.max(10000, 100 / newScale)}vw`
+    zoomEl.style.height = `${Math.max(10000, 100 / newScale)}vh`
+
+    // Hint GPU compositing during active zoom
+    zoomEl.dataset.zooming = ''
 
     // Scroll so the same canvas point stays under the anchor
     el.scrollLeft = canvasX * newScale - anchorX
     el.scrollTop = canvasY * newScale - anchorY
 
-    // Persist after both zoom and scroll are settled (the zoom effect
-    // fires inside flushSync before the scroll adjustment above, so it
-    // would capture stale scroll values).
-    if (viewportInitName.current === canvasId) {
-      saveViewportState(canvasId, {
-        zoom: clampedZoom,
-        scrollLeft: el.scrollLeft,
-        scrollTop: el.scrollTop,
-      })
+    // Debounced commit: update React state for toolbar display + persistence
+    clearTimeout(zoomCommitTimer.current)
+    zoomCommitTimer.current = setTimeout(() => {
+      // Remove GPU compositing hint
+      delete zoomEl.dataset.zooming
+      setZoom(clampedZoom)
+    }, 150)
+
+    // Throttled zoom-changed event for external consumers (toolbar)
+    if (!zoomEventTimer.current) {
+      zoomEventTimer.current = setTimeout(() => {
+        zoomEventTimer.current = null
+        window[CANVAS_BRIDGE_STATE_KEY] = { active: true, canvasId, zoom: zoomRef.current }
+        document.dispatchEvent(new CustomEvent('storyboard:canvas:zoom-changed', {
+          detail: { zoom: zoomRef.current }
+        }))
+      }, 100)
     }
   }
 
@@ -1067,9 +1121,15 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
       const fitZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Math.round(fitScale * 100)))
       const newScale = fitZoom / 100
 
-      // Apply zoom synchronously so DOM updates before we scroll
+      // Imperative DOM update — same path as applyZoom
       zoomRef.current = fitZoom
-      flushSync(() => setZoom(fitZoom))
+      const zoomEl = zoomElRef.current
+      if (zoomEl) {
+        zoomEl.style.transform = `scale(${newScale})`
+        zoomEl.style.width = `${Math.max(10000, 100 / newScale)}vw`
+        zoomEl.style.height = `${Math.max(10000, 100 / newScale)}vh`
+      }
+      setZoom(fitZoom)
 
       // Scroll so the bounding box top-left (with padding) is at viewport top-left
       el.scrollLeft = (bounds.minX - FIT_PADDING) * newScale
@@ -1623,6 +1683,15 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
   const canvasThemeVars = getCanvasThemeVars(canvasTheme)
   const canvasPrimerAttrs = getCanvasPrimerAttrs(canvasTheme)
 
+  // Stable callback for deselecting all widgets
+  const handleDeselectAll = useCallback(() => setSelectedWidgetIds(new Set()), [])
+
+  // Stable callback for widget removal + deselect
+  const handleWidgetRemoveAndDeselect = useCallback((id) => {
+    handleWidgetRemove(id)
+    setSelectedWidgetIds(new Set())
+  }, [handleWidgetRemove])
+
   // Merge JSX-sourced widgets (from .canvas.jsx) and JSON widgets
   const allChildren = []
 
@@ -1653,7 +1722,7 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
           selected={selectedWidgetIds.has(`jsx-${exportName}`)}
           multiSelected={isMultiSelected && selectedWidgetIds.has(`jsx-${exportName}`)}
           onSelect={(shiftKey) => handleWidgetSelect(`jsx-${exportName}`, shiftKey)}
-          onDeselect={() => setSelectedWidgetIds(new Set())}
+          onDeselect={handleDeselectAll}
           readOnly={!isLocalDev}
         >
           <ComponentWidget
@@ -1695,13 +1764,10 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
           selected={selectedWidgetIds.has(widget.id)}
           multiSelected={isMultiSelected && selectedWidgetIds.has(widget.id)}
           onSelect={(shiftKey) => handleWidgetSelect(widget.id, shiftKey)}
-          onDeselect={() => setSelectedWidgetIds(new Set())}
+          onDeselect={handleDeselectAll}
           onUpdate={isLocalDev ? handleWidgetUpdate : undefined}
           onCopy={isLocalDev ? handleWidgetCopy : undefined}
-          onRemove={isLocalDev ? (id) => {
-            handleWidgetRemove(id)
-            setSelectedWidgetIds(new Set())
-          } : undefined}
+          onRemove={isLocalDev ? handleWidgetRemoveAndDeselect : undefined}
           readOnly={!isLocalDev}
         />
       </div>
@@ -1729,10 +1795,11 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
           ...canvasThemeVars,
           ...(spaceHeld ? { cursor: panningActive ? 'grabbing' : 'grab' } : {}),
         }}
-        onClick={() => setSelectedWidgetIds(new Set())}
+        onClick={handleDeselectAll}
         onMouseDown={handlePanStart}
       >
         <div
+          ref={zoomElRef}
           data-storyboard-canvas-zoom
           data-sb-canvas-theme={canvasTheme}
           className={styles.canvasZoom}

package/src/canvas/CanvasPage.module.css

@@ -32,6 +32,13 @@
   min-height: 100%;
 }
 
+/* GPU compositing hint during active zoom gestures — applied imperatively
+   via data-zooming attribute and removed on zoom-end to avoid permanent
+   memory pressure on the large canvas surface. */
+.canvasZoom[data-zooming] {
+  will-change: transform;
+}
+
 /* Selection outline is now handled by WidgetChrome.module.css (.widgetSlotSelected) */
 
 .canvasTitle {

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -249,7 +249,8 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   }, [showIframe])
 
   // Exit interactive mode when clicking outside the embed.
-  // Keeps iframe mounted until snapshots are captured and preloaded.
+  // Hides iframe immediately for a responsive feel, then captures
+  // snapshots in the background with the iframe hidden but still mounted.
   useEffect(() => {
     if (!interactive || expanded) return
     function handlePointerDown(e) {
@@ -259,18 +260,10 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
 
         setInteractive(false)
         if (onUpdate && !isExternal && iframeLoaded && iframeRef.current?.contentWindow) {
+          // Keep iframe mounted but hidden for background capture
+          if (iframeRef.current) iframeRef.current.style.visibility = 'hidden'
           const session = ++exitSessionRef.current
-          requestCapture({ force: true }).then(async (updates) => {
-            if (exitSessionRef.current !== session) return
-            const urls = [updates?.snapshotLight, updates?.snapshotDark].filter(Boolean)
-            if (urls.length > 0) {
-              await Promise.all(urls.map(url => new Promise(resolve => {
-                const img = new Image()
-                img.onload = resolve
-                img.onerror = resolve
-                img.src = url
-              })))
-            }
+          requestCapture({ force: true }).then(() => {
             if (exitSessionRef.current !== session) return
             setShowIframe(false)
           })

package/src/canvas/widgets/StoryWidget.jsx

@@ -156,7 +156,8 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   }, [showIframe])
 
   // Exit interactive mode when clicking outside.
-  // Keeps iframe mounted until snapshots are captured and preloaded.
+  // Hides iframe immediately for a responsive feel, then captures
+  // snapshots in the background with the iframe hidden but still mounted.
   useEffect(() => {
     if (!interactive) return
     function handlePointerDown(e) {
@@ -166,18 +167,10 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
 
         setInteractive(false)
         if (onUpdate && iframeLoaded && iframeRef.current?.contentWindow) {
+          // Keep iframe mounted but hidden for background capture
+          if (iframeRef.current) iframeRef.current.style.visibility = 'hidden'
           const session = ++exitSessionRef.current
-          requestCapture({ force: true }).then(async (updates) => {
-            if (exitSessionRef.current !== session) return
-            const urls = [updates?.snapshotLight, updates?.snapshotDark].filter(Boolean)
-            if (urls.length > 0) {
-              await Promise.all(urls.map(url => new Promise(resolve => {
-                const img = new Image()
-                img.onload = resolve
-                img.onerror = resolve
-                img.src = url
-              })))
-            }
+          requestCapture({ force: true }).then(() => {
             if (exitSessionRef.current !== session) return
             setShowIframe(false)
           })

package/src/canvas/widgets/useSnapshotCapture.js

@@ -9,6 +9,10 @@
  * captures the alternate theme, and switches back. The user never
  * sees the theme flash because the iframe is hidden during the switch.
  *
+ * Optimized pipeline: the first theme's upload runs in parallel with
+ * the alternate theme's capture, and capture generation tokens prevent
+ * stale results from overwriting newer snapshots.
+ *
  * Only active in dev mode (when onUpdate is provided).
  */
 import { useState, useEffect, useCallback, useRef } from 'react'
@@ -84,6 +88,19 @@ function switchTheme(iframeContentWindow, theme, requestId, listeners) {
   })
 }
 
+/**
+ * Upload a captured dataUrl and return the resolved image URL.
+ */
+async function uploadAndResolve(dataUrl, widgetId, themeLabel, base) {
+  const filename = `snapshot-${widgetId}--${themeLabel}.webp`
+  const result = await uploadImage(dataUrl, `snapshot-${widgetId}`, filename)
+  if (result?.filename) {
+    const cacheBust = `?v=${Date.now()}`
+    return `${base}/_storyboard/canvas/images/${result.filename}${cacheBust}`
+  }
+  return null
+}
+
 export function useSnapshotCapture({
   iframeRef,
   widgetId,
@@ -94,6 +111,8 @@ export function useSnapshotCapture({
   const iframeReadyRef = useRef(false)
   const capturingRef = useRef(false)
   const requestIdCounter = useRef(0)
+  // Generation token — incremented on each capture request to detect stale results
+  const captureGeneration = useRef(0)
   // Handlers for both snapshot and theme-applied responses
   const responseHandlers = useRef([])
 
@@ -126,14 +145,18 @@ export function useSnapshotCapture({
 
     window.addEventListener('message', handler)
     return () => window.removeEventListener('message', handler)
-  }, [iframeRef, onUpdate]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [iframeRef, onUpdate])
 
   /**
-   * Dual-theme capture. Captures current theme, then hides iframe,
-   * switches to alternate theme, captures again, switches back.
-   * Returns { snapshotLight, snapshotDark } URLs.
+   * Dual-theme capture with pipelined uploads.
+   *
+   * Pipeline: capture theme-1 → start upload-1 in parallel with
+   * (hide iframe → switch theme → capture theme-2) → upload-2.
+   *
+   * Generation tokens prevent stale captures from overwriting newer ones.
+   *
    * @param {Object} opts
-   * @param {boolean} opts.force - Skip the iframeReady guard (use when iframe is known to be loaded)
+   * @param {boolean} opts.force - Skip the iframeReady guard
    */
   const requestCapture = useCallback(async ({ force = false } = {}) => {
     if (!onUpdate) return {}
@@ -142,6 +165,7 @@ export function useSnapshotCapture({
     if (!force && !iframeReadyRef.current) return {}
 
     capturingRef.current = true
+    const gen = ++captureGeneration.current
     const cw = iframeRef.current.contentWindow
     const iframe = iframeRef.current
     const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
@@ -153,57 +177,70 @@ export function useSnapshotCapture({
     try {
       // 1. Capture current theme (iframe is visible, user sees current state)
       const currentKey = isCurrentDark ? 'snapshotDark' : 'snapshotLight'
+      const currentLabel = isCurrentDark ? 'dark' : 'light'
       const currentReqId = ++requestIdCounter.current
       const currentDataUrl = await captureOnce(cw, currentReqId, responseHandlers.current)
 
+      // Bail if a newer capture started while we were waiting
+      if (gen !== captureGeneration.current) return {}
+
+      // 2. Start upload of theme-1 in parallel with alternate-theme capture
+      const uploadPromise1 = currentDataUrl
+        ? uploadAndResolve(currentDataUrl, widgetId, currentLabel, base)
+        : Promise.resolve(null)
+
+      // Publish theme-1 immediately so snapshot img is ready before iframe hides
       if (currentDataUrl) {
-        const filename = `snapshot-${widgetId}--${isCurrentDark ? 'dark' : 'light'}.webp`
-        const result = await uploadImage(currentDataUrl, `snapshot-${widgetId}`, filename)
-        if (result?.filename) {
-          const cacheBust = `?v=${Date.now()}`
-          updates[currentKey] = `${base}/_storyboard/canvas/images/${result.filename}${cacheBust}`
-          // Publish immediately so the snapshot img is ready before iframe hides
-          onUpdate?.({ [currentKey]: updates[currentKey] })
-          await new Promise(resolve => {
-            const img = new Image()
-            img.onload = resolve
-            img.onerror = resolve
-            img.src = updates[currentKey]
-            setTimeout(resolve, 2000)
-          })
-        }
+        uploadPromise1.then(url => {
+          if (url && gen === captureGeneration.current) {
+            updates[currentKey] = url
+            onUpdate?.({ [currentKey]: url })
+          }
+        }).catch(() => {})
       }
 
-      // 2. Hide iframe, switch theme, capture alternate (snapshot now visible behind)
+      // 3. Hide iframe, switch theme, capture alternate — overlaps with upload-1
       const savedVisibility = iframe.style.visibility
       iframe.style.visibility = 'hidden'
 
       const switchReqId = ++requestIdCounter.current
       const switched = await switchTheme(cw, alternateTheme, switchReqId, responseHandlers.current)
 
+      if (gen !== captureGeneration.current) {
+        iframe.style.visibility = savedVisibility || ''
+        return {}
+      }
+
       if (switched) {
         const altKey = isCurrentDark ? 'snapshotLight' : 'snapshotDark'
+        const altLabel = isCurrentDark ? 'light' : 'dark'
         const altReqId = ++requestIdCounter.current
         const altDataUrl = await captureOnce(cw, altReqId, responseHandlers.current)
 
+        if (gen !== captureGeneration.current) {
+          iframe.style.visibility = savedVisibility || ''
+          return {}
+        }
+
         if (altDataUrl) {
-          const filename = `snapshot-${widgetId}--${isCurrentDark ? 'light' : 'dark'}.webp`
-          const result = await uploadImage(altDataUrl, `snapshot-${widgetId}`, filename)
-          if (result?.filename) {
-            const cacheBust = `?v=${Date.now()}`
-            updates[altKey] = `${base}/_storyboard/canvas/images/${result.filename}${cacheBust}`
+          const altUrl = await uploadAndResolve(altDataUrl, widgetId, altLabel, base)
+          if (altUrl && gen === captureGeneration.current) {
+            updates[altKey] = altUrl
           }
         }
 
-        // 3. Switch back to original theme
+        // 4. Switch back to original theme
         const switchBackReqId = ++requestIdCounter.current
         await switchTheme(cw, currentTheme, switchBackReqId, responseHandlers.current)
       }
 
-      // 4. Restore iframe visibility
+      // Ensure upload-1 is complete before final update
+      await uploadPromise1
+
+      // 5. Restore iframe visibility
       iframe.style.visibility = savedVisibility || ''
 
-      if (Object.keys(updates).length > 0) {
+      if (gen === captureGeneration.current && Object.keys(updates).length > 0) {
         onUpdate?.(updates)
       }
       return updates
@@ -215,7 +252,7 @@ export function useSnapshotCapture({
     } finally {
       capturingRef.current = false
     }
-  }, [onUpdate, iframeRef, widgetId, canvasTheme]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [onUpdate, iframeRef, widgetId, canvasTheme])
 
   return { iframeReady, requestCapture }
 }

package/src/canvas/widgets/useSnapshotCapture.test.jsx

@@ -146,4 +146,80 @@ describe('useSnapshotCapture', () => {
       })
     )
   })
+
+  it('discards stale capture results via generation token', async () => {
+    const cw = createMockContentWindow()
+    const style = { visibility: "" }
+    const iframeRef = { current: { contentWindow: cw, style } }
+    const onUpdate = vi.fn()
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'gen-widget', onUpdate, canvasTheme: 'light' })
+    )
+
+    act(() => { dispatchMessage(cw, { type: 'storyboard:embed:snapshot-ready' }) })
+
+    uploadImage.mockResolvedValue({ filename: 'snapshot-gen-widget--light.webp' })
+
+    // Start first capture — will be waiting for response
+    let capture1Done = false
+    let capture2Done = false
+    await act(async () => {
+      const promise1 = result.current.requestCapture().then(() => { capture1Done = true })
+
+      // Respond to first capture
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:snapshot', requestId: 1, dataUrl: 'data:image/webp;base64,FIRST' })
+
+      // Start second capture before first completes its alternate-theme work
+      // This won't start because capturingRef is still true, so it will return {}
+      const promise2 = result.current.requestCapture().then(() => { capture2Done = true })
+
+      // Complete first capture's theme switch and alternate capture
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:theme-applied', requestId: 2 })
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:snapshot', requestId: 3, dataUrl: 'data:image/webp;base64,DARK' })
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:theme-applied', requestId: 4 })
+
+      await promise1
+      await promise2
+    })
+
+    // The second capture should have no-opped (capturingRef guard)
+    expect(capture1Done).toBe(true)
+    expect(capture2Done).toBe(true)
+  })
+
+  it('restores iframe visibility on error', async () => {
+    const cw = createMockContentWindow()
+    const style = { visibility: "visible" }
+    const iframeRef = { current: { contentWindow: cw, style } }
+    const onUpdate = vi.fn()
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'err-widget', onUpdate, canvasTheme: 'light' })
+    )
+
+    act(() => { dispatchMessage(cw, { type: 'storyboard:embed:snapshot-ready' }) })
+
+    // Make uploadImage throw to trigger error path
+    uploadImage.mockRejectedValueOnce(new Error('upload failed'))
+
+    await act(async () => {
+      const promise = result.current.requestCapture()
+
+      // Respond to capture
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:snapshot', requestId: 1, dataUrl: 'data:image/webp;base64,FAIL' })
+
+      await promise
+    })
+
+    // Visibility should be restored after error
+    expect(style.visibility).toBe('')
+    // onUpdate should not be called with failed data
+    expect(onUpdate).not.toHaveBeenCalledWith(
+      expect.objectContaining({ snapshotLight: expect.any(String) })
+    )
+  })
 })