@bendyline/squisq-cli 1.2.1 → 2.0.0

package/dist/index.js

@@ -1,4 +1,14 @@
 #!/usr/bin/env node
+import {
+  convert,
+  createCliRegistry,
+  detectFfmpegDetailed,
+  getFfmpegVersion,
+  readInput,
+  renderDocToGif,
+  renderDocToMp4
+} from "./chunk-JEE26SZS.js";
+import "./chunk-VM3ZFP3J.js";
 
 // src/index.ts
 import { createRequire } from "module";
@@ -6,503 +16,8 @@ import { Command } from "commander";
 
 // src/commands/convert.ts
 import { writeFile, mkdir } from "fs/promises";
-import { dirname, basename, extname as extname2, join as join3, resolve } from "path";
-import { BUILTIN_FORMAT_IDS, ConversionError as ConversionError2 } from "@bendyline/squisq-formats";
-
-// 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, readdir, stat } from "fs/promises";
-import { join, extname } from "path";
-import { parseMarkdown, stringifyMarkdown } from "@bendyline/squisq/markdown";
-import { markdownToDoc } from "@bendyline/squisq/doc";
-import { MemoryContentContainer } from "@bendyline/squisq/storage";
-import { zipToContainer } from "@bendyline/squisq-formats/container";
-import { defaultRegistry } from "@bendyline/squisq-formats";
-var MIME_TYPES = {
-  ".md": "text/markdown",
-  ".txt": "text/plain",
-  ".json": "application/json",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".png": "image/png",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".ogg": "audio/ogg",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm"
-};
-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 = "") {
-  const entries = await readdir(root, { withFileTypes: true });
-  const paths = [];
-  for (const entry of entries) {
-    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
-      paths.push(...await walkDir(join(root, entry.name), relPath));
-    } else if (entry.isFile()) {
-      paths.push(relPath);
-    }
-  }
-  return paths;
-}
-async function readInput(inputPath) {
-  const info = await stat(inputPath);
-  if (info.isDirectory()) {
-    return readFolder(inputPath);
-  }
-  const ext = extname(inputPath).toLowerCase();
-  if (ext === ".zip" || ext === ".dbk") {
-    return readContainer(inputPath);
-  }
-  if (ext === ".json") {
-    return readDocJsonFile(inputPath);
-  }
-  if (IMPORTER_EXTS.includes(ext)) {
-    const def = defaultRegistry().byExtension(ext);
-    if (def && (def.importContainer || def.importDoc)) {
-      return readViaImporter(inputPath, def);
-    }
-  }
-  return readMarkdownFile(inputPath);
-}
-async function readArrayBuffer(filePath) {
-  const data = await readFile(filePath);
-  return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
-}
-async function readMarkdownFile(filePath) {
-  const content = await readFile(filePath, "utf-8");
-  const container = new MemoryContentContainer();
-  await container.writeDocument(content);
-  const markdownDoc = parseMarkdown(content);
-  return { doc: markdownToDoc(markdownDoc), container, markdownDoc, sourceFormat: "md" };
-}
-async function readDocJsonFile(filePath) {
-  const content = await readFile(filePath, "utf-8");
-  const doc = JSON.parse(content);
-  const container = new MemoryContentContainer();
-  return { doc, container, sourceFormat: "json" };
-}
-async function readViaImporter(filePath, def) {
-  const buffer = await readArrayBuffer(filePath);
-  let container;
-  let markdownDoc;
-  if (def.importContainer) {
-    container = await def.importContainer(buffer, {});
-    const text = await container.readDocument();
-    markdownDoc = text ? parseMarkdown(text) : { type: "document", children: [] };
-  } else {
-    markdownDoc = await def.importDoc(buffer, {});
-    const mem = new MemoryContentContainer();
-    await mem.writeDocument(stringifyMarkdown(markdownDoc));
-    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) {
-  for (const name of DOC_JSON_NAMES) {
-    const jsonData = await container.readFile(name);
-    if (jsonData) {
-      const doc = JSON.parse(new TextDecoder().decode(jsonData));
-      return { doc, container, sourceFormat };
-    }
-  }
-  const markdown = await container.readDocument();
-  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));
-  return resolveContainer(
-    container,
-    "dbk",
-    `No markdown document or doc.json found in container: ${filePath}`
-  );
-}
-async function readFolder(dirPath) {
-  const container = new MemoryContentContainer();
-  const files = await walkDir(dirPath);
-  for (const relPath of files) {
-    const absPath = join(dirPath, relPath);
-    const data = await readFile(absPath);
-    await container.writeFile(
-      relPath,
-      new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
-      mimeFromExt(relPath)
-    );
-  }
-  return resolveContainer(
-    container,
-    "folder",
-    `No markdown document or doc.json found in folder: ${dirPath}`
-  );
-}
-
-// src/registry.ts
-import { randomBytes } from "crypto";
-import { readFile as readFile2, rm } from "fs/promises";
-import { tmpdir } from "os";
-import { join as join2 } from "path";
-import { defaultRegistry as defaultRegistry2 } from "@bendyline/squisq-formats";
-
-// src/api.ts
-import { resolveMediaSchedule } from "@bendyline/squisq/schemas";
-import { flattenBlocks } from "@bendyline/squisq/doc";
-import { generateRenderHtml } from "@bendyline/squisq-video";
-import { resolveDimensions } from "@bendyline/squisq-video";
-import { convert as formatsConvert } from "@bendyline/squisq-formats";
-
-// src/util/detectFfmpeg.ts
-import { execFile } from "child_process";
-function run(command, args) {
-  return new Promise((resolve4) => {
-    execFile(command, args, { timeout: 5e3 }, (err, stdout) => {
-      if (err || !stdout.trim()) {
-        resolve4(null);
-        return;
-      }
-      resolve4(stdout.trim());
-    });
-  });
-}
-async function getFfmpegVersion(path) {
-  const out = await run(path, ["-version"]);
-  return out ? out.split("\n")[0].trim() : null;
-}
-async function detectFfmpegDetailed() {
-  const envPath = process.env.SQUISQ_FFMPEG;
-  if (envPath) {
-    const version2 = await getFfmpegVersion(envPath);
-    if (!version2) {
-      throw new Error(
-        `SQUISQ_FFMPEG is set to "${envPath}" but running "${envPath} -version" failed. Fix the path or unset SQUISQ_FFMPEG.`
-      );
-    }
-    return { path: envPath, source: "env" };
-  }
-  const command = process.platform === "win32" ? "where" : "which";
-  const found = await run(command, ["ffmpeg"]);
-  if (found) {
-    return { path: found.split("\n")[0].trim(), source: "path" };
-  }
-  try {
-    const specifier = "ffmpeg-static";
-    const mod = await import(specifier);
-    const candidate = typeof mod === "string" ? mod : typeof mod.default === "string" ? mod.default : null;
-    if (candidate) {
-      return { path: candidate, source: "ffmpeg-static" };
-    }
-  } catch {
-  }
-  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) {
-  const timeline = computeAudioTimeline(doc, coverPreRoll);
-  if (timeline.length === 0) return null;
-  const bytesBySrc = /* @__PURE__ */ new Map();
-  const readSrc = async (src) => {
-    if (bytesBySrc.has(src)) return bytesBySrc.get(src);
-    const data = await container.readFile(src);
-    bytesBySrc.set(src, data ?? null);
-    return data ?? null;
-  };
-  const usable = [];
-  for (const clip of timeline) {
-    const buffer = await readSrc(clip.src);
-    if (buffer) usable.push({ clip, buffer });
-  }
-  if (usable.length === 0) return null;
-  return mixTimelineClips(ffmpegPath, usable);
-}
-async function mixTimelineClips(ffmpegPath, usable) {
-  const { writeFile: writeFile2, readFile: readFile3, mkdir: mkdir3, rm: rm2 } = await import("fs/promises");
-  const { join: join5 } = await import("path");
-  const { tmpdir: tmpdir2 } = await import("os");
-  const { randomBytes: randomBytes2 } = await import("crypto");
-  const { execFile: execFile2 } = await import("child_process");
-  const workDir = join5(tmpdir2(), `squisq-audio-mix-${randomBytes2(8).toString("hex")}`);
-  await mkdir3(workDir, { recursive: true });
-  const ms = (s) => Math.max(0, Math.round(s * 1e3));
-  try {
-    const inputs = [];
-    const filters = [];
-    const labels = [];
-    for (const { clip, buffer } of usable) {
-      const p = join5(workDir, `clip-${inputs.length}.mp3`);
-      await writeFile2(p, new Uint8Array(buffer));
-      const i = inputs.push(p) - 1;
-      const delayMs = ms(clip.startSec);
-      const start = Math.max(0, clip.sourceInSec);
-      const end = start + Math.max(0, clip.durationSec);
-      filters.push(
-        `[${i}:a]atrim=start=${start}:end=${end},asetpts=PTS-STARTPTS,adelay=${delayMs}|${delayMs}[a${i}]`
-      );
-      labels.push(`[a${i}]`);
-    }
-    const graph = `${filters.join(";")};${labels.join("")}amix=inputs=${labels.length}:normalize=0:dropout_transition=0[aout]`;
-    const outputPath = join5(workDir, "mixed.mp3");
-    const args = ["-y"];
-    for (const p of inputs) args.push("-i", p);
-    args.push(
-      "-filter_complex",
-      graph,
-      "-map",
-      "[aout]",
-      "-c:a",
-      "libmp3lame",
-      "-b:a",
-      "192k",
-      outputPath
-    );
-    await new Promise((resolve4, reject) => {
-      execFile2(ffmpegPath, args, { timeout: 18e4 }, (err) => {
-        if (err) reject(new Error(`ffmpeg audio mix failed: ${err.message}`));
-        else resolve4();
-      });
-    });
-    const data = await readFile3(outputPath);
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-  } finally {
-    await rm2(workDir, { recursive: true, force: true });
-  }
-}
-
-// src/api.ts
-import { MemoryContentContainer as MemoryContentContainer2 } from "@bendyline/squisq/storage";
-import { ConversionError } from "@bendyline/squisq-formats";
-async function convert(source, to, options = {}) {
-  return formatsConvert(source, to, {
-    registry: createCliRegistry(),
-    resolvePlayerScript: () => import("@bendyline/squisq-react/standalone-source").then((m) => m.PLAYER_BUNDLE),
-    ...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
-  });
-  const ffmpegPath = await detectFfmpeg();
-  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);
-  const { collectImagePaths } = await import("@bendyline/squisq-formats/html");
-  const imagePaths = collectImagePaths(doc);
-  const images = /* @__PURE__ */ new Map();
-  for (const imgPath of imagePaths) {
-    const data = await container.readFile(imgPath);
-    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);
-      }
-    }
-  }
-  const mediaSrcs = new Set(resolveMediaSchedule(doc).map((c) => c.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) {
-    if (images.has(src)) continue;
-    const data = await container.readFile(src);
-    if (data) images.set(src, data);
-  }
-  onProgress?.("generating render HTML", 10);
-  const { PLAYER_BUNDLE } = await import("@bendyline/squisq-react/standalone-source");
-  const renderHtml = generateRenderHtml(doc, {
-    playerScript: PLAYER_BUNDLE,
-    images,
-    audio: audio.size > 0 ? audio : void 0,
-    width: dimensions.width,
-    height: dimensions.height,
-    captionStyle
-  });
-  onProgress?.("launching browser", 15);
-  const { chromium } = await import("playwright-core");
-  let browser;
-  try {
-    browser = await chromium.launch({ headless: true });
-  } catch (err) {
-    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);
-  try {
-    await page.waitForFunction(
-      () => typeof window.getDuration === "function",
-      { timeout: 15e3 }
-    );
-  } catch {
-    await browser.close();
-    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;
-    });
-    if (hasCover) {
-      await page.evaluate(() => {
-        window.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();
-      });
-    }
-  }
-  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);
-    }
-  }
-  await browser.close();
-  onProgress?.("encoding video", 80);
-  const encodingAudio = await buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll);
-  const { framesToMp4Native } = await import("./nativeEncoder-DLLAT2RT.js");
-  await framesToMp4Native(ffmpegPath, frames, encodingAudio, outputPath, {
-    fps,
-    quality,
-    orientation,
-    width: dimensions.width,
-    height: dimensions.height,
-    onProgress: (percent, phase) => {
-      onProgress?.(`encoding: ${phase}`, 80 + Math.round(percent * 0.2));
-    }
-  });
-  onProgress?.("done", 100);
-  const totalDuration = docDuration + coverPreRoll;
-  return {
-    duration: totalDuration,
-    frameCount: frames.length,
-    outputPath
-  };
-}
-
-// src/registry.ts
-var MP4_DEFAULTS = {
-  fps: 30,
-  quality: "normal",
-  orientation: "landscape",
-  coverPreRoll: 0
-};
-function mp4Format() {
-  return {
-    id: "mp4",
-    label: "MP4 Video",
-    mimeType: "video/mp4",
-    extensions: [".mp4"],
-    async exportDoc(input, options) {
-      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 outputPath = join2(tmpdir(), `squisq-mp4-${randomBytes(8).toString("hex")}.mp4`);
-      try {
-        await renderDocToMp4(input.doc, input.container, {
-          outputPath,
-          fps,
-          quality,
-          orientation,
-          coverPreRoll
-        });
-        const data = await readFile2(outputPath);
-        const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-        return { bytes, mimeType: "video/mp4", suggestedFilename: "", warnings: [] };
-      } finally {
-        await rm(outputPath, { force: true });
-      }
-    }
-  };
-}
-function createCliRegistry() {
-  const registry = defaultRegistry2();
-  registry.register(mp4Format());
-  return registry;
-}
+import { dirname, basename, extname, join, resolve } from "path";
+import { BUILTIN_FORMAT_IDS, ConversionError } from "@bendyline/squisq-formats";
 
 // src/util/applyTransformPipeline.ts
 async function assertValidTransformStyle(style) {
@@ -541,7 +56,7 @@ async function applyTransformToDoc(doc, transformStyle, themeId) {
 }
 
 // src/commands/convert.ts
-var VALID_FORMATS = [...BUILTIN_FORMAT_IDS, "mp4"];
+var VALID_FORMATS = [...BUILTIN_FORMAT_IDS, "mp4", "gif"];
 var DEFAULT_FORMATS = [
   "docx",
   "pptx",
@@ -572,33 +87,38 @@ function parseFormats(value) {
 function formatFromOutputPath(outputPath) {
   const lower = outputPath.toLowerCase();
   if (lower.endsWith(".html.zip")) return "htmlzip";
-  const ext = extname2(lower);
+  const ext = extname(lower);
   const def = createCliRegistry().byExtension(ext);
   if (!def) {
     throw new Error(
-      `Cannot infer a format from output extension "${ext || "(none)"}". Use --format to specify one. Valid: ${VALID_FORMATS.join(", ")}`
+      `Cannot infer a format from output extension "${ext || "(none)"}". Use --formats to specify one. Valid: ${VALID_FORMATS.join(", ")}`
     );
   }
   return def.id;
 }
 function registerConvertCommand(program2) {
-  program2.command("convert").description("Convert a document to DOCX, PPTX, PDF, HTML, EPUB, MP4, and container formats").argument("<input>", "Path to .md/.docx/.pptx/.pdf/.xlsx/.csv/.html file, .zip/.dbk, or folder").option("-o, --output <file>", "Single output file (format inferred from its extension)").option(
+  program2.command("convert").description(
+    "Convert a document to DOCX, PPTX, PDF, HTML, EPUB, MP4, animated GIF, and container formats"
+  ).argument("<input>", "Path to .md/.docx/.pptx/.pdf/.xlsx/.csv/.html file, .zip/.dbk, or folder").option("-o, --output <file>", "Single output file (format inferred from its extension)").option(
     "-d, --output-dir <dir>",
     "Output directory for multi-format export (default: same as input)"
   ).option(
     "-f, --formats <list>",
     `Comma-separated formats to produce (default: a standard set). Valid: ${VALID_FORMATS.join(", ")}`
-  ).option("--format <id>", "Produce a single format (alias for a one-entry --formats)").option("-t, --theme <id>", "Squisq theme ID to apply (e.g., documentary, cinematic, bold)").option(
+  ).option("-t, --theme <id>", "Squisq theme ID to apply (e.g., documentary, cinematic, bold)").option(
     "--transform <style>",
     "Transform style to apply before export (e.g., documentary, magazine, minimal)"
   ).option(
     "--no-auto-templates",
     "Disable content-aware template auto-picking for unannotated headings"
-  ).action(async (inputPath, opts) => {
+  ).option(
+    "--no-infer-theme",
+    "Do not infer a Squisq theme from an office input file (PPTX theme colors/fonts)"
+  ).option("--no-infer-layouts", "Do not derive custom layout templates from PPTX slide layouts").option("--animations", "Enable slide animations/transitions in rendered media").option("--no-animations", "Disable slide animations/transitions in rendered media").action(async (inputPath, opts) => {
     try {
       await runConvert(inputPath, opts);
     } catch (err) {
-      if (err instanceof ConversionError2) {
+      if (err instanceof ConversionError) {
         console.error(`Error: ${err.message}`);
         if (err.hint) console.error(`  ${err.hint}`);
       } else {
@@ -611,21 +131,13 @@ function registerConvertCommand(program2) {
 }
 function resolveFormats(opts) {
   const hasOutput = Boolean(opts.output);
-  const hasFormatSelection = Boolean(opts.formats || opts.format);
+  const hasFormatSelection = Boolean(opts.formats);
   if (hasOutput && hasFormatSelection) {
-    throw new Error(
-      "--output is a single-file destination and cannot be combined with --formats/--format."
-    );
+    throw new Error("--output is a single-file destination and cannot be combined with --formats.");
   }
   if (hasOutput) {
     return [formatFromOutputPath(opts.output)];
   }
-  if (opts.format) {
-    if (!isValidFormat(opts.format.toLowerCase())) {
-      throw new Error(`Unknown format "${opts.format}". Valid: ${VALID_FORMATS.join(", ")}`);
-    }
-    return [opts.format.toLowerCase()];
-  }
   if (opts.formats) {
     return parseFormats(opts.formats);
   }
@@ -635,13 +147,16 @@ async function runConvert(inputPath, opts) {
   const resolvedInput = resolve(inputPath);
   const formats = resolveFormats(opts);
   const inputBasename = basename(resolvedInput);
-  const inputExt = extname2(inputBasename);
+  const inputExt = extname(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
   if (opts.transform) {
     await assertValidTransformStyle(opts.transform);
   }
   console.error(`Reading: ${resolvedInput}`);
-  const result = await readInput(resolvedInput);
+  const result = await readInput(resolvedInput, {
+    inferTheme: opts.inferTheme,
+    inferLayouts: opts.inferLayouts
+  });
   if (opts.theme) {
     await assertValidThemeId(opts.theme, result);
   }
@@ -655,16 +170,18 @@ async function runConvert(inputPath, opts) {
     console.error(`  Applying transform: ${opts.transform}`);
   }
   for (const format of formats) {
+    const formatOptions = (format === "mp4" || format === "gif") && opts.animations !== void 0 ? { [format]: { animationsEnabled: opts.animations } } : void 0;
     const conversion = await convert(source, format, {
       themeId: opts.theme,
       transformStyle: opts.transform,
       autoTemplates: opts.autoTemplates,
-      title: baseName
+      title: baseName,
+      formatOptions
     });
     for (const warning of conversion.warnings) {
       console.error(`  \u26A0 ${warning}`);
     }
-    const outPath = opts.output ? resolve(opts.output) : join3(
+    const outPath = opts.output ? resolve(opts.output) : join(
       opts.outputDir ? resolve(opts.outputDir) : dirname(resolvedInput),
       conversion.suggestedFilename
     );
@@ -677,15 +194,16 @@ async function runConvert(inputPath, opts) {
 
 // src/commands/video.ts
 import { mkdir as mkdir2 } from "fs/promises";
-import { dirname as dirname2, basename as basename2, extname as extname3, resolve as resolve2 } from "path";
+import { dirname as dirname2, basename as basename2, extname as extname2, resolve as resolve2 } from "path";
 var VALID_QUALITIES = ["draft", "normal", "high"];
 var VALID_ORIENTATIONS = ["landscape", "portrait"];
 var VALID_CAPTIONS = ["off", "standard", "social"];
+var VALID_FORMATS2 = ["mp4", "gif"];
+var VALID_GIF_DITHERS = ["bayer", "sierra2_4a", "none"];
 function registerVideoCommand(program2) {
-  program2.command("video").description("Render a squisq document to MP4 video").argument("<input>", "Path to .md file, .zip/.dbk container, or folder").argument("[output]", "Output MP4 path (default: <input>.mp4)").option("-o, --output <path>", "Output MP4 path (default: <input>.mp4)").option("--fps <number>", "Frames per second (default: 30)", "30").option(
+  program2.command("video").description("Render a squisq document to MP4 video or animated GIF").argument("<input>", "Path to .md file, .zip/.dbk container, or folder").argument("[output]", "Output .mp4 or .gif path (default: <input>.<format>)").option("-o, --output <path>", "Output .mp4 or .gif path (format inferred from extension)").option("--format <format>", `Output format: ${VALID_FORMATS2.join(", ")} (default: mp4)`).option("--fps <number>", "Frames per second (default: 30 for MP4, 10 for GIF)").option(
     "--quality <level>",
-    `Encoding quality: ${VALID_QUALITIES.join(", ")} (default: normal)`,
-    "normal"
+    `MP4 encoding quality: ${VALID_QUALITIES.join(", ")} (default: normal)`
   ).option(
     "--orientation <orient>",
     `Video orientation: ${VALID_ORIENTATIONS.join(", ")} (default: landscape)`,
@@ -704,7 +222,10 @@ function registerVideoCommand(program2) {
     "--cover-preroll <seconds>",
     "Seconds of cover-slide pre-roll before the story starts (default: 2)",
     "2"
-  ).option("--width <pixels>", "Override video width").option("--height <pixels>", "Override video height").action(async (inputPath, outputArg, opts) => {
+  ).option("--width <pixels>", "Override video width").option("--height <pixels>", "Override video height").option("--animations", "Enable slide animations/transitions (GIF default: disabled)").option("--no-animations", "Disable slide animations/transitions").option("--loop <count>", "GIF repeat count: 0 forever, -1 no loop (default: 0)").option("--max-colors <count>", "GIF palette size from 2 to 256 (default: 256)").option(
+    "--dither <algorithm>",
+    `GIF dithering: ${VALID_GIF_DITHERS.join(", ")} (default: sierra2_4a)`
+  ).option("--bayer-scale <number>", "GIF Bayer dither strength from 0 to 5 (default: 3)").action(async (inputPath, outputArg, opts) => {
     try {
       if (outputArg && !opts.output) {
         opts.output = outputArg;
@@ -719,11 +240,30 @@ function registerVideoCommand(program2) {
 }
 async function runVideo(inputPath, opts) {
   const resolvedInput = resolve2(inputPath);
-  const fps = parseInt(opts.fps ?? "30", 10);
-  if (isNaN(fps) || fps < 1 || fps > 120) {
-    throw new Error("FPS must be a number between 1 and 120");
+  const requestedFormat = opts.format?.toLowerCase();
+  if (requestedFormat !== void 0 && !VALID_FORMATS2.includes(requestedFormat)) {
+    throw new Error(`Invalid format "${requestedFormat}". Valid: ${VALID_FORMATS2.join(", ")}`);
+  }
+  const outputExtension = opts.output ? extname2(opts.output).toLowerCase() : "";
+  const extensionFormat = outputExtension === ".gif" ? "gif" : outputExtension === ".mp4" ? "mp4" : void 0;
+  if (opts.output && !extensionFormat) {
+    throw new Error("Output path must end in .mp4 or .gif");
+  }
+  if (requestedFormat && extensionFormat && requestedFormat !== extensionFormat) {
+    throw new Error(
+      `Output extension "${outputExtension}" conflicts with --format ${requestedFormat}.`
+    );
+  }
+  const outputFormat = requestedFormat ?? extensionFormat ?? "mp4";
+  const maxFps = outputFormat === "gif" ? 100 : 120;
+  const fps = parseInt(opts.fps ?? (outputFormat === "gif" ? "10" : "30"), 10);
+  if (isNaN(fps) || fps < 1 || fps > maxFps) {
+    throw new Error(`FPS must be a number between 1 and ${maxFps}`);
   }
   const quality = opts.quality ?? "normal";
+  if (outputFormat === "gif" && opts.quality !== void 0) {
+    throw new Error("--quality only applies to MP4 output");
+  }
   if (!VALID_QUALITIES.includes(quality)) {
     throw new Error(`Invalid quality "${quality}". Valid: ${VALID_QUALITIES.join(", ")}`);
   }
@@ -742,13 +282,33 @@ async function runVideo(inputPath, opts) {
   if (isNaN(coverPreRoll) || coverPreRoll < 0) {
     throw new Error("Cover pre-roll must be a number of seconds >= 0");
   }
+  const animationsEnabled = opts.animations ?? outputFormat === "mp4";
+  const loop = opts.loop === void 0 ? 0 : Number(opts.loop);
+  const maxColors = opts.maxColors === void 0 ? 256 : Number(opts.maxColors);
+  const bayerScale = opts.bayerScale === void 0 ? void 0 : Number(opts.bayerScale);
+  const dither = opts.dither ?? "sierra2_4a";
+  if (outputFormat === "mp4" && (opts.loop || opts.maxColors || opts.dither || opts.bayerScale)) {
+    throw new Error("--loop, --max-colors, --dither, and --bayer-scale only apply to GIF output");
+  }
+  if (!Number.isSafeInteger(loop) || loop < -1 || loop > 65535) {
+    throw new Error("GIF loop must be an integer between -1 and 65535");
+  }
+  if (!Number.isSafeInteger(maxColors) || maxColors < 2 || maxColors > 256) {
+    throw new Error("GIF max colors must be an integer between 2 and 256");
+  }
+  if (!VALID_GIF_DITHERS.includes(dither)) {
+    throw new Error(`Invalid GIF dither "${dither}". Valid: ${VALID_GIF_DITHERS.join(", ")}`);
+  }
+  if (bayerScale !== void 0 && (!Number.isSafeInteger(bayerScale) || bayerScale < 0 || bayerScale > 5)) {
+    throw new Error("GIF Bayer scale must be an integer between 0 and 5");
+  }
   if (opts.transform) {
     await assertValidTransformStyle(opts.transform);
   }
   const inputBasename = basename2(resolvedInput);
-  const inputExt = extname3(inputBasename);
+  const inputExt = extname2(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
-  const outputPath = opts.output ? resolve2(opts.output) : resolve2(dirname2(resolvedInput), `${baseName}.mp4`);
+  const outputPath = opts.output ? resolve2(opts.output) : resolve2(dirname2(resolvedInput), `${baseName}.${outputFormat}`);
   await mkdir2(dirname2(outputPath), { recursive: true });
   console.error(`Reading: ${resolvedInput}`);
   const result = await readInput(resolvedInput);
@@ -759,8 +319,11 @@ async function runVideo(inputPath, opts) {
   let doc = result.doc;
   if (result.markdownDoc) {
     if (opts.autoTemplates === false) {
-      const { markdownToDoc: markdownToDoc2 } = await import("@bendyline/squisq/doc");
-      doc = markdownToDoc2(result.markdownDoc, { autoTemplates: false });
+      const { markdownToDoc, resolveAudioMapping } = await import("@bendyline/squisq/doc");
+      doc = await resolveAudioMapping(
+        markdownToDoc(result.markdownDoc, { autoTemplates: false }),
+        container
+      );
     }
   } else {
     console.error("Using pre-built Doc JSON");
@@ -772,23 +335,37 @@ async function runVideo(inputPath, opts) {
   if (opts.theme) {
     doc = { ...doc, themeId: opts.theme };
   }
+  const motionLabel = animationsEnabled ? "animations on" : "animations off";
+  const qualityLabel = outputFormat === "mp4" ? `, quality: ${quality}` : "";
   console.error(
-    `Rendering: ${fps} fps, quality: ${quality}, orientation: ${orientation}, captions: ${captions}`
+    `Rendering ${outputFormat.toUpperCase()}: ${fps} fps${qualityLabel}, orientation: ${orientation}, captions: ${captions}, ${motionLabel}`
   );
-  const result2 = await renderDocToMp4(doc, container, {
+  const sharedRenderOptions = {
     outputPath,
     fps,
-    quality,
     orientation,
     width: opts.width ? parseInt(opts.width, 10) : void 0,
     height: opts.height ? parseInt(opts.height, 10) : void 0,
     captionStyle,
     coverPreRoll,
-    onProgress: (phase, percent) => {
-      writeProgress(phase, percent, 100);
-    }
+    animationsEnabled,
+    onProgress: (phase, percent) => writeProgress(phase, percent, 100)
+  };
+  const result2 = outputFormat === "gif" ? await renderDocToGif(doc, container, {
+    ...sharedRenderOptions,
+    loop,
+    maxColors,
+    dither,
+    bayerScale
+  }) : await renderDocToMp4(doc, container, {
+    ...sharedRenderOptions,
+    quality
   });
   clearProgress();
+  const warnings = "warnings" in result2 && Array.isArray(result2.warnings) ? result2.warnings : [];
+  for (const warning of warnings) {
+    console.error(`  \u26A0 ${warning}`);
+  }
   console.error(
     `  \u2713 ${outputPath} (${result2.duration.toFixed(1)}s, ${result2.frameCount} frames)`
   );
@@ -808,7 +385,7 @@ function clearProgress() {
 
 // src/commands/validate.ts
 import { existsSync, statSync } from "fs";
-import { dirname as dirname3, extname as extname4, join as join4, resolve as resolve3 } from "path";
+import { dirname as dirname3, extname as extname3, join as join2, resolve as resolve3 } from "path";
 import { validateMarkdownDoc } from "@bendyline/squisq/doc";
 function registerValidateCommand(program2) {
   program2.command("validate").description("Validate a squisq markdown document and report structural problems").argument("<input>", "Path to .md file, .zip/.dbk container, or folder").option("--json", "Output diagnostics as JSON (for tooling and agents)").option("--strict", "Exit non-zero on warnings as well as errors").action(async (inputPath, opts) => {
@@ -831,11 +408,11 @@ async function runValidate(inputPath, opts) {
   }
   const entries = await container.listFiles();
   const containerPaths = new Set(entries.map((e) => e.path));
-  const isBareMarkdown = statSync(resolvedInput).isFile() && ![".zip", ".dbk"].includes(extname4(resolvedInput).toLowerCase());
+  const isBareMarkdown = statSync(resolvedInput).isFile() && ![".zip", ".dbk"].includes(extname3(resolvedInput).toLowerCase());
   const baseDir = dirname3(resolvedInput);
   const hasAsset = (path) => {
     if (containerPaths.has(path) || containerPaths.has(path.replace(/^\.\//, ""))) return true;
-    if (isBareMarkdown) return existsSync(join4(baseDir, path));
+    if (isBareMarkdown) return existsSync(join2(baseDir, path));
     return false;
   };
   const result = validateMarkdownDoc(markdownDoc, { assets: hasAsset });