@dfosco/storyboard 0.9.3 → 0.9.5

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

@@ -13,200 +13,91 @@ Guide for adding new menu buttons to the storyboard CoreUIBar — the floating t
 
 ## Overview
 
-The CoreUIBar is a config-driven floating toolbar rendered by `packages/core/src/CoreUIBar.svelte`. All buttons are defined in `packages/core/toolbar.config.json` under the `menus` key. The toolbar reads this config at startup, filters menus by the current mode, and renders buttons in JSON key order (reversed, so top = rightmost after the command menu).
+The CoreUIBar is a config-driven floating React toolbar rendered by `packages/storyboard/src/core/ui/CoreUIBar.jsx`. All buttons are defined in `packages/storyboard/toolbar.config.json` under the `tools` key. The toolbar reads this config at startup, filters tools by the current mode and surface, and renders them in JSON key order.
+
+> **For the full how-to (config schema, render types, handler module interface, surface reference, recipes, registration of custom client handlers via `mountStoryboardCore({ handlers })`), see the canonical [`storyboard-tools`](../storyboard-tools/SKILL.md) skill.** This skill keeps only what's specific to working **inside** storyboard-core itself.
 
 ## Architecture
 
 ```
-toolbar.config.json          ← Menu declarations (icon, modes, behavior)
+toolbar.config.json                            ← Tool declarations
     ↓
-CoreUIBar.svelte              ← Reads config, renders buttons via {#each}
+packages/storyboard/src/core/ui/CoreUIBar.jsx  ← React; reads config, mounts tools
     ↓
-├── TriggerButton + Icon      ← Sidepanel buttons (docs, inspector)
-├── ActionMenuButton.svelte   ← Generic action-driven dropdown (config "action" key)
-├── CreateMenuButton.svelte   ← Workshop feature launcher (config "actions" + registry)
-├── CommentsMenuButton.svelte ← Auth-aware comments toggle
-└── CommandMenu.svelte        ← Always rightmost, special handling
-```
-
-## Menu Button Types
-
-There are three patterns, from simplest to most custom:
-
-### 1. Sidepanel button (config-only, no component)
-
-For buttons that toggle a side panel. Just add a config entry — no Svelte component needed.
-
-```json
-"docs": {
-  "ariaLabel": "Documentation",
-  "icon": "primer/book",
-  "modes": ["*"],
-  "sidepanel": "docs"
-}
-```
-
-### 2. Action menu button (config + registered action handler)
-
-**This is the preferred pattern for new dynamic menus.** The config declares an `"action"` key pointing to a command action ID. CoreUIBar registers the handler in `onMount`. The generic `ActionMenuButton.svelte` renders the items.
-
-```json
-"flows": {
-  "label": "Flows",
-  "ariaLabel": "Switch flow",
-  "icon": "feather/fast-forward",
-  "modes": ["*"],
-  "action": "core/flows"
-}
-```
-
-The handler is registered in CoreUIBar's `onMount`:
-
-```ts
-registerCommandAction('core/flows', {
-  getChildren: () => {
-    // return array of { id, label, type, active?, execute }
-    return items.map(item => ({
-      id: item.key,
-      label: item.title,
-      type: 'radio',       // or 'default', 'toggle'
-      active: item.isActive,
-      execute: () => { /* action */ },
-    }))
-  },
-})
-```
-
-**Supported child types:** `default` (plain item), `toggle` (checkbox), `radio` (radio group with check indicator).
-
-The button auto-hides when `getChildren()` returns an empty array.
-
-### 3. Custom component (for complex UI that doesn't fit action items)
-
-Only use when the menu needs UI beyond what action items support (e.g., auth flows, overlay panels, feature registries). Must still be declared in config and dynamically imported.
-
-```json
-"comments": {
-  "ariaLabel": "Comments",
-  "icon": "primer/comment",
-  "modes": ["*"]
-}
-```
-
-## Adding a New Menu Button
-
-### Step 1: Add config entry
-
-Add an entry to `packages/core/toolbar.config.json` under `menus`. The key order determines position (top = leftmost, bottom = rightmost before command menu).
-
-### Config field reference
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `ariaLabel` | yes | Accessible label, also shown in tooltip |
-| `icon` | yes | Namespaced icon name (see Icon section) |
-| `modes` | yes | Array of mode names or `["*"]` for all modes |
-| `action` | no | Command action ID — renders via generic `ActionMenuButton.svelte` (preferred for dynamic menus) |
-| `meta` | no | Passed as props to `<Icon>` (e.g. `{ "strokeWeight": 2, "scale": 1.1 }`) |
-| `sidepanel` | no | If set, button toggles this side panel tab (no custom component needed) |
-| `label` | no | Display label (used in dropdown headers) |
-| `actions` | no | Array of static action items with `feature` references (used by create menu) |
-| `excludeRoutes` | no | Array of route patterns where this menu is hidden |
-
-### Step 2: Register the action handler (for action menus)
-
-In `CoreUIBar.svelte`'s `onMount`, register a handler for your action ID:
-
-```ts
-registerCommandAction('core/my-feature', {
-  getChildren: () => {
-    // Compute items dynamically based on current state
-    return items.map(item => ({
-      id: item.key,
-      label: item.title,
-      type: 'radio',       // 'default', 'toggle', or 'radio'
-      active: item.isActive, // for radio/toggle: marks the selected item
-      execute: () => { /* what happens on click */ },
-    }))
-  },
-})
-```
-
-**That's it.** The generic `ActionMenuButton.svelte` handles all rendering. It:
-- Reads children from the action registry via `getActionChildren()`
-- Renders `RadioGroup` for `radio` type, `CheckboxItem` for `toggle`, `Item` for `default`
-- Auto-hides when `getChildren()` returns an empty array
-- Refreshes items on each open via `onOpenChange`
-
-### Step 3 (only for custom components): Wire into CoreUIBar.svelte
-
-Only needed when the action system can't express the UI you need (auth flows, overlay panels, etc.).
-
-**1. Add state variable:**
-
-```ts
-let MyFeatureButton: any = $state(null)
-```
-
-**2. Add visibility filter in `visibleMenus`:**
-
-```ts
-if (menu.key === 'my-feature') return !!MyFeatureButton
-```
-
-**3. Dynamic import in `onMount`:**
-
-```ts
-try {
-  const mod = await import('./MyFeatureButton.svelte')
-  MyFeatureButton = mod.default
-} catch {}
-```
-
-**4. Rendering branch in template:**
-
-```svelte
-{:else if menu.key === 'my-feature'}
-  <MyFeatureButton config={menu} {basePath} tabindex={getTabindex(i)} />
+packages/storyboard/src/core/tools/
+├── registry.js                                ← Core handler module map (core:* prefix)
+├── handlers/<name>.js                         ← One per built-in tool (flows, theme, …)
+└── surfaces/                                  ← Per-surface render orchestration
+    ↓
+React renderers in core/ui/ (TriggerButton, ActionMenuButton, CommandMenu, …)
+or the custom React component returned by the handler's component() export.
 ```
 
-### Important: Data index timing
-
-The storyboard data index (`virtual:storyboard-data-index`) is seeded by the React app, which initializes *after* the Svelte CoreUIBar mounts. If your handler reads from the data index (flows, objects, records), the action registry handles this naturally — `getChildren()` is called lazily when the menu opens, not at registration time.
+The handler module interface — `id`, `guard(ctx)`, `setup(ctx)`, `handler(ctx)`, `component()` — is documented in [`storyboard-tools/SKILL.md`](../storyboard-tools/SKILL.md#handler-module-interface) and is identical for core (`core:*`) and consumer (`custom:*`) handlers.
+
+## Adding a built-in tool to storyboard-core
+
+1. **Add the config entry** to `packages/storyboard/toolbar.config.json` under `tools`. See the [config reference](../storyboard-tools/SKILL.md#config-reference) for required fields.
+2. **Create the handler module** at `packages/storyboard/src/core/tools/handlers/<name>.js`. Export at minimum `id`. Add `guard`, `setup`, `handler`, and/or `component` as needed for the render type.
+3. **Register the lazy loader** in `packages/storyboard/src/core/tools/registry.js`:
+   ```js
+   export const coreHandlers = {
+     // …
+     'my-tool': () => import('./handlers/myTool.js'),
+   }
+   ```
+4. **(Custom React component, optional)** If you need a custom component instead of the default `TriggerButton` / `ActionMenuButton` renderer, drop the `.jsx` file in `packages/storyboard/src/core/ui/` and lazy-import it from `component()`:
+   ```js
+   export async function component() {
+     const mod = await import('../../ui/MyToolButton.jsx')
+     return mod.default
+   }
+   ```
+
+The CoreUIBar load loop (`packages/storyboard/src/core/ui/CoreUIBar.jsx` — search for `Object.entries(toolConfigs).map`) iterates **every** tool across every surface and resolves `core:` vs `custom:` via the `handler` field's prefix.
 
 ## Icon namespaces
 
-The `Icon.svelte` component supports multiple icon sources via namespaced names:
+`packages/storyboard/src/core/ui/Icon.jsx` resolves multi-source icon names:
 
 | Prefix | Source | Style | Example |
 |--------|--------|-------|---------|
 | `primer/` | Primer Octicons | fill | `primer/repo`, `primer/gear`, `primer/comment` |
 | `feather/` | Feather Icons | stroke | `feather/fast-forward`, `feather/tablet` |
 | `iconoir/` | Iconoir (registered) | stroke | `iconoir/plus-circle`, `iconoir/square-dashed` |
-| *(none)* | Custom overrides | fill | `folder`, `folder-open` |
+| *(none)* | Custom overrides | fill | `home`, `folder`, `folder-open`, `prototype`, `canvas` |
 
-Icon meta props: `strokeWeight`, `scale`, `rotate`, `flipX`, `offsetX`, `offsetY`.
+Icon meta props (passed via tool config `meta`): `strokeWeight`, `scale`, `rotate`, `flipX`, `offsetX`, `offsetY`.
 
-## Menu visibility
+> Primer icon names must be verified against `.agents/data/primer-octicons.json` before use — agents frequently invent names that don't exist.
 
-Menus can be hidden via:
+## Tool visibility
 
-- **Mode filtering**: `"modes": ["inspect"]` — only visible in inspect mode
-- **Route exclusion**: `"excludeRoutes": ["/viewfinder"]` — hidden on specific routes
-- **UI config**: `storyboard.config.json` → `ui.hide.menus: ["my-feature"]`
-- **Action menus**: auto-hide when `getChildren()` returns empty array
-- **Conditional logic**: custom visibility checks in the `visibleMenus` derived block
+A tool may be hidden by any of the following:
 
-## Existing menu buttons for reference
+- **Mode filtering** — `"modes": ["canvas"]` only shows the tool when the canvas mode is active. `["*"]` always.
+- **Surface filtering** — `surface` controls *where* a tool can appear; tools in `command-palette` only show inside ⌘K, etc.
+- **Route exclusion** — `"excludeRoutes": ["^/viewfinder"]` hides on regex-matching routes.
+- **UI config** — `storyboard.config.json` → `ui.hide.menus: ["my-tool"]` (legacy key, still honored).
+- **Tool state store** — `toolStateStore` can mark a tool `'hidden'` or `'disabled'` at runtime.
+- **`guard()` returning `false`** — handler-level gate; skips `setup`/`handler`/`component` entirely.
+- **`getChildren()` returning `[]`** — menu/submenu tools auto-hide when empty.
 
-| Key | Type | Config | Behavior |
-|-----|------|--------|----------|
-| `command` | custom | `trigger: "command"` | Always rightmost, command palette |
-| `create` | custom | `actions` + `feature` refs | Workshop feature launcher, overlay panels |
-| `flows` | action | `action: "core/flows"` | Lists prototype flows, radio-select to switch |
-| `comments` | custom | *(none)* | Auth-aware comments toggle |
-| `docs` | sidepanel | `sidepanel: "docs"` | Toggles docs side panel |
-| `inspector` | sidepanel | `sidepanel: "inspector"` | Toggles inspector side panel |
+## Built-in tools (selected reference)
+
+A non-exhaustive list of currently shipped core tools — useful as code-reading entry points. See `packages/storyboard/toolbar.config.json` for the live list and `packages/storyboard/src/core/tools/handlers/` for the implementations.
+
+| Tool key | Render | Surface | Handler module |
+|----------|--------|---------|----------------|
+| `command-palette` | `button` | `command-toolbar` | `handlers/commandPalette.js` |
+| `flows` | `menu` | `command-toolbar` | `handlers/flows.js` |
+| `theme` | `menu` | `command-toolbar` | `handlers/theme.js` |
+| `create` | `menu` | `command-toolbar` | `handlers/create.js` |
+| `comments` | `button` | `command-toolbar` | `handlers/comments.js` |
+| `hide-chrome` | `button` | `command-toolbar` | `handlers/hideChrome.js` |
+| `inspector` | `sidepanel` | `command-toolbar` | `handlers/inspector.js` |
+| `devtools` | `submenu` | `command-palette` | `handlers/devtools.js` |
+| `canvas-zoom` | `zoom-control` | `canvas-toolbar` | `handlers/canvasToolbar.js` |
 
 ## Optional & Heavy Dependencies in Published Packages
 
@@ -247,3 +138,4 @@ function loadOptionalDep() {
 const mod = await loadOptionalDep()
 if (!mod) return // graceful degradation
 ```
+

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)
 }
 
 /**