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

package/package.json

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

package/src/canvas/CanvasPage.jsx

@@ -257,7 +257,7 @@ function ChromeWrappedWidget({
   readOnly,
 }) {
   const widgetRef = useRef(null)
-  const features = getFeatures(widget.type)
+  const features = getFeatures(widget.type, { isLocalDev: !readOnly })
 
   const handleAction = useCallback((actionId) => {
     if (actionId === 'delete') {
@@ -1502,7 +1502,7 @@ export default function CanvasPage({ name }) {
   const allChildren = []
 
   // 1. Component widgets (from jsxExports or sources fallback)
-  const componentFeatures = getFeatures('component')
+  const componentFeatures = getFeatures('component', { isLocalDev })
   for (const entry of componentEntries) {
     const { exportName, Component, sourceData } = entry
     const sourcePosition = sourceData.position || { x: 0, y: 0 }

package/src/canvas/componentIsolate.jsx

@@ -12,6 +12,25 @@
  */
 import { createElement, Component as ReactComponent } from 'react'
 import { createRoot } from 'react-dom/client'
+import { ThemeProvider, BaseStyles } from '@primer/react'
+
+// ── Primer Primitives CSS (required for CSS variables) ──────────────
+import '@primer/primitives/dist/css/base/size/size.css'
+import '@primer/primitives/dist/css/base/typography/typography.css'
+import '@primer/primitives/dist/css/base/motion/motion.css'
+import '@primer/primitives/dist/css/functional/size/border.css'
+import '@primer/primitives/dist/css/functional/size/breakpoints.css'
+import '@primer/primitives/dist/css/functional/size/size-coarse.css'
+import '@primer/primitives/dist/css/functional/size/size-fine.css'
+import '@primer/primitives/dist/css/functional/size/size.css'
+import '@primer/primitives/dist/css/functional/size/viewport.css'
+import '@primer/primitives/dist/css/functional/typography/typography.css'
+import '@primer/primitives/dist/css/functional/themes/light.css'
+import '@primer/primitives/dist/css/functional/themes/light-colorblind.css'
+import '@primer/primitives/dist/css/functional/themes/dark.css'
+import '@primer/primitives/dist/css/functional/themes/dark-colorblind.css'
+import '@primer/primitives/dist/css/functional/themes/dark-high-contrast.css'
+import '@primer/primitives/dist/css/functional/themes/dark-dimmed.css'
 
 // ── Error Boundary ──────────────────────────────────────────────────
 class IsolateErrorBoundary extends ReactComponent {
@@ -62,6 +81,9 @@ const modulePath = params.get('module')
 const exportName = params.get('export')
 const theme = params.get('theme') || 'light'
 
+// Map theme to Primer colorMode
+const colorMode = theme.startsWith('dark') ? 'night' : 'day'
+
 // Apply theme to document for Primer / CSS-var inheritance
 document.documentElement.setAttribute('data-color-mode', theme.startsWith('dark') ? 'dark' : 'light')
 document.documentElement.setAttribute('data-dark-theme', theme.startsWith('dark') ? theme : '')
@@ -91,8 +113,12 @@ async function mount() {
     }
 
     root.render(
-      createElement(IsolateErrorBoundary, { name: exportName },
-        createElement(Component),
+      createElement(ThemeProvider, { colorMode },
+        createElement(BaseStyles, null,
+          createElement(IsolateErrorBoundary, { name: exportName },
+            createElement(Component),
+          ),
+        ),
       ),
     )
   } catch (err) {

package/src/canvas/widgets/ComponentWidget.jsx

@@ -3,6 +3,7 @@ import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
 import ComponentErrorBoundary from '../ComponentErrorBoundary.jsx'
 import styles from './ComponentWidget.module.css'
+import overlayStyles from './embedOverlay.module.css'
 
 /**
  * Renders a live JSX export from a .canvas.jsx companion file.
@@ -88,9 +89,25 @@ export default function ComponentWidget({
         </div>
         {!interactive && (
           <div
-            className={styles.interactOverlay}
-            onDoubleClick={enterInteractive}
-          />
+            className={overlayStyles.interactOverlay}
+            onClick={(e) => {
+              // Don't enter interactive mode for modifier clicks (shift/meta/ctrl for multi-select)
+              if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+              enterInteractive()
+            }}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                e.stopPropagation()
+                enterInteractive()
+              }
+            }}
+            aria-label="Click to interact with component"
+          >
+            <span className={overlayStyles.interactHint}>Click to interact</span>
+          </div>
         )}
         {resizable && (
           <ResizeHandle

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

@@ -3,6 +3,9 @@
   overflow: hidden;
   min-width: 100px;
   min-height: 60px;
+  background: var(--bgColor-default, #ffffff);
+  width: 100%;
+  height: 100%;
 }
 
 .content {
@@ -16,10 +19,3 @@
   height: 100%;
   border: none;
 }
-
-.interactOverlay {
-  position: absolute;
-  inset: 0;
-  z-index: 1;
-  cursor: default;
-}

package/src/canvas/widgets/FigmaEmbed.jsx

@@ -5,6 +5,7 @@ import { readProp } from './widgetProps.js'
 import { schemas } from './widgetConfig.js'
 import { toFigmaEmbedUrl, getFigmaTitle, getFigmaType, isFigmaUrl } from './figmaUrl.js'
 import styles from './FigmaEmbed.module.css'
+import overlayStyles from './embedOverlay.module.css'
 
 const figmaEmbedSchema = schemas['figma-embed']
 
@@ -126,9 +127,25 @@ export default forwardRef(function FigmaEmbed({ props, onUpdate, resizable }, re
             </div>
             {!interactive && !expanded && (
               <div
-                className={styles.dragOverlay}
-                onDoubleClick={enterInteractive}
-              />
+                className={overlayStyles.interactOverlay}
+                onClick={(e) => {
+                  // Don't enter interactive mode for modifier clicks (shift/meta/ctrl for multi-select)
+                  if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+                  enterInteractive()
+                }}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault()
+                    e.stopPropagation()
+                    enterInteractive()
+                  }
+                }}
+                aria-label="Click to interact with Figma embed"
+              >
+                <span className={overlayStyles.interactHint}>Click to interact</span>
+              </div>
             )}
           </>
         ) : (

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

@@ -47,13 +47,6 @@
   display: block;
 }
 
-.dragOverlay {
-  position: absolute;
-  inset: 0;
-  z-index: 1;
-  cursor: grab;
-}
-
 .resizeHandle {
   position: absolute;
   bottom: 0;

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -5,6 +5,7 @@ import WidgetWrapper from './WidgetWrapper.jsx'
 import { readProp, prototypeEmbedSchema } from './widgetProps.js'
 import { getEmbedChromeVars } from './embedTheme.js'
 import styles from './PrototypeEmbed.module.css'
+import overlayStyles from './embedOverlay.module.css'
 
 function formatName(name) {
   return name
@@ -401,9 +402,25 @@ export default forwardRef(function PrototypeEmbed({ props, onUpdate, resizable }
             </div>
             {!interactive && !expanded && (
               <div
-                className={styles.dragOverlay}
-                onDoubleClick={enterInteractive}
-              />
+                className={overlayStyles.interactOverlay}
+                onClick={(e) => {
+                  // Don't enter interactive mode for modifier clicks (shift/meta/ctrl for multi-select)
+                  if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+                  enterInteractive()
+                }}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault()
+                    e.stopPropagation()
+                    enterInteractive()
+                  }
+                }}
+                aria-label="Click to interact with prototype"
+              >
+                <span className={overlayStyles.interactHint}>Click to interact</span>
+              </div>
             )}
           </>
         ) : (

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

@@ -18,13 +18,6 @@
   display: block;
 }
 
-.dragOverlay {
-  position: absolute;
-  inset: 0;
-  z-index: 1;
-  cursor: grab;
-}
-
 .empty {
   display: flex;
   align-items: center;

package/src/canvas/widgets/WidgetChrome.jsx

@@ -411,14 +411,18 @@ export default function WidgetChrome({
     onUpdate?.({ color })
   }, [onUpdate])
 
-  const showToolbar = !readOnly && (hovered || selected)
+  // In readOnly mode, features are already filtered to prod-only by getFeatures.
+  // Show toolbar if there are prod features even when readOnly.
+  const hasFeatures = features.length > 0
+  const showToolbar = (hovered || selected) && (!readOnly || hasFeatures)
   const showFeatures = showToolbar && !multiSelected
+  const menuFeatures = features.filter((f) => f.menu)
 
   return (
     <div
       className={styles.chromeContainer}
-      onMouseEnter={readOnly ? undefined : handleMouseEnter}
-      onMouseLeave={readOnly ? undefined : handleMouseLeave}
+      onMouseEnter={(readOnly && !hasFeatures) ? undefined : handleMouseEnter}
+      onMouseLeave={(readOnly && !hasFeatures) ? undefined : handleMouseLeave}
     >
       <div className={`tc-drag-surface ${styles.widgetSlot} ${selected ? styles.widgetSlotSelected : ''} ${multiSelected ? styles.widgetSlotMultiSelected : ''}`}>
         {children}
@@ -495,22 +499,26 @@ export default function WidgetChrome({
 
               return null
             })}
-            <WidgetOverflowMenu
-              widgetId={widgetId}
-              menuFeatures={features.filter((f) => f.menu)}
-              onAction={onAction}
-            />
+            {menuFeatures.length > 0 && (
+              <WidgetOverflowMenu
+                widgetId={widgetId}
+                menuFeatures={menuFeatures}
+                onAction={onAction}
+              />
+            )}
           </div>
           )}
 
-          <Tooltip text={selected ? "Click and drag to move" : "Select"} direction="n">
-            <button
-              className={`tc-drag-handle ${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
-              onClick={handleHandleClick}
-              aria-label={selected ? "Drag to move widget" : "Select widget"}
-              aria-pressed={selected}
-            />
-          </Tooltip>
+          {!readOnly && (
+            <Tooltip text={selected ? "Click and drag to move" : "Select"} direction="n">
+              <button
+                className={`tc-drag-handle ${styles.selectHandle} ${selected ? styles.selectHandleActive : ''}`}
+                onClick={handleHandleClick}
+                aria-label={selected ? "Drag to move widget" : "Select widget"}
+                aria-pressed={selected}
+              />
+            </Tooltip>
+          )}
         </div>
       </div>
     </div>

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

@@ -33,7 +33,7 @@
   top: calc(100% + 10px);
 }
 
-/* Trigger dot — centered, visible at rest */
+/* Trigger dot — positioned in the toolbar, visible at rest */
 .triggerDot {
   width: 6px;
   height: 6px;
@@ -41,10 +41,6 @@
   background: var(--borderColor-muted, #d0d7de);
   opacity: 0.5;
   transition: opacity 120ms;
-  position: absolute;
-  left: 50%;
-  top: 50%;
-  transform: translate(-50%, -50%);
 }
 
 :global([data-sb-canvas-theme^='dark']) .triggerDot {
@@ -235,7 +231,7 @@
 .overflowMenu {
   position: absolute;
   top: calc(100% + 10px);
-  right: 0;
+  left: 0;
   min-width: max-content;
   padding: 4px;
   background: var(--bgColor-default, #ffffff);

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

@@ -11,6 +11,8 @@
 
 .content {
   position: relative;
+  width: 100%;
+  height: 100%;
 }
 
 @media (prefers-color-scheme: dark) {

package/src/canvas/widgets/embedInteraction.test.jsx

@@ -0,0 +1,155 @@
+/**
+ * Tests for embed interaction UX (click-to-interact overlay).
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, fireEvent, screen } from '@testing-library/react'
+import PrototypeEmbed from './PrototypeEmbed.jsx'
+import FigmaEmbed from './FigmaEmbed.jsx'
+import ComponentWidget from './ComponentWidget.jsx'
+
+// Mock buildPrototypeIndex for PrototypeEmbed
+vi.mock('@dfosco/storyboard-core', () => ({
+  buildPrototypeIndex: () => ({ folders: [], prototypes: [], globalFlows: [], sorted: { title: { prototypes: [], folders: [] } } }),
+}))
+
+// Simple mock wrapper for WidgetWrapper
+vi.mock('./WidgetWrapper.jsx', () => ({
+  default: ({ children }) => <div data-testid="widget-wrapper">{children}</div>,
+}))
+
+// Mock ResizeHandle
+vi.mock('./ResizeHandle.jsx', () => ({
+  default: () => <div data-testid="resize-handle" />,
+}))
+
+// Mock ComponentErrorBoundary
+vi.mock('../ComponentErrorBoundary.jsx', () => ({
+  default: ({ children }) => <div data-testid="error-boundary">{children}</div>,
+}))
+
+describe('Embed interaction overlay', () => {
+  describe('PrototypeEmbed', () => {
+    const defaultProps = {
+      props: { src: '/test', width: 400, height: 300, zoom: 100 },
+      onUpdate: vi.fn(),
+      resizable: false,
+    }
+
+    it('renders "Click to interact" hint on hover', () => {
+      render(<PrototypeEmbed {...defaultProps} />)
+      
+      const hint = screen.getByText('Click to interact')
+      expect(hint).toBeInTheDocument()
+      // CSS modules mangle class names, just check the element exists
+    })
+
+    it('enters interactive mode on single click (not double-click)', async () => {
+      render(<PrototypeEmbed {...defaultProps} />)
+      
+      // Overlay should exist before interaction
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      expect(overlay).toBeInTheDocument()
+      
+      // Single click should remove the overlay (enter interactive mode)
+      fireEvent.click(overlay)
+      
+      // Overlay should no longer exist
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+    })
+
+    it('does not enter interactive mode on shift+click (preserves multi-select)', () => {
+      render(<PrototypeEmbed {...defaultProps} />)
+      
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      fireEvent.click(overlay, { shiftKey: true })
+      
+      // Overlay should still exist (did not enter interactive mode)
+      expect(screen.getByRole('button', { name: /click to interact/i })).toBeInTheDocument()
+    })
+
+    it('does not enter interactive mode on meta+click (preserves multi-select)', () => {
+      render(<PrototypeEmbed {...defaultProps} />)
+      
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      fireEvent.click(overlay, { metaKey: true })
+      
+      expect(screen.getByRole('button', { name: /click to interact/i })).toBeInTheDocument()
+    })
+
+    it('supports keyboard interaction (Enter key) with event prevention', () => {
+      render(<PrototypeEmbed {...defaultProps} />)
+      
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const event = { key: 'Enter', preventDefault: vi.fn(), stopPropagation: vi.fn() }
+      fireEvent.keyDown(overlay, event)
+      
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+    })
+
+    it('supports keyboard interaction (Space key) with event prevention', () => {
+      render(<PrototypeEmbed {...defaultProps} />)
+      
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const event = { key: ' ', preventDefault: vi.fn(), stopPropagation: vi.fn() }
+      fireEvent.keyDown(overlay, event)
+      
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+    })
+  })
+
+  describe('FigmaEmbed', () => {
+    const defaultProps = {
+      props: { url: 'https://www.figma.com/design/abc123/Test', width: 400, height: 300 },
+      onUpdate: vi.fn(),
+      resizable: false,
+    }
+
+    it('renders "Click to interact" hint', () => {
+      render(<FigmaEmbed {...defaultProps} />)
+      
+      const hint = screen.getByText('Click to interact')
+      expect(hint).toBeInTheDocument()
+    })
+
+    it('enters interactive mode on single click', () => {
+      render(<FigmaEmbed {...defaultProps} />)
+      
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      fireEvent.click(overlay)
+      
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+    })
+  })
+
+  describe('ComponentWidget', () => {
+    const MockComponent = () => <div>Mock Component</div>
+    
+    const defaultProps = {
+      component: MockComponent,
+      jsxModule: null,
+      exportName: 'MockComponent',
+      canvasTheme: 'light',
+      isLocalDev: false,
+      width: 200,
+      height: 150,
+      onUpdate: vi.fn(),
+      resizable: false,
+    }
+
+    it('renders "Click to interact" hint', () => {
+      render(<ComponentWidget {...defaultProps} />)
+      
+      const hint = screen.getByText('Click to interact')
+      expect(hint).toBeInTheDocument()
+    })
+
+    it('enters interactive mode on single click', () => {
+      render(<ComponentWidget {...defaultProps} />)
+      
+      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      fireEvent.click(overlay)
+      
+      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+    })
+  })
+})

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

@@ -0,0 +1,35 @@
+/**
+ * Shared styles for embed interaction overlays.
+ * Used by PrototypeEmbed, FigmaEmbed, and ComponentWidget.
+ */
+
+.interactOverlay {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 150ms ease;
+}
+
+.interactOverlay:hover {
+  background-color: rgba(0, 0, 0, 0.15);
+}
+
+.interactHint {
+  opacity: 0;
+  color: var(--fgColor-onInverse);
+  background-color: var(--bgColor-inverse);
+  padding: var(--base-size-12) var(--base-size-16);
+  border-radius: var(--base-size-6);
+  font-size: 14px;
+  font-weight: 600;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+}
+
+.interactOverlay:hover .interactHint {
+  opacity: 1;
+}

package/src/canvas/widgets/widgetConfig.js

@@ -34,7 +34,16 @@ function resolveFeature(feature) {
     if (key === 'items' && Array.isArray(val)) {
       resolved[key] = val.map((item) => {
         const r = {}
-        for (const [k, v] of Object.entries(item)) r[k] = resolveVar(v)
+        for (const [k, v] of Object.entries(item)) {
+          // Resolve nested alt object inside items
+          if (k === 'alt' && v && typeof v === 'object') {
+            const altResolved = {}
+            for (const [ak, av] of Object.entries(v)) altResolved[ak] = resolveVar(av)
+            r[k] = altResolved
+          } else {
+            r[k] = resolveVar(v)
+          }
+        }
         return r
       })
     } else if (key === 'alt' && val && typeof val === 'object') {
@@ -103,14 +112,16 @@ export const widgetTypes = buildWidgetTypes()
 
 /**
  * Get the feature list for a widget type.
- * In production, only features with `prod: true` are returned.
+ * In production (or when isLocalDev is false, e.g. ?prodMode simulation),
+ * only features with `prod: true` are returned.
  * In dev, all features are returned.
  * @param {string} type — widget type string
+ * @param {{ isLocalDev?: boolean }} [options]
  * @returns {Array} features array from config (variables resolved), or empty array
  */
-export function getFeatures(type) {
+export function getFeatures(type, { isLocalDev = true } = {}) {
   const features = widgetTypes[type]?.features ?? []
-  if (import.meta.env?.PROD) {
+  if (import.meta.env?.PROD || !isLocalDev) {
     return features.filter(f => f.prod)
   }
   return features

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

@@ -32,6 +32,25 @@ describe('getFeatures', () => {
   it('returns empty array for unknown widget types', () => {
     expect(getFeatures('nonexistent')).toEqual([])
   })
+
+  it('returns only prod features when isLocalDev is false', () => {
+    const features = getFeatures('figma-embed', { isLocalDev: false })
+    expect(features.length).toBeGreaterThan(0)
+    expect(features.every(f => f.prod === true)).toBe(true)
+  })
+
+  it('returns all features when isLocalDev is true (default)', () => {
+    const allFeatures = getFeatures('figma-embed')
+    const prodFeatures = getFeatures('figma-embed', { isLocalDev: false })
+    expect(allFeatures.length).toBeGreaterThan(prodFeatures.length)
+  })
+
+  it('includes menu-only prod features when isLocalDev is false', () => {
+    const features = getFeatures('figma-embed', { isLocalDev: false })
+    const menuFeature = features.find(f => f.menu)
+    expect(menuFeature).toBeDefined()
+    expect(menuFeature.prod).toBe(true)
+  })
 })
 
 describe('getWidgetMeta', () => {

package/src/vite/data-plugin.js

@@ -633,6 +633,22 @@ function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root)
     `export { flows, scenes, objects, records, prototypes, folders, canvases }`,
     `export const index = { flows, scenes, objects, records, prototypes, folders, canvases }`,
     `export default index`,
+    '',
+    '// Live-patch canvas data on HMR events so SPA navigation shows fresh state',
+    'if (import.meta.hot) {',
+    '  import.meta.hot.on("storyboard:canvas-file-changed", (data) => {',
+    '    if (!data) return',
+    '    if (data.removed) {',
+    '      delete canvases[data.name]',
+    '    } else if (data.metadata) {',
+    '      // Merge into existing entry to preserve build-time fields (_jsxModule, _jsxImport, etc.)',
+    '      canvases[data.name] = canvases[data.name]',
+    '        ? Object.assign({}, canvases[data.name], data.metadata)',
+    '        : data.metadata',
+    '    }',
+    '    init({ flows, objects, records, prototypes, folders, canvases })',
+    '  })',
+    '}',
   ].join('\n')
 }
 
@@ -655,10 +671,11 @@ export default function storyboardDataPlugin() {
     config() {
       return {
         optimizeDeps: {
-          // debug is CJS-only but micromark's development export does
-          // `import createDebug from 'debug'`. Vite must pre-bundle it
-          // so the ESM default import resolves correctly.
-          include: ['debug'],
+          // @dfosco/storyboard-react is excluded (virtual module), so Vite
+          // can't trace into its deps. Include the remark entry points so
+          // Vite pre-bundles the full chain — covers all transitive CJS
+          // packages (debug, extend, etc.) without whack-a-mole.
+          include: ['remark', 'remark-gfm', 'remark-html'],
           exclude: ['@dfosco/storyboard-react'],
         },
       }
@@ -696,7 +713,7 @@ export default function storyboardDataPlugin() {
         const rawHtml = [
           '<!DOCTYPE html>',
           '<html><head>',
-          '<style>html,body{margin:0;padding:0;width:100%;height:100%}#root{width:100%;height:100%}</style>',
+          '<style>html,body{margin:0;padding:0;width:100%;height:100%;background:var(--bgColor-default,transparent)}#root{width:100%;height:100%}</style>',
           '</head><body>',
           '<div id="root"></div>',
           `<script type="module" src="/@fs${isolateEntryPath}"></script>`,
@@ -729,22 +746,50 @@ export default function storyboardDataPlugin() {
         }
       }
 
+      // Mark the virtual module as stale so the next page load rebuilds it,
+      // but do NOT trigger a full-reload (avoids losing canvas editing state).
+      const softInvalidate = () => {
+        buildResult = null
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
+        if (mod) server.moduleGraph.invalidateModule(mod)
+      }
+
+      // Read a canvas file and build HMR metadata for the client-side listener.
+      const readCanvasMetadata = (filePath, parsed) => {
+        try {
+          const absPath = path.resolve(root, filePath)
+          const raw = fs.readFileSync(absPath, 'utf-8')
+          const materialized = materializeFromText(raw)
+          const result = { ...materialized }
+          // Inject _route and _folder the same way generateModule does
+          if (parsed.inferredRoute) result._route = parsed.inferredRoute
+          const folderDirMatch = path.relative(root, absPath).replace(/\\/g, '/').match(/(?:^|\/)src\/(?:prototypes|canvas)\/([^/]+)\.folder\//)
+          if (folderDirMatch) result._folder = folderDirMatch[1]
+          return result
+        } catch {
+          return null
+        }
+      }
+
       const invalidate = (filePath) => {
         const normalized = filePath.replace(/\\/g, '/')
-        // Skip .canvas.jsonl content changes entirely — these are mutated
-        // at runtime by the canvas server API. A full-reload would create
-        // a feedback loop (save → file change → reload → lose editing state).
-        // Instead, send a custom HMR event so the active canvas page can refetch
-        // file-backed data in place with no navigation or document reload.
+        // Canvas .jsonl content changes are mutated at runtime by the canvas
+        // server API. A full-reload would create a feedback loop (save →
+        // file change → reload → lose editing state). Instead, soft-invalidate
+        // the virtual module (so page refresh picks up changes) and send a
+        // custom HMR event with updated metadata so the canvas page and
+        // viewfinder can react in place.
         if (/\.canvas\.jsonl$/.test(normalized)) {
           const parsed = parseDataFile(filePath)
           if (parsed?.suffix === 'canvas' && parsed?.name) {
+            const metadata = readCanvasMetadata(filePath, parsed)
             server.ws.send({
               type: 'custom',
               event: 'storyboard:canvas-file-changed',
-              data: { name: parsed.name },
+              data: { name: parsed.name, ...(metadata ? { metadata } : {}) },
             })
           }
+          softInvalidate()
           return
         }
 
@@ -789,23 +834,27 @@ export default function storyboardDataPlugin() {
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { name, removed: true },
               })
+              softInvalidate()
             }, 1500)
             pendingCanvasUnlinks.set(name, timer)
             return
           }
 
           if (eventType === 'add') {
+            const metadata = readCanvasMetadata(filePath, parsed)
             const pending = pendingCanvasUnlinks.get(name)
             if (pending) {
+              // unlink+add pair = in-place save (atomic write), not a real remove
               clearTimeout(pending)
               pendingCanvasUnlinks.delete(name)
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { name, ...(metadata ? { metadata } : {}) },
               })
+              softInvalidate()
               return
             }
 
@@ -813,8 +862,9 @@ export default function storyboardDataPlugin() {
               server.ws.send({
                 type: 'custom',
                 event: 'storyboard:canvas-file-changed',
-                data: { name },
+                data: { name, ...(metadata ? { metadata } : {}) },
               })
+              softInvalidate()
               return
             }
 
@@ -822,8 +872,9 @@ export default function storyboardDataPlugin() {
             server.ws.send({
               type: 'custom',
               event: 'storyboard:canvas-file-changed',
-              data: { name },
+              data: { name, ...(metadata ? { metadata } : {}) },
             })
+            softInvalidate()
             return
           }
         }
@@ -858,18 +909,10 @@ export default function storyboardDataPlugin() {
       const normalized = ctx.file.replace(/\\/g, '/')
       if (!/\.canvas\.jsonl$/.test(normalized)) return
 
-      const parsed = parseDataFile(ctx.file)
-      if (parsed?.suffix === 'canvas' && parsed?.name) {
-        ctx.server.ws.send({
-          type: 'custom',
-          event: 'storyboard:canvas-file-changed',
-          data: { name: parsed.name },
-        })
-      }
-
       // Prevent Vite's default fallback behavior (full page reload) for
-      // non-module .canvas.jsonl edits. Canvas pages consume these updates
-      // through the custom WS event and in-page refetch.
+      // non-module .canvas.jsonl edits. The watcher 'change' handler
+      // (invalidate) already sends the custom HMR event and soft-invalidates
+      // the virtual module — no duplicate event needed here.
       return []
     },
 

package/src/vite/data-plugin.test.js

@@ -1,4 +1,4 @@
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import storyboardDataPlugin, { resolveTemplateVars, computeTemplateVars } from './data-plugin.js'
@@ -53,10 +53,12 @@ describe('storyboardDataPlugin', () => {
     expect(config.optimizeDeps.exclude).toContain('@dfosco/storyboard-react')
   })
 
-  it('config() includes debug in optimizeDeps for ESM/CJS interop', () => {
+  it('config() includes remark stack in optimizeDeps so Vite pre-bundles transitive CJS deps', () => {
     const plugin = storyboardDataPlugin()
     const config = plugin.config()
-    expect(config.optimizeDeps.include).toContain('debug')
+    expect(config.optimizeDeps.include).toContain('remark')
+    expect(config.optimizeDeps.include).toContain('remark-gfm')
+    expect(config.optimizeDeps.include).toContain('remark-html')
   })
 
   it("resolveId returns resolved ID for 'virtual:storyboard-data-index'", () => {
@@ -827,3 +829,220 @@ describe('template variable integration', () => {
     warnSpy.mockRestore()
   })
 })
+
+// ── Canvas watcher / HMR tests ──────────────────────────────────────
+
+describe('canvas watcher behavior', () => {
+  /** Helper: create a mock Vite dev server for configureServer */
+  function createMockServer(root) {
+    const listeners = {}
+    const wsSent = []
+    const invalidatedModules = []
+
+    return {
+      wsSent,
+      invalidatedModules,
+      listeners,
+      config: { root, base: '/' },
+      watcher: {
+        add: vi.fn(),
+        on(event, fn) {
+          if (!listeners[event]) listeners[event] = []
+          listeners[event].push(fn)
+        },
+      },
+      moduleGraph: {
+        getModuleById(id) {
+          if (id === RESOLVED_ID) return { id: RESOLVED_ID }
+          return null
+        },
+        invalidateModule(mod) {
+          invalidatedModules.push(mod.id)
+        },
+      },
+      ws: {
+        send(msg) { wsSent.push(msg) },
+      },
+      middlewares: {
+        use: vi.fn(),
+      },
+    }
+  }
+
+  /** Emit a watcher event on the mock server */
+  function emit(server, event, filePath) {
+    for (const fn of (server.listeners[event] || [])) {
+      fn(filePath)
+    }
+  }
+
+  function writeCanvasFile(dir, name, title) {
+    const canvasDir = path.join(dir, 'src', 'canvas')
+    mkdirSync(canvasDir, { recursive: true })
+    const evt = { event: 'canvas_created', title: title || name, timestamp: Date.now() }
+    writeFileSync(path.join(canvasDir, `${name}.canvas.jsonl`), JSON.stringify(evt) + '\n')
+  }
+
+  it('soft-invalidates virtual module on canvas content change (no full-reload)', () => {
+    writeCanvasFile(tmpDir, 'test-canvas', 'Original Title')
+    const plugin = createPlugin()
+    // Force initial buildResult
+    plugin.load(RESOLVED_ID)
+
+    const server = createMockServer(tmpDir)
+    plugin.configureServer(server)
+
+    // Simulate a canvas file content change
+    const canvasPath = path.join(tmpDir, 'src', 'canvas', 'test-canvas.canvas.jsonl')
+    emit(server, 'change', canvasPath)
+
+    // Should have sent custom HMR event (not full-reload)
+    const customEvents = server.wsSent.filter(m => m.type === 'custom')
+    const fullReloads = server.wsSent.filter(m => m.type === 'full-reload')
+
+    expect(customEvents.length).toBe(1)
+    expect(customEvents[0].event).toBe('storyboard:canvas-file-changed')
+    expect(customEvents[0].data.name).toBe('test-canvas')
+    expect(fullReloads.length).toBe(0)
+
+    // Should have invalidated the virtual module
+    expect(server.invalidatedModules).toContain(RESOLVED_ID)
+  })
+
+  it('includes metadata in HMR event for canvas content changes', () => {
+    writeCanvasFile(tmpDir, 'meta-canvas', 'My Canvas Title')
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const server = createMockServer(tmpDir)
+    plugin.configureServer(server)
+
+    emit(server, 'change', path.join(tmpDir, 'src', 'canvas', 'meta-canvas.canvas.jsonl'))
+
+    const event = server.wsSent.find(m => m.type === 'custom')
+    expect(event.data.metadata).toBeDefined()
+    expect(event.data.metadata.title).toBe('My Canvas Title')
+  })
+
+  it('soft-invalidates on canvas file add (new canvas)', () => {
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const server = createMockServer(tmpDir)
+    plugin.configureServer(server)
+
+    // Create the file after the server is configured
+    writeCanvasFile(tmpDir, 'new-canvas', 'Brand New')
+    emit(server, 'add', path.join(tmpDir, 'src', 'canvas', 'new-canvas.canvas.jsonl'))
+
+    const customEvents = server.wsSent.filter(m => m.type === 'custom')
+    const fullReloads = server.wsSent.filter(m => m.type === 'full-reload')
+
+    expect(customEvents.length).toBe(1)
+    expect(customEvents[0].data.name).toBe('new-canvas')
+    expect(customEvents[0].data.metadata).toBeDefined()
+    expect(fullReloads.length).toBe(0)
+    expect(server.invalidatedModules).toContain(RESOLVED_ID)
+  })
+
+  it('soft-invalidates on canvas file unlink after timeout (true delete)', async () => {
+    writeCanvasFile(tmpDir, 'doomed-canvas', 'Gone Soon')
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const server = createMockServer(tmpDir)
+    plugin.configureServer(server)
+
+    emit(server, 'unlink', path.join(tmpDir, 'src', 'canvas', 'doomed-canvas.canvas.jsonl'))
+
+    // Immediately after unlink — no event yet (deferred by 1500ms)
+    expect(server.wsSent.length).toBe(0)
+
+    // Wait for deferred timer
+    await new Promise(resolve => setTimeout(resolve, 1600))
+
+    const customEvents = server.wsSent.filter(m => m.type === 'custom')
+    expect(customEvents.length).toBe(1)
+    expect(customEvents[0].data.name).toBe('doomed-canvas')
+    expect(customEvents[0].data.removed).toBe(true)
+    expect(server.invalidatedModules).toContain(RESOLVED_ID)
+  })
+
+  it('cancels deferred unlink on add (atomic write / in-place save)', async () => {
+    writeCanvasFile(tmpDir, 'saved-canvas', 'Saved')
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const server = createMockServer(tmpDir)
+    plugin.configureServer(server)
+
+    const canvasPath = path.join(tmpDir, 'src', 'canvas', 'saved-canvas.canvas.jsonl')
+
+    // Simulate atomic write: unlink then add within 1500ms
+    emit(server, 'unlink', canvasPath)
+    emit(server, 'add', canvasPath)
+
+    // Should have sent one event immediately (the add cancelling the unlink)
+    const customEvents = server.wsSent.filter(m => m.type === 'custom')
+    expect(customEvents.length).toBe(1)
+    expect(customEvents[0].data.name).toBe('saved-canvas')
+    expect(customEvents[0].data.removed).toBeUndefined()
+    expect(server.invalidatedModules).toContain(RESOLVED_ID)
+
+    // Wait past the unlink timer — should NOT get a second event
+    await new Promise(resolve => setTimeout(resolve, 1600))
+    const allCustom = server.wsSent.filter(m => m.type === 'custom')
+    expect(allCustom.length).toBe(1)
+  })
+
+  it('handleHotUpdate returns empty array for canvas files (suppresses full-reload)', () => {
+    const plugin = createPlugin()
+    const result = plugin.handleHotUpdate({
+      file: path.join(tmpDir, 'src', 'canvas', 'test.canvas.jsonl'),
+      server: createMockServer(tmpDir),
+      modules: [],
+    })
+    expect(result).toEqual([])
+  })
+
+  it('handleHotUpdate does not send duplicate HMR events', () => {
+    const plugin = createPlugin()
+    const server = createMockServer(tmpDir)
+    plugin.handleHotUpdate({
+      file: path.join(tmpDir, 'src', 'canvas', 'test.canvas.jsonl'),
+      server,
+      modules: [],
+    })
+    // handleHotUpdate should NOT send events (invalidate() handles it)
+    expect(server.wsSent.length).toBe(0)
+  })
+
+  it('generated virtual module includes HMR listener for canvas updates', () => {
+    writeCanvasFile(tmpDir, 'hmr-canvas', 'HMR Test')
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('import.meta.hot')
+    expect(code).toContain('storyboard:canvas-file-changed')
+    expect(code).toContain('data.removed')
+    expect(code).toContain('data.metadata')
+    // Should merge into existing entries to preserve build-time fields
+    expect(code).toContain('Object.assign')
+  })
+
+  it('page refresh after canvas add yields updated module with new canvas', () => {
+    const plugin = createPlugin()
+    // First load — no canvases
+    const code1 = plugin.load(RESOLVED_ID)
+    expect(code1).not.toContain('"refresh-canvas"')
+
+    // Simulate adding a canvas and clearing buildResult (what softInvalidate does)
+    writeCanvasFile(tmpDir, 'refresh-canvas', 'After Refresh')
+
+    // Manually clear buildResult by loading a fresh plugin instance with the same root
+    const plugin2 = createPlugin()
+    const code2 = plugin2.load(RESOLVED_ID)
+    expect(code2).toContain('"refresh-canvas"')
+    expect(code2).toContain('After Refresh')
+  })
+})