Skip to content

Write HTML. Render video. Built for agents.

18.1 KB
Raw Blame
import { describe, expect, it } from "vitest";
import {
  buildLayoutSampleTimes,
  buildTransitionSampleTimes,
  computeOverflow,
  overflowValueClips,
  collapseStaticLayoutIssues,
  limitLayoutIssues,
  mergeSampleTimes,
  summarizeLayoutIssues,
  formatLayoutIssue,
  type LayoutIssue,
} from "./layoutAudit.js";

describe("buildTransitionSampleTimes (#1380)", () => {
  it("samples boundaries plus the midpoint of each segment between them", () => {
    // The #1380 repro: capA fades out 11.33–11.55, capB slams in 11.35–11.69.
    // The collision window 11.35–11.55 only shows both captions half-visible
    // away from the exact boundaries — the midpoints land inside it.
    const result = buildTransitionSampleTimes({
      duration: 20,
      boundaries: [11.33, 11.55, 11.35, 11.69],
    });
    expect(result.times).toEqual([11.33, 11.34, 11.35, 11.45, 11.55, 11.62, 11.69]);
    expect(result.dropped).toBe(0);
  });

  it("drops boundaries outside the composition and dedupes repeats", () => {
    const result = buildTransitionSampleTimes({
      duration: 10,
      boundaries: [2, 2, -1, 10.5, NaN, 4],
    });
    expect(result.times).toEqual([2, 3, 4]);
    expect(result.dropped).toBe(0);
  });

  it("returns an empty list without a valid duration", () => {
    expect(buildTransitionSampleTimes({ duration: 0, boundaries: [1, 2] })).toEqual({
      times: [],
      dropped: 0,
    });
  });

  it("samples every collected boundary when no cap is given", () => {
    const boundaries = Array.from({ length: 200 }, (_, i) => i * 0.05);
    const result = buildTransitionSampleTimes({ duration: 10, boundaries });
    // 200 boundaries + 199 segment midpoints, all distinct after rounding.
    expect(result.times.length).toBe(399);
    expect(result.dropped).toBe(0);
  });

  it("caps only on explicit request, reporting the omitted count and keeping the extremes", () => {
    const boundaries = Array.from({ length: 200 }, (_, i) => i * 0.05);
    const result = buildTransitionSampleTimes({ duration: 10, boundaries, cap: 40 });
    expect(result.times.length).toBeLessThanOrEqual(40);
    expect(result.dropped).toBe(399 - result.times.length);
    expect(result.times[0]).toBe(0);
    expect(result.times[result.times.length - 1]).toBeCloseTo(9.95, 3);
  });

  it("merges with even-spacing samples into one deduplicated ascending list", () => {
    expect(mergeSampleTimes([1, 3, 5], [3, 2.5, 7])).toEqual([1, 2.5, 3, 5, 7]);
  });
});

describe("layoutAudit helpers", () => {
  it("samples the whole duration using stable midpoint timestamps", () => {
    expect(buildLayoutSampleTimes({ duration: 10, samples: 5 })).toEqual([1, 3, 5, 7, 9]);
  });

  it("prefers explicit timestamps and keeps them inside the composition duration", () => {
    expect(buildLayoutSampleTimes({ duration: 10, samples: 5, at: [0, 2.5, 12, -1, NaN] })).toEqual(
      [0, 2.5],
    );
  });

  it("computes per-side overflow beyond a tolerance", () => {
    const overflow = computeOverflow(
      { left: 88, top: 102, right: 231, bottom: 181, width: 143, height: 79 },
      { left: 100, top: 100, right: 220, bottom: 180, width: 120, height: 80 },
      2,
    );

    expect(overflow).toEqual({ left: 12, right: 11 });
  });

  it("returns no overflow when the subject only exceeds the box within tolerance", () => {
    const overflow = computeOverflow(
      { left: 99, top: 100, right: 221, bottom: 180, width: 122, height: 80 },
      { left: 100, top: 100, right: 220, bottom: 180, width: 120, height: 80 },
      2,
    );

    expect(overflow).toBeNull();
  });

  it("summarizes errors and warnings separately", () => {
    const issues: LayoutIssue[] = [
      issue("text_box_overflow", "error"),
      issue("canvas_overflow", "warning"),
      issue("clipped_text", "error"),
    ];

    expect(summarizeLayoutIssues(issues)).toEqual({
      ok: false,
      errorCount: 2,
      warningCount: 1,
      infoCount: 0,
      issueCount: 3,
    });
  });

  it("tracks info findings separately from warnings and errors", () => {
    expect(summarizeLayoutIssues([issue("canvas_overflow", "info")])).toEqual({
      ok: true,
      errorCount: 0,
      warningCount: 0,
      infoCount: 1,
      issueCount: 1,
    });
  });

  it("collapses repeated static issues across sampled timestamps", () => {
    const collapsed = collapseStaticLayoutIssues([
      { ...issue("text_box_overflow", "error"), time: 1 },
      { ...issue("text_box_overflow", "error"), time: 3 },
      { ...issue("text_box_overflow", "error"), time: 5 },
    ]);

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({
      time: 1,
      firstSeen: 1,
      lastSeen: 5,
      occurrences: 3,
    });
  });

  it("formats issues with timestamp, selector, container, and fix hint", () => {
    const formatted = formatLayoutIssue({
      ...issue("text_box_overflow", "error"),
      time: 3.25,
      selector: "#headline",
      containerSelector: ".bubble",
      text: "Quarterly plan",
      overflow: { right: 18, bottom: 7 },
      fixHint: "Increase container padding or reduce font-size.",
    });

    expect(formatted).toContain("t=3.25s");
    expect(formatted).toContain("#headline");
    expect(formatted).toContain("inside .bubble");
    expect(formatted).toContain("right 18px, bottom 7px");
    expect(formatted).toContain("Fix: Increase container padding");
  });

  it("formats collapsed issue time ranges", () => {
    const formatted = formatLayoutIssue({
      ...issue("text_box_overflow", "error"),
      time: 1,
      firstSeen: 1,
      lastSeen: 5,
      occurrences: 3,
    });

    expect(formatted).toContain("t=1-5s (3 samples)");
  });

  it("treats hidden, clip, auto, and scroll as clipping", () => {
    expect(overflowValueClips("hidden")).toBe(true);
    expect(overflowValueClips("clip")).toBe(true);
    expect(overflowValueClips("auto")).toBe(true);
    expect(overflowValueClips("scroll")).toBe(true);
    expect(overflowValueClips("visible")).toBe(false);
    expect(overflowValueClips("clip visible")).toBe(false);
    expect(overflowValueClips("")).toBe(false);
    expect(overflowValueClips(null)).toBe(false);
    expect(overflowValueClips(undefined)).toBe(false);
  });

  it("limits returned issues by severity before truncating", () => {
    const limited = limitLayoutIssues(
      [
        { ...issue("canvas_overflow", "info"), time: 1 },
        { ...issue("text_box_overflow", "error"), time: 2 },
      ],
      1,
    );

    expect(limited).toMatchObject({
      totalIssueCount: 2,
      truncated: true,
      issues: [{ code: "text_box_overflow", severity: "error" }],
    });
  });
});

// #U10: held-duration severity tiering on top of the existing collapse step.
// Sample counts below (9) mirror the CLI's default grid so the "1 sample =
// entrance/exit transient, 2+ adjacent samples = held" framing in the
// approach doc lines up with the numbers used here.

describe("persistence-tiered severity (#U10)", () => {
  it("demotes a content_overlap seen at only one sample among several to info", () => {
    const collapsed = collapseStaticLayoutIssues(
      [{ ...issue("content_overlap", "warning"), time: 3 }],
      9,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "info", occurrences: 1 });
  });

  it("promotes content_overlap held across >= 2 adjacent samples to error", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("content_overlap", "warning"), time: 3 },
        { ...issue("content_overlap", "warning"), time: 3.6 },
      ],
      9,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 2 });
  });

  it("keeps a content_overlap that spans under the 500ms floor as a warning, even with 2 occurrences", () => {
    // Two dense-pass occurrences ~125ms apart are under the held-duration floor, so occurrences>=2 alone must not promote to error.
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("content_overlap", "warning"), time: 4.0 },
        { ...issue("content_overlap", "warning"), time: 4.125 },
      ],
      73,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "warning", occurrences: 2 });
  });

  it("does NOT promote content_overlap whose two occurrences span exactly 499ms (under the floor)", () => {
    // Boundary: a span one millisecond short of the 500ms floor stays a warning — guards the AND-tighten for sparse callers.
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("content_overlap", "warning"), time: 4.0 },
        { ...issue("content_overlap", "warning"), time: 4.499 },
      ],
      73,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "warning", occurrences: 2 });
  });

  it("promotes a content_overlap whose text changes every sample (count-up over a label)", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        {
          ...issue("content_overlap", "warning"),
          time: 4.0,
          containerSelector: ".num",
          text: "$1,204",
        },
        {
          ...issue("content_overlap", "warning"),
          time: 4.5,
          containerSelector: ".num",
          text: "$8,930",
        },
      ],
      73,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 2 });
  });

  it("keeps a text_occluded over changing text at error, not demoted per sample", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        {
          ...issue("text_occluded", "error"),
          time: 4.0,
          containerSelector: ".scrim",
          text: "$1,204",
        },
        {
          ...issue("text_occluded", "error"),
          time: 4.5,
          containerSelector: ".scrim",
          text: "$8,930",
        },
      ],
      73,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 2 });
  });

  it("keeps two content_overlap pairs on different containers in separate groups", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("content_overlap", "warning"), time: 4.0, containerSelector: ".num" },
        { ...issue("content_overlap", "warning"), time: 4.5, containerSelector: ".pct" },
      ],
      73,
    );

    expect(collapsed).toHaveLength(2);
  });

  it("does not bridge two separate transients on one pair into a held collision", () => {
    const blip = { ...issue("content_overlap", "warning"), containerSelector: ".label" };
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...blip, time: 1.0 },
        { ...blip, time: 1.125 },
        { ...blip, time: 9.0 },
        { ...blip, time: 9.125 },
      ],
      73,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "warning", occurrences: 4 });
  });

  it("promotes only when one contiguous run clears the floor, not the span between runs", () => {
    const blip = { ...issue("content_overlap", "warning"), containerSelector: ".label" };
    const held = [1.0, 1.125, 1.25, 1.375, 1.5, 1.625].map((time) => ({ ...blip, time }));
    const collapsed = collapseStaticLayoutIssues([...held, { ...blip, time: 9.0 }], 73);

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 7 });
  });

  it("does not bridge two blips 1.5s apart, whatever grid the collapse was handed", () => {
    const blip = { ...issue("content_overlap", "warning"), containerSelector: ".label" };
    for (const sampleCount of [9, 81]) {
      const collapsed = collapseStaticLayoutIssues(
        [
          { ...blip, time: 2.0 },
          { ...blip, time: 3.5 },
        ],
        sampleCount,
      );
      expect(collapsed[0]).toMatchObject({ severity: "warning" });
    }
  });

  it("promotes a 625ms contiguous collision even when a tight pair sits elsewhere", () => {
    const blip = { ...issue("content_overlap", "warning"), containerSelector: ".label" };
    const held = [5.0, 5.125, 5.25, 5.375, 5.5, 5.625].map((time) => ({ ...blip, time }));
    const elsewhere = { ...issue("content_overlap", "warning"), containerSelector: ".other" };
    const collapsed = collapseStaticLayoutIssues(
      [
        ...held,
        { ...elsewhere, time: 2.0 },
        { ...elsewhere, time: 2.05 },
        { ...elsewhere, time: 2.1 },
      ],
      81,
    );

    const label = collapsed.find((entry) => entry.containerSelector === ".label");
    expect(label).toMatchObject({ severity: "error", heldMs: 625 });
  });

  it("still separates two distinct text_box_overflow findings that differ only by text", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("text_box_overflow", "warning"), time: 4.0, text: "first" },
        { ...issue("text_box_overflow", "warning"), time: 4.5, text: "second" },
      ],
      73,
    );

    expect(collapsed).toHaveLength(2);
  });

  it("promotes content_overlap whose two occurrences span exactly 500ms (at the floor)", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("content_overlap", "warning"), time: 4.0 },
        { ...issue("content_overlap", "warning"), time: 4.5 },
      ],
      73,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 2 });
  });

  it("promotes a held, canvas-scale canvas_overflow breach from info to warning", () => {
    const breach = {
      ...issue("canvas_overflow", "info"),
      overflow: { top: 140 },
      containerRect: { left: 0, top: 0, right: 1920, bottom: 1080, width: 1920, height: 1080 },
    };
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...breach, time: 1 },
        { ...breach, time: 3 },
      ],
      9,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "warning", occurrences: 2 });
  });

  it("keeps a held, large but fully off-canvas canvas_overflow at info — a parked entrance, not drift", () => {
    const breach = {
      ...issue("canvas_overflow", "info"),
      rect: { left: 2200, top: 300, right: 2800, bottom: 700, width: 600, height: 400 },
      overflow: { right: 880 },
      containerRect: { left: 0, top: 0, right: 1920, bottom: 1080, width: 1920, height: 1080 },
    };
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...breach, time: 1 },
        { ...breach, time: 3 },
      ],
      9,
    );

    expect(collapsed[0]).toMatchObject({ severity: "info", occurrences: 2 });
  });

  it("demotes single-sample coordinate-frame findings to info", () => {
    for (const code of [
      "escaped_container",
      "panel_out_of_canvas",
      "connector_detached",
      "connector_orphan",
    ] as const) {
      const collapsed = collapseStaticLayoutIssues([{ ...issue(code, "warning"), time: 3 }], 9);
      expect(collapsed[0]).toMatchObject({ severity: "info", occurrences: 1 });
    }
  });

  it("keeps id-less connector findings apart by geometry, so each stays a single sample", () => {
    for (const code of ["connector_detached", "connector_orphan"] as const) {
      const shaft = { ...issue(code, "warning"), selector: "svg path" };
      const collapsed = collapseStaticLayoutIssues(
        [
          { ...shaft, time: 1, rect: { ...shaft.rect, left: 100, top: 100 } },
          { ...shaft, time: 3, rect: { ...shaft.rect, left: 600, top: 300 } },
          { ...shaft, time: 5, rect: { ...shaft.rect, left: 1200, top: 700 } },
        ],
        9,
      );

      expect(collapsed).toHaveLength(3);
      for (const finding of collapsed) {
        expect(finding).toMatchObject({ severity: "info", occurrences: 1 });
      }
    }
  });

  it("keeps a held but small canvas_overflow at info", () => {
    const breach = {
      ...issue("canvas_overflow", "info"),
      overflow: { top: 30 },
      containerRect: { left: 0, top: 0, right: 1920, bottom: 1080, width: 1920, height: 1080 },
    };
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...breach, time: 1 },
        { ...breach, time: 3 },
      ],
      9,
    );

    expect(collapsed[0]).toMatchObject({ severity: "info", occurrences: 2 });
  });

  it("does not demote a finding held at every sample — persistence, not a single hit", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("text_box_overflow", "error"), time: 1 },
        { ...issue("text_box_overflow", "error"), time: 3 },
        { ...issue("text_box_overflow", "error"), time: 5 },
      ],
      9,
    );

    expect(collapsed).toHaveLength(1);
    expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 3 });
  });

  it("does not promote held codes without a promotion rule — container_overflow keeps its severity", () => {
    const collapsed = collapseStaticLayoutIssues(
      [
        { ...issue("container_overflow", "warning"), time: 3 },
        { ...issue("container_overflow", "warning"), time: 3.6 },
      ],
      9,
    );

    expect(collapsed[0]).toMatchObject({ severity: "warning" });
  });

  it("skips tiering entirely on a single-sample run — nothing to compare a transient against", () => {
    const collapsed = collapseStaticLayoutIssues(
      [{ ...issue("content_overlap", "warning"), time: 3 }],
      1,
    );

    expect(collapsed[0]).toMatchObject({ severity: "warning" });
  });

  it("infers the sample count from distinct issue times when none is given", () => {
    // Two distinct times among the raw issues imply a multi-sample run even
    // without an explicit count, so the single-occurrence group still demotes.
    const collapsed = collapseStaticLayoutIssues([
      { ...issue("content_overlap", "warning"), time: 3 },
      { ...issue("text_box_overflow", "error"), time: 5 },
    ]);

    const overlap = collapsed.find((found) => found.code === "content_overlap");
    expect(overlap).toMatchObject({ severity: "info" });
  });
});

function issue(code: LayoutIssue["code"], severity: LayoutIssue["severity"]): LayoutIssue {
  return {
    code,
    severity,
    time: 1,
    selector: ".label",
    message: "Layout issue",
    rect: { left: 0, top: 0, right: 100, bottom: 20, width: 100, height: 20 },
    overflow: { right: 8 },
    fixHint: "Adjust layout.",
  };
}