@bendyline/squisq-video 2.2.12 → 2.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Doc, Theme, VideoPresentation, VideoPipSize, VideoPipShape, VideoPipPosition } from '@bendyline/squisq/schemas';
+import { Doc, Theme, VideoPresentation, VideoPipSize, VideoPipShape, VideoPipPosition, ViewportPreset } from '@bendyline/squisq/schemas';
 export { fetchFile } from '@ffmpeg/util';
 
 /**
@@ -260,6 +260,26 @@ interface RenderHtmlOptions {
      * Defaults to true. Embedded/timed media and document timing are unaffected.
      */
     animationsEnabled?: boolean;
+    /**
+     * Player rendition mounted in the capture page (default 'slideshow').
+     * 'dashboard' renders the one-canvas dashboard projection for
+     * single-frame image capture.
+     */
+    displayMode?: 'slideshow' | 'dashboard';
+    /** Dashboard-mode options (ignored unless `displayMode` is 'dashboard'). */
+    dashboard?: {
+        /** Layout id or 'auto'. Overrides doc frontmatter. */
+        layout?: string;
+        /** Title-band override. Overrides doc frontmatter. */
+        title?: boolean;
+        /**
+         * Cell style variant ('basic' | 'card' | 'panel' | 'accent'). Overrides
+         * doc frontmatter; colors always come from the active theme.
+         */
+        style?: string;
+        /** Host-supplied title fallback (typically the file name). */
+        documentTitle?: string;
+    };
 }
 /**
  * Generate a self-contained HTML document for headless video frame capture.
@@ -273,6 +293,122 @@ interface RenderHtmlOptions {
  */
 declare function generateRenderHtml(doc: Doc, options: RenderHtmlOptions): string;
 
+/**
+ * Dashboard image export presets and dimension helpers.
+ *
+ * Lives in @bendyline/squisq-video (browser-pure, depended on by both the
+ * CLI and the browser export UI) so the `squisq image` command and the
+ * DashboardImageExportModal share one resolution table and one validator.
+ *
+ * These are EXPORT resolutions (physical pixels), distinct from core's
+ * `VIEWPORT_PRESETS` (virtual design-space viewports) — each preset names
+ * the viewport family its aspect ratio implies so layouts pick the right
+ * orientation variant. Validation follows the cover-image ruleset (whole
+ * pixels, sane bounds, megapixel cap), NOT the H.264 even-dimension rule:
+ * that constraint exists for yuv420p video encoding and has no meaning
+ * for a PNG.
+ */
+
+interface DashboardResolutionPreset {
+    id: string;
+    label: string;
+    width: number;
+    height: number;
+    /** The `VIEWPORT_PRESETS` family this aspect ratio implies. */
+    family: ViewportPreset;
+}
+/** Named export resolutions offered by the CLI and the export dialog. */
+declare const DASHBOARD_RESOLUTIONS: readonly [{
+    readonly id: "hd";
+    readonly label: "HD 1280×720";
+    readonly width: 1280;
+    readonly height: 720;
+    readonly family: "landscape";
+}, {
+    readonly id: "fhd";
+    readonly label: "Full HD 1920×1080";
+    readonly width: 1920;
+    readonly height: 1080;
+    readonly family: "landscape";
+}, {
+    readonly id: "4k";
+    readonly label: "4K UHD 3840×2160";
+    readonly width: 3840;
+    readonly height: 2160;
+    readonly family: "landscape";
+}, {
+    readonly id: "square";
+    readonly label: "Square 1080×1080";
+    readonly width: 1080;
+    readonly height: 1080;
+    readonly family: "square";
+}, {
+    readonly id: "square-2k";
+    readonly label: "Square 2160×2160";
+    readonly width: 2160;
+    readonly height: 2160;
+    readonly family: "square";
+}, {
+    readonly id: "portrait";
+    readonly label: "Portrait 1080×1920";
+    readonly width: 1080;
+    readonly height: 1920;
+    readonly family: "portrait";
+}, {
+    readonly id: "portrait-4k";
+    readonly label: "Portrait 4K 2160×3840";
+    readonly width: 2160;
+    readonly height: 3840;
+    readonly family: "portrait";
+}, {
+    readonly id: "standard";
+    readonly label: "4:3 1440×1080";
+    readonly width: 1440;
+    readonly height: 1080;
+    readonly family: "standard";
+}];
+type DashboardResolutionId = (typeof DASHBOARD_RESOLUTIONS)[number]['id'];
+declare const DEFAULT_DASHBOARD_RESOLUTION: DashboardResolutionId;
+/** Minimum edge length for a dashboard image, in pixels. */
+declare const MIN_DASHBOARD_IMAGE_DIMENSION = 64;
+/** Maximum edge length for a dashboard image, in pixels (8K width). */
+declare const MAX_DASHBOARD_IMAGE_DIMENSION = 7680;
+/** Maximum total pixels (4× the 1080p-based cover-image budget: 7680×4320). */
+declare const MAX_DASHBOARD_IMAGE_PIXELS = 33177600;
+/**
+ * Validate custom dashboard-image dimensions. Returns a human-readable
+ * problem description, or null when the dimensions are acceptable.
+ */
+declare function validateDashboardImageDimensions(width: number, height: number): string | null;
+/**
+ * The viewport family whose aspect ratio is nearest to `width`/`height` —
+ * a uniform log-ratio comparison over all four `VIEWPORT_PRESETS`
+ * families (core's `getViewportOrientation` has no 4:3 notion, so 1440×1080
+ * would misreport as plain landscape there).
+ */
+declare function dashboardFamilyForDimensions(width: number, height: number): ViewportPreset;
+interface ResolveDashboardDimensionsInput {
+    /** Named preset id (default {@link DEFAULT_DASHBOARD_RESOLUTION}). */
+    resolution?: string;
+    /** Custom width; requires `height` and excludes `resolution`. */
+    width?: number;
+    /** Custom height; requires `width` and excludes `resolution`. */
+    height?: number;
+}
+interface ResolvedDashboardDimensions {
+    width: number;
+    height: number;
+    family: ViewportPreset;
+}
+/**
+ * Resolve the export dimensions from a preset id or explicit pixels — the
+ * single resolution-logic implementation shared by the programmatic API,
+ * the `png` format, and the `squisq image` command. Throws `RangeError`
+ * on contradictory or invalid input so callers fail before any expensive
+ * rendering starts.
+ */
+declare function resolveDashboardDimensions(input?: ResolveDashboardDimensionsInput): ResolvedDashboardDimensions;
+
 /**
  * FFmpeg argument builders — the single source of truth for translating a
  * {@link VideoQuality} into ffmpeg CLI flags. Shared verbatim by every
@@ -358,4 +494,4 @@ declare function ffmpegGifOutputArgs(options: GifOutputOptions): string[];
  */
 declare function framesToMp4Wasm(frames: Uint8Array[], audio: Uint8Array | null, options?: VideoExportOptions): Promise<EncoderResult>;
 
-export { type AudioTimelineClip, type ComputeAudioTimelineOptions, type EncoderResult, FFMPEG_WASM_SETUP_HINT, type FfmpegWasmLoadConfig, type GifDither, type GifFilterOptions, type GifOutputOptions, ORIENTATION_DIMENSIONS, QUALITY_PRESETS, type QualityPreset, type RenderHtmlOptions, type VideoExportOptions, type VideoOrientation, type VideoQuality, audioBitrateArg, bitrateForQuality, computeAudioTimeline, ffmpegAudioMuxArgs, ffmpegGifFilterGraph, ffmpegGifOutputArgs, ffmpegGifPaletteApplicationArgs, ffmpegGifPaletteApplicationGraph, ffmpegGifPaletteGenerationFilter, ffmpegVideoQualityArgs, framesToMp4Wasm, generateRenderHtml, resolveDimensions, resolveFfmpegWasmLoad, validateVideoExportOptions };
+export { type AudioTimelineClip, type ComputeAudioTimelineOptions, DASHBOARD_RESOLUTIONS, DEFAULT_DASHBOARD_RESOLUTION, type DashboardResolutionId, type DashboardResolutionPreset, type EncoderResult, FFMPEG_WASM_SETUP_HINT, type FfmpegWasmLoadConfig, type GifDither, type GifFilterOptions, type GifOutputOptions, MAX_DASHBOARD_IMAGE_DIMENSION, MAX_DASHBOARD_IMAGE_PIXELS, MIN_DASHBOARD_IMAGE_DIMENSION, ORIENTATION_DIMENSIONS, QUALITY_PRESETS, type QualityPreset, type RenderHtmlOptions, type ResolveDashboardDimensionsInput, type ResolvedDashboardDimensions, type VideoExportOptions, type VideoOrientation, type VideoQuality, audioBitrateArg, bitrateForQuality, computeAudioTimeline, dashboardFamilyForDimensions, ffmpegAudioMuxArgs, ffmpegGifFilterGraph, ffmpegGifOutputArgs, ffmpegGifPaletteApplicationArgs, ffmpegGifPaletteApplicationGraph, ffmpegGifPaletteGenerationFilter, ffmpegVideoQualityArgs, framesToMp4Wasm, generateRenderHtml, resolveDashboardDimensions, resolveDimensions, resolveFfmpegWasmLoad, validateDashboardImageDimensions, validateVideoExportOptions };

package/dist/index.js

@@ -180,7 +180,9 @@ function generateRenderHtml(doc, options) {
     pipSize,
     pipShape,
     pipPosition,
-    animationsEnabled = true
+    animationsEnabled = true,
+    displayMode = "slideshow",
+    dashboard
   } = options;
   const imageMap = {};
   if (images) {
@@ -206,7 +208,8 @@ function generateRenderHtml(doc, options) {
     videoPresentation ? `    videoPresentation: ${JSON.stringify(videoPresentation)}` : null,
     pipSize ? `    pipSize: ${JSON.stringify(pipSize)}` : null,
     pipShape ? `    pipShape: ${JSON.stringify(pipShape)}` : null,
-    pipPosition ? `    pipPosition: ${JSON.stringify(pipPosition)}` : null
+    pipPosition ? `    pipPosition: ${JSON.stringify(pipPosition)}` : null,
+    displayMode === "dashboard" ? `    dashboard: ${escapeForScript(JSON.stringify(dashboard ?? {}))}` : null
   ].filter((line) => line !== null);
   return `<!DOCTYPE html>
 <html lang="en">
@@ -230,7 +233,7 @@ html,body{margin:0;padding:0;width:${width}px;height:${height}px;overflow:hidden
   var audio = ${audioMapJson === "null" ? "null" : "JSON.parse(" + JSON.stringify(audioMapJson) + ")"};
   var root = document.getElementById("squisq-root");
   SquisqPlayer.mount(root, doc, {
-    mode: "slideshow",
+    mode: ${JSON.stringify(displayMode === "dashboard" ? "dashboard" : "slideshow")},
     images: images,
     audio: audio,
     autoPlay: false,
@@ -244,6 +247,83 @@ ${playerOptionLines.join(",\n")}
 </html>`;
 }
 
+// src/dashboardImage.ts
+import { VIEWPORT_PRESETS } from "@bendyline/squisq/schemas";
+var DASHBOARD_RESOLUTIONS = [
+  { id: "hd", label: "HD 1280\xD7720", width: 1280, height: 720, family: "landscape" },
+  { id: "fhd", label: "Full HD 1920\xD71080", width: 1920, height: 1080, family: "landscape" },
+  { id: "4k", label: "4K UHD 3840\xD72160", width: 3840, height: 2160, family: "landscape" },
+  { id: "square", label: "Square 1080\xD71080", width: 1080, height: 1080, family: "square" },
+  { id: "square-2k", label: "Square 2160\xD72160", width: 2160, height: 2160, family: "square" },
+  { id: "portrait", label: "Portrait 1080\xD71920", width: 1080, height: 1920, family: "portrait" },
+  {
+    id: "portrait-4k",
+    label: "Portrait 4K 2160\xD73840",
+    width: 2160,
+    height: 3840,
+    family: "portrait"
+  },
+  { id: "standard", label: "4:3 1440\xD71080", width: 1440, height: 1080, family: "standard" }
+];
+var DEFAULT_DASHBOARD_RESOLUTION = "fhd";
+var MIN_DASHBOARD_IMAGE_DIMENSION = 64;
+var MAX_DASHBOARD_IMAGE_DIMENSION = 7680;
+var MAX_DASHBOARD_IMAGE_PIXELS = 33177600;
+function validateDashboardImageDimensions(width, height) {
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)) {
+    return "Width and height must be whole pixel counts.";
+  }
+  if (width < MIN_DASHBOARD_IMAGE_DIMENSION || height < MIN_DASHBOARD_IMAGE_DIMENSION) {
+    return `Each dimension must be at least ${MIN_DASHBOARD_IMAGE_DIMENSION} pixels.`;
+  }
+  if (width > MAX_DASHBOARD_IMAGE_DIMENSION || height > MAX_DASHBOARD_IMAGE_DIMENSION) {
+    return `Each dimension must be at most ${MAX_DASHBOARD_IMAGE_DIMENSION} pixels.`;
+  }
+  if (width * height > MAX_DASHBOARD_IMAGE_PIXELS) {
+    return `The image may not exceed ${MAX_DASHBOARD_IMAGE_PIXELS.toLocaleString("en-US")} total pixels.`;
+  }
+  return null;
+}
+function dashboardFamilyForDimensions(width, height) {
+  const aspect = width / Math.max(1, height);
+  let best = "landscape";
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const family of Object.keys(VIEWPORT_PRESETS)) {
+    const preset = VIEWPORT_PRESETS[family];
+    const distance = Math.abs(Math.log(aspect / (preset.width / preset.height)));
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = family;
+    }
+  }
+  return best;
+}
+function resolveDashboardDimensions(input = {}) {
+  const hasCustom = input.width !== void 0 || input.height !== void 0;
+  if (hasCustom && input.resolution !== void 0) {
+    throw new RangeError("Pass either a resolution preset or custom width/height, not both.");
+  }
+  if (hasCustom) {
+    if (input.width === void 0 || input.height === void 0) {
+      throw new RangeError("Custom dimensions require both width and height.");
+    }
+    const problem = validateDashboardImageDimensions(input.width, input.height);
+    if (problem) throw new RangeError(problem);
+    return {
+      width: input.width,
+      height: input.height,
+      family: dashboardFamilyForDimensions(input.width, input.height)
+    };
+  }
+  const id = input.resolution ?? DEFAULT_DASHBOARD_RESOLUTION;
+  const preset = DASHBOARD_RESOLUTIONS.find((entry) => entry.id === id);
+  if (!preset) {
+    const known = DASHBOARD_RESOLUTIONS.map((entry) => entry.id).join(", ");
+    throw new RangeError(`Unknown resolution preset "${id}". Valid presets: ${known}.`);
+  }
+  return { width: preset.width, height: preset.height, family: preset.family };
+}
+
 // src/ffmpegArgs.ts
 function ffmpegVideoQualityArgs(quality) {
   const preset = QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal;
@@ -413,12 +493,18 @@ async function framesToMp4Wasm(frames, audio, options = {}) {
   }
 }
 export {
+  DASHBOARD_RESOLUTIONS,
+  DEFAULT_DASHBOARD_RESOLUTION,
   FFMPEG_WASM_SETUP_HINT,
+  MAX_DASHBOARD_IMAGE_DIMENSION,
+  MAX_DASHBOARD_IMAGE_PIXELS,
+  MIN_DASHBOARD_IMAGE_DIMENSION,
   ORIENTATION_DIMENSIONS,
   QUALITY_PRESETS,
   audioBitrateArg,
   bitrateForQuality,
   computeAudioTimeline,
+  dashboardFamilyForDimensions,
   fetchFile,
   ffmpegAudioMuxArgs,
   ffmpegGifFilterGraph,
@@ -429,7 +515,9 @@ export {
   ffmpegVideoQualityArgs,
   framesToMp4Wasm,
   generateRenderHtml,
+  resolveDashboardDimensions,
   resolveDimensions,
   resolveFfmpegWasmLoad,
+  validateDashboardImageDimensions,
   validateVideoExportOptions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-video",
-  "version": "2.2.12",
+  "version": "2.3.0",
   "description": "Cross-runtime video and animated-GIF helpers with browser-based ffmpeg.wasm encoding for Squisq documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.7.1",
+    "@bendyline/squisq": "2.8.0",
     "@ffmpeg/ffmpeg": "0.12.15",
     "@ffmpeg/util": "0.12.2"
   },