pellicule 0.1.1 → 0.2.0

package/bin/cli.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url'
 import { renderToMp4 } from '../src/render.js'
 import { extractVideoConfig, resolveVideoConfig } from '../src/macros/define-video-config.js'
 import { detectProject, readPelliculeConfig, resolveInputFile } from '../src/config/detect.js'
+import { startDevServer } from '../src/dev/server.js'
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -49,6 +50,8 @@ ${c.bold('USAGE')}
   ${c.highlight('pellicule')}                            ${c.dim('→ renders Video.vue to output.mp4')}
   ${c.highlight('pellicule')} <input.vue>                ${c.dim('→ custom input file')}
   ${c.highlight('pellicule')} <input.vue> -o <file>      ${c.dim('→ custom output path')}
+  ${c.highlight('pellicule dev')}                        ${c.dim('→ live preview in browser')}
+  ${c.highlight('pellicule dev')} <input.vue>            ${c.dim('→ preview a specific component')}
 
 ${c.bold('OPTIONS')}
   ${c.info('-o, --output')} <file>     Output file path ${c.dim('(default: ./output.mp4)')}
@@ -114,6 +117,12 @@ ${c.bold('EXAMPLES')}
   ${c.dim('# Force Rsbuild bundler')}
   ${c.highlight('pellicule')} Video.vue --bundler rsbuild
 
+  ${c.dim('# Live preview with hot-reload (Space to play, arrows to step)')}
+  ${c.highlight('pellicule dev')}
+
+  ${c.dim('# Preview a specific component at 720p')}
+  ${c.highlight('pellicule dev')} MyVideo -w 1280 -h 720
+
 ${c.bold('DURATION HELPER')}
   frames = seconds * fps
   ${c.dim('3 seconds at 30fps  = 90 frames')}
@@ -176,6 +185,10 @@ async function main() {
     process.exit(0)
   }
 
+  // ── Subcommand detection ─────────────────────────────────────────
+  const isDevMode = positionals[0] === 'dev'
+  if (isDevMode) positionals.shift()
+
   // ── Auto-detection ────────────────────────────────────────────────
   const detected = detectProject()
   const pkgConfig = readPelliculeConfig()
@@ -188,6 +201,15 @@ async function main() {
   const serverUrl = values['server-url'] || pkgConfig.serverUrl || detected.defaultServerUrl || null
   const projectType = detected.projectType
 
+  const projectLabels = {
+    laravel: 'Laravel',
+    vite: 'Vite',
+    rsbuild: 'Rsbuild',
+    shipwright: 'Boring Stack (Shipwright)',
+    nuxt: 'Nuxt',
+    quasar: 'Quasar'
+  }
+
   // Validate bundler flag
   if (values.bundler && !['vite', 'rsbuild'].includes(values.bundler)) {
     fail(`Unknown bundler: ${values.bundler}`, 'Supported bundlers: vite, rsbuild')
@@ -267,15 +289,70 @@ async function main() {
   if (isNaN(durationInFrames) || durationInFrames <= 0) fail(`Invalid duration value: ${durationInFrames}`)
   if (isNaN(width) || width <= 0) fail(`Invalid width value: ${width}`)
   if (isNaN(height) || height <= 0) fail(`Invalid height value: ${height}`)
-  if (startFrame >= endFrame) fail(`Start frame (${startFrame}) must be less than end frame (${endFrame})`)
-  if (endFrame > durationInFrames) fail(`End frame (${endFrame}) exceeds duration (${durationInFrames})`)
+  if (!isDevMode && startFrame >= endFrame) fail(`Start frame (${startFrame}) must be less than end frame (${endFrame})`)
+  if (!isDevMode && endFrame > durationInFrames) fail(`End frame (${endFrame}) exceeds duration (${durationInFrames})`)
+
+  const durationSeconds = (durationInFrames / fps).toFixed(1)
+
+  // ── Dev mode ─────────────────────────────────────────────────────
+  if (isDevMode) {
+    printBanner()
+
+    console.log(`  ${c.bold('Mode')}       ${c.highlight('dev')} ${c.dim('(live preview)')}`)
+    console.log(`  ${c.bold('Input')}      ${c.info(basename(inputPath))}`)
+    if (componentConfig) {
+      console.log(`  ${c.bold('Config')}     ${c.highlight('defineVideoConfig')} ${c.dim('detected ✓')}`)
+    }
+    if (projectType !== 'standalone') {
+      console.log(`  ${c.bold('Project')}    ${c.highlight(projectLabels[projectType] || projectType)} ${c.dim('detected ✓')}`)
+    }
+    if (serverUrl) {
+      console.log(`  ${c.bold('Server')}     ${c.info(serverUrl)} ${c.dim('(BYOS)')}`)
+    }
+    console.log(`  ${c.bold('Resolution')} ${width}x${height}`)
+    console.log(`  ${c.bold('Duration')}   ${durationInFrames} frames @ ${fps}fps ${c.dim(`(${durationSeconds}s)`)}`)
+    console.log()
+
+    // For Nuxt/Quasar, construct /pellicule render page URL
+    let devServerUrl = serverUrl
+    if ((projectType === 'nuxt' || projectType === 'quasar') && serverUrl) {
+      const componentName = basename(inputPath, '.vue')
+      devServerUrl = `${serverUrl.replace(/\/$/, '')}/pellicule?component=${encodeURIComponent(componentName)}`
+    }
+
+    try {
+      const { url } = await startDevServer({
+        input: inputPath,
+        fps,
+        durationInFrames,
+        width,
+        height,
+        serverUrl: devServerUrl,
+        bundler,
+        configFile,
+        projectType,
+        version: VERSION
+      })
+
+      console.log(`  ${c.highlight('Preview ready!')} ${c.info(url)}`)
+      console.log()
+      console.log(`  ${c.dim('Controls:')} ${c.bold('Space')} play/pause  ${c.bold('←→')} step frame  ${c.bold('Home/End')} first/last`)
+      console.log(`  ${c.dim('Press')} ${c.bold('Ctrl+C')} ${c.dim('to stop')}`)
+      console.log()
+
+      // Keep process alive
+      await new Promise(() => {})
+    } catch (error) {
+      console.error(c.error(`  Error: ${error.message}`))
+      process.exit(1)
+    }
+  }
 
   // Print banner and config
   printBanner()
 
   const isPartialRender = startFrame > 0 || endFrame < durationInFrames
   const framesToRender = endFrame - startFrame
-  const durationSeconds = (durationInFrames / fps).toFixed(1)
   const partialSeconds = (framesToRender / fps).toFixed(1)
 
   console.log(`  ${c.bold('Input')}      ${c.info(basename(inputPath))}`)
@@ -283,16 +360,7 @@ async function main() {
     console.log(`  ${c.bold('Config')}     ${c.highlight('defineVideoConfig')} ${c.dim('detected ✓')}`)
   }
 
-  // Show detected project info
   if (projectType !== 'standalone') {
-    const projectLabels = {
-      laravel: 'Laravel',
-      vite: 'Vite',
-      rsbuild: 'Rsbuild',
-      shipwright: 'Boring Stack (Shipwright)',
-      nuxt: 'Nuxt',
-      quasar: 'Quasar'
-    }
     console.log(`  ${c.bold('Project')}    ${c.highlight(projectLabels[projectType] || projectType)} ${c.dim('detected ✓')}`)
   }
   if (serverUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pellicule",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Deterministic video rendering with Vue",
   "type": "module",
   "main": "./src/index.js",

package/src/bundler/entry.js

@@ -8,6 +8,7 @@
 
 import { writeFile, mkdir, rm } from 'fs/promises'
 import { join, basename } from 'path'
+import { generateOverlayScript } from '../dev/overlay.js'
 
 /**
  * Generate the entry HTML that wraps the video at the given dimensions.
@@ -15,9 +16,69 @@ import { join, basename } from 'path'
  * @param {object} options
  * @param {number} options.width
  * @param {number} options.height
+ * @param {boolean} [options.preview] - Whether to inject the dev overlay
+ * @param {number} [options.fps] - FPS (used for overlay display)
+ * @param {number} [options.durationInFrames] - Total frames (used for overlay)
+ * @param {string} [options.version] - Package version (shown in overlay)
  * @returns {string}
  */
-export function generateHtml({ width = 1920, height = 1080 }) {
+export function generateHtml({ width = 1920, height = 1080, preview = false, fps = 30, durationInFrames = 90, version = '' }) {
+  const overlayHtml = preview ? generateOverlayScript({ fps, durationInFrames, version }) : ''
+
+  if (preview) {
+    // Preview mode: scale the video canvas to fit the browser window
+    // while maintaining aspect ratio, with the overlay bar below
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; overflow: hidden; background: #111; }
+    #pellicule-canvas {
+      width: ${width}px;
+      height: ${height}px;
+      transform-origin: top left;
+      position: absolute;
+      top: 0;
+      left: 0;
+    }
+    #app { width: 100%; height: 100%; }
+  </style>
+</head>
+<body>
+  <div id="pellicule-canvas">
+    <div id="app"></div>
+  </div>
+  <script type="module" src="./entry.js"></script>
+  <script>
+    (function() {
+      const VIDEO_W = ${width};
+      const VIDEO_H = ${height};
+      const OVERLAY_H = 64;
+      const canvas = document.getElementById('pellicule-canvas');
+
+      function fitToWindow() {
+        const winW = window.innerWidth;
+        const winH = window.innerHeight - OVERLAY_H;
+        const scale = Math.min(winW / VIDEO_W, winH / VIDEO_H);
+        const offsetX = (winW - VIDEO_W * scale) / 2;
+        const offsetY = (winH - VIDEO_H * scale) / 2;
+        canvas.style.transform = 'scale(' + scale + ')';
+        canvas.style.left = offsetX + 'px';
+        canvas.style.top = offsetY + 'px';
+      }
+
+      fitToWindow();
+      window.addEventListener('resize', fitToWindow);
+    })();
+  </script>
+  ${overlayHtml}
+</body>
+</html>`
+  }
+
+  // Render mode: fixed pixel dimensions matching Playwright viewport
   return `<!DOCTYPE html>
 <html>
 <head>
@@ -99,16 +160,20 @@ try {
  * @param {string} options.inputPath - Absolute path to the .vue file
  * @param {number} options.width
  * @param {number} options.height
+ * @param {boolean} [options.preview] - Whether to inject the dev overlay
+ * @param {number} [options.fps] - FPS (used for overlay)
+ * @param {number} [options.durationInFrames] - Total frames (used for overlay)
+ * @param {string} [options.version] - Package version (shown in overlay)
  * @returns {Promise<{ tempDir: string, cleanup: () => Promise<void> }>}
  */
-export async function writeTempEntry({ inputPath, width = 1920, height = 1080 }) {
+export async function writeTempEntry({ inputPath, width = 1920, height = 1080, preview = false, fps = 30, durationInFrames = 90, version = '' }) {
   const inputDir = join(inputPath, '..')
   const inputFile = basename(inputPath)
   const tempDir = join(inputDir, '.pellicule')
 
   await mkdir(tempDir, { recursive: true })
 
-  const html = generateHtml({ width, height })
+  const html = generateHtml({ width, height, preview, fps, durationInFrames, version })
   const js = generateEntryJs({
     componentPath: `../${inputFile}`,
     width,

package/src/bundler/rsbuild.js

@@ -50,6 +50,10 @@ async function loadUserConfig(configFile, projectType) {
  * @param {number} options.height - Video height
  * @param {string|null} [options.configFile] - Path to the user's config file
  * @param {'rsbuild'|'shipwright'} [options.projectType] - Which config format to read
+ * @param {boolean} [options.preview] - Whether to inject the dev preview overlay
+ * @param {number} [options.fps] - FPS (passed to overlay when preview=true)
+ * @param {number} [options.durationInFrames] - Total frames (passed to overlay when preview=true)
+ * @param {string} [options.version] - Package version (shown in overlay)
  * @returns {Promise<{ server: object, url: string, cleanup: function, tempDir: string }>}
  */
 export async function createVideoServer(options) {
@@ -58,7 +62,11 @@ export async function createVideoServer(options) {
     width = 1920,
     height = 1080,
     configFile = null,
-    projectType = 'rsbuild'
+    projectType = 'rsbuild',
+    preview = false,
+    fps = 30,
+    durationInFrames = 90,
+    version = ''
   } = options
 
   // Resolve Rsbuild from the user's project (not from pellicule's location).
@@ -86,7 +94,11 @@ export async function createVideoServer(options) {
   const { tempDir, cleanup: cleanupTemp } = await writeTempEntry({
     inputPath,
     width,
-    height
+    height,
+    preview,
+    fps,
+    durationInFrames,
+    version
   })
 
   // Load @rsbuild/plugin-vue (also resolved from user's project)

package/src/bundler/vite.js

@@ -22,10 +22,14 @@ const pelliculeSrc = resolve(__dirname, '..')
  * @param {number} options.width - Video width
  * @param {number} options.height - Video height
  * @param {string|null} [options.configFile] - Path to the user's vite.config.js (auto-detected or explicit)
+ * @param {boolean} [options.preview] - Whether to inject the dev preview overlay
+ * @param {number} [options.fps] - FPS (passed to overlay when preview=true)
+ * @param {number} [options.durationInFrames] - Total frames (passed to overlay when preview=true)
+ * @param {string} [options.version] - Package version (shown in overlay)
  * @returns {Promise<{ server: object, url: string, cleanup: function, tempDir: string }>}
  */
 export async function createVideoServer(options) {
-  const { input, width = 1920, height = 1080, configFile = null } = options
+  const { input, width = 1920, height = 1080, configFile = null, preview = false, fps = 30, durationInFrames = 90, version = '' } = options
 
   const inputPath = resolve(input)
 
@@ -33,7 +37,11 @@ export async function createVideoServer(options) {
   const { tempDir, cleanup: cleanupTemp } = await writeTempEntry({
     inputPath,
     width,
-    height
+    height,
+    preview,
+    fps,
+    durationInFrames,
+    version
   })
 
   // Resolve Vue from the user's project to avoid duplicate Vue runtimes.

package/src/dev/overlay.js

@@ -0,0 +1,286 @@
+/**
+ * Generate the preview overlay HTML/CSS/JS that gets injected into the entry page.
+ *
+ * This is a self-contained vanilla JS overlay — no Vue dependency.
+ * It controls frames via the same `window.__PELLICULE_SET_FRAME__()` interface
+ * that Playwright uses during rendering, ensuring WYSIWYG fidelity.
+ *
+ * @param {object} options
+ * @param {number} options.fps
+ * @param {number} options.durationInFrames
+ * @param {string} options.version
+ * @returns {string} Script tag contents to inject
+ */
+export function generateOverlayScript({ fps = 30, durationInFrames = 90, version = '' }) {
+  // Inline SVG icons — consistent sizing across all platforms.
+  // These are static, trusted strings generated at build time (not user input).
+  const playIcon = '<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><polygon points="5,3 19,12 5,21"/></svg>'
+  const pauseIcon = '<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><rect x="5" y="3" width="4" height="18"/><rect x="15" y="3" width="4" height="18"/></svg>'
+  const prevIcon = '<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><polygon points="19,3 7,12 19,21"/><rect x="5" y="3" width="3" height="18"/></svg>'
+  const nextIcon = '<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><polygon points="5,3 17,12 5,21"/><rect x="16" y="3" width="3" height="18"/></svg>'
+
+  return `
+<style>
+  #pellicule-overlay {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    z-index: 99999;
+    background: rgba(15, 15, 15, 0.92);
+    backdrop-filter: blur(8px);
+    border-top: 1px solid rgba(66, 184, 131, 0.3);
+    padding: 8px 12px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
+    font-size: 12px;
+    color: #e0e0e0;
+    user-select: none;
+  }
+  #pellicule-overlay .po-top {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  #pellicule-overlay .po-bottom {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-top: 6px;
+  }
+  #pellicule-overlay .po-brand-group {
+    display: flex;
+    align-items: baseline;
+    gap: 5px;
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+  #pellicule-overlay .po-brand {
+    color: #42b883;
+    font-weight: 700;
+    font-size: 11px;
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
+  }
+  #pellicule-overlay .po-version {
+    color: rgba(66, 184, 131, 0.5);
+    font-size: 9px;
+    font-weight: 500;
+  }
+  #pellicule-overlay .po-controls {
+    display: flex;
+    gap: 4px;
+    flex-shrink: 0;
+  }
+  #pellicule-overlay .po-btn {
+    background: rgba(66, 184, 131, 0.15);
+    border: 1px solid rgba(66, 184, 131, 0.3);
+    color: #42b883;
+    border-radius: 4px;
+    width: 28px;
+    height: 28px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    transition: background 0.15s;
+    flex-shrink: 0;
+    padding: 0;
+    line-height: 0;
+  }
+  #pellicule-overlay .po-btn:hover {
+    background: rgba(66, 184, 131, 0.25);
+  }
+  #pellicule-overlay .po-btn svg {
+    display: block;
+  }
+  #pellicule-overlay .po-scrubber {
+    flex: 1;
+    min-width: 60px;
+    -webkit-appearance: none;
+    appearance: none;
+    height: 4px;
+    background: rgba(255, 255, 255, 0.1);
+    border-radius: 2px;
+    outline: none;
+    cursor: pointer;
+  }
+  #pellicule-overlay .po-scrubber::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 14px;
+    height: 14px;
+    border-radius: 50%;
+    background: #42b883;
+    cursor: pointer;
+    border: 2px solid #0f0f0f;
+  }
+  #pellicule-overlay .po-scrubber::-moz-range-thumb {
+    width: 14px;
+    height: 14px;
+    border-radius: 50%;
+    background: #42b883;
+    cursor: pointer;
+    border: 2px solid #0f0f0f;
+  }
+  #pellicule-overlay .po-info {
+    font-variant-numeric: tabular-nums;
+    color: #999;
+    white-space: nowrap;
+    font-size: 11px;
+    flex-shrink: 0;
+  }
+  #pellicule-overlay .po-info span {
+    color: #e0e0e0;
+  }
+  #pellicule-overlay .po-kbd {
+    font-size: 10px;
+    color: #666;
+    white-space: nowrap;
+    margin-left: auto;
+    flex-shrink: 0;
+  }
+  #pellicule-overlay .po-kbd kbd {
+    background: rgba(255, 255, 255, 0.08);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 3px;
+    padding: 1px 4px;
+    font-family: inherit;
+    font-size: 10px;
+    color: #888;
+  }
+  /* Responsive: hide keyboard hints on narrow screens */
+  @media (max-width: 640px) {
+    #pellicule-overlay .po-kbd { display: none; }
+  }
+</style>
+<div id="pellicule-overlay">
+  <div class="po-top">
+    <span class="po-brand-group">
+      <span class="po-brand">Pellicule</span>
+      <span class="po-version">v${version}</span>
+    </span>
+    <span class="po-controls">
+      <button class="po-btn" id="po-play" title="Play / Pause (Space)">${playIcon}</button>
+      <button class="po-btn" id="po-prev" title="Previous frame (←)">${prevIcon}</button>
+      <button class="po-btn" id="po-next" title="Next frame (→)">${nextIcon}</button>
+    </span>
+    <span class="po-info">
+      <span id="po-frame">0</span> / ${durationInFrames - 1}
+      &nbsp;·&nbsp;
+      <span id="po-time">0.00s</span> / ${(durationInFrames / fps).toFixed(2)}s
+      &nbsp;·&nbsp;
+      ${fps}fps
+    </span>
+    <span class="po-kbd">
+      <kbd>Space</kbd> play
+      <kbd>←</kbd><kbd>→</kbd> step
+    </span>
+  </div>
+  <div class="po-bottom">
+    <input type="range" class="po-scrubber" id="po-scrubber" min="0" max="${durationInFrames - 1}" value="0">
+  </div>
+</div>
+<script>
+(function() {
+  var FPS = ${fps};
+  var TOTAL = ${durationInFrames};
+  var FRAME_MS = 1000 / FPS;
+
+  var currentFrame = 0;
+  var playing = false;
+  var lastTime = 0;
+
+  var scrubber = document.getElementById('po-scrubber');
+  var frameDisplay = document.getElementById('po-frame');
+  var timeDisplay = document.getElementById('po-time');
+  var playBtn = document.getElementById('po-play');
+  var prevBtn = document.getElementById('po-prev');
+  var nextBtn = document.getElementById('po-next');
+
+  // Pre-create the SVG DOM nodes for play/pause toggle (avoids innerHTML)
+  var playTemplate = document.createElement('template');
+  playTemplate.innerHTML = '${playIcon}';
+  var pauseTemplate = document.createElement('template');
+  pauseTemplate.innerHTML = '${pauseIcon}';
+
+  function setFrame(f) {
+    f = Math.max(0, Math.min(TOTAL - 1, f));
+    if (f === currentFrame) return;
+    currentFrame = f;
+    scrubber.value = f;
+    frameDisplay.textContent = f;
+    timeDisplay.textContent = (f / FPS).toFixed(2) + 's';
+    if (window.__PELLICULE_SET_FRAME__) {
+      window.__PELLICULE_SET_FRAME__(f);
+    }
+  }
+
+  function togglePlay() {
+    playing = !playing;
+    // Swap the SVG icon by cloning from the template
+    playBtn.replaceChildren(
+      (playing ? pauseTemplate : playTemplate).content.cloneNode(true)
+    );
+    if (playing) {
+      lastTime = performance.now();
+      requestAnimationFrame(tick);
+    }
+  }
+
+  function tick(now) {
+    if (!playing) return;
+    var delta = now - lastTime;
+    if (delta >= FRAME_MS) {
+      var steps = Math.floor(delta / FRAME_MS);
+      var nextFrame = currentFrame + steps;
+      if (nextFrame >= TOTAL) {
+        setFrame(0);
+      } else {
+        setFrame(nextFrame);
+      }
+      lastTime = now - (delta % FRAME_MS);
+    }
+    requestAnimationFrame(tick);
+  }
+
+  // Scrubber interaction
+  scrubber.addEventListener('input', function() {
+    setFrame(parseInt(scrubber.value, 10));
+  });
+
+  playBtn.addEventListener('click', togglePlay);
+  prevBtn.addEventListener('click', function() { setFrame(currentFrame - 1); });
+  nextBtn.addEventListener('click', function() { setFrame(currentFrame + 1); });
+
+  // Keyboard shortcuts
+  document.addEventListener('keydown', function(e) {
+    if (e.target.tagName === 'INPUT' && e.target.type !== 'range') return;
+
+    switch (e.code) {
+      case 'Space':
+        e.preventDefault();
+        togglePlay();
+        break;
+      case 'ArrowLeft':
+        e.preventDefault();
+        if (playing) togglePlay();
+        setFrame(currentFrame - 1);
+        break;
+      case 'ArrowRight':
+        e.preventDefault();
+        if (playing) togglePlay();
+        setFrame(currentFrame + 1);
+        break;
+      case 'Home':
+        e.preventDefault();
+        setFrame(0);
+        break;
+      case 'End':
+        e.preventDefault();
+        setFrame(TOTAL - 1);
+        break;
+    }
+  });
+})();
+</script>`
+}

package/src/dev/server.js

@@ -0,0 +1,100 @@
+/**
+ * Dev preview server.
+ *
+ * Starts the same bundler dev server used for rendering, but instead of
+ * launching Playwright to screenshot frames, opens the user's browser
+ * with an interactive preview overlay.
+ *
+ * The overlay uses the same `window.__PELLICULE_SET_FRAME__()` mechanism
+ * as the renderer, so what you see in preview is what you get in the
+ * final render.
+ */
+
+import { execFile } from 'node:child_process'
+import { startBundlerServer } from '../renderer/render.js'
+
+/**
+ * Open a URL in the user's default browser using platform-native commands.
+ * Uses execFile (not exec) to avoid shell injection.
+ * @param {string} url
+ */
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start'
+    : 'xdg-open'
+  execFile(cmd, [url], () => {})
+}
+
+/**
+ * Start the dev preview server.
+ *
+ * @param {object} options
+ * @param {string} options.input - Absolute path to the .vue file
+ * @param {number} options.fps
+ * @param {number} options.durationInFrames
+ * @param {number} options.width
+ * @param {number} options.height
+ * @param {string|null} [options.serverUrl] - BYOS server URL (Nuxt/Quasar)
+ * @param {'vite'|'rsbuild'} [options.bundler]
+ * @param {string|null} [options.configFile]
+ * @param {string} [options.projectType]
+ * @param {string} [options.version] - Package version (shown in overlay)
+ * @returns {Promise<void>}
+ */
+export async function startDevServer(options) {
+  const {
+    input,
+    fps = 30,
+    durationInFrames = 90,
+    width = 1920,
+    height = 1080,
+    serverUrl = null,
+    bundler = 'vite',
+    configFile = null,
+    projectType = 'standalone',
+    version = ''
+  } = options
+
+  let url
+  let cleanup
+
+  if (serverUrl) {
+    // BYOS mode (Nuxt/Quasar) — just use the existing server
+    url = serverUrl
+    cleanup = async () => {}
+  } else {
+    // Start a bundler dev server with preview overlay enabled
+    const server = await startBundlerServer({
+      input,
+      width,
+      height,
+      bundler,
+      configFile,
+      projectType,
+      preview: true,
+      fps,
+      durationInFrames,
+      version
+    })
+    url = server.url
+    cleanup = server.cleanup
+  }
+
+  // Build the full URL with config params
+  const separator = url.includes('?') ? '&' : '?'
+  const fullUrl = `${url}${separator}fps=${fps}&duration=${durationInFrames}&width=${width}&height=${height}`
+
+  // Open in the user's default browser
+  openBrowser(fullUrl)
+
+  // Keep process alive and handle graceful shutdown
+  const shutdown = async () => {
+    await cleanup()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+
+  return { url: fullUrl, cleanup }
+}

package/src/renderer/render.js

@@ -12,9 +12,13 @@ import { join, dirname } from 'path'
  * @param {'vite'|'rsbuild'} options.bundler - Which bundler adapter to use
  * @param {string|null} options.configFile - Path to the user's config file
  * @param {string} options.projectType - Detected project type (for Shipwright config reading)
+ * @param {boolean} [options.preview] - Whether to inject the dev preview overlay
+ * @param {number} [options.fps] - FPS (passed to overlay when preview=true)
+ * @param {number} [options.durationInFrames] - Total frames (passed to overlay when preview=true)
+ * @param {string} [options.version] - Package version (shown in overlay)
  * @returns {Promise<{ url: string, cleanup: function, tempDir: string }>}
  */
-async function startBundlerServer(options) {
+export async function startBundlerServer(options) {
   const { bundler = 'vite', ...serverOptions } = options
 
   if (bundler === 'rsbuild') {