fix(cli): consolidate snapshot and frame diagnostics (#2402)

* fix(snapshot): preserve exact requested times

* fix(cli): fail video snapshots without FFmpeg

* fix(cli): honor navigation timeout in diagnostics

* fix(cli): preserve snapshot alpha and create shot dirs

packages/cli/src/commands/snapshot.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { computeSnapshotTimes, parseZoomScale, tailFrameTime } from "./snapshot.js";
+import { readFileSync } from "node:fs";
+import {
+  computeSnapshotTimes,
+  parseZoomScale,
+  requireSnapshotFfmpeg,
+  tailFrameTime,
+} from "./snapshot.js";
 
 // --zoom's crop-region math (selector bbox + padding + clamp, exact region
 // form, no-match error) is owned by and tested in
@@ -21,6 +27,15 @@ describe("tailFrameTime", () => {
   });
 });
 
+describe("transparent snapshot capture", () => {
+  it("asks Chrome to retain the alpha channel in review PNGs", () => {
+    const source = readFileSync(new URL("./snapshot.ts", import.meta.url), "utf8");
+    expect(source).toContain(
+      'page.screenshot({ path: framePath, type: "png", omitBackground: true })',
+    );
+  });
+});
+
 describe("computeSnapshotTimes (FINDING [7]: tail is always captured)", () => {
   it("default frames: last point is the readable tail, never exact duration", () => {
     const { times, appendedTail } = computeSnapshotTimes(8, { frames: 5 });
@@ -62,6 +77,16 @@ describe("computeSnapshotTimes (FINDING [7]: tail is always captured)", () => {
     expect(times).toEqual([1, 2]);
     expect(appendedTail).toBe(false);
   });
+
+  it("preserves exact explicit transition timestamps", () => {
+    const exactTransition = 3.3666666666666667;
+    const { times } = computeSnapshotTimes(8, {
+      frames: 5,
+      at: [exactTransition],
+      includeEnd: false,
+    });
+    expect(times).toEqual([exactTransition]);
+  });
 });
 
 describe("parseZoomScale (--zoom-scale)", () => {
@@ -79,3 +104,15 @@ describe("parseZoomScale (--zoom-scale)", () => {
     expect(parseZoomScale("-1")).toBe(3);
   });
 });
+
+describe("requireSnapshotFfmpeg", () => {
+  it("rejects video snapshot extraction when FFmpeg is unavailable", () => {
+    expect(() => requireSnapshotFfmpeg(undefined)).toThrow(
+      /FFmpeg is required to extract video frames for snapshots/,
+    );
+  });
+
+  it("preserves the resolved FFmpeg executable", () => {
+    expect(requireSnapshotFfmpeg("C:\\tools\\ffmpeg.exe")).toBe("C:\\tools\\ffmpeg.exe");
+  });
+});