@hyperframes/engine 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,78 @@
+# @hyperframes/engine
+
+Seekable web-page-to-video rendering engine built on Puppeteer and FFmpeg.
+
+Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations, or any web content that implements the `window.__hf` seek protocol.
+
+## Install
+
+```bash
+npm install @hyperframes/engine
+```
+
+**Requirements:** Node.js >= 22, Chrome/Chromium (auto-downloaded by Puppeteer), FFmpeg
+
+## What it does
+
+The engine opens your HTML composition in a headless Chrome instance, seeks frame-by-frame using Chrome's `HeadlessExperimental.beginFrame` API, captures screenshots, and encodes them into video with FFmpeg.
+
+### Key services
+
+| Service                 | Description                                                            |
+| ----------------------- | ---------------------------------------------------------------------- |
+| **browserManager**      | Launches and pools headless Chrome instances (`chrome-headless-shell`) |
+| **frameCapture**        | Manages capture sessions — seek, screenshot, buffer lifecycle          |
+| **screenshotService**   | BeginFrame-based capture with CDP (Chrome DevTools Protocol)           |
+| **chunkEncoder**        | FFmpeg encoding with chunked concat, GPU detection, faststart          |
+| **streamingEncoder**    | Pipe frames to FFmpeg in real time (no intermediate PNGs on disk)      |
+| **audioMixer**          | Parse `<audio>` elements and mix audio tracks via FFmpeg               |
+| **videoFrameExtractor** | Extract frames from `<video>` elements for compositing                 |
+| **parallelCoordinator** | Split frame ranges across worker processes                             |
+| **fileServer**          | Serve local HTML files to the browser via Hono                         |
+
+## Usage
+
+```typescript
+import {
+  acquireBrowser,
+  releaseBrowser,
+  createCaptureSession,
+  initializeSession,
+  captureFrame,
+  closeCaptureSession,
+} from "@hyperframes/engine";
+
+// 1. Launch browser
+const browser = await acquireBrowser({ captureMode: "beginFrame" });
+
+// 2. Open a capture session
+const session = createCaptureSession({
+  browser: browser.browser,
+  url: "http://localhost:3000/my-composition.html",
+  width: 1920,
+  height: 1080,
+  fps: 30,
+});
+await initializeSession(session);
+
+// 3. Capture frames
+for (let i = 0; i < totalFrames; i++) {
+  await captureFrame(session, i, `/tmp/frames/frame-${i}.png`);
+}
+
+// 4. Clean up
+await closeCaptureSession(session);
+await releaseBrowser(browser);
+```
+
+Most users should use `@hyperframes/producer` or the `hyperframes` CLI instead of calling the engine directly.
+
+## Documentation
+
+Full documentation: [hyperframes.heygen.com/packages/engine](https://hyperframes.heygen.com/packages/engine)
+
+## Related packages
+
+- [`@hyperframes/core`](../core) — types, parsers, frame adapters
+- [`@hyperframes/producer`](../producer) — high-level render pipeline built on this engine
+- [`hyperframes`](../cli) — CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,11 +10,12 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@hono/node-server": "^1.13.0",
-    "@hyperframes/core": "workspace:*",
+    "@hyperframes/core": "workspace:^",
     "hono": "^4.6.0",
     "linkedom": "^0.18.12",
     "puppeteer": "^24.0.0",
@@ -22,7 +23,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.1",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=22"

package/src/config.ts

@@ -131,26 +131,44 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
     concurrency: env("PRODUCER_MAX_WORKERS") ? Number(env("PRODUCER_MAX_WORKERS")) : undefined,
     coresPerWorker: envNum("PRODUCER_CORES_PER_WORKER", DEFAULT_CONFIG.coresPerWorker),
     minParallelFrames: envNum("PRODUCER_MIN_PARALLEL_FRAMES", DEFAULT_CONFIG.minParallelFrames),
-    largeRenderThreshold: envNum("PRODUCER_LARGE_RENDER_THRESHOLD", DEFAULT_CONFIG.largeRenderThreshold),
+    largeRenderThreshold: envNum(
+      "PRODUCER_LARGE_RENDER_THRESHOLD",
+      DEFAULT_CONFIG.largeRenderThreshold,
+    ),
 
     chromePath: env("PRODUCER_HEADLESS_SHELL_PATH"),
     disableGpu: envBool("PRODUCER_DISABLE_GPU", DEFAULT_CONFIG.disableGpu),
     enableBrowserPool: envBool("PRODUCER_ENABLE_BROWSER_POOL", DEFAULT_CONFIG.enableBrowserPool),
     browserTimeout: envNum("PRODUCER_PUPPETEER_LAUNCH_TIMEOUT_MS", DEFAULT_CONFIG.browserTimeout),
-    protocolTimeout: envNum("PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS", DEFAULT_CONFIG.protocolTimeout),
+    protocolTimeout: envNum(
+      "PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS",
+      DEFAULT_CONFIG.protocolTimeout,
+    ),
     expectedChromiumMajor: env("PRODUCER_EXPECTED_CHROMIUM_MAJOR")
       ? Number(env("PRODUCER_EXPECTED_CHROMIUM_MAJOR"))
       : undefined,
 
     forceScreenshot: envBool("PRODUCER_FORCE_SCREENSHOT", DEFAULT_CONFIG.forceScreenshot),
 
-    enableChunkedEncode: envBool("PRODUCER_ENABLE_CHUNKED_ENCODE", DEFAULT_CONFIG.enableChunkedEncode),
-    chunkSizeFrames: Math.max(120, envNum("PRODUCER_CHUNK_SIZE_FRAMES", DEFAULT_CONFIG.chunkSizeFrames)),
-    enableStreamingEncode: envBool("PRODUCER_ENABLE_STREAMING_ENCODE", DEFAULT_CONFIG.enableStreamingEncode),
+    enableChunkedEncode: envBool(
+      "PRODUCER_ENABLE_CHUNKED_ENCODE",
+      DEFAULT_CONFIG.enableChunkedEncode,
+    ),
+    chunkSizeFrames: Math.max(
+      120,
+      envNum("PRODUCER_CHUNK_SIZE_FRAMES", DEFAULT_CONFIG.chunkSizeFrames),
+    ),
+    enableStreamingEncode: envBool(
+      "PRODUCER_ENABLE_STREAMING_ENCODE",
+      DEFAULT_CONFIG.enableStreamingEncode,
+    ),
 
     ffmpegEncodeTimeout: envNum("FFMPEG_ENCODE_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegEncodeTimeout),
     ffmpegProcessTimeout: envNum("FFMPEG_PROCESS_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegProcessTimeout),
-    ffmpegStreamingTimeout: envNum("FFMPEG_STREAMING_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegStreamingTimeout),
+    ffmpegStreamingTimeout: envNum(
+      "FFMPEG_STREAMING_TIMEOUT_MS",
+      DEFAULT_CONFIG.ffmpegStreamingTimeout,
+    ),
 
     audioGain: envNum("PRODUCER_AUDIO_GAIN", DEFAULT_CONFIG.audioGain),
     frameDataUriCacheLimit: Math.max(
@@ -158,8 +176,14 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
       envNum("PRODUCER_FRAME_DATA_URI_CACHE_LIMIT", DEFAULT_CONFIG.frameDataUriCacheLimit),
     ),
 
-    playerReadyTimeout: envNum("PRODUCER_PLAYER_READY_TIMEOUT_MS", DEFAULT_CONFIG.playerReadyTimeout),
-    renderReadyTimeout: envNum("PRODUCER_RENDER_READY_TIMEOUT_MS", DEFAULT_CONFIG.renderReadyTimeout),
+    playerReadyTimeout: envNum(
+      "PRODUCER_PLAYER_READY_TIMEOUT_MS",
+      DEFAULT_CONFIG.playerReadyTimeout,
+    ),
+    renderReadyTimeout: envNum(
+      "PRODUCER_RENDER_READY_TIMEOUT_MS",
+      DEFAULT_CONFIG.renderReadyTimeout,
+    ),
 
     verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",
     runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),

package/src/index.ts

@@ -27,7 +27,7 @@
  * - **Optional lookups return `T | undefined` or `T | null`.**
  *   Functions that may legitimately find nothing (resolveHeadlessShellPath,
  *   getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
- * 
+ *
  */
 
 // ── Protocol types ─────────────────────────────────────────────────────────────
@@ -90,11 +90,7 @@ export {
   ENCODER_PRESETS,
   type GpuEncoder,
 } from "./services/chunkEncoder.js";
-export type {
-  EncoderOptions,
-  EncodeResult,
-  MuxResult,
-} from "./services/chunkEncoder.types.js";
+export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 
 export {
   spawnStreamingEncoder,
@@ -121,15 +117,8 @@ export {
 
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
 
-export {
-  parseAudioElements,
-  processCompositionAudio,
-} from "./services/audioMixer.js";
-export type {
-  AudioElement,
-  AudioTrack,
-  MixResult,
-} from "./services/audioMixer.types.js";
+export { parseAudioElements, processCompositionAudio } from "./services/audioMixer.js";
+export type { AudioElement, AudioTrack, MixResult } from "./services/audioMixer.types.js";
 
 // ── Parallel rendering ─────────────────────────────────────────────────────────
 export {
@@ -144,11 +133,20 @@ export {
 } from "./services/parallelCoordinator.js";
 
 // ── File server ────────────────────────────────────────────────────────────────
-export { createFileServer, type FileServerOptions, type FileServerHandle } from "./services/fileServer.js";
+export {
+  createFileServer,
+  type FileServerOptions,
+  type FileServerHandle,
+} from "./services/fileServer.js";
 
 // ── Utilities ──────────────────────────────────────────────────────────────────
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 
-export { extractVideoMetadata, extractAudioMetadata, type VideoMetadata, type AudioMetadata } from "./utils/ffprobe.js";
+export {
+  extractVideoMetadata,
+  extractAudioMetadata,
+  type VideoMetadata,
+  type AudioMetadata,
+} from "./utils/ffprobe.js";
 
 export { downloadToTemp, isHttpUrl } from "./utils/urlDownloader.js";

package/src/services/audioMixer.ts

@@ -98,14 +98,20 @@ async function extractAudioFromVideo(
   const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
 
   if (signal?.aborted) {
-    return { success: false, outputPath, durationMs: result.durationMs, error: "Audio extract cancelled" };
+    return {
+      success: false,
+      outputPath,
+      durationMs: result.durationMs,
+      error: "Audio extract cancelled",
+    };
   }
   if (!result.success) {
     return {
       success: false,
       outputPath,
       durationMs: result.durationMs,
-      error: result.exitCode !== null ? `FFmpeg exited with code ${result.exitCode}` : result.stderr,
+      error:
+        result.exitCode !== null ? `FFmpeg exited with code ${result.exitCode}` : result.stderr,
     };
   }
   return { success: true, outputPath, durationMs: result.durationMs };
@@ -143,7 +149,12 @@ async function prepareAudioTrack(
   const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
 
   if (signal?.aborted) {
-    return { success: false, outputPath, durationMs: result.durationMs, error: "Audio prepare cancelled" };
+    return {
+      success: false,
+      outputPath,
+      durationMs: result.durationMs,
+      error: "Audio prepare cancelled",
+    };
   }
   return {
     success: result.success,
@@ -183,7 +194,12 @@ async function generateSilence(
   const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
 
   if (signal?.aborted) {
-    return { success: false, outputPath, durationMs: result.durationMs, error: "Silence generation cancelled" };
+    return {
+      success: false,
+      outputPath,
+      durationMs: result.durationMs,
+      error: "Silence generation cancelled",
+    };
   }
   return {
     success: result.success,
@@ -272,10 +288,16 @@ async function mixAudioTracks(
       outputPath,
       durationMs: result.durationMs,
       tracksProcessed: 0,
-      error: result.exitCode !== null ? `FFmpeg exited with code ${result.exitCode}` : result.stderr,
+      error:
+        result.exitCode !== null ? `FFmpeg exited with code ${result.exitCode}` : result.stderr,
     };
   }
-  return { success: true, outputPath, durationMs: result.durationMs, tracksProcessed: tracks.length };
+  return {
+    success: true,
+    outputPath,
+    durationMs: result.durationMs,
+    tracksProcessed: tracks.length,
+  };
 }
 
 export async function processCompositionAudio(
@@ -309,7 +331,9 @@ export async function processCompositionAudio(
           try {
             srcPath = await downloadToTemp(srcPath, workDir);
           } catch (err: unknown) {
-            errors.push(`Download failed: ${element.id} — ${err instanceof Error ? err.message : String(err)}`);
+            errors.push(
+              `Download failed: ${element.id} — ${err instanceof Error ? err.message : String(err)}`,
+            );
             return;
           }
         }
@@ -323,7 +347,8 @@ export async function processCompositionAudio(
         if (element.end - element.start <= 0) {
           const metadata = await extractAudioMetadata(srcPath);
           const effectiveDuration = metadata.durationSeconds - element.mediaStart;
-          element.end = element.start + (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
+          element.end =
+            element.start + (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
         }
 
         let audioSrcPath = srcPath;

package/src/services/browserManager.ts

@@ -40,7 +40,9 @@ export interface AcquiredBrowser {
  * Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,
  * then scans Puppeteer's managed cache at ~/.cache/puppeteer/chrome-headless-shell/.
  */
-export function resolveHeadlessShellPath(config?: Partial<Pick<EngineConfig, "chromePath">>): string | undefined {
+export function resolveHeadlessShellPath(
+  config?: Partial<Pick<EngineConfig, "chromePath">>,
+): string | undefined {
   if (config?.chromePath) {
     return config.chromePath;
   }
@@ -78,7 +80,10 @@ export const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;
 export async function acquireBrowser(
   chromeArgs: string[],
   config?: Partial<
-    Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "enableBrowserPool" | "chromePath" | "forceScreenshot">
+    Pick<
+      EngineConfig,
+      "browserTimeout" | "protocolTimeout" | "enableBrowserPool" | "chromePath" | "forceScreenshot"
+    >
   >,
 ): Promise<AcquiredBrowser> {
   const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;

package/src/services/chunkEncoder.ts

@@ -289,7 +289,18 @@ export async function encodeFramesChunkedConcat(
   const concatInput = chunkPaths.map((path) => `file '${path.replace(/'/g, "'\\''")}'`).join("\n");
   writeFileSync(concatListPath, concatInput, "utf-8");
 
-  const concatArgs = ["-f", "concat", "-safe", "0", "-i", concatListPath, "-c", "copy", "-y", outputPath];
+  const concatArgs = [
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    concatListPath,
+    "-c",
+    "copy",
+    "-y",
+    outputPath,
+  ];
   const concatResult = await new Promise<{ success: boolean; error?: string }>((resolve) => {
     const ffmpeg = spawn("ffmpeg", concatArgs);
     let stderr = "";
@@ -358,7 +369,12 @@ export async function muxVideoWithAudio(
   const result = await runFfmpeg(args, { signal, timeout: processTimeout });
 
   if (signal?.aborted) {
-    return { success: false, outputPath, durationMs: result.durationMs, error: "FFmpeg mux cancelled" };
+    return {
+      success: false,
+      outputPath,
+      durationMs: result.durationMs,
+      error: "FFmpeg mux cancelled",
+    };
   }
   return {
     success: result.success,
@@ -384,7 +400,12 @@ export async function applyFaststart(
   const result = await runFfmpeg(args, { signal, timeout: processTimeout });
 
   if (signal?.aborted) {
-    return { success: false, outputPath, durationMs: result.durationMs, error: "FFmpeg faststart cancelled" };
+    return {
+      success: false,
+      outputPath,
+      durationMs: result.durationMs,
+      error: "FFmpeg faststart cancelled",
+    };
   }
   return {
     success: result.success,

package/src/services/fileServer.ts

@@ -135,7 +135,9 @@ export function createFileServer(options: FileServerOptions): Promise<FileServer
     // Remove leading slash
     const relativePath = requestPath.replace(/^\//, "");
     const compiledPath = compiledDir ? join(compiledDir, relativePath) : null;
-    const hasCompiledFile = Boolean(compiledPath && existsSync(compiledPath) && statSync(compiledPath).isFile());
+    const hasCompiledFile = Boolean(
+      compiledPath && existsSync(compiledPath) && statSync(compiledPath).isFile(),
+    );
     const filePath = hasCompiledFile ? (compiledPath as string) : join(projectDir, relativePath);
 
     if (!existsSync(filePath) || !statSync(filePath).isFile()) {

package/src/services/frameCapture.ts

@@ -22,7 +22,12 @@ import {
 } from "./browserManager.js";
 import { beginFrameCapture, getCdpSession, pageScreenshotCapture } from "./screenshotService.js";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
-import type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary } from "../types.js";
+import type {
+  CaptureOptions,
+  CaptureResult,
+  CaptureBufferResult,
+  CapturePerfSummary,
+} from "../types.js";
 
 export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
 
@@ -72,8 +77,12 @@ export async function createCaptureSession(
   const headlessShell = resolveHeadlessShellPath(config);
   const isLinux = process.platform === "linux";
   const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
-  const preMode: CaptureMode = headlessShell && isLinux && !forceScreenshot ? "beginframe" : "screenshot";
-  const chromeArgs = buildChromeArgs({ width: options.width, height: options.height, captureMode: preMode }, config);
+  const preMode: CaptureMode =
+    headlessShell && isLinux && !forceScreenshot ? "beginframe" : "screenshot";
+  const chromeArgs = buildChromeArgs(
+    { width: options.width, height: options.height, captureMode: preMode },
+    config,
+  );
 
   const { browser, captureMode } = await acquireBrowser(chromeArgs, config);
 
@@ -81,7 +90,10 @@ export async function createCaptureSession(
   const browserVersion = await browser.version();
   const expectedMajor = config?.expectedChromiumMajor;
   if (Number.isFinite(expectedMajor)) {
-    const actualChromiumMajor = Number.parseInt((browserVersion.match(/(\d+)\./) || [])[1] || "", 10);
+    const actualChromiumMajor = Number.parseInt(
+      (browserVersion.match(/(\d+)\./) || [])[1] || "",
+      10,
+    );
     if (Number.isFinite(actualChromiumMajor) && actualChromiumMajor !== expectedMajor) {
       throw new Error(
         `[FrameCapture] Chromium major mismatch expected=${expectedMajor} actual=${actualChromiumMajor} raw=${browserVersion}`,
@@ -121,13 +133,14 @@ export async function createCaptureSession(
 }
 
 export async function initializeSession(session: CaptureSession): Promise<void> {
-  const { page, serverUrl, options } = session;
+  const { page, serverUrl } = session;
 
   // Forward browser console to host with [Browser] prefix
   page.on("console", (msg: ConsoleMessage) => {
     const type = msg.type();
     const text = msg.text();
-    const prefix = type === "error" ? "[Browser:ERROR]" : type === "warn" ? "[Browser:WARN]" : "[Browser]";
+    const prefix =
+      type === "error" ? "[Browser:ERROR]" : type === "warn" ? "[Browser:WARN]" : "[Browser]";
     console.log(`${prefix} ${text}`);
 
     session.browserConsoleBuffer.push(`${prefix} ${text}`);
@@ -151,7 +164,8 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     // Screenshot mode: standard navigation, rAF works normally
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60000 });
 
-    const pageReadyTimeout = session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
+    const pageReadyTimeout =
+      session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
     await page.waitForFunction(
       `!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)`,
       { timeout: pageReadyTimeout },
@@ -230,7 +244,8 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
   // Wait for all video elements to have loaded metadata (dimensions + duration).
   // Without this, frame 0 captures videos at their 300x150 default size.
-  const videoDeadline = Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout);
+  const videoDeadline =
+    Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout);
   while (Date.now() < videoDeadline) {
     const videosReady = await page.evaluate(
       `document.querySelectorAll("video").length === 0 || Array.from(document.querySelectorAll("video")).every(v => v.readyState >= 1)`,
@@ -341,14 +356,24 @@ async function captureFrameCore(
   const startTime = Date.now();
 
   try {
-    const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(session, frameIndex, time);
+    const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
+      session,
+      frameIndex,
+      time,
+    );
 
     const screenshotStart = Date.now();
     let screenshotBuffer: Buffer;
 
     if (session.captureMode === "beginframe") {
-      const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
-      const result = await beginFrameCapture(page, options, frameTimeTicks, session.beginFrameIntervalMs);
+      const frameTimeTicks =
+        session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
+      const result = await beginFrameCapture(
+        page,
+        options,
+        frameTimeTicks,
+        session.beginFrameIntervalMs,
+      );
       if (result.hasDamage) session.beginFrameHasDamageCount++;
       else session.beginFrameNoDamageCount++;
       screenshotBuffer = result.buffer;
@@ -379,9 +404,17 @@ async function captureFrameCore(
   }
 }
 
-export async function captureFrame(session: CaptureSession, frameIndex: number, time: number): Promise<CaptureResult> {
+export async function captureFrame(
+  session: CaptureSession,
+  frameIndex: number,
+  time: number,
+): Promise<CaptureResult> {
   const { options, outputDir } = session;
-  const { buffer, quantizedTime, captureTimeMs } = await captureFrameCore(session, frameIndex, time);
+  const { buffer, quantizedTime, captureTimeMs } = await captureFrameCore(
+    session,
+    frameIndex,
+    time,
+  );
 
   const ext = options.format === "png" ? "png" : "jpg";
   const frameName = `frame_${String(frameIndex).padStart(6, "0")}.${ext}`;

package/src/services/parallelCoordinator.ts

@@ -57,7 +57,12 @@ const MIN_FRAMES_PER_WORKER = 30;
 export function calculateOptimalWorkers(
   totalFrames: number,
   requested?: number,
-  config?: Partial<Pick<EngineConfig, "concurrency" | "coresPerWorker" | "minParallelFrames" | "largeRenderThreshold">>,
+  config?: Partial<
+    Pick<
+      EngineConfig,
+      "concurrency" | "coresPerWorker" | "minParallelFrames" | "largeRenderThreshold"
+    >
+  >,
 ): number {
   // Resolve effective values: config overrides → DEFAULT_CONFIG fallback.
   const effectiveMaxWorkers = (() => {
@@ -69,7 +74,8 @@ export function calculateOptimalWorkers(
   })();
   const effectiveCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
   const effectiveMinParallelFrames = config?.minParallelFrames ?? DEFAULT_CONFIG.minParallelFrames;
-  const effectiveLargeRenderThreshold = config?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
+  const effectiveLargeRenderThreshold =
+    config?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
 
   if (requested !== undefined) {
     return Math.max(MIN_WORKERS, Math.min(effectiveMaxWorkers, requested));
@@ -107,7 +113,11 @@ export function calculateOptimalWorkers(
   return finalWorkers;
 }
 
-export function distributeFrames(totalFrames: number, workerCount: number, workDir: string): WorkerTask[] {
+export function distributeFrames(
+  totalFrames: number,
+  workerCount: number,
+  workDir: string,
+): WorkerTask[] {
   const tasks: WorkerTask[] = [];
   const framesPerWorker = Math.ceil(totalFrames / workerCount);
 
@@ -146,7 +156,13 @@ async function executeWorkerTask(
   let perf: CapturePerfSummary | undefined;
 
   try {
-    session = await createCaptureSession(serverUrl, task.outputDir, captureOptions, createBeforeCaptureHook(), config);
+    session = await createCaptureSession(
+      serverUrl,
+      task.outputDir,
+      captureOptions,
+      createBeforeCaptureHook(),
+      config,
+    );
     await initializeSession(session);
 
     for (let i = task.startFrame; i < task.endFrame; i++) {
@@ -248,7 +264,11 @@ export async function executeParallelCapture(
   return results;
 }
 
-export async function mergeWorkerFrames(workDir: string, tasks: WorkerTask[], outputDir: string): Promise<number> {
+export async function mergeWorkerFrames(
+  workDir: string,
+  tasks: WorkerTask[],
+  outputDir: string,
+): Promise<number> {
   if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
 
   let totalFrames = 0;

package/src/services/screenshotService.ts

@@ -203,7 +203,10 @@ export async function injectVideoFramesBatch(
   );
 }
 
-export async function syncVideoFrameVisibility(page: Page, activeVideoIds: string[]): Promise<void> {
+export async function syncVideoFrameVisibility(
+  page: Page,
+  activeVideoIds: string[],
+): Promise<void> {
   await page.evaluate((ids: string[]) => {
     const active = new Set(ids);
     const videos = Array.from(document.querySelectorAll("video[data-start]")) as HTMLVideoElement[];

package/src/services/videoFrameExtractor.ts

@@ -252,10 +252,20 @@ export async function extractAllVideoFrames(
     }
   }
 
-  return { success: errors.length === 0, extracted, errors, totalFramesExtracted, durationMs: Date.now() - startTime };
+  return {
+    success: errors.length === 0,
+    extracted,
+    errors,
+    totalFramesExtracted,
+    durationMs: Date.now() - startTime,
+  };
 }
 
-export function getFrameAtTime(extracted: ExtractedFrames, globalTime: number, videoStart: number): string | null {
+export function getFrameAtTime(
+  extracted: ExtractedFrames,
+  globalTime: number,
+  videoStart: number,
+): string | null {
   const localTime = globalTime - videoStart;
   if (localTime < 0) return null;
   const frameIndex = Math.floor(localTime * extracted.fps);
@@ -344,7 +354,9 @@ export class FrameLookupTable {
     this.lastTime = globalTime;
   }
 
-  getActiveFramePayloads(globalTime: number): Map<string, { framePath: string; frameIndex: number }> {
+  getActiveFramePayloads(
+    globalTime: number,
+  ): Map<string, { framePath: string; frameIndex: number }> {
     const frames = new Map<string, { framePath: string; frameIndex: number }>();
     this.refreshActiveSet(globalTime);
     for (const videoId of this.activeVideoIds) {
@@ -381,7 +393,10 @@ export class FrameLookupTable {
   }
 }
 
-export function createFrameLookupTable(videos: VideoElement[], extracted: ExtractedFrames[]): FrameLookupTable {
+export function createFrameLookupTable(
+  videos: VideoElement[],
+  extracted: ExtractedFrames[],
+): FrameLookupTable {
   const table = new FrameLookupTable();
   const extractedMap = new Map<string, ExtractedFrames>();
   for (const ext of extracted) extractedMap.set(ext.videoId, ext);