Function captureFrameCore

packages/engine/src/services/frameCapture.ts:1686–1768

* Internal core: prepare, screenshot, and track perf. * Shared by captureFrame (disk) and captureFrameToBuffer (buffer). * Returns the screenshot buffer, quantized time, and total capture time.

(
  session: CaptureSession,
  frameIndex: number,
  time: number,
)

 * Returns the screenshot buffer, quantized time, and total capture time.
 */
async function captureFrameCore(
  session: CaptureSession,
  frameIndex: number,
  time: number,
): Promise<{ buffer: Buffer; quantizedTime: number; captureTimeMs: number }> {
  const { page, options } = session;
  const startTime = Date.now();

  // Static-frame dedup: this frame is byte-identical to its predecessor (predicted +
  // anchor-verified at init) → reuse the prior buffer, skip the seek + screenshot.
  // KEY: index by the ABSOLUTE composition frame (derived from `time`), NOT the
  // `frameIndex` arg — chunked/parallel/distributed callers pass a chunk-RELATIVE
  // frameIndex (captureStage passes the loop `i`, parallelCoordinator passes
  // `i-outputFrameOffset`) while staticFrames is keyed in absolute frames. Using `time`
  // is correct on every path (sequential, per-worker range, distributed chunk) because
  // `time` is always the absolute composition time for the frame. Each session captures
  // its range in ascending order, so lastFrameBuffer is the correct in-range anchor (and
  // since a static run is verified identical, reusing the run's first in-range capture
  // equals reusing the global anchor). Telemetry: count reuses separately; do NOT bump
  // capturePerf.frames (that would dilute the per-frame timing averages).
  // Use the SAME floor+epsilon idiom as quantizeTimeToFrame so the dedup lookup agrees
  // with the frame the seek actually lands on, even if `time` ever isn't exactly i/fps.
  const absFrameIndex = Math.floor(time * fpsToNumber(options.fps) + 1e-9);
  if (session.staticFrames?.has(absFrameIndex) && session.lastFrameBuffer) {
    session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
    return {
      buffer: session.lastFrameBuffer,
      quantizedTime: quantizeTimeToFrame(time, fpsToNumber(options.fps)),
      captureTimeMs: Date.now() - startTime,
    };
  }

  try {
    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,
      );
      if (result.hasDamage) session.beginFrameHasDamageCount++;
      else session.beginFrameNoDamageCount++;
      screenshotBuffer = result.buffer;
    } else {
      screenshotBuffer = await pageScreenshotCapture(page, options);
    }