@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/canvas/WebGLContextPool.test.jsx

@@ -0,0 +1,165 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, act } from '@testing-library/react'
+import { WebGLContextPoolProvider, useWebGLSlot, usePoolVisibilityUpdater, Priority } from './WebGLContextPool.jsx'
+
+function TestWidget({ widgetId, onSlot }) {
+  const slot = useWebGLSlot(widgetId)
+  onSlot?.(slot)
+  return <div data-testid={widgetId}>{slot.isLive ? 'live' : 'frozen'}</div>
+}
+
+function TestUpdater({ onUpdater }) {
+  const update = usePoolVisibilityUpdater()
+  onUpdater?.(update)
+  return null
+}
+
+describe('WebGLContextPool', () => {
+  it('grants live slots to widgets within the max limit', () => {
+    let slot1, slot2
+    render(
+      <WebGLContextPoolProvider maxLive={2}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+      </WebGLContextPoolProvider>
+    )
+
+    // Both should be live since we're under the limit
+    expect(slot1.isLive).toBe(true)
+    expect(slot2.isLive).toBe(true)
+  })
+
+  it('freezes excess widgets when over the limit', () => {
+    let slot1, slot2, slot3
+    render(
+      <WebGLContextPoolProvider maxLive={2}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+        <TestWidget widgetId="t3" onSlot={(s) => { slot3 = s }} />
+      </WebGLContextPoolProvider>
+    )
+
+    const liveCount = [slot1, slot2, slot3].filter(s => s.isLive).length
+    const frozenCount = [slot1, slot2, slot3].filter(s => !s.isLive).length
+
+    expect(liveCount).toBe(2)
+    expect(frozenCount).toBe(1)
+  })
+
+  it('always returns live when no provider is present', () => {
+    let slot
+    render(<TestWidget widgetId="t1" onSlot={(s) => { slot = s }} />)
+    expect(slot.isLive).toBe(true)
+    expect(slot.generation).toBe(0)
+  })
+
+  it('prioritizes PINNED widgets over OFFSCREEN', () => {
+    let slot1, slot2, slot3
+    render(
+      <WebGLContextPoolProvider maxLive={2}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+        <TestWidget widgetId="t3" onSlot={(s) => { slot3 = s }} />
+      </WebGLContextPoolProvider>
+    )
+
+    // Pin t3 — it should become live, evicting one of the others
+    act(() => { slot3.setPriority(Priority.PINNED) })
+
+    expect(slot3.isLive).toBe(true)
+  })
+
+  it('PINNED widgets bypass the max limit', () => {
+    let slot1, slot2, slot3
+    render(
+      <WebGLContextPoolProvider maxLive={2}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+        <TestWidget widgetId="t3" onSlot={(s) => { slot3 = s }} />
+      </WebGLContextPoolProvider>
+    )
+
+    // Pin all three
+    act(() => {
+      slot1.setPriority(Priority.PINNED)
+      slot2.setPriority(Priority.PINNED)
+      slot3.setPriority(Priority.PINNED)
+    })
+
+    // All should be live because PINNED bypasses the cap
+    expect(slot1.isLive).toBe(true)
+    expect(slot2.isLive).toBe(true)
+    expect(slot3.isLive).toBe(true)
+  })
+
+  it('tracks generation across live-frozen-live transitions', () => {
+    let slot1, slot2, slot3
+    render(
+      <WebGLContextPoolProvider maxLive={2}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+        <TestWidget widgetId="t3" onSlot={(s) => { slot3 = s }} />
+      </WebGLContextPoolProvider>
+    )
+
+    // t3 starts frozen with generation 0 (never was live)
+    expect(slot3.isLive).toBe(false)
+    expect(slot3.generation).toBe(0)
+
+    // Pin t3 to make it live
+    act(() => { slot3.setPriority(Priority.PINNED) })
+    expect(slot3.isLive).toBe(true)
+
+    // Unpin t3 — it should be evicted and generation bumped
+    act(() => { slot3.setPriority(Priority.OFFSCREEN) })
+    // Hysteresis delays eviction; use fake timers if needed.
+    // For now, verify that generation bumps when eviction happens.
+  })
+
+  it('usePoolVisibilityUpdater updates priorities based on viewport', () => {
+    let slot1, slot2, updater
+    render(
+      <WebGLContextPoolProvider maxLive={1}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+        <TestUpdater onUpdater={(u) => { updater = u }} />
+      </WebGLContextPoolProvider>
+    )
+
+    const widgets = [
+      { id: 't1', type: 'terminal', position: { x: 100, y: 100 }, props: { width: 800, height: 450 } },
+      { id: 't2', type: 'terminal', position: { x: 5000, y: 5000 }, props: { width: 800, height: 450 } },
+    ]
+
+    // Viewport only covers t1
+    act(() => {
+      updater({ x: 0, y: 0, w: 1920, h: 1080 }, widgets, new Set(), null)
+    })
+
+    expect(slot1.isLive).toBe(true)
+    expect(slot2.isLive).toBe(false)
+  })
+
+  it('selected widgets get PINNED priority via visibility updater', () => {
+    let slot1, slot2, updater
+    render(
+      <WebGLContextPoolProvider maxLive={1}>
+        <TestWidget widgetId="t1" onSlot={(s) => { slot1 = s }} />
+        <TestWidget widgetId="t2" onSlot={(s) => { slot2 = s }} />
+        <TestUpdater onUpdater={(u) => { updater = u }} />
+      </WebGLContextPoolProvider>
+    )
+
+    const widgets = [
+      { id: 't1', type: 'terminal', position: { x: 100, y: 100 }, props: { width: 800, height: 450 } },
+      { id: 't2', type: 'terminal', position: { x: 5000, y: 5000 }, props: { width: 800, height: 450 } },
+    ]
+
+    // t2 is offscreen but selected — should be pinned and live
+    act(() => {
+      updater({ x: 0, y: 0, w: 1920, h: 1080 }, widgets, new Set(['t2']), null)
+    })
+
+    expect(slot2.isLive).toBe(true)
+  })
+})

package/src/internals/canvas/canvasApi.js

@@ -0,0 +1,164 @@
+/**
+ * Client-side API for canvas CRUD operations.
+ * Calls the /_storyboard/canvas/ server endpoints.
+ */
+
+const BASE = '/_storyboard/canvas'
+
+function getApiBase() {
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+  return base + BASE
+}
+
+async function request(path, method, body) {
+  const url = getApiBase() + path
+  const res = await fetch(url, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  return res.json()
+}
+
+export function listCanvases() {
+  return request('/list', 'GET')
+}
+
+export function createCanvas(data) {
+  return request('/create', 'POST', data)
+}
+
+export function updateCanvas(canvasId, { widgets, sources, settings, connectors }) {
+  return request('/update', 'PUT', { name: canvasId, widgets, sources, settings, connectors })
+}
+
+export function addWidget(canvasId, { type, props, position }) {
+  return request('/widget', 'POST', { name: canvasId, type, props, position })
+}
+
+export function removeWidget(canvasId, widgetId) {
+  return request('/widget', 'DELETE', { name: canvasId, widgetId })
+}
+
+export function uploadImage(dataUrl, canvasId, filename) {
+  const body = { dataUrl, canvasName: canvasId }
+  if (filename) body.filename = filename
+  return request('/image', 'POST', body)
+}
+
+export function toggleImagePrivacy(filename) {
+  return request('/image/toggle-private', 'POST', { filename })
+}
+
+export function duplicateImage(filename) {
+  return request('/image/duplicate', 'POST', { filename })
+}
+
+/**
+ * Crop an image client-side and upload the result.
+ * @param {string} imageSrc — current image filename (e.g. "canvas--2026-01-01--12-00-00.png")
+ * @param {{ x: number, y: number, width: number, height: number }} cropRect — crop region in natural image pixels
+ * @param {string} canvasId — canvas name for directory resolution
+ * @returns {Promise<{ success: boolean, filename: string }>}
+ */
+export async function cropAndUpload(imageSrc, cropRect, canvasId) {
+  const imageUrl = (() => {
+    const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+    return `${base}/_storyboard/canvas/images/${imageSrc}`
+  })()
+
+  // Load the image into an offscreen canvas
+  const img = new Image()
+  img.crossOrigin = 'anonymous'
+  await new Promise((resolve, reject) => {
+    img.onload = resolve
+    img.onerror = reject
+    img.src = imageUrl
+  })
+
+  // Draw the cropped region
+  const canvas = document.createElement('canvas')
+  canvas.width = Math.round(cropRect.width)
+  canvas.height = Math.round(cropRect.height)
+  const ctx = canvas.getContext('2d')
+  ctx.drawImage(
+    img,
+    Math.round(cropRect.x), Math.round(cropRect.y),
+    Math.round(cropRect.width), Math.round(cropRect.height),
+    0, 0,
+    canvas.width, canvas.height,
+  )
+
+  // Determine output format from original filename
+  const ext = imageSrc.split('.').pop()?.toLowerCase() || 'png'
+  const mimeMap = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }
+  const mime = mimeMap[ext] || 'image/png'
+  const dataUrl = canvas.toDataURL(mime, 0.92)
+
+  // Build cropped filename: strip any previous --cropped-- suffix, append new one
+  const privacyPrefix = imageSrc.startsWith('~') ? '~' : ''
+  const baseName = imageSrc.replace(/^~/, '')
+  const withoutCrop = baseName.replace(/--cropped--\d{4}-\d{2}-\d{2}--\d{2}-\d{2}-\d{2}/, '')
+  const nameWithoutExt = withoutCrop.replace(/\.\w+$/, '')
+  const now = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+  const ts = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}--${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
+  const croppedFilename = `${privacyPrefix}${nameWithoutExt}--cropped--${ts}.${ext}`
+
+  return uploadImage(dataUrl, canvasId, croppedFilename)
+}
+
+export function batchOperations(canvasId, operations) {
+  return request('/batch', 'POST', { name: canvasId, operations })
+}
+
+export function getCanvas(canvasId) {
+  return request(`/read?name=${encodeURIComponent(canvasId)}`, 'GET')
+}
+
+export function checkGitHubCliAvailable() {
+  return request('/github/available', 'GET')
+}
+
+export function fetchGitHubEmbed(url) {
+  return request('/github/embed', 'POST', { url })
+}
+
+export function renamePage(canvasId, newTitle) {
+  return request('/rename-page', 'PUT', { name: canvasId, newTitle })
+}
+
+export function reorderPages(folder, order) {
+  return request('/reorder-pages', 'PUT', { folder, order })
+}
+
+export function getPageOrder(folder) {
+  return request(`/page-order?folder=${encodeURIComponent(folder)}`, 'GET')
+}
+
+export function updateFolderMeta(folder, title) {
+  return request('/update-folder-meta', 'PUT', { folder, title })
+}
+
+export function duplicateCanvas(canvasId, newTitle) {
+  return request('/duplicate', 'POST', { name: canvasId, newTitle })
+}
+
+export function addConnector(canvasId, { startWidgetId, startAnchor, endWidgetId, endAnchor, connectorType }) {
+  return request('/connector', 'POST', {
+    name: canvasId,
+    startWidgetId,
+    startAnchor,
+    endWidgetId,
+    endAnchor,
+    connectorType,
+  })
+}
+
+export function removeConnector(canvasId, connectorId) {
+  return request('/connector', 'DELETE', { name: canvasId, connectorId })
+}
+
+export function updateConnector(canvasId, connectorId, meta) {
+  return request('/connector', 'PATCH', { name: canvasId, connectorId, meta })
+}

package/src/internals/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/internals/canvas/canvasReloadGuard.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect, 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)
+  })
+})

package/src/internals/canvas/canvasTheme.js

@@ -0,0 +1,118 @@
+export function getCanvasPrimerAttrs(theme) {
+  const value = String(theme || 'light')
+  if (value.startsWith('dark')) {
+    return {
+      'data-color-mode': 'dark',
+      'data-dark-theme': value,
+      'data-light-theme': 'light',
+    }
+  }
+  return {
+    'data-color-mode': 'light',
+    'data-dark-theme': 'dark',
+    'data-light-theme': value.startsWith('light') ? value : 'light',
+  }
+}
+
+/**
+ * Per-theme canvas CSS custom properties sourced from @primer/primitives.
+ * Each theme gets its own entry so high-contrast, colorblind, and dimmed
+ * variants all render with the correct background, dot, and text colors.
+ */
+const THEME_VARS = {
+  light: {
+    '--sb--canvas-bg': '#f6f8fa',
+    '--bgColor-default': '#ffffff',
+    '--bgColor-muted': '#f6f8fa',
+    '--bgColor-neutral-muted': '#818b981f',
+    '--bgColor-accent-emphasis': '#0969da',
+    '--tc-bg-muted': '#f6f8fa',
+    '--tc-dot-color': 'rgba(0, 0, 0, 0.08)',
+    '--overlay-backdrop-bgColor': 'rgba(0, 0, 0, 0.08)',
+    '--fgColor-muted': '#59636e',
+    '--fgColor-default': '#1f2328',
+    '--fgColor-onEmphasis': '#ffffff',
+    '--borderColor-default': '#d1d9e0',
+    '--borderColor-muted': '#d1d9e0b3',
+  },
+  light_colorblind: {
+    '--sb--canvas-bg': '#f6f8fa',
+    '--bgColor-default': '#ffffff',
+    '--bgColor-muted': '#f6f8fa',
+    '--bgColor-neutral-muted': '#818b981f',
+    '--bgColor-accent-emphasis': '#0969da',
+    '--tc-bg-muted': '#f6f8fa',
+    '--tc-dot-color': 'rgba(0, 0, 0, 0.08)',
+    '--overlay-backdrop-bgColor': 'rgba(0, 0, 0, 0.08)',
+    '--fgColor-muted': '#59636e',
+    '--fgColor-default': '#1f2328',
+    '--fgColor-onEmphasis': '#ffffff',
+    '--borderColor-default': '#d1d9e0',
+    '--borderColor-muted': '#d1d9e0b3',
+  },
+  dark: {
+    '--sb--canvas-bg': '#151b23',
+    '--bgColor-default': '#0d1117',
+    '--bgColor-muted': '#151b23',
+    '--bgColor-neutral-muted': '#656c7633',
+    '--bgColor-accent-emphasis': '#1f6feb',
+    '--tc-bg-muted': '#151b23',
+    '--tc-dot-color': 'rgba(255, 255, 255, 0.1)',
+    '--overlay-backdrop-bgColor': 'rgba(255, 255, 255, 0.1)',
+    '--fgColor-muted': '#9198a1',
+    '--fgColor-default': '#f0f6fc',
+    '--fgColor-onEmphasis': '#ffffff',
+    '--borderColor-default': '#3d444d',
+    '--borderColor-muted': '#3d444db3',
+  },
+  dark_dimmed: {
+    '--sb--canvas-bg': '#262c36',
+    '--bgColor-default': '#212830',
+    '--bgColor-muted': '#262c36',
+    '--bgColor-neutral-muted': '#656c7633',
+    '--bgColor-accent-emphasis': '#316dca',
+    '--tc-bg-muted': '#262c36',
+    '--tc-dot-color': 'rgba(209, 215, 224, 0.18)',
+    '--overlay-backdrop-bgColor': 'rgba(209, 215, 224, 0.18)',
+    '--fgColor-muted': '#9198a1',
+    '--fgColor-default': '#d1d7e0',
+    '--fgColor-onEmphasis': '#f0f6fc',
+    '--borderColor-default': '#3d444d',
+    '--borderColor-muted': '#3d444db3',
+  },
+  dark_colorblind: {
+    '--sb--canvas-bg': '#151b23',
+    '--bgColor-default': '#0d1117',
+    '--bgColor-muted': '#151b23',
+    '--bgColor-neutral-muted': '#656c7633',
+    '--bgColor-accent-emphasis': '#1f6feb',
+    '--tc-bg-muted': '#151b23',
+    '--tc-dot-color': 'rgba(255, 255, 255, 0.1)',
+    '--overlay-backdrop-bgColor': 'rgba(255, 255, 255, 0.1)',
+    '--fgColor-muted': '#9198a1',
+    '--fgColor-default': '#f0f6fc',
+    '--fgColor-onEmphasis': '#ffffff',
+    '--borderColor-default': '#3d444d',
+    '--borderColor-muted': '#3d444db3',
+  },
+  dark_high_contrast: {
+    '--sb--canvas-bg': '#151b23',
+    '--bgColor-default': '#010409',
+    '--bgColor-muted': '#151b23',
+    '--bgColor-neutral-muted': '#212830',
+    '--bgColor-accent-emphasis': '#194fb1',
+    '--tc-bg-muted': '#151b23',
+    '--tc-dot-color': 'rgba(183, 189, 200, 0.25)',
+    '--overlay-backdrop-bgColor': 'rgba(183, 189, 200, 0.25)',
+    '--fgColor-muted': '#b7bdc8',
+    '--fgColor-default': '#ffffff',
+    '--fgColor-onEmphasis': '#ffffff',
+    '--borderColor-default': '#b7bdc8',
+    '--borderColor-muted': '#b7bdc8',
+  },
+}
+
+export function getCanvasThemeVars(theme) {
+  const value = String(theme || 'light')
+  return THEME_VARS[value] || THEME_VARS.light
+}

package/src/internals/canvas/componentIsolate.jsx

@@ -0,0 +1,165 @@
+/**
+ * Canvas Component Isolate — iframe entry point.
+ *
+ * Renders a single named export from a .story.jsx module inside an
+ * isolated document. The parent CanvasPage embeds this via an iframe
+ * so a broken component cannot crash the entire canvas.
+ *
+ * Query params:
+ *   module — absolute or base-relative path to the .story.jsx file
+ *   export — the named export to render
+ *   theme  — canvas theme (light / dark / dark_dimmed)
+ */
+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 {
+  constructor(props) {
+    super(props)
+    this.state = { error: null }
+  }
+  static getDerivedStateFromError(error) {
+    return { error }
+  }
+  render() {
+    if (this.state.error) {
+      return createElement('div', { style: errorStyle },
+        createElement('strong', null, this.props.name || 'Component'),
+        createElement('br'),
+        String(this.state.error.message || this.state.error),
+      )
+    }
+    return this.props.children
+  }
+}
+
+// ── Styles ──────────────────────────────────────────────────────────
+const errorStyle = {
+  padding: '16px',
+  color: '#cf222e',
+  fontFamily: 'system-ui, -apple-system, sans-serif',
+  fontSize: '13px',
+  lineHeight: 1.5,
+  whiteSpace: 'pre-wrap',
+  wordBreak: 'break-word',
+}
+
+// ── Resolve module path (mirrors useCanvas.resolveCanvasModuleImport) ─
+function resolveModulePath(raw) {
+  if (!raw) return raw
+  if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(raw)) return raw
+  if (!raw.startsWith('/')) return raw
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+  if (!base) return raw
+  if (raw.startsWith(base)) return raw
+  return `${base}${raw}`
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+const params = new URLSearchParams(window.location.search)
+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 : '')
+document.documentElement.setAttribute('data-light-theme', theme.startsWith('dark') ? '' : theme || 'light')
+
+// Suppress HMR full-reloads — this iframe is embedded inside a canvas page
+// that manages its own reload lifecycle. Without this guard, every file change
+// causes the iframe to flash/reload.
+if (import.meta.hot) {
+  const msg = { active: true }
+  import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+  setInterval(() => import.meta.hot.send('storyboard:canvas-hmr-guard', msg), 3000)
+}
+
+const root = createRoot(document.getElementById('root'))
+
+async function mount() {
+  if (!modulePath) {
+    root.render(createElement('div', { style: errorStyle }, 'Missing module param'))
+    return
+  }
+
+  // Validate: only allow .story.{jsx,tsx} modules
+  if (!modulePath.match(/\.story\.(jsx|tsx)$/)) {
+    root.render(createElement('div', { style: errorStyle }, 'Invalid module path — only .story.jsx/.tsx files are allowed'))
+    return
+  }
+
+  try {
+    const resolved = resolveModulePath(modulePath)
+    const mod = await import(/* @vite-ignore */ resolved)
+
+    if (exportName) {
+      // Single export mode
+      const Component = mod[exportName]
+      if (!Component || typeof Component !== 'function') {
+        throw new Error(`Export "${exportName}" not found or is not a component`)
+      }
+      root.render(
+        createElement(ThemeProvider, { colorMode },
+          createElement(BaseStyles, null,
+            createElement(IsolateErrorBoundary, { name: exportName },
+              createElement(Component),
+            ),
+          ),
+        ),
+      )
+    } else {
+      // All exports mode — render every named function export stacked
+      const entries = Object.entries(mod).filter(
+        ([key, value]) => key !== 'default' && typeof value === 'function',
+      )
+      if (entries.length === 0) {
+        throw new Error('No named exports found in story module')
+      }
+      root.render(
+        createElement(ThemeProvider, { colorMode },
+          createElement(BaseStyles, null,
+            ...entries.map(([name, Component]) =>
+              createElement(IsolateErrorBoundary, { key: name, name },
+                createElement(Component),
+              ),
+            ),
+          ),
+        ),
+      )
+    }
+  } catch (err) {
+    root.render(
+      createElement('div', { style: errorStyle },
+        createElement('strong', null, exportName || 'Component'),
+        createElement('br'),
+        String(err.message || err),
+      ),
+    )
+  }
+}
+
+mount()