@bendyline/squisq-video-react 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -1,316 +1,9 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { MediaProvider, Doc } from '@bendyline/squisq/schemas';
-import { ResourcePolicy } from '@bendyline/squisq/markdown';
-import { VideoQuality, VideoOrientation, FfmpegWasmLoadConfig, RenderHtmlOptions } from '@bendyline/squisq-video';
+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-NtqZVgaz.js';
+export { FrameCaptureHandle, useFrameCapture } from './hooks/index.js';
+export { EncoderConfig, MainThreadEncoder, createEncoder, supportsWebCodecs, supportsWebCodecsAac, supportsWebCodecsH264 } from './encoder/index.js';
 export { 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;
-
-interface VideoExportModalProps {
-    /** The document to export */
-    doc: Doc;
-    /**
-     * Player IIFE bundle source. Unused by the browser export path (frames
-     * are captured from a live in-page DocPlayer); only forwarded for
-     * CLI/Playwright-style pipelines that render standalone HTML.
-     */
-    playerScript?: string;
-    /** Optional media provider for resolving images/audio */
-    mediaProvider?: MediaProvider;
-    /** Pre-collected images map (alternative to mediaProvider) */
-    images?: Map<string, ArrayBuffer>;
-    /** Pre-collected audio map */
-    audio?: Map<string, ArrayBuffer>;
-    /**
-     * 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';
-    /** Optional host overrides for dialog surfaces, controls, status, and accent colors. */
-    uiPalette?: Partial<VideoExportPalette>;
-    /** Called when the modal should close */
-    onClose: () => void;
-}
-interface VideoExportPalette {
-    overlay: string;
-    surface: string;
-    control: string;
-    border: string;
-    text: string;
-    heading: string;
-    label: string;
-    muted: string;
-    secondary: string;
-    primary: string;
-    primaryBorder: string;
-    primaryText: string;
-    success: string;
-    danger: string;
-}
-declare function VideoExportModal({ doc, playerScript, mediaProvider, images, audio, defaultConfig, colorScheme, uiPalette, onClose, }: VideoExportModalProps): react_jsx_runtime.JSX.Element;
-
-interface VideoExportButtonProps {
-    /** The document to export */
-    doc: Doc;
-    /**
-     * Player IIFE bundle source. Unused by the browser export path (frames
-     * are captured from a live in-page DocPlayer); only forwarded for
-     * CLI/Playwright-style pipelines that render standalone HTML.
-     */
-    playerScript?: string;
-    /** Optional media provider for resolving images/audio */
-    mediaProvider?: MediaProvider;
-    /** Pre-collected images map */
-    images?: Map<string, ArrayBuffer>;
-    /** Pre-collected audio map */
-    audio?: Map<string, ArrayBuffer>;
-    /**
-     * 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>;
-    /** Visual color scheme forwarded to the portaled modal. Defaults to light. */
-    colorScheme?: 'light' | 'dark';
-    /** Optional host palette overrides forwarded to the portaled modal. */
-    uiPalette?: Partial<VideoExportPalette>;
-    /** 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, colorScheme, uiPalette, label, style, disabled, }: VideoExportButtonProps): react_jsx_runtime.JSX.Element;
-
-/**
- * useFrameCapture — Hidden div + html2canvas frame capture.
- *
- * Mounts a DocPlayer in renderMode inside a hidden div (same document),
- * then captures individual frames by seeking the player and rendering
- * the DOM to a canvas via html2canvas.
- *
- * Uses React directly — no script injection, no iframes, no eval.
- *
- * Returns an ImageBitmap for each frame (transferable to a Worker).
- */
-
-interface FrameCaptureHandle {
-    /** Initialize the hidden player. Returns the video duration in seconds. */
-    init: (doc: Doc, renderOptions: Omit<RenderHtmlOptions, 'playerScript'>, captionMode?: CaptionMode) => Promise<number>;
-    /** Capture a single frame at the given time (seconds). Returns an ImageBitmap. */
-    captureFrame: (time: number) => Promise<ImageBitmap>;
-    /** Clean up resources. */
-    destroy: () => void;
-}
-/**
- * Hook that manages a hidden div for frame capture.
- */
-declare function useFrameCapture(): FrameCaptureHandle;
-
-/**
- * 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;
-    };
-}
-interface MainThreadEncoder {
-    /** Encode a single frame. The bitmap is closed after encoding. */
-    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
-     * 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.
- *
- * Replaces the CLI's ffmpeg `adelay`/`atrim`/`amix` graph with browser-native
- * primitives:
- *
- *  - {@link supportsWebCodecsAac} probes whether the browser can encode AAC
- *    (WebCodecs `AudioEncoder`).
- *  - {@link renderAudioTimeline} mixes an {@link AudioTimelineClip} list into a
- *    single `AudioBuffer` using an `OfflineAudioContext` (decode → schedule →
- *    render).
- *  - {@link encodeAacTrack} feeds that buffer through a WebCodecs
- *    `AudioEncoder` and hands the chunks to an mp4-muxer audio track (tier 1).
- *  - {@link audioBufferToWav} + {@link muxAudioWithFfmpegWasm} cover the
- *    ffmpeg.wasm fallback (tier 2).
- *  - {@link selectAudioTier} is the pure capability→tier decision shared with
- *    `useVideoExport` (and unit-tested at the module boundary).
- */
-
-/**
- * Whether the browser can encode AAC (`mp4a.40.2`) via WebCodecs.
- * Returns false when `AudioEncoder` is undefined (e.g. Node/jsdom, Safari,
- * older Chromium) or the config is unsupported.
- */
-declare function supportsWebCodecsAac(sampleRate?: number, channels?: number): Promise<boolean>;
-
-export { type EncoderConfig, type FrameCaptureHandle, type MainThreadEncoder, type VideoAudioPolicy, VideoExportButton, type VideoExportButtonProps, type VideoExportConfig, VideoExportModal, type VideoExportModalProps, type VideoExportPalette, type VideoExportResult, type VideoExportState, type VideoOutputFormat, createEncoder, supportsWebCodecs, supportsWebCodecsAac, supportsWebCodecsH264, useFrameCapture, useVideoExport };
+import 'react/jsx-runtime';
+import '@bendyline/squisq/schemas';
+import '@bendyline/squisq/markdown';
+import '@bendyline/squisq-react';