@1agh/maude 0.39.1 → 0.41.0

package/apps/studio/exporters/index.ts

@@ -15,11 +15,34 @@ import * as png from './png.ts';
 import * as pptx from './pptx.ts';
 import { type ResolveScopeArgs, resolveScope, type Scope, type Target } from './scope.ts';
 import * as svg from './svg.ts';
+// DDR-148 — temporal formats (capture-spine encode). Named exports mp4/webm/gif.
+import { gif, mp4, webm } from './video.ts';
 import * as zip from './zip.ts';
 
-export type Format = 'png' | 'pdf' | 'svg' | 'html' | 'pptx' | 'canva' | 'zip';
+export type Format =
+  | 'png'
+  | 'pdf'
+  | 'svg'
+  | 'html'
+  | 'pptx'
+  | 'canva'
+  | 'zip'
+  | 'mp4'
+  | 'webm'
+  | 'gif';
 
-export const FORMATS: readonly Format[] = ['png', 'pdf', 'svg', 'html', 'pptx', 'canva', 'zip'];
+export const FORMATS: readonly Format[] = [
+  'png',
+  'pdf',
+  'svg',
+  'html',
+  'pptx',
+  'canva',
+  'zip',
+  'mp4',
+  'webm',
+  'gif',
+];
 
 /** Options bag forwarded to the adapter. Format-specific keys are validated by each adapter. */
 export type ExportOptions = Record<string, unknown>;
@@ -63,6 +86,9 @@ const REGISTRY: Record<Format, Adapter> = {
   pptx,
   canva,
   zip,
+  mp4,
+  webm,
+  gif,
 };
 
 export function getAdapter(format: Format): Adapter | null {

package/apps/studio/exporters/pdf.ts

@@ -13,7 +13,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { PDFDocument } from 'pdf-lib';
-
+import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
@@ -22,7 +22,8 @@ import {
 } from './index.ts';
 import type { Target } from './scope.ts';
 
-const PDF_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_pdf-playwright.mjs');
+// DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
+const PDF_PLAYWRIGHT = exportShimPath('_pdf-playwright.mjs');
 
 async function capturePdf(
   target: Extract<Target, { kind: 'element' }>,
@@ -48,7 +49,7 @@ async function capturePdf(
     args.push('--out', path.join(outDir, `${target.canvasSlug}.pdf`));
   }
 
-  const proc = Bun.spawn(['node', ...args], {
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
     cwd: path.dirname(PDF_PLAYWRIGHT),
     stdout: 'pipe',
     stderr: 'pipe',

package/apps/studio/exporters/png.ts

@@ -12,7 +12,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import JSZip from 'jszip';
-
+import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
@@ -21,7 +21,9 @@ import {
 } from './index.ts';
 import type { Target } from './scope.ts';
 
-const PNG_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_png-playwright.mjs');
+// DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir` (→ /$bunfs/root
+// in a compiled binary). See exporters/_runtime.ts.
+const PNG_PLAYWRIGHT = exportShimPath('_png-playwright.mjs');
 
 interface CaptureOptions {
   scale?: 1 | 2 | 3;
@@ -66,7 +68,7 @@ async function captureElement(
     if (target.widen) args.push('--widen-to-artboard', '1');
     args.push('--out', path.join(outDir, `${target.canvasSlug}.png`));
   }
-  const proc = Bun.spawn(['node', ...args], {
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
     cwd: path.dirname(PNG_PLAYWRIGHT),
     stdout: 'pipe',
     stderr: 'pipe',

package/apps/studio/exporters/pptx.ts

@@ -27,6 +27,7 @@ import path from 'node:path';
 import PptxGenJS from 'pptxgenjs';
 
 import { getBrowserBundle } from './_browser-bundles.ts';
+import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
@@ -35,8 +36,9 @@ import {
 } from './index.ts';
 import type { Target } from './scope.ts';
 
-const SVG_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_svg-playwright.mjs');
-const PNG_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_png-playwright.mjs');
+// DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
+const SVG_PLAYWRIGHT = exportShimPath('_svg-playwright.mjs');
+const PNG_PLAYWRIGHT = exportShimPath('_png-playwright.mjs');
 const PPTX_MIME = 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
 const SLIDE_REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide';
 const SLIDE_CT = 'application/vnd.openxmlformats-officedocument.presentationml.slide+xml';
@@ -49,9 +51,9 @@ function isElementTarget(t: Target): t is ElementTarget {
   return t.kind === 'element';
 }
 
-/** Spawn a playwright shim via `node`, returning the written file paths (stdout). */
+/** Spawn a playwright shim via a resolved runtime, returning the written file paths (stdout). */
 async function spawnShim(args: string[]): Promise<string[]> {
-  const proc = Bun.spawn(['node', ...args], {
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
     cwd: path.dirname(args[0]),
     stdout: 'pipe',
     stderr: 'pipe',

package/apps/studio/exporters/svg.ts

@@ -13,6 +13,7 @@ import path from 'node:path';
 import JSZip from 'jszip';
 
 import { getBrowserBundle } from './_browser-bundles.ts';
+import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
@@ -21,7 +22,8 @@ import {
 } from './index.ts';
 import type { Target } from './scope.ts';
 
-const SVG_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_svg-playwright.mjs');
+// DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
+const SVG_PLAYWRIGHT = exportShimPath('_svg-playwright.mjs');
 
 async function captureSvg(
   target: Extract<Target, { kind: 'element' }>,
@@ -50,10 +52,12 @@ async function captureSvg(
     args.push('--out', path.join(outDir, `${target.canvasSlug}.svg`));
   }
 
-  // Run via `node` so the shim's `import 'playwright'` resolves against
-  // dev-server/node_modules (playwright is a devDep). `npm exec` doesn't
-  // bridge the module path for ESM imports — confirmed against npm 10.x.
-  const proc = Bun.spawn(['node', ...args], {
+  // Run via a resolved node/bun runtime so the shim's `import 'playwright'`
+  // resolves against dev-server/node_modules (playwright is a devDep). `npm exec`
+  // doesn't bridge the module path for ESM imports — confirmed against npm 10.x.
+  // resolveExportRuntime() replaces a hardcoded `'node'` so a compiled binary
+  // without `node` on PATH surfaces an actionable error, not `posix_spawn 'node'`.
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
     cwd: path.dirname(SVG_PLAYWRIGHT),
     stdout: 'pipe',
     stderr: 'pipe',

package/apps/studio/exporters/video-encode-lib.ts

@@ -0,0 +1,200 @@
+// video-encode-lib.ts — DDR-148 in-page MP4/WebM/GIF encoder.
+//
+// Runs INSIDE the capture Chromium (bundled to a self-contained module by
+// _browser-bundles.getEncodeLibBundle, injected via page.addScriptTag). WebCodecs
+// is guaranteed there — the user's shell browser / WKWebView never encodes.
+//
+// The Node shim (bin/_video-playwright.mjs) screenshots each frame, hands the
+// PNG in as base64, and this lib decodes → draws to an offscreen canvas →
+// encodes: mediabunny (Output + CanvasSource, H.264/avc in MP4, VP9/VP8 in WebM
+// as the fallback), or gifenc (quantize → applyPalette). Video codec is chosen
+// by mediabunny's own capability probe, so a browser without an H.264 encoder
+// degrades to WebM instead of failing. Audio mixing is added in a follow-up
+// slice (the comp's <Audio>/<Video> sources via OfflineAudioContext).
+//
+// The lib assigns a single `window.__maudeEnc` surface (no exports — it's a
+// side-effecting module script).
+
+import { applyPalette, GIFEncoder, quantize } from 'gifenc';
+import {
+  BufferTarget,
+  CanvasSource,
+  getFirstEncodableVideoCodec,
+  Mp4OutputFormat,
+  Output,
+  QUALITY_HIGH,
+  type VideoCodec,
+  WebMOutputFormat,
+} from 'mediabunny';
+
+interface StartVideoOpts {
+  width: number;
+  height: number;
+  fps: number;
+  format?: 'mp4' | 'webm';
+}
+interface StartGifOpts {
+  width: number;
+  height: number;
+  fps: number;
+  maxColors?: number;
+}
+interface EncodeResult {
+  b64: string;
+  bytes: number;
+  container: string;
+  codec: string;
+}
+
+interface MaudeEnc {
+  startVideo(opts: StartVideoOpts): Promise<{ container: string; codec: string }>;
+  addVideoFrame(b64png: string): Promise<void>;
+  finishVideo(): Promise<EncodeResult>;
+  startGif(opts: StartGifOpts): void;
+  addGifFrame(b64png: string): Promise<void>;
+  finishGif(): EncodeResult;
+}
+
+function b64ToBytes(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i += 1) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function bytesToB64(buf: ArrayBuffer | Uint8Array): string {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let bin = '';
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+async function decodeToBitmap(b64: string): Promise<ImageBitmap> {
+  return createImageBitmap(new Blob([b64ToBytes(b64)], { type: 'image/png' }));
+}
+
+let vstate: {
+  output: Output;
+  source: CanvasSource;
+  canvas: OffscreenCanvas;
+  ctx: OffscreenCanvasRenderingContext2D;
+  fps: number;
+  frame: number;
+  container: string;
+  codec: string;
+} | null = null;
+
+let gstate: {
+  enc: ReturnType<typeof GIFEncoder>;
+  canvas: OffscreenCanvas;
+  ctx: OffscreenCanvasRenderingContext2D;
+  delay: number;
+  maxColors: number;
+} | null = null;
+
+const MP4_CODECS: VideoCodec[] = ['avc', 'hevc'];
+const WEBM_CODECS: VideoCodec[] = ['vp9', 'vp8', 'av1'];
+
+const api: MaudeEnc = {
+  async startVideo({ width, height, fps, format }) {
+    const canvas = new OffscreenCanvas(width, height);
+    const ctx = canvas.getContext('2d');
+    if (!ctx) throw new Error('no 2d context for encode canvas');
+
+    // Prefer the requested container's codecs; fall back to WebM/VP9 so a
+    // browser without an H.264 encoder still produces a file.
+    const wantMp4 = format !== 'webm';
+    let outFormat: Mp4OutputFormat | WebMOutputFormat = wantMp4
+      ? new Mp4OutputFormat()
+      : new WebMOutputFormat();
+    let codec = await getFirstEncodableVideoCodec(wantMp4 ? MP4_CODECS : WEBM_CODECS, {
+      width,
+      height,
+    });
+    if (!codec && wantMp4) {
+      outFormat = new WebMOutputFormat();
+      codec = await getFirstEncodableVideoCodec(WEBM_CODECS, { width, height });
+    }
+    if (!codec) throw new Error('no encodable video codec available in this browser');
+
+    const output = new Output({ format: outFormat, target: new BufferTarget() });
+    const source = new CanvasSource(canvas, { codec, bitrate: QUALITY_HIGH });
+    output.addVideoTrack(source, { frameRate: fps });
+    await output.start();
+    const container = outFormat instanceof Mp4OutputFormat ? 'mp4' : 'webm';
+    vstate = { output, source, canvas, ctx, fps, frame: 0, container, codec };
+    return { container, codec };
+  },
+
+  async addVideoFrame(b64png) {
+    if (!vstate) throw new Error('startVideo not called');
+    const bmp = await decodeToBitmap(b64png);
+    vstate.ctx.drawImage(bmp, 0, 0, vstate.canvas.width, vstate.canvas.height);
+    if ('close' in bmp) bmp.close();
+    await vstate.source.add(vstate.frame / vstate.fps, 1 / vstate.fps);
+    vstate.frame += 1;
+  },
+
+  async finishVideo() {
+    if (!vstate) throw new Error('startVideo not called');
+    await vstate.output.finalize();
+    const buf = vstate.output.target.buffer;
+    if (!buf) throw new Error('encode produced no buffer');
+    const res: EncodeResult = {
+      b64: bytesToB64(buf),
+      bytes: buf.byteLength,
+      container: vstate.container,
+      codec: vstate.codec,
+    };
+    vstate = null;
+    return res;
+  },
+
+  startGif({ width, height, fps, maxColors }) {
+    const canvas = new OffscreenCanvas(width, height);
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    if (!ctx) throw new Error('no 2d context for gif canvas');
+    gstate = {
+      enc: GIFEncoder(),
+      canvas,
+      ctx,
+      delay: Math.max(2, Math.round(100 / fps)) * 10, // gifenc delay is in ms
+      maxColors: Math.max(2, Math.min(256, maxColors ?? 256)),
+    };
+  },
+
+  async addGifFrame(b64png) {
+    if (!gstate) throw new Error('startGif not called');
+    const bmp = await decodeToBitmap(b64png);
+    gstate.ctx.drawImage(bmp, 0, 0, gstate.canvas.width, gstate.canvas.height);
+    if ('close' in bmp) bmp.close();
+    const { data, width, height } = gstate.ctx.getImageData(
+      0,
+      0,
+      gstate.canvas.width,
+      gstate.canvas.height
+    );
+    const palette = quantize(data, gstate.maxColors);
+    const index = applyPalette(data, palette);
+    gstate.enc.writeFrame(index, width, height, { palette, delay: gstate.delay });
+  },
+
+  finishGif() {
+    if (!gstate) throw new Error('startGif not called');
+    gstate.enc.finish();
+    const bytes = gstate.enc.bytes();
+    const res: EncodeResult = {
+      b64: bytesToB64(bytes),
+      bytes: bytes.length,
+      container: 'gif',
+      codec: 'gif',
+    };
+    gstate = null;
+    return res;
+  },
+};
+
+(globalThis as unknown as { __maudeEnc: MaudeEnc }).__maudeEnc = api;

package/apps/studio/exporters/video-render-lib.ts

@@ -0,0 +1,108 @@
+// video-render-lib.ts — DDR-148 addendum: in-page whole-comp render (video +
+// audio, one pass) via @remotion/web-renderer's renderMediaOnWeb.
+//
+// Runs INSIDE the capture Chromium (injected via addScriptTag, mirroring
+// video-encode-lib.ts). Replaces the frame-step + mediabunny screenshot loop
+// for video-comp mp4/webm export: Remotion owns the TransitionSeries offset
+// math and `<Audio volume={fn}>` closures internally, so a single
+// renderMediaOnWeb call produces a correctly-muxed, frame-accurate video+audio
+// file with no hand-rolled mixing. GIF export (no audio, no renderMediaOnWeb
+// container support) stays on the frame-step + gifenc path — proven compatible
+// with @remotion/media (screenshot-after-seek reliably shows decoded frames,
+// including mid-transition composites; see the DDR-148 addendum retro).
+//
+// Externalizes 'remotion' + '@remotion/media' (resolved via the SAME importmap
+// bundle the page's canvas module tree uses) to avoid the dual-package hazard:
+// the `component` passed in was created against the page's imported instances,
+// so renderMediaOnWeb's internal Composition/context providers MUST be the
+// same instances, or useCurrentFrame()/<Audio> volume closures bind to the
+// wrong (default) context and the render freezes / plays silent.
+//
+// Offline posture (DDR-148 security): the capture CSP already locks network
+// egress to loopback-only, which blocks web-renderer's optional telemetry
+// (remotion.pro/api/track/register-usage-point) at the network layer — no
+// additional code needed here. `licenseKey`/`isProduction` are still threaded
+// through per Remotion's disclosed-license posture (MAUDE_REMOTION_LICENSE).
+
+import { renderMediaOnWeb } from '@remotion/web-renderer';
+import type { ComponentType } from 'react';
+
+interface RenderVideoOpts {
+  component: ComponentType<Record<string, unknown>>;
+  inputProps?: Record<string, unknown>;
+  width: number;
+  height: number;
+  fps: number;
+  durationInFrames: number;
+  container: 'mp4' | 'webm';
+  videoCodec?: string;
+  audioCodec?: string;
+  scale?: number;
+  muted?: boolean;
+  frameRange?: [number, number];
+  licenseKey?: string;
+}
+
+interface RenderVideoResult {
+  b64: string;
+  bytes: number;
+  container: string;
+  videoCodec: string | null;
+  audioCodec: string | null;
+}
+
+function bytesToB64(buf: ArrayBuffer | Uint8Array): string {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let bin = '';
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+async function renderVideo(opts: RenderVideoOpts): Promise<RenderVideoResult> {
+  const muted = opts.muted ?? false;
+  const videoCodec = (opts.videoCodec ??
+    (opts.container === 'webm' ? 'vp9' : 'h264')) as Parameters<
+    typeof renderMediaOnWeb
+  >[0]['videoCodec'];
+  const audioCodec = muted
+    ? null
+    : ((opts.audioCodec ?? (opts.container === 'webm' ? 'opus' : 'aac')) as Parameters<
+        typeof renderMediaOnWeb
+      >[0]['audioCodec']);
+
+  const result = await renderMediaOnWeb({
+    composition: {
+      component: opts.component,
+      id: 'maude-export',
+      width: opts.width,
+      height: opts.height,
+      fps: opts.fps,
+      durationInFrames: opts.durationInFrames,
+    },
+    inputProps: opts.inputProps ?? {},
+    container: opts.container,
+    videoCodec,
+    audioCodec,
+    muted,
+    scale: opts.scale ?? 1,
+    frameRange: opts.frameRange ?? null,
+    isProduction: true,
+    licenseKey: opts.licenseKey ?? 'free-license',
+    logLevel: 'error',
+  });
+  const blob = await result.getBlob();
+  const buf = new Uint8Array(await blob.arrayBuffer());
+  return {
+    b64: bytesToB64(buf),
+    bytes: buf.length,
+    container: opts.container,
+    videoCodec: videoCodec ?? null,
+    audioCodec: audioCodec ?? null,
+  };
+}
+
+(globalThis as unknown as { __maudeRenderVideo__: typeof renderVideo }).__maudeRenderVideo__ =
+  renderVideo;

package/apps/studio/exporters/video.ts

@@ -0,0 +1,184 @@
+// DDR-148 — video/animation exporter (mp4 · webm · gif).
+//
+// Drives bin/_video-playwright.mjs, which picks one of two capture strategies:
+//   • mp4/webm of a registered video-comp — DDR-148 addendum (audio export):
+//     window.__maude_render_video__ → @remotion/web-renderer's renderMediaOnWeb,
+//     video+audio in one pass (Remotion owns the TransitionSeries/volume-closure
+//     timeline math). `getWebRendererBundle()` supplies the in-page renderer.
+//   • everything else (gif, ordinary/CSS-WAAPI artboards, or no registered
+//     comp) — the original frame-step spine: steps the artboard frame-by-frame
+//     via window.__maude_seek__ and encodes in-page with mediabunny (H.264/avc
+//     MP4, VP9/VP8 WebM fallback) or gifenc. `getEncodeLibBundle()` supplies
+//     this in-page encoder, and doubles as the render-lib path's fallback when
+//     the target has no registered comp (the shim decides at runtime — see
+//     _video-playwright.mjs for the exact routing condition).
+// Scope is always `artboard`. No native binaries; the capture Chromium is the
+// same one every other exporter already uses (DDR-041).
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { getEncodeLibBundle, getWebRendererBundle } from './_browser-bundles.ts';
+import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import {
+  canvasShellUrl,
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+} from './index.ts';
+import type { Target } from './scope.ts';
+
+// DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
+const VIDEO_PLAYWRIGHT = exportShimPath('_video-playwright.mjs');
+
+type VideoFormat = 'mp4' | 'webm' | 'gif';
+
+const CONTENT_TYPE: Record<string, string> = {
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  gif: 'image/gif',
+};
+
+/** Hard cap so a runaway/huge comp can't spawn an unbounded screenshot loop. */
+const MAX_FRAMES = 900; // 30 s @ 30 fps
+
+async function runVideo(
+  format: VideoFormat,
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  const el = targets.find((t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element');
+  if (!el) {
+    throw new Error(
+      `${format} export needs an artboard target — make the artboard a video-comp or add motion`
+    );
+  }
+
+  // gif has no renderMediaOnWeb container support (and no audio need — GIF is a
+  // silent format), so it never needs the render-lib bundle; mp4/webm build it
+  // alongside the frame-step encode-lib (the shim decides per-target at runtime
+  // whether the artboard has a registered comp to hand the renderer).
+  const [lib, renderLib] = await Promise.all([
+    getEncodeLibBundle(),
+    format === 'gif' ? Promise.resolve(null) : getWebRendererBundle(),
+  ]);
+  const tmp = mkdtempSync(path.join(tmpdir(), 'maude-video-'));
+  const outPath = path.join(tmp, `export.${format}`);
+
+  const args = [
+    VIDEO_PLAYWRIGHT,
+    '--url',
+    canvasShellUrl(ctx, el.file),
+    '--selector',
+    el.cssPath,
+    '--encode-lib',
+    lib,
+    '--format',
+    format,
+    '--out',
+    outPath,
+    '--timeout',
+    String((options.timeoutSec as number | undefined) ?? 120),
+  ];
+  if (renderLib) args.push('--render-lib', renderLib);
+  if (el.widen) args.push('--widen', '1');
+  // Ordinary artboards animate on wall-clock (WAAPI); video-comps on frame index.
+  if (options.mode === 'ordinary') args.push('--mode', 'ordinary');
+
+  // Export-with-audio (DDR-148 addendum) — default ON; only the render-lib path
+  // (mp4/webm of a registered comp) can actually produce audio, but the flag is
+  // harmless for the frame-step fallback (video-only, always has been).
+  const wantAudio = options.audio !== false;
+  args.push('--audio', wantAudio ? '1' : '0');
+  // Remotion license posture — MAUDE_REMOTION_LICENSE env (config-driven, per
+  // project); the shim defaults to 'free-license' when unset. Network egress
+  // for web-renderer's optional telemetry is blocked at the CSP layer regardless
+  // (cspForCapture's `connect-src 'self'`, http.ts) — no additional code needed
+  // for the offline posture beyond passing the key through.
+  if (process.env.MAUDE_REMOTION_LICENSE) {
+    args.push('--license-key', process.env.MAUDE_REMOTION_LICENSE);
+  }
+
+  // Resolution multiplier (1–3×) — the artboard's native size × scale. Default 2×
+  // so a 960×540 comp exports at 1920×1080 instead of a tiny native capture. The
+  // shim applies it as deviceScaleFactor AND sizes the encoder to match.
+  const scale = clampInt(options.scale, 1, 3) ?? 2;
+  args.push('--scale', String(scale));
+
+  const fps = clampInt(options.fps, 1, 60);
+  if (fps) args.push('--fps', String(fps));
+
+  const frames = resolveFrames(options, fps);
+  if (frames) args.push('--frames', String(frames));
+
+  if (format === 'gif') {
+    const colors = clampInt(options.gifColors, 2, 256);
+    if (colors) args.push('--gifColors', String(colors));
+  }
+
+  try {
+    const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+      cwd: path.dirname(VIDEO_PLAYWRIGHT),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    if (code !== 0) {
+      throw new Error(`_video-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
+    }
+    const body = new Uint8Array(readFileSync(outPath));
+    // The container can differ from the request (mp4 → webm fallback when the
+    // browser has no H.264 encoder). Read the summary line for the real ext.
+    let ext: string = format;
+    try {
+      const lastLine = stdout.trim().split('\n').filter(Boolean).pop() ?? '{}';
+      const summary = JSON.parse(lastLine) as { container?: string };
+      if (summary.container) ext = summary.container;
+    } catch {
+      /* keep the requested ext */
+    }
+    return {
+      filename: `${el.canvasSlug}.${ext}`,
+      contentType: CONTENT_TYPE[ext] ?? 'application/octet-stream',
+      body,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** Coerce an option to an int within [lo, hi], or undefined when absent/invalid. */
+function clampInt(raw: unknown, lo: number, hi: number): number | undefined {
+  const n = Math.round(Number(raw));
+  if (!Number.isFinite(n)) return undefined;
+  return Math.max(lo, Math.min(hi, n));
+}
+
+/** Resolve the frame count from options (frames | durationMs×fps), capped. */
+function resolveFrames(options: ExportOptions, fps: number | undefined): number | undefined {
+  const explicit = clampInt(options.frames, 1, MAX_FRAMES);
+  if (explicit) return explicit;
+  const durationMs = Number(options.durationMs);
+  if (Number.isFinite(durationMs) && durationMs > 0 && fps) {
+    return Math.min(MAX_FRAMES, Math.max(1, Math.round((durationMs / 1000) * fps)));
+  }
+  // No hint → the shim falls back to the in-page comp meta (durationInFrames),
+  // still clamped there. Pass the ceiling so an unbounded comp can't run away.
+  return undefined;
+}
+
+export const mp4 = {
+  run: (t: Target[], o: ExportOptions, c: ExportContext) => runVideo('mp4', t, o, c),
+};
+export const webm = {
+  run: (t: Target[], o: ExportOptions, c: ExportContext) => runVideo('webm', t, o, c),
+};
+export const gif = {
+  run: (t: Target[], o: ExportOptions, c: ExportContext) => runVideo('gif', t, o, c),
+};