Files
hyperframes/packages/cli/src/utils/layoutAudit.test.ts
T
Xuanru Li 09ab947e1a fix(layout): flag text a clipping card cuts off (#4577)
* fix(layout): flag text a clipping card cuts off

A short card with overflow hidden cut the words off, and the check
dropped text_box_overflow because that parent clips.
The text element's own box does not clip, so clipped_text stayed quiet.
A deliberate mask still clears with data-layout-allow-overflow.

* fix(layout): ignore a text line parked fully outside its box

A reel row that never enters the window was failing with the cut-off card.
Only a line that still meets the box and sticks out of it is an overflow.

* fix(layout): report visible text outside non-clipping cards

* fix(layout): distinguish line boxes from parked font extents

* test(layout): type browser audit test interfaces
2026-09-28 02:08:08 +00:00

539 lines
18 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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.",
};
}