@dfosco/storyboard 0.5.0-alpha.0

package/src/core/devtools/sceneDebug.js

@@ -0,0 +1,112 @@
+/**
+ * Storyboard FlowDebug — a vanilla JS debug panel that displays flow data.
+ *
+ * Framework-agnostic: creates a DOM element, no React/Vue/etc. needed.
+ *
+ * Usage:
+ *   import { mountFlowDebug } from '../index.js'
+ *   mountFlowDebug(document.getElementById('debug'))
+ *   // or
+ *   mountFlowDebug() // appends to document.body
+ */
+import { loadFlow } from '../data/loader.js'
+
+const STYLES = `
+.sb-scene-debug {
+  padding: 16px;
+  font-family: "Mona Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+}
+.sb-scene-debug-title {
+  font-size: 20px;
+  font-weight: 600;
+  margin-bottom: 8px;
+  color: #c9d1d9;
+}
+.sb-scene-debug-code {
+  padding: 16px;
+  background-color: #161b22;
+  border-radius: 8px;
+  overflow: auto;
+  font-size: 13px;
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  line-height: 1.5;
+  max-height: 70vh;
+  color: #c9d1d9;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.sb-scene-debug-error {
+  padding: 16px;
+  background-color: rgba(248, 81, 73, 0.1);
+  border-radius: 8px;
+}
+.sb-scene-debug-error-title {
+  color: #f85149;
+  font-weight: 600;
+}
+.sb-scene-debug-error-message {
+  color: #f85149;
+  margin-top: 4px;
+}
+`
+
+let stylesInjected = false
+
+/**
+ * Mount a flow debug panel into the DOM.
+ *
+ * @param {HTMLElement} [container=document.body] - Where to mount
+ * @param {string} [flowName] - Flow name override (defaults to ?flow= param or "default")
+ * @returns {HTMLElement} The created debug element
+ */
+export function mountFlowDebug(container, flowName) {
+  const target = container || document.body
+  const sp = new URLSearchParams(window.location.search)
+  const activeFlowName = flowName
+    || sp.get('flow') || sp.get('scene')
+    || 'default'
+
+  // Inject styles once
+  if (!stylesInjected) {
+    const styleEl = document.createElement('style')
+    styleEl.textContent = STYLES
+    document.head.appendChild(styleEl)
+    stylesInjected = true
+  }
+
+  const el = document.createElement('div')
+  el.className = 'sb-scene-debug'
+
+  let data = null
+  let error = null
+  try {
+    data = loadFlow(activeFlowName)
+  } catch (err) {
+    error = err.message
+  }
+
+  if (error) {
+    el.innerHTML = `
+      <div class="sb-scene-debug-error">
+        <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 = `Flow: ${activeFlowName}`
+
+    const pre = document.createElement('pre')
+    pre.className = 'sb-scene-debug-code'
+    pre.textContent = JSON.stringify(data, null, 2)
+
+    el.appendChild(title)
+    el.appendChild(pre)
+  }
+
+  target.appendChild(el)
+  return el
+}
+
+/** @deprecated Use mountFlowDebug() */
+export const mountSceneDebug = mountFlowDebug

package/src/core/devtools/sceneDebug.test.js

@@ -0,0 +1,141 @@
+import { vi } from 'vitest'
+
+const { mockLoadFlow } = vi.hoisted(() => ({
+  mockLoadFlow: vi.fn(() => ({ hello: 'world', count: 42 })),
+}))
+
+vi.mock('../data/loader.js', () => ({
+  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 { mountFlowDebug, mountSceneDebug } from './sceneDebug.js'
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  mockLoadFlow.mockReset()
+  mockLoadFlow.mockReturnValue({ hello: 'world', count: 42 })
+})
+
+describe('mountFlowDebug', () => {
+  it('injects styles into document.head on first call', () => {
+    // This MUST run first to capture the stylesInjected=false → true transition
+    mountFlowDebug()
+
+    const styles = document.head.querySelectorAll('style')
+    const hasDebugStyle = Array.from(styles).some((el) =>
+      el.textContent.includes('.sb-scene-debug')
+    )
+    expect(hasDebugStyle).toBe(true)
+  })
+
+  it('creates an element with class sb-scene-debug', () => {
+    const el = mountFlowDebug()
+
+    expect(el.classList.contains('sb-scene-debug')).toBe(true)
+  })
+
+  it('appends to document.body by default', () => {
+    mountFlowDebug()
+
+    expect(document.body.querySelector('.sb-scene-debug')).toBeInTheDocument()
+  })
+
+  it('appends to a custom container', () => {
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    mountFlowDebug(container)
+
+    expect(container.querySelector('.sb-scene-debug')).not.toBeNull()
+  })
+
+  it('returns the created element', () => {
+    const el = mountFlowDebug()
+
+    expect(el).toBeInstanceOf(HTMLElement)
+    expect(el.className).toBe('sb-scene-debug')
+  })
+
+  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-flow')
+  })
+
+  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(mockLoadFlow).toHaveBeenCalledWith('default')
+  })
+
+  it('renders JSON data in a pre element', () => {
+    mountFlowDebug()
+
+    const pre = document.body.querySelector('.sb-scene-debug-code')
+    expect(pre).not.toBeNull()
+    expect(pre.tagName).toBe('PRE')
+
+    const parsed = JSON.parse(pre.textContent)
+    expect(parsed).toEqual({ hello: 'world', count: 42 })
+  })
+
+  it('shows error when loadFlow throws', () => {
+    mockLoadFlow.mockImplementation(() => {
+      throw new Error('Flow not found')
+    })
+
+    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('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 flowName argument is given', () => {
+    window.history.pushState(null, '', '?scene=overview')
+
+    mountFlowDebug()
+
+    expect(mockLoadFlow).toHaveBeenCalledWith('overview')
+    const title = document.body.querySelector('.sb-scene-debug-title')
+    expect(title.textContent).toContain('overview')
+
+    // Clean up
+    window.history.pushState(null, '', '/')
+  })
+
+  it('allows multiple debug panels to be mounted', () => {
+    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/core/index.js

@@ -0,0 +1,124 @@
+/**
+ * storyboard-core — framework-agnostic data layer.
+ *
+ * This barrel exports all core utilities that have zero framework dependencies.
+ * Any frontend (React, Vue, Alpine, vanilla JS) can use these directly.
+ */
+
+// Data index initialization
+export { init } from './data/loader.js'
+
+// Flow, object & record loading
+export { loadFlow, listFlows, flowExists, getFlowsForPrototype, loadRecord, findRecord, loadObject, deepMerge } from './data/loader.js'
+// Scoped name resolution
+export { resolveFlowName, resolveRecordName, resolveObjectName } from './data/loader.js'
+// Prototype metadata
+export { listPrototypes, getPrototypeMetadata } from './data/loader.js'
+// Folder metadata
+export { listFolders, getFolderMetadata } from './data/loader.js'
+// Canvas data
+export { listCanvases, getCanvasData } from './data/loader.js'
+// Story data
+export { listStories, getStoryData } from './data/loader.js'
+// Deprecated scene aliases
+export { loadScene, listScenes, sceneExists } from './data/loader.js'
+
+// Dot-notation path utilities
+export { getByPath, setByPath, deepClone } from './data/dotPath.js'
+
+// URL hash session state (read/write)
+export { getParam, setParam, getAllParams, removeParam } from './session/session.js'
+
+// localStorage persistence
+export { getLocal, setLocal, removeLocal, getAllLocal, subscribeToStorage, getStorageSnapshot, notifyChange } from './session/localStorage.js'
+
+// Hide mode (clean URLs)
+export { isHideMode, activateHideMode, deactivateHideMode, getShadow, setShadow, removeShadow, getAllShadows, pushSnapshot, getOverrideHistory, getCurrentSnapshot, getCurrentRoute, getCurrentIndex, getNextIndex, canUndo, canRedo, undo, redo, syncHashToHistory, installHistorySync } from './session/hideMode.js'
+export { interceptHideParams, installHideParamListener } from './session/interceptHideParams.js'
+
+// Hash change subscription (for reactive frameworks)
+export { subscribeToHash, getHashSnapshot } from './session/hashSubscribe.js'
+
+// Body class sync (overrides + flow → <body> classes)
+export { installBodyClassSync, setFlowClass, syncOverrideClasses } from './session/bodyClasses.js'
+// Deprecated alias
+export { setSceneClass } from './session/bodyClasses.js'
+
+// Design modes (mode registry, switching, event bus)
+export { registerMode, unregisterMode, getRegisteredModes, getCurrentMode, activateMode, deactivateMode, subscribeToMode, getModeSnapshot, syncModeClasses, on, off, emit, initModesConfig, isModesEnabled, getLockedMode, isModeSwitcherVisible } from './modes/modes.js'
+
+// Tool registry (declared in modes.config.json, state managed at runtime)
+export { initTools, setToolAction, setToolState, getToolState, getToolsForMode, subscribeToTools, getToolsSnapshot } from './modes/modes.js'
+
+// Dev tools (vanilla JS, framework-agnostic)
+// mountDevTools delegates to the compiled UI bundle so consumers
+
+export { mountDevTools } from './devtools/devtools-consumer.js'
+export { mountFlowDebug } from './devtools/sceneDebug.js'
+// Deprecated alias
+export { mountSceneDebug } from './devtools/sceneDebug.js'
+
+// Single entry point for consumer apps
+export { mountStoryboardCore } from './mountStoryboardCore.js'
+
+// Viewfinder utilities
+export { hash, resolveFlowRoute, getFlowMeta, buildPrototypeIndex, appendTokens } from './data/viewfinder.js'
+// Deprecated aliases
+export { resolveSceneRoute, getSceneMeta } from './data/viewfinder.js'
+
+// Feature flags
+export { initFeatureFlags, getFlag, setFlag, toggleFlag, getAllFlags, resetFlags, getFlagKeys, syncFlagBodyClasses } from './stores/featureFlags.js'
+
+// Command actions (config-driven command menu entries)
+export { initCommandActions, registerCommandAction, unregisterCommandAction, setDynamicActions, clearDynamicActions, getActionsForMode, executeAction, getActionChildren, hasChildrenProvider, subscribeToCommandActions, getCommandActionsSnapshot, setRoutingBasePath, isExcludedByRoute } from './stores/commandActions.js'
+
+// Plugin configuration
+export { initPlugins, isPluginEnabled, getPluginsConfig } from './stores/plugins.js'
+
+// UI config (project-level chrome overrides)
+export { initUIConfig, isMenuHidden, getHiddenItems } from './stores/uiConfig.js'
+
+// Tool registry (declarative tool system)
+export { initToolRegistry, registerToolModule, setToolComponent, setToolGuardResult, getToolComponent, getToolModule, getToolsForToolbar, getToolConfig, getAllToolConfigs, subscribeToToolRegistry, getToolRegistrySnapshot } from './stores/toolRegistry.js'
+
+// Toolbar config store (reactive layered overrides: core → custom → prototype → user)
+export { initToolbarConfig, setPrototypeToolbarConfig, clearPrototypeToolbarConfig, getToolbarConfig, subscribeToToolbarConfig, getToolbarConfigSnapshot, setClientToolbarOverrides, consumeClientToolbarOverrides } from './stores/toolbarConfigStore.js'
+
+// Toolbar tool state management (runtime state for toolbar tools)
+export { TOOL_STATES, initToolbarToolStates, setToolbarToolState, getToolbarToolState, isToolbarToolLocalOnly, subscribeToToolbarToolStates, getToolbarToolStatesSnapshot } from './stores/toolStateStore.js'
+
+// Comments system
+export { initCommentsConfig, getCommentsConfig, isCommentsEnabled } from './comments/config.js'
+
+// Canvas config (paste rules, canvas-level overrides)
+export { initCanvasConfig, getPasteRules, getTerminalConfig, getAgentsConfig, isTerminalResizable, getTerminalDimensions, getCanvasZoom } from './stores/canvasConfig.js'
+export { getCommandPaletteConfig, initCommandPaletteConfig } from './stores/commandPaletteConfig.js'
+
+// Unified config store
+export { initConfig, getConfig, setOverrides, clearOverrides, clearAllOverrides, subscribeToConfig, getConfigSnapshot } from './stores/configStore.js'
+
+// Customer mode config
+export { initCustomerModeConfig, getCustomerModeConfig, isCustomerMode } from './stores/customerModeConfig.js'
+
+// Theme
+export {
+  setTheme,
+  getTheme,
+  themeState,
+  themeSyncState,
+  THEMES,
+  getThemeSyncTargets,
+  setThemeSyncTarget,
+} from './stores/themeStore.js'
+
+// Recent artifacts (command palette recents)
+export { trackRecent, getRecent, clearRecent } from './stores/recentArtifacts.js'
+
+// Fuzzy search (scoring used by command palette custom filter)
+export { scoreMatch } from './utils/fuzzySearch.js'
+
+// Icon component for UI rendering
+export { default as Icon, default as IconDefault } from './ui/Icon.jsx'
+
+// Shared UI components
+export { default as BranchSelect } from './ui/BranchSelect.jsx'

package/src/core/inspector/fiberWalker.js

@@ -0,0 +1,239 @@
+/**
+ * Fiber Walker — React fiber tree inspector for DOM elements.
+ *
+ * Framework-agnostic (zero npm dependencies).
+ * Intended for dev-time inspection only — relies on React's internal
+ * fiber keys and _debugSource which are only present in development builds.
+ */
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the React fiber key on a DOM element.
+ * React attaches fibers via private keys like __reactFiber$xxxx.
+ * The suffix changes per React instance, so we search by prefix.
+ *
+ * @param {Element} el
+ * @returns {string|undefined}
+ */
+function findFiberKey(el) {
+  return Object.keys(el).find(
+    k => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$')
+  )
+}
+
+/**
+ * Check whether a fiber represents a user-defined component
+ * (as opposed to a host element like 'div' or a React internal like Fragment).
+ * Handles function components, forwardRef, and memo wrappers.
+ *
+ * @param {object} fiber
+ * @returns {boolean}
+ */
+function isUserComponent(fiber) {
+  if (!fiber || !fiber.type) return false
+  const t = fiber.type
+  // Plain function/class component
+  if (typeof t === 'function') return true
+  // forwardRef: { $$typeof: Symbol(react.forward_ref), render: fn }
+  // memo: { $$typeof: Symbol(react.memo), type: ... }
+  if (typeof t === 'object' && t !== null) {
+    if (typeof t.render === 'function') return true  // forwardRef
+    if (t.$$typeof && typeof t.type === 'function') return true  // memo
+    if (t.$$typeof && typeof t.type === 'object') return true  // memo(forwardRef)
+  }
+  return false
+}
+
+/**
+ * Derive a human-readable name from a fiber's type.
+ * Handles plain components, forwardRef, and memo wrappers.
+ * Skips minified names (single-char or generic) in favor of 'ForwardRef'/'Memo'
+ * so the caller can try walking up the tree for a better name.
+ *
+ * @param {object} fiber
+ * @returns {string}
+ */
+function getComponentName(fiber) {
+  if (!fiber || !fiber.type) return 'Unknown'
+  const t = fiber.type
+  // Plain function/class
+  if (typeof t === 'function') return t.displayName || t.name || 'Anonymous'
+  // forwardRef / memo wrapper objects
+  if (typeof t === 'object' && t !== null) {
+    if (t.displayName) return t.displayName
+    // forwardRef: { render: fn }
+    if (typeof t.render === 'function') {
+      const name = t.render.displayName || t.render.name
+      return isUsableName(name) ? name : 'ForwardRef'
+    }
+    // memo: { type: ... }
+    if (t.type) {
+      const inner = t.type
+      if (typeof inner === 'function') {
+        const name = inner.displayName || inner.name
+        return isUsableName(name) ? name : 'Memo'
+      }
+      // memo(forwardRef)
+      if (typeof inner === 'object' && inner.render) {
+        if (inner.displayName) return inner.displayName
+        const name = inner.render.displayName || inner.render.name
+        return isUsableName(name) ? name : 'ForwardRef'
+      }
+    }
+  }
+  return 'Unknown'
+}
+
+/**
+ * Check if a resolved component name is usable (not minified).
+ * Minified names are typically 1-2 chars or all lowercase short strings.
+ */
+function isUsableName(name) {
+  if (!name) return false
+  // Single-char names (e, t, r, n) are almost certainly minified
+  if (name.length <= 2) return false
+  return true
+}
+
+/**
+ * Extract debug source info from a fiber (dev builds only).
+ *
+ * @param {object} fiber
+ * @returns {{ fileName: string, lineNumber: number, columnNumber: number }|null}
+ */
+function getDebugSource(fiber) {
+  if (!fiber || !fiber._debugSource) return null
+  const src = fiber._debugSource
+  return {
+    fileName: src.fileName ?? null,
+    lineNumber: src.lineNumber ?? null,
+    columnNumber: src.columnNumber ?? null,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the React fiber node attached to a DOM element.
+ * React attaches fibers via private keys like __reactFiber$xxx.
+ * Returns null if the element has no fiber (not a React-rendered element).
+ *
+ * @param {Element} el - A DOM element
+ * @returns {object|null} The fiber node, or null
+ */
+export function getFiberFromElement(el) {
+  if (!el || typeof el !== 'object') return null
+  const key = findFiberKey(el)
+  if (!key) return null
+  return el[key] ?? null
+}
+
+/**
+ * Extract component information from a fiber node.
+ * Walks up the fiber tree to find the nearest user component
+ * (skipping host elements like div, span, etc.).
+ *
+ * Returns: { name, props, source, owner } or null
+ * - name: component display name or function name
+ * - props: current memoized props object
+ * - source: { fileName, lineNumber, columnNumber } from _debugSource, or null
+ * - owner: name of the owning/parent component, or null
+ *
+ * @param {object} fiber - A React fiber node
+ * @returns {{ name: string, props: object, source: object|null, owner: string|null }|null}
+ */
+export function getComponentInfo(fiber) {
+  if (!fiber) return null
+
+  // Walk up to the nearest user component
+  let current = fiber
+  while (current && !isUserComponent(current)) {
+    current = current.return
+  }
+
+  if (!current) return null
+
+  let name = getComponentName(current)
+
+  // If we got a generic name (ForwardRef, Memo), try walking up
+  // to find the nearest ancestor with a real component name
+  if (name === 'ForwardRef' || name === 'Memo') {
+    let ancestor = current.return
+    while (ancestor) {
+      if (isUserComponent(ancestor)) {
+        const ancestorName = getComponentName(ancestor)
+        if (ancestorName !== 'ForwardRef' && ancestorName !== 'Memo' && ancestorName !== 'Unknown') {
+          name = ancestorName
+          break
+        }
+      }
+      ancestor = ancestor.return
+    }
+  }
+
+  const ownerFiber = current._debugOwner ?? null
+
+  return {
+    name,
+    props: current.memoizedProps ?? {},
+    source: getDebugSource(current),
+    owner: ownerFiber ? getComponentName(ownerFiber) : null,
+  }
+}
+
+/**
+ * Walk up the fiber tree and collect all user components in the chain.
+ * Returns an array from the given fiber up to the root.
+ * Each entry: { name, source }
+ * Skips host elements (div, span, etc.) and React internal types.
+ *
+ * @param {object} fiber - A React fiber node
+ * @returns {Array<{ name: string, source: object|null }>}
+ */
+export function getComponentChain(fiber) {
+  const chain = []
+  let current = fiber
+
+  while (current) {
+    if (isUserComponent(current)) {
+      chain.push({
+        name: getComponentName(current),
+        source: getDebugSource(current),
+      })
+    }
+    current = current.return
+  }
+
+  return chain
+}
+
+/**
+ * Convenience: given a DOM element, get full component info.
+ * Combines getFiberFromElement + getComponentInfo.
+ *
+ * @param {Element} el - A DOM element
+ * @returns {{ name: string, props: object, source: object|null, owner: string|null }|null}
+ */
+export function inspectElement(el) {
+  const fiber = getFiberFromElement(el)
+  if (!fiber) return null
+  return getComponentInfo(fiber)
+}
+
+/**
+ * Given a DOM element, get ALL React components in the ancestry chain.
+ * Combines getFiberFromElement + getComponentChain.
+ *
+ * @param {Element} el - A DOM element
+ * @returns {Array<{ name: string, source: object|null }>}
+ */
+export function inspectElementChain(el) {
+  const fiber = getFiberFromElement(el)
+  if (!fiber) return []
+  return getComponentChain(fiber)
+}