@dfosco/storyboard-react 4.2.0-beta.1 → 4.2.0-beta.18

package/src/canvas/widgets/TerminalWidget.jsx

@@ -1,53 +1,122 @@
-import { useRef, useEffect, useCallback, useState } from 'react'
+import { useRef, useEffect, useCallback, useState, useMemo, forwardRef, useImperativeHandle } from 'react'
 import { readProp } from './widgetProps.js'
 import { schemas } from './widgetProps.js'
-import { getTerminalConfig } from '@dfosco/storyboard-core'
-import ResizeHandle from './ResizeHandle.jsx'
+import { getTerminalConfig, getTerminalDimensions, getStoryData } from '@dfosco/storyboard-core'
+import { useOverride } from '../../hooks/useOverride.js'
+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'
 
 const terminalSchema = schemas['terminal']
 
-/**
- * Lazy-load ghostty-web to avoid bundling WASM in prod.
- */
 let ghosttyPromise = null
 function loadGhostty() {
   if (!ghosttyPromise) {
-    ghosttyPromise = import('ghostty-web').then(async (mod) => {
-      if (mod.init) await mod.init()
-      return mod
-    })
+    ghosttyPromise = import('ghostty-web')
+      .then(async (mod) => {
+        if (mod.init) await mod.init()
+        return mod
+      })
+      .catch((err) => {
+        ghosttyPromise = null
+        console.warn('[TerminalWidget] ghostty-web not available:', err.message)
+        return null
+      })
   }
   return ghosttyPromise
 }
 
-/**
- * Build the WebSocket URL for the terminal backend.
- * Includes the base path (e.g. /branch--4.2.0/) so the proxy routes correctly.
- * Passes canvasId as a query parameter for session scoping.
- */
-function getWsUrl(sessionId, prettyName) {
+// 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) || '/'
   const baseClean = base.endsWith('/') ? base : base + '/'
   const canvasId = window.__storyboardCanvasBridgeState?.canvasId || 'unknown'
   let url = `${protocol}//${location.host}${baseClean}_storyboard/terminal/${sessionId}?canvas=${encodeURIComponent(canvasId)}`
   if (prettyName) url += `&name=${encodeURIComponent(prettyName)}`
+  if (startupCommand) url += `&startupCommand=${encodeURIComponent(startupCommand)}`
   return url
 }
 
+function calcDimensions(widthPx, heightPx, fontSize = 13) {
+  // Cell dimensions scale proportionally with font size.
+  // Base measurements at 13px: ~7.8px wide, ~17px tall.
+  const scale = fontSize / 13
+  const cellWidth = 7.8 * scale
+  const cellHeight = 17 * scale
+  // .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 }
+}
+
 /**
- * Calculate terminal cols/rows from pixel dimensions.
+ * 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 calcDimensions(widthPx, heightPx) {
-  // Approximate character cell size for 13px monospace
-  const cellWidth = 7.8
-  const cellHeight = 17
-  const padding = 24 // 12px each side
-  const cols = Math.max(10, Math.floor((widthPx - padding) / cellWidth))
-  const rows = Math.max(4, Math.floor((heightPx - padding) / cellHeight))
-  return { cols, rows }
+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) {
+  const bridge = window.__storyboardCanvasBridgeState
+  if (!bridge?.connectors || !bridge?.widgets) return null
+  const connectedIds = new Set()
+  for (const c of bridge.connectors) {
+    if (c.start?.widgetId === widgetId) connectedIds.add(c.end?.widgetId)
+    if (c.end?.widgetId === widgetId) connectedIds.add(c.start?.widgetId)
+  }
+  for (const w of bridge.widgets) {
+    if (connectedIds.has(w.id) && EMBED_TYPES.has(w.type)) return w
+  }
+  return null
+}
+
+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 = getStoryData(storyId)
+    if (storyData?._route) {
+      const route = exportName ? `${storyData._route}?export=${exportName}` : storyData._route
+      return `${baseClean}${route}`
+    }
+    return null
+  }
+  return null
 }
 
 const DEFAULT_THEME = {
@@ -73,25 +142,88 @@ const DEFAULT_THEME = {
   brightWhite: '#f0f6fc',
 }
 
-export default function TerminalWidget({ id, props, onUpdate, resizable }) {
-  const width = readProp(props, 'width', terminalSchema)
-  const height = readProp(props, 'height', terminalSchema)
+export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizable, multiSelected }, ref) {
+  const cfg = getTerminalConfig()
+  const fontSize = cfg.fontSize ?? 13
+  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 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') { 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, props, onUpdate])
 
-  const handleResize = useCallback((w, h) => {
-    onUpdate?.({ width: w, height: h })
-  }, [onUpdate])
+  // 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])
 
-  // Initialize terminal
+  // Exit interactive when terminal becomes part of a multi-selection
+  useEffect(() => {
+    if (multiSelected && interactive) setInteractive(false)
+  }, [multiSelected])
+
+  // Connect terminal + WebSocket
   useEffect(() => {
     if (!containerRef.current) return
 
@@ -103,8 +235,12 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
       try {
         const ghostty = await loadGhostty()
         if (disposed) return
+        if (!ghostty) {
+          setError('ghostty-web not installed — add it to your dependencies to enable terminal widgets')
+          return
+        }
 
-        const dims = calcDimensions(width, height)
+        const dims = calcDimensions(width, height, fontSize)
         const cfg = getTerminalConfig()
 
         term = new ghostty.Terminal({
@@ -120,8 +256,44 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
         term.open(containerRef.current)
         termRef.current = term
 
-        // Connect WebSocket
-        const url = getWsUrl(id, prettyName)
+        // 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
+          const sock = wsRef.current
+          if (!sock || sock.readyState !== WebSocket.OPEN) return true
+          const btn = e.deltaY < 0 ? 64 : 65
+          const lines = Math.max(1, Math.min(5, Math.ceil(Math.abs(e.deltaY) / 33)))
+          for (let i = 0; i < lines; i++) {
+            sock.send(`\x1b[<${btn};1;1M`)
+            sock.send(`\x1b[<${btn};1;1m`)
+          }
+          return true
+        })
+
+        const url = getWsUrl(id, prettyName, startupCommand)
         ws = new WebSocket(url)
         wsRef.current = ws
 
@@ -134,17 +306,16 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
         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
+              if (msg.type === 'resource-limited') {
+                setResourceLimited(msg)
+                setSessionEnded(true)
                 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))
         }
@@ -161,12 +332,12 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
           setSessionEnded(true)
         }
 
-        // Terminal input → WebSocket
         term.onData((data) => {
-          if (ws.readyState === WebSocket.OPEN) {
-            ws.send(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')
       }
@@ -176,6 +347,7 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
 
     return () => {
       disposed = true
+      terminalRegistry.delete(id)
       if (ws && ws.readyState <= WebSocket.OPEN) ws.close()
       if (term) term.dispose()
       termRef.current = null
@@ -187,8 +359,22 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
   useEffect(() => {
     if (!termRef.current) return
     const timer = setTimeout(() => {
-      const dims = calcDimensions(width, height)
+      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 }))
       }
@@ -196,49 +382,221 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
     return () => clearTimeout(timer)
   }, [width, height])
 
+  // Reveal mask — hide terminal for 750ms after ready to mask startup flash
+  useEffect(() => {
+    if (!ready) {
+      setRevealed(false)
+      return
+    }
+    const timer = setTimeout(() => {
+      setRevealed(true)
+      setInteractive(true)
+    }, 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
+  useEffect(() => {
+    if (expanded || !termRef.current) return
+    const timer = setTimeout(() => {
+      const dims = calcDimensions(width, height, 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 }))
+      }
+    }, 100)
+    return () => clearTimeout(timer)
+  }, [expanded, width, height])
+
+  // Focus terminal on expand
+  useEffect(() => {
+    if (expanded && expandContainerRef.current) {
+      fitTerminalToElement(id, expandContainerRef.current)
+    }
+  }, [expanded])
+
   const handleClick = useCallback(() => {
-    if (sessionEnded) return
-    termRef.current?.focus()
-  }, [sessionEnded])
+    if (sessionEnded || multiSelected) return
+    if (revealed) {
+      setInteractive(true)
+      const scrollEl = terminalRef.current?.closest('[class*="canvasScroll"]')
+      const scrollTop = scrollEl?.scrollTop
+      const scrollLeft = scrollEl?.scrollLeft
+      termRef.current?.focus({ preventScroll: true })
+      if (scrollEl && (scrollEl.scrollTop !== scrollTop || scrollEl.scrollLeft !== scrollLeft)) {
+        scrollEl.scrollTop = scrollTop
+        scrollEl.scrollLeft = scrollLeft
+      }
+    }
+  }, [sessionEnded, multiSelected, revealed])
 
-  const [waking, setWaking] = useState(false)
+  const handleTerminalPointerDown = useCallback((e) => {
+    if (!interactive) return
+    if (e.target.closest('.tc-drag-handle')) return
+    e.stopPropagation()
+    const startX = e.clientX
+    const startY = e.clientY
+    let moved = false
+    function onMove(me) {
+      if (!moved && (Math.abs(me.clientX - startX) > 5 || Math.abs(me.clientY - startY) > 5)) {
+        moved = true
+        setShowDragHint(true)
+        clearTimeout(dragHintTimer.current)
+        dragHintTimer.current = setTimeout(() => setShowDragHint(false), 2000)
+      }
+    }
+    function onUp() {
+      document.removeEventListener('pointermove', onMove)
+      document.removeEventListener('pointerup', onUp)
+    }
+    document.addEventListener('pointermove', onMove)
+    document.addEventListener('pointerup', onUp)
+  }, [interactive])
 
   const handleStartSession = useCallback(() => {
     setWaking(true)
     setTimeout(() => {
       setWaking(false)
       setSessionEnded(false)
+      setResourceLimited(null)
       setError(null)
       setConnectAttempt(c => c + 1)
     }, 1500)
   }, [])
 
-  // Show interact gate when session is ready but not interacting
+  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 titleLabel = `terminal · ${prettyName || '...'}`
 
   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}
+        onKeyDown={interactive ? (e) => e.stopPropagation() : undefined}
       >
+        {showDragHint && (
+          <div className={styles.dragHint}>
+            <span className={styles.dragHintArrow}>←</span> Drag here to move widget
+          </div>
+        )}
         {error && !sessionEnded && (
           <div className={styles.error}>
             <span>⚠ {error}</span>
           </div>
         )}
-        <div ref={containerRef} className={styles.xtermContainer} />
-        {sessionEnded && (
+        <div ref={containerRef} className={styles.xtermContainer} style={{ opacity: revealed ? 1 : 0 }} />
+
+        {/* Live but not interactive */}
+        {revealed && !interactive && !sessionEnded && (
           <div
             className={overlayStyles.interactOverlay}
-            style={{ backgroundColor: '#0d1117', flexDirection: 'column', gap: 0 }}
+            style={{ backgroundColor: 'transparent' }}
+            onClick={(e) => {
+              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 (!multiSelected && e.key === 'Enter') { setInteractive(true); termRef.current?.focus({ preventScroll: true }) } }}
+            aria-label="Click to interact"
+          >
+            {!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 — normal (zzz) */}
+        {sessionEnded && !resourceLimited && (
+          <div
+            className={overlayStyles.interactOverlay}
+            style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: 0 }}
             onClick={handleStartSession}
             role="button"
             tabIndex={0}
@@ -253,22 +611,91 @@ export default function TerminalWidget({ id, props, onUpdate, resizable }) {
               </div>
             )}
             <span className={overlayStyles.interactHint}>
-              {waking ? 'Waking up...' : 'Start terminal session'}
+              {waking ? 'Waking up...' : connectAttempt > 0 ? 'Continue terminal session' : 'Start terminal session'}
             </span>
           </div>
         )}
-        {!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>
+    {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}
+    />
   )
 }