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

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

@@ -0,0 +1,71 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import LinkPreview from './LinkPreview.jsx'
+
+describe('LinkPreview', () => {
+  it('renders GitHub issue card with markdown body and author byline', () => {
+    const { container } = render(
+      <LinkPreview
+        id="link-1"
+        props={{
+          url: 'https://github.com/dfosco/storyboard/issues/42',
+          title: '#42 Ship GitHub embeds',
+          github: {
+            context: 'GitHub · dfosco/storyboard · Issue #42',
+            body: '## Summary\n\nThis is a **bold** point.\n\n- Item one\n- Item two',
+            authors: ['dfosco'],
+            createdAt: '2026-01-01T00:00:00Z',
+          },
+        }}
+      />,
+    )
+
+    // Title split: text + muted number
+    expect(screen.getByText('Ship GitHub embeds')).toBeInTheDocument()
+    expect(screen.getByText('#42')).toBeInTheDocument()
+
+    // Markdown body renders headings, bold, lists
+    const headings = container.querySelectorAll('h2')
+    expect(headings.length).toBeGreaterThanOrEqual(1)
+    // Find the body heading (not the title)
+    const summaryHeading = Array.from(headings).find(h => h.textContent === 'Summary')
+    expect(summaryHeading).toBeTruthy()
+    expect(container.querySelectorAll('li')).toHaveLength(2)
+
+    // Author byline
+    expect(screen.getByText('dfosco')).toBeInTheDocument()
+  })
+
+  it('does not render GitHub layout for non-GitHub links', () => {
+    render(
+      <LinkPreview
+        id="link-2"
+        props={{
+          url: 'https://example.com/docs',
+          title: 'Example docs',
+        }}
+      />,
+    )
+
+    expect(screen.getByText('Example docs')).toBeInTheDocument()
+    expect(screen.getByText('example.com')).toBeInTheDocument()
+  })
+
+  it('renders plain link-preview without github data', () => {
+    const { container } = render(
+      <LinkPreview
+        id="link-3"
+        props={{
+          url: 'https://figma.com/design/abc',
+          title: 'My design',
+          width: 320,
+          height: 120,
+        }}
+      />,
+    )
+
+    expect(screen.getByText('My design')).toBeInTheDocument()
+    // No issue card rendered
+    expect(container.querySelector('header')).toBeNull()
+  })
+})

package/src/canvas/widgets/MarkdownBlock.jsx

@@ -19,7 +19,8 @@ function renderMarkdown(text) {
     .use(remarkGfm)
     .use(remarkHtml, { sanitize: false })
     .processSync(text)
-  return String(result)
+  // Open all links in new tabs
+  return String(result).replace(/<a\s/g, '<a target="_blank" rel="noopener noreferrer" ')
 }
 
 /**

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

@@ -24,6 +24,38 @@
   pointer-events: none;
 }
 
+.preview a {
+  color: var(--sb--markdown-accent);
+  text-decoration: none;
+  pointer-events: auto;
+  cursor: pointer;
+}
+
+.preview a:hover {
+  text-decoration: underline;
+}
+
+.preview img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 6px;
+  border: 1px solid var(--borderColor-default, #d0d7de);
+  margin: 8px 0;
+  display: block;
+  pointer-events: auto;
+}
+
+.preview video {
+  max-width: 100%;
+  height: auto;
+  border-radius: 6px;
+  border: 1px solid var(--borderColor-default, #d0d7de);
+  margin: 8px 0;
+  display: block;
+  pointer-events: auto;
+  background: var(--bgColor-muted, #f6f8fa);
+}
+
 .preview h1 {
   font-size: 20px;
   font-weight: 700;
@@ -75,10 +107,11 @@
   list-style-type: decimal;
 }
 
-/* GFM: Task lists */
+/* GFM: Task lists — accent-colored checkboxes */
 .preview input[type="checkbox"] {
   margin-right: 6px;
   pointer-events: none;
+  accent-color: var(--sb--markdown-accent);
 }
 
 .preview li:has(input[type="checkbox"]) {
@@ -112,16 +145,6 @@
   font-weight: 600;
 }
 
-/* GFM: Autolinks */
-.preview a {
-  color: var(--sb--markdown-accent);
-  text-decoration: none;
-}
-
-.preview a:hover {
-  text-decoration: underline;
-}
-
 /* Code blocks */
 .preview pre {
   padding: 12px 16px;

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -3,9 +3,10 @@ import { createPortal } from 'react-dom'
 import { buildPrototypeIndex } from '@dfosco/storyboard-core'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import { readProp, prototypeEmbedSchema } from './widgetProps.js'
-import { getEmbedChromeVars, resolveCanvasTheme } from './embedTheme.js'
+import { getEmbedChromeVars, subscribeCanvasTheme } from './embedTheme.js'
 import { useIframeDevLogs } from './iframeDevLogs.js'
 import { useSnapshotCapture } from './useSnapshotCapture.js'
+import { enqueueRefresh, cancelRefresh, REVEAL_INTERVAL } from './refreshQueue.js'
 import styles from './PrototypeEmbed.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
@@ -66,8 +67,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   const height = readProp(props, 'height', prototypeEmbedSchema)
   const zoom = readProp(props, 'zoom', prototypeEmbedSchema)
   const label = readProp(props, 'label', prototypeEmbedSchema) || src
-  const snapshotLight = props?.snapshotLight || ''
-  const snapshotDark = props?.snapshotDark || ''
+  const snapshot = props?.snapshot || props?.snapshotLight || props?.snapshotDark || ''
 
   const basePath = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
   const baseSegment = basePath.replace(/^\//, '')
@@ -88,7 +88,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   const [iframeLoaded, setIframeLoaded] = useState(false)
   const [expanded, setExpanded] = useState(false)
   const [filter, setFilter] = useState('')
-  const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasTheme())
+  const [canvasTheme, setCanvasTheme] = useState('light')
   const [brokenSnaps, setBrokenSnaps] = useState({})
 
   const inputRef = useRef(null)
@@ -97,6 +97,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   const iframeRef = useRef(null)
   const captureOnReadyRef = useRef(false)
   const exitSessionRef = useRef(0)
+  const teardownTimerRef = useRef(null)
   const inlineContainerRef = useRef(null)
   const modalContainerRef = useRef(null)
   const resizeTimerRef = useRef(null)
@@ -108,14 +109,11 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     iframeRef,
     widgetId,
     onUpdate: isExternal ? null : onUpdate,
-    canvasTheme,
+    showIframe,
   })
 
-  // Determine available snapshots for layered rendering
-  const isDark = canvasTheme?.startsWith('dark')
-  const hasLightSnap = !isExternal && !!(snapshotLight && snapshotLight.includes(widgetId) && !brokenSnaps[snapshotLight])
-  const hasDarkSnap = !isExternal && !!(snapshotDark && snapshotDark.includes(widgetId) && !brokenSnaps[snapshotDark])
-  const hasAnySnap = hasLightSnap || hasDarkSnap
+  // Single snapshot — backward compat reads snapshotLight/snapshotDark if snapshot is missing
+  const hasSnap = !isExternal && !!(snapshot && snapshot.includes(widgetId) && !brokenSnaps[snapshot])
 
   const iframeSrc = useMemo(() => {
     if (!rawSrc) return ''
@@ -125,8 +123,8 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     const base = hashIdx >= 0 ? rawSrc.slice(0, hashIdx) : rawSrc
     const hash = hashIdx >= 0 ? rawSrc.slice(hashIdx) : ''
     const sep = base.includes('?') ? '&' : '?'
-    return `${base}${sep}_sb_embed&_sb_theme_target=prototype&_sb_canvas_theme=${canvasTheme}${hash}`
-  }, [rawSrc, canvasTheme])
+    return `${base}${sep}_sb_embed&_sb_theme_target=prototype${hash}`
+  }, [rawSrc])
 
   useIframeDevLogs({
     widget: 'PrototypeEmbed',
@@ -260,13 +258,36 @@ 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(() => {
+          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 if (isExternal && showIframe) {
+          // External embeds (e.g. Figma) are slow to reload — keep the
+          // iframe mounted for 2 min so re-entering is instant.
+          const session = ++exitSessionRef.current
+          clearTimeout(teardownTimerRef.current)
+          teardownTimerRef.current = setTimeout(() => {
             if (exitSessionRef.current !== session) return
             setShowIframe(false)
-          })
+          }, 2 * 60 * 1000)
         } else {
           setShowIframe(false)
         }
@@ -276,17 +297,34 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     return () => document.removeEventListener('pointerdown', handlePointerDown)
   }, [interactive, expanded, onUpdate, isExternal, iframeLoaded, requestCapture])
 
+  useEffect(() => subscribeCanvasTheme({
+    anchorRef: embedRef,
+    onTheme: setCanvasTheme,
+  }), [])
+
+  // On canvas theme change, enqueue a background snapshot refresh.
+  // Skips the initial render (canvasThemeInitRef tracks first value).
+  const canvasThemeInitRef = useRef(true)
+  const refreshMetaRef = useRef(null)
   useEffect(() => {
-    const readTheme = () => setCanvasTheme(resolveCanvasTheme())
-    readTheme()
-    document.addEventListener('storyboard:theme:changed', readTheme)
-    return () => document.removeEventListener('storyboard:theme:changed', readTheme)
-  }, [])
+    if (canvasThemeInitRef.current) { canvasThemeInitRef.current = false; return }
+    if (isExternal || !onUpdate || interactive) return
+    const rect = embedRef.current?.getBoundingClientRect()
+    enqueueRefresh(widgetId, ({ revealOrder, batchStart }) => {
+      return new Promise((resolve) => {
+        refreshMetaRef.current = { revealOrder, batchStart, resolve }
+        captureOnReadyRef.current = true
+        setShowIframe(true)
+        // Safety timeout — report failure so retry pass picks it up
+        setTimeout(() => { refreshMetaRef.current = null; resolve(false) }, 10000)
+      })
+    }, rect ? { x: rect.left, y: rect.top } : undefined)
+  }, [canvasTheme]) // eslint-disable-line react-hooks/exhaustive-deps
 
   // Capture snapshot on first iframe ready (when no existing snapshot)
   useEffect(() => {
     if (!iframeReady || !onUpdate || isExternal) return
-    if (!hasAnySnap) {
+    if (!hasSnap) {
       requestCapture()
     }
   }, [iframeReady]) // eslint-disable-line react-hooks/exhaustive-deps
@@ -295,12 +333,39 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   useEffect(() => {
     if (iframeReady && captureOnReadyRef.current) {
       captureOnReadyRef.current = false
-      requestCapture()
+      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), [])
+  // Cleanup timers on unmount
+  useEffect(() => () => {
+    clearTimeout(resizeTimerRef.current)
+    clearTimeout(teardownTimerRef.current)
+  }, [])
 
   // Close expanded modal on Escape
   useEffect(() => {
@@ -374,9 +439,11 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
 
   const enterInteractive = useCallback(() => {
     exitSessionRef.current++
+    clearTimeout(teardownTimerRef.current)
+    cancelRefresh(widgetId)
     setShowIframe(true)
     setInteractive(true)
-  }, [])
+  }, [widgetId])
 
   // Expose imperative action handlers for WidgetChrome
   useImperativeHandle(ref, () => ({
@@ -518,25 +585,14 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
               className={styles.iframeContainer}
               style={expanded ? { visibility: 'hidden' } : undefined}
             >
-              {/* Snapshot layer — both themes always in DOM for instant swap */}
-              {hasLightSnap && (
-                <img
-                  src={snapshotLight}
-                  className={styles.snapshotImage}
-                  style={(isDark && hasDarkSnap) ? { visibility: 'hidden' } : undefined}
-                  alt={`${prototypeTitle} snapshot`}
-                  draggable={false}
-                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshotLight]: true }))}
-                />
-              )}
-              {hasDarkSnap && (
+              {/* Snapshot layer — single image */}
+              {hasSnap && (
                 <img
-                  src={snapshotDark}
+                  src={snapshot}
                   className={styles.snapshotImage}
-                  style={(!isDark && hasLightSnap) ? { visibility: 'hidden' } : undefined}
                   alt={`${prototypeTitle} snapshot`}
                   draggable={false}
-                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshotDark]: true }))}
+                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshot]: true }))}
                 />
               )}
 
@@ -551,6 +607,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                     height: height / scale,
                     transform: `scale(${scale})`,
                     transformOrigin: '0 0',
+                    transition: 'opacity 150ms ease',
                     ...(iframeLoaded ? {} : { opacity: 0 }),
                   }}
                   onLoad={() => setIframeLoaded(true)}
@@ -559,8 +616,8 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                 />
               )}
 
-              {/* Placeholder — only when no snapshots and no iframe */}
-              {!hasAnySnap && !showIframe && (
+              {/* Placeholder — only when no snapshot and no iframe */}
+              {!hasSnap && !showIframe && (
                 <div className={styles.placeholder}>
                   <CollageFrameIcon size={36} />
                   <span className={styles.placeholderLabel}>{`${prototypeTitle} prototype`}</span>
@@ -584,9 +641,9 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                     enterInteractive()
                   }
                 }}
-                aria-label="Click to interact with prototype"
+                aria-label={hasSnap ? 'Click to interact with prototype' : 'Click to open prototype'}
               >
-                <span className={overlayStyles.interactHint}>Click to interact</span>
+                <span className={overlayStyles.interactHint}>{hasSnap ? 'Click to interact' : 'Click to open'}</span>
               </div>
             )}
           </>

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

@@ -92,6 +92,7 @@
   object-position: top left;
   display: block;
   pointer-events: none;
+  transition: opacity 150ms ease;
 }
 
 .empty {

package/src/canvas/widgets/StoryWidget.jsx

@@ -18,7 +18,8 @@ import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
 import { useIframeDevLogs } from './iframeDevLogs.js'
 import { useSnapshotCapture } from './useSnapshotCapture.js'
-import { resolveCanvasTheme } from './embedTheme.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'
 
@@ -39,7 +40,7 @@ function resolveStoryUrl(storyId, exportName) {
 
   const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
   const route = story._route
-  const params = new URLSearchParams({ _sb_embed: '1' })
+  const params = new URLSearchParams({ _sb_embed: '1', _sb_theme_target: 'prototype' })
   if (exportName) params.set('export', exportName)
 
   return `${base}${route}?${params}`
@@ -86,14 +87,14 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const exportName = props?.exportName || ''
   const width = props?.width
   const height = props?.height
-  const snapshotLight = props?.snapshotLight || ''
-  const snapshotDark = props?.snapshotDark || ''
+  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)
@@ -105,27 +106,39 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const [brokenSnaps, setBrokenSnaps] = useState({})
 
   // Resolve canvas theme — reactive to theme changes
-  const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasTheme())
+  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(() => {
-    const readTheme = () => setCanvasTheme(resolveCanvasTheme())
-    document.addEventListener('storyboard:theme:changed', readTheme)
-    return () => document.removeEventListener('storyboard:theme:changed', readTheme)
-  }, [])
+    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,
-    canvasTheme,
+    showIframe,
   })
 
-  // 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
+  // Single snapshot
+  const hasSnap = !!(snapshot && snapshot.includes(widgetId) && !brokenSnaps[snapshot])
 
   // Re-resolve story URL when the story index is live-patched (new story added)
   useEffect(() => {
@@ -147,9 +160,10 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
 
   const enterInteractive = useCallback(() => {
     exitSessionRef.current++
+    cancelRefresh(widgetId)
     setShowIframe(true)
     setInteractive(true)
-  }, [])
+  }, [widgetId])
 
   useEffect(() => {
     if (!showIframe) setIframeLoaded(false)
@@ -167,13 +181,27 @@ 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(() => {
+          setTimeout(() => {
             if (exitSessionRef.current !== session) return
-            setShowIframe(false)
-          })
+            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)
         }
@@ -193,7 +221,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   // Capture snapshot on first iframe ready (when no existing snapshot)
   useEffect(() => {
     if (!iframeReady || !onUpdate) return
-    if (!hasAnySnap) {
+    if (!hasSnap) {
       requestCapture()
     }
   }, [iframeReady]) // eslint-disable-line react-hooks/exhaustive-deps
@@ -202,7 +230,31 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   useEffect(() => {
     if (iframeReady && captureOnReadyRef.current) {
       captureOnReadyRef.current = false
-      requestCapture()
+      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])
 
@@ -388,25 +440,14 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
         ) : (
           <>
             <div className={styles.content}>
-              {/* Snapshot layer — both themes always in DOM for instant swap */}
-              {hasLightSnap && (
-                <img
-                  src={snapshotLight}
-                  className={styles.snapshotImage}
-                  style={(isDark && hasDarkSnap) ? { visibility: 'hidden' } : undefined}
-                  alt={`${displayName} snapshot`}
-                  draggable={false}
-                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshotLight]: true }))}
-                />
-              )}
-              {hasDarkSnap && (
+              {/* Snapshot layer — single image */}
+              {hasSnap && (
                 <img
-                  src={snapshotDark}
+                  src={snapshot}
                   className={styles.snapshotImage}
-                  style={(!isDark && hasLightSnap) ? { visibility: 'hidden' } : undefined}
                   alt={`${displayName} snapshot`}
                   draggable={false}
-                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshotDark]: true }))}
+                  onError={() => setBrokenSnaps(prev => ({ ...prev, [snapshot]: true }))}
                 />
               )}
 
@@ -416,14 +457,17 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
                   ref={iframeRef}
                   src={iframeSrc}
                   className={styles.iframe}
-                  style={iframeLoaded ? undefined : { opacity: 0 }}
+                  style={{
+                    ...(iframeLoaded ? undefined : { opacity: 0 }),
+                    transition: 'opacity 150ms ease',
+                  }}
                   onLoad={() => setIframeLoaded(true)}
                   title={displayName}
                 />
               )}
 
-              {/* Placeholder — only when no snapshots and no iframe */}
-              {!hasAnySnap && !showIframe && (
+              {/* Placeholder — only when no snapshot and no iframe */}
+              {!hasSnap && !showIframe && (
                 <div className={styles.placeholder}>
                   <ComponentIcon size={36} />
                   <span className={styles.placeholderLabel}>{displayName}</span>
@@ -447,9 +491,9 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
                     enterInteractive()
                   }
                 }}
-                aria-label="Click to interact with story component"
+                aria-label={hasSnap ? 'Click to interact with story component' : 'Click to open story component'}
               >
-                <span className={overlayStyles.interactHint}>Click to interact</span>
+                <span className={overlayStyles.interactHint}>{hasSnap ? 'Click to interact' : 'Click to open'}</span>
               </div>
             )}
           </>

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

@@ -93,6 +93,7 @@
   object-position: top left;
   display: block;
   pointer-events: none;
+  transition: opacity 150ms ease;
 }
 
 .codeView {