pellicule 0.0.4 → 0.1.0

package/bin/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
 import { parseArgs } from 'node:util'
-import { resolve, extname, basename, dirname } from 'node:path'
+import { resolve, join, extname, basename, dirname } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 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'
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -60,6 +61,13 @@ ${c.bold('OPTIONS')}
   ${c.info('--help')}                 Show this help message
   ${c.info('--version')}               Show version number
 
+${c.bold('INTEGRATION OPTIONS')}
+  ${c.info('--server-url')} <url>      Use a running dev server (BYOS mode)
+  ${c.info('--bundler')} <name>        Force a bundler: vite or rsbuild
+  ${c.info('--config')} <file>         Use a specific config file
+  ${c.info('--videos-dir')} <path>     Custom directory for video components
+  ${c.info('--out-dir')} <path>        Directory for rendered video output
+
 ${c.bold('COMPONENT CONFIG')}
   Use ${c.highlight('defineVideoConfig')} in your component to set defaults:
 
@@ -68,6 +76,22 @@ ${c.bold('COMPONENT CONFIG')}
   No import needed - it's a compiler macro like Vue's defineProps.
   Then just run: ${c.highlight('pellicule')} ${c.dim('(no flags needed!)')}
 
+${c.bold('PROJECT CONFIG')}
+  Set options once in package.json instead of passing CLI flags:
+
+  ${c.dim('{ "pellicule": { "serverUrl": "http://localhost:3000" } }')}
+
+  Supported keys: ${c.info('serverUrl')}, ${c.info('videosDir')}, ${c.info('outDir')}, ${c.info('bundler')}
+  Resolution: CLI flags > package.json > auto-detected > defaults
+
+${c.bold('AUTO-DETECTION')}
+  Pellicule reads your existing config files automatically:
+  ${c.dim('vite.config.js')}       → Vite adapter
+  ${c.dim('rsbuild.config.js')}    → Rsbuild adapter
+  ${c.dim('config/shipwright.js')} → Rsbuild adapter (boring stack)
+  ${c.dim('nuxt.config.ts')}       → BYOS mode (defaults to localhost:3000)
+  ${c.dim('No config')}            → Built-in Vite (zero config)
+
 ${c.bold('EXAMPLES')}
   ${c.dim('# Zero-config (uses defineVideoConfig from component)')}
   ${c.highlight('pellicule')}
@@ -84,6 +108,12 @@ ${c.bold('EXAMPLES')}
   ${c.dim('# Render only frames 100-200 (for faster iteration)')}
   ${c.highlight('pellicule')} Video.vue -r 100:200
 
+  ${c.dim('# Use with Nuxt (auto-detects, connects to localhost:3000)')}
+  ${c.highlight('pellicule')} InvoiceDemo
+
+  ${c.dim('# Force Rsbuild bundler')}
+  ${c.highlight('pellicule')} Video.vue --bundler rsbuild
+
 ${c.bold('DURATION HELPER')}
   frames = seconds * fps
   ${c.dim('3 seconds at 30fps  = 90 frames')}
@@ -125,6 +155,11 @@ async function main() {
       height: { type: 'string', short: 'h' },
       range: { type: 'string', short: 'r' },
       audio: { type: 'string', short: 'a' },
+      'server-url': { type: 'string' },
+      bundler: { type: 'string' },
+      config: { type: 'string' },
+      'videos-dir': { type: 'string' },
+      'out-dir': { type: 'string' },
       help: { type: 'boolean' },
       version: { type: 'boolean' }
     }
@@ -141,21 +176,37 @@ async function main() {
     process.exit(0)
   }
 
-  // Default to Video.vue if no input provided
-  const input = positionals[0] || 'Video.vue'
+  // ── Auto-detection ────────────────────────────────────────────────
+  const detected = detectProject()
+  const pkgConfig = readPelliculeConfig()
+
+  // Resolution: CLI flags > package.json "pellicule" key > auto-detected
+  const bundler = values.bundler || pkgConfig.bundler || detected.bundler
+  const configFile = values.config ? resolve(values.config) : detected.configFile
+  const videosDir = values['videos-dir'] ? resolve(values['videos-dir']) : pkgConfig.videosDir || detected.videosDir
+  const outDir = values['out-dir'] ? resolve(values['out-dir']) : pkgConfig.outDir || null
+  const serverUrl = values['server-url'] || pkgConfig.serverUrl || detected.defaultServerUrl || null
+  const projectType = detected.projectType
+
+  // Validate bundler flag
+  if (values.bundler && !['vite', 'rsbuild'].includes(values.bundler)) {
+    fail(`Unknown bundler: ${values.bundler}`, 'Supported bundlers: vite, rsbuild')
+  }
 
-  // Try to resolve the input file, auto-appending .vue if needed
-  let inputPath = resolve(input)
+  // ── Input file resolution ─────────────────────────────────────────
+  const input = positionals[0] || 'Video.vue'
+  const result = resolveInputFile(input, videosDir)
 
-  if (!existsSync(inputPath) && !input.endsWith('.vue')) {
-    const withVue = resolve(input + '.vue')
-    if (existsSync(withVue)) {
-      inputPath = withVue
-    }
+  if (result.error) {
+    const searchedPaths = result.searched.map(p => `  - ${p}`).join('\n')
+    fail(result.error, `Looked in:\n${searchedPaths}`)
   }
 
-  if (!existsSync(inputPath)) fail(`File not found: ${input}`)
-  if (extname(inputPath) !== '.vue') fail(`Input must be a .vue file, got: ${extname(inputPath) || '(no extension)'}`)
+  const inputPath = result.resolved
+
+  if (extname(inputPath) !== '.vue') {
+    fail(`Input must be a .vue file, got: ${extname(inputPath) || '(no extension)'}`)
+  }
 
   // Extract config from component (if defineVideoConfig is used)
   const componentConfig = extractVideoConfig(inputPath)
@@ -185,7 +236,16 @@ async function main() {
   const durationInFrames = resolvedConfig.durationInFrames
   const width = resolvedConfig.width
   const height = resolvedConfig.height
-  const output = values.output || './output.mp4'
+  let output
+  if (values.output) {
+    output = values.output
+  } else if (outDir) {
+    // Use component name as filename when outDir is configured
+    const componentName = basename(inputPath, '.vue')
+    output = join(outDir, `${componentName}.mp4`)
+  } else {
+    output = './output.mp4'
+  }
   const outputPath = resolve(output)
 
   // Parse optional range (start:end format)
@@ -222,6 +282,23 @@ async function main() {
   if (componentConfig) {
     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) {
+    console.log(`  ${c.bold('Server')}     ${c.info(serverUrl)} ${c.dim('(BYOS)')}`)
+  }
+
   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)`)}`)
@@ -239,6 +316,15 @@ async function main() {
   const clearLine = '\x1b[2K'  // Clear entire line
   const cursorToStart = '\r'   // Move cursor to start of line
 
+  // For Nuxt and Quasar projects, construct the /pellicule render page URL.
+  // - Nuxt: pellicule/nuxt module injects the page
+  // - Quasar: pellicule/quasar Vite plugin serves the page
+  let finalServerUrl = serverUrl
+  if ((projectType === 'nuxt' || projectType === 'quasar') && serverUrl) {
+    const componentName = basename(inputPath, '.vue')
+    finalServerUrl = `${serverUrl.replace(/\/$/, '')}/pellicule?component=${encodeURIComponent(componentName)}`
+  }
+
   try {
     // Render with progress callback
     await renderToMp4({
@@ -252,6 +338,10 @@ async function main() {
       output: outputPath,
       audio: audioPath,
       silent: true,
+      serverUrl: finalServerUrl,
+      bundler,
+      configFile,
+      projectType,
       onProgress: ({ frame, total, fps: currentFps }) => {
         // Clear line and print progress (stays on same line)
         process.stdout.write(clearLine + cursorToStart + formatProgress(frame, total, currentFps || fps))
@@ -280,6 +370,12 @@ async function main() {
       console.error()
     }
 
+    if (error.message.includes('Rsbuild')) {
+      console.error(c.warn('  Hint: Install @rsbuild/core and @rsbuild/plugin-vue'))
+      console.error(c.dim('  npm install -D @rsbuild/core @rsbuild/plugin-vue'))
+      console.error()
+    }
+
     process.exit(1)
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pellicule",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "Deterministic video rendering with Vue",
   "type": "module",
   "main": "./src/index.js",
@@ -9,7 +9,9 @@
   },
   "exports": {
     ".": "./src/index.js",
-    "./render": "./src/render.js"
+    "./render": "./src/render.js",
+    "./nuxt": "./src/nuxt/module.js",
+    "./quasar": "./src/quasar/index.js"
   },
   "keywords": [
     "vue",
@@ -27,12 +29,28 @@
     "url": "https://github.com/sailscastshq/pellicule"
   },
   "dependencies": {
-    "@vue/compiler-sfc": "^3.0.0",
     "@vitejs/plugin-vue": "^5.0.0",
     "playwright": "^1.40.0",
     "vite": "^5.0.0"
   },
   "peerDependencies": {
+    "@nuxt/kit": "^3.0.0",
+    "@rsbuild/core": "^1.0.0",
+    "@rsbuild/plugin-vue": "^1.0.0",
     "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@rsbuild/core": {
+      "optional": true
+    },
+    "@rsbuild/plugin-vue": {
+      "optional": true
+    },
+    "@nuxt/kit": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nuxt/kit": "^4.3.0"
   }
 }

package/src/bundler/entry.js

@@ -0,0 +1,126 @@
+/**
+ * Bundler-agnostic entry file generation.
+ *
+ * Both the Vite adapter and the Rsbuild adapter produce the same
+ * index.html + entry.js scaffold to mount the user's Vue component.
+ * This module owns that template so changes propagate everywhere.
+ */
+
+import { writeFile, mkdir, rm } from 'fs/promises'
+import { join, basename } from 'path'
+
+/**
+ * Generate the entry HTML that wraps the video at the given dimensions.
+ *
+ * @param {object} options
+ * @param {number} options.width
+ * @param {number} options.height
+ * @returns {string}
+ */
+export function generateHtml({ width = 1920, height = 1080 }) {
+  return `<!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>`
+}
+
+/**
+ * Generate the entry JS that mounts the Vue component with
+ * Pellicule's frame/config injection.
+ *
+ * @param {object} options
+ * @param {string} options.componentPath - Relative path from the temp dir to the .vue file
+ * @param {number} options.width
+ * @param {number} options.height
+ * @returns {string}
+ */
+export function generateEntryJs({ componentPath, width = 1920, height = 1080 }) {
+  return `
+import { createApp, ref, provide, h, nextTick } from 'vue'
+import VideoComponent from '${componentPath}'
+
+// 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
+}
+`
+}
+
+/**
+ * Write the temp scaffold (.pellicule/ folder with index.html + entry.js).
+ *
+ * @param {object} options
+ * @param {string} options.inputPath - Absolute path to the .vue file
+ * @param {number} options.width
+ * @param {number} options.height
+ * @returns {Promise<{ tempDir: string, cleanup: () => Promise<void> }>}
+ */
+export async function writeTempEntry({ inputPath, width = 1920, height = 1080 }) {
+  const inputDir = join(inputPath, '..')
+  const inputFile = basename(inputPath)
+  const tempDir = join(inputDir, '.pellicule')
+
+  await mkdir(tempDir, { recursive: true })
+
+  const html = generateHtml({ width, height })
+  const js = generateEntryJs({
+    componentPath: `../${inputFile}`,
+    width,
+    height
+  })
+
+  await writeFile(join(tempDir, 'index.html'), html)
+  await writeFile(join(tempDir, 'entry.js'), js)
+
+  const cleanup = async () => {
+    await rm(tempDir, { recursive: true, force: true })
+  }
+
+  return { tempDir, cleanup }
+}

package/src/bundler/rsbuild.js

@@ -0,0 +1,177 @@
+/**
+ * Rsbuild bundler adapter for Pellicule.
+ *
+ * Handles two scenarios:
+ *   1. Standalone Rsbuild projects (rsbuild.config.js / rsbuild.config.ts)
+ *   2. Boring Stack apps (config/shipwright.js → reads the `build` key)
+ *
+ * This module is lazy-loaded. @rsbuild/core is an optional peer dependency.
+ */
+
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { createRequire } from 'module'
+import { pelliculeMacroRsbuildPlugin } from '../macros/define-video-config.js'
+import { writeTempEntry } from './entry.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pelliculeSrc = resolve(__dirname, '..')
+
+/**
+ * Load the user's Rsbuild config from a config file.
+ *
+ * For Shipwright configs, reads config/shipwright.js and
+ * extracts the `build` key (standard Rsbuild config).
+ *
+ * @param {string} configFile - Absolute path to the config file
+ * @param {'rsbuild'|'shipwright'} projectType
+ * @returns {Promise<object>} Rsbuild config object
+ */
+async function loadUserConfig(configFile, projectType) {
+  if (projectType === 'shipwright') {
+    // Shipwright configs are CommonJS: module.exports.shipwright = { build: { ... } }
+    const require = createRequire(import.meta.url)
+    const mod = require(configFile)
+    return mod?.shipwright?.build || {}
+  }
+
+  // Standalone rsbuild.config.js — use Rsbuild's own config loader
+  const { loadConfig } = await import('@rsbuild/core')
+  const { content } = await loadConfig({ cwd: dirname(configFile) })
+  return content || {}
+}
+
+/**
+ * Creates an Rsbuild dev server for rendering a video component.
+ *
+ * @param {object} options
+ * @param {string} options.input - Absolute path to the .vue file
+ * @param {number} options.width - Video width
+ * @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
+ * @returns {Promise<{ server: object, url: string, cleanup: function, tempDir: string }>}
+ */
+export async function createVideoServer(options) {
+  const {
+    input,
+    width = 1920,
+    height = 1080,
+    configFile = null,
+    projectType = 'rsbuild'
+  } = options
+
+  // Resolve Rsbuild from the user's project (not from pellicule's location).
+  // This is necessary because pellicule may be symlinked, and ESM import()
+  // resolves relative to the file's physical location, not the project root.
+  const projectRequire = createRequire(resolve(process.cwd(), 'package.json'))
+
+  let createRsbuild, mergeRsbuildConfig
+  try {
+    const rsbuildCorePath = projectRequire.resolve('@rsbuild/core')
+    const rsbuildCore = await import(rsbuildCorePath)
+    createRsbuild = rsbuildCore.createRsbuild
+    mergeRsbuildConfig = rsbuildCore.mergeRsbuildConfig
+  } catch {
+    throw new Error(
+      'Rsbuild is required but not installed.\n' +
+      'Install it with: npm install -D @rsbuild/core @rsbuild/plugin-vue\n' +
+      'Or use --bundler vite to use the Vite adapter instead.'
+    )
+  }
+
+  const inputPath = resolve(input)
+
+  // Write the shared entry scaffold (.pellicule/index.html + entry.js)
+  const { tempDir, cleanup: cleanupTemp } = await writeTempEntry({
+    inputPath,
+    width,
+    height
+  })
+
+  // Load @rsbuild/plugin-vue (also resolved from user's project)
+  let pluginVue
+  try {
+    const pluginVuePath = projectRequire.resolve('@rsbuild/plugin-vue')
+    const mod = await import(pluginVuePath)
+    pluginVue = mod.pluginVue
+  } catch {
+    throw new Error(
+      '@rsbuild/plugin-vue is required for Rsbuild projects.\n' +
+      'Install it with: npm install -D @rsbuild/plugin-vue'
+    )
+  }
+
+  // Build resolve.alias — always alias 'pellicule' to the local source.
+  // Also alias 'vue' to the project's Vue to avoid duplicate Vue runtimes.
+  // Without this, pellicule's source files (physically located in the pellicule
+  // repo) would resolve 'vue' from their own node_modules, while the project's
+  // entry code resolves 'vue' from the project's node_modules — two different
+  // Vue instances means provide/inject breaks silently.
+  // For Shipwright projects, also add the conventional ~ and @ aliases
+  // that sails-hook-shipwright normally injects at runtime.
+  const aliases = {
+    'pellicule': pelliculeSrc,
+    'vue': projectRequire.resolve('vue')
+  }
+
+  if (projectType === 'shipwright') {
+    const cwd = process.cwd()
+    aliases['@'] = resolve(cwd, 'assets', 'js')
+    aliases['~'] = resolve(cwd, 'assets')
+  }
+
+  // Pellicule's required Rsbuild config
+  // logLevel: 'error' suppresses Rsbuild's "start build started..." and
+  // "ready built in X s" messages. Pellicule has its own progress display.
+  // Note: rsbuild.logger is NOT exposed on the createRsbuild() return object,
+  // so logger.override() doesn't work. logLevel is the config-level equivalent.
+  const pelliculeConfig = {
+    source: {
+      entry: {
+        index: resolve(tempDir, 'entry.js')
+      }
+    },
+    resolve: {
+      alias: aliases
+    },
+    html: {
+      template: resolve(tempDir, 'index.html')
+    },
+    plugins: [pelliculeMacroRsbuildPlugin(), pluginVue()],
+    server: {
+      strictPort: false,
+      printUrls: false
+    },
+    dev: {
+      writeToDisk: false
+    },
+    logLevel: 'error'
+  }
+
+  let finalConfig = pelliculeConfig
+
+  // If the user has a config file, load and merge it
+  if (configFile) {
+    const userConfig = await loadUserConfig(configFile, projectType)
+
+    if (userConfig && Object.keys(userConfig).length > 0) {
+      // User config is the base, Pellicule config merges on top
+      finalConfig = mergeRsbuildConfig(userConfig, pelliculeConfig)
+    }
+  }
+
+  const rsbuild = await createRsbuild({ rsbuildConfig: finalConfig })
+
+  const devServer = await rsbuild.createDevServer()
+  const { port } = await devServer.listen()
+
+  const url = `http://localhost:${port}`
+
+  const cleanup = async () => {
+    await devServer.close()
+    await cleanupTemp()
+  }
+
+  return { server: devServer, url, cleanup, tempDir }
+}