pellicule 0.0.0 → 0.0.2

package/bin/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util'
+import { resolve, extname, basename, dirname } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { renderToMp4 } from '../src/render.js'
+
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'))
+const VERSION = pkg.version
+
+// ANSI color codes (no dependencies needed)
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  pellicule: '\x1b[38;2;66;184;131m', // #42b883 - Vue green
+  bgPellicule: '\x1b[48;2;66;184;131m'
+}
+
+const c = {
+  error: (s) => `${colors.red}${s}${colors.reset}`,
+  warn: (s) => `${colors.yellow}${s}${colors.reset}`,
+  info: (s) => `${colors.cyan}${s}${colors.reset}`,
+  dim: (s) => `${colors.dim}${s}${colors.reset}`,
+  bold: (s) => `${colors.bold}${s}${colors.reset}`,
+  highlight: (s) => `${colors.pellicule}${s}${colors.reset}`,
+  brand: (s) => `${colors.bgPellicule}${colors.white}${colors.bold}${s}${colors.reset}`
+}
+
+function fail(msg, hint) {
+  console.error(c.error(`\nError: ${msg}\n`))
+  if (hint) console.error(c.dim(`  ${hint}\n`))
+  process.exit(1)
+}
+
+const HELP = `
+${c.bold('pellicule')} ${c.dim(`v${VERSION}`)} - Render Vue components to video
+
+${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.bold('OPTIONS')}
+  ${c.info('-o, --output')} <file>     Output file path ${c.dim('(default: ./output.mp4)')}
+  ${c.info('-d, --duration')} <frames> Duration in frames ${c.dim('(default: 90)')}
+  ${c.info('-f, --fps')} <number>      Frames per second ${c.dim('(default: 30)')}
+  ${c.info('-w, --width')} <pixels>    Video width ${c.dim('(default: 1920)')}
+  ${c.info('-h, --height')} <pixels>   Video height ${c.dim('(default: 1080)')}
+  ${c.info('-r, --range')} <start:end> Frame range for partial render ${c.dim('(e.g., 100:200)')}
+  ${c.info('--help')}                 Show this help message
+  ${c.info('--version')}               Show version number
+
+${c.bold('EXAMPLES')}
+  ${c.dim('# Zero-config (renders Video.vue → output.mp4)')}
+  ${c.highlight('pellicule')}
+
+  ${c.dim('# Specify input file (.vue extension is optional)')}
+  ${c.highlight('pellicule')} MyVideo
+
+  ${c.dim('# Custom output and duration')}
+  ${c.highlight('pellicule')} Video.vue -o intro.mp4 -d 150
+
+  ${c.dim('# 4K video at 60fps')}
+  ${c.highlight('pellicule')} Video.vue -w 3840 -h 2160 -f 60
+
+  ${c.dim('# 10 second video')}
+  ${c.highlight('pellicule')} Video.vue -d 300 -f 30
+
+  ${c.dim('# Render only frames 100-200 (for faster iteration)')}
+  ${c.highlight('pellicule')} Video.vue -d 300 -r 100:200
+
+  ${c.dim('# Render from frame 150 to 250')}
+  ${c.highlight('pellicule')} Video.vue -d 300 --range 150:250
+
+${c.bold('DURATION HELPER')}
+  frames = seconds * fps
+  ${c.dim('3 seconds at 30fps  = 90 frames')}
+  ${c.dim('5 seconds at 30fps  = 150 frames')}
+  ${c.dim('10 seconds at 60fps = 600 frames')}
+
+${c.dim('Documentation: https://docs.sailscasts.com/pellicule')}
+`
+
+function printBanner() {
+  console.log()
+  console.log(`  ${c.brand(' PELLICULE ')} ${c.dim(`v${VERSION}`)}`)
+  console.log()
+}
+
+function formatTime(ms) {
+  if (ms < 1000) return `${ms}ms`
+  const seconds = (ms / 1000).toFixed(1)
+  return `${seconds}s`
+}
+
+function formatProgress(frame, total, fps) {
+  const percent = Math.round(((frame + 1) / total) * 100)
+  const barWidth = 30
+  const filled = Math.round((percent / 100) * barWidth)
+  const empty = barWidth - filled
+  const bar = c.highlight('█'.repeat(filled)) + c.dim('░'.repeat(empty))
+  return `  ${bar} ${c.bold(percent + '%')} ${c.dim(`(${frame + 1}/${total} @ ${fps.toFixed(1)} fps)`)}`
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      output: { type: 'string', short: 'o' },
+      duration: { type: 'string', short: 'd' },
+      fps: { type: 'string', short: 'f' },
+      width: { type: 'string', short: 'w' },
+      height: { type: 'string', short: 'h' },
+      range: { type: 'string', short: 'r' },
+      help: { type: 'boolean' },
+      version: { type: 'boolean' }
+    }
+  })
+
+  // Handle help and version
+  if (values.help) {
+    console.log(HELP)
+    process.exit(0)
+  }
+
+  if (values.version) {
+    console.log(VERSION)
+    process.exit(0)
+  }
+
+  // Default to Video.vue if no input provided
+  const input = positionals[0] || 'Video.vue'
+
+  // Try to resolve the input file, auto-appending .vue if needed
+  let inputPath = resolve(input)
+
+  if (!existsSync(inputPath) && !input.endsWith('.vue')) {
+    const withVue = resolve(input + '.vue')
+    if (existsSync(withVue)) {
+      inputPath = withVue
+    }
+  }
+
+  if (!existsSync(inputPath)) fail(`File not found: ${input}`)
+  if (extname(inputPath) !== '.vue') fail(`Input must be a .vue file, got: ${extname(inputPath) || '(no extension)'}`)
+
+  // Parse options with defaults
+  const fps = parseInt(values.fps || '30', 10)
+  const durationInFrames = parseInt(values.duration || '90', 10)
+  const width = parseInt(values.width || '1920', 10)
+  const height = parseInt(values.height || '1080', 10)
+  const output = values.output || './output.mp4'
+  const outputPath = resolve(output)
+
+  // Parse optional range (start:end format)
+  let startFrame = 0
+  let endFrame = durationInFrames
+
+  if (values.range) {
+    const rangeParts = values.range.split(':')
+    if (rangeParts.length !== 2) fail(`Invalid range format: ${values.range}`, 'Expected format: start:end (e.g., 100:200)')
+    const [startStr, endStr] = rangeParts
+    startFrame = parseInt(startStr, 10)
+    endFrame = parseInt(endStr, 10)
+    if (isNaN(startFrame) || startFrame < 0) fail(`Invalid start frame in range: ${startStr}`)
+    if (isNaN(endFrame) || endFrame <= 0) fail(`Invalid end frame in range: ${endStr}`)
+  }
+
+  // Validate options
+  if (isNaN(fps) || fps <= 0) fail(`Invalid fps value: ${values.fps}`)
+  if (isNaN(durationInFrames) || durationInFrames <= 0) fail(`Invalid duration value: ${values.duration}`)
+  if (isNaN(width) || width <= 0) fail(`Invalid width value: ${values.width}`)
+  if (isNaN(height) || height <= 0) fail(`Invalid height value: ${values.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})`)
+
+  // 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))}`)
+  console.log(`  ${c.bold('Output')}     ${c.info(basename(outputPath))}`)
+  console.log(`  ${c.bold('Resolution')} ${width}x${height}`)
+  console.log(`  ${c.bold('Duration')}   ${durationInFrames} frames @ ${fps}fps ${c.dim(`(${durationSeconds}s)`)}`)
+  if (isPartialRender) {
+    console.log(`  ${c.bold('Range')}      ${c.highlight(`frames ${startFrame}-${endFrame - 1}`)} ${c.dim(`(${framesToRender} frames, ${partialSeconds}s)`)}`)
+  }
+  console.log()
+
+  const startTime = Date.now()
+
+  // ANSI escape codes for line control
+  const clearLine = '\x1b[2K'  // Clear entire line
+  const cursorToStart = '\r'   // Move cursor to start of line
+
+  try {
+    // Render with progress callback
+    await renderToMp4({
+      input: inputPath,
+      fps,
+      durationInFrames,
+      startFrame,
+      endFrame,
+      width,
+      height,
+      output: outputPath,
+      silent: true,
+      onProgress: ({ frame, total, fps: currentFps }) => {
+        // Clear line and print progress (stays on same line)
+        process.stdout.write(clearLine + cursorToStart + formatProgress(frame, total, currentFps || fps))
+      }
+    })
+
+    // Clear progress line when done
+    process.stdout.write(clearLine + cursorToStart)
+
+    const totalTime = Date.now() - startTime
+    console.log()
+    console.log(`  ${c.highlight('Done!')} Rendered ${framesToRender} frames in ${formatTime(totalTime)}`)
+    console.log(`  ${c.dim('Output:')} ${outputPath}`)
+    console.log()
+
+  } catch (error) {
+    // Clear progress line on error
+    process.stdout.write(clearLine + cursorToStart)
+    console.error()
+    console.error(c.error(`  Error: ${error.message}`))
+    console.error()
+
+    if (error.message.includes('ffmpeg')) {
+      console.error(c.warn('  Hint: Make sure FFmpeg is installed and available in your PATH'))
+      console.error(c.dim('  Install: https://ffmpeg.org/download.html'))
+      console.error()
+    }
+
+    process.exit(1)
+  }
+}
+
+main().catch((error) => {
+  console.error(c.error(`\nUnexpected error: ${error.message}\n`))
+  process.exit(1)
+})

package/package.json

@@ -1,42 +1,37 @@
 {
   "name": "pellicule",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Deterministic video rendering with Vue",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "pellicule": "./bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./render": "./src/render.js"
+  },
   "keywords": [
     "vue",
     "video",
     "rendering",
     "animation",
     "frames",
-    "remotion",
     "programmatic-video"
   ],
-  "author": "",
+  "author": "Kelvin Omereshone <kelvin@sailscasts.com>",
   "license": "MIT",
+  "homepage": "https://docs.sailscasts.com/pellicule",
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "https://github.com/sailscastshq/pellicule"
   },
-  "homepage": "",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
-    }
+  "dependencies": {
+    "vite": "^5.0.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "playwright": "^1.40.0"
   },
-  "files": [
-    "dist"
-  ],
   "peerDependencies": {
     "vue": "^3.0.0"
-  },
-  "devDependencies": {
-    "vue": "^3.4.0",
-    "typescript": "^5.0.0"
   }
 }

package/src/bundler/vite.js

@@ -0,0 +1,124 @@
+import { createServer } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { writeFile, mkdir, rm } from 'fs/promises'
+import { join, resolve, dirname, basename } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pelliculeSrc = resolve(__dirname, '..')
+
+/**
+ * Creates a Vite dev server in the user's project directory.
+ * This way Vite naturally finds their node_modules with Vue installed.
+ *
+ * @param {object} options
+ * @param {string} options.input - Path to the .vue file
+ * @param {number} options.width - Video width
+ * @param {number} options.height - Video height
+ * @returns {Promise<{ server: object, url: string, cleanup: function }>}
+ */
+export async function createVideoServer(options) {
+  const { input, width = 1920, height = 1080 } = options
+
+  const inputPath = resolve(input)
+  const inputDir = dirname(inputPath)
+  const inputFile = basename(inputPath)
+
+  // Create .pellicule temp folder in user's project
+  const tempDir = join(inputDir, '.pellicule')
+  await mkdir(tempDir, { recursive: true })
+
+  // Create entry HTML
+  const htmlContent = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: ${width}px; height: ${height}px; overflow: hidden; }
+    #app { width: 100%; height: 100%; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="./entry.js"></script>
+</body>
+</html>`
+
+  // Create entry JS with setFrame function for fast frame updates
+  const entryContent = `
+import { createApp, ref, provide, h, nextTick } from 'vue'
+import VideoComponent from '../${inputFile}'
+
+// Pellicule injection keys (must match composables.js)
+const FRAME_KEY = Symbol.for('pellicule-frame')
+const CONFIG_KEY = Symbol.for('pellicule-config')
+
+// Get initial config from URL
+const params = new URLSearchParams(window.location.search)
+const fps = parseInt(params.get('fps') || '30', 10)
+const durationInFrames = parseInt(params.get('duration') || '90', 10)
+const width = parseInt(params.get('width') || '${width}', 10)
+const height = parseInt(params.get('height') || '${height}', 10)
+
+const config = { fps, durationInFrames, width, height }
+
+// Frame ref - reactive, will trigger re-render when changed
+const frameRef = ref(0)
+
+// Expose setFrame function for the renderer to call
+window.__PELLICULE_SET_FRAME__ = async (frame) => {
+  frameRef.value = frame
+  await nextTick() // Wait for Vue to re-render
+}
+
+try {
+  // Create app with frame context
+  const app = createApp({
+    setup() {
+      provide(FRAME_KEY, frameRef)
+      provide(CONFIG_KEY, config)
+      return () => h(VideoComponent)
+    }
+  })
+
+  app.mount('#app')
+  window.__PELLICULE_READY__ = true
+} catch (error) {
+  console.error('Pellicule render error:', error)
+  window.__PELLICULE_READY__ = true
+  window.__PELLICULE_ERROR__ = error.message
+}
+`
+
+  await writeFile(join(tempDir, 'index.html'), htmlContent)
+  await writeFile(join(tempDir, 'entry.js'), entryContent)
+
+  // Create Vite server rooted in the user's project directory
+  const server = await createServer({
+    root: tempDir,
+    plugins: [vue()],
+    server: {
+      port: 0,
+      strictPort: false
+    },
+    resolve: {
+      alias: {
+        'pellicule': pelliculeSrc
+      }
+    },
+    logLevel: 'warn'
+  })
+
+  await server.listen()
+
+  const address = server.httpServer.address()
+  const url = `http://localhost:${address.port}`
+
+  const cleanup = async () => {
+    await server.close()
+    await rm(tempDir, { recursive: true, force: true })
+  }
+
+  return { server, url, cleanup, tempDir }
+}

package/src/components/Sequence.vue

@@ -0,0 +1,34 @@
+<script setup>
+import { computed } from 'vue'
+import { useFrame } from '../composables/frame.js'
+import { provideSequence } from '../composables/sequence.js'
+
+const props = defineProps({
+  /**
+   * The frame number where this sequence starts
+   */
+  from: {
+    type: Number,
+    required: true
+  },
+  /**
+   * Duration of this sequence in frames
+   */
+  durationInFrames: {
+    type: Number,
+    required: true
+  }
+})
+
+const globalFrame = useFrame()
+
+// Provide sequence context to children
+const { isActive } = provideSequence(props.from, props.durationInFrames)
+
+// Compute whether to show content
+const shouldRender = computed(() => isActive.value)
+</script>
+
+<template>
+  <slot v-if="shouldRender" />
+</template>

package/src/composables/frame.js

@@ -0,0 +1,24 @@
+import { inject, computed } from 'vue'
+import { FRAME_KEY } from './keys.js'
+
+/**
+ * Get the current frame number.
+ * Must be used within a Pellicule render context.
+ *
+ * @returns {import('vue').ComputedRef<number>} Current frame number
+ *
+ * @example
+ * const frame = useFrame()
+ * const opacity = computed(() => frame.value / 30) // fade in over 1 second at 30fps
+ */
+export function useFrame() {
+  const frame = inject(FRAME_KEY)
+
+  if (frame === undefined) {
+    throw new Error(
+      'useFrame() must be used within a Pellicule render context'
+    )
+  }
+
+  return computed(() => frame.value)
+}

package/src/composables/keys.js

@@ -0,0 +1,7 @@
+/**
+ * Injection keys for Pellicule context
+ * Using Symbol.for() so keys are shared across module instances
+ */
+export const FRAME_KEY = Symbol.for('pellicule-frame')
+export const CONFIG_KEY = Symbol.for('pellicule-config')
+export const SEQUENCE_KEY = Symbol.for('pellicule-sequence')

package/src/composables/sequence.js

@@ -0,0 +1,82 @@
+import { inject, computed, provide } from 'vue'
+import { SEQUENCE_KEY } from './keys.js'
+import { useFrame } from './frame.js'
+
+/**
+ * Get sequence timing information.
+ * Can be used in two ways:
+ *
+ * 1. Inside a <Sequence> component - returns timing for that sequence
+ * 2. With explicit timing - useSequence(from, durationInFrames)
+ *
+ * @param {number} [from] - Start frame (optional if inside <Sequence>)
+ * @param {number} [durationInFrames] - Duration in frames (optional if inside <Sequence>)
+ * @returns {{ localFrame: ComputedRef<number>, progress: ComputedRef<number>, isActive: ComputedRef<boolean> }}
+ *
+ * @example
+ * // Inside a <Sequence> component
+ * const { localFrame, progress, isActive } = useSequence()
+ *
+ * @example
+ * // With explicit timing
+ * const verse1 = useSequence(0, 90)
+ * const verse2 = useSequence(90, 90)
+ */
+export function useSequence(from, durationInFrames) {
+  const globalFrame = useFrame()
+
+  // If arguments provided, use them directly
+  if (from !== undefined && durationInFrames !== undefined) {
+    const end = from + durationInFrames
+
+    const localFrame = computed(() => Math.max(0, globalFrame.value - from))
+    const progress = computed(() => {
+      if (globalFrame.value < from) return 0
+      if (globalFrame.value >= end) return 1
+      return (globalFrame.value - from) / durationInFrames
+    })
+    const isActive = computed(() =>
+      globalFrame.value >= from && globalFrame.value < end
+    )
+
+    return { localFrame, progress, isActive }
+  }
+
+  // Otherwise, try to get from parent <Sequence>
+  const sequenceContext = inject(SEQUENCE_KEY, null)
+
+  if (!sequenceContext) {
+    throw new Error(
+      'useSequence() must be used within a <Sequence> component or called with (from, durationInFrames) arguments'
+    )
+  }
+
+  return sequenceContext
+}
+
+/**
+ * Provide sequence context to children.
+ * Used internally by the <Sequence> component.
+ *
+ * @param {number} from - Start frame
+ * @param {number} durationInFrames - Duration in frames
+ */
+export function provideSequence(from, durationInFrames) {
+  const globalFrame = useFrame()
+  const end = from + durationInFrames
+
+  const localFrame = computed(() => Math.max(0, globalFrame.value - from))
+  const progress = computed(() => {
+    if (globalFrame.value < from) return 0
+    if (globalFrame.value >= end) return 1
+    return (globalFrame.value - from) / durationInFrames
+  })
+  const isActive = computed(() =>
+    globalFrame.value >= from && globalFrame.value < end
+  )
+
+  const context = { localFrame, progress, isActive, from, durationInFrames }
+  provide(SEQUENCE_KEY, context)
+
+  return context
+}

package/src/composables/video-config.js

@@ -0,0 +1,23 @@
+import { inject } from 'vue'
+import { CONFIG_KEY } from './keys.js'
+
+/**
+ * Get the video configuration (fps, duration, dimensions).
+ * Must be used within a Pellicule render context.
+ *
+ * @returns {{ fps: number, durationInFrames: number, width: number, height: number }}
+ *
+ * @example
+ * const { fps, durationInFrames, width, height } = useVideoConfig()
+ */
+export function useVideoConfig() {
+  const config = inject(CONFIG_KEY)
+
+  if (!config) {
+    throw new Error(
+      'useVideoConfig() must be used within a Pellicule render context'
+    )
+  }
+
+  return config
+}

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * Pellicule - Deterministic video rendering with Vue
+ *
+ * This is the browser-safe entry point.
+ * For rendering (Node.js), import from 'pellicule/render'
+ */
+
+// Composables
+export { useFrame } from './composables/frame.js'
+export { useVideoConfig } from './composables/video-config.js'
+export { useSequence } from './composables/sequence.js'
+export { FRAME_KEY, CONFIG_KEY, SEQUENCE_KEY } from './composables/keys.js'
+
+// Components
+export { default as Sequence } from './components/Sequence.vue'
+
+// Animation utilities
+export { interpolate, sequence, Easing } from './utils/math.js'

package/src/render.js

@@ -0,0 +1,8 @@
+/**
+ * Pellicule Renderer - Node.js only
+ *
+ * This module requires Node.js and cannot run in the browser.
+ */
+
+export { renderVideo } from './renderer/render.js'
+export { encodeVideo, renderToMp4 } from './renderer/encode.js'

package/src/renderer/encode.js

@@ -0,0 +1,95 @@
+import { spawn } from 'child_process'
+import path from 'path'
+
+/**
+ * Encodes PNG frames into an MP4 video using FFmpeg.
+ *
+ * @param {object} options
+ * @param {string} options.framesDir - Directory containing frame-XXXXX.png files
+ * @param {string} options.output - Output video path (default: './output.mp4')
+ * @param {number} options.fps - Frames per second (default: 30)
+ * @param {boolean} options.silent - Suppress console output (default: false)
+ * @returns {Promise<string>} Path to the output video
+ */
+export function encodeVideo(options) {
+  const {
+    framesDir,
+    output = './output.mp4',
+    fps = 30,
+    silent = false
+  } = options
+
+  return new Promise((resolve, reject) => {
+    const framePattern = path.join(framesDir, 'frame-%05d.png')
+
+    const args = [
+      '-y', // Overwrite output
+      '-framerate', String(fps),
+      '-i', framePattern,
+      '-c:v', 'libx264',
+      '-pix_fmt', 'yuv420p', // Compatibility
+      '-preset', 'fast',
+      output
+    ]
+
+    if (!silent) {
+      console.log(`Encoding video: ffmpeg ${args.join(' ')}`)
+    }
+
+    const ffmpeg = spawn('ffmpeg', args)
+
+    ffmpeg.stderr.on('data', (data) => {
+      // FFmpeg outputs progress to stderr
+      if (!silent) {
+        const line = data.toString()
+        if (line.includes('frame=')) {
+          process.stdout.write(`\r${line.trim()}`)
+        }
+      }
+    })
+
+    ffmpeg.on('close', (code) => {
+      if (!silent) {
+        console.log('') // New line after progress
+      }
+      if (code === 0) {
+        if (!silent) {
+          console.log(`Video saved to ${output}`)
+        }
+        resolve(output)
+      } else {
+        reject(new Error(`FFmpeg exited with code ${code}`))
+      }
+    })
+
+    ffmpeg.on('error', (err) => {
+      reject(new Error(`ffmpeg error: ${err.message}. Is ffmpeg installed?`))
+    })
+  })
+}
+
+/**
+ * Full render pipeline: Vue component → frames → MP4
+ *
+ * @param {object} options - Same as renderVideo, plus output path
+ * @param {boolean} options.silent - Suppress console output (default: false)
+ * @returns {Promise<string>} Path to the output video
+ */
+export async function renderToMp4(options) {
+  const { renderVideo } = await import('./render.js')
+
+  const { output = './output.mp4', silent = false, ...renderOptions } = options
+
+  // Step 1: Render frames
+  const { framesDir } = await renderVideo({ ...renderOptions, silent })
+
+  // Step 2: Encode to MP4
+  const videoPath = await encodeVideo({
+    framesDir,
+    output,
+    fps: renderOptions.fps || 30,
+    silent
+  })
+
+  return videoPath
+}

package/src/renderer/render.js

@@ -0,0 +1,134 @@
+import { chromium } from 'playwright'
+import { createVideoServer } from '../bundler/vite.js'
+import { mkdir } from 'fs/promises'
+import { join } from 'path'
+
+/**
+ * Renders a .vue component to video frames.
+ *
+ * @param {object} options
+ * @param {string} options.input - Path to the .vue file
+ * @param {number} options.fps - Frames per second (default: 30)
+ * @param {number} options.durationInFrames - Total frames in the video (for animation calculations)
+ * @param {number} options.startFrame - First frame to render (default: 0)
+ * @param {number} options.endFrame - Last frame to render, exclusive (default: durationInFrames)
+ * @param {number} options.width - Video width in pixels (default: 1920)
+ * @param {number} options.height - Video height in pixels (default: 1080)
+ * @param {string} options.outputDir - Directory for frame images (default: './frames')
+ * @param {function} options.onProgress - Progress callback
+ * @returns {Promise<{ framesDir: string, totalFrames: number }>}
+ */
+export async function renderVideo(options) {
+  const {
+    input,
+    fps = 30,
+    durationInFrames,
+    startFrame = 0,
+    endFrame,
+    width = 1920,
+    height = 1080,
+    outputDir = './frames',
+    onProgress,
+    silent = false
+  } = options
+
+  // Calculate actual frame range to render
+  const actualEndFrame = endFrame !== undefined ? endFrame : durationInFrames
+  const framesToRender = actualEndFrame - startFrame
+
+  const log = silent ? () => {} : console.log.bind(console)
+
+  const startTime = Date.now()
+
+  // Start Vite server with the video component
+  log(`Starting Vite server for ${input}...`)
+  const viteStart = Date.now()
+  const { url, cleanup } = await createVideoServer({ input, width, height })
+  log(`Server ready in ${Date.now() - viteStart}ms`)
+
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true })
+
+  // Launch browser
+  const browser = await chromium.launch()
+  const context = await browser.newContext({
+    viewport: { width, height },
+    deviceScaleFactor: 1
+  })
+  const page = await context.newPage()
+
+  // Capture console errors (only log if not silent)
+  page.on('console', msg => {
+    if (msg.type() === 'error' && !silent) {
+      console.error('Browser error:', msg.text())
+    }
+  })
+
+  page.on('pageerror', error => {
+    if (!silent) {
+      console.error('Page error:', error.message)
+    }
+  })
+
+  const rangeInfo = startFrame > 0 || actualEndFrame < durationInFrames
+    ? ` (frames ${startFrame}-${actualEndFrame - 1})`
+    : ''
+  log(`Rendering ${framesToRender} frames at ${fps}fps (${width}x${height})${rangeInfo}`)
+
+  try {
+    // Load page ONCE with config (durationInFrames stays full for correct animation calculations)
+    const pageUrl = `${url}?fps=${fps}&duration=${durationInFrames}&width=${width}&height=${height}`
+    await page.goto(pageUrl, { waitUntil: 'networkidle' })
+
+    // Wait for Vue to mount
+    await page.waitForFunction(() => window.__PELLICULE_READY__ === true, { timeout: 10000 })
+
+    // Check for errors
+    const error = await page.evaluate(() => window.__PELLICULE_ERROR__)
+    if (error) {
+      throw new Error(`Render error: ${error}`)
+    }
+
+    const renderStart = Date.now()
+
+    // Render each frame in the specified range
+    for (let frame = startFrame; frame < actualEndFrame; frame++) {
+      // Update frame number - Vue reactivity handles re-render
+      await page.evaluate((f) => window.__PELLICULE_SET_FRAME__(f), frame)
+
+      // Screenshot - output frames are numbered from 0
+      const outputFrameNum = frame - startFrame
+      const framePath = join(outputDir, `frame-${String(outputFrameNum).padStart(5, '0')}.png`)
+      await page.screenshot({ path: framePath })
+
+      // Progress callback
+      if (onProgress) {
+        const elapsed = Date.now() - renderStart
+        const framesRendered = outputFrameNum + 1
+        const currentFps = framesRendered / (elapsed / 1000)
+        onProgress({ frame: outputFrameNum, total: framesToRender, fps: currentFps })
+      }
+
+      // Log progress every 10 frames
+      const outputFrameIndex = frame - startFrame
+      if (outputFrameIndex % 10 === 0 || frame === actualEndFrame - 1) {
+        const percent = Math.round(((outputFrameIndex + 1) / framesToRender) * 100)
+        const elapsed = Date.now() - renderStart
+        const framesPerSec = ((outputFrameIndex + 1) / (elapsed / 1000)).toFixed(1)
+        log(`Frame ${outputFrameIndex + 1}/${framesToRender} (${percent}%) - ${framesPerSec} fps`)
+      }
+    }
+
+    const renderTime = Date.now() - renderStart
+    log(`Rendered ${framesToRender} frames in ${renderTime}ms (${(framesToRender / (renderTime / 1000)).toFixed(1)} fps)`)
+
+  } finally {
+    await browser.close()
+    await cleanup()
+  }
+
+  log(`Total time: ${Date.now() - startTime}ms`)
+  log(`Frames saved to ${outputDir}`)
+
+  return { framesDir: outputDir, totalFrames: framesToRender }
+}

package/src/utils/math.js

@@ -0,0 +1,78 @@
+/**
+ * Easing functions for smooth animations
+ */
+export const Easing = {
+  linear: (t) => t,
+  easeIn: (t) => t * t,
+  easeOut: (t) => t * (2 - t),
+  easeInOut: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t)
+}
+
+/**
+ * Maps a value from one range to another.
+ * The core animation primitive in Pellicule.
+ *
+ * @param {number} frame - Current frame number
+ * @param {[number, number]} inputRange - [startFrame, endFrame]
+ * @param {[number, number]} outputRange - [startValue, endValue]
+ * @param {object} options - Optional settings
+ * @param {function} options.easing - Easing function (default: linear)
+ * @param {'clamp'|'extend'} options.extrapolate - Behavior outside input range
+ * @returns {number} Interpolated value
+ *
+ * @example
+ * // Fade in over first 30 frames
+ * const opacity = interpolate(frame, [0, 30], [0, 1])
+ *
+ * @example
+ * // Slide from left with easing
+ * const x = interpolate(frame, [0, 60], [-100, 0], { easing: Easing.easeOut })
+ */
+export function interpolate(frame, inputRange, outputRange, options = {}) {
+  const { easing = Easing.linear, extrapolate = 'clamp' } = options
+
+  const [inStart, inEnd] = inputRange
+  const [outStart, outEnd] = outputRange
+
+  // Calculate progress (0 to 1)
+  let progress = (frame - inStart) / (inEnd - inStart)
+
+  // Handle extrapolation
+  if (extrapolate === 'clamp') {
+    progress = Math.max(0, Math.min(1, progress))
+  }
+
+  // Apply easing
+  const easedProgress = easing(progress)
+
+  // Map to output range
+  return outStart + (outEnd - outStart) * easedProgress
+}
+
+/**
+ * Creates a sequence of timed animations.
+ * Useful for staggered or chained animations.
+ *
+ * @param {number} frame - Current frame number
+ * @param {Array<{start: number, end: number, from: number, to: number}>} sequence
+ * @returns {number} Current value in the sequence
+ *
+ * @example
+ * const scale = sequence(frame, [
+ *   { start: 0, end: 15, from: 0, to: 1 },    // grow
+ *   { start: 45, end: 60, from: 1, to: 0 }    // shrink
+ * ])
+ */
+export function sequence(frame, steps) {
+  for (const step of steps) {
+    if (frame >= step.start && frame <= step.end) {
+      return interpolate(frame, [step.start, step.end], [step.from, step.to])
+    }
+    if (frame < step.start) {
+      return step.from
+    }
+  }
+  // Return last value if past all steps
+  const lastStep = steps[steps.length - 1]
+  return lastStep ? lastStep.to : 0
+}

package/dist/index.cjs

@@ -1,6 +0,0 @@
-/**
- * Pellicule - Deterministic video rendering with Vue
- */
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = '0.0.0';

package/dist/index.d.ts

@@ -1,4 +0,0 @@
-/**
- * Pellicule - Deterministic video rendering with Vue
- */
-export declare const VERSION = "0.0.0";

package/dist/index.js

@@ -1,4 +0,0 @@
-/**
- * Pellicule - Deterministic video rendering with Vue
- */
-export const VERSION = '0.0.0';