@1agh/maude 0.39.1 → 0.40.0

package/apps/studio/exporters/_browser-bundles.ts

@@ -9,6 +9,8 @@ import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
+import { DEV_SERVER_ROOT } from '../paths.ts';
+
 interface CachedBundle {
   path: string;
   ready: Promise<string>;
@@ -68,6 +70,121 @@ async function buildIife(entry: string, globalName: string, cachePath: string):
   return cachePath;
 }
 
+/**
+ * DDR-148 — build the in-page video encoder (`video-encode-lib.ts`) to a
+ * self-contained browser ESM module cached under the OS temp dir. It imports
+ * mediabunny + gifenc (both INLINED — no externals) and assigns
+ * `window.__maudeEnc`; the capture shim injects it via
+ * `page.addScriptTag({ content, type: 'module' })`. Returns the cache path.
+ *
+ * Unlike getBrowserBundle this bundles a LOCAL source entry (not an npm
+ * package) and keeps ESM (the module's top-level `window.__maudeEnc = …` side
+ * effect runs on load — no IIFE export-hoisting needed).
+ */
+let encodeLibReady: Promise<string> | null = null;
+export function getEncodeLibBundle(): Promise<string> {
+  if (encodeLibReady) return encodeLibReady;
+  // DDR-045: derive from DEV_SERVER_ROOT, never `import.meta.dir`. In a compiled
+  // binary the latter is the virtual `/$bunfs/root`, so `Bun.build` fails with
+  // "failed to open root directory: /$bunfs/root" (the mp4/gif export bug).
+  const entry = path.join(DEV_SERVER_ROOT, 'exporters', 'video-encode-lib.ts');
+  const cachePath = path.join(tmpdir(), 'maude-video-encode-lib.mjs');
+  encodeLibReady = (async () => {
+    const built = await Bun.build({
+      entrypoints: [entry],
+      target: 'browser',
+      format: 'esm',
+      minify: true,
+      conditions: ['browser', 'import'],
+    });
+    if (!built.success) {
+      throw new Error(`encode-lib bundle failed: ${built.logs.map((l) => l.message).join('; ')}`);
+    }
+    const first = built.outputs[0];
+    if (!first) throw new Error('encode-lib bundle produced no outputs');
+    await Bun.write(cachePath, await first.text());
+    return cachePath;
+  })();
+  return encodeLibReady;
+}
+
+/**
+ * DDR-148 addendum (audio export) — build the in-page whole-comp renderer
+ * (`video-render-lib.ts`, wraps @remotion/web-renderer's renderMediaOnWeb) to a
+ * self-contained browser ESM module cached under the OS temp dir. Assigns
+ * `window.__maudeRenderVideo__`; the capture shim injects it via addScriptTag
+ * before calling `window.__maude_render_video__` (video-comp.tsx bridge).
+ *
+ * UNLIKE getEncodeLibBundle, this externalizes 'remotion' + '@remotion/media' —
+ * they must resolve to the SAME module instances the canvas's importmap already
+ * loaded (dual-package hazard: a second bundled copy would give
+ * renderMediaOnWeb's internal Composition/context providers a different
+ * `TimelineContext` than the one the passed `component`'s hooks read from,
+ * freezing every frame at 0 / silencing audio). The browser's importmap
+ * (declared in _shell.html) resolves these bare specifiers even for a
+ * dynamically injected `<script type=module>` tag.
+ */
+let webRendererLibReady: Promise<string> | null = null;
+export function getWebRendererBundle(): Promise<string> {
+  if (webRendererLibReady) return webRendererLibReady;
+  const entry = path.join(DEV_SERVER_ROOT, 'exporters', 'video-render-lib.ts');
+  const cachePath = path.join(tmpdir(), 'maude-video-render-lib.mjs');
+  webRendererLibReady = (async () => {
+    // Bun's `external` field is package-name PREFIX matched (runtime-bundle.ts's
+    // comment on the same gotcha) — listing 'remotion' also externalizes deep
+    // subpaths like 'remotion/version' (a real import inside web-renderer's own
+    // dependency tree). The importmap only maps the bare 'remotion' specifier, so
+    // an externalized 'remotion/version' 404s in the browser with "Failed to
+    // resolve module specifier". Use an exact-match onResolve plugin (mirrors
+    // canvas-build.ts's `exact-externals`) so ONLY the specifiers the importmap
+    // actually covers are externalized; every subpath (version, no-react, etc.)
+    // gets bundled inline like any other dependency.
+    //
+    // react/react-dom MUST also be externalized here (not just remotion) — a
+    // second bundled React copy inside this module renders the SAME `component`
+    // reference the page's importmap-loaded React created, and two React
+    // instances in one page is the textbook "Invalid Hook Call" (minified React
+    // error #321): the component's hooks resolve against instance A's dispatcher
+    // while web-renderer's internal renderer/reconciler is instance B. Discovered
+    // empirically — the first working build threw exactly this error.
+    const EXTERNAL_EXACT = new Set([
+      'remotion',
+      '@remotion/media',
+      'react',
+      'react-dom',
+      'react-dom/client',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+    ]);
+    const built = await Bun.build({
+      entrypoints: [entry],
+      target: 'browser',
+      format: 'esm',
+      minify: true,
+      conditions: ['browser', 'import'],
+      plugins: [
+        {
+          name: 'exact-externals',
+          setup(builder) {
+            builder.onResolve({ filter: /.*/ }, (args) => {
+              if (EXTERNAL_EXACT.has(args.path)) return { path: args.path, external: true };
+              return null;
+            });
+          },
+        },
+      ],
+    });
+    if (!built.success) {
+      throw new Error(`web-renderer bundle failed: ${built.logs.map((l) => l.message).join('; ')}`);
+    }
+    const first = built.outputs[0];
+    if (!first) throw new Error('web-renderer bundle produced no outputs');
+    await Bun.write(cachePath, await first.text());
+    return cachePath;
+  })();
+  return webRendererLibReady;
+}
+
 /**
  * Returns the path to an IIFE bundle for the given npm package, attaching its
  * exports under `window[globalName]`. Caches under the OS temp dir so a long-

package/apps/studio/exporters/_runtime.ts

@@ -0,0 +1,69 @@
+// Shared runtime + path resolution for the external playwright render shims
+// (`bin/_{png,pdf,svg,html,pptx,video}-playwright.mjs`).
+//
+// RCA: issue-desktop-export-failures. The render exporters were written for the
+// dev-server runtime and never migrated for the compiled-Bun sidecar packaging,
+// so they broke in two ways in every `bun --compile` standalone binary (the
+// desktop app AND `npm i -g @1agh/maude`):
+//
+//   1. Shim paths computed from `import.meta.dir` → inside a compiled binary that
+//      is the virtual `/$bunfs/root`, not a real disk path, so `Bun.spawn` /
+//      `Bun.build` fail with "failed to open root directory: /$bunfs/root". This
+//      is the DDR-045 bug: filesystem-relative paths MUST derive from
+//      `paths.ts`, never a local `import.meta.dir`.
+//   2. Spawning a hardcoded `'node'` → the desktop sidecar is a compiled Bun
+//      binary with no bundled `node`; a Finder-launched `.app` can't rely on one
+//      being on PATH, so the spawn fails with `posix_spawn 'node'` ENOENT.
+//
+// This module centralizes both concerns so all six adapters resolve identically.
+
+import path from 'node:path';
+
+import { DEV_SERVER_ROOT } from '../paths.ts';
+
+/**
+ * Real-disk dir holding the render shims (`<DEV_SERVER_ROOT>/bin`).
+ *
+ * Derived from `DEV_SERVER_ROOT` (paths.ts) — NEVER `import.meta.dir`, which is
+ * the virtual `/$bunfs/root` inside a compiled binary (DDR-045). In dev this is
+ * the same `apps/studio/bin` the old `path.join(import.meta.dir, '..', 'bin')`
+ * resolved to; in the desktop bundle it resolves to `Resources/apps/studio/bin`
+ * (the shims ARE staged there — stage-resources ships the whole source tree).
+ */
+export const EXPORT_SHIM_DIR: string = path.join(DEV_SERVER_ROOT, 'bin');
+
+/** Absolute path to a render shim by basename (e.g. `_png-playwright.mjs`). */
+export function exportShimPath(basename: string): string {
+  return path.join(EXPORT_SHIM_DIR, basename);
+}
+
+/**
+ * Resolve a JS runtime able to execute the external `.mjs` render shims.
+ *
+ * Ladder (mirrors `acp/probe.ts` resolveAgentRuntime): explicit override → a
+ * real `node` on PATH → a standalone `bun` on PATH. The compiled maude binary
+ * (`process.execPath`) is deliberately NOT a fallback — a `bun --compile`
+ * standalone ignores a script argument and re-runs its own embedded entrypoint,
+ * so it can't run a shim. When nothing resolves (a packaged desktop app whose
+ * sidecar has no node/bun on PATH) we throw an ACTIONABLE error instead of the
+ * cryptic `posix_spawn 'node'` ENOENT the hardcoded `'node'` produced.
+ */
+export function resolveExportRuntime(): string {
+  // Look up against the LIVE process PATH (the desktop sidecar sets it via env at
+  // spawn — DDR-128), not Bun's startup env snapshot, so a corrected PATH is
+  // honored and the lookup is deterministic/testable.
+  const pathEnv = process.env.PATH;
+  const runtime =
+    process.env.MAUDE_EXPORT_RUNTIME ||
+    Bun.which('node', { PATH: pathEnv }) ||
+    Bun.which('bun', { PATH: pathEnv });
+  if (!runtime) {
+    throw new Error(
+      'render export needs a JS runtime (node or bun) on PATH, but this build has none. ' +
+        'Run the export from the browser dev-server (`maude design serve`), install Node, ' +
+        'or set MAUDE_EXPORT_RUNTIME to a node/bun binary. ' +
+        '(Native desktop render-export backend is pending — see RCA issue-desktop-export-failures.)'
+    );
+  }
+  return runtime;
+}

package/apps/studio/exporters/html.ts

@@ -11,7 +11,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,
@@ -20,7 +20,8 @@ import {
 } from './index.ts';
 import type { Target } from './scope.ts';
 
-const HTML_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_html-playwright.mjs');
+// DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
+const HTML_PLAYWRIGHT = exportShimPath('_html-playwright.mjs');
 
 async function captureHtml(
   target: Extract<Target, { kind: 'element' }>,
@@ -45,7 +46,7 @@ async function captureHtml(
     if (target.widen) args.push('--widen-to-artboard', '1');
     args.push('--out', path.join(outDir, `${target.canvasSlug}.html`));
   }
-  const proc = Bun.spawn(['node', ...args], {
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
     cwd: path.dirname(HTML_PLAYWRIGHT),
     stdout: 'pipe',
     stderr: 'pipe',

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;