shapy-render 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemant Rao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# shapy-render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Export [Shapy](https://github.com/hemant-rao/shapy-bg) generative backgrounds to
+MP4, WebM, or a PNG sequence. Rendering is deterministic: Shapy captures each
+frame with `seek()` at a fixed timeline position, so the same seed and options
+produce the same clip.
+
+> **Sponsored by [Odio Book](https://odiobook.com)** — the all-in-one AI video &
+> audio studio: AI video editing, auto subtitles, scene detection, voice
+> generation and text-to-speech, all in the browser. Odio Book funds the time
+> that goes into this project. **[Try it free →](https://odiobook.com)**
+
+## Install
+
+```bash
+npm install shapy-bg shapy-render
+npx playwright install chromium
+```
+
+`shapy-render` uses Playwright for frame capture. MP4 output also needs a
+system `ffmpeg` with `libx264`. Non-alpha WebM works with the ffmpeg that
+Playwright installs; PNG sequences need no ffmpeg. Alpha WebM needs a full
+ffmpeg with PNG decoding; the Playwright build does not include a PNG decoder.
+
+## CLI
+
+```bash
+npx shapy-render --seed reel-01 --duration 8 --output reel.mp4
+```
+
+A 9:16 clip with platform safe zones and a poster:
+
+```bash
+npx shapy-render \
+  --seed reel-01 \
+  --palette ocean \
+  --width 1080 --height 1920 \
+  --duration 8 --fps 30 \
+  --loop 8 \
+  --safe-zones tiktok \
+  --output reel.mp4 \
+  --poster reel-poster.png
+```
+
+Common options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--output` | `shapy-render.mp4` | Output file, or directory for PNG frames. |
+| `--format` | inferred | `mp4`, `webm`, or `png`. |
+| `--width` / `--height` | `1080` / `1920` | Capture size in CSS pixels. |
+| `--fps` | `30` | Frames per second. |
+| `--duration` | `8` | Clip length in seconds. |
+| `--dpr` | `1` | Device pixel ratio. |
+| `--alpha` | off | Transparent background. WebM/PNG only. |
+| `--poster` | none | Also write a `.png`, `.jpg`, or `.jpeg` still. |
+| `--poster-time` | `0` | Timeline position for the poster. |
+| `--crf` | `20` | Quality, 0–51. Lower is better. |
+| `--loop` | none | Seamless loop period passed to Shapy. |
+| `--ffmpeg` | auto | Use a specific ffmpeg executable. |
+| `--keep-frames` | off | Keep captured image frames. |
+
+For a clean loop, keep `--duration` an exact multiple of `--loop` (for example
+`--loop 8 --duration 8`). `seek()` wraps at the loop period, so a duration that
+is not a multiple can jump mid-clip.
+
+Shapy options are passed straight through:
+
+```bash
+npx shapy-render \
+  --seed deck-01 \
+  --palette plum \
+  --shape-set custom \
+  --shapes circle,ring,emoji-4 \
+  --layout rows \
+  --align center \
+  --motion calm \
+  --safe-zones reels \
+  --output deck.webm
+```
+
+Use `--option key=value` for anything not listed, or `--options` with a JSON
+object:
+
+```bash
+npx shapy-render \
+  --options '{"seed":"json-seed","palette":"forest","text":"Shape your story."}' \
+  --output hero.mp4
+```
+
+Run `npx shapy-render --help` for the complete flag list.
+
+## Library
+
+```js
+import { render } from 'shapy-render';
+
+const result = await render({
+  output: 'reel.webm',
+  width: 1080,
+  height: 1920,
+  duration: 8,
+  fps: 30,
+  loop: 8,
+  options: {
+    seed: 'reel-01',
+    palette: 'ocean',
+    safeZones: 'tiktok'
+  },
+  onProgress({ frame, total }) {
+    console.log(`${frame}/${total}`);
+  }
+});
+
+console.log(result.seed, result.output);
+```
+
+`render()` returns:
+
+```js
+{
+  output,      // absolute output path
+  format,      // 'mp4' | 'webm' | 'png'
+  seed,        // the seed used, including an auto-generated one
+  engineVersion, // SHAPY_ENGINE_VERSION used for the capture
+  width,       // output pixels (width × dpr)
+  height,      // output pixels (height × dpr)
+  fps,
+  duration,    // actual duration in seconds
+  frames,      // captured frame count
+  poster,
+  ffmpeg,
+  framesDir    // when keepFrames is true
+}
+```
+
+## Alpha
+
+- **WebM VP9** supports alpha with `--alpha`. Alpha encoding needs a full ffmpeg
+  with a PNG decoder; Playwright's bundled ffmpeg does not include one.
+- **PNG sequences** support alpha with `--alpha` and `--format png`.
+- **MP4 does not support alpha.** `shapy-render` rejects the combination instead
+  of silently producing black frames.
+
+When `--alpha` is set, the background is forced to `transparent`. Poster images
+must be PNG in alpha mode.
+
+## PNG sequences
+
+`--format png` treats `--output` as a directory:
+
+```bash
+npx shapy-render --format png --output frames --duration 4
+```
+
+Frames are written as `frames/frame-000001.png`, `frame-000002.png`, and so on.
+Encode them separately if you need a different codec or container.
+
+## MP4 and ffmpeg
+
+MP4 encoding requires an ffmpeg binary with `libx264`:
+
+```bash
+ffmpeg -version
+ffmpeg -hide_banner -encoders | grep libx264
+```
+
+If ffmpeg is not on `PATH`, pass `--ffmpeg C:\path\to\ffmpeg.exe` or set
+`SHAPY_FFMPEG`. WebM needs `libvpx-vp9`; the ffmpeg bundled with Playwright
+includes it, so non-alpha WebM usually works without a system install. Alpha
+WebM additionally needs PNG decoding, which the bundled build does not provide.
+
+## Determinism
+
+The renderer:
+
+1. loads Shapy with `live="off"`,
+2. fixes the viewport, device pixel ratio, and color profile,
+3. waits for fonts and images,
+4. calls `seek(t)` for each frame, and
+5. captures a screenshot after the frame has painted (PNG, or JPEG when the
+   available ffmpeg build has no PNG decoder).
+
+Use a fixed seed, viewport, DPR, and engine version for reproducible output.
+Rasterization, emoji artwork, and font availability can still differ between
+operating systems. See
+[Seed stability](https://github.com/hemant-rao/shapy-bg/blob/main/docs/SEED_STABILITY.md).
+
+## Requirements
+
+- Node.js 20.19 or newer
+- `shapy-bg` 1.0 or newer
+- Playwright Chromium
+- ffmpeg with `libx264` for MP4
+
+## Security
+
+Report vulnerabilities privately through the
+[security policy](https://github.com/hemant-rao/shapy-bg/blob/main/SECURITY.md).
+Do not open a public issue for a security problem.
+
+## License
+
+MIT © [Hemant Rao](https://github.com/hemant-rao). Sponsored by
+[Odio Book](https://odiobook.com). Support the project through
+[GitHub Sponsors](https://github.com/sponsors/hemant-rao).

package/bin/shapy-render.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { render } from '../src/index.js';
+
+const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const HELP = `shapy-render ${packageJson.version}
+
+Export a Shapy background to MP4, WebM, or a PNG sequence.
+
+Usage:
+  shapy-render --output reel.mp4 [options]
+  shapy-render --format png --output frames [options]
+
+Output:
+  --output <path>       File for video, directory for PNG frames.
+  --format <format>     mp4, webm, or png. Inferred from --output.
+  --width <px>          Capture width. Default: 1080.
+  --height <px>         Capture height. Default: 1920.
+  --fps <number>        Frames per second. Default: 30.
+  --duration <seconds>  Clip length. Default: 8.
+  --dpr <number>        Device pixel ratio. Default: 1.
+  --alpha               Transparent background. WebM/PNG only.
+  --poster <path>       Also write a still (.png, .jpg, .jpeg).
+  --poster-time <sec>   Poster timeline position. Default: 0.
+  --crf <number>        Quality (0-51, lower is better). Default: 20.
+  --loop <seconds>      Seamless loop period passed to Shapy.
+  --ffmpeg <path>       Use a specific ffmpeg executable.
+  --keep-frames         Keep captured image frames after encoding.
+
+Shapy:
+  --seed <string>       Seed. A fresh seed is generated when omitted.
+  --palette <name>      midnight, sandstone, bauhaus, forest, plum,
+                        ocean, clay, or mono.
+  --shape-set <name>    all, geometry, lines, organic, emoji, stickers,
+                        or custom.
+  --shapes <list>       Comma-separated keys for shape-set="custom".
+  --layout <name>       auto, scatter, grid, rows, columns, center, edges.
+  --align <name>        random, left, center, right, top, middle, bottom.
+  --size-mode <name>    mixed, same, subtle, dramatic, small, medium, large.
+  --motion <name>       mixed, chaos, flow, bounce, drift, spin, pulse,
+                        wobble, orbit, calm.
+  --direction <name>    random, lr, rl, tb, bt, dr, dl, ur, ul, alternate.
+  --density <number>    20-100.
+  --scale <number>      60-140.
+  --speed <number>      50-200.
+  --move <number>       30-200.
+  --background <color>  Background color.
+  --custom-colors <list> Comma-separated palette overrides.
+  --safe-zones <list>   tiktok, reels, shorts, story, or a JSON array.
+  --safe-area           Keep shapes behind the text overlay clear.
+  --option key=value    Any other Shapy option. Repeatable.
+  --options <json>      JSON object of Shapy options. Merged last.
+  --help                Show this help.
+  --version             Print the version.
+`;
+
+function fail(message) {
+  console.error(`shapy-render: ${message}`);
+  console.error('Run shapy-render --help for usage.');
+  process.exit(1);
+}
+
+function parseValue(value) {
+  const text = String(value).trim();
+  if (text === 'true') return true;
+  if (text === 'false') return false;
+  if (text === 'null') return null;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  if ((text.startsWith('{') && text.endsWith('}')) || (text.startsWith('[') && text.endsWith(']'))) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+const VALUE_FLAGS = new Set([
+  'output', 'format', 'width', 'height', 'fps', 'duration', 'dpr',
+  'poster', 'poster-time', 'crf', 'loop', 'ffmpeg',
+  'seed', 'palette', 'shape-set', 'shapes', 'layout', 'align', 'size-mode',
+  'motion', 'direction', 'density', 'scale', 'speed', 'move', 'background',
+  'custom-colors', 'safe-zones', 'option', 'options'
+]);
+
+const BOOLEAN_FLAGS = new Set(['alpha', 'keep-frames', 'safe-area', 'help', 'version']);
+
+const args = process.argv.slice(2);
+const flags = {};
+const extraOptions = {};
+
+for (let index = 0; index < args.length; index += 1) {
+  const argument = args[index];
+  if (!argument.startsWith('--')) fail(`unexpected argument: ${argument}`);
+
+  const equals = argument.indexOf('=');
+  const name = argument.slice(2, equals === -1 ? undefined : equals);
+  let value = equals === -1 ? undefined : argument.slice(equals + 1);
+
+  if (BOOLEAN_FLAGS.has(name)) {
+    if (value !== undefined) fail(`--${name} does not take a value`);
+    flags[name] = true;
+    continue;
+  }
+  if (!VALUE_FLAGS.has(name)) fail(`unknown option: --${name}`);
+
+  if (value === undefined) {
+    index += 1;
+    value = args[index];
+    if (value === undefined) fail(`--${name} needs a value`);
+  }
+
+  if (name === 'option') {
+    const split = value.indexOf('=');
+    if (split < 1) fail('--option expects key=value');
+    extraOptions[value.slice(0, split)] = parseValue(value.slice(split + 1));
+  } else if (name === 'options') {
+    let parsed;
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      fail('--options expects a JSON object');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      fail('--options expects a JSON object');
+    }
+    Object.assign(extraOptions, parsed);
+  } else {
+    flags[name] = value;
+  }
+}
+
+if (flags.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (flags.version) {
+  console.log(packageJson.version);
+  process.exit(0);
+}
+
+const format = flags.format ? String(flags.format).toLowerCase() : '';
+let output = flags.output;
+if (!output) {
+  output = format === 'png' ? 'shapy-render-frames' : `shapy-render.${format || 'mp4'}`;
+}
+
+const options = { ...extraOptions };
+for (const key of [
+  'seed', 'palette', 'shape-set', 'shapes', 'layout', 'align', 'size-mode',
+  'motion', 'direction', 'density', 'scale', 'speed', 'move', 'background',
+  'custom-colors', 'safe-zones'
+]) {
+  if (flags[key] !== undefined) options[key] = parseValue(flags[key]);
+}
+if (flags['safe-area']) options.safeArea = true;
+
+let lastProgress = -1;
+const onProgress = (progress) => {
+  if (progress.phase === 'frames' && progress.total) {
+    const percent = Math.floor((progress.frame / progress.total) * 10) * 10;
+    if (percent !== lastProgress) {
+      lastProgress = percent;
+      process.stderr.write(`Captured ${progress.frame}/${progress.total} frames (${percent}%)\n`);
+    }
+  } else if (progress.phase === 'encode') {
+    process.stderr.write(`Encoding ${progress.message}...\n`);
+  } else if (progress.phase === 'poster') {
+    process.stderr.write('Writing poster...\n');
+  }
+};
+
+try {
+  const result = await render({
+    output,
+    format: format || undefined,
+    width: flags.width,
+    height: flags.height,
+    fps: flags.fps,
+    duration: flags.duration,
+    dpr: flags.dpr,
+    alpha: Boolean(flags.alpha),
+    poster: flags.poster,
+    posterTime: flags['poster-time'],
+    crf: flags.crf,
+    loop: flags.loop,
+    ffmpeg: flags.ffmpeg,
+    keepFrames: Boolean(flags['keep-frames']),
+    options,
+    onProgress
+  });
+
+  console.log(`Rendered ${result.frames} frames at ${result.width}x${result.height}, ${result.fps} fps (${result.duration.toFixed(2)}s)`);
+  console.log(`Seed: ${result.seed}`);
+  console.log(`Wrote ${result.output}`);
+  if (result.poster) console.log(`Poster: ${result.poster}`);
+  if (result.framesDir) console.log(`Frames: ${result.framesDir}`);
+  if (result.ffmpeg) console.log(`ffmpeg: ${result.ffmpeg}`);
+} catch (error) {
+  fail(error.message);
+}

package/index.d.ts

@@ -0,0 +1,65 @@
+import type { ShapyOptions } from 'shapy-bg';
+
+export type ShapyRenderFormat = 'mp4' | 'webm' | 'png';
+
+export interface ShapyRenderOptions {
+  /** Destination file for video, or directory for a PNG sequence. */
+  output: string;
+  /** Output format. Inferred from the output extension when omitted. */
+  format?: ShapyRenderFormat;
+  /** Capture width in CSS pixels. Defaults to 1080. */
+  width?: number;
+  /** Capture height in CSS pixels. Defaults to 1920. */
+  height?: number;
+  /** Frames per second. Defaults to 30. */
+  fps?: number;
+  /** Clip duration in seconds. Defaults to 8. */
+  duration?: number;
+  /** Device pixel ratio for the capture. Defaults to 1. */
+  dpr?: number;
+  /** Keep the background transparent. Not supported for MP4. */
+  alpha?: boolean;
+  /** Shapy element options passed through to setOptions(). */
+  options?: ShapyOptions;
+  /** Optional still frame path (.png, .jpg, or .jpeg). */
+  poster?: string;
+  /** Timeline position for the poster frame in seconds. Defaults to 0. */
+  posterTime?: number;
+  /** H.264 CRF for MP4 (0–51) or mapped VP9 quality for WebM. Defaults to 20. */
+  crf?: number;
+  /** Loop period passed to the element in seconds. */
+  loop?: number;
+  /** Use a specific ffmpeg executable. */
+  ffmpeg?: string;
+  /** Keep captured PNG frames after encoding. */
+  keepFrames?: boolean;
+  /** Progress callback for frame capture and encoding. */
+  onProgress?: (progress: ShapyRenderProgress) => void;
+}
+
+export interface ShapyRenderProgress {
+  phase: 'frames' | 'encode' | 'poster';
+  frame?: number;
+  total?: number;
+  time?: number;
+  message?: string;
+}
+
+export interface ShapyRenderResult {
+  output: string;
+  format: ShapyRenderFormat;
+  seed: string;
+  /** SHAPY_ENGINE_VERSION used for the capture. */
+  engineVersion: number;
+  width: number;
+  height: number;
+  fps: number;
+  duration: number;
+  frames: number;
+  poster?: string;
+  ffmpeg?: string;
+  framesDir?: string;
+}
+
+/** Render a Shapy background to MP4, WebM, or a PNG sequence. */
+export function render(options: ShapyRenderOptions): Promise<ShapyRenderResult>;

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "shapy-render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Export Shapy generative backgrounds to MP4, WebM, and PNG with Playwright.",
+  "author": {
+    "name": "Hemant Rao",
+    "url": "https://github.com/hemant-rao"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/hemant-rao"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hemant-rao/shapy-bg.git",
+    "directory": "packages/shapy-render"
+  },
+  "homepage": "https://github.com/hemant-rao/shapy-bg/tree/main/packages/shapy-render#readme",
+  "bugs": {
+    "url": "https://github.com/hemant-rao/shapy-bg/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "bin": {
+    "shapy-render": "./bin/shapy-render.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "bin",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "shapy-bg",
+    "video",
+    "export",
+    "mp4",
+    "webm",
+    "png",
+    "playwright",
+    "generative",
+    "background"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "playwright": "^1.65.0"
+  },
+  "peerDependencies": {
+    "shapy-bg": ">=1.0.0"
+  },
+  "license": "MIT"
+}

package/src/ffmpeg.js

@@ -0,0 +1,214 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createReadStream, existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const encoderCache = new Map();
+
+function binaryIn(directory, depth = 2) {
+  if (!existsSync(directory)) return '';
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const full = join(directory, entry.name);
+    if (entry.isFile()) {
+      const name = entry.name.toLowerCase();
+      if (name.startsWith('ffmpeg') && !name.endsWith('.dll') && !name.endsWith('.so')) {
+        return full;
+      }
+    } else if (entry.isDirectory() && depth > 0) {
+      const found = binaryIn(full, depth - 1);
+      if (found) return found;
+    }
+  }
+  return '';
+}
+
+function bundledCandidates(executablePath) {
+  if (!executablePath) return [];
+  // Playwright stores browsers as <browsers>/<browser-version>/<platform>/...
+  const root = dirname(dirname(dirname(executablePath)));
+  if (!existsSync(root)) return [];
+  const found = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith('ffmpeg-')) continue;
+    const binary = binaryIn(join(root, entry.name));
+    if (binary) found.push(binary);
+  }
+  return found;
+}
+
+function systemFfmpeg() {
+  const probe = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore', windowsHide: true });
+  return !probe.error && probe.status === 0 ? 'ffmpeg' : '';
+}
+
+export function ffmpegSupports(executable, encoder) {
+  let text = encoderCache.get(executable);
+  if (text === undefined) {
+    const probe = spawnSync(executable, ['-hide_banner', '-encoders'], {
+      encoding: 'utf8',
+      windowsHide: true
+    });
+    text = probe.status === 0 ? `${probe.stdout || ''}\n${probe.stderr || ''}` : '';
+    encoderCache.set(executable, text);
+  }
+  return new RegExp(`\\b${encoder}\\b`).test(text);
+}
+
+export function ffmpegSupportsDecoder(executable, decoder) {
+  const key = `decoders:${executable}`;
+  let text = encoderCache.get(key);
+  if (text === undefined) {
+    const probe = spawnSync(executable, ['-hide_banner', '-decoders'], {
+      encoding: 'utf8',
+      windowsHide: true
+    });
+    text = probe.status === 0 ? `${probe.stdout || ''}\n${probe.stderr || ''}` : '';
+    encoderCache.set(key, text);
+  }
+  return new RegExp(`\\b${decoder}\\b`).test(text);
+}
+
+/**
+ * Find an ffmpeg binary. MP4 requires libx264; WebM requires libvpx-vp9.
+ * An explicit path or SHAPY_FFMPEG wins over discovery.
+ */
+export function findFfmpeg({ ffmpeg, executablePath, format }) {
+  const encoder = format === 'mp4' ? 'libx264' : 'libvpx-vp9';
+  const explicit = ffmpeg || process.env.SHAPY_FFMPEG || '';
+  if (explicit) {
+    if (!ffmpegSupports(explicit, encoder)) {
+      throw new Error(
+        `${explicit} does not provide ${encoder}. ` +
+          (format === 'mp4'
+            ? 'Install ffmpeg with libx264 or use --format webm.'
+            : 'Install ffmpeg with libvpx-vp9 or use --format png.')
+      );
+    }
+    return explicit;
+  }
+
+  const candidates = [];
+  const add = (path, source) => {
+    if (path && !candidates.some((item) => item.path === path)) {
+      candidates.push({ path, source });
+    }
+  };
+
+  add(systemFfmpeg(), 'system PATH');
+  for (const path of bundledCandidates(executablePath)) add(path, 'Playwright');
+
+  for (const candidate of candidates) {
+    if (ffmpegSupports(candidate.path, encoder)) return candidate.path;
+  }
+
+  const detail = candidates.length
+    ? candidates.map((item) => `${item.path} (${item.source})`).join(', ')
+    : 'none found';
+  throw new Error(
+    `No ffmpeg with ${encoder} found. Checked: ${detail}. ` +
+      (format === 'mp4'
+        ? 'Install ffmpeg with libx264, or use --format webm or --format png.'
+        : 'Install ffmpeg with libvpx-vp9, or use --format png.')
+  );
+}
+
+function oddDimensionFilter(width, height) {
+  if (width % 2 === 0 && height % 2 === 0) return [];
+  return ['-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2'];
+}
+
+function writeChunk(stream, chunk) {
+  return new Promise((resolveWrite, rejectWrite) => {
+    stream.write(chunk, (error) => (error ? rejectWrite(error) : resolveWrite()));
+  });
+}
+
+export async function encodeFrames({
+  ffmpeg,
+  format,
+  framesDir,
+  frameExt = 'png',
+  frames = 0,
+  output,
+  fps,
+  width,
+  height,
+  alpha = false,
+  crf = 20
+}) {
+  const args = [
+    '-y',
+    '-hide_banner',
+    '-loglevel', 'error',
+    '-f', 'image2pipe',
+    '-vcodec', frameExt === 'jpg' ? 'mjpeg' : 'png',
+    '-framerate', String(fps),
+    '-i', 'pipe:0'
+  ];
+
+  if (format === 'mp4') {
+    args.push(
+      '-c:v', 'libx264',
+      '-preset', 'medium',
+      '-crf', String(Math.min(51, Math.max(0, crf))),
+      ...oddDimensionFilter(width, height),
+      '-pix_fmt', 'yuv420p',
+      '-movflags', '+faststart',
+      output
+    );
+  } else if (format === 'webm') {
+    const vp9Crf = Math.round(Math.min(63, Math.max(0, (crf / 51) * 63)));
+    args.push(
+      '-c:v', 'libvpx-vp9',
+      '-b:v', '0',
+      '-crf', String(vp9Crf),
+      '-row-mt', '1',
+      ...(alpha ? ['-auto-alt-ref', '0'] : []),
+      ...oddDimensionFilter(width, height),
+      '-pix_fmt', alpha ? 'yuva420p' : 'yuv420p',
+      output
+    );
+  } else {
+    throw new Error(`encodeFrames does not encode ${format}`);
+  }
+
+  const child = spawn(ffmpeg, args, {
+    windowsHide: true,
+    stdio: ['pipe', 'ignore', 'pipe']
+  });
+  let stderr = '';
+  let stdinError = null;
+  child.stdin.on('error', (error) => {
+    stdinError = error;
+  });
+  child.stderr.on('data', (chunk) => {
+    stderr = `${stderr}${chunk}`.slice(-4000);
+  });
+
+  const closed = new Promise((resolveClose, rejectClose) => {
+    child.on('error', rejectClose);
+    child.on('close', (code) => {
+      if (code === 0) resolveClose();
+      else rejectClose(new Error(`ffmpeg exited with code ${code}\n${stderr.trim()}`));
+    });
+  });
+  closed.catch(() => {});
+
+  try {
+    for (let index = 1; index <= frames; index += 1) {
+      const file = join(framesDir, `frame-${String(index).padStart(6, '0')}.${frameExt}`);
+      for await (const chunk of createReadStream(file)) {
+        await writeChunk(child.stdin, chunk);
+      }
+    }
+    child.stdin.end();
+  } catch (error) {
+    child.kill();
+    const detail = await closed.catch((reason) => reason);
+    throw new Error(
+      `Failed to send frames to ffmpeg: ${error.message}` +
+        (detail && detail.message ? `\n${detail.message}` : '')
+    );
+  }
+
+  await closed;
+}

package/src/index.js

@@ -0,0 +1,389 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, extname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { encodeFrames, ffmpegSupportsDecoder, findFfmpeg } from './ffmpeg.js';
+import { posterType, positiveInteger, positiveNumber, resolveFormat } from './options.js';
+
+const require = createRequire(import.meta.url);
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+
+function resolveShapyDir() {
+  try {
+    return dirname(require.resolve('shapy-bg/package.json'));
+  } catch {
+    const fallback = fileURLToPath(new URL('../../shapy-bg', import.meta.url));
+    if (existsSync(join(fallback, 'package.json'))) return fallback;
+    throw new Error('shapy-render needs the shapy-bg package installed in the same project.');
+  }
+}
+
+function pageHtml() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+  html, body { margin: 0; width: 100%; height: 100%; overflow: hidden; background: transparent; }
+  shapy-background { position: fixed; inset: 0; display: block; width: 100%; height: 100%; }
+</style>
+</head>
+<body>
+<shapy-background aria-hidden="true"></shapy-background>
+<script type="module">
+  import { SHAPY_ENGINE_VERSION } from '/shapy-bg/src/index.js';
+  window.__SHAPY_ENGINE_VERSION__ = SHAPY_ENGINE_VERSION;
+  window.__SHAPY_RENDER_READY__ = false;
+  (async () => {
+    await customElements.whenDefined('shapy-background');
+    const element = document.querySelector('shapy-background');
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    window.__SHAPY_RENDER_ELEMENT__ = element;
+    window.__SHAPY_RENDER_READY__ = true;
+  })();
+</script>
+</body>
+</html>`;
+}
+
+function createStaticServer(shapyDir, html) {
+  return createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url || '/', 'http://127.0.0.1');
+      if (url.pathname === '/' || url.pathname === '/index.html') {
+        response.writeHead(200, { 'content-type': MIME['.html'], 'cache-control': 'no-store' });
+        response.end(html);
+        return;
+      }
+      if (!url.pathname.startsWith('/shapy-bg/')) {
+        response.writeHead(404);
+        response.end('Not found');
+        return;
+      }
+      const relative = decodeURIComponent(url.pathname.slice('/shapy-bg/'.length));
+      const target = resolve(shapyDir, relative);
+      if (target !== shapyDir && !target.startsWith(`${shapyDir}${sep}`)) {
+        response.writeHead(403);
+        response.end('Forbidden');
+        return;
+      }
+      const data = await readFile(target);
+      response.writeHead(200, {
+        'content-type': MIME[extname(target).toLowerCase()] || 'application/octet-stream',
+        'cache-control': 'no-store'
+      });
+      response.end(data);
+    } catch {
+      response.writeHead(404);
+      response.end('Not found');
+    }
+  });
+}
+
+function listen(server) {
+  return new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolveListen);
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolveClose) => {
+    if (!server) {
+      resolveClose();
+      return;
+    }
+    server.close(() => resolveClose());
+  });
+}
+
+async function applyOptions(page, options, alpha) {
+  return page.evaluate(async ({ next, transparent }) => {
+    const element = window.__SHAPY_RENDER_ELEMENT__;
+    element.setOptions({
+      ...next,
+      live: false,
+      paused: false,
+      time: null,
+      aspect: 'auto',
+      ...(transparent ? { background: 'transparent' } : {})
+    });
+
+    await document.fonts.ready;
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+    if (transparent && !element.shadowRoot.querySelector('#shapy-render-alpha')) {
+      const style = document.createElement('style');
+      style.id = 'shapy-render-alpha';
+      style.textContent = '.app { background: transparent !important; } .bg, .scrim, .grain { display: none !important; }';
+      element.shadowRoot.appendChild(style);
+    }
+
+    const images = [...element.shadowRoot.querySelectorAll('img')];
+    await Promise.all(images.map((image) => {
+      if (image.complete) return Promise.resolve();
+      return new Promise((resolve) => {
+        const done = () => resolve();
+        image.addEventListener('load', done, { once: true });
+        image.addEventListener('error', done, { once: true });
+        setTimeout(done, 5000);
+      });
+    }));
+
+    await element.seek(0);
+    const snapshot = element.getOptions();
+    return {
+      seed: snapshot.seed,
+      options: snapshot,
+      engineVersion: window.__SHAPY_ENGINE_VERSION__
+    };
+  }, { next: options, transparent: alpha });
+}
+
+async function capture(page, alpha, frameExt) {
+  const jpeg = frameExt === 'jpg';
+  return page.screenshot({
+    type: jpeg ? 'jpeg' : 'png',
+    ...(jpeg ? { quality: 95 } : {}),
+    omitBackground: alpha,
+    animations: 'allow',
+    caret: 'hide'
+  });
+}
+
+async function seek(page, seconds) {
+  await page.evaluate(async (time) => {
+    await window.__SHAPY_RENDER_ELEMENT__.seek(time);
+  }, seconds);
+}
+
+/**
+ * Render a Shapy background to MP4, WebM, or a PNG sequence.
+ */
+export async function render(input = {}) {
+  const {
+    output,
+    format: requestedFormat,
+    width: requestedWidth = 1080,
+    height: requestedHeight = 1920,
+    fps: requestedFps = 30,
+    duration: requestedDuration = 8,
+    dpr: requestedDpr = 1,
+    alpha = false,
+    options = {},
+    poster = '',
+    posterTime = 0,
+    crf = 20,
+    loop,
+    ffmpeg: requestedFfmpeg = '',
+    keepFrames = false,
+    onProgress
+  } = input;
+
+  if (!output || typeof output !== 'string') {
+    throw new Error('output is required');
+  }
+
+  const format = resolveFormat(requestedFormat, output);
+  const width = positiveInteger(requestedWidth, 1080, 'width', 16, 8192);
+  const height = positiveInteger(requestedHeight, 1920, 'height', 16, 8192);
+  const fps = positiveNumber(requestedFps, 30, 'fps', 1, 120);
+  const duration = positiveNumber(requestedDuration, 8, 'duration', 0.01, 3600);
+  const dpr = positiveNumber(requestedDpr, 1, 'dpr', 0.5, 4);
+  const quality = positiveNumber(crf, 20, 'crf', 0, 51);
+  const posterAt = positiveNumber(posterTime, 0, 'posterTime', 0, 86400);
+  const posterFormat = poster ? posterType(poster) : '';
+  const frameCount = Math.max(1, Math.round(duration * fps));
+
+  if (alpha && format === 'mp4') {
+    throw new Error('MP4 does not support alpha. Use --format webm or --format png.');
+  }
+  if (poster && alpha && posterFormat === 'jpeg') {
+    throw new Error('Alpha posters must be PNG.');
+  }
+  if (loop !== undefined && loop !== null) {
+    const loopValue = Number(loop);
+    if (!Number.isFinite(loopValue) || loopValue <= 0) {
+      throw new Error('loop must be a positive number of seconds');
+    }
+  }
+
+  let server;
+  let browser;
+  let framesDir = '';
+  let removeFrames = false;
+
+  try {
+    let chromium;
+    try {
+      ({ chromium } = await import('playwright'));
+    } catch {
+      throw new Error('shapy-render needs playwright. Install it with: npm install playwright');
+    }
+
+    const ffmpeg = format === 'mp4' || format === 'webm'
+      ? findFfmpeg({
+          ffmpeg: requestedFfmpeg,
+          executablePath: chromium.executablePath(),
+          format
+        })
+      : '';
+
+    let frameExt = 'png';
+    if (ffmpeg) {
+      if (alpha && !ffmpegSupportsDecoder(ffmpeg, 'png')) {
+        throw new Error(
+          'Alpha WebM needs ffmpeg with PNG decoding. Install a full ffmpeg or use --format png.'
+        );
+      }
+      if (!alpha && !ffmpegSupportsDecoder(ffmpeg, 'png')) {
+        if (!ffmpegSupportsDecoder(ffmpeg, 'mjpeg')) {
+          throw new Error('ffmpeg cannot decode PNG or JPEG input frames.');
+        }
+        frameExt = 'jpg';
+      }
+    }
+
+    const shapyDir = resolveShapyDir();
+    server = createStaticServer(shapyDir, pageHtml());
+    await listen(server);
+    const address = server.address();
+    const port = address && typeof address === 'object' ? address.port : 0;
+
+    try {
+      browser = await chromium.launch({
+        headless: true,
+        args: [
+          '--force-color-profile=srgb',
+          '--disable-lcd-text',
+          '--font-render-hinting=none',
+          '--hide-scrollbars'
+        ]
+      });
+    } catch (error) {
+      throw new Error(
+        `Could not launch Chromium. Run "npx playwright install chromium" and try again.\n${error.message}`
+      );
+    }
+
+    const context = await browser.newContext({
+      viewport: { width, height },
+      deviceScaleFactor: dpr,
+      colorScheme: 'dark',
+      reducedMotion: 'no-preference'
+    });
+    const page = await context.newPage();
+    const pageErrors = [];
+    page.on('pageerror', (error) => pageErrors.push(error.message));
+    page.on('console', (message) => {
+      if (message.type() === 'error') pageErrors.push(message.text());
+    });
+
+    await page.goto(`http://127.0.0.1:${port}/`, { waitUntil: 'load' });
+    try {
+      await page.waitForFunction(() => window.__SHAPY_RENDER_READY__ === true, undefined, { timeout: 20000 });
+    } catch {
+      throw new Error(
+        `Shapy did not initialize in the browser.${pageErrors.length ? `\n${pageErrors.join('\n')}` : ''}`
+      );
+    }
+
+    const applied = await applyOptions(
+      page,
+      loop === undefined || loop === null ? options : { ...options, loop },
+      alpha
+    );
+    const actualWidth = Math.round(width * dpr);
+    const actualHeight = Math.round(height * dpr);
+
+    if (format === 'png') {
+      framesDir = resolve(output);
+      await mkdir(framesDir, { recursive: true });
+    } else {
+      framesDir = await mkdtemp(join(tmpdir(), 'shapy-render-'));
+      removeFrames = true;
+    }
+
+    for (let index = 0; index < frameCount; index += 1) {
+      const time = index / fps;
+      await seek(page, time);
+      const buffer = await capture(page, alpha, frameExt);
+      const file = join(framesDir, `frame-${String(index + 1).padStart(6, '0')}.${frameExt}`);
+      await writeFile(file, buffer);
+      if (onProgress) {
+        onProgress({ phase: 'frames', frame: index + 1, total: frameCount, time });
+      }
+    }
+
+    if (poster) {
+      await seek(page, posterAt);
+      await mkdir(dirname(resolve(poster)), { recursive: true });
+      const buffer = await page.screenshot({
+        type: posterFormat,
+        omitBackground: alpha,
+        animations: 'allow',
+        caret: 'hide',
+        ...(posterFormat === 'jpeg' ? { quality: 92 } : {})
+      });
+      await writeFile(resolve(poster), buffer);
+      if (onProgress) onProgress({ phase: 'poster', message: poster });
+    }
+
+    if (format !== 'png') {
+      await mkdir(dirname(resolve(output)), { recursive: true });
+      if (onProgress) onProgress({ phase: 'encode', message: format });
+      await encodeFrames({
+        ffmpeg,
+        format,
+        framesDir,
+        frameExt,
+        frames: frameCount,
+        output: resolve(output),
+        fps,
+        width: actualWidth,
+        height: actualHeight,
+        alpha,
+        crf: quality
+      });
+    }
+
+    return {
+      output: resolve(output),
+      format,
+      seed: applied.seed,
+      engineVersion: applied.engineVersion,
+      width: actualWidth,
+      height: actualHeight,
+      fps,
+      duration: frameCount / fps,
+      frames: frameCount,
+      poster: poster ? resolve(poster) : undefined,
+      ffmpeg: ffmpeg || undefined,
+      framesDir: keepFrames ? framesDir : undefined
+    };
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    await closeServer(server);
+    if (removeFrames && framesDir && !keepFrames) {
+      await rm(framesDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}

package/src/options.js

@@ -0,0 +1,36 @@
+import { extname } from 'node:path';
+
+export const RENDER_FORMATS = new Set(['mp4', 'webm', 'png']);
+
+export function positiveInteger(value, fallback, name, min, max) {
+  const number = value === undefined || value === null || value === '' ? fallback : Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) {
+    throw new Error(`${name} must be an integer from ${min} to ${max}`);
+  }
+  return number;
+}
+
+export function positiveNumber(value, fallback, name, min, max) {
+  const number = value === undefined || value === null || value === '' ? fallback : Number(value);
+  if (!Number.isFinite(number) || number < min || number > max) {
+    throw new Error(`${name} must be a number from ${min} to ${max}`);
+  }
+  return number;
+}
+
+export function resolveFormat(format, output) {
+  if (format) {
+    const token = String(format).toLowerCase();
+    if (!RENDER_FORMATS.has(token)) throw new Error('format must be mp4, webm, or png');
+    return token;
+  }
+  const extension = extname(output).slice(1).toLowerCase();
+  return RENDER_FORMATS.has(extension) ? extension : 'mp4';
+}
+
+export function posterType(poster) {
+  const extension = extname(poster).toLowerCase();
+  if (extension === '.jpg' || extension === '.jpeg') return 'jpeg';
+  if (extension === '.png') return 'png';
+  throw new Error('poster must end in .png, .jpg, or .jpeg');
+}