@dfosco/storyboard-react 4.2.4 → 4.2.5

package/src/canvas/widgets/TerminalWidget.jsx

@@ -5,6 +5,8 @@ import { getTerminalConfig, getTerminalDimensions } from '@dfosco/storyboard-cor
 import { useOverride } from '../../hooks/useOverride.js'
 import { getSplitPaneLabel, findAllConnectedSplitTargets, buildPaneForWidget, buildSplitLayout } from './expandUtils.js'
 import ExpandedPane from './ExpandedPane.jsx'
+import { useWebGLSlot, Priority } from '../WebGLContextPool.jsx'
+import FrozenTerminalOverlay from './FrozenTerminalOverlay.jsx'
 import styles from './TerminalWidget.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
@@ -106,17 +108,16 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
   const cfg = getTerminalConfig()
   const fontSize = cfg.fontSize ?? 13
   const agentId = props?.agentId || null
+  // Config dimensions are authoritative — always use them as the base
   const dims = getTerminalDimensions(agentId, {
     width: readProp(props, 'width', terminalSchema),
     height: readProp(props, 'height', terminalSchema),
   })
-  const rawWidth = props?.width ?? dims.width
-  const rawHeight = props?.height ?? dims.height
+  const width = dims.width
+  const height = dims.height
   const prettyName = props?.prettyName || null
   const startupCommand = props?.startupCommand || null
 
-  const width = rawWidth
-  const height = rawHeight
   // Snapped dimensions computed from ghostty's actual cell metrics (set after open)
   const [snappedHeight, setSnappedHeight] = useState(null)
   const [snappedWidth, setSnappedWidth] = useState(null)
@@ -145,6 +146,25 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
   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)
+
+  // Update pool priority based on widget state
+  useEffect(() => {
+    if (expanded || interactive) {
+      setPriority(Priority.PINNED)
+    }
+    // Priority for VISIBLE/NEAR/OFFSCREEN is set by CanvasPage via usePoolVisibilityUpdater
+  }, [expanded, interactive, setPriority])
+
+  // Request activation when user clicks a frozen terminal
+  const handleFrozenActivate = useCallback(() => {
+    setPriority(Priority.PINNED)
+  }, [setPriority])
+
   useImperativeHandle(ref, () => ({
     handleAction(actionId) {
       if (actionId === 'expand') { setExpanded('single'); return true }
@@ -179,8 +199,9 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
     if (multiSelected && interactive) setInteractive(false)
   }, [multiSelected])
 
-  // Connect terminal + WebSocket
+  // Connect terminal + WebSocket (only when pool grants a live slot)
   useEffect(() => {
+    if (!isLive) return
     if (!containerRef.current) return
 
     let disposed = false
@@ -308,8 +329,10 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
       if (term) term.dispose()
       termRef.current = null
       wsRef.current = null
+      setReady(false)
+      setRevealed(false)
     }
-  }, [id, connectAttempt])
+  }, [id, isLive, generation, connectAttempt])
 
   // Resize terminal on dimension changes
   useEffect(() => {
@@ -472,112 +495,135 @@ export default forwardRef(function TerminalWidget({ id, props, onUpdate, multiSe
         ref={terminalRef}
         className={styles.terminal}
         style={{
-          ...(typeof (snappedWidth ?? width) === 'number' ? { width: `${snappedWidth ?? width}px` } : undefined),
-          ...(typeof (snappedHeight ?? height) === 'number' ? { height: `${snappedHeight ?? height}px` } : undefined),
+          ...(typeof (isLive ? (snappedWidth ?? width) : width) === 'number'
+            ? { width: `${isLive ? (snappedWidth ?? width) : width}px` }
+            : undefined),
+          ...(typeof (isLive ? (snappedHeight ?? height) : height) === 'number'
+            ? { height: `${isLive ? (snappedHeight ?? height) : height}px` }
+            : undefined),
         }}
         onClick={handleClick}
         onPointerDown={handleTerminalPointerDown}
         onKeyDown={interactive ? (e) => e.stopPropagation() : undefined}
       >
-        {showDragHint && (
-          <div className={styles.dragHint}>
-            <span className={styles.dragHintArrow}>←</span> Drag here to move widget
-          </div>
-        )}
-        {error && !sessionEnded && (
-          <div className={styles.error}>
-            <span>⚠ {error}</span>
-          </div>
-        )}
-        <div ref={containerRef} className={styles.xtermContainer} style={{ opacity: revealed ? 1 : 0 }} />
-
-        {/* Live but not interactive */}
-        {revealed && !interactive && !sessionEnded && (
-          <div
-            className={overlayStyles.interactOverlay}
-            style={{ backgroundColor: 'transparent' }}
-            onClick={(e) => {
-              if (multiSelected || e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
-              setInteractive(true)
-              termRef.current?.focus({ preventScroll: true })
-            }}
-            role="button"
-            tabIndex={0}
-            onKeyDown={(e) => { if (!multiSelected && e.key === 'Enter') { setInteractive(true); termRef.current?.focus({ preventScroll: true }) } }}
-            aria-label="Click to interact"
-          >
-            {!multiSelected && <span className={overlayStyles.interactHint}>Click to interact</span>}
-          </div>
+        {/* ── Frozen state: WebGL context released, show snapshot ── */}
+        {!isLive && (
+          <FrozenTerminalOverlay
+            widgetId={id}
+            onActivate={handleFrozenActivate}
+          />
         )}
 
-        {/* Session ended — resource limited */}
-        {sessionEnded && resourceLimited && (
-          <div
-            className={overlayStyles.interactOverlay}
-            style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: '8px', padding: '24px' }}
-          >
-            <span className={styles.resourceIcon}>⚠</span>
-            <span className={styles.resourceTitle}>No terminal devices available</span>
-            <span className={styles.resourceMessage}>
-              Too many terminal sessions are open.
-              {resourceLimited.counts && (
-                <span className={styles.resourceCounts}>
-                  {resourceLimited.counts.live} live · {resourceLimited.counts.background} background · {resourceLimited.counts.archived} archived
-                </span>
-              )}
-            </span>
-            <div className={styles.resourceActions}>
-              {!resourceLimited.cleanupResult && (resourceLimited.counts?.background > 0 || resourceLimited.counts?.archived > 0) && (
-                <button className={styles.resourceBtn} onClick={handleCleanupAndRetry}>
-                  Close background sessions
-                </button>
-              )}
-              {resourceLimited.cleanupResult === 'nothing-to-clean' && (
-                <span className={styles.resourceMuted}>
-                  All background sessions already cleaned. Close some live terminals to free resources.
-                </span>
-              )}
-              {resourceLimited.cleanupResult === 'failed' && (
-                <span className={styles.resourceMuted}>
-                  Cleanup failed — could not reach dev server.
+        {/* ── Live state: ghostty WebGL terminal ── */}
+        {isLive && (
+          <>
+            {showDragHint && (
+              <div className={styles.dragHint}>
+                <span className={styles.dragHintArrow}>←</span> Drag here to move widget
+              </div>
+            )}
+            {error && !sessionEnded && (
+              <div className={styles.error}>
+                <span>⚠ {error}</span>
+              </div>
+            )}
+            <div ref={containerRef} className={styles.xtermContainer} style={{ opacity: revealed ? 1 : 0 }} />
+
+            {/* Live but not interactive */}
+            {revealed && !interactive && !sessionEnded && (
+              <div
+                className={overlayStyles.interactOverlay}
+                style={{ backgroundColor: 'transparent' }}
+                onClick={(e) => {
+                  if (multiSelected || e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+                  setInteractive(true)
+                  termRef.current?.focus({ preventScroll: true })
+                }}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => { if (!multiSelected && e.key === 'Enter') { setInteractive(true); termRef.current?.focus({ preventScroll: true }) } }}
+                aria-label="Click to interact"
+              >
+                {!multiSelected && <span className={overlayStyles.interactHint}>Click to interact</span>}
+              </div>
+            )}
+
+            {/* Session ended — resource limited */}
+            {sessionEnded && resourceLimited && (
+              <div
+                className={overlayStyles.interactOverlay}
+                style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: '8px', padding: '24px' }}
+              >
+                <span className={styles.resourceIcon}>⚠</span>
+                <span className={styles.resourceTitle}>No terminal devices available</span>
+                <span className={styles.resourceMessage}>
+                  Too many terminal sessions are open.
+                  {resourceLimited.counts && (
+                    <span className={styles.resourceCounts}>
+                      {resourceLimited.counts.live} live · {resourceLimited.counts.background} background · {resourceLimited.counts.archived} archived
+                    </span>
+                  )}
                 </span>
-              )}
-              <button className={styles.resourceBtnSecondary} onClick={handleStartSession}>
-                Retry
-              </button>
-            </div>
-          </div>
-        )}
+                <div className={styles.resourceActions}>
+                  {!resourceLimited.cleanupResult && (resourceLimited.counts?.background > 0 || resourceLimited.counts?.archived > 0) && (
+                    <button className={styles.resourceBtn} onClick={handleCleanupAndRetry}>
+                      Close background sessions
+                    </button>
+                  )}
+                  {resourceLimited.cleanupResult === 'nothing-to-clean' && (
+                    <span className={styles.resourceMuted}>
+                      All background sessions already cleaned. Close some live terminals to free resources.
+                    </span>
+                  )}
+                  {resourceLimited.cleanupResult === 'failed' && (
+                    <span className={styles.resourceMuted}>
+                      Cleanup failed — could not reach dev server.
+                    </span>
+                  )}
+                  <button className={styles.resourceBtnSecondary} onClick={handleStartSession}>
+                    Retry
+                  </button>
+                </div>
+              </div>
+            )}
 
-        {/* Session ended — normal (zzz) */}
-        {sessionEnded && !resourceLimited && (
-          <div
-            className={overlayStyles.interactOverlay}
-            style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: 0 }}
-            onClick={handleStartSession}
-            role="button"
-            tabIndex={0}
-            aria-label="Start terminal session"
-            onKeyDown={(e) => { if (e.key === 'Enter') handleStartSession() }}
-          >
-            {!waking && (
-              <div className={styles.buddyZzz}>
-                <span className={styles.z1}>z</span>
-                <span className={styles.z2}>z</span>
-                <span className={styles.z3}>z</span>
+            {/* Session ended — normal */}
+            {sessionEnded && !resourceLimited && (
+              <div
+                className={overlayStyles.interactOverlay}
+                style={{ backgroundColor: 'var(--term-bg, #0d1117)', flexDirection: 'column', gap: 0 }}
+                onClick={handleStartSession}
+                role="button"
+                tabIndex={0}
+                aria-label="Start terminal session"
+                onKeyDown={(e) => { if (e.key === 'Enter') handleStartSession() }}
+              >
+                {!waking && (
+                  <>
+                    <div className={styles.buddyZzz}>
+                      <span className={styles.z1}>z</span>
+                      <span className={styles.z2}>z</span>
+                      <span className={styles.z3}>z</span>
+                    </div>
+                    <span className={styles.sessionEndedBadge}>Session ended</span>
+                    <span className={styles.sessionEndedAction}>Click to start</span>
+                  </>
+                )}
+                {waking && (
+                  <span className={overlayStyles.interactHint} style={{ opacity: 1 }}>
+                    Waking up...
+                  </span>
+                )}
               </div>
             )}
-            <span className={overlayStyles.interactHint}>
-              {waking ? 'Waking up...' : connectAttempt > 0 ? 'Continue terminal session' : 'Start terminal session'}
-            </span>
-          </div>
-        )}
 
-        {/* Connecting / reveal mask */}
-        {!revealed && !error && !sessionEnded && (
-          <div className={styles.loading}>
-            <div className={styles.spinner} />
-          </div>
+            {/* Connecting / reveal mask */}
+            {!revealed && !error && !sessionEnded && (
+              <div className={styles.loading}>
+                <div className={styles.spinner} />
+              </div>
+            )}
+          </>
         )}
       </div>
     </div>

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

@@ -204,6 +204,29 @@
   }
 }
 
+/* ── Session-ended badge + action ── */
+
+.sessionEndedBadge {
+  display: inline-flex;
+  align-items: center;
+  background: rgba(110, 118, 129, 0.25);
+  color: #8b949e;
+  font-size: 12px;
+  padding: 5px 14px;
+  border-radius: 999px;
+  letter-spacing: 0.01em;
+  pointer-events: none;
+  margin-bottom: 12px;
+}
+
+.sessionEndedAction {
+  color: #e6edf3;
+  font-size: 14px;
+  font-weight: 600;
+  opacity: 0.7;
+  pointer-events: none;
+}
+
 /* ── Resource-limited overlay ── */
 
 .resourceIcon {

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

@@ -5,7 +5,6 @@ import { describe, it, expect, vi } from 'vitest'
 import { render, fireEvent, screen } from '@testing-library/react'
 import PrototypeEmbed from './PrototypeEmbed.jsx'
 import FigmaEmbed from './FigmaEmbed.jsx'
-import ComponentWidget from './ComponentWidget.jsx'
 import StoryWidget from './StoryWidget.jsx'
 
 // Mock buildPrototypeIndex for PrototypeEmbed
@@ -24,7 +23,7 @@ vi.mock('@dfosco/storyboard-core', () => ({
     globalFlows: [],
     sorted: { title: { prototypes: [], folders: [] } },
   }),
-  getStoryData: (storyId) => ({ _route: `/components/${storyId}` }),
+  getStoryData: (storyId) => ({ _storyModule: `/src/canvas/${storyId}.story.jsx`, _route: `/components/${storyId}` }),
 }))
 
 // Simple mock wrapper for WidgetWrapper
@@ -43,11 +42,6 @@ vi.mock('./ResizeHandle.jsx', () => ({
   default: () => <div data-testid="resize-handle" />,
 }))
 
-// Mock ComponentErrorBoundary
-vi.mock('../ComponentErrorBoundary.jsx', () => ({
-  default: ({ children }) => <div data-testid="error-boundary">{children}</div>,
-}))
-
 describe('Embed interaction overlay', () => {
   describe('PrototypeEmbed', () => {
     const defaultProps = {
@@ -176,58 +170,4 @@ describe('Embed interaction overlay', () => {
       expect(container.querySelector('iframe')).toBeInTheDocument()
     })
   })
-
-  describe('ComponentWidget', () => {
-    const MockComponent = () => <div>Mock Component</div>
-    
-    const defaultProps = {
-      component: MockComponent,
-      jsxModule: null,
-      exportName: 'MockComponent',
-      canvasTheme: 'light',
-      isLocalDev: false,
-      width: 200,
-      height: 150,
-      onUpdate: vi.fn(),
-      resizable: false,
-    }
-
-    it('renders "Click to interact" hint', () => {
-      render(<ComponentWidget {...defaultProps} />)
-      
-      const hint = screen.getByText('Click to interact')
-      expect(hint).toBeInTheDocument()
-    })
-
-    it('enters interactive mode on single click', () => {
-      render(<ComponentWidget {...defaultProps} />)
-      
-      const overlay = screen.getByRole('button', { name: /click to interact/i })
-      fireEvent.click(overlay)
-      
-      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
-    })
-
-    it('mounts dev iframe only after user activation', () => {
-      const { container } = render(
-        <ComponentWidget
-          {...defaultProps}
-          isLocalDev
-          jsxModule="/src/canvas/mock.story.jsx"
-          exportName="MockComponent"
-        />
-      )
-
-      const overlay = screen.getByRole('button', { name: /click to interact with component/i })
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
-
-      fireEvent.click(overlay)
-
-      expect(container.querySelector('iframe')).toBeInTheDocument()
-
-      fireEvent.pointerDown(document.body)
-      expect(screen.getByRole('button', { name: /click to interact with component/i })).toBeInTheDocument()
-      expect(container.querySelector('iframe')).not.toBeInTheDocument()
-    })
-  })
 })

package/src/canvas/widgets/expandUtils.js

@@ -470,12 +470,11 @@ export function buildSecondaryIframeUrl(widget) {
     const exportName = widget.props?.exportName
     if (!storyId) return null
     const storyData = getStoryData(storyId)
-    if (storyData?._route) {
+    if (storyData?._storyModule) {
       const params = new URLSearchParams()
+      params.set('module', storyData._storyModule)
       if (exportName) params.set('export', exportName)
-      params.set('_sb_embed', '')
-      params.set('_sb_hide_branch_bar', '')
-      return `${baseClean}${storyData._route}?${params}`
+      return `${baseClean}/_storyboard/canvas/isolate?${params}`
     }
     return null
   }

package/src/canvas/widgets/index.js

@@ -6,7 +6,7 @@ import ImageWidget from './ImageWidget.jsx'
 import FigmaEmbed from './FigmaEmbed.jsx'
 import CodePenEmbed from './CodePenEmbed.jsx'
 import StoryWidget from './StoryWidget.jsx'
-import ComponentSetWidget from './ComponentSetWidget.jsx'
+import StorySetWidget from './StorySetWidget.jsx'
 import TerminalWidget from './TerminalWidget.jsx'
 import TerminalReadWidget from './TerminalReadWidget.jsx'
 import PromptWidget from './PromptWidget.jsx'
@@ -25,7 +25,7 @@ export const widgetRegistry = {
   'figma-embed': FigmaEmbed,
   'codepen-embed': CodePenEmbed,
   'story': StoryWidget,
-  'component-set': ComponentSetWidget,
+  'component-set': StorySetWidget,
   'terminal': TerminalWidget,
   'terminal-read': TerminalReadWidget,
   'agent': TerminalWidget,

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

@@ -21,7 +21,7 @@ vi.mock('@dfosco/storyboard-core', () => ({
     globalFlows: [],
     sorted: { title: { prototypes: [], folders: [] } },
   }),
-  getStoryData: (storyId) => ({ _route: `/components/${storyId}` }),
+  getStoryData: (storyId) => ({ _storyModule: `/src/canvas/${storyId}.story.jsx`, _route: `/components/${storyId}` }),
 }))
 
 vi.mock('./WidgetWrapper.jsx', () => ({

package/src/context.jsx

@@ -1,8 +1,8 @@
-import { useState, useEffect, useMemo, Suspense, lazy } from 'react'
+import { useState, useEffect, useMemo, useRef, Suspense, lazy } from 'react'
 import { useParams, useLocation } from 'react-router-dom'
 // Named import seeds the core data index via init() AND provides canvas/story route data
 import { canvases, stories } from 'virtual:storyboard-data-index'
-import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, isModesEnabled } from '@dfosco/storyboard-core'
+import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, isModesEnabled, getPrototypeMetadata } from '@dfosco/storyboard-core'
 import { StoryboardContext } from './StoryboardContext.js'
 import usePrototypeReloadGuard from './hooks/usePrototypeReloadGuard.js'
 import styles from './FlowError.module.css'
@@ -270,12 +270,19 @@ function StoryboardProviderInner({ flowName, sceneName, recordName, recordParam,
   }, [])
 
   // Skip flow loading for canvas/story pages and flow-less pages
-  const { data, error } = useMemo(() => {
-    if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null }
-    if (!activeFlowName) return { data: {}, error: null }
+  const { data, error, flowTokens } = useMemo(() => {
+    if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null, flowTokens: null }
+    if (!activeFlowName) return { data: {}, error: null, flowTokens: null }
     try {
       let flowData = loadFlow(activeFlowName)
 
+      // Extract tokens before passing data to consumers (reserved metadata key)
+      const extractedTokens = flowData?.tokens || null
+      if (flowData?.tokens) {
+        flowData = { ...flowData }
+        delete flowData.tokens
+      }
+
       // Merge record data if configured (with scoped resolution)
       if (recordName && recordParam && params[recordParam]) {
         const resolvedRecord = resolveRecordName(prototypeName, recordName)
@@ -286,12 +293,68 @@ function StoryboardProviderInner({ flowName, sceneName, recordName, recordParam,
       }
 
       setFlowClass(activeFlowName)
-      return { data: flowData, error: null }
+      return { data: flowData, error: null, flowTokens: extractedTokens }
     } catch (err) {
-      return { data: null, error: err.message }
+      return { data: null, error: err.message, flowTokens: null }
     }
   }, [canvasId, isMissingCanvasRoute, storyName, isMissingStoryRoute, activeFlowName, recordName, recordParam, params, prototypeName])
 
+  // Resolve prototype-level tokens from .prototype.json metadata
+  const protoTokens = useMemo(() => {
+    if (!prototypeName) return null
+    const meta = getPrototypeMetadata(prototypeName)
+    return meta?.tokens || null
+  }, [prototypeName])
+
+  // Merge prototype + flow tokens (flow wins). Stable reference when tokens don't change.
+  const mergedTokens = useMemo(() => {
+    if (!protoTokens && !flowTokens) return null
+    return { ...(protoTokens || {}), ...(flowTokens || {}) }
+  }, [protoTokens, flowTokens])
+
+  // Track which URL params were set by tokens (vs. user-explicit params)
+  const managedParamsRef = useRef({})
+
+  // Apply merged tokens to URL search params via replaceState.
+  // Only sets params not already present (user-explicit wins on first load).
+  // Cleans up stale managed params when flow/prototype tokens change.
+  useEffect(() => {
+    const url = new URL(window.location.href)
+    const managed = managedParamsRef.current
+    const nextManaged = {}
+    let changed = false
+
+    // Remove stale managed params no longer in merged tokens
+    for (const key of Object.keys(managed)) {
+      if (!mergedTokens || !(key in mergedTokens)) {
+        url.searchParams.delete(key)
+        changed = true
+      }
+    }
+
+    // Apply current tokens
+    if (mergedTokens) {
+      const reserved = new Set(['flow', 'scene'])
+      for (const [key, value] of Object.entries(mergedTokens)) {
+        if (value == null || typeof value === 'object' || reserved.has(key)) continue
+        const strValue = String(value)
+        if (!url.searchParams.has(key) || (key in managed && managed[key] !== strValue)) {
+          url.searchParams.set(key, strValue)
+          nextManaged[key] = strValue
+          changed = true
+        } else if (key in managed) {
+          nextManaged[key] = strValue
+        }
+      }
+    }
+
+    managedParamsRef.current = nextManaged
+
+    if (changed) {
+      window.history.replaceState(window.history.state, '', url.toString())
+    }
+  }, [mergedTokens])
+
   // Canvas pages get their own rendering path — no flow data needed
   if (canvasId) {
     const canvasData = canvases?.[canvasId]

package/src/vite/data-plugin.js

@@ -1038,6 +1038,8 @@ export default function storyboardDataPlugin() {
       // The iframe loads componentIsolate.jsx which reads query params
       // (module, export, theme) and renders a single story export.
       const isolateEntryPath = new URL('../canvas/componentIsolate.jsx', import.meta.url).pathname
+      // Component-set isolate — renders all exports in a grid, bypassing the full SPA.
+      const componentSetIsolateEntryPath = new URL('../canvas/componentSetIsolate.jsx', import.meta.url).pathname
       server.middlewares.use(async (req, res, next) => {
         if (!req.url) return next()
         let url = req.url
@@ -1045,15 +1047,19 @@ export default function storyboardDataPlugin() {
         if (baseNoTrail && url.startsWith(baseNoTrail)) {
           url = url.slice(baseNoTrail.length) || '/'
         }
-        if (!url.startsWith('/_storyboard/canvas/isolate')) return next()
+        // Match both single-component and component-set isolate routes
+        const isComponentSet = url.startsWith('/_storyboard/canvas/isolate-set')
+        const isSingle = !isComponentSet && url.startsWith('/_storyboard/canvas/isolate')
+        if (!isSingle && !isComponentSet) return next()
 
+        const entryPath = isComponentSet ? componentSetIsolateEntryPath : isolateEntryPath
         const rawHtml = [
           '<!DOCTYPE html>',
           '<html><head>',
           '<style>html,body{margin:0;padding:0;width:100%;height:100%;background:var(--bgColor-default,transparent)}#root{width:100%;height:100%}</style>',
           '</head><body>',
           '<div id="root"></div>',
-          `<script type="module" src="/@fs${isolateEntryPath}"></script>`,
+          `<script type="module" src="/@fs${entryPath}"></script>`,
           '</body></html>',
         ].join('\n')