@bendyline/squisq-cli 2.0.0 → 2.0.1

package/dist/api.js

@@ -3,21 +3,30 @@ import {
   framesToGifNative,
   framesToGifNativeBytes,
   framesToMp4Native,
-  framesToMp4NativeBytes
-} from "./chunk-ESFEFKY4.js";
+  framesToMp4NativeBytes,
+  runFfmpeg
+} from "./chunk-OEN2RADG.js";
 
 // src/api.ts
 import { resolveMediaSchedule } from "@bendyline/squisq/schemas";
 import { flattenBlocks } from "@bendyline/squisq/doc";
 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;
@@ -26,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.`
@@ -42,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;
@@ -54,46 +65,55 @@ async function detectFfmpegDetailed() {
       return { path: candidate, source: "ffmpeg-static" };
     }
   } catch {
+    signal?.throwIfAborted();
   }
+  signal?.throwIfAborted();
   return 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);
@@ -118,19 +138,91 @@ 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) {
@@ -170,6 +262,7 @@ 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;
@@ -188,9 +281,13 @@ function mp4Format() {
           height: mp4Opts.height,
           captionStyle: mp4Opts.captionStyle,
           coverPreRoll,
-          animationsEnabled
+          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 {
@@ -206,6 +303,7 @@ function gifFormat() {
     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";
@@ -226,9 +324,13 @@ function gifFormat() {
           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
+          bayerScale: gifOpts.bayerScale,
+          signal: options.signal,
+          onProgress: gifOpts.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,
@@ -280,13 +382,16 @@ 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);
     }
@@ -294,21 +399,26 @@ async function walkDir(root, prefix = "") {
   return paths;
 }
 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);
@@ -316,28 +426,54 @@ async function readInputRaw(inputPath, options) {
       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, options) {
-  const buffer = await readArrayBuffer(filePath);
+  const signal = options?.signal;
+  throwIfAborted(signal);
+  const buffer = await readArrayBuffer(filePath, signal);
   const convertOptions = {
+    signal,
     formatOptions: {
       [def.id]: {
         inferTheme: options?.inferTheme !== false,
@@ -348,59 +484,85 @@ async function readViaImporter(filePath, def, options) {
   let container;
   let markdownDoc;
   if (def.importContainer) {
+    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 {
+    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";
@@ -411,25 +573,40 @@ async function convert(source, to, options = {}) {
     ...options
   });
 }
+async function prepareConversion(source, options = {}) {
+  return formatsPrepareConversion(source, {
+    registry: createCliRegistry(),
+    resolvePlayerScript: () => import("@bendyline/squisq-react/standalone-source").then((m) => m.PLAYER_BUNDLE),
+    ...options
+  });
+}
 async function captureDocFrames(doc, container, options) {
-  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress } = options;
+  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress, signal } = options;
+  signal?.throwIfAborted();
   resolveAppliedCoverPreRoll(coverPreRoll, true);
-  const ffmpegPath = (await detectFfmpegDetailed())?.path ?? null;
+  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");
+  signal?.throwIfAborted();
   const images = /* @__PURE__ */ new Map();
   for (const imgPath of collectImagePaths(doc)) {
+    signal?.throwIfAborted();
     const data = await container.readFile(imgPath);
+    signal?.throwIfAborted();
     if (data) images.set(imgPath, data);
   }
   const audio = /* @__PURE__ */ new Map();
   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);
@@ -442,12 +619,16 @@ async function captureDocFrames(doc, container, options) {
     }
   }
   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,
@@ -458,24 +639,39 @@ async function captureDocFrames(doc, container, options) {
     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, height } });
-  const pageErrors = [];
-  page.on("pageerror", (err) => pageErrors.push(err.message));
+  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 {
+    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(
         () => {
@@ -486,6 +682,7 @@ async function captureDocFrames(doc, container, options) {
         { 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.";
@@ -500,43 +697,61 @@ Page errors:
       if (!api) throw new Error("Squisq render API disappeared after initialization.");
       return api;
     });
+    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;
-    const frames = [];
     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);
+      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++) {
+      capturedFrames.throwIfAborted(signal);
       const time = i * frameInterval;
       await renderAPI.evaluate((api, t) => api.seekTo(t), time);
-      frames.push(new Uint8Array(await page.screenshot({ type: "png" })));
+      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(frames.length / totalFrames * 60));
+        onProgress?.(
+          "capturing frames",
+          20 + Math.round(capturedFrames.frameCount / totalFrames * 60)
+        );
+        capturedFrames.throwIfAborted(signal);
       }
     }
     return {
-      frames,
+      frames: capturedFrames.release(),
       totalDuration: docDuration + appliedCoverPreRoll,
       appliedCoverPreRoll,
       ffmpegPath
     };
+  } catch (err) {
+    capturedFrames.clear();
+    signal?.throwIfAborted();
+    throw err;
   } finally {
-    await renderAPI?.dispose();
-    await browser.close();
+    signal?.removeEventListener("abort", handleAbort);
+    await renderAPI?.dispose().catch(() => void 0);
+    await browser.close().catch(() => void 0);
   }
 }
 async function renderDocToMp4(doc, container, options) {
+  options.signal?.throwIfAborted();
   const fps = options.fps ?? 30;
   const quality = options.quality ?? "normal";
   const orientation = options.orientation ?? "landscape";
@@ -554,32 +769,45 @@ async function renderDocToMp4(doc, container, options) {
     captionStyle: options.captionStyle,
     coverPreRoll: options.coverPreRoll ?? 0,
     animationsEnabled: options.animationsEnabled ?? true,
-    onProgress: options.onProgress
+    onProgress: options.onProgress,
+    signal: options.signal
   });
-  options.onProgress?.("encoding video", 80);
-  const encodingAudio = await buildMixedAudioTrack(
-    doc,
-    container,
-    capture.ffmpegPath,
-    capture.appliedCoverPreRoll
-  );
-  const { framesToMp4Native: framesToMp4Native2 } = await import("./nativeEncoder-IQPN2RMC.js");
-  await framesToMp4Native2(capture.ffmpegPath, capture.frames, encodingAudio, options.outputPath, {
-    fps,
-    quality,
-    orientation,
-    width: dimensions.width,
-    height: dimensions.height,
-    onProgress: (percent, phase) => options.onProgress?.(`encoding: ${phase}`, 80 + Math.round(percent * 0.2))
-  });
-  options.onProgress?.("done", 100);
-  return {
-    duration: capture.totalDuration,
-    frameCount: capture.frames.length,
-    outputPath: options.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.");
@@ -604,60 +832,86 @@ async function renderDocToGif(doc, container, options) {
     captionStyle: options.captionStyle,
     coverPreRoll: options.coverPreRoll ?? 0,
     animationsEnabled: options.animationsEnabled ?? false,
-    onProgress: options.onProgress
-  });
-  options.onProgress?.("encoding GIF", 80);
-  const { framesToGifNative: framesToGifNative2 } = await import("./nativeEncoder-IQPN2RMC.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,
-    onProgress: (percent, phase) => options.onProgress?.(`encoding: ${phase}`, 80 + Math.round(percent * 0.2))
+    onProgress: options.onProgress,
+    signal: options.signal
   });
-  options.onProgress?.("done", 100);
-  const hasAudio = (doc.audio?.segments?.length ?? 0) > 0 || resolveMediaSchedule(doc).some((clip) => clip.kind === "audio");
-  return {
-    duration: capture.totalDuration,
-    frameCount: capture.frames.length,
-    outputPath: options.outputPath,
-    warnings: hasAudio ? ["Animated GIF does not support audio; audio tracks were omitted."] : []
-  };
+  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 detectFfmpegDetailed())?.path ?? null;
+  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,
@@ -666,6 +920,7 @@ export {
   framesToGifNativeBytes,
   framesToMp4Native,
   framesToMp4NativeBytes,
+  prepareConversion,
   readInput,
   renderDocToGif,
   renderDocToMp4