@dfosco/storyboard-react 4.0.0-beta.0 → 4.0.0-beta.10

package/src/canvas/CanvasPage.jsx

@@ -1,4 +1,4 @@
-import { createElement, useCallback, useEffect, useRef, useState } from 'react'
+import { createElement, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { flushSync } from 'react-dom'
 import { Canvas } from '@dfosco/tiny-canvas'
 import '@dfosco/tiny-canvas/style.css'
@@ -47,6 +47,35 @@ function resolveCanvasThemeFromStorage() {
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 }
 
+/**
+ * Get the copyable URL for a widget based on its type.
+ * Returns the most relevant URL/path for the widget content.
+ */
+function getWidgetCopyableUrl(widget) {
+  const { type, props = {} } = widget
+  const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
+  switch (type) {
+    case 'prototype':
+      // Prototype src is a path like "/MyPrototype" - make it a full URL
+      return props.src ? `${window.location.origin}${base.replace(/\/$/, '')}${props.src}` : ''
+    case 'figma-embed':
+      return props.url || ''
+    case 'link-preview':
+      return props.url || ''
+    case 'image':
+      // Return the served image URL
+      return props.src ? `${window.location.origin}${base.replace(/\/$/, '')}/_storyboard/canvas/images/${props.src}` : ''
+    case 'sticky-note':
+      // Sticky notes have text content, not a URL
+      return props.text || ''
+    case 'markdown':
+      // Markdown has content, not a URL
+      return props.content || ''
+    default:
+      return ''
+  }
+}
+
 /**
  * Debounce helper — returns a function that delays invocation.
  * Exposes `.cancel()` to abort pending calls (used by undo/redo).
@@ -158,7 +187,7 @@ const FIT_PADDING = 48
  * Compute the axis-aligned bounding box that contains every widget and source.
  * Returns { minX, minY, maxX, maxY } in canvas-space coordinates, or null if empty.
  */
-function computeCanvasBounds(widgets, sources, jsxExports) {
+function computeCanvasBounds(widgets, componentEntries) {
   let minX = Infinity
   let minY = Infinity
   let maxX = -Infinity
@@ -179,24 +208,18 @@ function computeCanvasBounds(widgets, sources, jsxExports) {
     hasItems = true
   }
 
-  // JSX sources
-  const sourceMap = Object.fromEntries(
-    (sources || []).filter((s) => s?.export).map((s) => [s.export, s])
-  )
-  if (jsxExports) {
-    for (const exportName of Object.keys(jsxExports)) {
-      const sourceData = sourceMap[exportName] || {}
-      const x = sourceData.position?.x ?? 0
-      const y = sourceData.position?.y ?? 0
-      const fallback = WIDGET_FALLBACK_SIZES['component']
-      const width = sourceData.width ?? fallback.width
-      const height = sourceData.height ?? fallback.height
-      minX = Math.min(minX, x)
-      minY = Math.min(minY, y)
-      maxX = Math.max(maxX, x + width)
-      maxY = Math.max(maxY, y + height)
-      hasItems = true
-    }
+  // Component widgets (from jsxExports or sources fallback)
+  for (const entry of componentEntries) {
+    const x = entry.sourceData?.position?.x ?? 0
+    const y = entry.sourceData?.position?.y ?? 0
+    const fallback = WIDGET_FALLBACK_SIZES['component']
+    const width = entry.sourceData?.width ?? fallback.width
+    const height = entry.sourceData?.height ?? fallback.height
+    minX = Math.min(minX, x)
+    minY = Math.min(minY, y)
+    maxX = Math.max(maxX, x + width)
+    maxY = Math.max(maxY, y + height)
+    hasItems = true
   }
 
   return hasItems ? { minX, minY, maxX, maxY } : null
@@ -275,7 +298,7 @@ function ChromeWrappedWidget({
  * @param {{ name: string }} props - Canvas name as indexed by the data plugin
  */
 export default function CanvasPage({ name }) {
-  const { canvas, jsxExports, loading } = useCanvas(name)
+  const { canvas, jsxExports, jsxError, loading } = useCanvas(name)
   const isLocalDev = typeof window !== 'undefined' && window.__SB_LOCAL_DEV__ === true && !new URLSearchParams(window.location.search).has('prodMode')
 
   // Local mutable copy of widgets for instant UI updates
@@ -293,6 +316,37 @@ export default function CanvasPage({ name }) {
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
   const [snapEnabled, setSnapEnabled] = useState(canvas?.snapToGrid ?? false)
   const [snapGridSize, setSnapGridSize] = useState(canvas?.gridSize || 40)
+  // Refs for snap settings (used by drop handler inside effect closure)
+  const snapEnabledRef = useRef(snapEnabled)
+  const snapGridSizeRef = useRef(snapGridSize)
+
+  // Centralized list of component export names.
+  // When jsxExports is available, use it (discovers new exports not yet in sources).
+  // When jsxExports is null (module import failed), fall back to sources so iframes
+  // still render — the error is contained inside each iframe.
+  const componentEntries = useMemo(() => {
+    const sourceMap = Object.fromEntries(
+      (localSources || []).filter((s) => s?.export).map((s) => [s.export, s]),
+    )
+    if (jsxExports) {
+      return Object.keys(jsxExports).map((exportName) => ({
+        exportName,
+        Component: jsxExports[exportName],
+        sourceData: sourceMap[exportName] || {},
+      }))
+    }
+    // Fallback: use sources when module import failed (iframe isolation still works)
+    if (jsxError && canvas?._jsxModule) {
+      return (localSources || [])
+        .filter((s) => s?.export)
+        .map((s) => ({
+          exportName: s.export,
+          Component: null,
+          sourceData: s,
+        }))
+    }
+    return []
+  }, [jsxExports, jsxError, localSources, canvas?._jsxModule])
 
   // Undo/redo history — tracks both widgets and sources as a combined snapshot
   const undoRedo = useUndoRedo()
@@ -673,16 +727,13 @@ export default function CanvasPage({ name }) {
     // Check JSX sources (jsx-ExportName)
     if (!widget && targetId.startsWith('jsx-')) {
       const exportName = targetId.slice(4)
-      const sourceMap = Object.fromEntries(
-        (localSources || []).filter((s) => s?.export).map((s) => [s.export, s])
-      )
-      const sourceData = sourceMap[exportName]
-      if (sourceData || (jsxExports && exportName in jsxExports)) {
+      const entry = componentEntries.find((e) => e.exportName === exportName)
+      if (entry) {
         const fallback = WIDGET_FALLBACK_SIZES['component']
-        x = sourceData?.position?.x ?? 0
-        y = sourceData?.position?.y ?? 0
-        w = sourceData?.width ?? fallback.width
-        h = sourceData?.height ?? fallback.height
+        x = entry.sourceData?.position?.x ?? 0
+        y = entry.sourceData?.position?.y ?? 0
+        w = entry.sourceData?.width ?? fallback.width
+        h = entry.sourceData?.height ?? fallback.height
       }
     }
 
@@ -696,7 +747,7 @@ export default function CanvasPage({ name }) {
     const url = new URL(window.location.href)
     url.searchParams.delete('widget')
     window.history.replaceState({}, '', url.toString())
-  }, [loading, localWidgets, localSources, jsxExports])
+  }, [loading, localWidgets, componentEntries])
 
   // Persist viewport state (zoom + scroll) to localStorage on changes
   useEffect(() => {
@@ -875,6 +926,7 @@ export default function CanvasPage({ name }) {
     document.dispatchEvent(new CustomEvent('storyboard:canvas:snap-state', {
       detail: { snapEnabled }
     }))
+    snapEnabledRef.current = snapEnabled
   }, [snapEnabled])
 
   // Listen for gridSize from Svelte toolbar config
@@ -887,13 +939,18 @@ export default function CanvasPage({ name }) {
     return () => document.removeEventListener('storyboard:canvas:grid-size', handleGridSize)
   }, [])
 
+  // Keep snapGridSize ref in sync for drop handler
+  useEffect(() => {
+    snapGridSizeRef.current = snapGridSize
+  }, [snapGridSize])
+
   // Listen for zoom-to-fit from CoreUIBar
   useEffect(() => {
     function handleZoomToFit() {
       const el = scrollRef.current
       if (!el) return
 
-      const bounds = computeCanvasBounds(localWidgets, localSources, jsxExports)
+      const bounds = computeCanvasBounds(localWidgets, componentEntries)
       if (!bounds) return
 
       const boxW = bounds.maxX - bounds.minX + FIT_PADDING * 2
@@ -917,7 +974,7 @@ export default function CanvasPage({ name }) {
     }
     document.addEventListener('storyboard:canvas:zoom-to-fit', handleZoomToFit)
     return () => document.removeEventListener('storyboard:canvas:zoom-to-fit', handleZoomToFit)
-  }, [localWidgets, localSources, jsxExports])
+  }, [localWidgets, componentEntries])
 
   // Canvas background should follow toolbar theme target.
   useEffect(() => {
@@ -958,6 +1015,34 @@ export default function CanvasPage({ name }) {
         e.preventDefault()
         setSelectedWidgetIds(new Set())
       }
+      // Copy shortcuts (single widget selected):
+      // - cmd+c → copy URL/content
+      // - Shift+C (no cmd) → copy widget ID (or file path for images)
+      const mod = e.metaKey || e.ctrlKey
+      if (mod && e.key === 'c' && !e.shiftKey && selectedWidgetIds.size === 1) {
+        const widgetId = [...selectedWidgetIds][0]
+        const widget = localWidgets?.find(w => w.id === widgetId)
+        if (widget) {
+          e.preventDefault()
+          const url = getWidgetCopyableUrl(widget)
+          if (url) {
+            navigator.clipboard.writeText(url).catch(() => {})
+          }
+        }
+      }
+      // Shift+C (uppercase C, no cmd) → copy ID or file path
+      if (e.key === 'C' && e.shiftKey && !mod && selectedWidgetIds.size === 1) {
+        const widgetId = [...selectedWidgetIds][0]
+        const widget = localWidgets?.find(w => w.id === widgetId)
+        if (widget) {
+          e.preventDefault()
+          if (widget.type === 'image' && widget.props?.src) {
+            navigator.clipboard.writeText(`src/canvas/images/${widget.props.src}`).catch(() => {})
+          } else {
+            navigator.clipboard.writeText(widgetId).catch(() => {})
+          }
+        }
+      }
       if (e.key === 'Delete' || e.key === 'Backspace') {
         e.preventDefault()
         if (selectedWidgetIds.size > 1) {
@@ -983,9 +1068,12 @@ export default function CanvasPage({ name }) {
     }
     document.addEventListener('keydown', handleKeyDown)
     return () => document.removeEventListener('keydown', handleKeyDown)
-  }, [selectedWidgetIds, handleWidgetRemove, undoRedo, name, debouncedSave])
+  }, [selectedWidgetIds, localWidgets, handleWidgetRemove, undoRedo, name, debouncedSave])
 
-  // Paste handler — images become image widgets, same-origin URLs become prototypes,
+  // Ref to store processImageFile for use by drop effect
+  const processImageFileRef = useRef(null)
+
+  // Paste and drop handler — images become image widgets, same-origin URLs become prototypes,
   // other URLs become link previews, text becomes markdown
   useEffect(() => {
     const origin = window.location.origin
@@ -1017,6 +1105,17 @@ export default function CanvasPage({ name }) {
       return pathname
     }
 
+    /** Parse text as a web URL (http/https only). Returns URL object or null. */
+    function looksLikeWebUrl(text) {
+      try {
+        const url = new URL(text)
+        if (url.protocol === 'http:' || url.protocol === 'https:') return url
+        return null
+      } catch {
+        return null
+      }
+    }
+
     function blobToDataUrl(blob) {
       return new Promise((resolve, reject) => {
         const reader = new FileReader()
@@ -1035,6 +1134,59 @@ export default function CanvasPage({ name }) {
       })
     }
 
+    /**
+     * Process an image file (from paste or drop) and add it as a widget.
+     * @param {File|Blob} file - Image file to process
+     * @param {{ x: number, y: number }|null} position - Drop position, or null to use viewport center
+     */
+    async function processImageFile(file, position = null) {
+      try {
+        const dataUrl = await blobToDataUrl(file)
+        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 false
+        }
+
+        // Use provided position or fall back to viewport center
+        let pos
+        if (position) {
+          pos = { x: position.x, y: position.y }
+        } else {
+          const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
+          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) {
+          undoRedo.snapshot(stateRef.current, 'add')
+          setLocalWidgets((prev) => [...(prev || []), result.widget])
+        }
+        return true
+      } catch (err) {
+        console.error('[canvas] Failed to process image:', err)
+        return false
+      }
+    }
+
+    // Store in ref for use by drag/drop effect
+    processImageFileRef.current = processImageFile
+
     async function handleImagePaste(e) {
       const items = e.clipboardData?.items
       if (!items) return false
@@ -1046,40 +1198,7 @@ export default function CanvasPage({ name }) {
         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) {
-            undoRedo.snapshot(stateRef.current, 'add')
-            setLocalWidgets((prev) => [...(prev || []), result.widget])
-          }
-        } catch (err) {
-          console.error('[canvas] Failed to paste image:', err)
-        }
+        await processImageFile(blob, null)
         return true
       }
       return false
@@ -1099,13 +1218,13 @@ export default function CanvasPage({ name }) {
       e.preventDefault()
 
       let type, props
-      try {
-        const parsed = new URL(text)
+      const url = looksLikeWebUrl(text)
+      if (url) {
         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 pathPortion = url.pathname + url.search + url.hash
           const src = extractPrototypeSrc(pathPortion)
           type = 'prototype'
           props = { src: src || '/', originalSrc: src || '/', label: '', width: 800, height: 600 }
@@ -1113,7 +1232,7 @@ export default function CanvasPage({ name }) {
           type = 'link-preview'
           props = { url: text, title: '' }
         }
-      } catch {
+      } else {
         type = 'markdown'
         props = { content: text }
       }
@@ -1134,10 +1253,75 @@ export default function CanvasPage({ name }) {
         console.error('[canvas] Failed to add widget from paste:', err)
       }
     }
+
     document.addEventListener('paste', handlePaste)
     return () => document.removeEventListener('paste', handlePaste)
   }, [name, undoRedo])
 
+  // --- Drag and drop handlers for images from Finder/file manager ---
+  // Separate effect to ensure listeners attach after scroll container mounts (loading=false)
+  useEffect(() => {
+    if (loading) return // Don't attach until canvas is loaded and scroll container exists
+
+    const scrollEl = scrollRef.current
+    if (!scrollEl) return
+
+    function handleDragOver(e) {
+      // Only handle if dragging files (not internal widget drag)
+      if (!e.dataTransfer?.types?.includes('Files')) return
+      e.preventDefault()
+      e.dataTransfer.dropEffect = 'copy'
+    }
+
+    async function handleDrop(e) {
+      // Only handle file drops, not internal widget drags
+      if (!e.dataTransfer?.types?.includes('Files')) return
+
+      // Prevent browser default (opening file) immediately for any file drop
+      e.preventDefault()
+      e.stopPropagation()
+
+      const files = e.dataTransfer.files
+      if (!files || files.length === 0) return
+
+      // Filter to image files only — non-images are silently ignored (default already prevented)
+      const imageFiles = Array.from(files).filter((f) => f.type.startsWith('image/'))
+      if (imageFiles.length === 0) return
+
+      // Convert drop coordinates to canvas coordinates
+      const rect = scrollEl.getBoundingClientRect()
+      const scale = zoomRef.current / 100
+
+      // Mouse position relative to scroll container
+      const mouseX = e.clientX - rect.left
+      const mouseY = e.clientY - rect.top
+
+      // Convert to canvas coordinates (account for scroll and zoom)
+      const canvasX = (scrollEl.scrollLeft + mouseX) / scale
+      const canvasY = (scrollEl.scrollTop + mouseY) / scale
+
+      // Snap to grid if enabled, using current grid size
+      const gridSize = snapGridSizeRef.current
+      const shouldSnap = snapEnabledRef.current
+      const snappedX = shouldSnap ? Math.round(canvasX / gridSize) * gridSize : Math.round(canvasX)
+      const snappedY = shouldSnap ? Math.round(canvasY / gridSize) * gridSize : Math.round(canvasY)
+
+      // Process each image file, offsetting subsequent images
+      for (let i = 0; i < imageFiles.length; i++) {
+        const offset = shouldSnap ? i * gridSize : i * 24
+        await processImageFileRef.current?.(imageFiles[i], { x: snappedX + offset, y: snappedY + offset })
+      }
+    }
+
+    scrollEl.addEventListener('dragover', handleDragOver)
+    scrollEl.addEventListener('drop', handleDrop)
+
+    return () => {
+      scrollEl.removeEventListener('dragover', handleDragOver)
+      scrollEl.removeEventListener('drop', handleDrop)
+    }
+  }, [loading])
+
   // --- Undo / Redo ---
   const handleUndo = useCallback(() => {
     const previous = undoRedo.undo(stateRef.current)
@@ -1317,54 +1501,50 @@ export default function CanvasPage({ name }) {
   // Merge JSX-sourced widgets (from .canvas.jsx) and JSON widgets
   const allChildren = []
 
-  const sourceDataByExport = Object.fromEntries(
-    (localSources || [])
-      .filter((source) => source?.export)
-      .map((source) => [source.export, source])
-  )
-
-  // 1. JSX-sourced component widgets (wrapped in WidgetChrome, not deletable)
+  // 1. Component widgets (from jsxExports or sources fallback)
   const componentFeatures = getFeatures('component')
-  if (jsxExports) {
-    for (const [exportName, Component] of Object.entries(jsxExports)) {
-      const sourceData = sourceDataByExport[exportName] || {}
-      const sourcePosition = sourceData.position || { x: 0, y: 0 }
-      allChildren.push(
-        <div
-          key={`jsx-${exportName}`}
-          id={`jsx-${exportName}`}
-          data-tc-x={sourcePosition.x}
-          data-tc-y={sourcePosition.y}
-          {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle, .tc-drag-surface' } : {})}
-          {...canvasPrimerAttrs}
-          style={canvasThemeVars}
-          onClick={isLocalDev ? (e) => {
-            e.stopPropagation()
-            if (!e.target.closest('.tc-drag-handle')) {
-              handleWidgetSelect(`jsx-${exportName}`, e.shiftKey)
-            }
-          } : undefined}
+  for (const entry of componentEntries) {
+    const { exportName, Component, sourceData } = entry
+    const sourcePosition = sourceData.position || { x: 0, y: 0 }
+    allChildren.push(
+      <div
+        key={`jsx-${exportName}`}
+        id={`jsx-${exportName}`}
+        data-tc-x={sourcePosition.x}
+        data-tc-y={sourcePosition.y}
+        {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle, .tc-drag-surface' } : {})}
+        {...canvasPrimerAttrs}
+        style={canvasThemeVars}
+        onClick={isLocalDev ? (e) => {
+          e.stopPropagation()
+          if (!e.target.closest('.tc-drag-handle')) {
+            handleWidgetSelect(`jsx-${exportName}`, e.shiftKey)
+          }
+        } : undefined}
+      >
+        <WidgetChrome
+          widgetId={`jsx-${exportName}`}
+          features={componentFeatures}
+          selected={selectedWidgetIds.has(`jsx-${exportName}`)}
+          multiSelected={isMultiSelected && selectedWidgetIds.has(`jsx-${exportName}`)}
+          onSelect={(shiftKey) => handleWidgetSelect(`jsx-${exportName}`, shiftKey)}
+          onDeselect={() => setSelectedWidgetIds(new Set())}
+          readOnly={!isLocalDev}
         >
-          <WidgetChrome
-            widgetId={`jsx-${exportName}`}
-            features={componentFeatures}
-            selected={selectedWidgetIds.has(`jsx-${exportName}`)}
-            multiSelected={isMultiSelected && selectedWidgetIds.has(`jsx-${exportName}`)}
-            onSelect={(shiftKey) => handleWidgetSelect(`jsx-${exportName}`, shiftKey)}
-            onDeselect={() => setSelectedWidgetIds(new Set())}
-            readOnly={!isLocalDev}
-          >
-            <ComponentWidget
-              component={Component}
-              width={sourceData.width}
-              height={sourceData.height}
-              onUpdate={isLocalDev ? (updates) => handleSourceUpdate(exportName, updates) : undefined}
-              resizable={isResizable('component') && isLocalDev}
-            />
-          </WidgetChrome>
-        </div>
-      )
-    }
+          <ComponentWidget
+            component={Component}
+            jsxModule={canvas?._jsxModule}
+            exportName={exportName}
+            canvasTheme={canvasTheme}
+            isLocalDev={isLocalDev}
+            width={sourceData.width}
+            height={sourceData.height}
+            onUpdate={isLocalDev ? (updates) => handleSourceUpdate(exportName, updates) : undefined}
+            resizable={isResizable('component') && isLocalDev}
+          />
+        </WidgetChrome>
+      </div>
+    )
   }
 
   // 2. JSON-defined mutable widgets (selectable, wrapped in WidgetChrome)

package/src/canvas/ComponentErrorBoundary.jsx

@@ -0,0 +1,50 @@
+import { Component } from 'react'
+
+/**
+ * Error boundary for canvas component widgets.
+ * Catches render-time errors so a single broken component
+ * doesn't crash the entire canvas page.
+ *
+ * Used as a production fallback when iframe isolation is not available.
+ */
+export default class ComponentErrorBoundary extends Component {
+  constructor(props) {
+    super(props)
+    this.state = { error: null }
+  }
+
+  static getDerivedStateFromError(error) {
+    return { error }
+  }
+
+  componentDidCatch(error, info) {
+    console.error(
+      `[storyboard] Component widget "${this.props.name || 'unknown'}" crashed:`,
+      error,
+      info?.componentStack,
+    )
+  }
+
+  render() {
+    if (this.state.error) {
+      return (
+        <div style={{
+          padding: '16px',
+          color: '#cf222e',
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          fontSize: '13px',
+          lineHeight: 1.5,
+          whiteSpace: 'pre-wrap',
+          wordBreak: 'break-word',
+          minWidth: 200,
+          minHeight: 60,
+        }}>
+          <strong>{this.props.name || 'Component'}</strong>
+          <br />
+          {String(this.state.error.message || this.state.error)}
+        </div>
+      )
+    }
+    return this.props.children
+  }
+}

package/src/canvas/canvasReloadGuard.js

@@ -0,0 +1,37 @@
+/**
+ * Canvas reload guard — client-side state for preventing HMR full reloads.
+ *
+ * This module tracks whether a canvas is currently active. When active,
+ * the Vite plugin suppresses full-page reloads to preserve canvas state.
+ *
+ * The actual guard logic is implemented in:
+ * - Server: vite.config.js (ws.send monkey-patch + heartbeat)
+ * - Client: CanvasPage.jsx (vite:beforeFullReload + vite:ws:disconnect)
+ *
+ * This module provides the state that those systems check.
+ */
+
+let active = false
+
+/**
+ * Enable the canvas reload guard.
+ * Call when a canvas page mounts.
+ */
+export function enableCanvasGuard() {
+  active = true
+}
+
+/**
+ * Disable the canvas reload guard.
+ * Call when a canvas page unmounts.
+ */
+export function disableCanvasGuard() {
+  active = false
+}
+
+/**
+ * Check if the canvas reload guard is currently active.
+ */
+export function isCanvasGuardActive() {
+  return active
+}

package/src/canvas/canvasReloadGuard.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { enableCanvasGuard, disableCanvasGuard, isCanvasGuardActive } from './canvasReloadGuard.js'
+
+describe('canvasReloadGuard', () => {
+  beforeEach(() => {
+    disableCanvasGuard()
+  })
+
+  it('starts inactive', () => {
+    expect(isCanvasGuardActive()).toBe(false)
+  })
+
+  it('can be enabled and disabled', () => {
+    enableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(true)
+    disableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(false)
+  })
+
+  it('enable is idempotent', () => {
+    enableCanvasGuard()
+    enableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(true)
+    disableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(false)
+  })
+})