@bendyline/squisq-cli 2.4.1 → 2.4.3

package/README.md

@@ -58,7 +58,7 @@ Notes:
 
 ### `squisq video <input> [output]`
 
-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.
+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. Documents with Mermaid fences automatically use the full standalone player so diagrams are captured; other documents keep the smaller light player. GIF has no audio track.
 
 ```bash
 squisq video input.md output.mp4
@@ -177,17 +177,16 @@ const result = await convert({ kind: 'markdown', markdown: '# Hello' }, 'docx');
 
 ```ts
 import { renderDocToMp4, readInput } from '@bendyline/squisq-cli/api';
-import { markdownToDoc } from '@bendyline/squisq/doc';
 
 // Load a document from disk (.md, .zip/.dbk, folder, or Doc .json)
 const input = await readInput('./my-article.md');
 
-// readInput returns { container, markdownDoc, doc? } — doc is only set for
-// JSON input, so build the Doc from markdown when needed:
-const doc = input.doc ?? markdownToDoc(input.markdownDoc!);
+// `doc` is always normalized and ready to render. `markdownDoc` is present
+// only when the source was markdown-shaped; `sourceFormat` identifies the input.
+const { doc, container, markdownDoc, sourceFormat } = input;
 
 // Render to MP4
-const result = await renderDocToMp4(doc, input.container, {
+const result = await renderDocToMp4(doc, container, {
   outputPath: './output.mp4',
   fps: 30, // default 30
   quality: 'high', // 'draft' | 'normal' | 'high' (default 'normal')
@@ -269,7 +268,7 @@ await extractThumbnails({
 
 ### Other exports
 
-- `readInput(inputPath)` → `{ container: MemoryContentContainer, markdownDoc: MarkdownDocument | null, doc?: Doc }`
+- `readInput(inputPath)` → `{ doc: Doc, container: ContentContainer, markdownDoc?: MarkdownDocument, sourceFormat: FormatId }`
 - `MemoryContentContainer` (re-export from `@bendyline/squisq/storage`)
 - `VideoQuality`, `VideoOrientation` types (re-exports from `@bendyline/squisq-video`)
 

package/THIRD_PARTY_LICENSES.txt

@@ -1,6 +1,6 @@
 THIRD-PARTY LICENSES FOR @bendyline/squisq-cli
 
-The inventory below covers the bundled light standalone player artifact.
+The inventory below covers the bundled light and full standalone player artifacts.
 
 Generated from the actual esbuild input graph. Package-local license, copying,
 and notice files are reproduced verbatim. When an npm tarball omits its

package/dist/{api-HBPJQ7MA.js → api-PBBQQMRP.js}

@@ -11,7 +11,7 @@ import {
   readInput,
   renderDocToGif,
   renderDocToMp4
-} from "./chunk-WR2BZJ77.js";
+} from "./chunk-X3GFPKRJ.js";
 import {
   GIF_EXPORT_DEFAULTS,
   framesToGifNative,

package/dist/api.js

@@ -9,8 +9,8 @@ import {
 
 // src/api.ts
 import { readFile as readFile3 } from "fs/promises";
-import { resolveMediaSchedule } from "@bendyline/squisq/schemas";
-import { flattenBlocks } from "@bendyline/squisq/doc";
+import { resolveMediaSchedule as resolveMediaSchedule2 } from "@bendyline/squisq/schemas";
+import { flattenBlocks as flattenBlocks2 } from "@bendyline/squisq/doc";
 import { ffmpegGifOutputArgs, generateRenderHtml } from "@bendyline/squisq-video";
 import { resolveDimensions } from "@bendyline/squisq-video";
 import {
@@ -22,17 +22,17 @@ import {
 import { execFile } from "child_process";
 function run(command, args, signal) {
   signal?.throwIfAborted();
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     execFile(command, args, { timeout: 5e3, signal }, (err, stdout) => {
       if (signal?.aborted) {
         reject(signal.reason);
         return;
       }
       if (err || !stdout.trim()) {
-        resolve(null);
+        resolve2(null);
         return;
       }
-      resolve(stdout.trim());
+      resolve2(stdout.trim());
     });
   });
 }
@@ -76,7 +76,7 @@ async function detectFfmpegDetailed(signal) {
 import { computeAudioTimeline } from "@bendyline/squisq-video";
 async function buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll, signal) {
   signal?.throwIfAborted();
-  const timeline = computeAudioTimeline(doc, coverPreRoll);
+  const timeline = computeAudioTimeline(doc, coverPreRoll, { includeVideoAudio: false });
   if (timeline.length === 0) return null;
   const bytesBySrc = /* @__PURE__ */ new Map();
   const readSrc = async (src) => {
@@ -271,6 +271,27 @@ function createMediaBudget() {
   };
 }
 
+// src/util/playerBundle.ts
+import { flattenBlocks } from "@bendyline/squisq/doc";
+function selectStandalonePlayerVariant(doc) {
+  for (const block of flattenBlocks(doc.blocks)) {
+    if (block.layers?.some((layer) => layer.type === "mermaid")) return "full";
+    if (containsMermaidFence(block.contents)) return "full";
+  }
+  return "light";
+}
+function containsMermaidFence(value) {
+  if (Array.isArray(value)) return value.some(containsMermaidFence);
+  if (!isRecord(value)) return false;
+  if (value.type === "code" && typeof value.lang === "string" && value.lang.trim().toLowerCase() === "mermaid") {
+    return true;
+  }
+  return containsMermaidFence(value.children);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
 // src/registry.ts
 import { randomBytes } from "crypto";
 import { readFile, rm } from "fs/promises";
@@ -397,13 +418,45 @@ function createCliRegistry() {
 import { MemoryContentContainer as MemoryContentContainer2 } from "@bendyline/squisq/storage";
 
 // src/util/readInput.ts
-import { readFile as readFile2, readdir, stat } from "fs/promises";
-import { join as join2, extname } from "path";
+import { readFile as readFile2, readdir, realpath, stat } from "fs/promises";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join as join2,
+  posix,
+  relative,
+  resolve,
+  sep,
+  win32
+} from "path";
 import { parseMarkdown, stringifyMarkdown } from "@bendyline/squisq/markdown";
 import { markdownToDoc, resolveAudioMapping } from "@bendyline/squisq/doc";
+import { resolveMediaSchedule, validateDocSchema } from "@bendyline/squisq/schemas";
 import { MemoryContentContainer } from "@bendyline/squisq/storage";
 import { zipToContainer } from "@bendyline/squisq-formats/container";
 import { defaultRegistry as defaultRegistry2 } from "@bendyline/squisq-formats";
+var DocInputValidationError = class extends Error {
+  constructor(source, issues) {
+    const detail = issues.map(formatSchemaIssueForError).join("; ");
+    super(`${source} is not a valid squisq Doc: ${detail}`);
+    this.name = "DocInputValidationError";
+    this.issues = issues;
+    this.diagnostics = issues.map((issue) => ({
+      severity: "error",
+      code: "invalid-doc-schema",
+      message: `${issue.path} ${issue.message}`
+    }));
+  }
+};
+function formatSchemaIssueForError(issue) {
+  if (issue.path === "$") {
+    const got = /\(got ([^)]+)\)/.exec(issue.message)?.[1] ?? "an invalid value";
+    return `expected a JSON object, got ${got}`;
+  }
+  return `"${issue.path}" ${issue.message}`;
+}
 var MIME_TYPES = {
   ".md": "text/markdown",
   ".txt": "text/plain",
@@ -418,7 +471,11 @@ var MIME_TYPES = {
   ".wav": "audio/wav",
   ".ogg": "audio/ogg",
   ".mp4": "video/mp4",
-  ".webm": "video/webm"
+  ".webm": "video/webm",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf"
 };
 var IMPORTER_EXTS = [".docx", ".pptx", ".pdf", ".xlsx", ".csv", ".html", ".htm"];
 function mimeFromExt(filePath) {
@@ -444,8 +501,10 @@ async function readInput(inputPath, options) {
   throwIfAborted(options?.signal);
   const result = await readInputRaw(inputPath, options);
   throwIfAborted(options?.signal);
+  assertValidDoc(result.doc, inputPath);
   const doc = await resolveAudioMapping(result.doc, result.container);
   throwIfAborted(options?.signal);
+  assertValidDoc(doc, inputPath);
   return doc === result.doc ? result : { ...result, doc };
 }
 async function readInputRaw(inputPath, options) {
@@ -498,69 +557,160 @@ async function readUtf8File(filePath, signal) {
 }
 async function readMarkdownFile(filePath, signal) {
   const content = await readUtf8File(filePath, signal);
-  const container = new MemoryContentContainer();
-  await container.writeDocument(content);
-  throwIfAborted(signal);
   const markdownDoc = parseMarkdown(content);
-  return { doc: markdownToDoc(markdownDoc), container, markdownDoc, sourceFormat: "md" };
+  const doc = markdownToDoc(markdownDoc);
+  const container = await buildBareMarkdownContainer(filePath, content, doc, signal);
+  return { doc, container, markdownDoc, sourceFormat: "md" };
 }
-function parseDocJson(content, source) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`${source} is not valid JSON: ${detail}`);
-  }
-  const fail = (detail) => {
-    throw new Error(`${source} is not a valid squisq Doc: ${detail}`);
-  };
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    fail(`expected a JSON object, got ${Array.isArray(parsed) ? "an array" : typeof parsed}`);
-  }
-  const doc = parsed;
-  if (!Array.isArray(doc.blocks)) {
-    fail(`"blocks" must be an array${doc.blocks === void 0 ? " (field is missing)" : ""}`);
+var NARRATION_EXTENSIONS = /* @__PURE__ */ new Set([".aac", ".flac", ".m4a", ".mp3", ".ogg", ".wav"]);
+async function buildBareMarkdownContainer(filePath, content, doc, signal) {
+  const container = new MemoryContentContainer();
+  await container.writeDocument(content, basename(filePath));
+  throwIfAborted(signal);
+  const refs = collectAuthoredAssetRefs(content, doc);
+  const root = dirname(resolve(filePath));
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    throwIfAborted(signal);
+    if (entry.isFile() && NARRATION_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      refs.add(entry.name);
+    }
   }
-  for (const [index, block] of doc.blocks.entries()) {
-    if (typeof block !== "object" || block === null || Array.isArray(block)) {
-      fail(`"blocks[${index}]" must be an object`);
+  refs.add("timing.json");
+  for (const ref of [...refs]) {
+    if (NARRATION_EXTENSIONS.has(extname(stripUrlSuffix(ref)).toLowerCase())) {
+      refs.add(`${stripUrlSuffix(ref)}.timing.json`);
     }
   }
-  if (doc.duration !== void 0 && !isFiniteNumber(doc.duration)) {
-    fail(`"duration" must be a finite number, got ${describe(doc.duration)}`);
+  const rootReal = await realpath(root);
+  let fileCount = 0;
+  let totalBytes = 0;
+  for (const authoredRef of refs) {
+    throwIfAborted(signal);
+    const safe = normalizeAssetReference(authoredRef);
+    if (!safe) continue;
+    const absolute = resolve(root, ...safe.split("/"));
+    if (!isContainedPath(root, absolute)) continue;
+    let assetReal;
+    let info;
+    try {
+      assetReal = await realpath(absolute);
+      if (!isContainedPath(rootReal, assetReal)) continue;
+      info = await stat(assetReal);
+    } catch (error) {
+      if (isMissingFileError(error)) continue;
+      throw error;
+    }
+    if (!info.isFile()) continue;
+    if (info.size > MAX_RENDER_MEDIA_FILE_BYTES) {
+      throw new Error(
+        `Sibling asset "${safe}" exceeds the ${formatMiB(MAX_RENDER_MEDIA_FILE_BYTES)} per-file input limit.`
+      );
+    }
+    if (fileCount + 1 > MAX_RENDER_MEDIA_FILES) {
+      throw new Error(
+        `Bare markdown input references more than ${MAX_RENDER_MEDIA_FILES} sibling assets.`
+      );
+    }
+    if (totalBytes + info.size > MAX_RENDER_MEDIA_TOTAL_BYTES) {
+      throw new Error(
+        `Sibling assets exceed the ${formatMiB(MAX_RENDER_MEDIA_TOTAL_BYTES)} total input limit.`
+      );
+    }
+    const data = await readBinaryFile(assetReal, signal);
+    if (data.byteLength > MAX_RENDER_MEDIA_FILE_BYTES) {
+      throw new Error(
+        `Sibling asset "${safe}" exceeds the ${formatMiB(MAX_RENDER_MEDIA_FILE_BYTES)} per-file input limit.`
+      );
+    }
+    if (totalBytes + data.byteLength > MAX_RENDER_MEDIA_TOTAL_BYTES) {
+      throw new Error(
+        `Sibling assets exceed the ${formatMiB(MAX_RENDER_MEDIA_TOTAL_BYTES)} total input limit.`
+      );
+    }
+    await container.writeFile(safe, data, mimeFromExt(safe));
+    fileCount += 1;
+    totalBytes += data.byteLength;
   }
-  if (doc.audio !== void 0) {
-    if (typeof doc.audio !== "object" || doc.audio === null || Array.isArray(doc.audio)) {
-      fail('"audio" must be an object');
+  return container;
+}
+function collectAuthoredAssetRefs(content, doc) {
+  const refs = /* @__PURE__ */ new Set();
+  const add = (value) => {
+    if (typeof value === "string" && value.trim()) refs.add(value.trim());
+  };
+  const scanObject = (value, seen = /* @__PURE__ */ new Set()) => {
+    if (!value || typeof value !== "object") return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      for (const item of value) scanObject(item, seen);
+      return;
     }
-    const segments = doc.audio.segments;
-    if (segments !== void 0) {
-      if (!Array.isArray(segments)) fail('"audio.segments" must be an array');
-      for (const [index, segment] of segments.entries()) {
-        if (typeof segment !== "object" || segment === null) {
-          fail(`"audio.segments[${index}]" must be an object`);
-        }
-        if (!isFiniteNumber(segment.duration)) {
-          fail(
-            `"audio.segments[${index}].duration" must be a finite number, got ${describe(segment.duration)}`
-          );
-        }
+    for (const [key, item] of Object.entries(value)) {
+      if (typeof item === "string" && ["src", "url", "heroSrc", "posterSrc", "staticSrc", "videoSrc", "imageSrc"].includes(key)) {
+        add(item);
+      } else {
+        scanObject(item, seen);
       }
     }
-  }
-  return {
-    ...doc,
-    audio: doc.audio ?? { segments: [] }
   };
+  scanObject(doc);
+  for (const segment of doc.audio.segments) add(segment.src);
+  for (const clip of resolveMediaSchedule(doc)) add(clip.src);
+  const patterns = [
+    /\b(?:src|href)\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s>]+))/gi,
+    /\b(?:src|audio|video|image|font)\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s}\]]+))/gi,
+    /\burl\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)/gi,
+    /!?\[[^\]]*\]\(\s*<?([^\s)>]+)>?/g
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while (match = pattern.exec(content)) add(match.slice(1).find(Boolean));
+  }
+  return refs;
+}
+function normalizeAssetReference(authoredRef) {
+  let value = stripUrlSuffix(authoredRef.trim().replace(/^<|>$/g, ""));
+  try {
+    value = decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+  if (!value || value.includes("\0") || /^[a-z][a-z\d+.-]*:/i.test(value) || posix.isAbsolute(value) || win32.isAbsolute(value) || isAbsolute(value)) {
+    return null;
+  }
+  const parts = value.replace(/\\/g, "/").split("/");
+  if (parts.some((part) => part === "..")) return null;
+  const normalized = parts.filter((part) => part && part !== ".").join("/");
+  return normalized || null;
+}
+function stripUrlSuffix(value) {
+  return value.split(/[?#]/, 1)[0] ?? value;
+}
+function isContainedPath(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+function formatMiB(bytes) {
+  return `${Math.round(bytes / (1024 * 1024))} MB`;
 }
-function isFiniteNumber(value) {
-  return typeof value === "number" && Number.isFinite(value);
+function assertValidDoc(value, source) {
+  const issues = validateDocSchema(value);
+  if (issues.length > 0) throw new DocInputValidationError(source, issues);
 }
-function describe(value) {
-  if (typeof value === "number") return Number.isNaN(value) ? "NaN" : String(value);
-  if (typeof value === "string") return JSON.stringify(value);
-  return value === null ? "null" : typeof value;
+function parseDocJson(content, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${source} is not valid JSON: ${detail}`);
+  }
+  assertValidDoc(parsed, source);
+  return parsed;
 }
 async function readDocJsonFile(filePath, signal) {
   const content = await readUtf8File(filePath, signal);
@@ -667,6 +817,7 @@ function throwIfAborted(signal) {
 // src/api.ts
 import { ConversionError } from "@bendyline/squisq-formats";
 var playerBundlePromise;
+var fullPlayerBundlePromise;
 function loadPlayerBundle() {
   playerBundlePromise ??= readFile3(
     new URL("../dist/squisq-player.global.js", import.meta.url),
@@ -674,6 +825,13 @@ function loadPlayerBundle() {
   );
   return playerBundlePromise;
 }
+function loadFullPlayerBundle() {
+  fullPlayerBundlePromise ??= readFile3(
+    new URL("../dist/squisq-player.full.global.js", import.meta.url),
+    "utf8"
+  );
+  return fullPlayerBundlePromise;
+}
 async function convert(source, to, options = {}) {
   return formatsConvert(source, to, {
     registry: createCliRegistry(),
@@ -725,8 +883,8 @@ async function captureDocFrames(doc, container, options) {
       audio.set(seg.name, data);
     }
   }
-  const mediaSrcs = new Set(resolveMediaSchedule(doc).map((clip) => clip.src));
-  for (const block of flattenBlocks(doc.blocks)) {
+  const mediaSrcs = new Set(resolveMediaSchedule2(doc).map((clip) => clip.src));
+  for (const block of flattenBlocks2(doc.blocks)) {
     for (const layer of block.layers ?? []) {
       if (layer.type === "video") mediaSrcs.add(layer.content.src);
     }
@@ -743,7 +901,7 @@ async function captureDocFrames(doc, container, options) {
   }
   onProgress?.("generating render HTML", 10);
   signal?.throwIfAborted();
-  const playerBundle = await loadPlayerBundle();
+  const playerBundle = await (selectStandalonePlayerVariant(doc) === "full" ? loadFullPlayerBundle() : loadPlayerBundle());
   signal?.throwIfAborted();
   const renderHtml = generateRenderHtml(doc, {
     playerScript: playerBundle,
@@ -976,7 +1134,7 @@ async function renderDocToGif(doc, container, options) {
     options.signal?.throwIfAborted();
     options.onProgress?.("done", 100);
     options.signal?.throwIfAborted();
-    const hasAudio = (doc.audio?.segments?.length ?? 0) > 0 || resolveMediaSchedule(doc).some((clip) => clip.kind === "audio");
+    const hasAudio = (doc.audio?.segments?.length ?? 0) > 0 || resolveMediaSchedule2(doc).some((clip) => clip.kind === "audio");
     return {
       duration: capture.totalDuration,
       frameCount,
@@ -991,8 +1149,30 @@ async function extractThumbnails(options) {
   const { videoPath, outputDir, slug, sizes, force, signal } = options;
   const { existsSync } = await import("fs");
   const { rm: rm2 } = await import("fs/promises");
-  const { join: join3 } = await import("path");
+  const { isAbsolute: isAbsolute2, relative: relative2, resolve: resolve2, sep: sep2 } = await import("path");
   signal?.throwIfAborted();
+  if (typeof slug !== "string" || !/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/.test(slug)) {
+    throw new TypeError(
+      "Thumbnail slug must be 1\u2013128 filename-safe characters (letters, numbers, dot, dash, or underscore) and must start and end with a letter or number."
+    );
+  }
+  for (const [index, thumb] of sizes.entries()) {
+    if (!Number.isSafeInteger(thumb.width) || thumb.width <= 0) {
+      throw new TypeError(`Thumbnail sizes[${index}].width must be a positive integer.`);
+    }
+    if (!Number.isSafeInteger(thumb.height) || thumb.height <= 0) {
+      throw new TypeError(`Thumbnail sizes[${index}].height must be a positive integer.`);
+    }
+  }
+  const resolvedOutputDir = resolve2(outputDir);
+  const outputPaths = sizes.map((thumb) => {
+    const outputPath = resolve2(resolvedOutputDir, `${slug}-${thumb.width}x${thumb.height}.jpg`);
+    const rel = relative2(resolvedOutputDir, outputPath);
+    if (rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute2(rel)) {
+      throw new TypeError("Thumbnail output path must remain inside outputDir.");
+    }
+    return outputPath;
+  });
   const ffmpegPath = (await detectFfmpegDetailed(signal))?.path ?? null;
   if (!ffmpegPath) {
     throw new Error(
@@ -1001,9 +1181,9 @@ async function extractThumbnails(options) {
   }
   const generatedPaths = [];
   try {
-    for (const thumb of sizes) {
+    for (const [index, thumb] of sizes.entries()) {
       signal?.throwIfAborted();
-      const outputPath = join3(outputDir, `${slug}-${thumb.width}x${thumb.height}.jpg`);
+      const outputPath = outputPaths[index];
       if (!force && existsSync(outputPath)) continue;
       try {
         await runFfmpeg(