Skip to content

Write HTML. Render video. Built for agents.

102 KB
Raw Blame
import { runCommand } from "citty";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";

const trackCheckReport = vi.fn();
vi.mock("../telemetry/events.js", () => ({
  trackCheckReport: (...args: unknown[]) => trackCheckReport(...args),
  trackCommandFailure: vi.fn(),
}));

import { contrastRatio, parseColorRGBA } from "./contrast-bg.js";
import { createCheckCommand, parseCheckRange } from "./check.js";
import { CheckDeadlineError } from "../utils/checkDeadline.js";
import { trackCommandFailures } from "../utils/command-failure-tracking.js";
import type { CommandDef } from "citty";

// Bare `--frame-check` is rewritten by the wrapCommand gate, so run through cli.ts's wrapping.
async function runViaCli(
  command: CommandDef<any>,
  opts: Parameters<typeof runCommand>[1],
): Promise<ReturnType<typeof runCommand>> {
  const wrapped = await trackCommandFailures(() => Promise.resolve(command))();
  return runCommand(wrapped, opts);
}
import {
  DEFAULT_CHECK_OPTIONS,
  checkExitCode,
  findingCropFilename,
  runAuditGrid,
  runCheckPipeline,
  selectContrastTimes,
  selectFindingCropRequests,
  type AnchoredLayoutIssue,
  type CheckAnchor,
  type CheckAuditDriver,
  type CheckBrowserResult,
  type CheckDependencies,
  type CheckFinding,
  type CheckFindingCropRequest,
  type CheckOptions,
  type CheckReport,
  type ContrastAuditEntry,
  type MotionSpecResolution,
} from "../utils/checkPipeline.js";
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
import { consumeCommandResult } from "../utils/commandResult.js";
import { ambiguousIssue } from "../utils/motionAudit.js";
import type { ProjectLintResult } from "../utils/lintProject.js";
import type {
  LayoutIssue,
  LayoutIssueCode,
  LayoutOverflow,
  LayoutRect,
} from "../utils/layoutAudit.js";
import type { CraftFrame, SeekClock } from "../utils/checkTypes.js";
import type { ProjectDir } from "../utils/project.js";

const PROJECT: ProjectDir = {
  dir: "/project",
  name: "project",
  indexPath: "/project/index.html",
};
const PNG_BASE64 = Buffer.from("png-bytes").toString("base64");
afterEach(() => {
  consumeCommandResult();
  trackCheckReport.mockClear();
  vi.restoreAllMocks();
});

function cleanLint(): ProjectLintResult {
  return {
    results: [
      {
        file: "index.html",
        contentHash: "test",
        result: {
          ok: true,
          errorCount: 0,
          warningCount: 0,
          infoCount: 0,
          findings: [],
        },
      },
    ],
    totalErrors: 0,
    totalWarnings: 0,
    totalInfos: 0,
  };
}

function lintWith(
  severity: "error" | "warning" | "info",
  code: string,
  message: string,
): ProjectLintResult {
  return {
    results: [
      {
        file: "index.html",
        contentHash: "test",
        result: {
          ok: severity !== "error",
          errorCount: severity === "error" ? 1 : 0,
          warningCount: severity === "warning" ? 1 : 0,
          infoCount: severity === "info" ? 1 : 0,
          findings: [{ severity, code, message }],
        },
      },
    ],
    totalErrors: severity === "error" ? 1 : 0,
    totalWarnings: severity === "warning" ? 1 : 0,
    totalInfos: severity === "info" ? 1 : 0,
  };
}

function anchor(selector: string, time: number): CheckAnchor {
  return {
    selector,
    dataAttributes: { "data-layout-name": "hero" },
    sourceFile: "compositions/scene.html",
    bbox: { x: 10, y: 20, width: 300, height: 80 },
    time,
  };
}

function layoutIssue(
  severity: "error" | "warning" | "info" = "error",
  overrides: { time?: number; code?: AnchoredLayoutIssue["code"] } = {},
): AnchoredLayoutIssue {
  const time = overrides.time ?? 0.5;
  return {
    ...anchor("#hero", time),
    code: overrides.code ?? (severity === "warning" ? "content_overlap" : "clipped_text"),
    severity,
    text: "Hero",
    message: severity === "warning" ? "Text may overlap." : "Text is clipped.",
    rect: { left: 10, top: 20, right: 310, bottom: 100, width: 300, height: 80 },
  };
}

function contrastEntry(overrides: Partial<ContrastAuditEntry> = {}): ContrastAuditEntry {
  return {
    ...anchor("#hero", 0.5),
    text: "Body text",
    ratio: 2.5,
    wcagAA: false,
    large: false,
    fg: "rgb(110,110,110)",
    bg: "rgb(30,30,30)",
    ...overrides,
  };
}

// A rendered frame that is a function of the last seek, as a seek-driven film's is.
function framesOfSeekedTime(): Pick<CheckAuditDriver, "seek" | "captureFrame"> {
  let seeked = 0;
  return {
    seek: vi.fn(async (time: number) => {
      seeked = time;
    }),
    captureFrame: vi.fn(async () => `frame@${seeked}`),
  };
}

function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver {
  // A distinct string per call so the frozen-sweep guard (#U10) never fires
  // by accident in unrelated scenarios — tests that want it force a constant
  // via `collectLayoutGeometry: vi.fn(async () => "same")`.
  let geometryCallCount = 0;
  const driver: CheckAuditDriver = {
    initialize: vi.fn(async (_contrast: boolean) => undefined),
    getDuration: vi.fn(async () => 9),
    hasNoTimelineDeclaration: vi.fn(async () => false),
    getTransitionBoundaries: vi.fn(async () => []),
    getClipEdges: vi.fn(async () => []),
    getCanvas: vi.fn(async () => ({ width: 1920, height: 1080 })),
    findAmbiguousSelectors: vi.fn(async (_selectors: string[]) => []),
    seek: vi.fn(async (_time: number) => undefined),
    seekGeometry: vi.fn(async (_time: number) => undefined),
    collectLayout: vi.fn(async (_time: number, _tolerance: number) => []),
    collectOverlap: vi.fn(async (_time: number) => []),
    collectLayoutGeometry: vi.fn(async () => `geometry-${geometryCallCount++}`),
    captureFrame: vi.fn(async (_scope?: string) => "frame"),
    framesDiffer: vi.fn(async (first: string, second: string) => first !== second),
    collectSeekClock: vi.fn(async () => [{ id: 1, time: 0, done: false }]),
    collectRotationSample: vi.fn(async (_time: number) => []),
    collectOffPivotRotationSample: vi.fn(async (time: number) => ({ time, samples: [] })),
    collectGeometryCandidates: vi.fn(async () => []),
    collectMotionFrame: vi.fn(async (time: number) => ({ time, data: {}, liveness: {} })),
    anchorMotionIssues: vi.fn(async (issues: LayoutIssue[]) =>
      issues.map((issue) => ({
        ...issue,
        ...anchor(issue.selector, issue.time),
      })),
    ),
    collectContrast: vi.fn(async (_time: number) => ({ entries: [], pngBase64: PNG_BASE64 })),
    collectOverlapGrid: vi.fn(async (times: number[]) => {
      const issues: AnchoredLayoutIssue[][] = [];
      for (const time of times) {
        await driver.seekGeometry(time);
        issues.push(await driver.collectOverlap(time));
      }
      return issues;
    }),
    ...overrides,
  };
  return driver;
}

interface GeometryFixture {
  kind: "text" | "media";
  tag: string;
  text: string;
  selector: string;
  rect: LayoutRect;
  elementRect?: LayoutRect;
  time: number;
  overflow?: LayoutOverflow;
  dataAttributes?: Record<string, string>;
}

function geometryCandidate(fixture: GeometryFixture) {
  return {
    ...anchor(fixture.selector, fixture.time),
    ...(fixture.dataAttributes ? { dataAttributes: fixture.dataAttributes } : {}),
    kind: fixture.kind,
    tag: fixture.tag,
    text: fixture.text,
    rect: fixture.rect,
    elementRect: fixture.elementRect ?? fixture.rect,
    bbox: {
      x: fixture.rect.left,
      y: fixture.rect.top,
      width: fixture.rect.width,
      height: fixture.rect.height,
    },
    overflow: fixture.overflow,
  };
}

function fixtureRect(left: number, top: number, width: number, height: number): LayoutRect {
  return { left, top, right: left + width, bottom: top + height, width, height };
}

function checkBrowserSource(): string {
  return readFileSync(new URL("../utils/checkBrowser.ts", import.meta.url), "utf8");
}

async function gateCandidates(
  time: number,
  request: { text: boolean; media: boolean; tolerance: number },
) {
  const candidates = [];
  if (request.text) {
    candidates.push(
      geometryCandidate({
        kind: "text",
        tag: "h2",
        text: "Repeated heading",
        selector: time === 2 ? "#first-heading" : "#later-heading",
        rect: fixtureRect(800, 880, 320, 60),
        time,
      }),
    );
  }
  if (request.media) {
    candidates.push(
      geometryCandidate({
        kind: "media",
        tag: "video",
        text: "video",
        selector: "#midpoint-video",
        rect: fixtureRect(-140, 100, 100, 100),
        overflow: { left: 140 },
        time,
      }),
    );
  }
  return candidates;
}

function noMotion(): MotionSpecResolution {
  return { kind: "none" };
}

function heroMotionFrame(time: number, visibleAt: (time: number) => boolean) {
  return {
    time,
    data: {
      "#hero": {
        rect: { left: 10, top: 20, right: 310, bottom: 100, width: 300, height: 80 },
        opacity: visibleAt(time) ? 1 : 0,
        visible: visibleAt(time),
      },
    },
    liveness: {},
  };
}

function dependencies(
  driver: CheckAuditDriver,
  options: {
    lint?: ProjectLintResult;
    motion?: MotionSpecResolution;
    runtime?: CheckFinding[];
    writeSnapshot?: CheckDependencies["writeSnapshot"];
    captureFindingCrops?: CheckDependencies["captureFindingCrops"];
    inspectHdrAutoPromotion?: NonNullable<CheckDependencies["inspectHdrAutoPromotion"]>;
  } = {},
): { deps: CheckDependencies; runBrowserCheck: ReturnType<typeof vi.fn> } {
  const runBrowserCheck = vi.fn(
    async (
      _project: ProjectDir,
      checkOptions: CheckOptions,
      motion: MotionSpecResolution,
    ): Promise<CheckBrowserResult> => {
      const result = await runAuditGrid(driver, checkOptions, motion);
      return { ...result, runtimeFindings: options.runtime ?? [] };
    },
  );
  const deps: CheckDependencies = {
    lintProject: vi.fn(async () => options.lint ?? cleanLint()),
    resolveMotionSpec: vi.fn(() => options.motion ?? noMotion()),
    runBrowserCheck,
    writeSnapshot:
      options.writeSnapshot ??
      vi.fn((_projectDir: string, index: number, time: number, _pngBase64: string) =>
        Promise.resolve(
          `snapshots/frame-${String(index).padStart(2, "0")}-at-${time.toFixed(1)}s.png`,
        ),
      ),
    captureFindingCrops: options.captureFindingCrops ?? vi.fn(async () => []),
    inspectHdrAutoPromotion: options.inspectHdrAutoPromotion ?? vi.fn(async () => null),
  };
  return { deps, runBrowserCheck };
}

async function runScenario(
  driver: CheckAuditDriver,
  optionOverrides: Partial<CheckOptions> = {},
  dependencyOverrides: Parameters<typeof dependencies>[1] = {},
): Promise<{ report: CheckReport; deps: CheckDependencies; browser: ReturnType<typeof vi.fn> }> {
  const { deps, runBrowserCheck } = dependencies(driver, dependencyOverrides);
  const report = await runCheckPipeline(
    PROJECT,
    { ...DEFAULT_CHECK_OPTIONS, ...optionOverrides },
    deps,
  );
  return { report, deps, browser: runBrowserCheck };
}

function runtimeError(): CheckFinding {
  return {
    code: "console_error",
    severity: "error",
    message: "boom",
    ...anchor("[data-composition-id]", 0),
  };
}

describe("contrast sample selection", () => {
  it("chooses five evenly distributed grid points including both ends", () => {
    expect(selectContrastTimes([0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5])).toEqual([
      0.5, 2.5, 4.5, 6.5, 8.5,
    ]);
    expect(selectContrastTimes([1, 2, 3])).toEqual([1, 2, 3]);
  });
});

it("parses the caption-zone grammar and enables the frame gate", async () => {
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
  vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => value,
  });

  await runCommand(command, {
    rawArgs: [
      "--json",
      "--caption-zone",
      "x0=0;y0=.82;x1=1;y1=1;severity=error;seek=.25,1",
      "--frame-check",
    ],
  });

  expect(runPipeline).toHaveBeenCalledWith(
    PROJECT,
    expect.objectContaining({
      captionZone: {
        x0: 0,
        y0: 0.82,
        x1: 1,
        y1: 1,
        severity: "error",
        seek: [0.25, 1],
      },
      frameCheck: {},
    }),
  );
});

it("preserves caption-zone after bare --frame-check", async () => {
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
  vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => value,
  });

  await runViaCli(command, {
    rawArgs: [
      "--frame-check",
      "--caption-zone",
      "x0=0;y0=.82;x1=1;y1=1;severity=error;seek=.25,1",
      "--json",
    ],
  });

  expect(runPipeline).toHaveBeenCalledWith(
    PROJECT,
    expect.objectContaining({
      captionZone: {
        x0: 0,
        y0: 0.82,
        x1: 1,
        y1: 1,
        severity: "error",
        seek: [0.25, 1],
      },
      frameCheck: {},
    }),
  );
});

it("preserves --json after bare --frame-check", async () => {
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
  const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => value,
  });

  await runViaCli(command, {
    rawArgs: ["--snapshots", "--samples", "15", "--frame-check", "--json"],
  });

  expect(runPipeline).toHaveBeenCalledWith(
    PROJECT,
    expect.objectContaining({
      samples: 15,
      snapshots: true,
      frameCheck: {},
    }),
  );
  expect(log).toHaveBeenCalledWith(expect.stringContaining('"ok"'));
});

it("prints a dash-prefixed --frame-check value's parse failure exactly once, not doubled", async () => {
  // run()'s own try/catch prints parseFrameCheck's error, so the throw site must not print too.
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
  const errorLog = vi.spyOn(console, "error").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => value,
  });

  await runViaCli(command, { rawArgs: ["--frame-check=--json"] });

  expect(runPipeline).not.toHaveBeenCalled();
  const matching = errorLog.mock.calls.filter(
    ([arg]) => typeof arg === "string" && arg.includes("Missing value for --frame-check"),
  );
  expect(matching).toHaveLength(1);
});

it("no longer swallows --json after a --layout value (the wider bug class beyond --frame-check)", async () => {
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
  const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => value,
  });

  await expect(runViaCli(command, { rawArgs: ["--layout", "--json"] })).rejects.toThrow(
    /Missing value for --layout/,
  );

  expect(runPipeline).not.toHaveBeenCalled();
  expect(log).not.toHaveBeenCalled();
});

it("includes local HDR auto-promotion attribution in --json output", async () => {
  const { report } = await runScenario(
    fakeDriver(),
    {},
    {
      inspectHdrAutoPromotion: vi.fn(async () => ({
        triggeringAsset: "assets/source-hdr.mp4",
        output: { colorSpace: "BT.2020", codec: "HEVC Main10" } as const,
      })),
    },
  );
  const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline: vi.fn(async () => report),
    withMeta: (value) => value,
  });

  await runCommand(command, { rawArgs: ["--json"] });

  expect(log).toHaveBeenCalledTimes(1);
  expect(JSON.parse(String(log.mock.calls[0]?.[0])).hdr.autoPromotion).toEqual({
    triggeringAsset: "assets/source-hdr.mp4",
    output: { colorSpace: "BT.2020", codec: "HEVC Main10" },
  });
});

it("distinguishes unavailable HDR inspection from no promotion", async () => {
  const { report } = await runScenario(
    fakeDriver(),
    {},
    {
      inspectHdrAutoPromotion: vi.fn(async () => Promise.reject(new Error("ffprobe unavailable"))),
    },
  );

  expect(report.hdr).toEqual({ autoPromotion: null, inspection: "unavailable" });
});

it("threads --no-proxy into the browser check options", async () => {
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
  vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => value,
  });

  await runCommand(command, { rawArgs: ["--json", "--no-proxy"] });

  expect(runPipeline).toHaveBeenCalledWith(PROJECT, expect.objectContaining({ autoProxy: false }));
});

it("waits for the project lock declared in HF_TOOL_CONTEXT before running the pipeline", async () => {
  const dir = mkdtempSync(join(tmpdir(), "hf-check-lock-"));
  const lock = join(dir, ".hyperframes", "project.lock");
  mkdirSync(join(dir, ".hyperframes"));
  writeFileSync(lock, JSON.stringify({ pid: process.pid, command: "snapshot", startedAt: 1 }));
  vi.stubEnv(
    "HF_TOOL_CONTEXT",
    JSON.stringify({ version: 1, capabilities: { "project-lock": { waitMs: 0 } } }),
  );
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async () => report);
  const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => ({ ...PROJECT, dir }),
    runPipeline,
    withMeta: (value) => value,
  });
  try {
    await runCommand(command, { rawArgs: ["--json"] });
    expect(runPipeline).not.toHaveBeenCalled();
    expect(consumeCommandResult().exitCode).toBe(1);
    expect(String(log.mock.calls[0]?.[0])).toContain("hyperframes snapshot");
  } finally {
    vi.unstubAllEnvs();
    rmSync(dir, { recursive: true, force: true });
  }
});

it("rejects malformed caption-zone specs instead of silently disabling the gate", async () => {
  const { report } = await runScenario(fakeDriver());
  const runPipeline = vi.fn(async () => report);
  const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
  const command = createCheckCommand({
    resolveProject: () => PROJECT,
    runPipeline,
    withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
  });

  await runCommand(command, {
    rawArgs: ["--json", "--caption-zone", "x0=0;y0=.8;x1=1;y1=1.2"],
  });

  expect(runPipeline).not.toHaveBeenCalled();
  expect(consumeCommandResult().exitCode).toBe(1);
  expect(log).toHaveBeenCalledTimes(1);
  expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toEqual({
    ok: false,
    error: expect.stringContaining("Invalid --caption-zone"),
    _meta: { version: "test" },
  });
});

it("flags text whose DOM box overlaps the caption band at the default end seek", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Centered title",
      selector: "#centered",
      rect: fixtureRect(860, 870, 200, 60),
      time,
    }),
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Overlap only",
      selector: "#overlap-only",
      rect: fixtureRect(860, 830, 200, 60),
      time,
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({
      getDuration: vi.fn(async () => 10),
      collectGeometryCandidates,
    }),
    {
      samples: 1,
      contrast: false,
      captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 0.9 },
    },
  );

  expect(collectGeometryCandidates).toHaveBeenCalledTimes(1);
  expect(collectGeometryCandidates).toHaveBeenCalledWith(10, {
    text: true,
    media: false,
    tolerance: 2,
  });
  expect(report.layout.samples).toEqual([5, 10]);
  expect(report.layout.findings).toEqual([
    expect.objectContaining({
      code: "caption_zone_collision",
      severity: "warning",
      selector: "#centered",
      text: "Centered title",
      time: 10,
    }),
    expect.objectContaining({
      code: "caption_zone_collision",
      severity: "warning",
      selector: "#overlap-only",
      text: "Overlap only",
      time: 10,
    }),
  ]);
  expect(report.ok).toBe(true);
});

it("rejects a 1920×1080 card centered at y=.860 that overlaps the 5% keepout", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Demand card",
      selector: "#at-860",
      rect: fixtureRect(200, 889, 400, 80),
      time,
    }),
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Clear above keepout",
      selector: "#tiny-860",
      rect: fixtureRect(200, 919, 400, 20),
      time,
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({
      getDuration: vi.fn(async () => 10),
      collectGeometryCandidates,
    }),
    {
      samples: 1,
      contrast: false,
      captionZone: { x0: 0.118, y0: 0.875, x1: 0.882, y1: 0.925, severity: "error" },
    },
  );

  expect(report.layout.findings).toEqual([
    expect.objectContaining({
      code: "caption_zone_collision",
      severity: "error",
      selector: "#at-860",
    }),
  ]);
  expect(report.ok).toBe(false);
});

it("skips caption_zone_collision when data-layout-allow-caption-zone is set", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Intentional lower third",
      selector: "#lower-third",
      rect: fixtureRect(860, 870, 200, 60),
      time,
      dataAttributes: { "data-layout-allow-caption-zone": "" },
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({ getDuration: vi.fn(async () => 10), collectGeometryCandidates }),
    { samples: 1, contrast: false, captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 0.9 } },
  );

  expect(report.layout.findings).toEqual([]);
});

it("keeps overlap waivers from suppressing changelog caption-rail collisions", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Release card copy",
      selector: "#release-card",
      rect: fixtureRect(120, 970, 840, 118),
      time,
      dataAttributes: { "data-layout-allow-overlap": "" },
    }),
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Intentional caption rail",
      selector: "#cap-line",
      rect: fixtureRect(0, 990, 1080, 52),
      time,
      dataAttributes: { "data-layout-allow-caption-zone": "" },
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({
      getCanvas: vi.fn(async () => ({ width: 1080, height: 1080 })),
      collectGeometryCandidates,
    }),
    {
      samples: 1,
      contrast: false,
      captionZone: { x0: 0, y0: 0.9, x1: 1, y1: 1, severity: "error" },
    },
  );

  expect(report.layout.findings).toEqual([
    expect.objectContaining({
      code: "caption_zone_collision",
      severity: "error",
      selector: "#release-card",
    }),
  ]);
  expect(report.ok).toBe(false);
});

it("skips full-frame and tiny wrappers when measuring the caption box", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "text",
      tag: "div",
      text: "Full-frame wrapper copy",
      selector: "#full-frame-wrapper",
      rect: fixtureRect(860, 870, 200, 60),
      elementRect: fixtureRect(0, 0, 1920, 1080),
      time,
    }),
    geometryCandidate({
      kind: "text",
      tag: "span",
      text: "Tiny wrapper copy",
      selector: "#tiny-wrapper",
      rect: fixtureRect(860, 870, 200, 60),
      elementRect: fixtureRect(860, 870, 3, 3),
      time,
    }),
  ]);
  const { report } = await runScenario(fakeDriver({ collectGeometryCandidates }), {
    contrast: false,
    captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 0.9 },
  });

  expect(report.layout.findings).toEqual([]);
});

it("checks media overflow at the default midpoint and applies warning severity", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "media",
      tag: "img",
      text: "img",
      selector: "#hero-image",
      rect: fixtureRect(1840, 100, 220, 200),
      overflow: { right: 140 },
      time,
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({ getDuration: vi.fn(async () => 10), collectGeometryCandidates }),
    { samples: 1, contrast: false, frameCheck: {} },
  );

  expect(collectGeometryCandidates).toHaveBeenCalledWith(5, {
    text: false,
    media: true,
    tolerance: 2,
  });
  expect(report.layout.findings[0]).toMatchObject({
    code: "frame_out_of_frame",
    severity: "warning",
    selector: "#hero-image",
    overflow: { right: 140 },
    time: 5,
  });
});

it("converts progress seeks to time, gates each collector, and keeps distinct caption elements", async () => {
  const collectGeometryCandidates = vi.fn(gateCandidates);
  const { report } = await runScenario(
    fakeDriver({
      getDuration: vi.fn(async () => 8),
      collectGeometryCandidates,
    }),
    {
      samples: 1,
      contrast: false,
      captionZone: {
        x0: 0,
        y0: 0.8,
        x1: 1,
        y1: 0.9,
        severity: "error",
        seek: [0.25, 0.75],
      },
      frameCheck: { severity: "error" },
    },
  );

  expect(report.layout.samples).toEqual([2, 4, 6]);
  expect(collectGeometryCandidates.mock.calls).toEqual([
    [2, { text: true, media: false, tolerance: 2 }],
    [4, { text: false, media: true, tolerance: 2 }],
    [6, { text: true, media: false, tolerance: 2 }],
  ]);
  expect(report.layout.findings).toEqual([
    expect.objectContaining({
      code: "caption_zone_collision",
      severity: "error",
      selector: "#first-heading",
      time: 2,
    }),
    expect.objectContaining({ code: "frame_out_of_frame", severity: "error", time: 4 }),
    expect.objectContaining({
      code: "caption_zone_collision",
      severity: "error",
      selector: "#later-heading",
      time: 6,
      times: [6],
    }),
  ]);
  expect(report.ok).toBe(false);
});

it("does not collect or emit opt-in geometry findings when both flags are off", async () => {
  const collectGeometryCandidates = vi.fn(async () => [
    geometryCandidate({
      kind: "media",
      tag: "video",
      text: "video",
      selector: "#video",
      rect: fixtureRect(1900, 0, 200, 200),
      overflow: { right: 180 },
      time: 4.5,
    }),
  ]);
  const { report } = await runScenario(fakeDriver({ collectGeometryCandidates }), {
    contrast: false,
  });

  expect(collectGeometryCandidates).not.toHaveBeenCalled();
  expect(JSON.stringify(report)).not.toContain("caption_zone_collision");
  expect(JSON.stringify(report)).not.toContain("frame_out_of_frame");
});

it("computes caption bands from a portrait composition viewport", async () => {
  const viewport = resolveCompositionViewportFromHtml(
    '<div data-composition-id="portrait" data-width="1080" data-height="1920"></div>',
  );
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "text",
      tag: "p",
      text: "Portrait caption collision",
      selector: "#portrait-copy",
      rect: fixtureRect(480, 1570, 120, 60),
      time,
    }),
  ]);
  const getCanvas = vi.fn(async () => viewport);
  const { report } = await runScenario(
    fakeDriver({
      getDuration: vi.fn(async () => 4),
      getCanvas,
      collectGeometryCandidates,
    }),
    {
      samples: 1,
      contrast: false,
      captionZone: { x0: 0.4, y0: 0.8, x1: 0.6, y1: 0.9 },
    },
  );

  expect(viewport).toEqual({ width: 1080, height: 1920 });
  expect(getCanvas).toHaveBeenCalled();
  expect(report.layout.findings).toEqual([
    expect.objectContaining({ code: "caption_zone_collision", selector: "#portrait-copy" }),
  ]);
});

it("suppresses frame breaches below the per-canvas floor and reports those above it", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "media",
      tag: "canvas",
      text: "canvas",
      selector: "#under-floor",
      rect: fixtureRect(3980, 100, 199, 100),
      overflow: { right: 179 },
      time,
    }),
    geometryCandidate({
      kind: "media",
      tag: "canvas",
      text: "canvas",
      selector: "#over-floor",
      rect: fixtureRect(3980, 300, 201, 100),
      overflow: { right: 181 },
      time,
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({
      getCanvas: vi.fn(async () => ({ width: 4000, height: 3000 })),
      collectGeometryCandidates,
    }),
    {
      contrast: false,
      frameCheck: {},
    },
  );

  expect(report.layout.findings).toEqual([
    expect.objectContaining({
      code: "frame_out_of_frame",
      selector: "#over-floor",
      overflow: { right: 181 },
    }),
  ]);
});

it("reports one moving element rule with both requested seek times", async () => {
  const collectGeometryCandidates = vi.fn(async (time: number) => [
    geometryCandidate({
      kind: "media",
      tag: "img",
      text: "img",
      selector: "#moving-image",
      rect: fixtureRect(1920, time === 2 ? 100 : 300, 130, 100),
      overflow: { right: 130 },
      time,
    }),
  ]);
  const { report } = await runScenario(
    fakeDriver({
      getDuration: vi.fn(async () => 8),
      collectGeometryCandidates,
    }),
    {
      samples: 1,
      contrast: false,
      frameCheck: { seek: [0.25, 0.75] },
    },
  );

  expect(report.layout.findings).toEqual([
    expect.objectContaining({
      code: "frame_out_of_frame",
      time: 2,
      times: [2, 6],
      firstSeen: 2,
      lastSeen: 6,
      occurrences: 2,
      heldMs: 0,
      bbox: { x: 1920, y: 100, width: 130, height: 100 },
    }),
  ]);
});

it("keeps contrast and snapshot sampling on the pre-gate layout grid", async () => {
  const collectContrast = vi.fn(async () => ({ entries: [], pngBase64: PNG_BASE64 }));
  const { report } = await runScenario(
    fakeDriver({
      getDuration: vi.fn(async () => 10),
      collectContrast,
    }),
    {
      samples: 1,
      captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 1 },
    },
  );

  expect(report.layout.samples).toEqual([5, 10]);
  expect(report.contrast.samples).toEqual([5]);
  expect(collectContrast).toHaveBeenCalledTimes(1);
  expect(collectContrast).toHaveBeenCalledWith(5);
});

it("waits for paint only on the grid seeks a contrast screenshot follows", async () => {
  const driver = fakeDriver({ getDuration: vi.fn(async () => 10) });
  await runScenario(driver, { samples: 1, captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 1 } });

  expect(vi.mocked(driver.seek).mock.calls).toEqual([
    [5, true],
    [10, false],
  ]);
});

function layoutFindingOf(
  code: LayoutIssueCode,
  severity: "error" | "warning" | "info",
  bbox: { x: number; y: number; width: number; height: number },
  time = 1,
): AnchoredLayoutIssue {
  return {
    code,
    severity,
    message: code,
    ...anchor("#el", time),
    bbox,
    rect: {
      left: bbox.x,
      top: bbox.y,
      right: bbox.x + bbox.width,
      bottom: bbox.y + bbox.height,
      ...bbox,
    },
  };
}

function checkFindingOf(
  code: string,
  severity: "error" | "warning" | "info",
  bbox: { x: number; y: number; width: number; height: number },
  time = 1,
): CheckFinding {
  return { code, severity, message: code, ...anchor("#el", time), bbox };
}

function emptySection<T extends CheckFinding>(findings: T[] = []) {
  return { ok: true, errorCount: 0, warningCount: 0, infoCount: 0, findings };
}

function reportWithFindings(overrides: Partial<CheckReport> = {}): CheckReport {
  return {
    ok: true,
    strict: false,
    browserSkipped: false,
    lint: { ...emptySection(), filesScanned: 0 },
    runtime: emptySection(),
    layout: {
      ...emptySection(),
      duration: 10,
      samples: [],
      transitionSamples: [],
      transitionSamplesDropped: 0,
      tolerance: 2,
      totalIssueCount: 0,
      truncated: false,
    },
    motion: { ...emptySection(), enabled: false, samples: 0 },
    contrast: { ...emptySection(), enabled: true, samples: [], checked: 0, passed: 0 },
    craft: { ...emptySection(), enabled: false, step: 0, samples: 0 },
    hdr: { autoPromotion: null, inspection: "available" },
    snapshots: { enabled: false, files: [], times: [], findingFiles: [] },
    ...overrides,
  };
}

describe("selectFindingCropRequests", () => {
  const NON_ZERO_BBOX = { x: 10, y: 20, width: 100, height: 50 };
  const ZERO_BBOX = { x: 0, y: 0, width: 0, height: 0 };

  it("filenames a request finding-NN-<code>.png with the finding's time and bbox", () => {
    const report = reportWithFindings({
      layout: {
        ...reportWithFindings().layout,
        findings: [layoutFindingOf("clipped_text", "error", NON_ZERO_BBOX, 2.5)],
      },
    });

    expect(selectFindingCropRequests(report)).toEqual([
      { filename: "finding-00-clipped_text.png", time: 2.5, bbox: NON_ZERO_BBOX },
    ]);
  });

  it("skips warnings/info and findings without a real bbox", () => {
    const report = reportWithFindings({
      layout: {
        ...reportWithFindings().layout,
        findings: [
          layoutFindingOf("content_overlap", "warning", NON_ZERO_BBOX),
          layoutFindingOf("clipped_text", "error", ZERO_BBOX),
        ],
      },
      runtime: { ...emptySection([checkFindingOf("console_error", "info", NON_ZERO_BBOX)]) },
    });

    expect(selectFindingCropRequests(report)).toEqual([]);
  });

  it("caps at 12 requests across sections", () => {
    const findings = Array.from({ length: 15 }, (_, index) =>
      checkFindingOf(`code_${index}`, "error", NON_ZERO_BBOX, index),
    );
    const report = reportWithFindings({
      runtime: { ...emptySection(findings) },
    });

    const requests = selectFindingCropRequests(report);
    expect(requests).toHaveLength(12);
    expect(requests[0]?.filename).toBe(findingCropFilename(0, "code_0"));
    expect(requests[11]?.filename).toBe(findingCropFilename(11, "code_11"));
  });

  it("sanitizes unusual characters out of the code when building a filename", () => {
    expect(findingCropFilename(3, "weird code/name")).toBe("finding-03-weird_code_name.png");
  });
});

describe("check pipeline", () => {
  afterEach(() => {
    consumeCommandResult();
    vi.restoreAllMocks();
  });

  it("emits one clean JSON envelope with every section and exit 0", async () => {
    const { report } = await runScenario(fakeDriver());
    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
    const command = createCheckCommand({
      resolveProject: () => PROJECT,
      runPipeline: vi.fn(async () => report),
      withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
    });

    await runCommand(command, { rawArgs: ["--json"] });

    expect(report.ok).toBe(true);
    expect(checkExitCode(report)).toBe(0);
    expect(consumeCommandResult().exitCode).toBe(0);
    expect(log).toHaveBeenCalledTimes(1);
    const output = log.mock.calls[0]?.[0];
    expect(typeof output).toBe("string");
    if (typeof output !== "string") throw new Error("expected JSON output");
    const envelope = JSON.parse(output);
    expect(envelope).toMatchObject({
      ok: true,
      browserSkipped: false,
      lint: { ok: true },
      runtime: { ok: true },
      layout: { ok: true },
      motion: { ok: true },
      contrast: { ok: true },
      snapshots: { enabled: false },
      _meta: { version: "test" },
    });
  });

  it("short-circuits on lint errors without launching a browser, and flags the skipped sections", async () => {
    const lint = lintWith(
      "error",
      "root_missing_composition_id",
      "Root element needs data-composition-id.",
    );
    const { report, browser } = await runScenario(fakeDriver(), {}, { lint });

    expect(report.ok).toBe(false);
    expect(checkExitCode(report)).toBe(1);
    expect(report.lint.findings).toHaveLength(1);
    expect(browser).not.toHaveBeenCalled();
    // The browser sections look clean either way; only browserSkipped tells them apart.
    expect(report.browserSkipped).toBe(true);
    expect(report.runtime).toMatchObject({ ok: true, errorCount: 0, findings: [] });
    expect(report.layout).toMatchObject({ ok: true, errorCount: 0, findings: [], duration: 0 });
    expect(report.motion).toMatchObject({ ok: true, errorCount: 0, findings: [] });
    expect(report.contrast).toMatchObject({ ok: true, errorCount: 0, findings: [] });
  });

  it("marks browserSkipped true when the linter itself crashes", async () => {
    const { deps } = dependencies(fakeDriver());
    deps.lintProject = vi.fn(async () => {
      throw new Error("unreadable index.html");
    });
    const report = await runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);

    expect(report.ok).toBe(false);
    expect(report.browserSkipped).toBe(true);
    expect(report.runtime.findings[0]?.code).toBe("check_lint_failure");
  });

  it.each([
    { lint: cleanLint(), handed: true },
    { lint: lintWith("error", "lint_error", "Lint error."), handed: false },
  ])(
    "closes the browser started during lint unless the browser pass took it",
    async ({ lint, handed }) => {
      const prelaunched = {
        launched: Promise.resolve(undefined),
        take: vi.fn(async () => undefined),
        discard: vi.fn(async () => undefined),
      };
      const { deps, runBrowserCheck } = dependencies(fakeDriver(), { lint });
      deps.prelaunchBrowser = vi.fn(async () => prelaunched);
      await runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);

      expect(runBrowserCheck.mock.calls.map((call) => call[4])).toEqual(
        handed ? [prelaunched] : [],
      );
      expect(prelaunched.discard).toHaveBeenCalledTimes(1);
    },
  );

  it("marks browserSkipped false once a browser session actually runs", async () => {
    const { report } = await runScenario(fakeDriver());
    expect(report.browserSkipped).toBe(false);
  });

  it("marks browserSkipped true when the browser session throws before producing results", async () => {
    const { deps } = dependencies(fakeDriver());
    deps.runBrowserCheck = vi.fn(async () => {
      throw new Error("Chrome launch failed");
    });
    const report = await runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);

    expect(report.ok).toBe(false);
    expect(report.browserSkipped).toBe(true);
    expect(report.runtime.findings).toHaveLength(1);
    expect(report.layout).toMatchObject({ ok: true, errorCount: 0, findings: [] });
  });

  it("gates AA contrast failures and --no-contrast skips the pass", async () => {
    const failingContrast = vi.fn(async (time: number) => ({
      entries: time === 0.5 ? [contrastEntry()] : [],
      pngBase64: PNG_BASE64,
    }));
    const { report } = await runScenario(fakeDriver({ collectContrast: failingContrast }));
    expect(report.ok).toBe(false);
    expect(checkExitCode(report)).toBe(1);
    expect(report.contrast.errorCount).toBe(1);

    const skippedContrast = vi.fn(async () => ({
      entries: [contrastEntry()],
      pngBase64: PNG_BASE64,
    }));
    const skipped = await runScenario(fakeDriver({ collectContrast: skippedContrast }), {
      contrast: false,
    });
    expect(skipped.report.ok).toBe(true);
    expect(checkExitCode(skipped.report)).toBe(0);
    expect(skipped.report.contrast.enabled).toBe(false);
    expect(skippedContrast).not.toHaveBeenCalled();
  });

  it("includes measured colors, thresholds, and a passing palette-direction suggestion", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectContrast: vi.fn(async () => ({
          entries: [contrastEntry()],
          pngBase64: PNG_BASE64,
        })),
      }),
    );
    const finding = report.contrast.findings[0];
    expect(finding).toMatchObject({
      fg: "rgb(110,110,110)",
      bg: "rgb(30,30,30)",
      ratio: 2.5,
      requiredRatio: 4.5,
    });
    if (!finding) throw new Error("expected contrast finding");
    const suggested = parseColorRGBA(finding.suggestedColor);
    const background = parseColorRGBA(finding.bg);
    expect(suggested).not.toBeNull();
    expect(background).not.toBeNull();
    if (!suggested || !background) throw new Error("expected parseable colors");
    expect(
      contrastRatio(
        [suggested[0], suggested[1], suggested[2]],
        [background[0], background[1], background[2]],
      ),
    ).toBeGreaterThanOrEqual(finding.requiredRatio);
    expect(suggested[0]).toBeGreaterThan(110);
  });

  it("preserves a resolving selector, source file, identity, bbox, and sample time", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
      }),
    );
    expect(report.layout.findings[0]).toMatchObject({
      selector: "#hero",
      dataAttributes: { "data-layout-name": "hero" },
      sourceFile: "compositions/scene.html",
      bbox: { x: 10, y: 20, width: 300, height: 80 },
      time: 0.5,
    });
  });

  it("reports layout and runtime errors from one browser session", async () => {
    const { report, browser } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
      }),
      {},
      { runtime: [runtimeError()] },
    );
    expect(report.runtime.errorCount).toBe(1);
    expect(report.layout.errorCount).toBe(1);
    expect(browser).toHaveBeenCalledTimes(1);
  });

  it("still audits layout when the motion sidecar is invalid", async () => {
    const motion: MotionSpecResolution = {
      kind: "invalid",
      path: "/project/index.motion.json",
      message: 'assertions[0] (staysInFrame): "selector" must be a non-empty string',
    };
    const driver = fakeDriver({
      collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
    });
    const { report, browser } = await runScenario(driver, {}, { motion });

    expect(browser).toHaveBeenCalledTimes(1);
    expect(report.layout.findings.length).toBeGreaterThan(0);
    expect(report.motion.findings).toEqual([
      expect.objectContaining({ code: "motion_spec_invalid", severity: "error" }),
    ]);
    expect(report.motion).toMatchObject({
      enabled: true,
      specPath: "/project/index.motion.json",
      samples: 0,
    });
    expect(report.ok).toBe(false);
  });

  it("does not sample motion for an invalid sidecar", async () => {
    const motion: MotionSpecResolution = {
      kind: "invalid",
      path: "/project/index.motion.json",
      message: "version 2 is not supported",
    };
    const driver = fakeDriver();
    const { report } = await runScenario(driver, {}, { motion });

    expect(report.motion.samples).toBe(0);
    expect(driver.collectMotionFrame).not.toHaveBeenCalled();
  });

  it("keeps evaluating the unambiguous assertions when one selector is ambiguous", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: {
        assertions: [
          { kind: "appearsBy", selector: ".item", bySec: 1 },
          { kind: "appearsBy", selector: "#hero", bySec: 0.2 },
        ],
      },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      findAmbiguousSelectors: vi.fn(async () => [
        { ...layoutIssue("error", { code: "motion_selector_ambiguous" }), selector: ".item" },
      ]),
      collectMotionFrame: vi.fn(async (time: number) => heroMotionFrame(time, (t) => t >= 0.5)),
    });
    const { report } = await runScenario(driver, {}, { motion });

    expect(report.motion.samples).toBeGreaterThan(0);
    expect(report.motion.findings.map((finding) => finding.code).sort()).toEqual([
      "motion_appears_late",
      "motion_selector_ambiguous",
    ]);
    expect(report.ok).toBe(false);
    expect(
      report.motion.findings.find((finding) => finding.code === "motion_selector_ambiguous")
        ?.message,
    ).toContain("1 assertion(s) naming it were not evaluated");
    expect(driver.collectMotionFrame).toHaveBeenCalledWith(expect.any(Number), ["#hero"], []);
  });

  it("separates the ambiguity message from the skipped-assertion count", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: { assertions: [{ kind: "appearsBy", selector: ".item", bySec: 1 }] },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      findAmbiguousSelectors: vi.fn(async () => [
        { ...layoutIssue("error"), ...ambiguousIssue(".item") },
      ]),
    });
    const { report } = await runScenario(driver, {}, { motion });

    const message = report.motion.findings.find(
      (finding) => finding.code === "motion_selector_ambiguous",
    )?.message;
    expect(message).toContain("exactly one. 1 assertion(s)");
  });

  it("counts skipped assertions per ambiguous selector, not across all of them", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: {
        assertions: [
          { kind: "appearsBy", selector: ".item", bySec: 1 },
          { kind: "appearsBy", selector: ".card", bySec: 1 },
          { kind: "appearsBy", selector: ".card", bySec: 2 },
        ],
      },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      findAmbiguousSelectors: vi.fn(async () => [
        { ...layoutIssue("error", { code: "motion_selector_ambiguous" }), selector: ".item" },
        { ...layoutIssue("error", { code: "motion_selector_ambiguous" }), selector: ".card" },
      ]),
    });
    const { report } = await runScenario(driver, {}, { motion });

    const messages = report.motion.findings
      .filter((finding) => finding.code === "motion_selector_ambiguous")
      .map((finding) => finding.message);
    expect(messages.filter((m) => m.includes("1 assertion(s) naming it"))).toHaveLength(1);
    expect(messages.filter((m) => m.includes("2 assertion(s) naming it"))).toHaveLength(1);
  });

  it("drops a before assertion when either side is ambiguous, keeping the rest", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: {
        assertions: [
          { kind: "before", a: "#hero", b: ".item" },
          { kind: "appearsBy", selector: "#hero", bySec: 0.2 },
        ],
      },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      findAmbiguousSelectors: vi.fn(async () => [
        { ...layoutIssue("error", { code: "motion_selector_ambiguous" }), selector: ".item" },
      ]),
      collectMotionFrame: vi.fn(async (time: number) => heroMotionFrame(time, (t) => t >= 0.5)),
    });
    const { report } = await runScenario(driver, {}, { motion });

    expect(report.motion.findings.map((finding) => finding.code).sort()).toEqual([
      "motion_appears_late",
      "motion_selector_ambiguous",
    ]);
    expect(driver.collectMotionFrame).toHaveBeenCalledWith(expect.any(Number), ["#hero"], []);
  });

  it("does not sample when every assertion names an ambiguous selector", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: { assertions: [{ kind: "appearsBy", selector: ".item", bySec: 1 }] },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      findAmbiguousSelectors: vi.fn(async () => [
        { ...layoutIssue("error", { code: "motion_selector_ambiguous" }), selector: ".item" },
      ]),
    });
    const { report } = await runScenario(driver, {}, { motion });

    expect(report.motion.samples).toBe(0);
    expect(report.motion.findings.map((finding) => finding.code)).toEqual([
      "motion_selector_ambiguous",
    ]);
  });

  it("reports a failing appearsBy sidecar as motion_appears_late", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: { assertions: [{ kind: "appearsBy", selector: "#hero", bySec: 0.2 }] },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      collectMotionFrame: vi.fn(async (time: number) => heroMotionFrame(time, (t) => t >= 0.5)),
    });
    const { report } = await runScenario(driver, {}, { motion });

    expect(report.motion.findings).toEqual([
      expect.objectContaining({
        code: "motion_appears_late",
        severity: "error",
        selector: "#hero",
      }),
    ]);
    expect(report.ok).toBe(false);
  });

  it("writes cached contrast PNGs only with --snapshots at the contrast timestamps", async () => {
    const writer = vi.fn(
      async (_projectDir: string, index: number, time: number, _pngBase64: string) =>
        `snapshots/frame-${String(index).padStart(2, "0")}-at-${time.toFixed(1)}s.png`,
    );
    const captured = fakeDriver({
      collectContrast: vi.fn(async () => ({ entries: [], pngBase64: PNG_BASE64 })),
    });
    const { report } = await runScenario(captured, { snapshots: true }, { writeSnapshot: writer });

    expect(report.snapshots.times).toEqual([0.5, 2.5, 4.5, 6.5, 8.5]);
    expect(report.snapshots.files).toEqual([
      "snapshots/frame-00-at-0.5s.png",
      "snapshots/frame-01-at-2.5s.png",
      "snapshots/frame-02-at-4.5s.png",
      "snapshots/frame-03-at-6.5s.png",
      "snapshots/frame-04-at-8.5s.png",
    ]);
    expect(writer).toHaveBeenCalledTimes(5);

    const absentWriter = vi.fn(async () => "unused.png");
    await runScenario(fakeDriver(), { snapshots: false }, { writeSnapshot: absentWriter });
    expect(absentWriter).not.toHaveBeenCalled();
  });

  it("captures finding crops for error findings with bboxes only when --snapshots is set", async () => {
    const capture = vi.fn(
      async (
        _project: ProjectDir,
        _options: CheckOptions,
        _requests: CheckFindingCropRequest[],
      ) => ["snapshots/finding-00-clipped_text.png"],
    );
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
      }),
      { snapshots: true },
      { captureFindingCrops: capture },
    );

    expect(capture).toHaveBeenCalledTimes(1);
    expect(capture.mock.calls[0]?.[2]).toEqual([
      {
        filename: "finding-00-clipped_text.png",
        time: 0.5,
        bbox: { x: 10, y: 20, width: 300, height: 80 },
      },
    ]);
    expect(report.snapshots.findingFiles).toEqual(["snapshots/finding-00-clipped_text.png"]);

    const withoutSnapshots = vi.fn(async () => ["unused.png"]);
    await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
      }),
      { snapshots: false },
      { captureFindingCrops: withoutSnapshots },
    );
    expect(withoutSnapshots).not.toHaveBeenCalled();

    const noErrors = vi.fn(async () => ["unused.png"]);
    await runScenario(
      fakeDriver({
        collectLayout: vi.fn(
          async (time: number) =>
            // container_overflow, not content_overlap: this fixture wants a plain
            // warning-severity finding held across the whole run, unaffected by
            // content_overlap's #U10 held-duration re-promotion to error.
            [layoutIssue("warning", { time, code: "container_overflow" })],
        ),
      }),
      { snapshots: true },
      { captureFindingCrops: noErrors },
    );
    expect(noErrors).not.toHaveBeenCalled();
  });

  it("reports the total deadline during crops while retaining the audit failure", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
      }),
      { snapshots: true },
      {
        captureFindingCrops: async () => {
          throw new CheckDeadlineError();
        },
      },
    );
    expect(report.ok).toBe(false);
    expect(report.layout.errorCount).toBeGreaterThan(0);
    expect(report.runtime.findings).toContainEqual(
      expect.objectContaining({
        code: "check_runtime_failure",
        message: "Check did not finish within its deadline.",
      }),
    );
  });

  it("a deadline that fires in the overlap pass names that pass in its finding", async () => {
    vi.useFakeTimers();
    try {
      let aborted!: AbortSignal;
      const driver = fakeDriver({
        collectOverlapGrid: vi.fn(
          () =>
            new Promise<never>((_, reject) =>
              aborted.addEventListener("abort", () => reject(aborted.reason)),
            ),
        ),
      });
      const { deps } = dependencies(driver);
      deps.runBrowserCheck = async (_project, options, motion, deadline) => {
        aborted = deadline!.signal;
        deadline!.start();
        return runAuditGrid(driver, options, motion, undefined, deadline!.enter);
      };
      const pending = runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);
      await vi.advanceTimersByTimeAsync(120_000);
      const report = await pending;
      const failure = report.runtime.findings.find(
        (finding) => finding.code === "check_runtime_failure",
      );
      expect(failure?.message).toMatch(/^Check did not finish within its deadline/);
      expect(failure?.message).toContain("while running the overlap pass.");
      expect(failure?.message).toContain("checking samples 0.0, running the overlap pass 120.0.");
    } finally {
      vi.useRealTimers();
    }
  });

  it("--strict flips a warnings-only result from exit 0 to exit 1", async () => {
    const warningDriver = () =>
      fakeDriver({
        collectLayout: vi.fn(
          async (time: number) =>
            // container_overflow, not content_overlap: this fixture wants a plain
            // warning-severity finding held across the whole run, unaffected by
            // content_overlap's #U10 held-duration re-promotion to error.
            [layoutIssue("warning", { time, code: "container_overflow" })],
        ),
      });
    const normal = await runScenario(warningDriver(), { strict: false });
    const strict = await runScenario(warningDriver(), { strict: true });

    expect(checkExitCode(normal.report)).toBe(0);
    expect(checkExitCode(strict.report)).toBe(1);
  });

  it("splits samples over a helper page and returns what one page seeking every sample returns", async () => {
    const pageOfTime = () => {
      let seeked = 0;
      return fakeDriver({
        seek: vi.fn(async (time: number) => {
          seeked = time;
        }),
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
        collectLayoutGeometry: vi.fn(async () => `geometry-${seeked}`),
        collectContrast: vi.fn(async (time: number) => ({
          entries: [contrastEntry({ ...anchor("#hero", time), ratio: 1 + time })],
          pngBase64: `${PNG_BASE64}-${time}`,
        })),
      });
    };
    const options = { ...DEFAULT_CHECK_OPTIONS, contrast: true };
    const { timings: _serialTimings, ...serial } = await runAuditGrid(
      pageOfTime(),
      options,
      noMotion(),
    );
    const primary = pageOfTime();
    const helper = pageOfTime();
    const { timings: _splitTimings, ...split } = await runAuditGrid(
      primary,
      options,
      noMotion(),
      Promise.resolve([helper]),
    );

    expect(split).toEqual(serial);
    expect(serial.layoutIssues.length).toBeGreaterThan(2);
    expect(helper.initialize).toHaveBeenCalledWith(true);
    const seeks = (driver: CheckAuditDriver) =>
      vi.mocked(driver.seek).mock.calls.map(([time]) => time);
    expect(seeks(helper).length).toBeGreaterThan(0);
    expect(seeks(primary).filter((time) => seeks(helper).includes(time))).toEqual([]);
  });

  it("redoes a crashed helper page's samples on the first page and returns the serial result", async () => {
    let helperSeeks = 0;
    const pageOfTime = (crashOnSeek?: number) => {
      let seeked = 0;
      return fakeDriver({
        markSamples: vi.fn(),
        seek: vi.fn(async (time: number) => {
          if (crashOnSeek !== undefined && ++helperSeeks === crashOnSeek)
            throw new Error("Target closed");
          await new Promise((resolve) => setImmediate(resolve));
          seeked = time;
        }),
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
        collectLayoutGeometry: vi.fn(async () => `geometry-${seeked}`),
      });
    };
    const { timings: _serialTimings, ...serial } = await runAuditGrid(
      pageOfTime(),
      DEFAULT_CHECK_OPTIONS,
      noMotion(),
    );
    const unhandled = vi.fn();
    process.on("unhandledRejection", unhandled);
    const primary = pageOfTime();
    const helper = pageOfTime(2);
    const { timings: _splitTimings, ...split } = await runAuditGrid(
      primary,
      DEFAULT_CHECK_OPTIONS,
      noMotion(),
      Promise.resolve([helper]),
    );
    await new Promise((resolve) => setImmediate(resolve));
    process.off("unhandledRejection", unhandled);

    expect(split).toEqual(serial);
    expect(helperSeeks).toBe(2);
    expect(helper.markSamples).toHaveBeenLastCalledWith("drop");
    expect(unhandled).not.toHaveBeenCalled();
  });

  it("waits for the helper's sample in flight when the first page runs out of samples", async () => {
    const pageOfTime = (onSeek?: () => Promise<void>) =>
      fakeDriver({
        seek: vi.fn(async () => onSeek?.()),
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
        collectLayoutGeometry: vi.fn(async () => "geometry"),
      });
    const serialPage = pageOfTime();
    const { timings: _serialTimings, ...serial } = await runAuditGrid(
      serialPage,
      DEFAULT_CHECK_OPTIONS,
      noMotion(),
    );
    const samples = vi.mocked(serialPage.collectLayout).mock.calls.length;
    let firstPageSeeks = 0;
    let othersTaken!: () => void;
    const allOthersTaken = new Promise<void>((resolve) => (othersTaken = resolve));
    const primary = pageOfTime(async () => {
      if (++firstPageSeeks === samples - 1) setImmediate(othersTaken);
    });
    const helper = pageOfTime(() => allOthersTaken);
    const { timings: _splitTimings, ...split } = await runAuditGrid(
      primary,
      DEFAULT_CHECK_OPTIONS,
      noMotion(),
      Promise.resolve([helper]),
    );

    expect(vi.mocked(helper.seek).mock.calls).toHaveLength(1);
    expect(split).toEqual(serial);
  });

  it("fails clearly without samples when no timeline duration is available, without hanging", async () => {
    const driver = fakeDriver({ getDuration: vi.fn(async () => 0) });
    await expect(runAuditGrid(driver, DEFAULT_CHECK_OPTIONS, noMotion())).rejects.toThrow(
      "Could not determine composition duration — no layout samples run",
    );
    await expect(
      runAuditGrid(
        driver,
        {
          ...DEFAULT_CHECK_OPTIONS,
          captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 1 },
        },
        noMotion(),
      ),
    ).rejects.toThrow("Could not determine composition duration — no layout samples run");

    const { report, browser } = await runScenario(driver);
    expect(browser).toHaveBeenCalledTimes(1);
    expect(report.runtime.findings[0]?.message).toContain(
      "Could not determine composition duration — no layout samples run",
    );
    expect(checkExitCode(report)).toBe(1);
  });

  describe("frozen-sweep guard (#U10)", () => {
    it("fails with sweep_static when a 6s composition's geometry never changes across samples", async () => {
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
      });
      const { report } = await runScenario(driver);

      expect(report.ok).toBe(false);
      expect(
        report.layout.findings.some(
          (finding) =>
            finding.code === "sweep_static" &&
            finding.severity === "error" &&
            finding.message.includes("did not advance") &&
            finding.fixHint?.includes("window.__timelines"),
        ),
      ).toBe(true);
    });

    function stillCard(clocks: (sample: number) => SeekClock[]) {
      let sample = 0;
      return fakeDriver({
        getDuration: vi.fn(async () => 4),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
        collectSeekClock: vi.fn(async () => clocks(sample++)),
      });
    }

    function sweepOf(report: CheckReport): [string, string][] {
      return report.layout.findings
        .filter((finding) => finding.code === "sweep_static")
        .map((finding) => [finding.severity, finding.message]);
    }

    it.each([
      [
        "whose timeline follows the seek",
        (sample: number) => [{ id: 1, time: sample, done: false }],
      ],
      ["with nothing that could move", () => []],
      ["whose only animation already holds at its end", () => [{ id: 1, time: 4, done: true }]],
      [
        "whose timeline is seen, listed twice, at only one sample",
        (sample: number) =>
          sample === 2
            ? [
                { id: 1, time: 0, done: false },
                { id: 1, time: 0, done: false },
              ]
            : [],
      ],
    ])("warns, without failing, on a still card %s", async (_case, clocks) => {
      const { report } = await runScenario(stillCard(clocks));

      expect(sweepOf(report)).toEqual([["warning", "Nothing on screen moved under seek."]]);
      expect(report.ok).toBe(true);
    });

    it.each([
      [
        "one animation is stuck while another follows the seek",
        (sample: number) => [
          { id: 1, time: 0, done: false },
          { id: 2, time: sample, done: false },
        ],
      ],
      [
        "a tween created mid-run is stuck",
        (sample: number) => [
          { id: 1, time: sample, done: false },
          ...(sample >= 2 ? [{ id: 2, time: 0, done: false }] : []),
        ],
      ],
    ])("fails when %s", async (_case, clocks) => {
      const { report } = await runScenario(stillCard(clocks));

      expect(sweepOf(report).map(([severity]) => severity)).toEqual(["error"]);
      expect(report.ok).toBe(false);
    });

    it("warns, without failing, when only the audio advanced and nothing on screen moved", async () => {
      let call = 0;
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectLayoutGeometry: vi.fn(async () => `still\u001f${call++}`),
      });
      const { report } = await runScenario(driver);

      const sweep = report.layout.findings.filter((finding) => finding.code === "sweep_static");
      expect(sweep.map((finding) => [finding.severity, finding.message])).toEqual([
        ["warning", "Only the audio advanced under seek; nothing on screen moved."],
      ]);
      expect(sweep[0]?.fixHint).toContain("data-no-timeline");
      expect(report.ok).toBe(true);
    });

    it("does not flag a sweep where something on screen moved", async () => {
      let call = 0;
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectLayoutGeometry: vi.fn(async () => `frame${call++}\u001f0`),
      });
      const { report } = await runScenario(driver);

      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
    });

    it.each([
      ["a timeline that looks stuck", (_sample: number) => "frozen", true],
      ["a still card", (_sample: number) => "frozen", false],
      ["an audio-only sweep", (sample: number) => `still\u001f${sample}`, false],
    ])("does not flag %s when the rendered frames differ", async (_case, geometry, stuck) => {
      let sample = 0;
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectLayoutGeometry: vi.fn(async () => geometry(sample++)),
        ...(stuck ? {} : { collectSeekClock: vi.fn(async () => []) }),
        ...framesOfSeekedTime(),
      });
      const { report } = await runScenario(driver);

      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
      expect(report.ok).toBe(true);
    });

    it("still warns when the frames change with the wall clock rather than the seek", async () => {
      let frame = 0;
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
        collectSeekClock: vi.fn(async () => []),
        captureFrame: vi.fn(async () => `frame${frame++}`),
      });
      const { report } = await runScenario(driver);

      expect(sweepOf(report)).toEqual([["warning", "Nothing on screen moved under seek."]]);
    });

    it("never captures frames when the signature already moved", async () => {
      const driver = fakeDriver({ getDuration: vi.fn(async () => 6) });
      await runScenario(driver);

      expect(driver.captureFrame).not.toHaveBeenCalled();
    });

    it("does not flag --at times the user picked on a still end card", async () => {
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 53.7),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
      });
      const { report } = await runScenario(driver, { at: [51, 52.5] });

      expect(report.layout.samples).toEqual([51, 52.5]);
      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
    });

    it("still judges the spread samples --at-transitions adds to an --at run", async () => {
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 53.7),
        getTransitionBoundaries: vi.fn(async () => [10, 20]),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
      });
      const { report } = await runScenario(driver, { at: [51, 52.5], atTransitions: true });

      expect(report.layout.samples).toEqual([10, 15, 20, 51, 52.5]);
      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(true);
    });

    it("does not flag intentional static content declared with data-no-timeline", async () => {
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        hasNoTimelineDeclaration: vi.fn(async () => true),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
      });

      const { report } = await runScenario(driver);

      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
    });

    it("does not flag a 1.5s static title card — too short for the guard to apply", async () => {
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 1.5),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
      });
      const { report } = await runScenario(driver);

      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
    });

    it("does not double-report when a motion_frozen finding already covers the same symptom", async () => {
      const motion: MotionSpecResolution = {
        kind: "valid",
        path: "/project/index.motion.json",
        spec: { assertions: [{ kind: "keepsMoving" }] },
      };
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectLayoutGeometry: vi.fn(async () => "frozen"),
        collectMotionFrame: vi.fn(async (time: number) => ({
          time,
          data: {},
          liveness: { "*": "unchanging" },
        })),
      });
      const { report } = await runScenario(driver, {}, { motion });

      expect(report.motion.findings.some((finding) => finding.code === "motion_frozen")).toBe(true);
      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
    });
  });

  describe("craft warnings", () => {
    // A 20 s film: frame 0 empty, a 7-word line on screen 6.2–6.9 s, nothing moving 7.5–12.5 s, no sound.
    function craftFrame(time: number): CraftFrame {
      const line = time >= 6.2 && time < 6.9;
      return {
        time,
        parts: line
          ? [
              {
                key: 1,
                block: 1,
                selector: "#title",
                blockSelector: "#title",
                sourceFile: "compositions/stat.html",
                text: "Every team gets one shared calendar now",
                opacity: 1,
                fontPx: 96,
                rect: { left: 160, top: 380, width: 1600, height: 220 },
                captions: false,
              },
            ]
          : [],
        held: false,
        painted: time > 0,
        signature: time >= 7.5 && time <= 12.5 ? "still" : `moving-${time}`,
      };
    }

    function craftDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver {
      return fakeDriver({
        getDuration: vi.fn(async () => 20),
        collectCraftFrame: vi.fn(async (time: number) => craftFrame(time)),
        collectCraftFilm: vi.fn(async () => ({ soundSources: 0 })),
        ...overrides,
      });
    }

    it("reports them as warnings that keep exit 0, even under --strict", async () => {
      const { report } = await runScenario(craftDriver());

      expect(report.craft.enabled).toBe(true);
      expect(report.craft.findings.map((finding) => finding.code).sort()).toEqual([
        "dead_stretch",
        "film_silent",
        "first_frame_empty",
        "line_unread",
      ]);
      expect(report.craft.findings.every((finding) => finding.severity === "warning")).toBe(true);
      expect(report.craft.warningCount).toBe(4);
      expect(report.ok).toBe(true);
      expect(checkExitCode(report)).toBe(0);

      const strict = await runScenario(craftDriver(), { strict: true });
      expect(checkExitCode(strict.report)).toBe(0);
    });

    it("re-measures a short line between dense samples before judging it", async () => {
      const driver = craftDriver();
      const { report } = await runScenario(driver);
      const line = report.craft.findings.find((finding) => finding.code === "line_unread");

      expect(line?.seconds).toBeCloseTo(0.7, 1);
      const sampled = vi.mocked(driver.collectCraftFrame!).mock.calls.map(([time]) => time);
      expect(sampled.some((time) => Math.round(time * 1000) % 125 !== 0)).toBe(true);
    });

    it("samples a long film at 8 fps, finer than the overlap pass's capped grid", async () => {
      // A 60 s film whose seven-word line shows 10.1-10.3 s, between two of the overlap grid's samples.
      const driver = craftDriver({
        getDuration: vi.fn(async () => 60),
        collectCraftFrame: vi.fn(async (time: number) => {
          const frame = craftFrame(time);
          const line = time >= 10.1 && time < 10.3;
          const part = craftFrame(6.5).parts[0];
          return { ...frame, parts: line && part ? [part] : [], signature: `moving-${time}` };
        }),
      });
      const { report } = await runScenario(driver);
      const line = report.craft.findings.find((finding) => finding.code === "line_unread");

      expect(line?.time).toBeCloseTo(10.1, 1);
    });

    it("skips the section for --range checks and for drivers without a craft sampler", async () => {
      const ranged = await runScenario(craftDriver(), { range: [2, 8] });
      expect(ranged.report.craft).toMatchObject({ enabled: false, findings: [] });

      const { report } = await runScenario(fakeDriver({ getDuration: vi.fn(async () => 20) }));
      expect(report.craft).toMatchObject({ enabled: false, findings: [] });
    });

    it("leaves stillness to sweep_static when the whole sweep is frozen", async () => {
      const driver = craftDriver({
        collectLayoutGeometry: vi.fn(async () => "frozen"),
        collectCraftFrame: vi.fn(async (time: number) => ({
          ...craftFrame(time),
          signature: "still",
        })),
      });
      const { report } = await runScenario(driver);

      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(true);
      expect(report.craft.findings.some((finding) => finding.code === "dead_stretch")).toBe(false);
    });
  });

  describe("keepsMoving frame check", () => {
    function frozenLiveness(withinSelector?: string) {
      const motion: MotionSpecResolution = {
        kind: "valid",
        path: "/project/index.motion.json",
        spec: { assertions: [{ kind: "keepsMoving", ...(withinSelector && { withinSelector }) }] },
      };
      const scope = withinSelector ?? "*";
      const overrides = {
        getDuration: vi.fn(async () => 6),
        collectMotionFrame: vi.fn(async (time: number) => ({
          time,
          data: {},
          liveness: { [scope]: "unchanging" },
        })),
      };
      return { motion, overrides };
    }

    function frozenFindings(report: CheckReport): string[] {
      return report.motion.findings
        .filter((finding) => finding.code === "motion_frozen")
        .map((finding) => finding.message);
    }

    it.each([undefined, "#scene"])(
      "does not call a scope (%s) frozen when its rendered frames keep changing",
      async (withinSelector) => {
        const { motion, overrides } = frozenLiveness(withinSelector);
        let frame = 0;
        const driver = fakeDriver({
          ...overrides,
          captureFrame: vi.fn(async () => `frame${frame++}`),
        });
        const { report } = await runScenario(driver, {}, { motion });

        expect(frozenFindings(report)).toEqual([]);
        expect(driver.captureFrame).toHaveBeenCalledWith(withinSelector);
        // One capture per half maxStaticSec, not one per motion frame.
        expect(vi.mocked(driver.captureFrame).mock.calls.length).toBeLessThanOrEqual(7);
      },
    );

    async function frozenIssues(driver: CheckAuditDriver, motion: MotionSpecResolution) {
      const result = await runAuditGrid(driver, DEFAULT_CHECK_OPTIONS, motion);
      return result.motionIssues.map((issue) => `${issue.code} ${issue.message}`);
    }

    it("splits a frozen span where its frames change once, keeping both halves", async () => {
      const { motion, overrides } = frozenLiveness();
      let seeked = 0;
      const driver = fakeDriver({
        ...overrides,
        // 9 s, so the last END_CARD_HOLD_SEC (6-9 s) a film may hold still stays clear of both spans.
        getDuration: vi.fn(async () => 9),
        seek: vi.fn(async (time: number) => {
          seeked = time;
        }),
        captureFrame: vi.fn(async () => (seeked < 3 ? "before" : "after")),
      });

      expect(await frozenIssues(driver, motion)).toEqual([
        expect.stringContaining("between 0s and 3s"),
        expect.stringContaining("between 3s and 6s"),
      ]);
    });

    it("keeps the second of two frozen spans that touch at a cut", async () => {
      const motion: MotionSpecResolution = {
        kind: "valid",
        path: "/project/index.motion.json",
        spec: { assertions: [{ kind: "keepsMoving" }] },
      };
      // A hold, a hard cut at 3 s into a second hold, then motion from 5.05 s to the end at 9 s,
      // clear of the last END_CARD_HOLD_SEC a film may hold still.
      const shot = (index: number) => (index < 60 ? "a" : index < 101 ? "b" : String(index));
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 9),
        collectMotionFrame: vi.fn(async (time: number) => ({
          time,
          data: {},
          liveness: { "*": shot(Math.round(time * 20)) },
        })),
      });

      expect(await frozenIssues(driver, motion)).toEqual([
        expect.stringContaining("between 0s and 3s"),
        expect.stringContaining("between 3s and 5.05s"),
      ]);
    });

    it("leaves a scope that matched nothing as missing while another scope is frozen", async () => {
      const motion: MotionSpecResolution = {
        kind: "valid",
        path: "/project/index.motion.json",
        spec: {
          assertions: [{ kind: "keepsMoving" }, { kind: "keepsMoving", withinSelector: "#typo" }],
        },
      };
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectMotionFrame: vi.fn(async (time: number) => ({
          time,
          data: {},
          liveness: { "*": "unchanging", "#typo": "" },
        })),
      });

      const codes = (await frozenIssues(driver, motion)).map((line) => line.split(" ")[0]);
      expect(codes).toEqual(["motion_frozen", "motion_selector_missing"]);
    });

    it("never captures frames when the liveness already moved", async () => {
      const motion: MotionSpecResolution = {
        kind: "valid",
        path: "/project/index.motion.json",
        spec: { assertions: [{ kind: "keepsMoving" }] },
      };
      const driver = fakeDriver({
        getDuration: vi.fn(async () => 6),
        collectMotionFrame: vi.fn(async (time: number) => ({
          time,
          data: {},
          liveness: { "*": String(time) },
        })),
      });
      const { report } = await runScenario(driver, {}, { motion });

      expect(frozenFindings(report)).toEqual([]);
      expect(driver.captureFrame).not.toHaveBeenCalled();
    });
  });
});

describe("frame-check flag grammar", () => {
  it("keeps bare --frame-check on defaults and parses the value form", async () => {
    const { parseFrameCheck } = await import("./check.js");
    expect(parseFrameCheck(undefined)).toBeUndefined();
    expect(parseFrameCheck(true)).toEqual({});
    expect(parseFrameCheck("")).toEqual({});
    expect(parseFrameCheck("severity=error;seek=.25,.75;tol=4")).toEqual({
      severity: "error",
      seek: [0.25, 0.75],
      tol: 4,
    });
    expect(() => parseFrameCheck("bogus=1")).toThrow("Invalid --frame-check");
    expect(() => parseFrameCheck("tol=-2")).toThrow("Invalid --frame-check");
    expect(() => parseFrameCheck("tol=4px")).toThrow("Invalid --frame-check");
    expect(() => parseFrameCheck("tol=2garbage")).toThrow("Invalid --frame-check");
  });

  it("attributes swallowed option values to --frame-check", async () => {
    const { parseFrameCheck } = await import("./check.js");

    expect(() => parseFrameCheck("--json")).toThrow(
      'Missing value for --frame-check: value "--json" appears to have swallowed the next option; use --frame-check= or move --frame-check to the end',
    );
    expect(() => parseFrameCheck("severity")).toThrow("Invalid --frame-check");
  });
});

describe("layout flag grammar", () => {
  it("parses proseCoverageFloor and rejects malformed specs", async () => {
    const { parseLayout } = await import("./check.js");
    expect(parseLayout(undefined)).toBeUndefined();
    expect(parseLayout("proseCoverageFloor=0.05")).toEqual({ proseCoverageFloor: 0.05 });
    expect(parseLayout("proseCoverageFloor=0")).toEqual({ proseCoverageFloor: 0 });
    expect(parseLayout("proseCoverageFloor=1")).toEqual({ proseCoverageFloor: 1 });
    expect(() => parseLayout(true)).toThrow("Invalid --layout");
    expect(() => parseLayout("")).toThrow("Invalid --layout");
    expect(() => parseLayout("bogus=1")).toThrow("Invalid --layout");
    expect(() => parseLayout("proseCoverageFloor=-0.1")).toThrow("Invalid --layout");
    expect(() => parseLayout("proseCoverageFloor=1.1")).toThrow("Invalid --layout");
    expect(() => parseLayout("proseCoverageFloor=0.05garbage")).toThrow("Invalid --layout");
    expect(() => parseLayout("proseCoverageFloor=0.1%")).toThrow("Invalid --layout");
    expect(() => parseLayout("proseCoverageFloor=")).toThrow("Invalid --layout");
  });

  it("threads --layout into the check pipeline options", async () => {
    const { report } = await runScenario(fakeDriver());
    const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
    vi.spyOn(console, "log").mockImplementation(() => undefined);
    const command = createCheckCommand({
      resolveProject: () => PROJECT,
      runPipeline,
      withMeta: (value) => value,
    });

    await runCommand(command, {
      rawArgs: ["--json", "--layout", "proseCoverageFloor=0.05"],
    });

    expect(runPipeline).toHaveBeenCalledWith(
      PROJECT,
      expect.objectContaining({
        layout: { proseCoverageFloor: 0.05 },
      }),
    );
  });

  it("forwards layout options into driver.collectLayout", async () => {
    const collectLayout = vi.fn(async (_time: number, _tolerance: number, _layout?: unknown) => []);
    await runScenario(fakeDriver({ collectLayout }), { layout: { proseCoverageFloor: 0.05 } });
    expect(collectLayout).toHaveBeenCalled();
    expect(collectLayout).toHaveBeenCalledWith(expect.any(Number), expect.any(Number), {
      proseCoverageFloor: 0.05,
    });
  });
});

describe("sampled finding reporting", () => {
  it("keeps the representative crop time paired with its geometry when dense observations arrive earlier", async () => {
    const movingOverlap = (time: number): AnchoredLayoutIssue => {
      const rect = fixtureRect(time * 1000, 20, 300, 80);
      return {
        ...layoutIssue("warning", { time, code: "content_overlap" }),
        rect,
        bbox: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
      };
    };
    const captureFindingCrops = vi.fn(async () => []);
    const { report } = await runScenario(
      fakeDriver({
        getDuration: vi.fn(async () => 1),
        collectLayout: vi.fn(async (time: number) => (time === 0.5 ? [movingOverlap(time)] : [])),
        collectOverlap: vi.fn(async (time: number) =>
          time >= 0.125 && time <= 0.75 ? [movingOverlap(time)] : [],
        ),
      }),
      { samples: 2, at: [0.5, 0.875], contrast: false, snapshots: true },
      { captureFindingCrops },
    );
    expect(report.layout.findings).toEqual([
      expect.objectContaining({
        code: "content_overlap",
        severity: "error",
        time: 0.5,
        firstSeen: 0.125,
        times: [0.125, 0.25, 0.375, 0.5, 0.625, 0.75],
        bbox: { x: 500, y: 20, width: 300, height: 80 },
      }),
    ]);
    expect(captureFindingCrops).toHaveBeenCalledWith(
      PROJECT,
      expect.objectContaining({ snapshots: true }),
      [
        {
          filename: "finding-00-content_overlap.png",
          time: 0.5,
          bbox: { x: 500, y: 20, width: 300, height: 80 },
        },
      ],
      expect.objectContaining({ signal: expect.any(AbortSignal) }),
    );
  });

  it("retains all sampled times for a stationary frame failure", async () => {
    const { report } = await runScenario(
      fakeDriver({
        getDuration: vi.fn(async () => 8),
        collectGeometryCandidates: vi.fn(async (time: number) => [
          geometryCandidate({
            kind: "media",
            tag: "img",
            text: "img",
            selector: "#stationary",
            rect: fixtureRect(1920, 100, 130, 100),
            overflow: { right: 130 },
            time,
          }),
        ]),
      }),
      { contrast: false, samples: 1, frameCheck: { seek: [0.25, 0.75] } },
    );
    expect(report.layout.findings).toEqual([
      expect.objectContaining({
        code: "frame_out_of_frame",
        selector: "#stationary",
        times: [2, 6],
      }),
    ]);
  });

  it("keeps different rules on one element as separate findings", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [
          layoutIssue("error", { time, code: "clipped_text" }),
          layoutIssue("error", { time, code: "text_box_overflow" }),
        ]),
      }),
      { contrast: false, samples: 2, at: [0.5, 1.5] },
    );
    expect(report.layout.findings.map(({ code, times }) => ({ code, times }))).toEqual([
      { code: "clipped_text", times: [0.5, 1.5] },
      { code: "text_box_overflow", times: [0.5, 1.5] },
    ]);
  });

  it("retains per-sample layout observations when collapse is explicitly disabled", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
      }),
      { contrast: false, collapseStatic: false, samples: 2, at: [0.5, 1.5] },
    );
    expect(report.layout.findings.map(({ code, time }) => ({ code, time }))).toEqual([
      { code: "clipped_text", time: 0.5 },
      { code: "clipped_text", time: 1.5 },
    ]);
  });

  it("reports held low contrast once with every occurrence time in JSON and terminal output", async () => {
    const times = [0.111, 0.556, 1, 1.444, 1.889];
    const { report } = await runScenario(
      fakeDriver({
        getDuration: vi.fn(async () => 2),
        collectContrast: vi.fn(async (time: number) => ({
          entries: [contrastEntry({ time, selector: "#low", ratio: time === 1 ? 1.2 : 2.5 })],
          pngBase64: PNG_BASE64,
        })),
      }),
      { samples: 5, at: times },
    );
    expect(report.contrast.findings).toEqual([
      expect.objectContaining({
        selector: "#low",
        severity: "error",
        times,
        time: 1,
        ratio: 1.2,
      }),
    ]);
    expect(report.contrast.errorCount).toBe(1);
    expect(report.contrast.checked).toBe(5);
    expect(checkExitCode(report)).toBe(1);
    const command = createCheckCommand({
      resolveProject: () => PROJECT,
      runPipeline: vi.fn(async () => report),
      withMeta: (value) => value,
    });
    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
    await runCommand(command, { rawArgs: [] });
    const output = log.mock.calls.map(([line]) => String(line)).join("\n");
    expect(output.match(/#low/g)).toHaveLength(1);
    expect(output).toContain("t=0.111, 0.556, 1, 1.444, 1.889s");
    log.mockClear();
    await runCommand(command, { rawArgs: ["--json"] });
    expect(JSON.parse(String(log.mock.calls[0]?.[0])).contrast.findings).toEqual(
      report.contrast.findings,
    );
  });

  it("keeps same-selector contrast failures in separate source files and grades each independently", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectContrast: vi.fn(async (time: number) => ({
          entries: [
            contrastEntry({
              time,
              selector: "#low",
              sourceFile: time < 1 ? "index.html" : "compositions/scene.html",
            }),
          ],
          pngBase64: PNG_BASE64,
        })),
      }),
      { samples: 2, at: [0.5, 1.5] },
    );
    expect(report.contrast.findings).toEqual([
      expect.objectContaining({ sourceFile: "index.html", severity: "warning", times: [0.5] }),
      expect.objectContaining({
        sourceFile: "compositions/scene.html",
        severity: "warning",
        times: [1.5],
      }),
    ]);
  });

  it("keeps same-selector layout findings from separate source files", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [
          {
            ...layoutIssue("error", { time }),
            sourceFile: time < 1 ? "index.html" : "compositions/scene.html",
          },
        ]),
      }),
      { contrast: false, samples: 2, at: [0.5, 1.5] },
    );
    expect(report.layout.findings).toEqual([
      expect.objectContaining({ sourceFile: "index.html", times: [0.5] }),
      expect.objectContaining({ sourceFile: "compositions/scene.html", times: [1.5] }),
    ]);
  });

  it("reports an element's repeated layout rule once even when its text changes", async () => {
    const { report } = await runScenario(
      fakeDriver({
        collectLayout: vi.fn(async (time: number) => [
          {
            ...layoutIssue("error", { time }),
            text: time < 1 ? "First" : "Changed",
          },
        ]),
      }),
      { contrast: false, samples: 2, at: [0.5, 1.5] },
    );
    expect(report.layout.findings).toHaveLength(1);
    expect(report.layout.findings[0]).toMatchObject({ code: "clipped_text", times: [0.5, 1.5] });
  });
});

describe("contrast persistence", () => {
  it("demotes a single-sample contrast failure to warning but gates held failures", async () => {
    const driver = fakeDriver({
      collectContrast: vi.fn(async (time: number) => ({
        entries: [
          // #hero fails at every sample: held, stays an error.
          contrastEntry({ time, selector: "#hero" }),
          // #entrance fails only at the first sample (mid-entrance): demoted.
          ...(time < 1
            ? [contrastEntry({ time, selector: "#entrance", text: "Fading in" })]
            : [
                contrastEntry({
                  time,
                  selector: "#entrance",
                  text: "Fading in",
                  ratio: 8,
                  wcagAA: true,
                }),
              ]),
        ],
        pngBase64: PNG_BASE64,
      })),
    });
    const { report } = await runScenario(driver);

    const bySelector = new Map(
      report.contrast.findings.map((finding) => [finding.selector, finding.severity]),
    );
    expect(bySelector.get("#hero")).toBe("error");
    expect(bySelector.get("#entrance")).toBe("warning");
    expect(checkExitCode(report)).toBe(1);
  });

  it("keeps full severity when only one sample time exists", async () => {
    const driver = fakeDriver({
      collectContrast: vi.fn(async (time: number) => ({
        entries: [contrastEntry({ time })],
        pngBase64: PNG_BASE64,
      })),
    });
    const { report } = await runScenario(driver, { samples: 1, at: [2] });

    expect(report.contrast.findings[0]?.severity).toBe("error");
  });
});

describe("check report telemetry", () => {
  it("reports one clean run with every gate and sampled-point count", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: { duration: 1, assertions: [{ kind: "appearsBy", selector: "#hero", bySec: 1 }] },
    };
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 1),
      collectMotionFrame: vi.fn(async (time: number) => heroMotionFrame(time, () => true)),
      collectContrast: vi.fn(async (time: number) => ({
        entries: [contrastEntry({ time, ratio: 7, wcagAA: true })],
        pngBase64: PNG_BASE64,
      })),
    });

    const { report } = await runScenario(
      driver,
      {
        samples: 1,
        captionZone: { x0: 0, y0: 0.8, x1: 1, y1: 1 },
        frameCheck: {},
        snapshots: true,
      },
      { motion },
    );

    expect(trackCheckReport).toHaveBeenCalledTimes(1);
    expect(trackCheckReport).toHaveBeenCalledWith(
      expect.objectContaining({
        contrastGate: true,
        motionGate: true,
        captionZoneGate: true,
        frameCheckGate: true,
        snapshotsGate: true,
        gridPoints: 2,
        contrastPoints: 1,
        ok: true,
        exitCode: 0,
      }),
    );
    expect(report.ok).toBe(true);
  });

  it("reports one failing contrast run with its section error count", async () => {
    const collectContrast = vi.fn(async (time: number) => ({
      entries: time === 0.5 ? [contrastEntry()] : [],
      pngBase64: PNG_BASE64,
    }));

    const { report } = await runScenario(fakeDriver({ collectContrast }));

    expect(trackCheckReport).toHaveBeenCalledTimes(1);
    expect(trackCheckReport).toHaveBeenCalledWith(
      expect.objectContaining({
        ok: false,
        exitCode: 1,
        contrastErrors: report.contrast.errorCount,
      }),
    );
    expect(report.contrast.errorCount).toBe(1);
  });

  it("reports zero browser samples and timings after a lint short circuit", async () => {
    const lint = lintWith(
      "error",
      "root_missing_composition_id",
      "Root element needs data-composition-id.",
    );

    const { report, browser } = await runScenario(fakeDriver(), {}, { lint });

    expect(browser).not.toHaveBeenCalled();
    expect(trackCheckReport).toHaveBeenCalledTimes(1);
    expect(trackCheckReport).toHaveBeenCalledWith(
      expect.objectContaining({
        ok: false,
        exitCode: 1,
        gridPoints: 0,
        contrastPoints: 0,
        launchSettleMs: 0,
        seekLoopMs: 0,
        contrastMs: 0,
      }),
    );
    expect(report.ok).toBe(false);
  });

  it("matches report counts for mixed findings across classes", async () => {
    const lint = lintWith("warning", "lint_warning", "Lint warning.");
    const driver = fakeDriver({
      collectLayout: vi.fn(async () => [layoutIssue(), layoutIssue("warning")]),
      collectContrast: vi.fn(async () => ({
        entries: [contrastEntry()],
        pngBase64: PNG_BASE64,
      })),
    });

    const { report } = await runScenario(
      driver,
      { samples: 1 },
      { lint, runtime: [runtimeError()] },
    );

    expect(trackCheckReport).toHaveBeenCalledTimes(1);
    expect(trackCheckReport).toHaveBeenCalledWith(
      expect.objectContaining({
        lintErrors: report.lint.errorCount,
        lintWarnings: report.lint.warningCount,
        runtimeErrors: report.runtime.errorCount,
        runtimeWarnings: report.runtime.warningCount,
        layoutErrors: report.layout.errorCount,
        layoutWarnings: report.layout.warningCount,
        motionErrors: report.motion.errorCount,
        motionWarnings: report.motion.warningCount,
        contrastErrors: report.contrast.errorCount,
        contrastWarnings: report.contrast.warningCount,
      }),
    );
    expect(report.lint.warningCount).toBe(1);
    expect(report.runtime.errorCount).toBe(1);
    expect(report.layout.errorCount).toBe(1);
    expect(report.layout.warningCount).toBe(1);
  });

  it("measures contrast work inside the overall seek loop", async () => {
    vi.spyOn(Date, "now")
      .mockReturnValueOnce(100)
      .mockReturnValueOnce(105)
      .mockReturnValueOnce(110)
      .mockReturnValueOnce(120);

    const result = await runAuditGrid(
      fakeDriver(),
      { ...DEFAULT_CHECK_OPTIONS, samples: 1 },
      noMotion(),
    );

    expect(result.timings).toEqual({ launchSettleMs: 0, seekLoopMs: 20, contrastMs: 5 });
  });
});

describe("contrast candidate round-trip", () => {
  it("passes the browser script's raw candidates back to finish, never the normalized copies", () => {
    const source = checkBrowserSource();

    // __contrastAuditFinish samples pixels via the page script's own bbox
    // shape ({x, y, w, h}); sending the Node-normalized candidate
    // ({width, height}) makes every sample rect NaN and the audit silently
    // reports zero checked elements. The raw object must round-trip verbatim.
    expect(source).toMatch(/prepared\.map\(\(entry\) => entry\.raw\)/);
    expect(source).toMatch(/raw: unknown;/);
    expect(source).not.toMatch(/prepared\.map\(\(entry\) => entry\.candidate\)/);
  });
});

describe("dense motion-overlap re-sampling", () => {
  // Collision lives inside (3.5, 4.5), a gap the sparse base grid seeks past; only the 8fps dense pass observes it.
  const inBetweenGridWindow = (time: number): boolean => time >= 3.6 && time <= 4.4;

  it("detects a content_overlap that occurs ONLY between two sparse grid samples", async () => {
    const driver = fakeDriver({
      // Sparse base grid sees nothing at any base sample time.
      collectLayout: vi.fn(async (_time: number) => []),
      // The transient exists only strictly between base samples 3.5 and 4.5.
      collectOverlap: vi.fn(async (time: number) =>
        inBetweenGridWindow(time)
          ? [layoutIssue("warning", { time, code: "content_overlap" })]
          : [],
      ),
    });
    const { report } = await runScenario(driver);
    expect(driver.collectOverlap).toHaveBeenCalled();
    expect(report.layout.findings.some((f) => f.code === "content_overlap")).toBe(true);
    // Held ~750ms across the dense grid (>= the 500ms floor) -> promoted.
    expect(report.layout.errorCount).toBeGreaterThan(0);
  });

  it("runs the dense pass even when sparse fingerprints are identical (aliased motion)", async () => {
    // Aliased motion has identical fingerprints yet still collides between samples — the false-negative the removed gate caused.
    const driver = fakeDriver({
      collectLayoutGeometry: vi.fn(async () => "static"),
      collectLayout: vi.fn(async (_time: number) => []),
      collectOverlap: vi.fn(async (time: number) =>
        inBetweenGridWindow(time)
          ? [layoutIssue("warning", { time, code: "content_overlap" })]
          : [],
      ),
    });
    const { report } = await runScenario(driver);
    expect(driver.collectOverlap).toHaveBeenCalled();
    expect(report.layout.findings.some((f) => f.code === "content_overlap")).toBe(true);
  });

  it("keeps a long film's dense pass to a fixed number of seeks", async () => {
    const clipEdges = Array.from({ length: 433 }, (_, i) => [i * 1.2, i * 1.2 + 1.1]).flat();
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 540),
      getClipEdges: async () => clipEdges,
    });
    await runScenario(driver);
    expect(vi.mocked(driver.seekGeometry).mock.calls.length).toBeLessThanOrEqual(240);
  });

  it("still promotes an overlap held on a long film", async () => {
    const held = (time: number): boolean => time >= 200 && time <= 260;
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 540),
      collectLayout: vi.fn(async (_time: number) => []),
      collectOverlap: vi.fn(async (time: number) =>
        held(time) ? [layoutIssue("warning", { time, code: "content_overlap" })] : [],
      ),
    });
    const { report } = await runScenario(driver);
    expect(report.layout.findings).toContainEqual(
      expect.objectContaining({ code: "content_overlap", severity: "error" }),
    );
    expect(vi.mocked(driver.seekGeometry).mock.calls.length).toBeLessThanOrEqual(240);
  });

  it("spends one hold probe on an overlap that stays the whole film", async () => {
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 540),
      collectLayout: vi.fn(async (_time: number) => []),
      collectOverlap: vi.fn(async (time: number) => [
        layoutIssue("warning", { time, code: "content_overlap" }),
      ]),
    });
    await runScenario(driver);
    expect(vi.mocked(driver.seekGeometry).mock.calls.length).toBeLessThanOrEqual(181);
  });

  it("samples a short clip the uniform grid steps over", async () => {
    const inShortClip = (time: number): boolean => time > 101 && time < 101.8;
    const driver = fakeDriver({
      getDuration: vi.fn(async () => 540),
      getClipEdges: async () => [101, 101.8],
      collectLayout: vi.fn(async (_time: number) => []),
      collectOverlap: vi.fn(async (time: number) =>
        inShortClip(time) ? [layoutIssue("warning", { time, code: "content_overlap" })] : [],
      ),
    });
    const { report } = await runScenario(driver);
    expect(report.layout.findings.some((f) => f.code === "content_overlap")).toBe(true);
  });
});

describe("scoped check", () => {
  it("bounds all runtime seeks, including dense overlap and transition samples", async () => {
    const times: number[] = [];
    const overlapTimes: number[] = [];
    const driver = fakeDriver({
      getDuration: async () => 10,
      getTransitionBoundaries: async () => [1, 7.9, 9],
      seek: async (t) => {
        times.push(t);
      },
      seekGeometry: async (t) => {
        times.push(t);
        overlapTimes.push(t);
      },
    });
    const { report } = await runScenario(driver, { range: [7.8, 8.2], atTransitions: true });
    expect(times.length).toBeGreaterThan(3);
    expect(times.every((t) => t >= 7.8 && t <= 8.2)).toBe(true);
    expect(times).toContain(7.9);
    expect(overlapTimes.every((time) => (String(time).split(".")[1]?.length ?? 0) <= 3)).toBe(true);
    expect(report.scope?.range).toEqual([7.8, 8.2]);
  });
  it("keeps the full-check failure when the only error is hidden by filtering", async () => {
    const driver = fakeDriver({
      collectLayout: async () => [layoutIssue("error")],
      matchComponents: async (_c, f) => f.map(() => false),
    });
    const { report } = await runScenario(driver, {
      components: ["#selected"],
      collapseStatic: false,
    });
    expect(report.ok).toBe(false);
    expect(report.layout.findings).toHaveLength(0);
    expect(report.layout.errorCount).toBe(1);
    expect(report.runtime.findings).toHaveLength(0);
    expect(report.scope?.hiddenFindings).toBe(1);
  });
  it.each([
    {
      flag: "--caption-zone",
      options: {
        range: [1, 2] as [number, number],
        captionZone: { x0: 0, y0: 0.5, x1: 1, y1: 0.7 },
      },
    },
    {
      flag: "--frame-check",
      options: { range: [0, 1] as [number, number], frameCheck: {} },
    },
  ])(
    "refuses $flag when none of its gate samples lie within --range",
    async ({ flag, options }) => {
      const { report } = await runScenario(fakeDriver({ getDuration: async () => 4 }), options);
      expect(report.ok).toBe(false);
      expect(report.browserSkipped).toBe(true);
      expect(report.runtime.findings).toEqual([
        expect.objectContaining({ message: expect.stringContaining(`No ${flag} seek samples`) }),
      ]);
    },
  );
  it("marks a motion spec disabled when a range skips whole-timeline assertions", async () => {
    const motion: MotionSpecResolution = {
      kind: "valid",
      path: "/project/index.motion.json",
      spec: { assertions: [] },
    };
    const { report } = await runScenario(
      fakeDriver({ getDuration: async () => 4 }),
      { range: [1, 2] },
      { motion },
    );
    expect(report.motion).toEqual(
      expect.objectContaining({
        enabled: false,
        specPath: "/project/index.motion.json",
        samples: 0,
      }),
    );
  });
  it("rejects a range outside the film rather than passing an empty check", async () => {
    const { report } = await runScenario(fakeDriver({ getDuration: async () => 2 }), {
      range: [3, 4],
    });
    expect(report.ok).toBe(false);
    expect(report.browserSkipped).toBe(true);
    expect(report.runtime.findings[0]?.message).toContain("2 seconds");
  });
});

it("validates range syntax before running a check", () => {
  expect(parseCheckRange("7.8,8.2")).toEqual([7.8, 8.2]);
  expect(parseCheckRange("7.8:8.2")).toEqual([7.8, 8.2]);
  for (const value of ["", "1", "1,1", "2,1", "-1,2", "NaN,2", "1,Infinity", ",2", "1,2,3"])
    expect(() => parseCheckRange(value)).toThrow();
});

it("applies transition sample limits within the requested range", async () => {
  const driver = fakeDriver({
    getDuration: async () => 10,
    getTransitionBoundaries: async () => [0, 1, 2, 3, 4, 5, 6, 7.8, 7.9, 8, 9, 10],
  });
  const { report } = await runScenario(driver, {
    range: [7.8, 8],
    atTransitions: true,
    maxTransitionSamples: 2,
  });
  expect(report.layout.transitionSamples).toEqual([7.8, 8]);
  expect(report.layout.transitionSamplesDropped).toBe(3);
});