@vosjs/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vosso
+
+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

@@ -0,0 +1,63 @@
+# @vosjs/cli
+
+[![npm](https://img.shields.io/npm/v/@vosjs/cli)](https://www.npmjs.com/package/@vosjs/cli)
+[![license](https://img.shields.io/npm/l/@vosjs/cli)](../../LICENSE)
+
+Command line for [vos](https://vos.so/engine), the open visual operating system — render deterministic videos and stills from vos configs, headlessly, from your terminal, CI, or an AI agent.
+
+```bash
+pnpm add -D @vosjs/cli
+npx vos render animation.json out.webm
+```
+
+## Commands
+
+```bash
+vos render <config.json|url> [out]   # config → video (WebM/MP4)
+vos still  <config.json|url> [out]   # config → single frame (WebP)
+vos info   <config.json|url>         # inspect a config
+vos preview <config.json|url>        # serve a local playback page
+vos versions                         # installed @vosjs/* versions
+```
+
+`vos render` accepts `--width` / `--height` / `--fps` / `--duration` / `--format webm|mp4`; `vos still` accepts `--time` / `--width` / `--height`. Configs can be local files or URLs, and API `{ "config": … }` envelopes are unwrapped automatically. Old config versions are migrated before rendering.
+
+Rendering runs the same deterministic pipeline everywhere: the config is compiled with `@vosjs/core`, wrapped in the engine's capture template, and encoded frame-by-frame (WebCodecs) in headless Chromium. Same input, same video — locally, in CI, or on a server.
+
+## Requirements
+
+A Chromium-family browser. The CLI uses your installed Google Chrome automatically; otherwise run `npx playwright install chromium` once, or point `VOS_BROWSER_PATH` at a Chrome/Chromium executable. Module dependencies (three, gsap) load from the CDN inside the render page, so rendering needs network access.
+
+## For scripts and agents
+
+- Results on stdout, logs on stderr.
+- `--json` switches stdout to NDJSON events, ending with `{"event":"done",…}`:
+
+```bash
+vos render animation.json --json
+{"event":"phase","phase":"compile"}
+{"event":"phase","phase":"render"}
+{"event":"done","out":"animation.webm","bytes":812345,"width":1920,"height":1080,"fps":30,"duration":5,"format":"webm"}
+```
+
+- Exit codes: `0` ok · `1` error · `2` usage · `3` no browser available.
+- No auth, no account — rendering is local.
+
+The same core is available programmatically:
+
+```ts
+import { launchBrowser, loadVosConfig, renderVideo } from '@vosjs/cli'
+
+const browser = await launchBrowser()
+const { config } = await loadVosConfig('animation.json')
+const { bytes } = await renderVideo(browser, {
+  config,
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  duration: 5,
+  format: 'webm',
+})
+```
+
+Part of [vos](https://github.com/vosjs/vos), the open visual operating system. MIT.

package/dist/chunk-A5AN2K5L.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+// src/args.ts
+var UsageError = class extends Error {
+};
+function parseArgs(argv, booleanFlags) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        continue;
+      }
+      const name = arg.slice(2);
+      if (booleanFlags.has(name)) {
+        flags[name] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next === void 0 || next.startsWith("--")) {
+        throw new UsageError(`--${name} expects a value`);
+      }
+      flags[name] = next;
+      i++;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return { positionals, flags };
+}
+function numFlag(flags, name, fallback) {
+  const v = flags[name];
+  if (v === void 0) return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n)) throw new UsageError(`--${name} expects a number, got "${String(v)}"`);
+  return n;
+}
+
+// src/loadConfig.ts
+import { readFile } from "fs/promises";
+import { CURRENT_CONFIG_VERSION, migrateConfig, vosConfigJsonSchema } from "@vosjs/core";
+async function loadVosConfig(source) {
+  const warnings = [];
+  let raw;
+  if (/^https?:\/\//.test(source)) {
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`fetch ${source} \u2192 ${res.status}`);
+    raw = await res.text();
+  } else {
+    raw = await readFile(source, "utf8");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new UsageError(`${source} is not valid JSON: ${e.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new UsageError(`${source} does not contain a JSON object`);
+  }
+  let obj = parsed;
+  if (typeof obj.config === "object" && obj.config !== null && !("createTimeline" in obj)) {
+    obj = obj.config;
+    warnings.push("unwrapped { config } envelope");
+  }
+  const version = obj.version;
+  const migrated = migrateConfig(obj);
+  if (version !== CURRENT_CONFIG_VERSION) {
+    warnings.push(`migrated config v${String(version ?? 1)} \u2192 v${CURRENT_CONFIG_VERSION}`);
+  }
+  const check = vosConfigJsonSchema.safeParse(migrated);
+  if (!check.success) {
+    const issues = check.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new UsageError(`invalid vos config:
+${issues}`);
+  }
+  return { config: migrated, warnings };
+}
+function configDuration(config) {
+  const d = config.duration;
+  return typeof d === "number" && Number.isFinite(d) && d > 0 ? d : void 0;
+}
+
+// src/browser.ts
+import { chromium } from "playwright";
+var BrowserUnavailableError = class extends Error {
+  constructor(cause) {
+    super(
+      `Could not launch a Chromium-family browser (${cause}).
+Fixes, in order of preference:
+  1. Install Google Chrome (used automatically), or
+  2. npx playwright install chromium, or
+  3. Set VOS_BROWSER_PATH to a Chrome/Chromium executable.`
+    );
+  }
+};
+async function launchBrowser() {
+  const explicit = process.env.VOS_BROWSER_PATH;
+  if (explicit) {
+    return chromium.launch({ executablePath: explicit }).catch((e) => {
+      throw new BrowserUnavailableError(`VOS_BROWSER_PATH failed: ${e.message}`);
+    });
+  }
+  try {
+    return await chromium.launch({ channel: "chrome" });
+  } catch {
+    try {
+      return await chromium.launch();
+    } catch (e) {
+      throw new BrowserUnavailableError(e.message.split("\n")[0] ?? "unknown");
+    }
+  }
+}
+
+// src/render.ts
+import { compileVosConfig } from "@vosjs/core";
+import { generateRenderTemplate } from "@vosjs/core/runtime";
+import { elementsBundleCode } from "@vosjs/elements/bundle";
+import { tweenRuntimeCode } from "@vosjs/tween/bundle";
+var RENDER_ORIGIN = "https://vos-cli.render";
+function compile(config) {
+  return compileVosConfig(config, { tweenEngine: "vos" });
+}
+async function runCapturePage(browser, html, opts) {
+  const context = await browser.newContext({
+    viewport: { width: opts.width, height: opts.height }
+  });
+  const page = await context.newPage();
+  const errors = [];
+  page.on("console", (m) => {
+    if (m.type() === "error") errors.push(m.text());
+  });
+  try {
+    await page.route(
+      `${RENDER_ORIGIN}/**`,
+      (route) => route.fulfill({ status: 200, contentType: "text/html", body: html })
+    );
+    await page.goto(`${RENDER_ORIGIN}/render`, { waitUntil: "domcontentloaded" });
+    const start = Date.now();
+    for (; ; ) {
+      const done = await page.evaluate("window.__renderComplete ?? null");
+      if (done) return done;
+      if (Date.now() - start > opts.timeoutMs) {
+        return {
+          success: false,
+          error: `render timed out after ${Math.round(opts.timeoutMs / 1e3)}s${errors.length ? ` (page errors: ${errors.slice(0, 3).join(" | ")})` : ""}`
+        };
+      }
+      await new Promise((r) => setTimeout(r, 400));
+    }
+  } finally {
+    await context.close();
+  }
+}
+function decodeDataUrl(dataUrl) {
+  const m = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl);
+  if (!m) throw new Error("capture page returned an unexpected payload");
+  return { bytes: Uint8Array.from(Buffer.from(m[2], "base64")), mimeType: m[1] };
+}
+async function renderVideo(browser, opts) {
+  opts.onPhase?.("compile");
+  const code = compile(opts.config);
+  const html = generateRenderTemplate(code, {
+    mode: "capture-video",
+    capture: {
+      width: opts.width,
+      height: opts.height,
+      duration: opts.duration,
+      fps: opts.fps,
+      format: opts.format
+    },
+    elementsBundleCode,
+    tweenEngine: "vos",
+    tweenBundleCode: tweenRuntimeCode
+  });
+  opts.onPhase?.("render");
+  const timeoutMs = 9e4 + opts.duration * opts.fps * 400;
+  const done = await runCapturePage(browser, html, {
+    width: opts.width,
+    height: opts.height,
+    timeoutMs
+  });
+  if (!done.success || !done.data) throw new Error(done.error ?? "render failed");
+  return decodeDataUrl(done.data);
+}
+async function renderStill(browser, opts) {
+  opts.onPhase?.("compile");
+  const code = compile(opts.config);
+  const html = generateRenderTemplate(code, {
+    mode: "capture-thumbnail",
+    capture: {
+      width: opts.width,
+      height: opts.height,
+      duration: Math.max(1, opts.time + 1),
+      fps: 30,
+      thumbnailTime: opts.time
+    },
+    elementsBundleCode,
+    tweenEngine: "vos",
+    tweenBundleCode: tweenRuntimeCode
+  });
+  opts.onPhase?.("render");
+  const done = await runCapturePage(browser, html, {
+    width: opts.width,
+    height: opts.height,
+    timeoutMs: 12e4
+  });
+  if (!done.success || !done.data) throw new Error(done.error ?? "still render failed");
+  return decodeDataUrl(done.data);
+}
+function previewPages(config) {
+  const code = compile(config);
+  const playerHtml = generateRenderTemplate(code, {
+    mode: "playback",
+    elementsBundleCode,
+    tweenEngine: "vos",
+    tweenBundleCode: tweenRuntimeCode
+  });
+  const codeJson = JSON.stringify(code).replace(/<\//g, "<\\/");
+  const hostHtml = `<!doctype html><html><head><meta charset="utf-8"><title>vos preview</title>
+<style>
+  html,body{margin:0;height:100%;background:#000;overflow:hidden}
+  iframe{position:absolute;inset:0;width:100%;height:100%;border:0}
+  #cover{position:fixed;inset:0;cursor:pointer}
+  #hud{position:fixed;left:12px;bottom:10px;color:#fff;opacity:.75;font:12px/1.4 ui-monospace,monospace;
+       background:rgba(0,0,0,.45);padding:4px 8px;border-radius:6px;pointer-events:none}
+</style></head><body>
+<iframe id="p" src="/player" allow="autoplay"></iframe>
+<div id="cover"></div>
+<div id="hud">loading\u2026</div>
+<script>
+  const code = ${codeJson}
+  const frame = document.getElementById('p')
+  const hud = document.getElementById('hud')
+  let ready = false
+  let playing = true
+  const post = (msg) => frame.contentWindow && frame.contentWindow.postMessage(msg, '*')
+  const load = () => post({ type: 'LOAD', code, autoplay: true })
+  window.addEventListener('message', (e) => {
+    const msg = e.data || {}
+    if (msg.type === 'BRIDGE_READY') load()
+    if (msg.type === 'READY') { ready = true; hud.textContent = '0.0 / ' + msg.duration.toFixed(1) + 's \u2014 click to pause' }
+    if (msg.type === 'UPDATE') hud.textContent = msg.time.toFixed(1) + ' / ' + msg.duration.toFixed(1) + 's \u2014 click to ' + (playing ? 'pause' : 'play')
+    if (msg.type === 'ERROR') hud.textContent = 'error: ' + msg.error
+  })
+  // Belt and braces: if BRIDGE_READY raced the host, retry LOAD until READY.
+  let tries = 0
+  const iv = setInterval(() => {
+    if (ready || tries++ > 20) return clearInterval(iv)
+    load()
+  }, 400)
+  // The iframe swallows clicks \u2014 capture them on an overlay above it.
+  document.getElementById('cover').addEventListener('click', () => {
+    if (!ready) return
+    playing = !playing
+    post({ type: playing ? 'PLAY' : 'PAUSE' })
+    hud.textContent = hud.textContent.replace(/click to (pause|play)/, 'click to ' + (playing ? 'pause' : 'play'))
+  })
+</script></body></html>`;
+  return { hostHtml, playerHtml };
+}
+
+export {
+  UsageError,
+  parseArgs,
+  numFlag,
+  loadVosConfig,
+  configDuration,
+  BrowserUnavailableError,
+  launchBrowser,
+  renderVideo,
+  renderStill,
+  previewPages
+};
+//# sourceMappingURL=chunk-A5AN2K5L.js.map

package/dist/chunk-A5AN2K5L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/args.ts","../src/loadConfig.ts","../src/browser.ts","../src/render.ts"],"sourcesContent":["/**\n * Minimal argv parser — positionals + `--flag value` / `--flag=value` /\n * boolean flags. Deliberately tiny: the CLI has a small, stable surface and\n * agents benefit from predictable, dependency-free parsing.\n */\nexport interface ParsedArgs {\n  positionals: string[]\n  flags: Record<string, string | true>\n}\n\nexport class UsageError extends Error {}\n\nexport function parseArgs(argv: string[], booleanFlags: ReadonlySet<string>): ParsedArgs {\n  const positionals: string[] = []\n  const flags: Record<string, string | true> = {}\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i]\n    if (arg === '--') {\n      positionals.push(...argv.slice(i + 1))\n      break\n    }\n    if (arg.startsWith('--')) {\n      const eq = arg.indexOf('=')\n      if (eq !== -1) {\n        flags[arg.slice(2, eq)] = arg.slice(eq + 1)\n        continue\n      }\n      const name = arg.slice(2)\n      if (booleanFlags.has(name)) {\n        flags[name] = true\n        continue\n      }\n      const next = argv[i + 1]\n      if (next === undefined || next.startsWith('--')) {\n        throw new UsageError(`--${name} expects a value`)\n      }\n      flags[name] = next\n      i++\n      continue\n    }\n    positionals.push(arg)\n  }\n  return { positionals, flags }\n}\n\nexport function numFlag(\n  flags: ParsedArgs['flags'],\n  name: string,\n  fallback: number,\n): number {\n  const v = flags[name]\n  if (v === undefined) return fallback\n  const n = Number(v)\n  if (!Number.isFinite(n)) throw new UsageError(`--${name} expects a number, got \"${String(v)}\"`)\n  return n\n}\n","import { readFile } from 'node:fs/promises'\nimport { CURRENT_CONFIG_VERSION, migrateConfig, vosConfigJsonSchema } from '@vosjs/core'\nimport { UsageError } from './args'\n\nexport interface LoadedConfig {\n  config: Record<string, unknown>\n  warnings: string[]\n}\n\n/**\n * Load a VosConfigJson from a file path or http(s) URL, unwrap API `{ config }`\n * envelopes, migrate old versions, and validate against the schema.\n */\nexport async function loadVosConfig(source: string): Promise<LoadedConfig> {\n  const warnings: string[] = []\n  let raw: string\n  if (/^https?:\\/\\//.test(source)) {\n    const res = await fetch(source)\n    if (!res.ok) throw new Error(`fetch ${source} → ${res.status}`)\n    raw = await res.text()\n  } else {\n    raw = await readFile(source, 'utf8')\n  }\n\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch (e) {\n    throw new UsageError(`${source} is not valid JSON: ${(e as Error).message}`)\n  }\n  if (typeof parsed !== 'object' || parsed === null) {\n    throw new UsageError(`${source} does not contain a JSON object`)\n  }\n\n  // API endpoints wrap the config: { config: {...} }.\n  let obj = parsed as Record<string, unknown>\n  if (\n    typeof obj.config === 'object' &&\n    obj.config !== null &&\n    !('createTimeline' in obj)\n  ) {\n    obj = obj.config as Record<string, unknown>\n    warnings.push('unwrapped { config } envelope')\n  }\n\n  const version = obj.version\n  const migrated = migrateConfig(obj)\n  if (version !== CURRENT_CONFIG_VERSION) {\n    warnings.push(`migrated config v${String(version ?? 1)} → v${CURRENT_CONFIG_VERSION}`)\n  }\n\n  const check = vosConfigJsonSchema.safeParse(migrated)\n  if (!check.success) {\n    const issues = check.error.issues\n      .slice(0, 5)\n      .map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`)\n      .join('\\n')\n    throw new UsageError(`invalid vos config:\\n${issues}`)\n  }\n\n  return { config: migrated, warnings }\n}\n\n/** Best-effort duration from the config (seconds). */\nexport function configDuration(config: Record<string, unknown>): number | undefined {\n  const d = config.duration\n  return typeof d === 'number' && Number.isFinite(d) && d > 0 ? d : undefined\n}\n","import { chromium } from 'playwright'\nimport type { Browser } from 'playwright'\n\nexport class BrowserUnavailableError extends Error {\n  constructor(cause: string) {\n    super(\n      `Could not launch a Chromium-family browser (${cause}).\\n` +\n        `Fixes, in order of preference:\\n` +\n        `  1. Install Google Chrome (used automatically), or\\n` +\n        `  2. npx playwright install chromium, or\\n` +\n        `  3. Set VOS_BROWSER_PATH to a Chrome/Chromium executable.`,\n    )\n  }\n}\n\n/**\n * Launch headless Chromium: explicit VOS_BROWSER_PATH → system Chrome\n * (no download needed) → Playwright's bundled Chromium.\n */\nexport async function launchBrowser(): Promise<Browser> {\n  const explicit = process.env.VOS_BROWSER_PATH\n  if (explicit) {\n    return chromium.launch({ executablePath: explicit }).catch((e) => {\n      throw new BrowserUnavailableError(`VOS_BROWSER_PATH failed: ${(e as Error).message}`)\n    })\n  }\n  try {\n    return await chromium.launch({ channel: 'chrome' })\n  } catch {\n    try {\n      return await chromium.launch()\n    } catch (e) {\n      throw new BrowserUnavailableError((e as Error).message.split('\\n')[0] ?? 'unknown')\n    }\n  }\n}\n","import { compileVosConfig } from '@vosjs/core'\nimport { generateRenderTemplate } from '@vosjs/core/runtime'\nimport { elementsBundleCode } from '@vosjs/elements/bundle'\nimport { tweenRuntimeCode } from '@vosjs/tween/bundle'\nimport type { Browser, Page } from 'playwright'\n\n/** Fake secure origin the render page is served from (WebCodecs needs one). */\nconst RENDER_ORIGIN = 'https://vos-cli.render'\n\nexport interface RenderCommonOptions {\n  config: Record<string, unknown>\n  width: number\n  height: number\n  /** Phase callback for progress reporting. */\n  onPhase?: (phase: string) => void\n}\n\nexport interface RenderVideoOptions extends RenderCommonOptions {\n  fps: number\n  /** Output duration in seconds. */\n  duration: number\n  format: 'webm' | 'mp4'\n}\n\nexport interface RenderStillOptions extends RenderCommonOptions {\n  /** Seek time for the captured frame, seconds. */\n  time: number\n}\n\nexport interface RenderResult {\n  bytes: Uint8Array\n  mimeType: string\n}\n\ninterface RenderComplete {\n  success: boolean\n  data?: string\n  error?: string\n}\n\nfunction compile(config: Record<string, unknown>): string {\n  return compileVosConfig(config as never, { tweenEngine: 'vos' })\n}\n\nasync function runCapturePage(\n  browser: Browser,\n  html: string,\n  opts: { width: number; height: number; timeoutMs: number },\n): Promise<RenderComplete> {\n  const context = await browser.newContext({\n    viewport: { width: opts.width, height: opts.height },\n  })\n  const page: Page = await context.newPage()\n  const errors: string[] = []\n  page.on('console', (m) => {\n    if (m.type() === 'error') errors.push(m.text())\n  })\n  try {\n    await page.route(`${RENDER_ORIGIN}/**`, (route) =>\n      route.fulfill({ status: 200, contentType: 'text/html', body: html }),\n    )\n    await page.goto(`${RENDER_ORIGIN}/render`, { waitUntil: 'domcontentloaded' })\n    const start = Date.now()\n    for (;;) {\n      const done = (await page.evaluate('window.__renderComplete ?? null')) as RenderComplete | null\n      if (done) return done\n      if (Date.now() - start > opts.timeoutMs) {\n        return {\n          success: false,\n          error: `render timed out after ${Math.round(opts.timeoutMs / 1000)}s${\n            errors.length ? ` (page errors: ${errors.slice(0, 3).join(' | ')})` : ''\n          }`,\n        }\n      }\n      await new Promise((r) => setTimeout(r, 400))\n    }\n  } finally {\n    await context.close()\n  }\n}\n\nfunction decodeDataUrl(dataUrl: string): RenderResult {\n  const m = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl)\n  if (!m) throw new Error('capture page returned an unexpected payload')\n  return { bytes: Uint8Array.from(Buffer.from(m[2], 'base64')), mimeType: m[1] }\n}\n\n/** Render a vos config to a video (WebM/MP4) in a headless browser. */\nexport async function renderVideo(\n  browser: Browser,\n  opts: RenderVideoOptions,\n): Promise<RenderResult> {\n  opts.onPhase?.('compile')\n  const code = compile(opts.config)\n  const html = generateRenderTemplate(code, {\n    mode: 'capture-video',\n    capture: {\n      width: opts.width,\n      height: opts.height,\n      duration: opts.duration,\n      fps: opts.fps,\n      format: opts.format,\n    },\n    elementsBundleCode,\n    tweenEngine: 'vos',\n    tweenBundleCode: tweenRuntimeCode,\n  })\n  opts.onPhase?.('render')\n  // Generous ceiling: startup + CDN module fetch + ~4× realtime per frame batch.\n  const timeoutMs = 90_000 + opts.duration * opts.fps * 400\n  const done = await runCapturePage(browser, html, {\n    width: opts.width,\n    height: opts.height,\n    timeoutMs,\n  })\n  if (!done.success || !done.data) throw new Error(done.error ?? 'render failed')\n  return decodeDataUrl(done.data)\n}\n\n/** Render a single frame of a vos config to an image in a headless browser. */\nexport async function renderStill(\n  browser: Browser,\n  opts: RenderStillOptions,\n): Promise<RenderResult> {\n  opts.onPhase?.('compile')\n  const code = compile(opts.config)\n  const html = generateRenderTemplate(code, {\n    mode: 'capture-thumbnail',\n    capture: {\n      width: opts.width,\n      height: opts.height,\n      duration: Math.max(1, opts.time + 1),\n      fps: 30,\n      thumbnailTime: opts.time,\n    },\n    elementsBundleCode,\n    tweenEngine: 'vos',\n    tweenBundleCode: tweenRuntimeCode,\n  })\n  opts.onPhase?.('render')\n  const done = await runCapturePage(browser, html, {\n    width: opts.width,\n    height: opts.height,\n    timeoutMs: 120_000,\n  })\n  if (!done.success || !done.data) throw new Error(done.error ?? 'still render failed')\n  return decodeDataUrl(done.data)\n}\n\nexport interface PreviewPages {\n  /** Host page: iframes the player and drives it over the bridge. */\n  hostHtml: string\n  /** The engine's playback-mode player (waits for a LOAD postMessage). */\n  playerHtml: string\n}\n\n/**\n * Pages for `vos preview`. The playback template is the iframe HALF of the\n * player bridge — it renders nothing until a host posts `LOAD`, so the CLI\n * serves a minimal host page that sends `LOAD { code, autoplay }` and shows\n * a transport line (time / duration, click to play-pause).\n */\nexport function previewPages(config: Record<string, unknown>): PreviewPages {\n  const code = compile(config)\n  const playerHtml = generateRenderTemplate(code, {\n    mode: 'playback',\n    elementsBundleCode,\n    tweenEngine: 'vos',\n    tweenBundleCode: tweenRuntimeCode,\n  })\n  const codeJson = JSON.stringify(code).replace(/<\\//g, '<\\\\/')\n  const hostHtml = `<!doctype html><html><head><meta charset=\"utf-8\"><title>vos preview</title>\n<style>\n  html,body{margin:0;height:100%;background:#000;overflow:hidden}\n  iframe{position:absolute;inset:0;width:100%;height:100%;border:0}\n  #cover{position:fixed;inset:0;cursor:pointer}\n  #hud{position:fixed;left:12px;bottom:10px;color:#fff;opacity:.75;font:12px/1.4 ui-monospace,monospace;\n       background:rgba(0,0,0,.45);padding:4px 8px;border-radius:6px;pointer-events:none}\n</style></head><body>\n<iframe id=\"p\" src=\"/player\" allow=\"autoplay\"></iframe>\n<div id=\"cover\"></div>\n<div id=\"hud\">loading…</div>\n<script>\n  const code = ${codeJson}\n  const frame = document.getElementById('p')\n  const hud = document.getElementById('hud')\n  let ready = false\n  let playing = true\n  const post = (msg) => frame.contentWindow && frame.contentWindow.postMessage(msg, '*')\n  const load = () => post({ type: 'LOAD', code, autoplay: true })\n  window.addEventListener('message', (e) => {\n    const msg = e.data || {}\n    if (msg.type === 'BRIDGE_READY') load()\n    if (msg.type === 'READY') { ready = true; hud.textContent = '0.0 / ' + msg.duration.toFixed(1) + 's — click to pause' }\n    if (msg.type === 'UPDATE') hud.textContent = msg.time.toFixed(1) + ' / ' + msg.duration.toFixed(1) + 's — click to ' + (playing ? 'pause' : 'play')\n    if (msg.type === 'ERROR') hud.textContent = 'error: ' + msg.error\n  })\n  // Belt and braces: if BRIDGE_READY raced the host, retry LOAD until READY.\n  let tries = 0\n  const iv = setInterval(() => {\n    if (ready || tries++ > 20) return clearInterval(iv)\n    load()\n  }, 400)\n  // The iframe swallows clicks — capture them on an overlay above it.\n  document.getElementById('cover').addEventListener('click', () => {\n    if (!ready) return\n    playing = !playing\n    post({ type: playing ? 'PLAY' : 'PAUSE' })\n    hud.textContent = hud.textContent.replace(/click to (pause|play)/, 'click to ' + (playing ? 'pause' : 'play'))\n  })\n</script></body></html>`\n  return { hostHtml, playerHtml }\n}\n"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+import {
+  BrowserUnavailableError,
+  UsageError,
+  configDuration,
+  launchBrowser,
+  loadVosConfig,
+  numFlag,
+  parseArgs,
+  previewPages,
+  renderStill,
+  renderVideo
+} from "./chunk-A5AN2K5L.js";
+
+// src/cli.ts
+import { writeFile } from "fs/promises";
+import { readFileSync } from "fs";
+import { basename, dirname, join } from "path";
+import { createServer } from "http";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+// src/output.ts
+var EXIT_OK = 0;
+var EXIT_ERROR = 1;
+var EXIT_USAGE = 2;
+var EXIT_NO_BROWSER = 3;
+function createReporter(json) {
+  return {
+    json,
+    log: (msg) => {
+      if (!json) process.stderr.write(`${msg}
+`);
+    },
+    event: (obj) => {
+      if (json) process.stdout.write(`${JSON.stringify(obj)}
+`);
+    },
+    done: (obj, humanLine) => {
+      if (json) process.stdout.write(`${JSON.stringify({ event: "done", ...obj })}
+`);
+      else process.stdout.write(`${humanLine}
+`);
+    }
+  };
+}
+
+// src/cli.ts
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "version"]);
+var HELP = `vos \u2014 command line for the vos programmatic video engine (https://vos.so)
+
+Usage
+  vos render <config.json|url> [out] [--width 1920] [--height 1080] [--fps 30]
+                               [--duration <s>] [--format webm|mp4] [--json]
+  vos still  <config.json|url> [out.webp] [--time 0] [--width] [--height] [--json]
+  vos info   <config.json|url> [--json]
+  vos preview <config.json|url> [--port 0]
+  vos versions [--json]
+  vos voila <subcommand> \u2026     (product-video pipeline \u2014 separate install)
+
+Conventions
+  Results go to stdout; logs go to stderr. --json switches stdout to NDJSON
+  events ending with {"event":"done",\u2026}. Exit codes: 0 ok, 1 error, 2 usage,
+  3 no browser available.
+`;
+function outName(source, ext) {
+  const base = basename(source).replace(/\.[a-z0-9]+$/i, "") || "vos";
+  return `${base}.${ext}`;
+}
+async function cmdRender(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS);
+  const source = positionals[0];
+  if (!source) throw new UsageError("vos render <config.json|url> [out]");
+  const r = createReporter(flags.json === true);
+  const format = flags.format ?? "webm";
+  if (format !== "webm" && format !== "mp4") throw new UsageError("--format must be webm or mp4");
+  const { config, warnings } = await loadVosConfig(source);
+  for (const w of warnings) r.log(`note: ${w}`);
+  const duration = numFlag(flags, "duration", configDuration(config) ?? 5);
+  const width = numFlag(flags, "width", 1920);
+  const height = numFlag(flags, "height", 1080);
+  const fps = numFlag(flags, "fps", 30);
+  const out = positionals[1] ?? outName(source, format);
+  const browser = await launchBrowser();
+  try {
+    const result = await renderVideo(browser, {
+      config,
+      width,
+      height,
+      fps,
+      duration,
+      format,
+      onPhase: (phase) => {
+        r.log(`${phase}\u2026`);
+        r.event({ event: "phase", phase });
+      }
+    });
+    await writeFile(out, result.bytes);
+    r.done(
+      { out, bytes: result.bytes.length, width, height, fps, duration, format },
+      `Wrote ${out} (${(result.bytes.length / 1024).toFixed(0)} KB, ${width}x${height}@${fps}, ${duration}s)`
+    );
+    return EXIT_OK;
+  } finally {
+    await browser.close();
+  }
+}
+async function cmdStill(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS);
+  const source = positionals[0];
+  if (!source) throw new UsageError("vos still <config.json|url> [out.webp]");
+  const r = createReporter(flags.json === true);
+  const { config, warnings } = await loadVosConfig(source);
+  for (const w of warnings) r.log(`note: ${w}`);
+  const time = numFlag(flags, "time", 0);
+  const width = numFlag(flags, "width", 1280);
+  const height = numFlag(flags, "height", 720);
+  const out = positionals[1] ?? outName(source, "webp");
+  const browser = await launchBrowser();
+  try {
+    const result = await renderStill(browser, {
+      config,
+      width,
+      height,
+      time,
+      onPhase: (phase) => {
+        r.log(`${phase}\u2026`);
+        r.event({ event: "phase", phase });
+      }
+    });
+    await writeFile(out, result.bytes);
+    r.done(
+      { out, bytes: result.bytes.length, width, height, time, mimeType: result.mimeType },
+      `Wrote ${out} (${(result.bytes.length / 1024).toFixed(0)} KB, ${width}x${height} @ t=${time}s)`
+    );
+    return EXIT_OK;
+  } finally {
+    await browser.close();
+  }
+}
+async function cmdInfo(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS);
+  const source = positionals[0];
+  if (!source) throw new UsageError("vos info <config.json|url>");
+  const r = createReporter(flags.json === true);
+  const { config, warnings } = await loadVosConfig(source);
+  const elements = Array.isArray(config.elements) ? config.elements.length : 0;
+  const data = typeof config.data === "object" && config.data !== null ? Object.keys(config.data) : [];
+  const fns = ["setup", "createContent", "createTimeline", "onFrame"].filter(
+    (k) => typeof config[k] === "string"
+  );
+  const info = {
+    version: config.version,
+    duration: configDuration(config) ?? null,
+    camera: config.camera?.preset ?? null,
+    elements,
+    dataKeys: data,
+    functions: fns,
+    warnings
+  };
+  if (r.json) r.done(info, "");
+  else {
+    for (const w of warnings) r.log(`note: ${w}`);
+    process.stdout.write(
+      `version:   v${String(info.version)}
+duration:  ${info.duration === null ? "(none)" : `${info.duration}s`}
+camera:    ${String(info.camera ?? "(default)")}
+elements:  ${elements}
+data keys: ${data.length ? data.join(", ") : "(none)"}
+functions: ${fns.join(", ")}
+`
+    );
+  }
+  return EXIT_OK;
+}
+function packageVersion(name) {
+  const require2 = createRequire(import.meta.url);
+  try {
+    return require2(`${name}/package.json`).version;
+  } catch {
+  }
+  let entry = null;
+  try {
+    entry = fileURLToPath(import.meta.resolve(name));
+  } catch {
+    try {
+      entry = require2.resolve(name);
+    } catch {
+      return null;
+    }
+  }
+  let dir = dirname(entry);
+  for (let i = 0; i < 6; i++) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      if (pkg.name === name && pkg.version) return pkg.version;
+    } catch {
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+async function cmdVersions(argv) {
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS);
+  const r = createReporter(flags.json === true);
+  const versions = {};
+  try {
+    const own = JSON.parse(
+      readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")
+    );
+    versions["@vosjs/cli"] = own.version;
+  } catch {
+    versions["@vosjs/cli"] = "(unknown)";
+  }
+  for (const name of ["@vosjs/core", "@vosjs/elements", "@vosjs/tween", "playwright"]) {
+    versions[name] = packageVersion(name) ?? "(not found)";
+  }
+  if (r.json) r.done({ versions }, "");
+  else for (const [k, v] of Object.entries(versions)) process.stdout.write(`${k} ${v}
+`);
+  return EXIT_OK;
+}
+async function cmdPreview(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS);
+  const source = positionals[0];
+  if (!source) throw new UsageError("vos preview <config.json|url> [--port 0]");
+  const r = createReporter(false);
+  const { config, warnings } = await loadVosConfig(source);
+  for (const w of warnings) r.log(`note: ${w}`);
+  const { hostHtml, playerHtml } = previewPages(config);
+  const server = createServer((req, res) => {
+    const path = new URL(req.url ?? "/", "http://x").pathname;
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(path === "/player" ? playerHtml : hostHtml);
+  });
+  const port = numFlag(flags, "port", 0);
+  await new Promise((resolve) => server.listen(port, resolve));
+  const addr = server.address();
+  const url = `http://localhost:${typeof addr === "object" && addr ? addr.port : port}/`;
+  process.stdout.write(`${url}
+`);
+  r.log("Serving playback preview \u2014 Ctrl-C to stop.");
+  await new Promise(() => {
+  });
+  return EXIT_OK;
+}
+async function cmdVoila(argv) {
+  try {
+    const mod = await import("@vosso/voila-cli");
+    if (typeof mod.run === "function") return await mod.run(argv);
+    process.stderr.write("@vosso/voila-cli is installed but exposes no run() \u2014 update it.\n");
+    return EXIT_ERROR;
+  } catch {
+    process.stderr.write(
+      "The Voila product-video pipeline ships separately.\n  npm i -D @vosso/voila-cli\nthen re-run: vos voila \u2026\n"
+    );
+    return EXIT_ERROR;
+  }
+}
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    process.stdout.write(HELP);
+    return cmd ? EXIT_OK : EXIT_USAGE;
+  }
+  if (cmd === "--version") return cmdVersions(["--json"]);
+  switch (cmd) {
+    case "render":
+      return cmdRender(rest);
+    case "still":
+      return cmdStill(rest);
+    case "info":
+      return cmdInfo(rest);
+    case "versions":
+      return cmdVersions(rest);
+    case "preview":
+      return cmdPreview(rest);
+    case "voila":
+      return cmdVoila(rest);
+    default:
+      throw new UsageError(`unknown command "${cmd}" \u2014 run vos help`);
+  }
+}
+main().then((code) => process.exit(code)).catch((e) => {
+  if (e instanceof UsageError) {
+    process.stderr.write(`usage error: ${e.message}
+`);
+    process.exit(EXIT_USAGE);
+  }
+  if (e instanceof BrowserUnavailableError) {
+    process.stderr.write(`${e.message}
+`);
+    process.exit(EXIT_NO_BROWSER);
+  }
+  process.stderr.write(`error: ${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(EXIT_ERROR);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/output.ts"],"sourcesContent":["import { writeFile } from 'node:fs/promises'\nimport { readFileSync } from 'node:fs'\nimport { basename, dirname, join } from 'node:path'\nimport { createServer } from 'node:http'\nimport { createRequire } from 'node:module'\nimport { fileURLToPath } from 'node:url'\nimport { parseArgs, numFlag, UsageError } from './args'\nimport {\n  createReporter,\n  EXIT_ERROR,\n  EXIT_NO_BROWSER,\n  EXIT_OK,\n  EXIT_USAGE,\n} from './output'\nimport { loadVosConfig, configDuration } from './loadConfig'\nimport { launchBrowser, BrowserUnavailableError } from './browser'\nimport { renderVideo, renderStill, previewPages } from './render'\n\nconst BOOLEAN_FLAGS = new Set(['json', 'help', 'version'])\n\nconst HELP = `vos — command line for the vos programmatic video engine (https://vos.so)\n\nUsage\n  vos render <config.json|url> [out] [--width 1920] [--height 1080] [--fps 30]\n                               [--duration <s>] [--format webm|mp4] [--json]\n  vos still  <config.json|url> [out.webp] [--time 0] [--width] [--height] [--json]\n  vos info   <config.json|url> [--json]\n  vos preview <config.json|url> [--port 0]\n  vos versions [--json]\n  vos voila <subcommand> …     (product-video pipeline — separate install)\n\nConventions\n  Results go to stdout; logs go to stderr. --json switches stdout to NDJSON\n  events ending with {\"event\":\"done\",…}. Exit codes: 0 ok, 1 error, 2 usage,\n  3 no browser available.\n`\n\nfunction outName(source: string, ext: string): string {\n  const base = basename(source).replace(/\\.[a-z0-9]+$/i, '') || 'vos'\n  return `${base}.${ext}`\n}\n\nasync function cmdRender(argv: string[]): Promise<number> {\n  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS)\n  const source = positionals[0]\n  if (!source) throw new UsageError('vos render <config.json|url> [out]')\n  const r = createReporter(flags.json === true)\n  const format = (flags.format as string) ?? 'webm'\n  if (format !== 'webm' && format !== 'mp4') throw new UsageError('--format must be webm or mp4')\n\n  const { config, warnings } = await loadVosConfig(source)\n  for (const w of warnings) r.log(`note: ${w}`)\n  const duration = numFlag(flags, 'duration', configDuration(config) ?? 5)\n  const width = numFlag(flags, 'width', 1920)\n  const height = numFlag(flags, 'height', 1080)\n  const fps = numFlag(flags, 'fps', 30)\n  const out = positionals[1] ?? outName(source, format)\n\n  const browser = await launchBrowser()\n  try {\n    const result = await renderVideo(browser, {\n      config,\n      width,\n      height,\n      fps,\n      duration,\n      format,\n      onPhase: (phase) => {\n        r.log(`${phase}…`)\n        r.event({ event: 'phase', phase })\n      },\n    })\n    await writeFile(out, result.bytes)\n    r.done(\n      { out, bytes: result.bytes.length, width, height, fps, duration, format },\n      `Wrote ${out} (${(result.bytes.length / 1024).toFixed(0)} KB, ${width}x${height}@${fps}, ${duration}s)`,\n    )\n    return EXIT_OK\n  } finally {\n    await browser.close()\n  }\n}\n\nasync function cmdStill(argv: string[]): Promise<number> {\n  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS)\n  const source = positionals[0]\n  if (!source) throw new UsageError('vos still <config.json|url> [out.webp]')\n  const r = createReporter(flags.json === true)\n\n  const { config, warnings } = await loadVosConfig(source)\n  for (const w of warnings) r.log(`note: ${w}`)\n  const time = numFlag(flags, 'time', 0)\n  const width = numFlag(flags, 'width', 1280)\n  const height = numFlag(flags, 'height', 720)\n  const out = positionals[1] ?? outName(source, 'webp')\n\n  const browser = await launchBrowser()\n  try {\n    const result = await renderStill(browser, {\n      config,\n      width,\n      height,\n      time,\n      onPhase: (phase) => {\n        r.log(`${phase}…`)\n        r.event({ event: 'phase', phase })\n      },\n    })\n    await writeFile(out, result.bytes)\n    r.done(\n      { out, bytes: result.bytes.length, width, height, time, mimeType: result.mimeType },\n      `Wrote ${out} (${(result.bytes.length / 1024).toFixed(0)} KB, ${width}x${height} @ t=${time}s)`,\n    )\n    return EXIT_OK\n  } finally {\n    await browser.close()\n  }\n}\n\nasync function cmdInfo(argv: string[]): Promise<number> {\n  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS)\n  const source = positionals[0]\n  if (!source) throw new UsageError('vos info <config.json|url>')\n  const r = createReporter(flags.json === true)\n\n  const { config, warnings } = await loadVosConfig(source)\n  const elements = Array.isArray(config.elements) ? config.elements.length : 0\n  const data = typeof config.data === 'object' && config.data !== null ? Object.keys(config.data) : []\n  const fns = ['setup', 'createContent', 'createTimeline', 'onFrame'].filter(\n    (k) => typeof config[k] === 'string',\n  )\n  const info = {\n    version: config.version,\n    duration: configDuration(config) ?? null,\n    camera: (config.camera as Record<string, unknown> | undefined)?.preset ?? null,\n    elements,\n    dataKeys: data,\n    functions: fns,\n    warnings,\n  }\n  if (r.json) r.done(info, '')\n  else {\n    for (const w of warnings) r.log(`note: ${w}`)\n    process.stdout.write(\n      `version:   v${String(info.version)}\\n` +\n        `duration:  ${info.duration === null ? '(none)' : `${info.duration}s`}\\n` +\n        `camera:    ${String(info.camera ?? '(default)')}\\n` +\n        `elements:  ${elements}\\n` +\n        `data keys: ${data.length ? data.join(', ') : '(none)'}\\n` +\n        `functions: ${fns.join(', ')}\\n`,\n    )\n  }\n  return EXIT_OK\n}\n\nfunction packageVersion(name: string): string | null {\n  const require = createRequire(import.meta.url)\n  // Fast path — packages that export ./package.json (e.g. playwright).\n  try {\n    return (require(`${name}/package.json`) as { version: string }).version\n  } catch {\n    // Strict `exports` maps (the @vosjs packages) hide package.json — resolve\n    // the entry module instead and walk up to the owning package.json.\n  }\n  let entry: string | null = null\n  try {\n    entry = fileURLToPath(import.meta.resolve(name))\n  } catch {\n    try {\n      entry = require.resolve(name)\n    } catch {\n      return null\n    }\n  }\n  let dir = dirname(entry)\n  for (let i = 0; i < 6; i++) {\n    try {\n      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as {\n        name?: string\n        version?: string\n      }\n      if (pkg.name === name && pkg.version) return pkg.version\n    } catch {\n      // keep walking\n    }\n    const parent = dirname(dir)\n    if (parent === dir) return null\n    dir = parent\n  }\n  return null\n}\n\nasync function cmdVersions(argv: string[]): Promise<number> {\n  const { flags } = parseArgs(argv, BOOLEAN_FLAGS)\n  const r = createReporter(flags.json === true)\n  const versions: Record<string, string> = {}\n  // Own version: read relative to dist (self-require is blocked by `exports`).\n  try {\n    const own = JSON.parse(\n      readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),\n    ) as { version: string }\n    versions['@vosjs/cli'] = own.version\n  } catch {\n    versions['@vosjs/cli'] = '(unknown)'\n  }\n  for (const name of ['@vosjs/core', '@vosjs/elements', '@vosjs/tween', 'playwright']) {\n    versions[name] = packageVersion(name) ?? '(not found)'\n  }\n  if (r.json) r.done({ versions }, '')\n  else for (const [k, v] of Object.entries(versions)) process.stdout.write(`${k} ${v}\\n`)\n  return EXIT_OK\n}\n\nasync function cmdPreview(argv: string[]): Promise<number> {\n  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS)\n  const source = positionals[0]\n  if (!source) throw new UsageError('vos preview <config.json|url> [--port 0]')\n  const r = createReporter(false)\n  const { config, warnings } = await loadVosConfig(source)\n  for (const w of warnings) r.log(`note: ${w}`)\n  const { hostHtml, playerHtml } = previewPages(config)\n  const server = createServer((req, res) => {\n    const path = new URL(req.url ?? '/', 'http://x').pathname\n    res.writeHead(200, { 'content-type': 'text/html' })\n    res.end(path === '/player' ? playerHtml : hostHtml)\n  })\n  const port = numFlag(flags, 'port', 0)\n  await new Promise<void>((resolve) => server.listen(port, resolve))\n  const addr = server.address()\n  const url = `http://localhost:${typeof addr === 'object' && addr ? addr.port : port}/`\n  process.stdout.write(`${url}\\n`)\n  r.log('Serving playback preview — Ctrl-C to stop.')\n  await new Promise(() => {}) // keep alive until interrupted\n  return EXIT_OK\n}\n\nasync function cmdVoila(argv: string[]): Promise<number> {\n  try {\n    const mod = (await import('@vosso/voila-cli' as string)) as {\n      run?: (argv: string[]) => Promise<number>\n    }\n    if (typeof mod.run === 'function') return await mod.run(argv)\n    process.stderr.write('@vosso/voila-cli is installed but exposes no run() — update it.\\n')\n    return EXIT_ERROR\n  } catch {\n    process.stderr.write(\n      'The Voila product-video pipeline ships separately.\\n' +\n        '  npm i -D @vosso/voila-cli\\n' +\n        'then re-run: vos voila …\\n',\n    )\n    return EXIT_ERROR\n  }\n}\n\nasync function main(): Promise<number> {\n  const [cmd, ...rest] = process.argv.slice(2)\n  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {\n    process.stdout.write(HELP)\n    return cmd ? EXIT_OK : EXIT_USAGE\n  }\n  if (cmd === '--version') return cmdVersions(['--json'])\n  switch (cmd) {\n    case 'render':\n      return cmdRender(rest)\n    case 'still':\n      return cmdStill(rest)\n    case 'info':\n      return cmdInfo(rest)\n    case 'versions':\n      return cmdVersions(rest)\n    case 'preview':\n      return cmdPreview(rest)\n    case 'voila':\n      return cmdVoila(rest)\n    default:\n      throw new UsageError(`unknown command \"${cmd}\" — run vos help`)\n  }\n}\n\nmain()\n  .then((code) => process.exit(code))\n  .catch((e) => {\n    if (e instanceof UsageError) {\n      process.stderr.write(`usage error: ${e.message}\\n`)\n      process.exit(EXIT_USAGE)\n    }\n    if (e instanceof BrowserUnavailableError) {\n      process.stderr.write(`${e.message}\\n`)\n      process.exit(EXIT_NO_BROWSER)\n    }\n    process.stderr.write(`error: ${e instanceof Error ? e.message : String(e)}\\n`)\n    process.exit(EXIT_ERROR)\n  })\n","/**\n * Output conventions (agent-safe by construction):\n * - logs/progress → stderr (human readable)\n * - results → stdout; with --json, NDJSON events (`{\"event\":\"phase\"...}` then\n *   `{\"event\":\"done\"...}`) so scripts and agents never parse prose\n * - exit codes: 0 ok · 1 failure · 2 usage · 3 browser unavailable\n */\nexport const EXIT_OK = 0\nexport const EXIT_ERROR = 1\nexport const EXIT_USAGE = 2\nexport const EXIT_NO_BROWSER = 3\n\nexport interface Reporter {\n  json: boolean\n  /** Human log line (stderr; suppressed in --json mode). */\n  log: (msg: string) => void\n  /** Machine event (stdout NDJSON in --json mode; no-op otherwise). */\n  event: (obj: Record<string, unknown>) => void\n  /** Final result: NDJSON `done` event in --json mode, plain line otherwise. */\n  done: (obj: Record<string, unknown>, humanLine: string) => void\n}\n\nexport function createReporter(json: boolean): Reporter {\n  return {\n    json,\n    log: (msg) => {\n      if (!json) process.stderr.write(`${msg}\\n`)\n    },\n    event: (obj) => {\n      if (json) process.stdout.write(`${JSON.stringify(obj)}\\n`)\n    },\n    done: (obj, humanLine) => {\n      if (json) process.stdout.write(`${JSON.stringify({ event: 'done', ...obj })}\\n`)\n      else process.stdout.write(`${humanLine}\\n`)\n    },\n  }\n}\n"],"mappings":"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","names":["require"]}

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { Browser } from 'playwright';
+
+interface RenderCommonOptions {
+    config: Record<string, unknown>;
+    width: number;
+    height: number;
+    /** Phase callback for progress reporting. */
+    onPhase?: (phase: string) => void;
+}
+interface RenderVideoOptions extends RenderCommonOptions {
+    fps: number;
+    /** Output duration in seconds. */
+    duration: number;
+    format: 'webm' | 'mp4';
+}
+interface RenderStillOptions extends RenderCommonOptions {
+    /** Seek time for the captured frame, seconds. */
+    time: number;
+}
+interface RenderResult {
+    bytes: Uint8Array;
+    mimeType: string;
+}
+/** Render a vos config to a video (WebM/MP4) in a headless browser. */
+declare function renderVideo(browser: Browser, opts: RenderVideoOptions): Promise<RenderResult>;
+/** Render a single frame of a vos config to an image in a headless browser. */
+declare function renderStill(browser: Browser, opts: RenderStillOptions): Promise<RenderResult>;
+interface PreviewPages {
+    /** Host page: iframes the player and drives it over the bridge. */
+    hostHtml: string;
+    /** The engine's playback-mode player (waits for a LOAD postMessage). */
+    playerHtml: string;
+}
+/**
+ * Pages for `vos preview`. The playback template is the iframe HALF of the
+ * player bridge — it renders nothing until a host posts `LOAD`, so the CLI
+ * serves a minimal host page that sends `LOAD { code, autoplay }` and shows
+ * a transport line (time / duration, click to play-pause).
+ */
+declare function previewPages(config: Record<string, unknown>): PreviewPages;
+
+interface LoadedConfig {
+    config: Record<string, unknown>;
+    warnings: string[];
+}
+/**
+ * Load a VosConfigJson from a file path or http(s) URL, unwrap API `{ config }`
+ * envelopes, migrate old versions, and validate against the schema.
+ */
+declare function loadVosConfig(source: string): Promise<LoadedConfig>;
+/** Best-effort duration from the config (seconds). */
+declare function configDuration(config: Record<string, unknown>): number | undefined;
+
+declare class BrowserUnavailableError extends Error {
+    constructor(cause: string);
+}
+/**
+ * Launch headless Chromium: explicit VOS_BROWSER_PATH → system Chrome
+ * (no download needed) → Playwright's bundled Chromium.
+ */
+declare function launchBrowser(): Promise<Browser>;
+
+export { BrowserUnavailableError, type LoadedConfig, type RenderResult, type RenderStillOptions, type RenderVideoOptions, configDuration, launchBrowser, loadVosConfig, previewPages, renderStill, renderVideo };

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import {
+  BrowserUnavailableError,
+  configDuration,
+  launchBrowser,
+  loadVosConfig,
+  previewPages,
+  renderStill,
+  renderVideo
+} from "./chunk-A5AN2K5L.js";
+export {
+  BrowserUnavailableError,
+  configDuration,
+  launchBrowser,
+  loadVosConfig,
+  previewPages,
+  renderStill,
+  renderVideo
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@vosjs/cli",
+  "version": "0.1.0",
+  "description": "Command line for the vos programmatic video engine — render deterministic videos and stills from vos configs, headlessly, from your terminal or an AI agent.",
+  "type": "module",
+  "license": "MIT",
+  "author": "vosso",
+  "homepage": "https://vos.so/engine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vosjs/vos.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/vosjs/vos/issues"
+  },
+  "keywords": [
+    "vos",
+    "cli",
+    "video",
+    "render",
+    "deterministic",
+    "headless",
+    "agent",
+    "animation",
+    "three"
+  ],
+  "bin": {
+    "vos": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "playwright": "^1.49.0",
+    "@vosjs/core": "^0.7.0",
+    "@vosjs/tween": "^0.7.2",
+    "@vosjs/elements": "^0.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsup": "^8.5.0",
+    "typescript": "^5",
+    "vitest": "^3.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "clean": "rm -rf dist node_modules"
+  }
+}