@bendyline/squisq-video-react 1.2.2 → 2.0.1

package/src/__tests__/useVideoExportGif.test.ts

@@ -0,0 +1,155 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Doc } from '@bendyline/squisq/schemas';
+
+const mocks = vi.hoisted(() => {
+  const bitmap = { close: vi.fn() } as unknown as ImageBitmap;
+  return {
+    bitmap,
+    frameInit: vi.fn(async () => 0.1),
+    captureFrame: vi.fn(async () => bitmap),
+    destroy: vi.fn(),
+    encodeFrame: vi.fn(async (frame: ImageBitmap) => frame.close()),
+    finalize: vi.fn(async () => new Uint8Array([0, 0, 0, 1]).buffer),
+    closeEncoder: vi.fn(),
+    computeAudioTimeline: vi.fn(() => []),
+    supportsAac: vi.fn(async () => true),
+    gifTranscode: vi.fn(
+      async (_video: Uint8Array, _options: unknown, _loadConfig?: unknown, _signal?: AbortSignal) =>
+        new Uint8Array([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]),
+    ),
+  };
+});
+
+vi.mock('../hooks/useFrameCapture.js', () => ({
+  useFrameCapture: () => ({
+    init: mocks.frameInit,
+    captureFrame: mocks.captureFrame,
+    destroy: mocks.destroy,
+  }),
+}));
+
+vi.mock('../mainThreadEncoder.js', () => ({
+  supportsWebCodecs: () => true,
+  supportsWebCodecsH264: async () => true,
+  createEncoder: () => ({
+    encodeFrame: mocks.encodeFrame,
+    finalize: mocks.finalize,
+    close: mocks.closeEncoder,
+  }),
+}));
+
+vi.mock('../gifTranscode.js', () => ({
+  transcodeMp4ToGifWithFfmpegWasm: mocks.gifTranscode,
+}));
+
+vi.mock('../audioTrack.js', () => ({
+  supportsWebCodecsAac: mocks.supportsAac,
+  selectAudioTier: () => ({ tier: 3, reason: null }),
+  renderAudioTimeline: vi.fn(),
+  encodeAacTrack: vi.fn(),
+  audioBufferToWav: vi.fn(),
+  muxAudioWithFfmpegWasm: vi.fn(),
+  EXPORT_AUDIO_SAMPLE_RATE: 48_000,
+  EXPORT_AUDIO_CHANNELS: 2,
+}));
+
+vi.mock('@bendyline/squisq-video', async () => {
+  const actual =
+    await vi.importActual<typeof import('@bendyline/squisq-video')>('@bendyline/squisq-video');
+  return { ...actual, computeAudioTimeline: mocks.computeAudioTimeline };
+});
+
+import { useVideoExport } from '../hooks/useVideoExport.js';
+
+const doc: Doc = {
+  articleId: 'gif-hook-test',
+  duration: 0.1,
+  blocks: [{ id: 'b1', startTime: 0, duration: 0.1, audioSegment: 0, layers: [] }],
+  audio: {
+    segments: [{ name: 'narration', src: 'narration.mp3', startTime: 0, duration: 0.1 }],
+  },
+};
+
+describe('useVideoExport GIF flow', () => {
+  let createObjectUrl: ReturnType<typeof vi.spyOn>;
+  let revokeObjectUrl: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.gifTranscode.mockResolvedValue(new Uint8Array([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]));
+    createObjectUrl = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:gif-output');
+    revokeObjectUrl = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
+    if (typeof SharedArrayBuffer === 'undefined') {
+      vi.stubGlobal('SharedArrayBuffer', ArrayBuffer);
+    }
+  });
+
+  afterEach(() => {
+    createObjectUrl.mockRestore();
+    revokeObjectUrl.mockRestore();
+    vi.unstubAllGlobals();
+  });
+
+  it('uses compact/static defaults, skips audio, and emits an image/gif Blob', async () => {
+    const { result, unmount } = renderHook(() => useVideoExport());
+
+    await act(async () => {
+      await result.current.startExport(doc, { outputFormat: 'gif' });
+    });
+
+    expect(mocks.frameInit).toHaveBeenCalledWith(
+      doc,
+      expect.objectContaining({ width: 960, height: 540, animationsEnabled: false }),
+      undefined,
+    );
+    expect(mocks.captureFrame).toHaveBeenCalledTimes(1);
+    expect(mocks.computeAudioTimeline).not.toHaveBeenCalled();
+    expect(mocks.supportsAac).not.toHaveBeenCalled();
+    expect(mocks.gifTranscode).toHaveBeenCalledWith(
+      expect.any(Uint8Array),
+      { width: 960, height: 540, loop: 0 },
+      undefined,
+      expect.any(AbortSignal),
+    );
+
+    const blob = createObjectUrl.mock.calls[0][0] as Blob;
+    expect(blob.type).toBe('image/gif');
+    expect(result.current.state).toBe('complete');
+    expect(result.current.outputFormat).toBe('gif');
+    expect(result.current.audioIncluded).toBe(false);
+    expect(result.current.audioSkippedReason).toBeNull();
+
+    unmount();
+  });
+
+  it('aborts the palette worker when the export is cancelled', async () => {
+    mocks.gifTranscode.mockImplementationOnce(
+      async (_video: Uint8Array, _options: unknown, _loadConfig: unknown, signal?: AbortSignal) =>
+        new Promise<Uint8Array<ArrayBuffer>>((_resolve, reject) => {
+          if (!signal) throw new Error('Expected an AbortSignal');
+          signal.addEventListener(
+            'abort',
+            () => reject(new DOMException('cancelled', 'AbortError')),
+            { once: true },
+          );
+        }),
+    );
+    const { result, unmount } = renderHook(() => useVideoExport());
+
+    let exportPromise!: Promise<void>;
+    await act(async () => {
+      exportPromise = result.current.startExport(doc, { outputFormat: 'gif' });
+      await vi.waitFor(() => expect(mocks.gifTranscode).toHaveBeenCalledOnce());
+    });
+    const signal = mocks.gifTranscode.mock.calls[0][3] as AbortSignal;
+
+    act(() => result.current.cancel());
+    await act(async () => exportPromise);
+
+    expect(signal.aborted).toBe(true);
+    expect(result.current.state).toBe('idle');
+    expect(result.current.phase).toBe('Cancelled');
+    unmount();
+  });
+});

package/src/__tests__/videoExportProps.test.tsx

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { render, renderHook } from '@testing-library/react';
+import { fireEvent, render, renderHook } from '@testing-library/react';
 import { VideoExportButton } from '../VideoExportButton';
 import { VideoExportModal } from '../VideoExportModal';
 import { useVideoExport } from '../hooks/useVideoExport';
@@ -34,6 +34,19 @@ describe('VideoExportButton', () => {
     );
     expect(getByRole('button', { name: 'Export Video' })).toBeTruthy();
   });
+
+  it('uses a GIF-specific default label when configured for GIF output', () => {
+    const { getByRole } = render(
+      <VideoExportButton doc={minimalDoc()} defaultConfig={{ outputFormat: 'gif' }} />,
+    );
+    expect(getByRole('button', { name: 'Export GIF' })).toBeTruthy();
+  });
+
+  it('forwards the requested color scheme to its portaled modal', () => {
+    const { getByRole } = render(<VideoExportButton doc={minimalDoc()} colorScheme="dark" />);
+    fireEvent.click(getByRole('button', { name: 'Export Video' }));
+    expect(document.querySelector('[data-color-scheme="dark"]')).toBeTruthy();
+  });
 });
 
 describe('VideoExportModal', () => {
@@ -55,18 +68,80 @@ describe('VideoExportModal', () => {
         onClose={() => {}}
       />,
     );
-    const selects = Array.from(container.querySelectorAll('select')) as HTMLSelectElement[];
-    // Order in the configure form: Quality, Frame Rate, Orientation, Captions.
-    expect(selects[0].value).toBe('high');
-    expect(selects[1].value).toBe('30');
-    expect(selects[2].value).toBe('portrait');
-    expect(selects[3].value).toBe('standard');
+    expect((container.querySelector('[aria-label="Format"]') as HTMLSelectElement).value).toBe(
+      'mp4',
+    );
+    expect((container.querySelector('[aria-label="Quality"]') as HTMLSelectElement).value).toBe(
+      'high',
+    );
+    expect((container.querySelector('[aria-label="Frame Rate"]') as HTMLSelectElement).value).toBe(
+      '30',
+    );
+    expect((container.querySelector('[aria-label="Orientation"]') as HTMLSelectElement).value).toBe(
+      'portrait',
+    );
+    expect((container.querySelector('[aria-label="Captions"]') as HTMLSelectElement).value).toBe(
+      'standard',
+    );
+    expect(
+      (container.querySelector('[aria-label="Animations and transitions"]') as HTMLSelectElement)
+        .value,
+    ).toBe('enabled');
+  });
+
+  it('defaults GIF export to 10fps with animations and transitions disabled', () => {
+    const { container, getByRole } = render(
+      <VideoExportModal
+        doc={minimalDoc()}
+        defaultConfig={{ outputFormat: 'gif' }}
+        onClose={() => {}}
+      />,
+    );
+
+    expect(getByRole('heading', { name: 'Export Animated GIF' })).toBeTruthy();
+    expect((container.querySelector('[aria-label="Frame Rate"]') as HTMLSelectElement).value).toBe(
+      '10',
+    );
+    expect(
+      (container.querySelector('[aria-label="Animations and transitions"]') as HTMLSelectElement)
+        .value,
+    ).toBe('disabled');
+    expect(container.textContent).toContain('Landscape (960 × 540)');
+    expect(getByRole('button', { name: 'Export GIF' })).toBeTruthy();
+  });
+
+  it('applies GIF recommendations when the format selection changes', () => {
+    const { container } = render(<VideoExportModal doc={minimalDoc()} onClose={() => {}} />);
+    fireEvent.change(container.querySelector('[aria-label="Format"]')!, {
+      target: { value: 'gif' },
+    });
+
+    expect((container.querySelector('[aria-label="Frame Rate"]') as HTMLSelectElement).value).toBe(
+      '10',
+    );
+    expect(
+      (container.querySelector('[aria-label="Animations and transitions"]') as HTMLSelectElement)
+        .value,
+    ).toBe('disabled');
+  });
+
+  it('applies dark colors to the modal surface and native controls', () => {
+    const { container } = render(
+      <VideoExportModal doc={minimalDoc()} colorScheme="dark" onClose={() => {}} />,
+    );
+    const overlay = container.querySelector('[data-color-scheme="dark"]');
+    const modal = overlay?.firstElementChild as HTMLElement | null;
+    const select = container.querySelector('select');
+    expect(modal?.style.colorScheme).toBe('dark');
+    expect(modal?.style.background).toBe('rgb(17, 24, 39)');
+    expect(select?.style.colorScheme).toBe('dark');
   });
 });
 
 describe('useVideoExport result shape', () => {
   it('exposes the additive audio result fields, defaulted for idle', () => {
     const { result } = renderHook(() => useVideoExport());
+    expect(result.current.outputFormat).toBe('mp4');
     expect(result.current.audioIncluded).toBe(false);
     expect(result.current.audioSkippedReason).toBeNull();
   });

package/src/__tests__/workerEncoder.test.ts

@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createWorkerEncoder } from '../workerEncoder.js';
+import type { MainToWorkerMessage, WorkerToMainMessage } from '../workers/workerTypes.js';
+
+class FakeWorker {
+  static instances: FakeWorker[] = [];
+
+  onmessage: ((event: MessageEvent<WorkerToMainMessage>) => void) | null = null;
+  onerror: ((event: ErrorEvent) => void) | null = null;
+  readonly posted: MainToWorkerMessage[] = [];
+  readonly terminate = vi.fn();
+
+  constructor() {
+    FakeWorker.instances.push(this);
+  }
+
+  postMessage(message: MainToWorkerMessage): void {
+    this.posted.push(message);
+  }
+
+  emit(message: WorkerToMainMessage): void {
+    this.onmessage?.({ data: message } as MessageEvent<WorkerToMainMessage>);
+  }
+}
+
+function createEncoder() {
+  return createWorkerEncoder({ width: 640, height: 360, fps: 30, quality: 'normal' });
+}
+
+function bitmap(): ImageBitmap {
+  return { close: vi.fn() } as unknown as ImageBitmap;
+}
+
+describe('createWorkerEncoder', () => {
+  beforeEach(() => {
+    FakeWorker.instances = [];
+    vi.stubGlobal('Worker', FakeWorker);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('rejects invalid configs before allocating a worker', () => {
+    expect(() =>
+      createWorkerEncoder({ width: 640, height: 360, fps: 0, quality: 'normal' }),
+    ).toThrow('Video FPS');
+    expect(FakeWorker.instances).toHaveLength(0);
+  });
+
+  it('keeps frame backpressure until the worker acknowledges the frame', async () => {
+    const encoder = createEncoder();
+    const worker = FakeWorker.instances[0];
+    worker.emit({ type: 'capabilities', backend: 'webcodecs' });
+    await expect(encoder.ready).resolves.toBe('webcodecs');
+
+    let completed = false;
+    const pending = encoder.encodeFrame(bitmap(), 7).then(() => {
+      completed = true;
+    });
+
+    await Promise.resolve();
+    expect(completed).toBe(false);
+    expect(worker.posted[worker.posted.length - 1]).toMatchObject({ type: 'frame', frameIndex: 7 });
+
+    worker.emit({ type: 'frame-complete', frameIndex: 7 });
+    await pending;
+    expect(completed).toBe(true);
+  });
+
+  it('threads self-hosted ffmpeg core URLs through worker initialization', () => {
+    createWorkerEncoder({
+      width: 640,
+      height: 360,
+      fps: 30,
+      quality: 'normal',
+      ffmpegWasm: {
+        coreURL: '/vendor/ffmpeg-core.js',
+        wasmURL: '/vendor/ffmpeg-core.wasm',
+      },
+    });
+
+    expect(FakeWorker.instances[0].posted[0]).toMatchObject({
+      type: 'init',
+      ffmpegWasm: {
+        coreURL: '/vendor/ffmpeg-core.js',
+        wasmURL: '/vendor/ffmpeg-core.wasm',
+      },
+    });
+  });
+
+  it('does not finalize until every submitted frame has completed', async () => {
+    const encoder = createEncoder();
+    const worker = FakeWorker.instances[0];
+    worker.emit({ type: 'capabilities', backend: 'ffmpeg-wasm' });
+    await encoder.ready;
+
+    const frame = encoder.encodeFrame(bitmap(), 3);
+    const finalized = encoder.finalize();
+    await Promise.resolve();
+    expect(worker.posted.some((message) => message.type === 'finalize')).toBe(false);
+
+    worker.emit({ type: 'frame-complete', frameIndex: 3 });
+    await frame;
+    await Promise.resolve();
+    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'finalize' });
+
+    const result = new ArrayBuffer(4);
+    worker.emit({ type: 'complete', data: result, size: result.byteLength });
+    await expect(finalized).resolves.toBe(result);
+    expect(worker.terminate).toHaveBeenCalledOnce();
+  });
+
+  it('rejects readiness when closed during initialization', async () => {
+    const encoder = createEncoder();
+    const worker = FakeWorker.instances[0];
+    const readiness = expect(encoder.ready).rejects.toThrow('Encoder closed');
+
+    encoder.close();
+
+    await readiness;
+    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'cancel' });
+    expect(worker.terminate).toHaveBeenCalledOnce();
+  });
+
+  it('rejects an in-flight finalization when closed', async () => {
+    const encoder = createEncoder();
+    const worker = FakeWorker.instances[0];
+    worker.emit({ type: 'capabilities', backend: 'webcodecs' });
+    await encoder.ready;
+
+    const finalized = encoder.finalize();
+    await Promise.resolve();
+    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'finalize' });
+
+    encoder.close();
+
+    await expect(finalized).rejects.toThrow('Encoder closed');
+    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'cancel' });
+    expect(worker.terminate).toHaveBeenCalledOnce();
+  });
+});

package/src/audioTrack.ts

@@ -17,7 +17,11 @@
  *    `useVideoExport` (and unit-tested at the module boundary).
  */
 
-import type { AudioTimelineClip } from '@bendyline/squisq-video';
+import {
+  ffmpegAudioMuxArgs,
+  type AudioTimelineClip,
+  type FfmpegWasmLoadConfig,
+} from '@bendyline/squisq-video';
 
 /** Sample rate the export renders + encodes audio at. */
 export const EXPORT_AUDIO_SAMPLE_RATE = 48_000;
@@ -287,34 +291,39 @@ export function audioBufferToWav(buffer: AudioBuffer): Uint8Array {
 
 /**
  * Mux a pre-encoded video-only MP4 with a WAV audio track in a single
- * ffmpeg.wasm pass (`-c:v copy -c:a aac -shortest`). Requires
+ * ffmpeg.wasm pass (`-c:v copy -c:a aac -af apad -shortest`). Requires
  * `SharedArrayBuffer` (cross-origin isolation). Returns the muxed MP4 bytes.
  */
 export async function muxAudioWithFfmpegWasm(
   videoMp4: Uint8Array,
   wav: Uint8Array,
   audioBitrate: number,
+  loadConfig?: FfmpegWasmLoadConfig,
 ): Promise<Uint8Array> {
   const { FFmpeg } = await import('@ffmpeg/ffmpeg');
   const ffmpeg = new FFmpeg();
-  await ffmpeg.load();
   try {
+    await ffmpeg.load({
+      ...loadConfig,
+      classWorkerURL:
+        loadConfig?.classWorkerURL ??
+        new URL('./workers/ffmpeg.class-worker.js', import.meta.url).href,
+    });
     await ffmpeg.writeFile('video.mp4', videoMp4);
     await ffmpeg.writeFile('audio.wav', wav);
-    await ffmpeg.exec([
+    const exitCode = await ffmpeg.exec([
       '-i',
       'video.mp4',
       '-i',
       'audio.wav',
       '-c:v',
       'copy',
-      '-c:a',
-      'aac',
-      '-b:a',
-      String(audioBitrate),
-      '-shortest',
+      ...ffmpegAudioMuxArgs(audioBitrate),
       'out.mp4',
     ]);
+    if (exitCode !== 0) {
+      throw new Error(`ffmpeg.wasm audio mux failed with exit code ${exitCode}`);
+    }
     const data = await ffmpeg.readFile('out.mp4');
     return data instanceof Uint8Array ? data : new TextEncoder().encode(data as string);
   } finally {

package/src/gifTranscode.ts

@@ -0,0 +1,75 @@
+/**
+ * Animated GIF finalization for the browser export path.
+ *
+ * The frame-capture pipeline already produces a compact, video-only MP4. For
+ * the GIF MVP we use that MP4 as a bounded-memory intermediate, then run a
+ * palette generation/application pass through ffmpeg.wasm.
+ */
+
+import {
+  ffmpegGifOutputArgs,
+  type FfmpegWasmLoadConfig,
+  type GifOutputOptions,
+} from '@bendyline/squisq-video';
+
+/** Build the deterministic ffmpeg arguments used for MP4 -> animated GIF. */
+export function buildGifFfmpegArgs(options: GifOutputOptions): string[] {
+  return ['-y', '-i', 'video.mp4', ...ffmpegGifOutputArgs(options), 'out.gif'];
+}
+
+/**
+ * Convert a video-only MP4 into a looping animated GIF with a generated
+ * palette. The ffmpeg runtime is always terminated, including on failure.
+ */
+export async function transcodeMp4ToGifWithFfmpegWasm(
+  videoMp4: Uint8Array,
+  options: GifOutputOptions,
+  loadConfig?: FfmpegWasmLoadConfig,
+  signal?: AbortSignal,
+): Promise<Uint8Array> {
+  if (videoMp4.byteLength === 0) {
+    throw new Error('Cannot create an animated GIF from an empty MP4.');
+  }
+  if (signal?.aborted) {
+    throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
+  }
+
+  const args = buildGifFfmpegArgs(options);
+  const { FFmpeg } = await import('@ffmpeg/ffmpeg');
+  const ffmpeg = new FFmpeg();
+  let terminated = false;
+  const terminate = () => {
+    if (terminated) return;
+    terminated = true;
+    ffmpeg.terminate();
+  };
+  const handleAbort = () => terminate();
+  signal?.addEventListener('abort', handleAbort, { once: true });
+  try {
+    await ffmpeg.load({
+      ...loadConfig,
+      classWorkerURL:
+        loadConfig?.classWorkerURL ??
+        new URL('./workers/ffmpeg.class-worker.js', import.meta.url).href,
+    });
+    if (signal?.aborted) {
+      throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
+    }
+    await ffmpeg.writeFile('video.mp4', videoMp4);
+    if (signal?.aborted) {
+      throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
+    }
+    const exitCode = await ffmpeg.exec(args);
+    if (signal?.aborted) {
+      throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
+    }
+    if (exitCode !== 0) {
+      throw new Error(`ffmpeg.wasm GIF transcode failed with exit code ${exitCode}`);
+    }
+    const data = await ffmpeg.readFile('out.gif');
+    return data instanceof Uint8Array ? data : new TextEncoder().encode(data as string);
+  } finally {
+    signal?.removeEventListener('abort', handleAbort);
+    terminate();
+  }
+}

package/src/hooks/useFrameCapture.ts

@@ -16,7 +16,7 @@ import { useRef, useCallback, useMemo } from 'react';
 import type { Doc, MediaProvider } from '@bendyline/squisq/schemas';
 import type { RenderHtmlOptions } from '@bendyline/squisq-video';
 import { DocPlayer, MediaContext } from '@bendyline/squisq-react';
-import type { SquisqWindow, CaptionMode, CaptionStyle } from '@bendyline/squisq-react';
+import type { SquisqRenderAPI, CaptionMode, CaptionStyle } from '@bendyline/squisq-react';
 import html2canvas from 'html2canvas';
 
 export interface FrameCaptureHandle {
@@ -95,6 +95,7 @@ function createInlineProvider(images: Map<string, ArrayBuffer>): MediaProvider {
 export function useFrameCapture(): FrameCaptureHandle {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const rootRef = useRef<Root | null>(null);
+  const renderAPIRef = useRef<SquisqRenderAPI | null>(null);
   const dimensionsRef = useRef<{ width: number; height: number }>({ width: 1920, height: 1080 });
 
   const init = useCallback(
@@ -111,6 +112,7 @@ export function useFrameCapture(): FrameCaptureHandle {
         const oldContainer = containerRef.current;
         rootRef.current = null;
         containerRef.current = null;
+        renderAPIRef.current = null;
         await new Promise<void>((resolve) => {
           setTimeout(() => {
             if (oldRoot) oldRoot.unmount();
@@ -122,6 +124,7 @@ export function useFrameCapture(): FrameCaptureHandle {
 
       const width = renderOptions.width ?? 1920;
       const height = renderOptions.height ?? 1080;
+      const animationsEnabled = renderOptions.animationsEnabled ?? true;
       dimensionsRef.current = { width, height };
 
       // Create a hidden container
@@ -150,16 +153,26 @@ export function useFrameCapture(): FrameCaptureHandle {
       // Derive caption props from captionMode
       const captionsEnabled = captionMode !== undefined && captionMode !== 'off';
       const captionStyle: CaptionStyle = captionMode === 'social' ? 'social' : 'standard';
+      let resolveRenderAPI!: (api: SquisqRenderAPI) => void;
+      const renderAPIReady = new Promise<SquisqRenderAPI>((resolve) => {
+        resolveRenderAPI = resolve;
+      });
 
       const playerElement = createElement(DocPlayer, {
         doc,
         basePath: '.',
         renderMode: true,
+        animationsEnabled,
         showControls: false,
         autoPlay: false,
         forceViewport: { width, height, name: 'export' },
         captionsEnabled,
         captionStyle,
+        onRenderAPIReady: (api: SquisqRenderAPI | null) => {
+          if (containerRef.current !== container) return;
+          renderAPIRef.current = api;
+          if (api) resolveRenderAPI(api);
+        },
       });
 
       // Defer rendering to the next microtask to avoid "synchronously unmount
@@ -173,12 +186,12 @@ export function useFrameCapture(): FrameCaptureHandle {
         root.render(playerElement);
       }
 
-      // Wait for the render API to appear on window
+      // Wait for this exact player's instance API.
       return new Promise<number>((resolve, reject) => {
         const timeout = setTimeout(() => {
-          const w = window as SquisqWindow;
-          const hasSeek = typeof w.seekTo === 'function';
-          const hasDur = typeof w.getDuration === 'function';
+          const api = renderAPIRef.current;
+          const hasSeek = typeof api?.seekTo === 'function';
+          const hasDur = typeof api?.getDuration === 'function';
           const rootEl = containerRef.current?.querySelector('#squisq-capture-root');
           const hasPlayer = rootEl ? rootEl.querySelector('.doc-player') !== null : false;
           reject(
@@ -189,19 +202,10 @@ export function useFrameCapture(): FrameCaptureHandle {
           );
         }, 15000);
 
-        const checkApi = () => {
-          const w = window as SquisqWindow;
-          if (typeof w.getDuration === 'function' && typeof w.seekTo === 'function') {
-            clearTimeout(timeout);
-            const duration = w.getDuration();
-            resolve(duration);
-          } else {
-            requestAnimationFrame(checkApi);
-          }
-        };
-
-        // Give React time to mount and run useEffects
-        setTimeout(checkApi, 500);
+        void renderAPIReady.then((api) => {
+          clearTimeout(timeout);
+          resolve(api.getDuration());
+        });
       });
     },
     [],
@@ -209,15 +213,15 @@ export function useFrameCapture(): FrameCaptureHandle {
 
   const captureFrame = useCallback(async (time: number): Promise<ImageBitmap> => {
     const container = containerRef.current;
-    const w = window as SquisqWindow;
-    if (!container || typeof w.seekTo !== 'function') {
+    const api = renderAPIRef.current;
+    if (!container || !api) {
       throw new Error('Frame capture not initialized — call init() first');
     }
 
     const { width, height } = dimensionsRef.current;
 
     // Seek the player to the target time
-    await w.seekTo(time);
+    await api.seekTo(time);
 
     // Wait for the DOM to update after seek
     await new Promise<void>((resolve) =>
@@ -255,6 +259,7 @@ export function useFrameCapture(): FrameCaptureHandle {
       containerRef.current.remove();
       containerRef.current = null;
     }
+    renderAPIRef.current = null;
   }, []);
 
   // Return a stable object to prevent useEffect cleanup loops