@dfosco/storyboard-react 4.2.0-alpha.14 → 4.2.0-alpha.16

package/src/canvas/widgets/snapshotDisplay.test.jsx

@@ -1,8 +1,8 @@
 /**
  * Tests for iframe snapshot display — single snapshot prop.
  */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { render, fireEvent, waitFor, act } from '@testing-library/react'
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
 import PrototypeEmbed from './PrototypeEmbed.jsx'
 import StoryWidget from './StoryWidget.jsx'
 
@@ -54,9 +54,9 @@ afterEach(() => {
   document.querySelectorAll('[data-sb-canvas-theme]').forEach(el => el.remove())
 })
 
-describe('Snapshot display', () => {
+describe('Snapshot display (snapshots removed — iframes always render)', () => {
   describe('PrototypeEmbed', () => {
-    it('shows snapshot image when valid snapshot prop exists', () => {
+    it('renders iframe even when snapshot prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-abc123"
@@ -72,13 +72,11 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-proto-abc123.webp')
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('falls back to snapshotLight for backward compat', () => {
+    it('renders iframe when snapshotLight prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-abc123"
@@ -94,12 +92,11 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-proto-abc123--light.webp')
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('shows placeholder when no snapshot exists', () => {
+    it('renders iframe when no snapshot exists', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-xyz"
@@ -110,32 +107,10 @@ describe('Snapshot display', () => {
       )
 
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
-    })
-
-    it('falls back to placeholder when snapshot image fails to load', () => {
-      const { wrapper } = renderInCanvas(
-        <PrototypeEmbed
-          id="proto-abc123"
-          props={{
-            src: '/test',
-            width: 400,
-            height: 300,
-            zoom: 100,
-            snapshot: '/_storyboard/canvas/images/snapshot-proto-abc123.webp?v=123',
-          }}
-          onUpdate={vi.fn()}
-          resizable={false}
-        />
-      )
-
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      fireEvent.error(img)
-      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('ignores snapshot that does not match widget ID', () => {
+    it('ignores snapshot prop that does not match widget ID', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-abc123"
@@ -152,9 +127,10 @@ describe('Snapshot display', () => {
       )
 
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('does not show snapshot for external URLs', () => {
+    it('renders iframe for external URLs regardless of snapshot', () => {
       const { wrapper } = renderInCanvas(
         <PrototypeEmbed
           id="proto-ext"
@@ -171,11 +147,12 @@ describe('Snapshot display', () => {
       )
 
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
   })
 
   describe('StoryWidget', () => {
-    it('shows snapshot image when valid snapshot prop exists', () => {
+    it('renders iframe even when snapshot prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <StoryWidget
           id="story-abc123"
@@ -191,13 +168,11 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-story-abc123.webp')
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('falls back to snapshotDark for backward compat', () => {
+    it('renders iframe when snapshotDark prop is provided', () => {
       const { wrapper } = renderInCanvas(
         <StoryWidget
           id="story-abc123"
@@ -210,50 +185,27 @@ describe('Snapshot display', () => {
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      expect(img.src).toContain('snapshot-story-abc123--dark.webp')
-    })
-
-    it('shows placeholder when no snapshot exists', () => {
-      const { wrapper } = renderInCanvas(
-        <StoryWidget
-          id="story-xyz"
-          props={{
-            storyId: 'button-patterns',
-            exportName: 'Primary',
-            width: 400,
-            height: 300,
-          }}
-          onUpdate={vi.fn()}
-          resizable={false}
-        />
-      )
-
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
-      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
 
-    it('falls back to placeholder when snapshot image fails to load', () => {
+    it('renders iframe when no snapshot exists', () => {
       const { wrapper } = renderInCanvas(
         <StoryWidget
-          id="story-abc123"
+          id="story-xyz"
           props={{
             storyId: 'button-patterns',
             exportName: 'Primary',
             width: 400,
             height: 300,
-            snapshot: '/_storyboard/canvas/images/snapshot-story-abc123.webp?v=456',
           }}
           onUpdate={vi.fn()}
           resizable={false}
         />
       )
 
-      const img = wrapper.querySelector('img')
-      expect(img).toBeInTheDocument()
-      fireEvent.error(img)
       expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).toBeInTheDocument()
     })
   })
 })

package/src/canvas/widgets/useEmbedsPaused.js

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from 'react'
+
+/**
+ * Returns true when embed refreshes are paused globally.
+ * Tracks the `storyboard-embeds-paused` class on <html>.
+ */
+function subscribe(callback) {
+  const observer = new MutationObserver(callback)
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
+  return () => observer.disconnect()
+}
+
+function getSnapshot() {
+  return document.documentElement.classList.contains('storyboard-embeds-paused')
+}
+
+export function useEmbedsPaused() {
+  return useSyncExternalStore(subscribe, getSnapshot, () => false)
+}

package/src/hooks/useConfig.js

@@ -0,0 +1,14 @@
+import { useSyncExternalStore, useCallback } from 'react'
+import { getConfig, subscribeToConfig, getConfigSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * React hook for reading from the unified config store.
+ *
+ * @param {string} [domain] - Optional domain key (e.g. 'toolbar', 'canvas')
+ * @returns {object} The config object (full or domain slice)
+ */
+export function useConfig(domain) {
+  const snapshot = useSyncExternalStore(subscribeToConfig, getConfigSnapshot)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useCallback(() => getConfig(domain), [snapshot, domain])()
+}

package/src/index.js

@@ -25,6 +25,7 @@ export { useUndoRedo } from './hooks/useUndoRedo.js'
 export { useFeatureFlag } from './hooks/useFeatureFlag.js'
 export { useMode } from './hooks/useMode.js'
 export { useThemeState, useThemeSyncTargets } from './hooks/useThemeState.js'
+export { useConfig } from './hooks/useConfig.js'
 
 // React Router integration
 export { installHashPreserver } from './hashPreserver.js'

package/src/vite/data-plugin.js

@@ -526,6 +526,166 @@ function readModesConfig(root) {
   return fallback
 }
 
+/**
+ * Read a JSON/JSONC file, returning null on failure.
+ */
+function readJsonFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8')
+    const errors = []
+    const parsed = parseJsonc(raw, errors)
+    return errors.length === 0 ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Find a core config file from either the monorepo workspace or node_modules.
+ */
+function readCoreConfigFile(root, filename) {
+  const candidates = [
+    path.resolve(root, `packages/core/${filename}`),
+    path.resolve(root, `node_modules/@dfosco/storyboard-core/${filename}`),
+  ]
+  for (const p of candidates) {
+    const parsed = readJsonFile(p)
+    if (parsed) return parsed
+  }
+  return null
+}
+
+/**
+ * Deep-merge helper (same as loader.js deepMerge but available at build time).
+ * Arrays are replaced, not concatenated. Objects are recursively merged.
+ */
+function deepMergeBuild(target, source) {
+  if (!source || typeof source !== 'object') return target
+  if (!target || typeof target !== 'object') return source
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    const sv = source[key]
+    const tv = target[key]
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      result[key] = deepMergeBuild(tv, sv)
+    } else {
+      result[key] = sv
+    }
+  }
+  return result
+}
+
+/**
+ * Build the unified config object by reading and merging all config sources.
+ *
+ * Priority (lowest → highest):
+ *   core defaults → user widgets → user paste → user toolbar → user commandpalette → storyboard.config.json
+ *
+ * Returns { unified, warnings } where warnings is an array of overlap messages.
+ */
+function buildUnifiedConfig(root) {
+  const warnings = []
+
+  // 1. Read core defaults
+  const coreToolbar = readCoreConfigFile(root, 'toolbar.config.json') || {}
+  const coreCommandPalette = readCoreConfigFile(root, 'commandpalette.config.json') || {}
+  const corePaste = readCoreConfigFile(root, 'paste.config.json') || {}
+  const coreWidgets = readCoreConfigFile(root, 'widgets.config.json') || {}
+
+  // 2. Read user config files (priority order)
+  const userFiles = [
+    { domain: 'widgets', filename: 'widgets.config.json', priority: 1 },
+    { domain: 'paste', filename: 'paste.config.json', priority: 2 },
+    { domain: 'toolbar', filename: 'toolbar.config.json', priority: 3 },
+    { domain: 'commandPalette', filename: 'commandpalette.config.json', priority: 4 },
+  ]
+
+  const userConfigs = {}
+  for (const { domain, filename } of userFiles) {
+    const filePath = path.resolve(root, filename)
+    const parsed = readJsonFile(filePath)
+    if (parsed) userConfigs[domain] = { data: parsed, filename }
+  }
+
+  // 3. Read storyboard.config.json (highest priority)
+  // Use the schema-defaulted config for most things, but also read
+  // the raw file to know which keys were explicitly set by the user.
+  const { config: sbConfig } = readConfig(root)
+  const rawSbConfig = readJsonFile(path.resolve(root, 'storyboard.config.json')) || {}
+
+  // 4. Merge core defaults with user overrides per domain
+  const toolbar = userConfigs.toolbar
+    ? deepMergeBuild(coreToolbar, userConfigs.toolbar.data)
+    : coreToolbar
+  const commandPalette = userConfigs.commandPalette
+    ? deepMergeBuild(coreCommandPalette, userConfigs.commandPalette.data)
+    : coreCommandPalette
+  const paste = userConfigs.paste
+    ? deepMergeBuild(corePaste, userConfigs.paste.data)
+    : corePaste
+  const widgets = userConfigs.widgets
+    ? deepMergeBuild(coreWidgets, userConfigs.widgets.data)
+    : coreWidgets
+
+  // 5. Apply storyboard.config.json overrides (highest priority for all domains)
+  // Only merge when the user explicitly defined the key in storyboard.config.json
+  // (not from configSchema defaults, which would overwrite core config with empty arrays).
+  const finalToolbar = rawSbConfig.toolbar
+    ? deepMergeBuild(toolbar, sbConfig.toolbar)
+    : toolbar
+  const finalCommandPalette = rawSbConfig.commandPalette
+    ? deepMergeBuild(commandPalette, sbConfig.commandPalette)
+    : commandPalette
+
+  // 6. Detect overlaps between user config files and storyboard.config.json
+  if (rawSbConfig.toolbar && userConfigs.toolbar) {
+    const overlaps = findOverlappingKeys(userConfigs.toolbar.data, rawSbConfig.toolbar)
+    for (const key of overlaps) {
+      warnings.push(`Config overlap: "${key}" is defined in both toolbar.config.json and storyboard.config.json.toolbar — storyboard.config.json wins.`)
+    }
+  }
+  if (rawSbConfig.commandPalette && userConfigs.commandPalette) {
+    const overlaps = findOverlappingKeys(userConfigs.commandPalette.data, rawSbConfig.commandPalette)
+    for (const key of overlaps) {
+      warnings.push(`Config overlap: "${key}" is defined in both commandpalette.config.json and storyboard.config.json.commandPalette — storyboard.config.json wins.`)
+    }
+  }
+
+  // 7. Build the unified config object
+  const unified = {
+    toolbar: finalToolbar,
+    commandPalette: finalCommandPalette,
+    paste,
+    widgets,
+    featureFlags: sbConfig?.featureFlags || {},
+    modes: sbConfig?.modes || {},
+    ui: sbConfig?.ui || {},
+    canvas: sbConfig?.canvas || {},
+    comments: sbConfig?.comments || {},
+    customerMode: sbConfig?.customerMode || {},
+    plugins: sbConfig?.plugins || {},
+    repository: sbConfig?.repository || {},
+    workshop: sbConfig?.workshop || {},
+  }
+
+  return { unified, warnings }
+}
+
+/**
+ * Find top-level keys that exist in both objects (overlap detection).
+ */
+function findOverlappingKeys(a, b, prefix = '') {
+  const overlaps = []
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return overlaps
+  for (const key of Object.keys(a)) {
+    if (key in b) {
+      const path = prefix ? `${prefix}.${key}` : key
+      overlaps.push(path)
+    }
+  }
+  return overlaps
+}
+
 function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasAliases, canvasGroups, storyRoutes }, root) {
   const declarations = []
   const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder', 'canvas']
@@ -585,18 +745,28 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasA
         parsed = { ...parsed, folder: protoFolders[name] }
       }
 
-      // Load toolbar.config.json from prototype directory if present
+      // Load prototype-level config overrides from the prototype directory.
+      // Any config file placed alongside the .prototype.json becomes an override
+      // for that domain when the prototype is active.
       if (suffix === 'prototype') {
         const protoDir = path.dirname(absPath)
-        const toolbarConfigPath = path.join(protoDir, 'toolbar.config.json')
-        if (fs.existsSync(toolbarConfigPath)) {
-          try {
-            const toolbarRaw = fs.readFileSync(toolbarConfigPath, 'utf-8')
-            const toolbarConfig = parseJsonc(toolbarRaw)
-            if (toolbarConfig) {
-              parsed = { ...parsed, toolbarConfig }
-            }
-          } catch { /* skip invalid toolbar config */ }
+        const protoConfigFiles = [
+          { filename: 'toolbar.config.json', key: 'toolbarConfig' },
+          { filename: 'commandpalette.config.json', key: 'commandPaletteConfig' },
+          { filename: 'widgets.config.json', key: 'widgetsConfig' },
+          { filename: 'paste.config.json', key: 'pasteConfig' },
+        ]
+        for (const { filename, key } of protoConfigFiles) {
+          const cfgPath = path.join(protoDir, filename)
+          if (fs.existsSync(cfgPath)) {
+            try {
+              const raw = fs.readFileSync(cfgPath, 'utf-8')
+              const cfg = parseJsonc(raw)
+              if (cfg) {
+                parsed = { ...parsed, [key]: cfg }
+              }
+            } catch { /* skip invalid config */ }
+          }
         }
       }
 
@@ -694,6 +864,14 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasA
   const imports = [`import { init } from '@dfosco/storyboard-core'`]
   const initCalls = [`init({ flows, objects, records, prototypes, folders, canvases, stories })`]
 
+  // Build unified config from all sources
+  const { unified: unifiedConfig, warnings: configWarnings } = buildUnifiedConfig(root)
+  for (const w of configWarnings) {
+    console.warn(`[storyboard] ⚠ ${w}`)
+  }
+  imports.push(`import { initConfig } from '@dfosco/storyboard-core'`)
+  initCalls.push(`initConfig(${JSON.stringify(unifiedConfig)})`)
+
   // Feature flags from storyboard.config.json
   const { config } = readConfig(root)
   if (config?.featureFlags && Object.keys(config.featureFlags).length > 0) {
@@ -737,6 +915,20 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes, canvasA
     initCalls.push(`initCustomerModeConfig(${JSON.stringify(config.customerMode)})`)
   }
 
+  // Client toolbar overrides from root toolbar.config.json
+  const clientToolbarPath = path.resolve(root, 'toolbar.config.json')
+  try {
+    if (fs.existsSync(clientToolbarPath)) {
+      const raw = fs.readFileSync(clientToolbarPath, 'utf-8')
+      const errors = []
+      const parsed = parseJsonc(raw, errors)
+      if (parsed && errors.length === 0) {
+        imports.push(`import { setClientToolbarOverrides } from '@dfosco/storyboard-core'`)
+        initCalls.push(`setClientToolbarOverrides(${JSON.stringify(parsed)})`)
+      }
+    }
+  } catch { /* skip if unreadable */ }
+
   // Log info when multiple flows target the same route
   const routeGroups = {}
   for (const [name, { route, isDefault }] of Object.entries(resolvedFlowRoutes)) {
@@ -974,8 +1166,21 @@ export default function storyboardDataPlugin() {
           return
         }
 
-        // Invalidate when toolbar.config.json inside a prototype changes
-        if (normalized.endsWith('/toolbar.config.json') && normalized.includes('/prototypes/')) {
+        // Invalidate when any config file inside a prototype changes
+        const protoConfigPattern = /\/(toolbar|commandpalette|widgets|paste)\.config\.json$/
+        if (protoConfigPattern.test(normalized) && normalized.includes('/prototypes/')) {
+          buildResult = null
+          const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
+          if (mod) {
+            server.moduleGraph.invalidateModule(mod)
+            server.ws.send({ type: 'full-reload' })
+          }
+          return
+        }
+
+        // Invalidate when root toolbar.config.json changes
+        if (normalized === path.resolve(root, 'toolbar.config.json').split(path.sep).join('/') ||
+            normalized === path.resolve(root, 'toolbar.config.json')) {
           buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
           if (mod) {
@@ -989,6 +1194,9 @@ export default function storyboardDataPlugin() {
         // Also invalidate when files are added/removed inside .folder/ directories
         const inFolder = normalized.includes('.folder/')
         if (!parsed && !inFolder) return
+        // Source files inside .folder/ dirs (jsx, css, etc.) are handled by
+        // Vite's built-in HMR / React Fast Refresh — don't full-reload for them.
+        if (!parsed && inFolder) return
         // Rebuild index and invalidate virtual module
         buildResult = null
         const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
@@ -1002,6 +1210,9 @@ export default function storyboardDataPlugin() {
         const parsed = parseDataFile(filePath)
         const inFolder = filePath.replace(/\\/g, '/').includes('.folder/')
         if (!parsed && !inFolder) return
+        // Source files (jsx, css, etc.) inside .folder/ dirs are handled by
+        // Vite's built-in HMR — don't trigger a full-reload for them.
+        if (!parsed && inFolder) return
 
         // Canvas writers/editors can emit unlink+add for an in-place save.
         // Treat canvas add/unlink as runtime data updates and never full-reload
@@ -1097,8 +1308,14 @@ export default function storyboardDataPlugin() {
       // Watch storyboard.config.json for changes
       const { configPath } = readConfig(root)
       watcher.add(configPath)
+
+      // Watch root toolbar.config.json for changes
+      const clientToolbarConfigPath = path.resolve(root, 'toolbar.config.json')
+      watcher.add(clientToolbarConfigPath)
+
       const invalidateConfig = (filePath) => {
-        if (path.resolve(filePath) === configPath) {
+        const resolved = path.resolve(filePath)
+        if (resolved === configPath || resolved === clientToolbarConfigPath) {
           buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
           if (mod) {