@dfosco/storyboard-core 2.0.0 → 2.2.0

package/src/svelte-plugin-ui/stores/toolStore.ts

@@ -0,0 +1,71 @@
+/**
+ * Svelte store that wraps the core tool registry API.
+ *
+ * Provides a readable store whose value updates whenever:
+ * - The active mode changes (different tools for each mode)
+ * - Tool state or actions change (setToolState, setToolAction)
+ *
+ * Groups tools into { tools, devTools } for the toolbar to consume.
+ */
+
+import { writable, type Readable } from 'svelte/store'
+import {
+  getCurrentMode,
+  getToolsForMode,
+  subscribeToMode,
+  subscribeToTools,
+} from './types.js'
+import type { ResolvedTool } from './types.js'
+
+export interface ToolStoreState {
+  /** Tools in the 'tools' group for the current mode */
+  tools: ResolvedTool[]
+  /** Tools in the 'dev' group for the current mode */
+  devTools: ResolvedTool[]
+}
+
+function snapshot(): ToolStoreState {
+  const mode = getCurrentMode()
+  const allTools = getToolsForMode(mode)
+  return {
+    tools: allTools.filter((t) => t.group === 'tools'),
+    devTools: allTools.filter((t) => t.group === 'dev'),
+  }
+}
+
+function createToolStore(): Readable<ToolStoreState> {
+  const { subscribe: rawSubscribe, set } = writable<ToolStoreState>(snapshot())
+
+  const subscribe: Readable<ToolStoreState>['subscribe'] = (run, invalidate) => {
+    set(snapshot())
+
+    // Re-snapshot on mode changes OR tool state/action changes
+    const unsubMode = subscribeToMode(() => set(snapshot()))
+    const unsubTools = subscribeToTools(() => set(snapshot()))
+
+    const unsubStore = rawSubscribe(run, invalidate)
+
+    return () => {
+      unsubStore()
+      unsubMode()
+      unsubTools()
+    }
+  }
+
+  return { subscribe }
+}
+
+/**
+ * Readable Svelte store for the tool registry.
+ *
+ * ```svelte
+ * <script>
+ *   import { toolState } from '../stores/toolStore.js'
+ * </script>
+ *
+ * {#each $toolState.tools as tool}
+ *   <button onclick={tool.action} disabled={!tool.state.enabled}>{tool.label}</button>
+ * {/each}
+ * ```
+ */
+export const toolState: Readable<ToolStoreState> = createToolStore()

package/src/svelte-plugin-ui/stores/types.ts

@@ -19,14 +19,11 @@ export {
   on,
   off,
   emit,
+  getToolsForMode,
+  subscribeToTools,
+  getToolsSnapshot,
 } from '../../modes.js'
 
-export interface ModeToolConfig {
-  id: string
-  label: string
-  action: () => void
-}
-
 export interface ModeConfig {
   name: string
   label: string
@@ -34,6 +31,23 @@ export interface ModeConfig {
   className?: string | string[]
   onActivate?: (options?: Record<string, unknown>) => void
   onDeactivate?: () => void
-  tools?: ModeToolConfig[]
-  devTools?: ModeToolConfig[]
+}
+
+export interface ToolState {
+  enabled: boolean
+  active: boolean
+  busy: boolean
+  hidden: boolean
+  badge: string | number | null
+}
+
+export interface ResolvedTool {
+  id: string
+  label: string
+  group: 'tools' | 'dev'
+  icon: string | null
+  order: number
+  modes: string[]
+  state: ToolState
+  action: (() => void) | null
 }

package/src/{svelte-plugin-ui/plugins → ui}/design-modes.ts

@@ -1,19 +1,20 @@
 /**
- * Design-modes plugin mount entry point.
+ * Design-modes UI mount entry point.
  *
  * Call mountDesignModesUI() once at app startup to render the ModeSwitch
  * and ToolbarShell components.  Framework-agnostic — works from any JS
- * context (React _app.jsx, vanilla JS, etc.).
+ * context (React StoryboardProvider, vanilla JS, etc.).
  *
  * Usage:
- *   import { mountDesignModesUI } from '@dfosco/storyboard-core/svelte-plugin-ui/design-modes'
+ *   import { mountDesignModesUI } from '@dfosco/storyboard-core/ui/design-modes'
  *   mountDesignModesUI()  // mounts to document.body
  *   mountDesignModesUI(document.getElementById('my-container'))
  */
 
-import { mountSveltePlugin, type PluginHandle } from '../mount.js'
-import ModeSwitch from '../components/ModeSwitch.svelte'
-import ToolbarShell from '../components/ToolbarShell.svelte'
+import { mountSveltePlugin, type PluginHandle } from '../svelte-plugin-ui/mount.js'
+import ModeSwitch from '../svelte-plugin-ui/components/ModeSwitch.svelte'
+// TODO: Re-enable after migrating devtools features into tool registry
+// import ToolbarShell from '../svelte-plugin-ui/components/ToolbarShell.svelte'
 
 let handles: PluginHandle[] = []
 
@@ -35,7 +36,8 @@ export function mountDesignModesUI(
 
   handles.push(
     mountSveltePlugin(target, ModeSwitch),
-    mountSveltePlugin(target, ToolbarShell),
+    // TODO: Re-enable after migrating devtools features into tool registry
+    // mountSveltePlugin(target, ToolbarShell),
   )
 
   return unmountDesignModesUI

package/src/ui/viewfinder.ts

@@ -0,0 +1,58 @@
+/**
+ * Viewfinder UI mount entry point.
+ *
+ * Call mountViewfinder() to render the prototype index dashboard.
+ * Framework-agnostic — works from any JS context (React wrapper,
+ * vanilla JS, etc.).
+ *
+ * Usage:
+ *   import { mountViewfinder } from '@dfosco/storyboard-core/ui/viewfinder'
+ *   const handle = mountViewfinder(document.getElementById('root'), {
+ *     title: 'My Storyboard',
+ *     knownRoutes: ['Dashboard', 'Settings'],
+ *   })
+ *   // later: handle.destroy()
+ */
+
+import { mountSveltePlugin, type PluginHandle } from '../svelte-plugin-ui/mount.js'
+import Viewfinder from '../svelte-plugin-ui/components/Viewfinder.svelte'
+
+export interface ViewfinderProps {
+  title?: string
+  subtitle?: string
+  basePath?: string
+  knownRoutes?: string[]
+  showThumbnails?: boolean
+  hideDefaultFlow?: boolean
+}
+
+let handle: PluginHandle | null = null
+
+/**
+ * Mount the Viewfinder dashboard into a DOM container.
+ *
+ * Idempotent — calling multiple times is a no-op.
+ * Returns a handle with destroy() method.
+ *
+ * @param container - DOM element to mount into
+ * @param props - Viewfinder configuration
+ */
+export function mountViewfinder(
+  container: HTMLElement,
+  props?: ViewfinderProps,
+): PluginHandle {
+  if (handle) return handle
+
+  handle = mountSveltePlugin(container, Viewfinder as any, props as any)
+  return handle
+}
+
+/**
+ * Remove the Viewfinder from the DOM.
+ */
+export function unmountViewfinder(): void {
+  if (handle) {
+    handle.destroy()
+    handle = null
+  }
+}

package/src/viewfinder.js

@@ -1,4 +1,4 @@
-import { loadScene } from './loader.js'
+import { loadFlow, listFlows, listPrototypes, getPrototypeMetadata } from './loader.js'
 
 /**
  * Deterministic hash from a string — used for seeding generative placeholders.
@@ -14,52 +14,132 @@ export function hash(str) {
 }
 
 /**
- * Resolve the target route path for a scene.
+ * Resolve the target route path for a flow.
  *
- * 1. If scene name matches a known route (case-insensitive), use that route
- * 2. If scene data has a `sceneMeta.route` or `route` key, use that
+ * 1. If flow name matches a known route (case-insensitive), use that route
+ * 2. If flow data has a top-level `route`, or `meta.route` / `sceneMeta.route`, use that
  * 3. Fall back to root "/"
  *
- * @param {string} sceneName
+ * @param {string} flowName
  * @param {string[]} knownRoutes - Array of route names (e.g. ["Dashboard", "Repositories"])
- * @returns {string} Full path with ?scene= param
+ * @returns {string} Full path with ?flow= param
  */
-export function resolveSceneRoute(sceneName, knownRoutes = []) {
+export function resolveFlowRoute(flowName, knownRoutes = []) {
   // Case-insensitive match against known routes
   for (const route of knownRoutes) {
-    if (route.toLowerCase() === sceneName.toLowerCase()) {
-      // Scene name matches the route — no ?scene= needed,
+    if (route.toLowerCase() === flowName.toLowerCase()) {
+      // Flow name matches the route — no ?flow= needed,
       // StoryboardProvider auto-matches by page name
       return `/${route}`
     }
   }
 
-  // Check for explicit route in sceneMeta or top-level route key
+  // Check for explicit route: top-level `route`, then meta.route, then legacy sceneMeta.route
   try {
-    const data = loadScene(sceneName)
-    const route = data?.sceneMeta?.route || data?.route
+    const data = loadFlow(flowName)
+    const route = data?.route || data?.meta?.route || data?.flowMeta?.route || data?.sceneMeta?.route
     if (route) {
       const normalized = route.startsWith('/') ? route : `/${route}`
-      return `${normalized}?scene=${encodeURIComponent(sceneName)}`
+      return `${normalized}?flow=${encodeURIComponent(flowName)}`
     }
   } catch {
     // ignore load errors
   }
 
-  return `/?scene=${encodeURIComponent(sceneName)}`
+  return `/?flow=${encodeURIComponent(flowName)}`
 }
 
+/** @deprecated Use resolveFlowRoute() */
+export const resolveSceneRoute = resolveFlowRoute
+
 /**
- * Get sceneMeta for a scene (route, author, etc).
+ * Get meta for a flow (title, description, author, etc).
  *
- * @param {string} sceneName
- * @returns {{ route?: string, author?: string | string[] } | null}
+ * @param {string} flowName
+ * @returns {{ title?: string, description?: string, author?: string | string[] } | null}
  */
-export function getSceneMeta(sceneName) {
+export function getFlowMeta(flowName) {
   try {
-    const data = loadScene(sceneName)
-    return data?.sceneMeta || null
+    const data = loadFlow(flowName)
+    return data?.meta || data?.flowMeta || data?.sceneMeta || null
   } catch {
     return null
   }
 }
+
+/** @deprecated Use getFlowMeta() */
+export const getSceneMeta = getFlowMeta
+
+/**
+ * Build a structured prototype index grouping flows by prototype.
+ *
+ * Returns an object with:
+ * - prototypes: array of prototype entries with metadata and their flows
+ * - globalFlows: flows not belonging to any prototype
+ *
+ * @param {string[]} [knownRoutes] - Array of known route names
+ * @returns {{ prototypes: Array, globalFlows: Array }}
+ */
+export function buildPrototypeIndex(knownRoutes = []) {
+  const flows = listFlows()
+  const protoMap = {}
+  const globalFlows = []
+
+  // Seed from .prototype.json metadata (even prototypes with no flows appear)
+  for (const name of listPrototypes()) {
+    const raw = getPrototypeMetadata(name)
+    const meta = raw?.meta || raw || {}
+    protoMap[name] = {
+      name: meta.title || name,
+      dirName: name,
+      description: meta.description || null,
+      author: meta.author || null,
+      gitAuthor: raw?.gitAuthor || null,
+      icon: meta.icon || null,
+      team: meta.team || null,
+      tags: meta.tags || null,
+      flows: [],
+    }
+  }
+
+  for (const flowName of flows) {
+    const slashIdx = flowName.indexOf('/')
+    if (slashIdx > 0) {
+      const protoName = flowName.substring(0, slashIdx)
+      const shortName = flowName.substring(slashIdx + 1)
+
+      if (!protoMap[protoName]) {
+        protoMap[protoName] = {
+          name: protoName,
+          dirName: protoName,
+          description: null,
+          author: null,
+          gitAuthor: null,
+          icon: null,
+          team: null,
+          tags: null,
+          flows: [],
+        }
+      }
+
+      protoMap[protoName].flows.push({
+        key: flowName,
+        name: shortName,
+        route: resolveFlowRoute(flowName, knownRoutes),
+        meta: getFlowMeta(flowName),
+      })
+    } else {
+      globalFlows.push({
+        key: flowName,
+        name: flowName,
+        route: resolveFlowRoute(flowName, knownRoutes),
+        meta: getFlowMeta(flowName),
+      })
+    }
+  }
+
+  return {
+    prototypes: Object.values(protoMap),
+    globalFlows,
+  }
+}

package/src/viewfinder.test.js

@@ -1,17 +1,17 @@
 import { init } from './loader.js'
-import { hash, resolveSceneRoute, getSceneMeta } from './viewfinder.js'
+import { hash, resolveFlowRoute, getFlowMeta, resolveSceneRoute, getSceneMeta } from './viewfinder.js'
 
 const makeIndex = () => ({
-  scenes: {
+  flows: {
     default: { title: 'Default Scene' },
     Dashboard: { heading: 'Dashboard' },
     'custom-route': { route: 'Overview', title: 'Custom' },
     'absolute-route': { route: '/Forms', title: 'Absolute' },
     'no-route': { title: 'No route key' },
-    'meta-route': { sceneMeta: { route: 'Repositories' }, title: 'Meta Route' },
-    'meta-author': { sceneMeta: { author: 'dfosco' }, title: 'With Author' },
-    'meta-authors': { sceneMeta: { author: ['dfosco', 'heyamie', 'branonconor'] }, title: 'Multi Author' },
-    'meta-both': { sceneMeta: { route: '/Overview', author: 'octocat' }, title: 'Both' },
+    'meta-route': { flowMeta: { route: 'Repositories' }, title: 'Meta Route' },
+    'meta-author': { flowMeta: { author: 'dfosco' }, title: 'With Author' },
+    'meta-authors': { flowMeta: { author: ['dfosco', 'heyamie', 'branonconor'] }, title: 'Multi Author' },
+    'meta-both': { flowMeta: { route: '/Overview', author: 'octocat' }, title: 'Both' },
   },
   objects: {},
   records: {},
@@ -41,90 +41,112 @@ describe('hash', () => {
   })
 })
 
-describe('resolveSceneRoute', () => {
+describe('resolveFlowRoute', () => {
   const routes = ['Dashboard', 'Overview', 'Forms', 'Repositories']
 
-  it('matches scene name to route (exact case)', () => {
-    expect(resolveSceneRoute('Dashboard', routes)).toBe('/Dashboard')
+  it('matches flow name to route (exact case)', () => {
+    expect(resolveFlowRoute('Dashboard', routes)).toBe('/Dashboard')
   })
 
-  it('matches scene name to route (case-insensitive)', () => {
-    expect(resolveSceneRoute('dashboard', routes)).toBe('/Dashboard')
+  it('matches flow name to route (case-insensitive)', () => {
+    expect(resolveFlowRoute('dashboard', routes)).toBe('/Dashboard')
   })
 
-  it('uses route key from scene data when no route matches', () => {
-    expect(resolveSceneRoute('custom-route', routes)).toBe('/Overview?scene=custom-route')
+  it('uses route key from flow data when no route matches', () => {
+    expect(resolveFlowRoute('custom-route', routes)).toBe('/Overview?flow=custom-route')
   })
 
   it('handles absolute route key (with leading slash)', () => {
-    expect(resolveSceneRoute('absolute-route', routes)).toBe('/Forms?scene=absolute-route')
+    expect(resolveFlowRoute('absolute-route', routes)).toBe('/Forms?flow=absolute-route')
   })
 
   it('falls back to root when no match and no route key', () => {
-    expect(resolveSceneRoute('no-route', routes)).toBe('/?scene=no-route')
+    expect(resolveFlowRoute('no-route', routes)).toBe('/?flow=no-route')
   })
 
-  it('falls back to root for default scene', () => {
-    expect(resolveSceneRoute('default', routes)).toBe('/?scene=default')
+  it('falls back to root for default flow', () => {
+    expect(resolveFlowRoute('default', routes)).toBe('/?flow=default')
   })
 
-  it('falls back to root when scene does not exist', () => {
-    expect(resolveSceneRoute('nonexistent', routes)).toBe('/?scene=nonexistent')
+  it('falls back to root when flow does not exist', () => {
+    expect(resolveFlowRoute('nonexistent', routes)).toBe('/?flow=nonexistent')
   })
 
   it('works with empty routes array', () => {
-    expect(resolveSceneRoute('Dashboard', [])).toBe('/?scene=Dashboard')
+    expect(resolveFlowRoute('Dashboard', [])).toBe('/?flow=Dashboard')
   })
 
   it('works with no routes argument', () => {
-    expect(resolveSceneRoute('custom-route')).toBe('/Overview?scene=custom-route')
+    expect(resolveFlowRoute('custom-route')).toBe('/Overview?flow=custom-route')
   })
 
-  it('encodes special characters in scene name', () => {
+  it('encodes special characters in flow name', () => {
     init({
-      scenes: { 'has spaces': { title: 'Spaces' } },
+      flows: { 'has spaces': { title: 'Spaces' } },
       objects: {},
       records: {},
     })
-    expect(resolveSceneRoute('has spaces', [])).toBe('/?scene=has%20spaces')
+    expect(resolveFlowRoute('has spaces', [])).toBe('/?flow=has%20spaces')
   })
 
-  it('uses sceneMeta.route when no route matches', () => {
-    expect(resolveSceneRoute('meta-route', routes)).toBe('/Repositories?scene=meta-route')
+  it('uses flowMeta.route when no route matches', () => {
+    expect(resolveFlowRoute('meta-route', routes)).toBe('/Repositories?flow=meta-route')
   })
 
-  it('uses sceneMeta.route with absolute path', () => {
-    expect(resolveSceneRoute('meta-both', routes)).toBe('/Overview?scene=meta-both')
+  it('uses flowMeta.route with absolute path', () => {
+    expect(resolveFlowRoute('meta-both', routes)).toBe('/Overview?flow=meta-both')
   })
 
-  it('prefers sceneMeta.route over top-level route key', () => {
+  it('prefers top-level route over flowMeta.route', () => {
     init({
-      scenes: { conflict: { route: 'Forms', sceneMeta: { route: 'Dashboard' } } },
+      flows: { conflict: { route: 'Forms', flowMeta: { route: 'Dashboard' } } },
       objects: {},
       records: {},
     })
-    expect(resolveSceneRoute('conflict', [])).toBe('/Dashboard?scene=conflict')
+    expect(resolveFlowRoute('conflict', [])).toBe('/Forms?flow=conflict')
   })
 })
 
-describe('getSceneMeta', () => {
-  it('returns sceneMeta when present', () => {
-    expect(getSceneMeta('meta-author')).toEqual({ author: 'dfosco' })
+describe('getFlowMeta', () => {
+  it('returns flowMeta when present', () => {
+    expect(getFlowMeta('meta-author')).toEqual({ author: 'dfosco' })
+  })
+
+  it('returns flowMeta with both fields', () => {
+    expect(getFlowMeta('meta-both')).toEqual({ route: '/Overview', author: 'octocat' })
   })
 
-  it('returns sceneMeta with both fields', () => {
-    expect(getSceneMeta('meta-both')).toEqual({ route: '/Overview', author: 'octocat' })
+  it('returns flowMeta with array author', () => {
+    expect(getFlowMeta('meta-authors')).toEqual({ author: ['dfosco', 'heyamie', 'branonconor'] })
   })
 
-  it('returns sceneMeta with array author', () => {
-    expect(getSceneMeta('meta-authors')).toEqual({ author: ['dfosco', 'heyamie', 'branonconor'] })
+  it('returns null when no flowMeta', () => {
+    expect(getFlowMeta('default')).toBeNull()
   })
 
-  it('returns null when no sceneMeta', () => {
-    expect(getSceneMeta('default')).toBeNull()
+  it('returns null for nonexistent flow', () => {
+    expect(getFlowMeta('nonexistent')).toBeNull()
+  })
+})
+
+// ── Deprecated aliases ──
+
+describe('resolveSceneRoute (deprecated alias)', () => {
+  it('is the same function as resolveFlowRoute', () => {
+    expect(resolveSceneRoute).toBe(resolveFlowRoute)
   })
 
-  it('returns null for nonexistent scene', () => {
-    expect(getSceneMeta('nonexistent')).toBeNull()
+  it('resolves a flow route', () => {
+    expect(resolveSceneRoute('Dashboard', ['Dashboard'])).toBe('/Dashboard')
+  })
+})
+
+describe('getSceneMeta (deprecated alias)', () => {
+  it('is the same function as getFlowMeta', () => {
+    expect(getSceneMeta).toBe(getFlowMeta)
+  })
+
+  it('returns flow meta', () => {
+    expect(getSceneMeta('meta-author')).toEqual({ author: 'dfosco' })
   })
 })

package/src/workshop/features/createPage/server.js

@@ -9,7 +9,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 
-const SCENE_SKELETON = JSON.stringify({ $global: [] }, null, 2) + '\n'
+const FLOW_SKELETON = JSON.stringify({ $global: [] }, null, 2) + '\n'
 
 /**
  * Convert a raw name to PascalCase for use as component name + filename.
@@ -66,7 +66,7 @@ function renderTemplate(templatesDir, templateName, pageName) {
  * List all existing page files in src/pages/.
  */
 function listPages(root) {
-  const pagesDir = path.join(root, 'src', 'pages')
+  const pagesDir = path.join(root, 'src', 'prototypes')
   if (!fs.existsSync(pagesDir)) return []
 
   return fs.readdirSync(pagesDir)
@@ -103,7 +103,7 @@ export function createPagesHandler(ctx, templatesDir) {
       }
 
       const { pascalName } = validation
-      const pagesDir = path.join(root, 'src', 'pages')
+      const pagesDir = path.join(root, 'src', 'prototypes')
       const pagePath = path.join(pagesDir, `${pascalName}.jsx`)
 
       if (fs.existsSync(pagePath)) {
@@ -124,18 +124,18 @@ export function createPagesHandler(ctx, templatesDir) {
 
       const result = {
         success: true,
-        path: `src/pages/${pascalName}.jsx`,
+        path: `src/prototypes/${pascalName}.jsx`,
         route: `/${pascalName}`,
       }
 
       if (createScene) {
         const dataDir = path.join(root, 'src', 'data')
-        const scenePath = path.join(dataDir, `${pascalName}.scene.json`)
+        const flowPath = path.join(dataDir, `${pascalName}.flow.json`)
 
-        if (!fs.existsSync(scenePath)) {
+        if (!fs.existsSync(flowPath)) {
           fs.mkdirSync(dataDir, { recursive: true })
-          fs.writeFileSync(scenePath, SCENE_SKELETON, 'utf-8')
-          result.scenePath = `src/data/${pascalName}.scene.json`
+          fs.writeFileSync(flowPath, FLOW_SKELETON, 'utf-8')
+          result.flowPath = `src/data/${pascalName}.flow.json`
         }
       }