@dfosco/storyboard-react 4.2.0-alpha.15 → 4.2.0-alpha.16

package/src/canvas/widgets/TerminalWidget.jsx

@@ -3,15 +3,13 @@ import { createPortal } from 'react-dom'
 import { readProp } from './widgetProps.js'
 import { schemas } from './widgetProps.js'
 import { getTerminalConfig } from '@dfosco/storyboard-core'
+import { useOverride } from '../../hooks/useOverride.js'
 import ResizeHandle from './ResizeHandle.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) {
@@ -29,11 +27,6 @@ function loadGhostty() {
   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) {
   const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
   const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
@@ -44,14 +37,10 @@ function getWsUrl(sessionId, prettyName) {
   return url
 }
 
-/**
- * Calculate terminal cols/rows from pixel dimensions.
- */
 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 padding = 24
   const cols = Math.max(10, Math.floor((widthPx - padding) / cellWidth))
   const rows = Math.max(4, Math.floor((heightPx - padding) / cellHeight))
   return { cols, rows }
@@ -59,9 +48,6 @@ function calcDimensions(widthPx, heightPx) {
 
 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
@@ -76,9 +62,6 @@ function findConnectedEmbed(widgetId) {
   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) || '/'
@@ -136,27 +119,27 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
   const terminalRef = useRef(null)
   const wsRef = useRef(null)
 
-  // 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 [ready, setReady] = useState(false)
+  const [error, setError] = useState(null)
+  const [sessionEnded, setSessionEnded] = useState(false)
   const [connectAttempt, setConnectAttempt] = useState(0)
-  const [expanded, setExpanded] = useState(false)
+  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')
+    else clearExpandedOverride()
+  }, [setExpandedOverride, clearExpandedOverride])
   const [waking, setWaking] = useState(false)
+  const [showDragHint, setShowDragHint] = useState(false)
   const expandContainerRef = useRef(null)
+  const dragHintTimer = 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])
+  useImperativeHandle(ref, () => ({
+    handleAction(actionId) {
+      if (actionId === 'expand') setExpanded(true)
+    },
+  }), [setExpanded])
 
   // Exit interactive on click outside
   useEffect(() => {
@@ -172,22 +155,13 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     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])
 
-  // Connect terminal + WebSocket only when phase is 'connecting'
+  // Connect terminal + WebSocket
   useEffect(() => {
-    if (phase !== 'connecting' || !containerRef.current) return
+    if (!containerRef.current) return
 
     let disposed = false
     let term = null
@@ -196,7 +170,11 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     async function setup() {
       try {
         const ghostty = await loadGhostty()
-        if (disposed || !ghostty) return
+        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 cfg = getTerminalConfig()
@@ -214,13 +192,28 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
         term.open(containerRef.current)
         termRef.current = term
 
+        // 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)
         ws = new WebSocket(url)
         wsRef.current = ws
 
         ws.onopen = () => {
           if (disposed) return
-          setPhase('live')
+          setReady(true)
+          setInteractive(true)
           ws.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
         }
 
@@ -238,22 +231,21 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
 
         ws.onclose = () => {
           if (disposed) return
-          setPhase('ended')
+          setReady(false)
+          setSessionEnded(true)
         }
 
         ws.onerror = () => {
           if (disposed) return
-          setPhase('ended')
+          setReady(false)
+          setSessionEnded(true)
         }
 
         term.onData((data) => {
           if (ws.readyState === WebSocket.OPEN) ws.send(data)
         })
       } catch (err) {
-        if (!disposed) {
-          setErrorMsg(err.message || 'Failed to load terminal')
-          setPhase('error')
-        }
+        if (!disposed) setError(err.message || 'Failed to load terminal')
       }
     }
 
@@ -266,7 +258,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
       termRef.current = null
       wsRef.current = null
     }
-  }, [id, phase === 'connecting', connectAttempt])
+  }, [id, connectAttempt])
 
   // Resize terminal on dimension changes
   useEffect(() => {
@@ -281,7 +273,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     return () => clearTimeout(timer)
   }, [width, height])
 
-  // Resize terminal to fill the expand container
+  // Resize for expand
   useEffect(() => {
     if (!expanded || !termRef.current || !expandContainerRef.current) return
     const timer = setTimeout(() => {
@@ -292,14 +284,15 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
       if (wsRef.current?.readyState === WebSocket.OPEN) {
         wsRef.current.send(JSON.stringify({ type: 'resize', cols: dims.cols, rows: dims.rows }))
       }
+      setInteractive(true)
+      termRef.current?.focus?.()
     }, 100)
     return () => clearTimeout(timer)
   }, [expanded])
 
-  // Restore terminal size when collapsing
+  // Restore size on collapse
   useEffect(() => {
-    if (expanded) return
-    if (!termRef.current) return
+    if (expanded || !termRef.current) return
     const timer = setTimeout(() => {
       const dims = calcDimensions(width, height)
       termRef.current?.resize?.(dims.cols, dims.rows)
@@ -310,7 +303,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
     return () => clearTimeout(timer)
   }, [expanded, width, height])
 
-  // Reparent terminal DOM node between inline and expand
+  // Reparent terminal DOM between inline and expand
   useEffect(() => {
     const xtermEl = containerRef.current
     if (!xtermEl) return
@@ -322,38 +315,57 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
   }, [expanded])
 
   const handleClick = useCallback(() => {
-    if (phase === 'ended') return
-    if (phase === 'live') {
-      // Save canvas scroll position — terminal focus can trigger browser scroll
+    if (sessionEnded) return
+    if (ready) {
+      setInteractive(true)
       const scrollEl = terminalRef.current?.closest('[class*="canvasScroll"]')
       const scrollTop = scrollEl?.scrollTop
       const scrollLeft = scrollEl?.scrollLeft
       termRef.current?.focus({ preventScroll: true })
-      // Restore if browser scrolled anyway
       if (scrollEl && (scrollEl.scrollTop !== scrollTop || scrollEl.scrollLeft !== scrollLeft)) {
         scrollEl.scrollTop = scrollTop
         scrollEl.scrollLeft = scrollLeft
       }
     }
-  }, [phase])
+  }, [sessionEnded, ready])
+
+  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)
-      setErrorMsg(null)
-      setPhase('connecting')
+      setSessionEnded(false)
+      setError(null)
       setConnectAttempt(c => c + 1)
     }, 1500)
   }, [])
 
-  // 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 (
     <>
@@ -367,44 +379,34 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
           ...(typeof height === 'number' ? { height: `${height}px` } : undefined),
         }}
         onClick={handleClick}
+        onPointerDown={handleTerminalPointerDown}
+        onKeyDown={interactive ? (e) => e.stopPropagation() : undefined}
       >
-        {phase === 'error' && (
-          <div className={styles.error}>
-            <span>⚠ {errorMsg}</span>
+        {showDragHint && (
+          <div className={styles.dragHint}>
+            <span className={styles.dragHintArrow}>←</span> Drag here to move widget
           </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>
+        {error && !sessionEnded && (
+          <div className={styles.error}>
+            <span>⚠ {error}</span>
           </div>
         )}
+        <div ref={containerRef} className={styles.xtermContainer} />
 
-        {/* Live but not interactive: gated overlay */}
-        {phase === 'live' && !interactive && (
+        {/* Live but not interactive */}
+        {ready && !interactive && !sessionEnded && (
           <div
             className={overlayStyles.interactOverlay}
             style={{ backgroundColor: 'transparent' }}
             onClick={(e) => {
               if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
-              enterInteractive()
+              setInteractive(true)
+              termRef.current?.focus({ preventScroll: true })
             }}
             role="button"
             tabIndex={0}
-            onKeyDown={(e) => { if (e.key === 'Enter') enterInteractive() }}
+            onKeyDown={(e) => { if (e.key === 'Enter') { setInteractive(true); termRef.current?.focus({ preventScroll: true }) } }}
             aria-label="Click to interact"
           >
             <span className={overlayStyles.interactHint}>Click to interact</span>
@@ -412,7 +414,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
         )}
 
         {/* Session ended */}
-        {phase === 'ended' && (
+        {sessionEnded && (
           <div
             className={overlayStyles.interactOverlay}
             style={{ backgroundColor: '#0d1117', flexDirection: 'column', gap: 0 }}
@@ -430,13 +432,13 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, resizab
               </div>
             )}
             <span className={overlayStyles.interactHint}>
-              {waking ? 'Waking up...' : 'Start terminal session'}
+              {waking ? 'Waking up...' : connectAttempt > 0 ? 'Continue terminal session' : 'Start terminal session'}
             </span>
           </div>
         )}
 
         {/* Connecting */}
-        {phase === 'connecting' && (
+        {!ready && !error && !sessionEnded && (
           <div className={styles.loading}>Connecting…</div>
         )}
       </div>

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

@@ -33,7 +33,7 @@
   background: #0d1117;
   border: 1px solid var(--borderColor-default, #30363d);
   box-shadow: 0 1px 3px rgba(0, 0, 0, 0.24);
-  padding: 8px;
+  padding: var(--base-size-24, 24px) var(--base-size-16, 16px);
 }
 
 .xtermContainer {
@@ -49,6 +49,22 @@
   padding: 12px;
 }
 
+/* Hide the native caret on ghostty-web's helper textarea —
+   without this it renders a visible blinking cursor at (0,0)
+   and triggers scrollIntoView on focus (scroll-to-top bug). */
+.xtermContainer :global(.xterm-helper-textarea),
+.xtermContainer textarea {
+  caret-color: transparent !important;
+  opacity: 0 !important;
+  position: absolute !important;
+  top: 0 !important;
+  left: 0 !important;
+  width: 1px !important;
+  height: 1px !important;
+  overflow: hidden !important;
+  pointer-events: none !important;
+}
+
 .xtermContainer :global(.xterm-viewport) {
   overflow-y: auto;
 }
@@ -158,6 +174,38 @@
 }
 
 /* Fullscreen expand */
+
+/* Drag hint tooltip — appears when user tries to drag the terminal body */
+.dragHint {
+  position: absolute;
+  bottom: -32px;
+  right: 0;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 4px 10px;
+  border-radius: 6px;
+  background: var(--bgColor-inverse, #1f2328);
+  color: var(--fgColor-onInverse, #ffffff);
+  font-size: 12px;
+  font-weight: 500;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  white-space: nowrap;
+  pointer-events: none;
+  animation: dragHintIn 150ms ease;
+}
+
+.dragHintArrow {
+  font-size: 14px;
+  opacity: 0.7;
+}
+
+@keyframes dragHintIn {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
 .expandBackdrop {
   position: fixed;
   inset: 0;

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()
     })
   })