@bendyline/squisq-cli 1.2.2 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @bendyline/squisq-cli
 
-Command-line tool and programmatic API for converting Squisq documents between DOCX, PPTX, PDF, XLSX, CSV, HTML, EPUB, Markdown, and container ZIP — and rendering them to MP4 video. Reads Markdown, binary documents (`.docx`/`.pptx`/`.pdf`/`.xlsx`/`.csv`/`.html`), ZIP/`.dbk` containers, folders, or pre-built Doc JSON as input.
+Command-line tool and programmatic API for converting Squisq documents between DOCX, PPTX, PDF, XLSX, CSV, HTML, EPUB, Markdown, and container ZIP — and rendering them to MP4 video or animated GIF. Reads Markdown, binary documents (`.docx`/`.pptx`/`.pdf`/`.xlsx`/`.csv`/`.html`), ZIP/`.dbk` containers, folders, or pre-built Doc JSON as input.
 
 Part of the [Squisq](https://github.com/bendyline/squisq) monorepo.
 
@@ -13,7 +13,7 @@ Part of the [Squisq](https://github.com/bendyline/squisq) monorepo.
 npm install -g @bendyline/squisq-cli
 ```
 
-For `squisq video` (and `convert` to `mp4`) you also need:
+For `squisq video` (and `convert` to `mp4` or `gif`) you also need:
 
 - ffmpeg — resolved from the `SQUISQ_FFMPEG` env var, then your `PATH` (`brew install ffmpeg` / `apt install ffmpeg` / `winget install ffmpeg`), then an optionally-installed `ffmpeg-static` package.
 - A Playwright-managed Chromium for headless frame capture (e.g. `npx playwright install chromium`)
@@ -29,55 +29,62 @@ Convert a document to one or more formats. Input can be Markdown or a binary doc
 ```bash
 squisq convert input.md -o report.docx           # single file; format inferred from extension
 squisq convert report.docx -o report.md           # binary input → markdown
-squisq convert input.md --format pptx              # single format to the default output dir
+squisq convert input.md --formats pptx             # single format to the default output dir
 squisq convert input.md --formats docx,pptx,pdf    # multiple formats
 squisq convert project.dbk --output-dir ./out --formats html,docx
-squisq convert input.md --theme cinematic --transform magazine --format pptx
+squisq convert input.md --theme cinematic --transform magazine --formats pptx
 ```
 
-| Option                | Description                                                                                             | Default       |
-| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------- |
-| `-o, --output <file>` | **Single** output file; format inferred from its extension (cannot combine with `--formats`/`--format`) | —             |
-| `-d, --output-dir`    | Output directory (multi-format mode)                                                                    | same as input |
-| `-f, --formats`       | Comma-separated: `docx`, `pptx`, `pdf`, `html`, `htmlzip`, `epub`, `dbk`, `md`, `xlsx`, `csv`, `mp4`    | default set   |
-| `--format <id>`       | Produce a single format (alias for a one-entry `--formats`)                                             | —             |
-| `-t, --theme`         | Squisq theme id — built-in or a custom theme inlined in the doc's frontmatter                           | none          |
-| `--transform`         | Transform style applied before export (e.g. `documentary`, `magazine`, `minimal`)                       | none          |
-| `--no-auto-templates` | Disable content-aware template auto-picking for unannotated headings                                    | (auto on)     |
+| Option                | Description                                                                                                 | Default       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------- | ------------- |
+| `-o, --output <file>` | **Single** output file; format inferred from its extension (cannot combine with `--formats`)                | —             |
+| `-d, --output-dir`    | Output directory (multi-format mode)                                                                        | same as input |
+| `-f, --formats`       | Comma-separated: `docx`, `pptx`, `pdf`, `html`, `htmlzip`, `epub`, `dbk`, `md`, `xlsx`, `csv`, `mp4`, `gif` | default set   |
+| `-t, --theme`         | Squisq theme id — built-in or a custom theme inlined in the doc's frontmatter                               | none          |
+| `--transform`         | Transform style applied before export (e.g. `documentary`, `magazine`, `minimal`)                           | none          |
+| `--no-auto-templates` | Disable content-aware template auto-picking for unannotated headings                                        | (auto on)     |
 
-> **v1.5 breaking flag change:** `-o` is now a **single-file** destination (format inferred from the extension). The old `-o` output-**directory** behavior is now `-d, --output-dir`. A bare `convert <input>` with no `-o`/`--format`/`--formats` writes a default set that deliberately excludes `md`/`xlsx`/`csv`/`mp4`.
+> **v1.5 breaking flag change:** `-o` is now a **single-file** destination (format inferred from the extension). The old `-o` output-**directory** behavior is now `-d, --output-dir`. A bare `convert <input>` with no `-o`/`--formats` writes a default set that deliberately excludes `md`/`xlsx`/`csv`/`mp4`/`gif`.
 
 Notes:
 
 - `html` produces a single self-contained file with the standalone player inlined (static mode); `htmlzip` produces a `<name>.html.zip` archive with external assets and optional audio.
 - `epub` embeds images from the input container and, when the doc has narration segments, generates EPUB 3 Media Overlays.
-- `xlsx` export is tables-only; `csv` export emits the first table; `mp4` requires the video toolchain (see Install).
+- `xlsx` export is tables-only; `csv` export emits the first table; `mp4` and `gif` require the render toolchain (see Install).
 - `dbk` re-serializes the input container as a ZIP.
 
 ### `squisq video <input> [output]`
 
-Render a document to MP4: Playwright captures frames from a headless player page, native ffmpeg encodes them (H.264 + AAC when the doc has audio).
+Render a document to MP4 or animated GIF. Playwright captures deterministic frames from a headless player page; native ffmpeg encodes H.264 + AAC for MP4 or a generated global palette for GIF. GIF has no audio track.
 
 ```bash
 squisq video input.md output.mp4
+squisq video input.md output.gif
+squisq video input.md --format gif --no-animations
 squisq video project.dbk --quality high --fps 30
 squisq video ./my-folder --orientation portrait --captions social
 squisq video input.md -t documentary --transform magazine --cover-preroll 1.5
 squisq video doc.json -o out.mp4
 ```
 
-| Option                 | Description                                                          | Default         |
-| ---------------------- | -------------------------------------------------------------------- | --------------- |
-| `-o, --output`         | Output MP4 path (positional `[output]` wins over the flag)           | `<input>.mp4`   |
-| `--fps`                | Frames per second (1–120)                                            | 30              |
-| `--quality`            | `draft`, `normal`, or `high`                                         | normal          |
-| `--orientation`        | `landscape` (1920×1080) or `portrait` (1080×1920)                    | landscape       |
-| `--captions`           | `off`, `standard`, or `social`                                       | off             |
-| `-t, --theme`          | Squisq theme id to apply                                             | none            |
-| `--transform`          | Transform style to apply before rendering                            | none            |
-| `--cover-preroll`      | Seconds of cover-slide pre-roll before the story starts              | 2               |
-| `--width` / `--height` | Dimension overrides in pixels                                        | per orientation |
-| `--no-auto-templates`  | Disable content-aware template auto-picking for unannotated headings | (auto on)       |
+| Option                             | Description                                                          | Default                   |
+| ---------------------------------- | -------------------------------------------------------------------- | ------------------------- |
+| `-o, --output`                     | Output `.mp4` or `.gif` path; extension selects the format           | `<input>.mp4`             |
+| `--format`                         | `mp4` or `gif`                                                       | inferred, otherwise `mp4` |
+| `--fps`                            | Frames per second (MP4 1–120; GIF 1–100)                             | MP4 30; GIF 10            |
+| `--quality`                        | MP4-only quality: `draft`, `normal`, or `high`                       | normal                    |
+| `--orientation`                    | `landscape` or `portrait`                                            | landscape                 |
+| `--captions`                       | `off`, `standard`, or `social`                                       | off                       |
+| `--animations` / `--no-animations` | Enable/disable layer animations and block transitions                | MP4 enabled; GIF disabled |
+| `--loop`                           | GIF repeat count (`0` forever, `-1` no loop)                         | 0                         |
+| `--max-colors`                     | GIF palette size, 2–256                                              | 256                       |
+| `--dither`                         | GIF dithering: `bayer`, `sierra2_4a`, or `none`                      | `sierra2_4a`              |
+| `--bayer-scale`                    | Ordered Bayer strength, 0–5                                          | 3                         |
+| `-t, --theme`                      | Squisq theme id to apply                                             | none                      |
+| `--transform`                      | Transform style to apply before rendering                            | none                      |
+| `--cover-preroll`                  | Seconds of cover-slide pre-roll before the story starts              | 2                         |
+| `--width` / `--height`             | Dimension overrides in pixels                                        | MP4 1080p; GIF 960×540    |
+| `--no-auto-templates`              | Disable content-aware template auto-picking for unannotated headings | (auto on)                 |
 
 ### `squisq doctor`
 
@@ -118,11 +125,11 @@ All commands accept:
 
 ## Programmatic API
 
-Import `@bendyline/squisq-cli/api` to use the same pipeline as a library from Node.js — no shell-out required. Like the CLI, `renderDocToMp4` requires ffmpeg and a Playwright-managed Chromium.
+Import `@bendyline/squisq-cli/api` to use the same pipeline as a library from Node.js — no shell-out required. Like the CLI, `renderDocToMp4` and `renderDocToGif` require ffmpeg and a Playwright-managed Chromium.
 
 ### `convert()`
 
-A pre-bound wrapper over `@bendyline/squisq-formats`' `convert()` that injects the CLI's format registry (every built-in exporter plus the CLI-only `mp4` format) and a default `resolvePlayerScript` (so HTML/player-embedding exports work out of the box). Both are overridable via `options`. `createCliRegistry()` returns that same registry for direct use.
+A pre-bound wrapper over `@bendyline/squisq-formats`' `convert()` that injects the CLI's format registry (every built-in exporter plus the CLI-only `mp4` and `gif` formats) and a default `resolvePlayerScript` (so HTML/player-embedding exports work out of the box). Both are overridable via `options`. `createCliRegistry()` returns that same registry for direct use.
 
 ```ts
 import { convert, createCliRegistry, ConversionError } from '@bendyline/squisq-cli/api';
@@ -153,6 +160,7 @@ const result = await renderDocToMp4(doc, input.container, {
   quality: 'high', // 'draft' | 'normal' | 'high' (default 'normal')
   orientation: 'landscape', // 'landscape' | 'portrait' (default 'landscape')
   captionStyle: 'social', // 'standard' | 'social' — omit for no captions
+  animationsEnabled: false, // static slide changes; media/timing remain active
   coverPreRoll: 2, // seconds of cover-slide pre-roll (default 0)
   onProgress: (phase, pct) => console.log(`${phase}: ${pct}%`),
 });
@@ -162,6 +170,49 @@ console.log(`Rendered ${result.frameCount} frames (${result.duration}s) → ${re
 
 The container's audio segments become the MP4's audio track; timed media clips and block videos found in the doc are embedded and mixed at their scheduled positions.
 
+### `renderDocToGif`
+
+```ts
+import { renderDocToGif } from '@bendyline/squisq-cli/api';
+
+const result = await renderDocToGif(doc, input.container, {
+  outputPath: './output.gif',
+  fps: 10,
+  animationsEnabled: false,
+  maxColors: 256,
+  loop: 0,
+});
+```
+
+GIF defaults to 960×540 landscape (540×960 portrait), 10 fps, an infinite
+loop, and disabled slide animations/transitions. Embedded video still advances,
+but all audio is omitted and reported through `result.warnings`.
+
+### Native frame encoding
+
+For callers that already have PNG frames and do not need Playwright capture,
+the API exposes the native FFmpeg layer directly:
+
+```ts
+import { framesToGifNativeBytes, framesToMp4NativeBytes } from '@bendyline/squisq-cli/api';
+
+const mp4 = await framesToMp4NativeBytes('/usr/bin/ffmpeg', pngFrames, audioBytes, {
+  fps: 30,
+  quality: 'high',
+});
+
+const gif = await framesToGifNativeBytes('/usr/bin/ffmpeg', pngFrames, {
+  fps: 10,
+  width: 960,
+  height: 540,
+});
+```
+
+The path variants write to a caller-supplied output; each `Bytes` variant returns
+a `Uint8Array`. MP4 pads short audio with silence so narration cannot truncate
+the timeline. GIF uses a compression-friendly diff palette and changed-rectangle
+application.
+
 ### `extractThumbnails`
 
 Extract JPEG thumbnails from the first frame of a rendered video:

package/dist/api-LE75OSRQ.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import {
+  CapturedFrameBudgetError,
+  ConversionError,
+  MAX_CAPTURED_FRAME_BYTES,
+  MemoryContentContainer,
+  convert,
+  createCliRegistry,
+  extractThumbnails,
+  prepareConversion,
+  readInput,
+  renderDocToGif,
+  renderDocToMp4
+} from "./chunk-FVFK4ZJU.js";
+import {
+  GIF_EXPORT_DEFAULTS,
+  framesToGifNative,
+  framesToGifNativeBytes,
+  framesToMp4Native,
+  framesToMp4NativeBytes
+} from "./chunk-JDHONKFZ.js";
+export {
+  CapturedFrameBudgetError,
+  ConversionError,
+  GIF_EXPORT_DEFAULTS,
+  MAX_CAPTURED_FRAME_BYTES,
+  MemoryContentContainer,
+  convert,
+  createCliRegistry,
+  extractThumbnails,
+  framesToGifNative,
+  framesToGifNativeBytes,
+  framesToMp4Native,
+  framesToMp4NativeBytes,
+  prepareConversion,
+  readInput,
+  renderDocToGif,
+  renderDocToMp4
+};
+//# sourceMappingURL=api-LE75OSRQ.js.map

package/dist/api-LE75OSRQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/api.d.ts

@@ -1,12 +1,53 @@
 import { Doc } from '@bendyline/squisq/schemas';
 import { ContentContainer } from '@bendyline/squisq/storage';
 export { MemoryContentContainer } from '@bendyline/squisq/storage';
-import { VideoQuality, VideoOrientation } from '@bendyline/squisq-video';
-export { VideoOrientation, VideoQuality } from '@bendyline/squisq-video';
-import { FormatId, FormatRegistry, ConvertSource, ConvertOptions, ConversionResult } from '@bendyline/squisq-formats';
-export { ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionResult, ConvertOptions, ConvertSource, FormatDefinition, FormatId, FormatRegistry, NormalizedInput } from '@bendyline/squisq-formats';
+import { VideoQuality, VideoOrientation, GifDither, VideoExportOptions } from '@bendyline/squisq-video';
+export { GifDither, VideoOrientation, VideoQuality } from '@bendyline/squisq-video';
+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';
 
+/**
+ * CLI format registry.
+ *
+ * The CLI extends the formats package's default registry with `mp4` and `gif`
+ * formats so `convert()` can produce rendered media like DOCX/PDF/HTML. These
+ * exports are Node-only (Playwright + FFmpeg), which is why they live here
+ * rather than in the browser-pure formats package.
+ */
+
+interface Mp4FormatOptions {
+    onProgress?: (phase: string, percent: number) => void;
+    fps?: number;
+    quality?: VideoQuality;
+    orientation?: VideoOrientation;
+    width?: number;
+    height?: number;
+    captionStyle?: 'standard' | 'social';
+    coverPreRoll?: number;
+    animationsEnabled?: boolean;
+}
+/** Per-export options for `convert(..., 'gif')`. */
+interface GifFormatOptions {
+    onProgress?: (phase: string, percent: number) => void;
+    fps?: number;
+    orientation?: VideoOrientation;
+    width?: number;
+    height?: number;
+    captionStyle?: 'standard' | 'social';
+    coverPreRoll?: number;
+    animationsEnabled?: boolean;
+    loop?: number;
+    maxColors?: number;
+    dither?: GifDither;
+    bayerScale?: number;
+}
+/**
+ * Build the CLI's format registry: every built-in format from
+ * `@bendyline/squisq-formats` plus the CLI-only rendered-media exporters.
+ */
+declare function createCliRegistry(): FormatRegistry;
+
 /**
  * readInput
  *
@@ -37,33 +78,121 @@ interface ReadInputResult {
     /** Detected source format id (registry id, or `md`/`json`/`dbk`/`folder`). */
     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.
+     */
+    inferTheme?: boolean;
+    /** Derive custom layout templates from PPTX slide layouts. Default true. */
+    inferLayouts?: boolean;
+}
 /**
  * Read input from a file path (markdown, JSON Doc, ZIP/DBK container, folder,
  * or an importable binary format) and resolve it to a populated
  * {@link ReadInputResult}.
  */
-declare function readInput(inputPath: string): Promise<ReadInputResult>;
+declare function readInput(inputPath: string, options?: ReadInputOptions): Promise<ReadInputResult>;
 
 /**
- * CLI format registry.
+ * Hard retained-memory ceiling for PNG frames captured before native encoding.
  *
- * The CLI extends the formats package's default registry with an `mp4` format
- * so `convert()` can produce video the same way it produces DOCX/PDF/HTML. MP4
- * export is Node-only (it needs Playwright + FFmpeg), which is why it lives
- * here in the CLI rather than in the browser-pure formats package.
+ * 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);
+}
 
 /**
- * Build the CLI's format registry: every built-in format from
- * `@bendyline/squisq-formats` plus the CLI-only `mp4` exporter.
+ * Native FFmpeg Encoder
+ *
+ * Encodes PNG frames to MP4 or animated GIF using a locally installed ffmpeg
+ * binary. Writes frames to a temporary directory, invokes ffmpeg as a child
+ * process, and reads the resulting media file.
+ *
+ * This is the Node fast path used after the CLI detects native FFmpeg. Browser
+ * callers use the WebCodecs/ffmpeg.wasm paths in the video packages instead.
  */
-declare function createCliRegistry(): FormatRegistry;
 
+/** 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). */
+    width?: number;
+    /** Output height in pixels (default: 540 landscape / 960 portrait). */
+    height?: number;
+    /** Viewport orientation used for default dimensions. */
+    orientation?: VideoOrientation;
+    /** Number of repeats; 0 loops forever and -1 disables looping. */
+    loop?: number;
+    /** Palette size, between 2 and 256 (default: 256). */
+    maxColors?: number;
+    /** Palette dithering algorithm (default: sierra2_4a). */
+    dither?: GifDither;
+    /** Bayer strength when dither is bayer (0-5, default: 3). */
+    bayerScale?: number;
+    /** Encoding progress callback. */
+    onProgress?: (percent: number, phase: string) => void;
+}
+/** Compression-friendly defaults for animated GIF output. */
+declare const GIF_EXPORT_DEFAULTS: {
+    readonly fps: 10;
+    readonly width: 960;
+    readonly height: 540;
+    readonly loop: 0;
+    readonly maxColors: 256;
+    readonly dither: GifDither;
+};
 /**
- * Programmatic Video API
+ * Encode frame PNGs to MP4 using native ffmpeg.
  *
- * Provides a library-style entry point for rendering Squisq documents to MP4
- * from Node.js callers (e.g., Qualla's pipeline). This avoids the need to shell
+ * @param ffmpegPath - Absolute path to the ffmpeg binary
+ * @param frames - Array of PNG image bytes (one per frame)
+ * @param audio - Optional audio file bytes to mux
+ * @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?: 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?: NativeVideoExportOptions): Promise<Uint8Array>;
+/**
+ * Encode PNG frames to an animated GIF using native FFmpeg.
+ *
+ * The shared palette graph uses changed-frame statistics and rectangle-scoped
+ * palette application so static slide regions remain stable and compress well.
+ * GIF has no audio track; callers should surface that limitation before calling.
+ */
+declare function framesToGifNative(ffmpegPath: string, frames: Uint8Array[], outputPath: string, options?: GifExportOptions): Promise<void>;
+/** Encode frames with native FFmpeg and return animated-GIF bytes. */
+declare function framesToGifNativeBytes(ffmpegPath: string, frames: Uint8Array[], options?: GifExportOptions): Promise<Uint8Array>;
+
+/**
+ * Programmatic Rendered-Media API
+ *
+ * Provides library-style entry points for rendering Squisq documents to MP4
+ * or animated GIF from Node.js callers (e.g., Qualla's pipeline). This avoids
+ * the need to shell
  * out to the `squisq video` CLI and gives callers full control over the Doc,
  * MemoryContentContainer, and encoding options.
  *
@@ -78,28 +207,45 @@ declare function createCliRegistry(): FormatRegistry;
  *     quality: 'normal',
  *     orientation: 'landscape',
  *   });
+ *
+ *   await renderDocToGif(doc, container, {
+ *     outputPath: '/tmp/output.gif',
+ *     animationsEnabled: false,
+ *   });
  */
 
+/** Convert options with the CLI-only rendered-media adapters strongly typed. */
+type CliConvertOptions = Omit<ConvertOptions, 'formatOptions'> & {
+    formatOptions?: ConvertOptions['formatOptions'] & {
+        mp4?: Mp4FormatOptions;
+        gif?: GifFormatOptions;
+    };
+};
+
 /**
  * Convert a document to a target format using the CLI's format registry.
  *
  * This is a thin, pre-bound wrapper over `convert()` from
  * `@bendyline/squisq-formats`: it injects the CLI registry (which adds the
- * `mp4` format on top of every built-in exporter) and a default
+ * `mp4` and `gif` formats on top of every built-in exporter) and a default
  * `resolvePlayerScript` that lazily loads the standalone player IIFE bundle
  * (required for HTML/EPUB-style exports). Callers may override either via
  * `options`.
  *
  * @param source - A bytes / markdown / doc {@link ConvertSource}.
- * @param to - Target format id (`docx`, `pdf`, `pptx`, `html`, `mp4`, …).
+ * @param to - Target format id (`docx`, `pdf`, `pptx`, `html`, `mp4`, `gif`, …).
  * @param options - Conversion options; `registry` and `resolvePlayerScript`
  *   default to the CLI's values but can be overridden.
  * @returns The encoded bytes plus mime type, suggested filename, and warnings.
  * @throws {@link ConversionError} on any failure, with a stable `code`.
  */
-declare function convert(source: ConvertSource, to: FormatId, options?: ConvertOptions): Promise<ConversionResult>;
+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). */
@@ -114,6 +260,8 @@ interface RenderDocToMp4Options {
     height?: number;
     /** Caption style to bake into the video (default: none). */
     captionStyle?: 'standard' | 'social';
+    /** Render layer animations and block transitions (default: true). */
+    animationsEnabled?: boolean;
     /**
      * Seconds of cover-slide pre-roll before the story starts (default: 0).
      *
@@ -127,6 +275,37 @@ interface RenderDocToMp4Options {
      */
     onProgress?: (phase: string, percent: number) => void;
 }
+/** 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). */
+    fps?: number;
+    /** Viewport orientation (default: landscape). */
+    orientation?: VideoOrientation;
+    /** Override output width (default: 960 landscape / 540 portrait). */
+    width?: number;
+    /** Override output height (default: 540 landscape / 960 portrait). */
+    height?: number;
+    /** Caption style to bake into the GIF (default: none). */
+    captionStyle?: 'standard' | 'social';
+    /** Seconds of cover-slide pre-roll (default: 0). */
+    coverPreRoll?: number;
+    /** Render layer animations and block transitions (default: false). */
+    animationsEnabled?: boolean;
+    /** Number of repeats; 0 loops forever and -1 disables looping. */
+    loop?: number;
+    /** Palette size, from 2 through 256 (default: 256). */
+    maxColors?: number;
+    /** Palette dithering algorithm (default: sierra2_4a). */
+    dither?: GifDither;
+    /** Bayer strength when dither is bayer (0-5, default: 3). */
+    bayerScale?: number;
+    /** Progress callback. */
+    onProgress?: (phase: string, percent: number) => void;
+}
 /** Result returned by renderDocToMp4. */
 interface RenderDocToMp4Result {
     /** Duration of the rendered video in seconds (including pre-roll). */
@@ -136,24 +315,15 @@ interface RenderDocToMp4Result {
     /** Output file path. */
     outputPath: string;
 }
-/**
- * Render a Doc + media container to an MP4 video file.
- *
- * The container should contain audio and image files referenced by the Doc's
- * audio.segments[].src and block image paths. Files are embedded as base64
- * data URIs in a self-contained render HTML page.
- *
- * Requires:
- * - Playwright (chromium) — for headless frame capture
- * - FFmpeg — for video encoding (resolved from SQUISQ_FFMPEG, PATH, or an
- *   optionally installed `ffmpeg-static` package — see detectFfmpeg)
- *
- * @param doc - The Doc structure to render
- * @param container - MemoryContentContainer with audio/image files
- * @param options - Rendering and encoding options
- * @returns Result with duration and frame count
- */
+/** Result returned by renderDocToGif. */
+interface RenderDocToGifResult extends RenderDocToMp4Result {
+    /** Non-fatal fidelity warnings, including GIF's lack of audio. */
+    warnings: string[];
+}
+/** Render a Doc + media container to an MP4 video file. */
 declare function renderDocToMp4(doc: Doc, container: ContentContainer, options: RenderDocToMp4Options): Promise<RenderDocToMp4Result>;
+/** Render a Doc + media container to a silent animated GIF. */
+declare function renderDocToGif(doc: Doc, container: ContentContainer, options: RenderDocToGifOptions): Promise<RenderDocToGifResult>;
 /** A thumbnail size specification. */
 interface ThumbnailSpec {
     /** Label for the thumbnail (used in filename: `{slug}-{width}x{height}.jpg`). */
@@ -167,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;
@@ -177,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 ExtractThumbnailsOptions, type ReadInputResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, readInput, 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 };