@dfosco/storyboard 0.9.2 → 0.9.4

package/scaffold/skills/storyboard-widget/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: storyboard-widget
+description: Guide for creating custom canvas widgets — register a React component as a new widget type with full control over chrome (decorated or invisible), interaction switches (selectable / movable / resizable / expandable / split-screen / interact-gate), connector anchors, toolbar features, and prop schemas. Use when asked to create a custom widget, register a widget, add a new canvas widget type, build an invisible/locked/pinned widget, expose a component as a widget, or override a core widget.
+metadata:
+  author: Daniel Fosco
+  version: "2026.6.6"
+---
+
+# Skill: storyboard-widget — Custom Canvas Widget Creation
+
+Creating a new canvas widget type means registering a React component plus a small metadata definition with the storyboard widget registry. The same configuration surface drives the built-in core widgets (sticky-note, image, terminal, etc.) — so anything they can do, your widget can do too.
+
+> **Authoritative reference:** [`DOCS/custom-widgets.md` on GitHub](https://github.com/dfosco/storyboard/blob/main/DOCS/custom-widgets.md). When in doubt, fetch that doc and follow it.
+
+## Triggers
+
+- "create a custom widget", "register a widget", "add a new canvas widget type"
+- "expose this component as a widget", "make X a canvas widget"
+- "build an invisible widget", "build a locked / pinned / decorative widget"
+- "override the sticky note / image / terminal widget"
+- "add custom toolbar actions to a widget"
+- Any prompt mentioning `mountStoryboardCore({ widgets })`, `registerWidget`, or `chrome.enabled`
+
+---
+
+## Decision flow — collect these inputs before writing code
+
+Ask the user (one question per turn — use `ask_user`) until you have all of:
+
+1. **Widget `type` string** — kebab-case, e.g. `kpi-tile`, `code-runner`. This goes into the canvas JSONL and never changes after the first widget instance is saved.
+2. **Display label + icon** — what appears in the `+ Add widget` menu (skip if the widget should be hidden via `unlisted: true`).
+3. **Chrome decision** — three choices:
+   - **Decorated (default)** — wrap in standard WidgetChrome (hover toolbar, anchor ports, select handle, optional gate). Use when the widget should feel like a native storyboard widget.
+   - **Invisible (`chrome.enabled: false`)** — no built-in chrome. Component owns 100 % of the rendered surface. Use for landing-page decorations, brand chrome, fully custom interaction surfaces.
+   - **Decorated but locked** (`chrome.enabled: true` + `interaction.movable: false` and/or `interaction.selectable: false`) — keep the chrome for actions but pin in place / hide select handle.
+4. **Interaction switches** — confirm defaults or override:
+   - `selectable` (default `true`)
+   - `movable` (default `true`)
+   - `resize` (default disabled — pass `{ enabled: true, prod: false }` to enable dev-only resize, `prod: true` for prod too)
+   - `expandable` (default `false`)
+   - `splitScreen` (default `false`)
+   - `interactGate` (default `false`) — when `true`, overlays "Click to interact" until clicked. Use for embedded iframes, third-party components, anything that swallows pointer events you don't want stealing canvas pan/zoom.
+5. **Connectors** — accept all (`accept: ['*']`) or restrict to specific types? Any anchors that should be `disabled` or `unavailable`?
+6. **Toolbar features** — most widgets only need `copy` + `delete` in the overflow menu. Skip for invisible widgets that own their own UI.
+7. **Props schema** — at minimum `width` and `height` (used by the autoplacement engine for default size). Any other persisted state (`text`, `url`, `variant`, etc.) goes here.
+8. **Where to register** — almost always `mountStoryboardCore({ widgets })` in the consumer's main entry. If the user wants per-canvas dynamic registration, use `registerWidget()` instead.
+
+If the user gives you incomplete info, fill in safe defaults and tell them.
+
+---
+
+## Implementation steps
+
+### 1. Create the component file
+
+`src/widgets/<WidgetName>/<WidgetName>.jsx` (follow the project convention — components in their own directory). Use CSS modules for styles.
+
+The component receives these props by the contract:
+
+| Prop | Type |
+|---|---|
+| `id` | `string` — stable widget id |
+| `props` | `object` — current persisted props (matches your `props` schema) |
+| `onUpdate(updates)` | `(object) => void` — patch persisted props |
+| `resizable` | `boolean` |
+| `selected` | `boolean` |
+| `onSelect(shiftKey?)` | `(boolean) => void` |
+| `multiSelected` | `boolean` |
+
+**For invisible widgets (`chrome.enabled: false`):** render your own select affordance when `selected` is true. Otherwise the user can't tell the widget is selected.
+
+**For widgets with custom toolbar features:** wrap the component in `forwardRef` + `useImperativeHandle(ref, () => ({ handleAction(actionId) { ... } }))`. Return `false` to fall through to the default canvas handler; return anything else (or undefined) to claim the action.
+
+### 2. Register at mount
+
+In the consumer's entry (typically `src/main.jsx` or a `_app.jsx` file):
+
+```js
+import { mountStoryboardCore } from '@dfosco/storyboard'
+import storyboardConfig from './storyboard.config.json'
+import MyWidget from './widgets/MyWidget/MyWidget'
+
+mountStoryboardCore(storyboardConfig, {
+  basePath: import.meta.env.BASE_URL || '/',
+  widgets: {
+    'my-widget': {
+      component: MyWidget,
+      label: 'My Widget',
+      icon: 'sparkle-fill',
+      chrome: { enabled: true },
+      interaction: { selectable: true, movable: true },
+      connectors: { anchors: { top: 'available', bottom: 'available', left: 'available', right: 'available' }, accept: ['*'], exclude: [] },
+      features: [
+        { id: 'copy',   type: 'action', action: 'copy',   label: 'Duplicate', icon: 'duplicate', menu: true, prod: true },
+        { id: 'delete', type: 'action', action: 'delete', label: 'Delete',    icon: 'trash',     menu: true, prod: true },
+      ],
+      props: {
+        width:  { type: 'number', label: 'Width',  default: 360 },
+        height: { type: 'number', label: 'Height', default: 240 },
+      },
+    },
+  },
+})
+```
+
+### 3. Register server-side metadata in `storyboard.config.json`
+
+So autoplacement (the `+ Add widget` flow) and collision detection use the right default size:
+
+```json
+{
+  "widgets": {
+    "my-widget": {
+      "label": "My Widget",
+      "props": {
+        "width":  { "type": "number", "default": 360 },
+        "height": { "type": "number", "default": 240 }
+      }
+    }
+  }
+}
+```
+
+**Important:** the browser-side and server-side metadata must agree on default sizes. The server side does not load React components — it only needs the JSON-safe metadata.
+
+### 4. Verify icon exists
+
+Before picking an `icon` value, check that the name exists in `.agents/data/primer-octicons.json` (the authoritative list). Storyboard uses the Primer Octicons set. If your preferred icon doesn't exist, pick the closest available — never guess.
+
+### 5. (Optional) Test the widget
+
+If the consumer wants tests, add `MyWidget.test.jsx` next to the component using Vitest. Focus on:
+
+- Renders without crashing given minimal props
+- `onUpdate` is called with the right patch when user interacts
+- `selected` state triggers any custom selection affordance (for chrome-disabled widgets)
+
+---
+
+## Recipe table — pick the right configuration
+
+| Use case | `chrome.enabled` | `interaction.movable` | `interaction.selectable` | Notes |
+|---|---|---|---|---|
+| Standard widget (markdown-like) | `true` | `true` | `true` | Default — same as core widgets |
+| Resizable rich widget | `true` | `true` | `true` | Add `interaction.resize: { enabled: true, prod: false }` |
+| Iframe / embed | `true` | `true` | `true` | Add `interaction.interactGate: true` to prevent canvas scroll from being swallowed |
+| Hero canvas decoration | `false` | `false` | `false` | Fully custom, no interaction. Combine with `unlisted: true` to hide from menu. |
+| Background sticker (selectable to delete) | `false` | `false` | `true` | Render your own selection ring inside the component |
+| Floating accent (custom UI, draggable) | `false` | `true` | `true` | Component handles its visual chrome; canvas handles drag |
+| Override a core widget (e.g. sticky-note) | match core | match core | match core | **Replaces** the entire built-in definition — re-declare all features/anchors/props if you want them |
+
+---
+
+## Common pitfalls
+
+- **Forgetting server-side metadata** → `+ Add widget` places the widget at the generic 270 × 170 default, not your intended size. Always add the same `widgets.<type>` block to `storyboard.config.json`.
+- **`chrome.enabled: false` without rendering a select affordance** → users can't tell the widget is selected before deleting. Render an outline / ring / handle when `selected` is true.
+- **`movable: false` without `selectable: false`** → user can still select and delete the "locked" widget. That's usually what you want (so they can clean up). Pair both to `false` only for truly immutable decoration.
+- **Overriding a core widget partially** → consumer registrations REPLACE the entire core entry. Copy the baseline from `packages/storyboard/widgets.config.json` first if you want to tweak just one field.
+- **Using the wrong icon name** → check `.agents/data/primer-octicons.json` first. Invented icon names crash the page at runtime.
+- **Not stamping `width`/`height` defaults in the props schema** → collision detection treats unknown widgets as 270 × 170 fallback.
+- **Naming the type with uppercase/spaces** → use kebab-case strings only. The type is a stable identifier persisted in canvas JSONL.
+
+---
+
+## Reference
+
+- Full API reference + TypeScript-flavored type: [`DOCS/custom-widgets.md`](https://github.com/dfosco/storyboard/blob/main/DOCS/custom-widgets.md)
+- Live examples of every feature shape, connector config, prop schema: `node_modules/@dfosco/storyboard/widgets.config.json`
+- Browser-side registry source: `node_modules/@dfosco/storyboard/src/core/stores/widgetRegistry.js`
+- Server-side registry source: `node_modules/@dfosco/storyboard/src/core/canvas/customWidgets.js`
+- Chrome wrapper (consumes per-widget switches): `node_modules/@dfosco/storyboard/src/internals/canvas/widgets/WidgetChrome.jsx`

package/scaffold/skills/tools/SKILL.md

@@ -65,11 +65,11 @@ export async function handler(ctx) {
 
 ### 3. (Optional) Add a custom component
 
-If the default rendering for your render type isn't enough, export a `component()` function:
+If the default rendering for your render type isn't enough, export a `component()` function that returns a React component:
 
 ```js
 export async function component() {
-  const mod = await import('../../MyToolButton.svelte')
+  const mod = await import('../../MyToolButton.jsx')
   return mod.default
 }
 ```
@@ -241,13 +241,13 @@ export async function handler(ctx) {
 }
 ```
 
-#### `component()` → `Promise<SvelteComponent>`
+#### `component()` → `Promise<ReactComponent>`
 
-Optional. Returns a Svelte component to render the tool. If not provided, the surface uses its default renderer (e.g., `TriggerButton` for sidepanels, `ActionMenuButton` for menus).
+Optional. Returns a React component to render the tool. If not provided, the surface uses its default renderer (e.g., `TriggerButton` for sidepanels, `ActionMenuButton` for menus — both shipped with storyboard-core).
 
 ```js
 export async function component() {
-  const mod = await import('../../MyToolButton.svelte')
+  const mod = await import('../../MyToolButton.jsx')
   return mod.default
 }
 ```
@@ -379,7 +379,7 @@ A specialized compound control for canvas zoom (zoom in, zoom out, reset, curren
 
 - **Surface:** `canvas-toolbar`
 - **Handler return:** `{ zoomIn(zoom), zoomOut(zoom), zoomReset(), ZOOM_MIN, ZOOM_MAX }` (min/max read from `canvas.zoom` config)
-- **Component:** Custom Svelte component required
+- **Component:** Custom React component required
 
 ### `link`
 
@@ -472,7 +472,7 @@ export async function guard() {
 }
 
 export async function component() {
-  const mod = await import('../../components/CursorPresence.svelte')
+  const mod = await import('../../components/CursorPresence.jsx')
   return mod.default
 }
 ```
@@ -584,7 +584,7 @@ export async function handler(ctx) {
 }
 
 export async function component() {
-  const mod = await import('../../ActionMenuButton.svelte')
+  const mod = await import('../../ActionMenuButton.jsx')
   return mod.default
 }
 ```
@@ -674,7 +674,7 @@ export async function handler() {
 }
 
 export async function component() {
-  const mod = await import('../../CanvasZoomControl.svelte')
+  const mod = await import('../../CanvasZoomControl.jsx')
   return mod.default
 }
 ```
@@ -776,7 +776,7 @@ export async function guard() {
 }
 
 export async function component() {
-  const mod = await import('../../CommentsMenuButton.svelte')
+  const mod = await import('../../CommentsMenuButton.jsx')
   return mod.default
 }
 ```
@@ -830,7 +830,7 @@ export async function guard(ctx) {
 }
 
 export async function component() {
-  const mod = await import('../../CreateMenuButton.svelte')
+  const mod = await import('../../CreateMenuButton.jsx')
   return mod.default
 }
 ```
@@ -897,7 +897,7 @@ The tool system follows this sequence at startup:
 
 8. COMPONENT RESOLUTION
    If the handler exports component(), it is called to lazy-load
-   the Svelte component. If not exported, the surface uses its
+   the React component. If not exported, the surface uses its
    default component for the render type.
 
 9. SURFACE RENDER

package/src/core/canvas/collision.js

@@ -3,9 +3,13 @@
  *
  * When placing or moving widgets, this module checks for overlaps with
  * existing widgets and adjusts the position until no collisions remain.
+ *
+ * Widget default sizes are resolved from the merged widget registry
+ * (consumer-registered via `storyboard.config.json.widgets` over built-in
+ * `widgets.config.json`) so custom widget types autoplace correctly.
  */
 
-import widgetsConfig from '../../../widgets.config.json' with { type: 'json' }
+import { getServerWidgetDefinition, getAllServerWidgetDefinitions } from './customWidgets.js'
 
 const FALLBACK_SIZE = { width: 270, height: 170 }
 
@@ -20,32 +24,50 @@ const HARDCODED_DEFAULTS = {
   'story': { width: 780, height: 420 },
 }
 
+function resolveDefaultSize(type, def) {
+  const props = def?.props || {}
+  const hardcoded = HARDCODED_DEFAULTS[type]
+  const w = props.width?.default ?? hardcoded?.width ?? FALLBACK_SIZE.width
+  const h = props.height?.default ?? hardcoded?.height ?? FALLBACK_SIZE.height
+  return { width: w, height: h }
+}
+
 /**
- * Default widget sizes derived from widgets.config.json prop defaults,
- * with hardcoded fallbacks for types that don't specify both width+height.
+ * Snapshot of default sizes for all known widget types. Re-resolved on
+ * every access so consumer-registered widget sizes are reflected without
+ * a server restart.
  */
-export const DEFAULT_SIZES = buildDefaultSizes()
-
-function buildDefaultSizes() {
-  const sizes = {}
-  const widgets = widgetsConfig.widgets || {}
-  for (const [type, config] of Object.entries(widgets)) {
-    const props = config.props || {}
-    const hardcoded = HARDCODED_DEFAULTS[type]
-    const w = props.width?.default ?? hardcoded?.width ?? FALLBACK_SIZE.width
-    const h = props.height?.default ?? hardcoded?.height ?? FALLBACK_SIZE.height
-    sizes[type] = { width: w, height: h }
-  }
-  return sizes
-}
+export const DEFAULT_SIZES = new Proxy({}, {
+  get(_, type) {
+    if (typeof type !== 'string') return undefined
+    const def = getServerWidgetDefinition(type)
+    if (!def) return undefined
+    return resolveDefaultSize(type, def)
+  },
+  has(_, type) {
+    return typeof type === 'string' && !!getServerWidgetDefinition(type)
+  },
+  ownKeys() {
+    return Object.keys(getAllServerWidgetDefinitions())
+  },
+  getOwnPropertyDescriptor(_, type) {
+    if (typeof type !== 'string') return undefined
+    const def = getServerWidgetDefinition(type)
+    if (!def) return undefined
+    return { enumerable: true, configurable: true, value: resolveDefaultSize(type, def) }
+  },
+})
 
 /**
- * Get the default size for a widget type from widgets.config.json.
+ * Get the default size for a widget type. Resolves from the merged registry
+ * (consumer-registered widgets override built-ins).
  * @param {string} type - Widget type
  * @returns {{ width: number, height: number }}
  */
 export function getDefaultSize(type) {
-  return DEFAULT_SIZES[type] || FALLBACK_SIZE
+  const def = getServerWidgetDefinition(type)
+  if (!def) return FALLBACK_SIZE
+  return resolveDefaultSize(type, def)
 }
 
 /**

package/src/core/canvas/customWidgets.js

@@ -0,0 +1,92 @@
+/**
+ * Server-side Custom Widget Registry
+ *
+ * Consumer widget metadata loaded from `storyboard.config.json.widgets` at
+ * dev-server startup. Server-side modules (collision detection, widget
+ * placement, prop validation) consult this registry to resolve widget
+ * metadata for consumer-registered widget types.
+ *
+ * Mirrors the browser-side `core/stores/widgetRegistry.js` but holds only
+ * the JSON-serializable subset — no React components (those live in the
+ * browser only). The `definition` shape is otherwise identical:
+ *
+ *   {
+ *     label, icon,
+ *     chrome: { enabled },
+ *     interaction: { selectable, movable, resize, expandable, splitScreen, interactGate, interactGateLabel },
+ *     connectors: { anchors, accept, exclude, defaults },
+ *     features: [...],
+ *     unlisted,
+ *     props: { width: { type, default, ... }, ... }
+ *   }
+ *
+ * Consumer entries OVERRIDE the built-in `widgets.config.json` entry of the
+ * same type. The merge is whole-entry replacement (consumer wins) to match
+ * the browser-side behavior — consumers that want to extend a core widget
+ * must re-declare the merged definition.
+ */
+
+import widgetsConfig from '../../../widgets.config.json' with { type: 'json' }
+
+/** @type {Map<string, object>} */
+const _registry = new Map()
+
+/**
+ * Replace the entire registry from a consumer-supplied map.
+ * @param {Record<string, object>|null|undefined} map
+ */
+export function initServerWidgets(map) {
+  _registry.clear()
+  if (map && typeof map === 'object') {
+    for (const [type, def] of Object.entries(map)) {
+      if (def && typeof def === 'object') {
+        _registry.set(type, def)
+      }
+    }
+  }
+}
+
+/**
+ * Register a single widget type. Replaces any existing entry.
+ * @param {string} type
+ * @param {object} definition
+ */
+export function registerServerWidget(type, definition) {
+  if (!type || typeof type !== 'string') {
+    throw new Error('[storyboard] registerServerWidget: type must be a non-empty string')
+  }
+  if (!definition || typeof definition !== 'object') {
+    throw new Error(`[storyboard] registerServerWidget("${type}"): definition must be an object`)
+  }
+  _registry.set(type, definition)
+}
+
+/**
+ * Resolve the effective server-side widget definition for a type.
+ * Returns the consumer entry if present, otherwise the built-in entry from
+ * `widgets.config.json`, otherwise null.
+ * @param {string} type
+ * @returns {object|null}
+ */
+export function getServerWidgetDefinition(type) {
+  if (_registry.has(type)) return _registry.get(type)
+  return widgetsConfig.widgets?.[type] || null
+}
+
+/**
+ * Snapshot all definitions (consumer + built-in) keyed by type.
+ * Consumer entries override built-ins.
+ * @returns {Record<string, object>}
+ */
+export function getAllServerWidgetDefinitions() {
+  const merged = { ...(widgetsConfig.widgets || {}) }
+  for (const [type, def] of _registry) {
+    merged[type] = def
+  }
+  return merged
+}
+
+/** Reset all state. Only for tests. */
+export function _resetServerWidgets() {
+  _registry.clear()
+}

package/src/core/canvas/customWidgets.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  initServerWidgets,
+  registerServerWidget,
+  getServerWidgetDefinition,
+  getAllServerWidgetDefinitions,
+  _resetServerWidgets,
+} from './customWidgets.js'
+
+describe('customWidgets (server-side registry)', () => {
+  beforeEach(() => {
+    _resetServerWidgets()
+  })
+
+  it('falls back to built-in widgets.config.json when nothing registered', () => {
+    const sticky = getServerWidgetDefinition('sticky-note')
+    expect(sticky).toBeTruthy()
+    expect(sticky.label).toBeTruthy()
+  })
+
+  it('returns null for unknown widget types', () => {
+    expect(getServerWidgetDefinition('does-not-exist')).toBeNull()
+  })
+
+  it('registerServerWidget adds a consumer entry', () => {
+    registerServerWidget('my-thing', { label: 'My Thing', props: { width: { type: 'number', default: 400 } } })
+    const def = getServerWidgetDefinition('my-thing')
+    expect(def?.label).toBe('My Thing')
+    expect(def?.props.width.default).toBe(400)
+  })
+
+  it('consumer entry overrides built-in entry for the same type', () => {
+    registerServerWidget('sticky-note', { label: 'Custom Sticky', props: { width: { default: 999 } } })
+    const def = getServerWidgetDefinition('sticky-note')
+    expect(def.label).toBe('Custom Sticky')
+    expect(def.props.width.default).toBe(999)
+  })
+
+  it('initServerWidgets replaces all consumer entries', () => {
+    registerServerWidget('a', { label: 'A' })
+    initServerWidgets({ b: { label: 'B' } })
+    expect(getServerWidgetDefinition('a')).not.toEqual({ label: 'A' })
+    // 'a' may still resolve to a core entry if one exists; here it doesn't,
+    // so it falls back to null
+    expect(getServerWidgetDefinition('a')).toBeNull()
+    expect(getServerWidgetDefinition('b')).toEqual({ label: 'B' })
+  })
+
+  it('initServerWidgets accepts null/undefined to clear', () => {
+    registerServerWidget('a', { label: 'A' })
+    initServerWidgets(null)
+    expect(getServerWidgetDefinition('a')).toBeNull()
+    initServerWidgets({ x: { label: 'X' } })
+    initServerWidgets(undefined)
+    expect(getServerWidgetDefinition('x')).toBeNull()
+  })
+
+  it('getAllServerWidgetDefinitions includes both built-ins and consumer entries', () => {
+    registerServerWidget('my-thing', { label: 'My Thing' })
+    const all = getAllServerWidgetDefinitions()
+    expect(all['my-thing']?.label).toBe('My Thing')
+    expect(all['sticky-note']).toBeTruthy() // built-in still present
+  })
+
+  it('registerServerWidget throws on invalid input', () => {
+    expect(() => registerServerWidget('', {})).toThrow(/non-empty string/)
+    expect(() => registerServerWidget('foo', null)).toThrow(/must be an object/)
+  })
+})

package/src/core/canvas/server.js

@@ -54,16 +54,17 @@ import {
 import { stampBounds, stampBoundsAll, resolvePosition, getWidgetBounds, findBestAnchors } from './collision.js'
 import { markCanvasWrite, unmarkCanvasWrite } from './writeGuard.js'
 import { devLog } from '../logger/devLogger.js'
-import widgetsConfig from '../../../widgets.config.json' with { type: 'json' }
+import { getServerWidgetDefinition } from './customWidgets.js'
 import { listHubRoles, getDefaultRoleId } from './hub-roles.js'
 import { readAgentsConfig } from './configReader.js'
 
 /**
- * Read the prompt widget's execution config from widgets.config.json.
+ * Read the prompt widget's execution config from the merged widget registry.
  * Returns { default, agents } where each agent has a command template.
  */
 function getPromptExecution() {
-  return widgetsConfig?.widgets?.prompt?.execution || null
+  const def = getServerWidgetDefinition('prompt')
+  return def?.execution || null
 }
 
 /**

package/src/core/index.js

@@ -109,6 +109,19 @@ export {
   getPresentationSnapshot,
 } from './stores/presentationStore.js'
 
+// Custom widgets — public API. Register your own canvas widget types with
+// full control over rendering, chrome, interaction, and toolbar features.
+// See DOCS/custom-widgets.md.
+export {
+  initWidgetRegistry,
+  registerWidget,
+  unregisterWidget,
+  getWidgetDefinition,
+  getAllWidgetDefinitions,
+  subscribeToWidgetRegistry,
+  getWidgetRegistrySnapshot,
+} from './stores/widgetRegistry.js'
+
 // Canvas interaction (advanced, undocumented — scroll axis + zoom gesture gates)
 export {
   initCanvasInteraction,

package/src/core/mountStoryboardCore.js

@@ -16,6 +16,7 @@ import { installBodyClassSync } from './session/bodyClasses.js'
 import { applyEarlyTheme as bootstrapEarlyTheme } from './stores/themeBootstrap.js'
 import { getConfig as getSchemaDefaulted } from './stores/configSchema.js'
 import { initPresentation } from './stores/presentationStore.js'
+import { initWidgetRegistry } from './stores/widgetRegistry.js'
 import { initCanvasInteraction } from './stores/canvasInteractionStore.js'
 import {
   initCommentsConfig, isCommentsEnabled,
@@ -395,6 +396,7 @@ function installCmdClickForwarder() {
  * @param {HTMLElement} [options.container=document.body] - Where to mount devtools
  * @param {Record<string, () => Promise<any>>} [options.handlers={}] - Custom tool handlers (key → lazy loader)
  * @param {Record<string, object>} [options.presentation] - Optional, advanced: per-chrome-element presentation overrides. See `core/stores/presentationStore.js` for the shape. Keep undocumented — power-user surface for landing pages and heavy chrome customization.
+ * @param {Record<string, object>} [options.widgets] - Optional: custom widget registrations. Maps widget type string → WidgetDefinition. Defines the React component, label/icon, chrome wrapper opts, interaction switches (selectable/movable/resize/expandable/splitScreen/interactGate), connector anchors, toolbar features, and prop schema. Consumer entries override built-in widgets of the same type. See `DOCS/custom-widgets.md` and `core/stores/widgetRegistry.js` for the full shape.
  */
 export async function mountStoryboardCore(config = {}, options = {}) {
   if (_mounted) return
@@ -409,6 +411,14 @@ export async function mountStoryboardCore(config = {}, options = {}) {
     initPresentation(options.presentation)
   }
 
+  // Seed the widget registry before any canvas mounts so the first canvas
+  // render already resolves custom widget components, chrome opts, and
+  // interaction switches. Consumer entries override core widgets of the
+  // same type entirely.
+  if (options.widgets) {
+    initWidgetRegistry(options.widgets)
+  }
+
   // Migrate renamed localStorage keys (4.3.0: viewfinder → workspace)
   migrateLocalStorageKeys()
 

package/src/core/stores/configSchema.js

@@ -164,7 +164,8 @@
  * @property {HotPoolConfig} [hotPool]
  * @property {CommandPaletteConfig} [commandPalette]
  * @property {CustomerModeConfig} [customerMode]
- * @property {ThemesConfig} [themes]
+ * @property {ThemesConfig} [theming]
+ * @property {Record<string, object>} [widgets] — Custom widget metadata (server-side). Maps widget type string → definition (label, icon, chrome, interaction, connectors, features, props). Consumer entries override built-in widget metadata for collision detection, default sizes, prompt-exec config, etc. Browser-side widget components are registered separately via `mountStoryboardCore({ widgets })`. See `DOCS/custom-widgets.md`.
  */
 
 /** Built-in paste rules shipped with storyboard. */