@dfosco/storyboard-react 3.10.0-beta.1 → 3.11.0-beta.0

package/package.json

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

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

@@ -54,6 +54,10 @@ vi.mock('./widgets/index.js', () => ({
   getWidgetComponent: () => function MockWidget() { return <div>mock widget</div> },
 }))
 
+vi.mock('./widgets/WidgetChrome.jsx', () => ({
+  default: ({ children }) => <div data-testid="widget-chrome">{children}</div>,
+}))
+
 vi.mock('./widgets/widgetProps.js', () => ({
   schemas: {},
   getDefaults: () => ({}),

package/src/canvas/CanvasPage.jsx

@@ -1,4 +1,5 @@
 import { createElement, useCallback, useEffect, useRef, useState } from 'react'
+import { flushSync } from 'react-dom'
 import { Canvas } from '@dfosco/tiny-canvas'
 import '@dfosco/tiny-canvas/style.css'
 import { useCanvas } from './useCanvas.js'
@@ -7,9 +8,10 @@ import { getCanvasThemeVars, getCanvasPrimerAttrs } from './canvasTheme.js'
 import { getWidgetComponent } from './widgets/index.js'
 import { schemas, getDefaults } from './widgets/widgetProps.js'
 import { getFeatures } from './widgets/widgetConfig.js'
+import { isFigmaUrl, sanitizeFigmaUrl } from './widgets/figmaUrl.js'
 import WidgetChrome from './widgets/WidgetChrome.jsx'
 import ComponentWidget from './widgets/ComponentWidget.jsx'
-import { addWidget as addWidgetApi, updateCanvas, removeWidget as removeWidgetApi } from './canvasApi.js'
+import { addWidget as addWidgetApi, updateCanvas, removeWidget as removeWidgetApi, uploadImage } from './canvasApi.js'
 import styles from './CanvasPage.module.css'
 
 const ZOOM_MIN = 25
@@ -55,13 +57,68 @@ function debounce(fn, ms) {
   }
 }
 
+/** Per-canvas viewport state persistence (zoom + scroll position). */
+function getViewportStorageKey(canvasName) {
+  return `sb-canvas-viewport:${canvasName}`
+}
+
+function loadViewportState(canvasName) {
+  try {
+    const raw = localStorage.getItem(getViewportStorageKey(canvasName))
+    if (!raw) return null
+    const state = JSON.parse(raw)
+    return {
+      zoom: typeof state.zoom === 'number' ? Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, state.zoom)) : null,
+      scrollLeft: typeof state.scrollLeft === 'number' ? state.scrollLeft : null,
+      scrollTop: typeof state.scrollTop === 'number' ? state.scrollTop : null,
+    }
+  } catch { return null }
+}
+
+function saveViewportState(canvasName, state) {
+  try {
+    localStorage.setItem(getViewportStorageKey(canvasName), JSON.stringify(state))
+  } catch { /* quota exceeded — non-critical */ }
+}
+
 /**
- * Get viewport-center coordinates for placing a new widget.
+ * Get viewport-center coordinates in canvas space for placing a new widget.
+ * Converts the visible center of the scroll container to unscaled canvas coordinates.
  */
-function getViewportCenter() {
+function getViewportCenter(scrollEl, scale) {
+  if (!scrollEl) {
+    return { x: 0, y: 0 }
+  }
+  const cx = scrollEl.scrollLeft + scrollEl.clientWidth / 2
+  const cy = scrollEl.scrollTop + scrollEl.clientHeight / 2
   return {
-    x: Math.round(window.innerWidth / 2 - 120),
-    y: Math.round(window.innerHeight / 2 - 80),
+    x: Math.round(cx / scale),
+    y: Math.round(cy / scale),
+  }
+}
+
+/** Fallback sizes for widget types without explicit width/height defaults. */
+const WIDGET_FALLBACK_SIZES = {
+  'sticky-note':  { width: 180, height: 60 },
+  'markdown':     { width: 360, height: 200 },
+  'prototype':    { width: 800, height: 600 },
+  'link-preview': { width: 320, height: 120 },
+  'figma-embed':  { width: 800, height: 450 },
+  'component':    { width: 200, height: 150 },
+  'image':        { width: 400, height: 300 },
+}
+
+/**
+ * Offset a position so the widget's center (not its top-left corner)
+ * lands on the given point.
+ */
+function centerPositionForWidget(pos, type, props) {
+  const fallback = WIDGET_FALLBACK_SIZES[type] || { width: 200, height: 150 }
+  const w = props?.width ?? fallback.width
+  const h = props?.height ?? fallback.height
+  return {
+    x: Math.round(pos.x - w / 2),
+    y: Math.round(pos.y - h / 2),
   }
 }
 
@@ -140,9 +197,11 @@ export default function CanvasPage({ name }) {
   const [localWidgets, setLocalWidgets] = useState(canvas?.widgets ?? null)
   const [trackedCanvas, setTrackedCanvas] = useState(canvas)
   const [selectedWidgetId, setSelectedWidgetId] = useState(null)
-  const [zoom, setZoom] = useState(100)
-  const zoomRef = useRef(100)
+  const initialViewport = loadViewportState(name)
+  const [zoom, setZoom] = useState(initialViewport?.zoom ?? 100)
+  const zoomRef = useRef(initialViewport?.zoom ?? 100)
   const scrollRef = useRef(null)
+  const pendingScrollRestore = useRef(initialViewport)
   const [canvasTitle, setCanvasTitle] = useState(canvas?.title || name)
   const titleInputRef = useRef(null)
   const [localSources, setLocalSources] = useState(canvas?.sources ?? [])
@@ -257,6 +316,92 @@ export default function CanvasPage({ name }) {
     zoomRef.current = zoom
   }, [zoom])
 
+  // Restore scroll position from localStorage after first render
+  useEffect(() => {
+    const el = scrollRef.current
+    const saved = pendingScrollRestore.current
+    if (el && saved) {
+      if (saved.scrollLeft != null) el.scrollLeft = saved.scrollLeft
+      if (saved.scrollTop != null) el.scrollTop = saved.scrollTop
+      pendingScrollRestore.current = null
+    }
+  }, [name, loading])
+
+  // Persist viewport state (zoom + scroll) to localStorage on changes
+  useEffect(() => {
+    const el = scrollRef.current
+    saveViewportState(name, {
+      zoom,
+      scrollLeft: el?.scrollLeft ?? 0,
+      scrollTop: el?.scrollTop ?? 0,
+    })
+  }, [name, zoom])
+
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    function handleScroll() {
+      saveViewportState(name, {
+        zoom: zoomRef.current,
+        scrollLeft: el.scrollLeft,
+        scrollTop: el.scrollTop,
+      })
+    }
+    el.addEventListener('scroll', handleScroll, { passive: true })
+
+    // Flush viewport state on page unload so a refresh never misses it
+    function handleBeforeUnload() {
+      saveViewportState(name, {
+        zoom: zoomRef.current,
+        scrollLeft: el.scrollLeft,
+        scrollTop: el.scrollTop,
+      })
+    }
+    window.addEventListener('beforeunload', handleBeforeUnload)
+
+    return () => {
+      el.removeEventListener('scroll', handleScroll)
+      window.removeEventListener('beforeunload', handleBeforeUnload)
+    }
+  }, [name, loading])
+
+  /**
+   * Zoom to a new level, anchoring on an optional client-space point.
+   * When a cursor position is provided (e.g. from a wheel event), the
+   * canvas point under the cursor stays fixed. Otherwise falls back to
+   * the viewport center.
+   */
+  function applyZoom(newZoom, clientX, clientY) {
+    const el = scrollRef.current
+    const clampedZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, newZoom))
+
+    if (!el) {
+      setZoom(clampedZoom)
+      return
+    }
+
+    const oldScale = zoomRef.current / 100
+    const newScale = clampedZoom / 100
+
+    // Anchor point in scroll-container space
+    const rect = el.getBoundingClientRect()
+    const useViewportCenter = clientX == null || clientY == null
+    const anchorX = useViewportCenter ? el.clientWidth / 2 : clientX - rect.left
+    const anchorY = useViewportCenter ? el.clientHeight / 2 : clientY - rect.top
+
+    // Anchor → canvas coordinate
+    const canvasX = (el.scrollLeft + anchorX) / oldScale
+    const canvasY = (el.scrollTop + anchorY) / oldScale
+
+    // Synchronous render so the DOM has the new transform before we adjust scroll
+    zoomRef.current = clampedZoom
+    flushSync(() => setZoom(clampedZoom))
+
+    // Scroll so the same canvas point stays under the anchor
+    el.scrollLeft = canvasX * newScale - anchorX
+    el.scrollTop = canvasY * newScale - anchorY
+  }
+
   // Signal canvas mount/unmount to CoreUIBar
   useEffect(() => {
     window[CANVAS_BRIDGE_STATE_KEY] = { active: true, name, zoom: zoomRef.current }
@@ -278,10 +423,31 @@ export default function CanvasPage({ name }) {
     }
   }, [name])
 
+  // Tell the Vite dev server to suppress full-reloads while this canvas is active.
+  // The ?canvas-hmr URL param opts out of the guard for canvas UI development.
+  // Sends a heartbeat every 3s so the guard auto-expires if the tab closes.
+  useEffect(() => {
+    if (!import.meta.hot) return
+    const hmrEnabled = new URLSearchParams(window.location.search).has('canvas-hmr')
+    if (hmrEnabled) return
+
+    const msg = { active: true, hmrEnabled: false }
+    import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+    const interval = setInterval(() => {
+      import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+    }, 3000)
+
+    return () => {
+      clearInterval(interval)
+      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false, hmrEnabled: true })
+    }
+  }, [name])
+
   // Add a widget by type — used by CanvasControls and CoreUIBar event
   const addWidget = useCallback(async (type) => {
     const defaultProps = schemas[type] ? getDefaults(schemas[type]) : {}
-    const pos = getViewportCenter()
+    const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
+    const pos = centerPositionForWidget(center, type, defaultProps)
     try {
       const result = await addWidgetApi(name, {
         type,
@@ -310,7 +476,7 @@ export default function CanvasPage({ name }) {
     function handleZoom(e) {
       const { zoom: newZoom } = e.detail
       if (typeof newZoom === 'number') {
-        setZoom(Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, newZoom)))
+        applyZoom(newZoom)
       }
     }
     document.addEventListener('storyboard:canvas:set-zoom', handleZoom)
@@ -352,6 +518,10 @@ export default function CanvasPage({ name }) {
       if (!selectedWidgetId) return
       const tag = e.target.tagName
       if (tag === 'INPUT' || tag === 'TEXTAREA' || e.target.isContentEditable) return
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        setSelectedWidgetId(null)
+      }
       if (e.key === 'Delete' || e.key === 'Backspace') {
         e.preventDefault()
         handleWidgetRemove(selectedWidgetId)
@@ -362,7 +532,8 @@ export default function CanvasPage({ name }) {
     return () => document.removeEventListener('keydown', handleKeyDown)
   }, [selectedWidgetId, handleWidgetRemove])
 
-  // Paste handler — same-origin URLs become prototypes, other URLs become link previews, text becomes markdown
+  // Paste handler — images become image widgets, same-origin URLs become prototypes,
+  // other URLs become link previews, text becomes markdown
   useEffect(() => {
     const origin = window.location.origin
     const basePath = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
@@ -393,10 +564,81 @@ export default function CanvasPage({ name }) {
       return pathname
     }
 
+    function blobToDataUrl(blob) {
+      return new Promise((resolve, reject) => {
+        const reader = new FileReader()
+        reader.onload = () => resolve(reader.result)
+        reader.onerror = reject
+        reader.readAsDataURL(blob)
+      })
+    }
+
+    function getImageDimensions(dataUrl) {
+      return new Promise((resolve) => {
+        const img = new Image()
+        img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight })
+        img.onerror = () => resolve({ width: 400, height: 300 })
+        img.src = dataUrl
+      })
+    }
+
+    async function handleImagePaste(e) {
+      const items = e.clipboardData?.items
+      if (!items) return false
+
+      for (const item of items) {
+        if (!item.type.startsWith('image/')) continue
+
+        const blob = item.getAsFile()
+        if (!blob) continue
+
+        e.preventDefault()
+
+        try {
+          const dataUrl = await blobToDataUrl(blob)
+          const { width: natW, height: natH } = await getImageDimensions(dataUrl)
+
+          // Display at 2x retina: halve natural dimensions, then cap at 600px
+          const maxWidth = 600
+          let displayW = Math.round(natW / 2)
+          let displayH = Math.round(natH / 2)
+          if (displayW > maxWidth) {
+            displayH = Math.round(displayH * (maxWidth / displayW))
+            displayW = maxWidth
+          }
+
+          const uploadResult = await uploadImage(dataUrl, name)
+          if (!uploadResult.success) {
+            console.error('[canvas] Image upload failed:', uploadResult.error)
+            return true
+          }
+
+          const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
+          const pos = centerPositionForWidget(center, 'image', { width: displayW, height: displayH })
+          const result = await addWidgetApi(name, {
+            type: 'image',
+            props: { src: uploadResult.filename, private: false, width: displayW, height: displayH },
+            position: pos,
+          })
+          if (result.success && result.widget) {
+            setLocalWidgets((prev) => [...(prev || []), result.widget])
+          }
+        } catch (err) {
+          console.error('[canvas] Failed to paste image:', err)
+        }
+        return true
+      }
+      return false
+    }
+
     async function handlePaste(e) {
       const tag = e.target.tagName
       if (tag === 'INPUT' || tag === 'TEXTAREA' || e.target.isContentEditable) return
 
+      // Image paste takes priority
+      const handledImage = await handleImagePaste(e)
+      if (handledImage) return
+
       const text = e.clipboardData?.getData('text/plain')?.trim()
       if (!text) return
 
@@ -405,7 +647,10 @@ export default function CanvasPage({ name }) {
       let type, props
       try {
         const parsed = new URL(text)
-        if (isSameOriginPrototype(text)) {
+        if (isFigmaUrl(text)) {
+          type = 'figma-embed'
+          props = { url: sanitizeFigmaUrl(text), width: 800, height: 450 }
+        } else if (isSameOriginPrototype(text)) {
           const pathPortion = parsed.pathname + parsed.search + parsed.hash
           const src = extractPrototypeSrc(pathPortion)
           type = 'prototype'
@@ -419,7 +664,8 @@ export default function CanvasPage({ name }) {
         props = { content: text }
       }
 
-      const pos = getViewportCenter()
+      const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
+      const pos = centerPositionForWidget(center, type, props)
       try {
         const result = await addWidgetApi(name, {
           type,
@@ -449,7 +695,7 @@ export default function CanvasPage({ name }) {
       const step = Math.trunc(zoomAccum.current)
       if (step === 0) return
       zoomAccum.current -= step
-      setZoom((z) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, z + step)))
+      applyZoom(zoomRef.current + step, e.clientX, e.clientY)
     }
     document.addEventListener('wheel', handleWheel, { passive: false })
     return () => document.removeEventListener('wheel', handleWheel)

package/src/canvas/canvasApi.js

@@ -39,3 +39,11 @@ export function addWidget(name, { type, props, position }) {
 export function removeWidget(name, widgetId) {
   return request('/widget', 'DELETE', { name, widgetId })
 }
+
+export function uploadImage(dataUrl, canvasName) {
+  return request('/image', 'POST', { dataUrl, canvasName })
+}
+
+export function toggleImagePrivacy(filename) {
+  return request('/image/toggle-private', 'POST', { filename })
+}

package/src/canvas/widgets/FigmaEmbed.jsx

@@ -0,0 +1,106 @@
+import { forwardRef, useImperativeHandle, useMemo, useCallback, useState } from 'react'
+import WidgetWrapper from './WidgetWrapper.jsx'
+import { readProp } from './widgetProps.js'
+import { schemas } from './widgetConfig.js'
+import { toFigmaEmbedUrl, getFigmaTitle, getFigmaType, isFigmaUrl } from './figmaUrl.js'
+import styles from './FigmaEmbed.module.css'
+
+const figmaEmbedSchema = schemas['figma-embed']
+
+/** Inline Figma logo SVG */
+function FigmaLogo() {
+  return (
+    <svg className={styles.figmaLogo} viewBox="0 0 38 57" fill="none" aria-hidden="true">
+      <path d="M19 28.5a9.5 9.5 0 1 1 19 0 9.5 9.5 0 0 1-19 0z" fill="#1ABCFE" />
+      <path d="M0 47.5A9.5 9.5 0 0 1 9.5 38H19v9.5a9.5 9.5 0 1 1-19 0z" fill="#0ACF83" />
+      <path d="M19 0v19h9.5a9.5 9.5 0 1 0 0-19H19z" fill="#FF7262" />
+      <path d="M0 9.5A9.5 9.5 0 0 0 9.5 19H19V0H9.5A9.5 9.5 0 0 0 0 9.5z" fill="#F24E1E" />
+      <path d="M0 28.5A9.5 9.5 0 0 0 9.5 38H19V19H9.5A9.5 9.5 0 0 0 0 28.5z" fill="#A259FF" />
+    </svg>
+  )
+}
+
+const TYPE_LABELS = { board: 'Board', design: 'Design', proto: 'Prototype' }
+
+export default forwardRef(function FigmaEmbed({ props, onUpdate }, ref) {
+  const url = readProp(props, 'url', figmaEmbedSchema)
+  const width = readProp(props, 'width', figmaEmbedSchema)
+  const height = readProp(props, 'height', figmaEmbedSchema)
+
+  const [interactive, setInteractive] = useState(false)
+
+  // Validate URL at render time — only embed known Figma URLs
+  const isValid = useMemo(() => isFigmaUrl(url), [url])
+  const embedUrl = useMemo(() => (isValid ? toFigmaEmbedUrl(url) : ''), [url, isValid])
+  const title = useMemo(() => (url ? getFigmaTitle(url) : 'Figma'), [url])
+  const figmaType = useMemo(() => getFigmaType(url), [url])
+  const typeLabel = figmaType ? TYPE_LABELS[figmaType] : 'Figma'
+
+  const enterInteractive = useCallback(() => setInteractive(true), [])
+
+  useImperativeHandle(ref, () => ({
+    handleAction(actionId) {
+      if (actionId === 'open-external') {
+        if (url) window.open(url, '_blank', 'noopener')
+      }
+    },
+  }), [url])
+
+  return (
+    <WidgetWrapper>
+      <div className={styles.embed} style={{ width, height }}>
+        <div className={styles.header}>
+          <FigmaLogo />
+          <span className={styles.headerTitle}>{title}</span>
+        </div>
+        {embedUrl ? (
+          <>
+            <div className={styles.iframeContainer}>
+              <iframe
+                src={embedUrl}
+                className={styles.iframe}
+                title={`Figma ${typeLabel}: ${title}`}
+                allowFullScreen
+              />
+            </div>
+            {!interactive && (
+              <div
+                className={styles.dragOverlay}
+                onDoubleClick={enterInteractive}
+              />
+            )}
+          </>
+        ) : (
+          <div className={styles.iframeContainer} style={{ display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+            <p style={{ color: 'var(--fgColor-muted, #656d76)', fontSize: 14, fontStyle: 'italic' }}>
+              No Figma URL
+            </p>
+          </div>
+        )}
+      </div>
+      <div
+        className={styles.resizeHandle}
+        onMouseDown={(e) => {
+          e.stopPropagation()
+          e.preventDefault()
+          const startX = e.clientX
+          const startY = e.clientY
+          const startW = width
+          const startH = height
+          function onMove(ev) {
+            const newW = Math.max(200, startW + ev.clientX - startX)
+            const newH = Math.max(150, startH + ev.clientY - startY)
+            onUpdate?.({ width: newW, height: newH })
+          }
+          function onUp() {
+            document.removeEventListener('mousemove', onMove)
+            document.removeEventListener('mouseup', onUp)
+          }
+          document.addEventListener('mousemove', onMove)
+          document.addEventListener('mouseup', onUp)
+        }}
+        onPointerDown={(e) => e.stopPropagation()}
+      />
+    </WidgetWrapper>
+  )
+})

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

@@ -0,0 +1,83 @@
+.embed {
+  position: relative;
+  overflow: hidden;
+  background: var(--bgColor-default, #ffffff);
+  border: 3px solid var(--borderColor-default, #d0d7de);
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--fgColor-muted, #656d76);
+  background: var(--bgColor-muted, #f6f8fa);
+  border-bottom: 1px solid var(--borderColor-muted, #d8dee4);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  user-select: none;
+}
+
+.figmaLogo {
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+}
+
+.headerTitle {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.iframeContainer {
+  width: 100%;
+  height: calc(100% - 31px); /* subtract header height */
+  overflow: hidden;
+}
+
+.iframe {
+  width: 100%;
+  height: calc(100% + 24px); /* clip Figma's built-in bottom toolbar */
+  border: none;
+  display: block;
+}
+
+.dragOverlay {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  cursor: grab;
+}
+
+.resizeHandle {
+  position: absolute;
+  bottom: 0;
+  right: 0;
+  width: 16px;
+  height: 16px;
+  cursor: nwse-resize;
+  background: linear-gradient(
+    135deg,
+    transparent 40%,
+    var(--borderColor-muted, rgba(0, 0, 0, 0.15)) 40%,
+    var(--borderColor-muted, rgba(0, 0, 0, 0.15)) 50%,
+    transparent 50%,
+    transparent 65%,
+    var(--borderColor-muted, rgba(0, 0, 0, 0.15)) 65%,
+    var(--borderColor-muted, rgba(0, 0, 0, 0.15)) 75%,
+    transparent 75%
+  );
+  opacity: 0;
+  transition: opacity 150ms;
+  z-index: 2;
+}
+
+.embed:hover ~ .resizeHandle,
+.resizeHandle:hover {
+  opacity: 1;
+}

package/src/canvas/widgets/ImageWidget.jsx

@@ -0,0 +1,91 @@
+import { useRef, useCallback, useState, forwardRef, useImperativeHandle } from 'react'
+import WidgetWrapper from './WidgetWrapper.jsx'
+import ResizeHandle from './ResizeHandle.jsx'
+import { readProp } from './widgetProps.js'
+import { schemas } from './widgetConfig.js'
+import { toggleImagePrivacy } from '../canvasApi.js'
+import styles from './ImageWidget.module.css'
+
+const imageSchema = schemas['image']
+
+function getImageUrl(src) {
+  if (!src) return ''
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+  return `${base}/_storyboard/canvas/images/${src}`
+}
+
+/**
+ * Canvas widget that displays a pasted image.
+ * Supports aspect-ratio locked resize and privacy toggle.
+ */
+const ImageWidget = forwardRef(function ImageWidget({ props, onUpdate }, ref) {
+  const containerRef = useRef(null)
+  const [naturalRatio, setNaturalRatio] = useState(null)
+
+  const src = readProp(props, 'src', imageSchema)
+  const isPrivate = readProp(props, 'private', imageSchema)
+  const width = readProp(props, 'width', imageSchema)
+  const height = readProp(props, 'height', imageSchema)
+
+  const handleImageLoad = useCallback((e) => {
+    const img = e.target
+    if (img.naturalWidth && img.naturalHeight) {
+      setNaturalRatio(img.naturalWidth / img.naturalHeight)
+    }
+  }, [])
+
+  const handleResize = useCallback((newWidth) => {
+    const ratio = naturalRatio || (width && height ? width / height : 4 / 3)
+    const newHeight = Math.round(newWidth / ratio)
+    onUpdate?.({ width: newWidth, height: newHeight })
+  }, [naturalRatio, width, height, onUpdate])
+
+  useImperativeHandle(ref, () => ({
+    handleAction(actionId) {
+      if (actionId === 'toggle-private') {
+        if (!src) return
+        toggleImagePrivacy(src).then((result) => {
+          if (result.success) {
+            onUpdate?.({ src: result.filename, private: result.private })
+          }
+        }).catch((err) => {
+          console.error('[canvas] Failed to toggle image privacy:', err)
+        })
+      }
+    }
+  }), [src, onUpdate])
+
+  if (!src) return null
+
+  const sizeStyle = {}
+  if (typeof width === 'number') sizeStyle.width = `${width}px`
+
+  return (
+    <WidgetWrapper className={styles.imageWrapper}>
+      <div ref={containerRef} className={styles.container} style={sizeStyle}>
+        <div className={styles.frame}>
+          <img
+            src={getImageUrl(src)}
+            alt=""
+            className={styles.image}
+            onLoad={handleImageLoad}
+            draggable={false}
+          />
+          {isPrivate && (
+            <span className={styles.privateBadge} title="Private — not committed to git">
+              Private
+            </span>
+          )}
+        </div>
+        <ResizeHandle
+          targetRef={containerRef}
+          minWidth={100}
+          minHeight={60}
+          onResize={(w) => handleResize(w)}
+        />
+      </div>
+    </WidgetWrapper>
+  )
+})
+
+export default ImageWidget

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

@@ -0,0 +1,39 @@
+.imageWrapper {
+  min-width: unset;
+}
+
+.container {
+  position: relative;
+  overflow: hidden;
+  min-width: 100px;
+}
+
+.frame {
+  position: relative;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.image {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: 4px;
+  user-select: none;
+  pointer-events: none;
+}
+
+.privateBadge {
+  position: absolute;
+  top: 20px;
+  right: 20px;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 1.4;
+  letter-spacing: 0.02em;
+  color: var(--fgColor-onEmphasis, #fff);
+  background: var(--bgColor-neutral-emphasis, rgba(0, 0, 0, 0.55));
+  pointer-events: none;
+}

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -186,6 +186,8 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
     handleAction(actionId) {
       if (actionId === 'edit') {
         setEditing(true)
+      } else if (actionId === 'open-external') {
+        if (rawSrc) window.open(rawSrc, '_blank', 'noopener')
       } else if (actionId === 'zoom-in') {
         const step = zoom < 75 ? 5 : 25
         onUpdate?.({ zoom: Math.min(200, zoom + step) })
@@ -194,7 +196,7 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate }, ref) {
         onUpdate?.({ zoom: Math.max(25, zoom - step) })
       }
     },
-  }), [zoom, onUpdate])
+  }), [rawSrc, zoom, onUpdate])
 
   function handlePickRoute(route) {
     onUpdate?.({ src: route })

package/src/canvas/widgets/WidgetChrome.jsx

@@ -1,4 +1,6 @@
 import { useState, useCallback, useRef } from 'react'
+import { Tooltip } from '@primer/react'
+import { EyeIcon as OcticonEye, EyeClosedIcon as OcticonEyeClosed } from '@primer/octicons-react'
 import styles from './WidgetChrome.module.css'
 
 const STICKY_NOTE_COLORS = {
@@ -42,11 +44,29 @@ function EditIcon() {
   )
 }
 
+function OpenExternalIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+      <path d="M3.75 2h3.5a.75.75 0 0 1 0 1.5h-3.5a.25.25 0 0 0-.25.25v8.5c0 .138.112.25.25.25h8.5a.25.25 0 0 0 .25-.25v-3.5a.75.75 0 0 1 1.5 0v3.5A1.75 1.75 0 0 1 12.25 14h-8.5A1.75 1.75 0 0 1 2 12.25v-8.5C2 2.784 2.784 2 3.75 2Zm6.854-1h4.146a.25.25 0 0 1 .25.25v4.146a.25.25 0 0 1-.427.177L13.03 4.03 9.28 7.78a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042l3.75-3.75-1.543-1.543A.25.25 0 0 1 10.604 1Z" />
+    </svg>
+  )
+}
+
+function EyeIcon() {
+  return <OcticonEye size={12} />
+}
+
+function EyeClosedIcon() {
+  return <OcticonEyeClosed size={12} />
+}
+
 const ACTION_ICONS = {
   'delete': DeleteIcon,
   'zoom-in': ZoomInIcon,
   'zoom-out': ZoomOutIcon,
   'edit': EditIcon,
+  'open-external': OpenExternalIcon,
+  'toggle-private': EyeIcon,
 }
 
 const ACTION_LABELS = {
@@ -54,6 +74,8 @@ const ACTION_LABELS = {
   'zoom-in': 'Zoom in',
   'zoom-out': 'Zoom out',
   'edit': 'Edit',
+  'open-external': 'Open in new tab',
+  'toggle-private': 'Make private',
 }
 
 /**
@@ -145,16 +167,11 @@ export default function WidgetChrome({
     if (!pointerStartPos.current) return
     const start = pointerStartPos.current
     pointerStartPos.current = null
-    // Only toggle selection if the pointer stayed close (click, not drag)
     const dist = Math.hypot(e.clientX - start.x, e.clientY - start.y)
     if (dist > 10) return
     e.stopPropagation()
-    if (selected) {
-      onDeselect?.()
-    } else {
-      onSelect?.()
-    }
-  }, [selected, onSelect, onDeselect])
+    onSelect?.()
+  }, [onSelect])
 
   const handleActionClick = useCallback((actionId, e) => {
     e.stopPropagation()
@@ -211,17 +228,29 @@ export default function WidgetChrome({
               }
 
               if (feature.type === 'action') {
-                const Icon = ACTION_ICONS[feature.action]
+                let Icon = ACTION_ICONS[feature.action]
+                let label = ACTION_LABELS[feature.action] || feature.action
+
+                // Toggle-private: swap icon/label based on current state
+                if (feature.action === 'toggle-private') {
+                  if (widgetProps?.private) {
+                    Icon = EyeClosedIcon
+                    label = 'Private image — only visible locally'
+                  } else {
+                    label = 'Published image — deployed with canvas'
+                  }
+                }
+
                 return (
-                  <button
-                    key={feature.id}
-                    className={styles.featureBtn}
-                    onClick={(e) => handleActionClick(feature.action, e)}
-                    title={ACTION_LABELS[feature.action] || feature.action}
-                    aria-label={ACTION_LABELS[feature.action] || feature.action}
-                  >
-                    {Icon ? <Icon /> : feature.action}
-                  </button>
+                  <Tooltip key={feature.id} text={label} direction="n">
+                    <button
+                      className={styles.featureBtn}
+                      onClick={(e) => handleActionClick(feature.action, e)}
+                      aria-label={label}
+                    >
+                      {Icon ? <Icon /> : feature.action}
+                    </button>
+                  </Tooltip>
                 )
               }
 
@@ -229,14 +258,15 @@ export default function WidgetChrome({
             })}
           </div>
 
-          <button
-            className={`tc-drag-handle ${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
-            onPointerDown={handleHandlePointerDown}
-            onPointerUp={handleHandlePointerUp}
-            title={selected ? 'Deselect' : 'Select'}
-            aria-label={selected ? 'Deselect widget' : 'Select widget'}
-            aria-pressed={selected}
-          />
+          <Tooltip text="Select" direction="n">
+            <button
+              className={`tc-drag-handle ${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
+              onPointerDown={handleHandlePointerDown}
+              onPointerUp={handleHandlePointerUp}
+              aria-label="Select widget"
+              aria-pressed={selected}
+            />
+          </Tooltip>
         </div>
       </div>
     </div>

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

@@ -115,8 +115,8 @@
 .selectHandle {
   all: unset;
   cursor: grab;
-  width: 18px;
-  height: 12px;
+  width: 16px;
+  height: 16px;
   border-radius: 4px;
   border: 1.6px solid var(--borderColor-muted, #d0d7de);
   background: var(--bgColor-default, #ffffff);
@@ -159,9 +159,8 @@
 
 .colorPopup {
   position: absolute;
-  bottom: calc(100% + 6px);
-  left: 50%;
-  transform: translateX(-50%);
+  top: calc(100% + 2px);
+  left: -4px;
   display: flex;
   gap: 5px;
   padding: 6px 10px;
@@ -177,6 +176,17 @@
   white-space: nowrap;
 }
 
+/* Invisible bridge from the trigger button to the popup so mouse
+   travel doesn't create a gap that closes the picker. */
+.colorPopup::before {
+  content: '';
+  position: absolute;
+  bottom: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
 :global([data-sb-canvas-theme^='dark']) .colorPopup {
   background: var(--bgColor-muted, #161b22);
   box-shadow:

package/src/canvas/widgets/figmaUrl.js

@@ -0,0 +1,118 @@
+/**
+ * Figma URL utilities — detection, sanitization, and embed URL transformation.
+ *
+ * Supports three Figma link types:
+ *   - Board:  figma.com/board/{key}/{name}
+ *   - Design: figma.com/design/{key}/{name}
+ *   - Proto:  figma.com/proto/{key}/{name}
+ */
+
+const FIGMA_HOST_RE = /^(www\.)?figma\.com$/
+const FIGMA_PATH_RE = /^\/(board|design|proto)\/[A-Za-z0-9]+/
+
+/** Params to strip from stored/embed URLs (session/tracking tokens). */
+const STRIP_PARAMS = new Set(['t'])
+
+/**
+ * Check whether a URL string is a Figma board, design, or prototype link.
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isFigmaUrl(url) {
+  try {
+    const parsed = new URL(url)
+    return FIGMA_HOST_RE.test(parsed.hostname) && FIGMA_PATH_RE.test(parsed.pathname)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Return the Figma link type: 'board', 'design', or 'proto'.
+ * Returns null for non-Figma URLs.
+ * @param {string} url
+ * @returns {'board' | 'design' | 'proto' | null}
+ */
+export function getFigmaType(url) {
+  try {
+    const parsed = new URL(url)
+    if (!FIGMA_HOST_RE.test(parsed.hostname)) return null
+    const match = parsed.pathname.match(FIGMA_PATH_RE)
+    if (!match) return null
+    return match[1]
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Sanitize a Figma URL for storage — strips tracking params like `t`.
+ * Returns a canonical www.figma.com URL safe to persist in canvas data.
+ * @param {string} url — raw pasted Figma URL
+ * @returns {string} sanitized URL
+ */
+export function sanitizeFigmaUrl(url) {
+  try {
+    const parsed = new URL(url)
+    if (!FIGMA_HOST_RE.test(parsed.hostname)) return url
+    // Normalize to www.figma.com
+    parsed.hostname = 'www.figma.com'
+    for (const key of STRIP_PARAMS) {
+      parsed.searchParams.delete(key)
+    }
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Transform a Figma URL into its embed counterpart.
+ *
+ * - Replaces host with `embed.figma.com`
+ * - Strips tracking params (`t`)
+ * - Appends `embed-host=share`
+ *
+ * @param {string} url — original Figma URL
+ * @returns {string} embed URL, or the original URL if it can't be transformed
+ */
+export function toFigmaEmbedUrl(url) {
+  try {
+    const parsed = new URL(url)
+    if (!FIGMA_HOST_RE.test(parsed.hostname)) return url
+
+    parsed.hostname = 'embed.figma.com'
+
+    // Strip tracking/session params
+    for (const key of STRIP_PARAMS) {
+      parsed.searchParams.delete(key)
+    }
+
+    // Ensure embed-host is set
+    parsed.searchParams.set('embed-host', 'share')
+
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Extract a human-readable title from a Figma URL.
+ * Uses the name segment from the path (e.g. "Security-Products-HQ").
+ * @param {string} url
+ * @returns {string}
+ */
+export function getFigmaTitle(url) {
+  try {
+    const parsed = new URL(url)
+    // Path: /board|design|proto/{key}/{name}
+    const segments = parsed.pathname.split('/').filter(Boolean)
+    if (segments.length >= 3) {
+      return segments[2].replace(/-/g, ' ')
+    }
+    return 'Figma'
+  } catch {
+    return 'Figma'
+  }
+}

package/src/canvas/widgets/figmaUrl.test.js

@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest'
+import { isFigmaUrl, getFigmaType, toFigmaEmbedUrl, getFigmaTitle, sanitizeFigmaUrl } from './figmaUrl.js'
+
+describe('isFigmaUrl', () => {
+  it('detects board URLs', () => {
+    expect(isFigmaUrl('https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ?node-id=0-1&t=XBF45Am0VgicAITG-0')).toBe(true)
+  })
+
+  it('detects design URLs', () => {
+    expect(isFigmaUrl('https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=103-4739')).toBe(true)
+  })
+
+  it('detects proto URLs', () => {
+    expect(isFigmaUrl('https://www.figma.com/proto/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=122-9632&p=f&t=9XSi047pSbt81sZS-0&scaling=min-zoom')).toBe(true)
+  })
+
+  it('works without www prefix', () => {
+    expect(isFigmaUrl('https://figma.com/board/abc123/My-Board')).toBe(true)
+  })
+
+  it('rejects non-Figma URLs', () => {
+    expect(isFigmaUrl('https://example.com/board/abc')).toBe(false)
+    expect(isFigmaUrl('https://www.figma.com/file/abc')).toBe(false)
+    expect(isFigmaUrl('not a url')).toBe(false)
+    expect(isFigmaUrl('')).toBe(false)
+  })
+})
+
+describe('getFigmaType', () => {
+  it('returns board for board URLs', () => {
+    expect(getFigmaType('https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Name')).toBe('board')
+  })
+
+  it('returns design for design URLs', () => {
+    expect(getFigmaType('https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Name')).toBe('design')
+  })
+
+  it('returns proto for proto URLs', () => {
+    expect(getFigmaType('https://www.figma.com/proto/i8jI8RuxPnGQGp2QllfAr7/Name')).toBe('proto')
+  })
+
+  it('returns null for non-Figma URLs', () => {
+    expect(getFigmaType('https://example.com')).toBeNull()
+  })
+})
+
+describe('toFigmaEmbedUrl', () => {
+  it('transforms board URL', () => {
+    const input = 'https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ?node-id=0-1&t=XBF45Am0VgicAITG-0'
+    const result = toFigmaEmbedUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('embed.figma.com')
+    expect(parsed.pathname).toBe('/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ')
+    expect(parsed.searchParams.get('node-id')).toBe('0-1')
+    expect(parsed.searchParams.get('embed-host')).toBe('share')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('transforms design URL', () => {
+    const input = 'https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=103-4739'
+    const result = toFigmaEmbedUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('embed.figma.com')
+    expect(parsed.pathname).toBe('/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox')
+    expect(parsed.searchParams.get('node-id')).toBe('103-4739')
+    expect(parsed.searchParams.get('embed-host')).toBe('share')
+  })
+
+  it('transforms proto URL and preserves relevant params', () => {
+    const input = 'https://www.figma.com/proto/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=122-9632&p=f&t=9XSi047pSbt81sZS-0&scaling=min-zoom&content-scaling=fixed&page-id=103%3A4739&starting-point-node-id=140%3A5949'
+    const result = toFigmaEmbedUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('embed.figma.com')
+    expect(parsed.pathname).toBe('/proto/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox')
+    expect(parsed.searchParams.get('node-id')).toBe('122-9632')
+    expect(parsed.searchParams.get('p')).toBe('f')
+    expect(parsed.searchParams.get('scaling')).toBe('min-zoom')
+    expect(parsed.searchParams.get('content-scaling')).toBe('fixed')
+    expect(parsed.searchParams.get('page-id')).toBe('103:4739')
+    expect(parsed.searchParams.get('starting-point-node-id')).toBe('140:5949')
+    expect(parsed.searchParams.get('embed-host')).toBe('share')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('returns original URL for non-Figma URLs', () => {
+    expect(toFigmaEmbedUrl('https://example.com')).toBe('https://example.com')
+  })
+})
+
+describe('getFigmaTitle', () => {
+  it('extracts title from board URL', () => {
+    expect(getFigmaTitle('https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ')).toBe('Security Products HQ')
+  })
+
+  it('extracts title from design URL', () => {
+    expect(getFigmaTitle('https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox')).toBe("Darby s copilot metric sandbox")
+  })
+
+  it('returns Figma for URLs without name segment', () => {
+    expect(getFigmaTitle('https://www.figma.com/board/abc')).toBe('Figma')
+  })
+})
+
+describe('sanitizeFigmaUrl', () => {
+  it('strips tracking param and normalizes to www.figma.com', () => {
+    const input = 'https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ?node-id=0-1&t=XBF45Am0VgicAITG-0'
+    const result = sanitizeFigmaUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('www.figma.com')
+    expect(parsed.searchParams.get('node-id')).toBe('0-1')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('normalizes figma.com to www.figma.com', () => {
+    const input = 'https://figma.com/board/abc/Name?node-id=0-1'
+    const result = sanitizeFigmaUrl(input)
+    expect(new URL(result).hostname).toBe('www.figma.com')
+  })
+
+  it('preserves all non-tracking params for proto URLs', () => {
+    const input = 'https://www.figma.com/proto/abc/Name?node-id=1-2&p=f&t=TOKEN&scaling=min-zoom&page-id=103%3A4739'
+    const result = sanitizeFigmaUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.searchParams.get('node-id')).toBe('1-2')
+    expect(parsed.searchParams.get('p')).toBe('f')
+    expect(parsed.searchParams.get('scaling')).toBe('min-zoom')
+    expect(parsed.searchParams.get('page-id')).toBe('103:4739')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('returns non-Figma URLs unchanged', () => {
+    expect(sanitizeFigmaUrl('https://example.com')).toBe('https://example.com')
+  })
+})

package/src/canvas/widgets/index.js

@@ -2,6 +2,8 @@ import StickyNote from './StickyNote.jsx'
 import MarkdownBlock from './MarkdownBlock.jsx'
 import PrototypeEmbed from './PrototypeEmbed.jsx'
 import LinkPreview from './LinkPreview.jsx'
+import ImageWidget from './ImageWidget.jsx'
+import FigmaEmbed from './FigmaEmbed.jsx'
 
 /**
  * Maps widget type strings to their React components.
@@ -12,6 +14,8 @@ export const widgetRegistry = {
   'markdown': MarkdownBlock,
   'prototype': PrototypeEmbed,
   'link-preview': LinkPreview,
+  'image': ImageWidget,
+  'figma-embed': FigmaEmbed,
 }
 
 /**

package/src/canvas/widgets/widgetConfig.js

@@ -70,10 +70,10 @@ export function getWidgetMeta(type) {
 
 /**
  * Get all widget types as an array of { type, label, icon } for menus.
- * Excludes link-preview which is created via paste only.
+ * Excludes link-preview, image, and figma-embed which are created via paste only.
  */
 export function getMenuWidgetTypes() {
   return Object.entries(widgetTypes)
-    .filter(([type]) => type !== 'link-preview')
+    .filter(([type]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed')
     .map(([type, def]) => ({ type, label: def.label, icon: def.icon }))
 }

package/src/canvas/widgets/widgetProps.js

@@ -127,3 +127,5 @@ export const stickyNoteSchema = schemas['sticky-note']
 export const markdownSchema = schemas['markdown']
 export const prototypeEmbedSchema = schemas['prototype']
 export const linkPreviewSchema = schemas['link-preview']
+export const imageSchema = schemas['image']
+export const figmaEmbedSchema = schemas['figma-embed']