@dfosco/storyboard-core 4.2.3 → 4.2.5

package/package.json

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

package/scaffold/gitignore

@@ -0,0 +1,64 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/packages/**/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+/dist
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.playwright-profile
+
+.github/skills/_archive
+.github/skills/primer-primitives
+.github/skills/primer-components-catalog
+.github/skills/primer-screenshot-builder
+.github/skills/primer-screenshot-patterns
+.github/skills/primer-url-builder
+.github/skills/playwright-cli
+.worktrees
+# Agent symlinks are build targets — source of truth is .agents/agents/
+# storyboard setup creates symlinks for Copilot CLI and Claude Code
+.github/agents/_buddy-rails.md
+.github/agents/_buddy.md
+.github/agents/terminal-agent.md
+.github/agents/prompt-agent.md
+.claude/agents/
+_*.md
+
+# Compiled UI bundle (built before publish, not tracked in git)
+packages/core/dist/storyboard-ui.*
+
+.clips
+
+# Agent Browser
+agent-browser.json
+
+# Selected widgets bridge (real-time canvas selection for Copilot)
+.storyboard
+
+# Private canvas images (tilde prefix = not committed)
+src/canvas/images/~*
+assets/canvas/images/~*
+assets/canvas/snapshots/~*
+assets/.storyboard-public/terminal-snapshots/~*
+.sync-target
+
+# Integration test results (ephemeral local artifacts)
+test-results/

package/scaffold/manifest.json

@@ -6,7 +6,7 @@
       "mode": "updateable"
     },
     {
-      "source": "scaffold/.gitignore",
+      "source": "scaffold/gitignore",
       "target": ".gitignore",
       "mode": "updateable"
     },

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/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/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({