@bendyline/squisq-video-react 2.2.3 → 2.2.5

package/dist/{chunk-IDY64F4K.js → chunk-NZYFSB2T.js}

@@ -26,34 +26,61 @@ var MIME_MAP = {
   webp: "image/webp",
   svg: "image/svg+xml",
   bmp: "image/bmp",
-  avif: "image/avif"
+  avif: "image/avif",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  mp4: "video/mp4",
+  webm: "video/webm"
 };
-var VISUAL_UPDATE_FALLBACK_MS = 100;
+var CAPTURE_ASSET_TIMEOUT_MS = 15e3;
+var RENDER_TIME_EPSILON_SECONDS = 1e-6;
 var POTENTIALLY_ANIMATED_IMAGE_URL = /(?:^data:image\/(?:gif|webp|avif)[;,]|\.(?:gif|webp|avif)(?:[?#]|$))/i;
-function waitForVisualUpdate(frameCount = 1) {
-  return new Promise((resolve) => {
-    let settled = false;
-    let animationFrame = null;
-    const finish = () => {
-      if (settled) return;
-      settled = true;
-      window.clearTimeout(fallback);
-      if (animationFrame !== null) window.cancelAnimationFrame(animationFrame);
-      resolve();
-    };
-    const fallback = window.setTimeout(
-      finish,
-      document.visibilityState === "visible" ? VISUAL_UPDATE_FALLBACK_MS : 0
+async function waitForImageDecode(image) {
+  const src = image.currentSrc || image.src;
+  if (!src) return;
+  const decoded = typeof image.decode === "function" ? image.decode() : new Promise((resolve, reject) => {
+    if (image.complete) {
+      if (image.naturalWidth > 0) resolve();
+      else reject(new Error(`Image could not be decoded: ${src}`));
+      return;
+    }
+    image.addEventListener("load", () => resolve(), { once: true });
+    image.addEventListener(
+      "error",
+      () => reject(new Error(`Image could not be loaded: ${src}`)),
+      {
+        once: true
+      }
     );
-    if (document.visibilityState !== "visible") return;
-    const waitForFrame = (remaining) => {
-      animationFrame = window.requestAnimationFrame(() => {
-        if (remaining <= 1) finish();
-        else waitForFrame(remaining - 1);
-      });
-    };
-    waitForFrame(Math.max(1, frameCount));
   });
+  let timeout;
+  try {
+    await Promise.race([
+      decoded,
+      new Promise((_resolve, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error(`Image did not become ready within 15s: ${src}`)),
+          CAPTURE_ASSET_TIMEOUT_MS
+        );
+      })
+    ]);
+  } finally {
+    if (timeout !== void 0) clearTimeout(timeout);
+  }
+}
+async function waitForCaptureAssets(captureRoot, decodedImages = /* @__PURE__ */ new WeakSet()) {
+  const fonts = captureRoot.ownerDocument.fonts;
+  if (fonts) await fonts.ready;
+  const pendingImages = Array.from(captureRoot.querySelectorAll("img")).filter(
+    (image) => !decodedImages.has(image)
+  );
+  await Promise.all(
+    pendingImages.map(async (image) => {
+      await waitForImageDecode(image);
+      decodedImages.add(image);
+    })
+  );
 }
 function createInlineProvider(images) {
   const blobUrls = /* @__PURE__ */ new Map();
@@ -96,6 +123,159 @@ function shouldIgnoreCaptureSibling(element, captureRoot) {
 function finiteMediaTime(value) {
   return Number.isFinite(value) ? value.toFixed(6) : "unknown";
 }
+function coverSourceRect(sourceWidth, sourceHeight, destinationWidth, destinationHeight) {
+  const sourceRatio = sourceWidth / sourceHeight;
+  const destinationRatio = destinationWidth / destinationHeight;
+  if (sourceRatio > destinationRatio) {
+    const sw = sourceHeight * destinationRatio;
+    return { sx: (sourceWidth - sw) / 2, sy: 0, sw, sh: sourceHeight };
+  }
+  const sh = sourceWidth / destinationRatio;
+  return { sx: 0, sy: (sourceHeight - sh) / 2, sw: sourceWidth, sh };
+}
+function videoFrameRect(sourceWidth, sourceHeight, destinationWidth, destinationHeight, objectFit) {
+  if (objectFit === "cover") {
+    return {
+      ...coverSourceRect(sourceWidth, sourceHeight, destinationWidth, destinationHeight),
+      dx: 0,
+      dy: 0,
+      dw: destinationWidth,
+      dh: destinationHeight
+    };
+  }
+  if (objectFit === "contain" || objectFit === "scale-down") {
+    const containScale = Math.min(destinationWidth / sourceWidth, destinationHeight / sourceHeight);
+    const scale = objectFit === "scale-down" ? Math.min(1, containScale) : containScale;
+    const dw = sourceWidth * scale;
+    const dh = sourceHeight * scale;
+    return {
+      sx: 0,
+      sy: 0,
+      sw: sourceWidth,
+      sh: sourceHeight,
+      dx: (destinationWidth - dw) / 2,
+      dy: (destinationHeight - dh) / 2,
+      dw,
+      dh
+    };
+  }
+  if (objectFit === "none") {
+    return {
+      sx: 0,
+      sy: 0,
+      sw: sourceWidth,
+      sh: sourceHeight,
+      dx: (destinationWidth - sourceWidth) / 2,
+      dy: (destinationHeight - sourceHeight) / 2,
+      dw: sourceWidth,
+      dh: sourceHeight
+    };
+  }
+  return {
+    sx: 0,
+    sy: 0,
+    sw: sourceWidth,
+    sh: sourceHeight,
+    dx: 0,
+    dy: 0,
+    dw: destinationWidth,
+    dh: destinationHeight
+  };
+}
+function prepareScheduledVideoClones(originalRoot, clonedRoot) {
+  const captureFamilies = [
+    {
+      original: ".doc-player__media-clips video[data-clip-id]",
+      clone: ".doc-player__media-clips canvas"
+    },
+    {
+      original: ".block-layer--video video[data-clip-start]",
+      clone: ".block-layer--video canvas"
+    }
+  ];
+  const pairs = captureFamilies.flatMap(({ original, clone }) => {
+    const videos = Array.from(originalRoot.querySelectorAll(original));
+    const canvases = Array.from(clonedRoot.querySelectorAll(clone));
+    return videos.flatMap((video, index) => {
+      const canvas = canvases[index];
+      return canvas ? [{ video, canvas }] : [];
+    });
+  });
+  pairs.forEach(({ video, canvas }) => {
+    canvas.className = video.className;
+    canvas.style.cssText = video.style.cssText;
+    for (const attribute of Array.from(video.attributes)) {
+      if (attribute.name.startsWith("data-")) {
+        canvas.setAttribute(attribute.name, attribute.value);
+      }
+    }
+    canvas.dataset.videoCaptureClone = "true";
+    const destinationWidth = Math.round(video.clientWidth || video.offsetWidth);
+    const destinationHeight = Math.round(video.clientHeight || video.offsetHeight);
+    if (video.videoWidth <= 0 || video.videoHeight <= 0 || destinationWidth <= 0 || destinationHeight <= 0) {
+      return;
+    }
+    try {
+      const view = video.ownerDocument.defaultView;
+      const objectFit = video.style.objectFit || view?.getComputedStyle(video).objectFit || "fill";
+      const frame = videoFrameRect(
+        video.videoWidth,
+        video.videoHeight,
+        destinationWidth,
+        destinationHeight,
+        objectFit
+      );
+      const stagingCanvas = canvas.ownerDocument.createElement("canvas");
+      stagingCanvas.width = destinationWidth;
+      stagingCanvas.height = destinationHeight;
+      const stagingContext = stagingCanvas.getContext("2d");
+      const context = canvas.getContext("2d");
+      if (!stagingContext || !context) return;
+      stagingContext.drawImage(
+        video,
+        frame.sx,
+        frame.sy,
+        frame.sw,
+        frame.sh,
+        frame.dx,
+        frame.dy,
+        frame.dw,
+        frame.dh
+      );
+      canvas.width = destinationWidth;
+      canvas.height = destinationHeight;
+      context.drawImage(stagingCanvas, 0, 0);
+      const foreignObject = canvas.closest("foreignObject");
+      const svg = canvas.closest("svg");
+      if (foreignObject && svg) {
+        const originalHost = video.closest(".doc-player__block") ?? originalRoot;
+        const clonedHost = svg.closest(".doc-player__block") ?? clonedRoot;
+        const videoRect = video.getBoundingClientRect();
+        const hostRect = originalHost.getBoundingClientRect();
+        const renderedWidth = videoRect.width || destinationWidth;
+        const renderedHeight = videoRect.height || destinationHeight;
+        const fallbackX = Number.parseFloat(foreignObject.getAttribute("x") ?? "0") || 0;
+        const fallbackY = Number.parseFloat(foreignObject.getAttribute("y") ?? "0") || 0;
+        const left = videoRect.width ? videoRect.left - hostRect.left : fallbackX;
+        const top = videoRect.height ? videoRect.top - hostRect.top : fallbackY;
+        foreignObject.remove();
+        if (clonedHost === clonedRoot && !clonedHost.style.position) {
+          clonedHost.style.position = "relative";
+        }
+        canvas.style.position = "absolute";
+        canvas.style.left = `${left}px`;
+        canvas.style.top = `${top}px`;
+        canvas.style.width = `${renderedWidth}px`;
+        canvas.style.height = `${renderedHeight}px`;
+        canvas.style.zIndex = "3";
+        canvas.style.margin = "0";
+        canvas.style.transform = "none";
+        clonedHost.appendChild(canvas);
+      }
+    } catch {
+    }
+  });
+}
 function getFrameVisualStateKey(captureRoot, timelineTime) {
   const markup = captureRoot.innerHTML;
   let needsTimelineKey = false;
@@ -153,6 +333,7 @@ function useFrameCapture() {
   const captureCanvasRef = useRef(null);
   const lastVisualStateKeyRef = useRef(null);
   const hasCapturedFrameRef = useRef(false);
+  const decodedImagesRef = useRef(/* @__PURE__ */ new WeakSet());
   const dimensionsRef = useRef({ width: 1920, height: 1080 });
   const init = useCallback(
     async (doc, renderOptions, captionMode) => {
@@ -168,6 +349,7 @@ function useFrameCapture() {
         captureCanvasRef.current = null;
         lastVisualStateKeyRef.current = null;
         hasCapturedFrameRef.current = false;
+        decodedImagesRef.current = /* @__PURE__ */ new WeakSet();
         await new Promise((resolve) => {
           setTimeout(() => {
             if (oldRoot) oldRoot.unmount();
@@ -193,6 +375,7 @@ function useFrameCapture() {
       captureCanvasRef.current = captureCanvas;
       lastVisualStateKeyRef.current = null;
       hasCapturedFrameRef.current = false;
+      decodedImagesRef.current = /* @__PURE__ */ new WeakSet();
       const container = document.createElement("div");
       container.style.cssText = `position:fixed;left:0;top:0;width:${width}px;height:${height}px;opacity:0;pointer-events:none;z-index:-1;overflow:hidden;`;
       document.body.appendChild(container);
@@ -219,6 +402,12 @@ function useFrameCapture() {
         showControls: false,
         autoPlay: false,
         forceViewport: { width, height, name: "export" },
+        theme: renderOptions.theme,
+        videoPresentation: renderOptions.videoPresentation,
+        pipSize: renderOptions.pipSize,
+        pipShape: renderOptions.pipShape,
+        pipPosition: renderOptions.pipPosition,
+        showCoverSlide: renderOptions.showCoverSlide,
         captionsEnabled,
         captionStyle,
         onRenderAPIReady: (api) => {
@@ -246,14 +435,31 @@ function useFrameCapture() {
             )
           );
         }, 15e3);
-        void renderAPIReady.then((api) => {
-          clearTimeout(timeout);
-          resolve(api.getDuration());
+        void renderAPIReady.then(async (api) => {
+          try {
+            const captureRoot = container.querySelector("#squisq-capture-root");
+            if (!(captureRoot instanceof HTMLElement)) {
+              throw new Error("Capture root element not found after player initialization.");
+            }
+            await waitForCaptureAssets(captureRoot, decodedImagesRef.current);
+            clearTimeout(timeout);
+            resolve(api.getDuration());
+          } catch (assetError) {
+            clearTimeout(timeout);
+            reject(assetError);
+          }
         });
       });
     },
     []
   );
+  const setCoverVisible = useCallback(async (visible) => {
+    const api = renderAPIRef.current;
+    if (!api) throw new Error("Frame capture not initialized \xE2\u20AC\u201D call init() first");
+    if (visible) await api.showCover();
+    else await api.hideCover();
+    lastVisualStateKeyRef.current = null;
+  }, []);
   const captureCanvasFrame = useCallback(
     async (time, options = {}) => {
       const container = containerRef.current;
@@ -264,11 +470,17 @@ function useFrameCapture() {
       }
       const { width, height } = dimensionsRef.current;
       await api.seekTo(time);
-      await waitForVisualUpdate(2);
+      const renderedTime = api.getRenderedTime();
+      if (Math.abs(renderedTime - time) > RENDER_TIME_EPSILON_SECONDS) {
+        throw new Error(
+          `Player committed ${renderedTime.toFixed(6)}s while capture requested ${time.toFixed(6)}s.`
+        );
+      }
       const root = container.querySelector("#squisq-capture-root");
       if (!root) {
         throw new Error("Capture root element not found");
       }
+      await waitForCaptureAssets(root, decodedImagesRef.current);
       const visualStateKey = options.reuseIfUnchanged ? getFrameVisualStateKey(root, time) : null;
       if (visualStateKey !== null && hasCapturedFrameRef.current && lastVisualStateKeyRef.current === visualStateKey) {
         return captureCanvas;
@@ -286,6 +498,9 @@ function useFrameCapture() {
         allowTaint: true,
         backgroundColor: "#000000",
         logging: false,
+        onclone: (_clonedDocument, clonedRoot) => {
+          prepareScheduledVideoClones(root, clonedRoot);
+        },
         // html2canvas starts cloning at documentElement. Do not clone the rest
         // of the editor/site UI on every frame; only the capture root, its
         // ancestors, descendants, and document styles can affect this render.
@@ -322,11 +537,12 @@ function useFrameCapture() {
     }
     lastVisualStateKeyRef.current = null;
     hasCapturedFrameRef.current = false;
+    decodedImagesRef.current = /* @__PURE__ */ new WeakSet();
     renderAPIRef.current = null;
   }, []);
   return useMemo(
-    () => ({ init, captureFrame, captureCanvasFrame, destroy }),
-    [init, captureFrame, captureCanvasFrame, destroy]
+    () => ({ init, setCoverVisible, captureFrame, captureCanvasFrame, destroy }),
+    [init, setCoverVisible, captureFrame, captureCanvasFrame, destroy]
   );
 }
 
@@ -593,14 +809,22 @@ async function transcodeMp4ToGifWithFfmpegWasm(videoMp4, options, loadConfig, si
 
 // src/hooks/useVideoExport.ts
 var MAX_EXPORT_MEDIA_FILES = 256;
-var MAX_EXPORT_MEDIA_FILE_BYTES = 64 * 1024 * 1024;
-var MAX_EXPORT_MEDIA_TOTAL_BYTES = 256 * 1024 * 1024;
 var ENCODER_PROBE_TIMEOUT_MS = 5e3;
 var ENCODER_START_TIMEOUT_MS = 6e4;
 var FRAME_CAPTURE_TIMEOUT_MS = 6e4;
 var FRAME_ENCODE_TIMEOUT_MS = 6e4;
 var CAPTURE_PROGRESS_START = 7;
 var CAPTURE_PROGRESS_END = 95;
+var FRAME_RATE_WINDOW_SIZE = 30;
+var DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS = 2;
+function calculateRollingFramesPerSecond(frameBoundaryTimes) {
+  if (frameBoundaryTimes.length < 2) return null;
+  const firstIndex = Math.max(0, frameBoundaryTimes.length - (FRAME_RATE_WINDOW_SIZE + 1));
+  const elapsedMs = frameBoundaryTimes[frameBoundaryTimes.length - 1] - frameBoundaryTimes[firstIndex];
+  const completedFrames = frameBoundaryTimes.length - 1 - firstIndex;
+  if (elapsedMs <= 0 || completedFrames <= 0) return null;
+  return completedFrames * 1e3 / elapsedMs;
+}
 function releaseEncoderFrame(frame) {
   if ("close" in frame) frame.close();
 }
@@ -633,6 +857,14 @@ function settleWithin(operation, timeoutMs, timeoutMessage, onLateResult) {
 function toArrayBuffer(bytes) {
   return bytes.slice().buffer;
 }
+function resolveExportMediaResourcePolicy(declaredSize, policy) {
+  const knownSize = Number.isFinite(declaredSize) ? Math.max(0, declaredSize) : 0;
+  return {
+    ...DEFAULT_INTERACTIVE_RESOURCE_POLICY,
+    ...policy,
+    maxBytes: policy?.maxBytes ?? Math.max(DEFAULT_INTERACTIVE_RESOURCE_POLICY.maxBytes, knownSize)
+  };
+}
 function collectDocumentMediaReferences(doc) {
   const references = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new WeakSet();
@@ -672,10 +904,37 @@ async function resolveAudioBuffers(clips, sources) {
   }
   return out;
 }
-function useVideoExport() {
+function resolveFrontmatterBoolean(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "yes" || normalized === "on" || normalized === "show" || normalized === "visible") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "no" || normalized === "off" || normalized === "hide" || normalized === "hidden") {
+    return false;
+  }
+  return void 0;
+}
+function resolveVideoExportCover(doc, config = {}) {
+  const frontmatter = doc.frontmatter;
+  const frontmatterValue = frontmatter ? Object.prototype.hasOwnProperty.call(frontmatter, "squisq-cover-slide") ? frontmatter["squisq-cover-slide"] : frontmatter["cover-slide"] : void 0;
+  const showCoverSlide = config.showCoverSlide ?? resolveFrontmatterBoolean(frontmatterValue) ?? true;
+  const requestedPreRoll = config.coverPreRoll ?? DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS;
+  if (!Number.isFinite(requestedPreRoll) || requestedPreRoll < 0) {
+    throw new Error("Cover pre-roll must be a finite number of seconds greater than or equal to 0");
+  }
+  return {
+    showCoverSlide,
+    coverPreRoll: showCoverSlide && !!doc.startBlock ? requestedPreRoll : 0
+  };
+}
+function useVideoExport(options = {}) {
   const [state, setState] = useState("idle");
   const [progress, setProgress] = useState(0);
   const [phase, setPhase] = useState("");
+  const [currentFrameTime, setCurrentFrameTime] = useState(null);
+  const [processingFps, setProcessingFps] = useState(null);
   const [duration, setDuration] = useState(0);
   const [outputFormat, setOutputFormat] = useState("mp4");
   const [backend, setBackend] = useState(null);
@@ -692,6 +951,8 @@ function useVideoExport() {
   const downloadUrlRef = useRef2(null);
   const startTimeRef = useRef2(0);
   const elapsedTimerRef = useRef2(null);
+  const previewOptionsRef = useRef2(options);
+  previewOptionsRef.current = options;
   const frameCapture = useFrameCapture();
   useEffect(() => {
     return () => {
@@ -721,6 +982,8 @@ function useVideoExport() {
     setState("idle");
     setProgress(0);
     setPhase("");
+    setCurrentFrameTime(null);
+    setProcessingFps(null);
     setDuration(0);
     setOutputFormat("mp4");
     setBackend(null);
@@ -760,6 +1023,8 @@ function useVideoExport() {
       setAudioIncluded(false);
       setAudioSkippedReason(null);
       setError(null);
+      setCurrentFrameTime(null);
+      setProcessingFps(null);
       const quality = config.quality ?? "normal";
       const effectiveOutputFormat = config.outputFormat ?? "mp4";
       const fps = config.fps ?? (effectiveOutputFormat === "gif" ? 10 : 30);
@@ -769,6 +1034,7 @@ function useVideoExport() {
       const audioPolicy = config.audioPolicy ?? "require";
       setOutputFormat(effectiveOutputFormat);
       try {
+        const cover = resolveVideoExportCover(doc, config);
         const gifDefaults = orientation === "portrait" ? { width: 540, height: 960 } : { width: 960, height: 540 };
         const { width, height } = resolveDimensions({
           orientation,
@@ -815,42 +1081,42 @@ function useVideoExport() {
               `Document references ${neededEntries.length} media files; browser export supports at most ${MAX_EXPORT_MEDIA_FILES}.`
             );
           }
-          let totalMediaBytes = 0;
           for (const entry of neededEntries) {
             if (cancelledRef.current) return;
-            if (entry.size > MAX_EXPORT_MEDIA_FILE_BYTES) {
-              throw new Error(`Media file "${entry.name}" is too large for browser video export.`);
-            }
             const url2 = await config.mediaProvider.resolveUrl(entry.name);
             const resource = await fetchResourceBytes(url2, {
-              policy: {
-                ...DEFAULT_INTERACTIVE_RESOURCE_POLICY,
-                ...config.resourcePolicy,
-                maxBytes: Math.min(
-                  config.resourcePolicy?.maxBytes ?? MAX_EXPORT_MEDIA_FILE_BYTES,
-                  MAX_EXPORT_MEDIA_FILE_BYTES
-                )
-              }
+              policy: resolveExportMediaResourcePolicy(entry.size, config.resourcePolicy)
             });
             const data = toArrayBuffer(resource.bytes);
-            totalMediaBytes += data.byteLength;
-            if (totalMediaBytes > MAX_EXPORT_MEDIA_TOTAL_BYTES) {
-              throw new Error("Referenced media exceeds the browser video export memory limit.");
-            }
             images.set(entry.name, data);
           }
         }
         const docDuration = await frameCapture.init(
           doc,
-          { images, audio: config.audio, width, height, animationsEnabled },
+          {
+            images,
+            audio: config.audio,
+            width,
+            height,
+            animationsEnabled,
+            theme: config.theme,
+            videoPresentation: config.videoPresentation,
+            pipSize: config.pipSize,
+            pipShape: config.pipShape,
+            pipPosition: config.pipPosition,
+            showCoverSlide: cover.showCoverSlide
+          },
           captionMode
         );
         if (cancelledRef.current) return;
-        setDuration(docDuration);
         if (docDuration <= 0) {
           throw new Error("Document has zero duration \u2014 nothing to export");
         }
-        const totalFrames = Math.ceil(docDuration * fps);
+        const coverFrameCount = Math.ceil(cover.coverPreRoll * fps);
+        const storyFrameCount = Math.ceil(docDuration * fps);
+        const totalFrames = coverFrameCount + storyFrameCount;
+        const exportDuration = totalFrames / fps;
+        setDuration(exportDuration);
         setPhase("Checking video encoder\u2026");
         setProgress(5);
         const canUseWebCodecs = webCodecsAvailable && await settleWithin(
@@ -859,7 +1125,7 @@ function useVideoExport() {
           "The browser did not finish checking WebCodecs support."
         ).catch(() => false);
         const audioBitrate = (QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal).audioBitrate;
-        const timeline = effectiveOutputFormat === "mp4" && audioPolicy !== "omit" ? computeAudioTimeline(doc, 0) : [];
+        const timeline = effectiveOutputFormat === "mp4" && audioPolicy !== "omit" ? computeAudioTimeline(doc, coverFrameCount / fps) : [];
         const aacSupported = timeline.length > 0 ? await supportsWebCodecsAac(EXPORT_AUDIO_SAMPLE_RATE, EXPORT_AUDIO_CHANNELS) : false;
         const tierDecision = selectAudioTier({
           hasClips: timeline.length > 0,
@@ -894,7 +1160,7 @@ function useVideoExport() {
             } else {
               const totalAudioDur = timeline.reduce(
                 (max, c) => Math.max(max, c.startSec + c.durationSec),
-                docDuration
+                exportDuration
               );
               renderedAudio = await renderAudioTimeline(
                 timeline,
@@ -954,13 +1220,20 @@ function useVideoExport() {
         }
         if (cancelledRef.current) return;
         setProgress(CAPTURE_PROGRESS_START);
-        setPhase(`Capturing frame 1/${totalFrames} (0.0s)`);
+        setPhase(`Capturing frame 1/${totalFrames}`);
+        setCurrentFrameTime(0);
         setState("capturing");
         const captureStartTime = performance.now();
+        const frameBoundaryTimes = [captureStartTime];
+        if (coverFrameCount > 0) await frameCapture.setCoverVisible(true);
         for (let i = 0; i < totalFrames; i++) {
           if (cancelledRef.current) return;
+          if (coverFrameCount > 0 && i === coverFrameCount) {
+            await frameCapture.setCoverVisible(false);
+          }
           const time = i / fps;
-          const captureOperation = canUseWebCodecs ? frameCapture.captureCanvasFrame(time, { reuseIfUnchanged: true }) : frameCapture.captureFrame(time, { reuseIfUnchanged: true });
+          const captureTime = i < coverFrameCount ? 0 : (i - coverFrameCount) / fps;
+          const captureOperation = canUseWebCodecs ? frameCapture.captureCanvasFrame(captureTime, { reuseIfUnchanged: true }) : frameCapture.captureFrame(captureTime, { reuseIfUnchanged: true });
           const frame = await settleWithin(
             captureOperation,
             FRAME_CAPTURE_TIMEOUT_MS,
@@ -971,15 +1244,31 @@ function useVideoExport() {
             releaseEncoderFrame(frame);
             return;
           }
-          setPhase(`Encoding frame ${i + 1}/${totalFrames} (${time.toFixed(1)}s)`);
+          const previewOptions = previewOptionsRef.current;
+          const previewInterval = Math.max(1, Math.floor(previewOptions.previewEveryNFrames ?? 1));
+          if (previewOptions.onFramePreview && (i === 0 || i === totalFrames - 1 || i % previewInterval === 0)) {
+            try {
+              previewOptions.onFramePreview({ source: frame, frameIndex: i, totalFrames, time });
+            } catch {
+            }
+          }
+          setPhase(`Encoding frame ${i + 1}/${totalFrames}`);
+          setCurrentFrameTime(time);
           await settleWithin(
             encoder.encodeFrame(frame, i),
             FRAME_ENCODE_TIMEOUT_MS,
             `Video encoding stopped responding at frame ${i + 1}/${totalFrames}.`
           );
           const completedFrames = i + 1;
+          const completedAt = performance.now();
+          frameBoundaryTimes.push(completedAt);
+          if (frameBoundaryTimes.length > FRAME_RATE_WINDOW_SIZE + 1) {
+            frameBoundaryTimes.shift();
+          }
+          setProcessingFps(calculateRollingFramesPerSecond(frameBoundaryTimes));
+          setCurrentFrameTime(Math.min(completedFrames / fps, exportDuration));
           setPhase(
-            completedFrames < totalFrames ? `Capturing frame ${completedFrames + 1}/${totalFrames} (${(completedFrames / fps).toFixed(1)}s)` : `Captured ${totalFrames.toLocaleString()} frames\u2026`
+            completedFrames < totalFrames ? `Capturing frame ${completedFrames + 1}/${totalFrames}` : `Captured ${totalFrames.toLocaleString()} frames\u2026`
           );
           const captureRatio = completedFrames / totalFrames;
           const captureProgress = CAPTURE_PROGRESS_START + captureRatio * (CAPTURE_PROGRESS_END - CAPTURE_PROGRESS_START);
@@ -1085,6 +1374,8 @@ function useVideoExport() {
     state,
     progress,
     phase,
+    currentFrameTime,
+    processingFps,
     duration,
     outputFormat,
     backend,
@@ -1103,5 +1394,7 @@ function useVideoExport() {
 
 export {
   useFrameCapture,
+  DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS,
+  resolveVideoExportCover,
   useVideoExport
 };

package/dist/{chunk-ULNKIV4A.js → chunk-U2TST3MN.js}

@@ -1,6 +1,6 @@
 import {
   useVideoExport
-} from "./chunk-IDY64F4K.js";
+} from "./chunk-NZYFSB2T.js";
 
 // src/VideoExportModal.tsx
 import { useState, useCallback, useId, useRef } from "react";
@@ -12,6 +12,31 @@ function formatDuration(seconds) {
   const s = seconds % 60;
   return `${m}m ${s}s`;
 }
+function formatProcessingFps(framesPerSecond) {
+  return `${framesPerSecond.toFixed(2)} fps`;
+}
+function formatRealtimeMultiplier(processingFps, outputFps) {
+  return `${(processingFps / outputFps).toFixed(2)}\xD7 realtime`;
+}
+var FRAME_PREVIEW_INTERVAL = 15;
+var FRAME_PREVIEW_WIDTH = 480;
+var FRAME_PREVIEW_HEIGHT = 270;
+function drawVideoExportPreview(canvas, source) {
+  const context = canvas.getContext("2d");
+  if (!context || source.width <= 0 || source.height <= 0) return;
+  context.fillStyle = "#000000";
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  const scale = Math.min(canvas.width / source.width, canvas.height / source.height);
+  const width = source.width * scale;
+  const height = source.height * scale;
+  context.drawImage(
+    source,
+    (canvas.width - width) / 2,
+    (canvas.height - height) / 2,
+    width,
+    height
+  );
+}
 var VIDEO_EXPORT_PALETTES = {
   light: {
     overlay: "rgba(0, 0, 0, 0.5)",
@@ -139,6 +164,7 @@ function VideoExportModal({
 }) {
   const overlayRef = useRef(null);
   const dialogRef = useRef(null);
+  const previewCanvasRef = useRef(null);
   const titleId = useId();
   const initialOutputFormat = defaultConfig?.outputFormat ?? "mp4";
   const [outputFormat, setOutputFormat] = useState(initialOutputFormat);
@@ -188,11 +214,20 @@ function VideoExportModal({
     color: palette.text,
     border: `1px solid ${palette.border}`
   };
-  const exportHook = useVideoExport();
+  const handleFramePreview = useCallback((preview) => {
+    const canvas = previewCanvasRef.current;
+    if (canvas) drawVideoExportPreview(canvas, preview.source);
+  }, []);
+  const exportHook = useVideoExport({
+    onFramePreview: handleFramePreview,
+    previewEveryNFrames: FRAME_PREVIEW_INTERVAL
+  });
   const {
     state,
     progress,
     phase,
+    currentFrameTime,
+    processingFps,
     outputFormat: completedOutputFormat,
     downloadUrl,
     fileSize,
@@ -218,6 +253,12 @@ function VideoExportModal({
     }
   }, []);
   const handleExport = useCallback(async () => {
+    const previewCanvas = previewCanvasRef.current;
+    const previewContext = previewCanvas?.getContext("2d");
+    if (previewCanvas && previewContext) {
+      previewContext.fillStyle = "#000000";
+      previewContext.fillRect(0, 0, previewCanvas.width, previewCanvas.height);
+    }
     const config = {
       // defaultConfig is the base; explicit props/selections win over it.
       ...defaultConfig,
@@ -439,6 +480,27 @@ function VideoExportModal({
               ] })
             ] }),
             isExporting && /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(
+                "canvas",
+                {
+                  ref: previewCanvasRef,
+                  width: FRAME_PREVIEW_WIDTH,
+                  height: FRAME_PREVIEW_HEIGHT,
+                  role: "img",
+                  "aria-label": "Latest rendered video frame",
+                  "data-squisq-video-export-preview": true,
+                  style: {
+                    display: "block",
+                    width: "100%",
+                    height: "auto",
+                    aspectRatio: "16 / 9",
+                    boxSizing: "border-box",
+                    background: "#000000",
+                    border: `1px solid ${palette.border}`,
+                    marginBottom: 12
+                  }
+                }
+              ),
               /* @__PURE__ */ jsx(
                 "div",
                 {
@@ -463,16 +525,40 @@ function VideoExportModal({
                   )
                 }
               ),
-              /* @__PURE__ */ jsxs("p", { style: { fontSize: 13, margin: "0 0 4px 0" }, children: [
-                progress,
-                "% complete"
-              ] }),
-              phase && /* @__PURE__ */ jsx(
+              /* @__PURE__ */ jsxs(
                 "p",
                 {
-                  style: { fontSize: 12, color: palette.label, margin: "0 0 4px 0" },
+                  style: { fontSize: 13, fontVariantNumeric: "tabular-nums", margin: "0 0 4px 0" },
+                  "data-squisq-video-export-progress-label": true,
+                  children: [
+                    progress.toFixed(1),
+                    "% complete",
+                    currentFrameTime != null && `, @ ${currentFrameTime.toFixed(1)} seconds`
+                  ]
+                }
+              ),
+              phase && /* @__PURE__ */ jsxs(
+                "p",
+                {
+                  style: {
+                    fontSize: 12,
+                    fontVariantNumeric: "tabular-nums",
+                    color: palette.label,
+                    margin: "0 0 4px 0"
+                  },
                   "data-squisq-video-export-phase": true,
-                  children: phase
+                  children: [
+                    phase,
+                    processingFps != null && /* @__PURE__ */ jsxs(Fragment, { children: [
+                      " - ",
+                      /* @__PURE__ */ jsxs("span", { "data-squisq-video-export-frame-metrics": true, children: [
+                        formatProcessingFps(processingFps),
+                        " \xB7",
+                        " ",
+                        formatRealtimeMultiplier(processingFps, fps)
+                      ] })
+                    ] })
+                  ]
                 }
               ),
               /* @__PURE__ */ jsxs("p", { style: { fontSize: 12, color: palette.muted, margin: 0 }, children: [

package/dist/components/index.d.ts

@@ -1,9 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Doc, MediaProvider } from '@bendyline/squisq/schemas';
-import { a as VideoExportConfig } from '../useVideoExport-DAEglCva.js';
+import { a as VideoExportConfig } from '../useVideoExport-Okwrf8gg.js';
 import '@bendyline/squisq/markdown';
 import '@bendyline/squisq-video';
 import '@bendyline/squisq-react';
+import '../mainThreadEncoder-BgcFyYvO.js';
 
 interface VideoExportModalProps {
     /** The document to export */

package/dist/components/index.js

@@ -1,8 +1,8 @@
 import {
   VideoExportButton,
   VideoExportModal
-} from "../chunk-ULNKIV4A.js";
-import "../chunk-IDY64F4K.js";
+} from "../chunk-U2TST3MN.js";
+import "../chunk-NZYFSB2T.js";
 import "../chunk-ZQJBUX75.js";
 import "../chunk-MEPETH5V.js";
 export {

package/dist/encoder/index.d.ts

@@ -1,72 +1,6 @@
+export { E as EncoderConfig, a as EncoderFrameSource, M as MainThreadEncoder, c as createEncoder, s as supportsWebCodecs, b as supportsWebCodecsH264 } from '../mainThreadEncoder-BgcFyYvO.js';
 export { FfmpegWasmLoadConfig } from '@bendyline/squisq-video';
 
-/**
- * Main-thread WebCodecs encoder.
- *
- * Encodes video frames to MP4 using the WebCodecs API and mp4-muxer,
- * running directly on the main thread. This is simpler and avoids
- * worker module-resolution issues with bundlers. Since frame capture
- * via html2canvas (~100-200ms per frame) is the bottleneck — not
- * encoding (~1ms per frame with hardware-accelerated WebCodecs) —
- * worker offloading provides minimal benefit.
- *
- * Requirements: Chrome 94+ / Edge 94+ (WebCodecs support).
- */
-interface EncoderConfig {
-    width: number;
-    height: number;
-    fps: number;
-    quality: 'draft' | 'normal' | 'high';
-    /**
-     * Total frames the caller intends to submit, when known. Unused by the
-     * main-thread encoder (the caller owns the progress bar) but forwarded by
-     * {@link createWorkerEncoder} so the worker can report real progress instead
-     * of guessing from the frames it happens to have seen.
-     */
-    totalFrames?: number;
-    /**
-     * When present, the underlying muxer is configured with an AAC audio track
-     * and {@link MainThreadEncoder.addAudioChunk} becomes usable. Absent → the
-     * encoder produces a video-only MP4 exactly as before.
-     */
-    audio?: {
-        numberOfChannels: number;
-        sampleRate: number;
-    };
-}
-type EncoderFrameSource = ImageBitmap | HTMLCanvasElement;
-interface MainThreadEncoder {
-    /** Encode a single frame. ImageBitmap sources are closed after encoding. */
-    encodeFrame(frame: EncoderFrameSource, frameIndex: number): Promise<void>;
-    /**
-     * Hand an encoded audio chunk (from a WebCodecs `AudioEncoder`) to the muxer.
-     * Only valid when the encoder was created with an `audio` config; otherwise a
-     * no-op. Must be called before {@link finalize}.
-     */
-    addAudioChunk?(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;
-    /** Flush pending frames and finalize the MP4. Returns the MP4 ArrayBuffer. */
-    finalize(): Promise<ArrayBuffer>;
-    /** Close the encoder without producing output (e.g., on cancel). */
-    close(): void;
-}
-/**
- * Check whether the browser supports WebCodecs video encoding.
- */
-declare function supportsWebCodecs(): boolean;
-/**
- * Probe whether the WebCodecs encoder actually supports the H.264 profile
- * we use. The `VideoEncoder` global can exist while the specific codec is
- * unavailable — this is the case on Linux Chromium, which ships without
- * the proprietary H.264 encoder.
- */
-declare function supportsWebCodecsH264(config: EncoderConfig): Promise<boolean>;
-/**
- * Create a main-thread WebCodecs encoder.
- *
- * Throws if WebCodecs is not available.
- */
-declare function createEncoder(config: EncoderConfig): MainThreadEncoder;
-
 /**
  * audioTrack — In-browser audio rendering + AAC encoding for MP4 export.
  *
@@ -93,4 +27,4 @@ declare function createEncoder(config: EncoderConfig): MainThreadEncoder;
  */
 declare function supportsWebCodecsAac(sampleRate?: number, channels?: number): Promise<boolean>;
 
-export { type EncoderConfig, type EncoderFrameSource, type MainThreadEncoder, createEncoder, supportsWebCodecs, supportsWebCodecsAac, supportsWebCodecsH264 };
+export { supportsWebCodecsAac };

package/dist/hooks/index.d.ts

@@ -1,8 +1,9 @@
-export { V as VideoAudioPolicy, a as VideoExportConfig, b as VideoExportResult, c as VideoExportState, d as VideoOutputFormat, u as useVideoExport } from '../useVideoExport-DAEglCva.js';
+export { D as DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS, R as ResolvedVideoExportCover, U as UseVideoExportOptions, V as VideoAudioPolicy, a as VideoExportConfig, b as VideoExportFramePreview, c as VideoExportResult, d as VideoExportState, e as VideoOutputFormat, r as resolveVideoExportCover, u as useVideoExport } from '../useVideoExport-Okwrf8gg.js';
 import { Doc } from '@bendyline/squisq/schemas';
 import { RenderHtmlOptions } from '@bendyline/squisq-video';
 import { CaptionMode } from '@bendyline/squisq-react';
 import '@bendyline/squisq/markdown';
+import '../mainThreadEncoder-BgcFyYvO.js';
 
 /**
  * useFrameCapture — Hidden div + html2canvas frame capture.
@@ -24,9 +25,15 @@ interface FrameCaptureOptions {
      */
     reuseIfUnchanged?: boolean;
 }
+interface FrameCaptureRenderOptions extends Omit<RenderHtmlOptions, 'playerScript'> {
+    /** Whether the hidden player should materialize its managed cover. */
+    showCoverSlide?: boolean;
+}
 interface FrameCaptureHandle {
     /** Initialize the hidden player. Returns the video duration in seconds. */
-    init: (doc: Doc, renderOptions: Omit<RenderHtmlOptions, 'playerScript'>, captionMode?: CaptionMode) => Promise<number>;
+    init: (doc: Doc, renderOptions: FrameCaptureRenderOptions, captionMode?: CaptionMode) => Promise<number>;
+    /** Force the managed cover on or off before capturing export frames. */
+    setCoverVisible: (visible: boolean) => Promise<void>;
     /** Capture a single frame at the given time (seconds). Returns an ImageBitmap. */
     captureFrame: (time: number, options?: FrameCaptureOptions) => Promise<ImageBitmap>;
     /**
@@ -42,4 +49,4 @@ interface FrameCaptureHandle {
  */
 declare function useFrameCapture(): FrameCaptureHandle;
 
-export { type FrameCaptureHandle, type FrameCaptureOptions, useFrameCapture };
+export { type FrameCaptureHandle, type FrameCaptureOptions, type FrameCaptureRenderOptions, useFrameCapture };

package/dist/hooks/index.js

@@ -1,10 +1,14 @@
 import {
+  DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS,
+  resolveVideoExportCover,
   useFrameCapture,
   useVideoExport
-} from "../chunk-IDY64F4K.js";
+} from "../chunk-NZYFSB2T.js";
 import "../chunk-ZQJBUX75.js";
 import "../chunk-MEPETH5V.js";
 export {
+  DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS,
+  resolveVideoExportCover,
   useFrameCapture,
   useVideoExport
 };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { VideoExportButton, VideoExportButtonProps, VideoExportModal, VideoExportModalProps, VideoExportPalette } from './components/index.js';
-export { V as VideoAudioPolicy, a as VideoExportConfig, b as VideoExportResult, c as VideoExportState, d as VideoOutputFormat, u as useVideoExport } from './useVideoExport-DAEglCva.js';
-export { FrameCaptureHandle, FrameCaptureOptions, useFrameCapture } from './hooks/index.js';
-export { EncoderConfig, EncoderFrameSource, MainThreadEncoder, createEncoder, supportsWebCodecs, supportsWebCodecsAac, supportsWebCodecsH264 } from './encoder/index.js';
+export { D as DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS, R as ResolvedVideoExportCover, U as UseVideoExportOptions, V as VideoAudioPolicy, a as VideoExportConfig, b as VideoExportFramePreview, c as VideoExportResult, d as VideoExportState, e as VideoOutputFormat, r as resolveVideoExportCover, u as useVideoExport } from './useVideoExport-Okwrf8gg.js';
+export { FrameCaptureHandle, FrameCaptureOptions, FrameCaptureRenderOptions, useFrameCapture } from './hooks/index.js';
+export { E as EncoderConfig, a as EncoderFrameSource, M as MainThreadEncoder, c as createEncoder, s as supportsWebCodecs, b as supportsWebCodecsH264 } from './mainThreadEncoder-BgcFyYvO.js';
 export { FfmpegWasmLoadConfig } from '@bendyline/squisq-video';
+export { supportsWebCodecsAac } from './encoder/index.js';
 import 'react/jsx-runtime';
 import '@bendyline/squisq/schemas';
 import '@bendyline/squisq/markdown';

package/dist/index.js

@@ -1,11 +1,13 @@
 import {
   VideoExportButton,
   VideoExportModal
-} from "./chunk-ULNKIV4A.js";
+} from "./chunk-U2TST3MN.js";
 import {
+  DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS,
+  resolveVideoExportCover,
   useFrameCapture,
   useVideoExport
-} from "./chunk-IDY64F4K.js";
+} from "./chunk-NZYFSB2T.js";
 import {
   createEncoder,
   supportsWebCodecs,
@@ -14,9 +16,11 @@ import {
 } from "./chunk-ZQJBUX75.js";
 import "./chunk-MEPETH5V.js";
 export {
+  DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS,
   VideoExportButton,
   VideoExportModal,
   createEncoder,
+  resolveVideoExportCover,
   supportsWebCodecs,
   supportsWebCodecsAac,
   supportsWebCodecsH264,

package/dist/mainThreadEncoder-BgcFyYvO.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Main-thread WebCodecs encoder.
+ *
+ * Encodes video frames to MP4 using the WebCodecs API and mp4-muxer,
+ * running directly on the main thread. This is simpler and avoids
+ * worker module-resolution issues with bundlers. Since frame capture
+ * via html2canvas (~100-200ms per frame) is the bottleneck — not
+ * encoding (~1ms per frame with hardware-accelerated WebCodecs) —
+ * worker offloading provides minimal benefit.
+ *
+ * Requirements: Chrome 94+ / Edge 94+ (WebCodecs support).
+ */
+interface EncoderConfig {
+    width: number;
+    height: number;
+    fps: number;
+    quality: 'draft' | 'normal' | 'high';
+    /**
+     * Total frames the caller intends to submit, when known. Unused by the
+     * main-thread encoder (the caller owns the progress bar) but forwarded by
+     * {@link createWorkerEncoder} so the worker can report real progress instead
+     * of guessing from the frames it happens to have seen.
+     */
+    totalFrames?: number;
+    /**
+     * When present, the underlying muxer is configured with an AAC audio track
+     * and {@link MainThreadEncoder.addAudioChunk} becomes usable. Absent → the
+     * encoder produces a video-only MP4 exactly as before.
+     */
+    audio?: {
+        numberOfChannels: number;
+        sampleRate: number;
+    };
+}
+type EncoderFrameSource = ImageBitmap | HTMLCanvasElement;
+interface MainThreadEncoder {
+    /** Encode a single frame. ImageBitmap sources are closed after encoding. */
+    encodeFrame(frame: EncoderFrameSource, frameIndex: number): Promise<void>;
+    /**
+     * Hand an encoded audio chunk (from a WebCodecs `AudioEncoder`) to the muxer.
+     * Only valid when the encoder was created with an `audio` config; otherwise a
+     * no-op. Must be called before {@link finalize}.
+     */
+    addAudioChunk?(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;
+    /** Flush pending frames and finalize the MP4. Returns the MP4 ArrayBuffer. */
+    finalize(): Promise<ArrayBuffer>;
+    /** Close the encoder without producing output (e.g., on cancel). */
+    close(): void;
+}
+/**
+ * Check whether the browser supports WebCodecs video encoding.
+ */
+declare function supportsWebCodecs(): boolean;
+/**
+ * Probe whether the WebCodecs encoder actually supports the H.264 profile
+ * we use. The `VideoEncoder` global can exist while the specific codec is
+ * unavailable — this is the case on Linux Chromium, which ships without
+ * the proprietary H.264 encoder.
+ */
+declare function supportsWebCodecsH264(config: EncoderConfig): Promise<boolean>;
+/**
+ * Create a main-thread WebCodecs encoder.
+ *
+ * Throws if WebCodecs is not available.
+ */
+declare function createEncoder(config: EncoderConfig): MainThreadEncoder;
+
+export { type EncoderConfig as E, type MainThreadEncoder as M, type EncoderFrameSource as a, supportsWebCodecsH264 as b, createEncoder as c, supportsWebCodecs as s };

package/dist/{useVideoExport-DAEglCva.d.ts → useVideoExport-Okwrf8gg.d.ts}

@@ -1,7 +1,8 @@
-import { MediaProvider, Doc } from '@bendyline/squisq/schemas';
+import { MediaProvider, Theme, VideoPresentation, VideoPipSize, VideoPipShape, VideoPipPosition, 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';
+import { a as EncoderFrameSource } from './mainThreadEncoder-BgcFyYvO.js';
 
 /**
  * useVideoExport — Main orchestration hook for browser video export.
@@ -20,6 +21,7 @@ import { CaptionMode } from '@bendyline/squisq-react';
  *   <button onClick={() => startExport(doc, options)}>Export</button>
  */
 
+declare const DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS = 2;
 type VideoExportState = 'idle' | 'preparing' | 'capturing' | 'encoding' | 'complete' | 'error';
 /** Browser export container format. */
 type VideoOutputFormat = 'mp4' | 'gif';
@@ -62,11 +64,31 @@ interface VideoExportConfig {
     resourcePolicy?: ResourcePolicy;
     /** Caption mode for the exported video (default: 'off' for MP4, 'standard' for GIF). */
     captionMode?: CaptionMode;
+    /** Theme override for capture. Omitted values resolve from the Doc. */
+    theme?: Theme;
+    /** Player-level video placement override. Omitted values resolve from Doc frontmatter. */
+    videoPresentation?: VideoPresentation;
+    /** Picture-in-picture size override. Omitted values resolve from Doc frontmatter. */
+    pipSize?: VideoPipSize;
+    /** Picture-in-picture shape override. Omitted values resolve from Doc frontmatter. */
+    pipShape?: VideoPipShape;
+    /** Picture-in-picture corner override. Omitted values resolve from Doc frontmatter. */
+    pipPosition?: VideoPipPosition;
+    /** Managed-cover visibility override. Omitted values resolve from Doc frontmatter. */
+    showCoverSlide?: boolean;
+    /** Seconds to hold an enabled managed cover before story frame zero (default: 2). */
+    coverPreRoll?: number;
     /** 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 ResolvedVideoExportCover {
+    showCoverSlide: boolean;
+    coverPreRoll: number;
+}
+/** Resolve the cover segment shared by browser MP4/GIF capture. */
+declare function resolveVideoExportCover(doc: Doc, config?: Pick<VideoExportConfig, 'showCoverSlide' | 'coverPreRoll'>): ResolvedVideoExportCover;
 interface VideoExportResult {
     /** Current export state */
     state: VideoExportState;
@@ -74,6 +96,10 @@ interface VideoExportResult {
     progress: number;
     /** Human-readable description of the current phase */
     phase: string;
+    /** Current timestamp being captured from the output timeline (seconds). */
+    currentFrameTime: number | null;
+    /** Rolling throughput over at most the last 30 completed frames. */
+    processingFps: number | null;
     /** Video duration detected from the doc (seconds) */
     duration: number;
     /** Effective output format for the current or most recent export. */
@@ -110,6 +136,26 @@ interface VideoExportResult {
     /** Reset state back to idle (e.g., after complete or error) */
     reset: () => void;
 }
-declare function useVideoExport(): VideoExportResult;
+interface VideoExportFramePreview {
+    /** The raster that is about to be submitted to the encoder. Valid only during the callback. */
+    source: EncoderFrameSource;
+    /** Zero-based frame index. */
+    frameIndex: number;
+    /** Total number of frames in the export. */
+    totalFrames: number;
+    /** Timestamp on the output timeline, in seconds. */
+    time: number;
+}
+interface UseVideoExportOptions {
+    /**
+     * Observe an occasional captured frame without performing another rasterization.
+     * The source may be reused or closed as soon as this synchronous callback returns.
+     * Observer errors are ignored so display-only work cannot fail an export.
+     */
+    onFramePreview?: (preview: VideoExportFramePreview) => void;
+    /** Preview the first, last, and every Nth frame. Defaults to 1. */
+    previewEveryNFrames?: number;
+}
+declare function useVideoExport(options?: UseVideoExportOptions): 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 };
+export { DEFAULT_VIDEO_COVER_PRE_ROLL_SECONDS as D, type ResolvedVideoExportCover as R, type UseVideoExportOptions as U, type VideoAudioPolicy as V, type VideoExportConfig as a, type VideoExportFramePreview as b, type VideoExportResult as c, type VideoExportState as d, type VideoOutputFormat as e, resolveVideoExportCover as r, useVideoExport as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-video-react",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "React components for browser-based MP4 and animated-GIF export of Squisq documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -24,7 +24,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22.14.0"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -65,9 +65,9 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.3.3",
-    "@bendyline/squisq-video": "2.2.3",
-    "@bendyline/squisq-react": "2.3.3",
+    "@bendyline/squisq": "2.4.1",
+    "@bendyline/squisq-video": "2.2.5",
+    "@bendyline/squisq-react": "2.4.1",
     "@ffmpeg/core": "0.12.9",
     "@ffmpeg/ffmpeg": "0.12.15",
     "@ffmpeg/util": "0.12.2",