Files
hyperframes/packages/cli/src/utils/layoutAudit.ts
T
Xuanru LiandClaude Opus 4.8 72e2f08f15 feat(lint): dense motion re-sampling for content_overlap (#2746)
* feat(lint): dense motion re-sampling for content_overlap

Transient text-on-text collisions during continuous motion (e.g. an
orbiting label card crossing the center card) overlap for a fraction of
a second that the sparse 9-point layout grid seeks straight past. The
content_overlap detector is correct; it just never gets a sample at the
crossing moment. Rerun ONLY content_overlap on an 8fps grid (text-only,
cheap) when the composition animates; findings feed the existing
persistence tiering unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(lint): unconditional dense content_overlap pass + honor 500ms floor

Round-1 blocker: the dense motion-overlap re-pass was gated on sparse-grid
geometry fingerprints changing, so an animation aliased to the sparse grid
(identical fingerprints, yet colliding between samples) bypassed the pass —
exactly the transient false-negative it was built to catch. Remove the gate:
the dense pass now runs unconditionally (bounded, text-only), driven by the
composition timeline rather than a fingerprint heuristic.

Round-2 follow-ups:
- Persistence-tier drift: at 8fps, occurrences>=2 spans only ~125ms, not the
  ~500ms the design intends, and it short-circuited before the ms floor.
  content_overlap promotion now requires BOTH occurrences>=2 AND a literal
  firstSeen..lastSeen span >= 500ms, so the wall-clock floor is honored at any
  sampling density. Comment block updated to match.
- Sample cap scales to hold a true 8fps grid up to ~75s (raised 120 -> 600)
  with an explicit note that longer comps degrade below 8fps to stay bounded.

Tests:
- Replaced the trivial "warning at every sample" test with a real between-grid
  regression: a collision living only inside (3.5,4.5) — a gap the sparse grid
  seeks past — is detected and, held ~750ms, promoted to error.
- Replaced the now-invalid "skips when static" test with one asserting the
  dense pass runs even when sparse fingerprints are identical (aliased motion).
- Added a tiering regression: two dense occurrences spanning ~125ms stay a
  warning (not error). Both new guards verified red before the fix.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* perf(lint): settle-free geometry seek for dense content_overlap pass

The dense overlap re-pass did up to OVERLAP_MAX_SAMPLES full-settle seeks
(120ms paint settle each, ~72s of pure sleep at the ceiling) even though
collectOverlap only reads getBoundingClientRect geometry, valid
synchronously after the timeline setTime. Add a settle-free
DENSE_GEOMETRY_SEEK_OPTIONS + driver.seekGeometry used only by the dense
loop; the base grid keeps full-settle driver.seek.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(lint): document + cover content_overlap 500ms boundary for sparse callers

The occurrences>=2 AND heldMs>=500 promotion rule is a semantics change for
sparse callers (--samples 20, --at, short comps) whose two samples can land
<500ms apart. Document the change in the tiering comment and add boundary
tests: 499ms span stays warning, 500ms span promotes to error.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(lint): make dense content_overlap seek genuinely geometry-only

Per review: DENSE_GEOMETRY_SEEK_OPTIONS only overrode settleMs, still
inheriting animationFrameSettle:double + waitForFontsMs:500 → ~3 frame
waits + font wait per seek → ~30s at the 600-sample cap. Geometry
(getBoundingClientRect) is valid synchronously post-setTime, so drop all
post-seek waits (animationFrameSettle:none, waitForFontsMs:0, settleMs:0).
Add options-level regression locking the geometry-only contract. Also fix
a stale comment name (detectMotionTextOverlap → collectMotionOverlapSamples).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* style: collapse multi-line comments to single lines

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-25 11:29:24 -07:00

449 lines
16 KiB
TypeScript

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"
| "text_occluded"
| "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"
| "connector_detached"
// 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;
firstSeen?: number;
lastSeen?: number;
occurrences?: number;
selector: string;
containerSelector?: string;
text?: string;
message: string;
rect: LayoutRect;
containerRect?: LayoutRect;
overflow?: LayoutOverflow;
/** `text_occluded` only: approximate fraction (0-1) of the occlusion probe
* grid that hit an opaque occluder — see layout-audit.browser.js. */
coveredFraction?: 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 the rule the
* browser audit (layout-audit.browser.js) uses to decide that text spilling
* past such an ancestor is intentionally masked (odometer/ticker reels) rather
* than a `text_box_overflow` defect. Kept here as the one unit-testable seam of
* that suppression: only `visible` (and the `clip visible` no-op) must NOT clip
* — every clipping value must, or real masked overflow gets reported as a bug.
*/
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 {
const timeLabel =
issue.occurrences && issue.occurrences > 1
? `t=${formatNumber(issue.firstSeen ?? issue.time)}-${formatNumber(issue.lastSeen ?? issue.time)}s (${issue.occurrences} samples)`
: `t=${formatNumber(issue.time)}s`;
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 = [
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.
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",
"text_occluded",
"escaped_container",
"panel_out_of_canvas",
"connector_detached",
]);
export function collapseStaticLayoutIssues(
issues: LayoutIssue[],
totalSampleCount?: number,
): LayoutIssue[] {
const groups = new Map<
string,
{
issue: LayoutIssue;
firstSeen: number;
lastSeen: number;
occurrences: 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,
});
continue;
}
existing.firstSeen = Math.min(existing.firstSeen, issue.time);
existing.lastSeen = Math.max(existing.lastSeen, issue.time);
existing.occurrences += 1;
}
// 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 }) =>
applyPersistenceTier(
{ ...issue, time: firstSeen, firstSeen, lastSeen, occurrences },
multiSampleRun,
),
);
}
/**
* 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): 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 { ...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 = (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 [
issue.code,
issue.severity,
issue.selector,
issue.containerSelector ?? "",
issue.text ?? "",
issue.overflow ? formatOverflow(issue.overflow) : "",
framePositionKey(issue),
].join("|");
}
function framePositionKey(issue: LayoutIssue): string {
// connector_detached shares 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"
? `${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;
}