@dfosco/storyboard 0.6.0-beta.2 → 0.6.0-beta.21

package/src/core/vite/server-plugin.js

@@ -19,6 +19,7 @@ import { serverFeatures as workshopFeatures } from '../workshop/features/registr
 import { docsHandler, collectFiles } from './docs-handler.js'
 import { createCanvasHandler } from '../canvas/server.js'
 import { setupSelectedWidgets } from '../canvas/selectedWidgets.js'
+import { readAgentsConfig, readHotPoolConfig } from '../canvas/configReader.js'
 import { HotPoolManager } from '../canvas/hot-pool.js'
 import { createAutosyncHandler } from '../autosync/server.js'
 import { setupTerminalServer } from '../canvas/terminal-server.js'
@@ -122,6 +123,22 @@ export default function storyboardServer() {
             'highlight.js/lib/languages/xml',
           ],
         },
+        server: {
+          watch: {
+            // Never feed runtime-state directories to Vite's file watcher.
+            // These dirs are written to on sub-second cadence by terminals,
+            // canvas snapshots, agent state, etc. Letting them reach the
+            // watcher produces full-reload loops on any unguarded route.
+            // (server.watcher.unwatch() after the fact isn't enough — new
+            // files inside the dirs can still be re-added by chokidar.)
+            ignored: [
+              '**/.storyboard/**',
+              '**/assets/canvas/images/**',
+              '**/assets/canvas/snapshots/**',
+              '**/assets/.storyboard-public/**',
+            ],
+          },
+        },
       }
     },
 
@@ -133,6 +150,20 @@ export default function storyboardServer() {
     },
 
     configureServer(server) {
+      // --- Custom URL printer ----------------------------------------------------
+      // Vite calls server.printUrls() after its "ready in Xms" banner.
+      // Override to suppress Vite's default "➜ Local:" block and let the
+      // CLI render our own URL (and mascot) instead. Suppression is opt-in
+      // via STORYBOARD_QUIET_VITE=1 — we set this from storyboard dev.js
+      // when --verbose is OFF.
+      if (process.env.STORYBOARD_QUIET_VITE === '1') {
+        const originalPrintUrls = server.printUrls?.bind(server)
+        server.printUrls = () => {
+          // No-op: caller renders its own URL + mascot.
+          void originalPrintUrls
+        }
+      }
+
       // --- Reload guard ----------------------------------------------------------
       // Suppress full-reloads and HMR updates for guarded clients.
       //
@@ -140,7 +171,9 @@ export default function storyboardServer() {
       //   1. Canvas guard — canvas pages send heartbeats via storyboard:canvas-hmr-guard.
       //      Controlled by the "canvas-auto-reload" feature flag (default: false = guard ON).
       //   2. Prototype guard — all pages send heartbeats via storyboard:prototype-reload-guard.
-      //      Controlled by the "prototype-auto-reload" feature flag (default: true = guard OFF).
+      //      Controlled by the "prototype-auto-reload" feature flag (default: false = guard ON).
+      //      The prototype guard only drops `full-reload` payloads; `update` (HMR module /
+      //      React Fast Refresh) payloads still flow so component edits hot-update normally.
       //
       // Both guards auto-expire 5s after the last heartbeat so closed tabs never
       // leave them stuck. Custom storyboard events always pass through.
@@ -193,12 +226,14 @@ export default function storyboardServer() {
         server.httpServer?.on('close', () => clearInterval(cleanup))
         server.httpServer?.on('close', () => stopMaintenance())
 
-        function isClientGuarded(client) {
+        function isCanvasClientGuarded(client) {
           const cu = canvasGuardedClients.get(client)
-          if (cu != null && Date.now() < cu) return true
+          return cu != null && Date.now() < cu
+        }
+
+        function isPrototypeClientGuarded(client) {
           const pu = prototypeGuardedClients.get(client)
-          if (pu != null && Date.now() < pu) return true
-          return false
+          return pu != null && Date.now() < pu
         }
 
         const originalSend = server.ws.send.bind(server.ws)
@@ -217,10 +252,24 @@ export default function storyboardServer() {
             return originalSend(payload, ...rest)
           }
 
-          // For reload/update payloads, send only to unguarded clients
-          if (payload && (payload.type === 'full-reload' || payload.type === 'update')) {
+          // full-reload: drop for any guarded client (canvas OR prototype).
+          // Both guards exist to preserve in-page state across data file edits.
+          if (payload && payload.type === 'full-reload') {
+            for (const client of server.ws.clients) {
+              if (!isCanvasClientGuarded(client) && !isPrototypeClientGuarded(client)) {
+                client.send(payload)
+              }
+            }
+            return
+          }
+
+          // update (HMR module updates / React Fast Refresh): only drop for
+          // CANVAS-guarded clients (canvas state must not be disturbed by
+          // unrelated module updates). Prototype-guarded clients still
+          // receive updates so React Fast Refresh works while developing.
+          if (payload && payload.type === 'update') {
             for (const client of server.ws.clients) {
-              if (!isClientGuarded(client)) {
+              if (!isCanvasClientGuarded(client)) {
                 client.send(payload)
               }
             }
@@ -279,8 +328,8 @@ export default function storyboardServer() {
       routeHandlers.set('docs', docsHandler({ root, sendJson: sendJsonLogged }))
 
       // Create shared hot pool manager (per-type pre-warmed sessions)
-      const hotPoolConfig = config.hotPool || {}
-      const agentsConfig = config.canvas?.agents || {}
+      const hotPoolConfig = readHotPoolConfig(root)
+      const agentsConfig = readAgentsConfig(root)
       const wsSend = server.ws.send.bind(server.ws)
       const hotPool = new HotPoolManager({ root, config: hotPoolConfig, agentsConfig, wsSend })
       hotPool.start().catch((err) => {
@@ -759,6 +808,54 @@ export default function storyboardServer() {
         })
       }
 
+      // Auto-reload on Vite's "outdated optimize dep" 504 errors.
+      // Happens when the dep graph IDs in cached chunks no longer match
+      // what Vite is serving (after upgrades, dep additions, etc).
+      // We catch failed fetches inside the page and trigger a full reload
+      // once — the second load will see the freshly-built optimize deps.
+      if (isDev) {
+        tags.push({
+          tag: 'script',
+          children: `
+(function(){
+  var reloaded = false;
+  function maybeReload(reason){
+    if (reloaded) return;
+    if (sessionStorage.getItem('__sb_outdated_reload__')) return;
+    reloaded = true;
+    sessionStorage.setItem('__sb_outdated_reload__', '1');
+    console.warn('[storyboard] Reloading: ' + reason);
+    setTimeout(function(){ sessionStorage.removeItem('__sb_outdated_reload__'); }, 5000);
+    location.reload();
+  }
+  // Clear stale guard from previous successful loads.
+  if (document.readyState === 'complete') {
+    sessionStorage.removeItem('__sb_outdated_reload__');
+  } else {
+    window.addEventListener('load', function(){
+      setTimeout(function(){ sessionStorage.removeItem('__sb_outdated_reload__'); }, 2000);
+    });
+  }
+  // Catch module load failures.
+  window.addEventListener('error', function(e){
+    var msg = (e && e.message) || '';
+    if (/Outdated Optimize Dep|Failed to fetch dynamically imported module|504/i.test(msg)) {
+      maybeReload('outdated dep / dynamic import failure');
+    }
+  }, true);
+  // Catch unhandled promise rejections from dynamic imports.
+  window.addEventListener('unhandledrejection', function(e){
+    var msg = (e && e.reason && (e.reason.message || String(e.reason))) || '';
+    if (/Outdated Optimize Dep|Failed to fetch dynamically imported module|504/i.test(msg)) {
+      maybeReload('outdated dep / dynamic import failure');
+    }
+  });
+})();
+`.trim(),
+          injectTo: 'head',
+        })
+      }
+
       // Inject base path so the inspector UI can resolve static assets
       // (e.g. inspector.json) when deployed under a subpath
       tags.push({

package/src/internals/CommandPalette/CommandPalette.jsx

@@ -1412,7 +1412,7 @@ export default function StoryboardCommandPalette({ basePath }) {
                       >
                         <ItemIcon type={itemType} toolIcon={toolIcon} toolMeta={toolMeta} />
                         <span style={{ display: 'flex', width: '100%', justifyContent: 'space-between', alignItems: 'center', gap: '8px' }}>
-                          <span>{children}</span>
+                          <span style={{ flex: 1, minWidth: 0 }}>{children}</span>
                           {tag && <span data-cmdk-item-tag="">{tag}</span>}
                         </span>
                       </Command.Item>

package/src/internals/Viewfinder.jsx

@@ -99,6 +99,7 @@ const STARRED_KEY = 'sb-workspace-starred'
 const RECENT_KEY = 'sb-workspace-recent'
 const MAX_RECENT = 30
 const GROUP_BY_FOLDERS_KEY = 'sb-workspace-group-folders'
+const COLLAPSED_FOLDERS_KEY = 'sb-workspace-collapsed-folders'
 
 function readJSON(key, fallback) {
   try { return JSON.parse(localStorage.getItem(key)) || fallback }
@@ -471,7 +472,7 @@ function ArtifactCard({ item, basePath, starred, onToggleStar, onItemDeleted })
           <span className={css.cardBadge}>{getTypeLabel(item.type)}</span>
           <div className={css.cardActions}>
             <StarBtn active={starred} onClick={() => onToggleStar(item.id)} inline />
-            {item.flows?.length > 0 && <FlowsDropdown flows={item.flows} basePath={basePath} />}
+            {item.flows?.length > 1 && <FlowsDropdown flows={item.flows} basePath={basePath} />}
             {item.pages?.length > 1 && <PagesDropdown pages={item.pages} basePath={basePath} />}
             {canEditDelete && (
               <CardActionsMenu
@@ -1240,7 +1241,13 @@ function WorkspaceImpl({
   const [groupByFolders, setGroupByFolders] = useState(() => {
     try { return localStorage.getItem(GROUP_BY_FOLDERS_KEY) !== 'false' } catch { return true }
   })
-  const [collapsedFolders, setCollapsedFolders] = useState(new Set())
+  const [collapsedFolders, setCollapsedFolders] = useState(() => {
+    try {
+      const raw = localStorage.getItem(COLLAPSED_FOLDERS_KEY)
+      const parsed = raw ? JSON.parse(raw) : []
+      return new Set(Array.isArray(parsed) ? parsed : [])
+    } catch { return new Set() }
+  })
   const [hiddenItems, setHiddenItems] = useState(new Set())
   const { starred, toggle: toggleStar } = useStarred()
   const recentIds = useRecent()
@@ -1314,6 +1321,7 @@ function WorkspaceImpl({
       const next = new Set(prev)
       if (next.has(dirName)) next.delete(dirName)
       else next.add(dirName)
+      try { localStorage.setItem(COLLAPSED_FOLDERS_KEY, JSON.stringify([...next])) } catch { /* empty */ }
       return next
     })
   }, [])

package/src/internals/canvas/CanvasPage.jsx

@@ -10,7 +10,7 @@ import { getFeatures, isResizable, isExpandable, getAnchorState, canAcceptConnec
 import { createPasteContext, resolvePaste } from './widgets/pasteRules.js'
 import { getPasteRules } from '../../core/index.js'
 import { isTerminalResizable, getTerminalDimensions } from '../../core/index.js'
-import { getFlag } from '../../core/index.js'
+import { getFlag, subscribeToStorage } from '../../core/index.js'
 import { getCanvasZoom } from '../../core/index.js'
 import { registerSmoothCorners } from '../../core/utils/smoothCorners.js'
 import { registerHotPoolDevLogs } from './hotPoolDevLogs.js'
@@ -2115,21 +2115,42 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   // Controlled by the "canvas-auto-reload" feature flag (default: false = guard ON).
   // When the flag is true, the guard is skipped so canvas pages receive HMR updates.
   // Sends a heartbeat every 3s so the guard auto-expires if the tab closes.
+  // Re-syncs when the flag is toggled at runtime (e.g. from devtools menu).
   useEffect(() => {
     if (!import.meta.hot) return
-    const autoReload = getFlag('canvas-auto-reload')
-    if (autoReload) return
 
-    const msg = { active: true }
-    import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-    const interval = setInterval(() => {
+    let interval = null
+
+    function start() {
+      if (interval) return
+      const msg = { active: true }
       import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-    }, 3000)
+      interval = setInterval(() => {
+        import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+      }, 3000)
+    }
 
-    return () => {
-      clearInterval(interval)
+    function stop() {
+      if (interval) {
+        clearInterval(interval)
+        interval = null
+      }
       import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false })
     }
+
+    function sync() {
+      if (getFlag('canvas-auto-reload')) stop()
+      else start()
+    }
+
+    sync()
+
+    const unsub = subscribeToStorage(() => sync())
+
+    return () => {
+      stop()
+      unsub()
+    }
   }, [canvasId])
 
   // --- Selected widgets bridge ---

package/src/internals/canvas/WebGLContextPool.jsx

@@ -215,14 +215,13 @@ export function useWebGLSlot(widgetId, initialPriority) {
     [pool, widgetId],
   )
 
-  // When there's no pool provider (e.g. standalone usage), always be live
-  if (!pool || !slot) {
-    return { isLive: true, generation: 0, setPriority: () => {} }
-  }
-
+  // Gating disabled — every widget is always live. The pool still tracks
+  // priority/registration for any future consumer (and so setPriority calls
+  // remain valid), but isLive ignores the cap and viewport demotion entirely.
+  void slot
   return {
-    isLive: slot.live,
-    generation: slot.generation,
+    isLive: true,
+    generation: 0,
     setPriority,
   }
 }

package/src/internals/canvas/componentIsolate.jsx

@@ -68,15 +68,14 @@ const colorMode = theme.startsWith('dark') ? 'night' : 'day'
 document.documentElement.setAttribute('data-color-mode', theme.startsWith('dark') ? 'dark' : 'light')
 document.documentElement.setAttribute('data-dark-theme', theme.startsWith('dark') ? theme : '')
 document.documentElement.setAttribute('data-light-theme', theme.startsWith('dark') ? '' : theme || 'light')
+document.documentElement.setAttribute('data-sb-theme', theme || 'light')
 
-// Suppress HMR full-reloads — this iframe is embedded inside a canvas page
-// that manages its own reload lifecycle. Without this guard, every file change
-// causes the iframe to flash/reload.
-if (import.meta.hot) {
-  const msg = { active: true }
-  import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-  setInterval(() => import.meta.hot.send('storyboard:canvas-hmr-guard', msg), 3000)
-}
+// Note: we deliberately do NOT install the canvas-hmr-guard here. The guard
+// drops BOTH `full-reload` and `update` payloads server-side, which means
+// edits to the story source file never reach this iframe — no Fast Refresh,
+// no reload, nothing. Story widgets are expected to refresh when the
+// underlying .story.jsx is edited, so we let HMR through.
+void import.meta.hot
 
 const root = createRoot(document.getElementById('root'))
 

package/src/internals/canvas/componentSetIsolate.jsx

@@ -240,15 +240,14 @@ const colorMode = theme.startsWith('dark') ? 'night' : 'day'
 document.documentElement.setAttribute('data-color-mode', theme.startsWith('dark') ? 'dark' : 'light')
 document.documentElement.setAttribute('data-dark-theme', theme.startsWith('dark') ? theme : '')
 document.documentElement.setAttribute('data-light-theme', theme.startsWith('dark') ? '' : theme || 'light')
+document.documentElement.setAttribute('data-sb-theme', theme || 'light')
 
-// Suppress HMR full-reloads — this iframe is embedded inside a canvas page
-// that manages its own reload lifecycle. Without this guard, every file change
-// causes the iframe to flash/reload.
-if (import.meta.hot) {
-  const msg = { active: true }
-  import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
-  setInterval(() => import.meta.hot.send('storyboard:canvas-hmr-guard', msg), 3000)
-}
+// Note: we deliberately do NOT install the canvas-hmr-guard here. The guard
+// drops BOTH `full-reload` and `update` payloads server-side, which means
+// edits to the story source file never reach this iframe — no Fast Refresh,
+// no reload, nothing. Story/component-set widgets are expected to refresh
+// when the underlying .story.jsx is edited, so we let HMR through.
+void import.meta.hot
 
 const root = createRoot(document.getElementById('root'))
 

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

@@ -43,6 +43,8 @@ function resolveCanvasThemeFromStorage() {
     window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 }
 
+const HEADER_HEIGHT = 37
+
 export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdate, resizable }, ref) {
   const src = readProp(props, 'src', prototypeEmbedSchema)
   const width = readProp(props, 'width', prototypeEmbedSchema) || 800
@@ -412,7 +414,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                 className={styles.iframe}
                 style={{
                   width: width / scale,
-                  height: height / scale,
+                  height: (height - HEADER_HEIGHT) / scale,
                   transform: `scale(${scale})`,
                   transformOrigin: '0 0',
                 }}

package/src/internals/canvas/widgets/StorySetWidget.jsx

@@ -12,6 +12,7 @@
  */
 import { forwardRef, useImperativeHandle, useRef, useCallback, useState, useEffect, useMemo } from 'react'
 import { getStoryData } from '../../../core/index.js'
+import { useThemeState, useThemeSyncTargets } from '../../hooks/useThemeState.js'
 import Icon from '../../Icon.jsx'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
@@ -26,16 +27,23 @@ function GridIcon({ size = 16 }) {
   return <Icon name="iconoir/view-grid" size={size} />
 }
 
-function resolveStorySetUrl(storyId, layout, selected, density) {
+function resolveStorySetUrl(storyId, layout, selected, density, theme) {
   const story = getStoryData(storyId)
   if (!story?._storyModule) return ''
   const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
   const params = new URLSearchParams()
-  params.set('module', story._storyModule)
+  // Route via the real story page (works in dev AND prod). The dev-only
+  // `_storyboard/canvas/isolate-set` middleware doesn't exist in deployed
+  // builds, so we mount ComponentSetPage at the story's route with
+  // `_sb_component_set` instead. `_sb_embed` keeps the canvas chrome off.
+  params.set('_sb_embed', '')
+  params.set('_sb_component_set', '')
   if (layout) params.set('layout', layout)
   if (selected) params.set('selected', selected)
   if (density) params.set('density', density)
-  return `${base}/_storyboard/canvas/isolate-set?${params}`
+  if (theme) params.set('theme', theme)
+  const route = story._route || `/components/${storyId}`
+  return `${base}${route}?${params}`
 }
 
 export default forwardRef(function StorySetWidget({ id: widgetId, props, onUpdate, resizable }, ref) {
@@ -101,7 +109,7 @@ export default forwardRef(function StorySetWidget({ id: widgetId, props, onUpdat
         if (typeof width === 'number' && typeof height === 'number') return
         const headerH = 37
         const newW = typeof width === 'number' ? width : Math.max(200, Math.ceil(e.data.width))
-        const newH = typeof height === 'number' ? height : Math.max(120, Math.ceil(e.data.height) + headerH)
+        const newH = typeof height === 'number' ? height : Math.max(120, Math.ceil(e.data.height) + headerH + 8)
         onUpdate?.({ width: newW, height: newH })
       } else if (e.data?.type === 'storyboard:component-set:content-size') {
         contentSizeRef.current = {
@@ -126,7 +134,7 @@ export default forwardRef(function StorySetWidget({ id: widgetId, props, onUpdat
     const contentH = contentSizeRef.current.height
     const contentW = contentSizeRef.current.width
     if (!contentH && !contentW) return
-    const fitH = contentH ? contentH + headerH : h
+    const fitH = contentH ? contentH + headerH + 8 : h
     const fitW = contentW || w
     const shouldSnapH = contentH && h > fitH + 2
     const shouldSnapW = contentW && w > fitW + 2
@@ -163,11 +171,15 @@ export default forwardRef(function StorySetWidget({ id: widgetId, props, onUpdat
     },
   }), [storyId, layout, onUpdate, setExpanded])
 
+  const { resolved: resolvedTheme } = useThemeState() || {}
+  const { prototype: prototypeSync } = useThemeSyncTargets() || {}
+  const effectiveTheme = prototypeSync ? (resolvedTheme || 'light') : 'light'
+
   const iframeSrc = useMemo(
-    () => resolveStorySetUrl(storyId, layout, selected, density),
+    () => resolveStorySetUrl(storyId, layout, selected, density, effectiveTheme),
     // storyIndexKey forces re-evaluation when HMR mutates the story index
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [storyId, layout, selected, density, storyIndexKey],
+    [storyId, layout, selected, density, storyIndexKey, effectiveTheme],
   )
 
   useIframeDevLogs({

package/src/internals/canvas/widgets/StoryWidget.jsx

@@ -10,6 +10,7 @@
  */
 import { forwardRef, useImperativeHandle, useRef, useCallback, useState, useEffect, useMemo } from 'react'
 import { getStoryData } from '../../../core/index.js'
+import { useThemeState, useThemeSyncTargets } from '../../hooks/useThemeState.js'
 import { getConfig } from '../../../core/stores/configStore.js'
 import { createInspectorHighlighter } from '../../../core/inspector/highlighter.js'
 import Icon from '../../Icon.jsx'
@@ -42,13 +43,14 @@ function isInlineStoriesEnabled() {
   } catch { return false }
 }
 
-function resolveStoryUrl(storyId, exportName) {
+function resolveStoryUrl(storyId, exportName, theme) {
   const story = getStoryData(storyId)
   if (!story?._storyModule) return ''
   const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
   const params = new URLSearchParams()
   params.set('module', story._storyModule)
   if (exportName) params.set('export', exportName)
+  if (theme) params.set('theme', theme)
   return `${base}/_storyboard/canvas/isolate?${params}`
 }
 
@@ -194,9 +196,13 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
     },
   }), [storyId, showCode, toggleShowCode, copyCode, setExpandMode])
 
+  const { resolved: resolvedTheme } = useThemeState() || {}
+  const { prototype: prototypeSync } = useThemeSyncTargets() || {}
+  const effectiveTheme = prototypeSync ? (resolvedTheme || 'light') : 'light'
+
   const iframeSrc = useMemo(
-    () => resolveStoryUrl(storyId, exportName),
-    [storyId, exportName, storyIndexKey],
+    () => resolveStoryUrl(storyId, exportName, effectiveTheme),
+    [storyId, exportName, storyIndexKey, effectiveTheme],
   )
 
   const inlineEnabled = isInlineStoriesEnabled()

package/src/internals/canvas/widgets/TerminalWidget.jsx

@@ -180,14 +180,34 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
   const [waking, setWaking] = useState(false)
   const [resourceLimited, setResourceLimited] = useState(null)
   const [showDragHint, setShowDragHint] = useState(false)
+  // Set when the browser refuses to grant a WebGL context (hard limit ~8–16
+  // contexts depending on browser) or when an existing context is lost.
+  // Flips the widget back to the frozen overlay so it degrades gracefully
+  // instead of rendering as a broken/blank canvas.
+  const [webglUnavailable, setWebglUnavailable] = useState(false)
   const expandContainerRef = useRef(null)
   const dragHintTimer = useRef(null)
 
   // ── WebGL context pool integration ──
-  // webglReady: PINNED (bypass cap, guaranteed live — no frozen flash)
-  // All others: VISIBLE (auto-requests a live slot — no manual click needed)
-  const initialPriority = props?.webglReady ? Priority.PINNED : Priority.VISIBLE
-  const { isLive, generation, setPriority } = useWebGLSlot(id, initialPriority)
+  // All freshly-mounted terminals start at PINNED so they bypass the pool
+  // cap and come up live immediately — otherwise a new spawn loses the
+  // tiebreak against existing live widgets (stable sort, equal lastVisible)
+  // and renders the frozen "Click to resume" overlay even though tmux is
+  // running. After SPAWN_GRACE_MS the priority is handed back to
+  // usePoolVisibilityUpdater (CanvasPage) which manages VISIBLE/NEAR/OFFSCREEN
+  // based on viewport overlap.
+  const SPAWN_GRACE_MS = 5000
+  const { isLive, generation, setPriority } = useWebGLSlot(id, Priority.PINNED)
+
+  // Release the spawn-grace pin after the window expires, unless the
+  // widget is currently expanded/interactive (those keep it PINNED).
+  useEffect(() => {
+    const t = setTimeout(() => {
+      if (!expanded && !interactive) setPriority(Priority.VISIBLE)
+    }, SPAWN_GRACE_MS)
+    return () => clearTimeout(t)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
 
   // Update pool priority based on widget state
   useEffect(() => {
@@ -199,6 +219,10 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
 
   // Request activation when user clicks a frozen terminal
   const handleFrozenActivate = useCallback(() => {
+    // Clear any prior browser-WebGL-exhaustion flag and retry — the user
+    // may have closed other widgets/tabs since the original failure.
+    setWebglUnavailable(false)
+    setConnectAttempt((n) => n + 1)
     setPriority(Priority.PINNED)
   }, [setPriority])
 
@@ -269,6 +293,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
   // Connect terminal + WebSocket (only when pool grants a live slot)
   useEffect(() => {
     if (!isLive) return
+    if (webglUnavailable) return
     if (!containerRef.current) return
 
     let disposed = false
@@ -309,7 +334,43 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
           theme: { ...DEFAULT_THEME, ...cfg.theme },
         })
 
-        term.open(containerRef.current)
+        try {
+          term.open(containerRef.current)
+        } catch (openErr) {
+          // Most commonly the browser refusing to allocate yet another
+          // WebGL context (hard cap ~8–16). Degrade to the frozen overlay
+          // instead of leaving a blank canvas behind.
+          console.warn('[TerminalWidget] ghostty.open failed — falling back to frozen overlay:', openErr)
+          try { term.dispose?.() } catch { /* empty */ }
+          term = null
+          termRef.current = null
+          if (!disposed) setWebglUnavailable(true)
+          return
+        }
+
+        // If ghostty silently failed to obtain a WebGL renderer, treat
+        // the same as a browser-cap miss and show the frozen overlay.
+        if (!term.renderer) {
+          console.warn('[TerminalWidget] ghostty has no renderer (likely WebGL exhausted) — frozen fallback')
+          try { term.dispose?.() } catch { /* empty */ }
+          term = null
+          termRef.current = null
+          if (!disposed) setWebglUnavailable(true)
+          return
+        }
+
+        // Listen for the browser killing this WebGL context later (it
+        // does this LRU-style when other tabs/widgets need a slot).
+        const canvas = containerRef.current?.querySelector('canvas')
+        if (canvas) {
+          const onLost = (e) => {
+            e.preventDefault?.()
+            console.warn('[TerminalWidget] WebGL context lost — frozen fallback')
+            if (!disposed) setWebglUnavailable(true)
+          }
+          canvas.addEventListener('webglcontextlost', onLost, { once: true })
+        }
+
         termRef.current = term
 
         // Expose ghostty's actual computed cell metrics as CSS variables
@@ -411,7 +472,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
       setReady(false)
       setRevealed(false)
     }
-  }, [id, isLive, generation, connectAttempt])
+  }, [id, isLive, generation, connectAttempt, webglUnavailable])
 
   // Resize terminal on dimension changes
   useEffect(() => {
@@ -604,19 +665,19 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
         ref={terminalRef}
         className={styles.terminal}
         style={{
-          ...(typeof (isLive ? (snappedWidth ?? width) : width) === 'number'
-            ? { width: `${isLive ? (snappedWidth ?? width) : width}px` }
+          ...(typeof ((isLive && !webglUnavailable) ? (snappedWidth ?? width) : width) === 'number'
+            ? { width: `${(isLive && !webglUnavailable) ? (snappedWidth ?? width) : width}px` }
             : undefined),
-          ...(typeof (isLive ? (snappedHeight ?? height) : height) === 'number'
-            ? { height: `${isLive ? (snappedHeight ?? height) : height}px` }
+          ...(typeof ((isLive && !webglUnavailable) ? (snappedHeight ?? height) : height) === 'number'
+            ? { height: `${(isLive && !webglUnavailable) ? (snappedHeight ?? height) : height}px` }
             : undefined),
         }}
         onClick={handleClick}
         onPointerDown={handleTerminalPointerDown}
         onKeyDown={interactive ? (e) => e.stopPropagation() : undefined}
       >
-        {/* ── Frozen state: WebGL context released, show snapshot ── */}
-        {!isLive && (
+        {/* ── Frozen state: WebGL context released or unavailable ── */}
+        {(!isLive || webglUnavailable) && (
           <FrozenTerminalOverlay
             widgetId={id}
             onActivate={handleFrozenActivate}
@@ -624,7 +685,7 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
         )}
 
         {/* ── Live state: ghostty WebGL terminal ── */}
-        {isLive && (
+        {isLive && !webglUnavailable && (
           <>
             {showDragHint && (
               <div className={styles.dragHint}>

package/src/internals/canvas/widgets/expandUtils.js

@@ -513,12 +513,14 @@ export function buildSecondaryIframeUrl(widget) {
     const storyData = getStoryData(storyId)
     if (storyData?._storyModule) {
       const params = new URLSearchParams()
-      params.set('module', storyData._storyModule)
+      params.set('_sb_embed', '')
+      params.set('_sb_component_set', '')
       const layout = widget.props?.layout
       if (layout) params.set('layout', layout)
       const selected = widget.props?.selected
       if (selected) params.set('selected', selected)
-      return `${baseClean}/_storyboard/canvas/isolate-set?${params}`
+      const route = storyData._route || `/components/${storyId}`
+      return `${baseClean}${route}?${params}`
     }
     return null
   }