@dfosco/storyboard 0.5.0-alpha.0

package/src/core/session/session.js

@@ -0,0 +1,76 @@
+/**
+ * URL hash-based utilities for storyboard session state.
+ *
+ * Session params are stored in the URL hash fragment (after #) to avoid
+ * triggering React Router re-renders. React Router (used by generouted)
+ * patches history.replaceState/pushState, so any search-param change
+ * causes a full route tree re-render. The hash is invisible to the router.
+ *
+ * Format:  #key1=value1&key2=value2
+ * Example: /page?scene=default#user.name=Alice&settings.theme=dark
+ */
+
+/**
+ * Parse the current hash into a Map of key→value pairs.
+ * @returns {URLSearchParams}
+ */
+function parseHash() {
+  const raw = window.location.hash.replace(/^#/, '')
+  return new URLSearchParams(raw)
+}
+
+/**
+ * Write a URLSearchParams back to the hash.
+ * Uses window.location.hash (NOT history.replaceState) because
+ * generouted/React Router patches replaceState and would trigger
+ * a full route re-render. Native hash assignment only fires
+ * 'hashchange' which React Router ignores.
+ * @param {URLSearchParams} params
+ */
+function writeHash(params) {
+  const str = params.toString()
+  window.location.hash = str
+}
+
+/**
+ * Read a single session param value.
+ * @param {string} key
+ * @returns {string|null}
+ */
+export function getParam(key) {
+  return parseHash().get(key)
+}
+
+/**
+ * Write a single session param. Updates the hash in-place.
+ * @param {string} key
+ * @param {string} value
+ */
+export function setParam(key, value) {
+  const params = parseHash()
+  params.set(key, String(value))
+  writeHash(params)
+}
+
+/**
+ * Return all session params as a plain object.
+ * @returns {Record<string, string>}
+ */
+export function getAllParams() {
+  const params = parseHash()
+  const result = {}
+  for (const [key, value] of params.entries()) {
+    result[key] = value
+  }
+  return result
+}
+
+/**
+ * Remove a single session param from the hash.
+ * @param {string} key
+ */
+export function removeParam(key) {
+  const params = parseHash()
+  params.delete(key)
+  writeHash(params)
+}

package/src/core/session/session.test.js

@@ -0,0 +1,91 @@
+import { getParam, setParam, getAllParams, removeParam } from './session.js'
+
+describe('getParam', () => {
+  it('returns null when hash is empty', () => {
+    window.location.hash = ''
+    expect(getParam('key')).toBeNull()
+  })
+
+  it('returns value for existing param', () => {
+    window.location.hash = 'foo=bar'
+    expect(getParam('foo')).toBe('bar')
+  })
+
+  it('returns null for missing param', () => {
+    window.location.hash = 'foo=bar'
+    expect(getParam('missing')).toBeNull()
+  })
+
+  it('handles URL-encoded values', () => {
+    window.location.hash = 'name=hello%20world'
+    expect(getParam('name')).toBe('hello world')
+  })
+})
+
+describe('setParam', () => {
+  it('sets a new param in hash', () => {
+    window.location.hash = ''
+    setParam('key', 'value')
+    expect(getParam('key')).toBe('value')
+  })
+
+  it('updates existing param', () => {
+    window.location.hash = 'key=old'
+    setParam('key', 'new')
+    expect(getParam('key')).toBe('new')
+  })
+
+  it('preserves other params', () => {
+    window.location.hash = 'a=1&b=2'
+    setParam('c', '3')
+    expect(getParam('a')).toBe('1')
+    expect(getParam('b')).toBe('2')
+    expect(getParam('c')).toBe('3')
+  })
+
+  it('converts value to string', () => {
+    window.location.hash = ''
+    setParam('num', 42)
+    expect(getParam('num')).toBe('42')
+  })
+})
+
+describe('getAllParams', () => {
+  it('returns empty object for empty hash', () => {
+    window.location.hash = ''
+    expect(getAllParams()).toEqual({})
+  })
+
+  it('returns all params', () => {
+    window.location.hash = 'a=1&b=2'
+    expect(getAllParams()).toEqual({ a: '1', b: '2' })
+  })
+
+  it('handles multiple params', () => {
+    window.location.hash = 'x=hello&y=world&z=test'
+    const params = getAllParams()
+    expect(Object.keys(params)).toHaveLength(3)
+    expect(params).toEqual({ x: 'hello', y: 'world', z: 'test' })
+  })
+})
+
+describe('removeParam', () => {
+  it('removes existing param', () => {
+    window.location.hash = 'a=1&b=2'
+    removeParam('a')
+    expect(getParam('a')).toBeNull()
+  })
+
+  it('preserves other params', () => {
+    window.location.hash = 'a=1&b=2&c=3'
+    removeParam('b')
+    expect(getParam('a')).toBe('1')
+    expect(getParam('c')).toBe('3')
+  })
+
+  it('no-ops for missing param', () => {
+    window.location.hash = 'a=1'
+    removeParam('nonexistent')
+    expect(getParam('a')).toBe('1')
+  })
+})

package/src/core/stores/canvasConfig.js

@@ -0,0 +1,134 @@
+/**
+ * Canvas Config — project-level overrides for canvas behavior.
+ *
+ * Client repos use the "canvas" key in storyboard.config.json to customize
+ * canvas paste rules and other canvas-level settings.
+ *
+ *   {
+ *     "canvas": {
+ *       "pasteRules": [
+ *         { "pattern": "youtube\\.com/watch", "type": "link-preview", "props": { "url": "$url" } }
+ *       ]
+ *     }
+ *   }
+ *
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+let _pasteRules = []
+let _terminal = {}
+let _agents = {}
+let _zoom = { min: 10, max: 250, step: 10 }
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize canvas config from storyboard.config.json's "canvas" key.
+ * Called by mountStoryboardCore.
+ *
+ * @param {{ pasteRules?: object[], terminal?: object, agents?: object, zoom?: object }} [config]
+ */
+export function initCanvasConfig(config = {}) {
+  _pasteRules = Array.isArray(config.pasteRules) ? config.pasteRules : []
+  _terminal = config.terminal && typeof config.terminal === 'object' ? config.terminal : {}
+  _agents = config.agents && typeof config.agents === 'object' ? config.agents : {}
+  _zoom = config.zoom && typeof config.zoom === 'object'
+    ? { min: config.zoom.min ?? 10, max: config.zoom.max ?? 250, step: config.zoom.step ?? 10 }
+    : { min: 10, max: 250, step: 10 }
+}
+
+/**
+ * Get the configured paste rules (raw config objects).
+ *
+ * @returns {object[]}
+ */
+export function getPasteRules() {
+  return _pasteRules
+}
+
+/**
+ * Get terminal widget configuration.
+ *
+ * @returns {{ theme?: object, fontSize?: number, fontFamily?: string, prompt?: string }}
+ */
+export function getTerminalConfig() {
+  return _terminal
+}
+
+/**
+ * Get agent configurations.
+ *
+ * @returns {object}
+ */
+export function getAgentsConfig() {
+  return _agents
+}
+
+/**
+ * Get canvas zoom configuration (min, max, step).
+ *
+ * @returns {{ min: number, max: number, step: number }}
+ */
+export function getCanvasZoom() {
+  return _zoom
+}
+
+/**
+ * Check if a terminal/agent widget should be resizable based on config.
+ * Agent-level `resizable` overrides the base `terminal.resizable`.
+ *
+ * @param {string|null} [agentId] — agent ID to check for overrides
+ * @returns {boolean}
+ */
+export function isTerminalResizable(agentId = null) {
+  if (agentId) {
+    const agentCfg = _agents[agentId]
+    if (agentCfg && agentCfg.resizable !== undefined) return agentCfg.resizable
+  }
+  return _terminal.resizable ?? false
+}
+
+/**
+ * Get effective default dimensions for a terminal/agent widget.
+ * Cascade: agent config > terminal config > provided fallbacks.
+ *
+ * @param {string|null} [agentId] — agent ID to check for overrides
+ * @param {{ width: number, height: number }} [fallback] — schema-level fallbacks
+ * @returns {{ width: number, height: number }}
+ */
+export function getTerminalDimensions(agentId = null, fallback = { width: 800, height: 450 }) {
+  const base = {
+    width: _terminal.defaultWidth ?? fallback.width,
+    height: _terminal.defaultHeight ?? fallback.height,
+  }
+  if (agentId) {
+    const agentCfg = _agents[agentId]
+    if (agentCfg) {
+      return {
+        width: agentCfg.defaultWidth ?? base.width,
+        height: agentCfg.defaultHeight ?? base.height,
+      }
+    }
+  }
+  return base
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset all internal state. Only for use in tests.
+ */
+export function _resetCanvasConfig() {
+  _pasteRules = []
+  _terminal = {}
+  _agents = {}
+  _zoom = { min: 10, max: 250, step: 10 }
+}

package/src/core/stores/canvasConfig.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { initCanvasConfig, getPasteRules, isTerminalResizable, getTerminalDimensions, _resetCanvasConfig } from './canvasConfig.js'
+
+describe('canvasConfig', () => {
+  beforeEach(() => {
+    _resetCanvasConfig()
+  })
+
+  it('returns empty array by default', () => {
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('stores paste rules from config', () => {
+    const rules = [
+      { pattern: 'youtube\\.com', type: 'link-preview', props: { url: '$url' } },
+    ]
+    initCanvasConfig({ pasteRules: rules })
+    expect(getPasteRules()).toEqual(rules)
+  })
+
+  it('handles missing pasteRules gracefully', () => {
+    initCanvasConfig({})
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('handles undefined config', () => {
+    initCanvasConfig()
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('handles non-array pasteRules', () => {
+    initCanvasConfig({ pasteRules: 'not-an-array' })
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('resets on _resetCanvasConfig', () => {
+    initCanvasConfig({ pasteRules: [{ pattern: '.', type: 'test' }] })
+    expect(getPasteRules()).toHaveLength(1)
+    _resetCanvasConfig()
+    expect(getPasteRules()).toEqual([])
+  })
+})
+
+describe('isTerminalResizable', () => {
+  beforeEach(() => {
+    _resetCanvasConfig()
+  })
+
+  it('returns false by default', () => {
+    expect(isTerminalResizable()).toBe(false)
+  })
+
+  it('returns terminal.resizable when set', () => {
+    initCanvasConfig({ terminal: { resizable: true } })
+    expect(isTerminalResizable()).toBe(true)
+  })
+
+  it('agent overrides terminal resizable', () => {
+    initCanvasConfig({
+      terminal: { resizable: false },
+      agents: { myAgent: { resizable: true } },
+    })
+    expect(isTerminalResizable('myAgent')).toBe(true)
+    expect(isTerminalResizable()).toBe(false)
+  })
+
+  it('agent can disable resizable even when terminal enables it', () => {
+    initCanvasConfig({
+      terminal: { resizable: true },
+      agents: { fixedAgent: { resizable: false } },
+    })
+    expect(isTerminalResizable('fixedAgent')).toBe(false)
+    expect(isTerminalResizable()).toBe(true)
+  })
+
+  it('falls back to terminal config for unknown agent', () => {
+    initCanvasConfig({ terminal: { resizable: true } })
+    expect(isTerminalResizable('nonexistent')).toBe(true)
+  })
+})
+
+describe('getTerminalDimensions', () => {
+  beforeEach(() => {
+    _resetCanvasConfig()
+  })
+
+  it('returns fallback defaults when no config', () => {
+    expect(getTerminalDimensions()).toEqual({ width: 800, height: 450 })
+  })
+
+  it('returns terminal config dimensions', () => {
+    initCanvasConfig({ terminal: { defaultWidth: 1000, defaultHeight: 600 } })
+    expect(getTerminalDimensions()).toEqual({ width: 1000, height: 600 })
+  })
+
+  it('agent overrides terminal dimensions', () => {
+    initCanvasConfig({
+      terminal: { defaultWidth: 1000, defaultHeight: 600 },
+      agents: { bigAgent: { defaultWidth: 1400, defaultHeight: 800 } },
+    })
+    expect(getTerminalDimensions('bigAgent')).toEqual({ width: 1400, height: 800 })
+  })
+
+  it('agent partial override inherits from terminal for unset dimensions', () => {
+    initCanvasConfig({
+      terminal: { defaultWidth: 1000, defaultHeight: 600 },
+      agents: { wideAgent: { defaultWidth: 1400 } },
+    })
+    expect(getTerminalDimensions('wideAgent')).toEqual({ width: 1400, height: 600 })
+  })
+
+  it('falls back to terminal config for unknown agent', () => {
+    initCanvasConfig({ terminal: { defaultWidth: 900, defaultHeight: 500 } })
+    expect(getTerminalDimensions('nonexistent')).toEqual({ width: 900, height: 500 })
+  })
+
+  it('uses custom fallback when provided', () => {
+    expect(getTerminalDimensions(null, { width: 1200, height: 450 })).toEqual({ width: 1200, height: 450 })
+  })
+})

package/src/core/stores/commandActions.js

@@ -0,0 +1,284 @@
+/**
+ * Command Actions — config-driven registry for command menu entries.
+ *
+ * The command section of toolbar.config.json declares action metadata:
+ *   id, label, type, hideFrom, separatorBefore
+ *
+ * Handler shapes by type:
+ *   default:  () => void
+ *   toggle:   { execute(), getState() → boolean }
+ *   submenu:  { getChildren() → Array<{ id?, label, type, active?, execute }> }
+ */
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+let _config = { actions: {}, footer: '' }
+
+/** @type {Map<string, any>} id → handler (function or object) */
+const _handlers = new Map()
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed the registry from a menu config object.
+ * Called once at app startup.
+ *
+ * @param {{ actions: Array, footer?: string }} config
+ */
+export function initCommandActions(config) {
+  _config = { ...config }
+  _notify()
+}
+
+// ---------------------------------------------------------------------------
+// Handler registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a handler for a declared action.
+ *
+ * @param {string} id     Action id (e.g. "core/viewfinder")
+ * @param {Function|object} handler
+ *   - default type: () => void
+ *   - toggle type:  { execute(), getState() }
+ *   - submenu type: { getChildren() }
+ */
+export function registerCommandAction(id, handler) {
+  _handlers.set(id, handler)
+  _notify()
+}
+
+/**
+ * Remove a previously registered handler.
+ * @param {string} id
+ */
+export function unregisterCommandAction(id) {
+  _handlers.delete(id)
+  _notify()
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic actions (not in config — registered at runtime)
+// ---------------------------------------------------------------------------
+
+/** @type {Array} */
+let _dynamicActions = []
+
+/**
+ * Add dynamic actions (e.g. comments menu items).
+ * These are appended after config-declared actions.
+ *
+ * @param {string} group  Group key for bulk replacement (e.g. "comments")
+ * @param {Array<{ id: string, label: string, type?: string, separatorBefore?: boolean }>} actions
+ * @param {Record<string, Function|object>} [handlers]  id → handler map
+ */
+export function setDynamicActions(group, actions, handlers = {}) {
+  // Remove previous entries for this group
+  _dynamicActions = _dynamicActions.filter(a => a._group !== group)
+
+  for (const action of actions) {
+    _dynamicActions.push({ ...action, type: action.type || 'default', _group: group })
+  }
+
+  // Register handlers
+  for (const [id, handler] of Object.entries(handlers)) {
+    _handlers.set(id, handler)
+  }
+
+  _notify()
+}
+
+/**
+ * Remove all dynamic actions for a group.
+ * @param {string} group
+ */
+export function clearDynamicActions(group) {
+  const removed = _dynamicActions.filter(a => a._group === group)
+  _dynamicActions = _dynamicActions.filter(a => a._group !== group)
+  for (const a of removed) {
+    _handlers.delete(a.id)
+  }
+  _notify()
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+// Base path for route matching — set by CoreUIBar or app layer
+let _basePath = '/'
+
+/**
+ * Set the base path used by isExcludedByRoute for portable pattern matching.
+ * @param {string} basePath
+ */
+export function setRoutingBasePath(basePath) {
+  _basePath = basePath || '/'
+}
+
+/**
+ * Check if an item is excluded from the current route.
+ * Strips the base path so patterns match against app-relative paths
+ * (e.g. "/" for the root, "/Signup" for a prototype page).
+ * @param {object} item  Action or menu with optional excludeRoutes array
+ * @returns {boolean} true if the item should be hidden
+ */
+export function isExcludedByRoute(item) {
+  const patterns = item.excludeRoutes
+  if (!patterns || !Array.isArray(patterns) || patterns.length === 0) return false
+  if (typeof window === 'undefined') return false
+  let pathname = window.location.pathname
+  const base = _basePath.replace(/\/+$/, '')
+  if (base && pathname.startsWith(base)) {
+    pathname = pathname.slice(base.length) || '/'
+  }
+  return patterns.some(pattern => new RegExp(pattern).test(pathname))
+}
+
+/**
+ * Check if an action is visible in a given mode.
+ * @param {object} action
+ * @param {string} mode
+ * @returns {boolean}
+ */
+function actionVisibleInMode(action, mode) {
+  if (isExcludedByRoute(action)) return false
+  const modes = action.modes
+  if (!modes) return true
+  return modes.includes('*') || modes.includes(mode)
+}
+
+/**
+ * Get resolved actions for a given mode.
+ * Filters by each action's modes array, appends dynamic actions.
+ *
+ * @param {string} mode  Current mode name
+ * @returns {Array<{ id, label, type, separatorBefore?, handler?, active? }>}
+ */
+export function getActionsForMode(mode) {
+  const configActions = Array.isArray(_config.actions) ? _config.actions : []
+  const filtered = configActions.filter(a => actionVisibleInMode(a, mode))
+  const dynamic = _dynamicActions.filter(a => actionVisibleInMode(a, mode))
+
+  // Insert dynamic actions before the footer (if present)
+  const footerIndex = filtered.findIndex(a => a.type === 'footer')
+  let all
+  if (footerIndex >= 0 && dynamic.length > 0) {
+    all = [
+      ...filtered.slice(0, footerIndex),
+      ...dynamic,
+      ...filtered.slice(footerIndex),
+    ]
+  } else {
+    all = [...filtered, ...dynamic]
+  }
+
+  return all.map(a => {
+    const handler = _handlers.get(a.id)
+    const isToggle = a.type === 'toggle'
+    const active = isToggle && handler?.getState ? handler.getState() : false
+
+    return {
+      id: a.id,
+      label: a.label,
+      type: a.type || 'default',
+      url: a.url || null,
+      toolKey: a.toolKey || null,
+      localOnly: a.localOnly || false,
+      hideFromCommandPaletteSearch: a.hideFromCommandPaletteSearch || false,
+      handler,
+      active,
+    }
+  })
+}
+
+/**
+ * Execute an action by id.
+ * @param {string} id
+ */
+export function executeAction(id) {
+  const handler = _handlers.get(id)
+  if (!handler) return
+  if (typeof handler === 'function') {
+    handler()
+  } else if (handler.execute) {
+    handler.execute()
+  }
+  _notify()
+}
+
+/**
+ * Get submenu children for a submenu-type action.
+ * @param {string} id
+ * @returns {Array<{ id?, label, type, active?, execute? }>}
+ */
+export function getActionChildren(id) {
+  const handler = _handlers.get(id)
+  if (!handler?.getChildren) return []
+  return handler.getChildren()
+}
+
+/**
+ * Check if a handler provides dynamic children (getChildren).
+ * Used by CoreUIBar to distinguish action-menu tools (gate on children count)
+ * from custom-component menus (always visible, render their own content).
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function hasChildrenProvider(id) {
+  const handler = _handlers.get(id)
+  return !!handler?.getChildren
+}
+
+// ---------------------------------------------------------------------------
+// Reactivity
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to action changes. Compatible with useSyncExternalStore.
+ * @param {Function} callback
+ * @returns {Function} Unsubscribe
+ */
+export function subscribeToCommandActions(callback) {
+  _listeners.add(callback)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot for useSyncExternalStore.
+ * @returns {string}
+ */
+export function getCommandActionsSnapshot() {
+  return String(_snapshotVersion)
+}
+
+function _notify() {
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb() } catch (err) {
+      console.error('[storyboard] Error in command action subscriber:', err)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/** Reset all state. Only for tests. */
+export function _resetCommandActions() {
+  _config = { actions: {}, footer: '' }
+  _handlers.clear()
+  _dynamicActions = []
+  _listeners.clear()
+  _snapshotVersion = 0
+}