@dfosco/storyboard-react 3.11.0-beta.6 → 3.11.0-beta.7

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "3.11.0-beta.6",
+  "version": "3.11.0-beta.7",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "3.11.0-beta.6",
-    "@dfosco/tiny-canvas": "3.11.0-beta.6",
+    "@dfosco/storyboard-core": "3.11.0-beta.7",
+    "@dfosco/tiny-canvas": "3.11.0-beta.7",
     "@neodrag/react": "^2.3.1",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1"

package/src/Viewfinder.jsx

@@ -45,9 +45,11 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
         showThumbnails,
         hideDefaultFlow: shouldHideDefault,
       })
-      // Reveal after CSS has been processed to prevent FOUC
-      requestAnimationFrame(() => {
-        if (containerRef.current) containerRef.current.style.opacity = '1'
+      // Wait for styles to be fully loaded before revealing
+      handleRef.current.ready.then(() => {
+        requestAnimationFrame(() => {
+          if (containerRef.current) containerRef.current.style.opacity = '1'
+        })
       })
     })
 

package/src/canvas/CanvasPage.jsx

@@ -224,6 +224,7 @@ function WidgetRenderer({ widget, onUpdate, widgetRef }) {
 function ChromeWrappedWidget({
   widget,
   selected,
+  multiSelected,
   onSelect,
   onDeselect,
   onUpdate,
@@ -248,6 +249,7 @@ function ChromeWrappedWidget({
       widgetType={widget.type}
       features={features}
       selected={selected}
+      multiSelected={multiSelected}
       widgetProps={widget.props}
       widgetRef={widgetRef}
       onSelect={onSelect}
@@ -278,7 +280,7 @@ export default function CanvasPage({ name }) {
   // Local mutable copy of widgets for instant UI updates
   const [localWidgets, setLocalWidgets] = useState(canvas?.widgets ?? null)
   const [trackedCanvas, setTrackedCanvas] = useState(canvas)
-  const [selectedWidgetId, setSelectedWidgetId] = useState(null)
+  const [selectedWidgetIds, setSelectedWidgetIds] = useState(() => new Set())
   const initialViewport = loadViewportState(name)
   const [zoom, setZoom] = useState(initialViewport?.zoom ?? 100)
   const zoomRef = useRef(initialViewport?.zoom ?? 100)
@@ -307,6 +309,92 @@ export default function CanvasPage({ name }) {
     return writeQueueRef.current
   }
 
+  // Ref for selectedWidgetIds to avoid stale closures in callbacks
+  const selectedIdsRef = useRef(selectedWidgetIds)
+  useEffect(() => {
+    selectedIdsRef.current = selectedWidgetIds
+  }, [selectedWidgetIds])
+
+  const isMultiSelected = selectedWidgetIds.size > 1
+
+  /**
+   * Selection handler — shift+click toggles in/out of multi-select set,
+   * plain click single-selects (clears others).
+   */
+  const handleWidgetSelect = useCallback((widgetId, shiftKey) => {
+    if (shiftKey) {
+      setSelectedWidgetIds(prev => {
+        const next = new Set(prev)
+        if (next.has(widgetId)) {
+          next.delete(widgetId)
+        } else {
+          next.add(widgetId)
+        }
+        return next
+      })
+    } else {
+      setSelectedWidgetIds(new Set([widgetId]))
+    }
+  }, [])
+
+  // --- Multi-select live drag preview via imperative DOM transforms ---
+  // On drag start, snapshot ALL articles' translate values (same coord space).
+  // On each tick, read dragged article's current translate, compute delta
+  // from its snapshot, apply same delta to all peers.
+  const draggedArticleRef = useRef(null)
+  const draggedStartTranslate = useRef({ x: 0, y: 0 })
+  const peerSnapshots = useRef(new Map())
+
+  function parseTranslate(article) {
+    const raw = article?.style.translate || '0px 0px'
+    const parts = raw.match(/-?[\d.]+/g) || [0, 0]
+    return { x: parseFloat(parts[0]) || 0, y: parseFloat(parts[1]) || 0 }
+  }
+
+  const handleItemDragStart = useCallback((dragId) => {
+    const ids = selectedIdsRef.current
+    peerSnapshots.current.clear()
+    draggedArticleRef.current = null
+    if (ids.size <= 1 || !ids.has(dragId)) return
+
+    // Snapshot dragged widget's article translate
+    const draggedEl = document.getElementById(dragId)
+    const draggedArticle = draggedEl?.closest('article')
+    if (!draggedArticle) return
+    draggedArticleRef.current = draggedArticle
+    draggedStartTranslate.current = parseTranslate(draggedArticle)
+
+    // Snapshot each peer's article translate
+    for (const id of ids) {
+      if (id === dragId) continue
+      const widgetEl = document.getElementById(id)
+      const article = widgetEl?.closest('article')
+      if (!article) continue
+      peerSnapshots.current.set(id, {
+        article,
+        ...parseTranslate(article),
+      })
+    }
+  }, [])
+
+  const handleItemDrag = useCallback(() => {
+    if (!draggedArticleRef.current) return
+
+    // Read dragged article's CURRENT translate (set by neodrag)
+    const current = parseTranslate(draggedArticleRef.current)
+    const dx = current.x - draggedStartTranslate.current.x
+    const dy = current.y - draggedStartTranslate.current.y
+
+    for (const [, peer] of peerSnapshots.current) {
+      peer.article.style.translate = `${peer.x + dx}px ${peer.y + dy}px`
+    }
+  }, [])
+
+  const clearDragPreview = useCallback(() => {
+    peerSnapshots.current.clear()
+    draggedArticleRef.current = null
+  }, [])
+
   if (canvas !== trackedCanvas) {
     setTrackedCanvas(canvas)
     setLocalWidgets(canvas?.widgets ?? null)
@@ -447,6 +535,44 @@ export default function CanvasPage({ name }) {
       return
     }
 
+    const ids = selectedIdsRef.current
+    // Multi-select move: apply same delta to all selected widgets
+    if (ids.size > 1 && ids.has(dragId)) {
+      clearDragPreview()
+      undoRedo.snapshot(stateRef.current, 'multi-move')
+      const currentWidgets = stateRef.current.widgets ?? []
+      const draggedWidget = currentWidgets.find(w => w.id === dragId)
+      if (!draggedWidget) return
+      const oldPos = draggedWidget.position || { x: 0, y: 0 }
+      const dx = rounded.x - oldPos.x
+      const dy = rounded.y - oldPos.y
+
+      debouncedSave.cancel()
+      setLocalWidgets((prev) => {
+        if (!prev) return prev
+        const next = prev.map((w) => {
+          if (w.id === dragId) return { ...w, position: rounded }
+          if (ids.has(w.id)) {
+            return {
+              ...w,
+              position: {
+                x: Math.max(0, roundPosition((w.position?.x ?? 0) + dx)),
+                y: Math.max(0, roundPosition((w.position?.y ?? 0) + dy)),
+              },
+            }
+          }
+          return w
+        })
+        queueWrite(() =>
+          updateCanvas(name, { widgets: next }).catch((err) =>
+            console.error('[canvas] Failed to save multi-move:', err)
+          )
+        )
+        return next
+      })
+      return
+    }
+
     undoRedo.snapshot(stateRef.current, 'move', dragId)
     setLocalWidgets((prev) => {
       if (!prev) return prev
@@ -460,7 +586,7 @@ export default function CanvasPage({ name }) {
       )
       return next
     })
-  }, [name, undoRedo])
+  }, [name, undoRedo, debouncedSave, clearDragPreview])
 
   useEffect(() => {
     zoomRef.current = zoom
@@ -780,22 +906,39 @@ export default function CanvasPage({ name }) {
 
   useEffect(() => {
     function handleKeyDown(e) {
-      if (!selectedWidgetId) return
+      if (selectedWidgetIds.size === 0) return
       const tag = e.target.tagName
       if (tag === 'INPUT' || tag === 'TEXTAREA' || e.target.isContentEditable) return
       if (e.key === 'Escape') {
         e.preventDefault()
-        setSelectedWidgetId(null)
+        setSelectedWidgetIds(new Set())
       }
       if (e.key === 'Delete' || e.key === 'Backspace') {
         e.preventDefault()
-        handleWidgetRemove(selectedWidgetId)
-        setSelectedWidgetId(null)
+        if (selectedWidgetIds.size > 1) {
+          // Multi-delete — snapshot once, remove all, persist via updateCanvas
+          undoRedo.snapshot(stateRef.current, 'multi-remove')
+          debouncedSave.cancel()
+          setLocalWidgets((prev) => {
+            if (!prev) return prev
+            const next = prev.filter(w => !selectedWidgetIds.has(w.id))
+            queueWrite(() =>
+              updateCanvas(name, { widgets: next }).catch(err =>
+                console.error('[canvas] Failed to save multi-delete:', err)
+              )
+            )
+            return next
+          })
+        } else {
+          const widgetId = [...selectedWidgetIds][0]
+          if (widgetId) handleWidgetRemove(widgetId)
+        }
+        setSelectedWidgetIds(new Set())
       }
     }
     document.addEventListener('keydown', handleKeyDown)
     return () => document.removeEventListener('keydown', handleKeyDown)
-  }, [selectedWidgetId, handleWidgetRemove])
+  }, [selectedWidgetIds, handleWidgetRemove, undoRedo, name, debouncedSave])
 
   // Paste handler — images become image widgets, same-origin URLs become prototypes,
   // other URLs become link previews, text becomes markdown
@@ -1120,6 +1263,7 @@ export default function CanvasPage({ name }) {
     colorMode: canvas.colorMode === 'auto'
       ? getToolbarColorMode(canvasTheme)
       : (canvas.colorMode ?? 'auto'),
+    locked: !isLocalDev,
   }
 
   const canvasThemeVars = getCanvasThemeVars(canvasTheme)
@@ -1146,20 +1290,22 @@ export default function CanvasPage({ name }) {
           id={`jsx-${exportName}`}
           data-tc-x={sourcePosition.x}
           data-tc-y={sourcePosition.y}
-          {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle' } : {})}
+          {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle, .tc-drag-surface' } : {})}
           {...canvasPrimerAttrs}
           style={canvasThemeVars}
           onClick={isLocalDev ? (e) => {
             e.stopPropagation()
-            setSelectedWidgetId(`jsx-${exportName}`)
+            if (!e.target.closest('.tc-drag-handle')) {
+              handleWidgetSelect(`jsx-${exportName}`, e.shiftKey)
+            }
           } : undefined}
         >
           <WidgetChrome
             widgetId={`jsx-${exportName}`}
             features={componentFeatures}
-            selected={selectedWidgetId === `jsx-${exportName}`}
-            onSelect={() => setSelectedWidgetId(`jsx-${exportName}`)}
-            onDeselect={() => setSelectedWidgetId(null)}
+            selected={selectedWidgetIds.has(`jsx-${exportName}`)}
+            onSelect={(shiftKey) => handleWidgetSelect(`jsx-${exportName}`, shiftKey)}
+            onDeselect={() => setSelectedWidgetIds(new Set())}
             readOnly={!isLocalDev}
           >
             <ComponentWidget
@@ -1182,24 +1328,27 @@ export default function CanvasPage({ name }) {
         id={widget.id}
         data-tc-x={widget?.position?.x ?? 0}
         data-tc-y={widget?.position?.y ?? 0}
-        {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle' } : {})}
+        {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle, .tc-drag-surface' } : {})}
         {...canvasPrimerAttrs}
         style={canvasThemeVars}
         onClick={isLocalDev ? (e) => {
           e.stopPropagation()
-          setSelectedWidgetId(widget.id)
+          if (!e.target.closest('.tc-drag-handle')) {
+            handleWidgetSelect(widget.id, e.shiftKey)
+          }
         } : undefined}
       >
         <ChromeWrappedWidget
           widget={widget}
-          selected={selectedWidgetId === widget.id}
-          onSelect={() => setSelectedWidgetId(widget.id)}
-          onDeselect={() => setSelectedWidgetId(null)}
+          selected={selectedWidgetIds.has(widget.id)}
+          multiSelected={isMultiSelected && selectedWidgetIds.has(widget.id)}
+          onSelect={(shiftKey) => handleWidgetSelect(widget.id, shiftKey)}
+          onDeselect={() => setSelectedWidgetIds(new Set())}
           onUpdate={isLocalDev ? handleWidgetUpdate : undefined}
           onCopy={isLocalDev ? handleWidgetCopy : undefined}
           onRemove={isLocalDev ? (id) => {
             handleWidgetRemove(id)
-            setSelectedWidgetId(null)
+            setSelectedWidgetIds(new Set())
           } : undefined}
           readOnly={!isLocalDev}
         />
@@ -1240,7 +1389,7 @@ export default function CanvasPage({ name }) {
           ...canvasThemeVars,
           ...(spaceHeld ? { cursor: panningActive ? 'grabbing' : 'grab' } : {}),
         }}
-        onClick={() => setSelectedWidgetId(null)}
+        onClick={() => setSelectedWidgetIds(new Set())}
         onMouseDown={handlePanStart}
       >
         <div
@@ -1255,7 +1404,7 @@ export default function CanvasPage({ name }) {
             ...(spaceHeld ? { pointerEvents: 'none' } : {}),
           }}
         >
-          <Canvas {...canvasProps} onDragEnd={isLocalDev ? handleItemDragEnd : undefined}>
+          <Canvas {...canvasProps} onDragStart={isLocalDev ? handleItemDragStart : undefined} onDrag={isLocalDev ? handleItemDrag : undefined} onDragEnd={isLocalDev ? handleItemDragEnd : undefined}>
             {allChildren}
           </Canvas>
         </div>

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

@@ -0,0 +1,259 @@
+import { fireEvent, render, screen, act } from '@testing-library/react'
+import CanvasPage from './CanvasPage.jsx'
+import { updateCanvas, removeWidget } from './canvasApi.js'
+
+const MOCK_UNDO_REDO = {
+  snapshot: vi.fn(),
+  undo: vi.fn(),
+  redo: vi.fn(),
+  reset: vi.fn(),
+  canUndo: false,
+  canRedo: false,
+}
+
+vi.mock('./useUndoRedo.js', () => ({
+  default: () => MOCK_UNDO_REDO,
+}))
+
+// Expose onDragEnd so tests can trigger drags with specific IDs
+let capturedOnDragEnd = null
+vi.mock('@dfosco/tiny-canvas', () => ({
+  Canvas: ({ children, onDragEnd }) => {
+    capturedOnDragEnd = onDragEnd
+    return <div data-testid="tiny-canvas">{children}</div>
+  },
+}))
+
+const mockCanvas = {
+  title: 'Multi-Select Test',
+  widgets: [
+    { id: 'w1', type: 'sticky-note', position: { x: 100, y: 100 }, props: {} },
+    { id: 'w2', type: 'sticky-note', position: { x: 300, y: 100 }, props: {} },
+    { id: 'w3', type: 'markdown', position: { x: 500, y: 200 }, props: {} },
+  ],
+  sources: [],
+  centered: false,
+  dotted: false,
+  grid: false,
+  gridSize: 18,
+  colorMode: 'auto',
+}
+
+vi.mock('./useCanvas.js', () => ({
+  useCanvas: () => ({
+    canvas: mockCanvas,
+    jsxExports: null,
+    loading: false,
+  }),
+}))
+
+vi.mock('./widgets/index.js', () => ({
+  getWidgetComponent: () => function MockWidget({ id }) {
+    return <div data-testid={`widget-content-${id}`}>widget</div>
+  },
+}))
+
+// WidgetChrome mock that exposes onSelect with shift parameter
+vi.mock('./widgets/WidgetChrome.jsx', () => ({
+  default: ({ children, onSelect, selected, multiSelected, widgetId }) => (
+    <div
+      data-testid={`chrome-${widgetId}`}
+      data-selected={selected || undefined}
+      data-multi-selected={multiSelected || undefined}
+    >
+      {children}
+      <button
+        className="tc-drag-handle"
+        data-testid={`select-${widgetId}`}
+        onClick={(e) => { e.stopPropagation(); onSelect?.(false) }}
+      >
+        select
+      </button>
+      <button
+        className="tc-drag-handle"
+        data-testid={`shift-select-${widgetId}`}
+        onClick={(e) => { e.stopPropagation(); onSelect?.(true) }}
+      >
+        shift-select
+      </button>
+    </div>
+  ),
+}))
+
+vi.mock('./widgets/widgetProps.js', () => ({
+  schemas: {},
+  getDefaults: () => ({}),
+}))
+
+vi.mock('./widgets/widgetConfig.js', () => ({
+  getFeatures: () => [],
+  schemas: {},
+  getMenuWidgetTypes: () => [],
+}))
+
+vi.mock('./widgets/figmaUrl.js', () => ({
+  isFigmaUrl: () => false,
+  sanitizeFigmaUrl: (url) => url,
+}))
+
+vi.mock('./canvasApi.js', () => ({
+  addWidget: vi.fn(),
+  updateCanvas: vi.fn(() => Promise.resolve({ success: true })),
+  removeWidget: vi.fn(() => Promise.resolve({ success: true })),
+  uploadImage: vi.fn(),
+}))
+
+describe('CanvasPage multi-select', () => {
+  beforeEach(() => {
+    delete window.__storyboardCanvasBridgeState
+    window.__SB_LOCAL_DEV__ = true
+    vi.clearAllMocks()
+    capturedOnDragEnd = null
+  })
+
+  afterEach(() => {
+    delete window.__SB_LOCAL_DEV__
+  })
+
+  it('shift+click on select handle adds widget to selection', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    // Select first widget
+    fireEvent.click(screen.getByTestId('select-w1'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+    expect(screen.getByTestId('chrome-w1').dataset.selected).toBeDefined()
+
+    // Shift+select second widget
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+    expect(screen.getByTestId('chrome-w1').dataset.selected).toBeDefined()
+    expect(screen.getByTestId('chrome-w2').dataset.selected).toBeDefined()
+  })
+
+  it('shift+click on already selected widget removes it from selection', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    // Select both
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+    expect(screen.getByTestId('chrome-w1').dataset.selected).toBeDefined()
+    expect(screen.getByTestId('chrome-w2').dataset.selected).toBeDefined()
+
+    // Shift+click w1 again to remove it
+    fireEvent.click(screen.getByTestId('shift-select-w1'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+    expect(screen.getByTestId('chrome-w1').dataset.selected).toBeUndefined()
+    expect(screen.getByTestId('chrome-w2').dataset.selected).toBeDefined()
+  })
+
+  it('normal click replaces multi-selection with single', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    // Multi-select
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+    fireEvent.click(screen.getByTestId('shift-select-w3'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    // Normal click on w1 clears multi-select
+    fireEvent.click(screen.getByTestId('select-w1'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+    expect(screen.getByTestId('chrome-w1').dataset.selected).toBeDefined()
+    expect(screen.getByTestId('chrome-w2').dataset.selected).toBeUndefined()
+    expect(screen.getByTestId('chrome-w3').dataset.selected).toBeUndefined()
+  })
+
+  it('sets multiSelected on all selected widgets when multiple are selected', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    expect(screen.getByTestId('chrome-w1').dataset.multiSelected).toBeDefined()
+    expect(screen.getByTestId('chrome-w2').dataset.multiSelected).toBeDefined()
+    // Unselected widget should not have multiSelected
+    expect(screen.getByTestId('chrome-w3').dataset.multiSelected).toBeUndefined()
+  })
+
+  it('Escape clears all selection', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    fireEvent.keyDown(document, { key: 'Escape' })
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    expect(screen.getByTestId('chrome-w1').dataset.selected).toBeUndefined()
+    expect(screen.getByTestId('chrome-w2').dataset.selected).toBeUndefined()
+  })
+
+  it('Delete removes all selected widgets and calls updateCanvas', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    // Multi-select w1 and w2
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    // Press Delete
+    fireEvent.keyDown(document, { key: 'Delete' })
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    // Should call updateCanvas with only w3 remaining
+    expect(updateCanvas).toHaveBeenCalledWith(
+      'test-canvas',
+      expect.objectContaining({
+        widgets: [expect.objectContaining({ id: 'w3' })],
+      })
+    )
+    // Should NOT use individual removeWidget API for multi-delete
+    expect(removeWidget).not.toHaveBeenCalled()
+    // Should snapshot for undo
+    expect(MOCK_UNDO_REDO.snapshot).toHaveBeenCalled()
+  })
+
+  it('single-select Delete uses removeWidget API', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.keyDown(document, { key: 'Backspace' })
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    expect(removeWidget).toHaveBeenCalledWith('test-canvas', 'w1')
+  })
+
+  it('multi-select move applies delta to all selected widgets', async () => {
+    render(<CanvasPage name="test-canvas" />)
+
+    // Multi-select w1 (100,100) and w2 (300,100)
+    fireEvent.click(screen.getByTestId('select-w1'))
+    fireEvent.click(screen.getByTestId('shift-select-w2'))
+
+    // Wait for selectedIdsRef to sync
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    // Drag w1 to (150, 200) → delta is (+50, +100)
+    expect(capturedOnDragEnd).toBeTruthy()
+    act(() => {
+      capturedOnDragEnd('w1', { x: 150, y: 200 })
+    })
+    await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+
+    // w1 → (150, 200), w2 → (300+50, 100+100) = (350, 200)
+    expect(updateCanvas).toHaveBeenCalledWith(
+      'test-canvas',
+      expect.objectContaining({
+        widgets: expect.arrayContaining([
+          expect.objectContaining({ id: 'w1', position: { x: 150, y: 200 } }),
+          expect.objectContaining({ id: 'w2', position: { x: 350, y: 200 } }),
+          // w3 unchanged
+          expect.objectContaining({ id: 'w3', position: { x: 500, y: 200 } }),
+        ]),
+      })
+    )
+  })
+})

package/src/canvas/useCanvas.js

@@ -9,7 +9,8 @@ async function fetchCanvasFromServer(name) {
   try {
     const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
     const res = await fetch(`${base}/_storyboard/canvas/read?name=${encodeURIComponent(name)}`)
-    if (res.ok) return res.json()
+    const contentType = res.headers.get('content-type') || ''
+    if (res.ok && contentType.includes('application/json')) return res.json()
   } catch { /* fall back to build-time data */ }
   return null
 }

package/src/canvas/widgets/FigmaEmbed.jsx

@@ -1,4 +1,5 @@
-import { forwardRef, useImperativeHandle, useMemo, useCallback, useState } from 'react'
+import { forwardRef, useImperativeHandle, useMemo, useCallback, useState, useEffect, useRef } from 'react'
+import { createPortal } from 'react-dom'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import { readProp } from './widgetProps.js'
 import { schemas } from './widgetConfig.js'
@@ -28,6 +29,11 @@ export default forwardRef(function FigmaEmbed({ props, onUpdate }, ref) {
   const height = readProp(props, 'height', figmaEmbedSchema)
 
   const [interactive, setInteractive] = useState(false)
+  const [expanded, setExpanded] = useState(false)
+
+  const iframeRef = useRef(null)
+  const inlineContainerRef = useRef(null)
+  const modalContainerRef = useRef(null)
 
   // Validate URL at render time — only embed known Figma URLs
   const isValid = useMemo(() => isFigmaUrl(url), [url])
@@ -38,15 +44,65 @@ export default forwardRef(function FigmaEmbed({ props, onUpdate }, ref) {
 
   const enterInteractive = useCallback(() => setInteractive(true), [])
 
+  // Close expanded modal on Escape
+  useEffect(() => {
+    if (!expanded) return
+    function handleKeyDown(e) {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        setExpanded(false)
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown, true)
+    return () => document.removeEventListener('keydown', handleKeyDown, true)
+  }, [expanded])
+
+  // Reparent iframe DOM node between inline container and modal.
+  // Uses moveBefore() (Chrome 133+) which preserves the iframe's
+  // browsing context — no reload. Falls back to appendChild.
+  useEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe) return
+
+    if (expanded && modalContainerRef.current) {
+      iframe._savedClassName = iframe.className
+      iframe._savedStyle = iframe.getAttribute('style') || ''
+      iframe.className = styles.expandIframe
+      iframe.removeAttribute('style')
+      const target = modalContainerRef.current
+      if (target.moveBefore) {
+        target.moveBefore(iframe, target.firstChild)
+      } else {
+        target.prepend(iframe)
+      }
+    } else if (!expanded && inlineContainerRef.current) {
+      if (iframe._savedClassName !== undefined) {
+        iframe.className = iframe._savedClassName
+        iframe.setAttribute('style', iframe._savedStyle)
+        delete iframe._savedClassName
+        delete iframe._savedStyle
+      }
+      const target = inlineContainerRef.current
+      if (target.moveBefore) {
+        target.moveBefore(iframe, null)
+      } else {
+        target.appendChild(iframe)
+      }
+    }
+  }, [expanded])
+
   useImperativeHandle(ref, () => ({
     handleAction(actionId) {
       if (actionId === 'open-external') {
         if (url) window.open(url, '_blank', 'noopener')
+      } else if (actionId === 'expand') {
+        setExpanded(true)
       }
     },
   }), [url])
 
   return (
+    <>
     <WidgetWrapper>
       <div className={styles.embed} style={{ width, height }}>
         <div className={styles.header}>
@@ -55,15 +111,20 @@ export default forwardRef(function FigmaEmbed({ props, onUpdate }, ref) {
         </div>
         {embedUrl ? (
           <>
-            <div className={styles.iframeContainer}>
+            <div
+              ref={inlineContainerRef}
+              className={styles.iframeContainer}
+              style={expanded ? { visibility: 'hidden' } : undefined}
+            >
               <iframe
+                ref={iframeRef}
                 src={embedUrl}
                 className={styles.iframe}
                 title={`Figma ${typeLabel}: ${title}`}
                 allowFullScreen
               />
             </div>
-            {!interactive && (
+            {!interactive && !expanded && (
               <div
                 className={styles.dragOverlay}
                 onDoubleClick={enterInteractive}
@@ -102,5 +163,31 @@ export default forwardRef(function FigmaEmbed({ props, onUpdate }, ref) {
         onPointerDown={(e) => e.stopPropagation()}
       />
     </WidgetWrapper>
+    {createPortal(
+      <div
+        className={styles.expandBackdrop}
+        style={expanded && embedUrl ? undefined : { display: 'none' }}
+        onClick={() => setExpanded(false)}
+        onPointerDown={(e) => e.stopPropagation()}
+        onKeyDown={(e) => e.stopPropagation()}
+        onWheel={(e) => e.stopPropagation()}
+      >
+        <div
+          ref={modalContainerRef}
+          className={styles.expandContainer}
+          onClick={(e) => e.stopPropagation()}
+        >
+          {/* iframe is reparented here via useEffect */}
+          <button
+            className={styles.expandClose}
+            onClick={() => setExpanded(false)}
+            aria-label="Close expanded view"
+            autoFocus
+          >✕</button>
+        </div>
+      </div>,
+      document.body
+    )}
+    </>
   )
 })

package/src/canvas/widgets/FigmaEmbed.module.css

@@ -36,7 +36,7 @@
 
 .iframeContainer {
   width: 100%;
-  height: calc(100% - 31px); /* subtract header height */
+  height: calc(100% - 10px); /* subtract header height */
   overflow: hidden;
 }
 
@@ -81,3 +81,67 @@
 .resizeHandle:hover {
   opacity: 1;
 }
+
+/* Expand modal — fullscreen overlay for expanded iframe */
+.expandBackdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 100000;
+  background: rgba(0, 0, 0, 0.8);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  animation: expandFadeIn 0.15s ease;
+}
+
+@keyframes expandFadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.expandContainer {
+  width: 90vw;
+  height: 90vh;
+  position: relative;
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--bgColor-default, #ffffff);
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.4);
+  animation: expandScaleIn 0.2s ease;
+}
+
+@keyframes expandScaleIn {
+  from { transform: scale(0.95); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+
+.expandIframe {
+  border: none;
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.expandClose {
+  all: unset;
+  cursor: pointer;
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 8px;
+  background: rgba(0, 0, 0, 0.5);
+  color: #ffffff;
+  font-size: 16px;
+  z-index: 1;
+  transition: background 100ms;
+  backdrop-filter: blur(4px);
+}
+
+.expandClose:hover {
+  background: rgba(0, 0, 0, 0.7);
+}

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -1,4 +1,5 @@
 import { useState, useRef, useEffect, useCallback, useMemo, forwardRef, useImperativeHandle } from 'react'
+import { createPortal } from 'react-dom'
 import { buildPrototypeIndex } from '@dfosco/storyboard-core'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import { readProp, prototypeEmbedSchema } from './widgetProps.js'
@@ -51,12 +52,15 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
 
   const [editing, setEditing] = useState(false)
   const [interactive, setInteractive] = useState(false)
+  const [expanded, setExpanded] = useState(false)
   const [filter, setFilter] = useState('')
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
   const inputRef = useRef(null)
   const filterRef = useRef(null)
   const embedRef = useRef(null)
   const iframeRef = useRef(null)
+  const inlineContainerRef = useRef(null)
+  const modalContainerRef = useRef(null)
 
   const iframeSrc = useMemo(() => {
     if (!rawSrc) return ''
@@ -178,6 +182,54 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
     return () => document.removeEventListener('storyboard:theme:changed', readToolbarTheme)
   }, [])
 
+  // Close expanded modal on Escape
+  useEffect(() => {
+    if (!expanded) return
+    function handleKeyDown(e) {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        setExpanded(false)
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown, true)
+    return () => document.removeEventListener('keydown', handleKeyDown, true)
+  }, [expanded])
+
+  // Reparent iframe DOM node between inline container and modal.
+  // Uses moveBefore() (Chrome 133+) which preserves the iframe's
+  // browsing context — no reload. Falls back to appendChild which
+  // will reload but still works functionally.
+  useEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe) return
+
+    if (expanded && modalContainerRef.current) {
+      iframe._savedClassName = iframe.className
+      iframe._savedStyle = iframe.getAttribute('style') || ''
+      iframe.className = styles.expandIframe
+      iframe.removeAttribute('style')
+      const target = modalContainerRef.current
+      if (target.moveBefore) {
+        target.moveBefore(iframe, target.firstChild)
+      } else {
+        target.prepend(iframe)
+      }
+    } else if (!expanded && inlineContainerRef.current) {
+      if (iframe._savedClassName !== undefined) {
+        iframe.className = iframe._savedClassName
+        iframe.setAttribute('style', iframe._savedStyle)
+        delete iframe._savedClassName
+        delete iframe._savedStyle
+      }
+      const target = inlineContainerRef.current
+      if (target.moveBefore) {
+        target.moveBefore(iframe, null)
+      } else {
+        target.appendChild(iframe)
+      }
+    }
+  }, [expanded])
+
   // Listen for navigation events from the embedded prototype iframe
   useEffect(() => {
     function handleMessage(e) {
@@ -202,6 +254,8 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
     handleAction(actionId) {
       if (actionId === 'edit') {
         setEditing(true)
+      } else if (actionId === 'expand') {
+        setExpanded(true)
       } else if (actionId === 'open-external') {
         if (rawSrc) window.open(rawSrc, '_blank', 'noopener')
       } else if (actionId === 'zoom-in') {
@@ -234,6 +288,7 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
   }
 
   return (
+    <>
     <WidgetWrapper>
       <div
         ref={embedRef}
@@ -323,7 +378,11 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
           </div>
         ) : iframeSrc ? (
           <>
-            <div className={styles.iframeContainer}>
+            <div
+              ref={inlineContainerRef}
+              className={styles.iframeContainer}
+              style={expanded ? { visibility: 'hidden' } : undefined}
+            >
               <iframe
                 ref={iframeRef}
                 src={iframeSrc}
@@ -338,7 +397,7 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
                 sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
               />
             </div>
-            {!interactive && (
+            {!interactive && !expanded && (
               <div
                 className={styles.dragOverlay}
                 onDoubleClick={enterInteractive}
@@ -381,5 +440,31 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
         onPointerDown={(e) => e.stopPropagation()}
       />
     </WidgetWrapper>
+    {createPortal(
+      <div
+        className={styles.expandBackdrop}
+        style={expanded ? undefined : { display: 'none' }}
+        onClick={() => setExpanded(false)}
+        onPointerDown={(e) => e.stopPropagation()}
+        onKeyDown={(e) => e.stopPropagation()}
+        onWheel={(e) => e.stopPropagation()}
+      >
+        <div
+          ref={modalContainerRef}
+          className={styles.expandContainer}
+          onClick={(e) => e.stopPropagation()}
+        >
+          {/* iframe is reparented here via useEffect */}
+          <button
+            className={styles.expandClose}
+            onClick={() => setExpanded(false)}
+            aria-label="Close expanded view"
+            autoFocus
+          >✕</button>
+        </div>
+      </div>,
+      document.body
+    )}
+    </>
   )
 })

package/src/canvas/widgets/PrototypeEmbed.module.css

@@ -150,7 +150,7 @@
 }
 
 .pickerItem:focus-visible {
-  outline: 2px solid var(--bgColor-accent-emphasis, #2f81f7);
+  outline: 4px solid var(--bgColor-accent-emphasis, #2f81f7);
   outline-offset: -2px;
 }
 
@@ -326,3 +326,67 @@
   border-right: 1.5px solid var(--trigger-border, var(--borderColor-muted, #d0d7de));
   user-select: none;
 }
+
+/* Expand modal — fullscreen overlay for expanded iframe */
+.expandBackdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 100000;
+  background: rgba(0, 0, 0, 0.8);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  animation: expandFadeIn 0.15s ease;
+}
+
+@keyframes expandFadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.expandContainer {
+  width: 90vw;
+  height: 90vh;
+  position: relative;
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--bgColor-default, #ffffff);
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.4);
+  animation: expandScaleIn 0.2s ease;
+}
+
+@keyframes expandScaleIn {
+  from { transform: scale(0.95); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+
+.expandIframe {
+  border: none;
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.expandClose {
+  all: unset;
+  cursor: pointer;
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 8px;
+  background: rgba(0, 0, 0, 0.5);
+  color: #ffffff;
+  font-size: 16px;
+  z-index: 1;
+  transition: background 100ms;
+  backdrop-filter: blur(4px);
+}
+
+.expandClose:hover {
+  background: rgba(0, 0, 0, 0.7);
+}

package/src/canvas/widgets/WidgetChrome.jsx

@@ -102,6 +102,14 @@ function DownloadIcon() {
   )
 }
 
+function ExpandIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+      <path d="M1.75 10a.75.75 0 0 1 .75.75v2.5c0 .138.112.25.25.25h2.5a.75.75 0 0 1 0 1.5h-2.5A1.75 1.75 0 0 1 1 13.25v-2.5a.75.75 0 0 1 .75-.75Zm12.5 0a.75.75 0 0 1 .75.75v2.5A1.75 1.75 0 0 1 13.25 15h-2.5a.75.75 0 0 1 0-1.5h2.5a.25.25 0 0 0 .25-.25v-2.5a.75.75 0 0 1 .75-.75ZM2.75 1h2.5a.75.75 0 0 1 0 1.5h-2.5a.25.25 0 0 0-.25.25v2.5a.75.75 0 0 1-1.5 0v-2.5C1 1.784 1.784 1 2.75 1Zm10.5 0C14.216 1 15 1.784 15 2.75v2.5a.75.75 0 0 1-1.5 0v-2.5a.25.25 0 0 0-.25-.25h-2.5a.75.75 0 0 1 0-1.5Z" />
+    </svg>
+  )
+}
+
 /** Icon registry — maps icon name strings from config to React components. */
 const ICON_REGISTRY = {
   'trash': DeleteIcon,
@@ -116,6 +124,7 @@ const ICON_REGISTRY = {
   'more': MoreIcon,
   'chevron-down': ChevronDownIcon,
   'download': DownloadIcon,
+  'expand': ExpandIcon,
 }
 
 /** Danger-styled actions in the overflow menu. */
@@ -304,6 +313,7 @@ export default function WidgetChrome({
   widgetId,
   features = [],
   selected = false,
+  multiSelected = false,
   widgetProps,
   widgetRef,
   onSelect,
@@ -315,7 +325,6 @@ export default function WidgetChrome({
 }) {
   const [hovered, setHovered] = useState(false)
   const leaveTimer = useRef(null)
-  const pointerStartPos = useRef(null)
 
   const handleMouseEnter = useCallback(() => {
     clearTimeout(leaveTimer.current)
@@ -326,19 +335,12 @@ export default function WidgetChrome({
     leaveTimer.current = setTimeout(() => setHovered(false), 80)
   }, [])
 
-  // Track pointer position on the handle to distinguish click from drag.
-  const handleHandlePointerDown = useCallback((e) => {
-    pointerStartPos.current = { x: e.clientX, y: e.clientY }
-  }, [])
-
-  const handleHandlePointerUp = useCallback((e) => {
-    if (!pointerStartPos.current) return
-    const start = pointerStartPos.current
-    pointerStartPos.current = null
-    const dist = Math.hypot(e.clientX - start.x, e.clientY - start.y)
-    if (dist > 10) return
+  // Handle select via click — pointer events are intercepted by the drag
+  // gate in Draggable, so onPointerDown never reaches React on the handle.
+  // onClick fires reliably after pointer up.
+  const handleHandleClick = useCallback((e) => {
     e.stopPropagation()
-    onSelect?.()
+    onSelect?.(e.shiftKey)
   }, [onSelect])
 
   const handleActionClick = useCallback((actionId, e) => {
@@ -362,6 +364,7 @@ export default function WidgetChrome({
   }, [onUpdate])
 
   const showToolbar = !readOnly && (hovered || selected)
+  const showFeatures = showToolbar && !multiSelected
 
   return (
     <div
@@ -369,7 +372,7 @@ export default function WidgetChrome({
       onMouseEnter={readOnly ? undefined : handleMouseEnter}
       onMouseLeave={readOnly ? undefined : handleMouseLeave}
     >
-      <div className={`${styles.widgetSlot} ${selected ? styles.widgetSlotSelected : ''}`}>
+      <div className={`tc-drag-surface ${styles.widgetSlot} ${selected ? styles.widgetSlotSelected : ''} ${multiSelected ? styles.widgetSlotMultiSelected : ''}`}>
         {children}
       </div>
       <div
@@ -382,6 +385,7 @@ export default function WidgetChrome({
 
         {/* Toolbar content — visible on hover */}
         <div className={`${styles.toolbarContent} ${showToolbar ? styles.toolbarContentVisible : ''}`}>
+          {showFeatures && (
           <div className={styles.featureButtons}>
             {features.map((feature) => {
               // Menu features are rendered in WidgetOverflowMenu
@@ -449,13 +453,13 @@ export default function WidgetChrome({
               onAction={onAction}
             />
           </div>
+          )}
 
-          <Tooltip text="Select" direction="n">
+          <Tooltip text={selected ? "Click and drag to move" : "Select"} direction="n">
             <button
               className={`tc-drag-handle ${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
-              onPointerDown={handleHandlePointerDown}
-              onPointerUp={handleHandlePointerUp}
-              aria-label="Select widget"
+              onClick={handleHandleClick}
+              aria-label={selected ? "Drag to move widget" : "Select widget"}
               aria-pressed={selected}
             />
           </Tooltip>

package/src/canvas/widgets/WidgetChrome.module.css

@@ -11,11 +11,15 @@
 }
 
 .widgetSlotSelected {
-  outline: 2px solid var(--bgColor-accent-emphasis, #2f81f7);
+  outline: 4px solid var(--bgColor-accent-emphasis, #2f81f7);
   outline-offset: 2px;
   border-radius: 4px;
 }
 
+.widgetSlotMultiSelected {
+  outline-style: solid;
+}
+
 /* Toolbar — absolutely positioned below the widget so it doesn't affect
    the draggable box dimensions (tiny-canvas measures children for drag). */
 .toolbar {
@@ -26,7 +30,7 @@
   position: absolute;
   left: 0;
   right: 0;
-  top: calc(100% + 4px);
+  top: calc(100% + 10px);
 }
 
 /* Trigger dot — centered, visible at rest */
@@ -57,7 +61,7 @@
 .toolbarContent {
   display: flex;
   align-items: center;
-  justify-content: space-between;
+  justify-content: flex-start;
   width: 100%;
   opacity: 0;
   pointer-events: none;
@@ -122,6 +126,7 @@
   background: var(--bgColor-default, #ffffff);
   transition: background 100ms, border-color 100ms;
   flex-shrink: 0;
+  margin-left: auto;
 }
 
 :global([data-sb-canvas-theme^='dark']) .selectHandle {
@@ -227,7 +232,7 @@
 
 .overflowMenu {
   position: absolute;
-  top: calc(100% + 4px);
+  top: calc(100% + 10px);
   right: 0;
   min-width: 180px;
   padding: 4px;

package/src/canvas/widgets/widgetConfig.js

@@ -99,11 +99,17 @@ export const widgetTypes = buildWidgetTypes()
 
 /**
  * Get the feature list for a widget type.
+ * In production, only features with `prod: true` are returned.
+ * In dev, all features are returned.
  * @param {string} type — widget type string
  * @returns {Array} features array from config (variables resolved), or empty array
  */
 export function getFeatures(type) {
-  return widgetTypes[type]?.features ?? []
+  const features = widgetTypes[type]?.features ?? []
+  if (import.meta.env?.PROD) {
+    return features.filter(f => f.prod)
+  }
+  return features
 }
 
 /**