@dfosco/storyboard-react 4.2.0-beta.0 → 4.2.0-beta.17

package/src/canvas/widgets/WidgetChrome.jsx

@@ -1,6 +1,6 @@
 import { useState, useCallback, useRef, useEffect, useSyncExternalStore } from 'react'
 import { Tooltip } from '@primer/react'
-import { EyeIcon as OcticonEye, EyeClosedIcon as OcticonEyeClosed, CodeIcon as OcticonCode, UnwrapIcon as OcticonUnwrap, ImageIcon as OcticonImage, UnfoldIcon as OcticonUnfold, FoldIcon as OcticonFold } from '@primer/octicons-react'
+import { EyeIcon as OcticonEye, EyeClosedIcon as OcticonEyeClosed, CodeIcon as OcticonCode, UnwrapIcon as OcticonUnwrap, ImageIcon as OcticonImage, UnfoldIcon as OcticonUnfold, FoldIcon as OcticonFold, ScreenFullIcon as OcticonScreenFull } from '@primer/octicons-react'
 import { getConnectorConfig, getInteractGate } from './widgetConfig.js'
 import styles from './WidgetChrome.module.css'
 import overlayStyles from './embedOverlay.module.css'
@@ -117,11 +117,7 @@ function DownloadIcon() {
 }
 
 function ExpandIcon() {
-  return (
-    <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-      <path d="M1.75 10a.75.75 0 0 1 .75.75v2.5c0 .138.112.25.25.25h2.5a.75.75 0 0 1 0 1.5h-2.5A1.75 1.75 0 0 1 1 13.25v-2.5a.75.75 0 0 1 .75-.75Zm12.5 0a.75.75 0 0 1 .75.75v2.5A1.75 1.75 0 0 1 13.25 15h-2.5a.75.75 0 0 1 0-1.5h2.5a.25.25 0 0 0 .25-.25v-2.5a.75.75 0 0 1 .75-.75ZM2.75 1h2.5a.75.75 0 0 1 0 1.5h-2.5a.25.25 0 0 0-.25.25v2.5a.75.75 0 0 1-1.5 0v-2.5C1 1.784 1.784 1 2.75 1Zm10.5 0C14.216 1 15 1.784 15 2.75v2.5a.75.75 0 0 1-1.5 0v-2.5a.25.25 0 0 0-.25-.25h-2.5a.75.75 0 0 1 0-1.5Z" />
-    </svg>
-  )
+  return <OcticonScreenFull size={12} />
 }
 
 function SyncIcon() {
@@ -140,6 +136,14 @@ function FoldIcon() {
   return <OcticonFold size={12} />
 }
 
+function ColumnsIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M12 3v18" /><rect x="3" y="3" width="18" height="18" rx="2" />
+    </svg>
+  )
+}
+
 /** Icon registry — maps icon name strings from config to React components. */
 const ICON_REGISTRY = {
   'trash': DeleteIcon,
@@ -161,6 +165,7 @@ const ICON_REGISTRY = {
   'sync': SyncIcon,
   'unfold': UnfoldIcon,
   'fold': FoldIcon,
+  'columns': ColumnsIcon,
 }
 
 /** Danger-styled actions in the overflow menu. */
@@ -438,8 +443,8 @@ export default function WidgetChrome({
     }
     // Widget-specific actions go through the widget's imperative ref
     if (widgetRef?.current?.handleAction) {
-      widgetRef.current.handleAction(actionId)
-      return
+      const handled = widgetRef.current.handleAction(actionId)
+      if (handled !== false) return
     }
     // Fallback to generic handler
     onAction?.(actionId)
@@ -614,10 +619,10 @@ export default function WidgetChrome({
                     feature={feature}
                     onAction={(actionId) => {
                       if (widgetRef?.current?.handleAction) {
-                        widgetRef.current.handleAction(actionId)
-                      } else {
-                        onAction?.(actionId)
+                        const handled = widgetRef.current.handleAction(actionId)
+                        if (handled !== false) return
                       }
+                      onAction?.(actionId)
                     }}
                   />
                 )
@@ -632,10 +637,10 @@ export default function WidgetChrome({
                 onAction={(actionId) => {
                   // Route overflow menu actions through the widget ref first
                   if (actionId !== 'delete' && actionId !== 'copy' && widgetRef?.current?.handleAction) {
-                    widgetRef.current.handleAction(actionId)
-                  } else {
-                    onAction?.(actionId)
+                    const handled = widgetRef.current.handleAction(actionId)
+                    if (handled !== false) return
                   }
+                  onAction?.(actionId)
                 }}
               />
             )}

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

@@ -19,6 +19,16 @@
   pointer-events: auto;
 }
 
+/* Invisible expanded hit area — 15px padding around the visible dot */
+.anchorPort::before {
+  content: '';
+  position: absolute;
+  top: -15px;
+  left: -15px;
+  right: -15px;
+  bottom: -15px;
+}
+
 .chromeContainer:hover .anchorPort {
   opacity: 0.6;
 }

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

@@ -56,72 +56,70 @@ describe('Embed interaction overlay', () => {
       resizable: false,
     }
 
-    it('renders "Click to open" hint when no snapshot exists', () => {
+    it('renders "Click to interact" hint when no snapshot exists', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const hint = screen.getByText('Click to open')
+      const hint = screen.getByText('Click to interact')
       expect(hint).toBeInTheDocument()
-      // CSS modules mangle class names, just check the element exists
     })
 
     it('enters interactive mode on single click (not double-click)', async () => {
       const { container } = render(<PrototypeEmbed {...defaultProps} />)
       
-      // Overlay should exist before interaction
-      const overlay = screen.getByRole('button', { name: /click to open/i })
+      // Overlay should exist before interaction; iframe is always rendered
+      const overlay = screen.getByRole('button', { name: /click to interact with prototype/i })
       expect(overlay).toBeInTheDocument()
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
-      expect(screen.getByText('Design Overview')).toBeInTheDocument()
+      expect(container.querySelector('iframe')).toBeInTheDocument()
       
       // Single click should remove the overlay (enter interactive mode)
       fireEvent.click(overlay)
       
       // Overlay should no longer exist
-      expect(screen.queryByRole('button', { name: /click to open/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
       expect(container.querySelector('iframe')).toBeInTheDocument()
 
       fireEvent.pointerDown(document.body)
-      expect(screen.getByRole('button', { name: /click to open/i })).toBeInTheDocument()
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to interact with prototype/i })).toBeInTheDocument()
+      expect(container.querySelector('iframe')).toBeInTheDocument()
     })
 
     it('does not enter interactive mode on shift+click (preserves multi-select)', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to open/i })
+      const overlay = screen.getByRole('button', { name: /click to interact with prototype/i })
       fireEvent.click(overlay, { shiftKey: true })
       
       // Overlay should still exist (did not enter interactive mode)
-      expect(screen.getByRole('button', { name: /click to open/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to interact with prototype/i })).toBeInTheDocument()
     })
 
     it('does not enter interactive mode on meta+click (preserves multi-select)', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to open/i })
+      const overlay = screen.getByRole('button', { name: /click to interact with prototype/i })
       fireEvent.click(overlay, { metaKey: true })
       
-      expect(screen.getByRole('button', { name: /click to open/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to interact with prototype/i })).toBeInTheDocument()
     })
 
     it('supports keyboard interaction (Enter key) with event prevention', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to open/i })
+      const overlay = screen.getByRole('button', { name: /click to interact with prototype/i })
       const event = { key: 'Enter', preventDefault: vi.fn(), stopPropagation: vi.fn() }
       fireEvent.keyDown(overlay, event)
       
-      expect(screen.queryByRole('button', { name: /click to open/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
     })
 
     it('supports keyboard interaction (Space key) with event prevention', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to open/i })
+      const overlay = screen.getByRole('button', { name: /click to interact with prototype/i })
       const event = { key: ' ', preventDefault: vi.fn(), stopPropagation: vi.fn() }
       fireEvent.keyDown(overlay, event)
       
-      expect(screen.queryByRole('button', { name: /click to open/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
     })
   })
 
@@ -143,7 +141,7 @@ describe('Embed interaction overlay', () => {
       const { container } = render(<FigmaEmbed {...defaultProps} />)
       
       const overlay = screen.getByRole('button', { name: /click to interact/i })
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
+      expect(container.querySelector('iframe')).toBeInTheDocument()
       fireEvent.click(overlay)
       
       expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
@@ -151,7 +149,7 @@ describe('Embed interaction overlay', () => {
 
       fireEvent.pointerDown(document.body)
       expect(screen.getByRole('button', { name: /click to interact/i })).toBeInTheDocument()
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
+      expect(container.querySelector('iframe')).toBeInTheDocument()
     })
   })
 
@@ -162,20 +160,20 @@ describe('Embed interaction overlay', () => {
       resizable: false,
     }
 
-    it('mounts iframe only after user activation', () => {
+    it('mounts iframe and shows overlay initially, removes overlay on click', () => {
       const { container } = render(<StoryWidget {...defaultProps} />)
 
-      const overlay = screen.getByRole('button', { name: /click to open story component/i })
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
+      const overlay = screen.getByRole('button', { name: /click to interact$/i })
+      expect(container.querySelector('iframe')).toBeInTheDocument()
 
       fireEvent.click(overlay)
 
-      expect(screen.queryByRole('button', { name: /click to open story component/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
       expect(container.querySelector('iframe')).toBeInTheDocument()
 
       fireEvent.pointerDown(document.body)
-      expect(screen.getByRole('button', { name: /click to open story component/i })).toBeInTheDocument()
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to interact$/i })).toBeInTheDocument()
+      expect(container.querySelector('iframe')).toBeInTheDocument()
     })
   })
 

package/src/canvas/widgets/expandUtils.js

@@ -0,0 +1,188 @@
+/**
+ * Shared utilities for expandable widget modals and split-screen.
+ *
+ * Reads the canvas bridge state to find connected widgets eligible
+ * for split-screen, and builds iframe URLs for secondary panes.
+ */
+import { isSplitScreenCapable, getWidgetMeta } from './widgetConfig.js'
+
+/**
+ * Find a connected widget that is split-screen capable.
+ * Returns the first match, or null.
+ * @param {string} widgetId — the primary (expanded) widget's ID
+ * @returns {{ id: string, type: string, position: { x: number, y: number }, props: Object } | null}
+ */
+export function findConnectedSplitTarget(widgetId) {
+  const bridge = window.__storyboardCanvasBridgeState
+  if (!bridge?.connectors || !bridge?.widgets) return null
+
+  // Only allow split-screen when this widget has exactly one connection
+  const myConnections = bridge.connectors.filter(
+    (c) => c.start?.widgetId === widgetId || c.end?.widgetId === widgetId,
+  )
+  if (myConnections.length !== 1) return null
+
+  const conn = myConnections[0]
+  const otherId = conn.start?.widgetId === widgetId ? conn.end?.widgetId : conn.start?.widgetId
+
+  // The other widget must also have exactly one connection
+  const otherConnections = bridge.connectors.filter(
+    (c) => c.start?.widgetId === otherId || c.end?.widgetId === otherId,
+  )
+  if (otherConnections.length !== 1) return null
+
+  const other = bridge.widgets.find((w) => w.id === otherId)
+  if (other && isSplitScreenCapable(other.type)) return other
+  return null
+}
+
+/**
+ * Get the x-coordinate position of a widget from bridge state.
+ * @param {string} widgetId
+ * @returns {number}
+ */
+export function getWidgetX(widgetId) {
+  const bridge = window.__storyboardCanvasBridgeState
+  if (!bridge?.widgets) return 0
+  const w = bridge.widgets.find((w) => w.id === widgetId)
+  return w?.position?.x ?? 0
+}
+
+/**
+ * Determine pane order (left/right) based on x-coordinates.
+ * Returns { left, right } where each is 'primary' or 'secondary'.
+ * @param {string} primaryId — the widget being expanded
+ * @param {{ id: string, position?: { x: number } }} secondaryWidget
+ * @returns {{ primaryIsLeft: boolean }}
+ */
+export function getPaneOrder(primaryId, secondaryWidget) {
+  const primaryX = getWidgetX(primaryId)
+  const secondaryX = secondaryWidget?.position?.x ?? 0
+  return { primaryIsLeft: primaryX <= secondaryX }
+}
+
+/**
+ * Build an iframe URL for a widget to render in a secondary pane.
+ * Returns null if the widget type isn't iframe-embeddable.
+ * @param {{ type: string, props: Object }} widget
+ * @returns {string | null}
+ */
+export function buildSecondaryIframeUrl(widget) {
+  if (!widget) return null
+  const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
+  const baseClean = base.endsWith('/') ? base.slice(0, -1) : base
+
+  if (widget.type === 'prototype') {
+    const src = widget.props?.src
+    if (!src) return null
+    if (/^https?:\/\//.test(src)) return src
+    return `${baseClean}${src.startsWith('/') ? '' : '/'}${src}?_sb_embed&_sb_hide_branch_bar&_sb_theme_target=prototype`
+  }
+
+  if (widget.type === 'figma-embed') {
+    const url = widget.props?.url
+    if (!url) return null
+    // Inline a minimal figma embed URL builder to avoid circular deps
+    try {
+      const u = new URL(url)
+      if (!u.hostname.endsWith('figma.com')) return null
+      return `https://www.figma.com/embed?embed_host=storyboard&url=${encodeURIComponent(url)}`
+    } catch { return null }
+  }
+
+  if (widget.type === 'codepen-embed') {
+    const url = widget.props?.url
+    if (!url) return null
+    try {
+      const u = new URL(url)
+      if (!u.hostname.endsWith('codepen.io')) return null
+      const path = u.pathname.replace(/\/(pen|full|details)\//, '/embed/')
+      return `https://codepen.io${path}?default-tab=result`
+    } catch { return null }
+  }
+
+  if (widget.type === 'story') {
+    const storyId = widget.props?.storyId
+    const exportName = widget.props?.exportName
+    if (!storyId) return null
+    const storyData = typeof window !== 'undefined' && window.__storyboardStoryIndex?.[storyId]
+    if (storyData?._route) {
+      const params = new URLSearchParams()
+      if (exportName) params.set('export', exportName)
+      params.set('_sb_embed', '')
+      params.set('_sb_hide_branch_bar', '')
+      return `${baseClean}${storyData._route}?${params}`
+    }
+    return null
+  }
+
+  return null
+}
+
+/**
+ * Reparent a terminal widget's xterm container into a target element.
+ * Returns a cleanup function to restore the original position.
+ * @param {string} widgetId
+ * @param {HTMLElement} targetEl
+ * @returns {(() => void) | null}
+ */
+export function reparentTerminalInto(widgetId, targetEl) {
+  const widgetEl = document.querySelector(`[data-widget-id="${widgetId}"]`)
+  if (!widgetEl) return null
+
+  const xtermEl = widgetEl.querySelector('[class*="xtermContainer"]')
+  if (!xtermEl) return null
+
+  const originalParent = xtermEl.parentElement
+  const originalNextSibling = xtermEl.nextSibling
+
+  targetEl.appendChild(xtermEl)
+
+  return () => {
+    if (originalNextSibling) {
+      originalParent.insertBefore(xtermEl, originalNextSibling)
+    } else {
+      originalParent.appendChild(xtermEl)
+    }
+  }
+}
+
+/**
+ * Build a "Type · Metadata" label for a widget in split-screen top bar.
+ * @param {{ type: string, props: Object }} widget
+ * @returns {string}
+ */
+export function getSplitPaneLabel(widget) {
+  if (!widget) return ''
+  const meta = getWidgetMeta(widget.type)
+  const typeName = meta?.label || widget.type
+
+  if (widget.type === 'terminal' || widget.type === 'terminal-read') {
+    return `Terminal · ${widget.props?.prettyName || '…'}`
+  }
+  if (widget.type === 'prototype') {
+    return `Prototype · ${widget.props?.src || '…'}`
+  }
+  if (widget.type === 'figma-embed') {
+    const url = widget.props?.url || ''
+    let name = 'Figma'
+    try { name = new URL(url).pathname.split('/').pop() || 'Figma' } catch { /* */ }
+    return `Figma · ${name}`
+  }
+  if (widget.type === 'codepen-embed') {
+    return `CodePen · ${widget.props?.url || '…'}`
+  }
+  if (widget.type === 'story') {
+    return `Story · ${widget.props?.storyId || '…'}`
+  }
+  if (widget.type === 'markdown') {
+    const content = widget.props?.content || ''
+    const firstLine = content.split('\n').find((l) => l.trim()) || ''
+    const preview = firstLine.replace(/^#+\s*/, '').slice(0, 40)
+    return `Markdown · ${preview || '…'}`
+  }
+  if (widget.type === 'link-preview') {
+    return `${widget.props?.github ? 'GitHub' : 'Link'} · ${widget.props?.title || widget.props?.url || '…'}`
+  }
+  return typeName
+}

package/src/canvas/widgets/index.js

@@ -7,6 +7,8 @@ import FigmaEmbed from './FigmaEmbed.jsx'
 import CodePenEmbed from './CodePenEmbed.jsx'
 import StoryWidget from './StoryWidget.jsx'
 import TerminalWidget from './TerminalWidget.jsx'
+import TerminalReadWidget from './TerminalReadWidget.jsx'
+import ActionWidget from './ActionWidget.jsx'
 
 /**
  * Maps widget type strings to their React components.
@@ -22,6 +24,9 @@ export const widgetRegistry = {
   'codepen-embed': CodePenEmbed,
   'story': StoryWidget,
   'terminal': TerminalWidget,
+  'terminal-read': TerminalReadWidget,
+  'action': ActionWidget,
+  'agent': TerminalWidget,
 }
 
 /**

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

@@ -1,8 +1,8 @@
 /**
  * Tests for iframe snapshot display — single snapshot prop.
  */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { render, fireEvent, waitFor, act } from '@testing-library/react'
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
 import PrototypeEmbed from './PrototypeEmbed.jsx'
 import StoryWidget from './StoryWidget.jsx'
 
@@ -54,9 +54,9 @@ afterEach(() => {
   document.querySelectorAll('[data-sb-canvas-theme]').forEach(el => el.remove())
 })
 
-describe('Snapshot display', () => {
+describe('Snapshot display (snapshots removed — iframes always render)', () => {
   describe('PrototypeEmbed', () => {
-    it('shows snapshot image when valid snapshot prop exists', () => {
+    it('renders iframe even when snapshot prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-abc123"
@@ -72,13 +72,11 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-proto-abc123.webp')
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('falls back to snapshotLight for backward compat', () => {
+    it('renders iframe when snapshotLight prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-abc123"
@@ -94,12 +92,11 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-proto-abc123--light.webp')
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('shows placeholder when no snapshot exists', () => {
+    it('renders iframe when no snapshot exists', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-xyz"
@@ -110,32 +107,10 @@ describe('Snapshot display', () => {
       )
 
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
-    })
-
-    it('falls back to placeholder when snapshot image fails to load', () => {
-      const { wrapper } = renderInCanvas(
-        <PrototypeEmbed
-          id="proto-abc123"
-          props={{
-            src: '/test',
-            width: 400,
-            height: 300,
-            zoom: 100,
-            snapshot: '/_storyboard/canvas/images/snapshot-proto-abc123.webp?v=123',
-          }}
-          onUpdate={vi.fn()}
-          resizable={false}
-        />
-      )
-
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      fireEvent.error(img)
-      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('ignores snapshot that does not match widget ID', () => {
+    it('ignores snapshot prop that does not match widget ID', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-abc123"
@@ -152,9 +127,10 @@ describe('Snapshot display', () => {
       )
 
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('does not show snapshot for external URLs', () => {
+    it('renders iframe for external URLs regardless of snapshot', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-ext"
@@ -171,11 +147,12 @@ describe('Snapshot display', () => {
       )
 
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
   })
 
   describe('StoryWidget', () => {
-    it('shows snapshot image when valid snapshot prop exists', () => {
+    it('renders iframe even when snapshot prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <StoryWidget
           id="story-abc123"
@@ -191,13 +168,11 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-story-abc123.webp')
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('falls back to snapshotDark for backward compat', () => {
+    it('renders iframe when snapshotDark prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <StoryWidget
           id="story-abc123"
@@ -210,50 +185,27 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-story-abc123--dark.webp')
-    })
-
-    it('shows placeholder when no snapshot exists', () => {
-      const { wrapper } = renderInCanvas(
-        <StoryWidget
-          id="story-xyz"
-          props={{
-            storyId: 'button-patterns',
-            exportName: 'Primary',
-            width: 400,
-            height: 300,
-          }}
-          onUpdate={vi.fn()}
-          resizable={false}
-        />
-      )
-
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('falls back to placeholder when snapshot image fails to load', () => {
+    it('renders iframe when no snapshot exists', () => {
       const { wrapper } = renderInCanvas(
         <StoryWidget
-          id="story-abc123"
+          id="story-xyz"
           props={{
             storyId: 'button-patterns',
             exportName: 'Primary',
             width: 400,
             height: 300,
-            snapshot: '/_storyboard/canvas/images/snapshot-story-abc123.webp?v=456',
           }}
           onUpdate={vi.fn()}
           resizable={false}
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      fireEvent.error(img)
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
   })
 })

package/src/canvas/widgets/widgetConfig.js

@@ -151,6 +151,24 @@ export function getWidgetMeta(type) {
   return { label: def.label, icon: def.icon }
 }
 
+/**
+ * Check if a widget type supports expanding to a full-screen modal.
+ * @param {string} type — widget type string
+ * @returns {boolean}
+ */
+export function isExpandable(type) {
+  return widgetTypes[type]?.expandable === true
+}
+
+/**
+ * Check if a widget type can appear in a split-screen pane.
+ * @param {string} type — widget type string
+ * @returns {boolean}
+ */
+export function isSplitScreenCapable(type) {
+  return widgetTypes[type]?.splitScreen === true
+}
+
 /**
  * Get the interact gate config for a widget type.
  * @returns {{ enabled: boolean, label: string }} 
@@ -170,7 +188,7 @@ export function getInteractGate(type) {
  */
 export function getMenuWidgetTypes() {
   return Object.entries(widgetTypes)
-    .filter(([type]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed' && type !== 'codepen-embed' && type !== 'story')
+    .filter(([type]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed' && type !== 'codepen-embed' && type !== 'story' && type !== 'terminal-read')
     .map(([type, def]) => ({ type, label: def.label, icon: def.icon }))
 }