@dfosco/storyboard-core 4.2.4 → 4.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.2.4",
+  "version": "4.2.6",
   "type": "module",
   "license": "MIT",
   "bin": {

package/src/ActionMenuButton.jsx

@@ -16,6 +16,17 @@ export default function ActionMenuButton({ config = {}, data: _data, localOnly:
     return unsub
   }, [])
 
+  // Allow external callers (e.g. command palette) to open this menu
+  useEffect(() => {
+    const actionId = config.action
+    if (!actionId) return
+    function onTrigger(e) {
+      if (e.detail?.action === actionId) setMenuOpen(true)
+    }
+    window.addEventListener('storyboard:open-tool-menu', onTrigger)
+    return () => window.removeEventListener('storyboard:open-tool-menu', onTrigger)
+  }, [config.action])
+
   const children = config.action ? getActionChildren(config.action) : []
   const hasRadio = children.some((c) => c.type === 'radio')
   const activeValue = children.find((c) => c.type === 'radio' && c.active)?.id || ''

package/src/CoreUIBar.jsx

@@ -147,6 +147,9 @@ export default function CoreUIBar({ basePath = '/', toolbarConfig, customHandler
   const [visible, setVisible] = useState(
     () => !document.documentElement.classList.contains('storyboard-chrome-hidden')
   )
+  const [completelyHidden, setCompletelyHidden] = useState(
+    () => document.documentElement.classList.contains('storyboard-chrome-completely-hidden')
+  )
   const [toolComponents, setToolComponents] = useState({})
   const [toolData, setToolData] = useState({})
   const [navVersion, setNavVersion] = useState(0)
@@ -338,10 +341,25 @@ export default function CoreUIBar({ basePath = '/', toolbarConfig, customHandler
     setVisible((v) => {
       const next = !v
       document.documentElement.classList.toggle('storyboard-chrome-hidden', !next)
+      // Always clear completely-hidden when toggling via cmd+.
+      document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
       return next
     })
   }, [])
 
+  const toggleCompletelyHidden = useCallback(() => {
+    const isAnyHidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
+    if (isAnyHidden) {
+      document.documentElement.classList.remove('storyboard-chrome-hidden')
+      document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
+      setVisible(true)
+    } else {
+      document.documentElement.classList.add('storyboard-chrome-hidden')
+      document.documentElement.classList.add('storyboard-chrome-completely-hidden')
+      setVisible(false)
+    }
+  }, [])
+
   function showFlowInfoDialog(name, json, error) {
     setFlowName(name)
     setFlowJson(json)
@@ -497,13 +515,15 @@ export default function CoreUIBar({ basePath = '/', toolbarConfig, customHandler
 
     setRoutingBasePath(basePath)
 
-    // Sync visible state when storyboard-chrome-hidden is toggled externally
+    // Sync visible + completelyHidden state when classes are toggled externally
     const chromeObserver = new MutationObserver(() => {
       const hidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
+      const fully = document.documentElement.classList.contains('storyboard-chrome-completely-hidden')
       setVisible((v) => {
         if (v === !hidden) return v
         return !hidden
       })
+      setCompletelyHidden(fully)
     })
     chromeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
 
@@ -690,10 +710,21 @@ export default function CoreUIBar({ basePath = '/', toolbarConfig, customHandler
     function handleKeydown(e) {
       const hideKey = shortcutsConfig.hideChrome?.key || '.'
 
-      if (e.key === hideKey && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault()
-        toggleToolsVisibility()
+      if ((e.metaKey || e.ctrlKey) && !e.shiftKey) {
+        // Alt+Cmd+. — completely hide (use e.code since alt changes e.key on macOS)
+        if (e.altKey && e.code === 'Period') {
+          e.preventDefault()
+          toggleCompletelyHidden()
+          return
+        }
+        // Cmd+. — regular hide/show
+        if (!e.altKey && e.key === hideKey) {
+          e.preventDefault()
+          toggleToolsVisibility()
+          return
+        }
       }
+
       for (const menu of cleanedMenus) {
         const shortcut = menu.shortcut
         if (!shortcut?.key) continue
@@ -711,14 +742,14 @@ export default function CoreUIBar({ basePath = '/', toolbarConfig, customHandler
 
     window.addEventListener('keydown', handleKeydown)
     return () => window.removeEventListener('keydown', handleKeydown)
-  }, [shortcutsConfig, cleanedMenus, toggleToolsVisibility])
+  }, [shortcutsConfig, cleanedMenus, toggleToolsVisibility, toggleCompletelyHidden])
 
   if (isEmbed) return null
 
   return (
     <>
       {/* Canvas toolbar */}
-      {canvasActive && canvasMenus.length > 0 && (
+      {canvasActive && !completelyHidden && canvasMenus.length > 0 && (
         <div
           className="fixed bottom-6 left-6 z-[9999] font-sans flex items-center gap-3"
           role="toolbar"

package/src/HideChromeTrigger.jsx

@@ -2,6 +2,7 @@
  * HideChromeTrigger — toolbar button that toggles toolbar/branch bar visibility.
  * Always visible (even in hide mode). Uses the lightbulb icon.
  * In hide mode: goes 50% opacity.
+ * In completely-hidden mode: not rendered at all.
  */
 
 import { useState, useEffect, useCallback } from 'react'
@@ -12,10 +13,14 @@ export default function HideChromeTrigger({ config = {}, tabindex }) {
   const [hidden, setHidden] = useState(
     () => document.documentElement.classList.contains('storyboard-chrome-hidden')
   )
+  const [completelyHidden, setCompletelyHidden] = useState(
+    () => document.documentElement.classList.contains('storyboard-chrome-completely-hidden')
+  )
 
   useEffect(() => {
     const observer = new MutationObserver(() => {
       setHidden(document.documentElement.classList.contains('storyboard-chrome-hidden'))
+      setCompletelyHidden(document.documentElement.classList.contains('storyboard-chrome-completely-hidden'))
     })
     observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
     return () => observer.disconnect()
@@ -23,8 +28,11 @@ export default function HideChromeTrigger({ config = {}, tabindex }) {
 
   const toggle = useCallback(() => {
     document.documentElement.classList.toggle('storyboard-chrome-hidden')
+    document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
   }, [])
 
+  if (completelyHidden) return null
+
   return (
     <span style={{ opacity: hidden ? 0.5 : 1, transition: 'opacity 0.15s' }}>
       <TriggerButton

package/src/canvas/hot-pool.js

@@ -81,6 +81,7 @@ export class HotPool {
   #healthTimer = null
   #prereqsAvailable = null
   #wsSend = null
+  #webglReadySlots = 0
 
   // Agent config (null for bare shell pools)
   #agentConfig = null
@@ -100,7 +101,7 @@ export class HotPool {
   constructor({ root, poolId = 'terminal', config = {}, agentConfig = null, wsSend = null }) {
     this.#root = root
     this.#poolId = poolId
-    this.#poolSize = Math.max(1, config.pool_size ?? DEFAULT_POOL_SIZE)
+    this.#poolSize = Math.max(0, config.pool_size ?? DEFAULT_POOL_SIZE)
     this.#maxPoolSize = Math.max(this.#poolSize, config.max_pool_size ?? DEFAULT_MAX_POOL_SIZE)
     this.#cooldownMs = (config.load_balancer_cooldown_mins ?? DEFAULT_COOLDOWN_MINS) * 60_000
     this.#enabled = config.enabled !== false
@@ -108,6 +109,7 @@ export class HotPool {
     this.#loadBalancer = config.load_balancer !== false
     this.#wsSend = wsSend
     this.#agentConfig = agentConfig
+    this.#webglReadySlots = Math.max(0, config.webgl_ready_slots ?? 0)
   }
 
   get poolId() { return this.#poolId }
@@ -177,8 +179,12 @@ export class HotPool {
       return null
     }
 
+    // Session is WebGL-ready if its queue position was within webgl_ready_slots
+    const webglReady = this.#webglReadySlots > 0 && idx < this.#webglReadySlots
+
     const session = this.#queue.splice(idx, 1)[0]
     session.state = 'acquired'
+    session.webglReady = webglReady
     this.#acquired.set(session.id, session)
     const age = ((Date.now() - session.createdAt) / 1000).toFixed(1)
     const readyCount = this.#queue.filter(s => s.state === 'ready').length
@@ -186,10 +192,10 @@ export class HotPool {
     // Scale-up: queue drained to 0 ready → enter pressure mode
     if (readyCount === 0 && !this.#pressured) {
       this.#pressured = true
-      this.#log(`→ ACQUIRED ${session.id} tmux=${session.tmuxName} (age: ${age}s) — ⚡ PRESSURE ON (scaling to max_pool_size=${this.#maxPoolSize})`)
+      this.#log(`→ ACQUIRED ${session.id} tmux=${session.tmuxName} (age: ${age}s, webglReady: ${webglReady}) — ⚡ PRESSURE ON (scaling to max_pool_size=${this.#maxPoolSize})`)
       this.#resetCooldown()
     } else {
-      this.#log(`→ ACQUIRED ${session.id} tmux=${session.tmuxName} (age: ${age}s, queue: ${readyCount}/${this.#fillTarget})`)
+      this.#log(`→ ACQUIRED ${session.id} tmux=${session.tmuxName} (age: ${age}s, webglReady: ${webglReady}, queue: ${readyCount}/${this.#fillTarget})`)
       this.#resetCooldown()
     }
 
@@ -237,6 +243,7 @@ export class HotPool {
         load_balancer: this.#loadBalancer,
         load_balancer_cooldown_mins: this.#cooldownMs / 60_000,
         verbose: this.#verbose,
+        webgl_ready_slots: this.#webglReadySlots,
       },
       agentConfig: this.#agentConfig ? {
         startupCommand: this.#agentConfig.startupCommand,
@@ -254,10 +261,11 @@ export class HotPool {
   }
 
   reconfigure(config) {
-    if (config.max_pool_size !== undefined) this.#maxPoolSize = Math.max(1, config.max_pool_size)
+    if (config.max_pool_size !== undefined) this.#maxPoolSize = Math.max(0, config.max_pool_size)
     if (config.load_balancer_cooldown_mins !== undefined) this.#cooldownMs = config.load_balancer_cooldown_mins * 60_000
     if (config.load_balancer !== undefined) this.#loadBalancer = !!config.load_balancer
-    const newSize = Math.min(Math.max(1, config.pool_size ?? this.#poolSize), this.#maxPoolSize)
+    if (config.webgl_ready_slots !== undefined) this.#webglReadySlots = Math.max(0, config.webgl_ready_slots)
+    const newSize = Math.min(Math.max(0, config.pool_size ?? this.#poolSize), this.#maxPoolSize)
     const newEnabled = config.enabled !== false
     if (config.verbose !== undefined) this.#verbose = !!config.verbose
 
@@ -644,6 +652,7 @@ export class HotPoolManager {
       load_balancer: config.load_balancer !== false,
       enabled: this.#enabled,
       verbose: !!config.verbose,
+      webgl_ready_slots: poolsConfig[poolId]?.webgl_ready_slots ?? 0,
     })
 
     // Terminal pool (bare shells)
@@ -738,6 +747,7 @@ export class HotPoolManager {
         load_balancer: config.load_balancer,
         enabled: config.enabled,
         verbose: config.verbose,
+        webgl_ready_slots: poolsConfig[id]?.webgl_ready_slots,
       }
       pool.reconfigure(poolConfig)
     }

package/src/canvas/server.js

@@ -770,7 +770,7 @@ export function createCanvasHandler(ctx) {
         })
 
         const response = { success: true, widget }
-        if (hotSession) response.hotSession = { id: hotSession.id, tmuxName: hotSession.tmuxName || null }
+        if (hotSession) response.hotSession = { id: hotSession.id, tmuxName: hotSession.tmuxName || null, webglReady: !!hotSession.webglReady }
         sendJson(res, 201, response)
         pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
@@ -1334,7 +1334,7 @@ export function createCanvasHandler(ctx) {
                 if (ref) refs[ref] = widgetId
 
                 const result = { index: i, op: 'create-widget', ref: ref || undefined, widgetId, widget }
-                if (hotSession) result.hotSession = { id: hotSession.id, tmuxName: hotSession.tmuxName || null }
+                if (hotSession) result.hotSession = { id: hotSession.id, tmuxName: hotSession.tmuxName || null, webglReady: !!hotSession.webglReady }
                 results.push(result)
                 break
               }

package/src/configSchema.js

@@ -65,7 +65,7 @@
  * @property {number}  [default_max_pool_size] — default surge cap per pool (default: 3)
  * @property {boolean} [load_balancer] — enable auto-scaling (default: true)
  * @property {number}  [load_balancer_cooldown_mins] — minutes idle before scale-down (default: 10)
- * @property {Record<string, { pool_size?: number, max_pool_size?: number }>} [pools] — per-pool overrides (terminal, prompt, copilot, claude, codex)
+ * @property {Record<string, { pool_size?: number, max_pool_size?: number, webgl_ready_slots?: number }>} [pools] — per-pool overrides (terminal, prompt, copilot, claude, codex). webgl_ready_slots: how many front-of-queue sessions should start with PINNED WebGL priority (default: 0)
  */
 
 /**

package/src/index.js

@@ -62,7 +62,7 @@ export { mountSceneDebug } from './sceneDebug.js'
 export { mountStoryboardCore } from './mountStoryboardCore.js'
 
 // Viewfinder utilities
-export { hash, resolveFlowRoute, getFlowMeta, buildPrototypeIndex } from './viewfinder.js'
+export { hash, resolveFlowRoute, getFlowMeta, buildPrototypeIndex, appendTokens } from './viewfinder.js'
 // Deprecated aliases
 export { resolveSceneRoute, getSceneMeta } from './viewfinder.js'
 

package/src/mountStoryboardCore.js

@@ -28,6 +28,7 @@ import {
 let _mounted = false
 
 const CHROME_HIDDEN_KEY = 'sb-chrome-hidden'
+const CHROME_COMPLETELY_HIDDEN_KEY = 'sb-chrome-completely-hidden'
 
 /**
  * Migrate localStorage keys renamed in 4.3.0.
@@ -54,20 +55,26 @@ function migrateLocalStorageKeys() {
 function applyEarlyChromeState() {
   if (typeof document === 'undefined' || typeof localStorage === 'undefined') return
   const hidden = localStorage.getItem(CHROME_HIDDEN_KEY) === '1'
+  const completelyHidden = localStorage.getItem(CHROME_COMPLETELY_HIDDEN_KEY) === '1'
   if (hidden) {
     document.documentElement.classList.add('storyboard-chrome-hidden')
   }
+  if (completelyHidden) {
+    document.documentElement.classList.add('storyboard-chrome-completely-hidden')
+  }
 }
 
 /**
- * Watch for changes to the storyboard-chrome-hidden class and persist to
- * localStorage. Works regardless of which code path toggles the class.
+ * Watch for changes to chrome-hidden / chrome-completely-hidden classes
+ * and persist to localStorage. Works regardless of which code path toggles them.
  */
 function installChromeStatePersistence() {
   if (typeof document === 'undefined' || typeof localStorage === 'undefined') return
   const observer = new MutationObserver(() => {
     const hidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
+    const completelyHidden = document.documentElement.classList.contains('storyboard-chrome-completely-hidden')
     localStorage.setItem(CHROME_HIDDEN_KEY, hidden ? '1' : '0')
+    localStorage.setItem(CHROME_COMPLETELY_HIDDEN_KEY, completelyHidden ? '1' : '0')
   })
   observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
 }

package/src/tools/handlers/hideToolbars.js

@@ -17,6 +17,7 @@ export async function handler() {
         execute: () => {
           const isHidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
           document.documentElement.classList.toggle('storyboard-chrome-hidden', !isHidden)
+          document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
         },
       }]
     },

package/src/viewfinder.js

@@ -13,6 +13,26 @@ export function hash(str) {
   return Math.abs(h)
 }
 
+/**
+ * Append `tokens` from flow/prototype data as URL search params.
+ * Filters out reserved keys (`flow`, `scene`) and non-scalar values.
+ *
+ * @param {string} url - Base URL (may already contain query params)
+ * @param {object|null|undefined} tokens - Key-value pairs to append
+ * @returns {string} URL with token params appended
+ */
+export function appendTokens(url, tokens) {
+  if (!tokens || typeof tokens !== 'object') return url
+  const reserved = new Set(['flow', 'scene'])
+  const entries = Object.entries(tokens).filter(
+    ([k, v]) => v != null && !reserved.has(k) && typeof v !== 'object',
+  )
+  if (entries.length === 0) return url
+  const sep = url.includes('?') ? '&' : '?'
+  const qs = entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
+  return `${url}${sep}${qs}`
+}
+
 /**
  * Resolve the target route path for a flow.
  *
@@ -23,42 +43,51 @@ export function hash(str) {
  * 4. Fall back to root "/"
  *
  * Flows with `meta.default: true` targeting a route omit the `?flow=` param.
+ * If the flow data contains a `tokens` object, its entries are appended as query params.
  *
  * @param {string} flowName
  * @param {string[]} knownRoutes - Array of route names (e.g. ["Dashboard", "Repositories"])
  * @returns {string} Full path with optional ?flow= param
  */
 export function resolveFlowRoute(flowName, knownRoutes = []) {
+  let routeUrl
+  let data = null
+
   // Case-insensitive match against known routes
-  for (const route of knownRoutes) {
-    if (route.toLowerCase() === flowName.toLowerCase()) {
-      // Flow name matches the route — no ?flow= needed,
-      // StoryboardProvider auto-matches by page name
-      return `/${route}`
-    }
-  }
+  const matchedRoute = knownRoutes.find(r => r.toLowerCase() === flowName.toLowerCase())
 
-  try {
-    const data = loadFlow(flowName)
+  if (matchedRoute) {
+    routeUrl = `/${matchedRoute}`
+  } else {
+    try {
+      data = loadFlow(flowName)
 
-    // Check for explicit route: top-level `route`, then meta.route, then legacy sceneMeta.route
-    const explicitRoute = data?.route || data?.meta?.route || data?.flowMeta?.route || data?.sceneMeta?.route
-    if (explicitRoute) {
-      const normalized = explicitRoute.startsWith('/') ? explicitRoute : `/${explicitRoute}`
-      if (data?.meta?.default === true) return normalized
-      return `${normalized}?flow=${encodeURIComponent(flowName)}`
+      // Check for explicit route: top-level `route`, then meta.route, then legacy sceneMeta.route
+      const explicitRoute = data?.route || data?.meta?.route || data?.flowMeta?.route || data?.sceneMeta?.route
+      if (explicitRoute) {
+        const normalized = explicitRoute.startsWith('/') ? explicitRoute : `/${explicitRoute}`
+        routeUrl = data?.meta?.default === true
+          ? normalized
+          : `${normalized}?flow=${encodeURIComponent(flowName)}`
+      } else if (data?._route) {
+        // Use inferred route from file path (injected by Vite data plugin)
+        routeUrl = data?.meta?.default === true
+          ? data._route
+          : `${data._route}?flow=${encodeURIComponent(flowName)}`
+      } else {
+        routeUrl = `/?flow=${encodeURIComponent(flowName)}`
+      }
+    } catch {
+      routeUrl = `/?flow=${encodeURIComponent(flowName)}`
     }
+  }
 
-    // Use inferred route from file path (injected by Vite data plugin)
-    if (data?._route) {
-      if (data?.meta?.default === true) return data._route
-      return `${data._route}?flow=${encodeURIComponent(flowName)}`
-    }
-  } catch {
-    // ignore load errors
+  // Load flow data for tokens if not already loaded (e.g. known-route early match)
+  if (!data) {
+    try { data = loadFlow(flowName) } catch { /* ignore */ }
   }
 
-  return `/?flow=${encodeURIComponent(flowName)}`
+  return appendTokens(routeUrl, data?.tokens)
 }
 
 /** @deprecated Use resolveFlowRoute() */

package/src/viewfinder.test.js

@@ -1,5 +1,5 @@
 import { init } from './loader.js'
-import { hash, resolveFlowRoute, getFlowMeta, resolveSceneRoute, getSceneMeta, buildPrototypeIndex } from './viewfinder.js'
+import { hash, resolveFlowRoute, getFlowMeta, resolveSceneRoute, getSceneMeta, buildPrototypeIndex, appendTokens } from './viewfinder.js'
 
 const makeIndex = () => ({
   flows: {
@@ -343,3 +343,114 @@ describe('buildPrototypeIndex', () => {
     expect(result.prototypes[0].lastModified).toBeNull()
   })
 })
+
+// ── appendTokens ──
+
+describe('appendTokens', () => {
+  it('returns url unchanged when tokens is null', () => {
+    expect(appendTokens('/foo', null)).toBe('/foo')
+  })
+
+  it('returns url unchanged when tokens is undefined', () => {
+    expect(appendTokens('/foo', undefined)).toBe('/foo')
+  })
+
+  it('returns url unchanged when tokens is empty', () => {
+    expect(appendTokens('/foo', {})).toBe('/foo')
+  })
+
+  it('appends single token with ?', () => {
+    expect(appendTokens('/foo', { token: 'abc' })).toBe('/foo?token=abc')
+  })
+
+  it('appends multiple tokens', () => {
+    const result = appendTokens('/foo', { token: 'abc', model: 'gpt-4' })
+    expect(result).toBe('/foo?token=abc&model=gpt-4')
+  })
+
+  it('uses & separator when url already has query params', () => {
+    expect(appendTokens('/foo?flow=bar', { token: 'abc' })).toBe('/foo?flow=bar&token=abc')
+  })
+
+  it('filters out reserved key "flow"', () => {
+    expect(appendTokens('/foo', { flow: 'bad', token: 'good' })).toBe('/foo?token=good')
+  })
+
+  it('filters out reserved key "scene"', () => {
+    expect(appendTokens('/foo', { scene: 'bad', token: 'good' })).toBe('/foo?token=good')
+  })
+
+  it('filters out null and undefined values', () => {
+    expect(appendTokens('/foo', { a: null, b: undefined, c: 'ok' })).toBe('/foo?c=ok')
+  })
+
+  it('filters out object and array values', () => {
+    expect(appendTokens('/foo', { a: { nested: true }, b: [1, 2], c: 'ok' })).toBe('/foo?c=ok')
+  })
+
+  it('encodes special characters', () => {
+    expect(appendTokens('/foo', { key: 'hello world' })).toBe('/foo?key=hello%20world')
+  })
+
+  it('handles numeric and boolean values', () => {
+    expect(appendTokens('/foo', { count: 42, active: true })).toBe('/foo?count=42&active=true')
+  })
+})
+
+// ── resolveFlowRoute with tokens ──
+
+describe('resolveFlowRoute with tokens', () => {
+  it('appends tokens to a flow with explicit route', () => {
+    init({
+      flows: { 'with-tokens': { route: '/Overview', tokens: { token: 'sk-abc' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('with-tokens', [])).toBe('/Overview?flow=with-tokens&token=sk-abc')
+  })
+
+  it('appends tokens to a known-route match', () => {
+    init({
+      flows: { Dashboard: { heading: 'Hi', tokens: { model: 'gpt-4' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('Dashboard', ['Dashboard'])).toBe('/Dashboard?model=gpt-4')
+  })
+
+  it('appends tokens to inferred route', () => {
+    init({
+      flows: { 'inferred': { _route: '/Settings', tokens: { key: 'val' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('inferred', [])).toBe('/Settings?flow=inferred&key=val')
+  })
+
+  it('appends tokens to default flow fallback', () => {
+    init({
+      flows: { 'no-route': { title: 'No route', tokens: { api: '123' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('no-route', [])).toBe('/?flow=no-route&api=123')
+  })
+
+  it('does not append tokens when flow has none', () => {
+    init({
+      flows: { simple: { route: '/Page' } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('simple', [])).toBe('/Page?flow=simple')
+  })
+
+  it('appends tokens with meta.default route (no ?flow=)', () => {
+    init({
+      flows: { 'default-tokens': { _route: '/Home', meta: { default: true }, tokens: { key: 'val' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('default-tokens', [])).toBe('/Home?key=val')
+  })
+})

package/src/vite/server-plugin.js

@@ -567,6 +567,15 @@ export default function storyboardServer() {
           injectTo: 'head',
         })
 
+        // Inject dev domain name for branch bar display
+        if (config.devDomain) {
+          tags.push({
+            tag: 'script',
+            children: `window.__SB_DEV_DOMAIN__=${JSON.stringify(config.devDomain)}`,
+            injectTo: 'head',
+          })
+        }
+
         // Inject per-domain branch bar color (configurable via devDomainColor)
         if (config.devDomainColor) {
           tags.push({