@bendyline/squisq-cli 1.2.2 → 2.0.1

package/dist/api.js

@@ -1,15 +1,32 @@
+import {
+  GIF_EXPORT_DEFAULTS,
+  framesToGifNative,
+  framesToGifNativeBytes,
+  framesToMp4Native,
+  framesToMp4NativeBytes,
+  runFfmpeg
+} from "./chunk-OEN2RADG.js";
+
 // src/api.ts
 import { resolveMediaSchedule } from "@bendyline/squisq/schemas";
 import { flattenBlocks } from "@bendyline/squisq/doc";
-import { generateRenderHtml } from "@bendyline/squisq-video";
+import { ffmpegGifOutputArgs, generateRenderHtml } from "@bendyline/squisq-video";
 import { resolveDimensions } from "@bendyline/squisq-video";
-import { convert as formatsConvert } from "@bendyline/squisq-formats";
+import {
+  convert as formatsConvert,
+  prepareConversion as formatsPrepareConversion
+} from "@bendyline/squisq-formats";
 
 // src/util/detectFfmpeg.ts
 import { execFile } from "child_process";
-function run(command, args) {
-  return new Promise((resolve) => {
-    execFile(command, args, { timeout: 5e3 }, (err, stdout) => {
+function run(command, args, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { timeout: 5e3, signal }, (err, stdout) => {
+      if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+      }
       if (err || !stdout.trim()) {
         resolve(null);
         return;
@@ -18,14 +35,15 @@ function run(command, args) {
     });
   });
 }
-async function getFfmpegVersion(path) {
-  const out = await run(path, ["-version"]);
+async function getFfmpegVersion(path, signal) {
+  const out = await run(path, ["-version"], signal);
   return out ? out.split("\n")[0].trim() : null;
 }
-async function detectFfmpegDetailed() {
+async function detectFfmpegDetailed(signal) {
+  signal?.throwIfAborted();
   const envPath = process.env.SQUISQ_FFMPEG;
   if (envPath) {
-    const version = await getFfmpegVersion(envPath);
+    const version = await getFfmpegVersion(envPath, signal);
     if (!version) {
       throw new Error(
         `SQUISQ_FFMPEG is set to "${envPath}" but running "${envPath} -version" failed. Fix the path or unset SQUISQ_FFMPEG.`
@@ -34,11 +52,12 @@ async function detectFfmpegDetailed() {
     return { path: envPath, source: "env" };
   }
   const command = process.platform === "win32" ? "where" : "which";
-  const found = await run(command, ["ffmpeg"]);
+  const found = await run(command, ["ffmpeg"], signal);
   if (found) {
     return { path: found.split("\n")[0].trim(), source: "path" };
   }
   try {
+    signal?.throwIfAborted();
     const specifier = "ffmpeg-static";
     const mod = await import(specifier);
     const candidate = typeof mod === "string" ? mod : typeof mod.default === "string" ? mod.default : null;
@@ -46,50 +65,55 @@ async function detectFfmpegDetailed() {
       return { path: candidate, source: "ffmpeg-static" };
     }
   } catch {
+    signal?.throwIfAborted();
   }
+  signal?.throwIfAborted();
   return null;
 }
-async function detectFfmpeg() {
-  const detection = await detectFfmpegDetailed();
-  return detection?.path ?? null;
-}
 
 // src/util/audioMix.ts
 import { computeAudioTimeline } from "@bendyline/squisq-video";
-async function buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll) {
+async function buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll, signal) {
+  signal?.throwIfAborted();
   const timeline = computeAudioTimeline(doc, coverPreRoll);
   if (timeline.length === 0) return null;
   const bytesBySrc = /* @__PURE__ */ new Map();
   const readSrc = async (src) => {
+    signal?.throwIfAborted();
     if (bytesBySrc.has(src)) return bytesBySrc.get(src);
     const data = await container.readFile(src);
+    signal?.throwIfAborted();
     bytesBySrc.set(src, data ?? null);
     return data ?? null;
   };
   const usable = [];
   for (const clip of timeline) {
+    signal?.throwIfAborted();
     const buffer = await readSrc(clip.src);
     if (buffer) usable.push({ clip, buffer });
   }
   if (usable.length === 0) return null;
-  return mixTimelineClips(ffmpegPath, usable);
+  return mixTimelineClips(ffmpegPath, usable, signal);
 }
-async function mixTimelineClips(ffmpegPath, usable) {
+async function mixTimelineClips(ffmpegPath, usable, signal) {
   const { writeFile, readFile: readFile3, mkdir, rm: rm2 } = await import("fs/promises");
   const { join: join3 } = await import("path");
   const { tmpdir: tmpdir2 } = await import("os");
   const { randomBytes: randomBytes2 } = await import("crypto");
-  const { execFile: execFile2 } = await import("child_process");
+  signal?.throwIfAborted();
   const workDir = join3(tmpdir2(), `squisq-audio-mix-${randomBytes2(8).toString("hex")}`);
   await mkdir(workDir, { recursive: true });
   const ms = (s) => Math.max(0, Math.round(s * 1e3));
   try {
+    signal?.throwIfAborted();
     const inputs = [];
     const filters = [];
     const labels = [];
     for (const { clip, buffer } of usable) {
+      signal?.throwIfAborted();
       const p = join3(workDir, `clip-${inputs.length}.mp3`);
       await writeFile(p, new Uint8Array(buffer));
+      signal?.throwIfAborted();
       const i = inputs.push(p) - 1;
       const delayMs = ms(clip.startSec);
       const start = Math.max(0, clip.sourceInSec);
@@ -114,19 +138,99 @@ async function mixTimelineClips(ffmpegPath, usable) {
       "192k",
       outputPath
     );
-    await new Promise((resolve, reject) => {
-      execFile2(ffmpegPath, args, { timeout: 18e4 }, (err) => {
-        if (err) reject(new Error(`ffmpeg audio mix failed: ${err.message}`));
-        else resolve();
-      });
+    await runFfmpeg(ffmpegPath, args, {
+      timeoutMs: 18e4,
+      failureMessage: "ffmpeg audio mix failed",
+      signal
     });
+    signal?.throwIfAborted();
     const data = await readFile3(outputPath);
+    signal?.throwIfAborted();
     return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
   } finally {
     await rm2(workDir, { recursive: true, force: true });
   }
 }
 
+// src/util/capturedFrameBudget.ts
+var MAX_CAPTURED_FRAME_BYTES = 256 * 1024 * 1024;
+var CapturedFrameBudgetError = class extends Error {
+  constructor(capturedBytes, attemptedFrameBytes, maximumBytes) {
+    super(
+      `Captured PNG frames would retain ${capturedBytes + attemptedFrameBytes} bytes, exceeding the ${maximumBytes}-byte rendered-media memory limit.`
+    );
+    this.capturedBytes = capturedBytes;
+    this.attemptedFrameBytes = attemptedFrameBytes;
+    this.maximumBytes = maximumBytes;
+    this.code = "captured-frame-budget-exceeded";
+    this.name = "CapturedFrameBudgetError";
+  }
+};
+var CapturedFrameCollector = class {
+  constructor(maximumBytes = MAX_CAPTURED_FRAME_BYTES) {
+    this.maximumBytes = maximumBytes;
+    this.values = [];
+    this.seen = /* @__PURE__ */ new WeakSet();
+    this.bytes = 0;
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 1 || maximumBytes > MAX_CAPTURED_FRAME_BYTES) {
+      throw new Error(
+        `Captured-frame byte limit must be between 1 and ${MAX_CAPTURED_FRAME_BYTES}`
+      );
+    }
+  }
+  get frameCount() {
+    return this.values.length;
+  }
+  get retainedBytes() {
+    return this.bytes;
+  }
+  append(frame, repetitions = 1) {
+    if (!Number.isSafeInteger(repetitions) || repetitions < 1) {
+      throw new Error("Captured-frame repetition count must be a positive integer");
+    }
+    const additionalBytes = this.seen.has(frame) ? 0 : frame.byteLength;
+    if (this.bytes + additionalBytes > this.maximumBytes) {
+      const capturedBytes = this.bytes;
+      this.clear();
+      throw new CapturedFrameBudgetError(capturedBytes, additionalBytes, this.maximumBytes);
+    }
+    if (additionalBytes > 0) {
+      this.seen.add(frame);
+      this.bytes += additionalBytes;
+    }
+    for (let index = 0; index < repetitions; index += 1) this.values.push(frame);
+  }
+  /** Clear retained frame references before preserving the caller's abort reason. */
+  throwIfAborted(signal) {
+    if (!signal?.aborted) return;
+    this.clear();
+    signal.throwIfAborted();
+  }
+  /** Transfer ownership of the captured frames to the encoder. */
+  release() {
+    const released = this.values;
+    this.values = [];
+    this.seen = /* @__PURE__ */ new WeakSet();
+    this.bytes = 0;
+    return released;
+  }
+  /** Drop every retained reference so failed/cancelled captures can be collected promptly. */
+  clear() {
+    this.values.length = 0;
+    this.values = [];
+    this.seen = /* @__PURE__ */ new WeakSet();
+    this.bytes = 0;
+  }
+};
+
+// src/util/coverPreRoll.ts
+function resolveAppliedCoverPreRoll(requestedSeconds, hasCover) {
+  if (!Number.isFinite(requestedSeconds) || requestedSeconds < 0) {
+    throw new Error("Cover pre-roll must be a finite number of seconds greater than or equal to 0");
+  }
+  return hasCover ? requestedSeconds : 0;
+}
+
 // src/registry.ts
 import { randomBytes } from "crypto";
 import { readFile, rm } from "fs/promises";
@@ -137,7 +241,19 @@ var MP4_DEFAULTS = {
   fps: 30,
   quality: "normal",
   orientation: "landscape",
-  coverPreRoll: 0
+  coverPreRoll: 0,
+  animationsEnabled: true
+};
+var GIF_DEFAULTS = {
+  fps: 10,
+  orientation: "landscape",
+  width: 960,
+  height: 540,
+  coverPreRoll: 0,
+  animationsEnabled: false,
+  loop: 0,
+  maxColors: 256,
+  dither: "sierra2_4a"
 };
 function mp4Format() {
   return {
@@ -146,21 +262,32 @@ function mp4Format() {
     mimeType: "video/mp4",
     extensions: [".mp4"],
     async exportDoc(input, options) {
+      options.signal?.throwIfAborted();
       const mp4Opts = options.formatOptions?.mp4 ?? {};
       const fps = typeof mp4Opts.fps === "number" ? mp4Opts.fps : MP4_DEFAULTS.fps;
       const quality = typeof mp4Opts.quality === "string" ? mp4Opts.quality : MP4_DEFAULTS.quality;
       const orientation = typeof mp4Opts.orientation === "string" ? mp4Opts.orientation : MP4_DEFAULTS.orientation;
       const coverPreRoll = typeof mp4Opts.coverPreRoll === "number" ? mp4Opts.coverPreRoll : MP4_DEFAULTS.coverPreRoll;
+      const animationsEnabled = typeof mp4Opts.animationsEnabled === "boolean" ? mp4Opts.animationsEnabled : MP4_DEFAULTS.animationsEnabled;
       const outputPath = join(tmpdir(), `squisq-mp4-${randomBytes(8).toString("hex")}.mp4`);
       try {
-        await renderDocToMp4(input.doc, input.container, {
+        const { renderDocToMp4: renderDocToMp42 } = await import("./api.js");
+        await renderDocToMp42(input.doc, input.container, {
           outputPath,
           fps,
           quality,
           orientation,
-          coverPreRoll
+          width: mp4Opts.width,
+          height: mp4Opts.height,
+          captionStyle: mp4Opts.captionStyle,
+          coverPreRoll,
+          animationsEnabled,
+          signal: options.signal,
+          onProgress: mp4Opts.onProgress
         });
-        const data = await readFile(outputPath);
+        options.signal?.throwIfAborted();
+        const data = await readFile(outputPath, { signal: options.signal });
+        options.signal?.throwIfAborted();
         const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
         return { bytes, mimeType: "video/mp4", suggestedFilename: "", warnings: [] };
       } finally {
@@ -169,27 +296,69 @@ function mp4Format() {
     }
   };
 }
+function gifFormat() {
+  return {
+    id: "gif",
+    label: "Animated GIF",
+    mimeType: "image/gif",
+    extensions: [".gif"],
+    async exportDoc(input, options) {
+      options.signal?.throwIfAborted();
+      const gifOpts = options.formatOptions?.gif ?? {};
+      const orientation = typeof gifOpts.orientation === "string" ? gifOpts.orientation : GIF_DEFAULTS.orientation;
+      const portrait = orientation === "portrait";
+      const defaultWidth = portrait ? GIF_DEFAULTS.height : GIF_DEFAULTS.width;
+      const defaultHeight = portrait ? GIF_DEFAULTS.width : GIF_DEFAULTS.height;
+      const outputPath = join(tmpdir(), `squisq-gif-${randomBytes(8).toString("hex")}.gif`);
+      try {
+        const { renderDocToGif: renderDocToGif2 } = await import("./api.js");
+        const result = await renderDocToGif2(input.doc, input.container, {
+          outputPath,
+          fps: typeof gifOpts.fps === "number" ? gifOpts.fps : GIF_DEFAULTS.fps,
+          orientation,
+          width: typeof gifOpts.width === "number" ? gifOpts.width : defaultWidth,
+          height: typeof gifOpts.height === "number" ? gifOpts.height : defaultHeight,
+          captionStyle: gifOpts.captionStyle,
+          coverPreRoll: typeof gifOpts.coverPreRoll === "number" ? gifOpts.coverPreRoll : GIF_DEFAULTS.coverPreRoll,
+          animationsEnabled: typeof gifOpts.animationsEnabled === "boolean" ? gifOpts.animationsEnabled : GIF_DEFAULTS.animationsEnabled,
+          loop: typeof gifOpts.loop === "number" ? gifOpts.loop : GIF_DEFAULTS.loop,
+          maxColors: typeof gifOpts.maxColors === "number" ? gifOpts.maxColors : GIF_DEFAULTS.maxColors,
+          dither: gifOpts.dither ?? GIF_DEFAULTS.dither,
+          bayerScale: gifOpts.bayerScale,
+          signal: options.signal,
+          onProgress: gifOpts.onProgress
+        });
+        options.signal?.throwIfAborted();
+        const data = await readFile(outputPath, { signal: options.signal });
+        options.signal?.throwIfAborted();
+        const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        return {
+          bytes,
+          mimeType: "image/gif",
+          suggestedFilename: "",
+          warnings: result.warnings
+        };
+      } finally {
+        await rm(outputPath, { force: true });
+      }
+    }
+  };
+}
 function createCliRegistry() {
   const registry = defaultRegistry();
   registry.register(mp4Format());
+  registry.register(gifFormat());
   return registry;
 }
 
 // src/api.ts
 import { MemoryContentContainer as MemoryContentContainer2 } from "@bendyline/squisq/storage";
 
-// src/util/domPolyfill.ts
-import { DOMParser as XmldomDOMParser } from "@xmldom/xmldom";
-var globalScope = globalThis;
-if (typeof globalScope.DOMParser === "undefined") {
-  globalScope.DOMParser = XmldomDOMParser;
-}
-
 // src/util/readInput.ts
 import { readFile as readFile2, readdir, stat } from "fs/promises";
 import { join as join2, extname } from "path";
 import { parseMarkdown, stringifyMarkdown } from "@bendyline/squisq/markdown";
-import { markdownToDoc } from "@bendyline/squisq/doc";
+import { markdownToDoc, resolveAudioMapping } from "@bendyline/squisq/doc";
 import { MemoryContentContainer } from "@bendyline/squisq/storage";
 import { zipToContainer } from "@bendyline/squisq-formats/container";
 import { defaultRegistry as defaultRegistry2 } from "@bendyline/squisq-formats";
@@ -213,114 +382,187 @@ var IMPORTER_EXTS = [".docx", ".pptx", ".pdf", ".xlsx", ".csv", ".html", ".htm"]
 function mimeFromExt(filePath) {
   return MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
 }
-async function walkDir(root, prefix = "") {
+async function walkDir(root, prefix = "", signal) {
+  throwIfAborted(signal);
   const entries = await readdir(root, { withFileTypes: true });
+  throwIfAborted(signal);
   const paths = [];
   for (const entry of entries) {
+    throwIfAborted(signal);
     const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
-      paths.push(...await walkDir(join2(root, entry.name), relPath));
+      paths.push(...await walkDir(join2(root, entry.name), relPath, signal));
     } else if (entry.isFile()) {
       paths.push(relPath);
     }
   }
   return paths;
 }
-async function readInput(inputPath) {
+async function readInput(inputPath, options) {
+  throwIfAborted(options?.signal);
+  const result = await readInputRaw(inputPath, options);
+  throwIfAborted(options?.signal);
+  const doc = await resolveAudioMapping(result.doc, result.container);
+  throwIfAborted(options?.signal);
+  return doc === result.doc ? result : { ...result, doc };
+}
+async function readInputRaw(inputPath, options) {
+  throwIfAborted(options?.signal);
   const info = await stat(inputPath);
+  throwIfAborted(options?.signal);
   if (info.isDirectory()) {
-    return readFolder(inputPath);
+    return readFolder(inputPath, options?.signal);
   }
   const ext = extname(inputPath).toLowerCase();
   if (ext === ".zip" || ext === ".dbk") {
-    return readContainer(inputPath);
+    return readContainer(inputPath, options?.signal);
   }
   if (ext === ".json") {
-    return readDocJsonFile(inputPath);
+    return readDocJsonFile(inputPath, options?.signal);
   }
   if (IMPORTER_EXTS.includes(ext)) {
     const def = defaultRegistry2().byExtension(ext);
     if (def && (def.importContainer || def.importDoc)) {
-      return readViaImporter(inputPath, def);
+      return readViaImporter(inputPath, def, options);
     }
   }
-  return readMarkdownFile(inputPath);
+  return readMarkdownFile(inputPath, options?.signal);
 }
-async function readArrayBuffer(filePath) {
-  const data = await readFile2(filePath);
+async function readArrayBuffer(filePath, signal) {
+  const data = await readBinaryFile(filePath, signal);
   return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
 }
-async function readMarkdownFile(filePath) {
-  const content = await readFile2(filePath, "utf-8");
+async function readBinaryFile(filePath, signal) {
+  throwIfAborted(signal);
+  try {
+    const data = await readFile2(filePath, { signal });
+    throwIfAborted(signal);
+    return data;
+  } catch (error) {
+    throwIfAborted(signal);
+    throw error;
+  }
+}
+async function readUtf8File(filePath, signal) {
+  throwIfAborted(signal);
+  try {
+    const content = await readFile2(filePath, { encoding: "utf-8", signal });
+    throwIfAborted(signal);
+    return content;
+  } catch (error) {
+    throwIfAborted(signal);
+    throw error;
+  }
+}
+async function readMarkdownFile(filePath, signal) {
+  const content = await readUtf8File(filePath, signal);
   const container = new MemoryContentContainer();
   await container.writeDocument(content);
+  throwIfAborted(signal);
   const markdownDoc = parseMarkdown(content);
   return { doc: markdownToDoc(markdownDoc), container, markdownDoc, sourceFormat: "md" };
 }
-async function readDocJsonFile(filePath) {
-  const content = await readFile2(filePath, "utf-8");
+async function readDocJsonFile(filePath, signal) {
+  const content = await readUtf8File(filePath, signal);
   const doc = JSON.parse(content);
   const container = new MemoryContentContainer();
   return { doc, container, sourceFormat: "json" };
 }
-async function readViaImporter(filePath, def) {
-  const buffer = await readArrayBuffer(filePath);
+async function readViaImporter(filePath, def, options) {
+  const signal = options?.signal;
+  throwIfAborted(signal);
+  const buffer = await readArrayBuffer(filePath, signal);
+  const convertOptions = {
+    signal,
+    formatOptions: {
+      [def.id]: {
+        inferTheme: options?.inferTheme !== false,
+        inferLayouts: options?.inferLayouts !== false
+      }
+    }
+  };
   let container;
   let markdownDoc;
   if (def.importContainer) {
-    container = await def.importContainer(buffer, {});
+    throwIfAborted(signal);
+    container = await def.importContainer(buffer, convertOptions);
+    throwIfAborted(signal);
     const text = await container.readDocument();
+    throwIfAborted(signal);
     markdownDoc = text ? parseMarkdown(text) : { type: "document", children: [] };
   } else {
-    markdownDoc = await def.importDoc(buffer, {});
+    throwIfAborted(signal);
+    markdownDoc = await def.importDoc(buffer, convertOptions);
+    throwIfAborted(signal);
     const mem = new MemoryContentContainer();
     await mem.writeDocument(stringifyMarkdown(markdownDoc));
+    throwIfAborted(signal);
     container = mem;
   }
   return { doc: markdownToDoc(markdownDoc), container, markdownDoc, sourceFormat: def.id };
 }
 var DOC_JSON_NAMES = ["doc.json", "story.json"];
-async function resolveContainer(container, sourceFormat, missingMessage) {
+async function resolveContainer(container, sourceFormat, missingMessage, signal) {
   for (const name of DOC_JSON_NAMES) {
+    throwIfAborted(signal);
     const jsonData = await container.readFile(name);
+    throwIfAborted(signal);
     if (jsonData) {
       const doc = JSON.parse(new TextDecoder().decode(jsonData));
       return { doc, container, sourceFormat };
     }
   }
+  throwIfAborted(signal);
   const markdown = await container.readDocument();
+  throwIfAborted(signal);
   if (!markdown) {
     throw new Error(missingMessage);
   }
   const markdownDoc = parseMarkdown(markdown);
   return { doc: markdownToDoc(markdownDoc), container, markdownDoc, sourceFormat };
 }
-async function readContainer(filePath) {
-  const container = await zipToContainer(await readArrayBuffer(filePath));
+async function readContainer(filePath, signal) {
+  throwIfAborted(signal);
+  const container = await zipToContainer(await readArrayBuffer(filePath, signal));
+  throwIfAborted(signal);
   return resolveContainer(
     container,
     "dbk",
-    `No markdown document or doc.json found in container: ${filePath}`
+    `No markdown document or doc.json found in container: ${filePath}`,
+    signal
   );
 }
-async function readFolder(dirPath) {
+async function readFolder(dirPath, signal) {
+  throwIfAborted(signal);
   const container = new MemoryContentContainer();
-  const files = await walkDir(dirPath);
+  const files = await walkDir(dirPath, "", signal);
+  throwIfAborted(signal);
   for (const relPath of files) {
+    throwIfAborted(signal);
     const absPath = join2(dirPath, relPath);
-    const data = await readFile2(absPath);
+    const data = await readBinaryFile(absPath, signal);
+    throwIfAborted(signal);
     await container.writeFile(
       relPath,
       new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
       mimeFromExt(relPath)
     );
+    throwIfAborted(signal);
   }
   return resolveContainer(
     container,
     "folder",
-    `No markdown document or doc.json found in folder: ${dirPath}`
+    `No markdown document or doc.json found in folder: ${dirPath}`,
+    signal
   );
 }
+function throwIfAborted(signal) {
+  if (!signal?.aborted) return;
+  if (signal.reason !== void 0) throw signal.reason;
+  const error = new Error("Input reading was cancelled");
+  error.name = "AbortError";
+  throw error;
+}
 
 // src/api.ts
 import { ConversionError } from "@bendyline/squisq-formats";
@@ -331,201 +573,356 @@ async function convert(source, to, options = {}) {
     ...options
   });
 }
-async function renderDocToMp4(doc, container, options) {
-  const {
-    outputPath,
-    fps = 30,
-    quality = "normal",
-    orientation = "landscape",
-    captionStyle,
-    coverPreRoll = 0,
-    onProgress
-  } = options;
-  const dimensions = resolveDimensions({
-    orientation,
-    width: options.width,
-    height: options.height
+async function prepareConversion(source, options = {}) {
+  return formatsPrepareConversion(source, {
+    registry: createCliRegistry(),
+    resolvePlayerScript: () => import("@bendyline/squisq-react/standalone-source").then((m) => m.PLAYER_BUNDLE),
+    ...options
   });
-  const ffmpegPath = await detectFfmpeg();
+}
+async function captureDocFrames(doc, container, options) {
+  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress, signal } = options;
+  signal?.throwIfAborted();
+  resolveAppliedCoverPreRoll(coverPreRoll, true);
+  const ffmpegPath = (await detectFfmpegDetailed(signal))?.path ?? null;
+  signal?.throwIfAborted();
   if (!ffmpegPath) {
     throw new Error(
       "ffmpeg is required but not found in PATH.\nInstall it with:\n  macOS:   brew install ffmpeg\n  Ubuntu:  sudo apt install ffmpeg\n  Windows: winget install ffmpeg\nOr: npm install ffmpeg-static, or set SQUISQ_FFMPEG to an ffmpeg binary."
     );
   }
   onProgress?.("collecting media", 0);
+  signal?.throwIfAborted();
   const { collectImagePaths } = await import("@bendyline/squisq-formats/html");
-  const imagePaths = collectImagePaths(doc);
+  signal?.throwIfAborted();
   const images = /* @__PURE__ */ new Map();
-  for (const imgPath of imagePaths) {
+  for (const imgPath of collectImagePaths(doc)) {
+    signal?.throwIfAborted();
     const data = await container.readFile(imgPath);
-    if (data) {
-      images.set(imgPath, data);
-    }
+    signal?.throwIfAborted();
+    if (data) images.set(imgPath, data);
   }
   const audio = /* @__PURE__ */ new Map();
-  if (doc.audio?.segments?.length) {
-    for (const seg of doc.audio.segments) {
-      const data = await container.readFile(seg.src);
-      if (data) {
-        audio.set(seg.src, data);
-        audio.set(seg.name, data);
-      }
+  for (const seg of doc.audio?.segments ?? []) {
+    signal?.throwIfAborted();
+    const data = await container.readFile(seg.src);
+    signal?.throwIfAborted();
+    if (data) {
+      audio.set(seg.src, data);
+      audio.set(seg.name, data);
     }
   }
-  const mediaSrcs = new Set(resolveMediaSchedule(doc).map((c) => c.src));
+  const mediaSrcs = new Set(resolveMediaSchedule(doc).map((clip) => clip.src));
   for (const block of flattenBlocks(doc.blocks)) {
     for (const layer of block.layers ?? []) {
       if (layer.type === "video") mediaSrcs.add(layer.content.src);
     }
   }
   for (const src of mediaSrcs) {
+    signal?.throwIfAborted();
     if (images.has(src)) continue;
     const data = await container.readFile(src);
+    signal?.throwIfAborted();
     if (data) images.set(src, data);
   }
   onProgress?.("generating render HTML", 10);
+  signal?.throwIfAborted();
   const { PLAYER_BUNDLE } = await import("@bendyline/squisq-react/standalone-source");
+  signal?.throwIfAborted();
   const renderHtml = generateRenderHtml(doc, {
     playerScript: PLAYER_BUNDLE,
     images,
     audio: audio.size > 0 ? audio : void 0,
-    width: dimensions.width,
-    height: dimensions.height,
-    captionStyle
+    width,
+    height,
+    captionStyle,
+    animationsEnabled
   });
   onProgress?.("launching browser", 15);
+  signal?.throwIfAborted();
   const { chromium } = await import("playwright-core");
+  signal?.throwIfAborted();
   let browser;
   try {
     browser = await chromium.launch({ headless: true });
   } catch (err) {
+    signal?.throwIfAborted();
     const detail = err instanceof Error ? err.message.split("\n")[0] : String(err);
     throw new Error(
       `Playwright Chromium is not installed. Run: npx playwright install chromium
 (launch failed: ${detail})`
     );
   }
-  const page = await browser.newPage({
-    viewport: { width: dimensions.width, height: dimensions.height }
-  });
-  const pageErrors = [];
-  page.on("pageerror", (err) => pageErrors.push(err.message));
-  await page.setContent(renderHtml, { waitUntil: "load" });
-  await page.waitForTimeout(500);
+  const handleAbort = () => {
+    void browser.close().catch(() => void 0);
+  };
+  if (signal?.aborted) {
+    await browser.close().catch(() => void 0);
+    signal.throwIfAborted();
+  }
+  signal?.addEventListener("abort", handleAbort, { once: true });
+  let renderAPI = null;
+  const capturedFrames = new CapturedFrameCollector();
   try {
-    await page.waitForFunction(
-      () => typeof window.getDuration === "function",
-      { timeout: 15e3 }
-    );
-  } catch {
-    await browser.close();
-    const errorDetail = pageErrors.length ? `
+    const page = await browser.newPage({ viewport: { width, height } });
+    const pageErrors = [];
+    page.on("pageerror", (err) => pageErrors.push(err.message));
+    signal?.throwIfAborted();
+    await page.setContent(renderHtml, { waitUntil: "load" });
+    signal?.throwIfAborted();
+    await page.waitForTimeout(500);
+    signal?.throwIfAborted();
+    try {
+      await page.waitForFunction(
+        () => {
+          const root = document.getElementById("squisq-root");
+          const player = window.SquisqPlayer;
+          return root ? player?.getHandle(root)?.getRenderAPI() != null : false;
+        },
+        { timeout: 15e3 }
+      );
+    } catch {
+      signal?.throwIfAborted();
+      const errorDetail = pageErrors.length ? `
 Page errors:
   ${pageErrors.join("\n  ")}` : "\nNo page errors captured \u2014 the player may have failed to mount.";
-    throw new Error(
-      `The standalone player failed to boot in headless Chromium. Render API did not initialize within 15 seconds.${errorDetail}`
-    );
-  }
-  const docDuration = await page.evaluate(() => {
-    return window.getDuration();
-  });
-  if (docDuration <= 0) {
-    await browser.close();
-    throw new Error("Document has zero duration \u2014 nothing to render");
-  }
-  const storyFrameCount = Math.ceil(docDuration * fps);
-  const preRollFrameCount = Math.ceil(coverPreRoll * fps);
-  const totalFrames = preRollFrameCount + storyFrameCount;
-  const frames = [];
-  onProgress?.("capturing frames", 20);
-  if (preRollFrameCount > 0) {
-    const hasCover = await page.evaluate(() => {
-      const w = window;
-      return typeof w.hasCoverBlock === "function" ? w.hasCoverBlock() : false;
+      throw new Error(
+        `The standalone player failed to boot in headless Chromium. Render API did not initialize within 15 seconds.${errorDetail}`
+      );
+    }
+    renderAPI = await page.evaluateHandle(() => {
+      const root = document.getElementById("squisq-root");
+      const player = window.SquisqPlayer;
+      const api = root ? player?.getHandle(root)?.getRenderAPI() : null;
+      if (!api) throw new Error("Squisq render API disappeared after initialization.");
+      return api;
     });
-    if (hasCover) {
-      await page.evaluate(() => {
-        window.showCover();
-      });
+    signal?.throwIfAborted();
+    const docDuration = await renderAPI.evaluate((api) => api.getDuration());
+    signal?.throwIfAborted();
+    if (docDuration <= 0) throw new Error("Document has zero duration \u2014 nothing to render");
+    const hasCover = coverPreRoll > 0 ? await renderAPI.evaluate((api) => api.hasCoverBlock()) : false;
+    const appliedCoverPreRoll = resolveAppliedCoverPreRoll(coverPreRoll, hasCover);
+    const storyFrameCount = Math.ceil(docDuration * fps);
+    const preRollFrameCount = Math.ceil(appliedCoverPreRoll * fps);
+    const totalFrames = preRollFrameCount + storyFrameCount;
+    onProgress?.("capturing frames", 20);
+    capturedFrames.throwIfAborted(signal);
+    if (preRollFrameCount > 0) {
+      capturedFrames.throwIfAborted(signal);
+      await renderAPI.evaluate((api) => api.showCover());
       await page.waitForTimeout(100);
-      const coverFrame = new Uint8Array(await page.screenshot({ type: "png" }));
-      for (let i = 0; i < preRollFrameCount; i++) {
-        frames.push(coverFrame);
-      }
-      await page.evaluate(() => {
-        window.hideCover();
-      });
+      capturedFrames.throwIfAborted(signal);
+      const coverFrame = await page.screenshot({ type: "png" });
+      capturedFrames.throwIfAborted(signal);
+      capturedFrames.append(coverFrame, preRollFrameCount);
+      await renderAPI.evaluate((api) => api.hideCover());
     }
-  }
-  const frameInterval = 1 / fps;
-  for (let i = 0; i < storyFrameCount; i++) {
-    const time = i * frameInterval;
-    await page.evaluate((t) => {
-      return window.seekTo(t);
-    }, time);
-    const screenshot = await page.screenshot({ type: "png" });
-    frames.push(new Uint8Array(screenshot));
-    if (i % Math.max(1, Math.floor(fps / 2)) === 0 || i === storyFrameCount - 1) {
-      const pct = 20 + Math.round(frames.length / totalFrames * 60);
-      onProgress?.("capturing frames", pct);
+    const frameInterval = 1 / fps;
+    for (let i = 0; i < storyFrameCount; i++) {
+      capturedFrames.throwIfAborted(signal);
+      const time = i * frameInterval;
+      await renderAPI.evaluate((api, t) => api.seekTo(t), time);
+      const frame = await page.screenshot({ type: "png" });
+      capturedFrames.throwIfAborted(signal);
+      capturedFrames.append(frame);
+      if (i % Math.max(1, Math.floor(fps / 2)) === 0 || i === storyFrameCount - 1) {
+        onProgress?.(
+          "capturing frames",
+          20 + Math.round(capturedFrames.frameCount / totalFrames * 60)
+        );
+        capturedFrames.throwIfAborted(signal);
+      }
     }
+    return {
+      frames: capturedFrames.release(),
+      totalDuration: docDuration + appliedCoverPreRoll,
+      appliedCoverPreRoll,
+      ffmpegPath
+    };
+  } catch (err) {
+    capturedFrames.clear();
+    signal?.throwIfAborted();
+    throw err;
+  } finally {
+    signal?.removeEventListener("abort", handleAbort);
+    await renderAPI?.dispose().catch(() => void 0);
+    await browser.close().catch(() => void 0);
   }
-  await browser.close();
-  onProgress?.("encoding video", 80);
-  const encodingAudio = await buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll);
-  const { framesToMp4Native } = await import("./nativeEncoder-2HGWDEZZ.js");
-  await framesToMp4Native(ffmpegPath, frames, encodingAudio, outputPath, {
-    fps,
-    quality,
+}
+async function renderDocToMp4(doc, container, options) {
+  options.signal?.throwIfAborted();
+  const fps = options.fps ?? 30;
+  const quality = options.quality ?? "normal";
+  const orientation = options.orientation ?? "landscape";
+  const dimensions = resolveDimensions({
     orientation,
+    width: options.width,
+    height: options.height,
+    fps,
+    quality
+  });
+  const capture = await captureDocFrames(doc, container, {
+    fps,
     width: dimensions.width,
     height: dimensions.height,
-    onProgress: (percent, phase) => {
-      onProgress?.(`encoding: ${phase}`, 80 + Math.round(percent * 0.2));
-    }
+    captionStyle: options.captionStyle,
+    coverPreRoll: options.coverPreRoll ?? 0,
+    animationsEnabled: options.animationsEnabled ?? true,
+    onProgress: options.onProgress,
+    signal: options.signal
   });
-  onProgress?.("done", 100);
-  const totalDuration = docDuration + coverPreRoll;
-  return {
-    duration: totalDuration,
-    frameCount: frames.length,
-    outputPath
-  };
+  const frameCount = capture.frames.length;
+  try {
+    options.onProgress?.("encoding video", 80);
+    options.signal?.throwIfAborted();
+    const encodingAudio = await buildMixedAudioTrack(
+      doc,
+      container,
+      capture.ffmpegPath,
+      capture.appliedCoverPreRoll,
+      options.signal
+    );
+    options.signal?.throwIfAborted();
+    const { framesToMp4Native: framesToMp4Native2 } = await import("./nativeEncoder-ET3HUSOE.js");
+    await framesToMp4Native2(capture.ffmpegPath, capture.frames, encodingAudio, options.outputPath, {
+      fps,
+      quality,
+      orientation,
+      width: dimensions.width,
+      height: dimensions.height,
+      signal: options.signal,
+      onProgress: (percent, phase) => options.onProgress?.(`encoding: ${phase}`, 80 + Math.round(percent * 0.2))
+    });
+    options.signal?.throwIfAborted();
+    options.onProgress?.("done", 100);
+    options.signal?.throwIfAborted();
+    return {
+      duration: capture.totalDuration,
+      frameCount,
+      outputPath: options.outputPath
+    };
+  } finally {
+    capture.frames.length = 0;
+  }
+}
+async function renderDocToGif(doc, container, options) {
+  options.signal?.throwIfAborted();
+  const fps = options.fps ?? GIF_EXPORT_DEFAULTS.fps;
+  if (!Number.isFinite(fps) || fps <= 0 || fps > 100) {
+    throw new RangeError("GIF FPS must be a finite number between 1 and 100.");
+  }
+  const orientation = options.orientation ?? "landscape";
+  const portrait = orientation === "portrait";
+  const width = options.width ?? (portrait ? GIF_EXPORT_DEFAULTS.height : GIF_EXPORT_DEFAULTS.width);
+  const height = options.height ?? (portrait ? GIF_EXPORT_DEFAULTS.width : GIF_EXPORT_DEFAULTS.height);
+  resolveDimensions({ orientation, width, height, fps });
+  ffmpegGifOutputArgs({
+    width,
+    height,
+    loop: options.loop ?? GIF_EXPORT_DEFAULTS.loop,
+    maxColors: options.maxColors ?? GIF_EXPORT_DEFAULTS.maxColors,
+    dither: options.dither ?? GIF_EXPORT_DEFAULTS.dither,
+    bayerScale: options.bayerScale
+  });
+  const capture = await captureDocFrames(doc, container, {
+    fps,
+    width,
+    height,
+    captionStyle: options.captionStyle,
+    coverPreRoll: options.coverPreRoll ?? 0,
+    animationsEnabled: options.animationsEnabled ?? false,
+    onProgress: options.onProgress,
+    signal: options.signal
+  });
+  const frameCount = capture.frames.length;
+  try {
+    options.onProgress?.("encoding GIF", 80);
+    options.signal?.throwIfAborted();
+    const { framesToGifNative: framesToGifNative2 } = await import("./nativeEncoder-ET3HUSOE.js");
+    await framesToGifNative2(capture.ffmpegPath, capture.frames, options.outputPath, {
+      fps,
+      orientation,
+      width,
+      height,
+      loop: options.loop,
+      maxColors: options.maxColors,
+      dither: options.dither,
+      bayerScale: options.bayerScale,
+      signal: options.signal,
+      onProgress: (percent, phase) => options.onProgress?.(`encoding: ${phase}`, 80 + Math.round(percent * 0.2))
+    });
+    options.signal?.throwIfAborted();
+    options.onProgress?.("done", 100);
+    options.signal?.throwIfAborted();
+    const hasAudio = (doc.audio?.segments?.length ?? 0) > 0 || resolveMediaSchedule(doc).some((clip) => clip.kind === "audio");
+    return {
+      duration: capture.totalDuration,
+      frameCount,
+      outputPath: options.outputPath,
+      warnings: hasAudio ? ["Animated GIF does not support audio; audio tracks were omitted."] : []
+    };
+  } finally {
+    capture.frames.length = 0;
+  }
 }
 async function extractThumbnails(options) {
-  const { videoPath, outputDir, slug, sizes, force } = options;
+  const { videoPath, outputDir, slug, sizes, force, signal } = options;
   const { existsSync } = await import("fs");
+  const { rm: rm2 } = await import("fs/promises");
   const { join: join3 } = await import("path");
-  const { execFile: execFile2 } = await import("child_process");
-  const ffmpegPath = await detectFfmpeg();
+  signal?.throwIfAborted();
+  const ffmpegPath = (await detectFfmpegDetailed(signal))?.path ?? null;
   if (!ffmpegPath) {
     throw new Error(
       "ffmpeg is required for thumbnail extraction but not found in PATH.\nInstall it with:\n  macOS:   brew install ffmpeg\n  Ubuntu:  sudo apt install ffmpeg\n  Windows: winget install ffmpeg"
     );
   }
-  for (const thumb of sizes) {
-    const outputPath = join3(outputDir, `${slug}-${thumb.width}x${thumb.height}.jpg`);
-    if (!force && existsSync(outputPath)) continue;
-    await new Promise((resolve, reject) => {
-      execFile2(
-        ffmpegPath,
-        ["-y", "-i", videoPath, "-vf", thumb.filter, "-frames:v", "1", "-q:v", "2", outputPath],
-        { timeout: 3e4 },
-        (err) => {
-          if (err) reject(new Error(`Thumbnail extraction failed (${thumb.name}): ${err.message}`));
-          else resolve();
-        }
-      );
-    });
+  const generatedPaths = [];
+  try {
+    for (const thumb of sizes) {
+      signal?.throwIfAborted();
+      const outputPath = join3(outputDir, `${slug}-${thumb.width}x${thumb.height}.jpg`);
+      if (!force && existsSync(outputPath)) continue;
+      try {
+        await runFfmpeg(
+          ffmpegPath,
+          ["-y", "-i", videoPath, "-vf", thumb.filter, "-frames:v", "1", "-q:v", "2", outputPath],
+          {
+            timeoutMs: 3e4,
+            failureMessage: `Thumbnail extraction failed (${thumb.name})`,
+            signal
+          }
+        );
+        signal?.throwIfAborted();
+        generatedPaths.push(outputPath);
+      } catch (error) {
+        await rm2(outputPath, { force: true });
+        throw error;
+      }
+    }
+    signal?.throwIfAborted();
+  } catch (error) {
+    await Promise.allSettled(generatedPaths.map((path) => rm2(path, { force: true })));
+    throw error;
   }
 }
 export {
+  CapturedFrameBudgetError,
   ConversionError,
+  GIF_EXPORT_DEFAULTS,
+  MAX_CAPTURED_FRAME_BYTES,
   MemoryContentContainer2 as MemoryContentContainer,
   convert,
   createCliRegistry,
   extractThumbnails,
+  framesToGifNative,
+  framesToGifNativeBytes,
+  framesToMp4Native,
+  framesToMp4NativeBytes,
+  prepareConversion,
   readInput,
+  renderDocToGif,
   renderDocToMp4
 };
 //# sourceMappingURL=api.js.map