@dfosco/storyboard-core 2.0.0 → 2.2.0

package/src/modes.test.js

@@ -10,6 +10,13 @@ import {
   on,
   off,
   emit,
+  initTools,
+  setToolAction,
+  setToolState,
+  getToolState,
+  getToolsForMode,
+  subscribeToTools,
+  getToolsSnapshot,
   _resetModes,
 } from './modes.js'
 
@@ -289,3 +296,212 @@ describe('modes config', () => {
     expect(isModesEnabled()).toBe(false)
   })
 })
+
+// ---------------------------------------------------------------------------
+// Tool registry
+// ---------------------------------------------------------------------------
+
+describe('tool registry', () => {
+  const SAMPLE_TOOLS = {
+    '*': [
+      { id: 'viewfinder', label: 'Viewfinder', group: 'dev' },
+      { id: 'reset-params', label: 'Reset all params', group: 'dev' },
+    ],
+    'present': [
+      { id: 'comments-toggle', label: 'Comments', group: 'tools' },
+    ],
+  }
+
+  describe('initTools', () => {
+    it('seeds the registry from config', () => {
+      initTools(SAMPLE_TOOLS)
+      const tools = getToolsForMode('present')
+      const ids = tools.map(t => t.id)
+      expect(ids).toContain('viewfinder')
+      expect(ids).toContain('comments-toggle')
+    })
+
+    it('wildcard tools appear in all modes', () => {
+      initTools(SAMPLE_TOOLS)
+      const protoTools = getToolsForMode('prototype')
+      expect(protoTools.map(t => t.id)).toContain('viewfinder')
+    })
+
+    it('mode-specific tools only appear in their mode', () => {
+      initTools(SAMPLE_TOOLS)
+      const protoTools = getToolsForMode('prototype')
+      expect(protoTools.map(t => t.id)).not.toContain('comments-toggle')
+    })
+
+    it('tools start with default state', () => {
+      initTools(SAMPLE_TOOLS)
+      const state = getToolState('viewfinder')
+      expect(state).toEqual({
+        enabled: true,
+        active: false,
+        busy: false,
+        hidden: false,
+        badge: null,
+      })
+    })
+
+    it('merges mode assignments when tool appears in multiple keys', () => {
+      initTools({
+        '*': [{ id: 'shared', label: 'Shared', group: 'dev' }],
+        'inspect': [{ id: 'shared', label: 'Shared', group: 'dev' }],
+      })
+      const tool = getToolsForMode('inspect').find(t => t.id === 'shared')
+      expect(tool.modes).toContain('*')
+      expect(tool.modes).toContain('inspect')
+    })
+  })
+
+  describe('setToolAction', () => {
+    it('wires up an action callback', () => {
+      initTools({ '*': [{ id: 'test-tool', label: 'Test', group: 'tools' }] })
+      const action = vi.fn()
+      setToolAction('test-tool', action)
+
+      const tool = getToolsForMode('prototype').find(t => t.id === 'test-tool')
+      expect(tool.action).toBe(action)
+    })
+
+    it('warns when tool is not declared', () => {
+      const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      setToolAction('nonexistent', () => {})
+      expect(spy).toHaveBeenCalledWith(expect.stringContaining('not declared'))
+      spy.mockRestore()
+    })
+
+    it('notifies subscribers', () => {
+      initTools({ '*': [{ id: 'tool-a', label: 'A', group: 'tools' }] })
+      const cb = vi.fn()
+      const unsub = subscribeToTools(cb)
+      setToolAction('tool-a', () => {})
+      expect(cb).toHaveBeenCalled()
+      unsub()
+    })
+  })
+
+  describe('setToolState', () => {
+    it('merges partial state updates', () => {
+      initTools({ '*': [{ id: 'tool-b', label: 'B', group: 'tools' }] })
+      setToolState('tool-b', { active: true })
+      expect(getToolState('tool-b').active).toBe(true)
+      expect(getToolState('tool-b').enabled).toBe(true) // unchanged
+    })
+
+    it('sets busy state', () => {
+      initTools({ '*': [{ id: 'tool-c', label: 'C', group: 'tools' }] })
+      setToolState('tool-c', { busy: true })
+      expect(getToolState('tool-c').busy).toBe(true)
+    })
+
+    it('sets badge', () => {
+      initTools({ '*': [{ id: 'tool-d', label: 'D', group: 'tools' }] })
+      setToolState('tool-d', { badge: 3 })
+      expect(getToolState('tool-d').badge).toBe(3)
+    })
+
+    it('warns when tool is not declared', () => {
+      const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      setToolState('nonexistent', { enabled: false })
+      expect(spy).toHaveBeenCalledWith(expect.stringContaining('not declared'))
+      spy.mockRestore()
+    })
+
+    it('notifies subscribers', () => {
+      initTools({ '*': [{ id: 'tool-e', label: 'E', group: 'tools' }] })
+      const cb = vi.fn()
+      const unsub = subscribeToTools(cb)
+      setToolState('tool-e', { active: true })
+      expect(cb).toHaveBeenCalled()
+      unsub()
+    })
+  })
+
+  describe('getToolsForMode', () => {
+    it('sorts tools group first, dev second', () => {
+      initTools({
+        '*': [
+          { id: 'dev-tool', label: 'Dev', group: 'dev' },
+          { id: 'main-tool', label: 'Main', group: 'tools' },
+        ],
+      })
+      const tools = getToolsForMode('prototype')
+      expect(tools[0].id).toBe('main-tool')
+      expect(tools[1].id).toBe('dev-tool')
+    })
+
+    it('sorts by order within a group', () => {
+      initTools({
+        '*': [
+          { id: 'b', label: 'B', group: 'tools', order: 20 },
+          { id: 'a', label: 'A', group: 'tools', order: 10 },
+        ],
+      })
+      const tools = getToolsForMode('prototype')
+      expect(tools[0].id).toBe('a')
+      expect(tools[1].id).toBe('b')
+    })
+
+    it('excludes hidden tools', () => {
+      initTools({ '*': [{ id: 'hidden-tool', label: 'Hidden', group: 'tools' }] })
+      setToolState('hidden-tool', { hidden: true })
+      const tools = getToolsForMode('prototype')
+      expect(tools.map(t => t.id)).not.toContain('hidden-tool')
+    })
+
+    it('includes state and action in returned tools', () => {
+      initTools({ '*': [{ id: 'full-tool', label: 'Full', group: 'tools' }] })
+      const action = vi.fn()
+      setToolAction('full-tool', action)
+      setToolState('full-tool', { active: true, badge: 5 })
+
+      const tool = getToolsForMode('prototype').find(t => t.id === 'full-tool')
+      expect(tool.state.active).toBe(true)
+      expect(tool.state.badge).toBe(5)
+      expect(tool.action).toBe(action)
+    })
+
+    it('returns null action when not wired up', () => {
+      initTools({ '*': [{ id: 'no-action', label: 'No Action', group: 'tools' }] })
+      const tool = getToolsForMode('prototype').find(t => t.id === 'no-action')
+      expect(tool.action).toBeNull()
+    })
+  })
+
+  describe('subscribeToTools', () => {
+    it('unsubscribe stops further calls', () => {
+      const cb = vi.fn()
+      const unsub = subscribeToTools(cb)
+      unsub()
+      initTools({ '*': [{ id: 'x', label: 'X', group: 'tools' }] })
+      expect(cb).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('getToolsSnapshot', () => {
+    it('changes when state changes', () => {
+      initTools({ '*': [{ id: 'snap-tool', label: 'Snap', group: 'tools' }] })
+      const snap1 = getToolsSnapshot()
+      setToolState('snap-tool', { active: true })
+      const snap2 = getToolsSnapshot()
+      expect(snap1).not.toBe(snap2)
+    })
+
+    it('changes when action is set', () => {
+      initTools({ '*': [{ id: 'snap-tool2', label: 'Snap2', group: 'tools' }] })
+      const snap1 = getToolsSnapshot()
+      setToolAction('snap-tool2', () => {})
+      const snap2 = getToolsSnapshot()
+      expect(snap1).not.toBe(snap2)
+    })
+  })
+
+  describe('getToolState', () => {
+    it('returns null for undeclared tools', () => {
+      expect(getToolState('nonexistent')).toBeNull()
+    })
+  })
+})

package/src/sceneDebug.js

@@ -1,15 +1,15 @@
 /**
- * Storyboard SceneDebug — a vanilla JS debug panel that displays scene data.
+ * Storyboard FlowDebug — a vanilla JS debug panel that displays flow data.
  *
  * Framework-agnostic: creates a DOM element, no React/Vue/etc. needed.
  *
  * Usage:
- *   import { mountSceneDebug } from '@dfosco/storyboard-core'
- *   mountSceneDebug(document.getElementById('debug'))
+ *   import { mountFlowDebug } from '@dfosco/storyboard-core'
+ *   mountFlowDebug(document.getElementById('debug'))
  *   // or
- *   mountSceneDebug() // appends to document.body
+ *   mountFlowDebug() // appends to document.body
  */
-import { loadScene } from './loader.js'
+import { loadFlow } from './loader.js'
 
 const STYLES = `
 .sb-scene-debug {
@@ -53,16 +53,17 @@ const STYLES = `
 let stylesInjected = false
 
 /**
- * Mount a scene debug panel into the DOM.
+ * Mount a flow debug panel into the DOM.
  *
  * @param {HTMLElement} [container=document.body] - Where to mount
- * @param {string} [sceneName] - Scene name override (defaults to ?scene= param or "default")
+ * @param {string} [flowName] - Flow name override (defaults to ?flow= param or "default")
  * @returns {HTMLElement} The created debug element
  */
-export function mountSceneDebug(container, sceneName) {
+export function mountFlowDebug(container, flowName) {
   const target = container || document.body
-  const activeSceneName = sceneName
-    || new URLSearchParams(window.location.search).get('scene')
+  const sp = new URLSearchParams(window.location.search)
+  const activeFlowName = flowName
+    || sp.get('flow') || sp.get('scene')
     || 'default'
 
   // Inject styles once
@@ -79,7 +80,7 @@ export function mountSceneDebug(container, sceneName) {
   let data = null
   let error = null
   try {
-    data = loadScene(activeSceneName)
+    data = loadFlow(activeFlowName)
   } catch (err) {
     error = err.message
   }
@@ -87,13 +88,13 @@ export function mountSceneDebug(container, sceneName) {
   if (error) {
     el.innerHTML = `
       <div class="sb-scene-debug-error">
-        <div class="sb-scene-debug-error-title">Error loading scene</div>
+        <div class="sb-scene-debug-error-title">Error loading flow</div>
         <p class="sb-scene-debug-error-message">${error}</p>
       </div>`
   } else {
     const title = document.createElement('h2')
     title.className = 'sb-scene-debug-title'
-    title.textContent = `Scene: ${activeSceneName}`
+    title.textContent = `Flow: ${activeFlowName}`
 
     const pre = document.createElement('pre')
     pre.className = 'sb-scene-debug-code'
@@ -106,3 +107,6 @@ export function mountSceneDebug(container, sceneName) {
   target.appendChild(el)
   return el
 }
+
+/** @deprecated Use mountFlowDebug() */
+export const mountSceneDebug = mountFlowDebug

package/src/sceneDebug.test.js

@@ -1,28 +1,28 @@
 import { vi } from 'vitest'
 
-const { mockLoadScene } = vi.hoisted(() => ({
-  mockLoadScene: vi.fn(() => ({ hello: 'world', count: 42 })),
+const { mockLoadFlow } = vi.hoisted(() => ({
+  mockLoadFlow: vi.fn(() => ({ hello: 'world', count: 42 })),
 }))
 
 vi.mock('./loader.js', () => ({
-  loadScene: mockLoadScene,
+  loadFlow: mockLoadFlow,
 }))
 
 // We need a fresh module for each test since sceneDebug has a module-level
 // `stylesInjected` boolean. We test style injection on the very first call,
 // then subsequent tests just verify other behavior.
-import { mountSceneDebug } from './sceneDebug.js'
+import { mountFlowDebug, mountSceneDebug } from './sceneDebug.js'
 
 afterEach(() => {
   document.body.innerHTML = ''
-  mockLoadScene.mockReset()
-  mockLoadScene.mockReturnValue({ hello: 'world', count: 42 })
+  mockLoadFlow.mockReset()
+  mockLoadFlow.mockReturnValue({ hello: 'world', count: 42 })
 })
 
-describe('mountSceneDebug', () => {
+describe('mountFlowDebug', () => {
   it('injects styles into document.head on first call', () => {
     // This MUST run first to capture the stylesInjected=false → true transition
-    mountSceneDebug()
+    mountFlowDebug()
 
     const styles = document.head.querySelectorAll('style')
     const hasDebugStyle = Array.from(styles).some((el) =>
@@ -32,13 +32,13 @@ describe('mountSceneDebug', () => {
   })
 
   it('creates an element with class sb-scene-debug', () => {
-    const el = mountSceneDebug()
+    const el = mountFlowDebug()
 
     expect(el.classList.contains('sb-scene-debug')).toBe(true)
   })
 
   it('appends to document.body by default', () => {
-    mountSceneDebug()
+    mountFlowDebug()
 
     expect(document.body.querySelector('.sb-scene-debug')).toBeInTheDocument()
   })
@@ -47,36 +47,36 @@ describe('mountSceneDebug', () => {
     const container = document.createElement('div')
     document.body.appendChild(container)
 
-    mountSceneDebug(container)
+    mountFlowDebug(container)
 
     expect(container.querySelector('.sb-scene-debug')).not.toBeNull()
   })
 
   it('returns the created element', () => {
-    const el = mountSceneDebug()
+    const el = mountFlowDebug()
 
     expect(el).toBeInstanceOf(HTMLElement)
     expect(el.className).toBe('sb-scene-debug')
   })
 
-  it('renders the scene name in the title', () => {
-    mountSceneDebug(undefined, 'my-scene')
+  it('renders the flow name in the title', () => {
+    mountFlowDebug(undefined, 'my-flow')
 
     const title = document.body.querySelector('.sb-scene-debug-title')
     expect(title).not.toBeNull()
-    expect(title.textContent).toContain('my-scene')
+    expect(title.textContent).toContain('my-flow')
   })
 
-  it('defaults scene name to "default" when none is provided', () => {
-    mountSceneDebug()
+  it('defaults flow name to "default" when none is provided', () => {
+    mountFlowDebug()
 
     const title = document.body.querySelector('.sb-scene-debug-title')
     expect(title.textContent).toContain('default')
-    expect(mockLoadScene).toHaveBeenCalledWith('default')
+    expect(mockLoadFlow).toHaveBeenCalledWith('default')
   })
 
   it('renders JSON data in a pre element', () => {
-    mountSceneDebug()
+    mountFlowDebug()
 
     const pre = document.body.querySelector('.sb-scene-debug-code')
     expect(pre).not.toBeNull()
@@ -86,31 +86,31 @@ describe('mountSceneDebug', () => {
     expect(parsed).toEqual({ hello: 'world', count: 42 })
   })
 
-  it('shows error when loadScene throws', () => {
-    mockLoadScene.mockImplementation(() => {
-      throw new Error('Scene not found')
+  it('shows error when loadFlow throws', () => {
+    mockLoadFlow.mockImplementation(() => {
+      throw new Error('Flow not found')
     })
 
-    const el = mountSceneDebug()
+    const el = mountFlowDebug()
 
     const errorTitle = el.querySelector('.sb-scene-debug-error-title')
     expect(errorTitle).not.toBeNull()
     expect(errorTitle.textContent).toContain('Error')
 
     const errorMsg = el.querySelector('.sb-scene-debug-error-message')
-    expect(errorMsg.textContent).toContain('Scene not found')
+    expect(errorMsg.textContent).toContain('Flow not found')
 
     // Should NOT render the normal title/pre
     expect(el.querySelector('.sb-scene-debug-title')).toBeNull()
     expect(el.querySelector('.sb-scene-debug-code')).toBeNull()
   })
 
-  it('uses ?scene query param when no sceneName argument is given', () => {
+  it('uses ?scene query param when no flowName argument is given', () => {
     window.history.pushState(null, '', '?scene=overview')
 
-    mountSceneDebug()
+    mountFlowDebug()
 
-    expect(mockLoadScene).toHaveBeenCalledWith('overview')
+    expect(mockLoadFlow).toHaveBeenCalledWith('overview')
     const title = document.body.querySelector('.sb-scene-debug-title')
     expect(title.textContent).toContain('overview')
 
@@ -119,10 +119,23 @@ describe('mountSceneDebug', () => {
   })
 
   it('allows multiple debug panels to be mounted', () => {
-    mountSceneDebug()
-    mountSceneDebug()
+    mountFlowDebug()
+    mountFlowDebug()
 
     const panels = document.body.querySelectorAll('.sb-scene-debug')
     expect(panels).toHaveLength(2)
   })
 })
+
+// ── mountSceneDebug (deprecated alias) ──
+
+describe('mountSceneDebug (deprecated alias)', () => {
+  it('is the same function as mountFlowDebug', () => {
+    expect(mountSceneDebug).toBe(mountFlowDebug)
+  })
+
+  it('mounts a debug panel', () => {
+    const el = mountSceneDebug()
+    expect(el.classList.contains('sb-scene-debug')).toBe(true)
+  })
+})

package/src/svelte-plugin-ui/__tests__/ToolbarShell.test.ts

@@ -2,7 +2,9 @@ import { describe, it, expect, afterEach } from 'vitest'
 import { render, screen } from '@testing-library/svelte'
 import {
   registerMode,
-  activateMode,
+  initTools,
+  setToolAction,
+  setToolState,
 } from '@dfosco/storyboard-core'
 import { _resetModes } from '@test/modes'
 import ToolbarShell from '../components/ToolbarShell.svelte'
@@ -15,20 +17,22 @@ afterEach(() => {
 })
 
 describe('ToolbarShell', () => {
-  it('renders nothing when current mode has no tools', () => {
+  it('renders nothing when no tools are declared', () => {
     registerMode('prototype', { label: 'Navigate' })
     const { container } = render(ToolbarShell)
     expect(container.querySelector('[role="toolbar"]')).toBeNull()
   })
 
-  it('renders tool buttons for mode with tools', () => {
-    registerMode('prototype', {
-      label: 'Navigate',
-      tools: [
-        { id: 'zoom', label: 'Zoom', action: () => {} },
-        { id: 'pan', label: 'Pan', action: () => {} },
+  it('renders tool buttons from the tool registry', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [
+        { id: 'zoom', label: 'Zoom', group: 'tools' },
+        { id: 'pan', label: 'Pan', group: 'tools' },
       ],
     })
+    setToolAction('zoom', () => {})
+    setToolAction('pan', () => {})
 
     render(ToolbarShell)
 
@@ -36,13 +40,12 @@ describe('ToolbarShell', () => {
     expect(screen.getByTitle('Pan')).toBeInTheDocument()
   })
 
-  it('renders dev tools section when mode has devTools', () => {
-    registerMode('prototype', {
-      label: 'Navigate',
-      devTools: [
-        { id: 'debug', label: 'Debug', action: () => {} },
-      ],
+  it('renders dev tools section', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [{ id: 'debug', label: 'Debug', group: 'dev' }],
     })
+    setToolAction('debug', () => {})
 
     render(ToolbarShell)
 
@@ -50,12 +53,16 @@ describe('ToolbarShell', () => {
     expect(screen.getByText('Dev')).toBeInTheDocument()
   })
 
-  it('renders both tool groups when mode has both', () => {
-    registerMode('prototype', {
-      label: 'Navigate',
-      tools: [{ id: 'zoom', label: 'Zoom', action: () => {} }],
-      devTools: [{ id: 'debug', label: 'Debug', action: () => {} }],
+  it('renders both tool groups', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [
+        { id: 'zoom', label: 'Zoom', group: 'tools' },
+        { id: 'debug', label: 'Debug', group: 'dev' },
+      ],
     })
+    setToolAction('zoom', () => {})
+    setToolAction('debug', () => {})
 
     render(ToolbarShell)
 
@@ -64,4 +71,55 @@ describe('ToolbarShell', () => {
     expect(screen.getByText('Tools')).toBeInTheDocument()
     expect(screen.getByText('Dev')).toBeInTheDocument()
   })
+
+  it('disables tools without an action', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [{ id: 'no-action', label: 'No Action', group: 'tools' }],
+    })
+
+    render(ToolbarShell)
+
+    const btn = screen.getByTitle('No Action')
+    expect(btn).toBeDisabled()
+  })
+
+  it('disables tools with enabled: false state', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [{ id: 'disabled-tool', label: 'Disabled', group: 'tools' }],
+    })
+    setToolAction('disabled-tool', () => {})
+    setToolState('disabled-tool', { enabled: false })
+
+    render(ToolbarShell)
+
+    const btn = screen.getByTitle('Disabled')
+    expect(btn).toBeDisabled()
+  })
+
+  it('hides tools with hidden: true state', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [{ id: 'hidden-tool', label: 'Hidden', group: 'tools' }],
+    })
+    setToolState('hidden-tool', { hidden: true })
+
+    const { container } = render(ToolbarShell)
+
+    expect(container.querySelector('[role="toolbar"]')).toBeNull()
+  })
+
+  it('renders badge when present', () => {
+    registerMode('prototype', { label: 'Navigate' })
+    initTools({
+      '*': [{ id: 'badged', label: 'Badged', group: 'tools' }],
+    })
+    setToolAction('badged', () => {})
+    setToolState('badged', { badge: 5 })
+
+    render(ToolbarShell)
+
+    expect(screen.getByText('5')).toBeInTheDocument()
+  })
 })

package/src/svelte-plugin-ui/__tests__/designModes.test.ts

@@ -3,7 +3,7 @@ import {
   registerMode,
 } from '@dfosco/storyboard-core'
 import { _resetModes } from '@test/modes'
-import { mountDesignModesUI, unmountDesignModesUI } from '../plugins/design-modes.js'
+import { mountDesignModesUI, unmountDesignModesUI } from '../../ui/design-modes.js'
 
 afterEach(() => {
   unmountDesignModesUI()