@bendyline/squisq-video-react 2.0.2 → 2.2.0

package/dist/useVideoExport-NtqZVgaz.d.ts

@@ -0,0 +1,115 @@
+import { MediaProvider, Doc } from '@bendyline/squisq/schemas';
+import { ResourcePolicy } from '@bendyline/squisq/markdown';
+import { VideoQuality, VideoOrientation, FfmpegWasmLoadConfig } from '@bendyline/squisq-video';
+import { CaptionMode } from '@bendyline/squisq-react';
+
+/**
+ * useVideoExport — Main orchestration hook for browser video export.
+ *
+ * Coordinates frame capture (hidden iframe + html2canvas) with
+ * main-thread WebCodecs encoding via mp4-muxer. Manages the full
+ * lifecycle: prepare → capture + encode → download.
+ *
+ * Encoding runs on the main thread because frame capture via html2canvas
+ * (~100-200ms per frame) is the bottleneck, not encoding (~1ms per frame
+ * with hardware-accelerated WebCodecs). Worker offloading would add
+ * complexity with minimal benefit.
+ *
+ * Usage:
+ *   const { state, progress, phase, startExport, cancel, downloadUrl } = useVideoExport();
+ *   <button onClick={() => startExport(doc, options)}>Export</button>
+ */
+
+type VideoExportState = 'idle' | 'preparing' | 'capturing' | 'encoding' | 'complete' | 'error';
+/** Browser export container format. */
+type VideoOutputFormat = 'mp4' | 'gif';
+type VideoAudioPolicy = 'require' | 'best-effort' | 'omit';
+interface VideoExportConfig {
+    /** Output container (default: 'mp4') */
+    outputFormat?: VideoOutputFormat;
+    /**
+     * How authored MP4 audio is handled. `require` (default) fails before
+     * capture when audio cannot be loaded/decoded and fails the export if later
+     * encoding or muxing fails. `best-effort` explicitly permits video-only
+     * degradation; `omit` intentionally skips audio.
+     */
+    audioPolicy?: VideoAudioPolicy;
+    /** Render authored animations and slide transitions (default: true for MP4, false for GIF). */
+    animationsEnabled?: boolean;
+    /** Encoding quality preset (default: 'normal') */
+    quality?: VideoQuality;
+    /** Frames per second (default: 30) */
+    fps?: number;
+    /** Viewport orientation (default: 'landscape') */
+    orientation?: VideoOrientation;
+    /** Explicit output width. GIF defaults to 960 landscape / 540 portrait. */
+    width?: number;
+    /** Explicit output height. GIF defaults to 540 landscape / 960 portrait. */
+    height?: number;
+    /**
+     * Map of relative image paths to binary data.
+     * Used to embed images into the render HTML.
+     */
+    images?: Map<string, ArrayBuffer>;
+    /**
+     * Map of audio segment names to binary data.
+     * Used to embed audio into the render HTML.
+     */
+    audio?: Map<string, ArrayBuffer>;
+    /** MediaProvider to resolve media URLs (alternative to passing images directly) */
+    mediaProvider?: MediaProvider;
+    /** Policy and byte/time limits for MediaProvider URLs. */
+    resourcePolicy?: ResourcePolicy;
+    /** Caption mode for the exported video (default: 'off') */
+    captionMode?: CaptionMode;
+    /** Player IIFE bundle (unused in browser export, kept for CLI/Playwright path) */
+    playerScript?: string;
+    /** Optional self-hosted ffmpeg.wasm core URLs for fallback/offline/CSP use. */
+    ffmpegWasm?: FfmpegWasmLoadConfig;
+}
+interface VideoExportResult {
+    /** Current export state */
+    state: VideoExportState;
+    /** 0–100 progress percentage */
+    progress: number;
+    /** Human-readable description of the current phase */
+    phase: string;
+    /** Video duration detected from the doc (seconds) */
+    duration: number;
+    /** Effective output format for the current or most recent export. */
+    outputFormat: VideoOutputFormat;
+    /** Encoder backend ('webcodecs' when WebCodecs H.264 active, 'ffmpeg-wasm' when worker fallback active, null when idle) */
+    backend: 'webcodecs' | 'ffmpeg-wasm' | null;
+    /** Blob download URL (populated when state === 'complete') */
+    downloadUrl: string | null;
+    /** File size in bytes (populated when state === 'complete') */
+    fileSize: number;
+    /**
+     * Whether an audio track was muxed into the exported MP4 (populated when
+     * state === 'complete'). False when the doc had no audio or when audio was
+     * skipped/degraded — see {@link audioSkippedReason}.
+     */
+    audioIncluded: boolean;
+    /**
+     * Why audio is absent, when `audioIncluded` is false. `null` means the doc
+     * simply had no audio (not a failure); a non-null string explains a genuine
+     * capability shortfall or runtime failure. Audio problems never fail the
+     * export — the video always completes.
+     */
+    audioSkippedReason: string | null;
+    /** Error message (populated when state === 'error') */
+    error: string | null;
+    /** Seconds elapsed since export started */
+    elapsed: number;
+    /** Estimated seconds remaining (0 when idle or complete) */
+    estimatedRemaining: number;
+    /** Start a new export */
+    startExport: (doc: Doc, config: VideoExportConfig) => Promise<void>;
+    /** Cancel an in-progress export */
+    cancel: () => void;
+    /** Reset state back to idle (e.g., after complete or error) */
+    reset: () => void;
+}
+declare function useVideoExport(): VideoExportResult;
+
+export { type VideoAudioPolicy as V, type VideoExportConfig as a, type VideoExportResult as b, type VideoExportState as c, type VideoOutputFormat as d, useVideoExport as u };

package/dist/workers/encode.worker.js

@@ -1,9 +1,13 @@
 import {
   createMp4Muxer
-} from "../chunk-6DKLHXX3.js";
+} from "../chunk-VI5AIVOQ.js";
 
 // src/workers/encode.worker.ts
-import { bitrateForQuality, ffmpegVideoQualityArgs } from "@bendyline/squisq-video";
+import {
+  bitrateForQuality,
+  ffmpegVideoQualityArgs,
+  resolveFfmpegWasmLoad
+} from "@bendyline/squisq-video";
 var backend = null;
 var cancelled = false;
 var videoEncoder = null;
@@ -12,19 +16,27 @@ var ffmpegInstance = null;
 var ffmpegFrames = [];
 var ffmpegConfig = null;
 var totalFramesReceived = 0;
+var totalFramesExpected = 0;
 function post(msg, transfer) {
   self.postMessage(msg, { transfer: transfer ?? [] });
 }
 function postProgress(percent, phase) {
   post({ type: "progress", percent, phase });
 }
+function postFrameProgress(scale, phase) {
+  if (totalFramesExpected <= 0) {
+    post({ type: "progress", percent: 0, phase, indeterminate: true });
+    return;
+  }
+  const ratio = Math.min(totalFramesReceived / totalFramesExpected, 1);
+  post({ type: "progress", percent: Math.round(ratio * scale), phase });
+}
 function postError(message) {
   post({ type: "error", message });
 }
 function disposeFfmpeg() {
-  const instance = ffmpegInstance;
   try {
-    instance?.terminate?.();
+    ffmpegInstance?.terminate();
   } finally {
     ffmpegInstance = null;
   }
@@ -84,10 +96,10 @@ async function encodeFrameWebCodecs(msg) {
   frame.close();
   msg.bitmap.close();
   totalFramesReceived++;
-  postProgress(
-    Math.round(totalFramesReceived / (totalFramesReceived + 1) * 50),
-    `Encoding frame ${totalFramesReceived}`
-  );
+  postFrameProgress(50, frameLabel("Encoding"));
+}
+function frameLabel(verb) {
+  return totalFramesExpected > 0 ? `${verb} frame ${totalFramesReceived}/${totalFramesExpected}` : `${verb} frame ${totalFramesReceived}`;
 }
 async function finalizeWebCodecs() {
   if (!videoEncoder || !muxer || cancelled) return;
@@ -105,14 +117,14 @@ async function initFfmpegWasm(config) {
   ffmpegFrames = [];
   ffmpegSegments.length = 0;
   totalFramesReceived = 0;
+  const load = resolveFfmpegWasmLoad(config.ffmpegWasm, "The ffmpeg.wasm encoder fallback", {
+    classWorkerURL: new URL("./ffmpeg.class-worker.js", import.meta.url).href
+  });
   let ffmpeg = null;
   try {
     const { FFmpeg } = await import("@ffmpeg/ffmpeg");
     ffmpeg = new FFmpeg();
-    await ffmpeg.load({
-      ...config.ffmpegWasm,
-      classWorkerURL: config.ffmpegWasm?.classWorkerURL ?? new URL("./ffmpeg.class-worker.js", import.meta.url).href
-    });
+    await ffmpeg.load(load);
     ffmpegInstance = ffmpeg;
   } catch (err) {
     ffmpeg?.terminate();
@@ -140,10 +152,7 @@ async function encodeFrameFfmpeg(msg) {
   const arrayBuffer = await blob.arrayBuffer();
   ffmpegFrames.push({ data: new Uint8Array(arrayBuffer), index: msg.frameIndex });
   totalFramesReceived++;
-  postProgress(
-    Math.round(totalFramesReceived / (totalFramesReceived + 1) * 40),
-    `Collecting frame ${totalFramesReceived}`
-  );
+  postFrameProgress(80, frameLabel("Collecting"));
   const batchSize = (ffmpegConfig?.fps ?? 30) * 10;
   if (ffmpegFrames.length >= batchSize) {
     await encodeFfmpegBatch();
@@ -156,12 +165,19 @@ async function execOrThrow(ffmpeg, args, operation) {
     throw new Error(`${operation} failed with ffmpeg exit code ${exitCode}`);
   }
 }
+async function readBinaryFile(ffmpeg, path) {
+  const data = await ffmpeg.readFile(path);
+  if (typeof data === "string") {
+    throw new Error(`Expected binary data from ffmpeg for ${path}`);
+  }
+  return data;
+}
 async function encodeFfmpegBatch() {
   if (!ffmpegInstance || ffmpegFrames.length === 0 || cancelled) return;
   const ffmpeg = ffmpegInstance;
   const config = ffmpegConfig;
   const batchIndex = ffmpegSegments.length;
-  postProgress(40 + batchIndex * 5, `Encoding batch ${batchIndex + 1}\u2026`);
+  postFrameProgress(80, `Encoding batch ${batchIndex + 1}\u2026`);
   for (const frame of ffmpegFrames) {
     const paddedIndex = String(frame.index).padStart(6, "0");
     await ffmpeg.writeFile(`frame_${paddedIndex}.png`, frame.data);
@@ -188,7 +204,7 @@ async function encodeFfmpegBatch() {
     ],
     `Encoding video segment ${batchIndex + 1}`
   );
-  const segmentData = await ffmpeg.readFile(segmentName);
+  const segmentData = await readBinaryFile(ffmpeg, segmentName);
   ffmpegSegments.push(segmentData);
   for (const frame of ffmpegFrames) {
     const paddedIndex = String(frame.index).padStart(6, "0");
@@ -218,7 +234,7 @@ async function finalizeFfmpeg() {
       ["-f", "concat", "-safe", "0", "-i", "concat.txt", "-c", "copy", "output.mp4"],
       "Concatenating video segments"
     );
-    finalData = await ffmpeg.readFile("output.mp4");
+    finalData = await readBinaryFile(ffmpeg, "output.mp4");
     for (let i = 0; i < ffmpegSegments.length; i++) {
       await ffmpeg.deleteFile(`seg_${i}.mp4`);
     }
@@ -239,6 +255,7 @@ async function handleMessage(msg) {
     case "init": {
       cancelled = false;
       totalFramesReceived = 0;
+      totalFramesExpected = typeof msg.totalFrames === "number" && Number.isFinite(msg.totalFrames) ? Math.max(0, Math.floor(msg.totalFrames)) : 0;
       if (await supportsWebCodecsH264(msg)) {
         backend = "webcodecs";
         initWebCodecs(msg);
@@ -289,6 +306,7 @@ async function handleMessage(msg) {
       disposeFfmpeg();
       ffmpegFrames = [];
       ffmpegSegments.length = 0;
+      totalFramesExpected = 0;
       backend = null;
       break;
     }
@@ -303,4 +321,3 @@ self.onmessage = (event) => {
     postError(message);
   });
 };
-//# sourceMappingURL=encode.worker.js.map

package/dist/workers/ffmpeg.class-worker.js

@@ -177,4 +177,3 @@ self.onmessage = async ({ data: { id, type, data: _data } }) => {
   }
   self.postMessage({ id, type, data }, trans);
 };
-//# sourceMappingURL=ffmpeg.class-worker.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-video-react",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "React components for browser-based MP4 and animated-GIF export of Squisq documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -23,6 +23,9 @@
     "access": "public"
   },
   "type": "module",
+  "engines": {
+    "node": ">=22.14.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -30,14 +33,29 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js"
+    },
+    "./encoder": {
+      "types": "./dist/encoder/index.d.ts",
+      "import": "./dist/encoder/index.js"
     }
   },
   "files": [
     "dist",
-    "src"
+    "!dist/**/*.map",
+    "LICENSE",
+    "NOTICE.md",
+    "COPYING.GPL-2.0.txt"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node ../../scripts/remove-empty-chunks.mjs dist",
     "dev": "concurrently -n js,dts -c blue,gray -r \"tsup --watch --no-dts --no-clean\" \"tsup --watch --dts-only --no-clean\"",
     "typecheck": "tsc --noEmit"
   },
@@ -46,20 +64,20 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.1.0",
-    "@bendyline/squisq-video": "2.0.2",
-    "@bendyline/squisq-react": "2.1.0",
+    "@bendyline/squisq": "2.3.0",
+    "@bendyline/squisq-video": "2.2.0",
+    "@bendyline/squisq-react": "2.3.0",
     "@ffmpeg/core": "0.12.9",
     "@ffmpeg/ffmpeg": "0.12.15",
     "@ffmpeg/util": "0.12.2",
-    "html2canvas": "1.4.1",
-    "mp4-muxer": "5.2.2"
+    "html2canvas": "1.4.1"
   },
   "devDependencies": {
     "@types/react": "18.3.28",
     "@types/react-dom": "18.3.7",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "mp4-muxer": "5.2.2",
     "tsup": "8.5.1",
     "typescript": "5.9.3"
   },

package/dist/chunk-6DKLHXX3.js

@@ -1,47 +0,0 @@
-// src/mp4Mux.ts
-import { Muxer, ArrayBufferTarget } from "mp4-muxer";
-function createMp4Muxer(options) {
-  const target = new ArrayBufferTarget();
-  const muxer = new Muxer({
-    target,
-    video: {
-      codec: "avc",
-      width: options.width,
-      height: options.height
-    },
-    // Only declare the audio track when requested so the video-only
-    // configuration stays byte-identical to the historical output.
-    ...options.audio ? {
-      audio: {
-        codec: "aac",
-        numberOfChannels: options.audio.numberOfChannels,
-        sampleRate: options.audio.sampleRate
-      }
-    } : {},
-    fastStart: "in-memory"
-  });
-  return {
-    hasAudioTrack: options.audio !== void 0,
-    addVideoChunk(chunk, meta) {
-      muxer.addVideoChunk(chunk, meta);
-    },
-    addVideoChunkRaw(data, type, timestampMicros, durationMicros, meta) {
-      muxer.addVideoChunkRaw(data, type, timestampMicros, durationMicros, meta);
-    },
-    addAudioChunk(chunk, meta) {
-      muxer.addAudioChunk(chunk, meta);
-    },
-    addAudioChunkRaw(data, type, timestampMicros, durationMicros, meta) {
-      muxer.addAudioChunkRaw(data, type, timestampMicros, durationMicros, meta);
-    },
-    finalize() {
-      muxer.finalize();
-      return target.buffer;
-    }
-  };
-}
-
-export {
-  createMp4Muxer
-};
-//# sourceMappingURL=chunk-6DKLHXX3.js.map

package/dist/chunk-6DKLHXX3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/mp4Mux.ts"],"sourcesContent":["/**\n * mp4Mux — Thin wrapper around mp4-muxer for WebCodecs encoding.\n *\n * Creates a Muxer instance configured for H.264 video (and, optionally, an\n * AAC audio track), accumulates encoded chunks, and produces a final MP4\n * ArrayBuffer. When no `audio` option is supplied the muxer configuration is\n * byte-identical to the video-only path.\n */\n\nimport { Muxer, ArrayBufferTarget } from 'mp4-muxer';\n\nexport interface Mp4MuxerOptions {\n  width: number;\n  height: number;\n  fps: number;\n  /**\n   * When present, declares an AAC audio track alongside the video track.\n   * Feed encoded audio via {@link Mp4MuxerHandle.addAudioChunk} (from a\n   * WebCodecs `AudioEncoder`) or {@link Mp4MuxerHandle.addAudioChunkRaw}.\n   */\n  audio?: {\n    numberOfChannels: number;\n    sampleRate: number;\n  };\n}\n\nexport interface Mp4MuxerHandle {\n  /** Add an encoded video chunk to the muxer. */\n  addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata): void;\n  /**\n   * Add a raw video sample (bytes + timing) without an `EncodedVideoChunk`.\n   * Useful where no `VideoEncoder` instance is available (e.g. Node tests).\n   */\n  addVideoChunkRaw(\n    data: Uint8Array,\n    type: 'key' | 'delta',\n    timestampMicros: number,\n    durationMicros: number,\n    meta?: EncodedVideoChunkMetadata,\n  ): void;\n  /** Add an encoded audio chunk (from a WebCodecs `AudioEncoder`). */\n  addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;\n  /**\n   * Add a raw audio sample (bytes + timing) without an `EncodedAudioChunk`.\n   * Useful where no `AudioEncoder` instance is available (e.g. Node tests).\n   */\n  addAudioChunkRaw(\n    data: Uint8Array,\n    type: 'key' | 'delta',\n    timestampMicros: number,\n    durationMicros: number,\n    meta?: EncodedAudioChunkMetadata,\n  ): void;\n  /** Whether this muxer was created with an audio track. */\n  readonly hasAudioTrack: boolean;\n  /** Finalize and return the MP4 as an ArrayBuffer. */\n  finalize(): ArrayBuffer;\n}\n\n/**\n * Create an MP4 muxer configured for H.264 video, plus an optional AAC track.\n */\nexport function createMp4Muxer(options: Mp4MuxerOptions): Mp4MuxerHandle {\n  const target = new ArrayBufferTarget();\n\n  const muxer = new Muxer({\n    target,\n    video: {\n      codec: 'avc',\n      width: options.width,\n      height: options.height,\n    },\n    // Only declare the audio track when requested so the video-only\n    // configuration stays byte-identical to the historical output.\n    ...(options.audio\n      ? {\n          audio: {\n            codec: 'aac' as const,\n            numberOfChannels: options.audio.numberOfChannels,\n            sampleRate: options.audio.sampleRate,\n          },\n        }\n      : {}),\n    fastStart: 'in-memory',\n  });\n\n  return {\n    hasAudioTrack: options.audio !== undefined,\n\n    addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata) {\n      muxer.addVideoChunk(chunk, meta);\n    },\n\n    addVideoChunkRaw(\n      data: Uint8Array,\n      type: 'key' | 'delta',\n      timestampMicros: number,\n      durationMicros: number,\n      meta?: EncodedVideoChunkMetadata,\n    ) {\n      muxer.addVideoChunkRaw(data, type, timestampMicros, durationMicros, meta);\n    },\n\n    addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata) {\n      muxer.addAudioChunk(chunk, meta);\n    },\n\n    addAudioChunkRaw(\n      data: Uint8Array,\n      type: 'key' | 'delta',\n      timestampMicros: number,\n      durationMicros: number,\n      meta?: EncodedAudioChunkMetadata,\n    ) {\n      muxer.addAudioChunkRaw(data, type, timestampMicros, durationMicros, meta);\n    },\n\n    finalize(): ArrayBuffer {\n      muxer.finalize();\n      return target.buffer;\n    },\n  };\n}\n"],"mappings":";AASA,SAAS,OAAO,yBAAyB;AAqDlC,SAAS,eAAe,SAA0C;AACvE,QAAM,SAAS,IAAI,kBAAkB;AAErC,QAAM,QAAQ,IAAI,MAAM;AAAA,IACtB;AAAA,IACA,OAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,QAAQ;AAAA,MACf,QAAQ,QAAQ;AAAA,IAClB;AAAA;AAAA;AAAA,IAGA,GAAI,QAAQ,QACR;AAAA,MACE,OAAO;AAAA,QACL,OAAO;AAAA,QACP,kBAAkB,QAAQ,MAAM;AAAA,QAChC,YAAY,QAAQ,MAAM;AAAA,MAC5B;AAAA,IACF,IACA,CAAC;AAAA,IACL,WAAW;AAAA,EACb,CAAC;AAED,SAAO;AAAA,IACL,eAAe,QAAQ,UAAU;AAAA,IAEjC,cAAc,OAA0B,MAAkC;AACxE,YAAM,cAAc,OAAO,IAAI;AAAA,IACjC;AAAA,IAEA,iBACE,MACA,MACA,iBACA,gBACA,MACA;AACA,YAAM,iBAAiB,MAAM,MAAM,iBAAiB,gBAAgB,IAAI;AAAA,IAC1E;AAAA,IAEA,cAAc,OAA0B,MAAkC;AACxE,YAAM,cAAc,OAAO,IAAI;AAAA,IACjC;AAAA,IAEA,iBACE,MACA,MACA,iBACA,gBACA,MACA;AACA,YAAM,iBAAiB,MAAM,MAAM,iBAAiB,gBAAgB,IAAI;AAAA,IAC1E;AAAA,IAEA,WAAwB;AACtB,YAAM,SAAS;AACf,aAAO,OAAO;AAAA,IAChB;AAAA,EACF;AACF;","names":[]}