@bendyline/squisq-cli 2.5.4 → 2.6.0

package/README.md

@@ -96,9 +96,45 @@ Notes:
 - **An existing output file is never overwritten by default.** The check runs before rendering, so a colliding path costs you a second rather than a full capture. Pass `--overwrite` to replace.
 - FFmpeg failures report the one relevant line (e.g. `[libx264] width not divisible by 2 (851x480) (exit code 1)`) rather than dumping the whole command line and stderr buffer.
 
+### `squisq image <input> [output]`
+
+Render a document's **Dashboard** rendition — every block arranged on one
+canvas — to a PNG image. Needs Playwright Chromium only (no ffmpeg; this is a
+single-frame capture, not a video encode). The layout comes from the doc's
+`squisq-dashboard-layout` frontmatter (or `--layout`), defaulting to the
+auto-pick that chooses the smallest built-in layout fitting the block count;
+the document-title band renders by default and `--no-title` hides it. `--style`
+picks the cell dressing (`basic`, `card`, `panel`, `accent` — all theme-derived),
+defaulting to the doc's `squisq-dashboard-style`.
+
+```bash
+squisq image input.md output.png
+squisq image input.md --resolution 4k
+squisq image input.md --resolution square --layout grid-2x2
+squisq image input.md --style card
+squisq image input.md --width 1280 --height 720 --no-title
+squisq image input.md -t documentary --transform magazine
+```
+
+| Option                   | Description                                                                                                | Default       |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------- |
+| `-o, --output`           | Output `.png` path                                                                                         | `<input>.png` |
+| `--resolution`           | Named preset: `hd`, `fhd`, `4k`, `square`, `square-2k`, `portrait`, `portrait-4k`, `standard`              | `fhd`         |
+| `--width` / `--height`   | Custom pixels (both required together; excludes `--resolution`). 64–7680 per axis, ≤33 MP; odd values fine | preset        |
+| `--layout`               | Dashboard layout id (built-ins or a doc-defined custom layout), or `auto`                                  | `auto`        |
+| `--style`                | Cell style variant: `basic`, `card`, `panel`, `accent` (all theme-derived)                                 | doc setting   |
+| `--title` / `--no-title` | Show/hide the document-title band                                                                          | shown         |
+| `--format`               | Output format (`png`)                                                                                      | `png`         |
+| `-t, --theme`            | Squisq theme id to apply                                                                                   | none          |
+| `--transform`            | Transform style to apply before rendering                                                                  | none          |
+| `--overwrite`            | Replace an existing output file (otherwise refuse and exit non-zero)                                       | off           |
+| `--no-auto-templates`    | Disable content-aware template auto-picking for unannotated headings                                       | (auto on)     |
+
+The same export is available through the registry as `squisq convert <input> -f png`.
+
 ### `squisq doctor`
 
-Preflight the video toolchain: reports the resolved ffmpeg path, version, and which source it came from (`SQUISQ_FFMPEG` env / `PATH` / `ffmpeg-static`) with an install hint when missing, attempts a headless Chromium launch, and reports the Node version.
+Preflight the rendering toolchain: reports the resolved ffmpeg path, version, and which source it came from (`SQUISQ_FFMPEG` env / `PATH` / `ffmpeg-static`) with an install hint when missing, attempts a headless Chromium launch, reports the Node version, and summarizes per-feature readiness (video/GIF need ffmpeg + Chromium; the dashboard PNG image needs Chromium only).
 
 ```bash
 squisq doctor
@@ -222,6 +258,27 @@ captions, an infinite loop, and disabled slide animations/transitions. Set
 `captionStyle: 'off'` to omit captions. Embedded video still advances, but all
 audio is omitted and reported through `result.warnings`.
 
+### `renderDocToDashboardPng`
+
+```ts
+import { renderDocToDashboardPng } from '@bendyline/squisq-cli/api';
+
+const result = await renderDocToDashboardPng(doc, input.container, {
+  outputPath: './dashboard.png',
+  resolution: 'square', // or width/height for custom pixels
+  layout: 'grid-2x2', // 'auto' (default) picks by block count
+  style: 'card', // 'basic' (default) | 'card' | 'panel' | 'accent'
+  title: true,
+});
+// result: { bytes: Uint8Array, width, height, outputPath? }
+```
+
+Renders the Dashboard rendition to a single PNG. Needs Playwright Chromium
+only — no ffmpeg. `resolution` names a preset from `DASHBOARD_RESOLUTIONS`
+(default `fhd`, 1920×1080); explicit `width`/`height` (both together) replace
+it. Apply a theme upstream (`{ ...doc, themeId }`), the same convention the
+video renderers use.
+
 ### Native frame encoding
 
 For callers that already have PNG frames and do not need Playwright capture,
@@ -271,6 +328,7 @@ await extractThumbnails({
 - `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`)
+- `DASHBOARD_RESOLUTIONS`, `DEFAULT_DASHBOARD_RESOLUTION`, `resolveDashboardDimensions`, `validateDashboardImageDimensions` (re-exports from `@bendyline/squisq-video`)
 
 See the full [API Reference](https://github.com/bendyline/squisq/blob/main/docs/API.md#bendylinesquisq-cli) for all types and options.
 

package/THIRD_PARTY_LICENSES.txt

@@ -102,7 +102,7 @@ COMPONENTS
 - mdast-util-phrasing@4.1.0 (MIT); files: license
 - mdast-util-to-markdown@2.1.2 (MIT); files: license
 - mdast-util-to-string@4.0.0 (MIT); files: license
-- mermaid@11.16.0 (MIT); files: LICENSE
+- mermaid@11.16.1 (MIT); files: LICENSE
 - micromark-core-commonmark@2.0.3 (MIT); files: license
 - micromark-extension-directive@3.0.2 (MIT); files: license
 - micromark-extension-frontmatter@2.0.0 (MIT); files: license
@@ -2987,7 +2987,7 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ==============================================================================
-mermaid@11.16.0 - LICENSE
+mermaid@11.16.1 - LICENSE
 ==============================================================================
 The MIT License (MIT)
 

package/dist/{api-E5PDCULT.js → api-O3IMGDPH.js}

@@ -2,6 +2,8 @@
 import {
   CapturedFrameBudgetError,
   ConversionError,
+  DASHBOARD_RESOLUTIONS,
+  DEFAULT_DASHBOARD_RESOLUTION,
   MAX_CAPTURED_FRAME_BYTES,
   MemoryContentContainer,
   convert,
@@ -9,9 +11,12 @@ import {
   extractThumbnails,
   prepareConversion,
   readInput,
+  renderDocToDashboardPng,
   renderDocToGif,
-  renderDocToMp4
-} from "./chunk-SFBZGL54.js";
+  renderDocToMp4,
+  resolveDashboardDimensions,
+  validateDashboardImageDimensions
+} from "./chunk-2ZJW7F62.js";
 import {
   GIF_EXPORT_DEFAULTS,
   framesToGifNative,
@@ -22,6 +27,8 @@ import {
 export {
   CapturedFrameBudgetError,
   ConversionError,
+  DASHBOARD_RESOLUTIONS,
+  DEFAULT_DASHBOARD_RESOLUTION,
   GIF_EXPORT_DEFAULTS,
   MAX_CAPTURED_FRAME_BYTES,
   MemoryContentContainer,
@@ -34,6 +41,9 @@ export {
   framesToMp4NativeBytes,
   prepareConversion,
   readInput,
+  renderDocToDashboardPng,
   renderDocToGif,
-  renderDocToMp4
+  renderDocToMp4,
+  resolveDashboardDimensions,
+  validateDashboardImageDimensions
 };

package/dist/api.d.ts

@@ -1,8 +1,9 @@
 import { Doc } from '@bendyline/squisq/schemas';
+import { DashboardStyleId } from '@bendyline/squisq/doc';
 import { ContentContainer } from '@bendyline/squisq/storage';
 export { MemoryContentContainer } from '@bendyline/squisq/storage';
-import { VideoQuality, VideoOrientation, GifDither, VideoExportOptions } from '@bendyline/squisq-video';
-export { GifDither, VideoOrientation, VideoQuality } from '@bendyline/squisq-video';
+import { VideoQuality, VideoOrientation, GifDither, DashboardResolutionId, VideoExportOptions } from '@bendyline/squisq-video';
+export { DASHBOARD_RESOLUTIONS, DEFAULT_DASHBOARD_RESOLUTION, DashboardResolutionId, DashboardResolutionPreset, GifDither, VideoOrientation, VideoQuality, resolveDashboardDimensions, validateDashboardImageDimensions } from '@bendyline/squisq-video';
 import { FormatRegistry, FormatId, ConvertOptions, ConvertSource, ConversionResult, PreparedConversion } from '@bendyline/squisq-formats';
 export { ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionResult, ConvertOptions, ConvertSource, FormatDefinition, FormatId, FormatRegistry, NormalizedInput, PreparedConversion, PreparedExportOptions } from '@bendyline/squisq-formats';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
@@ -42,6 +43,22 @@ interface GifFormatOptions {
     dither?: GifDither;
     bayerScale?: number;
 }
+/**
+ * Per-export options for `convert(..., 'png')` — the Dashboard image.
+ * `resolution` names a preset; explicit `width`/`height` (both required
+ * together) win over it. `layout`/`style`/`title` override the doc's
+ * dashboard frontmatter.
+ */
+interface PngFormatOptions {
+    onProgress?: (phase: string, percent: number) => void;
+    resolution?: DashboardResolutionId;
+    width?: number;
+    height?: number;
+    layout?: string;
+    /** Cell style variant; unset defers to the doc's own frontmatter. */
+    style?: DashboardStyleId;
+    title?: boolean;
+}
 /**
  * Build the CLI's format registry: every built-in format from
  * `@bendyline/squisq-formats` plus the CLI-only rendered-media exporters.
@@ -218,6 +235,7 @@ type CliConvertOptions = Omit<ConvertOptions, 'formatOptions'> & {
     formatOptions?: ConvertOptions['formatOptions'] & {
         mp4?: Mp4FormatOptions;
         gif?: GifFormatOptions;
+        png?: PngFormatOptions;
     };
 };
 
@@ -319,6 +337,50 @@ interface RenderDocToGifResult extends RenderDocToMp4Result {
     /** Non-fatal fidelity warnings, including GIF's lack of audio. */
     warnings: string[];
 }
+/** Options for {@link renderDocToDashboardPng}. */
+interface RenderDashboardPngOptions {
+    /** Abort the render; rejects with the signal's reason. */
+    signal?: AbortSignal;
+    /** Optional output file; bytes are always returned. */
+    outputPath?: string;
+    /** Named resolution preset (default `'fhd'`, 1920×1080). */
+    resolution?: DashboardResolutionId;
+    /** Custom pixel width; requires `height` and excludes `resolution`. */
+    width?: number;
+    /** Custom pixel height; requires `width` and excludes `resolution`. */
+    height?: number;
+    /** Dashboard layout id, or `'auto'` for the block-count pick (default). */
+    layout?: string;
+    /**
+     * Render the document-title band. Leave unset to defer to the doc's own
+     * `squisq-dashboard-title` frontmatter (which itself defaults on).
+     */
+    title?: boolean;
+    /**
+     * Cell style variant (`basic` | `card` | `panel` | `accent`). Default:
+     * the document's own `squisq-dashboard-style` setting.
+     */
+    style?: DashboardStyleId;
+    /** Host-supplied title fallback when the doc has no frontmatter title. */
+    documentTitle?: string;
+    onProgress?: (phase: string, percent: number) => void;
+}
+/** Result returned by {@link renderDocToDashboardPng}. */
+interface RenderDashboardPngResult {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+    /** Absolute path written, when `outputPath` was requested. */
+    outputPath?: string;
+}
+/**
+ * Render a Doc's Dashboard rendition to a single PNG image.
+ *
+ * Needs Playwright Chromium only — unlike the video paths there is no
+ * ffmpeg involvement. Apply a theme upstream (`{ ...doc, themeId }`), the
+ * same convention `renderDocToMp4`/`renderDocToGif` use.
+ */
+declare function renderDocToDashboardPng(doc: Doc, container: ContentContainer, options?: RenderDashboardPngOptions): Promise<RenderDashboardPngResult>;
 /** Render a Doc + media container to an MP4 video file. */
 declare function renderDocToMp4(doc: Doc, container: ContentContainer, options: RenderDocToMp4Options): Promise<RenderDocToMp4Result>;
 /** Render a Doc + media container to a silent animated GIF. */
@@ -355,4 +417,4 @@ interface ExtractThumbnailsOptions {
  */
 declare function extractThumbnails(options: ExtractThumbnailsOptions): Promise<void>;
 
-export { CapturedFrameBudgetError, type CliConvertOptions, type ExtractThumbnailsOptions, GIF_EXPORT_DEFAULTS, type GifExportOptions, type GifFormatOptions, MAX_CAPTURED_FRAME_BYTES, type Mp4FormatOptions, type NativeVideoExportOptions, type ReadInputResult, type RenderDocToGifOptions, type RenderDocToGifResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, framesToGifNative, framesToGifNativeBytes, framesToMp4Native, framesToMp4NativeBytes, prepareConversion, readInput, renderDocToGif, renderDocToMp4 };
+export { CapturedFrameBudgetError, type CliConvertOptions, type ExtractThumbnailsOptions, GIF_EXPORT_DEFAULTS, type GifExportOptions, type GifFormatOptions, MAX_CAPTURED_FRAME_BYTES, type Mp4FormatOptions, type NativeVideoExportOptions, type PngFormatOptions, type ReadInputResult, type RenderDashboardPngOptions, type RenderDashboardPngResult, type RenderDocToGifOptions, type RenderDocToGifResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, framesToGifNative, framesToGifNativeBytes, framesToMp4Native, framesToMp4NativeBytes, prepareConversion, readInput, renderDocToDashboardPng, renderDocToGif, renderDocToMp4 };

package/dist/api.js

@@ -8,11 +8,12 @@ import {
 } from "./chunk-Z3BHD4AF.js";
 
 // src/api.ts
-import { readFile as readFile3 } from "fs/promises";
+import { mkdir, readFile as readFile3, writeFile } from "fs/promises";
+import { dirname as dirname2, resolve as resolvePath } from "path";
 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 { resolveDashboardDimensions, resolveDimensions } from "@bendyline/squisq-video";
 import {
   convert as formatsConvert,
   prepareConversion as formatsPrepareConversion
@@ -97,13 +98,13 @@ async function buildMixedAudioTrack(doc, container, ffmpegPath, coverPreRoll, si
   return mixTimelineClips(ffmpegPath, usable, signal);
 }
 async function mixTimelineClips(ffmpegPath, usable, signal) {
-  const { writeFile, readFile: readFile4, mkdir, rm: rm2 } = await import("fs/promises");
+  const { writeFile: writeFile2, readFile: readFile4, mkdir: mkdir2, rm: rm2 } = await import("fs/promises");
   const { join: join3 } = await import("path");
   const { tmpdir: tmpdir2 } = await import("os");
   const { randomBytes: randomBytes2 } = await import("crypto");
   signal?.throwIfAborted();
   const workDir = join3(tmpdir2(), `squisq-audio-mix-${randomBytes2(8).toString("hex")}`);
-  await mkdir(workDir, { recursive: true });
+  await mkdir2(workDir, { recursive: true });
   const ms = (s) => Math.max(0, Math.round(s * 1e3));
   try {
     signal?.throwIfAborted();
@@ -113,7 +114,7 @@ async function mixTimelineClips(ffmpegPath, usable, signal) {
     for (const { clip, buffer } of usable) {
       signal?.throwIfAborted();
       const p = join3(workDir, `clip-${inputs.length}.mp3`);
-      await writeFile(p, new Uint8Array(buffer));
+      await writeFile2(p, new Uint8Array(buffer));
       signal?.throwIfAborted();
       const i = inputs.push(p) - 1;
       const delayMs = ms(clip.startSec);
@@ -407,10 +408,38 @@ function gifFormat() {
     }
   };
 }
+function pngFormat() {
+  return {
+    id: "png",
+    templateAnnotationHandling: "rendered",
+    label: "Dashboard Image",
+    mimeType: "image/png",
+    extensions: [".png"],
+    async exportDoc(input, options) {
+      options.signal?.throwIfAborted();
+      const pngOpts = options.formatOptions?.png ?? {};
+      const { renderDocToDashboardPng: renderDocToDashboardPng2 } = await import("./api.js");
+      const result = await renderDocToDashboardPng2(input.doc, input.container, {
+        resolution: pngOpts.resolution,
+        width: pngOpts.width,
+        height: pngOpts.height,
+        layout: pngOpts.layout,
+        style: pngOpts.style,
+        title: pngOpts.title,
+        documentTitle: options.title ?? input.baseName,
+        signal: options.signal,
+        onProgress: pngOpts.onProgress
+      });
+      options.signal?.throwIfAborted();
+      return { bytes: result.bytes, mimeType: "image/png", suggestedFilename: "", warnings: [] };
+    }
+  };
+}
 function createCliRegistry() {
   const registry = defaultRegistry();
   registry.register(mp4Format());
   registry.register(gifFormat());
+  registry.register(pngFormat());
   return registry;
 }
 
@@ -827,6 +856,12 @@ function throwIfAborted(signal) {
 }
 
 // src/api.ts
+import {
+  DASHBOARD_RESOLUTIONS,
+  DEFAULT_DASHBOARD_RESOLUTION,
+  resolveDashboardDimensions as resolveDashboardDimensions2,
+  validateDashboardImageDimensions
+} from "@bendyline/squisq-video";
 import { ConversionError } from "@bendyline/squisq-formats";
 var playerBundlePromise;
 var fullPlayerBundlePromise;
@@ -866,17 +901,18 @@ async function prepareConversion(source, options = {}) {
     ...options
   });
 }
-async function captureDocFrames(doc, container, options) {
-  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress, signal } = options;
-  signal?.throwIfAborted();
-  resolveAppliedCoverPreRoll(coverPreRoll, true);
-  const ffmpegPath = (await detectFfmpegDetailed(signal))?.path ?? null;
-  signal?.throwIfAborted();
-  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."
-    );
-  }
+async function withRenderPage(doc, container, options, fn) {
+  const {
+    signal,
+    width,
+    height,
+    includeAudio,
+    captionStyle,
+    animationsEnabled,
+    displayMode,
+    dashboard,
+    onProgress
+  } = options;
   onProgress?.("collecting media", 0);
   signal?.throwIfAborted();
   const { collectImagePaths } = await import("@bendyline/squisq-formats/html");
@@ -893,14 +929,16 @@ async function captureDocFrames(doc, container, options) {
     }
   }
   const audio = /* @__PURE__ */ new Map();
-  for (const seg of doc.audio?.segments ?? []) {
-    signal?.throwIfAborted();
-    const data = await container.readFile(seg.src);
-    signal?.throwIfAborted();
-    if (data) {
-      budget.admit(seg.src, data);
-      audio.set(seg.src, data);
-      audio.set(seg.name, data);
+  if (includeAudio) {
+    for (const seg of doc.audio?.segments ?? []) {
+      signal?.throwIfAborted();
+      const data = await container.readFile(seg.src);
+      signal?.throwIfAborted();
+      if (data) {
+        budget.admit(seg.src, data);
+        audio.set(seg.src, data);
+        audio.set(seg.name, data);
+      }
     }
   }
   const mediaSrcs = new Set(resolveMediaSchedule2(doc).map((clip) => clip.src));
@@ -930,7 +968,9 @@ async function captureDocFrames(doc, container, options) {
     width,
     height,
     captionStyle,
-    animationsEnabled
+    animationsEnabled,
+    displayMode,
+    dashboard
   });
   onProgress?.("launching browser", 15);
   signal?.throwIfAborted();
@@ -956,7 +996,6 @@ async function captureDocFrames(doc, container, options) {
   }
   signal?.addEventListener("abort", handleAbort, { once: true });
   let renderAPI = null;
-  const capturedFrames = new CapturedFrameCollector();
   try {
     const page = await browser.newPage({ viewport: { width, height } });
     const pageErrors = [];
@@ -997,58 +1036,135 @@ Page errors:
       return api;
     });
     signal?.throwIfAborted();
-    const docDuration = await renderAPI.evaluate((api) => api.getDuration());
-    signal?.throwIfAborted();
-    if (docDuration <= 0) throw new Error("Document has zero duration \u2014 nothing to render");
-    const hasCover = coverPreRoll > 0 ? await renderAPI.evaluate((api) => api.hasCoverBlock()) : false;
-    const appliedCoverPreRoll = resolveAppliedCoverPreRoll(coverPreRoll, hasCover);
-    const storyFrameCount = Math.ceil(docDuration * fps);
-    const preRollFrameCount = Math.ceil(appliedCoverPreRoll * fps);
-    const totalFrames = preRollFrameCount + storyFrameCount;
-    onProgress?.("capturing frames", 20);
-    capturedFrames.throwIfAborted(signal);
-    if (preRollFrameCount > 0) {
-      capturedFrames.throwIfAborted(signal);
-      await renderAPI.evaluate((api) => api.showCover());
-      await page.waitForTimeout(100);
-      capturedFrames.throwIfAborted(signal);
-      const coverFrame = await page.screenshot({ type: "png" });
-      capturedFrames.throwIfAborted(signal);
-      capturedFrames.append(coverFrame, preRollFrameCount);
-      await renderAPI.evaluate((api) => api.hideCover());
-    }
-    const frameInterval = 1 / fps;
-    for (let i = 0; i < storyFrameCount; i++) {
-      capturedFrames.throwIfAborted(signal);
-      const time = i * frameInterval;
-      await renderAPI.evaluate((api, t) => api.seekTo(t), time);
-      const frame = await page.screenshot({ type: "png" });
-      capturedFrames.throwIfAborted(signal);
-      capturedFrames.append(frame);
-      if (i % Math.max(1, Math.floor(fps / 2)) === 0 || i === storyFrameCount - 1) {
-        onProgress?.(
-          "capturing frames",
-          20 + Math.round(capturedFrames.frameCount / totalFrames * 60)
-        );
+    return await fn({ page, renderAPI });
+  } finally {
+    signal?.removeEventListener("abort", handleAbort);
+    await renderAPI?.dispose().catch(() => void 0);
+    await browser.close().catch(() => void 0);
+  }
+}
+async function captureDocFrames(doc, container, options) {
+  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress, signal } = options;
+  signal?.throwIfAborted();
+  resolveAppliedCoverPreRoll(coverPreRoll, true);
+  const ffmpegPath = (await detectFfmpegDetailed(signal))?.path ?? null;
+  signal?.throwIfAborted();
+  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."
+    );
+  }
+  const capturedFrames = new CapturedFrameCollector();
+  try {
+    return await withRenderPage(
+      doc,
+      container,
+      { signal, width, height, includeAudio: true, captionStyle, animationsEnabled, onProgress },
+      async ({ page, renderAPI }) => {
+        const docDuration = await renderAPI.evaluate((api) => api.getDuration());
+        signal?.throwIfAborted();
+        if (docDuration <= 0) throw new Error("Document has zero duration \u2014 nothing to render");
+        const hasCover = coverPreRoll > 0 ? await renderAPI.evaluate((api) => api.hasCoverBlock()) : false;
+        const appliedCoverPreRoll = resolveAppliedCoverPreRoll(coverPreRoll, hasCover);
+        const storyFrameCount = Math.ceil(docDuration * fps);
+        const preRollFrameCount = Math.ceil(appliedCoverPreRoll * fps);
+        const totalFrames = preRollFrameCount + storyFrameCount;
+        onProgress?.("capturing frames", 20);
         capturedFrames.throwIfAborted(signal);
+        if (preRollFrameCount > 0) {
+          capturedFrames.throwIfAborted(signal);
+          await renderAPI.evaluate((api) => api.showCover());
+          await page.waitForTimeout(100);
+          capturedFrames.throwIfAborted(signal);
+          const coverFrame = await page.screenshot({ type: "png" });
+          capturedFrames.throwIfAborted(signal);
+          capturedFrames.append(coverFrame, preRollFrameCount);
+          await renderAPI.evaluate((api) => api.hideCover());
+        }
+        const frameInterval = 1 / fps;
+        for (let i = 0; i < storyFrameCount; i++) {
+          capturedFrames.throwIfAborted(signal);
+          const time = i * frameInterval;
+          await renderAPI.evaluate((api, t) => api.seekTo(t), time);
+          const frame = await page.screenshot({ type: "png" });
+          capturedFrames.throwIfAborted(signal);
+          capturedFrames.append(frame);
+          if (i % Math.max(1, Math.floor(fps / 2)) === 0 || i === storyFrameCount - 1) {
+            onProgress?.(
+              "capturing frames",
+              20 + Math.round(capturedFrames.frameCount / totalFrames * 60)
+            );
+            capturedFrames.throwIfAborted(signal);
+          }
+        }
+        return {
+          frames: capturedFrames.release(),
+          totalDuration: docDuration + appliedCoverPreRoll,
+          appliedCoverPreRoll,
+          ffmpegPath
+        };
       }
-    }
-    return {
-      frames: capturedFrames.release(),
-      totalDuration: docDuration + appliedCoverPreRoll,
-      appliedCoverPreRoll,
-      ffmpegPath
-    };
+    );
   } catch (err) {
     capturedFrames.clear();
     signal?.throwIfAborted();
     throw err;
-  } finally {
-    signal?.removeEventListener("abort", handleAbort);
-    await renderAPI?.dispose().catch(() => void 0);
-    await browser.close().catch(() => void 0);
   }
 }
+async function renderDocToDashboardPng(doc, container, options = {}) {
+  const {
+    signal,
+    outputPath,
+    resolution,
+    width,
+    height,
+    layout,
+    title,
+    style,
+    documentTitle,
+    onProgress
+  } = options;
+  signal?.throwIfAborted();
+  const dimensions = resolveDashboardDimensions({ resolution, width, height });
+  const bytes = await withRenderPage(
+    doc,
+    container,
+    {
+      signal,
+      width: dimensions.width,
+      height: dimensions.height,
+      includeAudio: false,
+      animationsEnabled: false,
+      displayMode: "dashboard",
+      dashboard: { layout, title, style, documentTitle },
+      onProgress
+    },
+    async ({ page, renderAPI }) => {
+      onProgress?.("rendering dashboard", 50);
+      signal?.throwIfAborted();
+      await renderAPI.evaluate((api) => api.seekTo(0));
+      signal?.throwIfAborted();
+      await page.waitForTimeout(100);
+      signal?.throwIfAborted();
+      onProgress?.("capturing image", 85);
+      return await page.screenshot({ type: "png" });
+    }
+  );
+  let writtenPath;
+  if (outputPath) {
+    const absolute = resolvePath(outputPath);
+    await mkdir(dirname2(absolute), { recursive: true });
+    await writeFile(absolute, bytes);
+    writtenPath = absolute;
+  }
+  onProgress?.("done", 100);
+  return {
+    bytes,
+    width: dimensions.width,
+    height: dimensions.height,
+    ...writtenPath ? { outputPath: writtenPath } : {}
+  };
+}
 async function renderDocToMp4(doc, container, options) {
   options.signal?.throwIfAborted();
   const fps = options.fps ?? 30;
@@ -1231,6 +1347,8 @@ async function extractThumbnails(options) {
 export {
   CapturedFrameBudgetError,
   ConversionError,
+  DASHBOARD_RESOLUTIONS,
+  DEFAULT_DASHBOARD_RESOLUTION,
   GIF_EXPORT_DEFAULTS,
   MAX_CAPTURED_FRAME_BYTES,
   MemoryContentContainer2 as MemoryContentContainer,
@@ -1243,6 +1361,9 @@ export {
   framesToMp4NativeBytes,
   prepareConversion,
   readInput,
+  renderDocToDashboardPng,
   renderDocToGif,
-  renderDocToMp4
+  renderDocToMp4,
+  resolveDashboardDimensions2 as resolveDashboardDimensions,
+  validateDashboardImageDimensions
 };