Skip to content

Write HTML. Render video. Built for agents.

213 KB
Raw Blame
// fallow-ignore-file complexity code-duplication
/**
 * Frame Capture Service
 *
 * Uses Puppeteer to capture frames from any web page implementing the
 * window.__hf seek protocol. Navigates to a file server URL, waits for
 * the page to expose window.__hf, then captures frames deterministically
 * via Chrome's BeginFrame API or Page.captureScreenshot fallback.
 */

import {
  type Browser,
  type Page,
  type Protocol,
  type Viewport,
  type ConsoleMessage,
} from "puppeteer-core";
import { existsSync, mkdirSync, writeFileSync } from "fs";
import { join } from "path";
import {
  COMPOSITION_SOURCE_URL,
  quantizeSeekTime,
  quantizeTimeToFrame,
  fpsToNumber,
  resolveAuthoredTimingWindow,
  type RawAuthoredTiming,
} from "@hyperframes/core";

import { DrawElementCaptureError } from "./drawElementCaptureError.js";
import { encodePng } from "../utils/alphaBlit.js";
import {
  DEFAULT_SAMPLES_PER_FRAME,
  MotionBlurAccumulator,
  SPATIAL_TWEEN_PROPERTIES,
  adaptiveSampleCount,
  motionBlurProbeTimes,
  motionBlurSampleTimes,
  motionBlurWindowIsStatic,
  probeDiffMagnitude,
  resolveMotionBlurPlan,
  type MotionBlurPlan,
} from "./motionBlur.js";
import {
  describePageMotionBlur,
  describePageMotionBlurAtEnd,
  installPageMotionBlur,
} from "./pageMotionBlur.js";

// ── Extracted modules ───────────────────────────────────────────────────────
import {
  acquireBrowser,
  releaseBrowser,
  forceReleaseBrowser,
  buildChromeArgs,
  resolveBrowserGpuMode,
  captureWithoutWaylandDisplay,
  resolveHeadlessShellPath,
  compositionRequiresWebGpu,
  assertWebGpuAdapterAvailable,
  usesSoftwareWebGpu,
  type BrowserLease,
  type CaptureMode,
} from "./browserManager.js";
import {
  beginFrameCapture,
  ensureRenderFrameSiblings,
  getCdpSession,
  pageContentExceedsCaptureHeight,
  pageScreenshotCapture,
  initTransparentBackground,
  shouldDefaultCaptureBeyondViewport,
} from "./screenshotService.js";
import {
  classifyGpuRenderer,
  detectGpuBackend,
  injectDrawElementCanvas,
  captureDrawElementFrame,
  resolveDrawElementCaptureMode,
  instrumentAcceleratedCanvases,
  initDrawElementWorkerEncode,
  cleanupDrawElementWorkerEncode,
  produceDrawElementFrame,
  produceDrawElementFrameBatch,
  DE_CANVAS_NOT_INITIALIZED_CODE,
} from "./drawElementService.js";
import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
import { isPsnrFilterAvailable } from "../utils/psnrFilterAvailability.js";
import { DEFAULT_CONFIG, applyConcreteGpuScreenshotClamp, type EngineConfig } from "../config.js";
import type {
  CaptureOptions,
  CaptureVideoMetadataHint,
  CaptureResult,
  CaptureBufferResult,
  CapturePerfSummary,
  CaptureWarning,
  HfSeekOptions,
  SubTimelineWaitMemo,
  SubTimelineWaitOutcome,
} from "../types.js";
import { cloneCaptureWarnings } from "./captureWarning.js";
import { installMediaRenderIdBridge } from "./mediaRenderIdBridge.js";
import {
  createChromeMemorySampler,
  type ChromeMemorySampler,
  type ChromePids,
} from "./chromeMemorySampler.js";
import { sampleProcessRss } from "../utils/processRss.js";
export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";

export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };

/** Called after seeking, before screenshot. Use for video frame injection or other pre-capture work.
 * `heldVideoTime` (motion-blur samples only) is the output frame's time: a video on screen at
 * both times shows its frame for `heldVideoTime`, so footage does not smear. */
export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;

/** The per-frame wait a capture is in, worded for the stall error a user reads. */
type CaptureStep =
  | "seeking the timeline"
  | "decoding CSS background images"
  | "injecting video frames"
  | "waiting for page seek handlers"
  | "loading color-grading LUTs"
  | "compositing the page"
  | "capturing the frame";

export interface CaptureSession {
  browser: Browser;
  /** Exact ownership token for this browser acquisition. */
  browserLease?: BrowserLease;
  page: Page;
  options: CaptureOptions;
  serverUrl: string;
  outputDir: string;
  /** The composition served at `serverUrl` declares `data-requires-webgpu`. */
  requiresWebGpu?: boolean;
  /** The browser was launched to run that WebGPU on SwiftShader ({@link usesSoftwareWebGpu}). */
  softwareWebGpu?: boolean;
  onBeforeCapture: BeforeCaptureHook | null;
  isInitialized: boolean;
  /**
   * Static-frame dedup (default-on; opt out with `HF_STATIC_DEDUP=false`): indices of frames byte-identical
   * to their predecessor (no GSAP tween / clip cut active in either), predicted from
   * window.__timelines and empirically anchor-verified. These reuse `lastFrameBuffer`
   * instead of re-seeking + re-screenshotting. Undefined when disabled or ineligible.
   */
  staticFrames?: Set<number>;
  /** Last non-deduped frame buffer, reused for every `staticFrames` index in its run. */
  lastFrameBuffer?: Buffer;
  /** Absolute index represented by lastFrameBuffer; reuse requires direct adjacency. */
  lastFrameAbsoluteIndex?: number;
  /** Count of frames served from a reused buffer (dedup telemetry). */
  staticDedupCount?: number;
  /** Live Chrome memory sampler; started in initializeSession, stopped in closeCaptureSession. */
  chromeMemory?: ChromeMemorySampler;
  /**
   * Resolved sub-frame motion-blur plan, or undefined when off. Set once by
   * `resolveSessionMotionBlur` at the end of initialization, where the capture mode has
   * settled, so an unsupported combination fails before the first frame rather than
   * silently rendering unblurred.
   */
  motionBlur?: MotionBlurPlan;
  /** Frames confirmed to move only non-spatial properties (opacity, colour); set for
   * adaptive motion blur. Absent from this set means "probe" — see computeStaticFrameSet. */
  motionBlurNonSpatialFrames?: Set<number>;
  // ── Static-dedup observability (set by armStaticDedup; surfaced via
  // getCapturePerfSummary → RenderPerfSummary → the render_complete event) ──
  // `armed` derives from the verified staticFrames set. Predicted count is stored
  // separately because partial budget arming intentionally makes them diverge.
  /** Dedup was enabled for this render (default-on; opt out with `HF_STATIC_DEDUP=false`). */
  staticDedupEnabled?: boolean;
  /** Original predicted-static count, before profitability or partial verification. */
  staticDedupPredictedCount?: number;
  /** Bounded verifier taxonomy and counters for debug/perf reporting. */
  staticDedupVerification?: StaticVerificationResult;
  /**
   * Short machine code for WHY dedup did not arm, for a low-cardinality breakdown.
   * One of: `capture_mode` | `video_injection` | `page_composite` |
   * `ineligible` | `unprofitable` | `verification_failed` | `verification_budget`.
   * Undefined when armed or disabled.
   */
  staticDedupSkipReason?: string;
  // Tracks whether the page/browser handles have already been released by
  // closeCaptureSession. Used to make closeCaptureSession idempotent under
  // browser-pool semantics (see the function body for the full invariant).
  pageReleased?: boolean;
  browserReleased?: boolean;
  browserConsoleBuffer: string[];
  /**
   * Script resources that failed to load (request failure or HTTP >= 400).
   * pollSubCompositionTimelines fail-fasts on these: a comp whose timeline
   * script 404'd can never register window.__timelines[id], so waiting the
   * full playerReadyTimeout (45s) buys nothing (~1% of wild local renders
   * were hitting that wall — a 705-render spike at the 45s setup bucket).
   */
  scriptLoadFailures: string[];
  /** Uncaught page errors; a timed-out timeline wait with any of these becomes a script failure. */
  pageErrors: string[];
  /** The first VFX chain error; its frames would lack the effect, so it stops the render. */
  vfxFailure?: string;
  /** Outcome of the sub-composition timeline wait: ready | timeout | script_failure. */
  subTimelineWaitOutcome?: SubTimelineWaitOutcome;
  /**
   * Composition ids still unregistered when the timeline wait gave up. Already
   * computed for the stderr warning; kept on the session so the STRUCTURED
   * warning can name them too — a programmatic caller reads `warnings`, not
   * our console output.
   */
  pendingTimelineIds?: string[];
  /** The render's shared memo when the caller passed one, else this session's own. */
  subTimelineWaitMemo: SubTimelineWaitMemo;
  /** Structured readiness warnings surfaced to the producer's render policy. */
  warnings: CaptureWarning[];
  initTelemetry?: {
    initDurationMs: number;
    tweenCount: number;
    /** Live DOM element count at end of init; undefined when the measurement itself failed. Observational — see collectSessionInitTelemetry. */
    elementCount?: number;
  };
  capturePerf: {
    frames: number;
    seekMs: number;
    beforeCaptureMs: number;
    screenshotMs: number;
    totalMs: number;
    /** Per-frame capture durations (batch frames get the batch mean). Basis for
     * the warmup-robust p50 in the perf summary. */
    frameMs: number[];
  };
  captureMode: CaptureMode;
  /**
   * Browser LAUNCH mode, immutable after createCaptureSession. `captureMode`
   * is reassigned by initializeSession (e.g. to "drawelement"), so callers
   * that need to know whether this browser actually drives BeginFrame (the
   * SwiftShader liveness probe) read this field instead.
   */
  launchCaptureMode: CaptureMode;
  // BeginFrame state
  beginFrameTimeTicks: number;
  beginFrameIntervalMs: number;
  beginFrameHasDamageCount: number;
  beginFrameNoDamageCount: number;
  beginFrameSeekPresented?: boolean;
  /** Optional producer config — when set, overrides module-level env var constants. */
  config?: Partial<EngineConfig>;
  /** True if running on SwiftShader (detected at init). Undefined before init. */
  isSwiftShader?: boolean;
  /**
   * Low-cardinality GPU bucket (`<backend>/<vendor>`, e.g. `d3d11/nvidia`)
   * derived from the WebGL renderer at DE session init. Surfaces in
   * CapturePerfSummary → render telemetry so backend-specific drawElement
   * damage (Metal vs D3D11 vs GL) clusters attributably. The raw
   * driver-supplied string is deliberately NOT retained — see
   * classifyGpuRenderer.
   */
  gpuRenderer?: string;
  /** drawElementImage canvas was injected and is ready for capture. */
  drawElementReady?: boolean;
  /**
   * Worker-encode pipeline is active for this session. Set by
   * `initDrawElementOrTransparentBackground` when `enableDrawElementWorkerEncode`
   * is true and capture mode resolved to "drawelement".
   */
  workerEncodeEnabled?: boolean;
  /**
   * Frame indices that must be captured via screenshot rather than drawElement.
   * Populated at init by the clip-cut boundary predictor (Lim 6): frames where
   * the outgoing clip is dropped a frame before the incoming clip's paint record
   * is ready → black frame. Controlled by `HF_FAST_CAPTURE_BOUNDARY_SS=false`.
   * Empty/undefined when the predictor produces no frames.
   */
  clipBoundaryFrames?: Set<number>;
  /** Rolling drawElement frame byte-sizes (last ~60), for silent-blank-drop detection:
   * drawElement intermittently returns an anomalously small (blank) frame with no
   * throw; a frame far below the running median is re-captured via screenshot. */
  deFrameSizes?: number[];
  /** Last non-deduped encode result, reused for a static frame on the drawElement
   * worker-encode path (mirrors `lastFrameBuffer` on the screenshot path). Only set
   * when static-frame dedup is armed on the drawElement path. */
  lastEncodeResult?: Promise<Buffer>;
  /** Frame index lastEncodeResult belongs to — static-dedup reuse must verify
   * every frame in (lastEncodeResultFrame, i] is predicted-static (under the
   * interleaved parallel stride the "previous" produced frame is i−N, and
   * reusing it for frame i is only valid when the whole gap is static). */
  lastEncodeResultFrame?: number;
  /** Per-render self-verification ground truth (ungated-release safety net):
   * K screenshot frames captured at init BEFORE the drawElement canvas is
   * injected (the only window where a page screenshot shows the live DOM, not
   * the capture canvas's stale bitmap). The producer drain compares the DE
   * frame at each index against these; a breach aborts the render with
   * DrawElementVerificationError and the orchestrator re-renders via the
   * screenshot path. */
  deVerifyFrames?: Map<number, Buffer>;
  /** Low-cardinality init-gate reason when drawElement routed to baseline (telemetry). */
  deGateReason?: string;
  /**
   * Full trigger string when drawElement gated off to the screenshot fallback
   * path — preserves the specific CSS effect (`filter:blur`,
   * `filter:drop-shadow`, `backdrop-filter`, `clip-path`) that
   * {@link deGateReason} sanitizes down to a low-cardinality bucket. Populated
   * on the same fallback-gate branches as `deGateReason`; consumed by the
   * `capture_fallback_profile` observability checkpoint gated behind
   * `HF_PROFILE_FALLBACK_CAPTURE=true`. See
   * `packages/producer/src/services/render/fallbackCaptureProfile.ts`.
   */
  deFallbackTrigger?: string;
  /** Wall-clock ms spent capturing self-verification ground truth at init (telemetry). */
  deVerifyInitMs?: number;
  /** Count of paint-record/canvas failures requiring fresh screenshot capture (telemetry). */
  deNcprFallbacks?: number;
  /**
   * Count of drawElement frame captures that blew `HF_DE_FRAME_TIMEOUT_MS`
   * because the renderer stopped scheduling after drawElementImage returned
   * (PRINFRA-488). Each one aborts the drawElement attempt so the whole render
   * retries via screenshot.
   */
  deFrameTimeouts?: number;
  captureStep?: CaptureStep;
  /**
   * drawElement init passed every gate but stopped before verification +
   * canvas injection: the session has no video-frame injector yet (probe
   * sessions initialize before extraction) and the comp has <video> elements,
   * so ground-truth screenshots would capture black video boxes. The capture
   * stage completes the init via completeDeferredDrawElementInit once
   * prepareCaptureSessionForReuse attaches the injector.
   */
  deInitDeferred?: boolean;
}

/**
 * drawElement self-verification failure — a captured DE frame diverged from its
 * pre-injection screenshot ground truth (or a blank frame survived a retry).
 * The orchestrator catches this and re-renders the whole job with
 * forceScreenshot. Discriminant-based guard (not instanceof) so it survives
 * duplicated module instances across package boundaries.
 */
/**
 * Structured detail carried alongside the human-readable message — lets
 * telemetry report the actual failure kind / failing dB / frame index
 * instead of the orchestrator having to regex them back out of formatted
 * text (a message-text dependency is exactly the failure mode this shape
 * exists to close — review finding: message wording, translation, or a
 * cross-module/serialized error must never be able to flip the reported
 * kind). All fields but `kind` are optional: a blank-frame trip has no PSNR
 * score, so `failedDb`/`verifyThresholdDb` are omitted for that throw site.
 */
export interface DrawElementVerificationDetails {
  kind: "blank" | "psnr";
  frameIndex?: number;
  failedDb?: number;
  verifyThresholdDb?: number;
}

export class DrawElementVerificationError extends Error {
  readonly kind: "blank" | "psnr";
  readonly frameIndex?: number;
  readonly failedDb?: number;
  readonly verifyThresholdDb?: number;

  constructor(message: string, details: DrawElementVerificationDetails) {
    super(message);
    this.name = "DrawElementVerificationError";
    // Discriminant property, assigned dynamically: isDrawElementVerificationError
    // reads it structurally so detection survives duplicated module instances
    // across package boundaries (where instanceof fails).
    (this as unknown as { deVerificationFailure: boolean }).deVerificationFailure = true;
    this.kind = details.kind;
    this.frameIndex = details.frameIndex;
    this.failedDb = details.failedDb;
    this.verifyThresholdDb = details.verifyThresholdDb;
  }
}

export function isDrawElementVerificationError(err: unknown): boolean {
  // Walk the cause chain — the producer wraps capture errors (CaptureStageError).
  let e: unknown = err;
  for (let depth = 0; depth < 5 && typeof e === "object" && e !== null; depth++) {
    if ((e as { deVerificationFailure?: boolean }).deVerificationFailure === true) return true;
    e = (e as { cause?: unknown }).cause;
  }
  return false;
}

/**
 * Extracts the structured details off a (possibly cause-wrapped) verification
 * error — same chain-walk as isDrawElementVerificationError, structural
 * (not instanceof) for the same duplicated-module-instance reason. Returns
 * undefined when the error isn't a verification failure at all.
 */
export function getDrawElementVerificationDetails(
  err: unknown,
): DrawElementVerificationDetails | undefined {
  let e: unknown = err;
  for (let depth = 0; depth < 5 && typeof e === "object" && e !== null; depth++) {
    const rec = e as { deVerificationFailure?: boolean } & Partial<DrawElementVerificationDetails>;
    if (rec.deVerificationFailure === true) {
      // Every construction path sets `kind` (required on the constructor), so
      // this only defends against a malformed cross-module-instance shape —
      // treat anything other than exactly "blank" as "psnr", the same
      // fallback polarity the old message regex had, but driven by a
      // structural field instead of parsing text.
      const details: DrawElementVerificationDetails = {
        kind: rec.kind === "blank" ? "blank" : "psnr",
      };
      if (typeof rec.frameIndex === "number") details.frameIndex = rec.frameIndex;
      if (typeof rec.failedDb === "number") details.failedDb = rec.failedDb;
      if (typeof rec.verifyThresholdDb === "number")
        details.verifyThresholdDb = rec.verifyThresholdDb;
      return details;
    }
    e = (e as { cause?: unknown }).cause;
  }
  return undefined;
}

/** Wait for inline CSS background images introduced by the latest seek. */
export async function decodeDynamicCssBackgroundImages(page: Page): Promise<void> {
  await page.evaluate(async () => {
    const root = globalThis as typeof globalThis & {
      __hf_css_background_decoded?: Set<string>;
      __hfDecodeDynamicCssBackgroundImages?: () => Promise<void>;
    };
    const decode = (root.__hfDecodeDynamicCssBackgroundImages ??= async () => {
      const decoded = (root.__hf_css_background_decoded ??= new Set<string>());
      const urls: string[] = [];
      const parseBackgroundUrls = (value: string): string[] => {
        const found: string[] = [];
        let cursor = 0;

        while (cursor < value.length) {
          const start = value.indexOf("url(", cursor);
          if (start < 0) break;

          let index = start + 4;
          while (index < value.length && /\s/.test(value[index] ?? "")) index += 1;

          const quote = value[index] === '"' || value[index] === "'" ? value[index] : null;
          if (quote) index += 1;
          const contentStart = index;
          let contentEnd = -1;

          while (index < value.length) {
            const char = value[index];
            if (char === "\\") {
              index = Math.min(index + 2, value.length);
              continue;
            }
            if ((quote && char === quote) || (!quote && char === ")")) {
              contentEnd = index;
              break;
            }
            index += 1;
          }

          if (contentEnd < 0) break;
          if (quote) {
            index += 1;
            while (index < value.length && /\s/.test(value[index] ?? "")) index += 1;
            if (value[index] !== ")") {
              cursor = index;
              continue;
            }
          }

          const url = value.slice(contentStart, contentEnd).trim();
          if (url) found.push(url);
          cursor = index + 1;
        }

        return found;
      };

      for (const element of document.querySelectorAll<HTMLElement>('[style*="background"]')) {
        const backgroundImage = element.style.backgroundImage;
        if (!backgroundImage || backgroundImage === "none") continue;

        for (const url of parseBackgroundUrls(backgroundImage)) {
          if (!decoded.has(url)) urls.push(url);
        }
      }

      await Promise.all(
        [...new Set(urls)].map(async (url) => {
          const image = new Image();
          image.src = url;
          try {
            await image.decode();
            decoded.add(url);
          } catch {
            // Keep existing capture behavior for missing assets; request diagnostics report them.
          }
        }),
      );
    });

    await decode();
  });
}

// Circular buffer for browser console messages dumped on render failure diagnostics.
// Complex compositions produce 100+ messages; 50 was too small to capture relevant errors.
const BROWSER_CONSOLE_BUFFER_SIZE = 200;
const CAPTURE_SESSION_CLOSE_TIMEOUT_MS = 5_000;

function appendBrowserDiagnostic(session: CaptureSession, text: string): void {
  session.browserConsoleBuffer.push(text);
  if (session.browserConsoleBuffer.length > BROWSER_CONSOLE_BUFFER_SIZE) {
    session.browserConsoleBuffer.shift();
  }
}

async function collectSessionInitTelemetry(
  page: Page,
  initStart: number,
): Promise<{ initDurationMs: number; tweenCount: number; elementCount?: number }> {
  const initDurationMs = Date.now() - initStart;
  // Live DOM size, measured once the init sequence has completed so
  // script-generated elements are present. This is the SAME quantity the
  // short-comp routing gate wants, but measured here it is observational
  // only — capture has already started, so it is far too late to route on.
  // Its job is coverage: the routing gate can only read a live count on the
  // ~17% of renders that get a probe session, which leaves the fleet
  // element-count distribution unknowable for the rest (and hides exactly
  // the dangerous shape — small source markup, huge runtime DOM).
  //
  // Coverage caveat, since the "every render reaches this" claim is easy to
  // over-read: every render that SURVIVES TO END OF INIT reaches it. Renders
  // that die in browser launch, navigation, or OOM before init completes
  // never emit — and on the huge-DOM tail this field exists to characterize,
  // those are disproportionately the ones that fail early. The distribution
  // is therefore survivor-biased toward smaller comps; treat the tail as a
  // lower bound (review finding).
  // Deliberately `undefined` (not 0) when the measurement fails, breaking
  // from the tweenCount fallback pattern directly above. A page.evaluate
  // crash during init is most likely on exactly the huge-DOM compositions
  // this field exists to observe, and a 0 there is indistinguishable from a
  // legitimately empty comp — the fleet p50/p99 would silently absorb both
  // (review finding). Mirrors the live/static provenance split the routing
  // resolver already uses: "not measured" must not read as "measured small".
  // getElementsByTagName over querySelectorAll: a live HTMLCollection's
  // length avoids materializing a 40k-node static NodeList on the tail this
  // is here to characterize.
  let elementCount: number | undefined;
  try {
    elementCount = await page.evaluate(() => document.getElementsByTagName("*").length);
  } catch {
    elementCount = undefined;
  }
  let tweenCount = 0;
  try {
    tweenCount = await page.evaluate(() => {
      const timelines =
        (window as unknown as { __timelines?: Record<string, unknown> }).__timelines || {};
      const seen = new Set<object>();
      let count = 0;
      for (const timeline of Object.values(timelines)) {
        const maybeTimeline = timeline as { getChildren?: unknown };
        if (typeof maybeTimeline?.getChildren !== "function") continue;
        const children = maybeTimeline.getChildren(true, true, false) as unknown[];
        for (const child of children) {
          if (child && typeof child === "object" && !seen.has(child)) {
            seen.add(child);
            count++;
          }
        }
      }
      return count;
    });
  } catch {
    tweenCount = 0;
  }
  return { initDurationMs, tweenCount, elementCount };
}

async function recordSessionInitTelemetry(
  session: CaptureSession,
  initStart: number,
): Promise<void> {
  const telemetry = await collectSessionInitTelemetry(session.page, initStart);
  session.initTelemetry = telemetry;
  appendBrowserDiagnostic(
    session,
    `[FrameCapture:INIT] complete initDurationMs=${telemetry.initDurationMs} tweenCount=${telemetry.tweenCount}` +
      // Omitted rather than zeroed when unmeasured, so the parser reports
      // absent instead of inventing an empty DOM.
      (telemetry.elementCount === undefined ? "" : ` elementCount=${telemetry.elementCount}`),
  );
}

export function sanitizeDiagnosticUrl(input: string): string {
  if (!input) return "(empty)";
  if (input.startsWith("data:")) return "data:<redacted>";
  if (input.startsWith("blob:")) return "blob:<redacted>";
  if (input.startsWith("/")) {
    try {
      const url = new URL(input, "http://hyperframes.local");
      return url.pathname;
    } catch {
      return input;
    }
  }

  try {
    const url = new URL(input);
    url.username = "";
    url.password = "";
    url.search = "";
    url.hash = "";
    return url.toString();
  } catch {
    return input;
  }
}

export function formatNavigationFailureDiagnostic(input: {
  captureMode: CaptureMode;
  url: string;
  timeoutMs: number;
  elapsedMs: number;
  error: unknown;
}): string {
  const message = input.error instanceof Error ? input.error.message : String(input.error);
  return (
    `[FrameCapture:ERROR] page.goto failed ` +
    `mode=${input.captureMode} timeoutMs=${input.timeoutMs} elapsedMs=${input.elapsedMs} ` +
    `url=${sanitizeDiagnosticUrl(input.url)} error=${message}`
  );
}

export function formatNavigationStartDiagnostic(input: {
  captureMode: CaptureMode;
  url: string;
  timeoutMs: number;
}): string {
  return (
    `[FrameCapture:NAV] page.goto start ` +
    `mode=${input.captureMode} timeoutMs=${input.timeoutMs} ` +
    `url=${sanitizeDiagnosticUrl(input.url)}`
  );
}

export function formatRequestFailureDiagnostic(input: {
  method: string;
  resourceType: string;
  url: string;
  failureText: string;
}): string {
  return (
    `[Browser:REQUESTFAILED] ${input.method} ${sanitizeDiagnosticUrl(input.url)} ` +
    `resource=${input.resourceType} error=${input.failureText}`
  );
}

/**
 * Chromium reports media loads that it intentionally cancels during probing as
 * request failures. They are expected when the probe discovers or seeks local
 * audio/video and do not indicate a missing asset.
 */
export function shouldIgnoreRequestFailureDiagnostic(input: {
  resourceType: string;
  url: string;
  failureText: string;
}): boolean {
  if (input.failureText !== "net::ERR_ABORTED") return false;
  if (input.resourceType === "media") return true;
  try {
    return /\.(?:aac|flac|m4a|mp3|mp4|mov|oga|ogg|ogv|wav|webm)$/i.test(
      new URL(input.url).pathname,
    );
  } catch {
    return false;
  }
}

export function formatHttpErrorDiagnostic(input: {
  method: string;
  resourceType: string;
  url: string;
  status: number;
  statusText: string;
}): string {
  const statusText = input.statusText ? ` ${input.statusText}` : "";
  return (
    `[Browser:HTTP${input.status}] ${input.method} ${sanitizeDiagnosticUrl(input.url)} ` +
    `resource=${input.resourceType}${statusText}`
  );
}

/**
 * Fixed warmup-loop iteration count used when `CaptureOptions.lockWarmupTicks`
 * is `true`. Picked to roughly match the median tick count observed by the
 * unlocked wall-clock loop during a typical 2s page load at 30fps — so
 * `beginFrameTimeTicks` lands in a similar range regardless of host speed.
 */
export const LOCKED_WARMUP_TICKS = 60;

/**
 * Internal driver for the BeginFrame warmup loop.
 *
 *   - Unlocked: exits as soon as `state.running` flips to `false`. Tick count
 *     varies with wall-clock page-load time.
 *   - Locked: ignores `state.running` entirely and exits once it has driven
 *     exactly `LOCKED_WARMUP_TICKS` iterations. Caller awaits this promise
 *     after page-readiness so `session.beginFrameTimeTicks` is identical
 *     across hosts.
 *   - `tick` errors are swallowed (Chrome's `beginFrame` is best-effort
 *     during page load — the page hasn't installed CDP listeners yet). When
 *     `tick` throws, the iteration count does NOT advance.
 *
 * `intervalMs` is the BeginFrame interval (≈33ms at 30fps).
 *
 * `frameTimeTicks` is derived as `ticks * intervalMs` and exposed via
 * {@link warmupFrameTimeTicks} — not stored on the state, to keep `ticks`
 * the single source of truth.
 */
export interface WarmupTickState {
  running: boolean;
  ticks: number;
  /** Set when session init fails: stops the loop in either mode, since a closed page fails every tick. */
  cancelled?: boolean;
}

export interface WarmupTickOptions {
  intervalMs: number;
  lockWarmupTicks: boolean;
  tick: (frameTimeTicks: number, intervalMs: number) => Promise<void>;
  /** Injectable so tests can advance "time" without real setTimeout. */
  sleep?: (ms: number) => Promise<void>;
}

const realSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * Derive the current simulated frame time from a warmup state. Single source
 * of truth so tests and callers stay in sync.
 */
export function warmupFrameTimeTicks(state: WarmupTickState, intervalMs: number): number {
  return state.ticks * intervalMs;
}

const BEGIN_FRAME_CAPTURE_HEADROOM_INTERVALS = 10;
const BEGIN_FRAME_COMMIT_LEAD_INTERVALS = 6;
const BEGIN_FRAME_PROBE_LEAD_INTERVALS = 5;

export interface BeginFrameTimelineTicks {
  capture: number;
  commit: number;
  probe: number;
}

export interface PreparedBeginFrameTimeline {
  commitParams: {
    frameTimeTicks: number;
    interval: number;
    noDisplayUpdates: false;
  };
  timeline: BeginFrameTimelineTicks;
}

/**
 * Place frame zero after the warmup clock while retaining capture-rate-sized
 * headroom for the visual commit and liveness probe ticks that precede it.
 *
 * The warmup and capture intervals can differ (warmup currently runs at a
 * fixed 33ms). Basing both clocks on the capture interval would move time
 * backwards whenever the output frame rate is faster than the warmup rate.
 */
export function deriveBeginFrameTimeTicks(
  state: WarmupTickState,
  warmupIntervalMs: number,
  captureIntervalMs: number,
): number {
  const legacyCaptureTimeTicks =
    (state.ticks + BEGIN_FRAME_CAPTURE_HEADROOM_INTERVALS) * captureIntervalMs;
  const legacyCommitTimeTicks = deriveBeginFrameCommitTimeTicks(
    legacyCaptureTimeTicks,
    captureIntervalMs,
  );
  const lastWarmupTimeTicks = Math.max(0, state.ticks - 1) * warmupIntervalMs;
  if (legacyCommitTimeTicks > lastWarmupTimeTicks) return legacyCaptureTimeTicks;

  const monotonicCaptureTimeTicks =
    warmupFrameTimeTicks(state, warmupIntervalMs) +
    BEGIN_FRAME_CAPTURE_HEADROOM_INTERVALS * captureIntervalMs;
  return monotonicCaptureTimeTicks;
}

function deriveBeginFrameCommitTimeTicks(
  captureTimeTicks: number,
  captureIntervalMs: number,
): number {
  return captureTimeTicks - BEGIN_FRAME_COMMIT_LEAD_INTERVALS * captureIntervalMs;
}

export function deriveBeginFrameProbeTimeTicks(
  captureTimeTicks: number,
  captureIntervalMs: number,
): number {
  return Math.max(0, captureTimeTicks - BEGIN_FRAME_PROBE_LEAD_INTERVALS * captureIntervalMs);
}

export function deriveBeginFrameTimelineTicks(
  state: WarmupTickState,
  warmupIntervalMs: number,
  captureIntervalMs: number,
): BeginFrameTimelineTicks {
  const capture = deriveBeginFrameTimeTicks(state, warmupIntervalMs, captureIntervalMs);
  return {
    capture,
    commit: deriveBeginFrameCommitTimeTicks(capture, captureIntervalMs),
    probe: deriveBeginFrameProbeTimeTicks(capture, captureIntervalMs),
  };
}

export function prepareBeginFrameTimeline(
  session: Pick<CaptureSession, "beginFrameIntervalMs" | "beginFrameTimeTicks">,
  state: WarmupTickState,
  warmupIntervalMs: number,
): PreparedBeginFrameTimeline {
  const timeline = deriveBeginFrameTimelineTicks(
    state,
    warmupIntervalMs,
    session.beginFrameIntervalMs,
  );
  session.beginFrameTimeTicks = timeline.capture;
  return {
    timeline,
    commitParams: {
      frameTimeTicks: timeline.commit,
      interval: session.beginFrameIntervalMs,
      noDisplayUpdates: false,
    },
  };
}

/** Runs BeginFrame session setup; a failure stops the warm-up loop, which would otherwise tick forever. */
export async function cancelWarmupOnError<T>(
  state: WarmupTickState,
  setup: () => Promise<T>,
): Promise<T> {
  try {
    return await setup();
  } catch (error) {
    state.cancelled = true;
    throw error;
  }
}

export async function driveWarmupTicks(
  options: WarmupTickOptions,
  state: WarmupTickState,
): Promise<void> {
  const sleep = options.sleep ?? realSleep;
  while (!state.cancelled) {
    if (options.lockWarmupTicks) {
      // Locked mode exits on the iteration count, ignoring `state.running` —
      // the caller flips `running=false` after page-readiness but we keep
      // ticking until LOCKED_WARMUP_TICKS so the count is host-independent.
      if (state.ticks >= LOCKED_WARMUP_TICKS) return;
    } else {
      // Unlocked mode is wall-clock-bounded.
      if (!state.running) return;
    }
    try {
      await options.tick(state.ticks * options.intervalMs, options.intervalMs);
      state.ticks += 1;
    } catch {
      // Page not ready yet; keep spinning.
    }
    await sleep(options.intervalMs);
  }
}

export function resolveCaptureSessionOptions(
  options: CaptureOptions,
  browserVersion: string,
  platform: NodeJS.Platform = process.platform,
): CaptureOptions {
  return {
    ...options,
    captureBeyondViewport:
      options.captureBeyondViewport ?? shouldDefaultCaptureBeyondViewport(browserVersion, platform),
  };
}

async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boolean> {
  let timedOut = false;
  let timer: ReturnType<typeof setTimeout> | undefined;
  await Promise.race([
    promise.then(
      () => undefined,
      () => undefined,
    ),
    new Promise<void>((resolve) => {
      timer = setTimeout(() => {
        timedOut = true;
        resolve();
      }, CAPTURE_SESSION_CLOSE_TIMEOUT_MS);
    }),
  ]);
  if (timer) clearTimeout(timer);
  return !timedOut;
}

/**
 * Post-readiness capture-surface init, shared by the screenshot and BeginFrame
 * init paths (called after the page is fully ready). When `useDrawElement` is
 * set, detect SwiftShader and route: transparent+SwiftShader falls back to
 * screenshot capture (the drawElement transparent path is broken on SwiftShader),
 * everything else injects the drawElement canvas and switches to "drawelement"
 * mode. Otherwise, for PNG output, force a transparent page background so the
 * screenshots carry a real alpha channel (Chrome resets the override on every
 * navigation, so this must run after page load).
 *
 * drawElement is also skipped when scaling (deviceScaleFactor other than 1):
 * `drawElementImage` reads the canvas at CSS pixels and has no equivalent of
 * `Page.captureScreenshot`'s clip+scale, so it would silently capture at 1x and
 * drop the requested supersample. Such renders fall through to the screenshot
 * path (preMode already forces "screenshot" for DPR other than 1).
 */
async function initDrawElementOrTransparentBackground(
  session: CaptureSession,
  page: Page,
  logInitPhase: (phase: string) => void,
): Promise<void> {
  const supersampling = (session.options.deviceScaleFactor ?? 1) !== 1;
  // forceScreenshot is an explicit routing decision made upstream (render-mode
  // compat hints like raw requestAnimationFrame, alpha formats, low-memory) —
  // drawElement must not override it. Concretely: an rAF-compat comp on
  // SwiftShader gets a screenshot-launched (free-running) browser, where
  // drawElement runs in paint-event-sync mode; SwiftShader never refreshes a
  // 2d canvas bitmap inside a cached paint record there, so every canvas
  // captures frozen-blank (raf-ball rendered fully black). On a GPU the same
  // path happens to work, but the hint asked for screenshot — honor it.
  const forceScreenshot = session.config?.forceScreenshot ?? false;
  // DIAGNOSTIC ONLY — HF_FORCE_DRAWELEMENT=1 forces the drawElement path,
  // bypassing every compile/init gate AND the compatibility hints (it overrides
  // forceScreenshot). Exists for upstream-Chromium repro work (isolating gate
  // behavior from drawElementImage behavior, e.g. the crbug 521861819 149-vs-151
  // comparison) and for R&D on gated effect classes. Renders under this flag may
  // be DAMAGED by design — the gates it skips exist because measured damage
  // (blur/backdrop ~18-49dB, 3D backface, SwiftShader sub-layer drops) is real.
  // Never set it in production; it is intentionally not documented in user-facing
  // help, and the safety-net blank guard also stands down under it so diagnostic
  // frames arrive unmodified.
  const forceDE = process.env.HF_FORCE_DRAWELEMENT === "1";
  const useDrawElement =
    ((session.config?.useDrawElement ?? false) || forceDE) &&
    !supersampling &&
    (!forceScreenshot || forceDE);
  if ((session.config?.useDrawElement ?? false) && supersampling) {
    session.deGateReason = "supersampling";
    session.deFallbackTrigger = "supersampling";
    console.log(
      "[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
        "ignores deviceScaleFactor, so scaled (DPR other than 1) output uses screenshot capture.",
    );
  }
  if ((session.config?.useDrawElement ?? false) && !supersampling && forceScreenshot) {
    session.deGateReason = "render_mode_hint";
    session.deFallbackTrigger = "render_mode_hint";
    console.log(
      "[engine] fast capture falls back to screenshot: render-mode compatibility " +
        "hint forced screenshot capture (e.g. raw requestAnimationFrame composition).",
    );
  }
  if (useDrawElement) {
    const gpuBackend = await detectGpuBackend(page);
    session.isSwiftShader = gpuBackend.isSwiftShader;
    session.gpuRenderer = classifyGpuRenderer(gpuBackend.renderer);
    const transparent = session.options.format === "png";
    async function routeToFallback(): Promise<void> {
      session.captureMode = session.launchCaptureMode;
      if (transparent) {
        await initTransparentBackground(session.page);
      }
      // Static-frame dedup is capture-mode-independent (the serial path reuses
      // lastFrameBuffer regardless of how the frame was captured) and lossless
      // (anchor-verified). A comp only reaches THIS fallback with useDrawElement=true
      // AND forceScreenshot=false — i.e. it is deterministic: raw-rAF / iframe /
      // htmlInCanvas comps are forced to screenshot upstream (forceScreenshot=true) and
      // never enter this block, so they never arm dedup. The comps that DO fall back here
      // (blur / backdrop / 3D / at-risk) carry only a compositor
      // EFFECT drawElement can't paint, not nondeterminism, so their predicted-static set
      // is sound. Verification seeks via Page.captureScreenshot, which hangs on a
      // BeginFrame-launched browser — gate on the launch mode (macOS fast-capture launches
      // screenshot-mode; Linux/Docker launches beginframe and is skipped).
      if (session.launchCaptureMode === "screenshot") {
        await armStaticDedup(session, page, logInitPhase);
      }
    }
    // Capability gate: `canvas.drawElementImage` is an unlaunched Blink feature
    // that only exists on recent Chrome builds (150+ behind a flag); it is absent
    // from Stable and from most system Chrome installs. The
    // `--enable-features=CanvasDrawElement` flag no-ops silently on a build that
    // doesn't implement it, so without this probe the first drawElementImage()
    // call throws `TypeError: ... is not a function` deep inside the capture
    // loop and takes the whole render down instead of falling back (HF#2060).
    // Cheap (no paint-wait) and must run before any other drawElement work.
    // Not gated by forceDE (HF_FORCE_DRAWELEMENT, an R&D knob that bypasses the
    // quality gates below to measure raw damage) — there's no "forced but
    // degraded" mode for a method that doesn't exist, only a crash, so this
    // always routes to the fallback instead.
    const supportsDrawElement = await page.evaluate(() => {
      const c = document.createElement("canvas");
      const ctx = c.getContext("2d");
      return (
        typeof (ctx as unknown as { drawElementImage?: unknown })?.drawElementImage === "function"
      );
    });
    if (!supportsDrawElement) {
      session.deGateReason = "unsupported_chrome";
      session.deFallbackTrigger = "unsupported_chrome";
      console.log(
        `[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
          "this Chrome build does not implement canvas.drawElementImage (Dev/Canary-only " +
          "feature); run `hyperframes browser ensure --force` to fetch a supported " +
          "build, or set HYPERFRAMES_BROWSER_PATH to one.",
      );
      await routeToFallback();
      return;
    }
    // ffmpeg-psnr preflight: the disk-sample self-verify path
    // (parallelCoordinator's psnrForDiskSample → psnrDb) shells to
    // `ffmpeg -lavfi psnr`. When the resident ffmpeg is missing or was built
    // without libpostproc, every per-sample compare throws and
    // psnrForDiskSample swallows the error — the safety net silently fails
    // open. Force-fallback to the reliable capture path so the safety net
    // for drawElement isn't the one thing standing between a compositor bug
    // and a shipped video. Skipped under HF_FORCE_DRAWELEMENT (matches the
    // policy of every other gate below).
    if (!forceDE && !(await isPsnrFilterAvailable())) {
      session.deGateReason = "ffmpeg_no_psnr_filter";
      session.deFallbackTrigger = "ffmpeg_no_psnr_filter";
      console.warn(
        `[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
          "host ffmpeg is missing or was built without the `psnr` filter " +
          "(libpostproc), so drawElement self-verification cannot run. Install " +
          "an ffmpeg build that includes libpostproc (or set HYPERFRAMES_FFMPEG_PATH " +
          "to one) to re-enable fast capture.",
      );
      await routeToFallback();
      return;
    }
    // SwiftShader gate: drawElement's only advantage is skipping the GPU→CPU
    // screenshot-readback IPC. On a software rasterizer (Docker/CI, no GPU) both
    // paths block on identical software raster, so drawElement is parity-or-slower
    // — route to the platform baseline.
    //
    // Two gates were REMOVED here once Chrome 151 fixed crbug 521861819
    // (drawElementImage dropped compositor-promoted opacity layers mid-fade):
    //   - the <video> gate (a proxy for the word-by-word caption opacity pattern,
    //     Lim 2), and
    //   - the stacked-fade gate (>=2 overlapping viewport-scale opacity-fade targets).
    // Both reproduced on Chrome <=150 (video+caption-fade ~12 dB; stacked fade
    // 24.5 dB) and both render correctly on 151 (verified: video+nested-fade repro
    // PSNR=inf; efb59c5b 24.5→47.4 dB, 0 damaged frames). 151 is the pinned floor.
    const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent);
    if (mode === "screenshot") {
      session.deGateReason = "swiftshader";
      session.deFallbackTrigger = "swiftshader";
      // Fall back to the browser's LAUNCH mode, not unconditionally to
      // "screenshot": on a BeginFrame-launched browser (Linux fast capture)
      // Page.captureScreenshot hangs for the full protocol timeout, while
      // beginFrameCapture is the platform's normal baseline path.
      console.log(
        `[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
          "SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
          "parity-or-slower; see fast-capture-limitations.md)",
      );
      await routeToFallback();
    } else {
      // CSS-effect gate: backdrop-filter samples the compositor backdrop and
      // filter:blur/drop-shadow render differently through the paint-record
      // path — drawElementImage can't reproduce either, producing 18–49 dB
      // damaged frames (community eval). Fall back to the platform baseline.
      // HF_FAST_CAPTURE_CSSFX=true bypasses for R&D.
      if (!forceDE && process.env.HF_FAST_CAPTURE_CSSFX !== "true") {
        const cssFx = await detectCssEffectRisk(page);
        if (cssFx) {
          session.deGateReason = `css_effect:${(cssFx.split(":")[0] ?? "").replace(/[^a-z-]/gi, "")}`;
          // Full specific effect from `detectCssEffectRisk` (e.g. "filter:blur",
          // "mix-blend-mode", "webgl-context") — `deGateReason` keeps its
          // low-cardinality prefix, `deFallbackTrigger` the full value.
          session.deFallbackTrigger = cssFx;
          console.log(
            `[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
              `${cssFx} detected (drawElementImage cannot reproduce it; see fast-capture-limitations.md)`,
          );
          await routeToFallback();
          return;
        }
      }
      // Lim 7: timeline-interval at-risk predictor. Walk window.__timelines and
      // find tweens animating compositor-incompatible props (opacity, filter,
      // blend-mode, 3D transform, clip-path, mask). drawElementImage drops these
      // mid-animation (crbug 521861819 et al), and whether it drops a given one
      // cannot be told reliably without rendering (jump-seek != sequential render,
      // proven 2026-06-16) nor from geometry (size is a proxy, not the mechanism).
      // The only deterministic + reliable route to 0 damage is to gate on the
      // PRESENCE of any such tween — a pure fact of the declared timeline, the same
      // every run. Conservative by design: comps whose risky tweens drawElement
      // would have handled also fall back, but correctness is never at risk and the
      // fast path stays open for static + plain-2D-transform comps (x/y/scale are
      // NOT in the at-risk set). Tune the gate's frame-fraction floor with
      // HF_FAST_CAPTURE_INTERVAL_FRACTION (default 0 = any at-risk frame gates).
      // Must run BEFORE canvas injection so a whole-comp fallback doesn't leave the
      // drawElement canvas wrapping the composition root. Disable with
      // HF_FAST_CAPTURE_INTERVAL_SS=false.
      if (!forceDE && process.env.HF_FAST_CAPTURE_INTERVAL_SS !== "false") {
        const fps = fpsToNumber(session.options.fps);
        const { frames: atRisk, totalFrames } = await computeTimelineAtRiskFrames(page, fps);
        const atRiskFraction = atRisk.size / totalFrames;
        const fractionFloor = Number(process.env.HF_FAST_CAPTURE_INTERVAL_FRACTION ?? "0");
        logInitPhase(
          `timeline at-risk predictor: ${atRisk.size}/${totalFrames} frames (${Math.round(atRiskFraction * 100)}%)`,
        );
        if (atRisk.size > 0 && atRiskFraction > fractionFloor) {
          session.deGateReason = "at_risk_timeline";
          session.deFallbackTrigger = "at_risk_timeline";
          console.log(
            `[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
              `${atRisk.size}/${totalFrames} frames animate a compositor-incompatible prop ` +
              `(blend/3D/clip/mask); drawElementImage drops these mid-animation ` +
              `(deterministic timeline gate; see fast-capture-limitations.md Lim 7)`,
          );
          await routeToFallback();
          return;
        }
      }
      // Rewrite CSS 3D contexts into WebGL-projected canvases BEFORE the
      // layoutsubtree canvas goes in (rects are measured in normal layout).
      // drawElementImage cannot paint 3D rendering contexts — see
      // threeDProjection.ts. No-op for compositions without 3D content.
      const threeD = await initThreeDProjection(page);
      if (!forceDE && !threeD.ok) {
        session.deGateReason = "3d_init_failed";
        session.deFallbackTrigger = "3d_init_failed";
        console.log(
          `[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
            `3D projection init failed (${threeD.reason ?? "unknown"})`,
        );
        await routeToFallback();
        return;
      }
      if (threeD.groups > 0) {
        logInitPhase(
          `3D projection active: ${threeD.groups} context(s), ${threeD.quads} quad(s), ` +
            `${threeD.selfQuads ?? 0} self-quad el(s), ${threeD.stubTargets ?? 0} stub target(s)`,
        );
      }
      // Task B: arm static-frame dedup here — drawElement is confirmed (all gates
      // passed) and the DOM is still normal (canvas not yet injected, so the
      // verification screenshots are valid). drawElement-path only; see armStaticDedup.
      await armStaticDedup(session, page, logInitPhase);
      // Video comps on injector-less sessions (probe sessions initialize before
      // video extraction) DEFER the rest of the drawElement init: ground-truth
      // screenshots would capture black <video> boxes, and once the canvas is
      // injected they can never be retaken. The capture stage completes the
      // init after prepareCaptureSessionForReuse attaches the injector.
      if (!session.onBeforeCapture && !forceDE) {
        const hasVideos = await page.evaluate(() => document.querySelector("video") !== null);
        if (hasVideos) {
          session.deInitDeferred = true;
          logInitPhase("drawElement init deferred: video comp awaiting frame injector");
          return;
        }
      }
      await finalizeDrawElementInit(session, page, logInitPhase, { transparent, forceDE });
    }
  } else if (session.options.format === "png") {
    await initTransparentBackground(session.page);
  }
}

/**
 * The tail of drawElement init: self-verification ground truth (pre-injection),
 * canvas injection, capture-mode flip, clip-boundary predictor, worker-encode.
 * Runs inline when the session already has its video-frame injector (or the
 * comp has no videos); runs deferred via completeDeferredDrawElementInit for
 * probe-initialized video comps.
 */
async function finalizeDrawElementInit(
  session: CaptureSession,
  page: Page,
  logInitPhase: (phase: string) => void,
  opts: { transparent: boolean; forceDE: boolean },
): Promise<void> {
  const { transparent, forceDE } = opts;
  // Install the page-local decoder before batch drawElement capture begins;
  // the batch loop re-runs it after every in-page seek.
  await decodeDynamicCssBackgroundImages(page);
  // Self-verification ground truth: must run pre-injection — after the canvas
  // wraps the root, a page screenshot shows the canvas's last-drawn bitmap,
  // not the live DOM (see the Lim 6 boundary-screenshot note).
  {
    const verifyStart = Date.now();
    await captureDeVerificationFrames(session, page, logInitPhase);
    session.deVerifyInitMs = Date.now() - verifyStart;
  }
  await injectDrawElementCanvas(page, session.options.width, session.options.height);
  if (transparent) {
    await initTransparentBackground(session.page);
  }
  session.captureMode = "drawelement";
  session.drawElementReady = true;
  logInitPhase("drawElement canvas injected");
  // Lim 6: clip-cut boundary frames — screenshot these instead of drawElement.
  if (process.env.HF_FAST_CAPTURE_BOUNDARY_SS !== "false" && !forceDE) {
    const fps = fpsToNumber(session.options.fps);
    const boundaryFrames = await computeClipBoundaryFrames(page, fps);
    if (boundaryFrames.size > 0) {
      session.clipBoundaryFrames = boundaryFrames;
      logInitPhase(`screenshot fallback: ${boundaryFrames.size} clip-boundary frame(s)`);
    }
  }
  // Worker-encode pipeline: macOS hardware GPU path only (syncToPaintEvent=true,
  // beginFrameTimeTicks=0). Skip for BeginFrame (Linux/Docker) and transparent
  // (PNG) output — those use the existing synchronous path unchanged.
  const workerEncodeEnabled =
    (session.config?.enableDrawElementWorkerEncode ?? false) &&
    !transparent &&
    session.beginFrameTimeTicks === 0;
  if (workerEncodeEnabled) {
    await initDrawElementWorkerEncode(page);
    session.workerEncodeEnabled = true;
    logInitPhase("drawElement worker encode initialized");
  }
}

/**
 * Complete a deferred drawElement init (see CaptureSession.deInitDeferred).
 * Call after prepareCaptureSessionForReuse has attached the video-frame
 * injector; no-op when the session is not deferred or still has no injector.
 */
export async function completeDeferredDrawElementInit(session: CaptureSession): Promise<void> {
  if (!session.deInitDeferred || !session.onBeforeCapture) return;
  const page = session.page;
  const logInitPhase = (phase: string) =>
    console.log(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
  await finalizeDrawElementInit(session, page, logInitPhase, {
    transparent: session.options.format === "png",
    forceDE: process.env.HF_FORCE_DRAWELEMENT === "1",
  });
  session.deInitDeferred = false;
}

// fallow-ignore-next-line unit-size
export async function createCaptureSession(
  serverUrl: string,
  outputDir: string,
  options: CaptureOptions,
  onBeforeCapture: BeforeCaptureHook | null = null,
  config?: Partial<EngineConfig>,
): Promise<CaptureSession> {
  if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });

  // Determine capture mode before building args — BeginFrame flags only apply on Linux.
  // BeginFrame's compositor does not preserve alpha; callers that pass
  // `options.format === "png"` for transparent capture should also set
  // `config.forceScreenshot = true` (the producer's renderOrchestrator does this
  // automatically when `RenderConfig.format` is an alpha-capable value).
  // Exception: `useDrawElement=true` with png self-manages the screenshot-browser
  // requirement (both the SwiftShader fallback and the GPU transparent path need
  // a screenshot-launched browser — the SwiftShader path calls Page.captureScreenshot
  // which hangs on a BeginFrame browser, and the GPU path doesn't need BeginFrame
  // because the compositor runs freely on a screenshot-launched browser).
  const headlessShell = resolveHeadlessShellPath(config);
  const isLinux = process.platform === "linux";
  const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
  const useDrawElement = config?.useDrawElement ?? false;
  const drawElementTransparent = useDrawElement && options.format === "png";
  // drawElement and page-side shader compositing are mutually incompatible
  // capture strategies: drawElement reads the composition root's paint records
  // directly and skips the prepare→micro-screenshot→resolve protocol (the
  // micro-screenshot would also hang on an opaque/beginframe-launched browser).
  // `resolveConfig` forces page-side compositing off whenever useDrawElement is
  // set, so this only trips for a direct caller that bypassed resolveConfig and
  // passed both flags — warn once and treat page-side as disabled.
  if (
    useDrawElement &&
    (config?.enablePageSideCompositing ?? DEFAULT_CONFIG.enablePageSideCompositing)
  ) {
    console.warn(
      "[engine] useDrawElement is incompatible with page-side shader compositing, " +
        "ignoring enablePageSideCompositing for this render. Prefer resolveConfig, " +
        "which disables page-side compositing automatically for fast-capture renders.",
    );
  }
  // BeginFrame's screenshot does not honor a viewport `deviceScaleFactor`
  // (the captured surface is sized by the OS window in CSS pixels regardless
  // of `Emulation.setDeviceMetricsOverride`'s DPR). When supersampling we
  // need explicit clip+scale on `Page.captureScreenshot`, so fall back to
  // the screenshot path for any DPR other than 1.
  const supersampling = (options.deviceScaleFactor ?? 1) !== 1;
  const requestedGpuMode = config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode;
  const resolvedGpuMode = await resolveBrowserGpuMode(requestedGpuMode, {
    chromePath: headlessShell ?? undefined,
    browserTimeout: config?.browserTimeout,
  });
  // Apply the software-GPU→screenshot invariant at the concrete-resolved
  // point too — `resolveConfig` can only see the pre-resolve `browserGpuMode`
  // string, so `"auto"` that probes to software would otherwise slip through
  // and launch BeginFrame + SwiftShader (the exact combination the invariant
  // is meant to prevent). Both env and programmatic opt-outs preserved via
  // `applyConcreteGpuScreenshotClamp` (the programmatic one carried on the
  // config as `forceScreenshotExplicitlyOptedOut`, since at this point the
  // boolean `forceScreenshot === false` is otherwise ambiguous between
  // default and explicit opt-out).
  const effectiveForceScreenshot = applyConcreteGpuScreenshotClamp(
    forceScreenshot,
    resolvedGpuMode,
    config,
  );
  const preMode: CaptureMode =
    headlessShell &&
    isLinux &&
    !effectiveForceScreenshot &&
    !supersampling &&
    !drawElementTransparent
      ? "beginframe"
      : "screenshot";
  // Callers that already have the HTML pass options.requiresWebGpu; others
  // fall back to fetching the server about to be navigated to anyway. A
  // fetch failure defaults to false — the real page.goto moments later
  // still fails loudly if the server is actually down.
  const requiresWebGpu =
    options.requiresWebGpu ??
    (await fetch(`${serverUrl}/index.html`, { signal: AbortSignal.timeout(5_000) })
      .then((res) => res.text())
      .then(compositionRequiresWebGpu)
      .catch(() => false));
  const gpuConfig = { ...config, browserGpuMode: resolvedGpuMode };
  const chromeArgs = buildChromeArgs(
    { width: options.width, height: options.height, captureMode: preMode, requiresWebGpu },
    gpuConfig,
  );

  const withoutWaylandDisplay = await captureWithoutWaylandDisplay(resolvedGpuMode);
  const browserLease = await acquireBrowser(chromeArgs, { ...config, withoutWaylandDisplay });
  return constructCaptureSessionWithRollback({
    browserLease,
    serverUrl,
    outputDir,
    options,
    onBeforeCapture,
    config,
    useDrawElement,
    requiresWebGpu,
    softwareWebGpu: usesSoftwareWebGpu(requiresWebGpu, gpuConfig),
  });
}

interface CaptureSessionConstructionInput {
  browserLease: BrowserLease;
  serverUrl: string;
  outputDir: string;
  options: CaptureOptions;
  onBeforeCapture: BeforeCaptureHook | null;
  config?: Partial<EngineConfig>;
  useDrawElement: boolean;
  requiresWebGpu?: boolean;
  softwareWebGpu?: boolean;
}

async function constructCaptureSessionWithRollback(
  input: CaptureSessionConstructionInput,
): Promise<CaptureSession> {
  let page: Page | undefined;
  try {
    return await constructCaptureSession({
      ...input,
      onPageCreated: (createdPage) => {
        page = createdPage;
      },
    });
  } catch (error) {
    let pageClosed = true;
    try {
      if (page) {
        const rollbackPage = page;
        pageClosed = await waitForCloseWithTimeout(
          Promise.resolve().then(() => rollbackPage.close()),
        );
      }
    } finally {
      if (!pageClosed) {
        console.warn(
          "[FrameCapture] Timed out closing page during construction rollback; forcing browser process shutdown",
        );
        input.browserLease.forceRelease();
      } else {
        const browserClosed = await waitForCloseWithTimeout(input.browserLease.release());
        if (!browserClosed) {
          console.warn(
            "[FrameCapture] Timed out closing browser during construction rollback; forcing browser process shutdown",
          );
          input.browserLease.forceRelease();
        }
      }
    }
    throw error;
  }
}

async function constructCaptureSession(
  input: CaptureSessionConstructionInput & { onPageCreated(page: Page): void },
): Promise<CaptureSession> {
  const {
    browserLease,
    serverUrl,
    outputDir,
    options,
    onBeforeCapture,
    config,
    useDrawElement,
    requiresWebGpu,
    softwareWebGpu,
    onPageCreated,
  } = input;
  const { browser, captureMode } = browserLease;

  const page = await browser.newPage();
  onPageCreated(page);
  // Cap the existing session's inspection buffer; new sessions have separate buffers.
  const frame = page.mainFrame();
  // Frame.client is runtime-only, so keep capture working when it is absent.
  const { CDPSession } = await import("puppeteer-core");
  if ("client" in frame && frame.client instanceof CDPSession) {
    await frame.client.send("Network.enable", {
      maxTotalBufferSize: 32 * 1024 * 1024,
      maxResourceBufferSize: 16 * 1024 * 1024,
    });
  }
  // Polyfill esbuild's keepNames helper inside the page.
  //
  // The engine is published as raw TypeScript (`packages/engine/package.json`
  // points `main`/`exports` at `./src/index.ts`) and downstream consumers
  // execute it through transpilers that may inject `__name(fn, "name")`
  // wrappers around named functions. Empirically, this happens with:
  //   - tsx (its esbuild loader runs with keepNames=true), used by the
  //     producer's parity-harness, ad-hoc dev scripts, and the
  //     `bun run --filter @hyperframes/engine test` Vitest path.
  //   - any tsup/esbuild build that explicitly enables keepNames.
  //
  // The HeyGen CLI (`packages/cli`) bundles this engine via tsup with
  // keepNames left at its default (false) — verified by grepping
  // `packages/cli/dist/cli.js`, where `__name(...)` call sites are absent.
  // Bun's TS loader also does not currently inject `__name`. Even so,
  // anything that calls `page.evaluate(fn)` with a nested named function
  // under tsx (most local development and tests) will serialize bodies
  // like `__name(nested,"nested")` and crash with `__name is not defined`
  // in the browser. The shim makes such calls a no-op.
  //
  // An alternative is to load browser-side code as raw text and inject it
  // via `page.addScriptTag({ content: ... })` — see
  // `packages/cli/src/commands/contrast-audit.browser.js` for that pattern.
  // Until every `page.evaluate(fn)` call site migrates, this polyfill is
  // the single line of defense. The companion regression test in
  // `frameCapture-namePolyfill.test.ts` verifies the shim stays wired up.
  await page.evaluateOnNewDocument(() => {
    const w = window as unknown as { __name?: <T>(fn: T, _name: string) => T };
    if (typeof w.__name !== "function") {
      w.__name = <T>(fn: T, _name: string): T => fn;
    }
  });
  // Media elements are addressed by a document-unique render id, not by the
  // per-file element id. Install the resolvers before any page script runs.
  await installMediaRenderIdBridge(page);
  // Fast capture: record accelerated canvases (webgl/webgl2/webgpu) and force
  // preserveDrawingBuffer before any page script can create a context — their
  // paint records freeze at the first frame, so captureDrawElementFrame
  // composites their live content via drawImage instead (see
  // instrumentAcceleratedCanvases). Must be registered before navigation.
  if (useDrawElement) {
    await page.evaluateOnNewDocument(instrumentAcceleratedCanvases);
  }
  // The opacity → autoAlpha tween rewrite was RETIRED with the requestPaint
  // contract adoption (crbug 529829538 closed WAI): a requestPaint-driven
  // paint refreshes nested opacity layers natively, and the rewrite itself
  // measured ~28 dB of damage on comps whose fades it touched. Warn instead
  // of silently ignoring the old escape hatch.
  if (process.env.HF_FAST_CAPTURE_AUTOALPHA !== undefined) {
    console.warn(
      "[engine] HF_FAST_CAPTURE_AUTOALPHA is retired and ignored: the requestPaint " +
        "paint contract captures animated opacity natively (see drawElementService.ts).",
    );
  }
  // Re-apply the captured root's own compositor-applied props to the 2D
  // context where the snapshot does not carry them (see the correction
  // comment in drawElementService.ts drawAndEncode: transform always —
  // never baked, verified under the requestPaint contract 2026-07-07;
  // opacity ratio only on non-requestPaint paints, where the snapshot holds
  // the load-time value). On by default; disable with
  // HF_FAST_CAPTURE_ROOT_PROPS=false.
  if (useDrawElement && process.env.HF_FAST_CAPTURE_ROOT_PROPS !== "false") {
    await page.evaluateOnNewDocument(() => {
      (window as unknown as { __HF_ROOT_PROPS__?: boolean }).__HF_ROOT_PROPS__ = true;
    });
  }
  // Inject render-time variable overrides before any page script runs, so the
  // runtime helper `getVariables()` returns the merged result on its first
  // call. Pass the JSON string and parse inside the page so we don't require
  // any JSON-incompatible value to round-trip through Puppeteer's serializer.
  if (options.variables && Object.keys(options.variables).length > 0) {
    const variablesJson = JSON.stringify(options.variables);
    await page.evaluateOnNewDocument((json: string) => {
      type WindowWithVariables = Window & { __hfVariables?: Record<string, unknown> };
      try {
        (window as WindowWithVariables).__hfVariables = JSON.parse(json);
      } catch {
        // The CLI validated the JSON before this point — a parse failure here
        // means the page swapped JSON.parse, which is the page's problem.
      }
    }, variablesJson);
  }
  await installPageMotionBlur(page, options);
  const browserVersion = await browser.version();
  const sessionOptions = resolveCaptureSessionOptions(options, browserVersion);
  const expectedMajor = config?.expectedChromiumMajor;
  if (Number.isFinite(expectedMajor)) {
    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}`,
      );
    }
  }
  const viewport: Viewport = {
    width: sessionOptions.width,
    height: sessionOptions.height,
    deviceScaleFactor: sessionOptions.deviceScaleFactor || 1,
  };
  await page.setViewport(viewport);

  // Transparent-background setup is intentionally NOT done here. Chrome resets
  // the default-background-color override on navigation, and the
  // `html,body{background:transparent}` stylesheet that
  // `initTransparentBackground` injects must land in a real `document.head`.
  // See `initializeSession()` below — it calls `initTransparentBackground` for
  // PNG captures after `page.goto(...)` and the `window.__hf` readiness poll.

  return {
    browser,
    browserLease,
    page,
    options: sessionOptions,
    serverUrl,
    outputDir,
    onBeforeCapture,
    requiresWebGpu,
    softwareWebGpu,
    isInitialized: false,
    browserConsoleBuffer: [],
    scriptLoadFailures: [],
    pageErrors: [],
    subTimelineWaitMemo: sessionOptions.subTimelineWaitMemo ?? {},
    warnings: [],
    capturePerf: {
      frames: 0,
      seekMs: 0,
      beforeCaptureMs: 0,
      screenshotMs: 0,
      totalMs: 0,
      frameMs: [],
    },
    captureMode,
    launchCaptureMode: captureMode,
    beginFrameTimeTicks: 0,
    // Frame interval in ms: 1000 * den / num. For 30/1 → 33.333…, for
    // 30000/1001 (NTSC) → 33.366…. JavaScript number precision is fine at
    // these scales — no rounding required.
    beginFrameIntervalMs: (1000 * options.fps.den) / Math.max(1, options.fps.num),
    beginFrameHasDamageCount: 0,
    beginFrameNoDamageCount: 0,
    config,
  };
}

/**
 * Classify a console "Failed to load resource" error as a font-load failure.
 *
 * These are expected when deterministic font injection replaces Google Fonts
 * @import URLs with embedded base64 — or when the render environment has no
 * network access to Google Fonts. Suppressing them reduces noise in render
 * output without hiding real asset failures (images, videos, scripts, etc.).
 *
 * Chrome's `msg.text()` for a failed resource is typically just
 * `"Failed to load resource: net::ERR_FAILED"` — the URL is only on
 * `msg.location().url`. We match against both so the filter works regardless
 * of which form Chrome emits.
 */
export function isFontResourceError(type: string, text: string, locationUrl: string): boolean {
  if (type !== "error") return false;
  if (!text.startsWith("Failed to load resource")) return false;
  return /fonts\.googleapis|fonts\.gstatic|\.(woff2?|ttf|otf)(\b|$)/i.test(
    `${locationUrl} ${text}`,
  );
}

export function formatConsoleDiagnostic(
  type: string,
  text: string,
  locationUrl: string,
): { text: string; suppressHostLog: boolean } {
  const isFontLoadError = isFontResourceError(type, text, locationUrl);
  if (isFontLoadError) return { text: `[Browser] ${text}`, suppressHostLog: true };

  if (text.startsWith("[hyperframes]")) {
    return {
      text: `[HyperFrames] ${text.slice("[hyperframes]".length).trim()}`,
      suppressHostLog: false,
    };
  }

  // Other "Failed to load resource" 404s are typically non-blocking (e.g.
  // favicon, sourcemaps, optional assets). Prefix them so users know they
  // are harmless and don't confuse them with real render errors.
  const isResourceLoadError = type === "error" && text.startsWith("Failed to load resource");
  const prefix = isResourceLoadError
    ? "[non-blocking]"
    : type === "error"
      ? "[Browser:ERROR]"
      : type === "warn"
        ? "[Browser:WARN]"
        : "[Browser]";

  return { text: `${prefix} ${text}`, suppressHostLog: false };
}

export const HF_READY_DIAGNOSTIC_EXPR = `(async function() {
  var hf = window.__hf;
  var player = window.__player;
  var renderReady = !!window.__renderReady;
  var hasSeek = !!(hf && typeof hf.seek === "function");
  var duration = hf ? hf.duration : -1;
  var hasTimeline = !!(window.__timelines && Object.keys(window.__timelines).length > 0);
  var root = document.querySelector("[data-composition-id]");
  var declaredDuration = root ? Number(root.getAttribute("data-duration")) : -1;
  var registry = (window.__hf && window.__hf.buildReady) || {};
  var keys = Object.keys(registry);
  // A microtask race mis-sorts a non-native thenable (extra adoption tick)
  // and rejects the whole expression on a rejected entry. Settling each
  // key onto its own record and waiting one macrotask avoids both.
  var settled = {};
  if (keys.length > 0) {
    keys.forEach(function(key) {
      Promise.resolve(registry[key]).then(
        function() { settled[key] = "resolved"; },
        function() { settled[key] = "rejected"; },
      );
    });
    await new Promise(function(r) { setTimeout(r, 0); });
  }
  // A thenable resolving via its own setTimeout(0) can still misreport as
  // pending here (macrotask registration order, not resolution order), a
  // narrow case that self-corrects on the next ~1s diagnostic tick.
  var pendingBuildReadyKeys = keys.filter(function(key) { return !settled[key]; });
  var rejectedBuildReadyKeys = keys.filter(function(key) { return settled[key] === "rejected"; });
  return {
    renderReady: renderReady,
    hasHf: !!hf,
    hasSeek: hasSeek,
    hasPlayer: !!player,
    duration: duration,
    hasTimeline: hasTimeline,
    declaredDuration: declaredDuration,
    pendingBuildReadyKeys: pendingBuildReadyKeys,
    rejectedBuildReadyKeys: rejectedBuildReadyKeys,
  };
})()`;

export interface HfDiagnostic {
  renderReady: boolean;
  hasHf: boolean;
  hasSeek: boolean;
  hasPlayer: boolean;
  duration: number;
  hasTimeline: boolean;
  declaredDuration: number;
  pendingBuildReadyKeys: string[];
  rejectedBuildReadyKeys: string[];
}

// fallow-ignore-next-line complexity
export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string {
  const hints: string[] = [];
  if (diag.pendingBuildReadyKeys.length > 0) {
    hints.push(
      `window.__hf.buildReady never resolved for: ${diag.pendingBuildReadyKeys.join(", ")}. ` +
        "The runtime holds render-ready until every registered buildReady promise settles. " +
        "Find where the composition registers that key and confirm it actually resolves.",
    );
  }
  if (diag.rejectedBuildReadyKeys.length > 0) {
    hints.push(
      `window.__hf.buildReady rejected for: ${diag.rejectedBuildReadyKeys.join(", ")}. ` +
        "That key's build promise failed rather than hanging. Find why it rejects.",
    );
  }
  if (!diag.hasPlayer) {
    hints.push("window.__player was never set: the HyperFrames runtime did not initialize.");
  }
  if (!diag.hasTimeline) {
    hints.push(
      "No GSAP timeline registered (window.__timelines is empty). " +
        "CSS/WAAPI/Lottie animations are usually auto-detected (the runtime infers " +
        "duration from the longest running animation), but this composition's duration " +
        "could not be inferred, which usually means an infinite/unbounded animation " +
        "(e.g. animation-iteration-count: infinite, repeat: -1 WAAPI, or a looping Lottie " +
        "clip) or a Three.js scene with no discoverable AnimationClip.",
    );
  }
  if (diag.declaredDuration <= 0 && !diag.hasTimeline) {
    hints.push(
      'Fix: add data-duration="<seconds>" to your root <div data-composition-id="..."> element.',
    );
  }
  if (diag.hasSeek && diag.duration === 0 && diag.renderReady) {
    hints.push("The runtime finished initializing but reported zero duration. This is permanent.");
  }
  return (
    `[FrameCapture] Composition has zero duration.\n` +
    `  Runtime ready: ${diag.renderReady}, __player: ${diag.hasPlayer}, ` +
    `__hf.seek: ${diag.hasSeek}, GSAP timeline: ${diag.hasTimeline}, ` +
    `data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` +
    (hints.length > 0 ? hints.map((h) => `  → ${h}`).join("\n") : "")
  );
}

async function evaluateHfDiagnostic(page: Page): Promise<HfDiagnostic> {
  return (await page.evaluate(HF_READY_DIAGNOSTIC_EXPR)) as HfDiagnostic;
}

export async function pollHfReady(
  page: Page,
  timeoutMs: number,
  intervalMs: number = 100,
): Promise<void> {
  const readyExpr = `!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)`;
  const FAST_FAIL_AFTER_MS = 10_000;
  // Throttle diagnostic CDP calls to ~1000ms — running evaluateHfDiagnostic on
  // every 100ms poll tick after the 10s mark generates ~350 unnecessary CDP
  // round-trips per failed render. One diagnostic per second is enough.
  const DIAGNOSTIC_INTERVAL_MS = 1_000;
  const deadline = Date.now() + timeoutMs;
  let lastDiagnosticAt = 0;

  while (Date.now() < deadline) {
    const state = await page.evaluate(
      `typeof window.__hfStartupError === "string" ? window.__hfStartupError : ${readyExpr}`,
    );
    if (typeof state === "string") throw new Error(state);
    if (state) return;

    const elapsed = timeoutMs - (deadline - Date.now());
    if (elapsed >= FAST_FAIL_AFTER_MS) {
      const now = Date.now();
      if (now - lastDiagnosticAt >= DIAGNOSTIC_INTERVAL_MS) {
        lastDiagnosticAt = now;
        const diag = await evaluateHfDiagnostic(page);
        // Only fast-fail when ALL signals are permanently zero:
        //   1. No GSAP timeline registered (GSAP sets duration synchronously
        //      before __renderReady, so a missing timeline won't self-correct).
        //   2. No data-duration declared on the root element.
        //   3. hf.duration is still 0 — this also covers CSS/WAAPI/Lottie
        //      auto-inference (see runtime/init.ts resolveAdapterDurationFloorSeconds):
        //      those runtimes report a non-zero hf.duration once discovery
        //      resolves, without any GSAP timeline or data-duration. Checking
        //      hf.duration directly (rather than only the two authored
        //      signals) avoids fast-failing a composition whose inferred
        //      duration just hasn't landed yet.
        // A composition with a GSAP timeline but no data-duration is still
        // valid — GSAP drives duration via __timelines, not data-duration.
        if (
          diag.renderReady &&
          diag.hasSeek &&
          !diag.hasTimeline &&
          diag.declaredDuration <= 0 &&
          diag.duration <= 0
        ) {
          throw new Error(buildZeroDurationDiagnostic(diag));
        }
      }
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  const diag = await evaluateHfDiagnostic(page);
  if (diag.hasSeek && diag.duration === 0) {
    throw new Error(buildZeroDurationDiagnostic(diag));
  }
  throw new Error(
    `[FrameCapture] window.__hf not ready after ${timeoutMs}ms. ` +
      `Page must expose window.__hf = { duration, seek }.\n` +
      `  State: __hf=${diag.hasHf}, seek=${diag.hasSeek}, player=${diag.hasPlayer}, ` +
      `renderReady=${diag.renderReady}, duration=${diag.duration}`,
  );
}

// Enumerated regardless of bail reason, so the warning names every composition still
// waited on, not only a failed script URL.
async function listUnregisteredTimelineIds(page: Page): Promise<string[]> {
  const evaluated = await page.evaluate(`(function() {
    var hosts = document.querySelectorAll("[data-composition-id]");
    var timelines = window.__timelines || {};
    var m = [];
    for (var i = 0; i < hosts.length; i++) {
      if (hosts[i].hasAttribute("data-no-timeline")) continue;
      var id = hosts[i].getAttribute("data-composition-id");
      if (id && !timelines[id]) m.push(id);
    }
    return m;
  })()`);
  // Builds a warning, so it must never throw: normalise a loosely typed result.
  return Array.isArray(evaluated) ? evaluated.map((id) => String(id)) : [];
}

export async function waitForSubCompositionTimelines(
  session: CaptureSession,
  page: Page,
  timeoutMs: number,
): Promise<void> {
  const memo = session.subTimelineWaitMemo;
  session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, timeoutMs, {
    getScriptLoadFailures: () => session.scriptLoadFailures,
    onPending: (ids) => {
      session.pendingTimelineIds = [...ids];
    },
    shouldStop: () => session.vfxFailure !== undefined,
    knownUnregisteredIds: memo.unregisteredIds,
  });
  // Only a clean full-length timeout is replayed: a VFX stop ends early, and page or script
  // errors must reach each session so it can still classify the wait as a script failure.
  const cleanTimeout =
    session.subTimelineWaitOutcome === "timeout" &&
    session.vfxFailure === undefined &&
    session.pageErrors.length === 0 &&
    session.scriptLoadFailures.length === 0;
  if (cleanTimeout) {
    memo.unregisteredIds = session.pendingTimelineIds ?? [];
  }
}

export interface SubTimelinePollOptions {
  intervalMs?: number;
  // Fail-fast: a script resource that failed to load can never register its timeline,
  // so once failures exist the poll ends `scriptFailureGraceMs` after it started.
  getScriptLoadFailures?: () => readonly string[];
  scriptFailureGraceMs?: number;
  // Receives the ids still unregistered at bail time, for the structured warning.
  onPending?: (ids: readonly string[]) => void;
  // Ends the wait at once; the caller then fails the render for its own reason.
  shouldStop?: () => boolean;
  // Ids an earlier session of this render already timed out on: not waited for again.
  knownUnregisteredIds?: readonly string[];
}

export async function pollSubCompositionTimelines(
  page: Page,
  timeoutMs: number,
  {
    intervalMs = 150,
    getScriptLoadFailures,
    scriptFailureGraceMs = 2_000,
    onPending,
    shouldStop,
    knownUnregisteredIds = [],
  }: SubTimelinePollOptions = {},
): Promise<SubTimelineWaitOutcome> {
  // Hosts may opt out of the timeline wait with `data-no-timeline` —
  // compositions driven purely by CSS animations / rAF (the render-compat
  // contract) never register window.__timelines[id], and without the opt-out
  // they stall here for the full playerReadyTimeout (45 s) on every render.
  const expression = `(function() {
    var hosts = document.querySelectorAll("[data-composition-id]");
    if (hosts.length === 0) return true;
    var timelines = window.__timelines || {};
    var known = ${JSON.stringify(knownUnregisteredIds)};
    for (var i = 0; i < hosts.length; i++) {
      if (hosts[i].hasAttribute("data-no-timeline")) continue;
      var id = hosts[i].getAttribute("data-composition-id");
      if (!id || known.indexOf(id) !== -1) continue;
      if (!timelines[id]) return false;
    }
    return true;
  })()`;
  const start = Date.now();
  const deadline = start + timeoutMs;
  let ready = false;
  let scriptFailureBail = false;
  for (;;) {
    ready = Boolean(await page.evaluate(expression));
    if (ready || shouldStop?.()) break;
    const now = Date.now();
    if (now >= deadline) break;
    const failures = getScriptLoadFailures?.() ?? [];
    if (failures.length > 0 && now - start >= scriptFailureGraceMs) {
      scriptFailureBail = true;
      console.warn(
        `[FrameCapture] Sub-composition timeline wait cut short after ${now - start}ms: ` +
          `script resource(s) failed to load (${failures.join(", ")}), so ` +
          `the timeline registration they carry can never arrive. ` +
          `Fix the script reference; the render proceeds without those animations.`,
      );
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  // Skipped known ids still count: if one is still unregistered, report the timeout again.
  const pendingIds =
    ready && knownUnregisteredIds.length === 0 ? [] : await listUnregisteredTimelineIds(page);
  if (ready && pendingIds.length > 0 && (getScriptLoadFailures?.() ?? []).length > 0) {
    scriptFailureBail = true;
  }
  // Always force a timeline rebind once sub-composition timelines are
  // confirmed present. The previous implementation only called rebind
  // when the timeline count grew during the poll, which missed the case
  // where all sub-comp scripts had already executed before the poll
  // started — leaving child timelines un-nested in the root and causing
  // the earliest sub-composition (data-start near 0) to render without
  // its GSAP animations.
  if (ready && pendingIds.length === 0) {
    await page.evaluate(`(function() {
      if (typeof window.__hfForceTimelineRebind === "function") {
        window.__hfForceTimelineRebind();
      }
    })()`);
    return "ready";
  }
  onPending?.(pendingIds);
  const missing = pendingIds.join(", ");
  if (scriptFailureBail) {
    console.warn(`[FrameCapture] Composition(s) still waiting on the failed script: ${missing}.`);
  } else {
    console.warn(
      `[FrameCapture] Sub-composition timelines not registered after ${timeoutMs}ms: ${missing}. ` +
        `Compositions that load data asynchronously (e.g. fetch) must register window.__timelines[id] after setup completes. ` +
        `Compositions intentionally driven without GSAP timelines (CSS animations / rAF) can mark the host with data-no-timeline to skip this wait.`,
    );
  }
  return scriptFailureBail ? "script_failure" : "timeout";
}

async function pollVideosReady(
  page: Page,
  skipIds: readonly string[],
  timeoutMs: number,
  intervalMs: number = 100,
): Promise<boolean> {
  const check = async (): Promise<boolean> => {
    return Boolean(
      await page.evaluate((skipIdList: readonly string[]) => {
        const skip = new Set(skipIdList);
        const vids = Array.from(document.querySelectorAll("video")).filter((v) => !skip.has(v.id));
        return (
          vids.length === 0 ||
          vids.every((v) => {
            const ve = v as HTMLVideoElement;
            if (ve.readyState >= 2) return true;
            if (ve.error) return true;
            if (ve.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) return true;
            return false;
          })
        );
      }, skipIds),
    );
  };
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if (await check()) return true;
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  return check();
}

// Wait for every `<img>` with a non-`data:` src to have settled — either
// successfully loaded (`complete && naturalWidth > 0`) or failed with a
// broken-image marker (`complete && naturalWidth === 0`, the HTMLImageElement
// equivalent of HTMLMediaElement.error). htmlCompiler localises remote `<img>`
// URLs to the local file server before this point, so in practice this polls
// for the local fetch to land — but the guard is a defensive net so that any
// future composition path that leaves a remote URL in place won't capture
// frames before the pixels arrive. Mirrors `pollVideosReady` for parity with
// the video-side readiness contract (videos exit-early on `ve.error`; images
// exit-early on `complete && naturalWidth === 0`).
/** @internal exported for unit testing only */
export async function pollImagesReady(
  page: Page,
  timeoutMs: number,
  intervalMs: number = 100,
): Promise<boolean> {
  const check = async (): Promise<boolean> => {
    return Boolean(
      await page.evaluate(() => {
        const imgs = Array.from(document.querySelectorAll("img"));
        return (
          imgs.length === 0 ||
          imgs.every((img) => {
            const ie = img as HTMLImageElement;
            const src = ie.getAttribute("src") || "";
            if (!src || src.startsWith("data:")) return true;
            // A `complete` image with zero naturalWidth has settled with an
            // error (404 / decode failure / CORS rejection / blocked). Treat
            // as done — waiting won't make it load — and let the render
            // continue with the broken-image marker visible. Mirrors how
            // pollVideosReady treats `ve.error`.
            if (ie.complete && ie.naturalWidth === 0) return true;
            if (ie.complete && ie.naturalWidth > 0) return true;
            return false;
          })
        );
      }),
    );
  };
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if (await check()) return true;
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  return check();
}

export async function waitForImagesReady(
  page: Page,
  timeoutMs: number,
  onUnloaded: (sources: string) => void,
): Promise<boolean> {
  const ready = await pollImagesReady(page, timeoutMs);
  if (!ready) {
    onUnloaded(
      await page.evaluate(() =>
        Array.from(document.querySelectorAll("img"))
          .filter((img) => {
            const src = img.getAttribute("src") || "";
            if (!src || src.startsWith("data:")) return false;
            return !(img.complete && img.naturalWidth > 0);
          })
          .map((img) => img.src || img.getAttribute("src") || "(no src)")
          .join(", "),
      ),
    );
  }
  await decodeAllImages(page);
  return ready;
}

type MediaReadinessSnapshot = {
  pendingImages: string[];
  failedImages: string[];
  pendingVideos: string[];
  failedVideos: string[];
};

/** @internal exported for contract testing. */
export async function collectMediaReadinessWarnings(
  page: Page,
  skipIds: readonly string[],
  timeoutMs: number,
): Promise<CaptureWarning[]> {
  const snapshot = await page.evaluate((skipIdList: readonly string[]): MediaReadinessSnapshot => {
    const skipped = new Set(skipIdList);
    const result: MediaReadinessSnapshot = {
      pendingImages: [],
      failedImages: [],
      pendingVideos: [],
      failedVideos: [],
    };

    for (const img of document.querySelectorAll("img")) {
      const src = img.getAttribute("src") || "";
      if (!src || src.startsWith("data:")) continue;
      if (!img.complete) result.pendingImages.push(img.src || src);
      else if (img.naturalWidth <= 0) result.failedImages.push(img.src || src);
    }

    // Browser media readiness is a frame-capture requirement only for video.
    // Audio is extracted and mixed out of band by the producer, so an idle
    // DOM <audio> element can legitimately remain at HAVE_NOTHING here. The
    // producer reports actual extraction/mix failures as audio_processing_failed.
    for (const media of document.querySelectorAll("video")) {
      const mediaElement = media as HTMLMediaElement;
      if (skipped.has(mediaElement.id)) continue;
      const src = mediaElement.currentSrc || mediaElement.getAttribute("src") || "(no src)";
      const failed =
        Boolean(mediaElement.error) ||
        mediaElement.networkState === HTMLMediaElement.NETWORK_NO_SOURCE;
      const pending = !failed && mediaElement.readyState < HTMLMediaElement.HAVE_CURRENT_DATA;
      if (failed) result.failedVideos.push(src);
      else if (pending) result.pendingVideos.push(src);
    }
    return result;
  }, skipIds);

  const warnings: CaptureWarning[] = [];
  const append = (
    code: CaptureWarning["code"],
    mediaType: "image" | "video" | "audio",
    sources: string[],
  ) => {
    if (sources.length === 0) return;
    const timedOut = code === "media_readiness_timeout";
    warnings.push({
      code,
      message: timedOut
        ? `${mediaType} media did not become capture-ready within ${timeoutMs}ms`
        : `${mediaType} media failed to load before capture`,
      details: { mediaType, sources: [...new Set(sources)].sort(), timeoutMs },
    });
  };
  append("media_readiness_timeout", "image", snapshot.pendingImages);
  append("media_load_failed", "image", snapshot.failedImages);
  append("media_readiness_timeout", "video", snapshot.pendingVideos);
  append("media_load_failed", "video", snapshot.failedVideos);
  return warnings;
}

function recordCaptureWarnings(session: CaptureSession, warnings: readonly CaptureWarning[]): void {
  for (const warning of warnings) {
    const key = `${warning.code}:${JSON.stringify(warning.details ?? {})}`;
    if (
      session.warnings.some(
        (existing) => `${existing.code}:${JSON.stringify(existing.details ?? {})}` === key,
      )
    ) {
      continue;
    }
    session.warnings.push(warning);
    console.warn(`[FrameCapture:${warning.code}] ${warning.message}`, warning.details ?? {});
  }
}

export function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): void {
  const outcome = session.subTimelineWaitOutcome;
  if (outcome === "ready" || !outcome) return;
  const threwThenTimedOut = outcome === "timeout" && session.pageErrors.length > 0;
  const scriptFailure = outcome === "script_failure" || threwThenTimedOut;
  const sources = [...session.scriptLoadFailures, ...session.pageErrors];
  const pending = session.pendingTimelineIds ?? [];
  const pendingSuffix = pending.length > 0 ? ` (still unregistered: ${pending.join(", ")})` : "";
  recordCaptureWarnings(session, [
    {
      code: scriptFailure ? "sub_timeline_script_failure" : "sub_timeline_readiness_timeout",
      message: threwThenTimedOut
        ? `A composition script threw and a timeline did not register within ${timeoutMs}ms` +
          `${pendingSuffix} (${sources.join(", ")}). Fix the error; a composition animated by ` +
          `CSS or rAF rather than a GSAP timeline must mark its host with data-no-timeline.`
        : scriptFailure
          ? `A sub-composition timeline script failed to load (${sources.join(", ")})`
          : `Sub-composition timelines did not become ready within ${timeoutMs}ms${pendingSuffix}. ` +
            `This can be intentional: a composition driven by CSS animations or rAF never registers ` +
            `window.__timelines[id], and marking its host with data-no-timeline skips the wait entirely. ` +
            `Otherwise, a composition that sets up asynchronously must register window.__timelines[id] ` +
            `once setup completes.`,
      details: {
        timeoutMs,
        sources,
        pendingCompositionIds: [...pending],
      },
    },
  ]);
}

/**
 * Runtime-mounted map-viewport markers, keyed by the CSS selector each map
 * library stamps on its live container. Selector presence means an actual map
 * INSTANCE is rendering in the page — not merely that a map library script
 * loaded — which keeps false positives low (a baked map video carries none of
 * these).
 */
const LIVE_MAP_MARKERS: ReadonlyArray<{ selector: string; library: string }> = [
  { selector: ".leaflet-container", library: "Leaflet" },
  { selector: ".maplibregl-map", library: "MapLibre GL" },
  { selector: ".mapboxgl-map", library: "Mapbox GL" },
  { selector: ".gm-style", library: "Google Maps" },
  { selector: ".ol-viewport", library: "OpenLayers" },
];

/**
 * Build the `live_map_detected` warning for the detected map libraries.
 * A live tile map violates the deterministic-render contract (tiles are
 * render-time network fetches): none of the readiness polls cover late-added
 * tile images or map canvases, so frames captured before tiles arrive ship a
 * blank/partial map with no error — the render exits success. Wild signature:
 * PRINFRA-300 (blank hook scene, zero diagnostics, "fixed" by re-render).
 */
export function buildLiveMapWarning(libraries: readonly string[]): CaptureWarning {
  return {
    code: "live_map_detected",
    message:
      `Live map viewport(s) detected in the composition (${libraries.join(", ")}). ` +
      `Map tiles load over the network at render time, which the deterministic-render ` +
      `contract forbids: frames captured before tiles arrive ship a blank or partial map ` +
      `with no error. Bake the map to a video first (the hyperframes skill's ` +
      `scripts/bake-basemap.mjs, see references/film.md) and use the baked file as the imagery layer.`,
    details: { sources: [...libraries] },
  };
}

/** Detect live map viewports in the page and record the warning. */
async function recordLiveMapWarning(session: CaptureSession, page: Page): Promise<void> {
  const libraries = (await page.evaluate(
    (markers: ReadonlyArray<{ selector: string; library: string }>) =>
      markers.filter((m) => document.querySelector(m.selector) !== null).map((m) => m.library),
    LIVE_MAP_MARKERS,
  )) as string[];
  if (libraries.length === 0) return;
  recordCaptureWarnings(session, [buildLiveMapWarning(libraries)]);
}

// Force every successfully-loaded `<img>` to be GPU-uploaded before the first
// frame capture. `naturalWidth > 0` means the bitmap has been decoded into
// CPU memory, but compositor-side GPU upload can still happen lazily on first
// paint. Calling `img.decode()` returns a Promise that resolves once the image
// is ready for synchronous painting — eliminating the small first-frame race
// between "image is technically loaded" and "the rasterized texture is on the
// GPU and ready to composite".
//
// Note this is purely an init-time guard; it doesn't prevent Chrome from
// evicting decoded pixels mid-render. The producer-side `localizeRemoteImageSources`
// is what bounds the eviction risk (a re-fetch hits the local file server's
// disk-backed paging, not S3 over the network).
//
// Critical: `decode()` on an in-flight image waits for the fetch to resolve.
// If `pollImagesReady` timed out with some images still loading (`!complete`),
// calling `decode()` on them would block here until the network finally
// completes — or until puppeteer's evaluate timeout fires and throws an
// uncaught error that aborts the render. Skip in-flight and broken images;
// only force GPU upload for images that successfully loaded.
async function decodeAllImages(page: Page): Promise<void> {
  await page.evaluate(async () => {
    const imgs = Array.from(document.querySelectorAll("img"));
    await Promise.all(
      imgs.map((img) => {
        const ie = img as HTMLImageElement;
        if (typeof ie.decode !== "function") return Promise.resolve();
        // Skip still-loading images (in-flight decode() would hang) and
        // broken images (decode() rejects, but pre-filtering is clearer
        // than relying on the .catch).
        if (!ie.complete || ie.naturalWidth === 0) return Promise.resolve();
        return ie.decode().catch(() => undefined);
      }),
    );
  });
}

export async function applyVideoMetadataHints(
  page: Page,
  hints: readonly CaptureVideoMetadataHint[] | undefined,
): Promise<void> {
  if (!hints || hints.length === 0) return;

  // fallow-ignore-next-line complexity
  await page.evaluate(
    async (metadataHints: CaptureVideoMetadataHint[]) => {
      const posters = new Set<string>();
      for (const hint of metadataHints) {
        if (
          !hint.id ||
          !Number.isFinite(hint.width) ||
          !Number.isFinite(hint.height) ||
          hint.width <= 0 ||
          hint.height <= 0
        ) {
          continue;
        }

        const video = (window.__hfMediaEl?.(hint.id) ??
          document.getElementById(hint.id)) as HTMLVideoElement | null;
        if (!video || video.hasAttribute("poster")) continue;

        const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${hint.width}" height="${hint.height}"/>`;
        const intrinsicSizePoster = `data:image/svg+xml,${encodeURIComponent(svg)}`;
        video.poster = intrinsicSizePoster;
        posters.add(intrinsicSizePoster);
      }
      await Promise.all(
        [...posters].map((src) => {
          const image = new Image();
          image.src = src;
          return image.decode();
        }),
      );
    },
    [...hints],
  );
}

async function waitForOptionalTailwindReady(page: Page, timeoutMs: number): Promise<void> {
  const hasTailwindReady = await page.evaluate(
    `(() => { const ready = window.__tailwindReady; return !!ready && typeof ready.then === "function"; })()`,
  );
  if (!hasTailwindReady) return;

  const ready = await Promise.race([
    page.evaluate(
      `Promise.resolve(window.__tailwindReady).then(() => true, () => false)`,
    ) as Promise<boolean>,
    new Promise<boolean>((resolve) => setTimeout(() => resolve(false), timeoutMs)),
  ]);

  if (!ready) {
    throw new Error(
      `[FrameCapture] window.__tailwindReady not resolved after ${timeoutMs}ms. Tailwind browser runtime must finish before frame capture starts.`,
    );
  }
}

/** Thrown once a VFX chain fails: the frames it paints would render without the effect. */
export class VfxFailureError extends Error {
  constructor(readonly detail: string) {
    super(`A VFX chain failed, so its frames would render without the effect (${detail})`);
    this.name = "VfxFailureError";
  }
}

function assertVfxIntact(session: CaptureSession): void {
  if (session.vfxFailure) throw new VfxFailureError(session.vfxFailure);
}

// A `vfx:` detail is a chain that cannot paint, so every frame is wrong; `vfx-frame:` is one frame, a page error.
function recordConsoleScriptError(session: CaptureSession, error: string | null): void {
  if (!error?.startsWith("runtime-error:vfx:")) {
    recordPageError(session, error);
    return;
  }
  if (session.vfxFailure) return;
  session.vfxFailure = error;
  const message = new VfxFailureError(error).message;
  recordCaptureWarnings(session, [{ code: "vfx_failure", message, details: { sources: [error] } }]);
}

function recordPageError(session: CaptureSession, error: string | null): void {
  if (error && !session.pageErrors.includes(error)) session.pageErrors.push(error);
}

// A 4xx `response` and a `requestfailed` can both fire for the same script
// (e.g. a `requestfailed` following the 4xx), and repeated <script> tags for
// the same URL duplicate it further — dedupe so the fail-fast warning names
// each failed URL once.
function recordScriptLoadFailure(session: CaptureSession, url: string): void {
  if (!session.scriptLoadFailures.includes(url)) {
    session.scriptLoadFailures.push(url);
  }
}

const SCRIPT_ERROR_LABEL = "[HyperFrames] composition script error:";

/** `runtime-error:<first line>` for the error a framework wrapper logs when a composition script throws. */
export function classifyConsoleScriptError(type: string, text: string): string | null {
  if (type !== "error" || !text.startsWith(SCRIPT_ERROR_LABEL)) return null;
  const [detail = ""] = text.slice(SCRIPT_ERROR_LABEL.length).trim().split("\n");
  return `runtime-error:${detail.trimEnd() || "unknown"}`;
}

export function classifyConsoleScriptFailure(type: string, text: string): string | null {
  if (type !== "error") return null;
  if (
    /failed to find a valid digest in the ['"]integrity['"] attribute/i.test(text) &&
    /resource has been blocked/i.test(text)
  ) {
    return "runtime-error:subresource-integrity";
  }
  return null;
}

function isPlayPauseAbort(message: string): boolean {
  return /^AbortError:/.test(message) && message.includes("play()") && message.includes("pause()");
}

/** `runtime-error:<first line>` when a script served with the composition threw; null if not attributable to one. */
export function classifyPageError(
  details: Protocol.Runtime.ExceptionDetails,
  projectScripts: ReadonlySet<string>,
): string | null {
  const exception = details.exception;
  const message = String(exception?.description ?? exception?.value ?? details.text);
  const [firstLine = ""] = message.split("\n");
  if (isPlayPauseAbort(firstLine)) return null;
  const frames = (details.stackTrace?.callFrames ?? []).map((frame) => frame.url);
  // Frameless: a parse error names its script; a rejection names whatever document is current, so it is unattributable.
  if (frames.length === 0 && details.text.startsWith("Uncaught (in promise)")) return null;
  const urls = frames.length > 0 ? frames : [details.url];
  // The render compiler names the composition's inline code.
  // Inline handlers report the document, which a widget can move.
  const owned = (url: string | undefined) =>
    url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
  return urls.some(owned) ? `runtime-error:${firstLine}` : null;
}

// fallow-ignore-next-line unit-size
export async function initializeSession(session: CaptureSession): Promise<void> {
  const { page, serverUrl } = session;

  // Forward browser console to host. HyperFrames runtime logs get a dedicated
  // prefix so page-context observability is visible in producer stdout.
  page.on("console", (msg: ConsoleMessage) => {
    const type = msg.type();
    const text = msg.text();
    const locationUrl = msg.location()?.url ?? "";
    const diagnostic = formatConsoleDiagnostic(type, text, locationUrl);
    if (!diagnostic.suppressHostLog) console.log(diagnostic.text);
    appendBrowserDiagnostic(session, diagnostic.text);

    // A blocked script can never register its timeline (#3352); a thrown one may still, so it only counts on timeout.
    const scriptFailure = classifyConsoleScriptFailure(type, text);
    if (scriptFailure) recordScriptLoadFailure(session, scriptFailure);
    recordConsoleScriptError(session, classifyConsoleScriptError(type, text));
  });

  page.on("pageerror", (err) => {
    const message = err instanceof Error ? err.message : String(err);
    const text = `[Browser:PAGEERROR] ${message}`;

    // Benign play/pause race during frame capture — suppress terminal noise, keep in buffer.
    if (!isPlayPauseAbort(message)) console.error(text);

    appendBrowserDiagnostic(session, text);
  });

  page.on("requestfailed", (request) => {
    const resourceType = request.resourceType();
    const url = request.url();
    const failureText = request.failure()?.errorText ?? "unknown";
    if (resourceType === "script") {
      recordScriptLoadFailure(session, request.url());
    }
    if (shouldIgnoreRequestFailureDiagnostic({ resourceType, url, failureText })) return;
    appendBrowserDiagnostic(
      session,
      formatRequestFailureDiagnostic({
        method: request.method(),
        resourceType,
        url,
        failureText,
      }),
    );
  });

  const projectScripts = new Set<string>();
  page.on("response", (response) => {
    const status = response.status();
    const request = response.request();
    const isScript = request.resourceType() === "script";
    const responseUrl = response.url();
    if (status < 400) {
      if (isScript && responseUrl.startsWith(`${serverUrl}/`)) projectScripts.add(responseUrl);
      return;
    }

    if (isScript) recordScriptLoadFailure(session, responseUrl);
    appendBrowserDiagnostic(
      session,
      formatHttpErrorDiagnostic({
        method: request.method(),
        resourceType: request.resourceType(),
        url: response.url(),
        status,
        statusText: response.statusText(),
      }),
    );
  });

  // Navigate to the file server
  const url = `${serverUrl}/index.html`;

  // Unlike the pageerror Error, this keeps the script URL of syntax errors and thrown non-errors.
  const runtimeClient = await getCdpSession(page);
  runtimeClient.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
    recordPageError(session, classifyPageError(exceptionDetails, projectScripts));
  });
  await runtimeClient.send("Runtime.enable");

  const pageNavigationTimeout =
    session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
  const initStart = Date.now();
  const logInitPhase = (phase: string) => {
    console.log(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
  };
  const gotoEntryPage = async (): Promise<void> => {
    appendBrowserDiagnostic(
      session,
      formatNavigationStartDiagnostic({
        captureMode: session.captureMode,
        url,
        timeoutMs: pageNavigationTimeout,
      }),
    );
    logInitPhase("page.goto start");
    try {
      await page.goto(url, { waitUntil: "domcontentloaded", timeout: pageNavigationTimeout });
    } catch (error) {
      appendBrowserDiagnostic(
        session,
        formatNavigationFailureDiagnostic({
          captureMode: session.captureMode,
          url,
          timeoutMs: pageNavigationTimeout,
          elapsedMs: Date.now() - initStart,
          error,
        }),
      );
      throw error;
    }
    await assertWebGpuAdapterAvailable(
      page,
      session.requiresWebGpu ?? false,
      session.softwareWebGpu,
    );
  };

  if (session.captureMode === "screenshot") {
    // Screenshot mode: standard navigation, rAF works normally
    await gotoEntryPage();
    logInitPhase("page.goto complete");

    // Flush the GSAP proxy queue synchronously instead of waiting for
    // rAF-based batch ticks (100 ops/tick at ~16ms). In headless mode there's
    // no UI responsiveness concern, so draining instantly eliminates the
    // largest init-time cost for tween-heavy compositions.
    await page.evaluate(`window.__hfFlushSync?.()`);
    logInitPhase("GSAP proxy flush complete");

    const pageReadyTimeout =
      session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
    await pollHfReady(page, pageReadyTimeout);
    logInitPhase("pollHfReady complete");

    await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
    logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
    assertVfxIntact(session);
    recordSubTimelineWarning(session, pageReadyTimeout);

    await applyVideoMetadataHints(page, session.options.videoMetadataHints);
    logInitPhase("applyVideoMetadataHints complete");

    // Run independent readiness checks in parallel — videos, images, fonts,
    // and Tailwind don't depend on each other's completion.
    const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
    const [videosReady] = await Promise.all([
      pollVideosReady(page, skipVideoIds, pageReadyTimeout),
      waitForImagesReady(page, pageReadyTimeout, (failedImages) =>
        console.warn(
          `[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
            `Continuing render. Affected images may appear blank/missing in early frames.`,
        ),
      ),
      page.evaluate(`document.fonts?.ready`),
      waitForOptionalTailwindReady(page, pageReadyTimeout),
    ]);
    logInitPhase("media + fonts + tailwind ready");

    if (!videosReady) {
      const failedVideos = await page.evaluate((skipIdList: readonly string[]) => {
        const skip = new Set(skipIdList);
        return Array.from(document.querySelectorAll("video"))
          .filter((v) => !skip.has(v.id))
          .filter((v) => (v as HTMLVideoElement).readyState < 2 && !(v as HTMLVideoElement).error)
          .map((v) => (v as HTMLVideoElement).src || v.getAttribute("src") || "(no src)")
          .join(", ");
      }, skipVideoIds);
      console.warn(
        `[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
          `Continuing render. Affected videos will appear as blank/black frames.`,
      );
    }
    recordCaptureWarnings(
      session,
      await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout),
    );
    await recordLiveMapWarning(session, page);

    await recordSessionInitTelemetry(session, initStart);

    // Ground-truth-check the upstream captureBeyondViewport request (see
    // pageContentExceedsCaptureHeight) now that the page is fully settled —
    // downgrade it when the page doesn't actually overflow the requested
    // capture height, since the beyond-viewport CDP path is otherwise pure
    // downside (HF#2550: phantom duplicate content on SwiftShader) for
    // content it was never needed for.
    if (session.options.captureBeyondViewport) {
      const needsBeyondViewport = await pageContentExceedsCaptureHeight(
        page,
        session.options.height,
      );
      if (!needsBeyondViewport) {
        session.options.captureBeyondViewport = false;
        logInitPhase("captureBeyondViewport downgraded: page content fits the capture viewport");
      }
    }

    // drawElement or transparent-background init — runs after page is fully ready.
    await initDrawElementOrTransparentBackground(session, page, logInitPhase);

    await armStaticDedup(session, session.page, logInitPhase);
    await ensureRenderFrameSiblings(session.page);
    finalizeSessionInit(session);
    return;
  }

  // In BeginFrame mode, Chrome's event loop is paused until we issue frames.
  // Start a warmup loop to drive rAF/setTimeout callbacks during page load.
  //
  // The unlocked path runs while `warmupState.running` stays true — wall-
  // clock-bounded. The locked path (`options.lockWarmupTicks`) additionally
  // exits at exactly `LOCKED_WARMUP_TICKS` iterations so `beginFrameTimeTicks`
  // is deterministic across hosts with different page-load latencies.
  const warmupIntervalMs = 33; // ~30fps
  const warmupState: WarmupTickState = {
    running: true,
    ticks: 0,
  };
  const lockWarmupTicks = session.options.lockWarmupTicks === true;
  let warmupClient: import("puppeteer-core").CDPSession | null = null;

  const acquireWarmupClient = async (): Promise<void> => {
    try {
      warmupClient = await getCdpSession(page);
      await warmupClient.send("HeadlessExperimental.enable");
    } catch {
      /* page not ready yet */
    }
  };

  const warmupLoopPromise = (async () => {
    await acquireWarmupClient();
    await driveWarmupTicks(
      {
        intervalMs: warmupIntervalMs,
        lockWarmupTicks,
        tick: async (frameTimeTicks, interval) => {
          if (!warmupClient) {
            // No CDP yet — let driveWarmupTicks count the tick anyway so the
            // locked iteration count is reached deterministically. Throwing
            // would skip the ticks++ increment, leaking host-load variance
            // back into the count.
            return;
          }
          await warmupClient.send("HeadlessExperimental.beginFrame", {
            frameTimeTicks,
            interval,
            noDisplayUpdates: true,
          });
        },
      },
      warmupState,
    );
  })();
  warmupLoopPromise.catch(() => {});
  logInitPhase("warmup loop started");

  await cancelWarmupOnError(warmupState, async () => {
    await gotoEntryPage();
    logInitPhase("page.goto complete");

    // Flush the GSAP proxy queue synchronously. In BeginFrame mode the rAF-based
    // batch drain runs on the warmup loop's 33ms ticks — for tween-heavy
    // compositions this is the dominant init cost. Flushing synchronously
    // eliminates the wait entirely.
    await page.evaluate(`window.__hfFlushSync?.()`);
    logInitPhase("GSAP proxy flush complete");

    // Poll for window.__hf readiness using manual evaluate loop (waitForFunction
    // uses rAF polling internally, which won't fire in beginFrame mode).
    const pageReadyTimeout =
      session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
    await pollHfReady(page, pageReadyTimeout);
    logInitPhase("pollHfReady complete");

    await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
    logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
    assertVfxIntact(session);
    recordSubTimelineWarning(session, pageReadyTimeout);

    await applyVideoMetadataHints(page, session.options.videoMetadataHints);
    logInitPhase("applyVideoMetadataHints complete");

    // Run independent readiness checks in parallel — videos, images, fonts,
    // and Tailwind don't depend on each other's completion.
    const bfSkipVideoIds = session.options.skipReadinessVideoIds ?? [];
    const [bfVideosReady] = await Promise.all([
      pollVideosReady(page, bfSkipVideoIds, pageReadyTimeout),
      waitForImagesReady(page, pageReadyTimeout, (failedImages) =>
        console.warn(
          `[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
            `Continuing render. Affected images may appear blank/missing in early frames.`,
        ),
      ),
      page.evaluate(`document.fonts?.ready`),
      waitForOptionalTailwindReady(page, pageReadyTimeout),
    ]);
    logInitPhase("media + fonts + tailwind ready");

    if (!bfVideosReady) {
      const failedVideos = await page.evaluate((skipIdList: readonly string[]) => {
        const skip = new Set(skipIdList);
        return Array.from(document.querySelectorAll("video"))
          .filter((v) => !skip.has(v.id))
          .filter((v) => (v as HTMLVideoElement).readyState < 2 && !(v as HTMLVideoElement).error)
          .map((v) => (v as HTMLVideoElement).src || v.getAttribute("src") || "(no src)")
          .join(", ");
      }, bfSkipVideoIds);
      console.warn(
        `[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
          `Continuing render. Affected videos will appear as blank/black frames.`,
      );
    }
    recordCaptureWarnings(
      session,
      await collectMediaReadinessWarnings(page, bfSkipVideoIds, pageReadyTimeout),
    );
    await recordLiveMapWarning(session, page);

    await recordSessionInitTelemetry(session, initStart);
  });

  // Stop warmup, then drain the loop in BOTH modes before any further
  // BeginFrame on this session (drawElement init, the render-frame commit tick
  // at the end of init, and frame 0). Clearing the flag only stops new
  // iterations — a warmup `HeadlessExperimental.beginFrame` may still be in
  // flight, and a second beginFrame on the same session while one is pending
  // fails with "Another frame is pending". Locked mode additionally needs the
  // await to reach the exact LOCKED_WARMUP_TICKS count before deriving the
  // baseline below.
  warmupState.running = false;
  await warmupLoopPromise.catch(() => {});

  // Preserve the legacy baseline when it is already safe. Otherwise continue
  // from the clock actually used by warmup, then reserve capture-rate headroom
  // for the commit and probe ticks below. Locked mode still produces an
  // identical timeline on every host because its driver ends at exactly
  // LOCKED_WARMUP_TICKS.
  const preparedBeginFrameTimeline = prepareBeginFrameTimeline(
    session,
    warmupState,
    warmupIntervalMs,
  );

  // drawElement or transparent-background init — runs after page is fully ready.
  // IMPORTANT: must stay after beginFrameTimeTicks is set above. The per-frame
  // drawelement branch gates its BeginFrame call on `beginFrameTimeTicks > 0`;
  // if this ran first, ticks would be 0 and the paused compositor would never
  // advance for opaque drawElement on Linux. (In beginframe-launched mode,
  // transparent is always false — useDrawElement+png forces preMode="screenshot"
  // upstream — so the SwiftShader fallback inside the helper is dead-but-harmless
  // defense-in-depth here.)
  await initDrawElementOrTransparentBackground(session, page, logInitPhase);

  await armStaticDedup(session, session.page, logInitPhase);

  // Pre-create the hidden `__render_frame__` siblings so the first per-session
  // `injectVideoFramesBatch` takes the `hasImg = true` (src-update) path instead
  // of inserting a fresh `<img>` mid-capture. Then drive ONE non-capture,
  // *visual* BeginFrame (`noDisplayUpdates: false`) to actually composite the
  // new layers before the first real capture. The warmup ticks above are
  // `noDisplayUpdates: true` (they advance the clock but don't paint), and the
  // seek in `prepareFrameForCapture` doesn't tick, so without this commit tick
  // the first *display-producing* BeginFrame would be the capture itself — and
  // the freshly-inserted layers would miss it (the per-session worker-boundary
  // near-black flash). The tick time sits in the gap between the last warmup
  // tick and frame 0 (`beginFrameTimeTicks` carries +10 intervals of headroom),
  // so ticks stay monotonic and no render frame is consumed.
  //
  // It must land BELOW the producer's BeginFrame liveness probe, which fires
  // from probeStage right after init at `beginFrameTimeTicks - 5·interval`
  // (screenshotService.probeBeginFrameLiveness). This commit tick is sent during
  // init — temporally before the probe — so if its tick were above the probe's,
  // the probe would run backwards in BeginFrame time (non-monotonic) and
  // chrome-headless-shell stalls it indefinitely (surfaced as a "SwiftShader
  // heavy-layer" probe timeout, then routed to screenshot capture). At the
  // original `-1·interval` that stalled every comp reaching the probe; at
  // `-6·interval` the order stays warmup < commit < probe < capture.
  await ensureRenderFrameSiblings(page);
  const commitCdp = await getCdpSession(page);
  await commitCdp.send("HeadlessExperimental.beginFrame", preparedBeginFrameTimeline.commitParams);

  finalizeSessionInit(session);
}

async function captureFrameErrorDiagnostics(
  session: CaptureSession,
  frameIndex: number,
  time: number,
  error: Error,
): Promise<string | null> {
  try {
    const diagnosticsDir = join(session.outputDir, "diagnostics");
    if (!existsSync(diagnosticsDir)) mkdirSync(diagnosticsDir, { recursive: true });
    const base = join(diagnosticsDir, `frame-error-${frameIndex}`);
    const pageScreenshotCanResolve = session.launchCaptureMode !== "beginframe";
    if (pageScreenshotCanResolve) {
      await session.page.screenshot({ path: `${base}.png`, type: "png", fullPage: true });
    }
    const html = await session.page.content();
    writeFileSync(`${base}.html`, html, "utf-8");
    writeFileSync(
      `${base}.json`,
      JSON.stringify(
        {
          frameIndex,
          time,
          error: error.message,
          stack: error.stack,
          browserConsoleTail: session.browserConsoleBuffer.slice(-30),
        },
        null,
        2,
      ),
      "utf-8",
    );
    return `${base}.json`;
  } catch {
    return null;
  }
}

/**
 * Internal helper: seek timeline and inject video frames.
 * Shared by captureFrame (disk) and captureFrameToBuffer (buffer).
 * Returns timing breakdown for perf tracking.
 */
export async function waitForPendingSeekCompletion(page: Pick<Page, "evaluate">): Promise<void> {
  await page.evaluate(async () => {
    const waitForCompletion = (
      window as Window & { __hfWaitForSeekCompletion?: () => Promise<void> }
    ).__hfWaitForSeekCompletion;
    await waitForCompletion?.();
  });
}

/**
 * Seek the page timeline and report whether a page-side composite is pending.
 *
 * The page's `seek()` owns all framework-specific stepping (GSAP, CSS animations, WAAPI);
 * the options object reaches it untouched through the producer's `__hf.seek` bridge.
 * Seek and pending-flag read share one round trip.
 */
async function seekPageTimeline(
  page: Page,
  time: number,
  seekOptions: HfSeekOptions | undefined,
): Promise<boolean> {
  return page.evaluate(
    (t: number, opts: HfSeekOptions | undefined) => {
      if (window.__hf && typeof window.__hf.seek === "function") {
        window.__hf.seek(t, opts);
      }
      return !!(window as unknown as { __hf_page_composite_pending?: boolean })
        .__hf_page_composite_pending;
    },
    time,
    seekOptions,
  );
}

async function prepareFrameForCapture(
  session: CaptureSession,
  frameIndex: number,
  time: number,
  seekOptions?: HfSeekOptions,
  heldVideoTime?: number,
): Promise<{
  quantizedTime: number;
  seekMs: number;
  beforeCaptureMs: number;
}> {
  const { page, options } = session;

  if (!session.isInitialized) {
    throw new Error("[FrameCapture] Session not initialized");
  }
  assertVfxIntact(session);

  const quantizedTime = quantizeSeekTime(
    time,
    fpsToNumber(options.fps),
    seekOptions?.subFrameDivisions,
  );

  const seekStart = Date.now();
  session.captureStep = "seeking the timeline";
  const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);

  session.captureStep = "decoding CSS background images";
  await decodeDynamicCssBackgroundImages(page);

  const seekMs = Date.now() - seekStart;

  // Before-capture hook (e.g. video frame injection) — runs before
  // page-side compositor clones so cloneNode picks up injected <img>
  // replacements for <video> elements.
  const beforeCaptureStart = Date.now();
  if (session.onBeforeCapture) {
    session.captureStep = "injecting video frames";
    await session.onBeforeCapture(page, quantizedTime, heldVideoTime);
  }
  session.captureStep = "waiting for page seek handlers";
  await waitForPendingSeekCompletion(page);
  session.captureStep = "loading color-grading LUTs";
  await page.evaluate(async () => {
    const runtime = (
      window as Window & {
        __hf?: { colorGrading?: { waitForActiveLuts?: () => Promise<number> } };
      }
    ).__hf?.colorGrading;
    await runtime?.waitForActiveLuts?.();
  });
  const beforeCaptureMs = Date.now() - beforeCaptureStart;

  // Page-side compositing three-phase protocol:
  //  1. prepare — clone scenes (now containing injected video <img>s)
  //  2. micro-screenshot — force browser to paint cloned elements
  //  3. resolve — drawElementImage reads paint records, shader composites
  if (
    hasPendingComposite &&
    session.captureMode !== "beginframe" &&
    session.captureMode !== "drawelement"
  ) {
    session.captureStep = "compositing the page";
    await page.evaluate(async () => {
      const w = window as unknown as { __hf_page_composite_prepare?: () => Promise<boolean> };
      if (typeof w.__hf_page_composite_prepare === "function") {
        await w.__hf_page_composite_prepare();
      }
    });
    const cdp = await getCdpSession(page);
    await cdp.send("Page.captureScreenshot", {
      format: "jpeg",
      quality: 1,
      clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 },
    });
    await page.evaluate(() => {
      const w = window as unknown as { __hf_page_composite_resolve?: () => boolean };
      if (typeof w.__hf_page_composite_resolve === "function") {
        w.__hf_page_composite_resolve();
      }
    });
  }

  session.captureStep = "capturing the frame";
  return { quantizedTime, seekMs, beforeCaptureMs };
}

// ── Static-frame dedup (default-on, opt-out HF_STATIC_DEDUP=false) ─────────────
// Skip re-seeking + re-screenshotting frames that are byte-identical to their
// predecessor. A frame is dedupable iff no GSAP tween or clip cut is active in it or
// its predecessor (predicted from window.__timelines), AND an empirical anchor-compare
// confirms it. Capture-mode-independent (works on screenshot + beginframe), lossless
// (verification disables the whole comp on any drift), default off. Pays on
// static-hold content (title cards, slideshows, data-viz pauses); a no-op on
// continuously-animated comps and disqualified by video/canvas/non-GSAP animation.

/**
 * Clip-cut boundary frames (±1) from the [data-start] schedule. A hard scene swap at a
 * cut changes content with no tween; treat those frames as animated so the post-cut
 * frame is captured fresh and later static frames reuse the correct scene.
 */
export function computeAuthoredClipBoundaryFrames(
  schedule: RawAuthoredTiming[],
  fps: number,
): Set<number> {
  const frames = new Set<number>();
  for (const rawTiming of schedule) {
    const timing = resolveAuthoredTimingWindow(rawTiming);
    if (!timing) continue;
    const edges = [Math.round(timing.start * fps)];
    if (timing.end != null) edges.push(Math.round(timing.end * fps));
    for (const e of edges) {
      for (const f of [e - 1, e, e + 1]) {
        if (f >= 0) frames.add(f);
      }
    }
  }
  return frames;
}

async function computeClipBoundaryFrames(page: Page, fps: number): Promise<Set<number>> {
  const schedule = await page.evaluate(() =>
    Array.from(document.querySelectorAll("[data-start]")).map((el) => ({
      start: el.getAttribute("data-start"),
      duration: el.getAttribute("data-duration"),
      authoredDuration: el.getAttribute("data-hf-authored-duration"),
      end: el.getAttribute("data-end"),
      authoredEnd: el.getAttribute("data-hf-authored-end"),
    })),
  );
  return computeAuthoredClipBoundaryFrames(schedule, fps);
}

// Static dedup is an optional optimization. Building frame-index Sets scales with the
// composition's declared duration, so malformed/sentinel durations must fail closed before
// allocating them. Normal capture and the producer's typed duration validation still proceed.
export const MAX_STATIC_DEDUP_ANALYSIS_FRAMES = 1_000_000;

export function isStaticDedupFrameAnalysisSafe(totalFrames: number): boolean {
  return (
    Number.isFinite(totalFrames) &&
    Number.isSafeInteger(totalFrames) &&
    totalFrames > 0 &&
    totalFrames <= MAX_STATIC_DEDUP_ANALYSIS_FRAMES
  );
}

/**
 * Predict the dedupable (static) frame set from window.__timelines. A frame f (f>0) is
 * static iff NEITHER f NOR f-1 falls inside any GSAP tween interval — content didn't
 * change f-1→f, so f can reuse f-1's buffer. Requiring BOTH neighbours static under-
 * claims by one frame at each tween edge (the SAFE direction). Disqualifies the whole
 * comp on any signal the tween-walker can't see: video / canvas / webgl (redraw without
 * a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
 */
export async function computeStaticFrameSet(
  page: Page,
  fps: number,
): Promise<{
  totalFrames: number;
  staticFrameSet: Set<number>;
  /** Frames whose only active motion is non-spatial (opacity, colour); safe to skip
   * the adaptive probe. Empty (not meaningful) when `!eligible`. */
  nonSpatialOnlyFrameSet: Set<number>;
  hasVideo: boolean;
  hasCanvas: boolean;
  hasNonGsapAnim: boolean;
  tweenCount: number;
  eligible: boolean;
  reason: string;
}> {
  const result = await page.evaluate((spatialProps: readonly string[]) => {
    type AnyTween = {
      startTime(): number;
      duration(): number;
      totalDuration?(): number;
      getChildren?(nested: boolean, tweens: boolean, timelines: boolean): AnyTween[];
      vars?: Record<string, unknown>;
    };
    // Passed in from SPATIAL_TWEEN_PROPERTIES rather than declared here, so the list
    // stays the one this module's own tests exercise (the matching code itself must
    // stay inline — this closure is serialized and runs in the page realm).
    const SPATIAL_PROPS = new Set(spatialProps);
    function isSpatial(vars: Record<string, unknown> | undefined): boolean {
      if (!vars) return false;
      for (const key of Object.keys(vars)) if (SPATIAL_PROPS.has(key)) return true;
      return false;
    }
    const intervals: Array<{ start: number; end: number; spatial: boolean }> = [];
    let tweenCount = 0;
    // totalDuration() (NOT duration()): a repeat/yoyo tween animates past one iteration;
    // a repeating timeline is marked opaque over its whole span (conservative).
    // A GSAP tl.call() is a zero-duration tween whose vars wire the callback as
    // onComplete (and onReverseComplete, fired on backward crossing — GSAP has
    // no separate "undo" callback, so both directions invoke the SAME forward
    // side effect). A one-shot DOM mutation driven this way (e.g. a counter's
    // textContent) is not seek-idempotent: crossing it during the static-dedup
    // verifier's own arm-time seeking permanently mutates the page, and that
    // corruption can leak into a LATER, unrelated static run's real capture
    // (the verifier's mismatch check only catches drift within the run being
    // checked, not contamination from a run checked afterward). No reliable
    // way to tell a DOM-mutating call() from a harmless one (analytics ping,
    // class toggle with no visual effect) without executing it, so disqualify
    // the whole comp on ANY call() rather than risk shipping wrong pixels.
    let hasTimelineCall = false;
    function walk(tl: AnyTween, offset: number): void {
      if (typeof tl.getChildren !== "function") return;
      // A timeline with an onUpdate callback can drive motion without any
      // visible tween (e.g. setting x/y from Math.random inside onUpdate).
      // Mark its entire span as animated so those frames are never deduped.
      if (typeof tl.vars?.onUpdate === "function") {
        const total = typeof tl.totalDuration === "function" ? tl.totalDuration() : 0;
        // onUpdate can move anything (e.g. x/y from Math.random) — conservatively spatial.
        if (total > 0) intervals.push({ start: offset, end: offset + total, spatial: true });
      }
      for (const child of tl.getChildren(false, true, true)) {
        const start = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
        const single = typeof child.duration === "function" ? child.duration() : 0;
        const total = typeof child.totalDuration === "function" ? child.totalDuration() : single;
        if (typeof child.getChildren === "function") {
          if (total > single + 1e-6) {
            // A repeating nested timeline's own children are walked for their real
            // vars below; this span is a conservative (spatial) placeholder for the
            // repeat/yoyo overrun, which a per-child walk doesn't otherwise cover.
            intervals.push({ start, end: start + total, spatial: true });
            // Still descend for hasTimelineCall even though the repeating
            // span is already opaque (its frames are excluded from dedup
            // regardless): a call() inside it is a review-flagged detection
            // gap otherwise — the arm-time verifier can still forward-seek
            // through this span while checking a LATER static run, firing
            // the call() and corrupting the page (review).
            walk(child, start);
          } else {
            walk(child, start);
          }
        } else {
          tweenCount++;
          intervals.push({ start, end: start + total, spatial: isSpatial(child.vars) });
          if (
            total <= 1e-6 &&
            (typeof child.vars?.onComplete === "function" ||
              typeof child.vars?.onReverseComplete === "function")
          ) {
            hasTimelineCall = true;
          }
        }
      }
    }
    const w = window as unknown as {
      __timelines?: Record<string, AnyTween>;
      __hf?: { duration?: number };
      __hfHasFrameSources?: () => boolean;
    };
    for (const tl of Object.values(w.__timelines || {})) {
      if (tl && typeof tl.getChildren === "function") walk(tl, 0);
    }
    const hasVideo = !!document.querySelector("video");
    const hasCanvas = !!document.querySelector("canvas");
    const hasFrameSources = w.__hfHasFrameSources?.() ?? false;
    const hasIframe = !!document.querySelector("iframe");
    // A non-numeric data-start (reference expression like "intro+0.5") can't be turned
    // into a clip-cut boundary by computeClipBoundaryFrames' parseFloat, so the cut goes
    // unprotected and could be deduped into the previous scene. Disqualify the comp.
    const hasUnresolvableClipStart = Array.from(document.querySelectorAll("[data-start]")).some(
      (el) => {
        const v = (el as HTMLElement).dataset.start;
        return v != null && v.trim() !== "" && !Number.isFinite(parseFloat(v));
      },
    );
    // Non-GSAP animation (CSS @keyframes / transitions / WAAPI) surfaces via
    // getAnimations(); any running/paused one can change content without a tween.
    let hasNonGsapAnim = false;
    try {
      const docAnims = (document as unknown as { getAnimations?: () => Animation[] }).getAnimations;
      if (typeof docAnims === "function") {
        hasNonGsapAnim = docAnims.call(document).some((a) => {
          const t = a as Animation & { playState?: string };
          return t.playState === "running" || t.playState === "paused";
        });
      }
    } catch {
      hasNonGsapAnim = true;
    }
    return {
      intervals,
      tweenCount,
      duration: w.__hf?.duration ?? 0,
      hasVideo,
      hasCanvas,
      hasFrameSources,
      hasIframe,
      hasNonGsapAnim,
      hasUnresolvableClipStart,
      hasTimelineCall,
    };
  }, SPATIAL_TWEEN_PROPERTIES);

  const {
    intervals,
    tweenCount,
    duration,
    hasVideo,
    hasCanvas,
    hasFrameSources,
    hasIframe,
    hasNonGsapAnim,
    hasUnresolvableClipStart,
    hasTimelineCall,
  } = result as {
    intervals: Array<{ start: number; end: number; spatial: boolean }>;
    tweenCount: number;
    duration: number;
    hasVideo: boolean;
    hasCanvas: boolean;
    hasFrameSources: boolean;
    hasIframe: boolean;
    hasNonGsapAnim: boolean;
    hasUnresolvableClipStart: boolean;
    hasTimelineCall: boolean;
  };
  const totalFrames = Math.max(1, Math.ceil(duration * fps));
  if (!isStaticDedupFrameAnalysisSafe(totalFrames)) {
    return {
      totalFrames,
      staticFrameSet: new Set<number>(),
      nonSpatialOnlyFrameSet: new Set<number>(),
      hasVideo,
      hasCanvas,
      hasNonGsapAnim,
      tweenCount,
      eligible: false,
      reason: `static-dedup frame analysis limit (${MAX_STATIC_DEDUP_ANALYSIS_FRAMES})`,
    };
  }
  const animated = new Set<number>();
  const spatialFrameSet = new Set<number>();
  for (const { start, end, spatial } of intervals) {
    const lo = Math.max(0, Math.floor(start * fps));
    const hi = Math.min(totalFrames - 1, Math.ceil(end * fps));
    for (let f = lo; f <= hi; f++) {
      animated.add(f);
      if (spatial) spatialFrameSet.add(f);
    }
  }
  for (const f of await computeClipBoundaryFrames(page, fps)) animated.add(f);
  const reasons: string[] = [];
  if (!(duration > 0)) reasons.push("unknown/zero duration");
  if (hasVideo) reasons.push("video");
  if (hasCanvas) reasons.push("canvas/webgl");
  // GSAP intervals cannot predict frame-source or opaque iframe draws.
  if (hasFrameSources) reasons.push("registered frame source");
  if (hasIframe) reasons.push("iframe");
  if (tweenCount === 0) reasons.push("no GSAP tweens (non-GSAP animation)");
  if (hasNonGsapAnim) reasons.push("running CSS/WAAPI animation");
  // tl.call() side effects are not seek-idempotent (see hasTimelineCall detection
  // above) — the arm-time verifier's own forward-seeking can permanently fire
  // one, corrupting the page for a later, unrelated static run's real capture
  // even though each run's own verification passes in isolation (HF static-
  // dedup content-drift report, tools-onboarding FR render).
  if (hasTimelineCall) reasons.push("tl.call() side effect (not seek-safe)");
  if (hasUnresolvableClipStart) reasons.push("unresolvable clip start (reference expression)");
  const eligible = reasons.length === 0;
  const staticFrameSet = new Set<number>();
  if (eligible) {
    for (let f = 1; f < totalFrames; f++) {
      if (!animated.has(f) && !animated.has(f - 1)) staticFrameSet.add(f);
    }
  }
  const nonSpatialOnlyFrameSet = new Set<number>();
  if (eligible) {
    for (const f of animated) if (!spatialFrameSet.has(f)) nonSpatialOnlyFrameSet.add(f);
  }
  return {
    totalFrames,
    staticFrameSet,
    nonSpatialOnlyFrameSet,
    hasVideo,
    hasCanvas,
    hasNonGsapAnim,
    tweenCount,
    eligible,
    reason: eligible ? "eligible" : reasons.join("+"),
  };
}

// Fixed density target for verification checks: never leave a gap wider than this
// many frames within a run, independent of the user-tunable sampleCount. This is
// what fixes long runs going nearly unverified — deliberately NOT derived from
// sampleCount, so that knob's effect on density stays monotonic (see below).
const STATIC_VERIFY_REFERENCE_STRIDE = 24;

// Verification uses full-page screenshots, whose cost scales with canvas size
// and page complexity rather than frame count. Bound wall time as well as the
// capture count so a long composition cannot spend minutes proving an
// optimization before the real render starts. Exhaustion fails closed: dedup is
// disabled and normal capture proceeds.
const STATIC_VERIFY_MAX_MS = 15_000;
// Two captures (anchor + comparison) are the minimum proof for a run. Four hundred
// therefore permits 200 fully verified runs while bounding pathological schedules.
const STATIC_VERIFY_MIN_SCREENSHOT_CAP = 400;
// Preserve the legacy tuning headroom: raising the composition-wide sample floor may
// raise the cap proportionally, but never changes the fixed wall deadline.
const STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER = 8;
// Keep sample-driven work within the 400-screenshot base cap: 50 comparisons × 8
// legacy headroom. Mandatory <=24-gap points may still raise the independent cap.
const STATIC_VERIFY_MAX_GLOBAL_SAMPLE_FLOOR =
  STATIC_VERIFY_MIN_SCREENSHOT_CAP / STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER;

export interface StaticVerificationRun {
  a: number;
  b: number;
  anchor: number;
  comparisons: number[];
  frameCount: number;
  netSavings: number;
}

export interface StaticVerificationPlan {
  runs: StaticVerificationRun[];
  skippedRuns: Array<{ a: number; b: number; reason: "unprofitable" }>;
  effectiveSampleFloor: number;
  predictedFrames: number;
  verifiedCandidateFrames: number;
  plannedAnchors: number;
  plannedComparisons: number;
  plannedScreenshots: number;
}

function contiguousStaticRuns(frames: number[]): Array<{ a: number; b: number }> {
  const runs: Array<{ a: number; b: number }> = [];
  for (const frame of frames) {
    const last = runs.at(-1);
    if (last && frame === last.b + 1) last.b = frame;
    else runs.push({ a: frame, b: frame });
  }
  return runs;
}

function mandatoryRunComparisons(anchor: number, end: number): number[] {
  const points = new Set<number>();
  for (
    let frame = anchor + STATIC_VERIFY_REFERENCE_STRIDE;
    frame < end;
    frame += STATIC_VERIFY_REFERENCE_STRIDE
  ) {
    points.add(frame);
  }
  points.add(end);
  return [...points].sort((left, right) => left - right);
}

/** Pure composition-wide planner. Every retained run is profitable and has gaps <=24 frames. */
export function planStaticVerification(
  staticFrames: Set<number>,
  sampleFloor: number,
): StaticVerificationPlan {
  const frames = [...staticFrames].sort((left, right) => left - right);
  const allRuns = contiguousStaticRuns(frames).map(({ a, b }): StaticVerificationRun => {
    const comparisons = mandatoryRunComparisons(a - 1, b);
    const frameCount = b - a + 1;
    return {
      a,
      b,
      anchor: a - 1,
      comparisons,
      frameCount,
      netSavings: frameCount - comparisons.length - 1,
    };
  });
  const runs = allRuns.filter((run) => run.anchor >= 0 && run.netSavings > 0);
  const skippedRuns = allRuns
    .filter((run) => run.anchor < 0 || run.netSavings <= 0)
    .map((run) => ({ a: run.a, b: run.b, reason: "unprofitable" as const }));

  const normalizedSampleFloor = Number.isFinite(sampleFloor)
    ? Math.max(1, Math.floor(sampleFloor))
    : 1;
  const effectiveSampleFloor = Math.min(
    normalizedSampleFloor,
    STATIC_VERIFY_MAX_GLOBAL_SAMPLE_FLOOR,
  );
  const comparisonCount = () => runs.reduce((sum, run) => sum + run.comparisons.length, 0);
  while (comparisonCount() < effectiveSampleFloor) {
    const candidates = runs
      .filter((run) => run.frameCount > run.comparisons.length + 2)
      .flatMap((run) => {
        const points = [run.anchor, ...run.comparisons];
        return points.slice(1).map((right, index) => ({
          run,
          left: points[index]!,
          right,
          width: right - points[index]!,
        }));
      })
      .filter((gap) => gap.width > 1)
      .sort(
        (left, right) =>
          right.width - left.width || left.run.a - right.run.a || left.left - right.left,
      );
    const selected = candidates[0];
    if (!selected) break;
    selected.run.comparisons.push(Math.floor((selected.left + selected.right) / 2));
    selected.run.comparisons.sort((left, right) => left - right);
    selected.run.netSavings = selected.run.frameCount - selected.run.comparisons.length - 1;
  }

  runs.sort((left, right) => right.netSavings - left.netSavings || left.a - right.a);
  const plannedComparisons = comparisonCount();
  return {
    runs,
    skippedRuns,
    effectiveSampleFloor,
    predictedFrames: frames.length,
    verifiedCandidateFrames: runs.reduce((sum, run) => sum + run.frameCount, 0),
    plannedAnchors: runs.length,
    plannedComparisons,
    plannedScreenshots: runs.length + plannedComparisons,
  };
}

export type StaticVerificationOutcome =
  | "verified"
  | "unprofitable"
  | "time_budget"
  | "count_budget"
  | "mismatch"
  | "infrastructure";

export interface StaticVerificationStats {
  plannedRuns: number;
  completedRuns: number;
  plannedAnchors: number;
  completedAnchors: number;
  plannedComparisons: number;
  completedComparisons: number;
  seeks: number;
  screenshots: number;
  byteComparisons: number;
  elapsedMs: number;
  predictedFrames: number;
  verifiedFrames: number;
  unverifiedFrames: number;
}

export interface StaticVerificationResult {
  outcome: StaticVerificationOutcome;
  verifiedFrames: Set<number>;
  badFrame?: number;
  stats: StaticVerificationStats;
}

interface StaticVerificationDependencies {
  now?: () => number;
  capture?: typeof pageScreenshotCapture;
}

/**
 * Prepare an isolated page for static-frame verification. Verification seeks
 * intentionally visit frames out of capture order on a SEPARATE page that is
 * never used for the real capture — out-of-order event-callback side effects
 * are contained to this disposable page and cannot corrupt sequential capture.
 */
export async function createStaticVerificationPage(session: CaptureSession): Promise<Page> {
  const page = await session.browser.newPage();
  const pageNavigationTimeout =
    session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
  const pageReadyTimeout = session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;

  try {
    await page.evaluateOnNewDocument(() => {
      const w = window as unknown as { __name?: <T>(fn: T, _name: string) => T };
      if (typeof w.__name !== "function") {
        w.__name = <T>(fn: T, _name: string): T => fn;
      }
    });
    if (session.options.variables && Object.keys(session.options.variables).length > 0) {
      const variablesJson = JSON.stringify(session.options.variables);
      await page.evaluateOnNewDocument((json: string) => {
        (window as Window & { __hfVariables?: Record<string, unknown> }).__hfVariables =
          JSON.parse(json);
      }, variablesJson);
    }
    await installPageMotionBlur(page, session.options);
    await page.setViewport({
      width: session.options.width,
      height: session.options.height,
      deviceScaleFactor: session.options.deviceScaleFactor || 1,
    });
    await page.goto(`${session.serverUrl}/index.html`, {
      waitUntil: "domcontentloaded",
      timeout: pageNavigationTimeout,
    });
    await page.evaluate(`window.__hfFlushSync?.()`);
    await pollHfReady(page, pageReadyTimeout);
    await pollSubCompositionTimelines(page, pageReadyTimeout, {
      getScriptLoadFailures: () => session.scriptLoadFailures,
      knownUnregisteredIds: session.subTimelineWaitMemo.unregisteredIds,
    });
    await applyVideoMetadataHints(page, session.options.videoMetadataHints);

    const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
    await Promise.all([
      pollVideosReady(page, skipVideoIds, pageReadyTimeout),
      pollImagesReady(page, pageReadyTimeout).then((ready) =>
        ready ? decodeAllImages(page) : undefined,
      ),
      page.evaluate(`document.fonts?.ready`),
      waitForOptionalTailwindReady(page, pageReadyTimeout),
    ]);
    if (session.options.format === "png") await initTransparentBackground(page);
    return page;
  } catch (error) {
    await page.close().catch(() => {});
    throw error;
  }
}

/**
 * Empirically verify the predicted-static set before trusting it. Group static frames
 * into runs; each run [a..b] reuses anchor a-1. CRITICAL: compare against the ANCHOR,
 * not the predecessor — a slow drift with sub-quantization per-frame deltas is byte-
 * identical frame-to-frame yet drifts far from the anchor by the run's end (the real
 * frozen error). Capture each run's anchor once, compare its end plus deterministic
 * composition-wide points that preserve a 24-frame maximum gap; any mismatch ⇒ the
 * run isn't truly static ⇒ disable dedup whole-comp. Capture-mode-
 * independent (seeks + screenshots in normal DOM). Budget exhaustion may retain only
 * runs whose anchor and every planned comparison completed successfully.
 */
export async function verifyStaticFramesSafe(
  session: CaptureSession,
  page: Page,
  staticFrames: Set<number>,
  fps: number,
  sampleCount: number,
  dependencies: StaticVerificationDependencies = {},
): Promise<StaticVerificationResult> {
  const plan = planStaticVerification(staticFrames, sampleCount);
  const now = dependencies.now ?? Date.now;
  const capture = dependencies.capture ?? pageScreenshotCapture;
  const startedAt = now();
  const deadline = startedAt + STATIC_VERIFY_MAX_MS;
  const verifiedFrames = new Set<number>();
  const stats: StaticVerificationStats = {
    plannedRuns: plan.runs.length,
    completedRuns: 0,
    plannedAnchors: plan.plannedAnchors,
    completedAnchors: 0,
    plannedComparisons: plan.plannedComparisons,
    completedComparisons: 0,
    seeks: 0,
    screenshots: 0,
    byteComparisons: 0,
    elapsedMs: 0,
    predictedFrames: plan.predictedFrames,
    verifiedFrames: 0,
    unverifiedFrames: plan.predictedFrames,
  };
  const finish = (
    outcome: StaticVerificationOutcome,
    badFrame?: number,
  ): StaticVerificationResult => ({
    outcome,
    verifiedFrames,
    ...(badFrame == null ? {} : { badFrame }),
    stats,
  });
  if (plan.runs.length === 0) return finish("unprofitable");
  const seekToFrame = async (frameIdx: number): Promise<void> => {
    stats.seeks++;
    const t = quantizeTimeToFrame(frameIdx / fps, fps);
    await page.evaluate((tt: number) => {
      const hf = (
        window as unknown as {
          __hf?: { seek?: (t: number, options?: { suppressEvents?: boolean }) => void };
        }
      ).__hf;
      if (hf && typeof hf.seek === "function") hf.seek(tt, { suppressEvents: false });
    }, t);
  };
  const hardCap = Math.max(
    STATIC_VERIFY_MIN_SCREENSHOT_CAP,
    plan.effectiveSampleFloor * STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER,
    Math.ceil(plan.predictedFrames / STATIC_VERIFY_REFERENCE_STRIDE) * 3 + plan.runs.length,
  );
  const seekCapture = async (
    frameIdx: number,
  ): Promise<Buffer | "time_budget" | "count_budget"> => {
    if (now() >= deadline) return "time_budget";
    if (stats.screenshots >= hardCap) return "count_budget";
    await seekToFrame(frameIdx);
    stats.screenshots++;
    return capture(page, session.options);
  };
  // Verify profitable runs in deterministic savings order. A run is added to the armed
  // set only after its anchor and every planner-selected comparison match. Budget exits
  // retain completed runs; mismatch or infrastructure failure clears all verified frames.
  try {
    for (const run of plan.runs) {
      const anchorBuf = await seekCapture(run.anchor);
      if (typeof anchorBuf === "string") return finish(anchorBuf, run.a);
      stats.completedAnchors++;
      for (const f of run.comparisons) {
        const cur = await seekCapture(f);
        if (typeof cur === "string") return finish(cur, f);
        stats.completedComparisons++;
        stats.byteComparisons++;
        if (!anchorBuf.equals(cur)) {
          verifiedFrames.clear();
          stats.verifiedFrames = 0;
          stats.unverifiedFrames = plan.predictedFrames;
          return finish("mismatch", f);
        }
      }
      stats.completedRuns++;
      for (let frame = run.a; frame <= run.b; frame++) verifiedFrames.add(frame);
      stats.verifiedFrames = verifiedFrames.size;
      stats.unverifiedFrames = plan.predictedFrames - verifiedFrames.size;
    }
    return finish("verified");
  } catch {
    verifiedFrames.clear();
    stats.verifiedFrames = 0;
    stats.unverifiedFrames = plan.predictedFrames;
    return finish("infrastructure");
  } finally {
    await seekToFrame(0).catch(() => {});
    stats.elapsedMs = Math.max(0, now() - startedAt);
  }
}

/**
 * Arm static-frame dedup for this render (default-on; opt out with HF_STATIC_DEDUP=false).
 * Runs at init in normal DOM state so the verification screenshots are valid. Predicts
 * the static set, anchor-verifies it (skip with HF_STATIC_DEDUP_VERIFY=false — unsafe),
 * and on success stores it on the session for captureFrameCore to reuse. Sample budget
 * via HF_STATIC_DEDUP_SAMPLES (default 24).
 */
async function armStaticDedup(
  session: CaptureSession,
  page: Page,
  logInitPhase: (phase: string) => void,
): Promise<void> {
  // Adaptive motion-blur sample-count classification shares the GSAP-timeline walk
  // below but is gated independently of dedup (capture mode / before-capture hooks are
  // about buffer-reuse safety, irrelevant to which properties a tween touches), so it
  // is computed here, once, ahead of dedup's own idempotency check. Cached in
  // `sharedStaticFrameStats` so dedup's own call further down does not repeat the walk.
  // Reads `session.options.motionBlur` (the raw caller options), not `session.motionBlur`
  // (the resolved plan) — every armStaticDedup call site runs before finalizeSessionInit
  // resolves the plan, so the resolved field is never set yet at this point.
  let sharedStaticFrameStats: Awaited<ReturnType<typeof computeStaticFrameSet>> | undefined;
  if (
    session.options.motionBlur &&
    session.options.motionBlur.samplesPerFrame === undefined &&
    !session.motionBlurNonSpatialFrames
  ) {
    sharedStaticFrameStats = await computeStaticFrameSet(page, fpsToNumber(session.options.fps));
    session.motionBlurNonSpatialFrames = sharedStaticFrameStats.nonSpatialOnlyFrameSet;
  }
  // Idempotent: the drawElement init path arms dedup BEFORE canvas injection
  // (verification screenshots need the un-injected DOM), and initializeSession
  // calls this again unconditionally afterwards. Once staticFrames is
  // populated, re-running would overwrite the armed state with
  // skipReason="capture_mode" (captureMode is "drawelement" by then) —
  // contradictory telemetry — and re-run the verification seeks. No-op instead.
  if (session.staticFrames || session.staticDedupSkipReason) return;
  // Default ON for everyone; opt out via HF_STATIC_DEDUP in {false,0,off} (resolved into
  // EngineConfig.staticFrameDedup by resolveConfig). Verification is the safety net at scale.
  // Default-on: only an explicit `staticFrameDedup === false` (resolved from
  // HF_STATIC_DEDUP) disables; a missing config leaves dedup enabled.
  session.staticDedupEnabled = session.config?.staticFrameDedup !== false;
  if (!session.staticDedupEnabled) return;
  // Conservative gates: dedup is verified against the plain screenshot path, so only arm
  // where the production capture matches what verification measures, and where reuse is
  // sound. Skip when:
  //  - capture mode is not screenshot (BeginFrame advances the compositor clock per
  //    frame; skipping beginFrame for static frames gaps the tick sequence, and the
  //    verifier uses pageScreenshotCapture not beginFrameCapture — its proof wouldn't
  //    transfer);
  //  - a before-capture hook is set (per-frame video-frame injection — those frames are
  //    NOT static even if the GSAP timeline is idle, and the injector is skipped on reuse);
  //  - page-side compositing is active (shader transitions / drawElement composite paint
  //    a frame the plain verification screenshot doesn't reproduce).
  if (session.captureMode !== "screenshot") {
    session.staticDedupSkipReason = "capture_mode";
    logInitPhase(
      `static-frame dedup: disabled (capture mode ${session.captureMode}, not screenshot)`,
    );
    return;
  }
  if (session.onBeforeCapture) {
    session.staticDedupSkipReason = "video_injection";
    logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
    return;
  }
  const pageComposite = await page
    .evaluate(
      () =>
        typeof (window as unknown as { __hf_page_composite_prepare?: unknown })
          .__hf_page_composite_prepare === "function",
    )
    .catch(() => true); // fail CLOSED: if we can't determine, assume compositing → skip dedup
  if (pageComposite) {
    session.staticDedupSkipReason = "page_composite";
    logInitPhase("static-frame dedup: disabled (page-side compositing active)");
    return;
  }
  const fps = fpsToNumber(session.options.fps);
  const stats = sharedStaticFrameStats ?? (await computeStaticFrameSet(page, fps));
  if (!stats.eligible || stats.staticFrameSet.size === 0) {
    session.staticDedupSkipReason = "ineligible";
    logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
    return;
  }
  const rawSamples = Number(process.env.HF_STATIC_DEDUP_SAMPLES ?? "24");
  const samples = Number.isFinite(rawSamples) && rawSamples >= 1 ? rawSamples : 24;
  session.staticDedupPredictedCount = stats.staticFrameSet.size;
  if (process.env.HF_STATIC_DEDUP_VERIFY === "false") {
    session.staticFrames = stats.staticFrameSet;
    logInitPhase(
      `static-frame dedup: ${stats.staticFrameSet.size}/${stats.totalFrames} frame(s) reusable ` +
        `(verification explicitly disabled)`,
    );
    return;
  }
  let verificationPage: Page | undefined;
  let verdict: StaticVerificationResult;
  try {
    verificationPage = await createStaticVerificationPage(session);
    verdict = await verifyStaticFramesSafe(
      session,
      verificationPage,
      stats.staticFrameSet,
      fps,
      samples,
    );
  } catch {
    session.staticDedupSkipReason = "verification_failed";
    logInitPhase("static-frame dedup: disabled (verification infrastructure failure)");
    return;
  } finally {
    await verificationPage?.close().catch(() => {});
  }
  session.staticDedupVerification = verdict;
  if (verdict.outcome === "mismatch" || verdict.outcome === "infrastructure") {
    session.staticDedupSkipReason = "verification_failed";
    logInitPhase(
      verdict.outcome === "mismatch"
        ? `static-frame dedup: disabled (verification mismatch at predicted-static frame ${verdict.badFrame})`
        : "static-frame dedup: disabled (verification infrastructure failure)",
    );
    return;
  }
  if (verdict.outcome === "unprofitable") {
    session.staticDedupSkipReason = "unprofitable";
    logInitPhase("static-frame dedup: disabled (verification cost cannot save captures)");
    return;
  }
  if (verdict.verifiedFrames.size === 0) {
    session.staticDedupSkipReason = "verification_budget";
    logInitPhase(
      `static-frame dedup: disabled (${verdict.outcome} before frame ${verdict.badFrame}; no run fully verified)`,
    );
    return;
  }
  session.staticFrames = verdict.verifiedFrames;
  logInitPhase(
    `static-frame dedup: ${verdict.verifiedFrames.size}/${stats.staticFrameSet.size} predicted frame(s) reusable ` +
      `(outcome=${verdict.outcome}, runs=${verdict.stats.completedRuns}/${verdict.stats.plannedRuns}, ` +
      `screenshots=${verdict.stats.screenshots}, seeks=${verdict.stats.seeks}, elapsedMs=${verdict.stats.elapsedMs})`,
  );
}

/**
 * Walk window.__timelines and collect frame intervals where GSAP tweens animate
 * compositor-incompatible properties (blend-mode, 3D transforms, clip-path, mask).
 * drawElement cannot reproduce these effects mid-tween → capture those frames via
 * screenshot instead. opacity/filter fades were dropped from the set once Chrome 151
 * fixed crbug 521861819.
 *
 * Returns the union of at-risk frame indices (±1 margin around each tween interval)
 * and totalFrames (for fraction computation by the caller).
 */
async function computeTimelineAtRiskFrames(
  page: Page,
  fps: number,
): Promise<{ frames: Set<number>; totalFrames: number }> {
  const result = await page.evaluate(() => {
    // opacity/autoAlpha/filter fades were removed from this set once Chrome 151
    // fixed crbug 521861819 (drawElementImage dropped promoted opacity layers
    // mid-fade) — those now render correctly on the drawElement path. backdrop-filter
    // and filter:blur stay gated by detectCssEffectRisk (architectural single-element
    // capture limit, not 521861819). What remains here is the per-tween backstop for
    // effects drawElementImage still cannot reproduce mid-animation: mix-blend-mode,
    // CSS 3D transforms (crbug 522872457), clip-path, and mask.
    const AT_RISK_PROPS = new Set([
      "backdropFilter",
      "backdrop-filter",
      "mixBlendMode",
      "mix-blend-mode",
      "rotationX",
      "rotationY",
      "rotateX",
      "rotateY",
      "z",
      "translateZ",
      "clipPath",
      "clip-path",
      "maskImage",
      "mask",
    ]);

    type AnyTween = {
      startTime(): number;
      duration(): number;
      vars?: Record<string, unknown>;
      getChildren?(nested: boolean, tweens: boolean, timelines: boolean): AnyTween[];
    };

    function walkTimeline(
      tl: AnyTween,
      offset: number,
      out: Array<{ start: number; end: number }>,
    ): void {
      if (typeof tl.getChildren !== "function") return;
      for (const child of tl.getChildren(false, true, true)) {
        const childStart = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
        const childDur = typeof child.duration === "function" ? child.duration() : 0;
        if (typeof child.getChildren === "function") {
          walkTimeline(child, childStart, out);
        } else {
          const vars = child.vars || {};
          if (Object.keys(vars).some((k) => AT_RISK_PROPS.has(k))) {
            out.push({ start: childStart, end: childStart + childDur });
          }
        }
      }
    }

    const w = window as unknown as {
      __timelines?: Record<string, AnyTween>;
      __hf?: { duration?: number };
    };
    const timelines = w.__timelines || {};
    const intervals: Array<{ start: number; end: number }> = [];
    for (const tl of Object.values(timelines)) {
      if (tl && typeof tl.getChildren === "function") {
        walkTimeline(tl, 0, intervals);
      }
    }
    const duration = w.__hf?.duration ?? 0;
    return { intervals, duration };
  });

  const { intervals, duration } = result as {
    intervals: Array<{ start: number; end: number }>;
    duration: number;
  };
  const frames = new Set<number>();
  for (const { start, end } of intervals) {
    const lo = Math.floor(start * fps) - 1;
    const hi = Math.ceil(end * fps) + 1;
    for (let f = Math.max(0, lo); f <= hi; f++) {
      frames.add(f);
    }
  }
  const totalFrames = Math.max(1, Math.ceil(duration * fps));
  return { frames, totalFrames };
}
/**
 * True for the drawElement `InvalidStateError: No cached paint record for element`
 * thrown when a subtree element has no paint record for the current frame (display
 * toggled / detached / freshly-shown at a clip-cut boundary). Per-frame, not
 * whole-comp — callers fall back to screenshot for the single frame.
 *
 * This is a NATIVE Chrome DOMException (`drawElementImage`'s own error), so we
 * can't bake a discriminant into it the way we can for our own thrown errors
 * (see {@link isCanvasNotInitializedError}) — Puppeteer's `page.evaluate`
 * error reconstruction also doesn't preserve a usable `.name` for it (comes
 * back generic). Match on the FULL native phrase ("...for element"), not just
 * the generic "No cached paint record" prefix, to cut the odds of an
 * unrelated message coincidentally matching (review: substring-match footgun).
 */
function isNoCachedPaintRecordError(err: unknown): boolean {
  const msg = err instanceof Error ? err.message : String(err);
  return msg.includes("No cached paint record for element");
}

/**
 * True for the drawElement "capture canvas isn't set up yet" error — thrown
 * (or, on the batch path, returned as a string) by drawElementService when
 * the injected capture canvas (`#__hf_de_canvas`) isn't set up yet (observed
 * at frame 0 on some macOS/Chrome combinations, see #3423). Recoverable:
 * the composition root IS present, so `pageScreenshotCapture` captures valid
 * content.
 *
 * This is distinct from the composition-root-missing case
 * (`HF_DE_COMPOSITION_ROOT_MISSING`), which is NOT recoverable — the page
 * has no composition content to screenshot, so falling back would capture
 * blank or navigated-away content.
 *
 * Matches the {@link DE_CANVAS_NOT_INITIALIZED_CODE} discriminant baked into
 * the message (not free-text), so it survives `produceDrawElementFrameBatch`'s
 * "batch produce failed at frame N: <code>: ..." wrapping.
 */
function isCanvasNotInitializedError(err: unknown): boolean {
  const msg = err instanceof Error ? err.message : String(err);
  return msg.includes(DE_CANVAS_NOT_INITIALIZED_CODE);
}

/**
 * Single gate for drawElement failures the fast-capture pipeline knows how to
 * recover from by falling back to screenshot capture instead of aborting the
 * render. Both {@link captureFrameCore} and {@link captureFrameToBufferPipelined}
 * consult this so a newly-recognized recoverable error only needs to be taught
 * here once.
 */
function isRecoverableDrawElementError(err: unknown): boolean {
  return isNoCachedPaintRecordError(err) || isCanvasNotInitializedError(err);
}

/**
 * Per-frame deadline for the drawElement capture round-trip.
 *
 * drawElementImage can return normally and then leave the renderer not draining
 * its task queue: the `setTimeout(…, 0)` that drawAndEncode schedules to run
 * `toDataURL` never fires, so the capture `page.evaluate` never settles.
 * Reproduced deterministically on Chromium 152.0.7977.30, one comp, always the
 * same frame (PRINFRA-488). Nothing below the render-level watchdog bounded
 * this, so a single bad frame failed the ENTIRE render after a 60 s stall.
 *
 * This bounds the round-trip so the producer can discard the wedged page and
 * retry the whole render on a fresh screenshot session. A per-frame screenshot
 * cannot recover because the same page has stopped scheduling. Tune with
 * `HF_DE_FRAME_TIMEOUT_MS`; 0 disables.
 */
const DE_FRAME_TIMEOUT_MS = Number(process.env.HF_DE_FRAME_TIMEOUT_MS ?? "15000");

class DeFrameTimeoutError extends Error {
  constructor(label: string, ms: number) {
    super(`drawElement ${label} exceeded ${ms}ms (renderer stopped scheduling; see PRINFRA-488)`);
    this.name = "DeFrameTimeoutError";
  }
}

/**
 * Race `work` against a deadline. The losing promise is NOT cancellable —
 * puppeteer cannot abort an in-flight `page.evaluate` — so its rejection is
 * swallowed to avoid an unhandled rejection when it eventually settles (or
 * never does). The orphaned round-trip keeps running in its Chrome worker;
 * that worker is reclaimed by the outer retry rebuilding the page
 * (`closeOrphanedProbeForRetry`), not by anything here.
 *
 * `onTimeout` fires exactly when the deadline wins, and is the ONLY place the
 * stall is observable: because the deadline races `work` from outside, nothing
 * inside `work` — including its own catch blocks — ever sees this error.
 *
 * Exported for the deadline unit test; `captureFrameToBuffer` is the only
 * production caller.
 */
export async function withFrameDeadline<T>(
  work: Promise<T>,
  label: string,
  ms: number,
  onTimeout?: () => void,
): Promise<T> {
  if (!(ms > 0)) return work;
  let timer: ReturnType<typeof setTimeout> | undefined;
  const guard = new Promise<never>((_resolve, reject) => {
    timer = setTimeout(() => {
      onTimeout?.();
      reject(new DeFrameTimeoutError(label, ms));
    }, ms);
  });
  try {
    return await Promise.race([work, guard]);
  } finally {
    if (timer) clearTimeout(timer);
    void work.catch(() => {
      /* orphaned round-trip — see doc above */
    });
  }
}

/**
 * Resolve the session's motion-blur plan, rejecting combinations the accumulation pass
 * cannot render correctly instead of silently producing an unblurred frame.
 *
 * Called once initialization has settled the capture mode. `format: "png"` is required
 * because samples are averaged pixel by pixel: JPEG samples would be averaged after
 * lossy quantization and the blended frame is re-encoded as PNG.
 */
export function resolveSessionMotionBlur(session: CaptureSession): MotionBlurPlan | undefined {
  const plan = resolveMotionBlurPlan(session.options.motionBlur);
  if (!plan) return undefined;
  if (session.captureMode !== "screenshot") {
    throw new Error(
      `[MotionBlur] sub-frame motion blur requires screenshot capture mode, got "${session.captureMode}"`,
    );
  }
  if (session.options.format !== "png") {
    throw new Error(
      `[MotionBlur] sub-frame motion blur requires format "png", got "${session.options.format ?? "jpeg"}"`,
    );
  }
  return plan;
}

/** Frame timings shared by the single-capture and accumulation paths. */
interface CapturedSurface {
  buffer: Buffer;
  quantizedTime: number;
  seekMs: number;
  beforeCaptureMs: number;
  screenshotMs: number;
}

/** Seek to `time` and capture one surface with the session's capture mode. */
async function captureFrameSurface(
  session: CaptureSession,
  frameIndex: number,
  time: number,
  seekOptions?: HfSeekOptions,
  heldVideoTime?: number,
): Promise<CapturedSurface> {
  const { page, options } = session;
  const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
    session,
    frameIndex,
    time,
    seekOptions,
    heldVideoTime,
  );

  const screenshotStart = Date.now();
  let screenshotBuffer: Buffer;

  if (session.captureMode === "beginframe") {
    const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
    if (!session.beginFrameSeekPresented) {
      // A session's first capture can return the frame composited during init instead of
      // this seek, so display the seek once at a tick between the probe and this capture.
      const client = await getCdpSession(page);
      await client.send("HeadlessExperimental.beginFrame", {
        frameTimeTicks: frameTimeTicks - session.beginFrameIntervalMs / 2,
        interval: session.beginFrameIntervalMs,
        noDisplayUpdates: false,
      });
      session.beginFrameSeekPresented = true;
    }
    const result = await beginFrameCapture(
      page,
      options,
      frameTimeTicks,
      session.beginFrameIntervalMs,
    );
    if (result.hasDamage) session.beginFrameHasDamageCount++;
    else session.beginFrameNoDamageCount++;
    screenshotBuffer = result.buffer;
  } else if (
    session.captureMode === "drawelement" &&
    session.clipBoundaryFrames?.has(frameIndex) &&
    process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true"
  ) {
    throw new DrawElementCaptureError(
      frameIndex,
      "boundary screenshot requested on an injected canvas page",
    );
  } else if (session.captureMode === "drawelement") {
    // Advance compositor state via BeginFrame when available (Linux headless-shell);
    // on macOS the compositor advances naturally without BeginFrame.
    if (session.beginFrameTimeTicks > 0) {
      const client = await getCdpSession(page);
      await client.send("HeadlessExperimental.beginFrame", {
        frameTimeTicks: session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs,
        interval: session.beginFrameIntervalMs,
        noDisplayUpdates: false,
        // no screenshot param — we capture via canvas
      });
    }
    try {
      screenshotBuffer = await captureDrawElementFrame(
        page,
        options.width,
        options.height,
        options.format ?? "jpeg",
        options.quality ?? 80,
        // Paint-event sync only without BeginFrame (macOS / screenshot-launched):
        // under BeginFrame control the per-frame beginFrame above already painted
        // a fresh snapshot, and no further paint would arrive during a wait.
        session.beginFrameTimeTicks === 0,
      );
      // A tiny JPEG may be a dropped paint record. Never screenshot this page:
      // its injected canvas can still hold the preceding frame's bitmap.
      // Restart on a fresh screenshot page even if this was a simple valid frame.
      if ((options.format ?? "jpeg") !== "png" && process.env.HF_FORCE_DRAWELEMENT !== "1") {
        const sizes = (session.deFrameSizes ??= []);
        const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
        const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
        const floor = Math.max(20000, median * 0.12);
        if (screenshotBuffer.length < floor) {
          throw new DrawElementCaptureError(
            frameIndex,
            `suspect small frame (${screenshotBuffer.length}B < ${Math.round(floor)}B)`,
          );
        } else {
          if (sizes.length >= 60) sizes.shift();
          sizes.push(screenshotBuffer.length);
        }
      }
    } catch (err) {
      // Missing paint records/canvas state require a new screenshot page.
      if (isRecoverableDrawElementError(err)) {
        session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
        const reason = isCanvasNotInitializedError(err)
          ? "drawElement canvas not initialized"
          : "No cached paint record";
        throw new DrawElementCaptureError(frameIndex, reason, err);
      } else {
        throw err;
      }
    }
  } else {
    screenshotBuffer = await pageScreenshotCapture(page, options);
  }

  const screenshotMs = Date.now() - screenshotStart;

  return { buffer: screenshotBuffer, quantizedTime, seekMs, beforeCaptureMs, screenshotMs };
}

/**
 * Mark the session ready to capture.
 *
 * The single owner of what finishing initialization means, because `initializeSession`
 * has two exits: screenshot mode returns early, and every other mode falls through the
 * end. Resolving motion blur at only one of them marks the session ready with no plan,
 * which silently renders unblurred rather than failing. Both fields are set here so a
 * third exit cannot forget one.
 */
function finalizeSessionInit(session: CaptureSession): void {
  session.motionBlur = resolveSessionMotionBlur(session);
  session.isInitialized = true;
  startChromeMemorySampler(session);
}

/** Shape of one `SystemInfo.getProcessInfo` row; only the fields we read. */
export interface CdpProcessInfoRow {
  type: string;
  id: number;
  cpuTime: number;
}

/** Group Chrome child pids by role. `browser` comes from puppeteer, not CDP. */
export function classifyChromeProcesses(
  browserPid: number | undefined,
  processInfo: readonly CdpProcessInfoRow[],
): ChromePids {
  const renderers: number[] = [];
  const gpu: number[] = [];
  for (const row of processInfo) {
    if (row.type === "renderer") renderers.push(row.id);
    else if (row.type === "GPU") gpu.push(row.id);
  }
  return browserPid === undefined ? { renderers, gpu } : { browser: browserPid, renderers, gpu };
}

/** The slice of a CDP session `readChromePids` needs. */
interface ProcessInfoCdpSession {
  send(method: "SystemInfo.getProcessInfo"): Promise<{
    processInfo: readonly CdpProcessInfoRow[];
  }>;
  detach(): Promise<void>;
}

/**
 * Chrome pids for one browser. `SystemInfo.getProcessInfo` is served ONLY by
 * the browser target — a page-target session rejects with "is only supported
 * on the browser target", which the sampler would swallow into a permanently
 * empty reading. Hence the explicit browser-session factory.
 */
export async function readChromePids(
  browserPid: number | undefined,
  createBrowserCdpSession: () => Promise<ProcessInfoCdpSession>,
): Promise<ChromePids> {
  const cdp = await createBrowserCdpSession();
  try {
    const info = await cdp.send("SystemInfo.getProcessInfo");
    return classifyChromeProcesses(browserPid, info.processInfo);
  } finally {
    await cdp.detach().catch(() => {});
  }
}

const CHROME_MEMORY_SAMPLE_MS_DEFAULT = 2_000;

function resolveChromeMemorySampleMs(): number {
  const raw = process.env.HF_CHROME_MEMORY_SAMPLE_MS;
  const parsed = raw === undefined ? Number.NaN : Number(raw);
  return Number.isFinite(parsed) && parsed >= 250 ? parsed : CHROME_MEMORY_SAMPLE_MS_DEFAULT;
}

function startChromeMemorySampler(session: CaptureSession): void {
  if (session.chromeMemory) return;
  if (process.env.HF_CHROME_MEMORY_SAMPLER === "false") return;
  const sampler = createChromeMemorySampler({
    intervalMs: resolveChromeMemorySampleMs(),
    onSample: session.options.onMemorySample,
    sampleRss: (pids) => sampleProcessRss(pids),
    getPids: () =>
      readChromePids(session.browser.process()?.pid, () =>
        session.browser.target().createCDPSession(),
      ),
  });
  session.chromeMemory = sampler;
  sampler.start();
}

/** Choose how many samples this frame gets when the plan is adaptive: the floor with
 * no probe for a frame confirmed non-spatial, otherwise two edge probes (see
 * motionBlurProbeTimes) mapped through adaptiveSampleCount. Probe cost is returned
 * alongside the count so the caller folds it into the frame's timing totals. */
async function resolveAdaptiveSampleCount(
  session: CaptureSession,
  frameIndex: number,
  absFrameIndex: number,
  plan: MotionBlurPlan,
  fps: number,
  sampleSeek: HfSeekOptions,
  frameTime: number,
): Promise<{
  samplesPerFrame: number;
  seekMs: number;
  beforeCaptureMs: number;
  screenshotMs: number;
}> {
  if (session.motionBlurNonSpatialFrames?.has(absFrameIndex)) {
    return {
      samplesPerFrame: DEFAULT_SAMPLES_PER_FRAME,
      seekMs: 0,
      beforeCaptureMs: 0,
      screenshotMs: 0,
    };
  }
  const { windowStart, windowEnd } = motionBlurProbeTimes(plan, absFrameIndex, fps);
  const probeA = await captureFrameSurface(session, frameIndex, windowStart, sampleSeek, frameTime);
  const probeB = await captureFrameSurface(session, frameIndex, windowEnd, sampleSeek, frameTime);
  return {
    samplesPerFrame: adaptiveSampleCount(probeDiffMagnitude(probeA.buffer, probeB.buffer)),
    seekMs: probeA.seekMs + probeB.seekMs,
    beforeCaptureMs: probeA.beforeCaptureMs + probeB.beforeCaptureMs,
    screenshotMs: probeA.screenshotMs + probeB.screenshotMs,
  };
}

/**
 * Capture one output frame as the average of some number of sub-frame captures — fixed
 * by the caller, or chosen per frame from measured motion (see
 * `resolveAdaptiveSampleCount`).
 *
 * Callback invariant: exactly one eventful seek per output frame, at the frame time,
 * arriving from the previous frame's time. Every sample seek (including a probe)
 * suppresses events and the playhead is restored to the frame time afterwards, so a
 * composition's own onUpdate/onComplete fire on the same interval boundaries as a
 * render with blur off.
 */
async function captureAccumulatedFrame(
  session: CaptureSession,
  frameIndex: number,
  absFrameIndex: number,
  plan: MotionBlurPlan,
): Promise<CapturedSurface> {
  const fps = fpsToNumber(session.options.fps);
  const frameTime = quantizeSeekTime(absFrameIndex / fps, fps);

  const eventfulSeekStart = Date.now();
  session.captureStep = "seeking the timeline";
  await seekPageTimeline(session.page, frameTime, undefined);
  const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
  if (session.onBeforeCapture) {
    // The injector copies a video's own style only when its frame changes: inject at frameTime
    // first so the held frame carries frameTime's style, not the first sample's.
    const injectStart = Date.now();
    session.captureStep = "injecting video frames";
    await session.onBeforeCapture(session.page, frameTime, frameTime);
    totals.beforeCaptureMs += Date.now() - injectStart;
  }

  const sampleSeek: HfSeekOptions = {
    suppressEvents: true,
    subFrameDivisions: plan.subFrameDivisions,
  };

  let samplesPerFrame = plan.fixedSamplesPerFrame;
  if (samplesPerFrame === null) {
    const chosen = await resolveAdaptiveSampleCount(
      session,
      frameIndex,
      absFrameIndex,
      plan,
      fps,
      sampleSeek,
      frameTime,
    );
    samplesPerFrame = chosen.samplesPerFrame;
    totals.seekMs += chosen.seekMs;
    totals.beforeCaptureMs += chosen.beforeCaptureMs;
    totals.screenshotMs += chosen.screenshotMs;
  }

  const accumulator = new MotionBlurAccumulator(plan.blend);
  for (const sampleTime of motionBlurSampleTimes(plan, absFrameIndex, fps, samplesPerFrame)) {
    const sample = await captureFrameSurface(
      session,
      frameIndex,
      sampleTime,
      sampleSeek,
      frameTime,
    );
    totals.seekMs += sample.seekMs;
    totals.beforeCaptureMs += sample.beforeCaptureMs;
    totals.screenshotMs += sample.screenshotMs;
    accumulator.add(sample.buffer);
  }

  const restoreSeekStart = Date.now();
  session.captureStep = "seeking the timeline";
  await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
  totals.seekMs += Date.now() - restoreSeekStart;

  const blended = accumulator.finish();
  return {
    buffer: encodePng(blended.width, blended.height, blended.data),
    quantizedTime: frameTime,
    ...totals,
  };
}

async function captureFrameCore(
  session: CaptureSession,
  frameIndex: number,
  time: number,
): Promise<{ buffer: Buffer; quantizedTime: number; captureTimeMs: number }> {
  const { 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.lastFrameAbsoluteIndex === absFrameIndex - 1 &&
    (!session.motionBlur ||
      motionBlurWindowIsStatic(session.motionBlur, absFrameIndex, session.staticFrames))
  ) {
    session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
    session.lastFrameAbsoluteIndex = absFrameIndex;
    return {
      buffer: session.lastFrameBuffer,
      quantizedTime: quantizeTimeToFrame(time, fpsToNumber(options.fps)),
      captureTimeMs: Date.now() - startTime,
    };
  }

  try {
    const plan = session.motionBlur;
    // One capture per frame, or `plan.samplesPerFrame` captures averaged into one. Both
    // report the same timings, so perf accounting and the dedup anchor stay shared.
    const { buffer, quantizedTime, seekMs, beforeCaptureMs, screenshotMs } = plan
      ? await captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
      : await captureFrameSurface(session, frameIndex, time);
    const captureTimeMs = Date.now() - startTime;

    session.capturePerf.frames += 1;
    session.capturePerf.seekMs += seekMs;
    session.capturePerf.beforeCaptureMs += beforeCaptureMs;
    session.capturePerf.screenshotMs += screenshotMs;
    session.capturePerf.totalMs += captureTimeMs;
    session.capturePerf.frameMs.push(captureTimeMs);
    if (session.capturePerf.frames === 1) {
      const blur = await describePageMotionBlur(session.page).catch(() => null);
      if (blur) console.log(blur);
    }

    // Retain this freshly-captured buffer so the following static frames can reuse it.
    if (session.staticFrames) {
      session.lastFrameBuffer = buffer;
      session.lastFrameAbsoluteIndex = absFrameIndex;
    }

    return { buffer, quantizedTime, captureTimeMs };
  } catch (captureError) {
    if (session.isInitialized) {
      await captureFrameErrorDiagnostics(
        session,
        frameIndex,
        time,
        captureError instanceof Error ? captureError : new Error(String(captureError)),
      );
    }
    throw captureError;
  }
}

export async function captureFrame(
  session: CaptureSession,
  frameIndex: number,
  time: number,
): Promise<CaptureResult> {
  const { buffer, quantizedTime, captureTimeMs } = await captureFrameCore(
    session,
    frameIndex,
    time,
  );
  const framePath = writeCapturedFrame(session, frameIndex, buffer);
  return { frameIndex, time: quantizedTime, path: framePath, captureTimeMs };
}

/**
 * File extension for a captured frame, keyed on the format the frames were actually
 * captured in. The encoder's input pattern and the writer must agree, so both read this
 * rather than re-deriving the answer from whether the OUTPUT needs alpha, which is a
 * different question and stops being equivalent as soon as anything else forces PNG.
 */
export function frameFileExtension(format: "jpeg" | "png" | undefined): "png" | "jpg" {
  return format === "png" ? "png" : "jpg";
}

/**
 * Write an already-captured frame buffer to the session's output dir using the
 * canonical `frame_NNNNNN.{jpg,png}` naming. `fileIndex` is the ENCODER-facing
 * index (0-based within the captured range), which may differ from the absolute
 * composition frame index used for seeking/boundary lookups. Extracted so the
 * disk worker-encode pipeline can write a buffer produced by
 * `captureFrameToBufferPipelined` without duplicating the naming convention.
 */
export function writeCapturedFrame(
  session: CaptureSession,
  fileIndex: number,
  buffer: Buffer,
): string {
  const ext = frameFileExtension(session.options.format);
  const framePath = join(session.outputDir, `frame_${String(fileIndex).padStart(6, "0")}.${ext}`);
  writeFileSync(framePath, buffer);
  return framePath;
}

/**
 * Capture a frame and return the screenshot as a Buffer instead of writing to disk.
 * Used by the streaming encode pipeline to pipe frames directly to FFmpeg stdin.
 */
export async function captureFrameToBuffer(
  session: CaptureSession,
  frameIndex: number,
  time: number,
): Promise<CaptureBufferResult> {
  const { buffer, captureTimeMs } =
    session.captureMode === "drawelement"
      ? await withFrameDeadline(
          captureFrameCore(session, frameIndex, time),
          `frame ${frameIndex}`,
          DE_FRAME_TIMEOUT_MS,
          () => {
            // Deliberately NO per-frame screenshot fallback. When the renderer
            // stops scheduling it is wedged for EVERY subsequent round-trip on
            // that page — measured: the screenshot fallback blew the same
            // deadline. Fail fast and let the producer re-render the whole comp
            // on a fresh page via the screenshot path, the only recovery that
            // works. Counted here rather than in captureFrameCore's catch: the
            // deadline rejects from outside it, so that catch never runs.
            session.deFrameTimeouts = (session.deFrameTimeouts ?? 0) + 1;
            console.log(
              `[engine] fast capture frame ${frameIndex}: capture exceeded ` +
                `${DE_FRAME_TIMEOUT_MS}ms; renderer stalled after drawElementImage ` +
                `(PRINFRA-488). Failing the drawElement attempt so the whole render ` +
                `retries via screenshot.`,
            );
          },
        )
      : await captureFrameCore(session, frameIndex, time);

  return { buffer, captureTimeMs };
}

/**
 * Pipelined drawElement frame capture for the worker-encode path.
 *
 * Performs seek prep + paint-wait + drawElementImage + composite +
 * `createImageBitmap` + transfers the bitmap to the in-page encode worker.
 * Returns `encodeResult` immediately (before the worker finishes encoding).
 * The caller overlaps frame N's encode with frame N+1's produce phase.
 *
 * Requirements:
 *  - `session.workerEncodeEnabled` must be true (set by initializeSession when
 *    `config.enableDrawElementWorkerEncode` is true and mode resolved to drawelement).
 *  - JPEG format only. PNG falls back to `captureFrameToBuffer`.
 *  - macOS hardware GPU path (syncToPaintEvent=true, beginFrameTimeTicks=0).
 *    BeginFrame (Linux) uses the standard synchronous path unchanged.
 */
/**
 * Worker-encode path, gated to drawElement capture. It does not route through
 * `captureFrameCore` and so has no accumulation branch; that is safe only because
 * `resolveSessionMotionBlur` rejects every capture mode except screenshot, which makes
 * this function unreachable with motion blur on. Widening the supported capture modes
 * means handling accumulation here too.
 */
export async function captureFrameToBufferPipelined(
  session: CaptureSession,
  frameIndex: number,
  time: number,
): Promise<{ encodeResult: Promise<Buffer>; captureTimeMs: number }> {
  const { page, options } = session;
  const startTime = Date.now();

  // Task B: static-frame dedup (worker path). Reuse the prior frame's encode result
  // and skip the seek + drawElement + encode entirely. Same predicate as the serial
  // path; clip-cut frames are excluded from staticFrames so they always capture.
  if (session.staticFrames?.has(frameIndex) && session.lastEncodeResult) {
    // Reuse is valid only when EVERY frame in (lastEncodeResultFrame, i] is
    // predicted-static — then all of them (and the reused buffer) share the
    // same pixels. Sequential capture reduces to has(i) (gap = {i}); the
    // interleaved parallel stride makes the gap N frames wide.
    const lastIdx = session.lastEncodeResultFrame ?? frameIndex - 1;
    let gapStatic = true;
    for (let j = lastIdx + 1; j <= frameIndex; j++) {
      if (!session.staticFrames.has(j)) {
        gapStatic = false;
        break;
      }
    }
    if (gapStatic) {
      session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
      session.capturePerf.frames += 1;
      // Advance the watermark on reuse too, not just on real captures — the
      // gap-check above starts from lastEncodeResultFrame, so leaving it
      // pinned to the last REAL capture makes every consecutive reuse rescan
      // an ever-widening window instead of just the one new frame (review).
      session.lastEncodeResultFrame = frameIndex;
      return { encodeResult: session.lastEncodeResult, captureTimeMs: Date.now() - startTime };
    }
  }

  try {
    const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
      session,
      frameIndex,
      time,
    );
    void quantizedTime;

    if (
      session.clipBoundaryFrames?.has(frameIndex) &&
      process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true"
    ) {
      throw new DrawElementCaptureError(
        frameIndex,
        "boundary screenshot requested on an injected canvas page",
      );
    }

    // Worker-encode is gated to the macOS GPU path (beginFrameTimeTicks === 0,
    // syncToPaintEvent = true); see initDrawElementOrTransparentBackground. The
    // BeginFrame branch present in the synchronous captureFrameCore is therefore
    // unreachable here and intentionally omitted.
    const { encodeResult } = await produceDrawElementFrame(
      page,
      options.width,
      options.height,
      options.quality ?? 80,
      true,
    );

    const captureTimeMs = Date.now() - startTime;

    session.capturePerf.frames += 1;
    session.capturePerf.seekMs += seekMs;
    session.capturePerf.beforeCaptureMs += beforeCaptureMs;
    // screenshotMs reflects produce time only (encode is async, not tracked here)
    session.capturePerf.screenshotMs += captureTimeMs - seekMs - beforeCaptureMs;
    session.capturePerf.totalMs += captureTimeMs;
    session.capturePerf.frameMs.push(captureTimeMs);

    // Task B: retain this encode result so a following static frame can reuse it.
    if (session.staticFrames) {
      session.lastEncodeResult = encodeResult;
      session.lastEncodeResultFrame = frameIndex;
    }

    return { encodeResult, captureTimeMs };
  } catch (captureError) {
    // Mirror captureFrameCore: capture per-frame diagnostics (frame-error
    // PNG/HTML/JSON + console tail) before rethrowing so pipelined-path
    // failures are debuggable like the serial path. Runs BEFORE the
    // recoverable-error wrapper below because the serial path's diagnostics
    // sit in an outer catch that its own DrawElementCaptureError throw
    // propagates through — ordering it after the wrapper would silently skip
    // the bundle for exactly the NCPR/canvas failures worth debugging.
    // Bounded: a recoverable error aborts the whole attempt, so this fires at
    // most once per attempt. captureFrameErrorDiagnostics self-catches, so a
    // dead page cannot mask the structural error the producer retries on.
    if (session.isInitialized) {
      await captureFrameErrorDiagnostics(
        session,
        frameIndex,
        time,
        captureError instanceof Error ? captureError : new Error(String(captureError)),
      );
    }
    // The viewport can contain the last injected bitmap, not the sought frame.
    if (isRecoverableDrawElementError(captureError)) {
      session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
      const reason = isCanvasNotInitializedError(captureError)
        ? "drawElement canvas not initialized"
        : "No cached paint record";
      throw new DrawElementCaptureError(frameIndex, reason, captureError);
    }
    throw captureError;
  }
}

/**
 * Verification-grade single-frame recapture for the producer's blank-frame
 * guard. Unlike {@link captureFrameToBufferPipelined} it takes NO shortcuts
 * and has NO fallbacks, both of which can return the WRONG FRAME's pixels at
 * drain time:
 *  - the static-dedup fast path returns session.lastEncodeResult, which by
 *    drain time can hold a frame several indices AHEAD of the suspect frame;
 *  - a screenshot of the injected page may hold the LAST drawn drawElement
 *    frame, not this one. Capture failures therefore require a fresh page.
 * Any failure here throws; the caller treats that as verification failure and
 * falls back the whole render (correct, never wrong-frame).
 */
export async function recaptureDrawElementFrameForVerify(
  session: CaptureSession,
  frameIndex: number,
  time: number,
): Promise<Buffer> {
  const { page, options } = session;
  if (!session.isInitialized) {
    throw new Error("[FrameCapture] Session not initialized");
  }
  await prepareFrameForCapture(session, frameIndex, time);
  const { encodeResult } = await produceDrawElementFrame(
    page,
    options.width,
    options.height,
    options.quality ?? 80,
    true,
  );
  return encodeResult;
}

/**
 * P6 prototype (HF_DE_BATCH): capture N consecutive frames in one CDP
 * round-trip via {@link produceDrawElementFrameBatch}. The caller pre-plans the
 * batch (consecutive frame indices, none static-dedup'd, none opt-in
 * boundary-screenshot). On a mid-batch in-page failure the remaining frames'
 * handling depends on whether the failure is one of the recoverable
 * per-frame drawElement conditions (canvas-not-initialized / no-cached-paint-
 * record, #3423):
 *  - Recoverable: reject the batch with DrawElementCaptureError so the producer
 *    re-renders on a fresh screenshot page. The injected canvas is not a valid
 *    screenshot fallback surface.
 *  - Anything else (unrecognized error): fall through to
 *    {@link captureFrameToBufferPipelined}, which re-attempts drawElement (so
 *    a genuinely transient, non-drawElement-specific failure still gets a
 *    second chance) and owns the same recoverable-error/fatal-error split for
 *    whatever it encounters — so failure behavior for a truly fatal error is
 *    identical to the unbatched path, just discovered at batch granularity.
 */
export async function captureFramesBatchPipelined(
  session: CaptureSession,
  frameIndices: number[],
  times: number[],
): Promise<Array<{ frameIndex: number; encodeResult: Promise<Buffer> }>> {
  const { page, options } = session;
  if (!session.isInitialized) {
    throw new Error("[FrameCapture] Session not initialized");
  }
  assertVfxIntact(session);
  const startTime = Date.now();
  const fps = fpsToNumber(options.fps);
  const quantized = times.map((t) => quantizeTimeToFrame(t, fps));

  session.captureStep = "capturing the frame";
  const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch(
    page,
    quantized,
    options.width,
    options.height,
    options.quality ?? 80,
  );

  // A later batch failure abandons this prefix. Its asynchronous encodes can
  // still reject while session cleanup shuts the worker down.
  for (const result of encodeResults) void result.catch(() => {});

  const okCount = failedAt === null ? frameIndices.length : failedAt;
  const elapsed = Date.now() - startTime;
  session.capturePerf.frames += okCount;
  // Round-trips are fused — attribute the whole batch to produce time; each
  // frame gets the batch mean for the per-frame sample series.
  session.capturePerf.screenshotMs += elapsed;
  session.capturePerf.totalMs += elapsed;
  if (okCount > 0) {
    const perFrame = elapsed / okCount;
    for (let s2 = 0; s2 < okCount; s2++) session.capturePerf.frameMs.push(perFrame);
  }

  const results: Array<{ frameIndex: number; encodeResult: Promise<Buffer> }> = [];
  for (let i = 0; i < okCount; i++) {
    const frameIndex = frameIndices[i];
    const encodeResult = encodeResults[i];
    if (frameIndex === undefined || !encodeResult) break;
    results.push({ frameIndex, encodeResult });
  }

  if (failedAt !== null) {
    // `error` is a plain string here (produceDrawElementFrameBatch returns it
    // out of an in-page evaluate rather than throwing an Error instance) —
    // isRecoverableDrawElementError accepts `unknown` and stringifies non-Error
    // input, so passing the string straight through classifies it correctly,
    // including through produceDrawElementFrameBatch's own error text (which
    // embeds the same DE_CANVAS_NOT_INITIALIZED_CODE / native paint-record
    // phrase the per-frame paths match on).
    if (isRecoverableDrawElementError(error)) {
      const reason = isCanvasNotInitializedError(error)
        ? "drawElement canvas not initialized"
        : "No cached paint record";
      session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
      throw new DrawElementCaptureError(frameIndices[failedAt] ?? failedAt, reason, error);
    } else {
      console.log(
        `[engine] fast capture: batch produce failed at frame ` +
          `${frameIndices[failedAt] ?? "?"} (${error ?? "?"}); ` +
          `re-capturing ${frameIndices.length - failedAt} frame(s) per-frame`,
      );
      for (let i = failedAt; i < frameIndices.length; i++) {
        const frameIndex = frameIndices[i];
        const time = times[i];
        if (frameIndex === undefined || time === undefined) break;
        const { encodeResult } = await captureFrameToBufferPipelined(session, frameIndex, time);
        results.push({ frameIndex, encodeResult });
      }
    }
  }

  // Task B: retain the last encode result so a following static frame can reuse it.
  const last = results[results.length - 1];
  if (session.staticFrames && last) session.lastEncodeResult = last.encodeResult;

  return results;
}

/**
 * Type of the "inner capture" function consumed by
 * {@link discardWarmupCapture}. Matches the real `captureFrameCore` signature
 * with the buffer-bearing result trimmed to what the caller actually uses
 * (the wrapper never inspects the buffer). Exposed so unit tests can inject
 * a stub instead of driving Chrome end-to-end.
 */
export type DiscardWarmupInnerCapture = (
  session: CaptureSession,
  frameIndex: number,
  time: number,
) => Promise<{ buffer: Buffer; quantizedTime: number; captureTimeMs: number }>;

/**
 * Perform one capture, throw away the buffer, and restore any session
 * side-effects (perf counters, BeginFrame damage tallies) so downstream
 * captures see state identical to a fresh session.
 *
 * Distributed chunk workers need this because Chrome's BeginFrame screenshot
 * pipeline maintains a per-process `lastFrameCache`: when a captured frame's
 * `hasDamage` reports `false`, the screenshot path returns the previously
 * captured buffer. For chunk N (N > 0) the worker has no prior frame in its
 * cache, so the very first capture's `hasDamage` reporting diverges from
 * what an in-process render at the same absolute frame index would see (the
 * in-process renderer always has frame N-1 cached). One discard capture
 * before the first real capture primes the cache.
 *
 * The function intentionally restores perf state so the warmup capture does
 * NOT bias `getCapturePerfSummary()`'s per-frame averages.
 *
 * No file is written; the buffer is discarded.
 *
 * @param session — initialized capture session
 * @param frameIndex — frame index to warm up with (default 0). Chunk
 *   workers typically pass their chunk's first absolute frame index.
 * @param time — time in seconds (default 0). Chunk workers typically pass
 *   the corresponding `frameIndex / fps`.
 * @param innerCapture — injectable for tests; defaults to the real
 *   `captureFrameCore`.
 */
export async function discardWarmupCapture(
  session: CaptureSession,
  frameIndex: number = 0,
  time: number = 0,
  innerCapture: DiscardWarmupInnerCapture = captureFrameCore,
): Promise<void> {
  // The discarded capture mutates frameMs, so preserve its samples by value.
  const perfBefore = { ...session.capturePerf, frameMs: [...session.capturePerf.frameMs] };
  const hasDamageBefore = session.beginFrameHasDamageCount;
  const noDamageBefore = session.beginFrameNoDamageCount;
  const dedupCountBefore = session.staticDedupCount;
  const lastFrameBufferBefore = session.lastFrameBuffer;
  const lastFrameAbsoluteIndexBefore = session.lastFrameAbsoluteIndex;
  try {
    await innerCapture(session, frameIndex, time);
  } finally {
    // Always restore — even on error. A failed warmup capture should not
    // leak inflated perf counters, a phantom dedup reuse, or a warmup-era
    // lastFrameBuffer anchor into the real capture summary/state.
    session.capturePerf = perfBefore;
    session.beginFrameHasDamageCount = hasDamageBefore;
    session.beginFrameNoDamageCount = noDamageBefore;
    session.staticDedupCount = dedupCountBefore;
    session.lastFrameBuffer = lastFrameBufferBefore;
    session.lastFrameAbsoluteIndex = lastFrameAbsoluteIndexBefore;
  }
}

export async function closeCaptureSession(session: CaptureSession): Promise<void> {
  if (session.chromeMemory) {
    session.chromeMemory.stop();
    // One last sample so the summary reflects the session's end state, not a
    // point up to `intervalMs` earlier. Best effort; the page may be gone.
    await session.chromeMemory.sampleOnce();
  }
  if (session.page && !session.pageReleased) {
    const blur = await describePageMotionBlurAtEnd(session.page);
    if (blur) console.log(blur);
  }
  // Realized static-dedup telemetry: how much the cache actually helped this
  // render (vs the prediction logged at arm time). Both capture paths
  // (sequential orchestrator + parallel workers) close their session here, so
  // this is the one uniform emit point. Zero the count afterward so the
  // idempotent re-close (HDR cleanup) doesn't double-log.
  const reused = session.staticDedupCount ?? 0;
  if (session.staticFrames && reused > 0) {
    const captured = session.capturePerf.frames; // excludes reuses by design
    const total = captured + reused;
    const pct = total > 0 ? Math.round((reused / total) * 100) : 0;
    const avgTotalMs = captured > 0 ? Math.round(session.capturePerf.totalMs / captured) : 0;
    console.log(
      `[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
        `est. ~${reused * avgTotalMs}ms saved (avg ${avgTotalMs}ms/frame)`,
    );
    session.staticDedupCount = 0;
  }
  // INVARIANT: closeCaptureSession is idempotent. The renderOrchestrator HDR
  // cleanup path tracks a `domSessionClosed` flag and may still re-call this
  // in the outer finally if the inner cleanup raised before the flag flipped.
  //
  // Naive idempotency would be unsafe under pool semantics: releaseBrowser
  // decrements pooledBrowserRefCount, so calling it twice for the same
  // acquire could close a browser that another session still holds. We make
  // it safe by gating each release behind a per-session "released" flag —
  // the second call sees the flag already set and skips the release.
  //
  // We set the flag AFTER (not before) the await so that if a release throws
  // midway, the unreleased resource is retried by the outer defensive call.
  // Example: page release succeeds, browser release throws → pageReleased=true
  // but browserReleased=false → second call no-ops on page and retries browser.
  // This matches the orchestrator's intent for HDR cleanup.
  if (session.workerEncodeEnabled && session.page && !session.pageReleased) {
    cleanupDrawElementWorkerEncode(session.page);
  }
  if (!session.pageReleased && session.page) {
    const pageClosed = await waitForCloseWithTimeout(session.page.close());
    if (!pageClosed) {
      console.warn("[FrameCapture] Timed out closing page; forcing browser process shutdown");
      if (session.browserLease) session.browserLease.forceRelease();
      else forceReleaseBrowser(session.browser);
      session.browserReleased = true;
    }
    session.pageReleased = true;
  }
  if (!session.browserReleased && session.browser) {
    const browserClosed = await waitForCloseWithTimeout(
      session.browserLease?.release() ?? releaseBrowser(session.browser, session.config),
    );
    if (!browserClosed) {
      console.warn("[FrameCapture] Timed out closing browser; forcing browser process shutdown");
      if (session.browserLease) session.browserLease.forceRelease();
      else forceReleaseBrowser(session.browser);
    }
    session.browserReleased = true;
  }
  session.isInitialized = false;
}

export function prepareCaptureSessionForReuse(
  session: CaptureSession,
  outputDir: string,
  onBeforeCapture: BeforeCaptureHook | null,
): void {
  if (!existsSync(outputDir)) {
    mkdirSync(outputDir, { recursive: true });
  }
  session.outputDir = outputDir;
  session.onBeforeCapture = onBeforeCapture;
  session.capturePerf = {
    frames: 0,
    seekMs: 0,
    beforeCaptureMs: 0,
    screenshotMs: 0,
    totalMs: 0,
    frameMs: [],
  };
  session.beginFrameHasDamageCount = 0;
  session.beginFrameNoDamageCount = 0;
  // Reset per-render dedup state so a buffer captured by the prior render/probe can't
  // bleed into this render's first static frame. staticFrames (the armed set) is left
  // intact: it's keyed in absolute frames and stays valid for a same-composition reuse;
  // lastFrameBuffer must be re-seeded by this render's first fresh capture.
  session.lastFrameBuffer = undefined;
  session.lastFrameAbsoluteIndex = undefined;
  session.staticDedupCount = 0;
}

export async function getCompositionDuration(session: CaptureSession): Promise<number> {
  if (!session.isInitialized) throw new Error("[FrameCapture] Session not initialized");

  return session.page.evaluate(() => {
    return window.__hf?.duration ?? 0;
  });
}

/**
 * Ungated-release safety net, part 1: capture K screenshot ground-truth frames
 * BEFORE the drawElement canvas is injected (the only window where a page
 * screenshot shows the live DOM). The producer's drain compares each DE frame
 * at these indices against its screenshot; a breach (or a blank frame that
 * survives one retry) throws DrawElementVerificationError, and the orchestrator
 * re-renders the whole job via the screenshot path.
 *
 * Env: HF_DE_VERIFY = sample count (default 4, clamp 0..8; 0 disables).
 * Deterministic index selection: fixed fractions of the timeline, nudged off
 * clip-cut boundaries (screenshot-vs-DE is legitimately ±1-frame desynced
 * there — Lim 6). Skipped for tiny comps (<10 frames) and under
 * HF_FORCE_DRAWELEMENT (debug escape hatch).
 *
 * False-positive bias is intentional: a nondeterministic comp may mismatch its
 * init-time screenshot → the render falls back to the screenshot path (slower,
 * never wrong). Cost when passing: ~K×(seek+screenshot) ≈ 150–300ms at init.
 */
/**
 * Timeline fractions the self-verify samples. First k-1 evenly spaced, last
 * pinned at 95%: late-onset damage (an end-of-comp reveal exposing pixels DE
 * paints wrong) was invisible to the old (i+1)/(k+1) grid, whose final sample
 * sat at 80% — measured miss: a body-gradient drop starting at ~79% of the
 * timeline passed verification while the drained output bottomed at 30.9 dB.
 */
export function computeDeVerifySampleFractions(k: number): number[] {
  if (k <= 0) return [];
  if (k === 1) return [0.95];
  return [...Array.from({ length: k - 1 }, (_, i) => (i + 1) / k), 0.95];
}

async function captureDeVerificationFrames(
  session: CaptureSession,
  page: Page,
  logInitPhase: (phase: string) => void,
): Promise<void> {
  // Explicit HF_DE_VERIFY wins; otherwise the session's own sample count
  // (raised by the parallel coordinator for multi-worker DE), then default 4.
  const kRaw = Number(process.env.HF_DE_VERIFY ?? session.options.deVerifySamples ?? "4");
  const k = Number.isFinite(kRaw) ? Math.max(0, Math.min(8, Math.floor(kRaw))) : 4;
  if (k === 0 || process.env.HF_FORCE_DRAWELEMENT === "1") return;
  if (session.options.format === "png") return; // worker-encode drain (the consumer) is jpeg-only
  const fps = fpsToNumber(session.options.fps);
  // Prefer the producer-resolved duration (the range that will actually be
  // drained). The page's raw __hf.duration can exceed it — timelines outrun
  // their data-duration, and infinite-repeat GSAP reports a huge sentinel —
  // and indices derived from it would never be drained, silently disarming
  // verification for exactly the comps that need it.
  const duration =
    session.options.compositionDurationSeconds ??
    (await page.evaluate(
      () => (window as unknown as { __hf?: { duration?: number } }).__hf?.duration ?? 0,
    ));
  const totalFrames = Math.floor(duration * fps);
  if (totalFrames < 10) return;
  if (duration > 3600) {
    // No producer duration and the page reports an implausible one.
    logInitPhase(`drawElement self-verify skipped: implausible duration ${duration}s`);
    return;
  }
  // Ground truth must show what the real capture paths would show: <video>
  // pixels come from the onBeforeCapture injector. When this session has no
  // injector (e.g. a probe session initialized before the render wires one
  // up) a video comp's truth would screenshot black boxes and every sample
  // would false-positive into the screenshot fallback — skip instead.
  if (!session.onBeforeCapture) {
    const hasVideos = await page.evaluate(() => document.querySelector("video") !== null);
    if (hasVideos) {
      logInitPhase("drawElement self-verify skipped: video comp without frame injector");
      return;
    }
  }
  const boundary = await computeClipBoundaryFrames(page, fps);
  // Ascending order, and seek frame 0 first: GSAP .from()/overlapping tweens
  // lazily record their start values on FIRST seek — scrubbing mid-timeline
  // before the render's frame-0 seek corrupts those caches for the whole
  // render (the detectCssEffectRisk lesson), and because DE frames and truth
  // would share the corruption, PSNR would pass on the damaged output.
  // Seeking 0 → ascending reproduces the render's own seek order.
  const fractions = computeDeVerifySampleFractions(k);
  const seekTo = async (t: number): Promise<void> => {
    await page.evaluate((tt: number) => {
      const hf = (
        window as unknown as {
          __hf?: { seek?: (x: number, options?: { suppressEvents?: boolean }) => void };
        }
      ).__hf;
      if (hf && typeof hf.seek === "function") hf.seek(tt, { suppressEvents: true });
    }, t);
  };
  await seekTo(quantizeTimeToFrame(0, fps));
  // Force one frame so lazy tween initialization paints at t=0 state.
  await pageScreenshotCapture(page, session.options);
  const frames = new Map<number, Buffer>();
  for (const f of fractions) {
    let idx = Math.min(totalFrames - 1, Math.max(1, Math.round(totalFrames * f)));
    // Nudge off clip-cut boundaries (±1-frame desync is legitimate there);
    // if the nudge saturates on a boundary index, skip the sample entirely.
    let guard = 0;
    while (boundary.has(idx) && guard++ < 6) idx = Math.min(totalFrames - 1, idx + 2);
    if (boundary.has(idx)) continue;
    if (frames.has(idx)) continue;
    const t = quantizeTimeToFrame(idx / fps, fps);
    await seekTo(t);
    // Video frame injection (same hook the real capture paths run) — without
    // it, <video> elements screenshot black and every video comp would
    // false-positive into the screenshot fallback.
    if (session.onBeforeCapture) await session.onBeforeCapture(page, t);
    // Double-capture: the first screenshot forces a frame, which is what runs
    // rAF-driven callbacks (count-up text counters land a tick after seek()
    // returns — a single immediate screenshot captures stale text and
    // false-positives the verify: 3bea8c73 28.7dB vs a truth missing its stat
    // values while the DE frame was correct). NOTE: waiting on rAF via
    // evaluate instead deadlocks — headless only fires rAF when a frame is
    // produced, and nothing produces one until a screenshot asks.
    await pageScreenshotCapture(page, session.options);
    frames.set(idx, await pageScreenshotCapture(page, session.options));
  }
  // Leave the page at frame 0 so the render's first seek starts from the
  // same state as an unverified render.
  await seekTo(quantizeTimeToFrame(0, fps));
  session.deVerifyFrames = frames;
  logInitPhase(
    `drawElement self-verify armed: ${frames.size} ground-truth frame(s) @ [${[...frames.keys()].join(", ")}] of ${totalFrames}`,
  );
}

function medianOf(samples: number[]): number {
  if (samples.length === 0) return 0;
  const sorted = [...samples].sort((a, b) => a - b);
  return Math.round(sorted[Math.floor(sorted.length / 2)] ?? 0);
}

/**
 * Percentile of a positive-real sample set (nearest-rank; matches how the
 * existing {@link medianOf} p50 helper picks the middle index). `p` is a
 * fraction in [0, 1]; the sample at `floor(p * n)` (clamped to `[0, n-1]`)
 * is returned. Sample set is not mutated. Returns 0 for empty input, mirroring
 * the p50 helper.
 *
 * Used for the `capture_fallback_profile` observability checkpoint added in
 * the fast-capture fallback profiling PR: we already collect `capturePerf.frameMs`
 * per session, so computing p95/p99 is one sort + two lookups — cheap enough
 * to always compute alongside the existing p50, no separate opt-in path
 * needed for the math. The env gate lives at the emission site.
 */
export function percentileOf(samples: number[], p: number): number {
  if (samples.length === 0) return 0;
  const sorted = [...samples].sort((a, b) => a - b);
  const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor(p * sorted.length)));
  return Math.round(sorted[idx] ?? 0);
}

/** Threshold for surfacing paint-record/canvas failures in partial-session diagnostics. */
const DE_FALLBACK_RATIO_WARN_THRESHOLD = 0.5;

export function getCapturePerfSummary(session: CaptureSession): CapturePerfSummary {
  const frames = Math.max(1, session.capturePerf.frames);
  const ncprFallbacks = session.deNcprFallbacks ?? 0;
  // These now reject capture and require a fresh screenshot page. Keep the
  // counter for failed-session telemetry; it no longer represents usable
  // per-frame screenshots from the injected canvas page.
  if (frames > 0 && ncprFallbacks / frames > DE_FALLBACK_RATIO_WARN_THRESHOLD) {
    const pct = Math.round((ncprFallbacks / frames) * 100);
    console.warn(
      `[engine] fast capture: ${ncprFallbacks}/${frames} frame(s) (${pct}%) rejected ` +
        `due to missing canvas/paint records; fresh screenshot capture required.`,
    );
  }
  return {
    frames: session.capturePerf.frames,
    avgTotalMs: Math.round(session.capturePerf.totalMs / frames),
    avgSeekMs: Math.round(session.capturePerf.seekMs / frames),
    avgBeforeCaptureMs: Math.round(session.capturePerf.beforeCaptureMs / frames),
    avgScreenshotMs: Math.round(session.capturePerf.screenshotMs / frames),
    p50TotalMs: medianOf(session.capturePerf.frameMs),
    p95TotalMs: percentileOf(session.capturePerf.frameMs, 0.95),
    p99TotalMs: percentileOf(session.capturePerf.frameMs, 0.99),
    subTimelineWaitOutcome: session.subTimelineWaitOutcome,
    initDurationMs: session.initTelemetry?.initDurationMs,
    initTweenCount: session.initTelemetry?.tweenCount,
    initElementCount: session.initTelemetry?.elementCount,
    warnings: cloneCaptureWarnings(session.warnings),
    staticDedupReused: session.staticDedupCount ?? 0,
    staticDedupEnabled: session.staticDedupEnabled ?? false,
    // armed ⟺ a non-empty static set survived verification.
    staticDedupArmed: (session.staticFrames?.size ?? 0) > 0,
    staticDedupPredicted: session.staticDedupPredictedCount ?? 0,
    staticDedupVerified: session.staticFrames?.size ?? 0,
    staticDedupVerificationOutcome: session.staticDedupVerification?.outcome,
    staticDedupVerificationPlannedRuns: session.staticDedupVerification?.stats.plannedRuns,
    staticDedupVerificationCompletedRuns: session.staticDedupVerification?.stats.completedRuns,
    staticDedupVerificationScreenshots: session.staticDedupVerification?.stats.screenshots,
    staticDedupVerificationSeeks: session.staticDedupVerification?.stats.seeks,
    staticDedupVerificationComparisons: session.staticDedupVerification?.stats.byteComparisons,
    staticDedupVerificationElapsedMs: session.staticDedupVerification?.stats.elapsedMs,
    staticDedupSkipReason: session.staticDedupSkipReason,
    beginFrameNoDamage: session.beginFrameNoDamageCount,
    beginFrameHasDamage: session.beginFrameHasDamageCount,
    captureMode: session.captureMode,
    gpuRenderer: session.gpuRenderer,
    chromeBrowserRssPeakMb: session.chromeMemory?.stats().browserRssPeakMb,
    chromeRendererRssPeakMb: session.chromeMemory?.stats().rendererRssPeakMb,
    chromeRssLastMb: session.chromeMemory?.stats().rssLastMb,
    chromeGpuProcessSeenLastSample: session.chromeMemory?.stats().gpuProcessSeenLastSample,
    chromeMemorySamples: session.chromeMemory?.stats().samples,
    deGateReason: session.deGateReason,
    deFallbackTrigger: session.deFallbackTrigger,
    deWorkerEncode: session.workerEncodeEnabled ?? false,
    deVerifyArmed: session.deVerifyFrames?.size ?? 0,
    deVerifyInitMs: session.deVerifyInitMs ?? 0,
    deBoundaryFrames: session.clipBoundaryFrames?.size ?? 0,
    deNcprFallbacks: ncprFallbacks,
    deFrameTimeouts: session.deFrameTimeouts ?? 0,
  };
}