@hyperframes/engine 0.1.1 → 0.1.3

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);

package/src/services/videoFrameInjector.ts

@@ -71,7 +71,10 @@ export function createVideoFrameInjector(
 ): BeforeCaptureHook | null {
   if (!frameLookup) return null;
 
-  const cacheLimit = Math.max(32, config?.frameDataUriCacheLimit ?? DEFAULT_CONFIG.frameDataUriCacheLimit);
+  const cacheLimit = Math.max(
+    32,
+    config?.frameDataUriCacheLimit ?? DEFAULT_CONFIG.frameDataUriCacheLimit,
+  );
   const frameCache = createFrameDataUriCache(cacheLimit);
   const lastInjectedFrameByVideo = new Map<string, number>();
 
@@ -81,13 +84,16 @@ export function createVideoFrameInjector(
     const updates: Array<{ videoId: string; dataUri: string; frameIndex: number }> = [];
     const activeIds = new Set<string>();
     if (activePayloads.size > 0) {
-      const pendingReads: Array<Promise<{ videoId: string; dataUri: string; frameIndex: number }>> = [];
+      const pendingReads: Array<Promise<{ videoId: string; dataUri: string; frameIndex: number }>> =
+        [];
       for (const [videoId, payload] of activePayloads) {
         activeIds.add(videoId);
         const lastFrameIndex = lastInjectedFrameByVideo.get(videoId);
         if (lastFrameIndex === payload.frameIndex) continue;
         pendingReads.push(
-          frameCache.get(payload.framePath).then((dataUri) => ({ videoId, dataUri, frameIndex: payload.frameIndex })),
+          frameCache
+            .get(payload.framePath)
+            .then((dataUri) => ({ videoId, dataUri, frameIndex: payload.frameIndex })),
         );
       }
       updates.push(...(await Promise.all(pendingReads)));

package/src/utils/ffprobe.ts

@@ -59,7 +59,15 @@ export async function extractVideoMetadata(filePath: string): Promise<VideoMetad
   }
 
   const probePromise = new Promise<VideoMetadata>((resolve, reject) => {
-    const args = ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", filePath];
+    const args = [
+      "-v",
+      "quiet",
+      "-print_format",
+      "json",
+      "-show_format",
+      "-show_streams",
+      filePath,
+    ];
 
     const ffprobe = spawn("ffprobe", args);
     let stdout = "";
@@ -87,7 +95,8 @@ export async function extractVideoMetadata(filePath: string): Promise<VideoMetad
         }
 
         const hasAudio = output.streams.some((s) => s.codec_type === "audio");
-        const fps = parseFrameRate(videoStream.avg_frame_rate) || parseFrameRate(videoStream.r_frame_rate);
+        const fps =
+          parseFrameRate(videoStream.avg_frame_rate) || parseFrameRate(videoStream.r_frame_rate);
         const durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
 
         const metadata: VideoMetadata = {
@@ -100,7 +109,11 @@ export async function extractVideoMetadata(filePath: string): Promise<VideoMetad
         };
         resolve(metadata);
       } catch (parseError: unknown) {
-        reject(new Error(`[FFmpeg] Failed to parse ffprobe output: ${parseError instanceof Error ? parseError.message : parseError}`));
+        reject(
+          new Error(
+            `[FFmpeg] Failed to parse ffprobe output: ${parseError instanceof Error ? parseError.message : parseError}`,
+          ),
+        );
       }
     });
 
@@ -128,7 +141,15 @@ export async function extractAudioMetadata(filePath: string): Promise<AudioMetad
   }
 
   const probePromise = new Promise<AudioMetadata>((resolve, reject) => {
-    const args = ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", filePath];
+    const args = [
+      "-v",
+      "quiet",
+      "-print_format",
+      "json",
+      "-show_format",
+      "-show_streams",
+      filePath,
+    ];
 
     const ffprobe = spawn("ffprobe", args);
     let stdout = "";

package/src/utils/urlDownloader.ts

@@ -14,7 +14,11 @@ function getFilenameFromUrl(url: string): string {
   return `download_${hash}${ext}`;
 }
 
-export async function downloadToTemp(url: string, destDir: string, timeoutMs: number = 300000): Promise<string> {
+export async function downloadToTemp(
+  url: string,
+  destDir: string,
+  timeoutMs: number = 300000,
+): Promise<string> {
   const cachedPath = downloadPathCache.get(url);
   if (cachedPath && existsSync(cachedPath)) {
     return cachedPath;