@dfosco/storyboard 0.5.0-alpha.0

package/src/core/stores/commandPaletteConfig.js

@@ -0,0 +1,31 @@
+/**
+ * Command Palette Config — runtime store for commandPalette config.
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+import { getConfig } from './configStore.js'
+
+let _config = { sections: [] }
+
+/**
+ * Initialize the command palette config.
+ * @param {object} config - The commandPalette object from storyboard.config.json
+ */
+export function initCommandPaletteConfig(config) {
+  _config = { sections: [], ...config }
+}
+
+/**
+ * Get the current command palette config.
+ * Falls back to the unified config store if the legacy store wasn't initialized.
+ * @returns {{ sections: Array }}
+ */
+export function getCommandPaletteConfig() {
+  if (_config.sections.length === 0) {
+    const uc = getConfig('commandPalette')
+    if (uc?.sections?.length > 0) {
+      _config = { sections: [], ...uc }
+    }
+  }
+  return _config
+}

package/src/core/stores/configSchema.js

@@ -0,0 +1,232 @@
+/**
+ * Config Schema — canonical shape and defaults for storyboard.config.json.
+ *
+ * Every consumer of storyboard.config.json should import `getConfig()` to get
+ * a fully defaulted, validated config object. New keys added here are safe for
+ * existing projects — they always have defaults.
+ *
+ * @module configSchema
+ */
+
+/**
+ * @typedef {object} PasteRule
+ * @property {string} match    — regex string tested against pasted URLs
+ * @property {string} widget   — widget type to create (e.g. "figma-embed", "link-preview")
+ * @property {Record<string, string>} [propsMap] — static props merged into widget props
+ */
+
+/**
+ * @typedef {object} CanvasTerminalConfig
+ * @property {boolean} [resizable]   — whether terminal widgets can be resized (default false)
+ * @property {number}  [defaultWidth]  — default width for new terminal widgets
+ * @property {number}  [defaultHeight] — default height for new terminal widgets
+ * @property {number}  [fontSize]    — terminal font size
+ * @property {string}  [fontFamily]  — terminal font family
+ * @property {string}  [prompt]      — shell prompt string
+ * @property {string|null} [startupCommand] — skip welcome screen: "copilot", "shell", or a custom command. null shows welcome.
+ * @property {object|null} [defaultStartupSequence] — sequence of steps to run after terminal opens
+ */
+
+/**
+ * @typedef {object} CanvasZoomConfig
+ * @property {number} min  — minimum zoom percentage (default 10)
+ * @property {number} max  — maximum zoom percentage (default 250)
+ * @property {number} step — zoom increment/decrement step (default 10)
+ */
+
+/**
+ * @typedef {object} CanvasConfig
+ * @property {PasteRule[]} pasteRules       — URL→widget conversion rules (evaluated in order, first match wins)
+ * @property {{ embedBehavior: string, ghGuard: string }} github — GitHub-specific embed settings
+ * @property {CanvasTerminalConfig} [terminal] — terminal widget settings
+ * @property {Record<string, CanvasAgentConfig>} [agents] — per-agent overrides
+ * @property {CanvasZoomConfig} [zoom] — zoom min/max/step settings
+ */
+
+/**
+ * @typedef {object} CanvasAgentConfig
+ * @property {string}  [label]         — display label
+ * @property {string}  [icon]          — icon name
+ * @property {string}  [startupCommand] — command to run on startup
+ * @property {string}  [resumeCommand]  — command to browse/resume existing sessions (e.g. "copilot --resume")
+ * @property {string}  [postStartup]   — command sent after agent readiness (e.g. "/allow-all on")
+ * @property {string}  [readinessSignal] — tmux pane text that signals the agent is ready (fragile, prefer readinessFile)
+ * @property {boolean} [readinessFile]  — use a file-based SessionStart hook for readiness (writes --settings with hook, polls for signal file)
+ * @property {boolean} [resizable]     — override terminal resizability for this agent
+ * @property {number}  [defaultWidth]  — override default width
+ * @property {number}  [defaultHeight] — override default height
+ */
+
+/**
+ * @typedef {object} HotPoolConfig
+ * @property {boolean} [enabled]       — enable/disable all pools (default: true)
+ * @property {boolean} [verbose]       — log to Vite terminal (default: false)
+ * @property {number}  [default_pool_size]     — default baseline per pool (default: 1)
+ * @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, 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)
+ */
+
+/**
+ * @typedef {object} CommandPaletteConfig
+ * @property {string[]} providers — provider IDs to enable
+ * @property {string}   ranking   — result ranking strategy
+ * @property {CommandPaletteSection[]} [sections] — declarative palette sections
+ */
+
+/**
+ * @typedef {object} CommandPaletteSection
+ * @property {string}  id       — unique section identifier
+ * @property {string}  [title]  — section heading in the palette
+ * @property {string}  [type]   — "tool-menu" for sub-page entries
+ * @property {string}  [label]  — display label (for tool-menu entries)
+ * @property {string[]} [keywords] — search keywords
+ * @property {CommandPaletteSectionItem[]} [items]   — static entries
+ * @property {string}  [source] — dynamic data source: "canvases" | "prototypes" | "stories"
+ * @property {string}  [order]  — ordering: "recent" | "alphabetical" | "recent-changes"
+ * @property {number}  [limit]  — max items from dynamic source
+ * @property {CommandPaletteOption[]} [options] — sub-page options (for tool-menu type)
+ */
+
+/**
+ * @typedef {object} CommandPaletteSectionItem
+ * @property {string} type     — "link" | "action"
+ * @property {string} label    — display text
+ * @property {string} [url]    — navigation URL (for links)
+ * @property {string} [action] — command action ID (for actions)
+ * @property {string[]} [keywords] — search keywords
+ */
+
+/**
+ * @typedef {object} CommandPaletteOption
+ * @property {string} label   — display text
+ * @property {string} action  — command action ID
+ * @property {*}      [value] — action payload
+ */
+
+/**
+ * @typedef {object} CustomerModeConfig
+ * @property {boolean} enabled       — master toggle for customer mode
+ * @property {boolean} hideChrome    — hides all toolbars (except canvas tools), branchbar, cmd+k, cmd+.
+ * @property {boolean} hideHomepage  — removes the storyboard homepage (leaves empty page)
+ * @property {string}  protoHomepage — internal /path that replaces homepage; redirects from / and /workspace
+ */
+
+/**
+ * @typedef {object} StoryboardConfig
+ * @property {string}   [customDomain]
+ * @property {string}   [devDomain]
+ * @property {string}   [devDomainColor] — CSS color for the BranchBar in local dev (default: blue)
+ * @property {{ owner: string, name: string }} [repository]
+ * @property {{ enabled: boolean }} [modes]
+ * @property {{ discussions: { category: string } }} [comments]
+ * @property {Record<string, boolean>} [plugins]
+ * @property {{ enabled?: boolean, features?: Record<string, boolean>, partials?: Array }} [workshop]
+ * @property {Record<string, boolean>} [featureFlags]
+ * @property {{ hide?: string[] }} [ui]
+ * @property {object}   [toolbar]
+ * @property {CanvasConfig} [canvas]
+ * @property {HotPoolConfig} [hotPool]
+ * @property {CommandPaletteConfig} [commandPalette]
+ * @property {CustomerModeConfig} [customerMode]
+ */
+
+/** Built-in paste rules shipped with storyboard. */
+export const builtinPasteRules = [
+  {
+    id: 'figma',
+    match: 'https?://(?:www\\.)?figma\\.com/',
+    widget: 'figma-embed',
+    propsMap: { width: 800, height: 450 },
+  },
+]
+
+/** Default config values. Every key here is safe to access without null checks. */
+export const configDefaults = {
+  customDomain: '',
+  devDomain: '',
+  devDomainColor: '',
+  repository: { owner: '', name: '' },
+  modes: { enabled: false },
+  comments: { discussions: { category: 'Comments' } },
+  plugins: {},
+  workshop: {
+    enabled: false,
+    features: { createPrototype: true, createFlow: true, createCanvas: true },
+  },
+  featureFlags: {},
+  ui: {},
+  toolbar: {},
+  canvas: {
+    pasteRules: builtinPasteRules,
+    github: {
+      embedBehavior: 'link-preview', // "link-preview" | "rich-embed"
+      ghGuard: 'copy',               // "copy" | "link" | "off"
+    },
+    zoom: {
+      min: 10,
+      max: 250,
+      step: 10,
+    },
+    terminal: {
+      resizable: false,
+      defaultWidth: 800,
+      defaultHeight: 450,
+    },
+  },
+  commandPalette: {
+    providers: ['prototypes', 'flows', 'canvases', 'pages'],
+    ranking: 'frecency',
+    sections: [],
+  },
+  customerMode: {
+    enabled: false,
+    hideChrome: false,
+    hideHomepage: false,
+    protoHomepage: '',
+  },
+}
+
+/**
+ * Deep-merge helper that replaces arrays instead of concatenating.
+ * Objects are recursively merged; all other values are overwritten.
+ */
+function mergeConfig(defaults, overrides) {
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return overrides ?? defaults
+  }
+  const result = { ...defaults }
+  for (const key of Object.keys(overrides)) {
+    const val = overrides[key]
+    if (val === undefined) continue
+    if (Array.isArray(val)) {
+      // Arrays replace (e.g. pasteRules, providers) — no concat
+      result[key] = val
+    } else if (val && typeof val === 'object' && !Array.isArray(val) && typeof defaults[key] === 'object' && !Array.isArray(defaults[key])) {
+      result[key] = mergeConfig(defaults[key], val)
+    } else {
+      result[key] = val
+    }
+  }
+  return result
+}
+
+/**
+ * Return a fully defaulted config by merging user-provided values over defaults.
+ * Safe to call with an empty object or undefined — returns full defaults.
+ *
+ * @param {Partial<StoryboardConfig>} [raw={}]
+ * @returns {StoryboardConfig}
+ */
+export function getConfig(raw = {}) {
+  return mergeConfig(configDefaults, raw)
+}
+
+/**
+ * Return a copy of the bare defaults (no user overrides).
+ * @returns {StoryboardConfig}
+ */
+export function getConfigDefaults() {
+  return JSON.parse(JSON.stringify(configDefaults))
+}

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

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+import { getConfig, getConfigDefaults, configDefaults, builtinPasteRules } from './configSchema.js'
+
+describe('configSchema', () => {
+  describe('getConfigDefaults', () => {
+    it('returns a full defaults object', () => {
+      const d = getConfigDefaults()
+      expect(d.canvas).toBeDefined()
+      expect(d.commandPalette).toBeDefined()
+      expect(d.repository).toEqual({ owner: '', name: '' })
+    })
+
+    it('returns a fresh copy each time', () => {
+      const a = getConfigDefaults()
+      const b = getConfigDefaults()
+      expect(a).not.toBe(b)
+      expect(a).toEqual(b)
+    })
+  })
+
+  describe('getConfig', () => {
+    it('returns full defaults when called with empty object', () => {
+      const c = getConfig({})
+      expect(c.canvas.pasteRules).toEqual(builtinPasteRules)
+      expect(c.canvas.github.embedBehavior).toBe('link-preview')
+      expect(c.canvas.github.ghGuard).toBe('copy')
+      expect(c.commandPalette.providers).toEqual(['prototypes', 'flows', 'canvases', 'pages'])
+      expect(c.commandPalette.ranking).toBe('frecency')
+      expect(c.customerMode.enabled).toBe(false)
+      expect(c.customerMode.hideChrome).toBe(false)
+      expect(c.customerMode.hideHomepage).toBe(false)
+      expect(c.customerMode.protoHomepage).toBe('')
+    })
+
+    it('returns full defaults when called with undefined', () => {
+      const c = getConfig()
+      expect(c.canvas).toBeDefined()
+      expect(c.commandPalette).toBeDefined()
+    })
+
+    it('merges user config over defaults', () => {
+      const c = getConfig({
+        repository: { owner: 'test', name: 'repo' },
+        canvas: { github: { ghGuard: 'link' } },
+      })
+      expect(c.repository).toEqual({ owner: 'test', name: 'repo' })
+      expect(c.canvas.github.ghGuard).toBe('link')
+      // Other defaults preserved
+      expect(c.canvas.github.embedBehavior).toBe('link-preview')
+      expect(c.canvas.pasteRules).toEqual(builtinPasteRules)
+    })
+
+    it('replaces arrays instead of concatenating', () => {
+      const customRules = [{ id: 'custom', match: 'https://example.com', widget: 'link-preview' }]
+      const c = getConfig({ canvas: { pasteRules: customRules } })
+      expect(c.canvas.pasteRules).toEqual(customRules)
+      expect(c.canvas.pasteRules).not.toContainEqual(builtinPasteRules[0])
+    })
+
+    it('preserves existing keys not in defaults', () => {
+      const c = getConfig({ devDomain: 'my-project', featureFlags: { 'show-banner': true } })
+      expect(c.devDomain).toBe('my-project')
+      expect(c.featureFlags['show-banner']).toBe(true)
+    })
+
+    it('does not mutate configDefaults', () => {
+      const before = JSON.stringify(configDefaults)
+      getConfig({ canvas: { github: { ghGuard: 'off' } } })
+      expect(JSON.stringify(configDefaults)).toBe(before)
+    })
+  })
+})

package/src/core/stores/configStore.js

@@ -0,0 +1,161 @@
+/**
+ * Unified Config Store — single source of truth for all storyboard configuration.
+ *
+ * Replaces the scattered init/store pattern with one reactive config object.
+ * Domain-specific stores (toolbarConfigStore, canvasConfig, etc.) become thin
+ * wrappers that delegate here — zero consumer changes needed.
+ *
+ * Override priority (lowest → highest):
+ *   core defaults → widgets → paste → toolbar → commandPalette → storyboard.config.json → prototype
+ *
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+import { deepMerge } from '../data/loader.js'
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+/** @type {object} Full merged config (set once at startup) */
+let _baseConfig = {}
+
+/** @type {Record<string, object>} Domain → prototype-level overrides */
+let _prototypeOverrides = {}
+
+/** @type {object} Final merged config (base + prototype overrides) */
+let _mergedConfig = {}
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed the unified config with the pre-merged config object.
+ * Called once at app startup (from the virtual module or mountStoryboardCore).
+ *
+ * @param {object} config - The unified config with all domains
+ */
+export function initConfig(config) {
+  _baseConfig = config || {}
+  _prototypeOverrides = {}
+  _recompute()
+}
+
+// ---------------------------------------------------------------------------
+// Domain access
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the full merged config or a specific domain slice.
+ *
+ * @param {string} [domain] - Optional domain key (e.g. 'toolbar', 'canvas')
+ * @returns {object}
+ */
+export function getConfig(domain) {
+  if (!domain) return _mergedConfig
+  return _mergedConfig[domain] || {}
+}
+
+// ---------------------------------------------------------------------------
+// Prototype overrides
+// ---------------------------------------------------------------------------
+
+/**
+ * Set overrides for a specific domain from a prototype-local config file.
+ * Called on route change when entering a prototype with local config.
+ *
+ * @param {string} domain - Config domain (e.g. 'toolbar', 'widgets')
+ * @param {object} overrides - Prototype-level overrides to deep-merge
+ */
+export function setOverrides(domain, overrides) {
+  if (!overrides) return
+  _prototypeOverrides[domain] = overrides
+  _recompute()
+}
+
+/**
+ * Clear overrides for a specific domain.
+ *
+ * @param {string} domain
+ */
+export function clearOverrides(domain) {
+  if (!_prototypeOverrides[domain]) return
+  delete _prototypeOverrides[domain]
+  _recompute()
+}
+
+/**
+ * Clear all prototype overrides (e.g. when leaving a prototype).
+ */
+export function clearAllOverrides() {
+  if (Object.keys(_prototypeOverrides).length === 0) return
+  _prototypeOverrides = {}
+  _recompute()
+}
+
+// ---------------------------------------------------------------------------
+// Reactivity
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to config changes. Compatible with external stores.
+ *
+ * @param {Function} callback - Called with the full merged config
+ * @returns {Function} Unsubscribe
+ */
+export function subscribeToConfig(callback) {
+  _listeners.add(callback)
+  callback(_mergedConfig)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot version for useSyncExternalStore.
+ *
+ * @returns {string}
+ */
+export function getConfigSnapshot() {
+  return String(_snapshotVersion)
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+function _recompute() {
+  if (Object.keys(_prototypeOverrides).length === 0) {
+    _mergedConfig = _baseConfig
+  } else {
+    const result = { ..._baseConfig }
+    for (const [domain, overrides] of Object.entries(_prototypeOverrides)) {
+      result[domain] = result[domain]
+        ? deepMerge(result[domain], overrides)
+        : overrides
+    }
+    _mergedConfig = result
+  }
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb(_mergedConfig) } catch (err) {
+      console.error('[storyboard] Error in config subscriber:', err)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+export function _resetConfig() {
+  _baseConfig = {}
+  _prototypeOverrides = {}
+  _mergedConfig = {}
+  _listeners.clear()
+  _snapshotVersion = 0
+}

package/src/core/stores/customerModeConfig.js

@@ -0,0 +1,30 @@
+/**
+ * Customer Mode Config — runtime store for customerMode config.
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+let _config = { enabled: false, hideChrome: false, hideHomepage: false, protoHomepage: '' }
+
+/**
+ * Initialize customer mode config.
+ * @param {object} config - The customerMode object from storyboard.config.json
+ */
+export function initCustomerModeConfig(config) {
+  _config = { enabled: false, hideChrome: false, hideHomepage: false, protoHomepage: '', ...config }
+}
+
+/**
+ * Get the current customer mode config.
+ * @returns {{ enabled: boolean, hideChrome: boolean, hideHomepage: boolean, protoHomepage: string }}
+ */
+export function getCustomerModeConfig() {
+  return _config
+}
+
+/**
+ * Check if customer mode is enabled.
+ * @returns {boolean}
+ */
+export function isCustomerMode() {
+  return _config.enabled
+}

package/src/core/stores/featureFlags.js

@@ -0,0 +1,127 @@
+/**
+ * Feature flag system for Storyboard.
+ *
+ * Flags are defined in storyboard.config.json under "featureFlags" and
+ * initialized at app startup via the Vite data plugin.
+ *
+ * Read priority:  localStorage → config defaults
+ * Write target:   localStorage (persistent per-browser)
+ *
+ * All flag keys in localStorage are prefixed with "flag." to avoid
+ * collisions with scene overrides.
+ */
+
+import { getLocal, setLocal, removeLocal, getAllLocal } from '../session/localStorage.js'
+
+const FLAG_PREFIX = 'flag.'
+const BODY_CLASS_PREFIX = 'sb-ff-'
+
+/** Built-in feature flag defaults — always available even if initFeatureFlags is never called. */
+const BUILTIN_DEFAULTS = {
+  'canvas-auto-reload': false,
+  'prototype-auto-reload': true,
+}
+
+/** Module-level storage for config defaults */
+let _defaults = {}
+
+/**
+ * Sync body classes for active feature flags.
+ * Adds `sb-ff-{name}` for every flag that resolves to true,
+ * removes it for every flag that resolves to false.
+ */
+export function syncFlagBodyClasses() {
+  if (typeof document === 'undefined') return
+  for (const key of Object.keys(_defaults)) {
+    const cls = BODY_CLASS_PREFIX + key
+    if (getFlag(key)) {
+      document.body.classList.add(cls)
+    } else {
+      document.body.classList.remove(cls)
+    }
+  }
+}
+
+/**
+ * Initialize the feature flag system with config defaults.
+ * Only writes a default to localStorage when no user override exists yet,
+ * so toggled values survive across reloads.
+ * @param {Record<string, boolean>} defaults - Flag key → default value
+ */
+export function initFeatureFlags(defaults = {}) {
+  _defaults = { ...BUILTIN_DEFAULTS, ...defaults }
+  for (const [key, value] of Object.entries(_defaults)) {
+    if (getLocal(FLAG_PREFIX + key) === null) {
+      setLocal(FLAG_PREFIX + key, String(value))
+    }
+  }
+  syncFlagBodyClasses()
+}
+
+/**
+ * Read a flag value. Priority: localStorage → config default.
+ * @param {string} key - Flag key (without prefix)
+ * @returns {boolean}
+ */
+export function getFlag(key) {
+  const localVal = getLocal(FLAG_PREFIX + key)
+  if (localVal !== null) return localVal === 'true'
+
+  return _defaults[key] ?? BUILTIN_DEFAULTS[key] ?? false
+}
+
+/**
+ * Set a flag value. Writes to localStorage for persistence.
+ * @param {string} key - Flag key (without prefix)
+ * @param {boolean} value
+ */
+export function setFlag(key, value) {
+  setLocal(FLAG_PREFIX + key, String(value))
+  syncFlagBodyClasses()
+}
+
+/**
+ * Toggle a flag. Reads current value, writes opposite to localStorage.
+ * @param {string} key - Flag key (without prefix)
+ */
+export function toggleFlag(key) {
+  setFlag(key, !getFlag(key))
+}
+
+/**
+ * Get all flags with their default and current (resolved) values.
+ * @returns {Record<string, { default: boolean, current: boolean }>}
+ */
+export function getAllFlags() {
+  const allKeys = new Set([...Object.keys(BUILTIN_DEFAULTS), ...Object.keys(_defaults)])
+  const result = {}
+  for (const key of allKeys) {
+    result[key] = {
+      default: _defaults[key] ?? BUILTIN_DEFAULTS[key] ?? false,
+      current: getFlag(key),
+    }
+  }
+  return result
+}
+
+/**
+ * Reset all flags — removes localStorage overrides.
+ * Flags revert to config defaults.
+ */
+export function resetFlags() {
+  const allLocal = getAllLocal()
+  for (const localKey of Object.keys(allLocal)) {
+    if (localKey.startsWith(FLAG_PREFIX)) {
+      removeLocal(localKey)
+    }
+  }
+  syncFlagBodyClasses()
+}
+
+/**
+ * Get all registered flag keys.
+ * @returns {string[]}
+ */
+export function getFlagKeys() {
+  return [...new Set([...Object.keys(BUILTIN_DEFAULTS), ...Object.keys(_defaults)])]
+}