@dfosco/storyboard-react 4.2.0-alpha.11 → 4.2.0-alpha.13

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "4.2.0-alpha.11",
+  "version": "4.2.0-alpha.13",
   "type": "module",
   "dependencies": {
     "@base-ui/react": "^1.4.0",
-    "@dfosco/storyboard-core": "4.2.0-alpha.11",
-    "@dfosco/tiny-canvas": "4.2.0-alpha.11",
+    "@dfosco/storyboard-core": "4.2.0-alpha.13",
+    "@dfosco/tiny-canvas": "4.2.0-alpha.13",
     "@neodrag/react": "^2.3.1",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1",

package/src/canvas/CanvasPage.jsx

@@ -12,6 +12,7 @@ import { getPasteRules } from '@dfosco/storyboard-core'
 import { registerSmoothCorners } from '@dfosco/storyboard-core/smooth-corners'
 import { isGitHubEmbedUrl } from './widgets/githubUrl.js'
 import WidgetChrome from './widgets/WidgetChrome.jsx'
+import { EmbedControllerProvider } from './widgets/useEmbedController.jsx'
 import ComponentWidget from './widgets/ComponentWidget.jsx'
 import useUndoRedo from './useUndoRedo.js'
 import useMarqueeSelect from './useMarqueeSelect.js'
@@ -530,6 +531,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
   const [snapEnabled, setSnapEnabled] = useState(canvas?.snapToGrid ?? false)
   const [snapGridSize, setSnapGridSize] = useState(canvas?.gridSize || 40)
+  const [perfMode, setPerfMode] = useState(canvas?.performanceMode ?? false)
   const [showGhInstallBanner, setShowGhInstallBanner] = useState(false)
 
   // Refs for snap settings (used by drop handler inside effect closure)
@@ -670,6 +672,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     setLocalSources(canvas?.sources ?? [])
     setSnapEnabled(canvas?.snapToGrid ?? false)
     setSnapGridSize(canvas?.gridSize || 40)
+    setPerfMode(canvas?.performanceMode ?? false)
     undoRedo.reset()
     // Only reset viewport state when switching to a different canvas,
     // not when the same canvas refreshes with server data.
@@ -1549,6 +1552,21 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     return () => document.removeEventListener('storyboard:canvas:toggle-snap', handleSnapToggle)
   }, [canvasId])
 
+  // Listen for performance mode toggle from command palette
+  useEffect(() => {
+    function handlePerfToggle() {
+      setPerfMode((prev) => {
+        const next = !prev
+        updateCanvas(canvasId, { settings: { performanceMode: next } }).catch((err) =>
+          console.error('[canvas] Failed to persist performance mode:', err)
+        )
+        return next
+      })
+    }
+    document.addEventListener('storyboard:canvas:toggle-performance-mode', handlePerfToggle)
+    return () => document.removeEventListener('storyboard:canvas:toggle-performance-mode', handlePerfToggle)
+  }, [canvasId])
+
   // Broadcast snap state to Svelte toolbar
   useEffect(() => {
     document.dispatchEvent(new CustomEvent('storyboard:canvas:snap-state', {
@@ -1649,6 +1667,14 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }))
   }, [canvasId, zoom])
 
+  // Keep bridge in sync with widgets/connectors for expand features
+  useEffect(() => {
+    const bridge = window[CANVAS_BRIDGE_STATE_KEY] || {}
+    bridge.widgets = localWidgets
+    bridge.connectors = localConnectors
+    window[CANVAS_BRIDGE_STATE_KEY] = bridge
+  }, [localWidgets, localConnectors])
+
   // Delete selected widget on Delete/Backspace key
   useEffect(() => {
     function handleSelectStart(e) {
@@ -2403,9 +2429,11 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
             dragPreview={connectorDrag}
             hidden={widgetDragging}
           />
+          <EmbedControllerProvider performanceMode={perfMode} scrollRef={scrollRef}>
           <Canvas {...canvasProps} onDragStart={isLocalDev ? handleItemDragStart : undefined} onDrag={isLocalDev ? handleItemDrag : undefined} onDragEnd={isLocalDev ? handleItemDragEnd : undefined}>
             {allChildren}
           </Canvas>
+          </EmbedControllerProvider>
         </div>
       </div>
       {showGhInstallBanner && (

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -6,6 +6,7 @@ import ResizeHandle from './ResizeHandle.jsx'
 import { readProp, prototypeEmbedSchema } from './widgetProps.js'
 import { getEmbedChromeVars } from './embedTheme.js'
 import { useIframeDevLogs } from './iframeDevLogs.js'
+import { useEmbedActive } from './useEmbedController.jsx'
 import styles from './PrototypeEmbed.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
@@ -67,6 +68,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   const [expanded, setExpanded] = useState(false)
   const [filter, setFilter] = useState('')
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
+  const { active: embedActive, activate: activateEmbed, performanceMode, tooMany } = useEmbedActive(widgetId, embedRef)
   const inputRef = useRef(null)
   const filterRef = useRef(null)
   const embedRef = useRef(null)
@@ -84,6 +86,8 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     return `${base}${sep}_sb_embed&_sb_hide_branch_bar&_sb_theme_target=prototype&_sb_canvas_theme=${canvasTheme}${hash}`
   }, [rawSrc, canvasTheme])
 
+  const inactive = !embedActive
+
   const prototypeIndex = useMemo(() => {
     try { return buildPrototypeIndex() }
     catch { return { folders: [], prototypes: [], globalFlows: [], sorted: { title: { prototypes: [], folders: [] } } } }
@@ -295,7 +299,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
         className={styles.embed}
         style={{ width, height, ...chromeVars }}
       >
-        <div className={styles.header}>
+        <div className={`${styles.header}${inactive ? ` ${styles.headerPaused}` : ''}`}>
           <span className={styles.headerIcon}><CollageFrameIcon size={16} /></span>
           <span className={styles.headerTitle}>{prototypeTitle}</span>
         </div>
@@ -353,6 +357,17 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
               </div>
             </form>
           </div>
+        ) : iframeSrc && inactive ? (
+          <div
+            className={overlayStyles.interactOverlay}
+            onClick={() => { activateEmbed(); enterInteractive() }}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => { if (e.key === 'Enter') { activateEmbed(); enterInteractive() } }}
+            aria-label="Click to refresh"
+          >
+            <span className={overlayStyles.interactHint}>Click to refresh</span>
+          </div>
         ) : iframeSrc ? (
           <>
             <div

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

@@ -33,6 +33,12 @@
   text-overflow: ellipsis;
 }
 
+.headerPaused {
+  background: var(--bgColor-attention-muted, #fff8c5);
+  color: var(--fgColor-attention, #9a6700);
+  border-bottom-color: var(--borderColor-attention-muted, #d4a72c66);
+}
+
 .iframeContainer {
   position: relative;
   width: 100%;

package/src/canvas/widgets/StoryWidget.jsx

@@ -10,6 +10,7 @@
  */
 import { forwardRef, useImperativeHandle, useRef, useCallback, useState, useEffect, useMemo } from 'react'
 import { getStoryData } from '@dfosco/storyboard-core'
+import { useEmbedActive } from './useEmbedController.jsx'
 import { createInspectorHighlighter } from '@dfosco/storyboard-core/inspector/highlighter'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
@@ -65,6 +66,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const [highlightedHtml, setHighlightedHtml] = useState(null)
   const [sourceLoading, setSourceLoading] = useState(false)
   const [storyIndexKey, setStoryIndexKey] = useState(0)
+  const { active: embedActive, activate: activateEmbed, performanceMode, tooMany } = useEmbedActive(widgetId, containerRef)
 
   // Re-resolve story URL when the story index is live-patched
   useEffect(() => {
@@ -171,6 +173,9 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     [storyId, exportName, storyIndexKey],
   )
 
+  // Only render iframe when embed is active (controlled by EmbedController)
+  const shouldRenderIframe = embedActive && iframeSrc
+
   useIframeDevLogs({
     widget: 'StoryWidget',
     loaded: interactive && !showCode && Boolean(iframeSrc),
@@ -178,6 +183,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   })
 
   const displayName = exportName ? `${storyId} / ${exportName}` : storyId
+  const inactive = !embedActive
 
   if (!storyId) {
     return (
@@ -212,7 +218,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   return (
     <WidgetWrapper>
       <div ref={containerRef} className={styles.container} style={sizeStyle}>
-        <div className={styles.header}>
+        <div className={`${styles.header}${inactive ? ` ${styles.headerPaused}` : ''}`}>
           <span className={styles.headerIcon}><ComponentIcon size={16} /></span>
           <span className={styles.headerTitle}>{displayName}</span>
         </div>
@@ -236,6 +242,17 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
               <pre className={styles.codeBlock}><code>{sourceCode || ''}</code></pre>
             )}
           </div>
+        ) : inactive ? (
+          <div
+            className={overlayStyles.interactOverlay}
+            onClick={() => { activateEmbed(); enterInteractive() }}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => { if (e.key === 'Enter') { activateEmbed(); enterInteractive() } }}
+            aria-label="Click to refresh"
+          >
+            <span className={overlayStyles.interactHint}>Click to refresh</span>
+          </div>
         ) : (
           <>
             <div className={styles.content}>

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

@@ -37,6 +37,12 @@
   text-overflow: ellipsis;
 }
 
+.headerPaused {
+  background: var(--bgColor-attention-muted, #fff8c5);
+  color: var(--fgColor-attention, #9a6700);
+  border-bottom-color: var(--borderColor-attention-muted, #d4a72c66);
+}
+
 .content {
   position: relative;
   width: 100%;

package/src/canvas/widgets/TerminalWidget.jsx

@@ -1,4 +1,5 @@
-import { useRef, useEffect, useCallback, useState } from 'react'
+import { useRef, useEffect, useCallback, useState, forwardRef, useImperativeHandle } from 'react'
+import { createPortal } from 'react-dom'
 import { readProp } from './widgetProps.js'
 import { schemas } from './widgetProps.js'
 import { getTerminalConfig } from '@dfosco/storyboard-core'
@@ -56,6 +57,52 @@ function calcDimensions(widthPx, heightPx) {
   return { cols, rows }
 }
 
+const EMBED_TYPES = new Set(['prototype', 'story'])
+
+/**
+ * Find the first connected embed (prototype or story) widget via the canvas bridge.
+ */
+function findConnectedEmbed(widgetId) {
+  const bridge = window.__storyboardCanvasBridgeState
+  if (!bridge?.connectors || !bridge?.widgets) return null
+  const connectedIds = new Set()
+  for (const c of bridge.connectors) {
+    if (c.startWidgetId === widgetId) connectedIds.add(c.endWidgetId)
+    if (c.endWidgetId === widgetId) connectedIds.add(c.startWidgetId)
+  }
+  for (const w of bridge.widgets) {
+    if (connectedIds.has(w.id) && EMBED_TYPES.has(w.type)) return w
+  }
+  return null
+}
+
+/**
+ * Build an iframe URL for a connected embed widget.
+ */
+function buildEmbedUrl(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`
+  }
+  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 route = exportName ? `${storyData._route}?export=${exportName}` : storyData._route
+      return `${baseClean}${route}`
+    }
+    return null
+  }
+  return null
+}
+
 const DEFAULT_THEME = {
   background: '#0d1117',
   foreground: '#e6edf3',
@@ -79,7 +126,7 @@ const DEFAULT_THEME = {
   brightWhite: '#f0f6fc',
 }
 
-export default function TerminalWidget({ id, props, onUpdate, resizable }) {
+export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizable }, ref) {
   const width = readProp(props, 'width', terminalSchema)
   const height = readProp(props, 'height', terminalSchema)
   const prettyName = props?.prettyName || null
@@ -88,18 +135,59 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
   const termRef = useRef(null)
   const terminalRef = useRef(null)
   const wsRef = useRef(null)
-  const [ready, setReady] = useState(false)
-  const [error, setError] = useState(null)
-  const [sessionEnded, setSessionEnded] = useState(false)
+
+  // State machine: dormant → connecting → live → ended
+  //                                    ↘ error
+  const [phase, setPhase] = useState('dormant') // dormant | connecting | live | error | ended
+  const [errorMsg, setErrorMsg] = useState(null)
+  const [interactive, setInteractive] = useState(false)
   const [connectAttempt, setConnectAttempt] = useState(0)
+  const [expanded, setExpanded] = useState(false)
+  const [waking, setWaking] = useState(false)
+  const expandContainerRef = useRef(null)
+
+  // Activate: transition from dormant to connecting
+  const activate = useCallback(() => {
+    if (phase === 'dormant') setPhase('connecting')
+  }, [phase])
+
+  const enterInteractive = useCallback(() => {
+    if (phase === 'dormant') {
+      setPhase('connecting')
+    }
+    setInteractive(true)
+  }, [phase])
+
+  // Exit interactive on click outside
+  useEffect(() => {
+    if (!interactive) return
+    function handlePointerDown(e) {
+      if (terminalRef.current && !terminalRef.current.contains(e.target)) {
+        const chromeEl = e.target.closest(`[data-widget-id="${id}"]`)
+        if (chromeEl) return
+        setInteractive(false)
+      }
+    }
+    document.addEventListener('pointerdown', handlePointerDown)
+    return () => document.removeEventListener('pointerdown', handlePointerDown)
+  }, [interactive, id])
+
+  useImperativeHandle(ref, () => ({
+    handleAction(actionId) {
+      if (actionId === 'expand') {
+        if (phase === 'dormant') setPhase('connecting')
+        setExpanded(true)
+      }
+    },
+  }), [phase])
 
   const handleResize = useCallback((w, h) => {
     onUpdate?.({ width: w, height: h })
   }, [onUpdate])
 
-  // Initialize terminal
+  // Connect terminal + WebSocket only when phase is 'connecting'
   useEffect(() => {
-    if (!containerRef.current) return
+    if (phase !== 'connecting' || !containerRef.current) return
 
     let disposed = false
     let term = null
@@ -126,55 +214,46 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
         term.open(containerRef.current)
         termRef.current = term
 
-        // Connect WebSocket
         const url = getWsUrl(id, prettyName)
         ws = new WebSocket(url)
         wsRef.current = ws
 
         ws.onopen = () => {
           if (disposed) return
-          setReady(true)
+          setPhase('live')
           ws.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
         }
 
         ws.onmessage = (e) => {
           if (disposed) return
           const data = typeof e.data === 'string' ? e.data : null
-          // Intercept JSON control messages from the server
           if (data && data.startsWith('{')) {
             try {
               const msg = JSON.parse(data)
-              if (msg.type === 'session-info' || msg.type === 'conflict' || msg.type === 'detached') {
-                // Control message — don't render to terminal
-                return
-              }
-            } catch {
-              // Not valid JSON — pass through as terminal data
-            }
+              if (msg.type === 'session-info' || msg.type === 'conflict' || msg.type === 'detached') return
+            } catch { /* not JSON */ }
           }
           term.write(typeof e.data === 'string' ? e.data : new Uint8Array(e.data))
         }
 
         ws.onclose = () => {
           if (disposed) return
-          setReady(false)
-          setSessionEnded(true)
+          setPhase('ended')
         }
 
         ws.onerror = () => {
           if (disposed) return
-          setReady(false)
-          setSessionEnded(true)
+          setPhase('ended')
         }
 
-        // Terminal input → WebSocket
         term.onData((data) => {
-          if (ws.readyState === WebSocket.OPEN) {
-            ws.send(data)
-          }
+          if (ws.readyState === WebSocket.OPEN) ws.send(data)
         })
       } catch (err) {
-        if (!disposed) setError(err.message || 'Failed to load terminal')
+        if (!disposed) {
+          setErrorMsg(err.message || 'Failed to load terminal')
+          setPhase('error')
+        }
       }
     }
 
@@ -187,7 +266,7 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
       termRef.current = null
       wsRef.current = null
     }
-  }, [id, connectAttempt])
+  }, [id, phase === 'connecting', connectAttempt])
 
   // Resize terminal on dimension changes
   useEffect(() => {
@@ -202,19 +281,57 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
     return () => clearTimeout(timer)
   }, [width, height])
 
-  const handleClick = useCallback(() => {
-    if (sessionEnded) return
-    termRef.current?.focus()
-  }, [sessionEnded])
+  // Resize terminal to fill the expand container
+  useEffect(() => {
+    if (!expanded || !termRef.current || !expandContainerRef.current) return
+    const timer = setTimeout(() => {
+      const el = expandContainerRef.current
+      if (!el) return
+      const dims = calcDimensions(el.clientWidth, el.clientHeight - 40)
+      termRef.current?.resize?.(dims.cols, dims.rows)
+      if (wsRef.current?.readyState === WebSocket.OPEN) {
+        wsRef.current.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
+      }
+    }, 100)
+    return () => clearTimeout(timer)
+  }, [expanded])
 
-  const [waking, setWaking] = useState(false)
+  // Restore terminal size when collapsing
+  useEffect(() => {
+    if (expanded) return
+    if (!termRef.current) return
+    const timer = setTimeout(() => {
+      const dims = calcDimensions(width, height)
+      termRef.current?.resize?.(dims.cols, dims.rows)
+      if (wsRef.current?.readyState === WebSocket.OPEN) {
+        wsRef.current.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
+      }
+    }, 100)
+    return () => clearTimeout(timer)
+  }, [expanded, width, height])
+
+  // Reparent terminal DOM node between inline and expand
+  useEffect(() => {
+    const xtermEl = containerRef.current
+    if (!xtermEl) return
+    if (expanded && expandContainerRef.current) {
+      expandContainerRef.current.appendChild(xtermEl)
+    } else if (!expanded && terminalRef.current) {
+      terminalRef.current.appendChild(xtermEl)
+    }
+  }, [expanded])
+
+  const handleClick = useCallback(() => {
+    if (phase === 'ended') return
+    if (phase === 'live') termRef.current?.focus()
+  }, [phase])
 
   const handleStartSession = useCallback(() => {
     setWaking(true)
     setTimeout(() => {
       setWaking(false)
-      setSessionEnded(false)
-      setError(null)
+      setErrorMsg(null)
+      setPhase('connecting')
       setConnectAttempt(c => c + 1)
     }, 1500)
   }, [])
@@ -222,8 +339,13 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
   // Show interact gate when session is ready but not interacting
 
   const titleLabel = `terminal · ${prettyName || '...'}`
+  const connectedEmbed = expanded ? findConnectedEmbed(id) : null
+  const embedUrl = expanded ? buildEmbedUrl(connectedEmbed) : null
+  const hasSplit = Boolean(embedUrl)
+  const isDormant = phase === 'dormant'
 
   return (
+    <>
     <div className={styles.container}>
       <div className={styles.titleBar}>{titleLabel}</div>
       <div
@@ -235,13 +357,51 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
         }}
         onClick={handleClick}
       >
-        {error && !sessionEnded && (
+        {phase === 'error' && (
           <div className={styles.error}>
-            <span>⚠ {error}</span>
+            <span>⚠ {errorMsg}</span>
+          </div>
+        )}
+        {!expanded && <div ref={containerRef} className={styles.xtermContainer} />}
+
+        {/* Dormant: not yet activated */}
+        {isDormant && (
+          <div
+            className={overlayStyles.interactOverlay}
+            style={{ backgroundColor: '#0d1117' }}
+            onClick={(e) => {
+              if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+              enterInteractive()
+            }}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => { if (e.key === 'Enter') enterInteractive() }}
+            aria-label="Click to interact"
+          >
+            <span className={overlayStyles.interactHint}>Click to interact</span>
+          </div>
+        )}
+
+        {/* Live but not interactive: gated overlay */}
+        {phase === 'live' && !interactive && (
+          <div
+            className={overlayStyles.interactOverlay}
+            style={{ backgroundColor: 'transparent' }}
+            onClick={(e) => {
+              if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+              enterInteractive()
+            }}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => { if (e.key === 'Enter') enterInteractive() }}
+            aria-label="Click to interact"
+          >
+            <span className={overlayStyles.interactHint}>Click to interact</span>
           </div>
         )}
-        <div ref={containerRef} className={styles.xtermContainer} />
-        {sessionEnded && (
+
+        {/* Session ended */}
+        {phase === 'ended' && (
           <div
             className={overlayStyles.interactOverlay}
             style={{ backgroundColor: '#0d1117', flexDirection: 'column', gap: 0 }}
@@ -263,7 +423,9 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
             </span>
           </div>
         )}
-        {!ready && !error && !sessionEnded && (
+
+        {/* Connecting */}
+        {phase === 'connecting' && (
           <div className={styles.loading}>Connecting…</div>
         )}
       </div>
@@ -276,5 +438,34 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
         />
       )}
     </div>
+    {createPortal(
+      <div
+        className={styles.expandBackdrop}
+        style={expanded ? undefined : { display: 'none' }}
+        onPointerDown={(e) => e.stopPropagation()}
+        onKeyDown={(e) => { if (e.key === 'Escape') setExpanded(false) }}
+        onWheel={(e) => e.stopPropagation()}
+      >
+        <div className={styles.expandTopBar}>
+          <span className={styles.expandTitle}>{titleLabel}</span>
+          {hasSplit && connectedEmbed && (
+            <span className={styles.expandEmbedLabel}>
+              {connectedEmbed.type === 'story' ? connectedEmbed.props?.storyId : connectedEmbed.props?.src || 'Prototype'}
+            </span>
+          )}
+          <button className={styles.expandClose} onClick={() => setExpanded(false)} aria-label="Close expanded view" autoFocus>✕</button>
+        </div>
+        <div className={`${styles.expandBody}${hasSplit ? ` ${styles.expandSplit}` : ''}`}>
+          <div ref={expandContainerRef} className={styles.expandTerminal} />
+          {hasSplit && (
+            <div className={styles.expandEmbed}>
+              <iframe src={embedUrl} className={styles.expandIframe} title="Connected embed" />
+            </div>
+          )}
+        </div>
+      </div>,
+      document.body
+    )}
+    </>
   )
-}
+})

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

@@ -156,3 +156,108 @@
     transform: translateY(-24px);
   }
 }
+
+/* Fullscreen expand */
+.expandBackdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 100000;
+  background: #0d1117;
+  display: flex;
+  flex-direction: column;
+  animation: expandFadeIn 0.15s ease;
+}
+
+@keyframes expandFadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.expandTopBar {
+  display: flex;
+  align-items: center;
+  height: 40px;
+  padding: 0 12px;
+  background: #161b22;
+  border-bottom: 1px solid #30363d;
+  flex-shrink: 0;
+}
+
+.expandTitle {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  font-size: 12px;
+  font-weight: 500;
+  color: #e6edf3;
+}
+
+.expandEmbedLabel {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  font-size: 12px;
+  color: #8b949e;
+  margin-left: auto;
+  margin-right: 12px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.expandClose {
+  all: unset;
+  cursor: pointer;
+  margin-left: auto;
+  width: 28px;
+  height: 28px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 6px;
+  color: #8b949e;
+  font-size: 14px;
+  transition: background 100ms, color 100ms;
+}
+
+.expandClose:hover {
+  background: #30363d;
+  color: #e6edf3;
+}
+
+.expandEmbedLabel + .expandClose {
+  margin-left: 0;
+}
+
+.expandBody {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+}
+
+.expandTerminal {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  background: #0d1117;
+}
+
+.expandTerminal :global(.xterm) {
+  height: 100%;
+}
+
+.expandSplit .expandTerminal {
+  flex: 1;
+  border-right: 1px solid #30363d;
+}
+
+.expandSplit .expandEmbed {
+  flex: 1;
+  min-width: 0;
+}
+
+.expandEmbed {
+  display: flex;
+}
+
+.expandIframe {
+  border: none;
+  width: 100%;
+  height: 100%;
+}

package/src/canvas/widgets/useEmbedController.jsx

@@ -0,0 +1,223 @@
+/**
+ * Embed Controller — manages iframe lifecycle for canvas embed widgets.
+ *
+ * Behaviors:
+ * - Performance mode (per-canvas setting): embeds don't render until clicked
+ * - Viewport threshold: if >7 embeds visible, none render (zoom in to reduce)
+ * - Viewport exit: embeds deactivate 5s after leaving the viewport
+ *
+ * Usage:
+ *   <EmbedControllerProvider performanceMode={bool} scrollRef={ref}>
+ *     <StoryWidget ... />
+ *   </EmbedControllerProvider>
+ *
+ *   // Inside a widget:
+ *   const { active, activate } = useEmbedActive(widgetId, containerRef)
+ */
+import { createContext, useContext, useCallback, useEffect, useRef, useSyncExternalStore } from 'react'
+
+const DEACTIVATE_DELAY = 5000
+const MAX_VISIBLE_EMBEDS = 7
+
+// ── Shared state (module-level, one per page) ──────────────────────────
+
+let performanceMode = false
+let visibleEmbedIds = new Set()
+let activeEmbedIds = new Set()
+let manuallyActivatedIds = new Set()
+let listeners = new Set()
+
+function notify() {
+  for (const fn of listeners) fn()
+}
+
+function subscribe(fn) {
+  listeners.add(fn)
+  return () => listeners.delete(fn)
+}
+
+function setPerformanceMode(value) {
+  performanceMode = value
+  if (value) {
+    // Entering perf mode: deactivate all non-manually-activated embeds
+    activeEmbedIds = new Set(manuallyActivatedIds)
+  }
+  notify()
+}
+
+function getPerformanceMode() {
+  return performanceMode
+}
+
+function registerEmbed(id) {
+  // In normal mode with few embeds, auto-activate
+  if (!performanceMode && visibleEmbedIds.size <= MAX_VISIBLE_EMBEDS) {
+    activeEmbedIds.add(id)
+  }
+  notify()
+}
+
+function unregisterEmbed(id) {
+  visibleEmbedIds.delete(id)
+  activeEmbedIds.delete(id)
+  manuallyActivatedIds.delete(id)
+  notify()
+}
+
+function markVisible(id) {
+  visibleEmbedIds.add(id)
+  // Auto-activate if not in perf mode and under threshold
+  if (!performanceMode && visibleEmbedIds.size <= MAX_VISIBLE_EMBEDS) {
+    activeEmbedIds.add(id)
+  }
+  // If was manually activated, keep it active
+  if (manuallyActivatedIds.has(id)) {
+    activeEmbedIds.add(id)
+  }
+  notify()
+}
+
+function markHidden(id) {
+  visibleEmbedIds.delete(id)
+  // Check if other embeds should now activate (dropped below threshold)
+  if (!performanceMode && visibleEmbedIds.size <= MAX_VISIBLE_EMBEDS) {
+    for (const vid of visibleEmbedIds) {
+      activeEmbedIds.add(vid)
+    }
+  }
+  notify()
+}
+
+function deactivateEmbed(id) {
+  activeEmbedIds.delete(id)
+  manuallyActivatedIds.delete(id)
+  notify()
+}
+
+function activateEmbed(id) {
+  activeEmbedIds.add(id)
+  manuallyActivatedIds.add(id)
+  notify()
+}
+
+function isActive(id) {
+  return activeEmbedIds.has(id)
+}
+
+function isTooManyVisible() {
+  return visibleEmbedIds.size > MAX_VISIBLE_EMBEDS
+}
+
+// ── React context ──────────────────────────────────────────────────────
+
+const EmbedControllerContext = createContext(null)
+
+export function EmbedControllerProvider({ performanceMode: perfModeProp, scrollRef, children }) {
+  // Sync prop to module state
+  useEffect(() => {
+    setPerformanceMode(perfModeProp)
+  }, [perfModeProp])
+
+  // Reset on unmount
+  useEffect(() => {
+    return () => {
+      visibleEmbedIds = new Set()
+      activeEmbedIds = new Set()
+      manuallyActivatedIds = new Set()
+      performanceMode = false
+      notify()
+    }
+  }, [])
+
+  return (
+    <EmbedControllerContext.Provider value={scrollRef}>
+      {children}
+    </EmbedControllerContext.Provider>
+  )
+}
+
+/**
+ * Hook for embed widgets. Returns { active, activate, performanceMode, tooMany }.
+ * - active: whether the iframe should be rendered
+ * - activate: call to manually activate (user clicked)
+ * - performanceMode: whether perf mode is on
+ * - tooMany: whether there are too many visible embeds
+ */
+export function useEmbedActive(widgetId, containerRef) {
+  const scrollRef = useContext(EmbedControllerContext)
+  const deactivateTimerRef = useRef(null)
+
+  // Subscribe to state changes
+  const snapshot = useSyncExternalStore(subscribe, () => ({
+    active: isActive(widgetId),
+    performanceMode: getPerformanceMode(),
+    tooMany: isTooManyVisible(),
+  }), () => ({
+    active: false,
+    performanceMode: false,
+    tooMany: false,
+  }))
+
+  // Need a stable reference check since useSyncExternalStore compares by reference
+  const activeRef = useRef(false)
+  const perfRef = useRef(false)
+  const tooManyRef = useRef(false)
+
+  const active = isActive(widgetId)
+  const perf = getPerformanceMode()
+  const tooMany = isTooManyVisible()
+
+  if (activeRef.current !== active || perfRef.current !== perf || tooManyRef.current !== tooMany) {
+    activeRef.current = active
+    perfRef.current = perf
+    tooManyRef.current = tooMany
+  }
+
+  // Register/unregister
+  useEffect(() => {
+    registerEmbed(widgetId)
+    return () => {
+      unregisterEmbed(widgetId)
+      if (deactivateTimerRef.current) clearTimeout(deactivateTimerRef.current)
+    }
+  }, [widgetId])
+
+  // IntersectionObserver for viewport tracking
+  useEffect(() => {
+    const el = containerRef?.current
+    if (!el) return
+
+    const root = scrollRef?.current || null
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          // Entered viewport
+          if (deactivateTimerRef.current) {
+            clearTimeout(deactivateTimerRef.current)
+            deactivateTimerRef.current = null
+          }
+          markVisible(widgetId)
+        } else {
+          // Left viewport — start deactivation timer
+          markHidden(widgetId)
+          if (deactivateTimerRef.current) clearTimeout(deactivateTimerRef.current)
+          deactivateTimerRef.current = setTimeout(() => {
+            deactivateEmbed(widgetId)
+            deactivateTimerRef.current = null
+          }, DEACTIVATE_DELAY)
+        }
+      },
+      { root, threshold: 0 }
+    )
+
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [widgetId, containerRef, scrollRef])
+
+  const activate = useCallback(() => {
+    activateEmbed(widgetId)
+  }, [widgetId])
+
+  return { active, activate, performanceMode: perf, tooMany }
+}