@bendyline/squisq-cli 2.0.0 → 2.0.1

package/dist/{api-6KN3F6IQ.js → api-LE75OSRQ.js}

@@ -1,24 +1,29 @@
 #!/usr/bin/env node
 import {
+  CapturedFrameBudgetError,
   ConversionError,
+  MAX_CAPTURED_FRAME_BYTES,
   MemoryContentContainer,
   convert,
   createCliRegistry,
   extractThumbnails,
+  prepareConversion,
   readInput,
   renderDocToGif,
   renderDocToMp4
-} from "./chunk-JEE26SZS.js";
+} from "./chunk-FVFK4ZJU.js";
 import {
   GIF_EXPORT_DEFAULTS,
   framesToGifNative,
   framesToGifNativeBytes,
   framesToMp4Native,
   framesToMp4NativeBytes
-} from "./chunk-VM3ZFP3J.js";
+} from "./chunk-JDHONKFZ.js";
 export {
+  CapturedFrameBudgetError,
   ConversionError,
   GIF_EXPORT_DEFAULTS,
+  MAX_CAPTURED_FRAME_BYTES,
   MemoryContentContainer,
   convert,
   createCliRegistry,
@@ -27,8 +32,9 @@ export {
   framesToGifNativeBytes,
   framesToMp4Native,
   framesToMp4NativeBytes,
+  prepareConversion,
   readInput,
   renderDocToGif,
   renderDocToMp4
 };
-//# sourceMappingURL=api-6KN3F6IQ.js.map
+//# sourceMappingURL=api-LE75OSRQ.js.map

package/dist/api.d.ts

@@ -3,8 +3,8 @@ import { ContentContainer } from '@bendyline/squisq/storage';
 export { MemoryContentContainer } from '@bendyline/squisq/storage';
 import { VideoQuality, VideoOrientation, GifDither, VideoExportOptions } from '@bendyline/squisq-video';
 export { GifDither, VideoOrientation, VideoQuality } from '@bendyline/squisq-video';
-import { FormatRegistry, FormatId, ConvertOptions, ConvertSource, ConversionResult } from '@bendyline/squisq-formats';
-export { ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionResult, ConvertOptions, ConvertSource, FormatDefinition, FormatId, FormatRegistry, NormalizedInput } from '@bendyline/squisq-formats';
+import { FormatRegistry, FormatId, ConvertOptions, ConvertSource, ConversionResult, PreparedConversion } from '@bendyline/squisq-formats';
+export { ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionResult, ConvertOptions, ConvertSource, FormatDefinition, FormatId, FormatRegistry, NormalizedInput, PreparedConversion, PreparedExportOptions } from '@bendyline/squisq-formats';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
 
 /**
@@ -17,6 +17,7 @@ import { MarkdownDocument } from '@bendyline/squisq/markdown';
  */
 
 interface Mp4FormatOptions {
+    onProgress?: (phase: string, percent: number) => void;
     fps?: number;
     quality?: VideoQuality;
     orientation?: VideoOrientation;
@@ -28,6 +29,7 @@ interface Mp4FormatOptions {
 }
 /** Per-export options for `convert(..., 'gif')`. */
 interface GifFormatOptions {
+    onProgress?: (phase: string, percent: number) => void;
     fps?: number;
     orientation?: VideoOrientation;
     width?: number;
@@ -77,6 +79,8 @@ interface ReadInputResult {
     sourceFormat: FormatId;
 }
 interface ReadInputOptions {
+    /** Cancel filesystem traversal, import, or audio resolution at a bounded boundary. */
+    signal?: AbortSignal;
     /**
      * Infer a Squisq theme from an OOXML source's theme part (PPTX today).
      * Default true — the importer carries it as frontmatter.
@@ -92,6 +96,24 @@ interface ReadInputOptions {
  */
 declare function readInput(inputPath: string, options?: ReadInputOptions): Promise<ReadInputResult>;
 
+/**
+ * Hard retained-memory ceiling for PNG frames captured before native encoding.
+ *
+ * The Node renderer currently keeps captured PNGs in memory while FFmpeg is
+ * prepared. Bounding the actual encoded PNG bytes prevents visually complex
+ * documents from exhausting the process even when their dimensions and frame
+ * counts satisfy higher-level render budgets.
+ */
+declare const MAX_CAPTURED_FRAME_BYTES: number;
+/** Stable failure raised before another captured frame is retained. */
+declare class CapturedFrameBudgetError extends Error {
+    readonly capturedBytes: number;
+    readonly attemptedFrameBytes: number;
+    readonly maximumBytes: number;
+    readonly code = "captured-frame-budget-exceeded";
+    constructor(capturedBytes: number, attemptedFrameBytes: number, maximumBytes: number);
+}
+
 /**
  * Native FFmpeg Encoder
  *
@@ -103,8 +125,14 @@ declare function readInput(inputPath: string, options?: ReadInputOptions): Promi
  * callers use the WebCodecs/ffmpeg.wasm paths in the video packages instead.
  */
 
+/** Node-native video options with cooperative and child-process cancellation. */
+interface NativeVideoExportOptions extends VideoExportOptions {
+    signal?: AbortSignal;
+}
 /** Options for native animated-GIF encoding. */
 interface GifExportOptions {
+    /** Cancel staging or encoding and terminate the native FFmpeg process. */
+    signal?: AbortSignal;
     /** Frames per second (default: 10; GIF timing is centisecond-based). */
     fps?: number;
     /** Output width in pixels (default: 960 landscape / 540 portrait). */
@@ -142,12 +170,12 @@ declare const GIF_EXPORT_DEFAULTS: {
  * @param outputPath - Where to write the final MP4
  * @param options - Encoding options (fps, quality, dimensions, progress)
  */
-declare function framesToMp4Native(ffmpegPath: string, frames: Uint8Array[], audio: Uint8Array | null, outputPath: string, options?: VideoExportOptions): Promise<void>;
+declare function framesToMp4Native(ffmpegPath: string, frames: Uint8Array[], audio: Uint8Array | null, outputPath: string, options?: NativeVideoExportOptions): Promise<void>;
 /**
  * Encode frames using native ffmpeg and return the MP4 bytes (instead of writing to disk).
  * Useful when the caller needs the bytes in memory.
  */
-declare function framesToMp4NativeBytes(ffmpegPath: string, frames: Uint8Array[], audio: Uint8Array | null, options?: VideoExportOptions): Promise<Uint8Array>;
+declare function framesToMp4NativeBytes(ffmpegPath: string, frames: Uint8Array[], audio: Uint8Array | null, options?: NativeVideoExportOptions): Promise<Uint8Array>;
 /**
  * Encode PNG frames to an animated GIF using native FFmpeg.
  *
@@ -212,8 +240,12 @@ type CliConvertOptions = Omit<ConvertOptions, 'formatOptions'> & {
  * @throws {@link ConversionError} on any failure, with a stable `code`.
  */
 declare function convert(source: ConvertSource, to: FormatId, options?: CliConvertOptions): Promise<ConversionResult>;
+/** Normalize and transform once using the CLI registry, then export one or more targets. */
+declare function prepareConversion(source: ConvertSource, options?: CliConvertOptions): Promise<PreparedConversion>;
 /** Options for renderDocToMp4. */
 interface RenderDocToMp4Options {
+    /** Cancel capture/encoding and terminate browser and FFmpeg work. */
+    signal?: AbortSignal;
     /** Output file path for the MP4. */
     outputPath: string;
     /** Frames per second (default: 30). */
@@ -245,6 +277,8 @@ interface RenderDocToMp4Options {
 }
 /** Options for rendering a document to an animated GIF. */
 interface RenderDocToGifOptions {
+    /** Cancel capture/encoding and terminate browser and FFmpeg work. */
+    signal?: AbortSignal;
     /** Output file path for the GIF. */
     outputPath: string;
     /** Frames per second (default: 10). */
@@ -303,7 +337,7 @@ interface ThumbnailSpec {
 }
 /** Options for extractThumbnails. */
 interface ExtractThumbnailsOptions {
-    /** Path to the source MP4 video. */
+    /** Path to the source MP4 or animated GIF. */
     videoPath: string;
     /** Directory to write thumbnails into. */
     outputDir: string;
@@ -313,11 +347,13 @@ interface ExtractThumbnailsOptions {
     sizes: ThumbnailSpec[];
     /** Overwrite existing thumbnails (default: false). */
     force?: boolean;
+    /** Cancels FFmpeg and rejects with the caller's exact abort reason. */
+    signal?: AbortSignal;
 }
 /**
- * Extract thumbnail images from the first frame of an MP4 video.
+ * Extract thumbnail images from the first frame of an MP4 or animated GIF.
  * Produces JPEG files at each specified size using FFmpeg video filters.
  */
 declare function extractThumbnails(options: ExtractThumbnailsOptions): Promise<void>;
 
-export { type CliConvertOptions, type ExtractThumbnailsOptions, GIF_EXPORT_DEFAULTS, type GifExportOptions, type GifFormatOptions, type Mp4FormatOptions, type ReadInputResult, type RenderDocToGifOptions, type RenderDocToGifResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, framesToGifNative, framesToGifNativeBytes, framesToMp4Native, framesToMp4NativeBytes, readInput, renderDocToGif, renderDocToMp4 };
+export { CapturedFrameBudgetError, type CliConvertOptions, type ExtractThumbnailsOptions, GIF_EXPORT_DEFAULTS, type GifExportOptions, type GifFormatOptions, MAX_CAPTURED_FRAME_BYTES, type Mp4FormatOptions, type NativeVideoExportOptions, type ReadInputResult, type RenderDocToGifOptions, type RenderDocToGifResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, framesToGifNative, framesToGifNativeBytes, framesToMp4Native, framesToMp4NativeBytes, prepareConversion, readInput, renderDocToGif, renderDocToMp4 };