@dfosco/storyboard 0.9.2 → 0.9.4

package/src/core/stores/widgetRegistry.js

@@ -0,0 +1,184 @@
+/**
+ * Widget Registry — consumer-supplied custom widget types.
+ *
+ * Consumers register widgets through `mountStoryboardCore({ widgets })`:
+ *
+ *   mountStoryboardCore(config, {
+ *     widgets: {
+ *       'my-thing': {
+ *         component: MyThing,
+ *         label: 'My Thing',
+ *         icon: 'sparkle',
+ *         chrome: { enabled: true },                  // optional, default true
+ *         interaction: {
+ *           selectable: true,                          // default true
+ *           movable: true,                             // default true
+ *           resize: { enabled: true, prod: false },    // default disabled
+ *           expandable: false,
+ *           splitScreen: false,
+ *           interactGate: false,
+ *           interactGateLabel: 'Click to interact',
+ *         },
+ *         connectors: { anchors: {...}, accept: ['*'], exclude: [] },
+ *         features: [ ... ],                          // toolbar actions
+ *         unlisted: false,                            // hide from "+ Add widget"
+ *         props: { width: { type: 'number', default: 400 }, ... },
+ *       },
+ *     },
+ *   })
+ *
+ * Definitions registered through this store are merged with — and override —
+ * the built-in widget configs from `widgets.config.json` on a per-type basis.
+ *
+ * Built-in core widgets (sticky-note, markdown, image, etc.) ALSO live in
+ * this registry once `seedCoreWidgets()` runs at module load. Consumer
+ * overrides for those types replace the core entry entirely; if a consumer
+ * wants to extend a core widget they should re-declare the merged definition.
+ *
+ * Framework-agnostic (zero npm dependencies). React typing is structural —
+ * the `component` field is opaque from this store's perspective.
+ *
+ * @typedef {object} WidgetChromeOptions
+ * @property {boolean} [enabled]  Render component inside WidgetChrome. Default: true.
+ *                                When false, the widget renders raw with no toolbar,
+ *                                no anchor ports, no select handle, no interact gate.
+ *                                Consumer owns 100% of the visible UI.
+ *
+ * @typedef {object} WidgetInteractionOptions
+ * @property {boolean} [selectable]   Default: true. False → no select handle, single-click
+ *                                    does not select.
+ * @property {boolean} [movable]      Default: true. False → drag surface class is omitted,
+ *                                    widget cannot be dragged.
+ * @property {{ enabled: boolean, prod?: boolean }} [resize]
+ *                                    Default: disabled. Same shape as widgets.config.json.
+ * @property {boolean} [expandable]   Default: false. Adds the "Expand" action.
+ * @property {boolean} [splitScreen]  Default: false. Eligible as a split-screen pane.
+ * @property {boolean} [interactGate] Default: false. Overlays "Click to interact" until clicked.
+ * @property {string}  [interactGateLabel] Default: 'Click to interact'.
+ *
+ * @typedef {object} WidgetDefinition
+ * @property {*}        [component]    React component or render function.
+ *                                     Required for consumer widgets; not stored for
+ *                                     core widgets when they fall back to widgets.config.json.
+ * @property {string}   [label]        Display label for menus and selectors.
+ * @property {string}   [icon]         Icon key from ICON_REGISTRY.
+ * @property {WidgetChromeOptions}      [chrome]
+ * @property {WidgetInteractionOptions} [interaction]
+ * @property {object}   [connectors]   { anchors, accept, exclude, defaults }.
+ * @property {Array<object>} [features] Toolbar feature list.
+ * @property {boolean}  [unlisted]     Hide from "+ Add widget" menu.
+ * @property {Record<string, object>} [props] Prop schema.
+ *
+ * The following back-compat fields are still read (mirrors widgets.config.json
+ * legacy shape so an unchanged JSON entry continues to work after migration):
+ * @property {{ enabled: boolean, prod?: boolean }} [resize]
+ * @property {boolean} [expandable]
+ * @property {boolean} [splitScreen]
+ * @property {boolean} [interactGate]
+ * @property {string}  [interactGateLabel]
+ */
+
+/** @type {Map<string, WidgetDefinition>} */
+let _registry = new Map()
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+/**
+ * Replace the entire registry from a consumer-supplied map.
+ * Pass null/undefined to clear.
+ * @param {Record<string, WidgetDefinition>|null|undefined} map
+ */
+export function initWidgetRegistry(map) {
+  _registry = new Map()
+  if (map && typeof map === 'object') {
+    for (const [type, def] of Object.entries(map)) {
+      if (def && typeof def === 'object') {
+        _registry.set(type, def)
+      }
+    }
+  }
+  _notify()
+}
+
+/**
+ * Register a single widget type (consumer-side). Replaces any existing entry.
+ * @param {string} type
+ * @param {WidgetDefinition} definition
+ */
+export function registerWidget(type, definition) {
+  if (!type || typeof type !== 'string') {
+    throw new Error('[storyboard] registerWidget: type must be a non-empty string')
+  }
+  if (!definition || typeof definition !== 'object') {
+    throw new Error(`[storyboard] registerWidget("${type}"): definition must be an object`)
+  }
+  _registry.set(type, definition)
+  _notify()
+}
+
+/**
+ * Remove a registry entry. Built-in widgets re-seeded via seedCoreWidgets()
+ * are unaffected; only the consumer override is removed.
+ * @param {string} type
+ */
+export function unregisterWidget(type) {
+  if (_registry.delete(type)) _notify()
+}
+
+/**
+ * Get the registered definition for a widget type, or null.
+ * Consumers should prefer `getMergedWidgetDefinition()` which also folds in
+ * the static widgets.config.json shape.
+ * @param {string} type
+ * @returns {WidgetDefinition|null}
+ */
+export function getWidgetDefinition(type) {
+  return _registry.get(type) || null
+}
+
+/**
+ * Snapshot of the entire registry as a plain object.
+ * @returns {Record<string, WidgetDefinition>}
+ */
+export function getAllWidgetDefinitions() {
+  return Object.fromEntries(_registry)
+}
+
+/**
+ * Subscribe to registry changes. Returns unsubscribe fn.
+ * Compatible with `useSyncExternalStore`.
+ * @param {Function} callback
+ * @returns {Function}
+ */
+export function subscribeToWidgetRegistry(callback) {
+  _listeners.add(callback)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot version string for change detection.
+ * Compatible with `useSyncExternalStore`.
+ * @returns {string}
+ */
+export function getWidgetRegistrySnapshot() {
+  return String(_snapshotVersion)
+}
+
+function _notify() {
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb() } catch (err) {
+      console.error('[storyboard] Error in widgetRegistry subscriber:', err)
+    }
+  }
+}
+
+/** Reset all state. Only for tests. */
+export function _resetWidgetRegistry() {
+  _registry = new Map()
+  _listeners.clear()
+  _snapshotVersion = 0
+}

package/src/core/stores/widgetRegistry.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  initWidgetRegistry,
+  registerWidget,
+  unregisterWidget,
+  getWidgetDefinition,
+  getAllWidgetDefinitions,
+  subscribeToWidgetRegistry,
+  getWidgetRegistrySnapshot,
+  _resetWidgetRegistry,
+} from './widgetRegistry.js'
+
+describe('widgetRegistry', () => {
+  beforeEach(() => {
+    _resetWidgetRegistry()
+  })
+
+  it('starts empty', () => {
+    expect(getAllWidgetDefinitions()).toEqual({})
+    expect(getWidgetDefinition('anything')).toBeNull()
+  })
+
+  it('initWidgetRegistry seeds the store with valid entries', () => {
+    const Component = () => null
+    initWidgetRegistry({
+      'my-thing': { component: Component, label: 'My Thing' },
+      'other': { label: 'Other' },
+    })
+    expect(getWidgetDefinition('my-thing')).toEqual({ component: Component, label: 'My Thing' })
+    expect(getWidgetDefinition('other')).toEqual({ label: 'Other' })
+    expect(Object.keys(getAllWidgetDefinitions()).sort()).toEqual(['my-thing', 'other'])
+  })
+
+  it('initWidgetRegistry replaces previous entries', () => {
+    initWidgetRegistry({ a: { label: 'A' } })
+    initWidgetRegistry({ b: { label: 'B' } })
+    expect(getWidgetDefinition('a')).toBeNull()
+    expect(getWidgetDefinition('b')).toEqual({ label: 'B' })
+  })
+
+  it('initWidgetRegistry ignores null/undefined and non-object entries', () => {
+    initWidgetRegistry({
+      ok: { label: 'OK' },
+      nullish: null,
+      undef: undefined,
+      notObj: 'string',
+    })
+    expect(Object.keys(getAllWidgetDefinitions())).toEqual(['ok'])
+  })
+
+  it('initWidgetRegistry with null/undefined clears the store', () => {
+    initWidgetRegistry({ a: { label: 'A' } })
+    initWidgetRegistry(null)
+    expect(getAllWidgetDefinitions()).toEqual({})
+  })
+
+  it('registerWidget adds a single entry', () => {
+    registerWidget('foo', { label: 'Foo' })
+    expect(getWidgetDefinition('foo')).toEqual({ label: 'Foo' })
+  })
+
+  it('registerWidget replaces an existing entry', () => {
+    registerWidget('foo', { label: 'Foo' })
+    registerWidget('foo', { label: 'Foo2' })
+    expect(getWidgetDefinition('foo')).toEqual({ label: 'Foo2' })
+  })
+
+  it('registerWidget throws on invalid type', () => {
+    expect(() => registerWidget('', { label: 'X' })).toThrow(/non-empty string/)
+    expect(() => registerWidget(null, { label: 'X' })).toThrow(/non-empty string/)
+  })
+
+  it('registerWidget throws on invalid definition', () => {
+    expect(() => registerWidget('foo', null)).toThrow(/must be an object/)
+    expect(() => registerWidget('foo', 'string')).toThrow(/must be an object/)
+  })
+
+  it('unregisterWidget removes an entry', () => {
+    registerWidget('foo', { label: 'Foo' })
+    unregisterWidget('foo')
+    expect(getWidgetDefinition('foo')).toBeNull()
+  })
+
+  it('unregisterWidget on missing entry is a no-op', () => {
+    expect(() => unregisterWidget('nope')).not.toThrow()
+  })
+
+  it('subscribeToWidgetRegistry fires on init/register/unregister', () => {
+    let calls = 0
+    const unsubscribe = subscribeToWidgetRegistry(() => { calls++ })
+    initWidgetRegistry({ a: { label: 'A' } })
+    expect(calls).toBe(1)
+    registerWidget('b', { label: 'B' })
+    expect(calls).toBe(2)
+    unregisterWidget('a')
+    expect(calls).toBe(3)
+    unsubscribe()
+    registerWidget('c', { label: 'C' })
+    expect(calls).toBe(3)
+  })
+
+  it('getWidgetRegistrySnapshot returns a stable string per state', () => {
+    const a = getWidgetRegistrySnapshot()
+    expect(a).toBe(getWidgetRegistrySnapshot())
+    registerWidget('foo', { label: 'Foo' })
+    const b = getWidgetRegistrySnapshot()
+    expect(b).not.toBe(a)
+  })
+})

package/src/core/ui/CoreUIBar.jsx

@@ -116,7 +116,7 @@ function menuVisibleInMode(menu, mode) {
   return menu.modes.includes('*') || menu.modes.includes(mode)
 }
 
-// Subscribable mode state for useExternalStore (replaces Svelte modeState)
+// Subscribable mode state for useExternalStore
 const modeState = {
   get mode() { return getCurrentMode() },
   get modes() { return getRegisteredModes() },

package/src/core/ui-entry.js

@@ -22,9 +22,3 @@ export { mountDevTools, unmountDevTools } from './devtools/devtools.js'
 
 // Comments UI
 export { mountComments } from './comments/ui/mount.js'
-
-// Viewfinder dashboard
-export { mountViewfinder, unmountViewfinder } from './ui/viewfinder.ts'
-
-// Design modes
-export { mountDesignModesUI as mountDesignModes } from './ui/design-modes.ts'

package/src/core/vite/server-plugin.js

@@ -14,6 +14,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { parse as parseJsonc } from 'jsonc-parser'
 import { getConfig } from '../stores/configSchema.js'
+import { initServerWidgets } from '../canvas/customWidgets.js'
 import { createDevLogger, setDevLogger } from '../logger/devLogger.js'
 import { serverFeatures as workshopFeatures } from '../workshop/features/registry-server.js'
 import { docsHandler, collectFiles } from './docs-handler.js'
@@ -161,6 +162,17 @@ export default function storyboardServer() {
       base = viteConfig.base || '/'
       config = readConfig(root)
       isDev = viteConfig.command === 'serve'
+
+      // Seed the server-side custom-widget registry from the consumer's
+      // `storyboard.config.json.widgets` block. Consumer entries override
+      // built-in widget metadata for collision detection, default sizes,
+      // prompt-exec config, etc. Server-side does not load React components
+      // — those are seeded in the browser via `mountStoryboardCore({ widgets })`.
+      try {
+        initServerWidgets(config?.widgets || null)
+      } catch (err) {
+        console.warn('[storyboard] Failed to init custom widget registry:', err.message)
+      }
     },
 
     configureServer(server) {

package/src/internals/BranchBar/BranchBar.jsx

@@ -11,6 +11,7 @@ import { useState, useEffect, useMemo } from 'react'
 import { createPortal } from 'react-dom'
 import { GitBranchIcon } from '@primer/octicons-react'
 import { useBranches } from './useBranches.js'
+import ChromeSlot from '../../core/ui/ChromeSlot.jsx'
 import css from './BranchBar.module.css'
 
 /** Check if we're in local dev mode (respects ?prodMode simulation). */
@@ -78,28 +79,34 @@ export default function BranchBar({ basePath }) {
   }
 
   return createPortal(
-    <div className={css.bar} data-branch-bar>
-      <div
-        className={`${css.barInner}${isLocalDev ? '' : ` ${css.barProd}`}`}
-        style={domainColor ? { '--sb-branch-bar-bg': domainColor } : undefined}
-      >
-        <span className={css.barLabel}>
-          {isLocalDev && window.__SB_DEV_DOMAIN__ && <>
-            <span className={css.barDomainName}>⌘ {window.__SB_DEV_DOMAIN__}</span>
-            <span className={css.barSeparator}>·</span>
-          </>}
-          <GitBranchIcon size={12} />
-          <span className={css.barBranchName}>{currentBranch}</span>
-          {isLocalDev && <>
-            <span className={css.barSeparator}>·</span>
-            <span>Local development</span>
-          </>}
-        </span>
-        <div className={css.barActions}>
-          <button className={css.barAction} onClick={hideChrome}>Hide</button>
+    <ChromeSlot id="branch-bar:root" surface="branch-bar" ctx={{ currentBranch, isLocalDev }}>
+      <div className={css.bar} data-branch-bar>
+        <div
+          className={`${css.barInner}${isLocalDev ? '' : ` ${css.barProd}`}`}
+          style={domainColor ? { '--sb-branch-bar-bg': domainColor } : undefined}
+        >
+          <ChromeSlot id="branch-bar:label" surface="branch-bar" ctx={{ currentBranch, isLocalDev }}>
+            <span className={css.barLabel}>
+              {isLocalDev && window.__SB_DEV_DOMAIN__ && <>
+                <span className={css.barDomainName}>⌘ {window.__SB_DEV_DOMAIN__}</span>
+                <span className={css.barSeparator}>·</span>
+              </>}
+              <GitBranchIcon size={12} />
+              <span className={css.barBranchName}>{currentBranch}</span>
+              {isLocalDev && <>
+                <span className={css.barSeparator}>·</span>
+                <span>Local development</span>
+              </>}
+            </span>
+          </ChromeSlot>
+          <div className={css.barActions}>
+            <ChromeSlot id="branch-bar:hide-button" surface="branch-bar" ctx={{ currentBranch, isLocalDev }}>
+              <button className={css.barAction} onClick={hideChrome}>Hide</button>
+            </ChromeSlot>
+          </div>
         </div>
       </div>
-    </div>,
+    </ChromeSlot>,
     portalContainer
   )
 }

package/src/internals/canvas/CanvasPage.bridge.test.jsx

@@ -72,6 +72,8 @@ vi.mock('./widgets/widgetConfig.js', async () => {
     getAnchorState: () => ({}),
     canAcceptConnection: () => false,
     isSplitScreenCapable: () => false,
+    getChromeOptions: () => ({ enabled: true }),
+    getInteractionOptions: () => ({ selectable: true, movable: true, resize: null, expandable: false, splitScreen: false, interactGate: false, interactGateLabel: 'Click to interact' }),
     schemas: {},
     getMenuWidgetTypes: () => [],
     getConnectorDefaults: actual.getConnectorDefaults,

package/src/internals/canvas/CanvasPage.dragdrop.test.jsx

@@ -57,6 +57,8 @@ vi.mock('./widgets/widgetConfig.js', async () => {
     getAnchorState: () => ({}),
     canAcceptConnection: () => false,
     isSplitScreenCapable: () => false,
+    getChromeOptions: () => ({ enabled: true }),
+    getInteractionOptions: () => ({ selectable: true, movable: true, resize: null, expandable: false, splitScreen: false, interactGate: false, interactGateLabel: 'Click to interact' }),
     schemas: {},
     getMenuWidgetTypes: () => [],
     getConnectorDefaults: actual.getConnectorDefaults,

package/src/internals/canvas/CanvasPage.jsx

@@ -6,7 +6,7 @@ import { shouldPreventCanvasTextSelection } from './textSelection.js'
 import { getCanvasThemeVars, getCanvasPrimerAttrs } from './canvasTheme.js'
 import { getWidgetComponent } from './widgets/index.js'
 import { schemas, getDefaults } from './widgets/widgetProps.js'
-import { getFeatures, isResizable, isExpandable, getAnchorState, canAcceptConnection, isSplitScreenCapable } from './widgets/widgetConfig.js'
+import { getFeatures, isResizable, isExpandable, getAnchorState, canAcceptConnection, isSplitScreenCapable, getChromeOptions, getInteractionOptions } from './widgets/widgetConfig.js'
 import { createPasteContext, resolvePaste } from './widgets/pasteRules.js'
 import { getPasteRules } from '../../core/index.js'
 import { isTerminalResizable, getTerminalDimensions } from '../../core/index.js'
@@ -346,7 +346,7 @@ function computeCanvasBounds(widgets, componentEntries) {
 }
 
 /** Renders a single JSON-defined widget by type lookup. */
-function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefreshGitHub, multiSelected }) {
+function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefreshGitHub, multiSelected, selected, onSelect }) {
   const Component = getWidgetComponent(widget.type)
   if (!Component) {
     console.warn(`[canvas] Unknown widget type: ${widget.type}`)
@@ -355,7 +355,10 @@ function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefre
   const resizable = (widget.type === 'terminal' || widget.type === 'agent')
     ? isTerminalResizable(widget.props?.agentId) && !!onUpdate
     : isResizable(widget.type) && !!onUpdate
-  // Only pass ref to forwardRef-wrapped components (e.g. PrototypeEmbed)
+  // Standard contract: every custom widget component receives these props.
+  // selected / onSelect are especially important for chrome-disabled custom
+  // widgets that own their visible UI and need to render their own select
+  // affordance.
   const elementProps = {
     id: widget.id,
     props: widget.props,
@@ -364,6 +367,8 @@ function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefre
     onRefreshGitHub,
     canRefreshGitHub,
     multiSelected,
+    selected,
+    onSelect,
   }
   if (Component.$$typeof === Symbol.for('react.forward_ref')) {
     elementProps.ref = widgetRef
@@ -536,6 +541,12 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
     onUpdate?.(widget.id, updates)
   }, [onUpdate, widget.id])
 
+  // Per-widget chrome + interaction switches from the (consumer-merged)
+  // widget definition. Defaults match historical behavior, so core widgets
+  // (sticky-note, image, terminal, etc.) are unaffected.
+  const chromeOpts = useMemo(() => getChromeOptions(widget.type), [widget.type])
+  const interactionOpts = useMemo(() => getInteractionOptions(widget.type), [widget.type])
+
   return (
     <WidgetChrome
       widgetId={widget.id}
@@ -554,6 +565,9 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
       currentRole={widget.props?.role || defaultHubRole}
       onRoleChange={onRoleChange ? (roleId) => onRoleChange(widget.id, roleId) : undefined}
       readOnly={readOnly}
+      chromeEnabled={chromeOpts.enabled}
+      movable={interactionOpts.movable}
+      selectable={interactionOpts.selectable}
     >
       <WidgetRenderer
         widget={widget}
@@ -562,6 +576,8 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
         onRefreshGitHub={onRefreshGitHub}
         canRefreshGitHub={canRefreshGitHub}
         multiSelected={multiSelected}
+        selected={selected}
+        onSelect={onSelect}
       />
     </WidgetChrome>
   )

package/src/internals/canvas/CanvasPage.multiselect.test.jsx

@@ -100,6 +100,8 @@ vi.mock('./widgets/widgetConfig.js', async () => {
     isExpandable: () => false,
     isSplitScreenCapable: () => false,
     getInteractGate: () => ({ enabled: false, label: 'Click to interact' }),
+    getChromeOptions: () => ({ enabled: true }),
+    getInteractionOptions: () => ({ selectable: true, movable: true, resize: null, expandable: false, splitScreen: false, interactGate: false, interactGateLabel: 'Click to interact' }),
     getWidgetMeta: () => null,
     getConnectorConfig: actual.getConnectorConfig,
     getAnchorState: actual.getAnchorState,

package/src/internals/canvas/widgets/WidgetChrome.jsx

@@ -344,6 +344,25 @@ function ColorPickerFeature({ currentColor, options, onColorChange }) {
  *   useImperativeHandle(ref, () => ({ handleAction(actionId) { ... } }))
  * WidgetChrome will call widgetRef.current.handleAction(actionId) for
  * non-standard actions (anything other than 'delete').
+ *
+ * ## Per-widget chrome / interaction switches
+ *
+ * Three booleans (read from the widget definition by CanvasPage) gate the
+ * built-in chrome surface. Defaults match historical behavior so existing
+ * widgets are unaffected.
+ *
+ * - `chromeEnabled` (default true) — When false, the entire WidgetChrome
+ *   wrapper short-circuits and renders `children` inside a minimal
+ *   `<div data-widget-id>` shell. No toolbar, no anchors, no select handle,
+ *   no interact gate. Use this for fully custom client widgets that own
+ *   their own visual chrome.
+ * - `movable` (default true) — When false, the `tc-drag-surface` class is
+ *   omitted from the inner slot so tiny-canvas won't treat the widget as
+ *   draggable. Useful for pinned/locked widgets (background stickers,
+ *   decorative chrome).
+ * - `selectable` (default true) — When false, the select handle button is
+ *   not rendered and select-via-handle is unavailable. Canvas-level click
+ *   selection (configured elsewhere) is independent of this flag.
  */
 export default function WidgetChrome({
   widgetId,
@@ -363,6 +382,9 @@ export default function WidgetChrome({
   onRoleChange,
   children,
   readOnly = false,
+  chromeEnabled = true,
+  movable = true,
+  selectable = true,
 }) {
   const [hovered, setHovered] = useState(false)
   const altHeld = useAltKey()
@@ -461,6 +483,29 @@ export default function WidgetChrome({
     onSelect?.()
   }, [onSelect])
 
+  // ── chrome.enabled: false short-circuit ──
+  // Render the widget bare with just a minimal positioning shell. Keep
+  // data-widget-id so DOM lookups (anchor port queries, scroll-to-widget,
+  // selection state propagation) still work. All hooks above remain in
+  // play so React's hook ordering is stable regardless of this flag.
+  if (!chromeEnabled) {
+    return (
+      <div
+        className={styles.chromeContainer}
+        data-widget-id={widgetId}
+        data-widget-chrome-disabled
+        data-widget-selected={selected || undefined}
+      >
+        {children}
+      </div>
+    )
+  }
+
+  // Drag surface class is omitted when `movable: false` — tiny-canvas only
+  // initiates a drag from elements matching `data-tc-handle=".tc-drag-handle,
+  // .tc-drag-surface"`, so dropping the class effectively pins the widget.
+  const slotDragClass = movable ? 'tc-drag-surface' : ''
+
   return (
     <div
       className={styles.chromeContainer}
@@ -470,7 +515,7 @@ export default function WidgetChrome({
       onMouseEnter={(readOnly && !hasFeatures) ? undefined : handleMouseEnter}
       onMouseLeave={(readOnly && !hasFeatures) ? undefined : handleMouseLeave}
     >
-      <div ref={slotRef} className={`tc-drag-surface ${styles.widgetSlot} ${selected ? styles.widgetSlotSelected : ''} ${multiSelected ? styles.widgetSlotMultiSelected : ''}`} data-widget-selected={selected || undefined} data-widget-interacting={interacting || undefined}>
+      <div ref={slotRef} className={`${slotDragClass} ${styles.widgetSlot} ${selected ? styles.widgetSlotSelected : ''} ${multiSelected ? styles.widgetSlotMultiSelected : ''}`} data-widget-selected={selected || undefined} data-widget-interacting={interacting || undefined}>
         {children}
         {gate.enabled && !interacting && !readOnly && (
           <div
@@ -645,12 +690,12 @@ export default function WidgetChrome({
           </div>
           )}
 
-          {!readOnly && (
-            <Tooltip text={selected ? "Click and drag to move" : "Select"} direction="n">
+          {!readOnly && selectable && (
+            <Tooltip text={selected ? (movable ? "Click and drag to move" : "Selected") : "Select"} direction="n">
               <button
-                className={`tc-drag-handle ${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
+                className={`${movable ? 'tc-drag-handle ' : ''}${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
                 onClick={handleHandleClick}
-                aria-label={selected ? "Drag to move widget" : "Select widget"}
+                aria-label={selected ? (movable ? "Drag to move widget" : "Widget selected") : "Select widget"}
                 aria-pressed={selected}
               />
             </Tooltip>

package/src/internals/canvas/widgets/WidgetChrome.test.jsx

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import WidgetChrome from './WidgetChrome.jsx'
+
+function renderChrome(extra = {}) {
+  return render(
+    <WidgetChrome widgetId="w1" widgetType="sticky-note" {...extra}>
+      <div data-testid="inner">inner</div>
+    </WidgetChrome>
+  )
+}
+
+describe('WidgetChrome chrome/interaction switches', () => {
+  it('renders the full chrome shell by default', () => {
+    const { container, getByTestId } = renderChrome()
+    expect(getByTestId('inner')).toBeTruthy()
+    expect(container.querySelector('[data-widget-id="w1"]')).toBeTruthy()
+    // Drag surface is present (allows tiny-canvas drag) and select handle exists
+    expect(container.querySelector('.tc-drag-surface')).toBeTruthy()
+    expect(container.querySelector('.tc-drag-handle')).toBeTruthy()
+    // Not flagged as chrome-disabled
+    expect(container.querySelector('[data-widget-chrome-disabled]')).toBeNull()
+  })
+
+  it('chromeEnabled=false short-circuits to a minimal shell', () => {
+    const { container, getByTestId } = renderChrome({ chromeEnabled: false })
+    expect(getByTestId('inner')).toBeTruthy()
+    const root = container.querySelector('[data-widget-id="w1"]')
+    expect(root).toBeTruthy()
+    expect(root.hasAttribute('data-widget-chrome-disabled')).toBe(true)
+    // No toolbar, no anchors, no select handle
+    expect(container.querySelector('.tc-drag-surface')).toBeNull()
+    expect(container.querySelector('.tc-drag-handle')).toBeNull()
+    // Inner content rendered directly
+    expect(root.contains(getByTestId('inner'))).toBe(true)
+  })
+
+  it('chromeEnabled=false propagates selected state for custom widgets', () => {
+    const { container } = renderChrome({ chromeEnabled: false, selected: true })
+    const root = container.querySelector('[data-widget-id="w1"]')
+    expect(root.getAttribute('data-widget-selected')).toBe('true')
+  })
+
+  it('movable=false omits the tc-drag-surface class from the slot', () => {
+    const { container } = renderChrome({ movable: false })
+    expect(container.querySelector('.tc-drag-surface')).toBeNull()
+    // Select handle still renders (selectable default true) and is no longer
+    // a drag handle — should NOT carry tc-drag-handle.
+    const handle = container.querySelector('button[aria-label*="Select"], button[aria-label*="selected"], button[aria-pressed]')
+    expect(handle).toBeTruthy()
+    expect(handle.className.includes('tc-drag-handle')).toBe(false)
+  })
+
+  it('selectable=false hides the select handle', () => {
+    const { container } = renderChrome({ selectable: false })
+    // The select-handle button has aria-pressed; no other button in chrome
+    // exposes aria-pressed by default (color picker, etc. use aria-label only)
+    expect(container.querySelector('button[aria-pressed]')).toBeNull()
+  })
+
+  it('chromeEnabled=false skips select handle even when selectable=true', () => {
+    const { container } = renderChrome({ chromeEnabled: false, selectable: true })
+    expect(container.querySelector('button[aria-pressed]')).toBeNull()
+  })
+})