@hyperframes/engine 0.1.0

package/src/services/parallelCoordinator.ts

@@ -0,0 +1,293 @@
+/**
+ * Parallel Coordinator Service
+ *
+ * Coordinates parallel frame capture across multiple Puppeteer sessions.
+ * Auto-detects optimal worker count based on CPU/memory.
+ */
+
+import { cpus, freemem, totalmem } from "os";
+import { existsSync, mkdirSync, readdirSync } from "fs";
+import { copyFile, rename } from "fs/promises";
+import { join } from "path";
+
+import {
+  createCaptureSession,
+  initializeSession,
+  closeCaptureSession,
+  captureFrame,
+  captureFrameToBuffer,
+  getCapturePerfSummary,
+  type CaptureSession,
+  type CaptureOptions,
+  type CapturePerfSummary,
+  type BeforeCaptureHook,
+} from "./frameCapture.js";
+import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
+
+export interface WorkerTask {
+  workerId: number;
+  startFrame: number;
+  endFrame: number;
+  outputDir: string;
+}
+
+export interface WorkerResult {
+  workerId: number;
+  framesCaptured: number;
+  startFrame: number;
+  endFrame: number;
+  durationMs: number;
+  perf?: CapturePerfSummary;
+  error?: string;
+}
+
+export interface ParallelProgress {
+  totalFrames: number;
+  capturedFrames: number;
+  activeWorkers: number;
+  workerProgress: Map<number, number>;
+}
+
+const MEMORY_PER_WORKER_MB = 256;
+const MIN_WORKERS = 1;
+const ABSOLUTE_MAX_WORKERS = 10;
+const DEFAULT_SAFE_MAX_WORKERS = 6;
+const MIN_FRAMES_PER_WORKER = 30;
+
+export function calculateOptimalWorkers(
+  totalFrames: number,
+  requested?: number,
+  config?: Partial<Pick<EngineConfig, "concurrency" | "coresPerWorker" | "minParallelFrames" | "largeRenderThreshold">>,
+): number {
+  // Resolve effective values: config overrides → DEFAULT_CONFIG fallback.
+  const effectiveMaxWorkers = (() => {
+    const concurrency = config?.concurrency ?? DEFAULT_CONFIG.concurrency;
+    if (concurrency !== "auto") {
+      return Math.max(MIN_WORKERS, Math.min(ABSOLUTE_MAX_WORKERS, Math.floor(concurrency)));
+    }
+    return DEFAULT_SAFE_MAX_WORKERS;
+  })();
+  const effectiveCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
+  const effectiveMinParallelFrames = config?.minParallelFrames ?? DEFAULT_CONFIG.minParallelFrames;
+  const effectiveLargeRenderThreshold = config?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
+
+  if (requested !== undefined) {
+    return Math.max(MIN_WORKERS, Math.min(effectiveMaxWorkers, requested));
+  }
+
+  if (totalFrames < MIN_FRAMES_PER_WORKER * 2) return 1;
+
+  const cpuCount = cpus().length;
+  const cpuBasedWorkers = Math.max(1, cpuCount - 2);
+
+  // Use total memory instead of free memory — macOS reports misleadingly low
+  // freemem() because it aggressively caches files in "inactive" memory that
+  // is immediately reclaimable.
+  const totalMemoryMB = Math.round(totalmem() / (1024 * 1024));
+  const memoryBasedWorkers = Math.max(1, Math.floor((totalMemoryMB * 0.5) / MEMORY_PER_WORKER_MB));
+
+  const frameBasedWorkers = Math.floor(totalFrames / MIN_FRAMES_PER_WORKER);
+
+  const optimal = Math.min(cpuBasedWorkers, memoryBasedWorkers, frameBasedWorkers);
+  const minWorkersForJob = totalFrames >= effectiveMinParallelFrames ? 2 : MIN_WORKERS;
+  let finalWorkers = Math.max(minWorkersForJob, Math.min(effectiveMaxWorkers, optimal));
+
+  // Adaptive scaling: cap workers for large renders to prevent CPU contention.
+  // Each Chrome process (with SwiftShader) is CPU-heavy; too many on a long
+  // render causes protocol timeouts from compositor starvation.
+  // Scale proportionally to CPU count: ~3 cores per worker (benchmarked).
+  // 8 cores → 2 workers, 16 cores → 5 workers, 32 cores → 10 workers.
+  if (totalFrames >= effectiveLargeRenderThreshold) {
+    const cpuScaledMax = Math.max(2, Math.floor(cpuCount / effectiveCoresPerWorker));
+    if (finalWorkers > cpuScaledMax) {
+      finalWorkers = cpuScaledMax;
+    }
+  }
+
+  return finalWorkers;
+}
+
+export function distributeFrames(totalFrames: number, workerCount: number, workDir: string): WorkerTask[] {
+  const tasks: WorkerTask[] = [];
+  const framesPerWorker = Math.ceil(totalFrames / workerCount);
+
+  for (let i = 0; i < workerCount; i++) {
+    const startFrame = i * framesPerWorker;
+    const endFrame = Math.min((i + 1) * framesPerWorker, totalFrames);
+    if (startFrame >= totalFrames) break;
+
+    tasks.push({
+      workerId: i,
+      startFrame,
+      endFrame,
+      outputDir: join(workDir, `worker-${i}`),
+    });
+  }
+
+  return tasks;
+}
+
+async function executeWorkerTask(
+  task: WorkerTask,
+  serverUrl: string,
+  captureOptions: CaptureOptions,
+  createBeforeCaptureHook: () => BeforeCaptureHook | null,
+  signal?: AbortSignal,
+  onFrameCaptured?: (workerId: number, frameIndex: number) => void,
+  onFrameBuffer?: (frameIndex: number, buffer: Buffer) => Promise<void>,
+  config?: Partial<EngineConfig>,
+): Promise<WorkerResult> {
+  const startTime = Date.now();
+  let framesCaptured = 0;
+
+  if (!existsSync(task.outputDir)) mkdirSync(task.outputDir, { recursive: true });
+
+  let session: CaptureSession | null = null;
+  let perf: CapturePerfSummary | undefined;
+
+  try {
+    session = await createCaptureSession(serverUrl, task.outputDir, captureOptions, createBeforeCaptureHook(), config);
+    await initializeSession(session);
+
+    for (let i = task.startFrame; i < task.endFrame; i++) {
+      if (signal?.aborted) {
+        throw new Error("Parallel worker cancelled");
+      }
+      const time = i / captureOptions.fps;
+
+      if (onFrameBuffer) {
+        // Streaming mode: capture to buffer and invoke callback
+        const { buffer } = await captureFrameToBuffer(session, i, time);
+        await onFrameBuffer(i, buffer);
+      } else {
+        // Disk mode: capture to file
+        await captureFrame(session, i, time);
+      }
+      framesCaptured++;
+
+      if (onFrameCaptured) onFrameCaptured(task.workerId, i);
+    }
+
+    perf = getCapturePerfSummary(session);
+    return {
+      workerId: task.workerId,
+      framesCaptured,
+      startFrame: task.startFrame,
+      endFrame: task.endFrame,
+      durationMs: Date.now() - startTime,
+      perf,
+    };
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    return {
+      workerId: task.workerId,
+      framesCaptured,
+      startFrame: task.startFrame,
+      endFrame: task.endFrame,
+      durationMs: Date.now() - startTime,
+      perf,
+      error: errMsg,
+    };
+  } finally {
+    if (session) await closeCaptureSession(session).catch(() => {});
+  }
+}
+
+export async function executeParallelCapture(
+  serverUrl: string,
+  workDir: string,
+  tasks: WorkerTask[],
+  captureOptions: CaptureOptions,
+  createBeforeCaptureHook: () => BeforeCaptureHook | null,
+  signal?: AbortSignal,
+  onProgress?: (progress: ParallelProgress) => void,
+  onFrameBuffer?: (frameIndex: number, buffer: Buffer) => Promise<void>,
+  config?: Partial<EngineConfig>,
+): Promise<WorkerResult[]> {
+  const totalFrames = tasks.reduce((sum, t) => sum + (t.endFrame - t.startFrame), 0);
+  const workerProgress = new Map<number, number>();
+
+  for (const task of tasks) workerProgress.set(task.workerId, 0);
+
+  const onFrameCaptured = (workerId: number, _frameIndex: number) => {
+    const current = workerProgress.get(workerId) || 0;
+    workerProgress.set(workerId, current + 1);
+
+    if (onProgress) {
+      const capturedFrames = Array.from(workerProgress.values()).reduce((a, b) => a + b, 0);
+      onProgress({
+        totalFrames,
+        capturedFrames,
+        activeWorkers: tasks.length,
+        workerProgress: new Map(workerProgress),
+      });
+    }
+  };
+
+  const results = await Promise.all(
+    tasks.map((task) =>
+      executeWorkerTask(
+        task,
+        serverUrl,
+        captureOptions,
+        createBeforeCaptureHook,
+        signal,
+        onFrameCaptured,
+        onFrameBuffer,
+        config,
+      ),
+    ),
+  );
+
+  const errors = results.filter((r) => r.error);
+  if (errors.length > 0) {
+    const errorMessages = errors.map((e) => `Worker ${e.workerId}: ${e.error}`).join("; ");
+    throw new Error(`[Parallel] Capture failed: ${errorMessages}`);
+  }
+
+  return results;
+}
+
+export async function mergeWorkerFrames(workDir: string, tasks: WorkerTask[], outputDir: string): Promise<number> {
+  if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+  let totalFrames = 0;
+  const sortedTasks = [...tasks].sort((a, b) => a.startFrame - b.startFrame);
+
+  for (const task of sortedTasks) {
+    if (!existsSync(task.outputDir)) {
+      continue;
+    }
+
+    const files = readdirSync(task.outputDir)
+      .filter((f) => f.startsWith("frame_") && (f.endsWith(".jpg") || f.endsWith(".png")))
+      .sort();
+    const copyTasks = files.map(async (file) => {
+      const sourcePath = join(task.outputDir, file);
+      const targetPath = join(outputDir, file);
+      try {
+        await rename(sourcePath, targetPath);
+      } catch {
+        await copyFile(sourcePath, targetPath);
+      }
+    });
+    await Promise.all(copyTasks);
+    totalFrames += files.length;
+  }
+
+  return totalFrames;
+}
+
+export function getSystemResources(): {
+  cpuCores: number;
+  totalMemoryMB: number;
+  freeMemoryMB: number;
+  recommendedWorkers: number;
+} {
+  return {
+    cpuCores: cpus().length,
+    totalMemoryMB: Math.round(totalmem() / (1024 * 1024)),
+    freeMemoryMB: Math.round(freemem() / (1024 * 1024)),
+    recommendedWorkers: calculateOptimalWorkers(1000),
+  };
+}

package/src/services/screenshotService.ts

@@ -0,0 +1,222 @@
+/**
+ * Screenshot Service
+ *
+ * BeginFrame-based deterministic screenshot capture and video frame injection.
+ */
+
+import { type Page } from "puppeteer-core";
+import { type CaptureOptions } from "../types.js";
+import { MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
+
+export const cdpSessionCache = new WeakMap<Page, import("puppeteer-core").CDPSession>();
+
+export async function getCdpSession(page: Page): Promise<import("puppeteer-core").CDPSession> {
+  let client = cdpSessionCache.get(page);
+  if (!client) {
+    client = await page.createCDPSession();
+    cdpSessionCache.set(page, client);
+  }
+  return client;
+}
+
+/**
+ * BeginFrame result with screenshot data and damage detection.
+ */
+export interface BeginFrameResult {
+  buffer: Buffer;
+  hasDamage: boolean;
+}
+
+/**
+ * Capture a frame using HeadlessExperimental.beginFrame.
+ *
+ * This is an atomic operation: one CDP call runs a single layout-paint-composite
+ * cycle and returns the screenshot + hasDamage boolean. Replaces the separate
+ * settle → screenshot pipeline with a single deterministic render cycle.
+ *
+ * Requires chrome-headless-shell with --enable-begin-frame-control and
+ * --deterministic-mode flags.
+ */
+// Cache the last valid screenshot buffer per page for hasDamage=false frames.
+// When Chrome reports no visual change, we reuse the previous frame rather than
+// attempting Page.captureScreenshot (which times out in beginFrame mode since
+// the compositor is paused).
+const lastFrameCache = new WeakMap<Page, Buffer>();
+
+export async function beginFrameCapture(
+  page: Page,
+  options: CaptureOptions,
+  frameTimeTicks: number,
+  interval: number,
+): Promise<BeginFrameResult> {
+  const client = await getCdpSession(page);
+
+  const format = options.format === "png" ? "png" : "jpeg";
+  const result = await client.send("HeadlessExperimental.beginFrame", {
+    frameTimeTicks,
+    interval,
+    screenshot: {
+      format,
+      quality: format === "jpeg" ? (options.quality ?? 80) : undefined,
+      optimizeForSpeed: true,
+    },
+  });
+
+  let buffer: Buffer;
+  if (result.screenshotData) {
+    buffer = Buffer.from(result.screenshotData, "base64");
+    lastFrameCache.set(page, buffer);
+  } else {
+    // hasDamage=false — nothing changed visually. Reuse the last frame.
+    const cached = lastFrameCache.get(page);
+    if (cached) {
+      buffer = cached;
+    } else {
+      // No cached frame yet (shouldn't happen — frame 0 always has damage).
+      // Issue another beginFrame with a tiny time advance to force a composite.
+      const retry = await client.send("HeadlessExperimental.beginFrame", {
+        frameTimeTicks: frameTimeTicks + 0.001,
+        interval,
+        screenshot: {
+          format,
+          quality: format === "jpeg" ? (options.quality ?? 80) : undefined,
+          optimizeForSpeed: true,
+        },
+      });
+      buffer = retry.screenshotData ? Buffer.from(retry.screenshotData, "base64") : Buffer.alloc(0);
+      if (buffer.length > 0) lastFrameCache.set(page, buffer);
+    }
+  }
+
+  return {
+    buffer,
+    hasDamage: result.hasDamage,
+  };
+}
+
+/**
+ * Capture a screenshot using standard Page.captureScreenshot CDP call.
+ * Fallback for environments where BeginFrame is unavailable (macOS, Windows).
+ */
+export async function pageScreenshotCapture(page: Page, options: CaptureOptions): Promise<Buffer> {
+  const client = await getCdpSession(page);
+  const format = options.format === "png" ? "png" : "jpeg";
+  const result = await client.send("Page.captureScreenshot", {
+    format,
+    quality: format === "jpeg" ? (options.quality ?? 80) : undefined,
+    optimizeForSpeed: true,
+  });
+  return Buffer.from(result.data, "base64");
+}
+
+export async function injectVideoFramesBatch(
+  page: Page,
+  updates: Array<{ videoId: string; dataUri: string }>,
+): Promise<void> {
+  if (updates.length === 0) return;
+  await page.evaluate(
+    async (items: Array<{ videoId: string; dataUri: string }>, visualProperties: string[]) => {
+      const pendingDecodes: Array<Promise<void>> = [];
+      for (const item of items) {
+        const video = document.getElementById(item.videoId) as HTMLVideoElement | null;
+        if (!video) continue;
+
+        let img = video.nextElementSibling as HTMLImageElement | null;
+        const isNewImage = !img || !img.classList.contains("__render_frame__");
+        const computedStyle = window.getComputedStyle(video);
+        const computedOpacity = parseFloat(computedStyle.opacity) || 1;
+        const sourceIsStatic = !computedStyle.position || computedStyle.position === "static";
+
+        if (isNewImage) {
+          img = document.createElement("img");
+          img.classList.add("__render_frame__");
+          img.id = `__render_frame_${item.videoId}__`;
+          img.style.pointerEvents = "none";
+          video.parentNode?.insertBefore(img, video.nextSibling);
+        }
+        if (!img) continue;
+
+        if (!sourceIsStatic) {
+          img.style.position = computedStyle.position;
+          img.style.width = computedStyle.width;
+          img.style.height = computedStyle.height;
+          img.style.top = computedStyle.top;
+          img.style.left = computedStyle.left;
+          img.style.right = computedStyle.right;
+          img.style.bottom = computedStyle.bottom;
+          img.style.inset = computedStyle.inset;
+        } else {
+          const videoRect = video.getBoundingClientRect();
+          const offsetLeft = Number.isFinite(video.offsetLeft) ? video.offsetLeft : 0;
+          const offsetTop = Number.isFinite(video.offsetTop) ? video.offsetTop : 0;
+          const offsetWidth = video.offsetWidth > 0 ? video.offsetWidth : videoRect.width;
+          const offsetHeight = video.offsetHeight > 0 ? video.offsetHeight : videoRect.height;
+          img.style.position = "absolute";
+          img.style.inset = "auto";
+          img.style.left = `${offsetLeft}px`;
+          img.style.top = `${offsetTop}px`;
+          img.style.right = "auto";
+          img.style.bottom = "auto";
+          img.style.width = `${offsetWidth}px`;
+          img.style.height = `${offsetHeight}px`;
+        }
+        img.style.objectFit = computedStyle.objectFit;
+        img.style.objectPosition = computedStyle.objectPosition;
+        img.style.zIndex = computedStyle.zIndex;
+
+        for (const property of visualProperties) {
+          if (
+            sourceIsStatic &&
+            (property === "top" ||
+              property === "left" ||
+              property === "right" ||
+              property === "bottom" ||
+              property === "inset")
+          ) {
+            continue;
+          }
+          const value = computedStyle.getPropertyValue(property);
+          if (value) {
+            img.style.setProperty(property, value);
+          }
+        }
+        img.decoding = "sync";
+        img.src = item.dataUri;
+        pendingDecodes.push(
+          img
+            .decode()
+            .catch(() => undefined)
+            .then(() => undefined),
+        );
+        img.style.opacity = String(computedOpacity);
+        img.style.visibility = "visible";
+        video.style.setProperty("visibility", "hidden", "important");
+        video.style.setProperty("opacity", "0", "important");
+        video.style.setProperty("pointer-events", "none", "important");
+      }
+      if (pendingDecodes.length > 0) {
+        await Promise.all(pendingDecodes);
+      }
+    },
+    updates,
+    [...MEDIA_VISUAL_STYLE_PROPERTIES],
+  );
+}
+
+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[];
+    for (const video of videos) {
+      if (active.has(video.id)) continue;
+      video.style.removeProperty("display");
+      video.style.setProperty("visibility", "hidden", "important");
+      video.style.setProperty("opacity", "0", "important");
+      video.style.setProperty("pointer-events", "none", "important");
+      const img = video.nextElementSibling as HTMLElement | null;
+      if (img && img.classList.contains("__render_frame__")) {
+        img.style.visibility = "hidden";
+      }
+    }
+  }, activeVideoIds);
+}