@dfosco/storyboard-react 4.2.4 → 4.2.6

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "4.2.4",
+  "version": "4.2.6",
   "type": "module",
   "dependencies": {
     "@base-ui/react": "^1.4.0",
-    "@dfosco/storyboard-core": "4.2.4",
-    "@dfosco/tiny-canvas": "4.2.4",
+    "@dfosco/storyboard-core": "4.2.6",
+    "@dfosco/tiny-canvas": "4.2.6",
     "@neodrag/react": "^2.3.1",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-visually-hidden": "^1.2.4",

package/src/CommandPalette/CommandPalette.jsx

@@ -56,6 +56,31 @@ function AvatarIcon({ username }) {
   )
 }
 
+/**
+ * Alt-reactive label for the "Hide toolbars" command palette item.
+ * Shows "Completely hide toolbars" when alt is held, "Hide toolbars" otherwise.
+ */
+function HideToolbarsLabel({ isHidden }) {
+  const [altHeld, setAltHeld] = useState(false)
+  useEffect(() => {
+    const onKey = (e) => setAltHeld(e.altKey)
+    const onUp = () => setAltHeld(false)
+    document.addEventListener('keydown', onKey, true)
+    document.addEventListener('keyup', onUp, true)
+    return () => {
+      document.removeEventListener('keydown', onKey, true)
+      document.removeEventListener('keyup', onUp, true)
+    }
+  }, [])
+
+  return (
+    <span style={{ display: 'flex', width: '100%', justifyContent: 'space-between', alignItems: 'center' }}>
+      <span>{altHeld ? 'Completely hide toolbars' : 'Hide toolbars'}</span>
+      <span>{isHidden ? '✓' : ''}</span>
+    </span>
+  )
+}
+
 /**
  * Check if a tool should be hidden from the command palette on the current route.
  * Uses the same pattern-matching logic as excludeRoutes.
@@ -228,11 +253,16 @@ function buildConfigSections(prefix, onNavigateToPage, onCreateAction) {
         remainingItems.push({
           id: `cfg:${section.id}:${toolId}`,
           children: label,
-          keywords: [label, toolId, 'hide', 'show', 'toolbar'].filter(Boolean),
+          keywords: [label, toolId, 'hide', 'show', 'toolbar', 'completely'].filter(Boolean),
           showType: false,
           onClick: () => {
+            document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
             document.documentElement.classList.toggle('storyboard-chrome-hidden')
           },
+          onAltClick: () => {
+            document.documentElement.classList.add('storyboard-chrome-hidden')
+            document.documentElement.classList.add('storyboard-chrome-completely-hidden')
+          },
         })
         continue
       }
@@ -254,19 +284,17 @@ function buildConfigSections(prefix, onNavigateToPage, onCreateAction) {
           onClick: () => { window.location.href = resolvedUrl },
         })
       } else {
-        // Menu tools: close palette and click the toolbar button to open the menu
+        // Menu tools: close palette and dispatch event to open the toolbar menu
         if (tool.render === 'menu') {
-          const ariaLabel = tool.ariaLabel || tool.label || toolId
+          const handlerId = tool.handler || `core:${toolId}`
           remainingItems.push({
             id: `cfg:${section.id}:${toolId}`,
             children: label,
             keywords: [label, toolId].filter(Boolean),
             showType: false,
             onClick: () => {
-              // Find and click the toolbar button
               setTimeout(() => {
-                const btn = document.querySelector(`[aria-label="${ariaLabel}"]`)
-                if (btn) btn.click()
+                window.dispatchEvent(new CustomEvent('storyboard:open-tool-menu', { detail: { action: handlerId } }))
               }, 100)
             },
           })
@@ -549,7 +577,7 @@ function buildDynamicSection(section, prefix, onNavigateToPage, onCreateAction)
     const pushProtoFlows = (p) => {
       if (p.isExternal) {
         sourceItems.push({ name: p.name, route: p.externalUrl, id: p.dirName, type: 'prototype', isExternal: true })
-      } else if (p.hideFlows || p.flows.length <= 1) {
+      } else if (p.flows.length <= 1) {
         const route = p.flows.length === 1 ? `${prefix}${p.flows[0].route}` : `${prefix}/${p.dirName}`
         sourceItems.push({ name: p.name, route, id: p.dirName, type: 'prototype' })
       } else {
@@ -668,17 +696,19 @@ function buildToolsSection(section, prefix, onNavigateToPage) {
       const isHidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
       items.push({
         id: `cfg:${section.id}:${toolId}`,
-        toolIcon: isHidden ? 'primer/light-bulb' : 'primer/light-bulb',
-        children: <span style={{ display: 'flex', width: '100%', justifyContent: 'space-between', alignItems: 'center' }}>
-          <span>Hide toolbars</span>
-          <span>{isHidden ? '✓' : ''}</span>
-        </span>,
-        keywords: [label, toolId, 'hide', 'show', 'toolbar'].filter(Boolean),
+        toolIcon: 'primer/light-bulb',
+        children: <HideToolbarsLabel isHidden={isHidden} />,
+        keywords: [label, toolId, 'hide', 'show', 'toolbar', 'completely'].filter(Boolean),
         showType: false,
         closeOnSelect: entryCloseOnSelect,
         onClick: () => {
+          document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
           document.documentElement.classList.toggle('storyboard-chrome-hidden')
         },
+        onAltClick: () => {
+          document.documentElement.classList.add('storyboard-chrome-hidden')
+          document.documentElement.classList.add('storyboard-chrome-completely-hidden')
+        },
       })
       continue
     }
@@ -1220,7 +1250,7 @@ export default function StoryboardCommandPalette({ basePath }) {
                 !search && <Command.Separator key={list.id} />
               ) : (
                 <Command.Group key={list.id} heading={list.heading}>
-                  {list.items.map(({ id, children, keywords, onClick, itemType, toolIcon, toolMeta, closeOnSelect, hideFromSearch, url }) => {
+                  {list.items.map(({ id, children, keywords, onClick, onAltClick, itemType, toolIcon, toolMeta, closeOnSelect, hideFromSearch, url }) => {
                     if (search && hideFromSearch) return null
                     if (hiddenFromSearchIds.size > 0) {
                       for (const toolId of hiddenFromSearchIds) {
@@ -1236,6 +1266,8 @@ export default function StoryboardCommandPalette({ basePath }) {
                             copyLinkToClipboard(url, itemType)
                           } else if (url && modifierHeldRef.current) {
                             window.open(url, '_blank')
+                          } else if (onAltClick && altHeldRef.current) {
+                            onAltClick()
                           } else {
                             onClick?.()
                           }

package/src/Viewfinder.jsx

@@ -1100,10 +1100,13 @@ export default function Workspace({
 
     // Prototypes (ungrouped + from folders)
     const addProto = (proto) => {
-      // For prototypes with flows, use the first flow's route
-      const route = proto.flows?.length > 0
-        ? proto.flows[0].route
-        : `/${proto.dirName}`
+      // Prefer a flow marked as default, fall back to the first flow
+      const defaultFlow = proto.flows?.find(f => f.meta?.default === true)
+      const route = defaultFlow
+        ? defaultFlow.route
+        : proto.flows?.length > 0
+          ? proto.flows[0].route
+          : `/${proto.dirName}`
 
       items.push({
         id: `proto:${proto.dirName}`,

package/src/canvas/CanvasPage.jsx

@@ -15,6 +15,7 @@ import { getCanvasZoom } from '@dfosco/storyboard-core'
 import { registerSmoothCorners } from '@dfosco/storyboard-core/smooth-corners'
 import { registerHotPoolDevLogs } from './hotPoolDevLogs.js'
 import { isGitHubEmbedUrl } from './widgets/githubUrl.js'
+import { WebGLContextPoolProvider, usePoolVisibilityUpdater } from './WebGLContextPool.jsx'
 
 import WidgetChrome from './widgets/WidgetChrome.jsx'
 import ComponentWidget from './widgets/ComponentWidget.jsx'
@@ -1086,6 +1087,9 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         position,
       })
       if (result.success && result.widget) {
+        if (result.hotSession?.webglReady) {
+          result.widget.props = { ...result.widget.props, webglReady: true }
+        }
         setLocalWidgets((prev) => [...(prev || []), result.widget])
         setSelectedWidgetIds(new Set([result.widget.id]))
       }
@@ -1239,6 +1243,9 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           position,
         })
         if (result.success && result.widget) {
+          if (result.hotSession?.webglReady) {
+            result.widget.props = { ...result.widget.props, webglReady: true }
+          }
           newWidgets.push(result.widget)
         }
       } catch (err) {
@@ -1996,6 +2003,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         position: pos,
       })
       if (result.success && result.widget) {
+        // Hot pool WebGL-ready flag: add to props so TerminalWidget starts PINNED
+        if (result.hotSession?.webglReady) {
+          result.widget.props = { ...result.widget.props, webglReady: true }
+        }
         undoRedo.snapshot(stateRef.current, 'add')
         setLocalWidgets((prev) => [...(prev || []), result.widget])
         setSelectedWidgetIds(new Set([result.widget.id]))
@@ -2190,6 +2201,50 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     window[CANVAS_BRIDGE_STATE_KEY] = bridge
   }, [localWidgets, localConnectors])
 
+  // ── WebGL context pool: viewport-based visibility tracking ──
+  const updatePoolVisibility = usePoolVisibilityUpdater()
+  const poolRafRef = useRef(null)
+
+  // Compute viewport rect in canvas coordinates and update terminal priorities
+  const syncPoolVisibility = useCallback(() => {
+    const el = scrollRef.current
+    if (!el || !localWidgets) return
+    const currentZoom = zoomRef.current || 100
+    const currentScale = currentZoom / 100
+    const viewportRect = {
+      x: el.scrollLeft / currentScale,
+      y: el.scrollTop / currentScale,
+      w: el.clientWidth / currentScale,
+      h: el.clientHeight / currentScale,
+    }
+    updatePoolVisibility(viewportRect, localWidgets, selectedWidgetIds, null)
+  }, [updatePoolVisibility, localWidgets, selectedWidgetIds])
+
+  // Throttle visibility updates via rAF on scroll
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    function onScroll() {
+      if (poolRafRef.current) return
+      poolRafRef.current = requestAnimationFrame(() => {
+        poolRafRef.current = null
+        syncPoolVisibility()
+      })
+    }
+    el.addEventListener('scroll', onScroll, { passive: true })
+    // Initial sync
+    syncPoolVisibility()
+    return () => {
+      el.removeEventListener('scroll', onScroll)
+      if (poolRafRef.current) cancelAnimationFrame(poolRafRef.current)
+    }
+  }, [syncPoolVisibility])
+
+  // Re-sync on zoom changes
+  useEffect(() => {
+    syncPoolVisibility()
+  }, [zoom, syncPoolVisibility])
+
   // Delete selected widget on Delete/Backspace key
   useEffect(() => {
     function handleSelectStart(e) {
@@ -2427,6 +2482,9 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
               position: { x: baseX + relX, y: baseY + relY },
             })
             if (result.success && result.widget) {
+              if (result.hotSession?.webglReady) {
+                result.widget.props = { ...result.widget.props, webglReady: true }
+              }
               newWidgets.push(result.widget)
             }
           }
@@ -2954,7 +3012,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   const filteredConnectors = localConnectors
 
   return (
-    <>
+    <WebGLContextPoolProvider>
       <div className={styles.canvasTitle}>
         <a href={(import.meta.env?.BASE_URL || '/')} className={styles.canvasLogo} aria-label="Go to homepage">
           <Icon name="home" size={16} color="#fff" />
@@ -3029,6 +3087,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           </button>
         </aside>
       )}
-    </>
+    </WebGLContextPoolProvider>
   )
 }

package/src/canvas/WebGLContextPool.jsx

@@ -0,0 +1,292 @@
+import { createContext, useContext, useCallback, useEffect, useMemo, useSyncExternalStore } from 'react'
+
+/**
+ * WebGL Context Pool — manages live WebGL slots for terminal widgets.
+ *
+ * Browsers cap WebGL contexts at ~8-16. This pool ensures only a subset
+ * of terminal widgets hold live ghostty-web renderers at any time.
+ * Offscreen terminals release their context and show a frozen snapshot.
+ *
+ * Architecture:
+ * - Lease-based: widgets register and receive live/frozen status
+ * - Priority: PINNED > VISIBLE > NEAR_VIEWPORT > OFFSCREEN
+ * - Hysteresis: 3s grace before evicting recently-visible terminals
+ * - Generation tokens prevent stale async opens after eviction
+ */
+
+// Priority levels (higher = more important to keep live)
+export const Priority = {
+  OFFSCREEN: 0,
+  NEAR_VIEWPORT: 1,
+  VISIBLE: 2,
+  PINNED: 3, // expanded, focused, or actively interacting
+}
+
+const DEFAULT_MAX_LIVE = 6
+const HYSTERESIS_MS = 3000
+
+// ── Pool Engine (framework-agnostic) ─────────────────────────────────
+
+class ContextPool {
+  constructor(maxLive = DEFAULT_MAX_LIVE) {
+    this._maxLive = maxLive
+    /** @type {Map<string, { priority: number, generation: number, live: boolean, lastVisible: number }>} */
+    this._slots = new Map()
+    this._listeners = new Set()
+    this._hysteresisTimers = new Map()
+    // Monotonic version counter — bumped on every state change so
+    // useSyncExternalStore detects updates via a new snapshot value.
+    this._version = 0
+  }
+
+  /** Subscribe to pool state changes. Returns unsubscribe fn. */
+  subscribe(listener) {
+    this._listeners.add(listener)
+    return () => this._listeners.delete(listener)
+  }
+
+  _notify() {
+    this._version++
+    for (const fn of this._listeners) fn()
+  }
+
+  /** Register a widget. Returns its initial generation. */
+  register(widgetId, initialPriority = Priority.OFFSCREEN) {
+    if (this._slots.has(widgetId)) return this._slots.get(widgetId).generation
+    this._slots.set(widgetId, {
+      priority: initialPriority,
+      generation: 0,
+      live: false,
+      lastVisible: initialPriority >= Priority.VISIBLE ? Date.now() : 0,
+    })
+    this._recompute()
+    return 0
+  }
+
+  /** Unregister a widget (on unmount). */
+  unregister(widgetId) {
+    this._slots.delete(widgetId)
+    const timer = this._hysteresisTimers.get(widgetId)
+    if (timer) { clearTimeout(timer); this._hysteresisTimers.delete(widgetId) }
+    this._recompute()
+  }
+
+  /** Update a widget's priority. Triggers recomputation. */
+  setPriority(widgetId, priority) {
+    const slot = this._slots.get(widgetId)
+    if (!slot) return
+    const prev = slot.priority
+    slot.priority = priority
+
+    // Track when widget was last visible/pinned for hysteresis
+    if (priority >= Priority.VISIBLE) {
+      slot.lastVisible = Date.now()
+    }
+
+    // Immediate recompute when priority increases or widget is pinned
+    if (priority > prev || priority === Priority.PINNED) {
+      this._recompute()
+      return
+    }
+
+    // When priority drops (e.g. scrolled offscreen), use hysteresis
+    if (priority < prev && prev >= Priority.VISIBLE) {
+      const existing = this._hysteresisTimers.get(widgetId)
+      if (existing) clearTimeout(existing)
+      this._hysteresisTimers.set(widgetId, setTimeout(() => {
+        this._hysteresisTimers.delete(widgetId)
+        this._recompute()
+      }, HYSTERESIS_MS))
+      return
+    }
+
+    this._recompute()
+  }
+
+  /** Get current state for a widget. */
+  getSlot(widgetId) {
+    return this._slots.get(widgetId) || null
+  }
+
+  /**
+   * Recompute which widgets should be live.
+   * Sorts by priority (desc), then by lastVisible (desc).
+   * Top N get live status; rest are frozen.
+   */
+  _recompute() {
+    const entries = [...this._slots.entries()]
+
+    // Sort: pinned first, then by priority desc, then by recency
+    entries.sort(([, a], [, b]) => {
+      if (a.priority !== b.priority) return b.priority - a.priority
+      return b.lastVisible - a.lastVisible
+    })
+
+    let liveCount = 0
+    const changes = []
+
+    for (const [id, slot] of entries) {
+      // Pinned terminals always get a slot (they bypass the cap)
+      const shouldBeLive = slot.priority === Priority.PINNED || liveCount < this._maxLive
+      if (shouldBeLive) liveCount++
+
+      if (slot.live !== shouldBeLive) {
+        changes.push({ id, slot, shouldBeLive })
+      }
+    }
+
+    if (changes.length === 0) return
+
+    for (const { slot, shouldBeLive } of changes) {
+      slot.live = shouldBeLive
+      if (!shouldBeLive) {
+        // Bump generation so stale async opens abort
+        slot.generation++
+      }
+    }
+
+    this._notify()
+  }
+}
+
+// ── React Context ────────────────────────────────────────────────────
+
+const WebGLPoolContext = createContext(null)
+
+/**
+ * Provider that creates and owns the context pool.
+ * Place this around the canvas widget tree in CanvasPage.
+ *
+ * @param {{ maxLive?: number, children: React.ReactNode }} props
+ */
+export function WebGLContextPoolProvider({ maxLive = DEFAULT_MAX_LIVE, children }) {
+  // useMemo is correct here: the pool is a stable singleton for this provider's lifetime.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const pool = useMemo(() => new ContextPool(maxLive), [])
+  return (
+    <WebGLPoolContext.Provider value={pool}>
+      {children}
+    </WebGLPoolContext.Provider>
+  )
+}
+
+/**
+ * Hook that manages a terminal widget's WebGL slot lifecycle.
+ *
+ * Returns:
+ * - `isLive`: whether this widget should create a live ghostty terminal
+ * - `generation`: counter that increments on each live→frozen transition;
+ *   use as an effect dep to detect when to re-create the terminal
+ * - `setPriority(p)`: update this widget's priority
+ *
+ * @param {string} widgetId
+ * @returns {{ isLive: boolean, generation: number, setPriority: (p: number) => void }}
+ */
+export function useWebGLSlot(widgetId, initialPriority) {
+  const pool = useContext(WebGLPoolContext)
+
+  // Register on mount, unregister on unmount
+  useEffect(() => {
+    if (!pool) return
+    pool.register(widgetId, initialPriority)
+    return () => pool.unregister(widgetId)
+  }, [pool, widgetId]) // initialPriority intentionally excluded — only used on first register
+
+  // Subscribe to pool state for reactivity.
+  // getSnapshot returns the pool's version counter — a primitive that changes
+  // on every state mutation, satisfying useSyncExternalStore's identity check.
+  const subscribe = useCallback(
+    (cb) => pool ? pool.subscribe(cb) : () => {},
+    [pool],
+  )
+  const getSnapshot = useCallback(() => {
+    if (!pool) return -1
+    return pool._version
+  }, [pool])
+
+  // This triggers re-render whenever the pool version changes
+  useSyncExternalStore(subscribe, getSnapshot)
+
+  // Read the actual slot state (after subscription ensures freshness)
+  const slot = pool?.getSlot(widgetId)
+
+  const setPriority = useCallback(
+    (p) => pool?.setPriority(widgetId, p),
+    [pool, widgetId],
+  )
+
+  // When there's no pool provider (e.g. standalone usage), always be live
+  if (!pool || !slot) {
+    return { isLive: true, generation: 0, setPriority: () => {} }
+  }
+
+  return {
+    isLive: slot.live,
+    generation: slot.generation,
+    setPriority,
+  }
+}
+
+/**
+ * Hook for CanvasPage to batch-update visibility for all terminal widgets.
+ * Call this with the current viewport rect and widget positions.
+ *
+ * @returns {(viewportRect: {x:number,y:number,w:number,h:number}, widgets: Array<{id:string,type:string,position:{x:number,y:number},props?:object}>, selectedIds: Set<string>, expandedId: string|null) => void}
+ */
+export function usePoolVisibilityUpdater() {
+  const pool = useContext(WebGLPoolContext)
+
+  return useCallback((viewportRect, widgets, selectedIds, expandedId) => {
+    if (!pool) return
+
+    const NEAR_MARGIN = 400 // canvas-space pixels for "near viewport" zone
+
+    const terminalTypes = new Set(['terminal', 'agent', 'prompt'])
+
+    for (const w of widgets) {
+      if (!terminalTypes.has(w.type)) continue
+
+      // Determine priority
+      if (w.id === expandedId) {
+        pool.setPriority(w.id, Priority.PINNED)
+        continue
+      }
+
+      if (selectedIds?.has(w.id)) {
+        pool.setPriority(w.id, Priority.PINNED)
+        continue
+      }
+
+      const wx = w.position?.x ?? 0
+      const wy = w.position?.y ?? 0
+      const ww = w.props?.width ?? 800
+      const wh = w.props?.height ?? 450
+
+      // Check overlap with viewport
+      const visible = rectsOverlap(
+        viewportRect.x, viewportRect.y, viewportRect.w, viewportRect.h,
+        wx, wy, ww, wh,
+      )
+
+      if (visible) {
+        pool.setPriority(w.id, Priority.VISIBLE)
+        continue
+      }
+
+      // Check overlap with expanded viewport (near margin)
+      const near = rectsOverlap(
+        viewportRect.x - NEAR_MARGIN,
+        viewportRect.y - NEAR_MARGIN,
+        viewportRect.w + NEAR_MARGIN * 2,
+        viewportRect.h + NEAR_MARGIN * 2,
+        wx, wy, ww, wh,
+      )
+
+      pool.setPriority(w.id, near ? Priority.NEAR_VIEWPORT : Priority.OFFSCREEN)
+    }
+  }, [pool])
+}
+
+function rectsOverlap(ax, ay, aw, ah, bx, by, bw, bh) {
+  return ax < bx + bw && ax + aw > bx && ay < by + bh && ay + ah > by
+}