@dfosco/storyboard-core 2.0.0 → 2.2.0

package/src/loader.test.js

@@ -1,7 +1,7 @@
-import { init, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge } from './loader.js'
+import { init, loadFlow, listFlows, flowExists, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge, resolveFlowName, resolveRecordName } from './loader.js'
 
 const makeIndex = () => ({
-  scenes: {
+  flows: {
     default: {
       title: 'Default Scene',
       user: { $ref: 'jane-doe' },
@@ -72,111 +72,149 @@ describe('init', () => {
     expect(() => init('string')).toThrow()
   })
 
-  it('stores data so loadScene works', () => {
+  it('stores data so loadFlow works', () => {
     init(makeIndex())
-    const scene = loadScene('default')
-    expect(scene.title).toBe('Default Scene')
+    const flow = loadFlow('default')
+    expect(flow.title).toBe('Default Scene')
   })
 
   it('handles missing properties gracefully', () => {
     init({})
-    expect(sceneExists('anything')).toBe(false)
+    expect(flowExists('anything')).toBe(false)
+  })
+
+  it('accepts { scenes } for backward compat', () => {
+    init({ scenes: { legacy: { title: 'Legacy' } }, objects: {}, records: {} })
+    expect(flowExists('legacy')).toBe(true)
   })
 })
 
-describe('loadScene', () => {
-  it('loads scene by name', () => {
-    const scene = loadScene('empty')
-    expect(scene).toEqual({})
+describe('loadFlow', () => {
+  it('loads flow by name', () => {
+    const flow = loadFlow('empty')
+    expect(flow).toEqual({})
   })
 
   it('resolves $ref to objects', () => {
-    const scene = loadScene('default')
-    expect(scene.user).toEqual({ name: 'Jane Doe', role: 'admin' })
+    const flow = loadFlow('default')
+    expect(flow.user).toEqual({ name: 'Jane Doe', role: 'admin' })
   })
 
   it('resolves nested $ref', () => {
-    const scene = loadScene('with-nested-ref')
-    expect(scene.team.lead).toEqual({ name: 'Jane Doe', role: 'admin' })
+    const flow = loadFlow('with-nested-ref')
+    expect(flow.team.lead).toEqual({ name: 'Jane Doe', role: 'admin' })
   })
 
-  it('resolves $global and merges into root, scene wins conflicts', () => {
-    const scene = loadScene('Dashboard')
-    expect(scene.links).toEqual(['home', 'about'])
-    expect(scene.heading).toBe('Dashboard')
-    // scene value should win over global value
-    expect(scene.nav).toBe('scene-wins')
+  it('resolves $global and merges into root, flow wins conflicts', () => {
+    const flow = loadFlow('Dashboard')
+    expect(flow.links).toEqual(['home', 'about'])
+    expect(flow.heading).toBe('Dashboard')
+    // flow value should win over global value
+    expect(flow.nav).toBe('scene-wins')
   })
 
-  it('throws for missing scene', () => {
-    expect(() => loadScene('nonexistent')).toThrow()
+  it('throws for missing flow', () => {
+    expect(() => loadFlow('nonexistent')).toThrow()
   })
 
   it('case-insensitive lookup', () => {
-    const scene = loadScene('dashboard')
-    expect(scene.heading).toBe('Dashboard')
+    const flow = loadFlow('dashboard')
+    expect(flow.heading).toBe('Dashboard')
   })
 
   it('returns deep clone (mutations do not affect index)', () => {
-    const scene1 = loadScene('empty')
-    scene1.injected = true
-    const scene2 = loadScene('empty')
-    expect(scene2.injected).toBeUndefined()
+    const flow1 = loadFlow('empty')
+    flow1.injected = true
+    const flow2 = loadFlow('empty')
+    expect(flow2.injected).toBeUndefined()
   })
 
   it('resolves $global on repeated calls (no index mutation)', () => {
-    const first = loadScene('Dashboard')
+    const first = loadFlow('Dashboard')
     expect(first.links).toEqual(['home', 'about'])
     expect(first.heading).toBe('Dashboard')
 
     // Second call must return the same resolved data — $global must not
     // be deleted from the index by the first call
-    const second = loadScene('Dashboard')
+    const second = loadFlow('Dashboard')
     expect(second.links).toEqual(['home', 'about'])
     expect(second.heading).toBe('Dashboard')
     expect(second.nav).toBe('scene-wins')
   })
 
-  it('default param loads "default" scene', () => {
-    const scene = loadScene()
-    expect(scene.title).toBe('Default Scene')
+  it('default param loads "default" flow', () => {
+    const flow = loadFlow()
+    expect(flow.title).toBe('Default Scene')
   })
 
   it('detects circular $ref and throws', () => {
-    expect(() => loadScene('circular-a')).toThrow(/circular/i)
+    expect(() => loadFlow('circular-a')).toThrow(/circular/i)
   })
 })
 
-describe('sceneExists', () => {
-  it('returns true for existing scene', () => {
-    expect(sceneExists('default')).toBe(true)
+describe('flowExists', () => {
+  it('returns true for existing flow', () => {
+    expect(flowExists('default')).toBe(true)
   })
 
-  it('returns false for missing scene', () => {
-    expect(sceneExists('nope')).toBe(false)
+  it('returns false for missing flow', () => {
+    expect(flowExists('nope')).toBe(false)
   })
 
   it('is case-insensitive', () => {
-    expect(sceneExists('dashboard')).toBe(true)
-    expect(sceneExists('DASHBOARD')).toBe(true)
+    expect(flowExists('dashboard')).toBe(true)
+    expect(flowExists('DASHBOARD')).toBe(true)
   })
 })
 
-describe('listScenes', () => {
-  it('returns all scene names', () => {
-    const names = listScenes()
+describe('listFlows', () => {
+  it('returns all flow names', () => {
+    const names = listFlows()
     expect(names).toContain('default')
     expect(names).toContain('Dashboard')
     expect(names).toContain('empty')
   })
 
   it('returns an array', () => {
-    expect(Array.isArray(listScenes())).toBe(true)
+    expect(Array.isArray(listFlows())).toBe(true)
   })
 
-  it('returns empty array when no scenes registered', () => {
-    init({ scenes: {}, objects: {}, records: {} })
-    expect(listScenes()).toEqual([])
+  it('returns empty array when no flows registered', () => {
+    init({ flows: {}, objects: {}, records: {} })
+    expect(listFlows()).toEqual([])
+  })
+})
+
+// ── Deprecated aliases ──
+
+describe('loadScene (deprecated alias)', () => {
+  it('is the same function as loadFlow', () => {
+    expect(loadScene).toBe(loadFlow)
+  })
+
+  it('loads flow data', () => {
+    const scene = loadScene('default')
+    expect(scene.title).toBe('Default Scene')
+  })
+})
+
+describe('sceneExists (deprecated alias)', () => {
+  it('is the same function as flowExists', () => {
+    expect(sceneExists).toBe(flowExists)
+  })
+
+  it('returns true for existing flow', () => {
+    expect(sceneExists('default')).toBe(true)
+  })
+})
+
+describe('listScenes (deprecated alias)', () => {
+  it('is the same function as listFlows', () => {
+    expect(listScenes).toBe(listFlows)
+  })
+
+  it('returns all flow names', () => {
+    expect(listScenes()).toContain('default')
   })
 })
 
@@ -275,3 +313,106 @@ describe('loadObject', () => {
     expect(() => loadObject('circular-obj-a')).toThrow(/circular/i)
   })
 })
+
+describe('resolveFlowName', () => {
+  beforeEach(() => {
+    init({
+      flows: {
+        default: { title: 'Global Default' },
+        signup: { title: 'Global Signup' },
+        'Dashboard/default': { title: 'Dashboard Default' },
+        'Dashboard/signup': { title: 'Dashboard Signup' },
+        'Blog/default': { title: 'Blog Default' },
+      },
+      objects: {},
+      records: {},
+    })
+  })
+
+  it('returns scoped name when it exists', () => {
+    expect(resolveFlowName('Dashboard', 'default')).toBe('Dashboard/default')
+    expect(resolveFlowName('Dashboard', 'signup')).toBe('Dashboard/signup')
+  })
+
+  it('falls back to global name when scoped does not exist', () => {
+    expect(resolveFlowName('Blog', 'signup')).toBe('signup')
+  })
+
+  it('returns global name when scope is null', () => {
+    expect(resolveFlowName(null, 'default')).toBe('default')
+    expect(resolveFlowName(null, 'signup')).toBe('signup')
+  })
+
+  it('returns scoped name for error messages when neither exists', () => {
+    expect(resolveFlowName('Dashboard', 'nonexistent')).toBe('Dashboard/nonexistent')
+  })
+
+  it('returns plain name for error messages when scope is null and name does not exist', () => {
+    expect(resolveFlowName(null, 'nonexistent')).toBe('nonexistent')
+  })
+
+  it('handles already-scoped names (explicit cross-prototype)', () => {
+    expect(resolveFlowName('Blog', 'Dashboard/signup')).toBe('Dashboard/signup')
+  })
+})
+
+describe('resolveRecordName', () => {
+  beforeEach(() => {
+    init({
+      flows: {},
+      objects: {},
+      records: {
+        posts: [{ id: '1' }],
+        'Dashboard/metrics': [{ id: 'm1' }],
+        'Dashboard/posts': [{ id: 'd1' }],
+      },
+    })
+  })
+
+  it('returns scoped name when it exists', () => {
+    expect(resolveRecordName('Dashboard', 'metrics')).toBe('Dashboard/metrics')
+    expect(resolveRecordName('Dashboard', 'posts')).toBe('Dashboard/posts')
+  })
+
+  it('falls back to global when scoped does not exist', () => {
+    expect(resolveRecordName('Blog', 'posts')).toBe('posts')
+  })
+
+  it('returns global when scope is null', () => {
+    expect(resolveRecordName(null, 'posts')).toBe('posts')
+  })
+})
+
+describe('error hints for scoped data', () => {
+  beforeEach(() => {
+    init({
+      flows: {
+        'Dashboard/signup': { title: 'Dashboard Signup' },
+        default: { title: 'Global Default' },
+      },
+      objects: {},
+      records: {
+        'Blog/posts': [{ id: '1' }],
+        tags: [{ id: 'js' }],
+      },
+    })
+  })
+
+  it('loadFlow error suggests scoped alternatives', () => {
+    expect(() => loadFlow('signup')).toThrow(/Did you mean: Dashboard\/signup/)
+  })
+
+  it('loadRecord error suggests scoped alternatives', () => {
+    expect(() => loadRecord('posts')).toThrow(/Did you mean: Blog\/posts/)
+  })
+
+  it('loadFlow error for truly missing name has no hint', () => {
+    expect(() => loadFlow('xyz')).toThrow(/Failed to load flow: xyz/)
+    expect(() => loadFlow('xyz')).not.toThrow(/Did you mean/)
+  })
+
+  it('loadRecord error for truly missing name has no hint', () => {
+    expect(() => loadRecord('xyz')).toThrow(/Record not found: xyz/)
+    expect(() => loadRecord('xyz')).not.toThrow(/Did you mean/)
+  })
+})

package/src/modes.js

@@ -17,6 +17,12 @@ const DEFAULT_MODE = 'prototype'
 
 let _modesEnabled = false
 
+// Tool registry — seeded from modes.config.json, state managed at runtime
+const _tools = new Map()          // id → { id, label, group, modes[] }
+const _toolState = new Map()      // id → { enabled, active, busy, hidden, badge }
+const _toolActions = new Map()    // id → action function
+const _toolListeners = new Set()  // subscribers to tool state/action changes
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -281,6 +287,166 @@ export function isModesEnabled() {
   return _modesEnabled
 }
 
+// ---------------------------------------------------------------------------
+// Tool registry
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TOOL_STATE = Object.freeze({
+  enabled: true,
+  active: false,
+  busy: false,
+  hidden: false,
+  badge: null,
+})
+
+/**
+ * Seed the tool registry from modes.config.json.
+ * Called by the Vite data plugin's generated virtual module.
+ *
+ * @param {Record<string, Array<{ id: string, label: string, group: string }>>} config
+ *        Keys are mode names or '*' (all modes). Values are tool declarations.
+ */
+export function initTools(config = {}) {
+  for (const [modeKey, tools] of Object.entries(config)) {
+    if (!Array.isArray(tools)) continue
+    for (const tool of tools) {
+      if (!tool.id) continue
+      const existing = _tools.get(tool.id)
+      if (existing) {
+        // Merge mode assignments (tool declared in multiple mode keys)
+        if (!existing.modes.includes(modeKey)) {
+          existing.modes.push(modeKey)
+        }
+      } else {
+        _tools.set(tool.id, {
+          id: tool.id,
+          label: tool.label ?? tool.id,
+          group: tool.group ?? 'tools',
+          icon: tool.icon ?? null,
+          order: tool.order ?? 100,
+          modes: [modeKey],
+        })
+        _toolState.set(tool.id, { ...DEFAULT_TOOL_STATE })
+      }
+    }
+  }
+  _notifyTools()
+}
+
+/**
+ * Wire up a click handler for a declared tool.
+ * Plugins call this to provide the action callback.
+ *
+ * @param {string} id       Tool id (must exist in registry)
+ * @param {Function} action Click handler
+ */
+export function setToolAction(id, action) {
+  if (!_tools.has(id)) {
+    console.warn(`[storyboard] Tool "${id}" is not declared in modes.config.json.`)
+    return
+  }
+  _toolActions.set(id, action)
+  _notifyTools()
+}
+
+/**
+ * Update the runtime state of a tool.
+ * Merges the update into existing state — only the provided keys change.
+ *
+ * @param {string} id    Tool id (must exist in registry)
+ * @param {object} state Partial state update
+ * @param {boolean} [state.enabled]  Whether the tool can be interacted with
+ * @param {boolean} [state.active]   Whether the tool is currently "on" (highlighted)
+ * @param {boolean} [state.busy]     Whether the tool is in use / unavailable
+ * @param {boolean} [state.hidden]   Whether the tool should be hidden entirely
+ * @param {string|number|null} [state.badge] Notification badge
+ */
+export function setToolState(id, state = {}) {
+  if (!_tools.has(id)) {
+    console.warn(`[storyboard] Tool "${id}" is not declared in modes.config.json.`)
+    return
+  }
+  const current = _toolState.get(id) ?? { ...DEFAULT_TOOL_STATE }
+  _toolState.set(id, { ...current, ...state })
+  _notifyTools()
+}
+
+/**
+ * Get the current runtime state of a tool.
+ *
+ * @param {string} id Tool id
+ * @returns {{ enabled: boolean, active: boolean, busy: boolean, hidden: boolean, badge: string|number|null } | null}
+ */
+export function getToolState(id) {
+  return _toolState.get(id) ?? null
+}
+
+/**
+ * Get all tools for a given mode, merged with '*' wildcard tools.
+ * Returns tool declarations with their current state and action.
+ * Sorted by group (tools first, dev second), then by order.
+ *
+ * @param {string} modeName
+ * @returns {Array<{ id, label, group, icon, order, modes, state, action }>}
+ */
+export function getToolsForMode(modeName) {
+  const result = []
+  for (const [id, tool] of _tools) {
+    if (!tool.modes.includes(modeName) && !tool.modes.includes('*')) continue
+    const state = _toolState.get(id) ?? { ...DEFAULT_TOOL_STATE }
+    if (state.hidden) continue
+    result.push({
+      ...tool,
+      state,
+      action: _toolActions.get(id) ?? null,
+    })
+  }
+  // Sort: 'tools' group before 'dev', then by order
+  const groupOrder = { tools: 0, dev: 1 }
+  result.sort((a, b) => {
+    const ga = groupOrder[a.group] ?? 0
+    const gb = groupOrder[b.group] ?? 0
+    if (ga !== gb) return ga - gb
+    return (a.order ?? 100) - (b.order ?? 100)
+  })
+  return result
+}
+
+/**
+ * Subscribe to tool state/action changes.
+ * Compatible with React's useSyncExternalStore.
+ *
+ * @param {Function} callback Called on any tool change
+ * @returns {Function} Unsubscribe function
+ */
+export function subscribeToTools(callback) {
+  _toolListeners.add(callback)
+  return () => _toolListeners.delete(callback)
+}
+
+/**
+ * Snapshot for useSyncExternalStore.
+ * Returns a serialised string that changes when tool state/actions change.
+ */
+export function getToolsSnapshot() {
+  const entries = []
+  for (const [id, state] of _toolState) {
+    const hasAction = _toolActions.has(id) ? '1' : '0'
+    entries.push(`${id}:${state.enabled}:${state.active}:${state.busy}:${state.hidden}:${state.badge}:${hasAction}`)
+  }
+  return entries.join('|')
+}
+
+function _notifyTools() {
+  for (const cb of _toolListeners) {
+    try {
+      cb()
+    } catch (err) {
+      console.error('[storyboard] Error in tool subscriber:', err)
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------
@@ -292,5 +458,9 @@ export function _resetModes() {
   _modes.clear()
   _listeners.clear()
   _eventListeners.clear()
+  _tools.clear()
+  _toolState.clear()
+  _toolActions.clear()
+  _toolListeners.clear()
   _modesEnabled = false
 }