@bendyline/squisq-cli 1.1.6 → 1.2.1

package/dist/index.js

@@ -1,18 +1,29 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/commands/convert.ts
 import { writeFile, mkdir } from "fs/promises";
-import { dirname, basename, extname as extname2, join as join2, resolve } from "path";
+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 } from "@bendyline/squisq/markdown";
+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",
@@ -29,6 +40,7 @@ var MIME_TYPES = {
   ".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";
 }
@@ -57,41 +69,70 @@ async function readInput(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 { container, markdownDoc };
+  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 { container, markdownDoc: null, doc };
+  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 readContainer(filePath) {
-  const data = await readFile(filePath);
-  const container = await zipToContainer(
-    data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
-  );
+async function resolveContainer(container, sourceFormat, missingMessage) {
   for (const name of DOC_JSON_NAMES) {
     const jsonData = await container.readFile(name);
     if (jsonData) {
-      const decoder = new TextDecoder();
-      const doc = JSON.parse(decoder.decode(jsonData));
-      return { container, markdownDoc: null, doc };
+      const doc = JSON.parse(new TextDecoder().decode(jsonData));
+      return { doc, container, sourceFormat };
     }
   }
   const markdown = await container.readDocument();
   if (!markdown) {
-    throw new Error(`No markdown document or doc.json found in container: ${filePath}`);
+    throw new Error(missingMessage);
   }
   const markdownDoc = parseMarkdown(markdown);
-  return { container, markdownDoc };
+  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();
@@ -105,270 +146,159 @@ async function readFolder(dirPath) {
       mimeFromExt(relPath)
     );
   }
-  for (const name of DOC_JSON_NAMES) {
-    const jsonData = await container.readFile(name);
-    if (jsonData) {
-      const decoder = new TextDecoder();
-      const doc = JSON.parse(decoder.decode(jsonData));
-      return { container, markdownDoc: null, doc };
-    }
-  }
-  const markdown = await container.readDocument();
-  if (!markdown) {
-    throw new Error(`No markdown document or doc.json found in folder: ${dirPath}`);
-  }
-  const markdownDoc = parseMarkdown(markdown);
-  return { container, markdownDoc };
+  return resolveContainer(
+    container,
+    "folder",
+    `No markdown document or doc.json found in folder: ${dirPath}`
+  );
 }
 
-// src/commands/convert.ts
-var ALL_FORMATS = ["docx", "pptx", "pdf", "html", "htmlzip", "epub", "dbk"];
-function parseFormats(value) {
-  const requested = value.split(",").map((s) => s.trim().toLowerCase());
-  const valid = [];
-  for (const r of requested) {
-    if (ALL_FORMATS.includes(r)) {
-      valid.push(r);
-    } else {
-      console.warn(`Unknown format "${r}" \u2014 skipping. Valid: ${ALL_FORMATS.join(", ")}`);
-    }
-  }
-  if (valid.length === 0) {
-    throw new Error(`No valid formats specified. Valid: ${ALL_FORMATS.join(", ")}`);
-  }
-  return valid;
-}
-function registerConvertCommand(program2) {
-  program2.command("convert").description("Convert a markdown document to DOCX, PPTX, PDF, HTML, and DBK container formats").argument("<input>", "Path to .md file, .zip/.dbk container, or folder").option("-o, --output-dir <dir>", "Output directory (default: same as input)").option(
-    "-f, --formats <list>",
-    `Comma-separated formats to produce (default: all). Valid: ${ALL_FORMATS.join(", ")}`
-  ).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)"
-  ).action(async (inputPath, opts) => {
-    try {
-      await runConvert(inputPath, opts);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      console.error(`Error: ${message}`);
-      process.exitCode = 1;
-    }
+// 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 runConvert(inputPath, opts) {
-  const resolvedInput = resolve(inputPath);
-  const formats = opts.formats ? parseFormats(opts.formats) : [...ALL_FORMATS];
-  const outputDir = opts.outputDir ? resolve(opts.outputDir) : dirname(resolvedInput);
-  const inputBasename = basename(resolvedInput);
-  const inputExt = extname2(inputBasename);
-  const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
-  await mkdir(outputDir, { recursive: true });
-  if (opts.theme) {
-    const { getAvailableThemes } = await import("@bendyline/squisq/schemas");
-    const themes = getAvailableThemes();
-    if (!themes.includes(opts.theme)) {
-      throw new Error(`Unknown theme "${opts.theme}". Available: ${themes.join(", ")}`);
-    }
-  }
-  if (opts.transform) {
-    const { getTransformStyleIds } = await import("@bendyline/squisq/transform");
-    const styles = getTransformStyleIds();
-    if (!styles.includes(opts.transform)) {
+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(
-        `Unknown transform style "${opts.transform}". Available: ${styles.join(", ")}`
+        `SQUISQ_FFMPEG is set to "${envPath}" but running "${envPath} -version" failed. Fix the path or unset SQUISQ_FFMPEG.`
       );
     }
+    return { path: envPath, source: "env" };
   }
-  console.error(`Reading: ${resolvedInput}`);
-  const result = await readInput(resolvedInput);
-  const { container } = result;
-  if (!result.markdownDoc) {
-    throw new Error(
-      "Convert command requires a markdown document. JSON Doc input is not supported for convert \u2014 use the video command instead."
-    );
-  }
-  let exportMarkdownDoc = result.markdownDoc;
-  if (opts.transform) {
-    exportMarkdownDoc = await applyTransformToMarkdown(
-      result.markdownDoc,
-      container,
-      opts.transform,
-      opts.theme
-    );
-    console.error(`  Applied transform: ${opts.transform}`);
+  const command = process.platform === "win32" ? "where" : "which";
+  const found = await run(command, ["ffmpeg"]);
+  if (found) {
+    return { path: found.split("\n")[0].trim(), source: "path" };
   }
-  const themeId = opts.theme;
-  for (const format of formats) {
-    const outPath = join2(outputDir, `${baseName}.${format}`);
-    switch (format) {
-      case "docx": {
-        const { markdownDocToDocx } = await import("@bendyline/squisq-formats/docx");
-        const buf = await markdownDocToDocx(exportMarkdownDoc, { themeId });
-        await writeFile(outPath, Buffer.from(buf));
-        break;
-      }
-      case "pptx": {
-        const { markdownDocToPptx } = await import("@bendyline/squisq-formats/pptx");
-        const images = await collectContainerImages(container);
-        const buf = await markdownDocToPptx(exportMarkdownDoc, { themeId, images });
-        await writeFile(outPath, Buffer.from(buf));
-        break;
-      }
-      case "pdf": {
-        const { markdownDocToPdf } = await import("@bendyline/squisq-formats/pdf");
-        const buf = await markdownDocToPdf(exportMarkdownDoc, { themeId });
-        await writeFile(outPath, Buffer.from(buf));
-        break;
-      }
-      case "html": {
-        const { markdownToDoc } = await import("@bendyline/squisq/doc");
-        const { docToHtml } = await import("@bendyline/squisq-formats/html");
-        const { PLAYER_BUNDLE } = await import("@bendyline/squisq-react/standalone-source");
-        const doc = markdownToDoc(exportMarkdownDoc);
-        const images = await collectImagesForHtml(doc, container);
-        const html = docToHtml(doc, {
-          playerScript: PLAYER_BUNDLE,
-          images,
-          title: baseName,
-          mode: "static",
-          themeId
-        });
-        await writeFile(outPath, html, "utf-8");
-        break;
-      }
-      case "htmlzip": {
-        const { markdownToDoc } = await import("@bendyline/squisq/doc");
-        const { docToHtmlZip } = await import("@bendyline/squisq-formats/html");
-        const { PLAYER_BUNDLE } = await import("@bendyline/squisq-react/standalone-source");
-        const doc = markdownToDoc(exportMarkdownDoc);
-        const images = await collectImagesForHtml(doc, container);
-        const blob = await docToHtmlZip(doc, {
-          playerScript: PLAYER_BUNDLE,
-          images,
-          title: baseName,
-          mode: "static",
-          themeId
-        });
-        const buf = Buffer.from(await blob.arrayBuffer());
-        await writeFile(outPath.replace(/\.htmlzip$/, ".html.zip"), buf);
-        break;
-      }
-      case "epub": {
-        const { markdownDocToEpub } = await import("@bendyline/squisq-formats/epub");
-        const images = await collectContainerImages(container);
-        const epubAudio = /* @__PURE__ */ new Map();
-        const audioSegments = result.doc?.audio?.segments;
-        if (audioSegments?.length) {
-          for (const seg of audioSegments) {
-            const data = await container.readFile(seg.src);
-            if (data) epubAudio.set(seg.src, data);
-          }
-        }
-        const hasNarration = epubAudio.size > 0;
-        const buf = await markdownDocToEpub(exportMarkdownDoc, {
-          title: baseName,
-          themeId,
-          images,
-          audio: hasNarration ? epubAudio : void 0,
-          audioSegments: hasNarration ? audioSegments : void 0,
-          totalDuration: hasNarration ? result.doc?.duration : void 0
-        });
-        await writeFile(outPath, Buffer.from(buf));
-        break;
-      }
-      case "dbk": {
-        const { containerToZip } = await import("@bendyline/squisq-formats/container");
-        const blob = await containerToZip(container);
-        const buf = await blob.arrayBuffer();
-        await writeFile(outPath, Buffer.from(buf));
-        break;
-      }
+  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" };
     }
-    console.error(`  \u2713 ${outPath}`);
+  } catch {
   }
-  console.error("Done.");
+  return null;
 }
-async function applyTransformToMarkdown(markdownDoc, container, transformStyle, themeId) {
-  const { markdownToDoc, docToMarkdown } = await import("@bendyline/squisq/doc");
-  const { applyTransform, extractDocImages } = await import("@bendyline/squisq/transform");
-  const doc = markdownToDoc(markdownDoc);
-  const images = extractDocImages(doc.blocks);
-  const result = applyTransform(doc, transformStyle, {
-    themeId,
-    images
-  });
-  return docToMarkdown(result.doc);
+async function detectFfmpeg() {
+  const detection = await detectFfmpegDetailed();
+  return detection?.path ?? null;
 }
-async function collectImagesForHtml(doc, container) {
-  const { collectImagePaths, extractFilename } = await import("@bendyline/squisq-formats/html");
-  const images = /* @__PURE__ */ new Map();
-  const docPaths = collectImagePaths(doc);
-  const needByFilename = /* @__PURE__ */ new Set();
-  for (const imgPath of docPaths) {
-    const data = await container.readFile(imgPath);
-    if (data) {
-      images.set(imgPath, data);
-      const filename = extractFilename(imgPath);
-      if (filename !== imgPath) images.set(filename, data);
-    } else {
-      needByFilename.add(extractFilename(imgPath));
-    }
-  }
-  if (needByFilename.size > 0) {
-    const files = await container.listFiles();
-    for (const file of files) {
-      const filename = extractFilename(file.path);
-      if (needByFilename.has(filename)) {
-        const data = await container.readFile(file.path);
-        if (data) {
-          images.set(filename, data);
-          images.set(file.path, data);
-        }
-      }
-    }
+
+// 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 });
   }
-  return images;
+  if (usable.length === 0) return null;
+  return mixTimelineClips(ffmpegPath, usable);
 }
-async function collectContainerImages(container) {
-  const images = /* @__PURE__ */ new Map();
-  const files = await container.listFiles();
-  for (const file of files) {
-    if (/\.(jpg|jpeg|png|gif|webp|svg|bmp|avif)$/i.test(file.path)) {
-      const data = await container.readFile(file.path);
-      if (data) {
-        images.set(file.path, data);
-      }
+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 });
   }
-  return images;
 }
 
-// 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";
-
 // src/api.ts
-import { generateRenderHtml } from "@bendyline/squisq-video";
-import { resolveDimensions } from "@bendyline/squisq-video";
-
-// src/util/detectFfmpeg.ts
-import { execFile } from "child_process";
-async function detectFfmpeg() {
-  const command = process.platform === "win32" ? "where" : "which";
-  return new Promise((resolve3) => {
-    execFile(command, ["ffmpeg"], { timeout: 5e3 }, (err, stdout) => {
-      if (err || !stdout.trim()) {
-        resolve3(null);
-        return;
-      }
-      const path = stdout.trim().split("\n")[0].trim();
-      resolve3(path);
-    });
+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
   });
 }
-
-// src/api.ts
-import { MemoryContentContainer as MemoryContentContainer2 } from "@bendyline/squisq/storage";
 async function renderDocToMp4(doc, container, options) {
   const {
     outputPath,
@@ -387,7 +317,7 @@ async function renderDocToMp4(doc, container, options) {
   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"
+      "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);
@@ -401,20 +331,25 @@ async function renderDocToMp4(doc, container, options) {
     }
   }
   const audio = /* @__PURE__ */ new Map();
-  const audioBuffers = [];
   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);
-        audioBuffers.push(data);
       }
     }
   }
-  let concatenatedAudio = null;
-  if (audioBuffers.length > 0) {
-    concatenatedAudio = await concatenateAudioBuffers(audioBuffers, ffmpegPath);
+  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");
@@ -428,7 +363,16 @@ async function renderDocToMp4(doc, container, options) {
   });
   onProgress?.("launching browser", 15);
   const { chromium } = await import("playwright-core");
-  const browser = await chromium.launch({ headless: true });
+  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 }
   });
@@ -446,7 +390,9 @@ async function renderDocToMp4(doc, container, options) {
     const errorDetail = pageErrors.length ? `
 Page errors:
   ${pageErrors.join("\n  ")}` : "\nNo page errors captured \u2014 the player may have failed to mount.";
-    throw new Error(`Render API did not initialize within 15 seconds.${errorDetail}`);
+    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();
@@ -494,11 +440,8 @@ Page errors:
   }
   await browser.close();
   onProgress?.("encoding video", 80);
-  let encodingAudio = concatenatedAudio;
-  if (coverPreRoll > 0 && concatenatedAudio) {
-    encodingAudio = await addAudioDelay(ffmpegPath, concatenatedAudio, coverPreRoll);
-  }
-  const { framesToMp4Native } = await import("./nativeEncoder-EXDP2O5B.js");
+  const encodingAudio = await buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll);
+  const { framesToMp4Native } = await import("./nativeEncoder-DLLAT2RT.js");
   await framesToMp4Native(ffmpegPath, frames, encodingAudio, outputPath, {
     fps,
     quality,
@@ -517,101 +460,224 @@ Page errors:
     outputPath
   };
 }
-async function concatenateAudioBuffers(buffers, ffmpegPath) {
-  if (buffers.length === 0) return new Uint8Array(0);
-  if (buffers.length === 1) return new Uint8Array(buffers[0]);
-  if (ffmpegPath) {
-    return concatenateAudioNative(ffmpegPath, buffers);
-  }
-  const totalLength = buffers.reduce((sum, b) => sum + b.byteLength, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const buf of buffers) {
-    result.set(new Uint8Array(buf), offset);
-    offset += buf.byteLength;
-  }
-  return result;
-}
-async function concatenateAudioNative(ffmpegPath, buffers) {
-  const { writeFile: writeFile2, readFile: readFile2, mkdir: mkdir3, rm } = await import("fs/promises");
-  const { join: join3 } = await import("path");
-  const { tmpdir } = await import("os");
-  const { randomBytes } = await import("crypto");
-  const { execFile: execFile2 } = await import("child_process");
-  const tmpId = randomBytes(8).toString("hex");
-  const workDir = join3(tmpdir(), `squisq-audio-concat-${tmpId}`);
-  await mkdir3(workDir, { recursive: true });
-  try {
-    const segmentPaths = [];
-    for (let i = 0; i < buffers.length; i++) {
-      const segPath = join3(workDir, `seg-${i}.mp3`);
-      await writeFile2(segPath, new Uint8Array(buffers[i]));
-      segmentPaths.push(segPath);
+
+// 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 });
+      }
     }
-    const listPath = join3(workDir, "concat-list.txt");
-    const listContent = segmentPaths.map((p) => `file '${p.replace(/\\/g, "/")}'`).join("\n");
-    await writeFile2(listPath, listContent);
-    const outputPath = join3(workDir, "combined.mp3");
-    await new Promise((resolve3, reject) => {
-      execFile2(
-        ffmpegPath,
-        ["-y", "-f", "concat", "-safe", "0", "-i", listPath, "-c", "copy", outputPath],
-        { timeout: 12e4 },
-        (err) => {
-          if (err) reject(new Error(`ffmpeg audio concat failed: ${err.message}`));
-          else resolve3();
-        }
-      );
-    });
-    const data = await readFile2(outputPath);
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-  } finally {
-    await rm(workDir, { recursive: true, force: true });
+  };
+}
+function createCliRegistry() {
+  const registry = defaultRegistry2();
+  registry.register(mp4Format());
+  return registry;
+}
+
+// src/util/applyTransformPipeline.ts
+async function assertValidTransformStyle(style) {
+  const { getTransformStyleIds } = await import("@bendyline/squisq/transform");
+  const styles = getTransformStyleIds();
+  if (!styles.includes(style)) {
+    throw new Error(`Unknown transform style "${style}". Available: ${styles.join(", ")}`);
   }
 }
-async function addAudioDelay(ffmpegPath, audioData, delaySecs) {
-  const { writeFile: writeFile2, readFile: readFile2, rm } = await import("fs/promises");
-  const { join: join3 } = await import("path");
-  const { tmpdir } = await import("os");
-  const { randomBytes } = await import("crypto");
-  const { execFile: execFile2 } = await import("child_process");
-  const tmpId = randomBytes(8).toString("hex");
-  const inputPath = join3(tmpdir(), `squisq-audio-delay-in-${tmpId}.mp3`);
-  const outputPath = join3(tmpdir(), `squisq-audio-delay-out-${tmpId}.mp3`);
-  try {
-    await writeFile2(inputPath, audioData);
-    const delayMs = Math.round(delaySecs * 1e3);
-    await new Promise((resolve3, reject) => {
-      execFile2(
-        ffmpegPath,
-        [
-          "-y",
-          "-i",
-          inputPath,
-          "-af",
-          `adelay=${delayMs}|${delayMs}`,
-          "-c:a",
-          "libmp3lame",
-          "-b:a",
-          "128k",
-          outputPath
-        ],
-        { timeout: 6e4 },
-        (err) => {
-          if (err) reject(new Error(`ffmpeg audio delay failed: ${err.message}`));
-          else resolve3();
-        }
-      );
+async function assertValidThemeId(themeId, source) {
+  const { getAvailableThemes } = await import("@bendyline/squisq/schemas");
+  const builtins = getAvailableThemes();
+  let customIds = [];
+  if (source.markdownDoc) {
+    const { readCustomThemesFromFrontmatter } = await import("@bendyline/squisq/doc");
+    customIds = (readCustomThemesFromFrontmatter(source.markdownDoc.frontmatter) ?? []).map(
+      (t) => t.id
+    );
+  } else if (source.doc?.customThemes) {
+    customIds = source.doc.customThemes.map((t) => t.id);
+  }
+  if (!builtins.includes(themeId) && !customIds.includes(themeId)) {
+    throw new Error(
+      `Unknown theme "${themeId}". Available: ${[...builtins, ...customIds].join(", ")}`
+    );
+  }
+}
+async function applyTransformToDoc(doc, transformStyle, themeId) {
+  const { applyTransform, extractDocImages } = await import("@bendyline/squisq/transform");
+  const images = extractDocImages(doc.blocks);
+  const result = applyTransform(doc, transformStyle, {
+    themeId,
+    images
+  });
+  return result.doc;
+}
+
+// src/commands/convert.ts
+var VALID_FORMATS = [...BUILTIN_FORMAT_IDS, "mp4"];
+var DEFAULT_FORMATS = [
+  "docx",
+  "pptx",
+  "pdf",
+  "html",
+  "htmlzip",
+  "epub",
+  "dbk"
+];
+function isValidFormat(id) {
+  return VALID_FORMATS.includes(id);
+}
+function parseFormats(value) {
+  const requested = value.split(",").map((s) => s.trim().toLowerCase());
+  const valid = [];
+  for (const r of requested) {
+    if (isValidFormat(r)) {
+      valid.push(r);
+    } else {
+      console.warn(`Unknown format "${r}" \u2014 skipping. Valid: ${VALID_FORMATS.join(", ")}`);
+    }
+  }
+  if (valid.length === 0) {
+    throw new Error(`No valid formats specified. Valid: ${VALID_FORMATS.join(", ")}`);
+  }
+  return valid;
+}
+function formatFromOutputPath(outputPath) {
+  const lower = outputPath.toLowerCase();
+  if (lower.endsWith(".html.zip")) return "htmlzip";
+  const ext = extname2(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(", ")}`
+    );
+  }
+  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(
+    "-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(
+    "--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) => {
+    try {
+      await runConvert(inputPath, opts);
+    } catch (err) {
+      if (err instanceof ConversionError2) {
+        console.error(`Error: ${err.message}`);
+        if (err.hint) console.error(`  ${err.hint}`);
+      } else {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+      }
+      process.exitCode = 1;
+    }
+  });
+}
+function resolveFormats(opts) {
+  const hasOutput = Boolean(opts.output);
+  const hasFormatSelection = Boolean(opts.formats || opts.format);
+  if (hasOutput && hasFormatSelection) {
+    throw new Error(
+      "--output is a single-file destination and cannot be combined with --formats/--format."
+    );
+  }
+  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);
+  }
+  return [...DEFAULT_FORMATS];
+}
+async function runConvert(inputPath, opts) {
+  const resolvedInput = resolve(inputPath);
+  const formats = resolveFormats(opts);
+  const inputBasename = basename(resolvedInput);
+  const inputExt = extname2(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);
+  if (opts.theme) {
+    await assertValidThemeId(opts.theme, result);
+  }
+  const source = result.markdownDoc ? {
+    kind: "markdown",
+    markdown: result.markdownDoc,
+    container: result.container,
+    baseName
+  } : { kind: "doc", doc: result.doc, container: result.container, baseName };
+  if (opts.transform) {
+    console.error(`  Applying transform: ${opts.transform}`);
+  }
+  for (const format of formats) {
+    const conversion = await convert(source, format, {
+      themeId: opts.theme,
+      transformStyle: opts.transform,
+      autoTemplates: opts.autoTemplates,
+      title: baseName
     });
-    const data = await readFile2(outputPath);
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-  } finally {
-    await rm(inputPath, { force: true });
-    await rm(outputPath, { force: true });
+    for (const warning of conversion.warnings) {
+      console.error(`  \u26A0 ${warning}`);
+    }
+    const outPath = opts.output ? resolve(opts.output) : join3(
+      opts.outputDir ? resolve(opts.outputDir) : dirname(resolvedInput),
+      conversion.suggestedFilename
+    );
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, Buffer.from(conversion.bytes));
+    console.error(`  \u2713 ${outPath}`);
   }
+  console.error("Done.");
 }
 
 // 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";
 var VALID_QUALITIES = ["draft", "normal", "high"];
 var VALID_ORIENTATIONS = ["landscape", "portrait"];
 var VALID_CAPTIONS = ["off", "standard", "social"];
@@ -628,6 +694,16 @@ function registerVideoCommand(program2) {
     "--captions <style>",
     `Caption style: ${VALID_CAPTIONS.join(", ")} (default: off)`,
     "off"
+  ).option(
+    "--no-auto-templates",
+    "Disable content-aware template auto-picking for unannotated headings"
+  ).option("-t, --theme <id>", "Squisq theme ID to apply (e.g., documentary, cinematic, bold)").option(
+    "--transform <style>",
+    "Transform style to apply before rendering (e.g., documentary, magazine, minimal)"
+  ).option(
+    "--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) => {
     try {
       if (outputArg && !opts.output) {
@@ -662,6 +738,13 @@ async function runVideo(inputPath, opts) {
     throw new Error(`Invalid captions "${captions}". Valid: ${VALID_CAPTIONS.join(", ")}`);
   }
   const captionStyle = captions === "off" ? void 0 : captions;
+  const coverPreRoll = parseFloat(opts.coverPreroll ?? "2");
+  if (isNaN(coverPreRoll) || coverPreRoll < 0) {
+    throw new Error("Cover pre-roll must be a number of seconds >= 0");
+  }
+  if (opts.transform) {
+    await assertValidTransformStyle(opts.transform);
+  }
   const inputBasename = basename2(resolvedInput);
   const inputExt = extname3(inputBasename);
   const baseName = inputExt ? inputBasename.slice(0, -inputExt.length) : inputBasename;
@@ -670,15 +753,24 @@ async function runVideo(inputPath, opts) {
   console.error(`Reading: ${resolvedInput}`);
   const result = await readInput(resolvedInput);
   const { container } = result;
-  let doc;
-  if (result.doc) {
-    console.error("Using pre-built Doc JSON");
-    doc = result.doc;
-  } else if (result.markdownDoc) {
-    const { markdownToDoc } = await import("@bendyline/squisq/doc");
-    doc = markdownToDoc(result.markdownDoc);
+  if (opts.theme) {
+    await assertValidThemeId(opts.theme, result);
+  }
+  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 });
+    }
   } else {
-    throw new Error("No document found in input");
+    console.error("Using pre-built Doc JSON");
+  }
+  if (opts.transform) {
+    doc = await applyTransformToDoc(doc, opts.transform, opts.theme);
+    console.error(`  Applied transform: ${opts.transform}`);
+  }
+  if (opts.theme) {
+    doc = { ...doc, themeId: opts.theme };
   }
   console.error(
     `Rendering: ${fps} fps, quality: ${quality}, orientation: ${orientation}, captions: ${captions}`
@@ -691,7 +783,7 @@ async function runVideo(inputPath, opts) {
     width: opts.width ? parseInt(opts.width, 10) : void 0,
     height: opts.height ? parseInt(opts.height, 10) : void 0,
     captionStyle,
-    coverPreRoll: 2,
+    coverPreRoll,
     onProgress: (phase, percent) => {
       writeProgress(phase, percent, 100);
     }
@@ -714,13 +806,134 @@ function clearProgress() {
   process.stderr.write("\r" + " ".repeat(80) + "\r");
 }
 
+// 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 { 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) => {
+    try {
+      const exitCode = await runValidate(inputPath, opts);
+      process.exitCode = exitCode;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Error: ${message}`);
+      process.exitCode = 2;
+    }
+  });
+}
+async function runValidate(inputPath, opts) {
+  const resolvedInput = resolve3(inputPath);
+  const { container, markdownDoc, doc } = await readInput(resolvedInput);
+  if (!markdownDoc) {
+    const diagnostics = doc.diagnostics ?? [];
+    return report(diagnostics, opts, "doc.json input \u2014 markdown-level checks skipped");
+  }
+  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 baseDir = dirname3(resolvedInput);
+  const hasAsset = (path) => {
+    if (containerPaths.has(path) || containerPaths.has(path.replace(/^\.\//, ""))) return true;
+    if (isBareMarkdown) return existsSync(join4(baseDir, path));
+    return false;
+  };
+  const result = validateMarkdownDoc(markdownDoc, { assets: hasAsset });
+  return report(result.diagnostics, opts);
+}
+function severityLabel(severity) {
+  switch (severity) {
+    case "error":
+      return "ERROR  ";
+    case "warning":
+      return "warning";
+    case "info":
+      return "\u2139 info ";
+  }
+}
+function report(diagnostics, opts, note) {
+  const errorCount = diagnostics.filter((d) => d.severity === "error").length;
+  const warningCount = diagnostics.filter((d) => d.severity === "warning").length;
+  const infoCount = diagnostics.filter((d) => d.severity === "info").length;
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ errorCount, warningCount, infoCount, diagnostics }, null, 2)}
+`
+    );
+  } else {
+    if (note) console.error(note);
+    for (const d of diagnostics) {
+      const location = d.line != null ? `line ${d.line}` : d.blockId ?? "\u2014";
+      console.error(`${severityLabel(d.severity)}  ${location}  [${d.code}] ${d.message}`);
+    }
+    if (diagnostics.length === 0) {
+      console.error("\u2713 No problems found");
+    } else {
+      console.error(`
+${errorCount} error(s), ${warningCount} warning(s), ${infoCount} info`);
+    }
+  }
+  if (errorCount > 0) return 1;
+  if (opts.strict && warningCount > 0) return 1;
+  return 0;
+}
+
+// src/commands/doctor.ts
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Check that ffmpeg and Playwright Chromium are available for video rendering").action(async () => {
+    const allPresent = await runDoctor();
+    process.exitCode = allPresent ? 0 : 1;
+  });
+}
+async function runDoctor() {
+  let allPresent = true;
+  console.error(`Node:     ${process.version}`);
+  try {
+    const detection = await detectFfmpegDetailed();
+    if (detection) {
+      const version2 = await getFfmpegVersion(detection.path);
+      console.error(
+        `ffmpeg:   ${detection.path} (source: ${detection.source}) \u2014 ${version2 ?? "version unknown"}`
+      );
+    } else {
+      allPresent = false;
+      console.error("ffmpeg:   not found.");
+      console.error("          Install it with:");
+      console.error("            macOS:   brew install ffmpeg");
+      console.error("            Ubuntu:  sudo apt install ffmpeg");
+      console.error("            Windows: winget install ffmpeg");
+      console.error("          Or: npm install ffmpeg-static, or set SQUISQ_FFMPEG.");
+    }
+  } catch (err) {
+    allPresent = false;
+    console.error(`ffmpeg:   ${err instanceof Error ? err.message : String(err)}`);
+  }
+  try {
+    const { chromium } = await import("playwright-core");
+    const browser = await chromium.launch({ headless: true });
+    await browser.close();
+    console.error(`Chromium: available (${chromium.executablePath()})`);
+  } catch (err) {
+    allPresent = false;
+    const detail = err instanceof Error ? err.message.split("\n")[0] : String(err);
+    console.error(`Chromium: not available \u2014 ${detail}`);
+    console.error("          Run: npx playwright install chromium");
+  }
+  console.error(allPresent ? "\n\u2713 All checks passed" : "\n\u2717 Some checks failed");
+  return allPresent;
+}
+
 // src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
 console.error(
-  "\x1B[36m{[\x1B[0m \x1B[1msquiggly square\x1B[0m \x1B[2m\u2014\x1B[0m \x1B[1msquisq\x1B[0m \x1B[2m\u2014\x1B[0m \x1B[33mv1.0.0\x1B[0m \x1B[36m]}\x1B[0m"
+  `\x1B[36m{[\x1B[0m \x1B[1msquiggly square\x1B[0m \x1B[2m\u2014\x1B[0m \x1B[1msquisq\x1B[0m \x1B[2m\u2014\x1B[0m \x1B[33mv${version}\x1B[0m \x1B[36m]}\x1B[0m`
 );
 var program = new Command();
-program.name("squisq").description("Squisq CLI \u2014 convert and process markdown-based documents").version("1.0.0");
+program.name("squisq").description("Squisq CLI \u2014 convert and process markdown-based documents").version(version);
 registerConvertCommand(program);
 registerVideoCommand(program);
+registerValidateCommand(program);
+registerDoctorCommand(program);
 program.parse();
 //# sourceMappingURL=index.js.map