@dfosco/storyboard-react 4.0.0-beta.11 → 4.0.0-beta.13

package/package.json

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

package/src/canvas/CanvasPage.jsx

@@ -12,7 +12,7 @@ import { isFigmaUrl, sanitizeFigmaUrl } from './widgets/figmaUrl.js'
 import WidgetChrome from './widgets/WidgetChrome.jsx'
 import ComponentWidget from './widgets/ComponentWidget.jsx'
 import useUndoRedo from './useUndoRedo.js'
-import { addWidget as addWidgetApi, updateCanvas, removeWidget as removeWidgetApi, uploadImage } from './canvasApi.js'
+import { addWidget as addWidgetApi, updateCanvas, removeWidget as removeWidgetApi, uploadImage, getCanvas as getCanvasApi } from './canvasApi.js'
 import styles from './CanvasPage.module.css'
 
 const ZOOM_MIN = 25
@@ -51,6 +51,7 @@ function resolveCanvasThemeFromStorage() {
  * Get the copyable URL for a widget based on its type.
  * Returns the most relevant URL/path for the widget content.
  */
+// eslint-disable-next-line no-unused-vars
 function getWidgetCopyableUrl(widget) {
   const { type, props = {} } = widget
   const base = (typeof import.meta !== 'undefined' && import.meta.env?.BASE_URL) || '/'
@@ -403,13 +404,13 @@ export default function CanvasPage({ name }) {
   // Flag to suppress the click-based selection reset that fires after a drag
   const justDraggedRef = useRef(false)
 
-  const handleItemDragStart = useCallback((dragId, position) => {
+  const handleItemDragStart = useCallback((dragId) => {
     const ids = selectedIdsRef.current
     peerArticlesRef.current.clear()
     if (ids.size <= 1 || !ids.has(dragId)) return
 
     // Suppress selection changes for the duration of the drag
-    justDraggedRef.current = true
+    justDraggedRef.current = true // eslint-disable-line react-hooks/immutability
 
     // Collect peer article elements for transition on drag end
     for (const id of ids) {
@@ -449,6 +450,8 @@ export default function CanvasPage({ name }) {
     setLocalWidgets(canvas?.widgets ?? null)
     setLocalSources(canvas?.sources ?? [])
     setCanvasTitle(canvas?.title || name)
+    setSnapEnabled(canvas?.snapToGrid ?? false)
+    setSnapGridSize(canvas?.gridSize || 40)
     undoRedo.reset()
   }
 
@@ -575,7 +578,7 @@ export default function CanvasPage({ name }) {
     if (ids.size > 1 && ids.has(dragId)) {
       transitionPeers()
       // Suppress the click-based selection reset that fires after pointerup
-      justDraggedRef.current = true
+      justDraggedRef.current = true // eslint-disable-line react-hooks/immutability
       requestAnimationFrame(() => { justDraggedRef.current = false })
       undoRedo.snapshot(stateRef.current, 'multi-move')
 
@@ -911,7 +914,7 @@ export default function CanvasPage({ name }) {
     function handleSnapToggle() {
       setSnapEnabled((prev) => {
         const next = !prev
-        updateCanvas(name, { snapToGrid: next }).catch((err) =>
+        updateCanvas(name, { settings: { snapToGrid: next } }).catch((err) =>
           console.error('[canvas] Failed to persist snap setting:', err)
         )
         return next
@@ -929,6 +932,17 @@ export default function CanvasPage({ name }) {
     snapEnabledRef.current = snapEnabled
   }, [snapEnabled])
 
+  // Respond to snap-state requests from Svelte toolbar (handles mount-order race)
+  useEffect(() => {
+    function handleRequest() {
+      document.dispatchEvent(new CustomEvent('storyboard:canvas:snap-state', {
+        detail: { snapEnabled: snapEnabledRef.current }
+      }))
+    }
+    document.addEventListener('storyboard:canvas:snap-state-request', handleRequest)
+    return () => document.removeEventListener('storyboard:canvas:snap-state-request', handleRequest)
+  }, [])
+
   // Listen for gridSize from Svelte toolbar config
   useEffect(() => {
     function handleGridSize(e) {
@@ -1015,33 +1029,13 @@ 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)
+      // Copy shortcut (single widget selected):
+      // cmd+c → copy canvasName/widgetId (for cross-canvas paste-duplicate)
       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(() => {})
-          }
-        }
+        e.preventDefault()
+        navigator.clipboard.writeText(`${name}/${widgetId}`).catch(() => {})
       }
       if (e.key === 'Delete' || e.key === 'Backspace') {
         e.preventDefault()
@@ -1217,6 +1211,40 @@ export default function CanvasPage({ name }) {
 
       e.preventDefault()
 
+      // Detect canvasName/widgetId format for widget duplication (cross-canvas copy-paste)
+      const widgetRefMatch = text.match(/^([^/]+)\/([^/]+)$/)
+      if (widgetRefMatch) {
+        const [, sourceCanvas, sourceWidgetId] = widgetRefMatch
+        // Component widgets are code, not duplicable data — silently consume the ref
+        if (sourceWidgetId.startsWith('jsx-')) return
+        try {
+          let sourceWidget = null
+          if (sourceCanvas === name) {
+            sourceWidget = (localWidgets ?? []).find(w => w.id === sourceWidgetId)
+          } else {
+            const canvasData = await getCanvasApi(sourceCanvas)
+            sourceWidget = (canvasData?.widgets ?? []).find(w => w.id === sourceWidgetId)
+          }
+          if (sourceWidget) {
+            const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
+            const pos = centerPositionForWidget(center, sourceWidget.type, sourceWidget.props)
+            undoRedo.snapshot(stateRef.current, 'add')
+            const result = await addWidgetApi(name, {
+              type: sourceWidget.type,
+              props: { ...sourceWidget.props },
+              position: pos,
+            })
+            if (result.success && result.widget) {
+              setLocalWidgets((prev) => [...(prev || []), result.widget])
+            }
+          }
+        } catch (err) {
+          console.error('[canvas] Failed to paste widget reference:', err)
+        }
+        // Always consume the ref — never fall through to markdown creation
+        return
+      }
+
       let type, props
       const url = looksLikeWebUrl(text)
       if (url) {
@@ -1256,7 +1284,7 @@ export default function CanvasPage({ name }) {
 
     document.addEventListener('paste', handlePaste)
     return () => document.removeEventListener('paste', handlePaste)
-  }, [name, undoRedo])
+  }, [name, undoRedo, localWidgets])
 
   // --- Drag and drop handlers for images from Finder/file manager ---
   // Separate effect to ensure listeners attach after scroll container mounts (loading=false)

package/src/canvas/CanvasPage.module.css

@@ -103,6 +103,12 @@
   overflow: visible;
 }
 
+/* Elevate stacking context for hovered/selected widgets so their chrome
+   (toolbar, menus, selection outline) renders above sibling widgets. */
+:global(.tc-drag:has([data-tc-elevated])) {
+  z-index: 1;
+}
+
 .localEditingLabel {
   display: inline-flex;
   align-items: center;

package/src/canvas/canvasApi.js

@@ -47,3 +47,7 @@ export function uploadImage(dataUrl, canvasName) {
 export function toggleImagePrivacy(filename) {
   return request('/image/toggle-private', 'POST', { filename })
 }
+
+export function getCanvas(name) {
+  return request(`/read?name=${encodeURIComponent(name)}`, 'GET')
+}

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 {

package/src/canvas/widgets/WidgetChrome.jsx

@@ -421,6 +421,7 @@ export default function WidgetChrome({
   return (
     <div
       className={styles.chromeContainer}
+      data-tc-elevated={(hovered || selected) || undefined}
       onMouseEnter={(readOnly && !hasFeatures) ? undefined : handleMouseEnter}
       onMouseLeave={(readOnly && !hasFeatures) ? undefined : handleMouseLeave}
     >

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/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') {

package/src/hooks/useSceneData.js

@@ -17,10 +17,12 @@ import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
  *
  * @param {string} [path] - Dot-notation path (e.g. 'user.profile.name').
  *                          Omit to get the entire flow object.
+ * @param {{ optional?: boolean }} [opts] - Pass { optional: true } to suppress
+ *                          the "path not found" warning for optional data.
  * @returns {*} The resolved value. Returns {} if path is missing after loading.
  * @throws If used outside a StoryboardProvider.
  */
-export function useFlowData(path) {
+export function useFlowData(path, opts) {
   const context = useContext(StoryboardContext)
 
   if (context === null) {
@@ -73,7 +75,7 @@ export function useFlowData(path) {
     }
 
     if (sceneValue === undefined) {
-      if (data != null && Object.keys(data).length > 0) {
+      if (!opts?.optional && data != null && Object.keys(data).length > 0) {
         console.warn(`[useFlowData] Path "${path}" not found in flow data.`)
       }
       return {}

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')
 }
 
@@ -697,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>`,
@@ -730,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
         }
 
@@ -790,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
             }
 
@@ -814,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
             }
 
@@ -823,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
           }
         }
@@ -859,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'
@@ -829,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')
+  })
+})