@dfosco/storyboard-react 4.2.0-beta.2 → 4.2.0-beta.21

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -1,11 +1,12 @@
 import { useState, useRef, useEffect, useCallback, useMemo, forwardRef, useImperativeHandle } from 'react'
-import { createPortal } from 'react-dom'
 import { buildPrototypeIndex } from '@dfosco/storyboard-core'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
 import { readProp, prototypeEmbedSchema } from './widgetProps.js'
 import { getEmbedChromeVars } from './embedTheme.js'
 import { useIframeDevLogs } from './iframeDevLogs.js'
+import { findAllConnectedSplitTargets, getSplitPaneLabel, buildPaneForWidget, buildSplitLayout } from './expandUtils.js'
+import ExpandedPane from './ExpandedPane.jsx'
 import styles from './PrototypeEmbed.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
@@ -64,7 +65,8 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
 
   const [editing, setEditing] = useState(false)
   const [interactive, setInteractive] = useState(false)
-  const [expanded, setExpanded] = useState(false)
+  const [expandMode, setExpandMode] = useState(null)
+  const expanded = expandMode !== null
   const [filter, setFilter] = useState('')
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
   const inputRef = 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 effectiveSrc = iframeSrc
+
   const prototypeIndex = useMemo(() => {
     try { return buildPrototypeIndex() }
     catch { return { folders: [], prototypes: [], globalFlows: [], sorted: { title: { prototypes: [], folders: [] } } } }
@@ -153,8 +157,8 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
 
   useIframeDevLogs({
     widget: 'PrototypeEmbed',
-    loaded: Boolean(iframeSrc && interactive),
-    src: iframeSrc,
+    loaded: Boolean(effectiveSrc && interactive),
+    src: effectiveSrc,
   })
 
   useEffect(() => {
@@ -189,19 +193,6 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     return () => document.removeEventListener('storyboard:theme:changed', readToolbarTheme)
   }, [])
 
-  // Close expanded modal on Escape
-  useEffect(() => {
-    if (!expanded) return
-    function handleKeyDown(e) {
-      if (e.key === 'Escape') {
-        e.stopPropagation()
-        setExpanded(false)
-      }
-    }
-    document.addEventListener('keydown', handleKeyDown, true)
-    return () => document.removeEventListener('keydown', handleKeyDown, true)
-  }, [expanded])
-
   // Reparent iframe between inline and modal
   useEffect(() => {
     const iframe = iframeRef.current
@@ -212,8 +203,12 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
       iframe.className = styles.expandIframe
       iframe.removeAttribute('style')
       const target = modalContainerRef.current
-      if (target.moveBefore) target.moveBefore(iframe, target.firstChild)
-      else target.prepend(iframe)
+      try {
+        if (target.moveBefore) target.moveBefore(iframe, target.firstChild)
+        else target.prepend(iframe)
+      } catch {
+        target.prepend(iframe)
+      }
     } else if (!expanded && inlineContainerRef.current) {
       if (iframe._savedClassName !== undefined) {
         iframe.className = iframe._savedClassName
@@ -222,8 +217,12 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
         delete iframe._savedStyle
       }
       const target = inlineContainerRef.current
-      if (target.moveBefore) target.moveBefore(iframe, null)
-      else target.appendChild(iframe)
+      try {
+        if (target.moveBefore) target.moveBefore(iframe, null)
+        else target.appendChild(iframe)
+      } catch {
+        target.appendChild(iframe)
+      }
     }
   }, [expanded])
 
@@ -250,8 +249,10 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
     handleAction(actionId) {
       if (actionId === 'edit') {
         setEditing(true)
-      } else if (actionId === 'expand') {
-        setExpanded(true)
+      } else if (actionId === 'expand' || actionId === 'expand-single') {
+        setExpandMode('single')
+      } else if (actionId === 'split-screen') {
+        setExpandMode('split')
       } else if (actionId === 'open-external') {
         if (rawSrc) window.open(rawSrc, '_blank', 'noopener')
       } else if (actionId === 'zoom-in') {
@@ -362,7 +363,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
             >
               <iframe
                 ref={iframeRef}
-                src={iframeSrc}
+                src={effectiveSrc}
                 className={styles.iframe}
                 style={{
                   width: width / scale,
@@ -372,6 +373,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                 }}
                 title={`${prototypeTitle} prototype`}
                 sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
+                onLoad={(e) => e.target.blur()}
               />
             </div>
             {!interactive && !expanded && (
@@ -405,21 +407,58 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
       </div>
       {resizable && <ResizeHandle targetRef={embedRef} width={width} height={height} onResize={handleResize} />}
     </WidgetWrapper>
-    {createPortal(
-      <div
-        className={styles.expandBackdrop}
-        style={expanded ? undefined : { display: 'none' }}
-        onClick={() => setExpanded(false)}
-        onPointerDown={(e) => e.stopPropagation()}
-        onKeyDown={(e) => e.stopPropagation()}
-        onWheel={(e) => e.stopPropagation()}
-      >
-        <div ref={modalContainerRef} className={styles.expandContainer} onClick={(e) => e.stopPropagation()}>
-          <button className={styles.expandClose} onClick={() => setExpanded(false)} aria-label="Close expanded view" autoFocus>✕</button>
-        </div>
-      </div>,
-      document.body
+    {expanded && (
+      <PrototypeExpandPane
+        widgetId={widgetId}
+        modalContainerRef={modalContainerRef}
+        splitMode={expandMode === 'split'}
+        onClose={() => setExpandMode(null)}
+      />
     )}
     </>
   )
 })
+
+/**
+ * Builds pane configs and renders ExpandedPane for an expanded prototype widget.
+ * The primary pane is an external pane that receives the iframe via reparenting.
+ */
+function PrototypeExpandPane({ widgetId, modalContainerRef, 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: 'prototype', position: { x: 0, y: 0 }, props: {} }
+  }, [widgetId])
+
+  const buildPaneFn = useCallback((widget) => {
+    if (widget.id === widgetId) {
+      return {
+        id: widgetId,
+        label: getSplitPaneLabel(primaryWidget),
+        widgetType: 'prototype',
+        kind: 'external',
+        attach: (container) => {
+          modalContainerRef.current = container
+          return () => { modalContainerRef.current = null }
+        },
+      }
+    }
+    return buildPaneForWidget(widget)
+  }, [widgetId, primaryWidget, modalContainerRef])
+
+  const layout = useMemo(
+    () => buildSplitLayout(primaryWidget, connectedWidgets, buildPaneFn),
+    [primaryWidget, connectedWidgets, buildPaneFn],
+  )
+
+  return (
+    <ExpandedPane
+      initialLayout={layout}
+      variant={layout.flat().length <= 1 ? 'modal' : 'full'}
+      onClose={onClose}
+    />
+  )
+}

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

@@ -460,3 +460,120 @@
 .expandClose:hover {
   background: rgba(0, 0, 0, 0.7);
 }
+
+/* ── Split-screen layout ──────────────────────────────────────────── */
+
+.expandContainerSplit {
+  flex: 1;
+  min-width: 0;
+  height: 100%;
+  position: relative;
+  overflow: hidden;
+  background: var(--bgColor-default, #ffffff);
+}
+
+.expandContainerSplit .expandIframe {
+  border: none;
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.expandSplitBody {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  animation: expandScaleIn 0.2s ease;
+}
+
+.expandSplitPanes {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+}
+
+.expandSplitLeft {
+  flex: 1;
+  min-width: 0;
+  height: 100%;
+  overflow: hidden;
+  border-right: 1px solid var(--borderColor-muted, #d8dee4);
+}
+
+.expandSplitRight {
+  flex: 1;
+  min-width: 0;
+  height: 100%;
+  overflow: hidden;
+}
+
+.expandSecondary {
+  width: 100%;
+  height: 100%;
+  overflow: auto;
+  background: var(--bgColor-default, #ffffff);
+}
+
+.expandSecondary iframe {
+  border: none;
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.expandTerminal {
+  width: 100%;
+  height: 100%;
+  background: #0d1117;
+}
+
+.expandMarkdownContent {
+  padding: 32px 40px;
+  font-size: 15px;
+  line-height: 1.7;
+  color: var(--fgColor-default, #1f2328);
+  max-width: 800px;
+  margin: 0 auto;
+}
+
+.expandMarkdownContent * { pointer-events: auto; }
+.expandMarkdownContent a { color: var(--fgColor-accent, #0969da); text-decoration: none; }
+.expandMarkdownContent a:hover { text-decoration: underline; }
+.expandMarkdownContent img { max-width: 100%; height: auto; border-radius: 6px; margin: 8px 0; display: block; }
+
+.expandGithubCard {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  background: var(--bgColor-default, #ffffff);
+}
+
+.expandGithubHeader {
+  padding: 16px 24px;
+  font-size: 18px;
+  font-weight: 600;
+  border-bottom: 1px solid var(--borderColor-muted, #d8dee4);
+}
+
+.expandGithubBody {
+  flex: 1;
+  overflow: auto;
+  padding: 24px;
+  font-size: 15px;
+  line-height: 1.7;
+}
+
+.expandGithubBody * { pointer-events: auto; }
+.expandGithubBody a { color: var(--fgColor-accent, #0969da); }
+
+.expandLinkCard {
+  padding: 32px 40px;
+}
+
+.expandLinkTitle {
+  font-size: 18px;
+  font-weight: 600;
+  margin: 0 0 8px;
+}

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

@@ -4,7 +4,7 @@ import { getEmbedChromeVars } from './embedTheme.js'
 describe('getEmbedChromeVars', () => {
   it('follows toolbar theme variants for embed edit chrome', () => {
     expect(getEmbedChromeVars('light')['--bgColor-default']).toBe('#ffffff')
-    expect(getEmbedChromeVars('dark')['--bgColor-default']).toBe('#161b22')
-    expect(getEmbedChromeVars('dark_dimmed')['--bgColor-default']).toBe('#22272e')
+    expect(getEmbedChromeVars('dark')['--bgColor-default']).toBe('#0d1117')
+    expect(getEmbedChromeVars('dark_dimmed')['--bgColor-default']).toBe('#212830')
   })
 })

package/src/canvas/widgets/ResizeHandle.jsx

@@ -13,9 +13,12 @@ import styles from './ResizeHandle.module.css'
  * @param {React.RefObject} props.targetRef - ref to the element being resized (reads offsetWidth/Height)
  * @param {number} [props.minWidth=180]  - minimum allowed width
  * @param {number} [props.minHeight=60]  - minimum allowed height
+ * @param {'both'|'vertical'|'horizontal'} [props.axis='both'] - constrain resize to a single axis
  * @param {Function} props.onResize - callback: (width, height) => void
+ * @param {Function} [props.onResizeStart] - called when drag begins
+ * @param {Function} [props.onResizeEnd] - called with final (width, height) on drag end
  */
-export default function ResizeHandle({ targetRef, minWidth = 180, minHeight = 60, onResize }) {
+export default function ResizeHandle({ targetRef, minWidth = 180, minHeight = 60, axis = 'both', onResize, onResizeStart, onResizeEnd }) {
   const handleMouseDown = useCallback((e) => {
     e.stopPropagation()
     e.preventDefault()
@@ -27,29 +30,37 @@ export default function ResizeHandle({ targetRef, minWidth = 180, minHeight = 60
     const startY = e.clientY
     const startW = el.offsetWidth
     const startH = el.offsetHeight
+    let lastW = startW
+    let lastH = startH
+
+    onResizeStart?.()
 
     function onMove(ev) {
-      const newW = Math.max(minWidth, startW + ev.clientX - startX)
-      const newH = Math.max(minHeight, startH + ev.clientY - startY)
-      onResize?.(newW, newH)
+      lastW = axis === 'vertical' ? startW : Math.max(minWidth, startW + ev.clientX - startX)
+      lastH = axis === 'horizontal' ? startH : Math.max(minHeight, startH + ev.clientY - startY)
+      onResize?.(lastW, lastH)
     }
 
     function onUp() {
       document.removeEventListener('mousemove', onMove)
       document.removeEventListener('mouseup', onUp)
+      onResizeEnd?.(lastW, lastH)
     }
 
     document.addEventListener('mousemove', onMove)
     document.addEventListener('mouseup', onUp)
-  }, [targetRef, minWidth, minHeight, onResize])
+  }, [targetRef, minWidth, minHeight, axis, onResize, onResizeStart, onResizeEnd])
+
+  const cursor = axis === 'vertical' ? 'ns-resize' : axis === 'horizontal' ? 'ew-resize' : 'nwse-resize'
 
   return (
     <div
       className={styles.handle}
+      style={axis !== 'both' ? { cursor } : undefined}
       onMouseDown={handleMouseDown}
       onPointerDown={(e) => e.stopPropagation()}
       role="separator"
-      aria-orientation="horizontal"
+      aria-orientation={axis === 'vertical' ? 'vertical' : 'horizontal'}
       aria-label="Resize"
     />
   )

package/src/canvas/widgets/StoryWidget.jsx

@@ -11,21 +11,17 @@
 import { forwardRef, useImperativeHandle, useRef, useCallback, useState, useEffect, useMemo } from 'react'
 import { getStoryData } from '@dfosco/storyboard-core'
 import { createInspectorHighlighter } from '@dfosco/storyboard-core/inspector/highlighter'
+import Icon from '../../Icon.jsx'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
 import { useIframeDevLogs } from './iframeDevLogs.js'
+import { findAllConnectedSplitTargets, getSplitPaneLabel, buildPaneForWidget, buildSplitLayout, buildSecondaryIframeUrl } from './expandUtils.js'
+import ExpandedPane from './ExpandedPane.jsx'
 import styles from './StoryWidget.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
 function ComponentIcon({ size = 36 }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" aria-hidden="true">
-      <path d="M5.21173 15.1113L2.52473 12.4243C2.29041 12.1899 2.29041 11.8101 2.52473 11.5757L5.21173 8.88873C5.44605 8.65442 5.82595 8.65442 6.06026 8.88873L8.74727 11.5757C8.98158 11.8101 8.98158 12.1899 8.74727 12.4243L6.06026 15.1113C5.82595 15.3456 5.44605 15.3456 5.21173 15.1113Z" />
-      <path d="M11.5757 21.475L8.88874 18.788C8.65443 18.5537 8.65443 18.1738 8.88874 17.9395L11.5757 15.2525C11.8101 15.0182 12.19 15.0182 12.4243 15.2525L15.1113 17.9395C15.3456 18.1738 15.3456 18.5537 15.1113 18.788L12.4243 21.475C12.19 21.7094 11.8101 21.7094 11.5757 21.475Z" />
-      <path d="M17.9395 15.1113L15.2525 12.4243C15.0182 12.1899 15.0182 11.8101 15.2525 11.5757L17.9395 8.88873C18.1738 8.65442 18.5537 8.65442 18.788 8.88873L21.475 11.5757C21.7094 11.8101 21.7094 12.1899 21.475 12.4243L18.788 15.1113C18.5537 15.3456 18.1738 15.3456 17.9395 15.1113Z" />
-      <path d="M11.5757 8.74727L8.88874 6.06026C8.65443 5.82595 8.65443 5.44605 8.88874 5.21173L11.5757 2.52473C11.8101 2.29041 12.19 2.29041 12.4243 2.52473L15.1113 5.21173C15.3456 5.44605 15.3456 5.82595 15.1113 6.06026L12.4243 8.74727C12.19 8.98158 11.8101 8.98158 11.5757 8.74727Z" />
-    </svg>
-  )
+  return <Icon name="iconoir/keyframe" size={size} />
 }
 
 function resolveStoryUrl(storyId, exportName) {
@@ -43,9 +39,10 @@ const _storySourcesCache = {}
 
 async function fetchStorySource(modulePath) {
   if (modulePath in _storySourcesCache) return _storySourcesCache[modulePath]
-  const url = modulePath.startsWith('/') ? modulePath : `/${modulePath}`
-  const res = await fetch(`${url}?raw`)
-  if (!res.ok) throw new Error(`Failed to fetch ${url}`)
+  const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
+  const path = modulePath.startsWith('/') ? modulePath : `/${modulePath}`
+  const res = await fetch(`${base}${path}?raw`)
+  if (!res.ok) throw new Error(`Failed to fetch ${base}${path}`)
   const code = await res.text()
   _storySourcesCache[modulePath] = code
   return code
@@ -58,6 +55,8 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const height = props?.height
 
   const containerRef = useRef(null)
+  const [expandMode, setExpandMode] = useState(null)
+  const expanded = expandMode !== null
   const iframeRef = useRef(null)
   const [interactive, setInteractive] = useState(false)
   const [showCode, setShowCode] = useState(!!props?.showCode)
@@ -156,6 +155,8 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     handleAction(actionId) {
       if (actionId === 'show-code') toggleShowCode()
       else if (actionId === 'copy-code') copyCode()
+      else if (actionId === 'expand' || actionId === 'expand-single') setExpandMode('single')
+      else if (actionId === 'split-screen') setExpandMode('split')
       else if (actionId === 'open-external') {
         const story = getStoryData(storyId)
         if (story?._route) {
@@ -171,10 +172,13 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     [storyId, exportName, storyIndexKey],
   )
 
+  // When paused and not interactive, freeze the iframe src to prevent reloads
+  const effectiveSrc = iframeSrc
+
   useIframeDevLogs({
     widget: 'StoryWidget',
-    loaded: interactive && !showCode && Boolean(iframeSrc),
-    src: iframeSrc,
+    loaded: interactive && !showCode && Boolean(effectiveSrc),
+    src: effectiveSrc,
   })
 
   const displayName = exportName ? `${storyId} / ${exportName}` : storyId
@@ -192,7 +196,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     )
   }
 
-  if (!iframeSrc) {
+  if (!effectiveSrc) {
     return (
       <WidgetWrapper>
         <div className={styles.container} ref={containerRef}>
@@ -210,6 +214,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   if (typeof height === 'number') sizeStyle.height = `${height}px`
 
   return (
+    <>
     <WidgetWrapper>
       <div ref={containerRef} className={styles.container} style={sizeStyle}>
         <div className={styles.header}>
@@ -241,9 +246,10 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
             <div className={styles.content}>
               <iframe
                 ref={iframeRef}
-                src={iframeSrc}
+                src={effectiveSrc}
                 className={styles.iframe}
                 title={displayName}
+                onLoad={(e) => e.target.blur()}
               />
             </div>
 
@@ -273,5 +279,56 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
       </div>
       {resizable && <ResizeHandle targetRef={containerRef} width={width} height={height} onResize={handleResize} />}
     </WidgetWrapper>
+    {expanded && (
+      <StoryExpandPane
+        widgetId={widgetId}
+        storyId={storyId}
+        exportName={exportName}
+        splitMode={expandMode === 'split'}
+        onClose={() => setExpandMode(null)}
+      />
+    )}
+    </>
   )
 })
+
+function StoryExpandPane({ widgetId, storyId, exportName, 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: 'story', position: { x: 0, y: 0 }, props: { storyId, exportName } }
+  }, [widgetId, storyId, exportName])
+
+  const buildPaneFn = useCallback((widget) => {
+    if (widget.id === widgetId) {
+      const url = buildSecondaryIframeUrl({ type: 'story', props: { storyId, exportName } })
+      return {
+        id: widgetId,
+        label: getSplitPaneLabel({ type: 'story', props: { storyId, exportName } }),
+        widgetType: 'story',
+        kind: 'react',
+        render: () => url
+          ? <iframe src={url} style={{ border: 'none', width: '100%', height: '100%', display: 'block' }} title={storyId} onLoad={(e) => e.target.blur()} />
+          : <div style={{ padding: 32, color: 'var(--fgColor-muted)' }}>Story "{storyId}" not found</div>,
+      }
+    }
+    return buildPaneForWidget(widget)
+  }, [widgetId, storyId, exportName])
+
+  const layout = useMemo(
+    () => buildSplitLayout(primaryWidget, connectedWidgets, buildPaneFn),
+    [primaryWidget, connectedWidgets, buildPaneFn],
+  )
+
+  return (
+    <ExpandedPane
+      initialLayout={layout}
+      variant={layout.flat().length <= 1 ? 'modal' : 'full'}
+      onClose={onClose}
+    />
+  )
+}

package/src/canvas/widgets/TerminalReadWidget.jsx

@@ -0,0 +1,146 @@
+import { useRef, useEffect, useState } from 'react'
+import { readProp, schemas } from './widgetProps.js'
+import styles from './TerminalReadWidget.module.css'
+
+const terminalSchema = schemas['terminal']
+
+let Convert = null
+let ansiLoadAttempted = false
+
+async function getConverter() {
+  if (Convert) return new Convert({ fg: '#e6edf3', bg: '#0d1117', newline: true })
+  if (ansiLoadAttempted) return null
+  ansiLoadAttempted = true
+  try {
+    const mod = await import(/* @vite-ignore */ 'ansi-to-html')
+    Convert = mod.default || mod
+    return new Convert({ fg: '#e6edf3', bg: '#0d1117', newline: true })
+  } catch {
+    return null
+  }
+}
+
+function stripAnsi(text) {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')
+}
+
+function getBaseUrl() {
+  const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
+  return base.endsWith('/') ? base : base + '/'
+}
+
+function getCanvasId() {
+  return window.__storyboardCanvasBridgeState?.canvasId || null
+}
+
+function isProduction() {
+  return typeof import.meta !== 'undefined' && import.meta.env?.PROD
+}
+
+export default function TerminalReadWidget({ id, props }) {
+  const width = readProp(props, 'width', terminalSchema)
+  const height = readProp(props, 'height', terminalSchema)
+  const prettyName = props?.prettyName || '...'
+
+  const [content, setContent] = useState(null)
+  const [html, setHtml] = useState(null)
+  const [failed, setFailed] = useState(false)
+  const contentRef = useRef(null)
+
+  useEffect(() => {
+    let cancelled = false
+    async function fetchSnapshot() {
+      const baseUrl = getBaseUrl()
+      const canvasId = getCanvasId()
+      if (!canvasId) { setFailed(true); return }
+
+      const urls = isProduction()
+        ? [
+            // New flat format: <widgetId>.snapshot.json
+            `${baseUrl}_storyboard/terminal-snapshots/${id}.snapshot.json`,
+            // Legacy nested format: <canvasDir>/<widgetId>.json
+            `${baseUrl}_storyboard/terminal-snapshots/${canvasId.replace(/\//g, '--')}/${id}.json`,
+          ]
+        : [
+            `${baseUrl}_storyboard/canvas/terminal-snapshot/${id}`,
+            `${baseUrl}_storyboard/terminal-snapshots/${id}.snapshot.json`,
+            `${baseUrl}_storyboard/terminal-snapshots/${canvasId.replace(/\//g, '--')}/${id}.json`,
+          ]
+
+      for (const url of urls) {
+        try {
+          const res = await fetch(url)
+          if (!res.ok) continue
+          const data = await res.json()
+          if (cancelled) return
+          const text = data.paneContent || data.content || data.output || ''
+          setContent(text)
+
+          const converter = await getConverter()
+          if (cancelled) return
+          if (converter) {
+            setHtml(converter.toHtml(text))
+          } else {
+            setContent(stripAnsi(text))
+          }
+          return
+        } catch {
+          continue
+        }
+      }
+      if (!cancelled) setFailed(true)
+    }
+    fetchSnapshot()
+    return () => { cancelled = true }
+  }, [id])
+
+  // Auto-scroll to bottom
+  useEffect(() => {
+    if (contentRef.current) {
+      contentRef.current.scrollTop = contentRef.current.scrollHeight
+    }
+  }, [html, content])
+
+  const titleLabel = `terminal · ${prettyName}`
+
+  return (
+    <div className={styles.container}>
+      <div className={`tc-drag-handle ${styles.titleBar}`}>
+        <span>{titleLabel}</span>
+        <span className={styles.readOnlyBadge}>read only</span>
+      </div>
+      <div
+        ref={contentRef}
+        className={styles.content}
+        style={{
+          ...(typeof width === 'number' ? { width: `${width}px` } : undefined),
+          ...(typeof height === 'number' ? { height: `${height}px` } : undefined),
+        }}
+      >
+        {failed && (
+          <div className={styles.placeholder}>
+            <span className={styles.placeholderTitle}>Terminal session · {prettyName}</span>
+            <span className={styles.placeholderSub}>No captured output available</span>
+          </div>
+        )}
+        {!failed && content === null && (
+          <div className={styles.placeholder}>
+            <span className={styles.placeholderSub}>Loading…</span>
+          </div>
+        )}
+        {!failed && html && (
+          <pre
+            style={{ margin: 0, whiteSpace: 'pre', fontFamily: 'inherit', fontSize: 'inherit', lineHeight: 'inherit' }}
+            dangerouslySetInnerHTML={{ __html: html }}
+          />
+        )}
+        {!failed && content !== null && !html && (
+          <pre style={{ margin: 0, whiteSpace: 'pre', fontFamily: 'inherit', fontSize: 'inherit', lineHeight: 'inherit' }}>
+            {content}
+          </pre>
+        )}
+      </div>
+    </div>
+  )
+}