Skip to content

Write HTML. Render video. Built for agents.

76.2 KB
Raw Blame
// fallow-ignore-file code-duplication
import { EventEmitter } from "events";
import { spawnSync } from "child_process";
import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
import { tmpdir } from "os";
import { basename, resolve } from "path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { extractMediaMetadata, extractPngMetadataFromBuffer, parseFrameRate } from "./ffprobe.js";

function crc32(buf: Buffer): number {
  let crc = 0xffffffff;
  for (let i = 0; i < buf.length; i++) {
    crc ^= buf[i] ?? 0;
    for (let bit = 0; bit < 8; bit++) {
      const mask = -(crc & 1);
      crc = (crc >>> 1) ^ (0xedb88320 & mask);
    }
  }
  return (crc ^ 0xffffffff) >>> 0;
}

function pngChunk(type: string, data: number[]): Buffer {
  const chunkData = Buffer.from(data);
  const header = Buffer.alloc(8);
  header.writeUInt32BE(chunkData.length, 0);
  header.write(type, 4, 4, "ascii");
  const crc = Buffer.alloc(4);
  crc.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, "ascii"), chunkData])), 0);
  return Buffer.concat([header, chunkData, crc]);
}

function buildPngWithChunks(chunks: Buffer[]): Buffer {
  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), ...chunks]);
}

function buildMinimalPng(options?: {
  cIcpAfterIdat?: boolean;
  invalidCrc?: boolean;
  longCicp?: boolean;
}) {
  const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
  const cicpData = options?.longCicp ? [9, 16, 0, 1, 255] : [9, 16, 0, 1];
  let cicp = pngChunk("cICP", cicpData);
  if (options?.invalidCrc) {
    cicp = Buffer.from(cicp);
    cicp[cicp.length - 1] ^= 0xff;
  }
  const idat = pngChunk(
    "IDAT",
    [0x78, 0x9c, 0x63, 0x60, 0x60, 0x60, 0x00, 0x00, 0x00, 0x04, 0x00, 0x01],
  );
  const iend = pngChunk("IEND", []);
  return options?.cIcpAfterIdat
    ? buildPngWithChunks([ihdr, idat, cicp, iend])
    : buildPngWithChunks([ihdr, cicp, idat, iend]);
}

describe("extractMediaMetadata", () => {
  it("reads HDR PNG cICP metadata when ffprobe color fields are absent", async () => {
    const fixturePath = resolve(
      __dirname,
      "../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
    );

    const metadata = await extractMediaMetadata(fixturePath);

    expect(metadata.colorSpace).toEqual({
      colorPrimaries: "bt2020",
      colorTransfer: "smpte2084",
      colorSpace: "gbr",
    });
  });
});

describe("extractMediaMetadata nb_frames duration cross-check", () => {
  afterEach(() => {
    vi.resetModules();
  });

  it("never reads a non-PNG video's bytes looking for PNG colour metadata", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 16,
              height: 16,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
            },
          ],
          format: { duration: "1" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
    // Bytes that carry PNG cICP, reported by ffprobe as an untagged H.264 stream.
    const dir = mkdtempSync(`${tmpdir()}/hf-not-png-`);
    const path = `${dir}/clip.mp4`;
    writeFileSync(path, buildMinimalPng());
    const meta = await mocked(path);
    rmSync(dir, { recursive: true, force: true });
    expect(meta.colorSpace).toBeNull();
  });

  it("uses nb_frames to bound video duration when stream duration is absent and audio is longer", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 1920,
              height: 1080,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
              nb_frames: "150",
            },
            { codec_type: "audio", codec_name: "aac" },
          ],
          format: { duration: "10" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
    const meta = await mocked("/tmp/stock-clip-long-audio.mp4");

    expect(meta.durationSeconds).toBe(10);
    expect(meta.videoStreamDurationSeconds).toBe(5);
    expect(meta.frames).toBe(150);
  });

  it("falls back to container duration when nb_frames is absent", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 1280,
              height: 720,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
            },
            { codec_type: "audio", codec_name: "aac" },
          ],
          format: { duration: "10" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
    const meta = await mocked("/tmp/no-nb-frames.mp4");

    expect(meta.videoStreamDurationSeconds).toBe(10);
    expect(meta.frames).toBeUndefined();
  });

  it("keeps container duration when nb_frames-derived duration is within 10%", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 1280,
              height: 720,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
              nb_frames: "285",
            },
          ],
          format: { duration: "10" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
    const meta = await mocked("/tmp/close-duration.mp4");

    // 285 / 30 = 9.5s, within 10% of container (10s), so keep container
    expect(meta.videoStreamDurationSeconds).toBe(10);
  });

  it("prefers stream duration over nb_frames when both are present", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 1280,
              height: 720,
              duration: "5",
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
              nb_frames: "300",
            },
          ],
          format: { duration: "10" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
    const meta = await mocked("/tmp/stream-duration-present.mp4");

    // stream duration (5s) takes precedence, nb_frames (300 / 30 = 10s) ignored
    expect(meta.videoStreamDurationSeconds).toBe(5);
  });
});

describe("extractPngMetadataFromBuffer", () => {
  it("accepts a valid cICP chunk before IDAT", () => {
    const metadata = extractPngMetadataFromBuffer(buildMinimalPng());
    expect(metadata?.colorSpace).toEqual({
      colorPrimaries: "bt2020",
      colorTransfer: "smpte2084",
      colorSpace: "gbr",
    });
  });

  it("rejects cICP chunks after IDAT", () => {
    const metadata = extractPngMetadataFromBuffer(buildMinimalPng({ cIcpAfterIdat: true }));
    expect(metadata).toEqual({
      width: 1,
      height: 1,
      colorSpace: null,
    });
  });

  it("rejects cICP chunks with invalid CRC", () => {
    expect(extractPngMetadataFromBuffer(buildMinimalPng({ invalidCrc: true }))).toBeNull();
  });

  it("rejects cICP chunks whose payload is not exactly four bytes", () => {
    const metadata = extractPngMetadataFromBuffer(buildMinimalPng({ longCicp: true }));
    expect(metadata).toEqual({
      width: 1,
      height: 1,
      colorSpace: null,
    });
  });

  it("continues to parse the checked-in HDR PNG fixture", () => {
    const fixture = readFileSync(
      resolve(__dirname, "../../../producer/tests/hdr-regression/src/hdr-photo-pq.png"),
    );
    expect(extractPngMetadataFromBuffer(fixture)?.colorSpace?.colorTransfer).toBe("smpte2084");
  });

  it("keeps metadata fallback independent from full PNG integrity validation", () => {
    const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
    expect(extractPngMetadataFromBuffer(buildPngWithChunks([ihdr]))).toMatchObject({
      width: 1,
      height: 1,
    });
  });
});

describe("probeMediaProfile", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
  });

  it("classifies still, moving, audio-only, and mixed streams from probe data", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "video", codec_name: "png" }],
          format: { format_name: "png_pipe" },
        }),
      },
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "video", codec_name: "h264" }],
          format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
        }),
      },
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "audio", codec_name: "mp3" }],
          format: { format_name: "mp3" },
        }),
      },
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "video" }, { codec_type: "audio" }],
          format: { format_name: "matroska,webm" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");

    const validPngPath = resolve(
      __dirname,
      "../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
    );
    await expect(probeMediaProfile(validPngPath)).resolves.toEqual({
      hasVideoStream: true,
      hasAudioStream: false,
      visualKind: "still",
    });
    await expect(probeMediaProfile("/tmp/extensionless-video")).resolves.toEqual({
      hasVideoStream: true,
      hasAudioStream: false,
      visualKind: "moving",
    });
    await expect(probeMediaProfile("/tmp/extensionless-audio")).resolves.toEqual({
      hasVideoStream: false,
      hasAudioStream: true,
      visualKind: "none",
    });
    await expect(probeMediaProfile("/tmp/mixed-av")).resolves.toEqual({
      hasVideoStream: true,
      hasAudioStream: true,
      visualKind: "moving",
    });
  });

  it("does not treat attached cover art in an audio container as an image asset", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            { codec_type: "video", disposition: { attached_pic: 1 } },
            { codec_type: "audio" },
          ],
          format: { format_name: "mp3" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");
    await expect(probeMediaProfile("/tmp/audio-with-cover")).resolves.toMatchObject({
      hasAudioStream: true,
      visualKind: "none",
    });
  });

  it("deduplicates probes within one cancellation scope without sharing across scopes", async () => {
    const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-media-probe-cache-"));
    const fixturePath = resolve(fixtureDir, "asset");
    writeFileSync(fixturePath, "cache identity only");
    const outcome = {
      kind: "exit" as const,
      code: 0,
      stdout: JSON.stringify({
        streams: [{ codec_type: "video", codec_name: "h264" }],
        format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
      }),
    };
    const { spawn, calls } = createSpawnSpy([outcome, outcome]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");
    const firstSignal = new AbortController().signal;
    const secondSignal = new AbortController().signal;
    try {
      await Promise.all([
        probeMediaProfile(fixturePath, { signal: firstSignal }),
        probeMediaProfile(fixturePath, { signal: firstSignal }),
      ]);
      expect(calls).toHaveLength(1);
      await probeMediaProfile(fixturePath, { signal: secondSignal });
      expect(calls).toHaveLength(2);
    } finally {
      rmSync(fixtureDir, { recursive: true, force: true });
    }
  });

  it("bounds the process-scoped probe cache", async () => {
    // Cache identity is derived from stat, so synthesise it instead of writing
    // 129 real files: the eviction rule is in-memory, and on a contended
    // Windows runner the file churn alone pushed this past the test timeout.
    const paths = Array.from({ length: 129 }, (_, index) => `/probe-lru/asset-${index}`);
    const outcome = {
      kind: "exit" as const,
      code: 0,
      stdout: JSON.stringify({
        streams: [{ codec_type: "audio", codec_name: "aac" }],
        format: { format_name: "aac" },
      }),
    };
    const { spawn, calls } = createSpawnSpy([outcome]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    vi.doMock("fs", async () => {
      const actual = await vi.importActual<typeof import("fs")>("fs");
      const statSync = (filePath: string) => ({
        dev: 1n,
        ino: BigInt(paths.indexOf(filePath)),
        size: 1n,
        mtimeNs: 0n,
        ctimeNs: 0n,
      });
      return { ...actual, statSync };
    });
    try {
      const { probeMediaProfile } = await import("./ffprobe.js");
      const [first, second, ...rest] = paths;
      for (const filePath of paths.slice(0, 128)) await probeMediaProfile(filePath);
      // A hit refreshes the entry, so the 129th insert evicts `second`, not `first`.
      await probeMediaProfile(first!);
      await probeMediaProfile(rest.at(-1)!);
      expect(calls).toHaveLength(129);
      await probeMediaProfile(first!);
      expect(calls).toHaveLength(129);
      await probeMediaProfile(second!);
      expect(calls).toHaveLength(130);
    } finally {
      vi.doUnmock("fs");
    }
  });

  it("classifies extensionless AVIF from its ISO-BMFF brand instead of the generic mov demuxer", async () => {
    const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-avif-profile-"));
    const fixturePath = resolve(fixtureDir, "asset");
    const ftyp = Buffer.alloc(24);
    ftyp.writeUInt32BE(24, 0);
    ftyp.write("ftyp", 4, 4, "ascii");
    ftyp.write("avif", 8, 4, "ascii");
    ftyp.writeUInt32BE(0, 12);
    ftyp.write("mif1", 16, 4, "ascii");
    ftyp.write("avif", 20, 4, "ascii");
    writeFileSync(fixturePath, ftyp);
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "video", codec_name: "av1" }],
          format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");
    try {
      await expect(probeMediaProfile(fixturePath)).resolves.toMatchObject({
        hasVideoStream: true,
        hasAudioStream: false,
        visualKind: "still",
      });
    } finally {
      rmSync(fixtureDir, { recursive: true, force: true });
    }
  });

  it("uses any non-attached video stream when cover art precedes moving video", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            { codec_type: "video", disposition: { attached_pic: 1 } },
            { codec_type: "video", codec_name: "h264" },
            { codec_type: "audio" },
          ],
          format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");
    await expect(probeMediaProfile("/tmp/video-with-cover")).resolves.toMatchObject({
      visualKind: "moving",
    });
  });

  it.skipIf(spawnSync("ffprobe", ["-version"]).status !== 0)(
    "rejects an IHDR-only truncated PNG even when ffprobe accepts png_pipe",
    async () => {
      vi.resetModules();
      vi.doUnmock("child_process");
      const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-truncated-png-profile-"));
      const fixturePath = resolve(fixtureDir, "asset");
      const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
      writeFileSync(fixturePath, buildPngWithChunks([ihdr]));
      const { probeMediaProfile } = await import("./ffprobe.js");
      try {
        await expect(probeMediaProfile(fixturePath)).rejects.toThrow();
      } finally {
        rmSync(fixtureDir, { recursive: true, force: true });
      }
    },
  );

  it("does not turn an aborted PNG probe into a successful metadata fallback", async () => {
    type KillableFakeProc = FakeProc & { kill: (signal?: NodeJS.Signals) => boolean };
    const spawn = () => {
      const proc = new EventEmitter() as KillableFakeProc;
      proc.stdout = new EventEmitter();
      proc.stderr = new EventEmitter();
      proc.kill = vi.fn(() => {
        process.nextTick(() => proc.emit("close", null, "SIGTERM"));
        return true;
      });
      process.nextTick(() => proc.emit("spawn"));
      return proc;
    };
    const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-aborted-png-profile-"));
    const fixturePath = resolve(fixtureDir, "asset");
    writeFileSync(fixturePath, buildMinimalPng());
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");
    const controller = new AbortController();
    try {
      const pending = probeMediaProfile(fixturePath, { signal: controller.signal });
      controller.abort(new Error("render cancelled"));
      await expect(pending).rejects.toThrow("render cancelled");
    } finally {
      rmSync(fixtureDir, { recursive: true, force: true });
    }
  });
});

interface SpawnCall {
  command: string;
  args: readonly string[];
}

interface FakeProc extends EventEmitter {
  stdout: EventEmitter;
  stderr: EventEmitter;
}

type SpawnOutcome =
  | { kind: "missing" }
  | { kind: "error"; message: string; code?: string }
  | {
      kind: "exit";
      code: number;
      stdout?: string;
      stderr?: string;
      /** Emit stdout as these exact byte chunks, to exercise a multi-byte
       *  character split across a pipe-chunk boundary. */
      stdoutChunks?: Buffer[];
    };

const NO_DECODED_FRAMES: SpawnOutcome = { kind: "exit", code: 0, stdout: "" };
const metadataProbes = (calls: SpawnCall[]) => calls.filter((c) => c.args.includes("-show_format"));

function createSpawnSpy(outcomes: SpawnOutcome[]): {
  spawn: (command: string, args: readonly string[]) => FakeProc;
  calls: SpawnCall[];
} {
  const calls: SpawnCall[] = [];
  let invocation = 0;
  const spawn = (command: string, args: readonly string[]): FakeProc => {
    calls.push({ command, args });
    const outcome = outcomes[invocation] ?? outcomes[outcomes.length - 1];
    invocation += 1;

    const proc = new EventEmitter() as FakeProc;
    proc.stdout = new EventEmitter();
    proc.stderr = new EventEmitter();

    process.nextTick(() => {
      if (!outcome) return;
      if (outcome.kind === "missing") {
        const err = new Error("spawn ffprobe ENOENT") as NodeJS.ErrnoException;
        err.code = "ENOENT";
        proc.emit("error", err);
        return;
      }
      if (outcome.kind === "error") {
        const err = new Error(outcome.message) as NodeJS.ErrnoException;
        if (outcome.code) err.code = outcome.code;
        proc.emit("error", err);
        return;
      }
      if (outcome.stdoutChunks) {
        for (const chunk of outcome.stdoutChunks) proc.stdout.emit("data", chunk);
      } else if (outcome.stdout) proc.stdout.emit("data", Buffer.from(outcome.stdout));
      if (outcome.stderr) proc.stderr.emit("data", Buffer.from(outcome.stderr));
      proc.emit("close", outcome.code);
    });

    return proc;
  };
  return { spawn, calls };
}

describe("media metadata cache invalidation", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
  });

  it("refreshes video metadata after an in-place file change", async () => {
    const dir = mkdtempSync(resolve(tmpdir(), "hf-video-metadata-change-"));
    const file = resolve(dir, "video.mp4");
    writeFileSync(file, "original file");
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            { codec_type: "video", width: 32, height: 24, avg_frame_rate: "10/1", duration: "1" },
          ],
          format: { duration: "1" },
        }),
      },
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            { codec_type: "video", width: 64, height: 48, avg_frame_rate: "24/1", duration: "2" },
          ],
          format: { duration: "2" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata } = await import("./ffprobe.js");
    try {
      expect(await extractMediaMetadata(file)).toMatchObject({ width: 32, durationSeconds: 1 });
      writeFileSync(file, "updated file with different dimensions");
      const refreshed = await extractMediaMetadata(file);
      expect(refreshed).toMatchObject({ width: 64, height: 48, fps: 24, durationSeconds: 2 });
      expect(await extractMediaMetadata(file)).toBe(refreshed);
      expect(calls).toHaveLength(2);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refreshes audio metadata after an atomic same-size file replacement", async () => {
    const dir = mkdtempSync(resolve(tmpdir(), "hf-audio-metadata-change-"));
    const file = resolve(dir, "audio.wav");
    const replacement = resolve(dir, "replacement.wav");
    writeFileSync(file, "first");
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            { codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "22050", channels: 1 },
          ],
          format: { duration: "1" },
        }),
      },
      NO_DECODED_FRAMES,
      NO_DECODED_FRAMES,
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            { codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "44100", channels: 2 },
          ],
          format: { duration: "2" },
        }),
      },
      NO_DECODED_FRAMES,
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractAudioMetadata } = await import("./ffprobe.js");
    try {
      expect(await extractAudioMetadata(file)).toMatchObject({
        durationSeconds: 1,
        sampleRate: 22050,
      });
      writeFileSync(replacement, "other");
      renameSync(replacement, file);
      const refreshed = await extractAudioMetadata(file);
      expect(refreshed).toMatchObject({ durationSeconds: 2, sampleRate: 44100, channels: 2 });
      expect(await extractAudioMetadata(file)).toBe(refreshed);
      expect(metadataProbes(calls)).toHaveLength(2);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.each([false, true])(
    "refreshes final-frame timestamps in signal scope %s",
    async (useSignal) => {
      const dir = mkdtempSync(resolve(tmpdir(), "hf-final-frame-change-"));
      const file = resolve(dir, "video.mp4");
      writeFileSync(file, "original file");
      const { spawn, calls } = createSpawnSpy([
        { kind: "exit", code: 0, stdout: "1.900000\n" },
        { kind: "exit", code: 0, stdout: "1.950000\n" },
      ]);
      vi.resetModules();
      vi.doMock("child_process", () => ({ spawn }));
      const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
      const metadata = { videoStreamDurationSeconds: 2, videoStreamStartSeconds: 0 };
      const signal = useSignal ? new AbortController().signal : undefined;
      try {
        expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.9);
        writeFileSync(file, "updated file with a different frame rate");
        expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.95);
        expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.95);
        expect(calls).toHaveLength(2);
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
  );

  it("does not return successful cached metadata after the file disappears", async () => {
    const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-removed-"));
    const file = resolve(dir, "video.mp4");
    writeFileSync(file, "original file");
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "video", width: 32, height: 24 }],
          format: { duration: "1" },
        }),
      },
      { kind: "exit", code: 1, stderr: "input missing" },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata } = await import("./ffprobe.js");
    try {
      await extractMediaMetadata(file);
      rmSync(file);
      await expect(extractMediaMetadata(file)).rejects.toThrow(/input missing/);
      expect(calls).toHaveLength(2);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("does not retain completed metadata when file identity is unavailable", async () => {
    const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-no-identity-"));
    const file = resolve(dir, "missing.wav");
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "audio", codec_name: "mp3" }],
          format: { duration: "1" },
        }),
      },
      NO_DECODED_FRAMES,
      NO_DECODED_FRAMES,
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "audio", codec_name: "mp3" }],
          format: { duration: "2" },
        }),
      },
      NO_DECODED_FRAMES,
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractAudioMetadata } = await import("./ffprobe.js");
    try {
      expect(await extractAudioMetadata(file)).toMatchObject({ durationSeconds: 1 });
      expect(await extractAudioMetadata(file)).toMatchObject({ durationSeconds: 2 });
      expect(metadataProbes(calls)).toHaveLength(2);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("keeps the replacement probe cached when an older probe fails", async () => {
    const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-probe-race-"));
    const file = resolve(dir, "video.mp4");
    writeFileSync(file, "original file");
    const factory = createSpawnSpy([]);
    const processes: FakeProc[] = [];
    vi.resetModules();
    vi.doMock("child_process", () => ({
      spawn: (command: string, args: readonly string[]) => {
        const proc = factory.spawn(command, args);
        processes.push(proc);
        return proc;
      },
    }));
    const { extractMediaMetadata } = await import("./ffprobe.js");
    try {
      const failed = expect(extractMediaMetadata(file)).rejects.toThrow(/code 1/);
      writeFileSync(file, "updated file with different dimensions");
      const replacement = extractMediaMetadata(file);
      processes[0]?.emit("close", 1);
      await failed;
      const shared = extractMediaMetadata(file);
      expect(factory.calls).toHaveLength(2);
      processes[1]?.stdout.emit(
        "data",
        Buffer.from(
          JSON.stringify({
            streams: [{ codec_type: "video", width: 64, height: 48 }],
            format: { duration: "2" },
          }),
        ),
      );
      processes[1]?.emit("close", 0);
      const [first, second] = await Promise.all([replacement, shared]);
      expect(second).toBe(first);
      expect(first).toMatchObject({ width: 64, durationSeconds: 2 });
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("still shares an unchanged file probe between concurrent callers", async () => {
    const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-shared-"));
    const file = resolve(dir, "video.mp4");
    writeFileSync(file, "unchanged file");
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "video", width: 32, height: 24 }],
          format: { duration: "1" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata } = await import("./ffprobe.js");
    try {
      const [first, second] = await Promise.all([
        extractMediaMetadata(file),
        extractMediaMetadata(file),
      ]);
      expect(second).toBe(first);
      expect(calls).toHaveLength(1);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe("ffprobe missing-binary fallback", () => {
  const originalFfprobePath = process.env.HYPERFRAMES_FFPROBE_PATH;
  const originalPath = process.env.PATH;

  function hidePathBinaries(): void {
    process.env.PATH = "";
  }

  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
    if (originalFfprobePath === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
    else process.env.HYPERFRAMES_FFPROBE_PATH = originalFfprobePath;
    if (originalPath === undefined) delete process.env.PATH;
    else process.env.PATH = originalPath;
  });

  it("spawns the configured absolute FFprobe path when HYPERFRAMES_FFPROBE_PATH is set", async () => {
    process.env.HYPERFRAMES_FFPROBE_PATH = "/tools/ffprobe.exe";
    const successfulStderr = "recoverable diagnostic on a successful probe";
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "audio", codec_name: "aac", sample_rate: "48000", channels: 2 }],
          format: { duration: "1.25", bit_rate: "128000" },
        }),
        stderr: successfulStderr,
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");
    const meta = await extractAudioMetadata("/tmp/uses-configured-ffprobe.wav");

    expect(meta.durationSeconds).toBe(1.25);
    expect(JSON.stringify(meta)).not.toContain(successfulStderr);
    expect(calls[0]?.command).toBe(resolve("/tools/ffprobe.exe"));
    expect(calls[0]?.args.slice(0, 2)).toEqual(["-v", "error"]);
  });

  it("does not accept an incomplete PNG through the missing-binary fallback", async () => {
    const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-truncated-png-fallback-"));
    const fixturePath = resolve(fixtureDir, "asset");
    const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
    writeFileSync(fixturePath, buildPngWithChunks([ihdr]));
    const { spawn } = createSpawnSpy([{ kind: "missing" }]);
    hidePathBinaries();
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { probeMediaProfile } = await import("./ffprobe.js");
    try {
      await expect(probeMediaProfile(fixturePath)).rejects.toThrow(/ffprobe/i);
    } finally {
      rmSync(fixtureDir, { recursive: true, force: true });
    }
  });

  // The container always reports 1.25s; each case varies what the decode probe finds.
  // `spawns` says whether the probe ran (no-frames also runs the full-scan fallback).
  it.each([
    {
      name: "non-AAC codec, decoded duration well beyond the container summary",
      codec: "flac",
      sampleRate: "48000",
      lastFrame: { best_effort_timestamp_time: "3.9", nb_samples: 4800 },
      expected: 4.0, // 3.9 + 4800/48000
      spawns: 2,
    },
    {
      name: "decoded duration within probe-precision margin of the summary — kept as-is",
      codec: "aac",
      sampleRate: "48000",
      // 1.2 + 3840/48000 = 1.28, only 0.03s over the 1.25s summary — under
      // the margin, so the summary (edit-list-corrected) duration wins.
      lastFrame: { best_effort_timestamp_time: "1.2", nb_samples: 3840 },
      expected: 1.25,
      spawns: 2,
    },
    {
      name: "no decodable frames — keeps the container duration",
      codec: "opus",
      sampleRate: "48000",
      lastFrame: undefined,
      expected: 1.25,
      // An empty tail read falls back to a full scan, which also finds
      // nothing (the mock's last outcome — the empty stdout — repeats).
      spawns: 3,
    },
    {
      name: "zero sample rate — skips the decode probe entirely",
      codec: "aac",
      sampleRate: "0",
      // Would have won on any other row; the probe is never spawned to see it.
      lastFrame: { best_effort_timestamp_time: "10", nb_samples: 999_999 },
      expected: 1.25,
      spawns: 1,
    },
  ])(
    "derives audio duration for $name",
    async ({ codec, sampleRate, lastFrame, expected, spawns }) => {
      const { spawn, calls } = createSpawnSpy([
        {
          kind: "exit",
          code: 0,
          stdout: JSON.stringify({
            streams: [
              { codec_type: "audio", codec_name: codec, sample_rate: sampleRate, channels: 2 },
            ],
            format: { duration: "1.25", bit_rate: "128000" },
          }),
        },
        {
          kind: "exit",
          code: 0,
          stdout: lastFrame
            ? `${lastFrame.best_effort_timestamp_time},${lastFrame.nb_samples}\n`
            : "",
        },
      ]);
      vi.resetModules();
      vi.doMock("child_process", () => ({ spawn }));

      const { extractAudioMetadata } = await import("./ffprobe.js");
      const meta = await extractAudioMetadata(`/tmp/${codec}-${sampleRate}.audio`);

      expect(meta.durationSeconds).toBeCloseTo(expected, 6);
      expect(calls).toHaveLength(spawns);
    },
  );

  // A bad seek index can make the tail read find nothing past a real final frame.
  it("falls back to a full decode when the tail-seeked read finds no frames", async () => {
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "audio", codec_name: "opus", sample_rate: "48000", channels: 2 }],
          format: { duration: "1.25" },
        }),
      },
      { kind: "exit", code: 0, stdout: "" }, // tail-seeked read: nothing found
      { kind: "exit", code: 0, stdout: "1.4,4800\n" }, // full-scan fallback: real frame
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");
    const meta = await extractAudioMetadata("/tmp/tail-seek-miss.opus");

    expect(meta.durationSeconds).toBeCloseTo(1.5, 6); // 1.4 + 4800/48000, well past the margin
    expect(calls).toHaveLength(3);
    expect(calls[1]?.args).toContain("-read_intervals");
    expect(calls[2]?.args).not.toContain("-read_intervals");
  });

  // An abort is the caller's own intent, so the decode probe must surface it
  // rather than swallow it the way it swallows a genuine probe failure. The
  // signal is aborted only once the decode probe has spawned — aborting up
  // front trips the container probe instead, leaving this path untested.
  it("propagates an abort raised during the decode probe", async () => {
    const controller = new AbortController();
    const { spawn: baseSpawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [{ codec_type: "audio", codec_name: "opus", sample_rate: "48000", channels: 2 }],
          format: { duration: "1.25" },
        }),
      },
      { kind: "exit", code: 0, stdout: "9,960\n" },
    ]);
    const spawn = (command: string, args: readonly string[]) => {
      if (calls.length === 1) controller.abort();
      return baseSpawn(command, args);
    };
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");
    await expect(
      extractAudioMetadata("/tmp/aborted.audio", { signal: controller.signal }),
    ).rejects.toThrow();
    expect(calls).toHaveLength(2);
  });

  it("extractMediaMetadata falls back to PNG cICP metadata when ffprobe is missing", async () => {
    const { spawn, calls } = createSpawnSpy([{ kind: "missing" }]);
    hidePathBinaries();
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
    const fixture = resolve(
      __dirname,
      "../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
    );
    const meta = await extractMediaMetadataMocked(fixture);

    expect(calls.length).toBe(1);
    expect(basename(calls[0]?.command ?? "")).toMatch(/^ffprobe(?:\.exe)?$/);
    expect(meta.videoCodec).toBe("png");
    expect(meta.durationSeconds).toBe(0);
    expect(meta.fps).toBe(0);
    expect(meta.hasAudio).toBe(false);
    expect(meta.isVFR).toBe(false);
    expect(meta.hasAlpha).toBe(false);
    expect(meta.colorSpace?.colorTransfer).toBe("smpte2084");
    expect(meta.colorSpace?.colorPrimaries).toBe("bt2020");
  });

  it("extractMediaMetadata detects VP9 alpha_mode streams", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "vp9",
              width: 320,
              height: 180,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
              pix_fmt: "yuv420p",
              tags: { alpha_mode: "1" },
            },
          ],
          format: { duration: "1.5" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
    const meta = await extractMediaMetadataMocked("/tmp/alpha.webm");

    expect(meta.videoCodec).toBe("vp9");
    expect(meta.hasAlpha).toBe(true);
  });

  it("normalizes omitted video color components to empty strings", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 64,
              height: 64,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
              pix_fmt: "yuv420p",
              color_space: "bt709",
            },
          ],
          format: { duration: "1" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
    const metadata = await extractMediaMetadataMocked("/tmp/partial-color.mp4");

    expect(metadata.colorSpace).toEqual({
      colorPrimaries: "",
      colorTransfer: "",
      colorSpace: "bt709",
    });
  });

  // Regression: newer libavformat builds (and the output of `hyperframes
  // remove-background` itself) write the VP9-alpha sidecar tag as
  // `ALPHA_MODE` (uppercase). The lowercase-only check classified those
  // files as having no alpha, the producer extracted them as JPGs, and
  // the injected <img> overlays were fully opaque rectangles that hid
  // every static element below them on the z-stack. The bug was silent —
  // studio preview rendered correctly via native <video> playback while
  // production renders covered headlines and captions with the avatar.
  it("extractMediaMetadata detects ALPHA_MODE (uppercase) streams from newer ffmpeg builds", async () => {
    const { spawn } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "vp9",
              width: 320,
              height: 180,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
              pix_fmt: "yuv420p",
              tags: { ALPHA_MODE: "1" },
            },
          ],
          format: { duration: "1.5" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
    const meta = await extractMediaMetadataMocked("/tmp/alpha-uppercase.webm");

    expect(meta.videoCodec).toBe("vp9");
    expect(meta.hasAlpha).toBe(true);
  });

  it("extractMediaMetadata rethrows ffprobe-missing error for non-image files without fallback", async () => {
    const { spawn } = createSpawnSpy([{ kind: "missing" }]);
    hidePathBinaries();
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");

    await expect(extractMediaMetadataMocked("/tmp/no-such-video.mp4")).rejects.toThrow(/ffprobe/);
  });

  it("surfaces bounded ffprobe stderr for invalid media", async () => {
    const leadingNoise = "x".repeat(10_000);
    const diagnostic = "Invalid data found when processing input";
    const inputPath = "/tmp/render/My Secret Video.mp4";
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 1,
        stderr: `${leadingNoise}${inputPath}: ${diagnostic}`,
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");

    let thrown: unknown;
    try {
      await extractAudioMetadata(inputPath);
    } catch (error) {
      thrown = error;
    }
    expect(String(thrown)).toContain(diagnostic);
    expect(String(thrown)).toContain("[input]");
    expect(String(thrown)).not.toContain(inputPath);
    expect(String(thrown)).not.toContain("My Secret Video.mp4");
    expect(String(thrown).length).toBeLessThan(4_500);
    expect(calls[0]?.args.slice(0, 2)).toEqual(["-v", "error"]);
    expect(calls[0]?.args.at(-1)).toBe(inputPath);
  });

  it("redacts an input path fragment when the stderr tail starts inside its basename", async () => {
    const diagnostic = "Invalid data found when processing input";
    const inputPath = "/tmp/render/Confidential Client Preview.mp4";
    const retainedPathFragment = "Client Preview.mp4";
    const diagnosticPrefix = `: ${diagnostic} `;
    const remainingBytes =
      8 * 1024 - Buffer.byteLength(retainedPathFragment) - Buffer.byteLength(diagnosticPrefix);
    const multibyteCount = Math.floor(remainingBytes / Buffer.byteLength("€"));
    const trailingAscii = "x".repeat(remainingBytes - multibyteCount * Buffer.byteLength("€"));
    const stderr = `${inputPath}${diagnosticPrefix}${"€".repeat(multibyteCount)}${trailingAscii}`;
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 1, stderr }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");

    let thrown: unknown;
    try {
      await extractAudioMetadata(inputPath);
    } catch (error) {
      thrown = error;
    }
    expect(String(thrown)).toContain(diagnostic);
    expect(String(thrown)).toContain("[input]");
    expect(String(thrown)).not.toContain(retainedPathFragment);
    expect(String(thrown)).not.toContain("Client Preview.mp4");
  });

  it("extractAudioMetadata surfaces a ffprobe-missing error verbatim", async () => {
    const { spawn, calls } = createSpawnSpy([{ kind: "missing" }]);
    hidePathBinaries();
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");

    await expect(extractAudioMetadata("/tmp/no-such-audio.wav")).rejects.toThrow(
      /ffprobe not found/,
    );
    expect(calls.length).toBe(1);
    expect(basename(calls[0]?.command ?? "")).toMatch(/^ffprobe(?:\.exe)?$/);
  });

  it("analyzeKeyframeIntervals flags a single-keyframe video as problematic, not healthy", async () => {
    // A single-GOP file (one keyframe at t=0) is the worst case this check exists to catch.
    // Regression for #3460, where fewer than 2 keyframes short-circuited to isProblematic:false.
    // Real `csv=p=0` output has a trailing comma per row; parseFloat must tolerate it.
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000,\n" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/single-gop.mp4", {
        videoStreamDurationSeconds: 6.5,
        videoStreamStartSeconds: 0,
      }),
    ).resolves.toEqual({
      avgIntervalSeconds: 6.5,
      maxIntervalSeconds: 6.5,
      keyframeCount: 1,
      isProblematic: true,
    });
  });

  it("analyzeKeyframeIntervals leaves a single keyframe exactly at the 2s threshold healthy", async () => {
    // isProblematic compares with a strict `>`, so exactly 2s must stay healthy.
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000\n" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/exactly-two-seconds.mp4", {
        videoStreamDurationSeconds: 2,
        videoStreamStartSeconds: 0,
      }),
    ).resolves.toEqual({
      avgIntervalSeconds: 2,
      maxIntervalSeconds: 2,
      keyframeCount: 1,
      isProblematic: false,
    });
  });

  it("analyzeKeyframeIntervals normalizes an absolute keyframe pts against a nonzero stream start", async () => {
    // ffprobe's pts_time is absolute, not relative to stream start. A clip with
    // start_time=5 and a keyframe at absolute pts 5.0 is still single-GOP end-to-end,
    // so it must stay flagged, not cleared by subtracting duration from the raw pts.
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "5.000000\n" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/nonzero-start-single-gop.mp4", {
        videoStreamDurationSeconds: 3,
        videoStreamStartSeconds: 5,
      }),
    ).resolves.toEqual({
      avgIntervalSeconds: 3,
      maxIntervalSeconds: 3,
      keyframeCount: 1,
      isProblematic: true,
    });
  });

  it("analyzeKeyframeIntervals leaves a short single-keyframe video healthy", async () => {
    // The single-GOP span is measured off the duration the caller passes in, so
    // a 1s video muxed with 10s of audio has to be probed with its video
    // stream's duration; the container's would overstate the span and warn.
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000\n" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/short-video-long-audio.mp4", {
        videoStreamDurationSeconds: 1,
        videoStreamStartSeconds: 0,
      }),
    ).resolves.toEqual({
      avgIntervalSeconds: 1,
      maxIntervalSeconds: 1,
      keyframeCount: 1,
      isProblematic: false,
    });
  });

  it("analyzeKeyframeIntervals treats a single keyframe with an unknown (NaN) duration as healthy, not NaN", async () => {
    // ffprobe reports "N/A" for duration on some containers, which parses to
    // NaN upstream in extractMediaMetadata. Without a finite-duration guard,
    // NaN propagates through Math.max unchanged into the returned interval.
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000\n" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/unknown-duration.mp4", {
        videoStreamDurationSeconds: NaN,
        videoStreamStartSeconds: 0,
      }),
    ).resolves.toEqual({
      avgIntervalSeconds: 0,
      maxIntervalSeconds: 0,
      keyframeCount: 1,
      isProblematic: false,
    });
  });

  it("analyzeKeyframeIntervals reports a zero-keyframe video as healthy, ignoring the duration", async () => {
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/no-keyframes.mp4", {
        videoStreamDurationSeconds: 6.5,
        videoStreamStartSeconds: 0,
      }),
    ).resolves.toEqual({
      avgIntervalSeconds: 0,
      maxIntervalSeconds: 0,
      keyframeCount: 0,
      isProblematic: false,
    });
  });

  it("analyzeKeyframeIntervals surfaces a ffprobe-missing error verbatim", async () => {
    const { spawn, calls } = createSpawnSpy([{ kind: "missing" }]);
    hidePathBinaries();
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { analyzeKeyframeIntervals } = await import("./ffprobe.js");

    await expect(
      analyzeKeyframeIntervals("/tmp/no-such-video.mp4", {
        videoStreamDurationSeconds: 10,
        videoStreamStartSeconds: 0,
      }),
    ).rejects.toThrow(/ffprobe not found/);
    expect(calls.length).toBe(1);
    expect(basename(calls[0]?.command ?? "")).toMatch(/^ffprobe(?:\.exe)?$/);
  });

  it("ffprobe-missing error message includes install hint", async () => {
    const { spawn } = createSpawnSpy([{ kind: "missing" }]);
    hidePathBinaries();
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata } = await import("./ffprobe.js");

    await expect(extractAudioMetadata("/tmp/example.mp3")).rejects.toThrow(/install FFmpeg/i);
  });
});

describe("ffprobe option separator", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
  });

  it("places -- before the file path so paths starting with - are not parsed as options", async () => {
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 320,
              height: 180,
              r_frame_rate: "30/1",
              avg_frame_rate: "30/1",
            },
          ],
          format: { duration: "1.5" },
        }),
      },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractMediaMetadata } = await import("./ffprobe.js");
    const filePath = "/tmp/-dangerous-name.mp4";
    await extractMediaMetadata(filePath);

    const args = calls[0]?.args ?? [];
    const filePathIndex = args.indexOf(filePath);
    expect(filePathIndex).toBeGreaterThan(0);
    expect(args[filePathIndex - 1]).toBe("--");
  });

  it("uses -- for audio and keyframe probes too", async () => {
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "audio",
              codec_name: "aac",
              sample_rate: "48000",
              channels: 2,
            },
          ],
          format: { duration: "1.25" },
        }),
      },
      // The decode-based duration probe also runs, so its argv (including its
      // own `--`) is covered here too.
      { kind: "exit", code: 0, stdout: "1.2,3840\n" },
      { kind: "exit", code: 0, stdout: "0.000\n1.000\n" },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));

    const { extractAudioMetadata, analyzeKeyframeIntervals } = await import("./ffprobe.js");
    await extractAudioMetadata("/tmp/-audio.wav");
    await analyzeKeyframeIntervals("/tmp/-video.mp4", {
      videoStreamDurationSeconds: 10,
      videoStreamStartSeconds: 0,
    });

    // Per call, not a flattened count. A total of 3 is satisfied by one call
    // emitting three `--` and two emitting none — i.e. it cannot fail for
    // misplacement, which is the shape of bug this exists to catch.
    expect(calls.map((call) => (call.args ?? []).slice(-2))).toEqual([
      ["--", "/tmp/-audio.wav"],
      ["--", "/tmp/-audio.wav"],
      ["--", "/tmp/-video.mp4"],
    ]);
  });
});

describe("parseFrameRate", () => {
  // Direct against the exported function. The previous table drove this
  // through extractMediaMetadata behind a spawn mock, which cost a
  // vi.resetModules() plus a dynamic re-import of core's 238-file barrel per
  // row (74.9 ms vs 0.094 ms) — and 4 of its 7 rows produced identical values
  // against the pre-fix implementation, so it could not fail for the bugs it
  // was written to catch.
  it.each([
    ["30/1", 30],
    ["30000/1001", 29.97],
    ["24000/1001", 23.98],
    ["60", 60],
    ["25.5", 25.5],
  ])("parses %s as %s", (input, expected) => {
    expect(parseFrameRate(input)).toBe(expected);
  });

  it.each([
    ["30/", 0],
    ["30/0", 0],
    ["0/0", 0],
    ["abc/def", 0],
    ["", 0],
    [undefined, 0],
  ])("returns 0 for unusable input %s", (input, expected) => {
    expect(parseFrameRate(input)).toBe(expected);
  });

  // Finite operands, infinite quotient — the operand-only guard missed these.
  it.each(["1e308/1e-10", "2/1e-320"])("returns 0 for overflowing quotient %s", (input) => {
    expect(parseFrameRate(input)).toBe(0);
  });

  // Negatives were truthy, so `meta.fps || 30` did not rescue them and
  // buildEncoderArgs emitted `-r -30`.
  it.each(["-30/1", "30/-1", "-60"])("returns 0 for negative rate %s", (input) => {
    expect(parseFrameRate(input)).toBe(0);
  });

  // Fell through to a bare parseFloat that stops at trailing garbage. The
  // rational operands had the same defect after the plain path was fixed.
  it.each(["30/1/2", "60fps", "60fps/1", "60/1fps", "30garbage/1garbage", "/", "/1", "30/"])(
    "returns 0 for malformed input %s",
    (input) => {
      expect(parseFrameRate(input)).toBe(0);
    },
  );

  // raw * 100 overflows for a finite-but-huge rate, so the rounded value was
  // Infinity even though the pre-round guard passed.
  it.each(["1e307", "1e307/1", "1e308/0.5"])("returns 0 when rounding overflows: %s", (input) => {
    expect(parseFrameRate(input)).toBe(0);
  });

  // 2dp rounding collapsed these to 0, and the caller's `|| 30` then
  // re-encoded a 300-second timelapse as a ~1/30-second clip.
  it.each([
    ["1/300", 0.01],
    ["1/1000", 0.01],
    ["1/200", 0.01],
  ])("floors sub-0.005 rate %s to %s rather than 0", (input, expected) => {
    expect(parseFrameRate(input)).toBe(expected);
  });
});

describe("extractPngMetadataFromBuffer cICP ordering", () => {
  it("does not emit color space until IHDR provides width and height", () => {
    const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
    const cicp = pngChunk("cICP", [9, 16, 0, 1]);
    const idat = pngChunk("IDAT", [0x78, 0x9c, 0x03, 0x00, 0x00, 0x00, 0x00, 0x01]);
    const iend = pngChunk("IEND", []);

    // cICP before IHDR is invalid PNG ordering; make sure we don't return
    // zero-sized metadata in that case.
    const malformed = buildPngWithChunks([cicp, ihdr, idat, iend]);
    expect(extractPngMetadataFromBuffer(malformed)).toEqual({
      width: 1,
      height: 1,
      colorSpace: {
        colorPrimaries: "bt2020",
        colorTransfer: "smpte2084",
        colorSpace: "gbr",
      },
    });

    // Without any IHDR, a cICP alone should not produce a result.
    const onlyCicp = buildPngWithChunks([cicp, iend]);
    expect(extractPngMetadataFromBuffer(onlyCicp)).toBeNull();
  });
});

describe("PNG chunk walk — integrity of the fallback itself", () => {
  const IHDR_4K = [0, 0, 0x0f, 0, 0, 0, 0x08, 0x70, 16, 2, 0, 0, 0];
  const CICP_PQ = [9, 16, 0, 1];

  // Regression: the walk used to continue past cICP to IEND, which made
  // whole-file integrity a precondition for returning anything. A damaged
  // trailing chunk in an otherwise-good HDR PNG nulled the whole result, and
  // extractMediaMetadata then re-throws the ffprobe error it had swallowed
  // rather than using the fallback it just computed.
  it("returns metadata even when a chunk AFTER cICP is corrupt", () => {
    const bad = pngChunk("tEXt", [65, 66]);
    bad[bad.length - 1] ^= 0xff; // break the CRC
    const png = buildPngWithChunks([
      pngChunk("IHDR", IHDR_4K),
      pngChunk("cICP", CICP_PQ),
      pngChunk("IDAT", [0x78, 0x9c, 0x63, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01]),
      bad,
      pngChunk("IEND", []),
    ]);
    expect(extractPngMetadataFromBuffer(png)).toEqual({
      width: 3840,
      height: 2160,
      colorSpace: { colorPrimaries: "bt2020", colorTransfer: "smpte2084", colorSpace: "gbr" },
    });
  });

  it("survives outright truncation after cICP", () => {
    const png = buildPngWithChunks([pngChunk("IHDR", IHDR_4K), pngChunk("cICP", CICP_PQ)]);
    const truncated = Buffer.concat([png, Buffer.from([0, 0, 0x7f, 0xff, 73, 68, 65, 84])]);
    expect(extractPngMetadataFromBuffer(truncated)?.width).toBe(3840);
  });

  // Regression: IHDR had no first-chunk anchor, so a later one overwrote the
  // real dimensions and the producer laid out a 1-pixel image.
  it("ignores a second IHDR", () => {
    const png = buildPngWithChunks([
      pngChunk("IHDR", IHDR_4K),
      pngChunk("cICP", CICP_PQ),
      pngChunk("IDAT", [0x78, 0x9c, 0x63, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01]),
      pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]),
      pngChunk("IEND", []),
    ]);
    const meta = extractPngMetadataFromBuffer(png);
    expect(meta?.width).toBe(3840);
    expect(meta?.height).toBe(2160);
  });

  // A truncated 8-byte IHDR used to be accepted, reading height out of the
  // CRC bytes; the spec length is 13.
  it("rejects a short IHDR rather than reading garbage dimensions", () => {
    const png = buildPngWithChunks([
      pngChunk("IHDR", [0, 0, 0, 7, 0, 0, 0, 9]),
      pngChunk("cICP", CICP_PQ),
      pngChunk("IEND", []),
    ]);
    expect(extractPngMetadataFromBuffer(png)).toBeNull();
  });

  it("still rejects a PNG whose IHDR or cICP itself is corrupt", () => {
    const badIhdr = pngChunk("IHDR", IHDR_4K);
    badIhdr[badIhdr.length - 1] ^= 0xff;
    expect(
      extractPngMetadataFromBuffer(buildPngWithChunks([badIhdr, pngChunk("IEND", [])])),
    ).toBeNull();
  });
});

describe("crc32 works on every runtime the package declares", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("node:zlib");
  });

  /** Load ffprobe.ts as it would evaluate on Node 22.0/22.1. */
  async function loadWithoutNativeCrc32() {
    const actual = await vi.importActual<typeof import("node:zlib")>("node:zlib");
    vi.resetModules();
    // zlib.crc32 landed in 22.2.0, but engine and cli both declare
    // `"node": ">=22"` behind a major-only gate. A NAMED import of a missing
    // export throws at module evaluation, so ffprobe.ts would fail to load
    // entirely on those runtimes — before any PNG is touched.
    vi.doMock("node:zlib", () => ({ ...actual, crc32: undefined }));
    return import("./ffprobe.js");
  }

  it("parses an HDR PNG identically with the native crc32 unavailable", async () => {
    const png = buildPngWithChunks([
      pngChunk("IHDR", [0, 0, 0x0f, 0, 0, 0, 0x08, 0x70, 16, 2, 0, 0, 0]),
      pngChunk("cICP", [9, 16, 0, 1]),
      pngChunk("IEND", []),
    ]);
    const withNative = extractPngMetadataFromBuffer(png);
    expect(withNative?.colorSpace?.colorTransfer).toBe("smpte2084");

    const fresh = await loadWithoutNativeCrc32();
    expect(fresh.extractPngMetadataFromBuffer(png)).toEqual(withNative);
  });

  it("rejects a corrupt chunk on the fallback path too", async () => {
    const bad = pngChunk("IHDR", [0, 0, 0x0f, 0, 0, 0, 0x08, 0x70, 16, 2, 0, 0, 0]);
    bad[bad.length - 1] ^= 0xff;
    const png = buildPngWithChunks([bad, pngChunk("IEND", [])]);

    const fresh = await loadWithoutNativeCrc32();
    expect(fresh.extractPngMetadataFromBuffer(png)).toBeNull();
  });
});

describe("audio duration decode probe never fails the call and needs no profile allowlist", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
  });

  const aacStream = (profile?: string) =>
    JSON.stringify({
      streams: [
        { codec_type: "audio", codec_name: "aac", sample_rate: "44100", channels: 2, profile },
      ],
      format: { duration: "600", bit_rate: "128000" },
    });

  async function probe(outcomes: SpawnOutcome[], file: string) {
    const { spawn, calls } = createSpawnSpy(outcomes);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractAudioMetadata } = await import("./ffprobe.js");
    return { meta: await extractAudioMetadata(file), calls };
  }

  // Regression: the old refinement had no try/catch, so its failure rejected a
  // call whose duration was already correct. htmlCompiler catches that as
  // "no audio stream", returns 0, and the render ships silent.
  it("keeps the container duration when the decode probe fails", async () => {
    const { meta, calls } = await probe(
      [
        { kind: "exit", code: 0, stdout: aacStream() },
        { kind: "exit", code: 1, stdout: "", stderr: "ffprobe exploded" },
      ],
      "/tmp/decode-probe-fails.m4a",
    );
    expect(meta.durationSeconds).toBe(600);
    // The tail-seeked attempt fails, so the full-scan fallback also runs (and
    // also fails, via the mock's repeated last outcome) before giving up.
    expect(calls).toHaveLength(3);
  });

  it("keeps the container duration when the decode probe returns junk", async () => {
    const { meta, calls } = await probe(
      [
        { kind: "exit", code: 0, stdout: aacStream() },
        { kind: "exit", code: 0, stdout: "not json at all" },
      ],
      "/tmp/decode-probe-junk.m4a",
    );
    expect(meta.durationSeconds).toBe(600);
    expect(calls).toHaveLength(3);
  });

  // The old refinement needed a profile allowlist because it guessed a fixed
  // samples-per-frame value (right for AAC-LC, wrong for HE-AAC/LD/ELD/etc).
  // Decoding the real last frame's own sample count has no such assumption,
  // so every profile goes through the same path with no special-casing.
  it.each(["LC", "HE-AAC", "HE-AACv2", "LD", "ELD", "Main", "", "SomethingNew"])(
    "corrects duration for AAC profile %s, with no allowlist",
    async (profile) => {
      const { meta, calls } = await probe(
        [
          { kind: "exit", code: 0, stdout: aacStream(profile) },
          { kind: "exit", code: 0, stdout: "603.9,4410\n" },
        ],
        `/tmp/aac-${profile || "none"}.m4a`,
      );
      expect(meta.durationSeconds).toBeCloseTo(604, 5); // 603.9 + 4410/44100
      expect(calls).toHaveLength(2);
    },
  );

  const audioProbe = (stream: object, format: object) =>
    JSON.stringify({
      streams: [{ codec_type: "audio", codec_name: "aac", sample_rate: "44100", ...stream }],
      format: { duration: "600", ...format },
    });
  const readInterval = (calls: SpawnCall[]) =>
    calls[1]?.args[calls[1].args.indexOf("-read_intervals") + 1];

  it.each([
    ["the stream", { start_time: "1.4" }, {}],
    ["the format, when the stream has none", {}, { start_time: "1.4" }],
  ])("measures the decoded end from the start time of %s", async (_, stream, format) => {
    const { meta, calls } = await probe(
      [
        { kind: "exit", code: 0, stdout: audioProbe(stream, format) },
        { kind: "exit", code: 0, stdout: "601.3,4410\n" },
      ],
      `/tmp/start-offset-${Object.keys(format).length}.ts`,
    );
    expect(meta.durationSeconds).toBe(600); // 601.3 + 0.1 - 1.4 is within the margin
    expect(readInterval(calls)).toBe("600.4%+2147483647");
  });

  it.each([
    ["trusts a shorter decode for raw ADTS", "aac", 10],
    ["keeps the container for an MP4, whose edit list may trim", "mov,mp4,m4a,3gp,3g2,mj2", 600],
  ])("%s", async (_, formatName, expected) => {
    const { meta } = await probe(
      [
        { kind: "exit", code: 0, stdout: audioProbe({}, { format_name: formatName }) },
        { kind: "exit", code: 0, stdout: "9.9,4410\n" },
      ],
      `/tmp/shorter-decode-${formatName.length}.aac`,
    );
    expect(meta.durationSeconds).toBeCloseTo(expected, 5);
  });

  it("reads the last frame of a decode listing longer than the stdout cap", async () => {
    const rows = Array.from({ length: 10000 }, (_, i) => `${(i / 100).toFixed(2)},4410`);
    const { meta } = await probe(
      [
        { kind: "exit", code: 0, stdout: aacStream() },
        { kind: "exit", code: 0, stdout: `${rows.join("\n")}\n603.9,4410\n` },
      ],
      "/tmp/long-decode-listing.m4a",
    );
    expect(meta.durationSeconds).toBeCloseTo(604, 5);
  });
});

// honest.mp4 is FLAC-in-MP4; lying.mp4 is the same bytes with the mvhd/tkhd/mdhd
// durations halved, every audio frame intact.
const HAS_FFPROBE = spawnSync("ffprobe", ["-version"]).status === 0;

describe.skipIf(!HAS_FFPROBE)(
  "extractAudioMetadata recovers a real lying container's true duration",
  () => {
    const honestPath = resolve(__dirname, "__fixtures__/lying-container/honest.mp4");
    const lyingPath = resolve(__dirname, "__fixtures__/lying-container/lying.mp4");

    it("recovers the true duration from a FLAC-in-MP4 file whose container atoms were patched to lie", async () => {
      const { extractAudioMetadata } = await import("./ffprobe.js");
      const trueMeta = await extractAudioMetadata(honestPath);
      expect(trueMeta.audioCodec).toBe("flac");
      expect(trueMeta.durationSeconds).toBeGreaterThan(3.9);

      const lyingMeta = await extractAudioMetadata(lyingPath);

      // Recovers the real duration — not the halved container summary.
      expect(lyingMeta.durationSeconds).toBeCloseTo(trueMeta.durationSeconds, 1);
    });

    // ffprobe reads an open interval's end from uninitialised heap; glibc's MALLOC_PERTURB_
    // makes that garbage deterministic on Linux, as Windows' heap does at random.
    it("decodes the tail in one pass when ffprobe's heap is dirty", async () => {
      const real = await vi.importActual<typeof import("child_process")>("child_process");
      const probes: string[][] = [];
      vi.resetModules();
      vi.doMock("child_process", () => ({
        ...real,
        spawn: (command: string, args: string[], options: object) => {
          probes.push(args);
          return real.spawn(command, args, options);
        },
      }));
      const previous = process.env.MALLOC_PERTURB_;
      process.env.MALLOC_PERTURB_ = "1";
      try {
        const { extractAudioMetadata } = await import("./ffprobe.js");
        expect((await extractAudioMetadata(lyingPath)).durationSeconds).toBeCloseTo(4, 3);
        // The container probe, then the tail decode; a third call is the full-scan fallback.
        expect(probes).toHaveLength(2);
      } finally {
        if (previous === undefined) delete process.env.MALLOC_PERTURB_;
        else process.env.MALLOC_PERTURB_ = previous;
        vi.doUnmock("child_process");
        vi.resetModules();
      }
    });

    // 2 s of AAC in MPEG-TS starting at 1.4 s: last frame 3.448 + 1024/16000 - 1.4.
    it("does not add an MPEG-TS start time to the duration", async () => {
      const { extractAudioMetadata } = await import("./ffprobe.js");
      const path = resolve(__dirname, "__fixtures__/lying-container/start-offset.mpegts");
      expect((await extractAudioMetadata(path)).durationSeconds).toBeCloseTo(2.112, 3);
    });

    // 2 s silence + 1 s noise as raw ADTS; ffprobe 8.1 estimates about 9.1 s from the quiet opening.
    it("corrects a raw ADTS duration that the container overclaims", async () => {
      const { extractAudioMetadata } = await import("./ffprobe.js");
      const path = resolve(__dirname, "__fixtures__/lying-container/overclaim.aac");
      expect((await extractAudioMetadata(path)).durationSeconds).toBeCloseTo(3.072, 3);
    });
  },
);

describe("final video frame timestamp probes", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
  });

  it("normalizes absolute frame PTS by the selected video stream start", async () => {
    const { spawn, calls } = createSpawnSpy([
      {
        kind: "exit",
        code: 0,
        stdout: JSON.stringify({
          streams: [
            {
              codec_type: "video",
              codec_name: "h264",
              width: 64,
              height: 64,
              duration: "3",
              start_time: "5",
              r_frame_rate: "1/1",
              avg_frame_rate: "1/1",
            },
          ],
          format: { duration: "8" },
        }),
      },
      { kind: "exit", code: 0, stdout: "5.000000,\n6.000000\n7.000000\n" },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractFinalVideoFrameTimestamp, extractMediaMetadata } = await import("./ffprobe.js");

    const metadata = await extractMediaMetadata("/tmp/nonzero-start.mp4");
    expect(metadata.videoStreamDurationSeconds).toBe(3);
    expect(metadata.videoStreamStartSeconds).toBe(5);
    await expect(extractFinalVideoFrameTimestamp("/tmp/nonzero-start.mp4", metadata)).resolves.toBe(
      2,
    );

    const intervalIndex = calls[1]?.args.indexOf("-read_intervals") ?? -1;
    expect(calls[1]?.args[intervalIndex + 1]).toBe("7%8");
  });

  it("falls back to a bounded-output full scan when a transport cannot interval-seek", async () => {
    const { spawn, calls } = createSpawnSpy([
      { kind: "exit", code: 0, stdout: "" },
      { kind: "exit", code: 0, stdout: "-2.000000,\n-1.000000\n0.000000\n" },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");

    await expect(
      extractFinalVideoFrameTimestamp("/tmp/unindexed-negative-base.ts", {
        videoStreamDurationSeconds: 3,
        videoStreamStartSeconds: -2,
      }),
    ).resolves.toBe(2);

    const intervalIndex = calls[0]?.args.indexOf("-read_intervals") ?? -1;
    expect(calls[0]?.args[intervalIndex + 1]).toBe("0%1");
    expect(calls[1]?.args).not.toContain("-read_intervals");
  });

  it("does not share a caller-cancellable probe across render consumers", async () => {
    type KillableFakeProc = FakeProc & { kill: (signal?: NodeJS.Signals) => boolean };
    const processes: KillableFakeProc[] = [];
    const spawn = () => {
      const proc = new EventEmitter() as KillableFakeProc;
      proc.stdout = new EventEmitter();
      proc.stderr = new EventEmitter();
      proc.kill = vi.fn(() => {
        process.nextTick(() => proc.emit("close", null, "SIGTERM"));
        return true;
      });
      processes.push(proc);
      process.nextTick(() => proc.emit("spawn"));
      return proc;
    };
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
    const metadata = { videoStreamDurationSeconds: 3, videoStreamStartSeconds: 0 };
    const firstController = new AbortController();
    const secondController = new AbortController();

    const first = extractFinalVideoFrameTimestamp(
      "/tmp/shared-source.mp4",
      metadata,
      firstController.signal,
    );
    const second = extractFinalVideoFrameTimestamp(
      "/tmp/shared-source.mp4",
      metadata,
      secondController.signal,
    );
    expect(processes).toHaveLength(2);

    firstController.abort();
    await expect(first).rejects.toThrow(/ffprobe abort/);
    expect(processes[0]?.kill).toHaveBeenCalledWith("SIGTERM");
    expect(processes[1]?.kill).not.toHaveBeenCalled();

    processes[1]?.stdout.emit("data", Buffer.from("2.000000\n"));
    processes[1]?.emit("close", 0, null);
    await expect(second).resolves.toBe(2);

    expect(secondController.signal.aborted).toBe(false);
  });

  it("deduplicates the interval and fallback chain within one cancellation scope", async () => {
    const { spawn, calls } = createSpawnSpy([
      { kind: "exit", code: 0, stdout: "" },
      { kind: "exit", code: 0, stdout: "-2.000000\n-1.000000\n0.000000\n" },
    ]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
    const metadata = { videoStreamDurationSeconds: 3, videoStreamStartSeconds: -2 };
    const signal = new AbortController().signal;

    await expect(
      Promise.all([
        extractFinalVideoFrameTimestamp("/tmp/repeated-held-tail.ts", metadata, signal),
        extractFinalVideoFrameTimestamp("/tmp/repeated-held-tail.ts", metadata, signal),
      ]),
    ).resolves.toEqual([2, 2]);

    expect(calls).toHaveLength(2);
    expect(calls[0]?.args).toContain("-read_intervals");
    expect(calls[1]?.args).not.toContain("-read_intervals");
  });

  it("still deduplicates cancellation-independent probes", async () => {
    const { spawn, calls } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "2.000000\n" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
    const metadata = { videoStreamDurationSeconds: 3, videoStreamStartSeconds: 0 };

    await Promise.all([
      extractFinalVideoFrameTimestamp("/tmp/shared-source.mp4", metadata),
      extractFinalVideoFrameTimestamp("/tmp/shared-source.mp4", metadata),
    ]);

    expect(calls).toHaveLength(1);
  });
});

describe("runFfprobe process and stream handling", () => {
  afterEach(() => {
    vi.resetModules();
    vi.doUnmock("child_process");
  });

  // Regression: `--` protects "-intro.mp4" but not a path of exactly "-",
  // which ffprobe rewrites to fd: AFTER option parsing and then reads stdin.
  // With stdin left as an unwritten pipe the probe hung for the full 30s
  // deadline and failed with an empty diagnostic.
  it("rejects a filePath of '-' immediately instead of hanging on stdin", async () => {
    const { spawn, calls } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "{}" }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata } = await import("./ffprobe.js");

    await expect(extractMediaMetadata("-")).rejects.toThrow(/stdin is not a supported input path/);
    expect(calls).toHaveLength(0);
  });

  it("never leaves the child's stdin as a writable pipe", async () => {
    const stdios: unknown[] = [];
    const spawn = (_c: string, _a: readonly string[], opts?: { stdio?: unknown }) => {
      stdios.push(opts?.stdio);
      const proc = new EventEmitter() as FakeProc;
      proc.stdout = new EventEmitter();
      proc.stderr = new EventEmitter();
      process.nextTick(() => {
        proc.stdout.emit(
          "data",
          Buffer.from(
            JSON.stringify({
              streams: [{ codec_type: "video", codec_name: "h264", width: 2, height: 2 }],
              format: { duration: "1" },
            }),
          ),
        );
        proc.emit("close", 0);
      });
      return proc;
    };
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata } = await import("./ffprobe.js");

    await extractMediaMetadata("/tmp/stdio-shape.mp4");
    expect(stdios[0]).toEqual(["ignore", "pipe", "pipe"]);
  });

  // NOTE on the StringDecoder change: a per-chunk toString() corrupts a
  // multi-byte character split across a pipe boundary into U+FFFD, but
  // U+FFFD is valid JSON string content, so JSON.parse still succeeds and
  // extractMediaMetadata's public surface returns nothing that exposes the
  // mangled tag value. There is no assertion here that fails on the old
  // implementation, so rather than ship a test that cannot fail, the
  // corruption is stated in the commit and this covers the bound instead.
  it("refuses to parse stdout that exceeds the size bound", async () => {
    const huge = "x".repeat(8_000_001);
    const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: huge }]);
    vi.resetModules();
    vi.doMock("child_process", () => ({ spawn }));
    const { extractMediaMetadata } = await import("./ffprobe.js");

    await expect(extractMediaMetadata("/tmp/unbounded-output.mov")).rejects.toThrow(
      /exceeded 8000000 characters/,
    );
  });
});