Files
hyperframes/packages/cli/src/utils/checkPipeline.ts
T
WaterrrForeverandClaude Fable 5.2 820d63d7f9 feat(cli): check finds text over a face, measure cuts names resumed takes, measure hands (#8074)
* feat(cli): check reports text drawn over a face in a video

The layout audit reports text painted in front of an opaque video with its
word boxes and where the video's frame lands; Node finds the faces in the
video file with the detector `measure face` uses and adds a `text_over_face`
finding (info from 5% of the face covered, warning from 30%) with
`coveredFraction` and `faceRect`. `layout.faceCheck` in the report says
whether the pass looked. `data-layout-allow-on-face` waives it.

Also reads a two-token `object-position` whose first token is "50%" as the
horizontal one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(cli): measure cuts names the shot a take resumes

A shot that returns to an earlier camera setup after at least one other
shot (a wide take, a close-up cut into it, the wide take again) carries
`continues`: the index in `shots` of the shot it resumes. It is read from
the signatures `cuts` already decodes, by the scene's edges, so a person
who has moved or an exposure that drifted does not hide the match.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(cli): measure hands follows a hand through a clip

`measure hands <video>` reports where a hand's palm (with the hand's
size), index fingertip or pinch is in each sampled frame of a stretch of
up to 15 s, from MediaPipe's hand landmarker. A frame with no such hand
is null, never filled in. The landmarker runs in the CLI's headless
Chrome on a page answered from disk; its code and model are not shipped
and are downloaded on first use, pinned by size and sha256, into the
trusted cache.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(cli): text_over_face is info only, and a stalled OpenCV download no longer stalls check

The face detector can take texture for a face, so text_over_face is
reported as info however much of the face is covered and never fails
--strict.

check passes its deadline and a 30 s limit into the detector's first-use
OpenCV download. A download that does not answer costs the face pass
only: faceCheck is { ran: false, reason }, the other findings are kept
and the process exits.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-17 17:16:20 +00:00

2545 lines
94 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 { terminalLines } from "@hyperframes/core";
import { DEFAULT_CONFIG } from "@hyperframes/engine";
import { BrowserCleanupError, onStopSignal } from "../browser/launch.js";
import type { CheckProgress } from "./checkProgress.js";
import {
CheckBudgetError,
CheckDeadline,
CheckCopiesUnfinishedError,
CheckDeadlineError,
CheckStoppedError,
idleWindow,
type CheckPhase,
} from "./checkDeadline.js";
import {
checkSnapshotDirectory,
beginCheckSnapshots,
finishCheckSnapshots,
} from "./checkSnapshotDirectory.js";
import { findingAtRoot, findingElementKey, groupSampledFindings } from "./checkFindings.js";
import { safeZoneEdgesCrossed, safeZoneLabel, safeZonesFor, type SafeZone } from "./safeZones.js";
import {
MAX_FINDING_FRAME_TIMES,
selectFindingFrames,
withFindingFrameFields,
findingFrameRequests,
} from "./checkFindingFrames.js";
export { selectFindingFrames } from "./checkFindingFrames.js";
import { writeFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import type { PrelaunchedBrowser } from "../capture/captureCompositionFrame.js";
import { join, relative } from "node:path";
import { trackCheckReport, trackCommandFailure } from "../telemetry/events.js";
import { trackLintRun } from "../telemetry/lintRun.js";
import { getRunId } from "../telemetry/runId.js";
import type { ProjectDir } from "./project.js";
import { lintProject, type ProjectLintResult } from "./lintProject.js";
import { unmountedNotice } from "@hyperframes/lint";
import {
buildLayoutSampleTimes,
buildTransitionSampleTimes,
collapseStaticLayoutIssues,
CONTENT_OVERLAP_HELD_ERROR_MS,
longestContiguousRunMs,
dedupeLayoutIssues,
isGuidanceIssue,
limitLayoutIssues,
mergeSampleTimes,
type LayoutIssue,
type LayoutRect,
} from "./layoutAudit.js";
import {
assertionTargets,
collectSamplingTargets,
DEFAULT_MAX_STATIC_SEC,
evaluateMotion,
frozenSpans,
type Canvas,
type MotionFrame,
} from "./motionAudit.js";
import { findMotionSpec, readMotionSpec, type MotionAssertion } from "./motionSpec.js";
import { auditCraft } from "./craftAudit.js";
import { inspectHdrAutoPromotion, remoteMediaNotInspected } from "./hdrPromotion.js";
import { collectProjectMedia, type ProjectMedia } from "./projectMedia.js";
import { normalizeErrorMessage } from "./errorMessage.js";
import {
parseColorRGBA,
requiredContrastRatio,
suggestCompliantForegroundColor,
type Rgb,
} from "../commands/contrast-bg.js";
import { rectToBbox } from "./checkTypes.js";
import type {
AnchoredLayoutIssue,
CheckAnnotationBox,
CheckAuditDriver,
CheckBbox,
CheckBrowserResult,
CheckContrastFinding,
CheckDependencies,
CheckFinding,
CheckFindingCropRequest,
CheckFindingFrameRequest,
CheckFindingFrames,
CheckGeometryCandidate,
CheckOptions,
CheckReport,
CheckScreenshot,
CheckSection,
ContrastAuditEntry,
CraftFinding,
CraftFrame,
CraftResult,
FaceCheck,
GeometryCandidateRequest,
MotionSpecResolution,
OffPivotFrame,
OffPivotRotationSample,
RotationSample,
SeekClock,
TextOverVideoCandidate,
} from "./checkTypes.js";
export type {
AnchoredLayoutIssue,
CheckAnchor,
CheckAuditDriver,
CheckBrowserResult,
CheckDependencies,
CheckFinding,
CheckFindingCropRequest,
CheckFindingFrameRequest,
CheckOptions,
CheckReport,
CheckSection,
ContrastAuditEntry,
MotionSpecResolution,
} from "./checkTypes.js";
const MOTION_FPS = 20;
const MOTION_MAX_SAMPLES = 300;
const ZERO_BBOX: CheckBbox = { x: 0, y: 0, width: 0, height: 0 };
// Ignore normal in/out slide travel; only substantive frame breaches are actionable.
const FRAME_BREACH_FLOOR_PX = 120;
const FRAME_BREACH_FLOOR_FRACTION = 0.06;
export const DEFAULT_CHECK_OPTIONS: CheckOptions = {
samples: 9,
atTransitions: false,
maxIssues: 80,
collapseStatic: true,
tolerance: 2,
timeout: DEFAULT_CONFIG.playerReadyTimeout,
contrast: true,
strict: false,
snapshots: false,
browserGpuMode: "auto",
};
/** Pick at most five evenly-strided points from the already-merged layout grid. */
export function selectContrastTimes(grid: number[]): number[] {
if (grid.length <= 5) return [...grid];
return Array.from({ length: 5 }, (_, index) => {
const selected = Math.floor((index * (grid.length - 1)) / 4);
return grid[selected] ?? grid[0] ?? 0;
});
}
function buildMotionSampleTimes(duration: number): number[] {
if (!Number.isFinite(duration) || duration <= 0) return [];
const count = Math.min(MOTION_MAX_SAMPLES, Math.max(2, Math.ceil(duration * MOTION_FPS) + 1));
const step = duration / (count - 1);
return Array.from({ length: count }, (_, index) => Math.round(index * step * 1000) / 1000);
}
interface SampleGrid {
duration: number;
layoutSamples: number[];
/** `--at` times: they can all land on a still stretch, so the frozen-sweep guard never judges them. */
userPickedSamples: number[];
captionSamples: number[];
frameSamples: number[];
transitionSamples: number[];
transitionSamplesDropped: number;
contrastSamples: number[];
}
function gateSampleTimes(
duration: number,
seeks: number[] | undefined,
fallback: number,
): number[] {
if (!Number.isFinite(duration) || duration <= 0) return [];
const fractions = seeks && seeks.length > 0 ? seeks : [fallback];
return mergeSampleTimes(fractions.map((fraction) => fraction * duration));
}
function validateSampleRange([start, end]: [number, number], duration: number): void {
if (!Number.isFinite(start + end) || start < 0 || end <= start || end > duration)
throw new Error(`Check range must lie within the composition duration (${duration} seconds)`);
}
function gateSamplesInRange(
flag: "--caption-zone" | "--frame-check",
samples: number[],
inRange: (time: number) => boolean,
range: [number, number] | undefined,
): number[] {
if (!range) return samples;
const selected = samples.filter(inRange);
if (samples.length > 0 && selected.length === 0) {
throw new Error(`No ${flag} seek samples lie within --range`);
}
return selected;
}
function layoutSamplesInRange(options: CheckOptions, duration: number) {
if (!options.range)
return {
inRange: (_t: number) => true,
baseSamples: buildLayoutSampleTimes({ duration, samples: options.samples, at: options.at }),
};
validateSampleRange(options.range, duration);
const [start, end] = options.range;
const inRange = (t: number) => t >= start && t <= end;
const selected = (options.at ?? []).filter(inRange);
if (options.at?.length && !selected.length) throw new Error("No --at samples lie within --range");
const baseSamples = buildLayoutSampleTimes({
duration: end - start,
samples: options.samples,
at: selected.map((t) => t - start),
}).map((t) => t + start);
return { inRange, baseSamples };
}
async function buildSampleGrid(
driver: CheckAuditDriver,
options: CheckOptions,
): Promise<SampleGrid> {
const duration = await driver.getDuration();
const { inRange, baseSamples } = layoutSamplesInRange(options, duration);
const transitions = options.atTransitions
? buildTransitionSampleTimes({
duration,
boundaries: (await driver.getTransitionBoundaries()).filter(inRange),
cap: options.maxTransitionSamples,
})
: { times: [], dropped: 0 };
const captionSamples = gateSamplesInRange(
"--caption-zone",
options.captionZone ? gateSampleTimes(duration, options.captionZone.seek, 1) : [],
inRange,
options.range,
);
const frameSamples = gateSamplesInRange(
"--frame-check",
options.frameCheck ? gateSampleTimes(duration, options.frameCheck.seek, 0.5) : [],
inRange,
options.range,
);
transitions.times = transitions.times.filter(inRange);
const auditSamples = mergeSampleTimes(baseSamples, transitions.times).filter(inRange);
const layoutSamples = mergeSampleTimes(auditSamples, captionSamples, frameSamples).filter(
inRange,
);
if (layoutSamples.length === 0) {
throw new Error("Could not determine composition duration — no layout samples run");
}
return {
duration,
layoutSamples,
userPickedSamples: options.at?.length ? baseSamples : [],
captionSamples,
frameSamples,
transitionSamples: transitions.times,
transitionSamplesDropped: transitions.dropped,
contrastSamples: options.contrast ? selectContrastTimes(auditSamples) : [],
};
}
interface MotionPlan {
times: number[];
selectors: string[];
livenessScopes: string[];
preflightIssues: AnchoredLayoutIssue[];
assertions: MotionAssertion[];
}
async function planMotionSampling(
driver: CheckAuditDriver,
motion: MotionSpecResolution,
duration: number,
): Promise<MotionPlan> {
if (motion.kind !== "valid") {
return { times: [], selectors: [], livenessScopes: [], preflightIssues: [], assertions: [] };
}
const preflightIssues = await driver.findAmbiguousSelectors(
collectSamplingTargets(motion.spec.assertions).selectors,
);
const ambiguous = new Set(preflightIssues.map((issue) => issue.selector));
const assertions = motion.spec.assertions.filter(
(assertion) =>
!assertionTargets(assertion).selectors.some((selector) => ambiguous.has(selector)),
);
noteSkippedAssertions(preflightIssues, motion.spec.assertions);
const targets = collectSamplingTargets(assertions);
const times =
assertions.length > 0 ? buildMotionSampleTimes(motion.spec.duration ?? duration) : [];
return { times, ...targets, preflightIssues, assertions };
}
function noteSkippedAssertions(issues: AnchoredLayoutIssue[], assertions: MotionAssertion[]): void {
for (const issue of issues) {
const skipped = assertions.filter((assertion) =>
assertionTargets(assertion).selectors.includes(issue.selector),
).length;
if (skipped > 0) issue.message += ` ${skipped} assertion(s) naming it were not evaluated.`;
}
}
interface GridSamples {
layoutIssues: AnchoredLayoutIssue[];
motionFrames: MotionFrame[];
contrastEntries: ContrastAuditEntry[];
screenshots: CheckScreenshot[];
contrastMs: number;
gridMs: number;
craftMs: number;
overlapMs: number;
/** One visible-state fingerprint and seek clock per layout sample (#U10 frozen-sweep guard). */
layoutStateSignatures: { time: number; signature: string; clock: SeekClock[] }[];
/** Every rotatable element's geometry at each layout sample; grouped by
* selector after the run to detect rotation_pivot_drift. */
rotationSamples: RotationSample[];
/** One time-hoisted frame of every elongated rotating SVG figure's
* material-point geometry + dial hub per layout sample; flattened by selector
* to detect off_pivot_rotation. */
indicatorFrames: OffPivotFrame[];
/** Text painted in front of a video at each layout sample; faces are looked for after the run. */
textOverVideo: TextOverVideoCandidate[];
/** No page that sampled could report text over video. */
textOverVideoUnavailable: boolean;
craftFrames: CraftFrame[];
}
function geometryRequest(
time: number,
grid: SampleGrid,
options: CheckOptions,
sets: SampleSets,
): GeometryCandidateRequest | null {
const text = grid.captionSamples.includes(time);
const media = grid.frameSamples.includes(time);
const blocks = sets.safeZones.length > 0 && sets.layout.has(time);
if (!text && !media && !blocks) return null;
const configuredTolerance = options.frameCheck?.tol;
const tolerance = typeof configuredTolerance === "number" ? configuredTolerance : 2;
return { text, media, blocks, tolerance };
}
function candidateIsSized(candidate: CheckGeometryCandidate, canvas: Canvas): boolean {
if (candidate.elementRect.width < 4 || candidate.elementRect.height < 4) return false;
return !(
candidate.elementRect.width >= 0.95 * canvas.width &&
candidate.elementRect.height >= 0.95 * canvas.height
);
}
function geometryIssueAnchor(candidate: CheckGeometryCandidate, time: number) {
return {
selector: candidate.selector,
dataAttributes: candidate.dataAttributes,
sourceFile: candidate.sourceFile,
bbox: candidate.bbox,
time,
rect: candidate.rect,
};
}
function captionBoxOverlapsZone(
box: CheckGeometryCandidate["elementRect"],
zone: NonNullable<CheckOptions["captionZone"]>,
canvas: Canvas,
): { overlaps: boolean; cy: number } {
const zx0 = zone.x0 * canvas.width;
const zy0 = zone.y0 * canvas.height;
const zx1 = zone.x1 * canvas.width;
const zy1 = zone.y1 * canvas.height;
const bx1 = box.left + box.width;
const by1 = box.top + box.height;
const overlaps = box.left < zx1 && bx1 > zx0 && box.top < zy1 && by1 > zy0;
return { overlaps, cy: box.top + box.height / 2 };
}
function captionFinding(
candidate: CheckGeometryCandidate,
options: CheckOptions,
canvas: Canvas,
time: number,
): AnchoredLayoutIssue | null {
const zone = options.captionZone;
if (!zone || candidate.kind !== "text" || !candidateIsSized(candidate, canvas)) return null;
// Backstop for mocks/non-browser sources; browser already strips via closest() (own attrs only here).
if ("data-layout-allow-caption-zone" in candidate.dataAttributes) return null;
const { overlaps, cy } = captionBoxOverlapsZone(candidate.elementRect, zone, canvas);
if (!overlaps) return null;
const text = candidate.text.slice(0, 48);
const pctFromBottom = Math.round(((canvas.height - cy) / canvas.height) * 100);
return {
...geometryIssueAnchor(candidate, time),
code: "caption_zone_collision",
severity: zone.severity === "error" ? "error" : "warning",
text,
message: `<${candidate.tag}> "${text}" overlaps the reserved caption band (~${pctFromBottom}% up from the bottom).`,
fixHint:
"Keep main content outside the configured caption band, or mark intentional lower-third copy with data-layout-allow-caption-zone.",
};
}
function safeZoneFinding(
candidate: CheckGeometryCandidate,
zones: SafeZone[],
canvas: Canvas,
time: number,
): AnchoredLayoutIssue | null {
if (candidate.kind !== "block" || candidate.rect.width < 4 || candidate.rect.height < 4) {
return null;
}
// Backstop for mocks/non-browser sources; the browser already drops opted-out text.
if ("data-layout-allow-safe-zone" in candidate.dataAttributes) return null;
const crossed = zones.flatMap((zone) => {
const edges = safeZoneEdgesCrossed(candidate.rect, canvas, zone);
if (edges.length === 0) return [];
return [`${safeZoneLabel(zone)} (${edges.join(" and ")} edge${edges.length > 1 ? "s" : ""})`];
});
if (crossed.length === 0) return null;
const text = candidate.text.slice(0, 48);
return {
...geometryIssueAnchor(candidate, time),
code: "outside_safe_zone",
severity: "warning",
text,
message: `<${candidate.tag}> "${text}" is outside the safe area: ${crossed.join(", ")}.`,
fixHint:
"Move the text inside the safe area, or mark text meant to sit there with data-layout-allow-safe-zone.",
};
}
function maxOverflow(candidate: CheckGeometryCandidate): number {
if (!candidate.overflow) return 0;
return Math.max(
candidate.overflow.left ?? 0,
candidate.overflow.top ?? 0,
candidate.overflow.right ?? 0,
candidate.overflow.bottom ?? 0,
);
}
function overflowMessage(candidate: CheckGeometryCandidate): string {
const overflow = candidate.overflow ?? {};
const edges: string[] = [];
if (overflow.left) edges.push(`${overflow.left}px past the left`);
if (overflow.top) edges.push(`${overflow.top}px past the top`);
if (overflow.right) edges.push(`${overflow.right}px past the right`);
if (overflow.bottom) edges.push(`${overflow.bottom}px past the bottom`);
return `<${candidate.tag}> "${candidate.text.slice(0, 48)}" spills outside the frame (${edges.join(", ")}).`;
}
function frameFinding(
candidate: CheckGeometryCandidate,
options: CheckOptions,
canvas: Canvas,
time: number,
): AnchoredLayoutIssue | null {
if (!options.frameCheck || candidate.kind !== "media" || !candidateIsSized(candidate, canvas)) {
return null;
}
const floor = Math.max(
FRAME_BREACH_FLOOR_PX,
FRAME_BREACH_FLOOR_FRACTION * Math.min(canvas.width, canvas.height),
);
if (maxOverflow(candidate) < floor) return null;
const text = candidate.text.slice(0, 48);
return {
...geometryIssueAnchor(candidate, time),
code: "frame_out_of_frame",
severity: options.frameCheck.severity === "error" ? "error" : "warning",
text,
overflow: candidate.overflow,
message: overflowMessage(candidate),
fixHint: "Keep media within the composition frame's safe area.",
};
}
async function collectGeometryAt(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
sets: SampleSets,
canvas: Canvas,
time: number,
): Promise<AnchoredLayoutIssue[]> {
const request = geometryRequest(time, grid, options, sets);
if (!request) return [];
const candidates = await driver.collectGeometryCandidates(time, request);
return candidates
.flatMap((candidate) => [
request.blocks ? safeZoneFinding(candidate, sets.safeZones, canvas, time) : null,
request.text ? captionFinding(candidate, options, canvas, time) : null,
request.media ? frameFinding(candidate, options, canvas, time) : null,
])
.filter((finding): finding is AnchoredLayoutIssue => finding !== null);
}
function emptyGridSamples(): GridSamples {
return {
layoutIssues: [],
motionFrames: [],
contrastEntries: [],
screenshots: [],
contrastMs: 0,
gridMs: 0,
craftMs: 0,
overlapMs: 0,
layoutStateSignatures: [],
rotationSamples: [],
indicatorFrames: [],
textOverVideo: [],
textOverVideoUnavailable: false,
craftFrames: [],
};
}
function appendGridSamples(into: GridSamples, from: GridSamples): void {
into.layoutIssues.push(...from.layoutIssues);
into.motionFrames.push(...from.motionFrames);
into.contrastEntries.push(...from.contrastEntries);
into.screenshots.push(...from.screenshots);
// Summed over pages, so with a helper it can exceed the wall time.
into.contrastMs += from.contrastMs;
into.layoutStateSignatures.push(...from.layoutStateSignatures);
into.rotationSamples.push(...from.rotationSamples);
into.indicatorFrames.push(...from.indicatorFrames);
into.textOverVideo.push(...from.textOverVideo);
into.textOverVideoUnavailable ||= from.textOverVideoUnavailable;
into.craftFrames.push(...from.craftFrames);
}
interface SampleSets {
layout: Set<number>;
motion: Set<number>;
contrast: Set<number>;
canvas: Canvas | null;
/** Platforms to judge text against; empty unless the frame is 9:16. */
safeZones: SafeZone[];
}
async function collectSampleAt(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
motion: MotionPlan,
sets: SampleSets,
time: number,
): Promise<GridSamples> {
const collected = emptyGridSamples();
await driver.seek(time, sets.contrast.has(time));
// Findings collected for THIS sample time, so the overview overlay (below)
// only ever annotates a frame with defects that are actually valid at
// that render time — never a stale bbox from an earlier/later sample.
const issuesAtTime: AnchoredLayoutIssue[] = [];
if (sets.layout.has(time)) {
const layoutIssues = await driver.collectLayout(time, options.tolerance, options.layout);
collected.layoutIssues.push(...layoutIssues);
issuesAtTime.push(...layoutIssues);
collected.layoutStateSignatures.push({
time,
signature: await driver.collectLayoutGeometry(),
clock: await driver.collectSeekClock(),
});
collected.rotationSamples.push(...(await driver.collectRotationSample(time)));
collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));
if (driver.collectTextOverVideo) {
collected.textOverVideo.push(...(await driver.collectTextOverVideo(time)));
} else collected.textOverVideoUnavailable = true;
}
if (sets.canvas) {
const geometryIssues = await collectGeometryAt(driver, options, grid, sets, sets.canvas, time);
collected.layoutIssues.push(...geometryIssues);
issuesAtTime.push(...geometryIssues);
}
if (sets.motion.has(time)) {
collected.motionFrames.push(
await driver.collectMotionFrame(time, motion.selectors, motion.livenessScopes),
);
}
if (sets.contrast.has(time))
await collectContrastAt(driver, options, time, issuesAtTime, collected);
return collected;
}
async function buildSampleSets(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
motion: MotionPlan,
): Promise<SampleSets> {
const safeZones = options.safeZones ?? [];
const geometryEnabled =
grid.captionSamples.length > 0 || grid.frameSamples.length > 0 || safeZones.length > 0;
const canvas = geometryEnabled ? await driver.getCanvas() : null;
return {
layout: new Set(grid.layoutSamples),
motion: new Set(motion.times),
contrast: new Set(grid.contrastSamples),
canvas,
safeZones: canvas ? safeZonesFor(safeZones, canvas) : [],
};
}
// Frames are a function of time, so a helper page that is ready takes the next unclaimed sample
// and the merge keeps the serial order. A helper only adds speed: one that fails hands its samples back.
async function collectGridSamples(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
motion: MotionPlan,
helpers: Promise<CheckAuditDriver[]>,
enter: (phase: CheckPhase, detail?: string) => void,
report: CheckProgress,
keep: (read: () => Partial<CheckBrowserResult>) => void,
): Promise<GridSamples> {
const sets = await buildSampleSets(driver, options, grid, motion);
const gridStart = performance.now();
const times = mergeSampleTimes(grid.layoutSamples, motion.times);
const pending = times.map((_, index) => index);
const perTime: GridSamples[] = [];
keep(() => {
const so = emptyGridSamples();
for (const samples of perTime) if (samples) appendGridSamples(so, samples);
const contrast = buildContrastResults(so.contrastEntries);
return {
layoutIssues: so.layoutIssues,
contrastFindings: contrast.findings,
contrastChecked: so.contrastEntries.length,
contrastPassed: contrast.passed,
};
});
let finished = 0;
const work = async (worker: CheckAuditDriver, taken: number[] = []) => {
for (let index = pending.shift(); index !== undefined; index = pending.shift()) {
taken.push(index);
const time = times[index] ?? 0;
enter("samples", `layout sample at ${time}s`);
perTime[index] = await collectSampleAt(worker, options, grid, motion, sets, time);
enter("samples");
report("samples", ++finished, times.length);
}
};
const helpWith = async (helper: CheckAuditDriver) => {
const taken: number[] = [];
try {
await helper.initialize(options.contrast);
helper.markSamples?.("start");
await work(helper, taken);
helper.markSamples?.("end");
} catch {
helper.markSamples?.("drop");
for (const index of taken) delete perTime[index];
pending.push(...taken);
}
};
let firstPageDone = false;
const running: Promise<void>[] = [];
void helpers.then((ready) => {
for (const helper of ready) if (!firstPageDone) running.push(helpWith(helper));
});
driver.markSamples?.("start");
await work(driver);
// A helper still opening is never waited for; one mid-sample may yet hand samples back.
firstPageDone = true;
await Promise.all(running);
await work(driver);
driver.markSamples?.("end");
const collected = emptyGridSamples();
for (const samples of perTime) appendGridSamples(collected, samples);
collected.gridMs = Math.round(performance.now() - gridStart);
enter("overlap");
await collectMotionOverlapSamples(
driver,
grid,
collected,
options.range,
craftEnabled(driver, options),
(detail) => enter("overlap", detail),
report,
);
enter("samples");
return collected;
}
function craftEnabled(driver: CheckAuditDriver, options: CheckOptions): boolean {
return (
options.craft !== false && !options.range && typeof driver.collectCraftFrame === "function"
);
}
async function collectContrastAt(
driver: CheckAuditDriver,
options: CheckOptions,
time: number,
issuesAtTime: AnchoredLayoutIssue[],
collected: GridSamples,
): Promise<void> {
const contrastStart = Date.now();
const annotations = options.snapshots ? annotationBoxesFrom(issuesAtTime) : undefined;
const capture = options.skipContrastInMotion
? await driver.collectContrast(time, annotations, true)
: options.snapshots
? await driver.collectContrast(time, annotations)
: await driver.collectContrast(time);
collected.contrastMs += Date.now() - contrastStart;
collected.contrastEntries.push(...capture.entries);
if (capture.pngBase64) collected.screenshots.push({ time, pngBase64: capture.pngBase64 });
}
// Dense grid catches mid-motion text collisions the sparse layout grid seeks past; text-only overlap collection is cheap enough to afford it.
const OVERLAP_SAMPLE_FPS = 8;
// A fixed ceiling, so check's work does not grow with film length: half uniform, half in clip windows it misses.
const OVERLAP_MAX_SAMPLES = 240;
// Part of it re-looks at an overlap half a second on where the grid is too sparse to show it held.
const OVERLAP_HOLD_PROBES = 60;
const OVERLAP_BATCH = 8;
function evenlyPicked(times: number[], count: number): number[] {
if (times.length <= count) return times;
const last = Math.max(1, count - 1);
return Array.from(
{ length: count },
(_, i) => times[Math.floor((i * (times.length - 1)) / last)] ?? 0,
);
}
function uniformTimes(duration: number, fill: number): number[] {
const step = duration / Math.max(1, fill - 1);
return Array.from({ length: fill }, (_, i) => i * step);
}
function buildOverlapSampleTimes(duration: number, clipEdges: number[]): number[] {
if (!Number.isFinite(duration) || duration <= 0) return [];
const count = Math.min(
OVERLAP_MAX_SAMPLES - OVERLAP_HOLD_PROBES,
Math.max(2, Math.ceil(duration * OVERLAP_SAMPLE_FPS) + 1),
);
const cuts: number[] = [];
for (const time of mergeSampleTimes(
[0, duration],
clipEdges.filter((t) => t > 0 && t < duration),
))
if (time - (cuts.at(-1) ?? -Infinity) >= CONTENT_OVERLAP_HELD_ERROR_MS / 1000) cuts.push(time);
// A stretch where the visible clips stay the same, and that the uniform half steps over, gets one sample.
const uncovered = (fill: number): number[] => {
const step = duration / Math.max(1, fill - 1);
return cuts.slice(1).flatMap((end, i) => {
const start = cuts[i] ?? 0;
return Math.floor(start / step) === Math.floor(end / step) ? [(start + end) / 2] : [];
});
};
let fill = count - Math.floor(count / 2);
let windows = uncovered(fill);
if (windows.length < count - fill) {
fill = count - windows.length;
windows = uncovered(fill);
}
const picked = evenlyPicked(windows, count - fill);
return mergeSampleTimes(
[...picked, ...uniformTimes(duration, fill)].map((t) => Math.round(t * 1000) / 1000),
);
}
/** Looks once more half a second on, where the grid is too sparse to show an overlap is held; each overlap once. */
function holdProber(driver: CheckAuditDriver, collected: GridSamples, end: number) {
const holdS = CONTENT_OVERLAP_HELD_ERROR_MS / 1000;
const held = new Set<string>();
const keyOf = (issue: AnchoredLayoutIssue) => `${issue.code} ${issue.selector}`;
let probes = 0;
return async (time: number, next: number, issues: AnchoredLayoutIssue[]): Promise<void> => {
const unproven = new Set(issues.map(keyOf).filter((key) => !held.has(key)));
const probe = Math.round((time + holdS) * 1000) / 1000;
const sparse = next - time > 2 * holdS && probe <= end;
if (!unproven.size || !sparse || probes >= OVERLAP_HOLD_PROBES) return;
probes += 1;
await driver.seekGeometry(probe);
const later = await driver.collectOverlap(probe);
collected.layoutIssues.push(...later);
for (const key of later.map(keyOf)) if (unproven.has(key)) held.add(key);
};
}
async function denseOverlapTimes(
driver: CheckAuditDriver,
grid: SampleGrid,
range?: [number, number],
): Promise<number[]> {
const offset = range?.[0] ?? 0;
const edges = (await driver.getClipEdges()).map((time) => time - offset);
const overlapTimes = buildOverlapSampleTimes(range ? range[1] - range[0] : grid.duration, edges);
return range ? mergeSampleTimes(overlapTimes.map((time) => time + range[0])) : overlapTimes;
}
/** Reruns content_overlap on a fine grid, unconditionally rather than gated on fingerprint change, since an animation aliased to the sparse grid collides between identical-fingerprint samples. */
async function collectOverlapGridInBatches(
driver: CheckAuditDriver,
times: number[],
progress: (detail?: string) => void,
report: CheckProgress,
): Promise<AnchoredLayoutIssue[][]> {
const issues: AnchoredLayoutIssue[][] = [];
const batches = Math.ceil(times.length / OVERLAP_BATCH);
for (let from = 0; from < times.length; from += OVERLAP_BATCH) {
progress(`overlap probes from ${times[from]}s`);
issues.push(...(await driver.collectOverlapGrid(times.slice(from, from + OVERLAP_BATCH))));
progress();
report("overlap", from / OVERLAP_BATCH + 1, batches);
}
return issues;
}
async function collectMotionOverlapSamples(
driver: CheckAuditDriver,
grid: SampleGrid,
collected: GridSamples,
range: [number, number] | undefined,
craft: boolean,
progress: (detail?: string) => void,
report: CheckProgress,
): Promise<void> {
const baseTimes = new Set(grid.layoutSamples);
const shiftedTimes = await denseOverlapTimes(driver, grid, range);
// Before the grid: a seek after it would overwrite the span the grid stamps on what its samples queue.
if (craft) {
const craftStart = performance.now();
// The render's last frame lands before the duration, where the runtime has already unmounted clips.
const craftTimes = buildCraftSampleTimes(grid.duration).filter((time) => time < grid.duration);
const last = craftTimes.length - 1;
for (let index = 0, sampled = 1; index <= last; sampled += 1) {
const time = craftTimes[index]!;
progress(`craft frame at ${time}s`);
await driver.seekGeometry(time, { draws: true });
collected.craftFrames.push(...(await collectCraftFrame(driver, time)));
progress();
report("craft", index + 1, craftTimes.length);
index =
index === last
? last + 1
: Math.min(last, index + craftStride(craftStart, sampled, last - index));
}
collected.craftMs = Math.round(performance.now() - craftStart);
}
const overlapStart = performance.now();
const probeHold = holdProber(driver, collected, range ? range[1] : grid.duration);
const gridTimes = shiftedTimes.filter((t) => !baseTimes.has(t));
const gridIssues = await collectOverlapGridInBatches(driver, gridTimes, progress, report);
let sample = 0;
for (const [index, time] of shiftedTimes.entries()) {
if (baseTimes.has(time)) continue;
const issues = gridIssues[sample++] ?? [];
collected.layoutIssues.push(...issues);
await probeHold(time, shiftedTimes[index + 1] ?? Number.POSITIVE_INFINITY, issues);
progress();
}
collected.overlapMs = Math.round(performance.now() - overlapStart);
}
// Craft times how long a line shows, so it keeps 8 fps past the overlap pass's ceiling, up to ~75 s.
const CRAFT_SAMPLE_FPS = 8;
const CRAFT_MAX_SAMPLES = 600;
const CRAFT_BUDGET_MS = 90_000;
const CRAFT_MAX_STRIDE = 12;
function craftStride(startedAt: number, sampled: number, remaining: number): number {
const spent = performance.now() - startedAt;
const left = CRAFT_BUDGET_MS - spent;
const wanted = left <= 0 ? remaining : Math.ceil(((spent / sampled) * remaining) / left);
return Math.min(CRAFT_MAX_STRIDE, Math.max(1, wanted));
}
function buildCraftSampleTimes(duration: number): number[] {
if (!Number.isFinite(duration) || duration <= 0) return [];
const count = Math.min(
CRAFT_MAX_SAMPLES,
Math.max(2, Math.ceil(duration * CRAFT_SAMPLE_FPS) + 1),
);
const step = duration / (count - 1);
return mergeSampleTimes(
Array.from({ length: count }, (_, index) => Math.round(index * step * 1000) / 1000),
);
}
async function collectCraftFrame(driver: CheckAuditDriver, time: number): Promise<CraftFrame[]> {
return driver.collectCraftFrame ? [await driver.collectCraftFrame(time)] : [];
}
// Frozen-sweep guard (#U10): compositions this short can legitimately hold a
// single static frame the whole time (a title card) — never flag those.
const SWEEP_STATIC_MIN_DURATION_SEC = 3;
const ZERO_LAYOUT_RECT: LayoutRect = {
left: 0,
top: 0,
right: 0,
bottom: 0,
width: 0,
height: 0,
};
/**
* Frozen-sweep guard (#U10): if every layout-grid sample produced the exact
* same visible-state fingerprint (see motion-signature.browser.js), the seek
* never actually advanced the composition's timeline — every other green
* verdict from this run is meaningless, not just a missed defect. Skips
* short (<3s) compositions, single-sample runs (nothing to compare), and
* runs where a `motion_frozen` finding already reported the same underlying
* symptom (no double-reporting the one thing that's wrong). A frame that never
* changes is an error only when an animation it can see is stuck and never finished.
*/
function detectSweepStatic(
duration: number,
samples: { signature: string; clock: SeekClock[] }[],
motionIssues: AnchoredLayoutIssue[],
hasNoTimelineDeclaration: boolean,
): AnchoredLayoutIssue[] {
if (hasNoTimelineDeclaration) return [];
if (duration < SWEEP_STATIC_MIN_DURATION_SEC) return [];
if (samples.length < 2) return [];
if (motionIssues.some((issue) => issue.code === "motion_frozen")) return [];
const signatures = samples.map((sample) => sample.signature);
if (allSame(signatures))
return [sweepStaticIssue(anAnimationIsStuck(samples) ? "error" : "still")];
if (allSame(signatures.map(seenPart))) return [sweepStaticIssue("audio")];
return [];
}
// The signature reads DOM channels, which miss paint such as SVG mask and clip contents, stroke dashes and
// canvas or WebGL pixels. Before calling a sweep still, the rendered frames get the last word. A change counts
// only if the first time still renders its first frame: wall-clock paint (an unregistered rAF loop) is no seek.
async function framesMoved(driver: CheckAuditDriver, times: number[]): Promise<boolean> {
const [firstTime, ...rest] = times;
if (firstTime === undefined) return false;
const first = await frameAt(driver, firstTime);
for (const time of rest) {
if (!(await driver.framesDiffer(first, await frameAt(driver, time)))) continue;
return !(await driver.framesDiffer(first, await frameAt(driver, firstTime)));
}
return false;
}
async function frameAt(driver: CheckAuditDriver, time: number, scope?: string): Promise<string> {
await driver.seek(time, true);
return driver.captureFrame(scope);
}
// keepsMoving reads the same liveness channels, so a span it calls frozen gets the frames' word too: one capture
// every half maxStaticSec, compared with the last capture that differed; frames up to the next capture share its mark.
async function withFrameMotion(
driver: CheckAuditDriver,
frames: MotionFrame[],
assertions: MotionAssertion[],
): Promise<MotionFrame[]> {
const marked = frames.map((frame) => ({ ...frame, liveness: { ...frame.liveness } }));
for (const assertion of assertions) {
if (assertion.kind !== "keepsMoving") continue;
const scope = assertion.withinSelector ?? "*";
// A scope that matched nothing stays motion_selector_missing.
if (frames.every((frame) => !frame.liveness[scope])) continue;
const maxStaticSec = assertion.maxStaticSec ?? DEFAULT_MAX_STATIC_SEC;
for (const span of frozenSpans(frames, scope, maxStaticSec)) {
const held = frames.find((frame) => frame.time === span.start)?.liveness[scope];
// The frame that ends a span opens the next run, so only frames still holding the span's signature belong.
const inSpan = marked.filter(
(frame, index) =>
frame.time >= span.start &&
frame.time <= span.end &&
frames[index]?.liveness[scope] === held,
);
await markFrameChanges(driver, inSpan, assertion.withinSelector, maxStaticSec / 2);
}
}
return marked;
}
async function markFrameChanges(
driver: CheckAuditDriver,
frames: MotionFrame[],
within: string | undefined,
captureEverySec: number,
): Promise<void> {
const scope = within ?? "*";
let reference: string | undefined;
let mark = 0;
let nextCapture = Number.NEGATIVE_INFINITY;
for (const frame of frames) {
if (frame.time >= nextCapture) {
nextCapture = frame.time + captureEverySec;
const capture = await frameAt(driver, frame.time, within);
if (reference === undefined) reference = capture;
else if (await driver.framesDiffer(reference, capture)) {
reference = capture;
mark++;
}
}
frame.liveness[scope] = `${frame.liveness[scope] ?? ""}|frame${mark}`;
}
}
function anAnimationIsStuck(samples: { clock: SeekClock[] }[]): boolean {
const seenById = new Map<number, SeekClock[]>();
for (const sample of samples) {
for (const clock of new Map(sample.clock.map((clock) => [clock.id, clock])).values()) {
seenById.set(clock.id, [...(seenById.get(clock.id) ?? []), clock]);
}
}
return [...seenById.values()].some(
(seen) =>
seen.length > 1 &&
allSame(seen.map((clock) => clock.time)) &&
seen.every((clock) => !clock.done),
);
}
// motion-signature.browser.js appends audio time after this; a signature without it is all "seen".
const AUDIO_TIME_SEPARATOR = "\u001f";
function seenPart(signature: string): string {
return signature.split(AUDIO_TIME_SEPARATOR)[0] ?? signature;
}
function allSame(values: readonly unknown[]): boolean {
return values.every((value) => value === values[0]);
}
const STILL_FIX_HINT =
"If the composition is meant to be still, add `data-no-timeline` to the element with `data-composition-id`. Otherwise confirm it seeks a paused GSAP/CSS timeline under `data-*` timing attributes rather than only autoplaying.";
const SWEEP_STATIC_MESSAGES = {
error: "Timeline did not advance under seek; every green verdict on this run is unreliable.",
still: "Nothing on screen moved under seek.",
audio: "Only the audio advanced under seek; nothing on screen moved.",
};
function sweepStaticIssue(kind: keyof typeof SWEEP_STATIC_MESSAGES): AnchoredLayoutIssue {
return {
code: "sweep_static",
severity: kind === "error" ? "error" : "warning",
time: 0,
selector: "[data-composition-id]",
dataAttributes: {},
sourceFile: "index.html",
bbox: ZERO_BBOX,
rect: ZERO_LAYOUT_RECT,
message: SWEEP_STATIC_MESSAGES[kind],
fixHint:
kind === "error"
? "An animation on the page never moved under seek. Build it on the paused GSAP timeline registered in `window.__timelines[compositionId]`, or as a CSS animation, so the seek drives it."
: STILL_FIX_HINT,
};
}
// rotation_pivot_drift: bbox center should stay fixed while the element spins.
const ROTATION_MIN_SAMPLES = 3;
// Minimum angle spread that counts as spinning rather than a static tilt.
const ROTATION_MIN_ANGLE_SPREAD_DEG = 20;
// Long-axis AABB growth ceiling (square@45° ≈ 1.41×); rejects non-rigid blow-ups before the model fit.
const ROTATION_MAX_SIZE_RATIO = 1.6;
// Relative slack when matching observed AABB to one rigid unrotated rectangle.
const ROTATION_RIGID_AABB_RATIO = 1.15;
// |cos2θ| below this → 45°-class sample; skip as an unrotated-size estimator (singular).
const ROTATION_RIGID_ESTIMATE_MIN_DET = 0.15;
// Skip tiny decorative spinners; only sizable rotating figures matter.
const ROTATION_MIN_MEDIAN_AREA_PX = 2500;
const ROTATION_DRIFT_SIZE_FRACTION = 0.1;
const ROTATION_DRIFT_VIEWPORT_FRACTION = 0.02;
function median(values: number[]): number {
if (values.length === 0) return 0;
const sorted = [...values].sort((a, b) => a - b);
const mid = Math.floor(sorted.length / 2);
const upper = sorted[mid] ?? 0;
return sorted.length % 2 === 0 ? ((sorted[mid - 1] ?? 0) + upper) / 2 : upper;
}
/** Widest angular gap between any two samples, wrap-aware (0/360 continuity). */
function maxAngleSpread(angles: number[]): number {
let max = 0;
for (let i = 0; i < angles.length; i++) {
const a = angles[i];
if (a === undefined) continue;
for (let j = i + 1; j < angles.length; j++) {
const b = angles[j];
if (b === undefined) continue;
const raw = Math.abs(a - b) % 360;
max = Math.max(max, Math.min(raw, 360 - raw));
}
}
return max;
}
/** Largest distance between any two bbox centers across the samples. */
function maxCenterDrift(samples: RotationSample[]): number {
let max = 0;
for (let i = 0; i < samples.length; i++) {
const first = samples[i];
if (!first) continue;
for (let j = i + 1; j < samples.length; j++) {
const second = samples[j];
if (!second) continue;
max = Math.max(max, Math.hypot(first.cx - second.cx, first.cy - second.cy));
}
}
return max;
}
function rotationDriftFinding(
samples: RotationSample[],
drift: number,
): AnchoredLayoutIssue | null {
const last = samples[samples.length - 1];
if (!last) return null;
const rect: LayoutRect = {
left: last.cx - last.w / 2,
top: last.cy - last.h / 2,
right: last.cx + last.w / 2,
bottom: last.cy + last.h / 2,
width: last.w,
height: last.h,
};
return {
code: "rotation_pivot_drift",
// EF promotes this to error separately; keep it a warning here.
severity: "warning",
time: last.time,
selector: last.selector,
dataAttributes: {},
sourceFile: "index.html",
bbox: rectToBbox(rect),
rect,
message: `Rotating element's bounding-box center drifts ${Math.round(drift)}px across rotation — it is not spinning about its own center (check transformOrigin/svgOrigin).`,
fixHint:
"The bounding-box center should stay fixed while the element spins; check its transformOrigin/svgOrigin so rotation pivots about the element's own center rather than a point in a coordinate space it was resized out of.",
};
}
/** Bucket items by a derived key, preserving insertion order within each bucket. */
function groupBy<T>(items: T[], keyOf: (item: T) => string): Map<string, T[]> {
const byKey = new Map<string, T[]>();
for (const item of items) {
const group = byKey.get(keyOf(item));
if (group) group.push(item);
else byKey.set(keyOf(item), [item]);
}
return byKey;
}
/** Bucket time-samples by their CSS selector so each element's trajectory can be
* analyzed independently. Shared by rotation_pivot_drift and off_pivot_rotation. */
function groupBySelector<T extends { selector: string }>(samples: T[]): Map<string, T[]> {
return groupBy(samples, (sample) => sample.selector);
}
/** Enough samples to establish a spin trajectory (one frame can't). */
function hasEnoughRotationSamples(group: RotationSample[]): boolean {
return group.length >= ROTATION_MIN_SAMPLES;
}
/** Real spin, not a fixed tilt: the rotation angle actually varies across the grid. */
function isActuallySpinning(group: RotationSample[]): boolean {
return maxAngleSpread(group.map((s) => s.angle)) > ROTATION_MIN_ANGLE_SPREAD_DEG;
}
/** AABB of an axis-aligned rectangle of size (elemW, elemH) after CSS rotation `angleDeg`. */
function aabbForRotatedRect(
elemW: number,
elemH: number,
angleDeg: number,
): { w: number; h: number } {
const rad = (angleDeg * Math.PI) / 180;
const cosAbs = Math.abs(Math.cos(rad));
const sinAbs = Math.abs(Math.sin(rad));
return { w: elemW * cosAbs + elemH * sinAbs, h: elemW * sinAbs + elemH * cosAbs };
}
/** Invert one sample to unrotated (elemW, elemH); null when θ is near 45° (singular). */
function unrotatedSizeFromSample(sample: RotationSample): { w: number; h: number } | null {
const rad = (sample.angle * Math.PI) / 180;
const cosAbs = Math.abs(Math.cos(rad));
const sinAbs = Math.abs(Math.sin(rad));
const det = cosAbs * cosAbs - sinAbs * sinAbs; // cos(2θ)
if (Math.abs(det) < ROTATION_RIGID_ESTIMATE_MIN_DET) return null;
const elemW = (cosAbs * sample.w - sinAbs * sample.h) / det;
const elemH = (cosAbs * sample.h - sinAbs * sample.w) / det;
if (!(elemW > 0) || !(elemH > 0)) return null;
return { w: elemW, h: elemH };
}
function aabbMatchesSample(expected: { w: number; h: number }, sample: RotationSample): boolean {
if (expected.w <= 0 || expected.h <= 0 || sample.w <= 0 || sample.h <= 0) return false;
return (
Math.max(expected.w, sample.w) / Math.min(expected.w, sample.w) <= ROTATION_RIGID_AABB_RATIO &&
Math.max(expected.h, sample.h) / Math.min(expected.h, sample.h) <= ROTATION_RIGID_AABB_RATIO
);
}
function isSingularRotationAngle(angleDeg: number): boolean {
const rad = (angleDeg * Math.PI) / 180;
const cosAbs = Math.abs(Math.cos(rad));
const sinAbs = Math.abs(Math.sin(rad));
return Math.abs(cosAbs * cosAbs - sinAbs * sinAbs) < ROTATION_RIGID_ESTIMATE_MIN_DET;
}
function isNearSquareAabb(sample: RotationSample): boolean {
if (sample.w <= 0 || sample.h <= 0) return false;
return Math.max(sample.w, sample.h) / Math.min(sample.w, sample.h) <= ROTATION_RIGID_AABB_RATIO;
}
/**
* All samples are 45°-class (no invertible estimator): a rigid rectangle projects to one
* near-square AABB size at every such phase, so mutual AABB agreement is the rigidity proof.
*/
function fitsSingularPhaseRigidProjection(group: RotationSample[]): boolean {
if (group.length === 0 || !group.every((s) => isSingularRotationAngle(s.angle))) return false;
if (!group.every(isNearSquareAabb)) return false;
const ref = group[0];
if (!ref) return false;
return group.every((sample) => aabbMatchesSample({ w: ref.w, h: ref.h }, sample));
}
/**
* Every sample's AABB matches one fixed unrotated rectangle spun by that sample's angle.
* Scale/entrance fails; partial-arc and all-singular (45°-class) rigid spins still pass.
*/
function fitsOneRigidRectangle(group: RotationSample[]): boolean {
for (const ref of group) {
const size = unrotatedSizeFromSample(ref);
if (!size) continue;
if (
group.every((sample) =>
aabbMatchesSample(aabbForRotatedRect(size.w, size.h, sample.angle), sample),
)
) {
return true;
}
}
return fitsSingularPhaseRigidProjection(group);
}
/** Rigid spin: long AABB side stays bounded, and all samples fit one rotated rectangle. */
function isRotationSizeStable(group: RotationSample[]): boolean {
if (group.some((s) => s.w <= 0 || s.h <= 0)) return false;
const longSides = group.map((s) => Math.max(s.w, s.h));
const minLong = Math.min(...longSides);
if (minLong <= 0) return false;
if (Math.max(...longSides) / minLong > ROTATION_MAX_SIZE_RATIO) return false;
return fitsOneRigidRectangle(group);
}
/** Skip tiny decorative spinners; only sizable rotating figures matter. */
function isSizableRotation(group: RotationSample[]): boolean {
return median(group.map((s) => s.w * s.h)) >= ROTATION_MIN_MEDIAN_AREA_PX;
}
/** Size/motion FP gates before the viewport-dependent center-drift test. */
function isRotationDriftCandidate(group: RotationSample[]): boolean {
return (
hasEnoughRotationSamples(group) &&
isActuallySpinning(group) &&
isRotationSizeStable(group) &&
isSizableRotation(group)
);
}
/** Flags a spinning element whose bbox center drifts — wrong transformOrigin/svgOrigin (elongated rotators included). */
export function detectRotationPivotDrift(
samples: RotationSample[],
canvas: Canvas,
): AnchoredLayoutIssue[] {
const findings: AnchoredLayoutIssue[] = [];
const viewportFloor = ROTATION_DRIFT_VIEWPORT_FRACTION * Math.min(canvas.width, canvas.height);
for (const group of groupBySelector(samples).values()) {
if (!isRotationDriftCandidate(group)) continue;
const medianSize = median(group.map((s) => Math.max(s.w, s.h)));
const threshold = Math.max(ROTATION_DRIFT_SIZE_FRACTION * medianSize, viewportFloor);
const drift = maxCenterDrift(group);
if (drift <= threshold) continue;
const finding = rotationDriftFinding(group, drift);
if (finding) findings.push(finding);
}
return findings;
}
// off_pivot_rotation thresholds. A pointer must actually sweep, sit on a
// resolvable dial hub, and its recovered center-of-rotation must land far from
// that hub relative to the pointer's own length.
//
// The fit MUST be OVERDETERMINED: any 3 non-collinear points fit a circle with
// ~zero residual, so a 3-sample "clean circle" guard is vacuous — arbitrary
// endpoint deformation or translation would read as a perfect orbit. Require
// >=5 distinct time-samples so the least-squares residual actually measures
// whether the trajectory lies on one circle.
const INDICATOR_MIN_SAMPLES = 5;
const INDICATOR_MIN_ANGLE_SPREAD_DEG = 20;
const INDICATOR_MIN_HUB_CIRCLES = 2;
// The Kåsa fit's RMS residual normalized by the fitted radius. With >=5 samples
// a genuine rotation lands well under this; non-circular motion (deformation,
// translation, skew, jitter/scatter) blows past it, so we skip rather than
// misread it as an off-hub pivot.
const INDICATOR_MAX_FIT_RESIDUAL_FRACTION = 0.05;
// Rigid-body guard: rotation preserves shape, so the pairwise distance between
// the two tracked material points must stay ~constant. If it swings more than
// this fraction of its median across the window the element is deforming, not
// rotating rigidly — do not flag.
const INDICATOR_MAX_RIGID_LEN_VARIATION = 0.15;
// Drift beyond this fraction of the pointer length is a wrong pivot. A correctly
// hubbed needle recovers a center within a few px of the hub (≈0); a base/edge
// pivot mistake puts the recovered center a large fraction of the needle away.
const INDICATOR_DRIFT_LENGTH_FRACTION = 0.35;
interface CircleFit {
cx: number;
cy: number;
radius: number;
residual: number;
}
/** Kåsa algebraic circle fit; null when the points are near-collinear/degenerate
* (no stable center recoverable).
*
* KEEP IN SYNC with `fitCirclePoints` in
* packages/cli/src/commands/layout-audit.browser.js — the browser sampler needs
* the same fit to resolve arc-drawn dial hubs, but it is injected as a raw
* string (no import across the puppeteer boundary), so the math is intentionally
* duplicated per-language. Any change to the algorithm must land in both. */
function fitCircle(points: Array<{ x: number; y: number }>): CircleFit | null {
const count = points.length;
if (count < 3) return null;
const meanX = points.reduce((sum, p) => sum + p.x, 0) / count;
const meanY = points.reduce((sum, p) => sum + p.y, 0) / count;
let suu = 0;
let svv = 0;
let suv = 0;
let suuu = 0;
let svvv = 0;
let suvv = 0;
let svuu = 0;
for (const point of points) {
const u = point.x - meanX;
const v = point.y - meanY;
suu += u * u;
svv += v * v;
suv += u * v;
suuu += u * u * u;
svvv += v * v * v;
suvv += u * v * v;
svuu += v * u * u;
}
const determinant = suu * svv - suv * suv;
if (Math.abs(determinant) < 1e-6) return null;
const rhsU = (suuu + suvv) / 2;
const rhsV = (svvv + svuu) / 2;
const uc = (rhsU * svv - rhsV * suv) / determinant;
const vc = (rhsV * suu - rhsU * suv) / determinant;
const cx = uc + meanX;
const cy = vc + meanY;
const radius = Math.sqrt(uc * uc + vc * vc + (suu + svv) / count);
// RMS radial residual: penalizes any point straying off the fitted circle
// more sharply than a mean-absolute error, so an overdetermined fit exposes
// non-circular trajectories instead of averaging them away.
let squaredError = 0;
for (const point of points) {
const delta = Math.hypot(point.x - cx, point.y - cy) - radius;
squaredError += delta * delta;
}
return { cx, cy, radius, residual: Math.sqrt(squaredError / count) };
}
/** A dial hub that is present for a SUSTAINED majority of the sampled window,
* not just the final frame — a transient single-frame hub is not a reliable
* anchor. The representative center is the median across the frames that carry
* one, so a stray frame can't yank it. */
const INDICATOR_MIN_HUB_PRESENCE_FRACTION = 0.6;
interface ResolvedHub {
hx: number;
hy: number;
}
function resolveHub(group: OffPivotRotationSample[]): ResolvedHub | null {
const present = group.filter(
(s) => s.hx !== null && s.hy !== null && s.hubCount >= INDICATOR_MIN_HUB_CIRCLES,
);
if (present.length < INDICATOR_MIN_HUB_PRESENCE_FRACTION * group.length) return null;
const hx = median(present.map((s) => s.hx as number));
const hy = median(present.map((s) => s.hy as number));
return { hx, hy };
}
/** Rigid-body guard: a rotation preserves the figure's shape, so the distance
* between the two tracked material points stays ~constant. Arbitrary endpoint
* deformation (morphing, stretching) changes it — reject so it isn't misread as
* an off-hub orbit. */
function isRigidBody(group: OffPivotRotationSample[]): boolean {
const lengths = group.map((s) => s.len).filter((len) => len > 0);
if (lengths.length < group.length) return false;
const mid = median(lengths);
if (mid <= 0) return false;
const spread = Math.max(...lengths) - Math.min(...lengths);
return spread <= INDICATOR_MAX_RIGID_LEN_VARIATION * mid;
}
/** Recover the center-of-rotation from whichever major-axis endpoint traces the
* larger orbit (more movement → more numerically stable), rejecting scattered
* fits. The fit is OVERDETERMINED (>=INDICATOR_MIN_SAMPLES points) so a high RMS
* residual genuinely means the trajectory is not one circle. */
function recoverPivot(group: OffPivotRotationSample[]): CircleFit | null {
if (group.length < INDICATOR_MIN_SAMPLES) return null;
const endpointA = group.map((s) => ({ x: s.ax, y: s.ay }));
const endpointB = group.map((s) => ({ x: s.bx, y: s.by }));
const fits = [fitCircle(endpointA), fitCircle(endpointB)].filter(
(fit): fit is CircleFit => fit !== null,
);
if (fits.length === 0) return null;
// Scoped-known blind spot: we keep the wider-radius endpoint fit and, if it
// fails the residual gate below, return null rather than falling back to the
// narrower fit. Deliberately conservative — a missed pointer (false negative)
// over threading both fits and risking a spurious pivot on a noisy arc.
const best = fits.reduce((widest, fit) => (fit.radius > widest.radius ? fit : widest));
if (best.radius <= 0) return null;
if (best.residual > INDICATOR_MAX_FIT_RESIDUAL_FRACTION * best.radius) return null;
return best;
}
/** An off-pivot sample with its frame time reattached for grouping/annotation.
* The wire shape ({@link OffPivotFrame}) hoists time to the frame; the detector
* flattens back to timed samples so the last frame's time anchors the finding. */
type TimedIndicatorSample = OffPivotRotationSample & { time: number };
function offPivotRotationFinding(
group: TimedIndicatorSample[],
drift: number,
): AnchoredLayoutIssue | null {
const last = group[group.length - 1];
if (!last) return null;
const rect: LayoutRect = {
left: Math.min(last.ax, last.bx) - 4,
top: Math.min(last.ay, last.by) - 4,
right: Math.max(last.ax, last.bx) + 4,
bottom: Math.max(last.ay, last.by) + 4,
width: Math.abs(last.bx - last.ax) + 8,
height: Math.abs(last.by - last.ay) + 8,
};
return {
code: "off_pivot_rotation",
severity: "warning",
time: last.time,
selector: last.selector,
dataAttributes: {},
sourceFile: "index.html",
bbox: rectToBbox(rect),
rect,
message: `Gauge/dial pointer rotates about a point ${Math.round(drift)}px from the dial hub — its center-of-rotation is off the hub, so it points wrong or overshoots the track (check the rotating group's pivot: translate to the hub before rotate, or set svgOrigin/transform-origin to the hub).`,
fixHint:
"The pointer's center-of-rotation must coincide with the dial hub. Rotate the group about the hub (e.g. transform-origin/svgOrigin set to the hub center, or translate the group so its rotation pivot lands on the hub) rather than about the element's own bbox center.",
};
}
/**
* off_pivot_rotation: a gauge needle / clock hand / radar sweep / dial pointer
* that rotates about the WRONG pivot — its center-of-rotation is far from the
* dial's hub, so the pointer aims wrong, runs off the track, or leaves the canvas.
*
* This is a HUB-REFERENCED check by necessity: a correctly-swept needle's bbox
* center orbits identically to a broken one (the pivot sits at the needle's
* base/edge either way), so no element-intrinsic measure separates them. The
* browser sampler records two fixed MATERIAL points on the pointer per frame; a
* circle fit recovers the true center-of-rotation, which is then compared to the
* dial's static hub (the screen point shared by the most non-rotating circles).
*
* FP guards are strict and STRUCTURAL (evaluated across the whole sampled
* window, not a single frame): requires real sweep (angle varies), a hub present
* for a sustained majority of frames (≥2 concentric static circles), a
* rigid-body trajectory (the two tracked points keep a constant separation), an
* OVERDETERMINED circle fit (≥5 samples, low RMS residual), and drift exceeding a
* fraction of the pointer's own length. When no sustained hub reference resolves
* it does not fire, so a lone decorative rotator can't trip it.
*/
interface IndicatorCandidate {
hubKey: string;
angleAboutHub: number;
drift: number;
length: number;
finding: AnchoredLayoutIssue | null;
}
/** Distinct angular positions about the hub among a set of candidates (nested
* blade parts share one angle; orbiting bodies spread to several). Exported for
* direct unit coverage of the multi-body/orbit-atom suppression guard. */
export function countAngularBodies(angles: number[]): number {
const clusters: number[] = [];
for (const angle of angles) {
if (
!clusters.some((rep) => Math.min(Math.abs(angle - rep), 360 - Math.abs(angle - rep)) <= 25)
) {
clusters.push(angle);
}
}
return clusters.length;
}
/** The pointer's angular position about the resolved hub, averaged across the
* window so the multi-body clustering compares a stable per-body angle rather
* than a single-frame snapshot. */
function angleAboutHub(group: OffPivotRotationSample[], hub: ResolvedHub): number {
const midX = median(group.map((s) => (s.ax + s.bx) / 2));
const midY = median(group.map((s) => (s.ay + s.by) / 2));
return (Math.atan2(midY - hub.hy, midX - hub.hx) * 180) / Math.PI;
}
/** Gate one element's samples into a candidate, applying every structural FP
* guard. Returns null when the element is not an off-pivot-able dial pointer. */
function buildIndicatorCandidate(group: TimedIndicatorSample[]): IndicatorCandidate | null {
if (group.length < INDICATOR_MIN_SAMPLES) return null;
if (maxAngleSpread(group.map((s) => s.angle)) <= INDICATOR_MIN_ANGLE_SPREAD_DEG) return null;
const hub = resolveHub(group);
if (!hub) return null;
if (!isRigidBody(group)) return null;
const pivot = recoverPivot(group);
if (!pivot) return null;
const drift = Math.hypot(pivot.cx - hub.hx, pivot.cy - hub.hy);
const length = median(group.map((s) => s.len));
const eligible = drift > INDICATOR_DRIFT_LENGTH_FRACTION * length;
return {
// Scoped-known blind spot: hubs bucketed by rounded screen coords, so two
// separate dials whose screen hubs land in the same 5px bucket merge into
// one multi-body group (rare — distinct dials stacked at ~identical screen
// position). Key by owning <svg> identity if that pattern shows up.
hubKey: `${Math.round(hub.hx / 5)}:${Math.round(hub.hy / 5)}`,
angleAboutHub: angleAboutHub(group, hub),
drift,
length,
finding: eligible ? offPivotRotationFinding(group, drift) : null,
};
}
/** Per hub: multiple bodies at distinct angular positions = an orbit/atom/radial
* system, not a single dial pointer — suppress. A real pointer (group + nested
* blades) collapses to one angular cluster. Otherwise emit one finding per hub,
* keeping the longest pointer. */
function selectHubFindings(candidates: IndicatorCandidate[]): AnchoredLayoutIssue[] {
const byHub = groupBy(candidates, (candidate) => candidate.hubKey);
const findings: AnchoredLayoutIssue[] = [];
for (const group of byHub.values()) {
// Count angular bodies only over ELIGIBLE (off-pivot) candidates. Sibling
// hands that are correctly hubbed (finding === null) are not orbiting
// bodies, so counting them would falsely suppress a lone off-pivot hand on
// a multi-hand clock/dial whose other hands pivot correctly.
const eligible = group.filter((c) => c.finding !== null);
if (countAngularBodies(eligible.map((c) => c.angleAboutHub)) >= 2) continue;
const best = group
.filter((c) => c.finding !== null)
.reduce<IndicatorCandidate | null>(
(max, c) => (!max || c.length > max.length ? c : max),
null,
);
if (best?.finding) findings.push(best.finding);
}
return findings;
}
export function detectOffPivotRotation(frames: OffPivotFrame[]): AnchoredLayoutIssue[] {
const timed: TimedIndicatorSample[] = frames.flatMap((frame) =>
frame.samples.map((sample) => ({ ...sample, time: frame.time })),
);
const candidates: IndicatorCandidate[] = [];
for (const group of groupBySelector(timed).values()) {
const candidate = buildIndicatorCandidate(group);
if (candidate) candidates.push(candidate);
}
return selectHubFindings(candidates);
}
/** Error-severity findings with real geometry become labeled overview boxes.
* Contrast failures are annotated separately by the driver itself, since
* they're only known once contrast measurement for this sample completes. */
function annotationBoxesFrom(issues: AnchoredLayoutIssue[]): CheckAnnotationBox[] {
return issues
.filter((issue) => issue.severity === "error" && issue.bbox.width > 0 && issue.bbox.height > 0)
.map((issue, index) => ({ label: `${index + 1} ${issue.code}`, bbox: issue.bbox }));
}
function wholeCompositionKeepsMoving(assertions: MotionAssertion[]): boolean {
return assertions.some(
(assertion) => assertion.kind === "keepsMoving" && assertion.withinSelector === undefined,
);
}
function disabledCraft(): CraftResult {
return { enabled: false, step: 0, samples: 0, findings: [] };
}
/** The analysis re-seeks and re-captures frames on its own; each call it makes restarts the idle window. */
export function reportingProgress<T extends object>(
driver: T,
enter: (phase: CheckPhase, detail?: string) => void,
): T {
return new Proxy(driver, {
get(target, name) {
const member = Reflect.get(target, name);
if (typeof member !== "function") return member;
return (...args: unknown[]) => {
enter("analysis", String(name));
return member.apply(target, args);
};
},
});
}
async function textOverFace(
collected: GridSamples,
onFile: () => void,
stop?: AbortSignal,
): Promise<{ issues: AnchoredLayoutIssue[]; faceCheck: FaceCheck }> {
if (collected.textOverVideoUnavailable) {
return {
issues: [],
faceCheck: { ran: false, reason: "this check driver does not report text over video" },
};
}
if (collected.textOverVideo.length === 0) {
return { issues: [], faceCheck: { ran: true, candidates: 0, faces: 0 } };
}
const { findTextOverFace } = await import("./textOverFace.js");
return findTextOverFace(collected.textOverVideo, undefined, onFile, stop);
}
export async function runAuditGrid(
driver: CheckAuditDriver,
options: CheckOptions,
motion: MotionSpecResolution,
helpers: Promise<CheckAuditDriver[]> = Promise.resolve([]),
enter: (phase: CheckPhase, detail?: string) => void = () => {},
report: CheckProgress = () => {},
keep: (read: () => Partial<CheckBrowserResult>) => void = () => {},
stop?: AbortSignal,
): Promise<CheckBrowserResult> {
enter("samples");
await driver.initialize(options.contrast);
const grid = await buildSampleGrid(driver, options);
const plan = await planMotionSampling(
driver,
options.range ? { kind: "none" } : motion,
grid.duration,
);
const seekLoopStart = Date.now();
const collected = await collectGridSamples(
driver,
options,
grid,
plan,
helpers,
enter,
report,
keep,
);
const seekLoopMs = Date.now() - seekLoopStart;
report("analyze", 0, 3);
enter("analysis");
const analysing = reportingProgress(driver, enter);
let motionIssues = plan.preflightIssues;
if (motion.kind === "valid" && plan.assertions.length > 0 && collected.motionFrames.length > 0) {
const canvas = await analysing.getCanvas();
let evaluated = evaluateMotion(collected.motionFrames, plan.assertions, canvas, grid.duration);
if (evaluated.some((issue) => issue.code === "motion_frozen")) {
const frames = await withFrameMotion(analysing, collected.motionFrames, plan.assertions);
evaluated = evaluateMotion(frames, plan.assertions, canvas, grid.duration);
}
motionIssues = [...motionIssues, ...(await analysing.anchorMotionIssues(evaluated))];
}
report("analyze", 1, 3);
const userPicked = new Set(grid.userPickedSamples);
const noTimeline = await analysing.hasNoTimelineDeclaration();
const sweepSamples = collected.layoutStateSignatures.filter(
(sample) => !userPicked.has(sample.time),
);
const sweepVerdict = options.range
? []
: detectSweepStatic(grid.duration, sweepSamples, motionIssues, noTimeline);
const sweepFindings =
sweepVerdict.length > 0 &&
(await framesMoved(
analysing,
sweepSamples.map((sample) => sample.time),
))
? []
: sweepVerdict;
const rotationFindings = detectRotationPivotDrift(
collected.rotationSamples,
await analysing.getCanvas(),
);
const offPivotFindings = detectOffPivotRotation(collected.indicatorFrames);
const overFace = await textOverFace(collected, () => enter("analysis", "faces under text"), stop);
const contrast = buildContrastResults(collected.contrastEntries);
report("analyze", 2, 3);
const craft = craftEnabled(analysing, options)
? await auditCraft(
{
frames: collected.craftFrames,
duration: grid.duration,
canvas: await analysing.getCanvas(),
soundSources: analysing.collectCraftFilm
? (await analysing.collectCraftFilm()).soundSources
: null,
stillnessJudgedElsewhere:
noTimeline || sweepFindings.length > 0 || wholeCompositionKeepsMoving(plan.assertions),
},
async (time) => {
await analysing.seekGeometry(time, { draws: true });
if (!analysing.collectCraftFrame) throw new Error("craft sampling unavailable");
return analysing.collectCraftFrame(time);
},
)
: disabledCraft();
if (options.components?.length) {
if (!driver.matchComponents)
throw new Error("Component filtering unavailable in this check driver");
const findings = [
...collected.layoutIssues,
...sweepFindings,
...rotationFindings,
...offPivotFindings,
...overFace.issues,
...motionIssues,
...contrast.findings,
...craft.findings,
];
const matches = await driver.matchComponents(options.components, findings);
findings.forEach((finding, i) => {
finding.componentMatch = matches[i];
});
}
return {
duration: grid.duration,
layoutSamples: grid.layoutSamples,
transitionSamples: grid.transitionSamples,
transitionSamplesDropped: grid.transitionSamplesDropped,
runtimeFindings: [],
layoutIssues: [
...collected.layoutIssues,
...sweepFindings,
...rotationFindings,
...offPivotFindings,
...overFace.issues,
],
faceCheck: overFace.faceCheck,
motionIssues,
motionSampleCount: collected.motionFrames.length,
contrastSamples: grid.contrastSamples,
contrastFindings: contrast.findings,
contrastChecked: collected.contrastEntries.length,
contrastPassed: contrast.passed,
craft,
screenshots: collected.screenshots,
timings: {
launchSettleMs: 0,
seekLoopMs,
contrastMs: collected.contrastMs,
gridMs: collected.gridMs,
craftMs: collected.craftMs,
overlapMs: collected.overlapMs,
},
skipped: false,
renderReadyTimedOut: false,
};
}
export const leavesNothingToLoad = (finding: { code: string; severity: string }): boolean =>
finding.severity === "error" && finding.code === "root_missing_composition_id";
const compositionCannotLoad = (lintResult: ProjectLintResult): boolean =>
lintResult.results[0]?.result.findings.some(leavesNothingToLoad) ?? false;
export async function runCheckPipeline(
project: ProjectDir,
options: CheckOptions,
dependencies: CheckDependencies = DEFAULT_DEPENDENCIES,
): Promise<CheckReport> {
beginCheckSnapshots(project.dir);
const prelaunched = dependencies.prelaunchBrowser?.(project, options).catch(() => undefined);
try {
let lintResult: ProjectLintResult;
const lintStartedAt = Date.now();
try {
lintResult = await dependencies.lintProject(project.dir, {
includeUnmounted: options.includeUnmounted === true,
});
const unmounted = lintResult.unmountedCompositions?.length ?? 0;
if (unmounted > 0) console.error(`[hyperframes] check: ${unmountedNotice(unmounted)}`);
} catch (error) {
// The linter itself crashed (unreadable file, internal error) — distinct
// from lint findings; a runtime-failure code would send the agent hunting
// for a script problem that doesn't exist.
return failureReport(options, runtimeFailure(error, "check_lint_failure"));
}
trackLintRun(project.dir, lintResult, {
command: "check",
durationMs: Date.now() - lintStartedAt,
...(getRunId() !== undefined ? { runId: getRunId() } : {}),
});
const lint = buildLintSection(lintResult);
const { hdr, audio } = await inspectProjectMedia(project, dependencies);
if (compositionCannotLoad(lintResult)) {
return buildReport(
options,
lint,
emptyBrowserResult(),
{ kind: "none" },
[],
[],
hdr,
await audio,
);
}
const motion = dependencies.resolveMotionSpec(project.dir);
const specFindings =
motion.kind === "invalid"
? [
findingAtRoot(
"motion_spec_invalid",
"error",
motion.message,
relative(project.dir, motion.path) || "index.motion.json",
),
]
: [];
const deadline = new CheckDeadline(idleWindow(options.timeout), options.budget);
const forgetStop = onStopSignal(deadline.stop);
let outcome: { kind: "report"; report: CheckReport } | { kind: "failed"; error: unknown };
try {
let browser: CheckBrowserResult;
try {
const browserAhead = await prelaunched;
browser = await deadline.run(() =>
dependencies.runBrowserCheck(project, options, motion, deadline, browserAhead),
);
} catch (error) {
const found = deadline.partialResult();
const ran = Object.keys(found).filter((key) => key !== "mediaCopies");
browser = { ...emptyBrowserResult(), ...found, skipped: ran.length === 0 };
browser.runtimeFindings = [...browser.runtimeFindings, runtimeFailure(error)];
}
const snapshotFiles = options.snapshots
? await writeContrastSnapshots(dependencies, project.dir, browser)
: [];
const report = buildReport(
options,
lint,
browser,
motion,
specFindings,
snapshotFiles,
hdr,
await audio,
);
outcome = {
kind: "report",
report: await withOptionalFindingFrames(
dependencies,
project,
options,
options.snapshots
? await withFindingCrops(dependencies, project, options, report, deadline)
: report,
deadline,
),
};
} catch (error) {
outcome = { kind: "failed", error };
}
forgetStop();
try {
await deadline.close();
} catch (error) {
if (outcome.kind === "failed") {
throw new BrowserCleanupError(
[outcome.error, error],
`${normalizeErrorMessage(outcome.error)}; ${normalizeErrorMessage(error)}`,
);
}
const report = outcome.report;
return {
...report,
ok: false,
runtime: section([
...report.runtime.findings,
runtimeFailure(error, "check_cleanup_failure"),
]),
};
}
if (outcome.kind === "failed") throw outcome.error;
return outcome.report;
} finally {
await (await prelaunched)?.discard();
await finishCheckSnapshots(project.dir).catch(() => undefined);
}
}
/** Persists the contrast pass's already-captured overview PNGs (or the
* annotated versions — see `collectContrast`'s overlay). A write failure
* becomes a runtime finding rather than aborting the whole report. */
async function writeContrastSnapshots(
dependencies: CheckDependencies,
projectDir: string,
browser: CheckBrowserResult,
): Promise<string[]> {
const files: string[] = [];
for (let index = 0; index < browser.screenshots.length; index += 1) {
const shot = browser.screenshots[index];
if (!shot) continue;
try {
files.push(await dependencies.writeSnapshot(projectDir, index, shot.time, shot.pngBase64));
} catch (error) {
browser.runtimeFindings.push(runtimeFailure(error, "snapshot_write_failed"));
}
}
return files;
}
/** Finding crops are bonus evidence, not gating — no eligible finding, or a
* capture failure (e.g. a second Chrome launch failing), returns the report
* unchanged rather than sinking an otherwise-good run. */
async function withFindingCrops(
dependencies: CheckDependencies,
project: ProjectDir,
options: CheckOptions,
report: CheckReport,
deadline: CheckDeadline,
): Promise<CheckReport> {
const cropRequests = selectFindingCropRequests(report);
if (cropRequests.length === 0 || deadline.signal.aborted) return report;
try {
deadline.enter("crops");
const findingFiles = await deadline.run(() =>
dependencies.captureFindingCrops(project, options, cropRequests, deadline),
);
return { ...report, snapshots: { ...report.snapshots, findingFiles } };
} catch (error) {
if (isCheckExpiry(error)) {
const finding = runtimeFailure(error);
return { ...report, ok: false, runtime: section([...report.runtime.findings, finding]) };
}
// Still non-gating, but observable: rollouts need the crop-failure rate
// (a second Chrome launch failing/timing out) without failing the run.
console.error(" finding crops skipped: " + terminalLines(normalizeErrorMessage(error)));
trackCommandFailure("check-finding-crops", error);
return report;
}
}
async function withOptionalFindingFrames(
dependencies: CheckDependencies,
project: ProjectDir,
options: CheckOptions,
report: CheckReport,
deadline: CheckDeadline,
): Promise<CheckReport> {
if (!options.findingFrames || deadline.signal.aborted) return report;
const plan = selectFindingFrames(report);
if (plan.requests.length === 0) return report;
if (plan.skipped > 0) {
console.error(
` finding frames: ${plan.skipped} finding(s) left out past ${MAX_FINDING_FRAME_TIMES} distinct times`,
);
}
const capture = dependencies.captureFindingFrames ?? captureFindingFrames;
try {
deadline.enter("frames");
const requests = findingFrameRequests(report, plan, options.inspect);
const captured = await deadline.run(() => capture(project, options, requests, deadline));
return withFindingFrameFields(report, plan, captured);
} catch (error) {
if (isCheckExpiry(error)) {
const finding = runtimeFailure(error);
return { ...report, ok: false, runtime: section([...report.runtime.findings, finding]) };
}
console.error(" finding frames skipped: " + terminalLines(normalizeErrorMessage(error)));
trackCommandFailure("check-finding-frames", error);
return report;
}
}
const isCheckExpiry = (error: unknown): boolean =>
error instanceof CheckDeadlineError ||
error instanceof CheckStoppedError ||
error instanceof CheckBudgetError;
const MAX_FINDING_CROPS = 12;
/** Which error findings get a `finding-NN-<code>.png` crop for `check --snapshots`:
* error severity, a real (non-zero) bbox, capped at 12. Pure and order-preserving
* so it's directly unit-testable without a browser. */
export function selectFindingCropRequests(report: CheckReport): CheckFindingCropRequest[] {
const candidates: CheckFinding[] = [
...report.layout.findings,
...report.motion.findings,
...report.contrast.findings,
...report.runtime.findings,
];
const requests: CheckFindingCropRequest[] = [];
for (const finding of candidates) {
if (requests.length >= MAX_FINDING_CROPS) break;
if (finding.severity !== "error" || !hasRealBbox(finding.bbox)) continue;
requests.push({
filename: findingCropFilename(requests.length, finding.code),
time: finding.time,
bbox: finding.bbox,
});
}
return requests;
}
function hasRealBbox(bbox: CheckBbox): boolean {
return bbox.width > 0 && bbox.height > 0;
}
export function findingCropFilename(index: number, code: string): string {
const safeCode = code.replace(/[^a-zA-Z0-9_-]/g, "_");
return `finding-${String(index).padStart(2, "0")}-${safeCode}.png`;
}
export function checkExitCode(report: CheckReport): 0 | 1 {
return report.ok ? 0 : 1;
}
// Same persistence rule the layout findings follow: a failure observed at a
// single contrast sample is usually text caught mid-entrance/exit (its real
// background not painted yet — white-on-white at exactly 1.0 is the classic
// shape), so it demotes to warning. A failure HELD at 2+ samples for the same
// element is a real, gating defect. Single-sample sweeps can't distinguish,
// so they keep full severity.
function contrastFailureHeld(
entries: ContrastAuditEntry[],
): (entry: ContrastAuditEntry) => boolean {
const sampledTimes = new Set(entries.map((entry) => entry.time)).size;
const failureSamples = new Map<string, Set<number>>();
for (const entry of entries) {
if (entry.wcagAA) continue;
const key = findingElementKey(entry);
const times = failureSamples.get(key) ?? new Set<number>();
times.add(entry.time);
failureSamples.set(key, times);
}
return (entry) =>
sampledTimes < 2 || (failureSamples.get(findingElementKey(entry))?.size ?? 0) >= 2;
}
function buildContrastResults(entries: ContrastAuditEntry[]): {
findings: CheckContrastFinding[];
passed: number;
} {
const findings: CheckContrastFinding[] = [];
let passed = 0;
const isHeld = contrastFailureHeld(entries);
for (const entry of entries) {
if (entry.wcagAA) {
passed += 1;
continue;
}
const held = isHeld(entry);
const requiredRatio = requiredContrastRatio(entry.large);
findings.push({
code: "contrast_aa_failure",
severity: held ? "error" : "warning",
message: `Contrast is ${entry.ratio}:1; WCAG AA requires ${requiredRatio}:1.`,
text: entry.text,
fg: entry.fg,
bg: entry.bg,
ratio: entry.ratio,
requiredRatio,
suggestedColor: suggestedColor(entry.fg, entry.bg, requiredRatio),
large: entry.large,
selector: entry.selector,
dataAttributes: entry.dataAttributes,
sourceFile: entry.sourceFile,
bbox: entry.bbox,
time: entry.time,
});
}
return {
findings: groupSampledFindings(
findings,
(next, current) => current.ratio / current.requiredRatio - next.ratio / next.requiredRatio,
),
passed,
};
}
function suggestedColor(fg: string, bg: string, requiredRatio: number): string {
const foreground = parseColorRGBA(fg);
const background = parseColorRGBA(bg);
if (!foreground || !background) return fg;
const fgRgb: Rgb = [foreground[0], foreground[1], foreground[2]];
const bgRgb: Rgb = [background[0], background[1], background[2]];
const suggested = suggestCompliantForegroundColor(fgRgb, bgRgb, requiredRatio);
return `rgb(${suggested[0]},${suggested[1]},${suggested[2]})`;
}
function buildLintSection(result: ProjectLintResult): CheckReport["lint"] {
const findings = result.results.flatMap(({ file, result: fileResult }) =>
fileResult.findings.map((finding) => ({
code: finding.code,
severity: finding.severity,
message: finding.message,
selector:
finding.selector ?? (finding.elementId ? `#${finding.elementId}` : "[data-composition-id]"),
dataAttributes: {},
sourceFile: finding.file ?? file,
bbox: ZERO_BBOX,
time: 0,
fixHint: finding.fixHint,
})),
);
return { ...section(findings), filesScanned: result.results.length };
}
function buildReport(
options: CheckOptions,
lint: CheckReport["lint"],
browser: CheckBrowserResult,
motion: MotionSpecResolution,
extraMotionFindings: CheckFinding[],
snapshotFiles: string[],
hdr: CheckReport["hdr"] = { autoPromotion: null, inspection: "available" },
audioFindings: CheckFinding[] = [],
): CheckReport {
const shaping = options.components?.length
? { ...options, maxIssues: Number.MAX_SAFE_INTEGER }
: options;
const layout = shapeLayoutSection(browser.layoutIssues, browser, shaping);
const shapedMotion = shapeLayoutFindings(browser.motionIssues, shaping);
const motionFindings: CheckFinding[] = [...shapedMotion.findings, ...extraMotionFindings];
const runtime = section(browser.runtimeFindings);
const motionSection = section(motionFindings);
const contrastSection = section(browser.contrastFindings);
const craftSection = section<CraftFinding>(browser.craft.findings);
const audioSection = section(audioFindings);
const warningCount =
lint.warningCount +
audioSection.warningCount +
runtime.warningCount +
layout.warningCount +
motionSection.warningCount +
contrastSection.warningCount +
craftSection.warningCount;
const errorCount =
lint.errorCount +
audioSection.errorCount +
runtime.errorCount +
layout.errorCount +
motionSection.errorCount +
contrastSection.errorCount +
craftSection.errorCount;
// Craft findings are judgment calls a film may break on purpose, so --strict gates defects only.
const guidanceWarnings = layout.findings.filter(
(finding) => finding.severity === "warning" && isGuidanceIssue(finding),
).length;
const strictWarningCount = warningCount - craftSection.warningCount - guidanceWarnings;
const report: CheckReport = {
ok: errorCount === 0 && (!options.strict || strictWarningCount === 0),
strict: options.strict,
browserSkipped: browser.skipped,
lint,
runtime,
layout,
motion: {
...motionSection,
enabled: motion.kind !== "none" && !options.range,
specPath: motion.kind === "none" ? undefined : motion.path,
samples: browser.motionSampleCount,
},
contrast: {
...contrastSection,
enabled: options.contrast,
samples: browser.contrastSamples,
checked: browser.contrastChecked,
passed: browser.contrastPassed,
},
craft: {
...craftSection,
enabled: browser.craft.enabled,
step: browser.craft.step,
samples: browser.craft.samples,
},
audio: audioSection,
hdr,
snapshots: {
enabled: options.snapshots,
files: snapshotFiles,
times: options.snapshots ? browser.screenshots.map((shot) => shot.time) : [],
findingFiles: [],
},
};
trackCheckReport({
contrastGate: options.contrast,
motionGate: motion.kind !== "none" && !options.range,
captionZoneGate: options.captionZone !== undefined,
frameCheckGate: options.frameCheck !== undefined,
snapshotsGate: options.snapshots,
lintErrors: lint.errorCount,
lintWarnings: lint.warningCount,
runtimeErrors: runtime.errorCount,
runtimeWarnings: runtime.warningCount,
layoutErrors: layout.errorCount,
layoutWarnings: layout.warningCount,
motionErrors: motionSection.errorCount,
motionWarnings: motionSection.warningCount,
contrastErrors: contrastSection.errorCount,
contrastWarnings: contrastSection.warningCount,
craftWarnings: craftSection.warningCount,
launchSettleMs: browser.timings.launchSettleMs,
renderReadyTimedOut: browser.renderReadyTimedOut,
seekLoopMs: browser.timings.seekLoopMs,
contrastMs: browser.timings.contrastMs,
gridMs: browser.timings.gridMs,
craftMs: browser.timings.craftMs,
overlapMs: browser.timings.overlapMs,
durationSec: browser.duration,
gridPoints: browser.layoutSamples.length,
contrastPoints: browser.contrastChecked,
ok: report.ok,
exitCode: checkExitCode(report),
stopCode: browser.runtimeFindings
.map((finding) => finding.code)
.find((code): code is StopCode => (STOP_CODES as readonly string[]).includes(code)),
mediaCopies: browser.mediaCopies,
runId: getRunId(),
});
return filterComponentReport(report, options);
}
function filterComponentReport(report: CheckReport, options: CheckOptions): CheckReport {
if (!options.range && !options.components?.length) return report;
{
report.scope = {
range: options.range,
components: options.components,
hiddenFindings: 0,
notes: [
"Static lint, audio and unscoped runtime failures remain project-wide.",
...(options.range
? [
"Whole-timeline motion assertions, frozen-sweep detection and craft warnings are skipped for range checks.",
]
: []),
],
};
for (const group of [report.layout, report.motion, report.contrast, report.craft]) {
const before = group.findings.length;
group.findings = group.findings.filter((f) => f.componentMatch !== false);
report.scope.hiddenFindings += before - group.findings.length;
if (group !== report.contrast && group.findings.length > options.maxIssues) {
group.findings = group.findings.slice(0, options.maxIssues);
report.scope.notes.push(
"Selected findings exceed --max-issues; increase it to see the remainder.",
);
if (group === report.layout) report.layout.truncated = true;
}
}
}
return report;
}
const FACE_CHECK_NOT_REACHED = "the check stopped before looking for faces under text";
function shapeLayoutSection(
issues: AnchoredLayoutIssue[],
browser: CheckBrowserResult,
options: CheckOptions,
): CheckReport["layout"] {
const shaped = shapeLayoutFindings(issues, options, browser.layoutSamples);
return {
...section(shaped.findings),
duration: browser.duration,
samples: browser.layoutSamples,
transitionSamples: browser.transitionSamples,
transitionSamplesDropped: browser.transitionSamplesDropped,
tolerance: options.tolerance,
totalIssueCount: shaped.totalIssueCount,
truncated: shaped.truncated,
faceCheck: browser.faceCheck ?? { ran: false, reason: FACE_CHECK_NOT_REACHED },
};
}
function shapeLayoutFindings(
issues: AnchoredLayoutIssue[],
options: CheckOptions,
sampleTimes?: readonly number[],
): { findings: AnchoredLayoutIssue[]; totalIssueCount: number; truncated: boolean } {
const deduped = dedupeLayoutIssues(issues);
const all = options.collapseStatic
? collapseStaticLayoutIssues(deduped, sampleTimes?.length, sampleTimes)
: deduped;
const anchored = all.map(ensureAnchoredLayoutIssue);
let grouped = anchored;
if (options.collapseStatic) {
grouped = groupSampledFindings(anchored).map((finding) => ({
...finding,
firstSeen: finding.times[0] ?? finding.time,
lastSeen: finding.times.at(-1) ?? finding.time,
occurrences: finding.times.length,
heldMs: longestContiguousRunMs(finding.times),
}));
}
const limited = limitLayoutIssues(grouped, options.maxIssues);
return {
findings: limited.issues.map(ensureAnchoredLayoutIssue),
totalIssueCount: limited.totalIssueCount,
truncated: limited.truncated,
};
}
function ensureAnchoredLayoutIssue(issue: LayoutIssue): AnchoredLayoutIssue {
const sourceFile = Reflect.get(issue, "sourceFile");
const dataAttributes = Reflect.get(issue, "dataAttributes");
const bbox = Reflect.get(issue, "bbox");
if (typeof sourceFile === "string" && isStringRecord(dataAttributes) && isBbox(bbox)) {
return { ...issue, sourceFile, dataAttributes, bbox };
}
return {
...issue,
sourceFile: "index.html",
dataAttributes: {},
bbox: rectToBbox(issue.rect),
};
}
function section<T extends CheckFinding>(findings: T[]): CheckSection<T> {
const errorCount = findings.filter((finding) => finding.severity === "error").length;
const warningCount = findings.filter((finding) => finding.severity === "warning").length;
const infoCount = findings.filter((finding) => finding.severity === "info").length;
return { ok: errorCount === 0, errorCount, warningCount, infoCount, findings };
}
function emptyBrowserResult(): CheckBrowserResult {
return {
duration: 0,
layoutSamples: [],
transitionSamples: [],
transitionSamplesDropped: 0,
runtimeFindings: [],
layoutIssues: [],
motionIssues: [],
motionSampleCount: 0,
contrastSamples: [],
contrastFindings: [],
contrastChecked: 0,
contrastPassed: 0,
craft: disabledCraft(),
screenshots: [],
timings: {
launchSettleMs: 0,
seekLoopMs: 0,
contrastMs: 0,
gridMs: 0,
craftMs: 0,
overlapMs: 0,
},
skipped: true,
renderReadyTimedOut: false,
};
}
const STOP_CODES = [
"media_copies_unfinished",
"check_budget_reached",
"check_runtime_failure",
] as const;
export type StopCode = (typeof STOP_CODES)[number];
function runtimeFailure(error: unknown, code?: string): CheckFinding {
return findingAtRoot(
code ??
(error instanceof CheckCopiesUnfinishedError
? "media_copies_unfinished"
: error instanceof CheckBudgetError
? "check_budget_reached"
: "check_runtime_failure"),
"error",
normalizeErrorMessage(error),
error instanceof CheckDeadlineError ? (error.sourceFile ?? "index.html") : "index.html",
);
}
function failureReport(options: CheckOptions, finding: CheckFinding): CheckReport {
const lint = { ...section([]), filesScanned: 0 };
const browser = emptyBrowserResult();
browser.runtimeFindings.push(finding);
return buildReport(options, lint, browser, { kind: "none" }, [], []);
}
function isBbox(value: unknown): value is CheckBbox {
if (typeof value !== "object" || value === null) return false;
return ["x", "y", "width", "height"].every((key) => typeof Reflect.get(value, key) === "number");
}
function isStringRecord(value: unknown): value is Record<string, string> {
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
return Object.keys(value).every((key) => typeof Reflect.get(value, key) === "string");
}
function resolveMotionSpec(projectDir: string): MotionSpecResolution {
const path = findMotionSpec(projectDir);
if (!path) return { kind: "none" };
const result = readMotionSpec(path);
return result.ok
? { kind: "valid", path, spec: result.spec }
: {
kind: "invalid",
path,
message: `Invalid motion spec ${path}: ${result.errors.join("; ")}`,
};
}
async function runBrowserCheck(
project: ProjectDir,
options: CheckOptions,
motion: MotionSpecResolution,
deadline?: CheckDeadline,
prelaunched?: PrelaunchedBrowser,
): Promise<CheckBrowserResult> {
const module = await import("./checkBrowser.js");
// runAuditGrid is handed over as a callback so checkBrowser never imports
// this module back (no import cycle).
return module.runBrowserCheck(project, options, motion, runAuditGrid, deadline, prelaunched);
}
// Chrome boots while lint, hdr and bundling run; the source index guesses the bundle's launch arguments.
let adoptedBrowser: PrelaunchedBrowser | undefined;
export async function prelaunchBrowserForNextCheck(
project: ProjectDir,
options: CheckOptions,
): Promise<PrelaunchedBrowser | undefined> {
adoptedBrowser = await prelaunchBrowser(project, options);
return adoptedBrowser;
}
async function prelaunchBrowser(
project: ProjectDir,
options: CheckOptions,
): Promise<PrelaunchedBrowser | undefined> {
const adopted = adoptedBrowser;
adoptedBrowser = undefined;
if (adopted) return adopted;
const html = await readFile(project.indexPath, "utf8").catch(() => undefined);
if (html === undefined) return undefined;
const { prelaunchCompositionBrowser } = await import("../capture/captureCompositionFrame.js");
return prelaunchCompositionBrowser(html, options.browserGpuMode);
}
async function writeSnapshot(
projectDir: string,
index: number,
time: number,
pngBase64: string,
): Promise<string> {
const snapshotDir = checkSnapshotDirectory(projectDir);
const filename = `frame-${String(index).padStart(2, "0")}-at-${time.toFixed(1)}s.png`;
const path = join(snapshotDir, filename);
writeFileSync(path, Buffer.from(pngBase64, "base64"));
return relative(projectDir, path);
}
async function captureFindingFrames(
project: ProjectDir,
options: CheckOptions,
requests: CheckFindingFrameRequest[],
deadline?: CheckDeadline,
): Promise<CheckFindingFrames> {
const module = await import("./checkBrowser.js");
return module.captureFindingFrames(project, options, requests, deadline);
}
async function captureFindingCrops(
project: ProjectDir,
options: CheckOptions,
requests: CheckFindingCropRequest[],
deadline?: CheckDeadline,
): Promise<string[]> {
const module = await import("./checkBrowser.js");
// Handed over the same way runBrowserCheck is (checkBrowser never imports this module back).
return module.captureFindingCrops(project, options, requests, deadline);
}
/** HDR promotion before the browser starts; audio findings later, overlapping the browser pass. */
async function inspectProjectMedia(
project: ProjectDir,
dependencies: CheckDependencies,
): Promise<{ hdr: CheckReport["hdr"]; audio: Promise<CheckFinding[]> }> {
const media = (dependencies.collectMedia ?? collectMedia)(project);
let hdr: CheckReport["hdr"];
try {
const found = await media;
const promotion = (dependencies.inspectHdrAutoPromotion ?? inspectHdrAutoPromotion)(
project,
found,
);
const remote = remoteMediaNotInspected(found);
hdr = {
autoPromotion: await promotion,
inspection: "available",
...(remote.length > 0 ? { remoteNotInspected: remote } : {}),
};
} catch {
hdr = { autoPromotion: null, inspection: "unavailable" };
}
const audio = media
.then((found) => (dependencies.inspectAudio ?? inspectAudio)(project, found))
.catch((error: unknown) => audioCheckFailure(project, error));
return { hdr, audio };
}
function collectMedia(project: ProjectDir): Promise<ProjectMedia> {
return collectProjectMedia(project.dir);
}
async function inspectAudio(project: ProjectDir, media: ProjectMedia): Promise<CheckFinding[]> {
const module = await import("./checkAudio.js");
return module.inspectAudio(project.dir, relative(project.dir, project.indexPath), media);
}
function audioCheckFailure(project: ProjectDir, error: unknown): CheckFinding[] {
return [
findingAtRoot(
"audio_check_unavailable",
"info",
`Audio was not checked: ${normalizeErrorMessage(error)}`,
relative(project.dir, project.indexPath),
),
];
}
const DEFAULT_DEPENDENCIES: CheckDependencies = {
lintProject: (projectDir, options) => lintProject(projectDir, undefined, {}, options),
resolveMotionSpec,
runBrowserCheck,
prelaunchBrowser,
writeSnapshot,
captureFindingCrops,
captureFindingFrames,
collectMedia,
inspectHdrAutoPromotion,
inspectAudio,
};