@dfosco/storyboard-core 3.3.2 → 3.4.0

package/src/toolbarConfigStore.js

@@ -0,0 +1,135 @@
+/**
+ * Toolbar Config Store — reactive toolbar configuration with layered overrides.
+ *
+ * Override priority (highest wins):
+ *   core (toolbar.config.json) → custom (client repo) → prototype → user (future)
+ *
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+import { deepMerge } from './loader.js'
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+/** @type {object} Merged core + custom config (set once at startup) */
+let _baseConfig = {}
+
+/** @type {object|null} Active prototype toolbar overrides */
+let _prototypeConfig = null
+
+/** @type {object} Final merged config (base + prototype) */
+let _mergedConfig = {}
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Set the base toolbar config (core defaults merged with client overrides).
+ * Called once at app startup by mountStoryboardCore.
+ *
+ * @param {object} config - Already-merged core + custom toolbar config
+ */
+export function initToolbarConfig(config) {
+  _baseConfig = config
+  _prototypeConfig = null
+  _recompute()
+}
+
+// ---------------------------------------------------------------------------
+// Prototype overrides
+// ---------------------------------------------------------------------------
+
+/**
+ * Set toolbar overrides for the active prototype.
+ * Called on route change when entering a prototype that has a toolbar.config.json.
+ *
+ * @param {object|null} config - Prototype-level overrides, or null to clear
+ */
+export function setPrototypeToolbarConfig(config) {
+  _prototypeConfig = config || null
+  _recompute()
+}
+
+/**
+ * Clear prototype overrides (e.g. when navigating to viewfinder or a
+ * prototype without its own toolbar.config.json).
+ */
+export function clearPrototypeToolbarConfig() {
+  if (_prototypeConfig === null) return
+  _prototypeConfig = null
+  _recompute()
+}
+
+// ---------------------------------------------------------------------------
+// Access
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the current merged toolbar config.
+ *
+ * @returns {object}
+ */
+export function getToolbarConfig() {
+  return _mergedConfig
+}
+
+// ---------------------------------------------------------------------------
+// Reactivity
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to toolbar config changes. Compatible with Svelte stores.
+ *
+ * @param {Function} callback
+ * @returns {Function} Unsubscribe
+ */
+export function subscribeToToolbarConfig(callback) {
+  _listeners.add(callback)
+  callback(_mergedConfig)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot for useSyncExternalStore.
+ *
+ * @returns {string}
+ */
+export function getToolbarConfigSnapshot() {
+  return String(_snapshotVersion)
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+function _recompute() {
+  _mergedConfig = _prototypeConfig
+    ? deepMerge(_baseConfig, _prototypeConfig)
+    : _baseConfig
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb(_mergedConfig) } catch (err) {
+      console.error('[storyboard] Error in toolbar config subscriber:', err)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+export function _resetToolbarConfig() {
+  _baseConfig = {}
+  _prototypeConfig = null
+  _mergedConfig = {}
+  _listeners.clear()
+  _snapshotVersion = 0
+}

package/src/tools/handlers/canvasAddWidget.js

@@ -0,0 +1,11 @@
+/**
+ * Canvas add-widget tool module — dropdown menu for adding widgets to canvas.
+ *
+ * Wraps the CanvasCreateMenu component. Only active on canvas pages.
+ */
+export const id = 'canvas-add-widget'
+
+export async function component() {
+  const mod = await import('../../CanvasCreateMenu.svelte')
+  return mod.default
+}

package/src/tools/handlers/canvasZoom.js

@@ -0,0 +1,34 @@
+/**
+ * Canvas zoom tool module — zoom in/out/reset controls for canvas pages.
+ *
+ * Provides zoom actions via custom events (Svelte↔React bridge).
+ * Uses the unique "zoom-control" render type.
+ */
+export const id = 'canvas-zoom'
+
+const ZOOM_STEP = 10
+const ZOOM_MIN = 25
+const ZOOM_MAX = 200
+
+export async function handler() {
+  return {
+    zoomIn(currentZoom) {
+      const next = Math.min(ZOOM_MAX, currentZoom + ZOOM_STEP)
+      document.dispatchEvent(new CustomEvent('storyboard:canvas:set-zoom', { detail: { zoom: next } }))
+    },
+    zoomOut(currentZoom) {
+      const next = Math.max(ZOOM_MIN, currentZoom - ZOOM_STEP)
+      document.dispatchEvent(new CustomEvent('storyboard:canvas:set-zoom', { detail: { zoom: next } }))
+    },
+    zoomReset() {
+      document.dispatchEvent(new CustomEvent('storyboard:canvas:set-zoom', { detail: { zoom: 100 } }))
+    },
+    ZOOM_MIN,
+    ZOOM_MAX,
+  }
+}
+
+export async function component() {
+  const mod = await import('../../CanvasZoomControl.svelte')
+  return mod.default
+}

package/src/tools/handlers/comments.js

@@ -0,0 +1,16 @@
+/**
+ * Comments tool module — comment pins and annotation system.
+ *
+ * Guard: only mounts if comments are enabled in storyboard.config.json.
+ */
+export const id = 'comments'
+
+export async function guard() {
+  const { isCommentsEnabled } = await import('../../comments/config.js')
+  return isCommentsEnabled()
+}
+
+export async function component() {
+  const mod = await import('../../CommentsMenuButton.svelte')
+  return mod.default
+}

package/src/tools/handlers/create.js

@@ -0,0 +1,39 @@
+/**
+ * Create tool module — workshop prototype/flow/canvas creation.
+ *
+ * Loads the workshop feature registry and CreateMenuButton component.
+ * Guard: only mounts if at least one create feature has an overlay.
+ */
+export const id = 'create'
+
+export async function setup(ctx) {
+  const { config } = ctx
+  const { features } = await import('../../workshop/features/registry.js')
+
+  const createActions = Array.isArray(config.actions) ? config.actions : []
+  const createFeatures = createActions
+    .filter(a => a.feature)
+    .map(a => {
+      const feat = features[a.feature]
+      if (!feat || !feat.overlayId || !feat.overlay) return null
+      return {
+        name: feat.name,
+        label: a.label || feat.label,
+        overlayId: feat.overlayId,
+        overlay: feat.overlay,
+      }
+    })
+    .filter(Boolean)
+
+  return { features: createFeatures }
+}
+
+export async function guard(ctx) {
+  const result = await setup(ctx)
+  return result.features.length > 0
+}
+
+export async function component() {
+  const mod = await import('../../CreateMenuButton.svelte')
+  return mod.default
+}

package/src/tools/handlers/devtools.js

@@ -0,0 +1,80 @@
+/**
+ * Devtools tool module — developer utilities submenu.
+ *
+ * Renders as a submenu in the command menu with:
+ * - Show flow info
+ * - Reset all params
+ * - Hide mode toggle
+ * - Logout (when authenticated)
+ */
+export const id = 'devtools'
+
+/**
+ * @param {object} ctx
+ * @param {Function} ctx.showFlowInfoDialog - callback to open flow info dialog
+ */
+export async function handler(ctx) {
+  let loader = null
+  let hm = null
+  let commentsAuth = null
+  try { loader = await import('../../loader.js') } catch { /* optional */ }
+  try { hm = await import('../../hideMode.js') } catch { /* optional */ }
+  try { commentsAuth = await import('../../comments/auth.js') } catch { /* optional */ }
+
+  return {
+    getChildren: () => {
+      const children = []
+      if (loader) {
+        children.push({
+          id: 'core/show-flow-info',
+          label: 'Show flow info',
+          type: 'default',
+          execute: () => {
+            const p = new URLSearchParams(window.location.search)
+            const name = p.get('flow') || p.get('scene') || 'default'
+            try {
+              const data = loader.loadFlow(name)
+              if (ctx.showFlowInfoDialog) {
+                ctx.showFlowInfoDialog(name, JSON.stringify(data, null, 2), null)
+              }
+            } catch (e) {
+              if (ctx.showFlowInfoDialog) {
+                ctx.showFlowInfoDialog(name, '', e.message)
+              }
+            }
+          },
+        })
+      }
+      children.push({
+        id: 'core/reset-params',
+        label: 'Reset all params',
+        type: 'default',
+        execute: () => { window.location.hash = '' },
+      })
+      if (hm) {
+        children.push({
+          id: 'core/hide-mode',
+          label: 'Hide mode',
+          type: 'toggle',
+          active: hm.isHideMode(),
+          execute: () => {
+            if (hm.isHideMode()) hm.deactivateHideMode()
+            else hm.activateHideMode()
+          },
+        })
+      }
+      if (commentsAuth?.isAuthenticated()) {
+        children.push({
+          id: 'core/logout',
+          label: 'Logout (remove token)',
+          type: 'default',
+          execute: () => {
+            commentsAuth.clearToken()
+            console.log('[storyboard] Token removed')
+          },
+        })
+      }
+      return children
+    },
+  }
+}

package/src/tools/handlers/docs.js

@@ -0,0 +1,11 @@
+/**
+ * Docs tool module — documentation sidepanel toggle.
+ */
+export const id = 'docs'
+
+// No component needed — sidepanel tools use generic TriggerButton
+
+export async function handler() {
+  const { togglePanel } = await import('../../stores/sidePanelStore.js')
+  return () => togglePanel('docs')
+}

package/src/tools/handlers/featureFlags.js

@@ -0,0 +1,21 @@
+/**
+ * Feature Flags tool module — toggle feature flags submenu.
+ *
+ * Renders as a submenu in the command menu listing all declared flags.
+ */
+export const id = 'feature-flags'
+
+export async function handler() {
+  const ff = await import('../../featureFlags.js')
+
+  return {
+    getChildren: () =>
+      ff.getFlagKeys().map(key => ({
+        id: `flags/${key}`,
+        label: key,
+        type: 'toggle',
+        active: ff.getFlag(key),
+        execute: () => ff.toggleFlag(key),
+      })),
+  }
+}

package/src/tools/handlers/flows.js

@@ -0,0 +1,59 @@
+/**
+ * Flows tool module — flow switcher action menu.
+ *
+ * Registers a command action handler that lists available flows
+ * for the current prototype and lets users switch between them.
+ */
+export const id = 'flows'
+
+export async function handler(ctx) {
+  const loader = await import('../../loader.js')
+  const vf = await import('../../viewfinder.js')
+  const { basePath = '/' } = ctx
+
+  return {
+    getChildren: () => {
+      let path = window.location.pathname
+      const base = basePath.replace(/\/+$/, '')
+      if (base && path.startsWith(base)) path = path.slice(base.length)
+      path = path.replace(/\/+$/, '') || '/'
+      const segments = path.split('/').filter(Boolean)
+      const proto = segments[0] || null
+      if (!proto) return []
+
+      const params = new URLSearchParams(window.location.search)
+      const explicit = params.get('flow') || params.get('scene')
+      let active
+      if (explicit) {
+        active = loader.resolveFlowName(proto, explicit)
+      } else {
+        const pageFlow = path === '/' ? 'index' : (path.split('/').pop() || 'index')
+        const scoped = loader.resolveFlowName(proto, pageFlow)
+        if (loader.flowExists(scoped)) active = scoped
+        else {
+          const protoFlow = loader.resolveFlowName(proto, proto)
+          active = loader.flowExists(protoFlow) ? protoFlow : 'default'
+        }
+      }
+
+      const flows = loader.getFlowsForPrototype(proto)
+      if (flows.length <= 1) return []
+
+      return flows.map(f => {
+        const meta = vf.getFlowMeta(f.key)
+        return {
+          id: f.key,
+          label: meta?.title || f.name,
+          type: 'radio',
+          active: f.key === active,
+          execute: () => { window.location.href = vf.resolveFlowRoute(f.key) },
+        }
+      })
+    },
+  }
+}
+
+export async function component() {
+  const mod = await import('../../ActionMenuButton.svelte')
+  return mod.default
+}

package/src/tools/handlers/inspector.js

@@ -0,0 +1,19 @@
+/**
+ * Inspector tool module — component inspector sidepanel.
+ *
+ * Auto-opens the panel if ?inspect= is in the URL.
+ */
+export const id = 'inspector'
+
+export async function setup() {
+  const { openPanel } = await import('../../stores/sidePanelStore.js')
+
+  try {
+    const inspectParam = new URL(window.location.href).searchParams.get('inspect')
+    if (inspectParam) {
+      openPanel('inspector')
+    }
+  } catch { /* ignore */ }
+}
+
+// No component needed — sidepanel tools use generic TriggerButton

package/src/tools/handlers/theme.js

@@ -0,0 +1,9 @@
+/**
+ * Theme tool module — theme switcher menu.
+ */
+export const id = 'theme'
+
+export async function component() {
+  const mod = await import('../../ThemeMenuButton.svelte')
+  return mod.default
+}

package/src/tools/registry.js

@@ -0,0 +1,21 @@
+/**
+ * Tool module registry — maps tool IDs to lazy-loaded handler modules.
+ *
+ * Each handler module exports: { id, component?, handler?, setup?, guard? }
+ * All imports are dynamic to enable code splitting.
+ */
+export const coreHandlers = {
+  create:               () => import('./handlers/create.js'),
+  theme:                () => import('./handlers/theme.js'),
+  comments:             () => import('./handlers/comments.js'),
+  flows:                () => import('./handlers/flows.js'),
+  docs:                 () => import('./handlers/docs.js'),
+  inspector:            () => import('./handlers/inspector.js'),
+  devtools:             () => import('./handlers/devtools.js'),
+  'feature-flags':      () => import('./handlers/featureFlags.js'),
+  'canvas-add-widget':  () => import('./handlers/canvasAddWidget.js'),
+  'canvas-zoom':        () => import('./handlers/canvasZoom.js'),
+}
+
+// Keep legacy export name for backward compatibility
+export const toolModules = coreHandlers

package/src/tools/surfaces/canvasToolbar.js

@@ -0,0 +1,10 @@
+/**
+ * Canvas Toolbar surface — floating bar at bottom-left on canvas pages.
+ *
+ * Only visible when a canvas page is active. Supports menus and
+ * custom render types like zoom-control.
+ */
+export const id = 'canvas-toolbar'
+export const label = 'Canvas Toolbar'
+export const position = 'bottom-left'
+export const renderTypes = ['menu', 'zoom-control']

package/src/tools/surfaces/commandList.js

@@ -0,0 +1,10 @@
+/**
+ * Command List surface — items rendered inside the ⌘K command menu.
+ *
+ * Tools here appear as menu items, submenus, or links within
+ * the command palette. They don't render as standalone buttons.
+ */
+export const id = 'command-list'
+export const label = 'Command Menu'
+export const position = 'overlay'
+export const renderTypes = ['link', 'submenu']

package/src/tools/surfaces/mainToolbar.js

@@ -0,0 +1,11 @@
+/**
+ * Main Toolbar surface — the primary floating bar at bottom-right.
+ *
+ * Supports all standard render types. Tools appear in reverse JSON order
+ * (first in config = leftmost in toolbar). The command menu button is
+ * always the rightmost item and is not a tool.
+ */
+export const id = 'main-toolbar'
+export const label = 'Main Toolbar'
+export const position = 'bottom-right'
+export const renderTypes = ['button', 'menu', 'sidepanel', 'separator']

package/src/tools/surfaces/registry.js

@@ -0,0 +1,19 @@
+/**
+ * Surface registry — exports all available rendering surfaces.
+ *
+ * Surfaces define WHERE a tool renders. Each surface has a position,
+ * supported render types, and rendering logic in CoreUIBar.
+ *
+ * To add a new surface:
+ * 1. Create a definition file in this directory
+ * 2. Export it from this registry
+ * 3. Add rendering logic in CoreUIBar.svelte
+ */
+export { id as mainToolbar } from './mainToolbar.js'
+export { id as canvasToolbar } from './canvasToolbar.js'
+export { id as commandList } from './commandList.js'
+
+/**
+ * All surface IDs for validation.
+ */
+export const SURFACE_IDS = ['main-toolbar', 'canvas-toolbar', 'command-list']

package/src/vite/server-plugin.js

@@ -64,6 +64,7 @@ export default function storyboardServer() {
   let root = ''
   let base = '/'
   let config = {}
+  let isDev = false
 
   // Route handler registry — plugins register here during setup
   const routeHandlers = new Map()
@@ -76,6 +77,7 @@ export default function storyboardServer() {
       root = viteConfig.root
       base = viteConfig.base || '/'
       config = readConfig(root)
+      isDev = viteConfig.command === 'serve'
     },
 
     configureServer(server) {
@@ -178,12 +180,14 @@ export default function storyboardServer() {
     transformIndexHtml() {
       const tags = []
 
-      // Inject local dev flag so the UI can gate dev-only tools
-      tags.push({
-        tag: 'script',
-        children: 'window.__SB_LOCAL_DEV__=true',
-        injectTo: 'head',
-      })
+      // Inject local dev flag only during dev server (not production builds)
+      if (isDev) {
+        tags.push({
+          tag: 'script',
+          children: 'window.__SB_LOCAL_DEV__=true',
+          injectTo: 'head',
+        })
+      }
 
       // Inject base path so the inspector UI can resolve static assets
       // (e.g. inspector.json) when deployed under a subpath
@@ -262,6 +266,32 @@ export default function storyboardServer() {
         }),
       })
 
+      // Emit README as static JSON so the docs panel works in deployed builds.
+      // Dev server serves this dynamically; production needs the static file.
+      let readmeContent = null
+      for (const candidate of ['README.md', 'readme.md', 'Readme.md']) {
+        try {
+          readmeContent = await fs.promises.readFile(path.join(root, candidate), 'utf-8')
+          break
+        } catch { /* try next */ }
+      }
+      if (readmeContent) {
+        this.emitFile({
+          type: 'asset',
+          fileName: '_storyboard/docs/readme',
+          source: JSON.stringify({ content: readmeContent, path: 'README.md' }),
+        })
+      }
+
+      // Emit repo info so the docs panel GitHub link works in deployed builds.
+      if (repo) {
+        this.emitFile({
+          type: 'asset',
+          fileName: '_storyboard/docs/repo',
+          source: JSON.stringify(repo),
+        })
+      }
+
       // GitHub Pages uses Jekyll which ignores _-prefixed directories.
       // Emit .nojekyll to ensure _storyboard/ is served.
       this.emitFile({