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

package/src/canvas/widgets/TerminalWidget.jsx

@@ -1,13 +1,10 @@
 import { useRef, useEffect, useCallback, useState, useMemo, 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'
-import { ScreenNormalIcon } from '@primer/octicons-react'
+import { getTerminalConfig, getTerminalDimensions, getStoryData } from '@dfosco/storyboard-core'
 import { useOverride } from '../../hooks/useOverride.js'
-import { getSplitPaneLabel, findConnectedSplitTarget, buildSecondaryIframeUrl as buildSplitUrl, getPaneOrder } from './expandUtils.js'
-import SplitScreenTopBar from './SplitScreenTopBar.jsx'
-import ResizeHandle from './ResizeHandle.jsx'
+import { getSplitPaneLabel, findAllConnectedSplitTargets, buildPaneForWidget, buildSplitLayout } from './expandUtils.js'
+import ExpandedPane from './ExpandedPane.jsx'
 import styles from './TerminalWidget.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
@@ -30,6 +27,10 @@ function loadGhostty() {
   return ghosttyPromise
 }
 
+// Global registry so split-screen can look up any terminal's ghostty + WS by widget ID
+const terminalRegistry = new Map()
+if (typeof window !== 'undefined') window.__storyboardTerminalRegistry = terminalRegistry
+
 function getWsUrl(sessionId, prettyName, startupCommand) {
   const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
   const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
@@ -47,12 +48,37 @@ function calcDimensions(widthPx, heightPx, fontSize = 13) {
   const scale = fontSize / 13
   const cellWidth = 7.8 * scale
   const cellHeight = 17 * scale
-  const padding = 24
-  const cols = Math.max(10, Math.floor((widthPx - padding) / cellWidth))
-  const rows = Math.max(4, Math.floor((heightPx - padding) / cellHeight))
+  // .terminal has 16px padding + 1px border on each side (box-sizing: border-box)
+  const hPad = 34 // (16+1) * 2
+  const vPad = 34
+  const cols = Math.max(10, Math.floor((widthPx - hPad) / cellWidth))
+  const rows = Math.max(4, Math.floor((heightPx - vPad) / cellHeight))
   return { cols, rows }
 }
 
+/**
+ * Fit a terminal (by widget ID) to a container element using real cell metrics.
+ * Works for both the primary and secondary terminal in split-screen.
+ */
+function fitTerminalToElement(widgetId, containerEl) {
+  const entry = terminalRegistry.get(widgetId)
+  if (!entry || !containerEl) return
+  const { term, ws } = entry
+  const cw = term.renderer?.charWidth
+  const ch = term.renderer?.charHeight
+  if (!cw || !ch) return
+  const w = containerEl.clientWidth
+  const h = containerEl.clientHeight
+  // Skip if container hasn't laid out yet (flex: 1 may not have resolved)
+  if (w < 50 || h < 50) return
+  const cols = Math.max(10, Math.floor(w / cw))
+  const rows = Math.max(4, Math.floor(h / ch))
+  term.resize?.(cols, rows)
+  if (ws?.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ type: 'resize', cols, rows }))
+  }
+}
+
 const EMBED_TYPES = new Set(['prototype', 'story'])
 
 function findConnectedEmbed(widgetId) {
@@ -83,7 +109,7 @@ function buildEmbedUrl(widget) {
     const storyId = widget.props?.storyId
     const exportName = widget.props?.exportName
     if (!storyId) return null
-    const storyData = typeof window !== 'undefined' && window.__storyboardStoryIndex?.[storyId]
+    const storyData = getStoryData(storyId)
     if (storyData?._route) {
       const route = exportName ? `${storyData._route}?export=${exportName}` : storyData._route
       return `${baseClean}${route}`
@@ -116,40 +142,67 @@ const DEFAULT_THEME = {
   brightWhite: '#f0f6fc',
 }
 
-export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizable }, ref) {
+export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizable, multiSelected }, ref) {
   const cfg = getTerminalConfig()
   const fontSize = cfg.fontSize ?? 13
-  const width = props?.width ?? cfg.defaultWidth ?? readProp(props, 'width', terminalSchema)
-  const height = props?.height ?? cfg.defaultHeight ?? readProp(props, 'height', terminalSchema)
+  const agentId = props?.agentId || null
+  const dims = getTerminalDimensions(agentId, {
+    width: readProp(props, 'width', terminalSchema),
+    height: readProp(props, 'height', terminalSchema),
+  })
+  const rawWidth = props?.width ?? dims.width
+  const rawHeight = props?.height ?? dims.height
   const prettyName = props?.prettyName || null
   const startupCommand = props?.startupCommand || null
 
+  // Snap dimensions to cell grid so the terminal fills its container exactly
+  const { cols, rows } = useMemo(
+    () => calcDimensions(rawWidth, rawHeight, fontSize),
+    [rawWidth, rawHeight, fontSize],
+  )
+  const width = rawWidth
+  const height = rawHeight
+  // Snapped dimensions computed from ghostty's actual cell metrics (set after open)
+  const [snappedHeight, setSnappedHeight] = useState(null)
+  const [snappedWidth, setSnappedWidth] = useState(null)
+
   const containerRef = useRef(null)
   const termRef = useRef(null)
   const terminalRef = useRef(null)
   const wsRef = useRef(null)
 
   const [ready, setReady] = useState(false)
+  const [revealed, setRevealed] = useState(false)
   const [error, setError] = useState(null)
   const [sessionEnded, setSessionEnded] = useState(false)
   const [connectAttempt, setConnectAttempt] = useState(0)
   const [interactive, setInteractive] = useState(false)
   const [expandedOverride, setExpandedOverride, clearExpandedOverride] = useOverride(`_terminal_expanded_${id}`)
-  const expanded = expandedOverride === 'true'
-  const setExpanded = useCallback((val) => {
-    if (val) setExpandedOverride('true')
+  const expandMode = expandedOverride === 'single' || expandedOverride === 'split' ? expandedOverride : expandedOverride === 'true' ? 'split' : null
+  const expanded = expandMode !== null
+  const setExpanded = useCallback((mode) => {
+    if (mode) setExpandedOverride(mode)
     else clearExpandedOverride()
   }, [setExpandedOverride, clearExpandedOverride])
   const [waking, setWaking] = useState(false)
+  const [resourceLimited, setResourceLimited] = useState(null)
   const [showDragHint, setShowDragHint] = useState(false)
   const expandContainerRef = useRef(null)
   const dragHintTimer = useRef(null)
 
   useImperativeHandle(ref, () => ({
     handleAction(actionId) {
-      if (actionId === 'expand' || actionId === 'split-screen') setExpanded(true)
+      if (actionId === 'expand') { setExpanded('single'); return true }
+      if (actionId === 'expand-single') { setExpanded('single'); return true }
+      if (actionId === 'split-screen') { setExpanded('split'); return true }
+      if (actionId === 'toggle-private') {
+        const isPrivate = !!props?.private
+        onUpdate?.({ private: !isPrivate })
+        return true
+      }
+      return false
     },
-  }), [setExpanded])
+  }), [setExpanded, props, onUpdate])
 
   // Exit interactive on click outside
   useEffect(() => {
@@ -165,9 +218,10 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     return () => document.removeEventListener('pointerdown', handlePointerDown)
   }, [interactive, id])
 
-  const handleResize = useCallback((w, h) => {
-    onUpdate?.({ width: w, height: h })
-  }, [onUpdate])
+  // Exit interactive when terminal becomes part of a multi-selection
+  useEffect(() => {
+    if (multiSelected && interactive) setInteractive(false)
+  }, [multiSelected])
 
   // Connect terminal + WebSocket
   useEffect(() => {
@@ -202,6 +256,29 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
         term.open(containerRef.current)
         termRef.current = term
 
+        // Expose ghostty's actual computed cell metrics as CSS variables
+        // Set on .terminal (terminalRef) so they cascade into .xtermContainer
+        const cw = term.renderer?.charWidth
+        const ch = term.renderer?.charHeight
+        const wrap = terminalRef.current
+        if (wrap && cw) wrap.style.setProperty('--term-char-width', `${cw}px`)
+        if (wrap && ch) wrap.style.setProperty('--term-char-height', `${ch}px`)
+        if (wrap) {
+          wrap.style.setProperty('--term-cols', dims.cols)
+          wrap.style.setProperty('--term-rows', dims.rows)
+          wrap.style.setProperty('--term-font-size', `${cfg.fontSize ?? 13}px`)
+          const theme = { ...DEFAULT_THEME, ...cfg.theme }
+          wrap.style.setProperty('--term-bg', theme.background)
+        }
+
+        // Snap container to exact cell grid using real metrics
+        // .terminal has 16px padding + 1px border on each side = 34px chrome per axis
+        if (!disposed) {
+          const pad = 34
+          if (ch) setSnappedHeight(Math.round(dims.rows * ch) + pad)
+          if (cw) setSnappedWidth(Math.round(dims.cols * cw) + pad)
+        }
+
         // SGR mouse wheel for tmux scroll in alternate screen
         term.attachCustomWheelEventHandler((e) => {
           if (!(term.wasmTerm?.isAlternateScreen?.() ?? false)) return false
@@ -223,7 +300,6 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
         ws.onopen = () => {
           if (disposed) return
           setReady(true)
-          setInteractive(true)
           ws.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
         }
 
@@ -233,6 +309,11 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
           if (data && data.startsWith('{')) {
             try {
               const msg = JSON.parse(data)
+              if (msg.type === 'resource-limited') {
+                setResourceLimited(msg)
+                setSessionEnded(true)
+                return
+              }
               if (msg.type === 'session-info' || msg.type === 'conflict' || msg.type === 'detached') return
             } catch { /* not JSON */ }
           }
@@ -254,6 +335,9 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
         term.onData((data) => {
           if (ws.readyState === WebSocket.OPEN) ws.send(data)
         })
+
+        // Register in global registry for split-screen access
+        terminalRegistry.set(id, { term, ws })
       } catch (err) {
         if (!disposed) setError(err.message || 'Failed to load terminal')
       }
@@ -263,6 +347,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
 
     return () => {
       disposed = true
+      terminalRegistry.delete(id)
       if (ws && ws.readyState <= WebSocket.OPEN) ws.close()
       if (term) term.dispose()
       termRef.current = null
@@ -276,6 +361,20 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     const timer = setTimeout(() => {
       const dims = calcDimensions(width, height, fontSize)
       termRef.current?.resize?.(dims.cols, dims.rows)
+      // Update CSS variables after resize
+      const wrap = terminalRef.current
+      const cw = termRef.current?.renderer?.charWidth
+      const ch = termRef.current?.renderer?.charHeight
+      if (wrap && cw) wrap.style.setProperty('--term-char-width', `${cw}px`)
+      if (wrap && ch) wrap.style.setProperty('--term-char-height', `${ch}px`)
+      if (wrap) {
+        wrap.style.setProperty('--term-cols', dims.cols)
+        wrap.style.setProperty('--term-rows', dims.rows)
+      }
+      // Re-snap to cell grid
+      const pad = 34
+      if (ch) setSnappedHeight(Math.round(dims.rows * ch) + pad)
+      if (cw) setSnappedWidth(Math.round(dims.cols * cw) + pad)
       if (wsRef.current?.readyState === WebSocket.OPEN) {
         wsRef.current.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
       }
@@ -283,21 +382,32 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     return () => clearTimeout(timer)
   }, [width, height])
 
-  // Resize for expand
+  // Reveal mask — hide terminal for 750ms after ready to mask startup flash
   useEffect(() => {
-    if (!expanded || !termRef.current || !expandContainerRef.current) return
+    if (!ready) {
+      setRevealed(false)
+      return
+    }
     const timer = setTimeout(() => {
-      const el = expandContainerRef.current
-      if (!el) return
-      const dims = calcDimensions(el.clientWidth, el.clientHeight - 40, fontSize)
-      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 }))
-      }
+      setRevealed(true)
       setInteractive(true)
-      termRef.current?.focus?.()
-    }, 100)
+    }, 750)
     return () => clearTimeout(timer)
+  }, [ready])
+
+  const isAgent = id.startsWith('agent-')
+  const typeLabel = isAgent ? 'Agent' : 'Terminal'
+  const titleLabel = `${typeLabel} · ${prettyName || '…'}`
+
+  // Reparent terminal DOM between inline and expand container
+  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])
 
   // Restore size on collapse
@@ -313,20 +423,16 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     return () => clearTimeout(timer)
   }, [expanded, width, height])
 
-  // Reparent terminal DOM between inline and expand
+  // Focus terminal on 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)
+      fitTerminalToElement(id, expandContainerRef.current)
     }
   }, [expanded])
 
   const handleClick = useCallback(() => {
-    if (sessionEnded) return
-    if (ready) {
+    if (sessionEnded || multiSelected) return
+    if (revealed) {
       setInteractive(true)
       const scrollEl = terminalRef.current?.closest('[class*="canvasScroll"]')
       const scrollTop = scrollEl?.scrollTop
@@ -337,7 +443,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
         scrollEl.scrollLeft = scrollLeft
       }
     }
-  }, [sessionEnded, ready])
+  }, [sessionEnded, multiSelected, revealed])
 
   const handleTerminalPointerDown = useCallback((e) => {
     if (!interactive) return
@@ -367,37 +473,50 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     setTimeout(() => {
       setWaking(false)
       setSessionEnded(false)
+      setResourceLimited(null)
       setError(null)
       setConnectAttempt(c => c + 1)
     }, 1500)
   }, [])
 
-  const titleLabel = `Terminal · ${prettyName || '…'}`
-  const connectedEmbed = expanded ? findConnectedSplitTarget(id) : null
-  const embedUrl = expanded ? buildSplitUrl(connectedEmbed) : null
-  const hasSplit = Boolean(connectedEmbed)
-  const [activePane, setActivePane] = useState('left')
+  const handleCleanupAndRetry = useCallback(async () => {
+    const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
+    const baseClean = base.endsWith('/') ? base : base + '/'
+    try {
+      const res = await fetch(`${baseClean}_storyboard/terminal/sessions/cleanup`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ statuses: ['archived', 'background'] }),
+      })
+      if (res.ok) {
+        const data = await res.json()
+        if (data.removed > 0) {
+          handleStartSession()
+          return
+        }
+        // Nothing was removed — update counts from server
+        setResourceLimited(prev => prev ? {
+          ...prev,
+          cleanupResult: 'nothing-to-clean',
+          counts: data.remaining || prev.counts,
+        } : prev)
+        return
+      }
+    } catch { /* ignore fetch errors */ }
+    setResourceLimited(prev => prev ? { ...prev, cleanupResult: 'failed' } : prev)
+  }, [handleStartSession])
 
-  const paneOrder = useMemo(
-    () => (hasSplit ? getPaneOrder(id, connectedEmbed) : { primaryIsLeft: true }),
-    [hasSplit, id, connectedEmbed],
-  )
-  const primaryWidget = useMemo(() => ({ type: 'terminal', props: { prettyName } }), [prettyName])
-  const primaryLabel = useMemo(() => getSplitPaneLabel(primaryWidget), [primaryWidget])
-  const secondaryLabel = useMemo(() => getSplitPaneLabel(connectedEmbed), [connectedEmbed])
-  const leftLabel = paneOrder.primaryIsLeft ? primaryLabel : secondaryLabel
-  const rightLabel = paneOrder.primaryIsLeft ? secondaryLabel : primaryLabel
 
   return (
     <>
     <div className={styles.container}>
-      <div className={styles.titleBar}>{titleLabel}</div>
+      <div className={`tc-drag-handle ${styles.titleBar}`}>{titleLabel}</div>
       <div
         ref={terminalRef}
         className={styles.terminal}
         style={{
-          ...(typeof width === 'number' ? { width: `${width}px` } : undefined),
-          ...(typeof height === 'number' ? { height: `${height}px` } : undefined),
+          ...(typeof (snappedWidth ?? width) === 'number' ? { width: `${snappedWidth ?? width}px` } : undefined),
+          ...(typeof (snappedHeight ?? height) === 'number' ? { height: `${snappedHeight ?? height}px` } : undefined),
         }}
         onClick={handleClick}
         onPointerDown={handleTerminalPointerDown}
@@ -413,32 +532,71 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
             <span>⚠ {error}</span>
           </div>
         )}
-        <div ref={containerRef} className={styles.xtermContainer} />
+        <div ref={containerRef} className={styles.xtermContainer} style={{ opacity: revealed ? 1 : 0 }} />
 
         {/* Live but not interactive */}
-        {ready && !interactive && !sessionEnded && (
+        {revealed && !interactive && !sessionEnded && (
           <div
             className={overlayStyles.interactOverlay}
             style={{ backgroundColor: 'transparent' }}
             onClick={(e) => {
-              if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+              if (multiSelected || e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
               setInteractive(true)
               termRef.current?.focus({ preventScroll: true })
             }}
             role="button"
             tabIndex={0}
-            onKeyDown={(e) => { if (e.key === 'Enter') { setInteractive(true); termRef.current?.focus({ preventScroll: true }) } }}
+            onKeyDown={(e) => { if (!multiSelected && e.key === 'Enter') { setInteractive(true); termRef.current?.focus({ preventScroll: true }) } }}
             aria-label="Click to interact"
           >
-            <span className={overlayStyles.interactHint}>Click to interact</span>
+            {!multiSelected && <span className={overlayStyles.interactHint}>Click to interact</span>}
+          </div>
+        )}
+
+        {/* Session ended — resource limited */}
+        {sessionEnded && resourceLimited && (
+          <div
+            className={overlayStyles.interactOverlay}
+            style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: '8px', padding: '24px' }}
+          >
+            <span className={styles.resourceIcon}>⚠</span>
+            <span className={styles.resourceTitle}>No terminal devices available</span>
+            <span className={styles.resourceMessage}>
+              Too many terminal sessions are open.
+              {resourceLimited.counts && (
+                <span className={styles.resourceCounts}>
+                  {resourceLimited.counts.live} live · {resourceLimited.counts.background} background · {resourceLimited.counts.archived} archived
+                </span>
+              )}
+            </span>
+            <div className={styles.resourceActions}>
+              {!resourceLimited.cleanupResult && (resourceLimited.counts?.background > 0 || resourceLimited.counts?.archived > 0) && (
+                <button className={styles.resourceBtn} onClick={handleCleanupAndRetry}>
+                  Close background sessions
+                </button>
+              )}
+              {resourceLimited.cleanupResult === 'nothing-to-clean' && (
+                <span className={styles.resourceMuted}>
+                  All background sessions already cleaned. Close some live terminals to free resources.
+                </span>
+              )}
+              {resourceLimited.cleanupResult === 'failed' && (
+                <span className={styles.resourceMuted}>
+                  Cleanup failed — could not reach dev server.
+                </span>
+              )}
+              <button className={styles.resourceBtnSecondary} onClick={handleStartSession}>
+                Retry
+              </button>
+            </div>
           </div>
         )}
 
-        {/* Session ended */}
-        {sessionEnded && (
+        {/* Session ended — normal (zzz) */}
+        {sessionEnded && !resourceLimited && (
           <div
             className={overlayStyles.interactOverlay}
-            style={{ backgroundColor: '#0d1117', flexDirection: 'column', gap: 0 }}
+            style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: 0 }}
             onClick={handleStartSession}
             role="button"
             tabIndex={0}
@@ -458,67 +616,86 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
           </div>
         )}
 
-        {/* Connecting */}
-        {!ready && !error && !sessionEnded && (
-          <div className={styles.loading}>Connecting…</div>
+        {/* Connecting / reveal mask */}
+        {!revealed && !error && !sessionEnded && (
+          <div className={styles.loading}>
+            <div className={styles.spinner} />
+          </div>
         )}
       </div>
-      {resizable && (
-        <ResizeHandle
-          targetRef={terminalRef}
-          onResize={handleResize}
-          minWidth={300}
-          minHeight={200}
-        />
-      )}
     </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()}
-      >
-        {hasSplit ? (
-          <SplitScreenTopBar
-            leftLabel={leftLabel}
-            rightLabel={rightLabel}
-            activePane={activePane}
-            onClose={() => setExpanded(false)}
-          />
-        ) : (
-          <div className={styles.expandTopBar}>
-            <span className={styles.expandTitle}>{titleLabel}</span>
-            <button className={styles.expandClose} onClick={() => setExpanded(false)} aria-label="Close expanded view" autoFocus><ScreenNormalIcon size={16} /></button>
-          </div>
-        )}
-        <div className={`${styles.expandBody}${hasSplit ? ` ${styles.expandSplit}` : ''}`}>
-          {hasSplit ? (
-            <>
-              {paneOrder.primaryIsLeft ? (
-                <>
-                  <div ref={expandContainerRef} className={styles.expandTerminal} onPointerDown={() => setActivePane('left')} />
-                  <div className={styles.expandEmbed} onPointerDown={() => setActivePane('right')}>
-                    {embedUrl ? <iframe src={embedUrl} className={styles.expandIframe} title="Connected embed" /> : null}
-                  </div>
-                </>
-              ) : (
-                <>
-                  <div className={styles.expandEmbed} onPointerDown={() => setActivePane('left')}>
-                    {embedUrl ? <iframe src={embedUrl} className={styles.expandIframe} title="Connected embed" /> : null}
-                  </div>
-                  <div ref={expandContainerRef} className={styles.expandTerminal} onPointerDown={() => setActivePane('right')} />
-                </>
-              )}
-            </>
-          ) : (
-            <div ref={expandContainerRef} className={styles.expandTerminal} />
-          )}
-        </div>
-      </div>,
-      document.body
+    {expanded && (
+      <TerminalExpandPane
+        widgetId={id}
+        expandContainerRef={expandContainerRef}
+        prettyName={prettyName}
+        isAgent={isAgent}
+        splitMode={expandMode === 'split'}
+        onClose={() => setExpanded(null)}
+      />
     )}
     </>
   )
 })
+
+/**
+ * Builds pane configs and renders ExpandedPane for an expanded terminal widget.
+ * Primary pane is an external pane that receives the xterm container + handles fit.
+ */
+function TerminalExpandPane({ widgetId, expandContainerRef, prettyName, isAgent, splitMode, onClose }) {
+  const connectedWidgets = useMemo(
+    () => splitMode ? findAllConnectedSplitTargets(widgetId) : [],
+    [widgetId, splitMode],
+  )
+
+  const primaryWidget = useMemo(() => {
+    const bridge = window.__storyboardCanvasBridgeState
+    return bridge?.widgets?.find((w) => w.id === widgetId) || {
+      id: widgetId,
+      type: isAgent ? 'agent' : 'terminal',
+      position: { x: 0, y: 0 },
+      props: { prettyName },
+    }
+  }, [widgetId, isAgent, prettyName])
+
+  // Custom pane builder for the primary widget (external pane with terminal fit)
+  const buildPaneFn = useCallback((widget) => {
+    if (widget.id === widgetId) {
+      return {
+        id: widgetId,
+        label: getSplitPaneLabel({ type: isAgent ? 'agent' : 'terminal', props: { prettyName } }),
+        widgetType: isAgent ? 'agent' : 'terminal',
+        kind: 'external',
+        attach: (container) => {
+          expandContainerRef.current = container
+          const t1 = setTimeout(() => fitTerminalToElement(widgetId, container), 150)
+          const t2 = setTimeout(() => fitTerminalToElement(widgetId, container), 400)
+          return () => {
+            clearTimeout(t1)
+            clearTimeout(t2)
+            expandContainerRef.current = null
+          }
+        },
+        onResize: () => {
+          if (expandContainerRef.current) {
+            fitTerminalToElement(widgetId, expandContainerRef.current)
+          }
+        },
+      }
+    }
+    return buildPaneForWidget(widget)
+  }, [widgetId, prettyName, isAgent, expandContainerRef])
+
+  const layout = useMemo(
+    () => buildSplitLayout(primaryWidget, connectedWidgets, buildPaneFn),
+    [primaryWidget, connectedWidgets, buildPaneFn],
+  )
+
+  return (
+    <ExpandedPane
+      initialLayout={layout}
+      variant="full"
+      onClose={onClose}
+    />
+  )
+}