Skip to content

Write HTML. Render video. Built for agents.

139 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { join, win32 } from "node:path";
import { tmpdir } from "node:os";
import type { CaptureOptions, EngineConfig, ExtractedFrames } from "@hyperframes/engine";
import {
  DEFAULT_CONFIG,
  DrawElementCaptureError,
  executeParallelCapture,
  mergeWorkerFrames,
} from "@hyperframes/engine";
import type { CompiledComposition } from "./htmlCompiler.js";

// Replace only the two engine functions the adaptive-retry loop uses to touch
// disk; everything else (distributeFrames, types, etc.) stays real so the loop
// runs for real against a temp framesDir.
vi.mock("@hyperframes/engine", async (importOriginal) => {
  const actual = await importOriginal<typeof import("@hyperframes/engine")>();
  return { ...actual, executeParallelCapture: vi.fn(), mergeWorkerFrames: vi.fn() };
});

import {
  buildMissingFrameRetryBatches,
  captureAttemptMadeProgress,
  closeOrphanedProbeForRetry,
  describeMemoryExhaustion,
  executeDiskCaptureWithAdaptiveRetry,
  explainStreamingEncodeGate,
  collectVideoMetadataHints,
  collectVideoReadinessSkipIds,
  findMissingFrameRanges,
  getNextRetryWorkerCount,
  isRecoverableParallelCaptureError,
  MAX_TRANSIENT_CAPTURE_RETRIES,
  resolveCaptureForceScreenshotForPageSideCompositing,
  resolveRenderWorkDirPrefix,
  shouldDiscardProbeSessionForPageSideCompositing,
  resolveInversionRetryPlan,
  resolveParallelRouterRetryPlan,
  resetCaptureAttemptProgress,
  shouldRetryViaPinnedFallback,
  isDeRendererStallError,
  isSequentialCaptureStallError,
  isParallelCaptureStallError,
  isParallelStreamForced,
  fallbackCaptureModeLabel,
  isRetryableEncoderDeath,
  scanElementTags,
  envInt,
  isDeParallelRouterEnabled,
  mergeWorkerInitObservability,
  resolveCompositionElementCount,
  detectAdaptersStatic,
  resolveAdaptersUsed,
  resolveDeShortBand,
  shouldClampDefaultDrawElement,
  shouldPreferParallelDrawElement,
  shouldPreferSingleWorkerDrawElement,
  isCaptureParallelStreamRouterEnabled,
  shouldSegmentCapture,
  SEGMENTED_MIN_SECONDS_AFTER_SOAK,
  resolveParallelCaptureMode,
  shouldStreamParallelCapture,
  shouldUseStreamingEncode,
  resolveObservedCaptureMode,
  createCaptureObservabilityUpdater,
  applyRenderWarningPolicy,
  createRenderJob,
  RenderQualityError,
} from "./renderOrchestrator.js";
import { probeRequiresBrowser } from "./render/stages/probeStage.js";
import { EncoderInterruptedError } from "./render/encoderInterruption.js";
import { ensureFrameWritten } from "./render/stages/captureHdrFrameShared.js";
import { resolveCompositeTransfer, shouldUseLayeredComposite } from "./hdrCompositor.js";
import {
  createCaptureCalibrationConfig,
  estimateCaptureCostMultiplier,
  estimateMeasuredCaptureCostMultiplier,
  resolveRenderWorkerCount,
  selectCaptureCalibrationFrames,
  shouldFallbackToScreenshotAfterCalibrationError,
} from "./render/captureCost.js";
import {
  applyRenderModeHints,
  createCompiledFrameSrcResolver,
  materializeExtractedFramesForCompiledDir,
  projectBrowserEndToCompositionTimeline,
  resolveDeviceScaleFactor,
  writeCompiledArtifacts,
} from "./render/shared.js";
import { formatCaptureFrameName, toExternalAssetKey } from "../utils/paths.js";

describe("resolveRenderWorkDirPrefix", () => {
  it("uses a short system temp prefix on Windows instead of the output path", () => {
    const outputPath = win32.join("C:\\deep", "nested".repeat(30), "renders", "final.mp4");

    expect(resolveRenderWorkDirPrefix(outputPath, "long-render-job-id", "win32", "C:/Temp")).toBe(
      join("C:/Temp", "hf-render-"),
    );
  });

  it("keeps macOS frames out of the project folder, which a sync client may be watching", () => {
    const outputPath = join("/Users/me/Nextcloud/project", "renders", "final.mp4");

    expect(resolveRenderWorkDirPrefix(outputPath, "job-id", "darwin", "/var/folders/x/T")).toBe(
      join("/var/folders/x/T", "hf-render-"),
    );
  });

  it("keeps Linux frames beside the output, where a container's small /tmp cannot fill", () => {
    expect(resolveRenderWorkDirPrefix("/work/renders/final.mp4", "job-id", "linux", "/tmp")).toBe(
      join("/work/renders", "work-job-id-"),
    );
  });
});

describe("captureAttemptMadeProgress", () => {
  it("resets completed frames before a fallback attempt starts", () => {
    const job = { framesRendered: 900 };

    resetCaptureAttemptProgress(job);

    expect(job.framesRendered).toBe(0);
  });

  it("retries when the attempt captured at least one frame toward its target", () => {
    // targeted 100 frames, 40 still missing -> 60 captured -> worth retrying the rest
    expect(captureAttemptMadeProgress(100, 40)).toBe(true);
    expect(captureAttemptMadeProgress(100, 99)).toBe(true);
  });

  it("bails when the attempt captured nothing (structurally broken composition)", () => {
    // targeted 100 frames, 100 still missing -> zero progress -> don't burn another timeout cycle
    expect(captureAttemptMadeProgress(100, 100)).toBe(false);
    // defensive: never-greater-than guard, treat >= target as no progress
    expect(captureAttemptMadeProgress(100, 120)).toBe(false);
  });
});

describe("executeDiskCaptureWithAdaptiveRetry — zero-progress bail (integration)", () => {
  const makeLog = () => ({ error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() });

  afterEach(() => {
    vi.mocked(executeParallelCapture).mockReset();
    vi.mocked(mergeWorkerFrames).mockReset();
  });

  it("propagates an untrusted drawElement frame even if all disk frames exist", async () => {
    const workDir = mkdtempSync(join(tmpdir(), "hf-de-untrusted-"));
    const framesDir = join(workDir, "frames");
    mkdirSync(framesDir);
    const error = new Error("capture stage failed", {
      cause: new DrawElementCaptureError(0, "No cached paint record"),
    });
    vi.mocked(executeParallelCapture).mockRejectedValueOnce(error);
    vi.mocked(mergeWorkerFrames).mockImplementationOnce(async () => {
      writeFileSync(join(framesDir, "frame_000000.jpg"), Buffer.alloc(100));
    });
    try {
      await expect(
        executeDiskCaptureWithAdaptiveRetry({
          serverUrl: "http://localhost:0",
          workDir,
          framesDir,
          totalFrames: 1,
          initialWorkerCount: 1,
          allowRetry: true,
          frameExt: "jpg",
          captureOptions: { width: 64, height: 64, fps: { num: 30, den: 1 } },
          createBeforeCaptureHook: () => null,
          cfg: DEFAULT_CONFIG,
          log: makeLog(),
          dedupPerfs: [],
        }),
      ).rejects.toBe(error);
      expect(executeParallelCapture).toHaveBeenCalledTimes(1);
    } finally {
      rmSync(workDir, { recursive: true, force: true });
    }
  });

  it("runs exactly one attempt (no worker-halving retries) when an attempt captures zero frames", async () => {
    // Capture writes nothing -> framesDir stays empty -> every frame still missing.
    vi.mocked(executeParallelCapture).mockResolvedValue([]);
    vi.mocked(mergeWorkerFrames).mockResolvedValue(undefined);

    const workDir = mkdtempSync(join(tmpdir(), "hf-retry-work-"));
    const framesDir = mkdtempSync(join(tmpdir(), "hf-retry-frames-"));
    const log = makeLog();
    try {
      await expect(
        executeDiskCaptureWithAdaptiveRetry({
          serverUrl: "http://localhost:0",
          workDir,
          framesDir,
          totalFrames: 4,
          initialWorkerCount: 4,
          allowRetry: true,
          frameExt: "jpg",
          captureOptions: {} as CaptureOptions,
          createBeforeCaptureHook: () => null,
          cfg: {} as EngineConfig,
          log,
          dedupPerfs: [],
        }),
      ).rejects.toThrow(/4 frame\(s\) are missing/);

      // The gate under test: without it the loop would walk 4 -> 2 -> 1 workers
      // (3 capture calls) before giving up. One call proves it bailed immediately.
      expect(vi.mocked(executeParallelCapture)).toHaveBeenCalledTimes(1);
      expect(log.warn).toHaveBeenCalledWith(
        expect.stringContaining("no forward progress"),
        expect.objectContaining({ attempt: 0, frameCount: 4, remainingCount: 4 }),
      );
    } finally {
      rmSync(workDir, { recursive: true, force: true });
      rmSync(framesDir, { recursive: true, force: true });
    }
  });
});

describe("executeDiskCaptureWithAdaptiveRetry — transient Target-closed single retry (integration)", () => {
  const makeLog = () => ({ error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() });

  const writeAllFrames = (framesDir: string, totalFrames: number): void => {
    for (let i = 0; i < totalFrames; i++) {
      writeFileSync(join(framesDir, formatCaptureFrameName(i, "jpg")), "captured-frame");
    }
  };

  afterEach(() => {
    vi.mocked(executeParallelCapture).mockReset();
    vi.mocked(mergeWorkerFrames).mockReset();
  });

  // Both shapes classify as transient_browser: the tab dying mid-capture, and a
  // CDP refusal of the capture call itself (no timeout wording, so it used to
  // fall through to the fatal "authoring" bucket and was never retried).
  it.each([
    ["a transient Target closed", "Protocol error (Page.captureScreenshot): Target closed"],
    [
      "a non-timeout captureScreenshot protocol refusal",
      "[Parallel] Capture failed: Worker 0: Protocol error (Page.captureScreenshot): Unable to capture screenshot",
    ],
  ])("retries ONCE at the same worker count on %s with zero progress", async (_label, message) => {
    const workDir = mkdtempSync(join(tmpdir(), "hf-transient-work-"));
    const framesDir = mkdtempSync(join(tmpdir(), "hf-transient-frames-"));
    const log = makeLog();
    let call = 0;
    // First attempt fails before any frame is captured (frame 0) — zero forward
    // progress, which the worker-halving retry deliberately bails on. The
    // transient retry recovers it without changing the worker count.
    vi.mocked(executeParallelCapture).mockImplementation(async () => {
      call++;
      if (call === 1) {
        throw new Error(message);
      }
      writeAllFrames(framesDir, 4);
      return [];
    });
    vi.mocked(mergeWorkerFrames).mockResolvedValue(undefined);

    try {
      const attempts = await executeDiskCaptureWithAdaptiveRetry({
        serverUrl: "http://localhost:0",
        workDir,
        framesDir,
        totalFrames: 4,
        initialWorkerCount: 1,
        allowRetry: true,
        frameExt: "jpg",
        captureOptions: {} as CaptureOptions,
        createBeforeCaptureHook: () => null,
        cfg: {} as EngineConfig,
        log,
        dedupPerfs: [],
      });

      expect(vi.mocked(executeParallelCapture)).toHaveBeenCalledTimes(2);
      // Both attempts ran at the same worker count (transient retry doesn't halve).
      expect(attempts.map((a) => a.workers)).toEqual([1, 1]);
      // The retry attempt is tagged `transient-retry` (vs the worker-halving
      // `retry`) so it's countable for telemetry (dashboard 1783183).
      expect(attempts.map((a) => a.reason)).toEqual(["initial", "transient-retry"]);
      expect(log.warn).toHaveBeenCalledWith(
        expect.stringContaining("Transient browser failure"),
        expect.objectContaining({ transientRetriesUsed: 1 }),
      );
    } finally {
      rmSync(workDir, { recursive: true, force: true });
      rmSync(framesDir, { recursive: true, force: true });
    }
  });

  it("retries Network.enable startup timeout once with fewer workers and zero progress", async () => {
    const workDir = mkdtempSync(join(tmpdir(), "hf-transient-work-"));
    const framesDir = mkdtempSync(join(tmpdir(), "hf-transient-frames-"));
    const log = makeLog();
    let call = 0;
    vi.mocked(executeParallelCapture).mockImplementation(async () => {
      call++;
      if (call === 1) {
        throw new Error("[Parallel] Capture failed: Worker 0: Network.enable timed out");
      }
      writeAllFrames(framesDir, 4);
      return [];
    });
    vi.mocked(mergeWorkerFrames).mockResolvedValue(undefined);

    try {
      const attempts = await executeDiskCaptureWithAdaptiveRetry({
        serverUrl: "http://localhost:0",
        workDir,
        framesDir,
        totalFrames: 4,
        initialWorkerCount: 4,
        allowRetry: true,
        frameExt: "jpg",
        captureOptions: { width: 64, height: 64, fps: { num: 30, den: 1 } },
        createBeforeCaptureHook: () => null,
        cfg: DEFAULT_CONFIG,
        log,
        dedupPerfs: [],
      });

      expect(vi.mocked(executeParallelCapture)).toHaveBeenCalledTimes(2);
      expect(attempts.map((a) => a.workers)).toEqual([4, 2]);
      expect(attempts.map((a) => a.reason)).toEqual(["initial", "retry"]);
      expect(log.warn).toHaveBeenCalledWith(
        expect.stringContaining("Browser initialization timed out"),
        expect.objectContaining({ fromWorkers: 4, toWorkers: 2 }),
      );
    } finally {
      rmSync(workDir, { recursive: true, force: true });
      rmSync(framesDir, { recursive: true, force: true });
    }
  });

  it.each(["Target closed", "Network.enable timed out"])(
    "does NOT retry %s after cancellation",
    async (message) => {
      const workDir = mkdtempSync(join(tmpdir(), "hf-transient-abort-work-"));
      const framesDir = mkdtempSync(join(tmpdir(), "hf-transient-abort-frames-"));
      const log = makeLog();
      const controller = new AbortController();
      // Cancellation tears the browser down, surfacing as a transient-looking
      // "Target closed" — but an aborted render must fail immediately, not retry.
      vi.mocked(executeParallelCapture).mockImplementation(async () => {
        controller.abort();
        throw new Error(message);
      });
      vi.mocked(mergeWorkerFrames).mockResolvedValue(undefined);

      try {
        await expect(
          executeDiskCaptureWithAdaptiveRetry({
            serverUrl: "http://localhost:0",
            workDir,
            framesDir,
            totalFrames: 4,
            initialWorkerCount: 2,
            allowRetry: true,
            frameExt: "jpg",
            captureOptions: {} as CaptureOptions,
            createBeforeCaptureHook: () => null,
            abortSignal: controller.signal,
            cfg: {} as EngineConfig,
            log,
            dedupPerfs: [],
          }),
        ).rejects.toThrow(message);

        // Exactly one attempt — no transient retry burned on a cancelled render.
        expect(vi.mocked(executeParallelCapture)).toHaveBeenCalledTimes(1);
        expect(log.warn).not.toHaveBeenCalledWith(
          expect.stringContaining("Transient browser failure"),
          expect.anything(),
        );
      } finally {
        rmSync(workDir, { recursive: true, force: true });
        rmSync(framesDir, { recursive: true, force: true });
      }
    },
  );

  it.each(["Session closed", "Network.enable timed out"])(
    "bounds repeated %s failures",
    async (message) => {
      const workDir = mkdtempSync(join(tmpdir(), "hf-transient2-work-"));
      const framesDir = mkdtempSync(join(tmpdir(), "hf-transient2-frames-"));
      const log = makeLog();
      vi.mocked(executeParallelCapture).mockRejectedValue(new Error(message));
      vi.mocked(mergeWorkerFrames).mockResolvedValue(undefined);

      try {
        await expect(
          executeDiskCaptureWithAdaptiveRetry({
            serverUrl: "http://localhost:0",
            workDir,
            framesDir,
            totalFrames: 4,
            initialWorkerCount: 1,
            allowRetry: true,
            frameExt: "jpg",
            captureOptions: {} as CaptureOptions,
            createBeforeCaptureHook: () => null,
            cfg: {} as EngineConfig,
            log,
            dedupPerfs: [],
          }),
        ).rejects.toThrow(message);

        // 1 initial attempt + exactly MAX_TRANSIENT_CAPTURE_RETRIES retries.
        expect(vi.mocked(executeParallelCapture)).toHaveBeenCalledTimes(
          1 + MAX_TRANSIENT_CAPTURE_RETRIES,
        );
      } finally {
        rmSync(workDir, { recursive: true, force: true });
        rmSync(framesDir, { recursive: true, force: true });
      }
    },
  );
});

describe("describeMemoryExhaustion", () => {
  it("returns actionable guidance for a memory-exhaustion error", () => {
    const msg = describeMemoryExhaustion(new Error("Set maximum size exceeded"), {
      width: 3840,
      height: 2160,
      totalFrames: 5400,
    });
    expect(msg).not.toBeNull();
    expect(msg).toContain("ran out of memory");
    expect(msg).toContain("3840×2160");
    expect(msg).toContain("5400 frames");
    expect(msg).toContain("Set maximum size exceeded");
    expect(msg).toContain("--low-memory-mode");
  });

  it("omits dimensions when they are unknown", () => {
    const msg = describeMemoryExhaustion(new Error("JavaScript heap out of memory"), {});
    expect(msg).not.toBeNull();
    expect(msg).not.toContain("×");
  });

  it("returns null for a non-memory error (leaves the original message intact)", () => {
    expect(
      describeMemoryExhaustion(new Error("Target closed"), {
        width: 1920,
        height: 1080,
        totalFrames: 100,
      }),
    ).toBeNull();
  });
});

describe("ensureFrameWritten", () => {
  it("returns without throwing when the frame was written", () => {
    expect(() => ensureFrameWritten(true, 0)).not.toThrow();
  });

  it("throws a bare frame-indexed error when no encoder context is supplied", () => {
    expect(() => ensureFrameWritten(false, 7)).toThrow(
      "Streaming encoder exited before frame 7 was written",
    );
  });

  it("includes the ffmpeg exit reason when the encoder reports one", () => {
    const encoder = { getExitError: () => "FFmpeg exited with code 1: Unknown encoder 'libx264'" };
    expect(() => ensureFrameWritten(false, 0, encoder)).toThrow(
      /Streaming encoder exited before frame 0 was written: FFmpeg exited with code 1: Unknown encoder 'libx264'/,
    );
  });

  it("falls back to the bare message when the encoder has no exit reason yet", () => {
    const encoder = { getExitError: () => undefined };
    expect(() => ensureFrameWritten(false, 3, encoder)).toThrow(
      "Streaming encoder exited before frame 3 was written",
    );
  });
});

describe("shouldUseStreamingEncode", () => {
  const streamingEnabledConfig = {
    enableStreamingEncode: true,
    streamingEncodeMaxDurationSeconds: 240,
    lowMemoryMode: false,
  };

  it("enables streaming for default single-worker video renders", () => {
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "mp4", 1, 240)).toBe(true);
  });

  it("lets config disable streaming encode", () => {
    expect(
      shouldUseStreamingEncode(
        { enableStreamingEncode: false, streamingEncodeMaxDurationSeconds: 240 },
        "mp4",
        1,
        240,
      ),
    ).toBe(false);
  });

  it("keeps png-sequence and parallel capture on the non-streaming path", () => {
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "png-sequence", 1, 240)).toBe(false);
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "mp4", 2, 240)).toBe(false);
  });

  it("forceParallelStream overrides the parallel-capture clamp for verified multi-worker streaming", () => {
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "mp4", 3, 240, true)).toBe(true);
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "mp4", 3, 240, false)).toBe(false);
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "png-sequence", 3, 240, true)).toBe(
      false,
    );
  });

  it("ignores the duration cap unless streamingEncodeDurationCapEnabled is true", () => {
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "mp4", 1, 240.001)).toBe(true);
    expect(shouldUseStreamingEncode(streamingEnabledConfig, "mp4", 1, 3600)).toBe(true);
    expect(
      shouldUseStreamingEncode(
        { ...streamingEnabledConfig, streamingEncodeDurationCapEnabled: true },
        "mp4",
        1,
        240.001,
      ),
    ).toBe(false);
    expect(
      shouldUseStreamingEncode(
        {
          enableStreamingEncode: true,
          streamingEncodeMaxDurationSeconds: 120,
          streamingEncodeDurationCapEnabled: true,
        },
        "mp4",
        1,
        120.001,
      ),
    ).toBe(false);
    expect(
      shouldUseStreamingEncode(
        { ...streamingEnabledConfig, streamingEncodeDurationCapEnabled: true },
        "mp4",
        1,
        240,
      ),
    ).toBe(true);
  });

  it("keeps long single-worker renders streaming in low-memory mode", () => {
    expect(
      shouldUseStreamingEncode({ ...streamingEnabledConfig, lowMemoryMode: true }, "mp4", 1, 411),
    ).toBe(true);
  });
});

describe("explainStreamingEncodeGate", () => {
  const cfg = {
    enableStreamingEncode: true,
    streamingEncodeMaxDurationSeconds: 240,
    lowMemoryMode: false,
  };

  it("names the reason for every decision", () => {
    expect(
      explainStreamingEncodeGate({ ...cfg, enableStreamingEncode: false }, "mp4", 1, 10),
    ).toEqual({ enabled: false, reason: "disabled_by_config" });
    expect(explainStreamingEncodeGate(cfg, "png-sequence", 1, 10)).toEqual({
      enabled: false,
      reason: "format_excluded",
    });
    expect(explainStreamingEncodeGate(cfg, "gif", 1, 10)).toEqual({
      enabled: false,
      reason: "format_excluded",
    });
    expect(explainStreamingEncodeGate(cfg, "mp4", 1, 0)).toEqual({
      enabled: false,
      reason: "invalid_duration",
    });
    expect(explainStreamingEncodeGate(cfg, "mp4", 1, Number.NaN)).toEqual({
      enabled: false,
      reason: "invalid_duration",
    });
    expect(
      explainStreamingEncodeGate(
        { ...cfg, streamingEncodeDurationCapEnabled: true },
        "mp4",
        1,
        300,
      ),
    ).toEqual({ enabled: false, reason: "duration_cap" });
    expect(
      explainStreamingEncodeGate(
        { ...cfg, streamingEncodeDurationCapEnabled: true, lowMemoryMode: true },
        "mp4",
        1,
        300,
      ),
    ).toEqual({ enabled: true, reason: "low_memory_mode" });
    expect(explainStreamingEncodeGate(cfg, "mp4", 3, 300, true)).toEqual({
      enabled: true,
      reason: "parallel_forced",
    });
    expect(explainStreamingEncodeGate(cfg, "mp4", 1, 300)).toEqual({
      enabled: true,
      reason: "single_worker",
    });
    expect(explainStreamingEncodeGate(cfg, "mp4", 2, 300)).toEqual({
      enabled: false,
      reason: "multi_worker",
    });
  });

  it("low-memory mode only bypasses the cap; it never streams an unforced multi-worker render", () => {
    // `--low-memory-mode --workers 4` is a real combination (only the
    // single-worker pin is bypassed by an explicit worker count). The
    // contiguous-chunk parallel writer stalls, so the gate must still say no.
    expect(
      explainStreamingEncodeGate(
        { ...cfg, streamingEncodeDurationCapEnabled: true, lowMemoryMode: true },
        "mp4",
        4,
        300,
      ),
    ).toEqual({ enabled: false, reason: "multi_worker" });
  });

  it("agrees with shouldUseStreamingEncode on every input", () => {
    const cases: Array<[typeof cfg, "mp4" | "webm" | "gif", number, number, boolean]> = [
      [cfg, "mp4", 1, 10, false],
      [cfg, "mp4", 2, 10, false],
      [cfg, "mp4", 2, 10, true],
      [cfg, "gif", 1, 10, false],
      [{ ...cfg, enableStreamingEncode: false }, "mp4", 1, 10, false],
    ];
    for (const [c, format, workers, duration, force] of cases) {
      expect(shouldUseStreamingEncode(c, format, workers, duration, force)).toBe(
        explainStreamingEncodeGate(c, format, workers, duration, force).enabled,
      );
    }
  });
});

describe("createCompiledFrameSrcResolver", () => {
  it("maps extracted frame paths under compiledDir to encoded server URLs", () => {
    const resolver = createCompiledFrameSrcResolver("/tmp/hf job/compiled");

    expect(
      resolver("/tmp/hf job/compiled/__hyperframes_video_frames/video 1/frame_00001.jpg"),
    ).toBe("/__hyperframes_video_frames/video%201/frame_00001.jpg");
  });

  it("returns null for paths outside compiledDir", () => {
    const resolver = createCompiledFrameSrcResolver("/tmp/hf-job/compiled");

    expect(resolver("/tmp/hf-job/video-frames/frame_00001.jpg")).toBeNull();
  });

  it("resolves symlinked cache frames when materialized under compiledDir", () => {
    const resolver = createCompiledFrameSrcResolver("/tmp/hf-job/compiled");

    expect(resolver("/tmp/hf-job/compiled/__hyperframes_video_frames/vid1/frame_00001.jpg")).toBe(
      "/__hyperframes_video_frames/vid1/frame_00001.jpg",
    );

    expect(resolver("/tmp/cache/abc123/frame_00001.jpg")).toBeNull();
  });

  it("encodes reserved characters in frame path segments", () => {
    const resolver = createCompiledFrameSrcResolver("/tmp/hf-job/compiled");

    expect(
      resolver("/tmp/hf-job/compiled/__hyperframes_video_frames/video#1/frame_00001.jpg"),
    ).toBe("/__hyperframes_video_frames/video%231/frame_00001.jpg");

    expect(
      resolver("/tmp/hf-job/compiled/__hyperframes_video_frames/video?q=1/frame_00001.jpg"),
    ).toBe("/__hyperframes_video_frames/video%3Fq%3D1/frame_00001.jpg");
  });
});

describe("materializeExtractedFramesForCompiledDir", () => {
  function createExtractedFrames(
    outputDir: string,
    framePath: string,
  ): Pick<ExtractedFrames, "videoId" | "outputDir" | "framePaths"> {
    return {
      videoId: "video-1",
      outputDir,
      framePaths: new Map([[0, framePath]]),
    };
  }

  it("leaves Windows frame paths already under compiledDir unchanged", () => {
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);

    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      fileSystem: {
        existsSync: () => {
          throw new Error("inside compiledDir should not touch the filesystem");
        },
        mkdirSync: () => {
          throw new Error("inside compiledDir should not mkdir");
        },
        symlinkSync: () => {
          throw new Error("inside compiledDir should not symlink");
        },
        cpSync: () => {
          throw new Error("inside compiledDir should not copy");
        },
      },
    });

    expect(extracted.outputDir).toBe(outputDir);
    expect(extracted.framePaths.get(0)).toBe(framePath);
  });

  // fallow-ignore-next-line code-duplication
  it("remaps Windows cache frames under compiledDir using only the frame basename", () => {
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);
    const symlinks: Array<{ target: string; path: string }> = [];

    // fallow-ignore-next-line code-duplication
    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      fileSystem: {
        existsSync: () => false,
        mkdirSync: () => undefined,
        symlinkSync: (target, path) => {
          symlinks.push({ target, path });
        },
        cpSync: () => {
          throw new Error("symlink path should not invoke cpSync");
        },
      },
    });

    const linkPath = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    expect(extracted.outputDir).toBe(linkPath);
    expect(extracted.framePaths.get(0)).toBe(win32.join(linkPath, "frame_000001.jpg"));
    expect(extracted.framePaths.get(0)).not.toContain(outputDir);
    expect(symlinks).toEqual([{ target: outputDir, path: linkPath }]);
  });

  // fallow-ignore-next-line code-duplication
  it("recursively copies frames into compiledDir when materializeSymlinks is true", () => {
    // Distributed plan() must produce a self-contained planDir — symlinks
    // don't survive S3 / GCS round-trips. With materializeSymlinks=true the
    // helper invokes cpSync(recursive) instead of symlinkSync.
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);
    const copies: Array<{ src: string; dest: string; recursive: boolean }> = [];

    // fallow-ignore-next-line code-duplication
    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      fileSystem: {
        existsSync: () => false,
        mkdirSync: () => undefined,
        symlinkSync: () => {
          throw new Error("copy path should not invoke symlinkSync");
        },
        cpSync: (src, dest, options) => {
          copies.push({ src, dest, recursive: options.recursive });
        },
      },
      materializeSymlinks: true,
    });

    const linkPath = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    expect(extracted.outputDir).toBe(linkPath);
    expect(extracted.framePaths.get(0)).toBe(win32.join(linkPath, "frame_000001.jpg"));
    expect(copies).toEqual([{ src: outputDir, dest: linkPath, recursive: true }]);
  });

  // fallow-ignore-next-line code-duplication
  it("falls back to copying frames when symlinkSync fails with EPERM (Windows, no Developer Mode)", () => {
    // Windows without Developer Mode/Administrator rejects symlink creation with
    // EPERM — high/standard-quality renders failed here while draft worked. The
    // helper must degrade to a recursive copy instead of throwing.
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);
    const copies: Array<{ src: string; dest: string; recursive: boolean }> = [];

    // fallow-ignore-next-line code-duplication
    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      fileSystem: {
        existsSync: () => false,
        mkdirSync: () => undefined,
        symlinkSync: () => {
          const err: NodeJS.ErrnoException = new Error("EPERM: operation not permitted, symlink");
          err.code = "EPERM";
          throw err;
        },
        cpSync: (src, dest, options) => {
          copies.push({ src, dest, recursive: options.recursive });
        },
      },
    });

    const linkPath = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    expect(copies).toEqual([{ src: outputDir, dest: linkPath, recursive: true }]);
    expect(extracted.outputDir).toBe(linkPath);
    expect(extracted.framePaths.get(0)).toBe(win32.join(linkPath, "frame_000001.jpg"));
  });

  it("rethrows a non-permission symlink error instead of masking it with a copy", () => {
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);

    expect(() =>
      materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
        pathModule: win32,
        fileSystem: {
          existsSync: () => false,
          mkdirSync: () => undefined,
          symlinkSync: () => {
            const err: NodeJS.ErrnoException = new Error("ENOSPC: no space left");
            err.code = "ENOSPC";
            throw err;
          },
          cpSync: () => {
            throw new Error("must not fall back to copy for a non-permission error");
          },
        },
      }),
    ).toThrow(/ENOSPC/);
  });

  // fallow-ignore-next-line code-duplication
  it("clears a stale dangling entry and re-stages when symlinkSync fails with EEXIST", () => {
    // After the extraction cache is GC'd, a symlink from a prior render dangles
    // (its target removed). existsSync() follows the dead link so the caller's
    // guard reads it as absent and reaches staging, but the link file itself
    // still exists, so symlinkSync collides with EEXIST. The helper must clear
    // the stale entry (rmSync) and re-stage, not hard-fail the render.
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);
    const linkPath = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    const removed: string[] = [];
    const symlinks: Array<{ target: string; path: string }> = [];
    let symlinkCalls = 0;

    // fallow-ignore-next-line code-duplication
    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      fileSystem: {
        existsSync: () => false,
        mkdirSync: () => undefined,
        symlinkSync: (target, path) => {
          symlinkCalls += 1;
          if (symlinkCalls === 1) {
            const err: NodeJS.ErrnoException = new Error("EEXIST: file already exists, symlink");
            err.code = "EEXIST";
            throw err;
          }
          symlinks.push({ target, path });
        },
        cpSync: () => {
          throw new Error("EEXIST recovery should re-link, not copy");
        },
        rmSync: (path) => {
          removed.push(path);
        },
      },
    });

    expect(removed).toEqual([linkPath]);
    expect(symlinks).toEqual([{ target: outputDir, path: linkPath }]);
    expect(extracted.framePaths.get(0)).toBe(win32.join(linkPath, "frame_000001.jpg"));
  });

  // fallow-ignore-next-line code-duplication
  it("falls back to copying when symlinkSync fails with UNKNOWN (some Windows privilege denials)", () => {
    // Some Windows builds surface a no-symlink-privilege denial as an
    // UNKNOWN-coded error rather than EPERM/EACCES — it must still degrade to a
    // copy, not hard-fail the render.
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);
    const copies: Array<{ src: string; dest: string; recursive: boolean }> = [];

    // fallow-ignore-next-line code-duplication
    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      fileSystem: {
        existsSync: () => false,
        mkdirSync: () => undefined,
        symlinkSync: () => {
          const err: NodeJS.ErrnoException = new Error("UNKNOWN: unknown error, symlink");
          err.code = "UNKNOWN";
          throw err;
        },
        cpSync: (src, dest, options) => {
          copies.push({ src, dest, recursive: options.recursive });
        },
      },
    });

    const linkPath = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    expect(copies).toEqual([{ src: outputDir, dest: linkPath, recursive: true }]);
    expect(extracted.framePaths.get(0)).toBe(win32.join(linkPath, "frame_000001.jpg"));
  });

  // fallow-ignore-next-line code-duplication
  it("clears a stale entry and re-copies when the eager-copy path (materializeSymlinks) hits EEXIST", () => {
    // #2025 routes Windows through the eager-copy branch. Reusing a dir a prior
    // Linux run populated with a (now dangling) symlink makes cpSync collide
    // with EEXIST — the recovery must clear the stale entry and re-copy, exactly
    // like the symlink path does.
    const compiledDir = win32.resolve("C:\\compiled");
    const outputDir = win32.resolve("D:\\cache\\abc123");
    const framePath = win32.join(outputDir, "frame_000001.jpg");
    const extracted = createExtractedFrames(outputDir, framePath);
    const linkPath = win32.join(compiledDir, "__hyperframes_video_frames", "video-1");
    const removed: string[] = [];
    const copies: Array<{ src: string; dest: string }> = [];
    let cpCalls = 0;

    // fallow-ignore-next-line code-duplication
    materializeExtractedFramesForCompiledDir([extracted], compiledDir, {
      pathModule: win32,
      materializeSymlinks: true,
      fileSystem: {
        existsSync: () => false,
        mkdirSync: () => undefined,
        symlinkSync: () => {
          throw new Error("eager-copy path must not symlink");
        },
        cpSync: (src, dest) => {
          cpCalls += 1;
          if (cpCalls === 1) {
            const err: NodeJS.ErrnoException = new Error("EEXIST: file already exists, cp");
            err.code = "EEXIST";
            throw err;
          }
          copies.push({ src, dest });
        },
        rmSync: (path) => {
          removed.push(path);
        },
      },
    });

    expect(removed).toEqual([linkPath]);
    expect(copies).toEqual([{ src: outputDir, dest: linkPath }]);
    expect(extracted.framePaths.get(0)).toBe(win32.join(linkPath, "frame_000001.jpg"));
  });
});

describe("writeCompiledArtifacts — external assets on Windows drive-letter paths (GH #321)", () => {
  const tempDirs: string[] = [];
  afterEach(() => {
    while (tempDirs.length > 0) {
      const d = tempDirs.pop();
      if (d) {
        try {
          rmSync(d, { recursive: true, force: true });
        } catch {
          /* ignore */
        }
      }
    }
  });

  function makeWorkDir(): string {
    const d = mkdtempSync(join(tmpdir(), "hf-orch-"));
    tempDirs.push(d);
    return d;
  }

  it("copies an external asset with a Windows-style drive-letter key into compileDir", () => {
    const workDir = makeWorkDir();
    const sourceDir = mkdtempSync(join(tmpdir(), "hf-src-"));
    tempDirs.push(sourceDir);
    const srcFile = join(sourceDir, "segment.wav");
    writeFileSync(srcFile, "fake wav bytes");

    const windowsStyleInput = "D:\\coder\\assets\\segment.wav";
    const key = toExternalAssetKey(windowsStyleInput);
    expect(key).toBe("hf-ext/D/coder/assets/segment.wav");

    const externalAssets = new Map<string, string>([[key, srcFile]]);
    const compiled = {
      html: "<!doctype html><html><body></body></html>",
      subCompositions: new Map<string, string>(),
      videos: [],
      audios: [],
      unresolvedCompositions: [],
      externalAssets,
      width: 1920,
      height: 1080,
      staticDuration: 10,
      renderModeHints: {
        recommendScreenshot: false,
        reasons: [],
      },
      hasShaderTransitions: false,
    };

    writeCompiledArtifacts(compiled, workDir, false);

    const landed = join(workDir, "compiled", key);
    expect(existsSync(landed)).toBe(true);
    expect(readFileSync(landed, "utf-8")).toBe("fake wav bytes");
  });

  it("rejects a maliciously crafted key that tries to escape compileDir", () => {
    const sandboxRoot = mkdtempSync(join(tmpdir(), "hf-orch-root-"));
    tempDirs.push(sandboxRoot);
    const workDir = join(sandboxRoot, "work", "inner");
    mkdirSync(workDir, { recursive: true });
    const sourceDir = mkdtempSync(join(tmpdir(), "hf-src-"));
    tempDirs.push(sourceDir);
    const srcFile = join(sourceDir, "evil.wav");
    writeFileSync(srcFile, "should never be copied");

    const externalAssets = new Map<string, string>([["hf-ext/../../etc/passwd", srcFile]]);
    const compiled = {
      html: "<!doctype html>",
      subCompositions: new Map<string, string>(),
      videos: [],
      audios: [],
      unresolvedCompositions: [],
      externalAssets,
      width: 1920,
      height: 1080,
      staticDuration: 10,
      renderModeHints: {
        recommendScreenshot: false,
        reasons: [],
      },
      hasShaderTransitions: false,
    };

    writeCompiledArtifacts(compiled, workDir, false);

    const escapeTarget = join(workDir, "etc", "passwd");
    expect(existsSync(escapeTarget)).toBe(false);
  });
});

function createCompiledComposition(
  reasonCodes: Array<"iframe" | "requestAnimationFrame">,
): CompiledComposition {
  return {
    html: "<html></html>",
    subCompositions: new Map(),
    videos: [],
    audios: [],
    unresolvedCompositions: [],
    externalAssets: new Map(),
    width: 1920,
    height: 1080,
    staticDuration: 5,
    renderModeHints: {
      recommendScreenshot: reasonCodes.length > 0,
      reasons: reasonCodes.map((code) => ({
        code,
        message: `reason: ${code}`,
      })),
    },
    hasShaderTransitions: false,
  };
}

// fallow-ignore-next-line code-duplication
function createConfig(): EngineConfig {
  return {
    fps: 30,
    quality: "standard",
    format: "jpeg",
    jpegQuality: 80,
    concurrency: "auto",
    coresPerWorker: 2.5,
    minParallelFrames: 120,
    largeRenderThreshold: 1000,
    disableGpu: false,
    browserGpuMode: "software",
    enableBrowserPool: false,
    browserTimeout: 120000,
    protocolTimeout: 300000,
    forceScreenshot: false,
    lowMemoryMode: false,
    enableChunkedEncode: false,
    chunkSizeFrames: 360,
    enableStreamingEncode: false,
    streamingEncodeMaxDurationSeconds: 240,
    ffmpegEncodeTimeout: 600000,
    ffmpegProcessTimeout: 300000,
    ffmpegStreamingTimeout: 600000,
    hdr: false,
    hdrAutoDetect: true,
    audioGain: 1,
    frameDataUriCacheLimit: 256,
    frameDataUriCacheBytesLimitMb: 1500,
    playerReadyTimeout: 45000,
    renderReadyTimeout: 15000,
    verifyRuntime: true,
    debug: false,
  };
}

describe("applyRenderModeHints", () => {
  // fallow-ignore-next-line code-duplication
  it("forces screenshot mode when compatibility hints recommend it", () => {
    const compiled = createCompiledComposition(["iframe", "requestAnimationFrame"]);
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const result = applyRenderModeHints(false, compiled, log);

    expect(result).toEqual({ forceScreenshot: true, autoSelected: true });
    expect(log.warn).toHaveBeenCalledOnce();
  });

  it("does nothing when screenshot mode is already forced", () => {
    const compiled = createCompiledComposition(["iframe"]);
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const result = applyRenderModeHints(true, compiled, log);

    expect(result).toEqual({ forceScreenshot: true, autoSelected: false });
    expect(log.warn).not.toHaveBeenCalled();
  });

  // fallow-ignore-next-line code-duplication
  it("returns false when neither caller nor hint forces", () => {
    const compiled = createCompiledComposition([]);
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const result = applyRenderModeHints(false, compiled, log);

    expect(result).toEqual({ forceScreenshot: false, autoSelected: false });
    expect(log.warn).not.toHaveBeenCalled();
  });
});

describe("collectVideoReadinessSkipIds", () => {
  it("skips native metadata waits for every injected video with dimensions", () => {
    expect(
      collectVideoReadinessSkipIds(new Set(["hdr-video"]), [
        { videoId: "video1", metadata: { width: 1920, height: 1080 } },
        { videoId: "video2", metadata: { width: 1920, height: 1080 } },
        { videoId: "video3", metadata: { width: 1920, height: 1080 } },
        { videoId: "hdr-video", metadata: { width: 1920, height: 1080 } },
        { videoId: "bad-metadata", metadata: { width: 0, height: 0 } },
      ]),
    ).toEqual(["hdr-video", "video1", "video2", "video3"]);
  });
});

describe("collectVideoMetadataHints", () => {
  it("passes extracted video dimensions to capture sessions", () => {
    expect(
      collectVideoMetadataHints([
        { videoId: "video2", metadata: { width: 1080, height: 1920, durationSeconds: 4 } },
        { videoId: "video1", metadata: { width: 1920, height: 1080, durationSeconds: 12 } },
        { videoId: "bad-metadata", metadata: { width: 0, height: 1080, durationSeconds: 1 } },
      ]),
    ).toEqual([
      { id: "video1", width: 1920, height: 1080 },
      { id: "video2", width: 1080, height: 1920 },
    ]);
  });
});

describe("resolveRenderWorkerCount", () => {
  const cfg = { ...createConfig(), coresPerWorker: 100 };

  it("reduces auto workers for expensive capture workloads", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const workers = resolveRenderWorkerCount(
      180,
      undefined,
      cfg,
      {
        hasShaderTransitions: true,
        renderModeHints: { recommendScreenshot: false, reasons: [] },
      },
      log,
    );

    expect(workers).toBe(1);
    expect(log.warn).toHaveBeenCalledOnce();
  });

  it("respects explicit worker requests", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const workers = resolveRenderWorkerCount(
      180,
      6,
      cfg,
      {
        hasShaderTransitions: true,
        renderModeHints: { recommendScreenshot: false, reasons: [] },
      },
      log,
    );

    expect(workers).toBe(6);
    expect(log.warn).not.toHaveBeenCalled();
  });

  it("uses measured capture cost when static hints miss an expensive composition", () => {
    const workers = resolveRenderWorkerCount(
      180,
      undefined,
      cfg,
      {
        hasShaderTransitions: false,
        renderModeHints: { recommendScreenshot: false, reasons: [] },
      },
      undefined,
      { multiplier: 4, reasons: ["calibration-p95=2400ms"] },
    );

    expect(workers).toBe(1);
  });

  // fallow-ignore-next-line code-duplication
  it("forces single worker when html-in-canvas is detected", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const workers = resolveRenderWorkerCount(
      900,
      undefined,
      cfg,
      {
        hasShaderTransitions: false,
        renderModeHints: {
          recommendScreenshot: false,
          reasons: [{ code: "htmlInCanvas", message: "layoutsubtree canvas" }],
        },
      },
      log,
    );

    expect(workers).toBe(1);
    expect(log.warn).toHaveBeenCalledOnce();
  });

  // fallow-ignore-next-line code-duplication
  it("overrides explicit --workers when html-in-canvas is detected", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const workers = resolveRenderWorkerCount(
      900,
      8,
      cfg,
      {
        hasShaderTransitions: false,
        renderModeHints: {
          recommendScreenshot: false,
          reasons: [{ code: "htmlInCanvas", message: "layoutsubtree canvas" }],
        },
      },
      log,
    );

    expect(workers).toBe(1);
    expect(log.warn).toHaveBeenCalledOnce();
  });

  it("does not pin a capture-motion-blur page to one worker", () => {
    const log = { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };

    const workers = resolveRenderWorkerCount(
      900,
      4,
      cfg,
      {
        hasShaderTransitions: false,
        renderModeHints: {
          recommendScreenshot: true,
          reasons: [{ code: "captureMotionBlur", message: "data-motion-blur" }],
        },
      },
      log,
    );

    expect(workers).toBe(4);
  });

  // fallow-ignore-next-line code-duplication
  it("pins to 1 worker in low-memory mode when no explicit --workers is set", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const workers = resolveRenderWorkerCount(
      900,
      undefined,
      { ...cfg, lowMemoryMode: true },
      {
        hasShaderTransitions: false,
        renderModeHints: { recommendScreenshot: false, reasons: [] },
      },
      log,
    );

    expect(workers).toBe(1);
    expect(log.info).toHaveBeenCalledOnce();
  });

  // fallow-ignore-next-line code-duplication
  it("respects explicit --workers in low-memory mode (only the pin is bypassed)", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const workers = resolveRenderWorkerCount(
      900,
      4,
      { ...cfg, lowMemoryMode: true, coresPerWorker: 2.5 },
      {
        hasShaderTransitions: false,
        renderModeHints: { recommendScreenshot: false, reasons: [] },
      },
      log,
    );

    expect(workers).toBe(4);
  });

  it("keeps baseline auto workers after screenshot fallback when measured capture is cheap", () => {
    const log = {
      error: vi.fn(),
      warn: vi.fn(),
      info: vi.fn(),
      debug: vi.fn(),
    };

    const stableCfg = {
      ...cfg,
      concurrency: 2 as const,
      largeRenderThreshold: 1_000,
    };
    const workers = resolveRenderWorkerCount(
      180,
      undefined,
      { ...stableCfg, forceScreenshot: true },
      {
        hasShaderTransitions: false,
        renderModeHints: { recommendScreenshot: false, reasons: [] },
      },
      log,
      { multiplier: 1, reasons: [], p95Ms: 180 },
    );

    expect(workers).toBe(2);
    expect(log.warn).not.toHaveBeenCalled();
  });
});

describe("resolveCaptureForceScreenshotForPageSideCompositing", () => {
  it("forces screenshot capture when page-side shader compositing is active", () => {
    expect(
      resolveCaptureForceScreenshotForPageSideCompositing({
        forceScreenshot: false,
        usePageSideCompositing: true,
      }),
    ).toBe(true);
  });

  it("preserves the existing capture mode when page-side compositing is inactive", () => {
    expect(
      resolveCaptureForceScreenshotForPageSideCompositing({
        forceScreenshot: false,
        usePageSideCompositing: false,
      }),
    ).toBe(false);
    expect(
      resolveCaptureForceScreenshotForPageSideCompositing({
        forceScreenshot: true,
        usePageSideCompositing: false,
      }),
    ).toBe(true);
  });
});

describe("shouldDiscardProbeSessionForPageSideCompositing", () => {
  it("discards a previously-loaded probe page when page-side compositing is selected", () => {
    expect(
      shouldDiscardProbeSessionForPageSideCompositing({
        hasProbeSession: true,
        usePageSideCompositing: true,
      }),
    ).toBe(true);
  });

  it("reuses the probe session when no page-side pre-head script is required", () => {
    expect(
      shouldDiscardProbeSessionForPageSideCompositing({
        hasProbeSession: true,
        usePageSideCompositing: false,
      }),
    ).toBe(false);
    expect(
      shouldDiscardProbeSessionForPageSideCompositing({
        hasProbeSession: false,
        usePageSideCompositing: true,
      }),
    ).toBe(false);
  });
});

describe("estimateCaptureCostMultiplier", () => {
  it("weights shader transitions and render mode hints without charging static media cost", () => {
    const cost = estimateCaptureCostMultiplier({
      hasShaderTransitions: true,
      renderModeHints: {
        recommendScreenshot: true,
        reasons: [{ code: "requestAnimationFrame", message: "raw rAF" }],
      },
    });

    expect(cost.multiplier).toBe(4);
    expect(cost.reasons).toEqual(["shader-transitions", "requestAnimationFrame"]);
  });
});

describe("shouldUseLayeredComposite", () => {
  it("uses the layered compositor for SDR shader transition renders", () => {
    expect(
      shouldUseLayeredComposite({
        hasHdrContent: false,
        hasShaderTransitions: true,
        isPngSequence: false,
      }),
    ).toBe(true);
  });

  it("does not route PNG sequence shader renders through the streaming layered compositor", () => {
    expect(
      shouldUseLayeredComposite({
        hasHdrContent: false,
        hasShaderTransitions: true,
        isPngSequence: true,
      }),
    ).toBe(false);
  });

  it("keeps HDR content on the layered compositor even without shader transitions", () => {
    expect(
      shouldUseLayeredComposite({
        hasHdrContent: true,
        hasShaderTransitions: false,
        isPngSequence: false,
      }),
    ).toBe(true);
  });
});

describe("resolveCompositeTransfer", () => {
  it("uses 16-bit-expanded sRGB for SDR layered shader transition renders", () => {
    expect(resolveCompositeTransfer(false, undefined)).toBe("srgb");
  });

  it("uses the active HDR transfer when HDR content is being preserved", () => {
    expect(resolveCompositeTransfer(true, { transfer: "hlg" })).toBe("hlg");
  });
});

describe("estimateMeasuredCaptureCostMultiplier", () => {
  it("turns slow calibration samples into a capture cost multiplier", () => {
    const estimate = estimateMeasuredCaptureCostMultiplier([
      { frameIndex: 0, captureTimeMs: 180 },
      { frameIndex: 45, captureTimeMs: 700 },
      { frameIndex: 90, captureTimeMs: 2400 },
      { frameIndex: 135, captureTimeMs: 900 },
    ]);

    expect(estimate.multiplier).toBe(4);
    expect(estimate.reasons).toEqual(["calibration-p95=2400ms"]);
  });

  it("keeps fast calibration samples at baseline cost", () => {
    const estimate = estimateMeasuredCaptureCostMultiplier([
      { frameIndex: 0, captureTimeMs: 120 },
      { frameIndex: 60, captureTimeMs: 180 },
      { frameIndex: 119, captureTimeMs: 220 },
    ]);

    expect(estimate.multiplier).toBe(1);
    expect(estimate.reasons).toEqual([]);
  });
});

describe("selectCaptureCalibrationFrames", () => {
  it("samples the start, middle, end, and quartiles without duplicates", () => {
    expect(selectCaptureCalibrationFrames(180)).toEqual([0, 45, 90, 135, 179]);
    expect(selectCaptureCalibrationFrames(3)).toEqual([0, 1, 2]);
  });
});

describe("capture calibration safeguards", () => {
  it("caps protocol timeout at calibration ceiling for fast fallback", () => {
    const cfg = createConfig();
    const calibrationCfg = createCaptureCalibrationConfig(cfg);

    // Default 300s is above the 30s calibration ceiling — cap at 30s
    // so a wedged BeginFrame times out fast and falls back to screenshot
    expect(calibrationCfg.protocolTimeout).toBe(30000);
    expect(cfg.protocolTimeout).toBe(300000);
  });

  it("preserves user timeout when already below calibration ceiling", () => {
    const cfg = createConfig();
    cfg.protocolTimeout = 5000;

    // 5s is below the 30s ceiling — keep the user's value
    expect(createCaptureCalibrationConfig(cfg).protocolTimeout).toBe(5000);
  });

  it("falls back to screenshot mode after beginFrame calibration failures", () => {
    expect(
      shouldFallbackToScreenshotAfterCalibrationError(
        new Error("HeadlessExperimental.beginFrame timed out"),
      ),
    ).toBe(true);
    expect(shouldFallbackToScreenshotAfterCalibrationError(new Error("ffmpeg exited"))).toBe(false);
  });

  it("falls back to screenshot mode after Runtime.callFunctionOn timeout during calibration", () => {
    expect(
      shouldFallbackToScreenshotAfterCalibrationError(
        new Error(
          "Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.",
        ),
      ),
    ).toBe(true);
    expect(
      shouldFallbackToScreenshotAfterCalibrationError(
        new Error(
          "Runtime.evaluate timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.",
        ),
      ),
    ).toBe(true);
  });
});

describe("adaptive missing-frame retry helpers", () => {
  const tempDirs: string[] = [];

  afterEach(() => {
    while (tempDirs.length > 0) {
      const d = tempDirs.pop();
      if (d) rmSync(d, { recursive: true, force: true });
    }
  });

  function makeFramesDir(): string {
    const d = mkdtempSync(join(tmpdir(), "hf-missing-frames-"));
    tempDirs.push(d);
    return d;
  }

  it("finds contiguous missing frame ranges from captured disk frames", () => {
    const framesDir = makeFramesDir();
    for (const frameIndex of [0, 1, 4]) {
      writeFileSync(
        join(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.jpg`),
        "captured-frame",
      );
    }

    expect(findMissingFrameRanges(6, framesDir, "jpg")).toEqual([
      { startFrame: 2, endFrame: 4 },
      { startFrame: 5, endFrame: 6 },
    ]);
  });

  it("retries a worker placeholder instead of accepting a truncated sequence", () => {
    const framesDir = makeFramesDir();
    for (let frameIndex = 0; frameIndex < 4; frameIndex++) {
      writeFileSync(
        join(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.jpg`),
        frameIndex === 2 ? "x" : "captured-frame",
      );
    }

    expect(findMissingFrameRanges(4, framesDir, "jpg")).toEqual([{ startFrame: 2, endFrame: 3 }]);
  });

  it("builds retry batches that cap active workers per attempt", () => {
    const batches = buildMissingFrameRetryBatches(
      [
        { startFrame: 2, endFrame: 4 },
        { startFrame: 5, endFrame: 6 },
        { startFrame: 9, endFrame: 12 },
      ],
      2,
      "/tmp/work",
      1,
    );

    expect(batches).toHaveLength(2);
    expect(batches[0]).toMatchObject([
      { workerId: 0, startFrame: 2, endFrame: 4 },
      { workerId: 1, startFrame: 5, endFrame: 6 },
    ]);
    expect(batches[1]).toMatchObject([{ workerId: 0, startFrame: 9, endFrame: 12 }]);
    expect(batches[0][0].outputDir).toContain("retry-1-batch-0-worker-0");
  });

  it("halves retry workers until sequential fallback", () => {
    expect(getNextRetryWorkerCount(8)).toBe(4);
    expect(getNextRetryWorkerCount(3)).toBe(1);
    expect(getNextRetryWorkerCount(2)).toBe(1);
    expect(getNextRetryWorkerCount(1)).toBe(1);
  });

  it("only retries parallel capture timeout failures", () => {
    expect(
      isRecoverableParallelCaptureError(
        new Error("[Parallel] Capture failed: Worker 0: Runtime.callFunctionOn timed out"),
      ),
    ).toBe(true);
    expect(
      isRecoverableParallelCaptureError(
        new Error("[Parallel] Capture failed: Worker 1: HeadlessExperimental.beginFrame timed out"),
      ),
    ).toBe(true);
    expect(
      isRecoverableParallelCaptureError(
        new Error(
          "[Parallel] Capture failed: Worker 2: Page.captureScreenshot timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.",
        ),
      ),
    ).toBe(true);
    expect(
      isRecoverableParallelCaptureError(
        new Error(
          "[Parallel] Capture failed: Worker 0: drawElement worker encode timed out (frame 42)",
        ),
      ),
    ).toBe(true);
    expect(
      isRecoverableParallelCaptureError(
        new Error(
          "[Parallel] Capture failed: Worker 0: Protocol error (Page.captureScreenshot): Unable to capture screenshot",
        ),
      ),
    ).toBe(true);
    expect(isRecoverableParallelCaptureError(new Error("Encoding failed: ffmpeg exited"))).toBe(
      false,
    );
  });
});

describe("projectBrowserEndToCompositionTimeline", () => {
  it("keeps end unchanged when browser and compiled starts share the same origin", () => {
    expect(projectBrowserEndToCompositionTimeline(2, 2, 6)).toBe(6);
  });

  it("reprojects a scene-local browser end into the compiled host timeline", () => {
    expect(projectBrowserEndToCompositionTimeline(4.417, 0, 85.52)).toBeCloseTo(89.937, 6);
  });

  it("preserves scene-local media offsets inside compositions that start much later", () => {
    expect(projectBrowserEndToCompositionTimeline(21.5, 1.5, 5.5)).toBe(25.5);
  });
});

describe("resolveDeviceScaleFactor", () => {
  const defaults = {
    compositionWidth: 1920,
    compositionHeight: 1080,
    hdrRequested: false,
    alphaRequested: false,
  } as const;

  it("returns 1 when no outputResolution is set (default behavior)", () => {
    expect(resolveDeviceScaleFactor({ ...defaults, outputResolution: undefined })).toBe(1);
  });

  it("returns 2 for the canonical 1080p → 4K supersample", () => {
    expect(resolveDeviceScaleFactor({ ...defaults, outputResolution: "landscape-4k" })).toBe(2);
  });

  it("returns 2 for portrait 1080p → portrait-4k", () => {
    expect(
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 1080,
        compositionHeight: 1920,
        outputResolution: "portrait-4k",
      }),
    ).toBe(2);
  });

  it("returns 1 when the composition already matches the requested resolution", () => {
    expect(
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 3840,
        compositionHeight: 2160,
        outputResolution: "landscape-4k",
      }),
    ).toBe(1);
  });

  it("rejects HDR + outputResolution with a clear message", () => {
    expect(() =>
      resolveDeviceScaleFactor({
        ...defaults,
        outputResolution: "landscape-4k",
        hdrRequested: true,
      }),
    ).toThrow(/hdrMode='force-hdr'/);
  });

  it("returns the requested DPR for alpha + outputResolution", () => {
    expect(
      resolveDeviceScaleFactor({
        ...defaults,
        outputResolution: "landscape-4k",
        alphaRequested: true,
      }),
    ).toBe(2);
  });

  it("rejects orientation mismatch (landscape comp → portrait-4k)", () => {
    expect(() =>
      resolveDeviceScaleFactor({ ...defaults, outputResolution: "portrait-4k" }),
    ).toThrow(/aspect ratio/);
  });

  it("suggests the matching-orientation preset in the aspect-mismatch message", () => {
    // Landscape composition + portrait preset → the message should point at
    // the landscape swap so the user isn't left to guess (workstream P1-3).
    expect(() => resolveDeviceScaleFactor({ ...defaults, outputResolution: "portrait" })).toThrow(
      /--resolution landscape/,
    );
  });

  it("returns 0.5 for a 4K composition → 1080p output", () => {
    expect(
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 3840,
        compositionHeight: 2160,
        outputResolution: "landscape",
      }),
    ).toBe(0.5);
  });

  it("scales 1080p down for 720p and 480p, so 480p frames are 854×480", () => {
    const scale = (outputResolution: "landscape-720p" | "landscape-480p") =>
      resolveDeviceScaleFactor({ ...defaults, outputResolution });
    expect(scale("landscape-720p")).toBeCloseTo(2 / 3);
    expect(scale("landscape-480p")).toBe(854 / 1920);
    expect([
      Math.round(1920 * scale("landscape-480p")),
      Math.round(1080 * scale("landscape-480p")),
    ]).toEqual([854, 480]);
  });

  it("rejects non-integer scale factors", () => {
    // 1500×844 → 3840×2160 has slightly different ratios in width vs height.
    // The aspect-ratio guard fires first; pinning the rejection message
    // covers both error paths since either is an acceptable failure here.
    expect(() =>
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 1500,
        compositionHeight: 844,
        outputResolution: "landscape-4k",
      }),
    ).toThrow(/aspect ratio|non-integer/);
  });

  it("returns 1 for a square comp matching the square preset", () => {
    expect(
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 1080,
        compositionHeight: 1080,
        outputResolution: "square",
      }),
    ).toBe(1);
  });

  it("returns 2 for square 1080 → square-4k", () => {
    expect(
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 1080,
        compositionHeight: 1080,
        outputResolution: "square-4k",
      }),
    ).toBe(2);
  });

  it("rejects landscape preset on a square composition", () => {
    expect(() =>
      resolveDeviceScaleFactor({
        ...defaults,
        compositionWidth: 1080,
        compositionHeight: 1080,
        outputResolution: "landscape",
      }),
    ).toThrow(/aspect ratio/);
  });
});

describe("shouldPreferSingleWorkerDrawElement (DE priority inversion)", () => {
  const eligible = {
    workerCount: 5,
    requestedWorkers: "auto" as const,
    useDrawElement: true,
    deCompileGate: undefined,
    forceScreenshot: false,
    outputFormat: "mp4" as const,
    totalFrames: 2380,
    minFrames: 900,
    singleWorkerStreamingOk: true,
    layeredOrEffectRoute: false,
    supersampling: false,
    probeDeGated: false,
    experimentalParallelDeOptIn: false,
  };

  it("inverts an auto-resolved multi-worker render for an eligible long comp", () => {
    expect(shouldPreferSingleWorkerDrawElement(eligible)).toBe(true);
  });

  // ── Short-comp band ──────────────────────────────────────────────────────────────────────
  // The call site evaluates the predicate TWICE — once at the 900 floor, once
  // at the 250 band floor — and the band is DECISIVE only when the calls
  // disagree. These pin that arithmetic, including the property the design
  // depends on: the band can only ADD inversions, never remove one.
  //
  // Measured basis (400f, single-DE vs parallel-screenshot-W4, ratio = ss4/de1
  // so >1 means DE wins):
  //   24 movers /     0 nodes -> 1.05   |   24 movers /  7000 nodes -> 0.96
  //  320 movers /     0 nodes -> 1.24   |   24 movers / 20000 nodes -> 0.71
  //  320 movers /  7000 nodes -> 1.09   |   24 movers / 40000 nodes -> 0.55
  // Motion helps DE, DOM size punishes it; the element ceiling is calibrated
  // at the lowest-motion case so every higher-motion comp is covered too.
  describe("short-comp band decisiveness (two-floor evaluation)", () => {
    const BAND_FLOOR = Math.min(900, 250);
    const atBase = (totalFrames: number, over?: Partial<typeof eligible>) =>
      shouldPreferSingleWorkerDrawElement({ ...eligible, ...over, totalFrames, minFrames: 900 });
    const atBand = (totalFrames: number, over?: Partial<typeof eligible>) =>
      shouldPreferSingleWorkerDrawElement({
        ...eligible,
        ...over,
        totalFrames,
        minFrames: BAND_FLOOR,
      });

    it("is decisive exactly in the 250-899 window for an otherwise-eligible render", () => {
      expect(atBand(400) && !atBase(400)).toBe(true);
      expect(atBand(250) && !atBase(250)).toBe(true);
      expect(atBand(899) && !atBase(899)).toBe(true);
    });

    it("is NOT decisive below the band floor — nothing fires either way", () => {
      expect(atBand(200)).toBe(false);
      expect(atBase(200)).toBe(false);
    });

    it("is NOT decisive at 900+ — the pre-existing floor already inverts, unchanged", () => {
      expect(atBase(2380)).toBe(true);
      expect(atBand(2380) && !atBase(2380)).toBe(false);
    });

    it("is NOT decisive when the render is ineligible for any other reason — the attribution cohort must exclude renders the band cannot affect", () => {
      for (const over of [
        { requestedWorkers: 3 as const },
        { useDrawElement: false },
        { deCompileGate: "css_effect:filter" },
        { forceScreenshot: true },
        { outputFormat: "webm" as const },
        { singleWorkerStreamingOk: false },
        { probeDeGated: true },
      ]) {
        expect(atBand(400, over)).toBe(false);
      }
    });

    it("HF_DE_SHORT_MIN_FRAMES=0 disables via the predicate's own minFrames guard", () => {
      expect(
        shouldPreferSingleWorkerDrawElement({
          ...eligible,
          totalFrames: 400,
          minFrames: Math.min(900, 0),
        }),
      ).toBe(false);
    });
  });

  describe("resolveDeShortBand", () => {
    const live = { elementCountSource: "live" as const };

    it("reports applied only when decisive, live-measured, and under the ceiling", () => {
      expect(
        resolveDeShortBand({
          ...live,
          invertAtBaseFloor: false,
          invertAtBandFloor: true,
          bandEnabled: true,
          bandOpen: true,
        }),
      ).toBe("applied");
    });

    it("reports skipped_elements when live-measured and over the ceiling", () => {
      expect(
        resolveDeShortBand({
          ...live,
          invertAtBaseFloor: false,
          invertAtBandFloor: true,
          bandEnabled: true,
          bandOpen: false,
        }),
      ).toBe("skipped_elements");
    });

    it("is undefined when the base floor already inverts — the band changed nothing", () => {
      expect(
        resolveDeShortBand({
          ...live,
          invertAtBaseFloor: true,
          invertAtBandFloor: true,
          bandEnabled: true,
          bandOpen: true,
        }),
      ).toBeUndefined();
    });

    it("is undefined when neither floor inverts — the render was ineligible for some other reason", () => {
      expect(
        resolveDeShortBand({
          ...live,
          invertAtBaseFloor: false,
          invertAtBandFloor: false,
          bandEnabled: true,
          bandOpen: true,
        }),
      ).toBeUndefined();
    });

    // Review finding (R1 + R2, both reviewers): HF_DE_SHORT_MAX_ELEMENTS=0
    // must read as "band disabled" (undefined), never "comp too large"
    // (skipped_elements) — the latter would poison the DiD control cohort by
    // mislabeling a kill-switch event as a real oversize measurement.
    it("HF_DE_SHORT_MAX_ELEMENTS=0 (bandEnabled=false) reports undefined even when the render would otherwise be decisive", () => {
      expect(
        resolveDeShortBand({
          ...live,
          invertAtBaseFloor: false,
          invertAtBandFloor: true, // an otherwise-eligible in-band render
          bandEnabled: false, // the kill switch
          bandOpen: false, // deShortBandOpen also false when the switch is off
        }),
      ).toBeUndefined();
    });

    // Review finding (R4): the probe supplying the live count is conditional,
    // so a static count is an UNBOUNDED undercount on runtime-generated DOM.
    // It must never produce "applied" (would route a 40k-node comp) and must
    // never produce "skipped_elements" either (would contaminate the DiD
    // control cohort with a number that isn't a real oversize observation).
    it("fails closed to unmeasured when the count came from the static scan, never applied", () => {
      expect(
        resolveDeShortBand({
          elementCountSource: "static",
          invertAtBaseFloor: false,
          invertAtBandFloor: true,
          bandEnabled: true,
          bandOpen: true, // static scan said "small" — must NOT be believed
        }),
      ).toBe("unmeasured");
    });

    it("reports unmeasured (not skipped_elements) for a static count over the ceiling — it is not a real observation either", () => {
      expect(
        resolveDeShortBand({
          elementCountSource: "static",
          invertAtBaseFloor: false,
          invertAtBandFloor: true,
          bandEnabled: true,
          bandOpen: false,
        }),
      ).toBe("unmeasured");
    });

    it("stays undefined for a static count when the band was not decisive anyway", () => {
      expect(
        resolveDeShortBand({
          elementCountSource: "static",
          invertAtBaseFloor: true,
          invertAtBandFloor: true,
          bandEnabled: true,
          bandOpen: true,
        }),
      ).toBeUndefined();
    });
  });

  // Review finding (R4), end-to-end: the review asked for a regression with a
  // known duration, no media / unresolved compositions, and >2500
  // script-created nodes, asserting it cannot enter `applied` without a live
  // count. This walks the real decision chain rather than a full render —
  // the probe gate, the count resolver, and the band attribution are each the
  // production function, wired in the same order the pipeline wires them.
  describe("no-probe dynamic-DOM composition cannot enter the applied cohort (R4 regression)", () => {
    // A caption-style comp: known duration, no media, builds 4000 spans in
    // its own init script. Mirrors packages/producer/tests/style-10-prod.
    const DYNAMIC_DOM_HTML = [
      '<div id="root"><div id="captions"></div></div>',
      "<script>",
      '  const c = document.getElementById("captions");',
      "  for (let i = 0; i < 4000; i++) {",
      '    const el = document.createElement("span");',
      "    el.textContent = String(i);",
      "    c.appendChild(el);",
      "  }",
      "</script>",
    ].join("\n");

    it("gets no browser probe — none of the probe conditions fire for this shape", () => {
      expect(
        probeRequiresBrowser({
          durationSeconds: 13.3, // known
          unresolvedCompositionCount: 0, // resolved
          hasAutoStart: false, // no media
          hasScriptedAudio: false,
          hasVariableMedia: false,
          // createElement("span") is not createElement("video"|"audio")
          hasInsertedMedia: false,
        }),
      ).toBe(false);
    });

    it("therefore measures statically, and the static count wildly understates the live DOM", async () => {
      const resolved = await resolveCompositionElementCount(null, DYNAMIC_DOM_HTML);
      expect(resolved.source).toBe("static");
      // Source markup has a handful of tags; the live DOM would have 4000+.
      expect(resolved.count).toBeLessThan(2500);
    });

    it("and therefore reports unmeasured — never applied — so it cannot route or join either cohort", async () => {
      const { count, source } = await resolveCompositionElementCount(null, DYNAMIC_DOM_HTML);
      const bandOpen = source === "live" && count <= 2500;
      const band = resolveDeShortBand({
        // A 400-frame render that would otherwise be perfectly eligible.
        invertAtBaseFloor: false,
        invertAtBandFloor: true,
        bandEnabled: true,
        bandOpen,
        elementCountSource: source,
      });
      expect(band).toBe("unmeasured");
      expect(band).not.toBe("applied");
    });
  });

  describe("mergeWorkerInitObservability", () => {
    it("max-merges across workers and ignores workers that reported nothing", () => {
      expect(
        mergeWorkerInitObservability([
          { initDurationMs: 400, initTweenCount: 900, initElementCount: 1200 },
          {},
          { initDurationMs: 1250, initTweenCount: 880, initElementCount: 1190 },
        ]),
      ).toEqual({ initDurationMs: 1250, tweenCount: 900, elementCount: 1200 });
    });

    it("returns undefined when no worker reported — summary.init must stay absent, not zeroed", () => {
      expect(mergeWorkerInitObservability([])).toBeUndefined();
      expect(mergeWorkerInitObservability([{}, {}])).toBeUndefined();
    });

    it("surfaces an element count even when a worker reported nothing else", () => {
      expect(mergeWorkerInitObservability([{ initElementCount: 4000 }])).toEqual({
        initDurationMs: undefined,
        tweenCount: undefined,
        elementCount: 4000,
      });
    });
  });

  describe("scanElementTags", () => {
    it("counts closing tags", () => {
      expect(scanElementTags("<div><span>a</span></div>").total).toBe(2);
    });

    it("counts void elements — an image gallery must not read as a tiny comp", () => {
      expect(scanElementTags("<img><br><hr>").total).toBe(3);
      expect(scanElementTags('<img src="a.png"><IMG SRC="b.png">').total).toBe(2);
    });

    // Review-flagged blocker (v1): SVG elements are neither closing-tag-shaped
    // nor in the HTML void list, so a self-closing-SVG-heavy comp read as
    // element count 0 — an UNBOUNDED undercount, the same failure class as
    // the original <img> counterexample, and the exact shape of comp the
    // measured 1.8x regression case is made of. The ceiling cannot bound an
    // error that has no bound of its own.
    it("counts self-closing SVG elements — the 40k-node regression case must not read as empty", () => {
      expect(scanElementTags("<circle/>".repeat(40000)).total).toBe(40000);
      expect(scanElementTags('<path d="M0 0 L1 1" stroke="red" />').total).toBe(1);
      expect(scanElementTags("<feGaussianBlur stdDeviation='2'/>").total).toBe(1);
    });

    it("does not double-count a self-closed void element (still just 1)", () => {
      expect(scanElementTags('<img src="a.png"/>').total).toBe(1);
      expect(scanElementTags('<img src="a.png" />').total).toBe(1);
    });

    it("does not false-positive on minified JS division-after-comparison (the self-closing alt's real risk)", () => {
      // Unspaced "<b/c>" is the adversarial case: "<" IS immediately
      // followed by a letter, so the generic self-closing alt gets as far as
      // starting a match — but it still requires the literal two-char "/>"
      // sequence, and here a "c" sits between the "/" and the ">", so
      // backtracking never finds one and it correctly fails to match.
      expect(scanElementTags("if(a<b/c>d){}").total).toBe(0);
    });

    it("does not false-positive on inline-script comparisons or void-prefixed words", () => {
      // Script bodies are stripped wholesale (with their own closing tag), so
      // nothing inside can match — including "<breadth" / "<imgWidth", which
      // would anyway fail the \b word boundary.
      expect(
        scanElementTags("<script>if (a < b && x <breadth && y <imgWidth) {}</script>").total,
      ).toBe(0);
    });

    // Review finding: the `</[a-zA-Z]` alternation matches ANY "</" + letter,
    // including inside JS strings and template literals. Compiled comps embed
    // large inline scripts, so this bias is systematic — and it lands entirely
    // on the ~83% of renders with no probe, for which this scan is the only
    // element signal.
    it("does not count closing tags written inside inline script strings", () => {
      expect(
        scanElementTags('<div></div><script>const h = "</div></div></div>";</script>').total,
      ).toBe(1);
      expect(
        scanElementTags("<p></p><script>const t = words.map(w => `</span>`).join('');</script>")
          .total,
      ).toBe(1);
    });

    it("strips <style> bodies too — CSS content strings can carry the same shapes", () => {
      expect(scanElementTags('<div></div><style>a::after{content:"</div>"}</style>').total).toBe(1);
    });

    // CodeQL "incomplete multi-character sanitization": a single-pass replace
    // can reform the very pattern it removed. Impact is nil here (the stripped
    // string is counted, never rendered) but a reformed tag would perturb the
    // count, so the strip runs to a fixed point.
    it("strips script tags that reform after one pass", () => {
      // Inner <script> removed by pass 1 leaves "<script>alert(1)</script>",
      // which pass 2 removes. A single pass would leave a stray tag behind.
      expect(scanElementTags("<div></div><scr<script></script>ipt>alert(1)</script>").total).toBe(
        1,
      );
    });

    it("terminates on input with no closing tag rather than looping", () => {
      expect(scanElementTags("<div></div><script>unterminated").total).toBe(1);
    });

    it("strips multiple and attributed script blocks, not just the first", () => {
      expect(
        scanElementTags(
          '<div></div><script type="module">"</span>"</script><script>"</span>"</script>',
        ).total,
      ).toBe(1);
    });

    it("is stable on empty and malformed input rather than throwing", () => {
      expect(scanElementTags("").total).toBe(0);
      expect(scanElementTags("<<<>>>").total).toBe(0);
    });

    it("scales to a large document without a full parse", () => {
      expect(scanElementTags("<p>x</p>".repeat(40000)).total).toBe(40000);
    });

    it("groups mixed native and custom hf-* tags by raw tag name", () => {
      const html =
        "<div><span>a</span></div><hf-caption></hf-caption><hf-audio-group></hf-audio-group><div></div>";
      const scan = scanElementTags(html);
      expect(scan.byTag).toEqual({ div: 2, span: 1, "hf-caption": 1, "hf-audio-group": 1 });
      expect(scan.total).toBe(5);
    });

    it("normalizes case so <DIV>/<Div>/<div> collapse into one key", () => {
      const scan = scanElementTags("<DIV></DIV><Div></Div><div></div>");
      expect(scan.byTag).toEqual({ div: 3 });
    });

    it("count/map consistency: the sum of byTag always equals total", () => {
      const html =
        '<div><img src="a.png"><hf-caption></hf-caption></div><circle/><path d="M0 0" />' +
        "<hf-audio-group></hf-audio-group>".repeat(3);
      const scan = scanElementTags(html);
      const sum = Object.values(scan.byTag).reduce((a, b) => a + b, 0);
      expect(sum).toBe(scan.total);
    });

    it("caps distinct reported tags, folding the overflow into an `other` bucket", () => {
      // 60 distinct single-use tag names, well past the 50-tag cap. "div"
      // (100 uses) takes the top rank, leaving only 49 of the 50 slots for
      // the 60 distinct tags — 11 of them fold into "other".
      const distinctTags = Array.from({ length: 60 }, (_, i) => `hf-tag-${i}`);
      const html = "<div></div>".repeat(100) + distinctTags.map((t) => `<${t}></${t}>`).join("");
      const scan = scanElementTags(html);
      expect(Object.keys(scan.byTag).length).toBe(51); // 50 reported + "other"
      expect(scan.byTag.div).toBe(100);
      expect(scan.byTag.other).toBe(11); // 60 distinct tags - 49 reported = 11 folded in
      const sum = Object.values(scan.byTag).reduce((a, b) => a + b, 0);
      expect(sum).toBe(scan.total);
      expect(scan.total).toBe(100 + 60);
    });

    it("counts <video data-aroll=true> elements, not audio/img carrying the same attribute", () => {
      const html =
        '<video data-aroll="true" src="a.mp4"></video>' +
        '<video src="b.mp4"></video>' +
        '<audio data-aroll="true" src="a.mp3"></audio>' +
        '<img data-aroll="true" src="a.png" />';
      expect(scanElementTags(html).arollVideoCount).toBe(1);
    });

    it("counts <video data-media-source=heygen> elements only, not other provider values", () => {
      const html =
        '<video data-media-source="heygen" src="a.mp4"></video>' +
        '<video src="b.mp4"></video>' +
        '<video data-media-source="ltx.local" src="c.mp4"></video>' +
        '<audio data-media-source="heygen" src="a.mp3"></audio>';
      expect(scanElementTags(html).heygenVideoCount).toBe(1);
    });

    it("counts audio/image/audio-group elements from the uncapped Map, not the capped byTag", () => {
      // 55 distinct single-use filler tags, each ranked (tied count=1) ahead
      // of audio/img/hf-audio-group by insertion order in a stable sort,
      // push all three past the 50-tag cap into "other" in byTag, but the
      // dedicated counts must still report the true number.
      const distinctTags = Array.from({ length: 55 }, (_, i) => `hf-tag-${i}`);
      const html =
        distinctTags.map((t) => `<${t}></${t}>`).join("") +
        "<audio></audio><img/><hf-audio-group></hf-audio-group>";
      const scan = scanElementTags(html);
      expect(scan.audioCount).toBe(1);
      expect(scan.imageCount).toBe(1);
      expect(scan.audioGroupCount).toBe(1);
      expect(scan.byTag.audio).toBeUndefined();
      expect(scan.byTag.img).toBeUndefined();
      expect(scan.byTag["hf-audio-group"]).toBeUndefined();
    });

    it("counts data-composition-src sub-composition mounts", () => {
      const html =
        '<div data-composition-src="a.html" data-duration="2"></div>' +
        '<section data-composition-src="b.html"></section><div></div>';
      expect(scanElementTags(html).subCompositionCount).toBe(2);
    });

    it("counts data-color-grading elements and detects a LUT reference", () => {
      const html =
        '<img data-color-grading=\'{"lut":{"src":"a.cube","intensity":0.5}}\'>' +
        '<video data-color-grading=\'{"exposure":0.2,"lut":null}\'></video>';
      const scan = scanElementTags(html);
      expect(scan.colorGradingCount).toBe(2);
      expect(scan.hasLut).toBe(true);
    });

    it("reports hasLut false when no color-grading element references a LUT", () => {
      const html = '<img data-color-grading=\'{"exposure":0.2,"lut":null}\'>';
      const scan = scanElementTags(html);
      expect(scan.colorGradingCount).toBe(1);
      expect(scan.hasLut).toBe(false);
    });

    it("decodes the &quot;-escaped attribute form the compile pipeline actually emits", () => {
      // linkedom's serializer re-emits this attribute &quot;-escaped on every
      // compile round-trip, the real mainstream shape, not single-quoted.
      const html = '<img data-color-grading="{&quot;lut&quot;:&quot;a.cube&quot;}">';
      const scan = scanElementTags(html);
      expect(scan.colorGradingCount).toBe(1);
      expect(scan.hasLut).toBe(true);
    });

    // Mirrors normalizeLut (@hyperframes/core colorGrading.ts): an empty
    // string, an object with no `src`, or a blank `src` are all "no LUT",
    // matching the runtime consumer, not just "the key is present".
    it("reports hasLut false for an empty-string, srcless, or blank-src lut value", () => {
      const html =
        '<img data-color-grading=\'{"lut":""}\'>' +
        "<img data-color-grading='{\"lut\":{}}'>" +
        '<img data-color-grading=\'{"lut":{"src":"  "}}\'>';
      const scan = scanElementTags(html);
      expect(scan.colorGradingCount).toBe(3);
      expect(scan.hasLut).toBe(false);
    });

    it("does not crash on malformed data-color-grading JSON, counts the element, no LUT signal", () => {
      const html = "<img data-color-grading='{not json'>";
      const scan = scanElementTags(html);
      expect(scan.colorGradingCount).toBe(1);
      expect(scan.hasLut).toBe(false);
    });

    it("reports zero (not undefined) for every count and an empty byTag when nothing matches", () => {
      const scan = scanElementTags("plain text, no tags at all");
      expect(scan.arollVideoCount).toBe(0);
      expect(scan.heygenVideoCount).toBe(0);
      expect(scan.audioCount).toBe(0);
      expect(scan.imageCount).toBe(0);
      expect(scan.subCompositionCount).toBe(0);
      expect(scan.audioGroupCount).toBe(0);
      expect(scan.colorGradingCount).toBe(0);
      expect(scan.hasLut).toBe(false);
      expect(scan.byTag).toEqual({});
      expect(scan.total).toBe(0);
      // Unlike the counts above, this pair reports absent (not a false/"0"
      // default) when there's no root tag at all to compare against.
      expect(scan.rootBodyMismatch).toBeUndefined();
      expect(scan.rootBodyDeltaPxBucket).toBeUndefined();
      // data-vfx-chain: no hosts, so vfxCapture never ran ("undefined", not
      // "none" — there is nothing to have a capture requirement).
      expect(scan.vfxHostCount).toBe(0);
      expect(scan.vfxTypes).toBe("");
      expect(scan.vfxCapture).toBeUndefined();
    });

    it("counts data-vfx-chain hosts, unions sorted def ids across every chain, and takes the strongest capture", () => {
      const html =
        '<div data-vfx-chain=\'{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{}}]}\'></div>' +
        '<div data-vfx-chain=\'{"version":1,"nodes":[{"type":"wave-warp","id":"n1","params":{}},' +
        '{"type":"displacement-map","id":"n2","params":{}}]}\'></div>';
      const scan = scanElementTags(html);
      expect(scan.vfxHostCount).toBe(2);
      // fractal-noise is capture "none"; wave-warp/displacement-map are "self"
      // — the strongest of the two hosts wins.
      expect(scan.vfxCapture).toBe("self");
      expect(scan.vfxTypes).toBe("displacement-map,fractal-noise,wave-warp");
    });

    it("excludes a disabled node's type from vfxTypes but still counts its host", () => {
      const html =
        '<div data-vfx-chain=\'{"version":1,"nodes":[' +
        '{"type":"wave-warp","id":"n1","enabled":false,"params":{}},' +
        '{"type":"fractal-noise","id":"n2","params":{}}]}\'></div>';
      const scan = scanElementTags(html);
      expect(scan.vfxHostCount).toBe(1);
      expect(scan.vfxTypes).toBe("fractal-noise");
      // The only enabled node is fractal-noise (capture "none") — the
      // disabled self-capture node must not inflate the chain's capture.
      expect(scan.vfxCapture).toBe("none");
    });

    it("decodes the &quot;-escaped data-vfx-chain form the compile pipeline emits", () => {
      const html =
        '<div data-vfx-chain="{&quot;version&quot;:1,&quot;nodes&quot;:[{&quot;type&quot;:' +
        '&quot;fractal-noise&quot;,&quot;id&quot;:&quot;n1&quot;,&quot;params&quot;:{}}]}"></div>';
      const scan = scanElementTags(html);
      expect(scan.vfxHostCount).toBe(1);
      expect(scan.vfxTypes).toBe("fractal-noise");
    });

    it("does not crash on a malformed data-vfx-chain attribute; still counts the host, no type or capture signal from it", () => {
      const html = "<div data-vfx-chain='{not json'></div>";
      const scan = scanElementTags(html);
      expect(scan.vfxHostCount).toBe(1);
      expect(scan.vfxTypes).toBe("");
      expect(scan.vfxCapture).toBeUndefined();
    });

    describe("rootBodyMismatch / rootBodyDeltaPxBucket", () => {
      function html(rootWidth: number, rootHeight: number, css: string): string {
        return (
          `<style>${css}</style>` +
          `<body><div data-composition-id="c1" data-width="${rootWidth}" data-height="${rootHeight}"></div></body>`
        );
      }

      it("reports no mismatch and bucket 0 when the scaffold's html/body CSS matches the root exactly", () => {
        const scan = scanElementTags(
          html(1080, 1920, "html, body { width: 1080px; height: 1920px; }"),
        );
        expect(scan.rootBodyMismatch).toBe(false);
        expect(scan.rootBodyDeltaPxBucket).toBe("0");
      });

      it("buckets a small stale-scaffold delta as 1-10", () => {
        const scan = scanElementTags(
          html(1080, 1920, "html, body { width: 1085px; height: 1920px; }"),
        );
        expect(scan.rootBodyMismatch).toBe(true);
        expect(scan.rootBodyDeltaPxBucket).toBe("1-10");
      });

      it("buckets a mid-size delta as 11-50", () => {
        const scan = scanElementTags(
          html(1080, 1920, "html, body { width: 1080px; height: 1950px; }"),
        );
        expect(scan.rootBodyMismatch).toBe(true);
        expect(scan.rootBodyDeltaPxBucket).toBe("11-50");
      });

      it("buckets a landscape-scaffold-under-portrait-root delta as 51+ (the real #4001 shape)", () => {
        const scan = scanElementTags(
          html(1080, 1920, "html, body { width: 1920px; height: 1080px; }"),
        );
        expect(scan.rootBodyMismatch).toBe(true);
        expect(scan.rootBodyDeltaPxBucket).toBe("51+");
      });

      it("reads a height-authored-before-width CSS block the same way", () => {
        const scan = scanElementTags(
          html(1080, 1920, "html, body { height: 1920px; width: 1080px; }"),
        );
        expect(scan.rootBodyMismatch).toBe(false);
        expect(scan.rootBodyDeltaPxBucket).toBe("0");
      });

      it("reports absent, not a false default, when there is no composition root to read", () => {
        const scan = scanElementTags(
          "<style>html, body { width: 1080px; height: 1920px; }</style><p>no root</p>",
        );
        expect(scan.rootBodyMismatch).toBeUndefined();
        expect(scan.rootBodyDeltaPxBucket).toBeUndefined();
      });

      it("reports absent, not a false default, when the scaffold has no html/body CSS block at all", () => {
        const scan = scanElementTags(
          '<body><div data-composition-id="c1" data-width="1080" data-height="1920"></div></body>',
        );
        expect(scan.rootBodyMismatch).toBeUndefined();
        expect(scan.rootBodyDeltaPxBucket).toBeUndefined();
      });
    });
  });

  describe("resolveCompositionElementCount", () => {
    // Review finding (R3): a static scan of SOURCE markup cannot see DOM a
    // composition's own script creates at runtime (document.createElement) —
    // an unbounded undercount no regex can close. style-10-prod's real
    // per-transcript-word caption generator is exactly this shape: 2 source
    // tags, thousands of live nodes after init.
    //
    // Review finding (R4): the probe that provides the live count is
    // CONDITIONAL, so the fallback cases below are not merely "less precise"
    // — they are UNSAFE to gate on, and every one of them must report
    // provenance "static" so the caller can fail closed.
    it("uses the live DOM count from an initialized probe session, ignoring the (much smaller) source scan", async () => {
      const session = { isInitialized: true, page: { evaluate: async () => 40001 } };
      expect(await resolveCompositionElementCount(session, "<div><span></span></div>")).toEqual({
        count: 40001,
        source: "live",
      });
    });

    it("reports static provenance when there is no probe session", async () => {
      expect(await resolveCompositionElementCount(null, "<div><span></span></div>")).toEqual({
        count: 2,
        source: "static",
        byTag: { div: 1, span: 1 },
        arollVideoCount: 0,
        heygenVideoCount: 0,
        audioCount: 0,
        imageCount: 0,
        subCompositionCount: 0,
        audioGroupCount: 0,
        colorGradingCount: 0,
        hasLut: false,
        vfxHostCount: 0,
        vfxTypes: "",
      });
    });

    it("reports static provenance when the probe session is not yet initialized", async () => {
      const session = { isInitialized: false, page: { evaluate: async () => 999 } };
      expect(await resolveCompositionElementCount(session, "<div></div>")).toEqual({
        count: 1,
        source: "static",
        byTag: { div: 1 },
        arollVideoCount: 0,
        heygenVideoCount: 0,
        audioCount: 0,
        imageCount: 0,
        subCompositionCount: 0,
        audioGroupCount: 0,
        colorGradingCount: 0,
        hasLut: false,
        vfxHostCount: 0,
        vfxTypes: "",
      });
    });

    it("reports static provenance when page.evaluate throws (detached frame, mid-navigation)", async () => {
      const session = {
        isInitialized: true,
        page: {
          evaluate: async () => {
            throw new Error("Execution context was destroyed");
          },
        },
      };
      expect(await resolveCompositionElementCount(session, "<div><span></span></div>")).toEqual({
        count: 2,
        source: "static",
        byTag: { div: 1, span: 1 },
        arollVideoCount: 0,
        heygenVideoCount: 0,
        audioCount: 0,
        imageCount: 0,
        subCompositionCount: 0,
        audioGroupCount: 0,
        colorGradingCount: 0,
        hasLut: false,
        vfxHostCount: 0,
        vfxTypes: "",
      });
    });

    it("reports static provenance when evaluate resolves a non-finite value", async () => {
      const session = { isInitialized: true, page: { evaluate: async () => Number.NaN } };
      expect(await resolveCompositionElementCount(session, "<div></div>")).toEqual({
        count: 1,
        source: "static",
        byTag: { div: 1 },
        arollVideoCount: 0,
        heygenVideoCount: 0,
        audioCount: 0,
        imageCount: 0,
        subCompositionCount: 0,
        audioGroupCount: 0,
        colorGradingCount: 0,
        hasLut: false,
        vfxHostCount: 0,
        vfxTypes: "",
      });
    });

    it("omits byTag/arollVideoCount on the live path — that path never runs the static scan", async () => {
      const session = { isInitialized: true, page: { evaluate: async () => 40001 } };
      const result = await resolveCompositionElementCount(session, "<div><span></span></div>");
      expect(result).not.toHaveProperty("byTag");
      expect(result).not.toHaveProperty("arollVideoCount");
      expect(result).not.toHaveProperty("heygenVideoCount");
    });
  });

  describe("detectAdaptersStatic", () => {
    it("returns empty for a composition using no tracked adapter", () => {
      expect(detectAdaptersStatic("<div><span>hello</span></div>")).toEqual([]);
    });

    it("detects gsap from a timeline call, not a bare mention", () => {
      expect(detectAdaptersStatic("<script>const gsap = 1;</script>")).toEqual([]);
      expect(detectAdaptersStatic("<script>gsap.timeline().to('.a', {x:1});</script>")).toEqual([
        "gsap",
      ]);
    });

    it("detects the __hf<Name> registration token for each array-registered adapter", () => {
      expect(detectAdaptersStatic("<script>window.__hfLottie.push(anim);</script>")).toEqual([
        "lottie",
      ]);
      expect(detectAdaptersStatic("<script>window.__hfAnime.push(tl);</script>")).toEqual([
        "animejs",
      ]);
      expect(detectAdaptersStatic("<script>window.__hfD3 = [t];</script>")).toEqual(["d3"]);
      expect(detectAdaptersStatic("<script>window.__hfLeaflet.push(m);</script>")).toEqual([
        "leaflet",
      ]);
      expect(detectAdaptersStatic("<script>window.__hfMapbox.push(m);</script>")).toEqual([
        "mapbox",
      ]);
      expect(detectAdaptersStatic("<script>window.__hfMaplibre.push(m);</script>")).toEqual([
        "maplibre",
      ]);
      expect(detectAdaptersStatic("<script>window.__hfGoogleMaps.push(m);</script>")).toEqual([
        "google-maps",
      ]);
    });

    it("detects three from a THREE global reference", () => {
      expect(
        detectAdaptersStatic("<script>const mgr = THREE.DefaultLoadingManager;</script>"),
      ).toEqual(["three"]);
    });

    it("detects typegpu from the data-requires-webgpu authoring attribute", () => {
      expect(
        detectAdaptersStatic('<div data-composition-id="a" data-requires-webgpu></div>'),
      ).toEqual(["typegpu"]);
    });

    it("detects css from an authored @keyframes rule", () => {
      expect(detectAdaptersStatic("<style>@keyframes spin { to { opacity: 1; } }</style>")).toEqual(
        ["css"],
      );
    });

    it("detects waapi from an element.animate keyframe-array call", () => {
      expect(
        detectAdaptersStatic("<script>el.animate([{opacity:0},{opacity:1}], 500);</script>"),
      ).toEqual(["waapi"]);
    });

    it("reports multiple adapters in KNOWN_RUNTIME_ADAPTERS order, not detection order", () => {
      const html = "<script>gsap.timeline();window.__hfLottie.push(a);window.__hfD3=[t];</script>";
      expect(detectAdaptersStatic(html)).toEqual(["d3", "gsap", "lottie"]);
    });
  });

  describe("resolveAdaptersUsed", () => {
    it("falls back to the static scan when there is no probe session", async () => {
      const html = "<script>gsap.timeline();</script>";
      expect(await resolveAdaptersUsed(null, html)).toEqual(["gsap"]);
    });

    it("falls back to the static scan when the probe session is not yet initialized", async () => {
      const session = { isInitialized: false, page: { evaluate: async () => ["three"] } };
      const html = "<script>gsap.timeline();</script>";
      expect(await resolveAdaptersUsed(session, html)).toEqual(["gsap"]);
    });

    it("unions the live probe result with the static scan, deduped and canonically ordered", async () => {
      const session = { isInitialized: true, page: { evaluate: async () => ["three", "lottie"] } };
      const html = "<script>gsap.timeline();window.__hfLottie.push(a);</script>";
      expect(await resolveAdaptersUsed(session, html)).toEqual(["gsap", "lottie", "three"]);
    });

    it("falls back to the static scan when page.evaluate throws", async () => {
      const session = {
        isInitialized: true,
        page: {
          evaluate: async () => {
            throw new Error("Execution context was destroyed");
          },
        },
      };
      const html = "<script>gsap.timeline();</script>";
      expect(await resolveAdaptersUsed(session, html)).toEqual(["gsap"]);
    });

    it("ignores unknown values the live probe might return", async () => {
      const session = { isInitialized: true, page: { evaluate: async () => ["gsap", "bogus"] } };
      expect(await resolveAdaptersUsed(session, "<div></div>")).toEqual(["gsap"]);
    });

    it("reports an empty list, not absent, when nothing is detected", async () => {
      const session = { isInitialized: true, page: { evaluate: async () => [] } };
      expect(await resolveAdaptersUsed(session, "<div></div>")).toEqual([]);
    });
  });

  describe("envInt", () => {
    afterEach(() => {
      delete process.env.HF_TEST_ENV_INT;
    });

    it("falls back when unset, empty, or non-numeric — a typo must not disable a guard", () => {
      expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(2500);
      process.env.HF_TEST_ENV_INT = "";
      expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(2500);
      process.env.HF_TEST_ENV_INT = "lots";
      expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(2500);
    });

    it("reads an explicit value, including 0 as a real disable", () => {
      process.env.HF_TEST_ENV_INT = "700";
      expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(700);
      process.env.HF_TEST_ENV_INT = "0";
      expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(0);
    });
  });

  it("honors explicitly requested workers", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, requestedWorkers: 3 })).toBe(false);
  });

  it("inverts for requestedWorkers undefined — the value production actually passes for auto", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, requestedWorkers: undefined })).toBe(
      true,
    );
  });

  it("skips comps routed to layered/HDR/shader paths (drawElement never runs there)", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, layeredOrEffectRoute: true })).toBe(
      false,
    );
  });

  it("skips supersampled renders (engine init-time DE gate)", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, supersampling: true })).toBe(false);
  });

  it("skips when the probe session already shows DE gated out", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, probeDeGated: true })).toBe(false);
  });

  it("honors the explicit experimental parallel-DE opt-in", () => {
    expect(
      shouldPreferSingleWorkerDrawElement({ ...eligible, experimentalParallelDeOptIn: true }),
    ).toBe(false);
  });

  it("skips below the amortization threshold (measured crossover ~900 frames)", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, totalFrames: 360 })).toBe(false);
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, totalFrames: 900 })).toBe(true);
  });

  it("is disabled by minFrames <= 0 (HF_DE_SINGLE_MIN_FRAMES=0 kill switch)", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, minFrames: 0 })).toBe(false);
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, minFrames: -1 })).toBe(false);
  });

  it("requires drawElement to be enabled and ungated", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, useDrawElement: false })).toBe(false);
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, deCompileGate: "3d" })).toBe(false);
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, forceScreenshot: true })).toBe(false);
  });

  it("only applies to the benchmarked configuration (mp4 + streaming-eligible)", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, outputFormat: "webm" })).toBe(false);
    expect(
      shouldPreferSingleWorkerDrawElement({ ...eligible, singleWorkerStreamingOk: false }),
    ).toBe(false);
  });

  it("is a no-op when workers already resolved to 1", () => {
    expect(shouldPreferSingleWorkerDrawElement({ ...eligible, workerCount: 1 })).toBe(false);
  });
});

describe("resolveInversionRetryPlan (self-verify retry rollback)", () => {
  const cfg = { enableStreamingEncode: true, streamingEncodeMaxDurationSeconds: 240 };

  it("returns null when the render was never inverted", () => {
    expect(
      resolveInversionRetryPlan({
        deWorkerInversion: undefined,
        preInversionWorkerCount: 5,
        cfg,
        outputFormat: "mp4",
        durationSeconds: 80,
        isMemoryExhaustion: false,
      }),
    ).toBe(null);
    expect(
      resolveInversionRetryPlan({
        deWorkerInversion: "reverted",
        preInversionWorkerCount: 5,
        cfg,
        outputFormat: "mp4",
        durationSeconds: 80,
        isMemoryExhaustion: false,
      }),
    ).toBe(null);
  });

  it("restores the pre-inversion worker count and routes multi-worker retries to disk", () => {
    const plan = resolveInversionRetryPlan({
      deWorkerInversion: "inverted",
      preInversionWorkerCount: 5,
      cfg,
      outputFormat: "mp4",
      durationSeconds: 80,
      isMemoryExhaustion: false,
    });
    expect(plan).toEqual({
      workerCount: 5,
      // shouldUseStreamingEncode is workerCount===1-only — parallel retry
      // goes through the disk path.
      useStreamingEncode: false,
      deWorkerInversion: "reverted",
    });
  });

  it("keeps streaming when the pre-inversion resolution was already single-worker", () => {
    const plan = resolveInversionRetryPlan({
      deWorkerInversion: "inverted",
      preInversionWorkerCount: 1,
      cfg,
      outputFormat: "mp4",
      durationSeconds: 80,
      isMemoryExhaustion: false,
    });
    expect(plan).toEqual({
      workerCount: 1,
      useStreamingEncode: true,
      deWorkerInversion: "reverted",
    });
  });

  it("drops to a single worker on OOM regardless of the pre-inversion count (the actual memory remedy)", () => {
    const plan = resolveInversionRetryPlan({
      deWorkerInversion: "inverted",
      preInversionWorkerCount: 5,
      cfg,
      outputFormat: "mp4",
      durationSeconds: 80,
      isMemoryExhaustion: true,
    });
    expect(plan).toEqual({
      workerCount: 1,
      useStreamingEncode: true,
      deWorkerInversion: "reverted",
    });
  });
});

describe("isDeParallelRouterEnabled (kill switch parsing)", () => {
  it("defaults ON when unset or set-but-empty", () => {
    expect(isDeParallelRouterEnabled({})).toBe(true);
    expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "" })).toBe(true);
    expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "   " })).toBe(true);
  });

  it("honours every conventional spelling of off — an opt-out must never fail OPEN", () => {
    // A naive `!== "false"` would enable the router for all of these, handing
    // 3-worker parallel DE to a user who explicitly asked for none.
    for (const v of ["false", "FALSE", "False", "0", "off", "OFF", "no", "No", " false "]) {
      expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: v })).toBe(false);
    }
  });

  it("treats any other value as enabled", () => {
    expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "true" })).toBe(true);
    expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "1" })).toBe(true);
  });
});

describe("shouldPreferParallelDrawElement (DE parallel router)", () => {
  const eligible = {
    workerCount: 5,
    requestedWorkers: "auto" as const,
    useDrawElement: true,
    deCompileGate: undefined,
    forceScreenshot: false,
    outputFormat: "mp4" as const,
    totalFrames: 2381,
    minFrames: 2000,
    layeredOrEffectRoute: false,
    supersampling: false,
    probeDeGated: false,
    experimentalParallelDeOptIn: false,
    routerEnabled: true,
    parallelStreamingAvailable: true,
    totalMemoryMb: 32768,
    minMemoryMb: 24576,
  };

  it("routes an auto-resolved multi-worker render for an eligible long comp", () => {
    expect(shouldPreferParallelDrawElement(eligible)).toBe(true);
  });

  it("withholds the bet when parallel streaming can't run (e.g. over the duration cap)", () => {
    // The router pins workerCount to 3 and skips calibration to serve the
    // verified parallel DE STREAMING path. If streaming is off for this
    // render — the >240s duration cap is the common case — firing would pay
    // the whole cost of the pin for none of the benefit.
    expect(
      shouldPreferParallelDrawElement({ ...eligible, parallelStreamingAvailable: false }),
    ).toBe(false);
  });

  it("withholds the parallel bet below the RAM floor (16 GB black-slab report)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, totalMemoryMb: 16384 })).toBe(false);
  });

  it("routes exactly at the RAM floor", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, totalMemoryMb: 24576 })).toBe(true);
  });

  it("minMemoryMb <= 0 disables the RAM guard", () => {
    expect(
      shouldPreferParallelDrawElement({ ...eligible, totalMemoryMb: 8192, minMemoryMb: 0 }),
    ).toBe(true);
  });

  it("is disabled by default (routerEnabled: false is the shipped default)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, routerEnabled: false })).toBe(false);
  });

  it("honors explicitly requested workers", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, requestedWorkers: 3 })).toBe(false);
  });

  it("routes for requestedWorkers undefined — the value production actually passes for auto", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, requestedWorkers: undefined })).toBe(
      true,
    );
  });

  it("skips comps routed to layered/HDR/shader paths (drawElement never runs there)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, layeredOrEffectRoute: true })).toBe(
      false,
    );
  });

  it("skips supersampled renders (engine init-time DE gate)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, supersampling: true })).toBe(false);
  });

  it("skips when the probe session already shows DE gated out", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, probeDeGated: true })).toBe(false);
  });

  it("honors the explicit experimental parallel-DE opt-in (already parallel, router is a no-op)", () => {
    expect(
      shouldPreferParallelDrawElement({ ...eligible, experimentalParallelDeOptIn: true }),
    ).toBe(false);
  });

  it("skips below the amortization threshold (benchmark: real-work comps clear 1.25x at ~2,000+ frames)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, totalFrames: 915 })).toBe(false);
    expect(shouldPreferParallelDrawElement({ ...eligible, totalFrames: 2000 })).toBe(true);
  });

  it("is disabled by minFrames <= 0 (HF_DE_PARALLEL_MIN_FRAMES=0 kill switch)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, minFrames: 0 })).toBe(false);
    expect(shouldPreferParallelDrawElement({ ...eligible, minFrames: -1 })).toBe(false);
  });

  it("requires drawElement to be enabled and ungated", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, useDrawElement: false })).toBe(false);
    expect(shouldPreferParallelDrawElement({ ...eligible, deCompileGate: "3d" })).toBe(false);
    expect(shouldPreferParallelDrawElement({ ...eligible, forceScreenshot: true })).toBe(false);
  });

  it("only applies to mp4 (the benchmarked configuration)", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, outputFormat: "webm" })).toBe(false);
  });

  it("is a no-op when workers already resolved to 1", () => {
    expect(shouldPreferParallelDrawElement({ ...eligible, workerCount: 1 })).toBe(false);
  });
});

describe("resolveParallelRouterRetryPlan (self-verify retry rollback)", () => {
  const cfg = { enableStreamingEncode: true, streamingEncodeMaxDurationSeconds: 240 };

  it("returns null when the render was never router-routed", () => {
    expect(
      resolveParallelRouterRetryPlan({
        deParallelRouter: undefined,
        preRouterWorkerCount: 5,
        cfg,
        outputFormat: "mp4",
        durationSeconds: 80,
        isMemoryExhaustion: false,
      }),
    ).toBe(null);
    expect(
      resolveParallelRouterRetryPlan({
        deParallelRouter: "reverted",
        preRouterWorkerCount: 5,
        cfg,
        outputFormat: "mp4",
        durationSeconds: 80,
        isMemoryExhaustion: false,
      }),
    ).toBe(null);
  });

  it("restores the pre-router worker count and routes multi-worker retries to disk", () => {
    const plan = resolveParallelRouterRetryPlan({
      deParallelRouter: "routed",
      preRouterWorkerCount: 5,
      cfg,
      outputFormat: "mp4",
      durationSeconds: 80,
      isMemoryExhaustion: false,
    });
    expect(plan).toEqual({
      workerCount: 5,
      useStreamingEncode: false,
      deParallelRouter: "reverted",
    });
  });

  it("drops to a single worker on OOM regardless of the pre-router count (the actual memory remedy)", () => {
    const plan = resolveParallelRouterRetryPlan({
      deParallelRouter: "routed",
      preRouterWorkerCount: 5,
      cfg,
      outputFormat: "mp4",
      durationSeconds: 80,
      isMemoryExhaustion: true,
    });
    expect(plan).toEqual({
      workerCount: 1,
      useStreamingEncode: true,
      deParallelRouter: "reverted",
    });
  });
});

describe("shouldRetryViaPinnedFallback (widen the self-verify retry to generic capture failures, including OOM)", () => {
  it.each([
    [false, false, true],
    [true, false, false],
    [false, true, false],
  ])(
    "routes an untrusted drawElement page unless cancelled/interrupted",
    (isCancellation, isEncoderInterrupted, expected) => {
      expect(
        shouldRetryViaPinnedFallback({
          isVerifyError: false,
          isDeCaptureError: true,
          isCancellation,
          isEncoderInterrupted,
          deWorkerInversion: undefined,
          deParallelRouter: undefined,
        }),
      ).toBe(expected);
    },
  );

  // PRINFRA-488: a wedged renderer must be retryable on ANY routing. Before this,
  // a comp that engaged drawElement on the ordinary single-worker path had no
  // whole-render fallback, so one stalled frame failed the entire render.
  it("retries a drawElement renderer stall even with no pinned routing", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isDeRendererStall: true,
      }),
    ).toBe(true);
  });

  it("still does NOT retry a generic capture failure with no pinned routing", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isDeRendererStall: false,
      }),
    ).toBe(false);
  });

  it("never retries a cancellation, even for a renderer stall", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: true,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isDeRendererStall: true,
      }),
    ).toBe(false);
  });

  it("recognizes the engine's stall error across the package boundary", () => {
    const byName = new Error("whatever");
    byName.name = "DeFrameTimeoutError";
    expect(isDeRendererStallError(byName)).toBe(true);
    expect(
      isDeRendererStallError(
        new Error(
          "drawElement frame 50 exceeded 15000ms (renderer stopped scheduling; see PRINFRA-488)",
        ),
      ),
    ).toBe(true);
    expect(isDeRendererStallError(new Error("some other capture failure"))).toBe(false);
    expect(isDeRendererStallError("not an error")).toBe(false);
  });

  it("always retries a drawElement self-verify failure, pinned or not", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: true,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
      }),
    ).toBe(true);
  });

  it("retries a generic capture failure when the router pinned the worker count", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: "routed",
      }),
    ).toBe(true);
  });

  it("retries a generic capture failure when the inversion pinned the worker count", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: "inverted",
        deParallelRouter: undefined,
      }),
    ).toBe(true);
  });

  it("does not retry a generic capture failure when nothing pinned the worker count", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
      }),
    ).toBe(false);
  });

  it("retries OOM too when the router pinned the worker count (fallback's Chrome processes are already dead by the time this runs, and the fallback is pooled/lighter than the pinned path)", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: "routed",
      }),
    ).toBe(true);
  });

  it("retries OOM too when the inversion pinned the worker count", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: "inverted",
        deParallelRouter: undefined,
      }),
    ).toBe(true);
  });

  it("does not retry a generic failure on an already-reverted cohort (no pin left to retreat from)", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: "reverted",
        deParallelRouter: undefined,
      }),
    ).toBe(false);
  });

  it("never retries a cancellation, even on a pinned cohort — must propagate immediately, not detour through a fresh encoder spin-up", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: true,
        deWorkerInversion: "inverted",
        deParallelRouter: undefined,
      }),
    ).toBe(false);
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: true,
        deWorkerInversion: undefined,
        deParallelRouter: "routed",
      }),
    ).toBe(false);
  });

  it("cancellation wins even if the error also looks like a self-verify failure", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: true,
        isCancellation: true,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
      }),
    ).toBe(false);
  });

  it("never hides an encoder host interruption behind the same-host pinned fallback", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        isEncoderInterrupted: true,
        deWorkerInversion: "inverted",
        deParallelRouter: undefined,
      }),
    ).toBe(false);
  });

  // --low-memory-mode is single-worker with no drawElement, so nothing ever
  // pins a count and that mode had no whole-render fallback at all.
  it("retries a transient capture-call refusal even with no pinned routing", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isTransientCaptureError: true,
      }),
    ).toBe(true);
  });

  it("never retries a transient capture-call refusal after cancellation", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: true,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isTransientCaptureError: true,
      }),
    ).toBe(false);
  });
});

describe("sequential capture stall recovery", () => {
  it("retries a typed stall on an explicit unpinned one-worker route", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        isEncoderInterrupted: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isDeRendererStall: true,
      }),
    ).toBe(true);
  });

  it("retries a typed screenshot stall on an unpinned low-memory route", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: false,
        isEncoderInterrupted: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isSequentialCaptureStall: true,
      }),
    ).toBe(true);
  });

  it("does not retry a screenshot stall after parent cancellation", () => {
    expect(
      shouldRetryViaPinnedFallback({
        isVerifyError: false,
        isCancellation: true,
        isEncoderInterrupted: false,
        deWorkerInversion: undefined,
        deParallelRouter: undefined,
        isSequentialCaptureStall: true,
      }),
    ).toBe(false);
  });

  it("recognizes a wrapped screenshot watchdog error across the stage boundary", () => {
    expect(
      isSequentialCaptureStallError(
        new Error(
          "[Render] Sequential screenshot capture stalled: no frame progress for 60000ms (stuck at frame 99/135).",
        ),
      ),
    ).toBe(true);
    expect(isSequentialCaptureStallError(new Error("ordinary screenshot failure"))).toBe(false);
  });
});

describe("resolveParallelCaptureMode", () => {
  const beginframe = {
    platform: "linux" as NodeJS.Platform,
    headlessShellPath: "/cache/chrome-headless-shell" as string | undefined,
    forceScreenshot: false,
    deviceScaleFactor: 1,
  };

  it("reports beginframe only for linux headless-shell at DPR 1 without forceScreenshot", () => {
    expect(resolveParallelCaptureMode(beginframe)).toBe("beginframe");
  });

  it("reports screenshot wherever the engine's preMode would", () => {
    expect(resolveParallelCaptureMode({ ...beginframe, platform: "darwin" })).toBe("screenshot");
    expect(resolveParallelCaptureMode({ ...beginframe, platform: "win32" })).toBe("screenshot");
    // System Chrome on linux: resolveObservedCaptureMode calls this beginframe,
    // the engine launches screenshot. Getting this wrong would default-enable
    // the router for a cohort whose real path is the screenshot one.
    expect(resolveParallelCaptureMode({ ...beginframe, headlessShellPath: undefined })).toBe(
      "screenshot",
    );
    expect(resolveParallelCaptureMode({ ...beginframe, forceScreenshot: true })).toBe("screenshot");
    // Supersampling: BeginFrame ignores deviceScaleFactor, so preMode falls back.
    expect(resolveParallelCaptureMode({ ...beginframe, deviceScaleFactor: 2 })).toBe("screenshot");
  });

  it("treats an unset deviceScaleFactor as 1", () => {
    expect(resolveParallelCaptureMode({ ...beginframe, deviceScaleFactor: undefined })).toBe(
      "beginframe",
    );
  });
});

describe("shouldSegmentCapture", () => {
  const base = {
    env: {} as Record<string, string | undefined>,
    durationSeconds: 900,
    outputFormat: "mp4",
    layeredOrEffectRoute: false,
    streamingOk: true,
  };

  it("does not route on duration until the soak flip", () => {
    // The threshold ships disabled: the release that introduces the route
    // must not also change which route every long render takes.
    expect(shouldSegmentCapture(base)).toBe(false);
    expect(shouldSegmentCapture({ ...base, durationSeconds: 36_000 })).toBe(false);
  });

  it("routes long mp4/mov renders once a threshold is set", () => {
    const env = { HF_SEGMENTED_MIN_SECONDS: String(SEGMENTED_MIN_SECONDS_AFTER_SOAK) };
    expect(shouldSegmentCapture({ ...base, env })).toBe(true);
    expect(shouldSegmentCapture({ ...base, env, outputFormat: "mov" })).toBe(true);
    expect(shouldSegmentCapture({ ...base, env, durationSeconds: 599 })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env, durationSeconds: 600 })).toBe(true);
  });

  it("is forced at any duration by the explicit opt-in", () => {
    expect(
      shouldSegmentCapture({
        ...base,
        durationSeconds: 5,
        env: { HF_SEGMENTED_CAPTURE: "true" },
      }),
    ).toBe(true);
  });

  it("honours the kill switch and the exclusions", () => {
    const env = { HF_SEGMENTED_MIN_SECONDS: "60" };
    expect(shouldSegmentCapture({ ...base, env: { ...env, HF_SEGMENTED_CAPTURE: "false" } })).toBe(
      false,
    );
    // The kill switch beats the force flag's other spellings too.
    expect(shouldSegmentCapture({ ...base, env: { HF_SEGMENTED_CAPTURE: "off" } })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env, outputFormat: "webm" })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env, outputFormat: "png-sequence" })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env, outputFormat: "hls" })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env, layeredOrEffectRoute: true })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env, streamingOk: false })).toBe(false);
    // Even the explicit force cannot route an excluded output.
    expect(
      shouldSegmentCapture({
        ...base,
        env: { HF_SEGMENTED_CAPTURE: "true" },
        outputFormat: "webm",
      }),
    ).toBe(false);
  });

  it("ignores an unparseable threshold rather than routing on it", () => {
    expect(shouldSegmentCapture({ ...base, env: { HF_SEGMENTED_MIN_SECONDS: "soon" } })).toBe(
      false,
    );
    expect(shouldSegmentCapture({ ...base, env: { HF_SEGMENTED_MIN_SECONDS: "-5" } })).toBe(false);
    expect(shouldSegmentCapture({ ...base, env: { HF_SEGMENTED_MIN_SECONDS: "0" } })).toBe(true);
  });
});

describe("isCaptureParallelStreamRouterEnabled", () => {
  it("is on by default only where capture will run BeginFrame", () => {
    expect(isCaptureParallelStreamRouterEnabled({}, "beginframe")).toBe(true);
    // macOS/Windows screenshot capture stays opt-in: its opt-in cohort runs a
    // 5.5% error rate against a ~1.1% baseline (stall watchdog / EPIPE class).
    expect(isCaptureParallelStreamRouterEnabled({}, "screenshot")).toBe(false);
    expect(
      isCaptureParallelStreamRouterEnabled({ HF_CAPTURE_PARALLEL_STREAM: "" }, "screenshot"),
    ).toBe(false);
  });

  it("honours the explicit opt-in for either mode", () => {
    expect(
      isCaptureParallelStreamRouterEnabled({ HF_CAPTURE_PARALLEL_STREAM: "true" }, "screenshot"),
    ).toBe(true);
    expect(
      isCaptureParallelStreamRouterEnabled({ HF_CAPTURE_PARALLEL_STREAM: " TRUE " }, "screenshot"),
    ).toBe(true);
  });

  it("honours the kill switch, using the same off-spellings as the DE router", () => {
    for (const off of ["false", "FALSE", "0", "off", "no"]) {
      expect(
        isCaptureParallelStreamRouterEnabled({ HF_CAPTURE_PARALLEL_STREAM: off }, "beginframe"),
      ).toBe(false);
    }
  });
});

describe("shouldStreamParallelCapture (non-DE parallel streaming router)", () => {
  const eligible = {
    routerEnabled: true,
    workerCount: 3,
    useDrawElement: false,
    outputFormat: "mp4" as const,
    streamingOk: true,
    layeredOrEffectRoute: false,
  };

  it("routes an eligible multi-worker non-drawElement render", () => {
    expect(shouldStreamParallelCapture(eligible)).toBe(true);
  });

  it("honours the kill switch when the caller passes routerEnabled=false", () => {
    expect(shouldStreamParallelCapture({ ...eligible, routerEnabled: false })).toBe(false);
  });

  it("never fires for single-worker renders (those already stream)", () => {
    expect(shouldStreamParallelCapture({ ...eligible, workerCount: 1 })).toBe(false);
  });

  it("never fires when drawElement will capture (the DE routers own that path)", () => {
    expect(shouldStreamParallelCapture({ ...eligible, useDrawElement: true })).toBe(false);
  });

  it("only applies to mp4", () => {
    expect(shouldStreamParallelCapture({ ...eligible, outputFormat: "webm" })).toBe(false);
    expect(shouldStreamParallelCapture({ ...eligible, outputFormat: "png-sequence" })).toBe(false);
  });

  it("respects the streaming-encode config/duration gates", () => {
    expect(shouldStreamParallelCapture({ ...eligible, streamingOk: false })).toBe(false);
  });

  it("skips HDR-layered and shader-transition routes", () => {
    expect(shouldStreamParallelCapture({ ...eligible, layeredOrEffectRoute: true })).toBe(false);
  });
});

describe("shouldClampDefaultDrawElement (default-on drawElement clamp)", () => {
  const unverifiedParallel = {
    useDrawElement: true,
    fastCaptureExplicitOptIn: false,
    useStreamingEncode: false,
    workerCount: 2,
    deParallelStreamVerified: false,
  };

  it("clamps default-on drawElement for unverified multi-worker capture", () => {
    expect(shouldClampDefaultDrawElement(unverifiedParallel)).toBe(true);
  });

  it("leaves useDrawElement alone once it is already false", () => {
    expect(shouldClampDefaultDrawElement({ ...unverifiedParallel, useDrawElement: false })).toBe(
      false,
    );
  });

  it("an explicit opt-in overrides the clamp", () => {
    expect(
      shouldClampDefaultDrawElement({ ...unverifiedParallel, fastCaptureExplicitOptIn: true }),
    ).toBe(false);
  });

  it("does not clamp a verified multi-worker streaming render", () => {
    expect(
      shouldClampDefaultDrawElement({ ...unverifiedParallel, deParallelStreamVerified: true }),
    ).toBe(false);
  });

  it("clamps a single-worker render with streaming off (the disk-path case)", () => {
    expect(shouldClampDefaultDrawElement({ ...unverifiedParallel, workerCount: 1 })).toBe(true);
  });

  it("leaves a single-worker streaming render unclamped (self-verified by the drain)", () => {
    expect(
      shouldClampDefaultDrawElement({
        ...unverifiedParallel,
        workerCount: 1,
        useStreamingEncode: true,
      }),
    ).toBe(false);
  });
});

describe("default-on drawElement clamp feeds the non-DE parallel-stream router", () => {
  // The router requires the drawElement clamp's OUTPUT, not its input. Both
  // predicates below are individually correct; a caller wiring them together
  // in the wrong order still reproduces the bug these two tests bound.
  const macOsDefaultOnMultiWorker = {
    useDrawElement: true,
    fastCaptureExplicitOptIn: false,
    useStreamingEncode: false,
    workerCount: 2,
    deParallelStreamVerified: false,
  };

  it("routes once the clamp's post-clamp value feeds the router", () => {
    const clamped = shouldClampDefaultDrawElement(macOsDefaultOnMultiWorker);
    const postClampUseDrawElement = clamped ? false : macOsDefaultOnMultiWorker.useDrawElement;

    expect(
      shouldStreamParallelCapture({
        routerEnabled: true,
        workerCount: macOsDefaultOnMultiWorker.workerCount,
        useDrawElement: postClampUseDrawElement,
        outputFormat: "mp4",
        streamingOk: true,
        layeredOrEffectRoute: false,
      }),
    ).toBe(true);
  });

  it("never routes if the router instead reads the PRE-clamp value (the bug)", () => {
    expect(
      shouldStreamParallelCapture({
        routerEnabled: true,
        workerCount: macOsDefaultOnMultiWorker.workerCount,
        useDrawElement: macOsDefaultOnMultiWorker.useDrawElement,
        outputFormat: "mp4",
        streamingOk: true,
        layeredOrEffectRoute: false,
      }),
    ).toBe(false);
  });
});

describe("closeOrphanedProbeForRetry (probe cleanup before verify-triggered retry)", () => {
  // Enough of a CaptureSession stand-in to exercise the closer path — the
  // helper never inspects the object; it just hands it to the injected closer.
  const stubSession = { browserConsoleBuffer: [] } as unknown as Parameters<
    typeof closeOrphanedProbeForRetry
  >[0];

  it("hands the still-owned probe to the closer before the caller clears it", async () => {
    const closer = vi.fn(async () => {});
    const log = { warn: vi.fn() };

    await closeOrphanedProbeForRetry(stubSession, closer, log, "streaming");

    expect(closer).toHaveBeenCalledTimes(1);
    expect(closer).toHaveBeenCalledWith(stubSession);
    expect(log.warn).not.toHaveBeenCalled();
  });

  it("swallows a close failure with a warn so the caller's retry can proceed", async () => {
    const closer = vi.fn(async () => {
      throw new Error("chrome zombie");
    });
    const log = { warn: vi.fn() };

    await expect(
      closeOrphanedProbeForRetry(stubSession, closer, log, "disk verify"),
    ).resolves.toBeUndefined();

    expect(closer).toHaveBeenCalledTimes(1);
    expect(log.warn).toHaveBeenCalledTimes(1);
    const [message, meta] = log.warn.mock.calls[0];
    expect(message).toContain("disk verify");
    expect((meta as { error: string }).error).toBe("chrome zombie");
  });

  it("preserves the retry context in the warn message so the audit trail names which retry path leaked", async () => {
    const closer = vi.fn(async () => {
      throw new Error("session already closed");
    });
    const log = { warn: vi.fn() };

    await closeOrphanedProbeForRetry(stubSession, closer, log, "streaming");

    expect(log.warn.mock.calls[0][0]).toContain("streaming");
    expect(log.warn.mock.calls[0][0]).not.toContain("disk verify");
  });

  it("stringifies non-Error rejections so the log entry still names the cause", async () => {
    const closer = vi.fn(async () => Promise.reject("string-only rejection"));
    const log = { warn: vi.fn() };

    await closeOrphanedProbeForRetry(stubSession, closer, log, "streaming");

    expect(log.warn).toHaveBeenCalledTimes(1);
    expect((log.warn.mock.calls[0][1] as { error: string }).error).toBe("string-only rejection");
  });
});

// BeginFrame is Linux-only in both real entry points, but the observability
// field derived its mode from `forceScreenshot` alone. That mislabelled 30,625
// Windows renders as `beginframe` over 14 days — a fifth of the fast-capture
// dashboard's capture-mode data — for captures that were really screenshot.
describe("resolveObservedCaptureMode", () => {
  it("only ever reports beginframe on linux", () => {
    expect(resolveObservedCaptureMode(false, "linux")).toBe("beginframe");
    expect(resolveObservedCaptureMode(false, "win32")).toBe("screenshot");
    expect(resolveObservedCaptureMode(false, "darwin")).toBe("screenshot");
  });

  // The case the old code got right, kept so a future simplification back to
  // a bare boolean fails here rather than in production telemetry.
  it("reports screenshot whenever screenshot was forced, linux included", () => {
    expect(resolveObservedCaptureMode(true, "linux")).toBe("screenshot");
    expect(resolveObservedCaptureMode(true, "win32")).toBe("screenshot");
  });
});

// The blocker found in review: seeding `captureMode` at construction is not
// enough. `updateCaptureObservability` fires at 23 sites, and the post-compile
// `{ forceScreenshot }` patch runs on EVERY render — the old closure re-derived
// from `forceScreenshot` alone and put `beginframe` back before capture began,
// so both telemetry emits read the reverted value. These go through the closure
// rather than the helper, which is the only way to catch that.
describe("createCaptureObservabilityUpdater", () => {
  const seed = (platform: NodeJS.Platform, forceScreenshot: boolean) => {
    const observability = {
      forceScreenshot,
      captureMode: resolveObservedCaptureMode(forceScreenshot, platform),
      browserGpuMode: "hardware" as const,
    } as Parameters<typeof createCaptureObservabilityUpdater>[0];
    return { observability, update: createCaptureObservabilityUpdater(observability, platform) };
  };

  // The exact production case: Windows, hardware GPU, screenshot not forced.
  it("keeps screenshot on win32 across an unrelated patch", () => {
    const { observability, update } = seed("win32", false);
    expect(observability.captureMode).toBe("screenshot");
    update({ transientRetries: 1 });
    expect(observability.captureMode).toBe("screenshot");
  });

  // The unconditional post-compile patch — the one that guaranteed the revert.
  it("keeps screenshot on win32 when forceScreenshot is re-patched false", () => {
    const { observability, update } = seed("win32", false);
    update({ forceScreenshot: false });
    expect(observability.captureMode).toBe("screenshot");
  });

  // Linux must still be able to report beginframe, or the fix would have
  // silently disabled the field everywhere instead of correcting it.
  it("still reports beginframe on linux, and honours a later force", () => {
    const { observability, update } = seed("linux", false);
    expect(observability.captureMode).toBe("beginframe");
    update({ transientRetries: 2 });
    expect(observability.captureMode).toBe("beginframe");
    update({ forceScreenshot: true });
    expect(observability.captureMode).toBe("screenshot");
  });

  it("applies the patch itself, not only the derived mode", () => {
    const { observability, update } = seed("win32", false);
    update({ workerCount: 4 });
    expect(observability.workerCount).toBe(4);
  });
});

describe("parallel stall and encoder death: retry eligibility on default routing", () => {
  it("recognises the parallel stall by name or by message", () => {
    const named = Object.assign(new Error("anything"), { name: "ParallelCaptureStallError" });
    expect(isParallelCaptureStallError(named)).toBe(true);
    expect(
      isParallelCaptureStallError(
        new Error(
          "[Render] Parallel screenshot capture stalled: no frame progress for 60000ms (stuck at 0/9000).",
        ),
      ),
    ).toBe(true);
    expect(
      isParallelCaptureStallError(
        new Error(
          "[Render] Parallel BeginFrame capture stalled after 60000ms with no frame progress",
        ),
      ),
    ).toBe(true);
    // The sequential stall has its own predicate and its own fallback shape.
    expect(
      isParallelCaptureStallError(
        new Error("[Render] Sequential screenshot capture stalled: no frame progress for 60000ms"),
      ),
    ).toBe(false);
    expect(isParallelCaptureStallError("[Render] Parallel screenshot capture stalled")).toBe(false);
  });

  it("retries an encoder death only once frames had started, and never a host interruption", () => {
    const died = (frame: number) =>
      new Error(
        `Streaming encoder exited before frame ${frame} was written: FFmpeg exited with code 1`,
      );
    // Frames 0 and 1: the encoder rejected its own arguments or first input.
    // That reproduces on a fresh ffmpeg, so a retry only doubles the time.
    expect(isRetryableEncoderDeath(died(0))).toBe(false);
    expect(isRetryableEncoderDeath(died(1))).toBe(false);
    expect(isRetryableEncoderDeath(died(2))).toBe(true);
    expect(isRetryableEncoderDeath(died(4831))).toBe(true);
    // Same prefix, but typed as a host lifecycle interruption: the producer
    // that owns this render retries that, not the capture stage.
    expect(
      isRetryableEncoderDeath(
        new EncoderInterruptedError("Streaming encoder exited before frame 4831 was written", "x"),
      ),
    ).toBe(false);
    expect(isRetryableEncoderDeath(new Error("Segment 3 encode failed: boom"))).toBe(false);
    expect(isRetryableEncoderDeath("Streaming encoder exited before frame 9 was written")).toBe(
      false,
    );
  });

  it("routes both through the pinned fallback with no pinned routing", () => {
    const base = {
      isVerifyError: false,
      isCancellation: false,
      deWorkerInversion: undefined,
      deParallelRouter: undefined,
    };
    // Default routing alone retries nothing…
    expect(shouldRetryViaPinnedFallback(base)).toBe(false);
    // …so each of these has to be its own gate, like the sequential stall.
    expect(shouldRetryViaPinnedFallback({ ...base, isParallelCaptureStall: true })).toBe(true);
    expect(shouldRetryViaPinnedFallback({ ...base, isEncoderDeath: true })).toBe(true);
    // Cancellation and host interruption still win.
    expect(
      shouldRetryViaPinnedFallback({ ...base, isParallelCaptureStall: true, isCancellation: true }),
    ).toBe(false);
    expect(
      shouldRetryViaPinnedFallback({ ...base, isEncoderDeath: true, isEncoderInterrupted: true }),
    ).toBe(false);
  });
});

describe("fallbackCaptureModeLabel: trace label when no probe session is open", () => {
  it("labels a non-Linux multi-worker render screenshot, not beginframe", () => {
    expect(
      fallbackCaptureModeLabel({
        forceScreenshot: false,
        useDrawElement: false,
        platform: "darwin",
      }),
    ).toBe("screenshot");
    expect(
      fallbackCaptureModeLabel({
        forceScreenshot: false,
        useDrawElement: false,
        platform: "win32",
      }),
    ).toBe("screenshot");
  });

  it("keeps beginframe for Linux and honours forced screenshot and drawElement", () => {
    expect(
      fallbackCaptureModeLabel({
        forceScreenshot: false,
        useDrawElement: false,
        platform: "linux",
      }),
    ).toBe("beginframe");
    expect(
      fallbackCaptureModeLabel({ forceScreenshot: true, useDrawElement: true, platform: "linux" }),
    ).toBe("screenshot");
    expect(
      fallbackCaptureModeLabel({
        forceScreenshot: false,
        useDrawElement: true,
        platform: "darwin",
      }),
    ).toBe("drawelement");
  });
});

describe("isParallelStreamForced: the plan carries the manual interleave opt-in", () => {
  const flagsOff = { deParallelStreamForced: false, captureParallelStreamForced: false };

  it("folds HF_DE_PARALLEL_STREAM=true into the plan flag so the retry drops to one worker", () => {
    expect(isParallelStreamForced({ HF_DE_PARALLEL_STREAM: "true" }, flagsOff)).toBe(true);
  });

  it("otherwise follows the two routers' flags", () => {
    expect(isParallelStreamForced({}, flagsOff)).toBe(false);
    expect(isParallelStreamForced({ HF_DE_PARALLEL_STREAM: "false" }, flagsOff)).toBe(false);
    expect(isParallelStreamForced({}, { ...flagsOff, deParallelStreamForced: true })).toBe(true);
    expect(isParallelStreamForced({}, { ...flagsOff, captureParallelStreamForced: true })).toBe(
      true,
    );
  });
});

describe("applyRenderWarningPolicy", () => {
  it("fails a best-effort render whose VFX chain failed, since its layer renders without the effect", () => {
    const job = createRenderJob({ fps: 30, quality: "standard" });
    const vfx = {
      code: "vfx_failure" as const,
      message: "A VFX chain failed",
      details: { sources: ["runtime-error:vfx: #host: unknown effect"] },
    };
    expect(() => applyRenderWarningPolicy(job, [vfx])).toThrow(RenderQualityError);
  });
});