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

package/src/canvas/widgets/StoryWidget.jsx

@@ -12,17 +12,25 @@
  * Props: { storyId, exportName, width, height }
  */
 import { forwardRef, useImperativeHandle, useRef, useCallback, useState, useEffect, useMemo } from 'react'
-import { getStoryData, getFlag } from '@dfosco/storyboard-core'
+import { getStoryData } from '@dfosco/storyboard-core'
 import { createInspectorHighlighter } from '@dfosco/storyboard-core/inspector/highlighter'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
-import { uploadImage } from '../canvasApi.js'
-import { useIframeQueue } from './useViewportEntry.js'
+import { useIframeDevLogs } from './iframeDevLogs.js'
+import { useSnapshotCapture } from './useSnapshotCapture.js'
+import { resolveCanvasTheme } from './embedTheme.js'
 import styles from './StoryWidget.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
-function devLog(...args) {
-  try { if (getFlag('dev-logs')) console.log('[canvas:story-widget]', ...args) } catch { /* */ }
+function ComponentIcon({ size = 36 }) {
+  return (
+    <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" />
+    </svg>
+  )
 }
 
 function resolveStoryUrl(storyId, exportName) {
@@ -78,89 +86,46 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const exportName = props?.exportName || ''
   const width = props?.width
   const height = props?.height
-
-  // Snapshot props for lazy loading
-  const snapshotLight = props?.snapshotLight || null
-  const snapshotDark = props?.snapshotDark || null
+  const snapshotLight = props?.snapshotLight || ''
+  const snapshotDark = props?.snapshotDark || ''
 
   const containerRef = useRef(null)
   const iframeRef = useRef(null)
+  const resizeTimerRef = useRef(null)
+  const captureOnReadyRef = useRef(false)
+  const exitSessionRef = useRef(0)
   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({})
 
-  // Theme tracking for snapshot selection
-  const [canvasTheme, setCanvasTheme] = useState(() => {
-    if (typeof localStorage === 'undefined') return 'light'
-    const stored = localStorage.getItem('sb-color-scheme') || 'system'
-    if (stored !== 'system') return stored
-    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
-  })
+  // Resolve canvas theme — reactive to theme changes
+  const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasTheme())
 
   useEffect(() => {
-    function onThemeChanged() {
-      const stored = localStorage.getItem('sb-color-scheme') || 'system'
-      if (stored !== 'system') { setCanvasTheme(stored); return }
-      setCanvasTheme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
-    }
-    document.addEventListener('storyboard:theme:changed', onThemeChanged)
-    return () => document.removeEventListener('storyboard:theme:changed', onThemeChanged)
+    const readTheme = () => setCanvasTheme(resolveCanvasTheme())
+    document.addEventListener('storyboard:theme:changed', readTheme)
+    return () => document.removeEventListener('storyboard:theme:changed', readTheme)
   }, [])
 
-  // Lazy loading state — only use snapshots that match this widget's ID
-  const isDark = canvasTheme?.startsWith('dark')
-  const snapshotMatchesWidget = (url) => url && widgetId && url.includes(widgetId)
-  const validSnapshotLight = snapshotMatchesWidget(snapshotLight) ? snapshotLight : null
-  const validSnapshotDark = snapshotMatchesWidget(snapshotDark) ? snapshotDark : null
-  const currentSnapshot = isDark ? validSnapshotDark : validSnapshotLight
-  const hasSnapshot = !!currentSnapshot
-
-  // Sequential iframe queue — prevents stampede when many embeds lack snapshots.
-  const { ready: queueReady, releaseSlot } = useIframeQueue(hasSnapshot, widgetId)
-  const [preloadIframe, setPreloadIframe] = useState(hasSnapshot)
-  const [iframeLoaded, setIframeLoaded] = useState(false)
-  const [showIframe, setShowIframe] = useState(hasSnapshot)
-  const [showSpinner, setShowSpinner] = useState(false)
-  const capturingRef = useRef(false)
-
-  devLog(widgetId, { hasSnapshot, queueReady, preloadIframe, showIframe, iframeLoaded, storyId })
-
-  // Start loading when the queue grants this widget a slot
-  useEffect(() => {
-    if (queueReady && !preloadIframe) {
-      devLog(widgetId, 'queue ready → loading iframe')
-      setPreloadIframe(true)
-      setShowIframe(true)
-    }
-  }, [queueReady, preloadIframe])
-
-  // Release the queue slot once the iframe has loaded or user clicked to interact
-  useEffect(() => {
-    if (iframeLoaded) {
-      devLog(widgetId, 'iframe loaded')
-      releaseSlot()
-    }
-  }, [iframeLoaded, releaseSlot])
-
-  // Click-to-interact: immediately start iframe and release queue slot for others
-  const activateIframe = useCallback(() => {
-    devLog(widgetId, 'user activated → jumping queue')
-    setShowIframe(true)
-    setPreloadIframe(true)
-    releaseSlot()
-  }, [releaseSlot, widgetId])
+  // Snapshot capture hook
+  const { iframeReady, requestCapture } = useSnapshotCapture({
+    iframeRef,
+    widgetId,
+    onUpdate,
+    canvasTheme,
+  })
 
-  // Show spinner only after 500ms of loading
-  useEffect(() => {
-    if (showIframe && !iframeLoaded && hasSnapshot) {
-      const timer = setTimeout(() => setShowSpinner(true), 500)
-      return () => clearTimeout(timer)
-    }
-    setShowSpinner(false)
-  }, [showIframe, iframeLoaded, hasSnapshot])
-  const [storyIndexKey, setStoryIndexKey] = useState(0)
+  // Determine available snapshots for layered rendering
+  const isDark = canvasTheme?.startsWith('dark')
+  const hasLightSnap = !!(snapshotLight && snapshotLight.includes(widgetId) && !brokenSnaps[snapshotLight])
+  const hasDarkSnap = !!(snapshotDark && snapshotDark.includes(widgetId) && !brokenSnaps[snapshotDark])
+  const hasAnySnap = hasLightSnap || hasDarkSnap
 
   // Re-resolve story URL when the story index is live-patched (new story added)
   useEffect(() => {
@@ -180,90 +145,69 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     })
   }, [onUpdate])
 
-  const enterInteractive = useCallback(() => setInteractive(true), [])
+  const enterInteractive = useCallback(() => {
+    exitSessionRef.current++
+    setShowIframe(true)
+    setInteractive(true)
+  }, [])
+
+  useEffect(() => {
+    if (!showIframe) setIframeLoaded(false)
+  }, [showIframe])
 
+  // 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.
   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) {
+          // Keep iframe mounted but hidden for background capture
+          if (iframeRef.current) iframeRef.current.style.visibility = 'hidden'
+          const session = ++exitSessionRef.current
+          requestCapture({ force: true }).then(() => {
+            if (exitSessionRef.current !== session) return
+            setShowIframe(false)
+          })
+        } else {
+          setShowIframe(false)
+        }
       }
     }
     document.addEventListener('pointerdown', handlePointerDown)
     return () => document.removeEventListener('pointerdown', handlePointerDown)
-  }, [interactive])
-
-  // Listen for snapshot messages from the iframe
-  useEffect(() => {
-    function handleMessage(e) {
-      if (!iframeRef.current?.contentWindow) return
-      if (e.source !== iframeRef.current.contentWindow) return
-
-      if (e.data?.type === 'storyboard:embed:snapshot') {
-        if (e.data.error) {
-          console.warn('[canvas] Story snapshot capture failed:', e.data.error)
-          return
-        }
-        handleSnapshotResult(e.data.dataUrl)
-        return
-      }
-
-      // snapshot-ready means the iframe content has fully rendered
-      if (e.data?.type === 'storyboard:embed:snapshot-ready') {
-        setIframeLoaded(true)
-        if (onUpdate) requestSnapshotCapture()
-      }
-    }
-    window.addEventListener('message', handleMessage)
-    return () => window.removeEventListener('message', handleMessage)
-  }, [onUpdate, canvasTheme])
-
-  const requestSnapshotCapture = useCallback(() => {
-    if (!iframeRef.current?.contentWindow || capturingRef.current) return
-    capturingRef.current = true
-    iframeRef.current.contentWindow.postMessage({
-      type: 'storyboard:embed:capture',
-      requestId: `story-snap-${Date.now()}`,
-    }, '*')
-  }, [])
-
-  const handleSnapshotResult = useCallback(async (dataUrl) => {
-    if (!dataUrl || !onUpdate || !widgetId) return
-    capturingRef.current = false
-    try {
-      const result = await uploadImage(dataUrl, `snapshot-${widgetId}`)
-      if (!result?.success || !result?.filename) return
-      const imageUrl = `/_storyboard/canvas/images/${result.filename}`
-      const themeKey = isDark ? 'snapshotDark' : 'snapshotLight'
-      onUpdate?.({ [themeKey]: imageUrl })
-    } catch (err) {
-      console.warn('[canvas] Failed to upload story snapshot:', err)
-    }
-  }, [onUpdate, isDark, widgetId])
-
-  // Re-capture after resize
-  const resizeCaptureTimer = useRef(null)
-  const triggerResizeCapture = useCallback(() => {
-    if (!onUpdate) return
-    clearTimeout(resizeCaptureTimer.current)
-    resizeCaptureTimer.current = setTimeout(() => requestSnapshotCapture(), 2000)
-  }, [requestSnapshotCapture, onUpdate])
+  }, [interactive, onUpdate, iframeLoaded, requestCapture])
 
   const handleResize = useCallback((w, h) => {
     onUpdate?.({ width: w, height: h })
-    triggerResizeCapture()
-  }, [onUpdate, triggerResizeCapture])
+    // Recapture snapshot after resize (debounced)
+    clearTimeout(resizeTimerRef.current)
+    resizeTimerRef.current = setTimeout(() => requestCapture(), 1500)
+  }, [onUpdate, requestCapture])
 
-  // Re-capture for alternate theme variant when theme changes
-  const prevThemeRef = useRef(canvasTheme)
+  // Capture snapshot on first iframe ready (when no existing snapshot)
   useEffect(() => {
-    if (canvasTheme !== prevThemeRef.current && onUpdate && showIframe) {
-      prevThemeRef.current = canvasTheme
-      const timer = setTimeout(() => requestSnapshotCapture(), 3000)
-      return () => clearTimeout(timer)
+    if (!iframeReady || !onUpdate) return
+    if (!hasAnySnap) {
+      requestCapture()
     }
-    prevThemeRef.current = canvasTheme
-  }, [canvasTheme, onUpdate, showIframe, requestSnapshotCapture])
+  }, [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()
+    }
+  }, [iframeReady, requestCapture])
+
+  // Cleanup resize timer on unmount
+  useEffect(() => () => clearTimeout(resizeTimerRef.current), [])
 
   // Load source code when show-code is toggled on
   useEffect(() => {
@@ -350,15 +294,28 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
           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])
+  }), [storyId, showCode, toggleShowCode, copyCode, iframeReady, requestCapture])
 
   const iframeSrc = useMemo(
     () => resolveStoryUrl(storyId, exportName),
     [storyId, exportName, storyIndexKey],
   )
 
+  useIframeDevLogs({
+    widget: 'StoryWidget',
+    loaded: showIframe && !showCode && Boolean(iframeSrc),
+    src: iframeSrc,
+  })
+
   const displayName = exportName ? `${storyId} / ${exportName}` : storyId
 
   // Error state — missing story or no route
@@ -367,7 +324,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
       <WidgetWrapper>
         <div className={styles.container} ref={containerRef}>
           <div className={styles.error}>
-            <span className={styles.errorIcon}>📖</span>
+            <span className={styles.errorIcon}><ComponentIcon size={20} /></span>
             <span className={styles.errorText}>Missing story ID</span>
           </div>
         </div>
@@ -380,7 +337,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
       <WidgetWrapper>
         <div className={styles.container} ref={containerRef}>
           <div className={styles.error}>
-            <span className={styles.errorIcon}>📖</span>
+            <span className={styles.errorIcon}><ComponentIcon size={20} /></span>
             <span className={styles.errorText}>Story &ldquo;{storyId}&rdquo; not found or has no route</span>
           </div>
         </div>
@@ -396,7 +353,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     <WidgetWrapper>
       <div ref={containerRef} className={styles.container} style={sizeStyle}>
         <div className={styles.header}>
-          <span className={styles.headerIcon}>📖</span>
+          <span className={styles.headerIcon}><ComponentIcon size={16} /></span>
           <span className={styles.headerTitle}>{displayName}</span>
         </div>
         {showCode ? (
@@ -430,47 +387,55 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
           </div>
         ) : (
           <>
-            {/* Snapshot image — shown until iframe is fully loaded */}
-            {hasSnapshot && !(showIframe && iframeLoaded) && (
-              <div className={styles.content}>
+            <div className={styles.content}>
+              {/* Snapshot layer — both themes always in DOM for instant swap */}
+              {hasLightSnap && (
                 <img
-                  src={(import.meta.env.BASE_URL || '/').replace(/\/$/, '') + currentSnapshot}
-                  alt={displayName}
+                  src={snapshotLight}
                   className={styles.snapshotImage}
+                  style={(isDark && hasDarkSnap) ? { visibility: 'hidden' } : undefined}
+                  alt={`${displayName} snapshot`}
                   draggable={false}
+                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshotLight]: true }))}
                 />
-                {showIframe && !iframeLoaded && showSpinner && (
-                  <div className={styles.snapshotSpinner}>
-                    <div className={styles.spinner} />
-                  </div>
-                )}
-              </div>
-            )}
+              )}
+              {hasDarkSnap && (
+                <img
+                  src={snapshotDark}
+                  className={styles.snapshotImage}
+                  style={(!isDark && hasLightSnap) ? { visibility: 'hidden' } : undefined}
+                  alt={`${displayName} snapshot`}
+                  draggable={false}
+                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshotDark]: true }))}
+                />
+              )}
 
-            {/* Iframe — preloaded on hover, revealed after load */}
-            {(preloadIframe || showIframe) && (
-              <div
-                className={styles.content}
-                style={hasSnapshot && !(showIframe && iframeLoaded) ? { position: 'absolute', top: 31, left: 0, right: 0, bottom: 0, opacity: 0, pointerEvents: 'none' } : undefined}
-              >
+              {/* Iframe layer — on top, transparent until loaded */}
+              {showIframe && (
                 <iframe
                   ref={iframeRef}
                   src={iframeSrc}
                   className={styles.iframe}
+                  style={iframeLoaded ? undefined : { opacity: 0 }}
+                  onLoad={() => setIframeLoaded(true)}
                   title={displayName}
                 />
-              </div>
-            )}
+              )}
+
+              {/* Placeholder — only when no snapshots and no iframe */}
+              {!hasAnySnap && !showIframe && (
+                <div className={styles.placeholder}>
+                  <ComponentIcon size={36} />
+                  <span className={styles.placeholderLabel}>{displayName}</span>
+                </div>
+              )}
+            </div>
 
             {!interactive && (
               <div
                 className={overlayStyles.interactOverlay}
-                onPointerEnter={() => {
-                  if (!preloadIframe) setPreloadIframe(true)
-                }}
                 onClick={(e) => {
                   if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
-                  activateIframe()
                   enterInteractive()
                 }}
                 role="button"
@@ -479,7 +444,6 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
                   if (e.key === 'Enter' || e.key === ' ') {
                     e.preventDefault()
                     e.stopPropagation()
-                    activateIframe()
                     enterInteractive()
                   }
                 }}

package/src/canvas/widgets/StoryWidget.module.css

@@ -15,7 +15,7 @@
   display: flex;
   align-items: center;
   gap: 6px;
-  padding: 6px 10px;
+  padding: 10px 10px;
   font-size: 12px;
   font-weight: 500;
   color: var(--fgColor-muted, #656d76);
@@ -28,7 +28,7 @@
 }
 
 .headerIcon {
-  font-size: 13px;
+  display: inline-flex;
   flex-shrink: 0;
 }
 
@@ -38,57 +38,67 @@
 }
 
 .content {
+  position: relative;
   width: 100%;
-  height: calc(100% - 31px);
-}
-
-.iframe {
-  display: block;
-  width: 100%;
-  height: 100%;
-  border: none;
-}
-
-.snapshotImage {
-  display: block;
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-  object-position: top left;
+  height: calc(100% - 37px);
 }
 
-.snapshotSpinner {
+.placeholder {
   position: absolute;
   inset: 0;
   display: flex;
+  flex-direction: column;
   align-items: center;
   justify-content: center;
-  background: rgba(0, 0, 0, 0.08);
-  animation: fadeIn 150ms ease;
+  gap: 8px;
+  color: var(--fgColor-muted, #656d76);
+  text-align: center;
+}
+
+.placeholderLabel {
+  font-size: 13px;
+  font-weight: 500;
 }
 
 .spinner {
   width: 24px;
   height: 24px;
-  border: 2.5px solid var(--borderColor-default, #d0d7de);
-  border-top-color: var(--fgColor-accent, #0969da);
+  border: 3px solid var(--borderColor-muted, #d0d7de);
+  border-top-color: var(--fgColor-accent, #2f81f7);
   border-radius: 50%;
-  animation: spin 0.6s linear infinite;
+  animation: spin 0.8s linear infinite;
 }
 
 @keyframes spin {
+  from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
 
-@keyframes fadeIn {
-  from { opacity: 0; }
-  to { opacity: 1; }
+.iframe {
+  position: absolute;
+  inset: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  border: none;
+  z-index: 1;
+}
+
+.snapshotImage {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: top left;
+  display: block;
+  pointer-events: none;
 }
 
 .codeView {
   display: flex;
   flex-direction: column;
-  height: calc(100% - 31px);
+  height: calc(100% - 37px);
   overflow: hidden;
 }
 

package/src/canvas/widgets/WidgetChrome.jsx

@@ -204,8 +204,8 @@ function WidgetOverflowMenu({ widgetId, menuFeatures, onAction }) {
       url.searchParams.set('widget', widgetId)
       navigator.clipboard.writeText(url.toString()).catch(() => {})
     } else if (action === 'copy-widget-id') {
-      const canvasName = window.location.pathname.split('/').filter(Boolean).pop() || ''
-      navigator.clipboard.writeText(`${canvasName}/${widgetId}`).catch(() => {})
+      const canvasId = window.__storyboardCanvasBridgeState?.canvasId || ''
+      navigator.clipboard.writeText(`${canvasId}::${widgetId}`).catch(() => {})
     } else {
       onAction?.(action)
     }
@@ -436,6 +436,7 @@ export default function WidgetChrome({
   return (
     <div
       className={styles.chromeContainer}
+      data-widget-id={widgetId}
       data-tc-elevated={(hovered || selected) || undefined}
       onMouseEnter={(readOnly && !hasFeatures) ? undefined : handleMouseEnter}
       onMouseLeave={(readOnly && !hasFeatures) ? undefined : handleMouseLeave}