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

package/src/canvas/widgets/useSnapshotCapture.js

@@ -0,0 +1,258 @@
+/**
+ * useSnapshotCapture — parent-side capture orchestration hook.
+ *
+ * Listens for snapshot-ready signals from an embedded iframe and
+ * provides a requestCapture() function that triggers a capture.
+ *
+ * Performs TRUE dual-theme capture: captures current theme, then
+ * tells the iframe to switch theme (hidden via visibility:hidden),
+ * 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'
+import { uploadImage } from '../canvasApi.js'
+
+const CAPTURE_TIMEOUT = 3000
+const THEME_SWITCH_TIMEOUT = 2000
+
+/**
+ * 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,
+    }, '*')
+  })
+}
+
+/**
+ * Tell the iframe to switch its Primer theme and wait for confirmation.
+ */
+function switchTheme(iframeContentWindow, theme, requestId, listeners) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      cleanup()
+      resolve(false)
+    }, THEME_SWITCH_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()
+      resolve(true)
+    }
+
+    listeners.push(handler)
+    iframeContentWindow.postMessage({
+      type: 'storyboard:embed:set-theme',
+      theme,
+      requestId,
+    }, '*')
+  })
+}
+
+/**
+ * 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,
+  onUpdate,
+  canvasTheme,
+}) {
+  const [iframeReady, setIframeReady] = useState(false)
+  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([])
+
+  // Reset ready state when iframe is unmounted/remounted
+  useEffect(() => {
+    setIframeReady(false)
+    iframeReadyRef.current = false
+  }, [widgetId])
+
+  // 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
+
+      if (e.data?.type === 'storyboard:embed:snapshot-ready') {
+        setIframeReady(true)
+        iframeReadyRef.current = true
+      }
+
+      if (e.data?.type === 'storyboard:embed:snapshot' ||
+          e.data?.type === 'storyboard:embed:theme-applied') {
+        for (const fn of responseHandlers.current) {
+          fn(e.data)
+        }
+      }
+    }
+
+    window.addEventListener('message', handler)
+    return () => window.removeEventListener('message', handler)
+  }, [iframeRef, onUpdate])
+
+  /**
+   * 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
+   */
+  const requestCapture = useCallback(async ({ force = false } = {}) => {
+    if (!onUpdate) return {}
+    if (!iframeRef.current?.contentWindow) return {}
+    if (capturingRef.current) return {}
+    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(/\/$/, '')
+    const updates = {}
+    const currentTheme = canvasTheme || 'light'
+    const isCurrentDark = currentTheme.startsWith('dark')
+    const alternateTheme = isCurrentDark ? 'light' : 'dark'
+
+    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) {
+        uploadPromise1.then(url => {
+          if (url && gen === captureGeneration.current) {
+            updates[currentKey] = url
+            onUpdate?.({ [currentKey]: url })
+          }
+        }).catch(() => {})
+      }
+
+      // 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 altUrl = await uploadAndResolve(altDataUrl, widgetId, altLabel, base)
+          if (altUrl && gen === captureGeneration.current) {
+            updates[altKey] = altUrl
+          }
+        }
+
+        // 4. Switch back to original theme
+        const switchBackReqId = ++requestIdCounter.current
+        await switchTheme(cw, currentTheme, switchBackReqId, responseHandlers.current)
+      }
+
+      // Ensure upload-1 is complete before final update
+      await uploadPromise1
+
+      // 5. Restore iframe visibility
+      iframe.style.visibility = savedVisibility || ''
+
+      if (gen === captureGeneration.current && Object.keys(updates).length > 0) {
+        onUpdate?.(updates)
+      }
+      return updates
+    } catch (err) {
+      // Always restore visibility on error
+      if (iframe) iframe.style.visibility = ''
+      console.warn('[snapshot] Capture failed:', err)
+      return {}
+    } finally {
+      capturingRef.current = false
+    }
+  }, [onUpdate, iframeRef, widgetId, canvasTheme])
+
+  return { iframeReady, requestCapture }
+}

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

@@ -0,0 +1,225 @@
+/**
+ * Tests for useSnapshotCapture hook — parent-side capture orchestration.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useSnapshotCapture } from './useSnapshotCapture.js'
+
+vi.mock('../canvasApi.js', () => ({
+  uploadImage: vi.fn().mockResolvedValue({ filename: 'snapshot-test-widget--light.webp' }),
+}))
+
+import { uploadImage } from '../canvasApi.js'
+
+function createMockIframeRef(contentWindow = null) {
+  return { current: contentWindow ? { contentWindow } : null }
+}
+
+function createMockContentWindow() {
+  return { postMessage: vi.fn() }
+}
+
+describe('useSnapshotCapture', () => {
+  let listeners = []
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    listeners = []
+    const origAdd = window.addEventListener
+    const origRemove = window.removeEventListener
+    vi.spyOn(window, 'addEventListener').mockImplementation((type, fn, opts) => {
+      if (type === 'message') listeners.push(fn)
+      origAdd.call(window, type, fn, opts)
+    })
+    vi.spyOn(window, 'removeEventListener').mockImplementation((type, fn, opts) => {
+      if (type === 'message') listeners = listeners.filter(l => l !== fn)
+      origRemove.call(window, type, fn, opts)
+    })
+    // Mock Image so preload resolves immediately in tests
+    vi.stubGlobal('Image', class MockImage {
+      constructor() { this._onload = null }
+      set onload(fn) { this._onload = fn }
+      get onload() { return this._onload }
+      set onerror(fn) { this._onerror = fn }
+      set src(v) { this._src = v; Promise.resolve().then(() => this._onload?.()) }
+      get src() { return this._src }
+    })
+  })
+
+  afterEach(() => { vi.restoreAllMocks() })
+
+  function dispatchMessage(source, data) {
+    const event = new MessageEvent('message', { source, data })
+    listeners.forEach(fn => fn(event))
+  }
+
+  it('returns iframeReady=false initially', () => {
+    const iframeRef = createMockIframeRef()
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'w1', onUpdate: vi.fn(), canvasTheme: 'light' })
+    )
+    expect(result.current.iframeReady).toBe(false)
+  })
+
+  it('sets iframeReady=true on snapshot-ready message', () => {
+    const cw = createMockContentWindow()
+    const iframeRef = createMockIframeRef(cw)
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'w1', onUpdate: vi.fn(), canvasTheme: 'light' })
+    )
+    act(() => { dispatchMessage(cw, { type: 'storyboard:embed:snapshot-ready' }) })
+    expect(result.current.iframeReady).toBe(true)
+  })
+
+  it('no-ops when onUpdate is null', async () => {
+    const cw = createMockContentWindow()
+    const iframeRef = createMockIframeRef(cw)
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'w1', onUpdate: null, canvasTheme: 'light' })
+    )
+    await act(async () => { await result.current.requestCapture() })
+    expect(cw.postMessage).not.toHaveBeenCalled()
+  })
+
+  it('no-ops when iframe not ready', async () => {
+    const cw = createMockContentWindow()
+    const iframeRef = createMockIframeRef(cw)
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'w1', onUpdate: vi.fn(), canvasTheme: 'light' })
+    )
+    await act(async () => { await result.current.requestCapture() })
+    expect(cw.postMessage).not.toHaveBeenCalled()
+  })
+
+  it('sends capture + set-theme + capture + set-theme for dual-theme', async () => {
+    const cw = createMockContentWindow()
+    // Need a real iframe element for style.visibility
+    const style = { visibility: "" }
+    
+    const iframeRef = { current: { contentWindow: cw, style } }
+    const onUpdate = vi.fn()
+    const { result } = renderHook(() =>
+      useSnapshotCapture({ iframeRef, widgetId: 'test-widget', onUpdate, canvasTheme: 'light' })
+    )
+
+    act(() => { dispatchMessage(cw, { type: 'storyboard:embed:snapshot-ready' }) })
+
+    uploadImage
+      .mockResolvedValueOnce({ filename: 'snapshot-test-widget--light.webp' })
+      .mockResolvedValueOnce({ filename: 'snapshot-test-widget--dark.webp' })
+
+    await act(async () => {
+      const promise = result.current.requestCapture()
+
+      // Respond to capture 1 (current=light)
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:snapshot', requestId: 1, dataUrl: 'data:image/webp;base64,LIGHT' })
+
+      // Respond to set-theme (switch to dark)
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:theme-applied', requestId: 2 })
+
+      // Respond to capture 2 (alternate=dark)
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:snapshot', requestId: 3, dataUrl: 'data:image/webp;base64,DARK' })
+
+      // Respond to set-theme back (switch to light)
+      await new Promise(r => setTimeout(r, 10))
+      dispatchMessage(cw, { type: 'storyboard:embed:theme-applied', requestId: 4 })
+
+      await promise
+    })
+
+    // 2 captures + 2 theme switches = 4 postMessages
+    expect(cw.postMessage).toHaveBeenCalledTimes(4)
+    expect(uploadImage).toHaveBeenCalledTimes(2)
+    // Intermediate onUpdate for current theme + final with both
+    expect(onUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        snapshotLight: expect.stringContaining('snapshot-test-widget--light.webp'),
+      })
+    )
+    expect(onUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        snapshotLight: expect.stringContaining('snapshot-test-widget--light.webp'),
+        snapshotDark: expect.stringContaining('snapshot-test-widget--dark.webp'),
+      })
+    )
+  })
+
+  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) })
+    )
+  })
+})

package/src/context.jsx

@@ -119,10 +119,10 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
   const params = useParams()
 
   // Canvas route detection — matches current URL against registered canvas routes
-  const canvasName = useMemo(() => matchCanvasRoute(location.pathname), [location.pathname])
+  const canvasId = useMemo(() => matchCanvasRoute(location.pathname), [location.pathname])
   const isMissingCanvasRoute = useMemo(
-    () => isCanvasPath(location.pathname) && !canvasName && !matchStoryRoute(location.pathname),
-    [location.pathname, canvasName],
+    () => isCanvasPath(location.pathname) && !canvasId && !matchStoryRoute(location.pathname),
+    [location.pathname, canvasId],
   )
 
   // Story route detection — matches current URL against registered story routes
@@ -139,7 +139,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
 
   // Resolve flow name with prototype scoping (skip for canvas/story pages)
   const activeFlowName = useMemo(() => {
-    if (canvasName || isMissingCanvasRoute || storyName || isMissingStoryRoute) return null
+    if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return null
     const requested = sceneParam || flowName || sceneName
     if (requested) {
       // Allow fully-scoped flow names from URLs/widgets without re-prefixing
@@ -163,7 +163,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     // 4. Global default — or null if no flow exists at all
     if (flowExists('default')) return 'default'
     return null
-  }, [canvasName, isMissingCanvasRoute, storyName, isMissingStoryRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
+  }, [canvasId, isMissingCanvasRoute, storyName, isMissingStoryRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
 
   // Auto-install body class sync (sb-key--value classes on <body>)
   useEffect(() => installBodyClassSync(), [])
@@ -175,10 +175,10 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     const branchSuffix = branchMatch ? ` (${branchMatch[1]})` : ''
 
     let title
-    if (canvasName) {
-      const canvasData = canvases?.[canvasName]
+    if (canvasId) {
+      const canvasData = canvases?.[canvasId]
       const meta = canvasData?._canvasMeta
-      const pageTitle = canvasData?.title || canvasName.split('/').pop()
+      const pageTitle = canvasData?.title || canvasId.split('/').pop()
       title = (meta?.title || pageTitle) + ' · Storyboard'
     } else if (prototypeName) {
       title = prototypeName + ' · Storyboard'
@@ -187,7 +187,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     }
 
     document.title = title + branchSuffix
-  }, [canvasName, prototypeName])
+  }, [canvasId, prototypeName])
 
   // Mount design modes UI when enabled in storyboard.config.json
   useEffect(() => {
@@ -207,7 +207,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
 
   // Skip flow loading for canvas/story pages and flow-less pages
   const { data, error } = useMemo(() => {
-    if (canvasName || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null }
+    if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null }
     if (!activeFlowName) return { data: {}, error: null }
     try {
       let flowData = loadFlow(activeFlowName)
@@ -226,11 +226,11 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     } catch (err) {
       return { data: null, error: err.message }
     }
-  }, [canvasName, isMissingCanvasRoute, storyName, isMissingStoryRoute, activeFlowName, recordName, recordParam, params, prototypeName])
+  }, [canvasId, isMissingCanvasRoute, storyName, isMissingStoryRoute, activeFlowName, recordName, recordParam, params, prototypeName])
 
   // Canvas pages get their own rendering path — no flow data needed
-  if (canvasName) {
-    const canvasData = canvases?.[canvasName]
+  if (canvasId) {
+    const canvasData = canvases?.[canvasId]
     const group = canvasData?._group
     const siblingPages = group ? canvasGroupMap.get(group) || [] : []
     const canvasMeta = canvasData?._canvasMeta || null
@@ -245,7 +245,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     return (
       <StoryboardContext.Provider value={canvasValue}>
         <Suspense fallback={null}>
-          <CanvasPageLazy name={canvasName} siblingPages={siblingPages} canvasMeta={canvasMeta} />
+          <CanvasPageLazy canvasId={canvasId} siblingPages={siblingPages} canvasMeta={canvasMeta} />
         </Suspense>
       </StoryboardContext.Provider>
     )

package/src/story/StoryPage.jsx

@@ -59,15 +59,15 @@ export default function StoryPage({ name }) {
     return () => { cancelled = true }
   }, [name, story])
 
-  // Signal snapshot-ready after story renders in embed mode
+  // Signal snapshot-ready after story renders in embed mode.
+  // Stories have no data loading so they render fast — fire
+  // the explicit ready signal instead of waiting for the 1.5s fallback.
   useEffect(() => {
     if (!isEmbed || !exports || window.parent === window) return
-    // Wait for fonts + paint to settle before signaling ready
-    Promise.all([
-      document.fonts?.ready || Promise.resolve(),
-      new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))),
-    ]).then(() => {
-      window.parent.postMessage({ type: 'storyboard:embed:snapshot-ready' }, '*')
+    document.fonts.ready.then(() => {
+      requestAnimationFrame(() => requestAnimationFrame(() => {
+        window.__sbSnapshotReady?.()
+      }))
     })
   }, [isEmbed, exports])