@bendyline/squisq-video-react 1.2.2 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @bendyline/squisq-video-react
 
-React components and hooks for exporting Squisq documents to MP4 video directly in the browser. Uses WebCodecs for hardware-accelerated H.264 encoding (with an ffmpeg.wasm worker fallback) and html2canvas for frame capture. As of v1.5 the exported MP4 also carries an **audio** track (narration + timed media).
+React components and hooks for exporting Squisq documents to MP4 video or animated GIF directly in the browser. MP4 uses WebCodecs for hardware-accelerated H.264 encoding (with an ffmpeg.wasm worker fallback); GIF uses that compact video as an intermediate for an ffmpeg.wasm global-palette pass. html2canvas provides deterministic frame capture. MP4 carries an **audio** track (narration + timed media); GIF is silent by design.
 
 Part of the [Squisq](https://github.com/bendyline/squisq) monorepo.
 
@@ -27,10 +27,18 @@ function App() {
 }
 ```
 
+To open directly in the compact GIF preset:
+
+```tsx
+<VideoExportButton doc={myDoc} defaultConfig={{ outputFormat: 'gif' }} />
+```
+
 **v1.5:** `playerScript` is now **optional** — the browser export captures frames
 from a live in-page `DocPlayer`, so the standalone bundle is only needed for
 CLI/Playwright-style pipelines. A new `defaultConfig?: Partial<VideoExportConfig>`
 prop seeds the modal's initial quality/fps/orientation/caption selections.
+Both components also accept `colorScheme="light" | "dark"` so their portaled
+modal can match the host application; the default remains `light`.
 
 ### Full Export Modal
 
@@ -58,10 +66,10 @@ function App() {
 
 ## Components
 
-| Component           | Description                                                             |
-| ------------------- | ----------------------------------------------------------------------- |
-| `VideoExportModal`  | Full modal UI — configure quality/fps/orientation, export, and download |
-| `VideoExportButton` | Drop-in button that opens the export modal via portal                   |
+| Component           | Description                                                              |
+| ------------------- | ------------------------------------------------------------------------ |
+| `VideoExportModal`  | Full modal UI — configure MP4/GIF, motion, quality, fps, and orientation |
+| `VideoExportButton` | Drop-in button that opens the export modal via portal                    |
 
 ## Hooks
 
@@ -74,10 +82,12 @@ function App() {
 
 The `VideoExportModal` lets users configure:
 
+- **Format:** MP4 video or animated GIF
 - **Quality:** draft, normal, or high
-- **FPS:** 15, 24, or 30
-- **Orientation:** landscape (1920x1080) or portrait (1080x1920)
+- **FPS:** 10, 15, 24, or 30
+- **Orientation:** MP4 defaults to 1920x1080/1080x1920; GIF defaults to 960x540/540x960
 - **Captions:** off, standard, or social
+- **Animations & transitions:** enabled by default for MP4 and disabled by default for GIF
 
 ## Using the Hook Directly
 
@@ -90,6 +100,7 @@ function CustomExport({ doc, images, audio }) {
   const {
     state, // 'idle' | 'preparing' | 'capturing' | 'encoding' | 'complete' | 'error'
     progress, // 0–100
+    outputFormat, // 'mp4' | 'gif'
     backend, // 'webcodecs' | 'ffmpeg-wasm' | null
     elapsed,
     estimatedRemaining,
@@ -105,12 +116,20 @@ function CustomExport({ doc, images, audio }) {
 
   return (
     <div>
-      <button onClick={() => startExport(doc, { images, audio, quality: 'normal', fps: 30 })}>
-        Export
+      <button
+        onClick={() =>
+          startExport(doc, {
+            outputFormat: 'gif',
+            images,
+            animationsEnabled: false,
+          })
+        }
+      >
+        Export GIF
       </button>
       {state === 'capturing' && <p>Progress: {progress}%</p>}
       {downloadUrl && (
-        <a href={downloadUrl} download="video.mp4">
+        <a href={downloadUrl} download={`document.${outputFormat}`}>
           Download
         </a>
       )}
@@ -124,7 +143,25 @@ function CustomExport({ doc, images, audio }) {
 WebCodecs H.264 encoding requires Chrome 94+ or Edge 94+. When WebCodecs H.264
 is unavailable, the export automatically falls back to an ffmpeg.wasm worker —
 which requires `SharedArrayBuffer` (i.e. Cross-Origin-Isolation headers on the
-host page). Use `supportsWebCodecs()` to probe at runtime:
+host page). Animated GIF always performs an ffmpeg.wasm palette pass and therefore
+also requires `SharedArrayBuffer`. The packaged class worker is bundler-safe.
+
+`@ffmpeg/core` is pinned as a runtime dependency. Hosts should publish its ESM
+`ffmpeg-core.js` and `ffmpeg-core.wasm` files from the same origin and pass their
+URLs, especially for offline or Content-Security-Policy-controlled deployments:
+
+```ts
+const config = {
+  ffmpegWasm: {
+    // Copy from node_modules/@ffmpeg/core/dist/esm/ during your build.
+    coreURL: '/ffmpeg-core/ffmpeg-core.js',
+    wasmURL: '/ffmpeg-core/ffmpeg-core.wasm',
+    workerURL: '/vendor/ffmpeg-core.worker.js', // for a multithread core
+  },
+};
+```
+
+Use `supportsWebCodecs()` to probe at runtime:
 
 ```ts
 import {
@@ -138,11 +175,12 @@ if (!supportsWebCodecs()) {
 }
 ```
 
-**Audio tiers.** The audio track is muxed via WebCodecs AAC when available
-(`supportsWebCodecsAac()`); otherwise it is skipped and the export reports
-`audioIncluded: false` with an `audioSkippedReason`. Audio problems never fail
-the export — the video always completes. `supportsWebCodecsH264(config)` probes a
-specific encoder configuration; `EncoderConfig` is also exported.
+**Audio tiers.** MP4 audio is muxed via WebCodecs AAC when available
+(`supportsWebCodecsAac()`), then via ffmpeg.wasm when cross-origin isolation is
+available, and otherwise skipped with `audioIncluded: false` plus an
+`audioSkippedReason`. Audio problems never fail the export — the video always
+completes. GIF skips audio preparation entirely. `supportsWebCodecsH264(config)` probes a specific encoder
+configuration; `EncoderConfig` and `FfmpegWasmLoadConfig` are also exported.
 
 ## Full API Reference
 
@@ -151,13 +189,16 @@ for complete prop tables, `VideoExportConfig`, and the encoder utilities.
 
 ## Related Packages
 
-| Package                                                                          | Description                                     |
-| -------------------------------------------------------------------------------- | ----------------------------------------------- |
-| [@bendyline/squisq-video](https://www.npmjs.com/package/@bendyline/squisq-video) | Headless video rendering and WASM encoding      |
-| [@bendyline/squisq](https://www.npmjs.com/package/@bendyline/squisq)             | Headless core — schemas, templates, markdown    |
-| [@bendyline/squisq-react](https://www.npmjs.com/package/@bendyline/squisq-react) | React components for rendering docs             |
-| [@bendyline/squisq-cli](https://www.npmjs.com/package/@bendyline/squisq-cli)     | CLI for document conversion and video rendering |
+| Package                                                                          | Description                                       |
+| -------------------------------------------------------------------------------- | ------------------------------------------------- |
+| [@bendyline/squisq-video](https://www.npmjs.com/package/@bendyline/squisq-video) | Headless video/GIF rendering and WASM helpers     |
+| [@bendyline/squisq](https://www.npmjs.com/package/@bendyline/squisq)             | Headless core — schemas, templates, markdown      |
+| [@bendyline/squisq-react](https://www.npmjs.com/package/@bendyline/squisq-react) | React components for rendering docs               |
+| [@bendyline/squisq-cli](https://www.npmjs.com/package/@bendyline/squisq-cli)     | CLI for document conversion and MP4/GIF rendering |
 
 ## License
 
 [MIT](https://github.com/bendyline/squisq/blob/main/LICENSE)
+
+The separately distributed `@ffmpeg/core` runtime retains its own
+GPL-2.0-or-later license.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { MediaProvider, Doc } from '@bendyline/squisq/schemas';
-import { VideoQuality, VideoOrientation, RenderHtmlOptions } from '@bendyline/squisq-video';
+import { VideoQuality, VideoOrientation, FfmpegWasmLoadConfig, RenderHtmlOptions } from '@bendyline/squisq-video';
+export { FfmpegWasmLoadConfig } from '@bendyline/squisq-video';
 import { CaptionMode } from '@bendyline/squisq-react';
 
 /**
@@ -21,13 +22,23 @@ import { CaptionMode } from '@bendyline/squisq-react';
  */
 
 type VideoExportState = 'idle' | 'preparing' | 'capturing' | 'encoding' | 'complete' | 'error';
+/** Browser export container format. */
+type VideoOutputFormat = 'mp4' | 'gif';
 interface VideoExportConfig {
+    /** Output container (default: 'mp4') */
+    outputFormat?: VideoOutputFormat;
+    /** 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.
@@ -44,6 +55,8 @@ interface VideoExportConfig {
     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 */
@@ -54,6 +67,8 @@ interface VideoExportResult {
     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') */
@@ -104,17 +119,19 @@ interface VideoExportModalProps {
     /** Pre-collected audio map */
     audio?: Map<string, ArrayBuffer>;
     /**
-     * Seeds the modal's initial quality/fps/orientation/captionMode selections
-     * and is merged (as a base) into the config passed to the export hook, so a
-     * host can share one config shape with `useVideoExport`. The individual
-     * `images`/`audio`/`mediaProvider`/`playerScript` props still take
-     * precedence over any matching key here.
+     * Seeds the modal's initial format, motion, quality, FPS, orientation, and
+     * caption selections. It is merged (as a base) into the config passed to the
+     * export hook, so a host can share one config shape with `useVideoExport`.
+     * The individual `images`/`audio`/`mediaProvider`/`playerScript` props still
+     * take precedence over any matching key here.
      */
     defaultConfig?: Partial<VideoExportConfig>;
+    /** Visual color scheme for the portaled dialog. Defaults to light. */
+    colorScheme?: 'light' | 'dark';
     /** Called when the modal should close */
     onClose: () => void;
 }
-declare function VideoExportModal({ doc, playerScript, mediaProvider, images, audio, defaultConfig, onClose, }: VideoExportModalProps): react_jsx_runtime.JSX.Element;
+declare function VideoExportModal({ doc, playerScript, mediaProvider, images, audio, defaultConfig, colorScheme, onClose, }: VideoExportModalProps): react_jsx_runtime.JSX.Element;
 
 interface VideoExportButtonProps {
     /** The document to export */
@@ -132,18 +149,21 @@ interface VideoExportButtonProps {
     /** Pre-collected audio map */
     audio?: Map<string, ArrayBuffer>;
     /**
-     * Seeds the modal's initial export settings and is merged as a base into the
-     * config passed to the export hook. Forwarded to {@link VideoExportModal}.
+     * Seeds the modal's initial output format and export settings and is merged
+     * as a base into the config passed to the export hook. Forwarded to
+     * {@link VideoExportModal}.
      */
     defaultConfig?: Partial<VideoExportConfig>;
-    /** Button label (default: "Export Video") */
+    /** Visual color scheme forwarded to the portaled modal. Defaults to light. */
+    colorScheme?: 'light' | 'dark';
+    /** Button label (defaults to "Export Video", or "Export GIF" for a GIF default config) */
     label?: string;
     /** Additional inline styles for the button */
     style?: React.CSSProperties;
     /** Whether the button is disabled */
     disabled?: boolean;
 }
-declare function VideoExportButton({ doc, playerScript, mediaProvider, images, audio, defaultConfig, label, style, disabled, }: VideoExportButtonProps): react_jsx_runtime.JSX.Element;
+declare function VideoExportButton({ doc, playerScript, mediaProvider, images, audio, defaultConfig, colorScheme, label, style, disabled, }: VideoExportButtonProps): react_jsx_runtime.JSX.Element;
 
 /**
  * useFrameCapture — Hidden div + html2canvas frame capture.
@@ -199,7 +219,7 @@ interface EncoderConfig {
 }
 interface MainThreadEncoder {
     /** Encode a single frame. The bitmap is closed after encoding. */
-    encodeFrame(bitmap: ImageBitmap, frameIndex: number): void;
+    encodeFrame(bitmap: ImageBitmap, 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
@@ -255,4 +275,4 @@ declare function createEncoder(config: EncoderConfig): MainThreadEncoder;
  */
 declare function supportsWebCodecsAac(sampleRate?: number, channels?: number): Promise<boolean>;
 
-export { type EncoderConfig, type FrameCaptureHandle, type MainThreadEncoder, VideoExportButton, type VideoExportButtonProps, type VideoExportConfig, VideoExportModal, type VideoExportModalProps, type VideoExportResult, type VideoExportState, createEncoder, supportsWebCodecs, supportsWebCodecsAac, supportsWebCodecsH264, useFrameCapture, useVideoExport };
+export { type EncoderConfig, type FrameCaptureHandle, type MainThreadEncoder, VideoExportButton, type VideoExportButtonProps, type VideoExportConfig, VideoExportModal, type VideoExportModalProps, type VideoExportResult, type VideoExportState, type VideoOutputFormat, createEncoder, supportsWebCodecs, supportsWebCodecsAac, supportsWebCodecsH264, useFrameCapture, useVideoExport };