@dfosco/storyboard 0.9.2 → 0.9.4

package/src/internals/canvas/widgets/index.js

@@ -11,10 +11,14 @@ import TerminalWidget from './TerminalWidget.jsx'
 import TerminalReadWidget from './TerminalReadWidget.jsx'
 import PromptWidget from './PromptWidget.jsx'
 import TilesWidget from './TilesWidget.jsx'
+import { getWidgetDefinition } from '../../../core/stores/widgetRegistry.js'
 
 /**
- * Maps widget type strings to their React components.
- * Each component receives: { id, props, onUpdate }
+ * Built-in widget components, keyed by type string.
+ * These are the fallback components when no consumer registration overrides
+ * a given type. Consumers can override any of these by registering a widget
+ * with the same `type` key via `mountStoryboardCore({ widgets })` or
+ * `registerWidget()`.
  */
 export const widgetRegistry = {
   'sticky-note': StickyNote,
@@ -34,9 +38,19 @@ export const widgetRegistry = {
 }
 
 /**
- * Resolve a widget type string to its component.
- * Returns null for unknown types.
+ * Resolve a widget type string to its React component.
+ *
+ * Lookup order:
+ *   1. Consumer registry (`registerWidget`/`mountStoryboardCore({ widgets })`)
+ *      — `def.component` wins if present
+ *   2. Built-in `widgetRegistry` above
+ *   3. null (unknown type)
+ *
+ * @param {string} type
+ * @returns {React.ComponentType | null}
  */
 export function getWidgetComponent(type) {
+  const def = getWidgetDefinition(type)
+  if (def?.component) return def.component
   return widgetRegistry[type] ?? null
 }

package/src/internals/canvas/widgets/widgetConfig.js

@@ -1,16 +1,27 @@
 /**
  * Widget Config Loader
  *
- * Reads widgets.config.json from @dfosco/storyboard and builds
- * schema objects compatible with the existing readProp/readAllProps/getDefaults API.
+ * Resolves per-widget metadata (label, icon, prop schemas, features, chrome
+ * options, interaction switches, connector rules) by merging the built-in
+ * `widgets.config.json` baseline with consumer registrations from
+ * `core/stores/widgetRegistry.js`.
  *
- * The config is the single source of truth for widget definitions —
- * prop schemas, feature lists, labels, and icons all come from here.
+ * Resolution order, per widget type:
+ *   1. Consumer override registered via `registerWidget()` /
+ *      `mountStoryboardCore({ widgets })` — REPLACES the core entry entirely
+ *      for this type. Consumers that want to extend a core widget must
+ *      re-declare the full merged definition.
+ *   2. Core entry from `widgets.config.json`.
  *
- * Supports `$variable` references in string values, resolved from
- * the top-level `variables` object in widgets.config.json.
+ * Supports `$variable` references in string values for core widgets only,
+ * resolved from the top-level `variables` object in `widgets.config.json`.
+ * (Consumer registrations are passed through verbatim.)
  */
 import widgetsConfig from '../../../../widgets.config.json'
+import {
+  getWidgetDefinition,
+  getAllWidgetDefinitions,
+} from '../../../core/stores/widgetRegistry.js'
 
 /** Variables defined in config — used to resolve `$key` references. */
 const variables = widgetsConfig.variables || {}
@@ -80,40 +91,178 @@ function configPropToSchema(propDef) {
 }
 
 /**
- * Build schema objects for all widget types from the config.
- * Returns the same shape as the old hardcoded schemas in widgetProps.js.
+ * Resolve the effective definition for a widget type.
+ * Consumer registry replaces the core entry entirely; consumers that need
+ * to extend a core widget should re-declare the merged definition.
+ *
+ * Features are NOT pre-resolved through `resolveFeature` for consumer
+ * entries — consumers are expected to pass plain values rather than
+ * `$label:foo` references, which are an internal storyboard.json idiom.
+ *
+ * @param {string} type
+ * @returns {object|null} The full widget definition with resolved features, or null
  */
-function buildSchemas() {
-  const result = {}
-  for (const [type, def] of Object.entries(widgetsConfig.widgets)) {
-    const schema = {}
-    for (const [key, propDef] of Object.entries(def.props || {})) {
-      schema[key] = configPropToSchema(propDef)
+function resolveDefinition(type) {
+  const consumer = getWidgetDefinition(type)
+  if (consumer) {
+    return {
+      ...consumer,
+      features: (consumer.features || []).map(resolveFeature),
     }
-    result[type] = schema
   }
-  return result
+  const core = widgetsConfig.widgets[type]
+  if (!core) return null
+  return {
+    ...core,
+    features: (core.features || []).map(resolveFeature),
+  }
 }
 
 /**
- * Build resolved widget type entries with variables expanded in features.
+ * Resolve schema (prop shape) for a widget type. Reads from the merged
+ * definition (consumer over core).
+ * @param {string} type
+ * @returns {Record<string, object>}
  */
-function buildWidgetTypes() {
+function resolveSchema(type) {
+  const def = resolveDefinition(type) || consumerOrCorePropsOnly(type)
+  if (!def?.props) return {}
+  const schema = {}
+  for (const [key, propDef] of Object.entries(def.props)) {
+    schema[key] = configPropToSchema(propDef)
+  }
+  return schema
+}
+
+// Fallback for resolveSchema when the registry has a partial entry that
+// lacks `props` — read from core so widgetProps' readProp helpers still work.
+function consumerOrCorePropsOnly(type) {
+  const consumer = getWidgetDefinition(type)
+  if (consumer?.props) return consumer
+  return widgetsConfig.widgets[type] || null
+}
+
+function getAllTypes() {
+  // Set ensures consumer-only types AND core types are both included
+  return new Set([
+    ...Object.keys(widgetsConfig.widgets),
+    ...Object.keys(getAllWidgetDefinitions()),
+  ])
+}
+
+/** All widget schemas, keyed by type string. Reactive: re-resolved on each access. */
+export const schemas = new Proxy({}, {
+  get(_, type) {
+    if (typeof type !== 'string') return undefined
+    return resolveSchema(type)
+  },
+  has(_, type) {
+    return typeof type === 'string' && (
+      !!widgetsConfig.widgets[type] || !!getWidgetDefinition(type)
+    )
+  },
+  ownKeys() {
+    return [...getAllTypes()]
+  },
+  getOwnPropertyDescriptor(_, type) {
+    if (typeof type !== 'string') return undefined
+    if (!widgetsConfig.widgets[type] && !getWidgetDefinition(type)) return undefined
+    return { enumerable: true, configurable: true, value: resolveSchema(type) }
+  },
+})
+
+/**
+ * Snapshot of all widget definitions with features resolved.
+ * Reactive helper kept for tests and tooling — prefer the typed getters below
+ * for runtime code.
+ */
+export function widgetTypesSnapshot() {
   const result = {}
-  for (const [type, def] of Object.entries(widgetsConfig.widgets)) {
-    result[type] = {
-      ...def,
-      features: (def.features || []).map(resolveFeature),
-    }
+  for (const type of getAllTypes()) {
+    const def = resolveDefinition(type)
+    if (def) result[type] = def
   }
   return result
 }
 
-/** All widget schemas, keyed by type string. */
-export const schemas = buildSchemas()
+/**
+ * Back-compat: a Proxy that behaves like the previous `widgetTypes` constant.
+ * Reads are live (consumer overrides win at access time).
+ */
+export const widgetTypes = new Proxy({}, {
+  get(_, type) {
+    if (typeof type !== 'string') return undefined
+    return resolveDefinition(type) || undefined
+  },
+  has(_, type) {
+    return typeof type === 'string' && (
+      !!widgetsConfig.widgets[type] || !!getWidgetDefinition(type)
+    )
+  },
+  ownKeys() {
+    return [...getAllTypes()]
+  },
+  getOwnPropertyDescriptor(_, type) {
+    if (typeof type !== 'string') return undefined
+    const def = resolveDefinition(type)
+    if (!def) return undefined
+    return { enumerable: true, configurable: true, value: def }
+  },
+})
 
-/** Full widget config entries (with resolved variables), keyed by type string. */
-export const widgetTypes = buildWidgetTypes()
+// ── Helpers to read the new `interaction` / `chrome` sub-blocks with
+// back-compat fallback to the legacy top-level keys used by widgets.config.json.
+
+function readInteraction(def) {
+  if (!def) return null
+  const i = def.interaction || {}
+  return {
+    selectable: i.selectable !== false,                    // default true
+    movable: i.movable !== false,                          // default true
+    resize: i.resize ?? def.resize ?? null,
+    expandable: i.expandable ?? def.expandable ?? false,
+    splitScreen: i.splitScreen ?? def.splitScreen ?? false,
+    interactGate: i.interactGate ?? def.interactGate ?? false,
+    interactGateLabel: i.interactGateLabel ?? def.interactGateLabel ?? 'Click to interact',
+  }
+}
+
+function readChrome(def) {
+  if (!def) return { enabled: true }
+  const c = def.chrome || {}
+  return {
+    enabled: c.enabled !== false,                          // default true
+  }
+}
+
+/**
+ * Get the chrome options for a widget type (used by CanvasPage to decide
+ * whether to wrap the widget in WidgetChrome at all).
+ * @param {string} type
+ * @returns {{ enabled: boolean }}
+ */
+export function getChromeOptions(type) {
+  return readChrome(resolveDefinition(type))
+}
+
+/**
+ * Get the per-widget interaction switches (selectable, movable, resize,
+ * expandable, splitScreen, interactGate). Merges new `interaction.*`
+ * sub-block over legacy top-level keys.
+ * @param {string} type
+ * @returns {{ selectable, movable, resize, expandable, splitScreen, interactGate, interactGateLabel }}
+ */
+export function getInteractionOptions(type) {
+  return readInteraction(resolveDefinition(type)) || {
+    selectable: true,
+    movable: true,
+    resize: null,
+    expandable: false,
+    splitScreen: false,
+    interactGate: false,
+    interactGateLabel: 'Click to interact',
+  }
+}
 
 /**
  * Get the feature list for a widget type.
@@ -130,7 +279,7 @@ export const widgetTypes = buildWidgetTypes()
  * @returns {Array} features array from config (variables resolved), or empty array
  */
 export function getFeatures(type, { isLocalDev = true } = {}) {
-  const features = widgetTypes[type]?.features ?? []
+  const features = resolveDefinition(type)?.features ?? []
   let filtered = features.filter(f => {
     const surfaces = f.surfaces || ['toolbar']
     return surfaces.includes('toolbar')
@@ -150,7 +299,7 @@ export function getFeatures(type, { isLocalDev = true } = {}) {
  * @returns {Array} filtered features for the given surface
  */
 export function getFeaturesForSurface(type, surface, { isLocalDev = true } = {}) {
-  let features = widgetTypes[type]?.features ?? []
+  let features = resolveDefinition(type)?.features ?? []
   if (import.meta.env?.PROD || !isLocalDev) {
     features = features.filter(f => f.prod)
   }
@@ -163,11 +312,12 @@ export function getFeaturesForSurface(type, surface, { isLocalDev = true } = {})
 /**
  * Check if a widget type supports resize in the current environment.
  * Returns false if resize is disabled, or if in production and prod is not true.
+ * Reads from `interaction.resize` (preferred) or legacy top-level `resize`.
  * @param {string} type — widget type string
  * @returns {boolean}
  */
 export function isResizable(type) {
-  const resize = widgetTypes[type]?.resize
+  const resize = getInteractionOptions(type).resize
   if (!resize?.enabled) return false
   if (import.meta.env?.PROD && !resize.prod) return false
   return true
@@ -179,50 +329,57 @@ export function isResizable(type) {
  * @returns {{ label: string, icon: string } | null}
  */
 export function getWidgetMeta(type) {
-  const def = widgetTypes[type]
+  const def = resolveDefinition(type)
   if (!def) return null
   return { label: def.label, icon: def.icon }
 }
 
 /**
  * Check if a widget type supports expanding to a full-screen modal.
+ * Reads from `interaction.expandable` (preferred) or legacy top-level.
  * @param {string} type — widget type string
  * @returns {boolean}
  */
 export function isExpandable(type) {
-  return widgetTypes[type]?.expandable === true
+  return getInteractionOptions(type).expandable === true
 }
 
 /**
  * Check if a widget type can appear in a split-screen pane.
+ * Reads from `interaction.splitScreen` (preferred) or legacy top-level.
  * @param {string} type — widget type string
  * @returns {boolean}
  */
 export function isSplitScreenCapable(type) {
-  return widgetTypes[type]?.splitScreen === true
+  return getInteractionOptions(type).splitScreen === true
 }
 
 /**
  * Get the interact gate config for a widget type.
- * @returns {{ enabled: boolean, label: string }} 
+ * Reads from `interaction.interactGate` (preferred) or legacy top-level.
+ * @returns {{ enabled: boolean, label: string }}
  */
 export function getInteractGate(type) {
-  const def = widgetTypes[type]
-  if (!def || !def.interactGate) return { enabled: false, label: 'Click to interact' }
-  return {
-    enabled: true,
-    label: def.interactGateLabel || 'Click to interact',
-  }
+  const i = getInteractionOptions(type)
+  if (!i.interactGate) return { enabled: false, label: i.interactGateLabel || 'Click to interact' }
+  return { enabled: true, label: i.interactGateLabel || 'Click to interact' }
 }
 
 /**
  * Get all widget types as an array of { type, label, icon } for menus.
- * Excludes link-preview, image, and figma-embed which are created via paste only.
+ * Excludes hidden core widgets (created via paste only) and any widget with
+ * `unlisted: true` (consumer- or core-side).
  */
 export function getMenuWidgetTypes() {
-  return Object.entries(widgetTypes)
-    .filter(([type, def]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed' && type !== 'codepen-embed' && type !== 'story' && type !== 'terminal-read' && !def.unlisted)
-    .map(([type, def]) => ({ type, label: def.label, icon: def.icon }))
+  const hidden = new Set(['link-preview', 'image', 'figma-embed', 'codepen-embed', 'story', 'terminal-read'])
+  const out = []
+  for (const type of getAllTypes()) {
+    if (hidden.has(type)) continue
+    const def = resolveDefinition(type)
+    if (!def || def.unlisted) continue
+    out.push({ type, label: def.label, icon: def.icon })
+  }
+  return out
 }
 
 /**
@@ -231,7 +388,7 @@ export function getMenuWidgetTypes() {
  * @returns {{ anchors: Record<string, string>, accept: string[], exclude: string[], defaults: Object|undefined }}
  */
 export function getConnectorConfig(type) {
-  const def = widgetTypes[type]?.connectors
+  const def = resolveDefinition(type)?.connectors
   return {
     anchors: def?.anchors ?? { top: 'available', bottom: 'available', left: 'available', right: 'available' },
     accept: def?.accept ?? ['*'],

package/src/internals/canvas/widgets/widgetConfig.merged.test.js

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import {
+  registerWidget,
+  _resetWidgetRegistry,
+} from '../../../core/stores/widgetRegistry.js'
+import {
+  getWidgetMeta,
+  isResizable,
+  isExpandable,
+  isSplitScreenCapable,
+  getInteractGate,
+  getMenuWidgetTypes,
+  getChromeOptions,
+  getInteractionOptions,
+  getFeatures,
+  getConnectorConfig,
+  schemas,
+} from './widgetConfig.js'
+
+describe('widgetConfig — merged consumer + built-in registry', () => {
+  beforeEach(() => {
+    _resetWidgetRegistry()
+  })
+
+  it('falls back to built-in widgets when nothing registered', () => {
+    expect(getWidgetMeta('sticky-note')?.label).toBeTruthy()
+    expect(getChromeOptions('sticky-note').enabled).toBe(true)
+    expect(getInteractionOptions('sticky-note').selectable).toBe(true)
+    expect(getInteractionOptions('sticky-note').movable).toBe(true)
+  })
+
+  it('consumer-registered widget exposes label/icon via getWidgetMeta', () => {
+    registerWidget('my-thing', { label: 'My Thing', icon: 'sparkle-fill' })
+    expect(getWidgetMeta('my-thing')).toEqual({ label: 'My Thing', icon: 'sparkle-fill' })
+  })
+
+  it('chrome.enabled defaults to true, overrideable to false', () => {
+    registerWidget('invisible', { label: 'Invisible', chrome: { enabled: false } })
+    expect(getChromeOptions('invisible').enabled).toBe(false)
+    registerWidget('visible', { label: 'Visible', chrome: { enabled: true } })
+    expect(getChromeOptions('visible').enabled).toBe(true)
+    registerWidget('default', { label: 'Default' })
+    expect(getChromeOptions('default').enabled).toBe(true)
+  })
+
+  it('interaction.selectable/movable default to true, overrideable to false', () => {
+    registerWidget('pinned', { label: 'Pinned', interaction: { movable: false } })
+    expect(getInteractionOptions('pinned').movable).toBe(false)
+    expect(getInteractionOptions('pinned').selectable).toBe(true)
+
+    registerWidget('decorative', { label: 'Deco', interaction: { selectable: false } })
+    expect(getInteractionOptions('decorative').selectable).toBe(false)
+    expect(getInteractionOptions('decorative').movable).toBe(true)
+  })
+
+  it('interaction.resize/expandable/splitScreen flow through to legacy getters', () => {
+    registerWidget('big', {
+      label: 'Big',
+      interaction: {
+        resize: { enabled: true, prod: true },
+        expandable: true,
+        splitScreen: true,
+        interactGate: true,
+        interactGateLabel: 'Tap to interact',
+      },
+    })
+    expect(isResizable('big')).toBe(true)
+    expect(isExpandable('big')).toBe(true)
+    expect(isSplitScreenCapable('big')).toBe(true)
+    expect(getInteractGate('big')).toEqual({ enabled: true, label: 'Tap to interact' })
+  })
+
+  it('legacy top-level keys still work as back-compat (widgets.config.json shape)', () => {
+    // No nested `interaction` block — the widgets.config.json baseline
+    // should keep working when consumer omits the block.
+    registerWidget('legacy', {
+      label: 'Legacy',
+      resize: { enabled: true, prod: false },
+      expandable: true,
+      splitScreen: true,
+      interactGate: true,
+      interactGateLabel: 'Old gate',
+    })
+    expect(isResizable('legacy')).toBe(true)
+    expect(isExpandable('legacy')).toBe(true)
+    expect(isSplitScreenCapable('legacy')).toBe(true)
+    expect(getInteractGate('legacy').enabled).toBe(true)
+    expect(getInteractGate('legacy').label).toBe('Old gate')
+  })
+
+  it('getMenuWidgetTypes includes consumer entries and excludes unlisted', () => {
+    registerWidget('shown', { label: 'Shown', icon: 'star' })
+    registerWidget('hidden', { label: 'Hidden', unlisted: true })
+    const types = getMenuWidgetTypes()
+    expect(types.some((t) => t.type === 'shown')).toBe(true)
+    expect(types.some((t) => t.type === 'hidden')).toBe(false)
+  })
+
+  it('consumer features flow through getFeatures', () => {
+    registerWidget('withFeat', {
+      label: 'With',
+      features: [
+        { id: 'foo', type: 'action', action: 'foo', label: 'Foo', icon: 'star', prod: true },
+      ],
+    })
+    const feats = getFeatures('withFeat', { isLocalDev: true })
+    expect(feats.length).toBe(1)
+    expect(feats[0].action).toBe('foo')
+  })
+
+  it('consumer connector config flows through getConnectorConfig', () => {
+    registerWidget('lockedConn', {
+      label: 'Locked',
+      connectors: { anchors: { top: 'unavailable', bottom: 'disabled', left: 'available', right: 'available' }, accept: ['sticky-note'] },
+    })
+    const cfg = getConnectorConfig('lockedConn')
+    expect(cfg.anchors.top).toBe('unavailable')
+    expect(cfg.anchors.bottom).toBe('disabled')
+    expect(cfg.accept).toEqual(['sticky-note'])
+  })
+
+  it('consumer schemas are exposed via the schemas proxy', () => {
+    registerWidget('withProps', {
+      label: 'WithProps',
+      props: {
+        title: { type: 'text', label: 'Title', default: 'Hi' },
+        width: { type: 'number', label: 'Width', default: 320 },
+      },
+    })
+    expect(schemas['withProps']).toEqual({
+      title: { type: 'text', label: 'Title', category: undefined, defaultValue: 'Hi' },
+      width: { type: 'number', label: 'Width', category: undefined, defaultValue: 320 },
+    })
+  })
+
+  it('consumer registration overrides core widget for same type', () => {
+    // sticky-note is movable by default
+    expect(getInteractionOptions('sticky-note').movable).toBe(true)
+    registerWidget('sticky-note', { label: 'Sticky', interaction: { movable: false } })
+    expect(getInteractionOptions('sticky-note').movable).toBe(false)
+    // After unregister via re-init the core entry returns
+    vi.clearAllMocks()
+  })
+})

package/src/internals/context.jsx

@@ -2,7 +2,7 @@ import { useState, useEffect, useMemo, useRef, Suspense, lazy, Component } from
 import { useParams, useLocation } from 'react-router-dom'
 // Named import seeds the core data index via init() AND provides canvas/story route data
 import { canvases, stories } from 'virtual:storyboard-data-index'
-import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, isModesEnabled, getPrototypeMetadata } from '../core/index.js'
+import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, getPrototypeMetadata } from '../core/index.js'
 import { StoryboardContext } from './StoryboardContext.js'
 import usePrototypeReloadGuard from './hooks/usePrototypeReloadGuard.js'
 import styles from './FlowError.module.css'
@@ -336,22 +336,6 @@ function StoryboardProviderInner({ flowName, sceneName, recordName, recordParam,
     document.title = title + branchSuffix
   }, [canvasId, prototypeName])
 
-  // Mount design modes UI when enabled in storyboard.config.json
-  useEffect(() => {
-    if (!isModesEnabled()) return
-
-    let cleanup
-    import('@dfosco/storyboard/ui-runtime')
-      .then(({ mountDesignModes }) => {
-        cleanup = mountDesignModes()
-      })
-      .catch(() => {
-        // UI not available — degrade gracefully
-      })
-
-    return () => cleanup?.()
-  }, [])
-
   // Skip flow loading for canvas/story pages and flow-less pages
   const { data, error, flowTokens } = useMemo(() => {
     if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null, flowTokens: null }

package/src/core/ui/design-modes.ts

@@ -1,7 +0,0 @@
-/**
- * Design modes UI mount — stub (Svelte UI removed).
- * These functions are no-ops. Mode switching is handled by React components.
- */
-
-export function mountDesignModesUI() {}
-export function unmountDesignModesUI() {}

package/src/core/ui/viewfinder.ts

@@ -1,7 +0,0 @@
-/**
- * Viewfinder mount — stub (Svelte UI removed).
- * These functions are no-ops. The viewfinder is rendered by React.
- */
-
-export function mountViewfinder() {}
-export function unmountViewfinder() {}

package/src/core/workshop/ui/mount.ts

@@ -1,6 +0,0 @@
-/**
- * Workshop panel mount — stub (Svelte UI removed).
- */
-
-export function mountWorkshopPanel() {}
-export function unmountWorkshopPanel() {}