@bendyline/squisq-video-react 2.2.11 → 2.3.0

package/README.md

@@ -76,10 +76,15 @@ function App() {
 
 ## Components
 
-| Component           | Description                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------- |
-| `VideoExportModal`  | Full modal UI — configure MP4/GIF, captions, motion, quality, fps, and orientation |
-| `VideoExportButton` | Drop-in button that opens the export modal via portal                              |
+| Component               | Description                                                                        |
+| ----------------------- | ---------------------------------------------------------------------------------- |
+| `VideoExportModal`      | Full modal UI — configure MP4/GIF, captions, motion, quality, fps, and orientation |
+| `VideoExportButton`     | Drop-in button that opens the export modal via portal                              |
+| `CoverImageExportModal` | Save the managed cover as PNG, JPEG, or WebP with bounded resolution controls      |
+
+Import `CoverImageExportModal` from
+`@bendyline/squisq-video-react/cover-image` when a surface only needs cover
+capture. This entry point excludes the MP4/GIF encoder worker graph.
 
 ## Hooks
 
@@ -99,6 +104,11 @@ The `VideoExportModal` lets users configure:
 - **Captions:** off, standard, or social
 - **Animations & transitions:** enabled by default for MP4 and disabled by default for GIF
 
+Managed covers inherit `squisq-cover-duration` and `squisq-cover-playback`
+from document frontmatter. `preroll` adds the cover before story frame zero
+and shifts audio; `overlay` keeps the exported duration unchanged while the
+story and audio advance underneath the visible cover.
+
 ## Using the Hook Directly
 
 For custom export UIs, use `useVideoExport` directly:

package/dist/{chunk-KJ5RKG67.js → chunk-32QCPFXE.js}

@@ -1,8 +1,9 @@
 import {
+  DEFAULT_MP4_SPILL_THRESHOLD_BYTES,
   applyWebCodecsBackpressure,
   createMp4Muxer,
   resolveWebCodecsQueueLimit
-} from "./chunk-I4SXMCDF.js";
+} from "./chunk-5MFQMJ5Z.js";
 
 // src/mainThreadEncoder.ts
 import { bitrateForQuality, validateVideoExportOptions } from "@bendyline/squisq-video";
@@ -43,7 +44,8 @@ function createEncoder(config) {
     width: config.width,
     height: config.height,
     fps: config.fps,
-    ...config.audio ? { audio: config.audio } : {}
+    ...config.audio ? { audio: config.audio } : {},
+    ...config.spillOutputToBlob ? { spillToBlobThresholdBytes: DEFAULT_MP4_SPILL_THRESHOLD_BYTES } : {}
   });
   let closed = false;
   let fatalError = null;

package/dist/{chunk-I4SXMCDF.js → chunk-5MFQMJ5Z.js}

@@ -1905,9 +1905,13 @@ ensureNotFinalized_fn = function() {
 };
 
 // src/mp4Mux.ts
+var DEFAULT_MP4_SPILL_THRESHOLD_BYTES = 32 * 1024 * 1024;
 var ChunkedMp4Output = class {
-  constructor() {
+  constructor(spillThresholdBytes = null) {
+    this.spillThresholdBytes = spillThresholdBytes;
     this.writes = [];
+    this.spilled = [];
+    this.bufferedBytes = 0;
     this.length = 0;
   }
   write(data, position) {
@@ -1915,7 +1919,9 @@ var ChunkedMp4Output = class {
     const end = position + owned.byteLength;
     if (position >= this.length) {
       this.writes.push({ position, data: owned });
+      this.bufferedBytes += owned.byteLength;
       this.length = end;
+      this.maybeSpill();
       return;
     }
     const updated = [];
@@ -1941,34 +1947,106 @@ var ChunkedMp4Output = class {
     updated.push({ position, data: owned });
     updated.sort((left, right) => left.position - right.position);
     this.writes = updated;
+    this.bufferedBytes = updated.reduce((sum, write) => sum + write.data.byteLength, 0);
     this.length = Math.max(this.length, end);
+    this.maybeSpill();
+  }
+  overlapsSpilled(write) {
+    const end = write.position + write.data.byteLength;
+    return this.spilled.some(
+      (part) => part.position < end && part.position + part.size > write.position
+    );
+  }
+  /**
+   * Consolidate buffered writes into Blob parts once they exceed the
+   * threshold. Writes overlapping an already-spilled region are patches over
+   * Blob bytes; they stay in memory (they are tiny) and win at assembly.
+   */
+  maybeSpill() {
+    if (this.spillThresholdBytes === null || this.bufferedBytes < this.spillThresholdBytes) return;
+    const spillable = this.writes.filter((write) => !this.overlapsSpilled(write)).sort((left, right) => left.position - right.position);
+    if (spillable.length === 0) return;
+    const keep = new Set(spillable);
+    let run = [];
+    const flushRun = () => {
+      if (run.length === 0) return;
+      const position = run[0].position;
+      const size = run.reduce((sum, write) => sum + write.data.byteLength, 0);
+      this.spilled.push({
+        position,
+        size,
+        blob: new Blob(run.map((write) => write.data))
+      });
+      run = [];
+    };
+    for (const write of spillable) {
+      const previous = run[run.length - 1];
+      if (previous && previous.position + previous.data.byteLength !== write.position) flushRun();
+      run.push(write);
+    }
+    flushRun();
+    this.spilled.sort((left, right) => left.position - right.position);
+    this.writes = this.writes.filter((write) => !keep.has(write));
+    this.bufferedBytes = this.writes.reduce((sum, write) => sum + write.data.byteLength, 0);
+  }
+  /** Regions in position order; in-memory writes take precedence over Blobs. */
+  assembleParts() {
+    const boundaries = /* @__PURE__ */ new Set([0, this.length]);
+    for (const write of this.writes) {
+      boundaries.add(write.position);
+      boundaries.add(write.position + write.data.byteLength);
+    }
+    for (const part of this.spilled) {
+      boundaries.add(part.position);
+      boundaries.add(part.position + part.size);
+    }
+    const sorted = [...boundaries].sort((left, right) => left - right);
+    const parts = [];
+    for (let i = 0; i + 1 < sorted.length; i++) {
+      const start = sorted[i];
+      const end = sorted[i + 1];
+      if (end <= start) continue;
+      const write = this.writes.find(
+        (candidate) => candidate.position <= start && candidate.position + candidate.data.byteLength >= end
+      );
+      if (write) {
+        parts.push(write.data.subarray(start - write.position, end - write.position));
+        continue;
+      }
+      const part = this.spilled.find(
+        (candidate) => candidate.position <= start && candidate.position + candidate.size >= end
+      );
+      if (part) {
+        parts.push(part.blob.slice(start - part.position, end - part.position));
+        continue;
+      }
+      parts.push(new Uint8Array(end - start));
+    }
+    return parts;
   }
   toArrayBuffer() {
+    if (this.spilled.length > 0) {
+      throw new Error("Spilled MP4 output can only finalize to a Blob");
+    }
     const output = new Uint8Array(this.length);
     for (const write of this.writes) output.set(write.data, write.position);
     this.release();
     return output.buffer;
   }
   toBlob() {
-    const parts = [];
-    let position = 0;
-    for (const write of this.writes) {
-      if (write.position > position) parts.push(new Uint8Array(write.position - position));
-      parts.push(write.data);
-      position = write.position + write.data.byteLength;
-    }
-    if (position < this.length) parts.push(new Uint8Array(this.length - position));
-    const blob = new Blob(parts, { type: "video/mp4" });
+    const blob = new Blob(this.assembleParts(), { type: "video/mp4" });
     this.release();
     return blob;
   }
   release() {
     this.writes = [];
+    this.spilled = [];
+    this.bufferedBytes = 0;
     this.length = 0;
   }
 };
 function createMp4Muxer(options) {
-  const output = new ChunkedMp4Output();
+  const output = new ChunkedMp4Output(options.spillToBlobThresholdBytes ?? null);
   const target = new StreamTarget({
     onData: (data, position) => output.write(data, position)
   });
@@ -2048,6 +2126,7 @@ function shouldEncodeFfmpegBatch(frameCount, byteLength, fps) {
 }
 
 export {
+  DEFAULT_MP4_SPILL_THRESHOLD_BYTES,
   createMp4Muxer,
   resolveWebCodecsQueueLimit,
   applyWebCodecsBackpressure,

package/dist/{chunk-KW5BBYKP.js → chunk-CRXJOZSH.js}

@@ -1,6 +1,6 @@
 import {
   useVideoExport
-} from "./chunk-F2XUI32B.js";
+} from "./chunk-U3RSDWQL.js";
 
 // src/VideoExportModal.tsx
 import { useState, useCallback, useId, useRef } from "react";

package/dist/chunk-NTRCMTCF.js

@@ -0,0 +1,401 @@
+import {
+  useFrameCapture
+} from "./chunk-YTEDBL6F.js";
+
+// src/CoverImageExportModal.tsx
+import { useCallback, useId, useRef, useState } from "react";
+import { useModalDialog } from "@bendyline/squisq-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var MIN_DIMENSION = 64;
+var MAX_DIMENSION = 7680;
+var MAX_PIXELS = 33177600;
+var COVER_IMAGE_SIZE_PRESETS = [{ label: "YouTube cover", width: 1280, height: 720 }];
+var FORMAT_DETAILS = {
+  png: { extension: "png", mime: "image/png", label: "PNG \u2014 lossless" },
+  jpeg: { extension: "jpg", mime: "image/jpeg", label: "JPEG \u2014 smaller file" },
+  webp: { extension: "webp", mime: "image/webp", label: "WebP \u2014 compact" }
+};
+function validateCoverImageDimensions(width, height) {
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)) {
+    return "Width and height must be whole numbers.";
+  }
+  if (width < MIN_DIMENSION || height < MIN_DIMENSION || width > MAX_DIMENSION || height > MAX_DIMENSION) {
+    return `Width and height must be between ${MIN_DIMENSION} and ${MAX_DIMENSION} pixels.`;
+  }
+  if (width * height > MAX_PIXELS) {
+    return "Resolution is too large. Choose a size at or below 33 megapixels.";
+  }
+  return null;
+}
+function coverImageFilename(requestedName, format) {
+  const extension = FORMAT_DETAILS[format].extension;
+  const base = requestedName?.replace(/\.[^.]+$/, "").replace(/[<>:"/\\|?*]/g, "-").split("").map((character) => character.charCodeAt(0) < 32 ? "-" : character).join("").trim().replace(/[. ]+$/g, "") || "document";
+  return `${base}-cover.${extension}`;
+}
+function canvasToBlob(canvas, format, quality) {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) resolve(blob);
+        else reject(new Error("The browser could not encode the cover image."));
+      },
+      FORMAT_DETAILS[format].mime,
+      format === "png" ? void 0 : quality
+    );
+  });
+}
+async function chooseSaveTarget(filename, format) {
+  const picker = window.showSaveFilePicker;
+  if (!picker) return void 0;
+  const details = FORMAT_DETAILS[format];
+  try {
+    return await picker.call(window, {
+      suggestedName: filename,
+      types: [
+        {
+          description: `${details.label.split(" \u2014")[0]} image`,
+          accept: { [details.mime]: [`.${details.extension}`] }
+        }
+      ]
+    });
+  } catch (caught) {
+    if (caught instanceof DOMException && caught.name === "AbortError") return null;
+    throw caught;
+  }
+}
+function downloadBlob(blob, filename) {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+var overlayStyle = {
+  position: "fixed",
+  inset: 0,
+  zIndex: 1e4,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  background: "rgba(0, 0, 0, 0.55)"
+};
+var rowStyle = {
+  display: "grid",
+  gridTemplateColumns: "1fr 1fr",
+  gap: 12
+};
+var labelStyle = {
+  display: "grid",
+  gap: 5,
+  marginBottom: 12,
+  fontSize: 13,
+  fontWeight: 600
+};
+function CoverImageExportModal({
+  doc,
+  mediaProvider,
+  theme,
+  coverSlideTemplate,
+  defaultWidth = 1920,
+  defaultHeight = 1080,
+  defaultFileName,
+  colorScheme = "light",
+  saveOutput,
+  onClose
+}) {
+  const overlayRef = useRef(null);
+  const dialogRef = useRef(null);
+  const titleId = useId();
+  const capture = useFrameCapture();
+  const [format, setFormat] = useState("png");
+  const [width, setWidth] = useState(defaultWidth);
+  const [height, setHeight] = useState(defaultHeight);
+  const [quality, setQuality] = useState(0.92);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const dark = colorScheme === "dark";
+  const surface = dark ? "#111827" : "#ffffff";
+  const control = dark ? "#0f172a" : "#ffffff";
+  const text = dark ? "#f8fafc" : "#1f2937";
+  const muted = dark ? "#94a3b8" : "#6b7280";
+  const border = dark ? "#475569" : "#cbd5e1";
+  const filename = coverImageFilename(defaultFileName, format);
+  const dimensionError = validateCoverImageDimensions(width, height);
+  const handleClose = useCallback(() => {
+    if (busy) return;
+    capture.destroy();
+    onClose();
+  }, [busy, capture, onClose]);
+  useModalDialog({
+    rootRef: overlayRef,
+    dialogRef,
+    closeOnEscape: !busy,
+    onClose: handleClose
+  });
+  const handleExport = useCallback(async () => {
+    if (dimensionError || !doc.startBlock) return;
+    setError(null);
+    try {
+      const saveTarget = saveOutput ? void 0 : await chooseSaveTarget(filename, format);
+      if (saveTarget === null) return;
+      setBusy(true);
+      await capture.init(
+        doc,
+        {
+          width,
+          height,
+          animationsEnabled: false,
+          theme,
+          mediaProvider: mediaProvider ?? void 0,
+          showCoverSlide: true,
+          coverSlideTemplate
+        },
+        "off"
+      );
+      await capture.setCoverVisible(true);
+      const canvas = await capture.captureCanvasFrame(0);
+      const blob = await canvasToBlob(canvas, format, quality);
+      if (saveOutput) {
+        const saved = await saveOutput(blob, filename);
+        if (saved === false) {
+          capture.destroy();
+          return;
+        }
+      } else if (saveTarget) {
+        const writable = await saveTarget.createWritable();
+        await writable.write(blob);
+        await writable.close();
+      } else {
+        downloadBlob(blob, filename);
+      }
+      capture.destroy();
+      onClose();
+    } catch (caught) {
+      capture.destroy();
+      setError(caught instanceof Error ? caught.message : "The cover image could not be exported.");
+    } finally {
+      setBusy(false);
+    }
+  }, [
+    capture,
+    coverSlideTemplate,
+    dimensionError,
+    doc,
+    filename,
+    format,
+    height,
+    mediaProvider,
+    onClose,
+    quality,
+    saveOutput,
+    theme,
+    width
+  ]);
+  const fieldStyle = {
+    boxSizing: "border-box",
+    width: "100%",
+    minHeight: 34,
+    border: `1px solid ${border}`,
+    borderRadius: 4,
+    background: control,
+    color: text,
+    padding: "6px 8px",
+    colorScheme
+  };
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: overlayRef,
+      style: overlayStyle,
+      "data-color-scheme": colorScheme,
+      onClick: (event) => event.stopPropagation(),
+      children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          ref: dialogRef,
+          role: "dialog",
+          "aria-modal": "true",
+          "aria-labelledby": titleId,
+          tabIndex: -1,
+          style: {
+            position: "relative",
+            boxSizing: "border-box",
+            width: "min(440px, calc(100vw - 32px))",
+            padding: 24,
+            border: `1px solid ${border}`,
+            borderRadius: 8,
+            background: surface,
+            color: text,
+            boxShadow: "0 18px 48px rgba(0, 0, 0, 0.28)",
+            fontFamily: "system-ui, -apple-system, sans-serif",
+            colorScheme
+          },
+          onClick: (event) => event.stopPropagation(),
+          children: [
+            /* @__PURE__ */ jsx("h2", { id: titleId, style: { margin: "0 36px 18px 0", fontSize: 19 }, children: "Export cover slide" }),
+            /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                "aria-label": "Close cover image export",
+                disabled: busy,
+                onClick: handleClose,
+                style: {
+                  position: "absolute",
+                  top: 12,
+                  right: 12,
+                  width: 32,
+                  height: 32,
+                  border: 0,
+                  background: "transparent",
+                  color: text,
+                  fontSize: 24,
+                  cursor: busy ? "default" : "pointer"
+                },
+                children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xD7" })
+              }
+            ),
+            /* @__PURE__ */ jsxs("label", { style: labelStyle, children: [
+              "Format",
+              /* @__PURE__ */ jsx(
+                "select",
+                {
+                  "aria-label": "Image format",
+                  value: format,
+                  disabled: busy,
+                  onChange: (event) => setFormat(event.target.value),
+                  style: fieldStyle,
+                  children: Object.entries(FORMAT_DETAILS).map(([value, details]) => /* @__PURE__ */ jsx("option", { value, children: details.label }, value))
+                }
+              )
+            ] }),
+            /* @__PURE__ */ jsxs("div", { style: rowStyle, children: [
+              /* @__PURE__ */ jsxs("label", { style: labelStyle, children: [
+                "Width",
+                /* @__PURE__ */ jsx(
+                  "input",
+                  {
+                    "aria-label": "Image width",
+                    type: "number",
+                    min: MIN_DIMENSION,
+                    max: MAX_DIMENSION,
+                    step: 1,
+                    value: width,
+                    disabled: busy,
+                    onChange: (event) => setWidth(Number(event.target.value)),
+                    style: fieldStyle
+                  }
+                )
+              ] }),
+              /* @__PURE__ */ jsxs("label", { style: labelStyle, children: [
+                "Height",
+                /* @__PURE__ */ jsx(
+                  "input",
+                  {
+                    "aria-label": "Image height",
+                    type: "number",
+                    min: MIN_DIMENSION,
+                    max: MAX_DIMENSION,
+                    step: 1,
+                    value: height,
+                    disabled: busy,
+                    onChange: (event) => setHeight(Number(event.target.value)),
+                    style: fieldStyle
+                  }
+                )
+              ] })
+            ] }),
+            /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 8, margin: "-2px 0 14px" }, children: [
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  disabled: busy,
+                  onClick: () => {
+                    setWidth(defaultWidth);
+                    setHeight(defaultHeight);
+                  },
+                  children: "1\xD7"
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  disabled: busy,
+                  onClick: () => {
+                    setWidth(defaultWidth * 2);
+                    setHeight(defaultHeight * 2);
+                  },
+                  children: "2\xD7"
+                }
+              ),
+              COVER_IMAGE_SIZE_PRESETS.map((preset) => /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  disabled: busy,
+                  title: `${preset.width} \xD7 ${preset.height} pixels`,
+                  onClick: () => {
+                    setWidth(preset.width);
+                    setHeight(preset.height);
+                  },
+                  children: preset.label
+                },
+                preset.label
+              )),
+              /* @__PURE__ */ jsxs("span", { style: { alignSelf: "center", color: muted, fontSize: 12 }, children: [
+                width.toLocaleString(),
+                " \xD7 ",
+                height.toLocaleString(),
+                " pixels"
+              ] })
+            ] }),
+            format !== "png" && /* @__PURE__ */ jsxs("label", { style: labelStyle, children: [
+              "Quality: ",
+              Math.round(quality * 100),
+              "%",
+              /* @__PURE__ */ jsx(
+                "input",
+                {
+                  "aria-label": "Image quality",
+                  type: "range",
+                  min: 0.5,
+                  max: 1,
+                  step: 0.05,
+                  value: quality,
+                  disabled: busy,
+                  onChange: (event) => setQuality(Number(event.target.value))
+                }
+              )
+            ] }),
+            (dimensionError || error) && /* @__PURE__ */ jsx("p", { role: "alert", style: { margin: "0 0 12px", color: dark ? "#fca5a5" : "#b91c1c" }, children: dimensionError ?? error }),
+            !doc.startBlock && /* @__PURE__ */ jsx("p", { role: "alert", style: { margin: "0 0 12px", color: dark ? "#fca5a5" : "#b91c1c" }, children: "This document does not have a cover slide to export." }),
+            /* @__PURE__ */ jsxs("div", { style: { display: "flex", justifyContent: "flex-end", gap: 8 }, children: [
+              /* @__PURE__ */ jsx("button", { type: "button", disabled: busy, onClick: handleClose, children: "Cancel" }),
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  disabled: busy || !!dimensionError || !doc.startBlock,
+                  onClick: () => void handleExport(),
+                  style: { minWidth: 132 },
+                  children: busy ? "Rendering\u2026" : "Choose location\u2026"
+                }
+              )
+            ] })
+          ]
+        }
+      )
+    }
+  );
+}
+
+export {
+  validateCoverImageDimensions,
+  coverImageFilename,
+  CoverImageExportModal
+};