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("keeps canvas_covered an error only when the canvas is covered for most of the film", () => { const covered = (times: number[], samples: number) => collapseStaticLayoutIssues( times.map((time) => ({ ...issue("canvas_covered", "error"), time })), samples, )[0]?.severity; expect(covered([1, 2, 3, 4, 5], 8)).toBe("error"); expect(covered([7, 8], 8)).toBe("info"); }); 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("shows control characters in composition text as visible escapes", () => { const formatted = formatLayoutIssue({ ...issue("text_box_overflow", "error"), selector: "#h\u001b]0;t\u0007", containerSelector: ".b\u009b2J", text: "Plan\u001b[2K", message: "clipped\u001b[1A", fixHint: "pad \u001b]52;c;Y2xpcA==\u0007", }); for (const control of ["\u0007", "\u001b", "\u009b"]) expect(formatted).not.toContain(control); expect(formatted).toContain("#h\\x1b]0;t\\x07 inside .b\\x9b2J"); expect(formatted).toContain('"Plan\\x1b[2K" — clipped\\x1b[1A'); expect(formatted).toContain("\n Fix: pad \\x1b]52;c;Y2xpcA==\\x07"); }); it("shows control characters in an issue code from the page as visible escapes", () => { const formatted = formatLayoutIssue({ ...issue("text_box_overflow", "error"), code: "text_box_overflow\u001b]52;c;Y2xpcA==\u0007" as LayoutIssue["code"], }); expect(formatted).not.toContain("\u001b"); expect(formatted).toContain("text_box_overflow\\x1b]52;c;Y2xpcA==\\x07"); }); 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 at error when the word lives one sample and is hidden at it", () => { const grid = [0.167, 0.5, 0.833, 1.167]; const word = (time: number, lifetime: { start: number; end: number }) => ({ ...issue("text_occluded", "error"), time, lifetime, }); const collapsed = collapseStaticLayoutIssues( [word(0.167, { start: 0, end: 0.4 }), word(0.5, { start: 0.4, end: 0.8 })].map((entry) => ({ ...entry, selector: `#w${entry.time}`, })), grid.length, grid, ); expect(collapsed.map((entry) => entry.severity)).toEqual(["error", "error"]); }); it("still demotes a text_occluded seen at one of several samples its clip spans", () => { const grid = [0.1, 0.3, 0.5, 0.7]; const collapsed = collapseStaticLayoutIssues( [{ ...issue("text_occluded", "error"), time: 0.3, lifetime: { start: 0, end: 1 } }], grid.length, grid, ); expect(collapsed[0]).toMatchObject({ severity: "info", occurrences: 1 }); }); 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.", }; }