prev-cli 0.24.20 → 0.25.0

package/src/preview-runtime/build.ts

@@ -1,8 +1,10 @@
 // src/preview-runtime/build.ts
 // Production build for previews - pre-bundles React/TSX at build time
 
-import { build } from 'esbuild'
 import type { PreviewConfig } from './types'
+import { mkdtempSync, writeFileSync, rmSync, existsSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { tmpdir } from 'os'
 
 export interface PreviewBuildResult {
   html: string
@@ -11,18 +13,10 @@ export interface PreviewBuildResult {
 
 /**
  * Build a preview into a standalone HTML file for production
- * Uses esbuild (native) to bundle at build time
+ * Uses Bun.build (native) to bundle at build time
  */
 export async function buildPreviewHtml(config: PreviewConfig): Promise<PreviewBuildResult> {
   try {
-    // Build virtual filesystem
-    const virtualFs: Record<string, { contents: string; loader: string }> = {}
-    for (const file of config.files) {
-      const ext = file.path.split('.').pop()?.toLowerCase()
-      const loader = ext === 'css' ? 'css' : ext === 'json' ? 'json' : ext || 'tsx'
-      virtualFs[file.path] = { contents: file.content, loader }
-    }
-
     // Find entry and check if it exports default
     const entryFile = config.files.find(f => f.path === config.entry)
     if (!entryFile) {
@@ -43,83 +37,82 @@ export async function buildPreviewHtml(config: PreviewConfig): Promise<PreviewBu
       import './${config.entry}'
     `
 
-    // Bundle with esbuild
-    const result = await build({
-      stdin: {
-        contents: entryCode,
-        loader: 'tsx',
-        resolveDir: '/',
-      },
-      bundle: true,
-      write: false,
-      format: 'esm',
-      jsx: 'automatic',
-      jsxImportSource: 'react',
-      target: 'es2020',
-      minify: true,
-      plugins: [{
-        name: 'virtual-fs',
-        setup(build) {
-          // External: React from CDN
-          build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, args => {
-            const parts = args.path.split('/')
-            const pkg = parts[0]
-            const subpath = parts.slice(1).join('/')
-            const url = subpath
-              ? `https://esm.sh/${pkg}@18/${subpath}`
-              : `https://esm.sh/${pkg}@18`
-            return { path: url, external: true }
-          })
-
-          // Auto-resolve npm packages via esm.sh
-          build.onResolve({ filter: /^[^./]/ }, args => {
-            if (args.path.startsWith('https://')) return
-            return { path: `https://esm.sh/${args.path}`, external: true }
-          })
-
-          // Resolve relative imports
-          build.onResolve({ filter: /^\./ }, args => {
-            let resolved = args.path.replace(/^\.\//, '')
-            if (!resolved.includes('.')) {
-              for (const ext of ['.tsx', '.ts', '.jsx', '.js', '.css']) {
-                if (virtualFs[resolved + ext]) {
-                  resolved = resolved + ext
-                  break
-                }
-              }
-            }
-            return { path: resolved, namespace: 'virtual' }
-          })
-
-          // Load from virtual filesystem
-          build.onLoad({ filter: /.*/, namespace: 'virtual' }, args => {
-            const file = virtualFs[args.path]
-            if (file) {
-              // CSS: convert to JS that injects styles
-              if (file.loader === 'css') {
-                const css = file.contents.replace(/`/g, '\\`').replace(/\$/g, '\\$')
+    // Write all files to temp directory
+    const tempDir = mkdtempSync(join(tmpdir(), 'prev-build-'))
+    const entryPath = join(tempDir, '__entry.tsx')
+
+    try {
+      writeFileSync(entryPath, entryCode)
+
+      // Write virtual files to temp dir
+      for (const file of config.files) {
+        const targetPath = join(tempDir, file.path)
+        const dir = dirname(targetPath)
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true })
+        }
+        writeFileSync(targetPath, file.content)
+      }
+
+      // Bundle with Bun.build
+      const result = await Bun.build({
+        entrypoints: [entryPath],
+        format: 'esm',
+        target: 'browser',
+        minify: true,
+        jsx: { runtime: 'automatic', importSource: 'react' },
+        define: {
+          'process.env.NODE_ENV': '"production"',
+        },
+        plugins: [{
+          name: 'preview-externals',
+          setup(build) {
+            // External: React from CDN
+            build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, args => {
+              const parts = args.path.split('/')
+              const pkg = parts[0]
+              const subpath = parts.slice(1).join('/')
+              const url = subpath
+                ? `https://esm.sh/${pkg}@18/${subpath}`
+                : `https://esm.sh/${pkg}@18`
+              return { path: url, external: true }
+            })
+
+            // Auto-resolve npm packages via esm.sh
+            build.onResolve({ filter: /^[^./]/ }, args => {
+              if (args.path.startsWith('https://')) return undefined
+              return { path: `https://esm.sh/${args.path}`, external: true }
+            })
+
+            // CSS: convert to JS that injects styles
+            build.onLoad({ filter: /\.css$/ }, args => {
+              const content = Bun.file(args.path)
+              return content.text().then(css => {
+                const escaped = css.replace(/`/g, '\\`').replace(/\$/g, '\\$')
                 return {
                   contents: `
                     const style = document.createElement('style');
-                    style.textContent = \`${css}\`;
+                    style.textContent = \`${escaped}\`;
                     document.head.appendChild(style);
                   `,
                   loader: 'js',
                 }
-              }
-              return { contents: file.contents, loader: file.loader as any }
-            }
-            return { contents: '', loader: 'empty' }
-          })
-        },
-      }],
-    })
+              })
+            })
+          },
+        }],
+      })
+
+      if (!result.success) {
+        const errors = result.logs.filter(l => l.level === 'error').map(l => l.message).join('; ')
+        return { html: '', error: errors || 'Build failed' }
+      }
 
-    const jsFile = result.outputFiles.find(f => f.path.endsWith('.js')) || result.outputFiles[0]
-    const jsCode = jsFile?.text || ''
+      const jsFile = result.outputs.find(f => f.path.endsWith('.js')) || result.outputs[0]
+      const jsCode = jsFile ? await jsFile.text() : ''
 
-    // Generate standalone HTML
-    const html = `<!DOCTYPE html>
+      // Generate standalone HTML
+      const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -137,7 +130,10 @@ export async function buildPreviewHtml(config: PreviewConfig): Promise<PreviewBu
 </body>
 </html>`
 
-    return { html }
+      return { html }
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true })
+    }
   } catch (err) {
     return {
       html: '',

package/src/preview-runtime/fast-template.html

@@ -50,18 +50,22 @@
     // Fast preview runtime - uses server-side bundled code
     const params = new URLSearchParams(window.location.search)
     const src = params.get('src')
+    const state = params.get('state')
 
     if (!src) {
       document.getElementById('root').innerHTML = '<div class="preview-error">No preview source specified</div>'
     } else {
       const startTime = performance.now()
+      const bundleUrl = state
+        ? `/_preview-bundle/${src}?state=${encodeURIComponent(state)}`
+        : `/_preview-bundle/${src}`
 
       try {
         // Pre-fetch tokens, JSX, and bundle in parallel
         const [tokensRes, jsxModule, bundleResponse] = await Promise.all([
           fetch('/_prev/tokens.json').then(r => r.json()).catch(() => null),
           import(`${window.location.origin}/_prev/jsx.js`),
-          fetch(`/_preview-bundle/${src}`)
+          fetch(bundleUrl)
         ])
 
         // Set tokens

package/src/preview-runtime/region-bridge.test.ts

@@ -0,0 +1,41 @@
+import { test, expect, describe } from 'bun:test'
+import { REGION_BRIDGE_SCRIPT } from './region-bridge'
+
+describe('REGION_BRIDGE_SCRIPT', () => {
+  test('is valid JavaScript (parses without error)', () => {
+    // Bun.Transpiler will throw on syntax errors
+    const transpiler = new Bun.Transpiler({ loader: 'js' })
+    expect(() => transpiler.transformSync(REGION_BRIDGE_SCRIPT)).not.toThrow()
+  })
+
+  test('contains click handler for [data-region]', () => {
+    expect(REGION_BRIDGE_SCRIPT).toContain('data-region')
+    expect(REGION_BRIDGE_SCRIPT).toContain('click')
+  })
+
+  test('contains highlight-regions listener', () => {
+    expect(REGION_BRIDGE_SCRIPT).toContain('highlight-regions')
+  })
+
+  test('posts region-click message to parent', () => {
+    expect(REGION_BRIDGE_SCRIPT).toContain('region-click')
+    expect(REGION_BRIDGE_SCRIPT).toContain('postMessage')
+  })
+
+  test('reports region-rects with bounding rect data', () => {
+    expect(REGION_BRIDGE_SCRIPT).toContain('region-rects')
+    expect(REGION_BRIDGE_SCRIPT).toContain('getBoundingClientRect')
+    expect(REGION_BRIDGE_SCRIPT).toContain('reportRegionRects')
+  })
+
+  test('sends empty region-rects when regions are cleared', () => {
+    // When highlight-regions is sent with empty array, bridge should report empty rects
+    expect(REGION_BRIDGE_SCRIPT).toContain("{ type: 'region-rects', rects: [] }")
+  })
+
+  test('debounces rect reporting on scroll and resize', () => {
+    expect(REGION_BRIDGE_SCRIPT).toContain('scroll')
+    expect(REGION_BRIDGE_SCRIPT).toContain('resize')
+    expect(REGION_BRIDGE_SCRIPT).toContain('debouncedReport')
+  })
+})

package/src/preview-runtime/region-bridge.ts

@@ -0,0 +1,101 @@
+// Bridge script injected into preview iframes to enable region interactivity.
+// Handles: click events on [data-region] elements → postMessage to parent
+//          highlight-regions message from parent → visual overlay on regions
+
+export const REGION_BRIDGE_SCRIPT = `
+(function() {
+  // Click handler: delegate clicks on [data-region] elements
+  document.addEventListener('click', function(e) {
+    var el = e.target;
+    while (el && el !== document.body) {
+      if (el.getAttribute && el.getAttribute('data-region')) {
+        e.preventDefault();
+        e.stopPropagation();
+        window.parent.postMessage({
+          type: 'region-click',
+          region: el.getAttribute('data-region')
+        }, '*');
+        return;
+      }
+      el = el.parentElement;
+    }
+  }, true);
+
+  // Highlight handler: parent sends list of region names to highlight
+  window.addEventListener('message', function(e) {
+    if (!e.data || e.data.type !== 'highlight-regions') return;
+
+    // Remove existing highlights
+    var existing = document.querySelectorAll('[data-region-highlight]');
+    for (var i = 0; i < existing.length; i++) {
+      existing[i].removeAttribute('data-region-highlight');
+      existing[i].style.cursor = '';
+    }
+
+    var regions = e.data.regions || [];
+    if (regions.length === 0) {
+      // Report empty rects when cleared
+      window.parent.postMessage({ type: 'region-rects', rects: [] }, '*');
+      return;
+    }
+
+    for (var j = 0; j < regions.length; j++) {
+      var els = document.querySelectorAll('[data-region="' + regions[j] + '"]');
+      for (var k = 0; k < els.length; k++) {
+        els[k].setAttribute('data-region-highlight', 'true');
+        els[k].style.cursor = 'pointer';
+      }
+    }
+
+    // Report bounding rects to parent
+    reportRegionRects();
+  });
+
+  // Measure and report region rects to parent
+  function reportRegionRects() {
+    var highlighted = document.querySelectorAll('[data-region-highlight]');
+    var rects = [];
+    for (var i = 0; i < highlighted.length; i++) {
+      var el = highlighted[i];
+      var rect = el.getBoundingClientRect();
+      rects.push({
+        name: el.getAttribute('data-region') || '',
+        x: rect.left,
+        y: rect.top,
+        width: rect.width,
+        height: rect.height
+      });
+    }
+    window.parent.postMessage({ type: 'region-rects', rects: rects }, '*');
+  }
+
+  // Debounced re-report on scroll/resize
+  var debounceTimer = null;
+  function debouncedReport() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(function() {
+      var highlighted = document.querySelectorAll('[data-region-highlight]');
+      if (highlighted.length > 0) reportRegionRects();
+    }, 100);
+  }
+  window.addEventListener('scroll', debouncedReport, true);
+  window.addEventListener('resize', debouncedReport);
+
+  // Token override handler: parent sends CSS overrides to inject
+  window.addEventListener('message', function(e) {
+    if (!e.data || e.data.type !== 'token-overrides') return;
+    var styleId = 'prev-token-overrides';
+    var existing = document.getElementById(styleId);
+    if (e.data.css) {
+      if (!existing) {
+        existing = document.createElement('style');
+        existing.id = styleId;
+        document.head.appendChild(existing);
+      }
+      existing.textContent = e.data.css;
+    } else if (existing) {
+      existing.remove();
+    }
+  });
+})();
+`

package/src/preview-runtime/types.ts

@@ -27,3 +27,9 @@ export type PreviewMessage =
   | { type: 'ready' }
   | { type: 'built'; result: BuildResult }
   | { type: 'error'; error: string }
+  // Region interactivity (flow previews)
+  | { type: 'region-click'; region: string }
+  | { type: 'highlight-regions'; regions: string[] }
+  | { type: 'region-rects'; rects: Array<{ name: string; x: number; y: number; width: number; height: number }> }
+  // Token override injection
+  | { type: 'token-overrides'; css: string }

package/src/preview-runtime/vendors.ts

@@ -1,9 +1,27 @@
-import { build } from 'esbuild'
-import { dirname } from 'path'
+import { join, dirname } from 'path'
+import { mkdtempSync, writeFileSync, rmSync, existsSync, readFileSync } from 'fs'
 import { fileURLToPath } from 'url'
+import { tmpdir } from 'os'
 
-// Resolve from CLI's location, not user's project (React is our dependency)
-const __dirname = dirname(fileURLToPath(import.meta.url))
+// Find CLI root for module resolution (React is our dependency)
+function findCliRoot(): string {
+  let dir = dirname(fileURLToPath(import.meta.url))
+  for (let i = 0; i < 10; i++) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        if (pkg.name === 'prev-cli') return dir
+      } catch {}
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return dirname(dirname(fileURLToPath(import.meta.url)))
+}
+
+const cliRoot = findCliRoot()
 
 export interface VendorBundleResult {
   success: boolean
@@ -18,6 +36,7 @@ export async function buildVendorBundle(): Promise<VendorBundleResult> {
       import * as ReactDOM from 'react-dom'
       import { createRoot } from 'react-dom/client'
       export { jsx, jsxs, Fragment } from 'react/jsx-runtime'
+      export { jsxDEV } from 'react/jsx-dev-runtime'
       export { React, ReactDOM, createRoot }
       // Re-export React hooks as named exports (preview code imports them directly)
       export {
@@ -31,26 +50,200 @@ export async function buildVendorBundle(): Promise<VendorBundleResult> {
       export default React
     `
 
-    const result = await build({
-      stdin: {
-        contents: entryCode,
-        loader: 'ts',
-        resolveDir: __dirname, // Resolve React from CLI's node_modules
-      },
-      bundle: true,
-      write: false,
-      format: 'esm',
-      target: 'es2020',
-      minify: true,
-    })
-
-    // Select JS output file explicitly (in case sourcemaps are added later)
-    const jsFile = result.outputFiles?.find(f => f.path.endsWith('.js')) || result.outputFiles?.[0]
-    if (!jsFile) {
-      return { success: false, code: '', error: 'No output generated' }
+    // Write temp file in CLI root so React can be resolved from node_modules
+    const tempDir = mkdtempSync(join(cliRoot, '.tmp-vendor-'))
+    const entryPath = join(tempDir, 'entry.ts')
+
+    try {
+      writeFileSync(entryPath, entryCode)
+
+      const result = await Bun.build({
+        entrypoints: [entryPath],
+        format: 'esm',
+        target: 'browser',
+        minify: true,
+      })
+
+      if (!result.success) {
+        const errors = result.logs.filter(l => l.level === 'error').map(l => l.message).join('; ')
+        return { success: false, code: '', error: errors || 'Build failed' }
+      }
+
+      const jsFile = result.outputs.find(f => f.path.endsWith('.js')) || result.outputs[0]
+      if (!jsFile) {
+        return { success: false, code: '', error: 'No output generated' }
+      }
+
+      return { success: true, code: await jsFile.text() }
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true })
+    }
+  } catch (err) {
+    return {
+      success: false,
+      code: '',
+      error: err instanceof Error ? err.message : String(err),
     }
+  }
+}
+
+/**
+ * Build @prev/jsx bundle for static preview builds
+ * React is externalized, so temp dir location doesn't matter for resolution
+ */
+export async function buildJsxBundle(vendorPath: string): Promise<VendorBundleResult> {
+  try {
+    const minimalJsx = `
+      import * as React from 'react'
 
-    return { success: true, code: jsFile.text }
+      // Default token values for standalone preview rendering
+      const defaultTokens = {
+        background: {
+          primary: '#3b82f6',
+          secondary: '#f1f5f9',
+          destructive: '#ef4444',
+          muted: '#f1f5f9',
+          accent: '#f1f5f9',
+          transparent: 'transparent',
+        },
+        color: {
+          'primary-foreground': '#ffffff',
+          'secondary-foreground': '#0f172a',
+          'destructive-foreground': '#ffffff',
+          'muted-foreground': '#64748b',
+          'accent-foreground': '#0f172a',
+          foreground: '#0f172a',
+        },
+        spacing: {
+          xs: '4px',
+          sm: '8px',
+          md: '12px',
+          lg: '16px',
+          xl: '24px',
+        },
+        radius: {
+          none: '0',
+          sm: '4px',
+          md: '6px',
+          lg: '8px',
+          full: '9999px',
+        },
+        'typography.size': {
+          xs: '12px',
+          sm: '14px',
+          base: '16px',
+          lg: '18px',
+          xl: '20px',
+        },
+        'typography.weight': {
+          normal: '400',
+          medium: '500',
+          semibold: '600',
+          bold: '700',
+        },
+      }
+
+      // Token resolution
+      let tokensConfig = null
+      export function setTokensConfig(config) { tokensConfig = config }
+
+      function resolveToken(category, token) {
+        // Check custom config first, then defaults
+        const config = tokensConfig || defaultTokens
+        const cat = config[category]
+        return cat?.[token] ?? token
+      }
+
+      // VNode type
+      export class VNode {
+        constructor(type, props, children) {
+          this.type = type
+          this.props = props || {}
+          this.children = children || []
+        }
+      }
+
+      // Primitives - return VNodes
+      export function Box(props) { return new VNode('Box', props, props.children ? [props.children] : []) }
+      export function Text(props) { return new VNode('Text', props, props.children ? [props.children] : []) }
+      export function Col(props) { return new VNode('Col', props, props.children || []) }
+      export function Row(props) { return new VNode('Row', props, props.children || []) }
+      export function Spacer(props) { return new VNode('Spacer', props, []) }
+      export function Slot(props) { return new VNode('Slot', props, []) }
+      export function Icon(props) { return new VNode('Icon', props, []) }
+      export function Image(props) { return new VNode('Image', props, []) }
+      export const Fragment = React.Fragment
+
+      // Convert VNode to React element
+      export function toReact(vnode) {
+        if (!vnode || typeof vnode !== 'object') return vnode
+        if (!(vnode instanceof VNode)) return vnode
+
+        const { type, props, children } = vnode
+        const style = {}
+
+        // Map props to styles
+        if (props.bg) style.backgroundColor = resolveToken('background', props.bg)
+        if (props.padding) style.padding = resolveToken('spacing', props.padding)
+        if (props.radius) style.borderRadius = resolveToken('radius', props.radius)
+        if (props.color) style.color = resolveToken('color', props.color)
+        if (props.size) style.fontSize = resolveToken('typography.size', props.size)
+        if (props.weight) style.fontWeight = resolveToken('typography.weight', props.weight)
+        if (props.gap) style.gap = resolveToken('spacing', props.gap)
+
+        // Layout types
+        if (type === 'Col') { style.display = 'flex'; style.flexDirection = 'column' }
+        if (type === 'Row') { style.display = 'flex'; style.flexDirection = 'row' }
+        if (type === 'Spacer') { style.flex = 1 }
+
+        const childElements = children.map(c => toReact(c))
+
+        return React.createElement('div', { style }, ...childElements)
+      }
+    `
+
+    // React is externalized via plugin, so temp dir location doesn't matter
+    const tempDir = mkdtempSync(join(tmpdir(), 'prev-jsx-'))
+    const entryPath = join(tempDir, 'entry.ts')
+
+    try {
+      writeFileSync(entryPath, minimalJsx)
+
+      const result = await Bun.build({
+        entrypoints: [entryPath],
+        format: 'esm',
+        target: 'browser',
+        minify: true,
+        plugins: [
+          {
+            name: 'jsx-externals',
+            setup(build) {
+              build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, () => {
+                return { path: vendorPath, external: true }
+              })
+            },
+          },
+        ],
+      })
+
+      if (!result.success) {
+        const errors = result.logs.filter(l => l.level === 'error').map(l => l.message).join('; ')
+        return { success: false, code: '', error: errors || 'Build failed' }
+      }
+
+      const jsFile = result.outputs.find(f => f.path.endsWith('.js')) || result.outputs[0]
+      if (!jsFile) {
+        return { success: false, code: '', error: 'No output generated' }
+      }
+
+      // Fix bare specifiers — Bun.build keeps original import paths for externals
+      let code = await jsFile.text()
+      code = code.replace(/from\s*["']react["']/g, `from"${vendorPath}"`)
+
+      return { success: true, code }
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true })
+    }
   } catch (err) {
     return {
       success: false,

package/src/primitives/CLAUDE.md

@@ -0,0 +1,17 @@
+<!-- c3-generated: c3-601, c3-602, c3-603, c3-604 -->
+# Template Primitives (WIP)
+
+Before modifying this code, read:
+- `.c3/c3-6-primitives/c3-601-types.md` - Type definitions
+- `.c3/c3-6-primitives/c3-602-parser.md` - Template parser
+- `.c3/c3-6-primitives/c3-603-template-parser.md` - Syntax parser
+- `.c3/c3-6-primitives/c3-604-template-renderer.md` - Output renderer
+
+Primitive types: `col`, `row`, `box`, `spacer`, `slot`, `text`, `icon`, `image`
+
+Key files:
+- `types.ts` - PrimitiveType, Primitive, props interfaces
+- `parser.ts` - Main template parser
+- `template-parser.ts` - Template syntax parsing
+- `template-renderer.ts` - Template to output
+<!-- end-c3-generated -->

package/src/theme/CLAUDE.md

@@ -0,0 +1,20 @@
+<!-- c3-generated: c3-301, c3-302, c3-303, c3-304, c3-305 -->
+# Theme Components
+
+Before modifying this code, read:
+- `.c3/c3-3-theme/c3-301-entry.md` - React app entry & routing
+- `.c3/c3-3-theme/c3-302-layout.md` - Page layout structure
+- `.c3/c3-3-theme/c3-303-mdx-provider.md` - MDX component mapping
+- `.c3/c3-3-theme/c3-304-toolbar.md` - Navigation toolbar
+- `.c3/c3-3-theme/c3-305-sidebar.md` - Sidebar navigation
+- Patterns: `ref-theming`
+
+Key files:
+- `entry.tsx` - TanStack Router setup, virtual module imports
+- `Layout.tsx` - Main layout with sidebar/toolbar
+- `mdx-components.tsx` - MDX component overrides
+- `Toolbar.tsx` - Top navigation bar
+- `TOCPanel.tsx` - Table of contents
+
+Full refs: `.c3/refs/ref-theming.md`
+<!-- end-c3-generated -->