Files
hyperframes/packages/cli/src/utils/layoutAudit.ts
T
Miguel Ángel f523ee2fca fix(cli): check flags caption words hidden behind a cut-out and ignores a mostly transparent cover (#6770)
* fix(cli): check flags caption words hidden behind a cut-out and ignores a mostly transparent cover

* fix(cli): a caption word's lifetime is shifted only by its composition hosts
2026-10-30 01:47:19 +00:00

533 lines
18 KiB
TypeScript

import { formatFindingTimes } from "./checkFindings.js";
export interface LayoutRect {
left: number;
top: number;
right: number;
bottom: number;
width: number;
height: number;
}
export type LayoutOverflow = Partial<Record<"left" | "right" | "top" | "bottom", number>>;
export type LayoutIssueCode =
| "text_box_overflow"
| "clipped_text"
| "canvas_overflow"
| "container_overflow"
| "content_overlap"
| "visibility_escapes_segment"
| "text_occluded"
| "canvas_covered"
| "video_alpha_unread"
| "text_not_painted"
| "caption_zone_collision"
| "frame_out_of_frame"
// Coordinate-frame findings — geometry computed in one frame, rendered in another.
| "escaped_container"
| "panel_out_of_canvas"
| "canvas_content_at_edge"
| "connector_detached"
| "connector_orphan"
// Cross-sample rotation finding — a spinning element whose bbox center drifts
// because it pivots about the wrong point (bad transformOrigin/svgOrigin).
| "rotation_pivot_drift"
// Hub-referenced rotation finding — a gauge/clock/radar pointer whose recovered
// center-of-rotation sits far from the dial's static hub (wrong pivot point).
| "off_pivot_rotation"
// Frozen-sweep guard (#U10) — a whole-run meta-finding, not a per-sample
// geometry observation; never persistence-tiered (see `applyPersistenceTier`).
| "sweep_static"
// Motion-verification findings (#1437) — evaluated against the seeked timeline.
| "motion_appears_late"
| "motion_out_of_order"
| "motion_off_frame"
| "motion_frozen"
| "motion_selector_missing"
| "motion_selector_ambiguous";
export type LayoutIssueSeverity = "error" | "warning" | "info";
export interface LayoutIssue {
code: LayoutIssueCode;
severity: LayoutIssueSeverity;
time: number;
times?: number[];
firstSeen?: number;
lastSeen?: number;
occurrences?: number;
heldMs?: number;
selector: string;
containerSelector?: string;
text?: string;
message: string;
rect: LayoutRect;
containerRect?: LayoutRect;
overflow?: LayoutOverflow;
/** `text_occluded` only (0-1): probe-grid share hit by an opaque occluder, or behind a
* transparent video the most covered word's share under its alpha (layout-audit.browser.js). */
coveredFraction?: number;
/** `text_occluded` only: the global window the element's own clip is on screen. */
lifetime?: { start: number; end: number };
fixHint?: string;
}
export interface LayoutSummary {
ok: boolean;
errorCount: number;
warningCount: number;
infoCount: number;
issueCount: number;
}
export interface LayoutSampleOptions {
duration: number;
samples: number;
at?: number[];
}
export function buildLayoutSampleTimes({ duration, samples, at }: LayoutSampleOptions): number[] {
if (at?.length) {
return uniqueSortedTimes(
at.filter(
(time) => Number.isFinite(time) && time >= 0 && (duration <= 0 || time <= duration),
),
);
}
if (!Number.isFinite(duration) || duration <= 0 || samples <= 0) return [];
const count = Math.max(1, Math.floor(samples));
return Array.from({ length: count }, (_, index) => roundTime(((index + 0.5) / count) * duration));
}
export function computeOverflow(
subject: LayoutRect,
container: LayoutRect,
tolerance: number,
): LayoutOverflow | null {
const overflow: LayoutOverflow = {};
if (subject.left < container.left - tolerance) {
overflow.left = roundPx(container.left - subject.left);
}
if (subject.right > container.right + tolerance) {
overflow.right = roundPx(subject.right - container.right);
}
if (subject.top < container.top - tolerance) {
overflow.top = roundPx(container.top - subject.top);
}
if (subject.bottom > container.bottom + tolerance) {
overflow.bottom = roundPx(subject.bottom - container.bottom);
}
return Object.keys(overflow).length > 0 ? overflow : null;
}
/**
* Whether a computed `overflow*` value clips its box. Mirrors
* `clipsOverflowValue` in layout-audit.browser.js. `visible` and `clip visible`
* do not clip.
*/
export function overflowValueClips(value: string | null | undefined): boolean {
return !!value && value !== "visible" && value !== "clip visible";
}
export function summarizeLayoutIssues(issues: LayoutIssue[]): LayoutSummary {
const errorCount = issues.filter((issue) => issue.severity === "error").length;
const warningCount = issues.filter((issue) => issue.severity === "warning").length;
const infoCount = issues.filter((issue) => issue.severity === "info").length;
return {
ok: errorCount === 0,
errorCount,
warningCount,
infoCount,
issueCount: issues.length,
};
}
export function formatLayoutIssue(issue: LayoutIssue): string {
let timeLabel = `t=${formatNumber(issue.time)}s`;
if (issue.times) {
timeLabel = formatFindingTimes(issue);
} else if (issue.occurrences && issue.occurrences > 1) {
timeLabel = `t=${formatNumber(issue.firstSeen ?? issue.time)}-${formatNumber(issue.lastSeen ?? issue.time)}s (${issue.occurrences} samples)`;
}
const parts = [
timeLabel,
issue.code,
issue.selector,
issue.containerSelector ? `inside ${issue.containerSelector}` : "",
issue.overflow ? `overflowed ${formatOverflow(issue.overflow)}` : "",
issue.text ? quoteText(issue.text) : "",
].filter(Boolean);
const line = `${parts.join(" ")} — ${issue.message}`;
return issue.fixHint ? `${line}\n Fix: ${issue.fixHint}` : line;
}
export function dedupeLayoutIssues(issues: LayoutIssue[]): LayoutIssue[] {
const seen = new Set<string>();
const result: LayoutIssue[] = [];
for (const issue of issues) {
const key = [
Reflect.get(issue, "sourceFile") ?? "",
issue.code,
issue.severity,
issue.time.toFixed(3),
issue.selector,
issue.containerSelector ?? "",
issue.text ?? "",
issue.overflow ? formatOverflow(issue.overflow) : "",
framePositionKey(issue),
].join("|");
if (seen.has(key)) continue;
seen.add(key);
result.push(issue);
}
return result;
}
// Persistence-tier thresholds (#U10): occurrences>=2 alone can't imply the 500ms floor under dense 8fps sampling, so content_overlap promotion requires a literal firstSeen..lastSeen span >= 500ms — stricter for sparse callers too.
export const CONTENT_OVERLAP_HELD_ERROR_MS = 500;
const HELD_ACROSS_SAMPLES_MIN_OCCURRENCES = 2;
// Tiering only applies to layout-audit.browser.js's own per-sample seek-grid
// findings — the ones this collapse step's firstSeen/lastSeen span was built
// to describe. `caption_zone_collision`/`frame_out_of_frame` (a different
// script, U3) and the `motion_*`/`sweep_static` codes (evaluated once over
// the whole run, not per grid sample) already carry their own singular
// dedupe/severity semantics; re-interpreting their occurrence count as a
// held-duration signal would misread it.
const PERSISTENCE_TIERED_CODES: ReadonlySet<LayoutIssueCode> = new Set([
"text_box_overflow",
"clipped_text",
"canvas_overflow",
"container_overflow",
"content_overlap",
"visibility_escapes_segment",
"text_occluded",
"escaped_container",
"panel_out_of_canvas",
"canvas_content_at_edge",
"connector_detached",
"connector_orphan",
]);
const CONTIGUOUS_SAMPLE_GAP_MS = CONTENT_OVERLAP_HELD_ERROR_MS * 2;
const TEXT_AGNOSTIC_KEY_CODES: ReadonlySet<LayoutIssueCode> = new Set([
"content_overlap",
"text_occluded",
]);
export function collapseStaticLayoutIssues(
issues: LayoutIssue[],
totalSampleCount?: number,
sampleTimes?: readonly number[],
): LayoutIssue[] {
const groups = new Map<
string,
{
issue: LayoutIssue;
firstSeen: number;
lastSeen: number;
occurrences: number;
times: number[];
}
>();
for (const issue of issues) {
const key = staticIssueKey(issue);
const existing = groups.get(key);
if (!existing) {
groups.set(key, {
issue,
firstSeen: issue.time,
lastSeen: issue.time,
occurrences: 1,
times: [issue.time],
});
continue;
}
existing.firstSeen = Math.min(existing.firstSeen, issue.time);
existing.lastSeen = Math.max(existing.lastSeen, issue.time);
existing.occurrences += 1;
existing.times.push(issue.time);
}
// A run that only ever sampled one point in time can't distinguish a
// transient from a persistent finding — skip tiering entirely rather than
// guess (see `applyPersistenceTier`).
const sampleCount = totalSampleCount ?? new Set(issues.map((issue) => issue.time)).size;
const multiSampleRun = sampleCount > 1;
return [...groups.values()].map(({ issue, firstSeen, lastSeen, occurrences, times }) =>
tierIssue(
{
...issue,
firstSeen,
lastSeen,
occurrences,
heldMs: longestContiguousRunMs(times),
times: [...new Set(times)].sort((a, b) => a - b),
},
multiSampleRun,
sampleCount,
sampleTimes,
),
);
}
export function longestContiguousRunMs(times: number[]): number {
const run = longestContiguousRun(times);
return ((run.at(-1) ?? 0) - (run[0] ?? 0)) * 1000;
}
export function longestContiguousRun(times: number[]): number[] {
const sorted = [...new Set(times)].sort((a, b) => a - b);
let longest: number[] = [];
let run: number[] = [];
const span = (values: number[]) => (values.at(-1) ?? 0) - (values[0] ?? 0);
for (const current of sorted) {
const previous = run.at(-1);
if (previous !== undefined && (current - previous) * 1000 > CONTIGUOUS_SAMPLE_GAP_MS) {
if (longest.length === 0 || span(run) > span(longest)) longest = run;
run = [];
}
run.push(current);
}
return longest.length === 0 || span(run) > span(longest) ? run : longest;
}
/** A full-frame card or a fade to colour covers the canvas briefly; most of the film is a blank stage. */
function coverTier(issue: LayoutIssue, sampleCount: number): LayoutIssue {
return (issue.occurrences ?? 1) * 2 >= sampleCount ? issue : { ...issue, severity: "info" };
}
function tierIssue(
issue: LayoutIssue,
multiSampleRun: boolean,
sampleCount: number,
sampleTimes?: readonly number[],
): LayoutIssue {
if (multiSampleRun && issue.code === "canvas_covered") return coverTier(issue, sampleCount);
return applyPersistenceTier(issue, multiSampleRun, sampleTimes);
}
/** An element whose clip spans no more samples than it was caught at was caught for its whole life. */
function caughtForWholeLifetime(issue: LayoutIssue, sampleTimes?: readonly number[]): boolean {
if (!issue.lifetime || !sampleTimes) return false;
const { start, end } = issue.lifetime;
const sampled = sampleTimes.filter((time) => time >= start && time < end).length;
return (issue.occurrences ?? 1) >= sampled;
}
/**
* Held-duration severity tiering (#U10). A finding observed at only one
* sample among several (held 0ms) is an entrance/exit transient, not a held
* defect — demote to info so it stays in the data (verbose/--json output)
* without gating the run. Two codes re-promote once held: `content_overlap`
* warning->error when the collision is sustained rather than a crossfade blip
* (resolves the TODO in layout-audit.browser.js's `overlapIssue`), and
* `canvas_overflow` info->warning when the breach is held, canvas-scale
* (>= 5% of the short edge) AND partially visible — a fully off-canvas rect
* is a parked entrance, not drift. Codes without a promotion rule are left
* untouched when held — persistence, not the code, decides their tier.
*/
function applyPersistenceTier(
issue: LayoutIssue,
multiSampleRun: boolean,
sampleTimes?: readonly number[],
): LayoutIssue {
if (!multiSampleRun) return issue;
if (!PERSISTENCE_TIERED_CODES.has(issue.code)) return issue;
const occurrences = issue.occurrences ?? 1;
// A single collapsed occurrence is held 0ms by construction (firstSeen ===
// lastSeen) — always under the ignore floor, so occurrences <= 1 is a
// complete (not approximate) test for "held under 250ms".
if (occurrences <= 1) {
return caughtForWholeLifetime(issue, sampleTimes) ? issue : { ...issue, severity: "info" };
}
if (issue.code === "content_overlap" && isContentOverlapHeldLongEnough(issue, occurrences)) {
return { ...issue, severity: "error" };
}
if (issue.code === "canvas_overflow" && isCanvasBreachHeldLarge(issue, occurrences)) {
return { ...issue, severity: "warning" };
}
return issue;
}
// A held, canvas-scale, PARTIALLY visible breach is drift; a fully off-canvas rect is a parked entrance.
function isCanvasBreachHeldLarge(issue: LayoutIssue, occurrences: number): boolean {
if (
occurrences < HELD_ACROSS_SAMPLES_MIN_OCCURRENCES ||
!issue.overflow ||
!issue.containerRect
) {
return false;
}
const breach = Math.max(
...Object.values(issue.overflow).filter((value) => typeof value === "number"),
);
if (breach < Math.min(issue.containerRect.width, issue.containerRect.height) * 0.05) return false;
const container = issue.containerRect;
const overlapX =
Math.min(issue.rect.right, container.right) - Math.max(issue.rect.left, container.left);
const overlapY =
Math.min(issue.rect.bottom, container.bottom) - Math.max(issue.rect.top, container.top);
return overlapX > 0 && overlapY > 0;
}
// Split out of applyPersistenceTier so the compound "held long enough" test reads as one boolean question.
function isContentOverlapHeldLongEnough(issue: LayoutIssue, occurrences: number): boolean {
// Two samples measure a span, but under dense 8fps sampling that span must still clear the wall-clock floor.
if (occurrences < HELD_ACROSS_SAMPLES_MIN_OCCURRENCES) return false;
const firstSeen = issue.firstSeen ?? issue.time;
const lastSeen = issue.lastSeen ?? issue.time;
const heldMs = issue.heldMs ?? (lastSeen - firstSeen) * 1000;
return heldMs >= CONTENT_OVERLAP_HELD_ERROR_MS;
}
export function limitLayoutIssues(
issues: LayoutIssue[],
maxIssues: number,
): { issues: LayoutIssue[]; totalIssueCount: number; truncated: boolean } {
const limit = Math.max(1, Math.floor(maxIssues));
const sortedIssues = [...issues].sort((a, b) => {
const severityDelta = severityRank(a.severity) - severityRank(b.severity);
if (severityDelta !== 0) return severityDelta;
return a.time - b.time;
});
return {
issues: sortedIssues.slice(0, limit),
totalIssueCount: issues.length,
truncated: issues.length > limit,
};
}
function severityRank(severity: LayoutIssueSeverity): number {
if (severity === "error") return 0;
if (severity === "warning") return 1;
return 2;
}
function staticIssueKey(issue: LayoutIssue): string {
return [
Reflect.get(issue, "sourceFile") ?? "",
issue.code,
issue.severity,
issue.selector,
issue.containerSelector ?? "",
TEXT_AGNOSTIC_KEY_CODES.has(issue.code) ? "" : (issue.text ?? ""),
issue.overflow ? formatOverflow(issue.overflow) : "",
framePositionKey(issue),
].join("|");
}
function framePositionKey(issue: LayoutIssue): string {
// connector_detached and connector_orphan share it: id-less paths collapse to one selector, so distinct lines need geometry in the key.
return issue.code === "frame_out_of_frame" ||
issue.code === "connector_detached" ||
issue.code === "connector_orphan"
? `${Math.round(issue.rect.left)},${Math.round(issue.rect.top)}`
: "";
}
function uniqueSortedTimes(times: number[]): number[] {
const rounded = times.map(roundTime);
return [...new Set(rounded)].sort((a, b) => a - b);
}
export interface TransitionSampleOptions {
duration: number;
boundaries: number[];
/** Optional hard limit on the returned sample count. No limit when absent. */
cap?: number;
}
export interface TransitionSamples {
times: number[];
/** Sample times omitted because of `cap`. Always 0 when no cap is given. */
dropped: number;
}
/**
* Build sample times from tween start/end boundaries: the boundaries
* themselves plus the midpoint of every segment between consecutive
* boundaries. Boundary frames are where transient overlaps live (#1380), but
* sampling exactly at a boundary can land on an element at opacity 0 — the
* segment midpoints catch the window where both sides of a transition are
* partially visible. Every collected boundary is sampled unless the caller
* passes an explicit `cap`, in which case the result is an evenly-strided
* subset and `dropped` reports how many sample times were omitted.
*/
export function buildTransitionSampleTimes({
duration,
boundaries,
cap,
}: TransitionSampleOptions): TransitionSamples {
if (!Number.isFinite(duration) || duration <= 0) return { times: [], dropped: 0 };
const inRange = uniqueSortedTimes(
boundaries.filter((time) => Number.isFinite(time) && time >= 0 && time <= duration),
);
const withMidpoints = [...inRange];
for (let i = 0; i < inRange.length - 1; i++) {
const current = inRange[i];
const next = inRange[i + 1];
if (current === undefined || next === undefined) continue;
withMidpoints.push(roundTime((current + next) / 2));
}
const merged = uniqueSortedTimes(withMidpoints);
if (cap === undefined || merged.length <= Math.max(2, cap)) {
return { times: merged, dropped: 0 };
}
const limit = Math.max(2, cap);
const strided: number[] = [];
for (let i = 0; i < limit; i++) {
const pick = merged[Math.floor((i * (merged.length - 1)) / (limit - 1))];
if (pick !== undefined) strided.push(pick);
}
const times = uniqueSortedTimes(strided);
return { times, dropped: merged.length - times.length };
}
/** Merge sample-time lists into one deduplicated ascending list. */
export function mergeSampleTimes(...lists: number[][]): number[] {
return uniqueSortedTimes(lists.flat());
}
function formatOverflow(overflow: LayoutOverflow): string {
return (["left", "right", "top", "bottom"] as const)
.flatMap((side) => {
const value = overflow[side];
return value == null ? [] : `${side} ${formatNumber(value)}px`;
})
.join(", ");
}
function quoteText(text: string): string {
const normalized = text.replace(/\s+/g, " ").trim();
const truncated = normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
return `"${truncated}"`;
}
function formatNumber(value: number): string {
return Number.isInteger(value)
? String(value)
: value.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
}
function roundTime(value: number): number {
return Math.round(value * 1000) / 1000;
}
function roundPx(value: number): number {
return Math.round(value * 100) / 100;
}