@dfosco/storyboard 0.11.3 → 0.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dfosco/storyboard",
-    "version": "0.11.3",
+    "version": "0.11.5",
     "type": "module",
     "license": "MIT",
     "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/src/internals/BranchesDropdown/BranchesDropdown.jsx

@@ -19,26 +19,37 @@ function branchLabel(entry, homeTitle, homeFolder) {
   return pieces.join(' ')
 }
 
-export default function BranchesDropdown({ branches, branchBasePath, currentBranch, homeTitle = '', homeFolder = null }) {
+export default function BranchesDropdown({ branches, branchBasePath, currentBranch, homeTitle = '', homeFolder = null, isBranchOnly = false }) {
   if (!currentBranch || isLocalDev() || !Array.isArray(branches)) return null
 
   const visibleBranches = branches.filter(entry => entry?.branch && entry.branch !== currentBranch)
   if (visibleBranches.length === 0) return null
 
+  // When the prototype is branch-only (i.e. the current branch doesn't
+  // have it), give the button a subtle accent so users can spot the
+  // affordance without painting the whole card. Tooltip text shifts to
+  // make the meaning explicit.
+  const btnClass = isBranchOnly ? `${css.iconBtn} ${css.iconBtnAccent}` : css.iconBtn
+  const label = isBranchOnly
+    ? 'Open on another branch'
+    : 'See branches'
+
   return (
     <Menu.Root>
       <Menu.Trigger
-        className={css.iconBtn}
+        className={btnClass}
         onClick={(e) => { e.preventDefault(); e.stopPropagation() }}
-        aria-label="See branches"
-        title="See branches"
+        aria-label={label}
+        title={label}
       >
         <GitBranchIcon size={16} />
       </Menu.Trigger>
       <Menu.Portal>
         <Menu.Positioner className={css.branchesPositioner} side="bottom" align="end" sideOffset={4}>
           <Menu.Popup className={css.branchesPopup}>
-            <div className={css.branchesTitle}>Branches</div>
+            <div className={css.branchesTitle}>
+              {isBranchOnly ? 'Available on' : 'Branches'}
+            </div>
             {visibleBranches.map(entry => {
               const href = entry.isExternal && entry.externalUrl
                 ? entry.externalUrl

package/src/internals/BranchesDropdown/BranchesDropdown.module.css

@@ -17,6 +17,22 @@
   color: var(--color-foreground-muted, #555);
 }
 
+/* Subtle accent applied when the current branch doesn't have the
+ * prototype (the card is "branch-only" elsewhere). Replaces the
+ * previous loud card-level blue background — now the only marker
+ * that a prototype lives on another branch is this single tinted
+ * button, plus an accent ring on hover/open. */
+.iconBtnAccent {
+  color: var(--color-foreground-accent, #0969da);
+  background: var(--color-background-accent-muted, #ddf4ff);
+}
+
+.iconBtnAccent:hover {
+  background: var(--color-background-accent-muted, #ddf4ff);
+  color: var(--color-foreground-accent, #0969da);
+  box-shadow: inset 0 0 0 1px var(--color-border-accent-muted, #54aeff66);
+}
+
 .branchesPositioner {
   z-index: 200;
 }

package/src/internals/BranchesDropdown/BranchesDropdown.test.jsx

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, cleanup } from '@testing-library/react'
+import BranchesDropdown from './BranchesDropdown.jsx'
+
+beforeEach(() => {
+  cleanup()
+  // BranchesDropdown bails out when window.__SB_LOCAL_DEV__ === true.
+  if (typeof window !== 'undefined') {
+    delete window.__SB_LOCAL_DEV__
+  }
+})
+
+const branches = [
+  { branch: 'main', folder: 'demos', route: '/Signup' },
+  { branch: 'feature-x', folder: 'demos', route: '/Signup' },
+]
+
+describe('BranchesDropdown', () => {
+  it('renders the trigger when other branches have the prototype', () => {
+    const { container } = render(
+      <BranchesDropdown branches={branches} branchBasePath="/" currentBranch="main" />,
+    )
+    const trigger = container.querySelector('button')
+    expect(trigger).toBeTruthy()
+    expect(trigger.getAttribute('aria-label')).toBe('See branches')
+  })
+
+  it('applies the accent class and re-labels when isBranchOnly is true', () => {
+    const { container } = render(
+      <BranchesDropdown
+        branches={branches}
+        branchBasePath="/"
+        currentBranch="main"
+        isBranchOnly
+      />,
+    )
+    const trigger = container.querySelector('button')
+    expect(trigger).toBeTruthy()
+    // CSS Modules hash class names — assert by suffix match.
+    expect(trigger.className).toMatch(/iconBtnAccent/)
+    expect(trigger.getAttribute('aria-label')).toBe('Open on another branch')
+  })
+
+  it('does NOT apply the accent class when isBranchOnly is false', () => {
+    const { container } = render(
+      <BranchesDropdown branches={branches} branchBasePath="/" currentBranch="main" />,
+    )
+    const trigger = container.querySelector('button')
+    expect(trigger.className).not.toMatch(/iconBtnAccent/)
+  })
+
+  it('returns null when only the current branch has the prototype', () => {
+    const { container } = render(
+      <BranchesDropdown
+        branches={[{ branch: 'main', folder: 'demos', route: '/Signup' }]}
+        branchBasePath="/"
+        currentBranch="main"
+      />,
+    )
+    expect(container.querySelector('button')).toBeNull()
+  })
+})

package/src/internals/Viewfinder.jsx

@@ -530,7 +530,12 @@ function ArtifactCard({ item, basePath, branchBasePath, currentBranch, starred,
   const dirName = item.id.split(':').slice(1).join(':')
   const typeLabel = item.type === 'canvas' ? 'Canvas' : item.type === 'prototype' ? 'Prototype' : 'Component'
   const canEditDelete = !isBranchOnly && (item.type === 'canvas' || item.type === 'prototype')
-  const cardClass = `${css.card}${item.isPrivate ? ' ' + css.cardPrivate : ''}${isBranchOnly ? ' ' + css.branchOnlyCard : ''}`
+  // Cards intentionally look identical regardless of `isBranchOnly`. The
+  // only marker that a prototype lives on another branch is now the
+  // subtle blue tint on the BranchesDropdown button (see below). The
+  // previous full-card .branchOnlyCard background drew the eye too
+  // strongly for what is effectively a "hint, not a blocker" state.
+  const cardClass = `${css.card}${item.isPrivate ? ' ' + css.cardPrivate : ''}`
 
   return (
     <>
@@ -538,7 +543,6 @@ function ArtifactCard({ item, basePath, branchBasePath, currentBranch, starred,
         <div className={css.cardHeader}>
           <div className={css.cardBadgeGroup}>
             <span className={css.cardBadge}>{getTypeLabel(item.type)}</span>
-            {isBranchOnly && <span className={css.branchOnlyBadge}>Branch-only</span>}
             {item.isPrivate && !isBranchOnly && (
               <Tooltip text={`${typeLabel} not published, only visible to you`} direction="n">
                 <button
@@ -562,6 +566,7 @@ function ArtifactCard({ item, basePath, branchBasePath, currentBranch, starred,
               currentBranch={currentBranch}
               homeTitle={item.name}
               homeFolder={item.folder}
+              isBranchOnly={isBranchOnly}
             />
             {canEditDelete && (
               <CardActionsMenu

package/src/internals/Viewfinder.module.css

@@ -650,15 +650,6 @@
   opacity: 1;
 }
 
-.branchOnlyCard {
-  background: var(--color-background-muted, #f6f8fa);
-  border-color: var(--color-border-muted, #d8dee4);
-}
-
-.branchOnlyCard:hover {
-  border-color: var(--color-border-accent-muted, #54aeff66);
-}
-
 .cardThumb {
   height: 140px;
   background: var(--color-background-muted, #f5f5f5);
@@ -680,17 +671,6 @@
   color: var(--color-foreground-muted, #555);
 }
 
-.branchOnlyBadge {
-  padding: 3px 8px;
-  border-radius: 999px;
-  font-size: 11px;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.4px;
-  background: var(--color-background-accent-muted, #ddf4ff);
-  color: var(--color-foreground-accent, #0969da);
-}
-
 .cardPrivateBadge {
   display: inline-flex;
   align-items: center;

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

@@ -0,0 +1,270 @@
+import {
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { getWidgetComponent } from './index.js'
+import styles from './Widget.module.css'
+
+/**
+ * `<Widget>` — render any registered canvas widget inside a normal React page.
+ *
+ * Canvas widgets follow a stable contract: they resolve from a `type` string
+ * (via `getWidgetComponent`), read their fields from a flat `props` object, and
+ * render chrome-less (the canvas applies toolbar/anchors/selection externally).
+ * This component reproduces that contract off-canvas so any widget can be used
+ * as a first-class element in a page:
+ *
+ *   <Widget type="markdown" content="# Hi" className="prose" />
+ *   <Widget type="prototype" src="StartupSignup" width={900} height={600} />
+ *   <Widget type="sticky-note" text="Note" color="yellow" draggable resizable />
+ *
+ * Prop mapping
+ * ------------
+ * Reserved props configure the wrapper / contract and are NOT forwarded into
+ * the widget's `props` object:
+ *   type, id, className, style, onUpdate, widgetRef, children,
+ *   draggable, resizable, chrome
+ * Every OTHER prop is spread into the widget `props` object, so all widget
+ * fields (content, settings, size — unique or not) are passable as props.
+ *
+ * onUpdate
+ * --------
+ * Defaults to internal local state (uncontrolled): widgets that self-heal or
+ * edit through `onUpdate(partial)` keep working, and resize/drag persist for
+ * the lifetime of the element. Pass your own `onUpdate` for controlled mode —
+ * it receives the same partial-merge object and you own the props.
+ *
+ * chrome
+ * ------
+ * `chrome` (default true) renders the canvas-style selection outline and the
+ * drag/select handle (the trigger dot that reveals a grab handle on hover),
+ * matching how widgets look on the canvas — minus the action menu. Set
+ * `chrome={false}` for a bare widget with no selection affordance.
+ *
+ * draggable / resizable
+ * ---------------------
+ * `resizable` (default false) is forwarded to the widget, which renders its own
+ * ResizeHandle and persists width/height through `onUpdate`. `draggable`
+ * (default false) is a page-level affordance: the widget body and the select
+ * handle become pointer-draggable and the offset is applied as a CSS translate.
+ */
+
+const RESERVED = new Set([
+  'type',
+  'id',
+  'className',
+  'style',
+  'onUpdate',
+  'widgetRef',
+  'children',
+  'draggable',
+  'resizable',
+  'chrome',
+])
+
+const DRAG_THRESHOLD = 3
+
+function isForwardRef(Component) {
+  return Component != null && Component.$$typeof === Symbol.for('react.forward_ref')
+}
+
+function Widget(
+  {
+    type,
+    id,
+    className,
+    style,
+    onUpdate,
+    draggable = false,
+    resizable = false,
+    chrome = true,
+    ...rest
+  },
+  ref,
+) {
+  const autoId = useId()
+  const widgetId = id || `widget-${type || 'unknown'}-${autoId}`
+
+  // Collect every non-reserved prop into the flat widget props object.
+  const incomingProps = useMemo(() => {
+    const out = {}
+    for (const key of Object.keys(rest)) {
+      if (!RESERVED.has(key)) out[key] = rest[key]
+    }
+    return out
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(rest)])
+
+  // Local override state powers the default (uncontrolled) onUpdate so that
+  // self-healing widgets, resizing, and editing all persist without a canvas.
+  const [overrides, setOverrides] = useState(null)
+
+  const handleUpdate = useCallback(
+    (partial) => {
+      if (!partial || typeof partial !== 'object') return
+      if (typeof onUpdate === 'function') {
+        onUpdate(partial)
+        return
+      }
+      setOverrides((prev) => ({ ...(prev || {}), ...partial }))
+    },
+    [onUpdate],
+  )
+
+  const effectiveProps = useMemo(
+    () => (overrides ? { ...incomingProps, ...overrides } : incomingProps),
+    [incomingProps, overrides],
+  )
+
+  // Selection + drag offset (canvas-style chrome affordances).
+  const [selected, setSelected] = useState(false)
+  const [hovered, setHovered] = useState(false)
+  const [offset, setOffset] = useState({ x: 0, y: 0 })
+  const offsetRef = useRef(offset)
+  offsetRef.current = offset
+  const containerRef = useRef(null)
+
+  const selectWidget = useCallback(() => setSelected(true), [])
+
+  // Click anywhere outside the widget deselects it.
+  useEffect(() => {
+    if (!chrome || !selected) return undefined
+    const onDocPointerDown = (e) => {
+      if (containerRef.current && !containerRef.current.contains(e.target)) {
+        setSelected(false)
+      }
+    }
+    document.addEventListener('pointerdown', onDocPointerDown)
+    return () => document.removeEventListener('pointerdown', onDocPointerDown)
+  }, [chrome, selected])
+
+  // Shared drag/click handler. `fromHandle` distinguishes a click on the select
+  // handle (selects when no drag occurs) from a body drag.
+  const beginPointer = useCallback(
+    (e, fromHandle) => {
+      // Let interactive controls (inputs, links, resize handle…) keep working.
+      if (
+        !fromHandle &&
+        e.target.closest(
+          'input, textarea, select, button, a, [contenteditable="true"], [data-widget-resize-handle]',
+        )
+      ) {
+        return
+      }
+      if (fromHandle) e.stopPropagation()
+      if (!draggable && !fromHandle) return
+
+      const startX = e.clientX
+      const startY = e.clientY
+      const start = offsetRef.current
+      let moved = false
+
+      const move = (ev) => {
+        const dx = ev.clientX - startX
+        const dy = ev.clientY - startY
+        if (!moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return
+        moved = true
+        if (draggable) setOffset({ x: start.x + dx, y: start.y + dy })
+      }
+      const up = () => {
+        document.removeEventListener('pointermove', move)
+        document.removeEventListener('pointerup', up)
+        if (fromHandle && !moved) selectWidget()
+      }
+      document.addEventListener('pointermove', move)
+      document.addEventListener('pointerup', up)
+    },
+    [draggable, selectWidget],
+  )
+
+  const Component = getWidgetComponent(type)
+  if (!Component) {
+    if (typeof console !== 'undefined') {
+      console.warn(`[storyboard] <Widget>: unknown widget type "${type}"`)
+    }
+    return null
+  }
+
+  const elementProps = {
+    id: widgetId,
+    props: effectiveProps,
+    onUpdate: handleUpdate,
+    resizable: !!resizable,
+    selected: chrome ? selected : false,
+    onSelect: chrome ? selectWidget : () => {},
+  }
+  if (isForwardRef(Component)) {
+    elementProps.ref = ref
+  }
+
+  const containerStyle = {
+    ...style,
+    ...(draggable
+      ? {
+          transform: `translate(${offset.x}px, ${offset.y}px)`,
+          touchAction: 'none',
+        }
+      : null),
+  }
+
+  const showHandle = chrome && (hovered || selected)
+
+  return (
+    <div
+      ref={containerRef}
+      className={[
+        styles.widget,
+        chrome ? styles.chromeContainer : '',
+        draggable ? styles.draggable : '',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      style={containerStyle}
+      data-widget-type={type}
+      data-widget-selected={chrome && selected ? '' : undefined}
+      onPointerDown={draggable ? (e) => beginPointer(e, false) : undefined}
+      onClick={chrome ? selectWidget : undefined}
+      onMouseEnter={chrome ? () => setHovered(true) : undefined}
+      onMouseLeave={chrome ? () => setHovered(false) : undefined}
+    >
+      <div
+        className={[styles.widgetSlot, chrome && selected ? styles.widgetSlotSelected : '']
+          .filter(Boolean)
+          .join(' ')}
+      >
+        {createElement(Component, elementProps)}
+      </div>
+
+      {chrome && (
+        <div className={styles.toolbar}>
+          <span
+            className={`${styles.triggerDot} ${showHandle ? styles.triggerDotHidden : ''}`}
+            aria-hidden="true"
+          />
+          <div className={`${styles.toolbarContent} ${showHandle ? styles.toolbarContentVisible : ''}`}>
+            <button
+              type="button"
+              className={`${styles.selectHandle} ${selected ? styles.selectHandleActive : ''} ${
+                draggable ? styles.selectHandleDraggable : ''
+              }`}
+              onPointerDown={(e) => beginPointer(e, true)}
+              aria-label={
+                selected ? (draggable ? 'Drag to move widget' : 'Widget selected') : 'Select widget'
+              }
+              aria-pressed={selected}
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default forwardRef(Widget)

package/src/internals/canvas/widgets/Widget.module.css

@@ -0,0 +1,132 @@
+/* <Widget> — page-embeddable canvas widget.
+   Mirrors the canvas WidgetChrome selection outline + drag/select handle,
+   minus the action menu. */
+
+.widget {
+  display: inline-block;
+  position: relative;
+  max-width: 100%;
+}
+
+.chromeContainer {
+  position: relative;
+}
+
+.draggable {
+  user-select: none;
+}
+
+/* Widget slot — selection outline targets this. */
+.widgetSlot {
+  position: relative;
+  border-radius: 4px;
+}
+
+.widgetSlotSelected {
+  outline: 4px solid var(--color-background-accent-emphasis, #2f81f7);
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+/* Toolbar — absolutely positioned below the widget so it never affects the
+   widget's box dimensions. */
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  height: 28px;
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + 10px);
+}
+
+/* Invisible hit-area bridging the 10px gap so hover survives the pointer
+   crossing the padding between the widget and its handle. */
+.toolbar::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 100%;
+  height: 10px;
+  pointer-events: auto;
+}
+
+/* Trigger dot — visible at rest, hidden once the handle is revealed. */
+.triggerDot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--color-border-muted, #d0d7de);
+  opacity: 0.5;
+  margin-left: auto;
+  transition: opacity 120ms;
+}
+
+:global([data-sb-canvas-theme^='dark']) .triggerDot {
+  background: var(--color-border-muted, #373e47);
+  opacity: 0.6;
+}
+
+.triggerDotHidden {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Toolbar content — holds the select handle. */
+.toolbarContent {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 120ms;
+}
+
+.toolbarContentVisible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* Select handle — rounded rect. Click selects; drag (when draggable) moves. */
+.selectHandle {
+  all: unset;
+  cursor: pointer;
+  width: 16px;
+  height: 16px;
+  border-radius: 4px;
+  border: 1.6px solid var(--color-border-muted, #d0d7de);
+  background: var(--color-background, #ffffff);
+  transition: background 100ms, border-color 100ms;
+  flex-shrink: 0;
+}
+
+.selectHandleDraggable {
+  cursor: grab;
+}
+
+.selectHandleDraggable:active {
+  cursor: grabbing;
+}
+
+:global([data-sb-canvas-theme^='dark']) .selectHandle {
+  background: var(--color-background-muted, #161b22);
+  border-color: var(--color-border-muted, #373e47);
+}
+
+.selectHandle:hover {
+  border-color: var(--color-background-accent-emphasis, #2f81f7);
+}
+
+.selectHandleActive,
+:global([data-sb-canvas-theme^='dark']) .selectHandleActive {
+  background: var(--color-background-accent-emphasis, #2f81f7);
+  border-color: var(--color-background-accent-emphasis, #2f81f7);
+}
+
+.selectHandleActive:hover,
+:global([data-sb-canvas-theme^='dark']) .selectHandleActive:hover {
+  background: var(--color-background-accent-emphasis, #388bfd);
+  border-color: var(--color-background-accent-emphasis, #388bfd);
+}

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

@@ -0,0 +1,186 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import Widget from './Widget.jsx'
+import {
+  registerWidget,
+  _resetWidgetRegistry,
+} from '../../../core/stores/widgetRegistry.js'
+
+afterEach(() => {
+  _resetWidgetRegistry()
+  vi.restoreAllMocks()
+})
+
+// A minimal probe widget that renders its props and exposes onUpdate so we can
+// assert the standard contract the dispatcher supplies.
+function ProbeWidget({ id, props, onUpdate, resizable }) {
+  return (
+    <div data-testid="probe" data-id={id} data-resizable={String(resizable)}>
+      <span data-testid="text">{props?.text ?? ''}</span>
+      <span data-testid="width">{String(props?.width ?? '')}</span>
+      <button type="button" onClick={() => onUpdate({ text: 'updated' })}>
+        update
+      </button>
+    </div>
+  )
+}
+
+describe('<Widget>', () => {
+  it('resolves a registered type and maps non-reserved props into the widget props object', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    render(<Widget type="probe" text="hello" width={320} />)
+
+    expect(screen.getByTestId('probe')).toBeInTheDocument()
+    expect(screen.getByTestId('text').textContent).toBe('hello')
+    expect(screen.getByTestId('width').textContent).toBe('320')
+  })
+
+  it('applies className and data-widget-type to the wrapper', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(
+      <Widget type="probe" className="my-class" text="x" />,
+    )
+
+    const wrapper = container.querySelector('[data-widget-type="probe"]')
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.className).toContain('my-class')
+  })
+
+  it('forwards the resizable prop to the widget', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    render(<Widget type="probe" resizable text="x" />)
+    expect(screen.getByTestId('probe').getAttribute('data-resizable')).toBe('true')
+
+    _resetWidgetRegistry()
+    registerWidget('probe', { component: ProbeWidget })
+    render(<Widget type="probe" text="y" />)
+    const probes = screen.getAllByTestId('probe')
+    expect(probes[probes.length - 1].getAttribute('data-resizable')).toBe('false')
+  })
+
+  it('defaults onUpdate to internal local state (uncontrolled)', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    render(<Widget type="probe" text="initial" />)
+    expect(screen.getByTestId('text').textContent).toBe('initial')
+
+    fireEvent.click(screen.getByText('update'))
+    expect(screen.getByTestId('text').textContent).toBe('updated')
+  })
+
+  it('uses a consumer-supplied onUpdate when provided (controlled)', () => {
+    registerWidget('probe', { component: ProbeWidget })
+    const onUpdate = vi.fn()
+
+    render(<Widget type="probe" text="initial" onUpdate={onUpdate} />)
+    fireEvent.click(screen.getByText('update'))
+
+    expect(onUpdate).toHaveBeenCalledWith({ text: 'updated' })
+    // Controlled: local state is not applied, text stays as the incoming prop.
+    expect(screen.getByTestId('text').textContent).toBe('initial')
+  })
+
+  it('does not forward reserved props into the widget props object', () => {
+    function PropsSpy({ props }) {
+      return <pre data-testid="json">{JSON.stringify(props)}</pre>
+    }
+    registerWidget('spy', { component: PropsSpy })
+
+    render(
+      <Widget
+        type="spy"
+        id="fixed-id"
+        className="c"
+        draggable
+        resizable
+        text="keep"
+      />,
+    )
+
+    const parsed = JSON.parse(screen.getByTestId('json').textContent)
+    expect(parsed).toEqual({ text: 'keep' })
+  })
+
+  it('renders nothing and warns for an unknown type', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { container } = render(<Widget type="does-not-exist" />)
+
+    expect(container.firstChild).toBeNull()
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('unknown widget type "does-not-exist"'),
+    )
+  })
+
+  it('applies a translate transform to the wrapper when draggable is set', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" draggable text="x" />)
+    const wrapper = container.querySelector('[data-widget-type="probe"]')
+    expect(wrapper.style.transform).toContain('translate(')
+  })
+
+  it('renders the chrome select handle by default and selects on handle click', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" text="x" />)
+    const handle = container.querySelector('[aria-label="Select widget"]')
+    expect(handle).toBeTruthy()
+    expect(handle.getAttribute('aria-pressed')).toBe('false')
+
+    // pointerDown without movement selects on pointerUp.
+    fireEvent.pointerDown(handle, { clientX: 0, clientY: 0 })
+    fireEvent.pointerUp(document, { clientX: 0, clientY: 0 })
+
+    expect(container.querySelector('[aria-pressed="true"]')).toBeTruthy()
+    expect(container.querySelector('[data-widget-selected]')).toBeTruthy()
+  })
+
+  it('selects when clicking anywhere on the widget body', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" text="x" />)
+    expect(container.querySelector('[data-widget-selected]')).toBeNull()
+
+    fireEvent.click(screen.getByTestId('probe'))
+    expect(container.querySelector('[data-widget-selected]')).toBeTruthy()
+  })
+
+  it('deselects when clicking outside the widget', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(
+      <div>
+        <Widget type="probe" text="x" />
+        <button type="button">outside</button>
+      </div>,
+    )
+
+    fireEvent.click(screen.getByTestId('probe'))
+    expect(container.querySelector('[data-widget-selected]')).toBeTruthy()
+
+    fireEvent.pointerDown(screen.getByText('outside'))
+    expect(container.querySelector('[data-widget-selected]')).toBeNull()
+  })
+
+  it('omits chrome (no handle, no selection) when chrome={false}', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" chrome={false} text="x" />)
+    expect(container.querySelector('[aria-label="Select widget"]')).toBeNull()
+    expect(screen.getByTestId('probe')).toBeInTheDocument()
+  })
+
+  it('does not forward the chrome prop into the widget props object', () => {
+    function PropsSpy({ props }) {
+      return <pre data-testid="json">{JSON.stringify(props)}</pre>
+    }
+    registerWidget('spy', { component: PropsSpy })
+
+    render(<Widget type="spy" chrome text="keep" />)
+    const parsed = JSON.parse(screen.getByTestId('json').textContent)
+    expect(parsed).toEqual({ text: 'keep' })
+  })
+})

package/src/internals/index.js

@@ -62,6 +62,10 @@ export { default as AuthModal } from './AuthModal/AuthModal.jsx'
 export { default as CanvasPage } from './canvas/CanvasPage.jsx'
 export { useCanvas } from './canvas/useCanvas.js'
 
+// Widget — render any registered canvas widget inside a normal React page.
+export { default as Widget } from './canvas/widgets/Widget.jsx'
+export { getWidgetComponent } from './canvas/widgets/index.js'
+
 // Error boundaries
 export { default as PrototypeErrorBoundary, ImportErrorFallback, AppErrorBoundary } from './PrototypeErrorBoundary.jsx'