mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* 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>
2485 lines
89 KiB
TypeScript
2485 lines
89 KiB
TypeScript
import { DEFAULT_CONFIG } from "@hyperframes/engine";
|
|
import { CheckCopiesUnfinishedError, COPY_BUDGET_MS, type CheckDeadline } from "./checkDeadline.js";
|
|
import { SEEK_SETTLES_BEFORE_PROTOCOL_TIMEOUT_MS } from "../capture/captureTimeout.js";
|
|
import { logCheckProgress } from "./checkProgress.js";
|
|
import { BrowserCleanupError, closeManagedBrowser, onStopSignal } from "../browser/launch.js";
|
|
import { collectMotionBlurDrafts, dropMotionBlurConsoleEcho } from "./checkMotionBlur.js";
|
|
import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";
|
|
import { existsSync, writeFileSync } from "node:fs";
|
|
import os from "node:os";
|
|
import { isAbsolute, join, relative, resolve } from "node:path";
|
|
import type { Browser, Page } from "puppeteer-core";
|
|
import {
|
|
AUDIT_SEEK_OPTIONS,
|
|
DENSE_GEOMETRY_SEEK_OPTIONS,
|
|
SCREENSHOT_SEEK_OPTIONS,
|
|
DEFAULT_ZOOM_PADDING_PX,
|
|
DEFAULT_ZOOM_SCALE,
|
|
captureRegionCrop,
|
|
openSettledCompositionPage,
|
|
padCropRegion,
|
|
resolveCliChromeGpuMode,
|
|
seekCompositionTimeline,
|
|
waitForPreferredSeekTarget,
|
|
seekInPage,
|
|
type PrelaunchedBrowser,
|
|
} from "../capture/captureCompositionFrame.js";
|
|
import {
|
|
auditClipDurations,
|
|
shouldIgnoreHttpError,
|
|
shouldIgnoreRequestFailure,
|
|
} from "../commands/validate.js";
|
|
import { loadBrowserScript } from "../commands/browserScript.js";
|
|
import { normalizeErrorMessage } from "./errorMessage.js";
|
|
import { ambiguousIssue, type MotionFrame } from "./motionAudit.js";
|
|
import type { LayoutIssue, LayoutIssueCode, LayoutRect } from "./layoutAudit.js";
|
|
import { serveStaticProjectHtml, type StaticProjectServer } from "./staticProjectServer.js";
|
|
import { prepareFindingInspector } from "./checkFindingInspect.js";
|
|
import { collectTweenRecords, findTweenTails, tweenTailMessage } from "./gsapTweenTails.js";
|
|
import {
|
|
measuredInMotion,
|
|
readContrastMotion,
|
|
type ContrastMotionSample,
|
|
} from "./contrastMotion.js";
|
|
import { resolveAutoProxy } from "./projectConfig.js";
|
|
import { findStageProxyBox } from "./compositionViewport.js";
|
|
import { mediaUsedSeconds } from "./mediaUsedSeconds.js";
|
|
import type { PreviewProxyBox } from "@hyperframes/core";
|
|
import { injectTagsAtHeadStart } from "@hyperframes/core/compiler/html-document";
|
|
import {
|
|
STUDIO_PREVIEW_CAPTURE_MODE,
|
|
STUDIO_PREVIEW_MARK_META,
|
|
} from "@hyperframes/core/studio-preview-mark";
|
|
import {
|
|
decideMediaProxyEligibility,
|
|
proxyVariantFor,
|
|
scanProjectMediaCodecMap,
|
|
shouldPrewarmProxy,
|
|
} from "@hyperframes/studio-server/media-codec-map";
|
|
import {
|
|
FfmpegUnavailableError,
|
|
getProxyCachePath,
|
|
proxyWindowSeconds,
|
|
resolveProxies,
|
|
type ProxyProgress,
|
|
} from "@hyperframes/studio-server/proxy-transcoder";
|
|
import { rectToBbox, type MediaCopyFacts } from "./checkTypes.js";
|
|
import type {
|
|
AnchoredLayoutIssue,
|
|
CheckAnchor,
|
|
CheckAnnotationBox,
|
|
CheckAuditDriver,
|
|
CheckBbox,
|
|
CheckBrowserResult,
|
|
CheckFinding,
|
|
CheckFindingCropRequest,
|
|
CheckFindingFrameRequest,
|
|
CheckFindingFrames,
|
|
CheckFindingInspection,
|
|
CheckGeometryCandidate,
|
|
CheckOptions,
|
|
CheckSeverity,
|
|
ContrastAuditEntry,
|
|
ContrastCapture,
|
|
CraftFilm,
|
|
CraftFrame,
|
|
CraftTextPart,
|
|
GeometryCandidateRequest,
|
|
LayoutOptions,
|
|
MotionSpecResolution,
|
|
OffPivotFrame,
|
|
OffPivotRotationSample,
|
|
RotationSample,
|
|
RunAuditGrid,
|
|
SeekClock,
|
|
TextOverVideoCandidate,
|
|
} from "./checkTypes.js";
|
|
import type { ProjectDir } from "./project.js";
|
|
|
|
export const RENDER_READY_WARNING_SUFFIX = `the scene may still be building, so results can miss late content; raise --timeout (for example ${(DEFAULT_CONFIG.playerReadyTimeout * 2) / 1000}s)`;
|
|
|
|
interface RuntimeDraft {
|
|
code: string;
|
|
severity: CheckSeverity;
|
|
message: string;
|
|
time: number;
|
|
timeRange?: [number, number];
|
|
url?: string;
|
|
line?: number;
|
|
count?: number;
|
|
abortedImage?: boolean;
|
|
networkChanged?: boolean;
|
|
fixHint?: string;
|
|
}
|
|
|
|
type RuntimeStamp = Pick<RuntimeDraft, "time" | "timeRange">;
|
|
|
|
interface RuntimeClock {
|
|
now(): RuntimeStamp;
|
|
at(time: number): void;
|
|
during(range: [number, number]): void;
|
|
}
|
|
|
|
interface AnchorRequest {
|
|
selector: string;
|
|
time: number;
|
|
bbox: CheckBbox;
|
|
}
|
|
|
|
interface ContrastCandidate {
|
|
selector: string;
|
|
text: string;
|
|
fg: [number, number, number, number];
|
|
large: boolean;
|
|
bbox: CheckBbox;
|
|
}
|
|
|
|
interface PreparedContrast {
|
|
// The untouched candidate object from __contrastAuditPrepare. It round-trips
|
|
// back into __contrastAuditFinish verbatim — the browser script owns its
|
|
// shape (e.g. bbox uses w/h, not width/height), so Node must not normalize
|
|
// what it sends back. `candidate` is the parsed copy for Node-side reporting.
|
|
raw: unknown;
|
|
candidate: ContrastCandidate;
|
|
knownBackdrop: boolean;
|
|
anchor: CheckAnchor;
|
|
motion: ContrastMotionSample | null;
|
|
}
|
|
|
|
interface FinishedContrast {
|
|
selector: string;
|
|
text: string;
|
|
ratio: number;
|
|
wcagAA: boolean;
|
|
large: boolean;
|
|
fg: string;
|
|
bg: string;
|
|
}
|
|
|
|
const COPY_HEARTBEAT_MS = 10_000;
|
|
|
|
function elapsedText(ms: number): string {
|
|
const seconds = Math.round(ms / 1000);
|
|
return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
|
|
}
|
|
|
|
/** Says on stderr how far each copy is, so a slow copy reads as slow and a stuck one as stuck. */
|
|
function startCopyHeartbeat(
|
|
sources: ReadonlyArray<{ file: string }>,
|
|
cached: readonly boolean[],
|
|
): {
|
|
progress: (index: number, progress: ProxyProgress) => void;
|
|
settled: (index: number) => void;
|
|
stop: () => void;
|
|
percent: (index: number) => string;
|
|
} {
|
|
const startedAt = Date.now();
|
|
const latest = new Map<number, ProxyProgress>();
|
|
const last = new Map<number, ProxyProgress>();
|
|
const total = cached.filter((isCached) => !isCached).length;
|
|
let finished = 0;
|
|
const timer = setInterval(() => {
|
|
for (const [index, { doneSeconds, totalSeconds }] of latest) {
|
|
if (cached[index]) continue;
|
|
const done = totalSeconds
|
|
? `${Math.min(100, Math.floor((doneSeconds / totalSeconds) * 100))}%`
|
|
: "";
|
|
console.error(
|
|
`[hyperframes] making browser-playable copies: ${finished} of ${total} done. ${sources[index]!.file}: ${done || `${Math.floor(doneSeconds)}s done`} (${elapsedText(Date.now() - startedAt)} so far)`,
|
|
);
|
|
}
|
|
}, COPY_HEARTBEAT_MS);
|
|
timer.unref();
|
|
return {
|
|
progress: (index, progress) => {
|
|
latest.set(index, progress);
|
|
last.set(index, progress);
|
|
},
|
|
percent: (index) => {
|
|
const { doneSeconds = 0, totalSeconds } = last.get(index) ?? {};
|
|
return totalSeconds
|
|
? `${Math.min(100, Math.floor((doneSeconds / totalSeconds) * 100))}%`
|
|
: "not started";
|
|
},
|
|
settled: (index) => {
|
|
latest.delete(index);
|
|
if (!cached[index]) finished += 1;
|
|
},
|
|
stop: () => clearInterval(timer),
|
|
};
|
|
}
|
|
|
|
/** Absolute path -> seconds of it the composition plays, for the given files worth copying only in part. */
|
|
async function copyWindows(
|
|
projectDir: string,
|
|
html: string,
|
|
pathnames: Iterable<string>,
|
|
): Promise<Map<string, number>> {
|
|
const used = mediaUsedSeconds(html);
|
|
const windows = new Map<string, number>();
|
|
await Promise.all(
|
|
[...pathnames].map(async (pathname) => {
|
|
const seconds = used.get(pathname);
|
|
if (seconds === undefined) return;
|
|
const sourcePath = resolve(projectDir, pathname.replace(/^\/+/, ""));
|
|
const window = await proxyWindowSeconds(sourcePath, seconds);
|
|
if (window !== undefined) windows.set(sourcePath, window);
|
|
}),
|
|
);
|
|
return windows;
|
|
}
|
|
|
|
/**
|
|
* Awaits the H.264 authoring proxy for every browser-hostile local video
|
|
* asset in `html` BEFORE the timed render-ready wait starts. `check`'s
|
|
* render-ready wait defaults to 45 s (`DEFAULT_CHECK_OPTIONS.timeout`,
|
|
* passed through as `renderReadyTimeoutMs`), and a cold `.transcode-cache`
|
|
* cannot fit inside that window — without this, a project's first
|
|
* hostile-asset check (e.g. a fresh CI checkout) would race the timeout
|
|
* instead of paying a bounded one-time transcode cost
|
|
* (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U4).
|
|
* A failed copy is a warning, not an error: a default render decodes the original with
|
|
* ffmpeg. One warning per failed file, or one for all of them when ffmpeg itself is unusable.
|
|
*/
|
|
export async function preResolveHostileMediaProxies(
|
|
projectDir: string,
|
|
html: string,
|
|
autoProxyOverride?: boolean,
|
|
budgetMs?: number,
|
|
record?: (facts: MediaCopyFacts) => void,
|
|
): Promise<ProxyPreResolution> {
|
|
const none: ProxyPreResolution = {
|
|
findings: [],
|
|
failedPaths: new Set(),
|
|
files: [],
|
|
limits: new Map(),
|
|
};
|
|
if (!resolveAutoProxy(projectDir, autoProxyOverride)) return none;
|
|
let codecMap: Awaited<ReturnType<typeof scanProjectMediaCodecMap>>;
|
|
try {
|
|
codecMap = await scanProjectMediaCodecMap(projectDir, [{ html }]);
|
|
} catch (err) {
|
|
console.error(
|
|
`[hyperframes] media proxy pre-resolve: scan failed (${normalizeErrorMessage(err)})`,
|
|
);
|
|
return none;
|
|
}
|
|
const hostileEntries = Object.entries(codecMap).filter(
|
|
([, facts]) => decideMediaProxyEligibility(facts).eligible && shouldPrewarmProxy(facts),
|
|
);
|
|
if (hostileEntries.length === 0) return none;
|
|
|
|
const startedAt = Date.now();
|
|
const stageBox = findStageProxyBox(html);
|
|
const sources: Array<{
|
|
pathname: string;
|
|
file: string;
|
|
sourcePath: string;
|
|
variant: ReturnType<typeof proxyVariantFor>;
|
|
box: PreviewProxyBox | undefined;
|
|
limitSeconds?: number;
|
|
}> = hostileEntries.map(([pathname, facts]) => {
|
|
const file = pathname.replace(/^\/+/, "");
|
|
return {
|
|
pathname,
|
|
file,
|
|
sourcePath: resolve(projectDir, file),
|
|
variant: proxyVariantFor(facts),
|
|
box: stageBox,
|
|
};
|
|
});
|
|
const windows =
|
|
mediaUsedSeconds(html).size > 0
|
|
? await copyWindows(
|
|
projectDir,
|
|
html,
|
|
sources.map(({ pathname }) => pathname),
|
|
)
|
|
: new Map<string, number>();
|
|
for (const source of sources) source.limitSeconds = windows.get(source.sourcePath);
|
|
const total = hostileEntries.length;
|
|
const cached = sources.map((source) => proxyCached(projectDir, source));
|
|
const toMake = cached.filter((isCached) => !isCached).length;
|
|
if (toMake > 0) {
|
|
console.error(
|
|
`[hyperframes] Making browser-playable copies of ${toMake} video${toMake === 1 ? "" : "s"} Chrome cannot decode. Only the first check of these files waits for this; later checks reuse the copies.`,
|
|
);
|
|
}
|
|
let settled = 0;
|
|
const heartbeat = startCopyHeartbeat(sources, cached);
|
|
const stopped = new AbortController();
|
|
const forgetStop = onStopSignal(() => stopped.abort());
|
|
let overBudget: number | undefined;
|
|
const budget =
|
|
budgetMs === undefined
|
|
? undefined
|
|
: setTimeout(() => {
|
|
overBudget = budgetMs;
|
|
stopped.abort();
|
|
}, budgetMs);
|
|
const results = await resolveProxies(
|
|
projectDir,
|
|
sources,
|
|
(index) => {
|
|
settled += 1;
|
|
heartbeat.settled(index);
|
|
if (toMake > 0) console.error(`[hyperframes] browser-playable copies: ${settled}/${total}`);
|
|
},
|
|
heartbeat.progress,
|
|
stopped.signal,
|
|
).finally(() => {
|
|
heartbeat.stop();
|
|
forgetStop();
|
|
clearTimeout(budget);
|
|
});
|
|
const unfinished = sources.flatMap(({ file }, index) =>
|
|
results[index]!.status === "rejected" ? [`${file} ${heartbeat.percent(index)}`] : [],
|
|
);
|
|
record?.({
|
|
total,
|
|
waitedMs: Date.now() - startedAt,
|
|
unfinished: overBudget === undefined ? 0 : unfinished.length,
|
|
});
|
|
if (overBudget !== undefined && unfinished.length > 0) {
|
|
throw new CheckCopiesUnfinishedError(overBudget, unfinished);
|
|
}
|
|
const failures = sources.flatMap((source, index) => {
|
|
const result = results[index]!;
|
|
return result.status === "rejected" ? [{ ...source, reason: result.reason }] : [];
|
|
});
|
|
console.error(
|
|
`[hyperframes] media proxy pre-resolve: ${total - failures.length}/${total} ready, ${failures.length} failed (${Date.now() - startedAt}ms)`,
|
|
);
|
|
const unusableFfmpeg = failures.filter(({ reason }) => reason instanceof FfmpegUnavailableError);
|
|
const findings = failures
|
|
.filter(({ reason }) => !(reason instanceof FfmpegUnavailableError))
|
|
.map(({ file, reason }) =>
|
|
proxyFailedDraft(
|
|
`Could not make a browser-playable copy of ${file}: ${normalizeErrorMessage(reason)}. A default render decodes the original with ffmpeg and does not need it, but publish stops on it (unless run with --no-proxy) and a browser that cannot decode the original will not play it in preview.`,
|
|
),
|
|
);
|
|
if (unusableFfmpeg[0]) {
|
|
findings.unshift(
|
|
proxyFailedDraft(
|
|
`Could not make browser-playable copies of ${unusableFfmpeg.map(({ file }) => file).join(", ")}: ${normalizeErrorMessage(unusableFfmpeg[0].reason)}. Publish stops on them (unless run with --no-proxy) and a browser that cannot decode them will not play them in preview.`,
|
|
),
|
|
);
|
|
}
|
|
const files = sources.map(({ file }, index): PreparedMediaFile => {
|
|
const result = results[index]!;
|
|
if (result.status === "rejected") {
|
|
return { file, state: "failed", reason: normalizeErrorMessage(result.reason) };
|
|
}
|
|
return { file, state: cached[index] ? "cached" : "ready" };
|
|
});
|
|
return {
|
|
findings,
|
|
failedPaths: new Set(failures.map(({ pathname }) => pathname)),
|
|
files,
|
|
limits: windows,
|
|
};
|
|
}
|
|
|
|
function proxyCached(
|
|
projectDir: string,
|
|
source: {
|
|
sourcePath: string;
|
|
variant: ReturnType<typeof proxyVariantFor>;
|
|
box?: PreviewProxyBox;
|
|
limitSeconds?: number;
|
|
},
|
|
): boolean {
|
|
try {
|
|
return existsSync(
|
|
getProxyCachePath(
|
|
projectDir,
|
|
source.sourcePath,
|
|
source.variant,
|
|
source.box,
|
|
source.limitSeconds,
|
|
),
|
|
);
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
export interface PreparedMediaFile {
|
|
file: string;
|
|
state: "ready" | "cached" | "failed";
|
|
reason?: string;
|
|
}
|
|
|
|
interface ProxyPreResolution {
|
|
findings: RuntimeDraft[];
|
|
/** Root-relative paths of the videos whose copy failed. */
|
|
failedPaths: Set<string>;
|
|
/** One entry per browser-hostile video, in project order. */
|
|
files: PreparedMediaFile[];
|
|
/** Absolute path -> seconds from the start that the composition plays, for the copies made short. */
|
|
limits: Map<string, number>;
|
|
}
|
|
|
|
function proxyFailedDraft(message: string): RuntimeDraft {
|
|
return { code: "media_proxy_failed", severity: "warning", message, time: 0 };
|
|
}
|
|
|
|
async function loadCheckHtmlWithDeferredMedia(dir: string): Promise<string> {
|
|
const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");
|
|
return withCapturePreviewMark(await bundleWithLocalizedFonts(dir));
|
|
}
|
|
|
|
function withCapturePreviewMark(html: string): string {
|
|
return injectTagsAtHeadStart(
|
|
html,
|
|
`<meta name="${STUDIO_PREVIEW_MARK_META}" content="${STUDIO_PREVIEW_CAPTURE_MODE}">`,
|
|
);
|
|
}
|
|
|
|
export async function runBrowserCheck(
|
|
project: ProjectDir,
|
|
options: CheckOptions,
|
|
motion: MotionSpecResolution,
|
|
runGrid: RunAuditGrid,
|
|
deadline?: CheckDeadline,
|
|
prelaunched?: PrelaunchedBrowser,
|
|
): Promise<CheckBrowserResult> {
|
|
const html = await loadCheckHtmlWithDeferredMedia(project.dir);
|
|
deadline?.enter("copies");
|
|
let mediaCopies: MediaCopyFacts | undefined;
|
|
deadline?.keepPartial(() => (mediaCopies ? { mediaCopies } : {}));
|
|
const {
|
|
findings: drafts,
|
|
failedPaths,
|
|
limits,
|
|
} = await preResolveHostileMediaProxies(
|
|
project.dir,
|
|
html,
|
|
options.autoProxy,
|
|
Math.min(COPY_BUDGET_MS, deadline?.remainingMs() ?? COPY_BUDGET_MS),
|
|
(facts) => {
|
|
mediaCopies = facts;
|
|
},
|
|
);
|
|
deadline?.enter("launch");
|
|
const server = await serveStaticProjectHtml(
|
|
project.dir,
|
|
html,
|
|
"Failed to bind check server",
|
|
[],
|
|
options.autoProxy,
|
|
limits,
|
|
);
|
|
const clock = createRuntimeClock();
|
|
let failure: { kind: "none" } | { kind: "failed"; error: unknown } = { kind: "none" };
|
|
let chromeBrowser: import("puppeteer-core").Browser | undefined;
|
|
const helperSession =
|
|
samplingBrowserCount(options) > 1
|
|
? startHelperSession(html, server.url, options, deadline, project.dir)
|
|
: undefined;
|
|
const helperOpen = helperSession?.opened;
|
|
const helpers = helperOpen?.then(
|
|
(helper) => [helper.driver],
|
|
() => [],
|
|
);
|
|
|
|
try {
|
|
const launchSettleStart = Date.now();
|
|
const session = await openSettledCompositionPage(html, server.url, {
|
|
navigationTimeoutMs: options.timeout,
|
|
renderReadyTimeoutMs: options.timeout,
|
|
renderReadyWarningSuffix: RENDER_READY_WARNING_SUFFIX,
|
|
prelaunched,
|
|
browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),
|
|
signal: deadline?.signal,
|
|
onBrowser: deadline?.ownBrowser,
|
|
onBrowserReady: deadline?.start,
|
|
beforeNavigate: async (page) => {
|
|
wireRuntimeListeners(page, drafts, clock);
|
|
await deadline?.preparePage(page);
|
|
},
|
|
onLoaded: () => deadline?.enter("settle"),
|
|
});
|
|
chromeBrowser = session.browser;
|
|
const page = session.page;
|
|
await waitForPreferredSeekTarget(page);
|
|
|
|
const rootAnchor = await resolveRootAnchor(page);
|
|
deadline?.keepPartial(() => ({
|
|
runtimeFindings: dropFailedProxyEchoes(
|
|
keepFailedNetworkChanges(keepBrokenImageAborts(drafts, new Set()), new Set()),
|
|
failedPaths,
|
|
).map((draft) => runtimeFinding(draft, rootAnchor)),
|
|
}));
|
|
const launchSettleMs = Date.now() - launchSettleStart;
|
|
// validate's per-media-element audit, kept in the consolidation: a clip
|
|
// whose intrinsic duration is meaningfully shorter than its data-duration
|
|
// slot silently shortens the slot at render time — invisible to lint (no
|
|
// intrinsic durations statically) and to the runtime listeners (nothing
|
|
// errors). The session is already open, so this is one extra evaluate.
|
|
const { analyzeClipMediaFit } = await import("@hyperframes/engine");
|
|
for (const entry of await auditClipDurations(page, analyzeClipMediaFit, options.timeout)) {
|
|
drafts.push({ code: "clip_media_fit", severity: entry.level, message: entry.text, time: 0 });
|
|
}
|
|
for (const tail of findTweenTails((await page.evaluate(collectTweenRecords)) ?? [])) {
|
|
const message = tweenTailMessage(tail);
|
|
drafts.push({ code: "gsap_tween_tail", severity: "warning", message, time: tail.later.end });
|
|
}
|
|
const blur = await collectMotionBlurDrafts(page);
|
|
drafts.push(...blur);
|
|
const sampleLog = sampleWindow(drafts);
|
|
const driver = createPageDriver(page, clock, sampleLog, project.dir);
|
|
const result = await runGrid(
|
|
driver,
|
|
options,
|
|
motion,
|
|
helpers,
|
|
deadline?.enter,
|
|
logCheckProgress,
|
|
deadline?.keepPartial,
|
|
deadline?.signal,
|
|
);
|
|
helperSession?.stop();
|
|
const helper = await helperOpen?.catch(() => undefined);
|
|
const merged = helper ? mergeHelperDrafts(sampleLog, helper.sampleLog) : drafts;
|
|
const broken = await abortedImagesStillBroken(page, merged);
|
|
const unreachable = await networkChangesStillFailing(merged);
|
|
return {
|
|
...result,
|
|
...(mediaCopies && { mediaCopies }),
|
|
timings: { ...result.timings, launchSettleMs },
|
|
renderReadyTimedOut: session.renderReadyTimedOut,
|
|
runtimeFindings: dropFailedProxyEchoes(
|
|
dropMotionBlurConsoleEcho(
|
|
keepFailedNetworkChanges(keepBrokenImageAborts(merged, broken), unreachable),
|
|
blur,
|
|
),
|
|
failedPaths,
|
|
).map((draft) => runtimeFinding(draft, rootAnchor)),
|
|
};
|
|
} catch (error) {
|
|
failure = { kind: "failed", error };
|
|
throw error;
|
|
} finally {
|
|
helperSession?.stop();
|
|
await helperOpen?.catch(() => undefined);
|
|
await closeCheckResources([chromeBrowser, helperSession?.browser()], server, failure);
|
|
}
|
|
}
|
|
|
|
function createRuntimeClock(): RuntimeClock {
|
|
let stamp: RuntimeStamp = { time: 0 };
|
|
return {
|
|
now: () => stamp,
|
|
at: (time) => {
|
|
stamp = { time };
|
|
},
|
|
during: (range) => {
|
|
stamp = { time: range[0], timeRange: range };
|
|
},
|
|
};
|
|
}
|
|
|
|
const SAMPLING_BROWSER_BYTES = 250 * 1024 * 1024;
|
|
|
|
/** Chromes the sample grid splits over: one per spare core and 250 MB free (a container's limit counts), at most 2. */
|
|
export function samplingBrowserCount(
|
|
options: CheckOptions,
|
|
cores = os.availableParallelism(),
|
|
free = Math.min(os.freemem(), process.availableMemory()),
|
|
): number {
|
|
if (options.at?.length === 1) return 1;
|
|
return Math.max(1, Math.min(2, cores - 1, Math.floor(free / SAMPLING_BROWSER_BYTES)));
|
|
}
|
|
|
|
interface SampleWindow {
|
|
drafts: RuntimeDraft[];
|
|
start: number;
|
|
end: number;
|
|
}
|
|
|
|
function sampleWindow(drafts: RuntimeDraft[]): SampleWindow {
|
|
return { drafts, start: Number.POSITIVE_INFINITY, end: Number.POSITIVE_INFINITY };
|
|
}
|
|
|
|
interface HelperSession {
|
|
driver: CheckAuditDriver;
|
|
sampleLog: SampleWindow;
|
|
}
|
|
|
|
/** Opens the helper Chrome; stop() cancels an open still in flight and closes it, once its pages are unused. */
|
|
function startHelperSession(
|
|
html: string,
|
|
url: string,
|
|
options: CheckOptions,
|
|
deadline: CheckDeadline | undefined,
|
|
projectDir: string,
|
|
) {
|
|
const abort = new AbortController();
|
|
let browser: Browser | undefined;
|
|
const opened = openHelperSession(html, url, options, deadline, projectDir, {
|
|
signal: deadline ? AbortSignal.any([deadline.signal, abort.signal]) : abort.signal,
|
|
onBrowser: (launched) => {
|
|
browser = launched;
|
|
deadline?.ownBrowser(launched);
|
|
},
|
|
});
|
|
return {
|
|
opened,
|
|
browser: () => browser,
|
|
stop: () => {
|
|
abort.abort();
|
|
// The close is shared, so the check's cleanup awaits this same close and reports its error.
|
|
if (browser) void closeManagedBrowser(browser).catch(() => undefined);
|
|
},
|
|
};
|
|
}
|
|
|
|
async function openHelperSession(
|
|
html: string,
|
|
url: string,
|
|
options: CheckOptions,
|
|
deadline: CheckDeadline | undefined,
|
|
projectDir: string,
|
|
owner: { signal: AbortSignal; onBrowser: (browser: Browser) => void },
|
|
): Promise<HelperSession> {
|
|
const sampleLog = sampleWindow([]);
|
|
const clock = createRuntimeClock();
|
|
const session = await openSettledCompositionPage(html, url, {
|
|
navigationTimeoutMs: options.timeout,
|
|
renderReadyTimeoutMs: options.timeout,
|
|
renderReadyWarningSuffix: RENDER_READY_WARNING_SUFFIX,
|
|
browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),
|
|
signal: owner.signal,
|
|
onBrowser: owner.onBrowser,
|
|
beforeNavigate: async (page) => {
|
|
wireRuntimeListeners(page, sampleLog.drafts, clock);
|
|
await deadline?.preparePage(page);
|
|
},
|
|
});
|
|
await waitForPreferredSeekTarget(session.page);
|
|
return {
|
|
driver: createPageDriver(session.page, clock, sampleLog, projectDir),
|
|
sampleLog,
|
|
};
|
|
}
|
|
|
|
const draftKey = (draft: RuntimeDraft) => `${draft.code} ${draft.time} ${draft.message}`;
|
|
|
|
/**
|
|
* The first page's drafts with the helper's sample-loop drafts merged in by time, as one page seeking every
|
|
* sample would have logged them; the helper's load is the first page's, and what both logged at one time counts once.
|
|
*/
|
|
export function mergeHelperDrafts(primary: SampleWindow, helper: SampleWindow): RuntimeDraft[] {
|
|
const window = ({ drafts, start, end }: SampleWindow) =>
|
|
drafts.slice(Math.min(start, drafts.length), Math.min(end, drafts.length));
|
|
const own = window(primary);
|
|
const seen = new Set(own.map(draftKey));
|
|
const extra = window(helper).filter((draft) => !seen.has(draftKey(draft)));
|
|
const start = Math.min(primary.start, primary.drafts.length);
|
|
return [
|
|
...primary.drafts.slice(0, start),
|
|
...[...own, ...extra].sort((a, b) => a.time - b.time),
|
|
...primary.drafts.slice(start + own.length),
|
|
];
|
|
}
|
|
|
|
/**
|
|
* `check --snapshots`'s per-finding evidence crops. Opens its own session
|
|
* (the main grid session already closed by the time findings are shaped) and
|
|
* re-seeks to each finding's sample time — renders are deterministic, so a
|
|
* fresh page at the same time reproduces the same pixels the grid audited.
|
|
*/
|
|
export async function captureFindingCrops(
|
|
project: ProjectDir,
|
|
options: CheckOptions,
|
|
requests: CheckFindingCropRequest[],
|
|
deadline?: CheckDeadline,
|
|
): Promise<string[]> {
|
|
if (requests.length === 0) return [];
|
|
return withFindingCapturePage(project, options, deadline, "crops", async (page, snapshotDir) => {
|
|
const written: string[] = [];
|
|
for (const request of requests) {
|
|
await seekCompositionTimeline(page, request.time, SCREENSHOT_SEEK_OPTIONS);
|
|
const canvas = await page.evaluate(() => ({
|
|
width: window.innerWidth,
|
|
height: window.innerHeight,
|
|
}));
|
|
const region = padCropRegion(request.bbox, canvas, DEFAULT_ZOOM_PADDING_PX);
|
|
const buffer = await captureRegionCrop(page, region, DEFAULT_ZOOM_SCALE);
|
|
writeFileSync(join(snapshotDir, request.filename), buffer);
|
|
written.push(join(snapshotDir, request.filename));
|
|
}
|
|
return written;
|
|
});
|
|
}
|
|
|
|
export async function captureFindingFrames(
|
|
project: ProjectDir,
|
|
options: CheckOptions,
|
|
requests: CheckFindingFrameRequest[],
|
|
deadline?: CheckDeadline,
|
|
): Promise<CheckFindingFrames> {
|
|
if (requests.length === 0) return { written: [], inspected: [] };
|
|
const inspector = requests.some((request) => request.inspect?.length)
|
|
? await prepareFindingInspector(project.dir, async (bundleOptions) => {
|
|
const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");
|
|
return withCapturePreviewMark(
|
|
await bundleWithLocalizedFonts(project.dir, undefined, bundleOptions),
|
|
);
|
|
})
|
|
: undefined;
|
|
deadline?.signal.throwIfAborted();
|
|
return withFindingCapturePage(
|
|
project,
|
|
options,
|
|
deadline,
|
|
"frames",
|
|
async (page, snapshotDir, server) => {
|
|
await inspector?.ready(server);
|
|
deadline?.signal.throwIfAborted();
|
|
const written: string[] = [];
|
|
const inspected: CheckFindingInspection[] = [];
|
|
for (const request of requests) {
|
|
deadline?.enter("frames");
|
|
await seekCompositionTimeline(page, request.time, SCREENSHOT_SEEK_OPTIONS);
|
|
const buffer = await page.screenshot({ type: "png", optimizeForSpeed: true });
|
|
writeFileSync(join(snapshotDir, request.filename), buffer);
|
|
written.push(join(snapshotDir, request.filename));
|
|
if (!inspector) continue;
|
|
for (const target of request.inspect ?? []) {
|
|
deadline?.enter("frames");
|
|
const inspect = await inspector.inspect(page, target);
|
|
deadline?.signal.throwIfAborted();
|
|
inspected.push({ time: request.time, target, inspect });
|
|
}
|
|
}
|
|
return { written, inspected };
|
|
},
|
|
inspector?.html,
|
|
);
|
|
}
|
|
|
|
async function withFindingCapturePage<T>(
|
|
project: ProjectDir,
|
|
options: CheckOptions,
|
|
deadline: CheckDeadline | undefined,
|
|
what: "crops" | "frames",
|
|
capture: (page: Page, snapshotDir: string, server: StaticProjectServer) => Promise<T>,
|
|
pageHtml?: string,
|
|
): Promise<T> {
|
|
const html = pageHtml ?? (await loadCheckHtmlWithDeferredMedia(project.dir));
|
|
const server = await serveStaticProjectHtml(
|
|
project.dir,
|
|
html,
|
|
"Failed to bind check server",
|
|
[],
|
|
options.autoProxy,
|
|
await copyWindows(project.dir, html, mediaUsedSeconds(html).keys()),
|
|
);
|
|
let chromeBrowser: import("puppeteer-core").Browser | undefined;
|
|
let failure: { kind: "none" } | { kind: "failed"; error: unknown } = { kind: "none" };
|
|
try {
|
|
const session = await openSettledCompositionPage(html, server.url, {
|
|
navigationTimeoutMs: options.timeout,
|
|
renderReadyTimeoutMs: options.timeout,
|
|
renderReadyWarningSuffix: `capturing finding ${what}`,
|
|
signal: deadline?.signal,
|
|
onBrowser: deadline?.ownBrowser,
|
|
onBrowserReady: deadline?.start,
|
|
beforeNavigate: (page) => deadline?.preparePage(page),
|
|
browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),
|
|
});
|
|
chromeBrowser = session.browser;
|
|
await waitForPreferredSeekTarget(session.page);
|
|
const snapshotDir = checkSnapshotDirectory(project.dir);
|
|
return await capture(session.page, snapshotDir, server);
|
|
} catch (error) {
|
|
failure = { kind: "failed", error };
|
|
throw error;
|
|
} finally {
|
|
await closeCheckResources([chromeBrowser], server, failure);
|
|
}
|
|
}
|
|
|
|
async function closeCheckResources(
|
|
browsers: (Browser | undefined)[],
|
|
server: { close(): Promise<void> },
|
|
failure: { kind: "none" } | { kind: "failed"; error: unknown },
|
|
): Promise<void> {
|
|
const cleanup = await Promise.allSettled([
|
|
...browsers.map((browser) => (browser ? closeManagedBrowser(browser) : Promise.resolve())),
|
|
server.close(),
|
|
]);
|
|
const errors = cleanup
|
|
.filter((entry) => entry.status === "rejected")
|
|
.map((entry) => entry.reason);
|
|
if (errors.length === 0) return;
|
|
if (failure.kind === "failed") errors.unshift(failure.error);
|
|
throw new BrowserCleanupError(errors, errors.map(normalizeErrorMessage).join("; "));
|
|
}
|
|
|
|
// `swapToProxy` / `emitUnavailableDiagnostic` (packages/core/src/runtime/
|
|
// mediaProxy.ts) embed their stable diagnostic codes in the console.info line
|
|
// precisely so this scraper can match a token instead of prose. Matching the
|
|
// shared "runtime_media_proxy_" prefix surfaces both codes; only those
|
|
// runtime-emitted info lines should ever become findings here — an ordinary
|
|
// `console.info` from a composition author's own script must not.
|
|
const MEDIA_PROXY_MARKER_PREFIX = "[hyperframes] runtime_media_proxy_";
|
|
const MEDIA_PROXY_UNAVAILABLE_MARKER = "[hyperframes] runtime_media_proxy_unavailable";
|
|
// `reportWebAudioMediaRoute` (packages/core/src/runtime/webAudioRoute.ts) uses
|
|
// the same code-in-the-console-line contract. It is emitted from the media
|
|
// DISCOVERY phase rather than from playback scheduling, precisely so this
|
|
// scraper can see it — `check` seeks, it never plays.
|
|
const WEB_AUDIO_BYPASS_MARKER = "[hyperframes] runtime_web_audio_bypass";
|
|
const WEBGPU_RUNTIME_FAILURE =
|
|
/\b(?:GPUValidationError|GPUOutOfMemoryError|GPUInternalError)\b|WebGPU uncaptured error|(?:destroyed\b.*\b(?:GPU )?(?:resource|buffer|texture)\b.*\bsubmit)|(?:(?:GPU )?(?:resource|buffer|texture)\b.*\bdestroyed\b.*\bsubmit)/i;
|
|
|
|
function isWebGpuRuntimeFailure(text: string): boolean {
|
|
return WEBGPU_RUNTIME_FAILURE.test(text);
|
|
}
|
|
|
|
function pushRuntimeDraft(drafts: RuntimeDraft[], draft: RuntimeDraft): void {
|
|
if (draft.code !== "webgpu_runtime_error") {
|
|
drafts.push(draft);
|
|
return;
|
|
}
|
|
const duplicate = drafts.find(
|
|
(entry) =>
|
|
entry.code === draft.code &&
|
|
entry.message === draft.message &&
|
|
entry.url === draft.url &&
|
|
entry.line === draft.line,
|
|
);
|
|
if (duplicate) {
|
|
duplicate.count = (duplicate.count ?? 1) + 1;
|
|
return;
|
|
}
|
|
drafts.push({ ...draft, count: 1 });
|
|
}
|
|
|
|
/**
|
|
* The finding code for a runtime-emitted `console.info` line, or null for the
|
|
* ordinary info logging a composition author's own script produces. Matching is
|
|
* prefix-anchored on the stable diagnostic codes the runtime deliberately embeds
|
|
* in the text, so a line that merely mentions one is not promoted.
|
|
*/
|
|
function runtimeInfoFindingCode(text: string): string | null {
|
|
if (text.startsWith(WEB_AUDIO_BYPASS_MARKER)) return "web_audio_bypass";
|
|
if (!text.startsWith(MEDIA_PROXY_MARKER_PREFIX)) return null;
|
|
return text.includes(MEDIA_PROXY_UNAVAILABLE_MARKER)
|
|
? "media_proxy_unavailable"
|
|
: "media_proxy_fallback";
|
|
}
|
|
|
|
const READ_PIXELS_STALL =
|
|
/^\[\.WebGL-[^\]]*\]GL Driver Message \([^)]*\): GPU stall due to ReadPixels/;
|
|
|
|
function wireRuntimeListeners(page: Page, drafts: RuntimeDraft[], clock: RuntimeClock): void {
|
|
followSampleTimeMarkers(page, clock.at);
|
|
page.on("console", (message) => {
|
|
const type = message.type();
|
|
const text = message.text();
|
|
if (type === "error" && !text.startsWith("Failed to load resource")) {
|
|
const location = message.location();
|
|
pushRuntimeDraft(drafts, {
|
|
code: "console_error",
|
|
severity: "error",
|
|
message: text,
|
|
...clock.now(),
|
|
url: location.url,
|
|
line: location.lineNumber,
|
|
});
|
|
} else if (type === "warn") {
|
|
if (READ_PIXELS_STALL.test(text)) return;
|
|
const location = message.location();
|
|
const webGpuFailure = isWebGpuRuntimeFailure(text);
|
|
pushRuntimeDraft(drafts, {
|
|
code: webGpuFailure ? "webgpu_runtime_error" : "console_warning",
|
|
severity: webGpuFailure ? "error" : "warning",
|
|
message: text,
|
|
...clock.now(),
|
|
url: location.url,
|
|
line: location.lineNumber,
|
|
});
|
|
} else if (type === "info") {
|
|
const code = runtimeInfoFindingCode(text);
|
|
if (!code) return;
|
|
const location = message.location();
|
|
pushRuntimeDraft(drafts, {
|
|
code,
|
|
severity: "info",
|
|
message: text,
|
|
...clock.now(),
|
|
url: location.url,
|
|
line: location.lineNumber,
|
|
});
|
|
}
|
|
});
|
|
page.on("pageerror", (error) => {
|
|
const message = normalizeErrorMessage(error);
|
|
if (message.includes("Unexpected token '<'") || message.includes("Unexpected token '<'")) {
|
|
return;
|
|
}
|
|
pushRuntimeDraft(drafts, {
|
|
code: "page_error",
|
|
severity: "error",
|
|
message,
|
|
...clock.now(),
|
|
});
|
|
});
|
|
wireNetworkListeners(page, drafts, clock);
|
|
}
|
|
|
|
export function keepFailedNetworkChanges(
|
|
drafts: RuntimeDraft[],
|
|
failing: Set<string>,
|
|
): RuntimeDraft[] {
|
|
return drafts.filter((draft) => !draft.networkChanged || failing.has(draft.url ?? ""));
|
|
}
|
|
|
|
/** Check's scrubs cancel image loads: an aborted image failed only if an `<img>` shows it and its decode fails. */
|
|
export function keepBrokenImageAborts(drafts: RuntimeDraft[], broken: Set<string>): RuntimeDraft[] {
|
|
return drafts.filter((draft) => !draft.abortedImage || broken.has(draft.url ?? ""));
|
|
}
|
|
|
|
/** One finding per failed proxy: the preview's own 502s and swap notes for that file repeat `media_proxy_failed`. */
|
|
export function dropFailedProxyEchoes(
|
|
drafts: RuntimeDraft[],
|
|
failedPaths: ReadonlySet<string>,
|
|
): RuntimeDraft[] {
|
|
if (failedPaths.size === 0) return drafts;
|
|
return drafts.filter((draft) => !failedPaths.has(proxyEchoPath(draft) ?? ""));
|
|
}
|
|
|
|
function proxyEchoPath(draft: RuntimeDraft): string | undefined {
|
|
if (draft.code === "http_error" || draft.code === "request_failed") {
|
|
const url = parseUrl(draft.url);
|
|
return url?.searchParams.has("hf-proxy") ? decodedPath(url) : undefined;
|
|
}
|
|
if (draft.code === "media_proxy_fallback" || draft.code === "media_proxy_unavailable") {
|
|
return decodedPath(parseUrl(/"([^"]+)"/.exec(draft.message)?.[1]));
|
|
}
|
|
return undefined;
|
|
}
|
|
|
|
function parseUrl(target: string | undefined): URL | undefined {
|
|
if (!target) return undefined;
|
|
try {
|
|
return new URL(target, "http://check.invalid/");
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|
|
|
|
function decodedPath(url: URL | undefined): string | undefined {
|
|
if (!url) return undefined;
|
|
try {
|
|
return decodeURIComponent(url.pathname);
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|
|
|
|
const IMAGE_DECODE_CAP_MS = 5000;
|
|
|
|
export async function networkChangesStillFailing(drafts: RuntimeDraft[]): Promise<Set<string>> {
|
|
const urls = [
|
|
...new Set(drafts.filter((draft) => draft.networkChanged).map((draft) => draft.url ?? "")),
|
|
];
|
|
const failing = await Promise.all(
|
|
urls.map(async (url) => {
|
|
try {
|
|
const response = await fetch(url, {
|
|
headers: { Range: "bytes=0-0", Referer: `${new URL(url).origin}/` },
|
|
signal: AbortSignal.timeout(5000),
|
|
});
|
|
await response.body?.cancel();
|
|
return response.status >= 400;
|
|
} catch {
|
|
return true;
|
|
}
|
|
}),
|
|
);
|
|
return new Set(urls.filter((_, i) => failing[i]));
|
|
}
|
|
|
|
async function abortedImagesStillBroken(page: Page, drafts: RuntimeDraft[]): Promise<Set<string>> {
|
|
const urls = drafts.filter((draft) => draft.abortedImage).map((draft) => draft.url ?? "");
|
|
if (urls.length === 0) return new Set();
|
|
const broken = await page.evaluate(
|
|
async (candidates: string[], capMs: number) => {
|
|
// A load still pending at the cap (a deferred lazy image) is not a failure.
|
|
const fails = (img: HTMLImageElement) =>
|
|
new Promise<boolean>((resolve) => {
|
|
const cap = setTimeout(() => resolve(false), capMs);
|
|
img
|
|
.decode()
|
|
.then(
|
|
() => resolve(false),
|
|
() => resolve(true),
|
|
)
|
|
.finally(() => clearTimeout(cap));
|
|
});
|
|
const stillBroken = await Promise.all(
|
|
candidates.map(async (url) => {
|
|
const shown = Array.from(document.querySelectorAll("img")).filter(
|
|
(img) => img.currentSrc === url || img.src === url,
|
|
);
|
|
return (await Promise.all(shown.map(fails))).some(Boolean);
|
|
}),
|
|
);
|
|
return candidates.filter((_, i) => stillBroken[i]);
|
|
},
|
|
urls,
|
|
IMAGE_DECODE_CAP_MS,
|
|
);
|
|
return new Set(broken);
|
|
}
|
|
|
|
function wireNetworkListeners(page: Page, drafts: RuntimeDraft[], clock: RuntimeClock): void {
|
|
page.on("requestfailed", (request) => {
|
|
const url = request.url();
|
|
if (url.includes("favicon") || url.startsWith("data:")) return;
|
|
const failure = request.failure()?.errorText;
|
|
if (shouldIgnoreRequestFailure(url, failure, request.resourceType())) return;
|
|
drafts.push({
|
|
code: "request_failed",
|
|
severity: "error",
|
|
message: `Failed to load ${urlPath(url)}: ${failure ?? "net::ERR_FAILED"}`,
|
|
...clock.now(),
|
|
url,
|
|
abortedImage: failure === "net::ERR_ABORTED" && request.resourceType() === "image",
|
|
networkChanged: failure === "net::ERR_NETWORK_CHANGED",
|
|
});
|
|
});
|
|
page.on("response", (response) => {
|
|
if (response.status() < 400) return;
|
|
const url = response.url();
|
|
if (url.includes("favicon")) return;
|
|
if (shouldIgnoreHttpError(url, response.status())) return;
|
|
drafts.push({
|
|
code: "http_error",
|
|
severity: "error",
|
|
message: `${response.status()} loading ${urlPath(url)}`,
|
|
...clock.now(),
|
|
url,
|
|
});
|
|
});
|
|
}
|
|
|
|
function failWhenPageDies(page: Page, driver: CheckAuditDriver): CheckAuditDriver {
|
|
const dead = new Promise<never>((_, reject) => {
|
|
page.on("error", (error) =>
|
|
reject(new Error(`The page crashed: ${normalizeErrorMessage(error)}`)),
|
|
);
|
|
page.on("close", () => reject(new Error("The page closed before the check finished")));
|
|
});
|
|
dead.catch(() => undefined);
|
|
return Object.fromEntries(
|
|
Object.entries(driver).map(([name, member]) => [
|
|
name,
|
|
typeof member === "function"
|
|
? (...args: unknown[]) => {
|
|
const result: unknown = Reflect.apply(member, driver, args);
|
|
return result instanceof Promise ? Promise.race([result, dead]) : result;
|
|
}
|
|
: member,
|
|
]),
|
|
) as unknown as CheckAuditDriver;
|
|
}
|
|
|
|
export function createPageDriver(
|
|
page: Page,
|
|
clock: RuntimeClock = createRuntimeClock(),
|
|
sampleLog?: SampleWindow,
|
|
projectDir?: string,
|
|
): CheckAuditDriver {
|
|
return failWhenPageDies(page, {
|
|
initialize: (contrast) => injectAuditScripts(page, contrast),
|
|
markSamples: (phase) => {
|
|
if (!sampleLog) return;
|
|
if (phase === "drop") sampleLog.start = sampleLog.end = Number.POSITIVE_INFINITY;
|
|
else sampleLog[phase] = sampleLog.drafts.length;
|
|
},
|
|
matchComponents: (components, findings) =>
|
|
page.evaluate(matchComponentFindings, { components, findings }),
|
|
getDuration: () => getCompositionDuration(page),
|
|
hasNoTimelineDeclaration: () => hasNoTimelineDeclaration(page),
|
|
getTransitionBoundaries: () => collectTweenBoundaries(page),
|
|
getClipEdges: () => collectClipEdges(page),
|
|
getCanvas: () =>
|
|
page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight })),
|
|
findAmbiguousSelectors: (selectors) => findAmbiguousSelectors(page, selectors),
|
|
seek: async (time, screenshotFollows) => {
|
|
clock.at(time);
|
|
await seekCompositionTimeline(
|
|
page,
|
|
time,
|
|
screenshotFollows ? SCREENSHOT_SEEK_OPTIONS : AUDIT_SEEK_OPTIONS,
|
|
);
|
|
},
|
|
seekGeometry: async (time, { draws = false } = {}) => {
|
|
clock.at(time);
|
|
const options = draws
|
|
? { ...DENSE_GEOMETRY_SEEK_OPTIONS, skipWebglDraws: false }
|
|
: DENSE_GEOMETRY_SEEK_OPTIONS;
|
|
await seekCompositionTimeline(page, time, options);
|
|
},
|
|
collectLayout: (time, tolerance, layout) => collectLayout(page, time, tolerance, layout),
|
|
collectOverlap: (time) => collectOverlap(page, time),
|
|
collectOverlapGrid: async (times) => {
|
|
const issues = await collectOverlapGrid(page, times);
|
|
// What a grid sample queued for later lands after the grid, so it gets the grid's span, not its last time.
|
|
if (times.length > 0) clock.during([times[0] ?? 0, times.at(-1) ?? 0]);
|
|
return issues;
|
|
},
|
|
collectLayoutGeometry: () => collectLayoutGeometry(page),
|
|
captureFrame: (scope) => captureFrame(page, scope),
|
|
framesDiffer: (first, second) =>
|
|
page
|
|
.evaluate(
|
|
(a, b) => Reflect.apply(Reflect.get(window, "__hyperframesFramesDiffer"), window, [a, b]),
|
|
first,
|
|
second,
|
|
)
|
|
.then((differ) => differ === true),
|
|
collectSeekClock: () => collectSeekClock(page),
|
|
collectRotationSample: (time) => collectRotationSample(page, time),
|
|
collectOffPivotRotationSample: (time) => collectOffPivotRotationSample(page, time),
|
|
...(projectDir === undefined
|
|
? {}
|
|
: { collectTextOverVideo: (time) => collectTextOverVideo(page, time, projectDir) }),
|
|
collectGeometryCandidates: (time, request) => collectGeometryCandidates(page, time, request),
|
|
collectMotionFrame: (time, selectors, scopes) =>
|
|
collectMotionFrame(page, time, selectors, scopes),
|
|
anchorMotionIssues: (issues) => anchorLayoutIssues(page, issues),
|
|
collectContrast: (time, annotations, skipInMotion) =>
|
|
collectContrast(page, time, annotations, skipInMotion),
|
|
collectCraftFrame: (time) => collectCraftFrame(page, time),
|
|
collectCraftFilm: () => collectCraftFilm(page),
|
|
});
|
|
}
|
|
|
|
async function collectCraftFrame(page: Page, time: number): Promise<CraftFrame> {
|
|
const raw = await page.evaluate((withCover: boolean) => {
|
|
const sample = Reflect.get(window, "__hyperframesCraftSample");
|
|
return typeof sample === "function" ? Reflect.apply(sample, window, [{ withCover }]) : null;
|
|
}, time <= 1e-3);
|
|
const record = isRecord(raw) ? raw : {};
|
|
const parts = Reflect.get(record, "parts");
|
|
const coveredBy = stringValue(record, "coveredBy");
|
|
return {
|
|
time,
|
|
parts: Array.isArray(parts) ? parts.flatMap(parseCraftTextPart) : [],
|
|
held: booleanValue(record, "held") ?? false,
|
|
painted: booleanValue(record, "painted") ?? true,
|
|
...(coveredBy ? { coveredBy } : {}),
|
|
signature: stringValue(record, "signature") ?? "",
|
|
};
|
|
}
|
|
|
|
async function collectCraftFilm(page: Page): Promise<CraftFilm> {
|
|
const raw = await page.evaluate(() => {
|
|
const film = Reflect.get(window, "__hyperframesCraftFilm");
|
|
return typeof film === "function" ? Reflect.apply(film, window, []) : null;
|
|
});
|
|
return { soundSources: (isRecord(raw) ? numberValue(raw, "soundSources") : null) ?? 0 };
|
|
}
|
|
|
|
const CRAFT_PART_NUMBERS = ["key", "block", "opacity", "fontPx"] as const;
|
|
const CRAFT_PART_STRINGS = [
|
|
"selector",
|
|
"blockSelector",
|
|
"sourceFile",
|
|
"text",
|
|
"blockText",
|
|
] as const;
|
|
const CRAFT_RECT_NUMBERS = ["left", "top", "width", "height"] as const;
|
|
|
|
function parseCraftTextPart(value: unknown): CraftTextPart[] {
|
|
if (!isRecord(value)) return [];
|
|
const nums = requiredNumbers(value, CRAFT_PART_NUMBERS);
|
|
const strings = requiredStrings(value, CRAFT_PART_STRINGS);
|
|
const rect = recordField(value, "rect");
|
|
const box = rect ? requiredNumbers(rect, CRAFT_RECT_NUMBERS) : null;
|
|
const captions = booleanValue(value, "captions");
|
|
return nums && strings && box && captions !== null
|
|
? [{ ...nums, ...strings, rect: box, captions }]
|
|
: [];
|
|
}
|
|
|
|
function requiredStrings<K extends string>(
|
|
value: Record<string, unknown>,
|
|
keys: readonly K[],
|
|
): { [P in K]: string } | null {
|
|
const out = {} as { [P in K]: string };
|
|
for (const key of keys) {
|
|
const entry = stringValue(value, key);
|
|
if (entry === null) return null;
|
|
out[key] = entry;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
async function hasNoTimelineDeclaration(page: Page): Promise<boolean> {
|
|
return page.evaluate(
|
|
() =>
|
|
document.querySelector("[data-composition-id]")?.hasAttribute("data-no-timeline") ?? false,
|
|
);
|
|
}
|
|
|
|
async function injectAuditScripts(page: Page, contrast: boolean): Promise<void> {
|
|
await page.addScriptTag({ content: loadBrowserScript("motion-signature.browser.js") });
|
|
await page.addScriptTag({ content: loadBrowserScript("layout-audit.browser.js") });
|
|
await page.addScriptTag({ content: loadBrowserScript("motion-sample.browser.js") });
|
|
if (contrast) {
|
|
await page.addScriptTag({ content: loadBrowserScript("contrast-audit.browser.js") });
|
|
}
|
|
}
|
|
|
|
async function getCompositionDuration(page: Page): Promise<number> {
|
|
// Duration resolution is serialized into the page and must remain self-contained.
|
|
// fallow-ignore-next-line complexity
|
|
return page.evaluate(() => {
|
|
const value = (target: unknown, key: string): unknown =>
|
|
typeof target === "object" && target !== null ? Reflect.get(target, key) : undefined;
|
|
const positive = (candidate: unknown): number | null =>
|
|
typeof candidate === "number" && candidate > 0 ? candidate : null;
|
|
const callDuration = (target: unknown): number | null => {
|
|
const duration = value(target, "duration");
|
|
if (typeof duration === "function") {
|
|
const result = Reflect.apply(duration, target, []);
|
|
return positive(result);
|
|
}
|
|
return positive(duration);
|
|
};
|
|
const hfDuration = positive(value(Reflect.get(window, "__hf"), "duration"));
|
|
if (hfDuration) return hfDuration;
|
|
const playerDuration = callDuration(Reflect.get(window, "__player"));
|
|
if (playerDuration) return playerDuration;
|
|
const root = document.querySelector("[data-composition-id][data-duration]");
|
|
const authored = root ? parseFloat(root.getAttribute("data-duration") ?? "0") : 0;
|
|
if (authored > 0) return authored;
|
|
const timelines = Reflect.get(window, "__timelines");
|
|
if (typeof timelines !== "object" || timelines === null) return 0;
|
|
for (const key of Object.keys(timelines)) {
|
|
const duration = callDuration(Reflect.get(timelines, key));
|
|
if (duration) return duration;
|
|
}
|
|
return 0;
|
|
});
|
|
}
|
|
|
|
async function collectClipEdges(page: Page): Promise<number[]> {
|
|
return page.evaluate(() => {
|
|
type Clip = { kind: string; start: number; duration: number };
|
|
const manifest = Reflect.get(window, "__clipManifest") as { clips?: Clip[] } | undefined;
|
|
return (manifest?.clips ?? [])
|
|
.filter((clip) => clip.kind !== "audio")
|
|
.flatMap((clip) => [clip.start, clip.start + clip.duration]);
|
|
});
|
|
}
|
|
|
|
async function collectTweenBoundaries(page: Page): Promise<number[]> {
|
|
// GSAP getter binding and parent-time conversion form one serialized algorithm.
|
|
// fallow-ignore-next-line complexity
|
|
return page.evaluate(() => {
|
|
const property = (target: unknown, key: string): unknown =>
|
|
(typeof target === "object" && target !== null) || typeof target === "function"
|
|
? Reflect.get(target, key)
|
|
: undefined;
|
|
const numberCall = (target: unknown, key: string, fallback: number): number => {
|
|
const method = property(target, key);
|
|
if (typeof method !== "function") return fallback;
|
|
const result = Reflect.apply(method, target, []);
|
|
return typeof result === "number" ? result : fallback;
|
|
};
|
|
const rootTime = (root: unknown, animation: unknown, local: number): number => {
|
|
let time = local;
|
|
let node = animation;
|
|
while (node && node !== root) {
|
|
time = numberCall(node, "startTime", 0) + time / (numberCall(node, "timeScale", 1) || 1);
|
|
node = property(node, "parent");
|
|
}
|
|
return time;
|
|
};
|
|
const timelines = Reflect.get(window, "__timelines");
|
|
if (typeof timelines !== "object" || timelines === null) return [];
|
|
const boundaries: number[] = [];
|
|
for (const key of Object.keys(timelines)) {
|
|
const timeline = Reflect.get(timelines, key);
|
|
const getChildren = property(timeline, "getChildren");
|
|
if (typeof getChildren !== "function") continue;
|
|
try {
|
|
const children = Reflect.apply(getChildren, timeline, [true, true, false]);
|
|
if (!Array.isArray(children)) continue;
|
|
for (const child of children) {
|
|
const duration = numberCall(child, "duration", Number.NaN);
|
|
if (!Number.isFinite(duration)) continue;
|
|
boundaries.push(rootTime(timeline, child, 0), rootTime(timeline, child, duration));
|
|
}
|
|
} catch {
|
|
continue;
|
|
}
|
|
}
|
|
return boundaries.filter(Number.isFinite);
|
|
});
|
|
}
|
|
|
|
async function collectLayout(
|
|
page: Page,
|
|
time: number,
|
|
tolerance: number,
|
|
layout?: LayoutOptions,
|
|
): Promise<AnchoredLayoutIssue[]> {
|
|
const raw = await page.evaluate(
|
|
(options: { time: number; tolerance: number; proseCoverageFloor?: number }) => {
|
|
const audit = Reflect.get(window, "__hyperframesLayoutAudit");
|
|
if (typeof audit !== "function") return [];
|
|
const result = Reflect.apply(audit, window, [options]);
|
|
return Array.isArray(result) ? result : [];
|
|
},
|
|
{
|
|
time,
|
|
tolerance,
|
|
...(typeof layout?.proseCoverageFloor === "number"
|
|
? { proseCoverageFloor: layout.proseCoverageFloor }
|
|
: {}),
|
|
},
|
|
);
|
|
return anchorLayoutIssues(page, raw.flatMap(parseLayoutIssue));
|
|
}
|
|
|
|
async function collectOverlap(page: Page, time: number): Promise<AnchoredLayoutIssue[]> {
|
|
const raw = await page.evaluate(
|
|
(options: { time: number }) => {
|
|
const audit = Reflect.get(window, "__hyperframesOverlapAudit");
|
|
if (typeof audit !== "function") return [];
|
|
const result = Reflect.apply(audit, window, [options]);
|
|
return Array.isArray(result) ? result : [];
|
|
},
|
|
{ time },
|
|
);
|
|
return anchorLayoutIssues(page, raw.flatMap(parseLayoutIssue));
|
|
}
|
|
|
|
const SAMPLE_TIME_MARKER = "__hfCheckSample ";
|
|
|
|
function followSampleTimeMarkers(page: Page, setTime: (time: number) => void): void {
|
|
page.on("console", (message) => {
|
|
const text = message.text();
|
|
if (message.type() === "debug" && text.startsWith(SAMPLE_TIME_MARKER)) {
|
|
setTime(Number(text.slice(SAMPLE_TIME_MARKER.length)));
|
|
}
|
|
});
|
|
}
|
|
|
|
interface OverlapGridSample {
|
|
raw: unknown[];
|
|
anchors: CheckAnchor[];
|
|
}
|
|
|
|
// Never yields to the renderer between samples, so it paints no frame for them.
|
|
async function overlapGridInPage(
|
|
grid: {
|
|
times: number[];
|
|
marker: string;
|
|
fallback: boolean;
|
|
skipDraws: boolean;
|
|
videoFrames: boolean;
|
|
timeoutMs: number;
|
|
},
|
|
seek: typeof seekInPage,
|
|
anchors: typeof anchorsInPage,
|
|
): Promise<OverlapGridSample[]> {
|
|
const audit = Reflect.get(window, "__hyperframesOverlapAudit");
|
|
const waitForCompletion = Reflect.get(window, "__hfWaitForSeekCompletion");
|
|
const samples: OverlapGridSample[] = [];
|
|
const deadline = performance.now() + grid.timeoutMs;
|
|
for (const time of grid.times) {
|
|
console.debug(`${grid.marker}${time}`);
|
|
seek(time, grid.fallback, false, grid.skipDraws);
|
|
if (typeof waitForCompletion === "function") {
|
|
const timeoutMs = Math.max(0, deadline - performance.now());
|
|
await Reflect.apply(waitForCompletion, window, [
|
|
{ videoFrames: grid.videoFrames, timeoutMs },
|
|
]);
|
|
}
|
|
const result: unknown =
|
|
typeof audit === "function" ? Reflect.apply(audit, window, [{ time }]) : [];
|
|
const raw = Array.isArray(result) ? result : [];
|
|
const zero = { x: 0, y: 0, width: 0, height: 0 };
|
|
const requests = raw.map((issue) => ({
|
|
selector: String(Reflect.get(Object(issue), "selector")),
|
|
time,
|
|
bbox: zero,
|
|
}));
|
|
samples.push({ raw, anchors: anchors(requests) });
|
|
}
|
|
return samples;
|
|
}
|
|
|
|
async function collectOverlapGrid(page: Page, times: number[]): Promise<AnchoredLayoutIssue[][]> {
|
|
if (times.length === 0) return [];
|
|
const grid = {
|
|
times,
|
|
marker: SAMPLE_TIME_MARKER,
|
|
fallback: DENSE_GEOMETRY_SEEK_OPTIONS.fallbackToBridgeAndTimelines,
|
|
skipDraws: DENSE_GEOMETRY_SEEK_OPTIONS.skipWebglDraws,
|
|
videoFrames: DENSE_GEOMETRY_SEEK_OPTIONS.waitForVideoFrames,
|
|
timeoutMs: SEEK_SETTLES_BEFORE_PROTOCOL_TIMEOUT_MS,
|
|
};
|
|
const samples = (await page.evaluate(
|
|
`(${overlapGridInPage})(${JSON.stringify(grid)}, ${seekInPage}, ${anchorsInPage})`,
|
|
)) as OverlapGridSample[];
|
|
return samples.map(({ raw, anchors }) =>
|
|
raw.flatMap((value, index) =>
|
|
parseLayoutIssue(value).map((issue) => ({
|
|
...issue,
|
|
...(anchors[index] ?? fallbackAnchor(undefined)),
|
|
bbox: rectToBbox(issue.rect),
|
|
time: issue.time,
|
|
})),
|
|
),
|
|
);
|
|
}
|
|
|
|
async function captureFrame(page: Page, scope?: string): Promise<string> {
|
|
if (!scope) return page.screenshot({ encoding: "base64", type: "png" });
|
|
try {
|
|
const box = await page.evaluate(isolateScopePaint, scope);
|
|
if (!box || box.width < 1 || box.height < 1) return "";
|
|
return await page.screenshot({
|
|
encoding: "base64",
|
|
type: "png",
|
|
clip: box,
|
|
omitBackground: true,
|
|
});
|
|
} finally {
|
|
await page.evaluate(restoreScopePaint);
|
|
}
|
|
}
|
|
|
|
// Liveness signs only the scope's subtree, so its frame must show only that paint: anything else behind or
|
|
// over the box (a moving background, grain, the page canvas) would read as the scope moving; the canvas stays clear.
|
|
function isolateScopePaint(
|
|
scope: string,
|
|
): { x: number; y: number; width: number; height: number } | null {
|
|
let target: Element | null = null;
|
|
try {
|
|
target = document.querySelector(scope);
|
|
} catch {
|
|
return null;
|
|
}
|
|
if (!target) return null;
|
|
const visibility = getComputedStyle(target).visibility;
|
|
target.setAttribute("data-hf-capture-scope", "");
|
|
const style = document.createElement("style");
|
|
style.id = "__hf_capture_scope_style";
|
|
style.textContent = `:not([data-hf-capture-scope], [data-hf-capture-scope] *) { visibility: hidden !important; }
|
|
:root:not([data-hf-capture-scope]), body:not([data-hf-capture-scope]) { background: none !important; }
|
|
[data-hf-capture-scope] { visibility: ${visibility} !important; }`;
|
|
document.head.append(style);
|
|
const rect = target.getBoundingClientRect();
|
|
return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
|
|
}
|
|
|
|
function restoreScopePaint(): void {
|
|
document.getElementById("__hf_capture_scope_style")?.remove();
|
|
document.querySelector("[data-hf-capture-scope]")?.removeAttribute("data-hf-capture-scope");
|
|
}
|
|
|
|
async function collectLayoutGeometry(page: Page): Promise<string> {
|
|
return page.evaluate(() => {
|
|
const geometry = Reflect.get(window, "__hyperframesLayoutGeometry");
|
|
if (typeof geometry !== "function") return "";
|
|
const result = Reflect.apply(geometry, window, []);
|
|
return typeof result === "string" ? result : "";
|
|
});
|
|
}
|
|
|
|
export async function collectSeekClock(page: Page): Promise<SeekClock[]> {
|
|
// Serialized into the page; each optional GSAP read is one branch of one function.
|
|
// fallow-ignore-next-line complexity
|
|
return page.evaluate(() => {
|
|
const callOrUndefined = (target: unknown, key: string, args: unknown[] = []): unknown => {
|
|
try {
|
|
return Reflect.apply(Reflect.get(Object(target), key), target, args);
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
};
|
|
const known: { ids: WeakMap<object, number>; next: number } = Reflect.get(
|
|
window,
|
|
"__hfSeekClocks",
|
|
) ?? {
|
|
ids: new WeakMap(),
|
|
next: 0,
|
|
};
|
|
Reflect.set(window, "__hfSeekClocks", known);
|
|
const idOf = (target: object): number => {
|
|
if (!known.ids.has(target)) known.ids.set(target, ++known.next);
|
|
return known.ids.get(target) ?? 0;
|
|
};
|
|
const clocks: SeekClock[] = [];
|
|
const timelines: unknown = Reflect.get(window, "__timelines");
|
|
const registered = typeof timelines === "object" && timelines ? Object.values(timelines) : [];
|
|
const gsapRoot = Reflect.get(Reflect.get(window, "gsap") ?? {}, "globalTimeline");
|
|
const children = callOrUndefined(gsapRoot, "getChildren", [false, true, true]);
|
|
for (const timeline of [...registered, ...(Array.isArray(children) ? children : [])]) {
|
|
const total = Number(
|
|
callOrUndefined(timeline, "totalDuration") ?? callOrUndefined(timeline, "duration"),
|
|
);
|
|
if (typeof timeline !== "object" || !timeline || !(total > 0)) continue;
|
|
const time = callOrUndefined(timeline, "totalTime") ?? callOrUndefined(timeline, "time");
|
|
if (typeof time !== "number" || !Number.isFinite(time)) continue;
|
|
const progress = Number(callOrUndefined(timeline, "totalProgress") ?? time / total);
|
|
const done = callOrUndefined(timeline, "reversed") === true ? progress <= 0 : progress >= 1;
|
|
clocks.push({ id: idOf(timeline), time, done });
|
|
}
|
|
for (const animation of document.getAnimations?.() ?? []) {
|
|
if (typeof animation.currentTime !== "number") continue;
|
|
const time = animation.currentTime;
|
|
const end = Number(animation.effect?.getComputedTiming().endTime ?? Number.POSITIVE_INFINITY);
|
|
const atEnd = animation.playbackRate < 0 ? time <= 0 : time >= end;
|
|
clocks.push({ id: idOf(animation), time, done: animation.playState === "finished" || atEnd });
|
|
}
|
|
return clocks;
|
|
});
|
|
}
|
|
|
|
/** Invoke a `window.__hyperframes*` sampler injected by layout-audit.browser.js
|
|
* and return its array result (or [] when absent / non-array). Shared by the
|
|
* per-frame sample collectors so the page.evaluate boilerplate lives once. */
|
|
async function evaluateSampler(page: Page, globalName: string): Promise<unknown[]> {
|
|
return page.evaluate((name) => {
|
|
const sample = Reflect.get(window, name);
|
|
if (typeof sample !== "function") return [];
|
|
const result = Reflect.apply(sample, window, []);
|
|
return Array.isArray(result) ? result : [];
|
|
}, globalName);
|
|
}
|
|
|
|
async function collectRotationSample(page: Page, time: number): Promise<RotationSample[]> {
|
|
const raw = await evaluateSampler(page, "__hyperframesRotationSample");
|
|
return raw.flatMap((value) => parseRotationSample(value, time));
|
|
}
|
|
|
|
function parseRotationSample(value: unknown, time: number): RotationSample[] {
|
|
if (!isRecord(value)) return [];
|
|
const selector = stringValue(value, "selector");
|
|
const cx = numberValue(value, "cx");
|
|
const cy = numberValue(value, "cy");
|
|
const w = numberValue(value, "w");
|
|
const h = numberValue(value, "h");
|
|
const angle = numberValue(value, "angle");
|
|
if (!selector || cx === null || cy === null || w === null || h === null || angle === null) {
|
|
return [];
|
|
}
|
|
return [{ time, selector, cx, cy, w, h, angle }];
|
|
}
|
|
|
|
async function collectTextOverVideo(
|
|
page: Page,
|
|
time: number,
|
|
projectDir: string,
|
|
): Promise<TextOverVideoCandidate[]> {
|
|
const raw = await page.evaluate(
|
|
(options: { time: number }) => {
|
|
const collect = Reflect.get(window, "__hyperframesTextOverVideo");
|
|
if (typeof collect !== "function") return [];
|
|
const result = Reflect.apply(collect, window, [options]);
|
|
return Array.isArray(result) ? result : [];
|
|
},
|
|
{ time },
|
|
);
|
|
return raw.flatMap((value) => parseTextOverVideo(value, time, page.url(), projectDir));
|
|
}
|
|
|
|
/** The project file a page-origin URL is served from; null for a remote source or a path outside the project. */
|
|
export function servedProjectFile(src: string, pageUrl: string, projectDir: string): string | null {
|
|
const url = parseUrl(src);
|
|
const path = decodedPath(url);
|
|
if (!url || !path || url.origin !== parseUrl(pageUrl)?.origin) return null;
|
|
const file = resolve(projectDir, `.${path}`);
|
|
const inside = relative(projectDir, file);
|
|
if (!inside || inside.startsWith("..") || isAbsolute(inside)) return null;
|
|
return existsSync(file) ? file : null;
|
|
}
|
|
|
|
function parsePlacedVideo(
|
|
value: Record<string, unknown> | null,
|
|
pageUrl: string,
|
|
projectDir: string,
|
|
): TextOverVideoCandidate["video"] | null {
|
|
if (!value) return null;
|
|
const selector = stringValue(value, "selector");
|
|
const file = servedProjectFile(stringValue(value, "src") ?? "", pageUrl, projectDir);
|
|
const mediaTime = numberValue(value, "mediaTime");
|
|
const box = parseBbox(Reflect.get(value, "box"));
|
|
const frame = parseBbox(Reflect.get(value, "frame"));
|
|
if (!selector || !file || mediaTime === null || !box || !frame) return null;
|
|
return {
|
|
selector,
|
|
file,
|
|
mediaTime,
|
|
box,
|
|
frame,
|
|
flipX: booleanValue(value, "flipX") === true,
|
|
flipY: booleanValue(value, "flipY") === true,
|
|
};
|
|
}
|
|
|
|
function parseTextOverVideo(
|
|
value: unknown,
|
|
time: number,
|
|
pageUrl: string,
|
|
projectDir: string,
|
|
): TextOverVideoCandidate[] {
|
|
if (!isRecord(value)) return [];
|
|
const rect = parseRect(Reflect.get(value, "rect"));
|
|
const anchor = rect ? parseGeometryAnchor(value, rect, time) : null;
|
|
const video = parsePlacedVideo(recordField(value, "video"), pageUrl, projectDir);
|
|
const rawWords: unknown = Reflect.get(value, "wordRects");
|
|
const wordRects = Array.isArray(rawWords)
|
|
? rawWords.flatMap((word) => parseBbox(word) ?? [])
|
|
: [];
|
|
if (!rect || !anchor || !video || wordRects.length === 0) return [];
|
|
return [{ ...anchor, text: stringValue(value, "text") ?? "", rect, wordRects, video }];
|
|
}
|
|
|
|
async function collectOffPivotRotationSample(page: Page, time: number): Promise<OffPivotFrame> {
|
|
const raw = await evaluateSampler(page, "__hyperframesOffPivotRotationSample");
|
|
return { time, samples: raw.flatMap(parseOffPivotRotationSample) };
|
|
}
|
|
|
|
/** Read every named key as a finite number; null if ANY is missing/non-finite.
|
|
* The mapped return type keeps each field a plain `number` (not `number |
|
|
* undefined`) so callers read `nums.ax` without re-narrowing. */
|
|
function requiredNumbers<K extends string>(
|
|
value: Record<string, unknown>,
|
|
keys: readonly K[],
|
|
): { [P in K]: number } | null {
|
|
const out = {} as { [P in K]: number };
|
|
for (const key of keys) {
|
|
const num = numberValue(value, key);
|
|
if (num === null) return null;
|
|
out[key] = num;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
const OFF_PIVOT_REQUIRED_NUMBERS = ["ax", "ay", "bx", "by", "len", "angle", "hubCount"] as const;
|
|
|
|
function parseOffPivotRotationSample(value: unknown): OffPivotRotationSample[] {
|
|
if (!isRecord(value)) return [];
|
|
const selector = stringValue(value, "selector");
|
|
const nums = requiredNumbers(value, OFF_PIVOT_REQUIRED_NUMBERS);
|
|
if (!selector || !nums) return [];
|
|
return [
|
|
{
|
|
selector,
|
|
ax: nums.ax,
|
|
ay: nums.ay,
|
|
bx: nums.bx,
|
|
by: nums.by,
|
|
len: nums.len,
|
|
angle: nums.angle,
|
|
hx: numberValue(value, "hx"),
|
|
hy: numberValue(value, "hy"),
|
|
hr: numberValue(value, "hr"),
|
|
hubCount: nums.hubCount,
|
|
},
|
|
];
|
|
}
|
|
|
|
async function collectGeometryCandidates(
|
|
page: Page,
|
|
time: number,
|
|
request: GeometryCandidateRequest,
|
|
): Promise<CheckGeometryCandidate[]> {
|
|
try {
|
|
const raw = await page.evaluate((options: GeometryCandidateRequest) => {
|
|
const collect = Reflect.get(window, "__hyperframesGeometryCandidates");
|
|
if (typeof collect !== "function") return [];
|
|
const result = Reflect.apply(collect, window, [options]);
|
|
return Array.isArray(result) ? result : [];
|
|
}, request);
|
|
return raw.flatMap((value) => parseGeometryCandidate(value, time));
|
|
} catch {
|
|
return [];
|
|
}
|
|
}
|
|
|
|
async function findAmbiguousSelectors(
|
|
page: Page,
|
|
selectors: string[],
|
|
): Promise<AnchoredLayoutIssue[]> {
|
|
const ambiguous = await page.evaluate(
|
|
(values: string[]) =>
|
|
values.filter((selector) => {
|
|
try {
|
|
return document.querySelectorAll(selector).length > 1;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}),
|
|
selectors,
|
|
);
|
|
return anchorLayoutIssues(page, ambiguous.map(ambiguousIssue));
|
|
}
|
|
|
|
async function collectMotionFrame(
|
|
page: Page,
|
|
time: number,
|
|
selectors: string[],
|
|
livenessScopes: string[],
|
|
): Promise<MotionFrame> {
|
|
const raw = await page.evaluate(
|
|
(options: { selectors: string[]; livenessScopes: string[] }) => {
|
|
const sample = Reflect.get(window, "__hyperframesMotionSample");
|
|
if (typeof sample !== "function") return null;
|
|
return Reflect.apply(sample, window, [options]);
|
|
},
|
|
{ selectors, livenessScopes },
|
|
);
|
|
return parseMotionFrame(raw, time, selectors, livenessScopes);
|
|
}
|
|
|
|
async function anchorLayoutIssues(
|
|
page: Page,
|
|
issues: LayoutIssue[],
|
|
): Promise<AnchoredLayoutIssue[]> {
|
|
const requests = issues.map((issue) => ({
|
|
selector: issue.selector,
|
|
time: issue.time,
|
|
bbox: rectToBbox(issue.rect),
|
|
}));
|
|
const anchors = await resolveAnchors(page, requests);
|
|
return issues.map((issue, index) => ({
|
|
...issue,
|
|
...(anchors[index] ?? fallbackAnchor(requests[index])),
|
|
}));
|
|
}
|
|
|
|
async function resolveAnchors(page: Page, requests: AnchorRequest[]): Promise<CheckAnchor[]> {
|
|
if (requests.length === 0) return [];
|
|
return page.evaluate(anchorsInPage, requests);
|
|
}
|
|
|
|
function anchorsInPage(values: AnchorRequest[]): CheckAnchor[] {
|
|
const root = document.querySelector("[data-composition-id]");
|
|
return values.map((request) => {
|
|
let element: Element | null = null;
|
|
try {
|
|
element = document.querySelector(request.selector);
|
|
} catch {
|
|
element = null;
|
|
}
|
|
element ??= root;
|
|
// Clones the anchor-extraction block in prepareContrast's evaluate() below;
|
|
// both run inside separate serialized browser closures and can't share a
|
|
// Node-side helper.
|
|
// fallow-ignore-next-line code-duplication
|
|
const dataAttributes: Record<string, string> = {};
|
|
for (const attribute of Array.from(element?.attributes ?? [])) {
|
|
if (attribute.name.startsWith("data-")) dataAttributes[attribute.name] = attribute.value;
|
|
}
|
|
const source = element
|
|
?.closest("[data-composition-file]")
|
|
?.getAttribute("data-composition-file");
|
|
return {
|
|
selector: element ? request.selector : "[data-composition-id]",
|
|
dataAttributes,
|
|
sourceFile: source || "index.html",
|
|
bbox: request.bbox,
|
|
time: request.time,
|
|
};
|
|
});
|
|
}
|
|
|
|
async function resolveRootAnchor(page: Page): Promise<CheckAnchor> {
|
|
const selector = await page.evaluate(
|
|
(explicit) => (document.querySelector(explicit) ? explicit : "[data-composition-id]"),
|
|
'[data-composition-id][data-root="true"]',
|
|
);
|
|
const anchors = await resolveAnchors(page, [
|
|
{ selector, time: 0, bbox: await compositionBbox(page, selector) },
|
|
]);
|
|
return anchors[0] ?? fallbackAnchor(undefined);
|
|
}
|
|
|
|
async function compositionBbox(page: Page, selector: string): Promise<CheckBbox> {
|
|
return page.evaluate((root) => {
|
|
const rect = document.querySelector(root)?.getBoundingClientRect();
|
|
return rect
|
|
? { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
|
|
: { x: 0, y: 0, width: 0, height: 0 };
|
|
}, selector);
|
|
}
|
|
|
|
async function collectContrast(
|
|
page: Page,
|
|
time: number,
|
|
snapshotAnnotations?: CheckAnnotationBox[],
|
|
skipInMotion = false,
|
|
): Promise<ContrastCapture> {
|
|
let prepared: PreparedContrast[] = [];
|
|
try {
|
|
const candidates = await prepareContrast(page, time);
|
|
const motion = skipInMotion ? await page.evaluate(readContrastMotion).catch(() => []) : [];
|
|
prepared = parsePreparedContrast(candidates, motion);
|
|
if (prepared.length === 0 && !snapshotAnnotations) return { entries: [] };
|
|
// This screenshot is the one contrast math is sampled from below — it must
|
|
// stay untouched by the annotation overlay (finishContrast reads real
|
|
// painted pixels), so annotation only ever happens on a SECOND shot.
|
|
const { shot, region } = await measurementShot(page, prepared);
|
|
const raw = await finishContrast(
|
|
page,
|
|
shot,
|
|
time,
|
|
prepared.map((entry) => entry.raw),
|
|
region,
|
|
);
|
|
const finished = raw.flatMap(parseFinishedContrast);
|
|
const entries = joinContrastEntries(finished, prepared);
|
|
if (!snapshotAnnotations) return { entries };
|
|
// __contrastAuditFinish restores the text paint hidden by prepare. The
|
|
// measurement screenshot intentionally has glyphs removed so contrast
|
|
// can sample the pixels behind them; never persist that image as visual
|
|
// QA evidence. Capture the restored page for the overview instead.
|
|
const overviewShot = await page.screenshot({ encoding: "base64", type: "png" });
|
|
if (typeof overviewShot !== "string") throw new Error("Overview screenshot was not base64");
|
|
// Contrast failures are only known once measurement above completes, so
|
|
// they're appended to the layout-derived annotations passed in by the
|
|
// pipeline rather than being requested up front.
|
|
const annotations = [
|
|
...snapshotAnnotations,
|
|
...contrastFailureAnnotations(entries, snapshotAnnotations.length),
|
|
];
|
|
const pngBase64 = await captureOverviewShot(page, annotations, overviewShot);
|
|
return { entries, pngBase64 };
|
|
} finally {
|
|
await page
|
|
.evaluate(() => {
|
|
const restore = Reflect.get(window, "__contrastAuditRestoreIfPending");
|
|
if (typeof restore === "function") Reflect.apply(restore, window, []);
|
|
})
|
|
.catch(() => undefined);
|
|
}
|
|
}
|
|
|
|
async function measurementShot(
|
|
page: Page,
|
|
prepared: PreparedContrast[],
|
|
): Promise<{ shot: string | null; region: TextRegion | undefined }> {
|
|
const frame = plainFrame(page.viewport());
|
|
const sampled = prepared.filter((entry) => !entry.knownBackdrop);
|
|
if (frame && sampled.length === 0) {
|
|
const clip = { x: 0, y: 0, ...frame };
|
|
return { shot: null, region: { clip, frameWidth: frame.width, frameHeight: frame.height } };
|
|
}
|
|
const region = textRegion(sampled, frame);
|
|
const shot = await page.screenshot({
|
|
encoding: "base64",
|
|
type: "png",
|
|
omitBackground: true,
|
|
...(region ? { clip: region.clip, captureBeyondViewport: false } : {}),
|
|
});
|
|
if (typeof shot !== "string") throw new Error("Contrast screenshot was not base64");
|
|
return { shot, region };
|
|
}
|
|
|
|
function contrastFailureAnnotations(
|
|
entries: ContrastAuditEntry[],
|
|
labelOffset: number,
|
|
): CheckAnnotationBox[] {
|
|
return entries
|
|
.filter((entry) => !entry.wcagAA)
|
|
.map((entry, index) => ({
|
|
label: `${labelOffset + index + 1} contrast_aa_failure`,
|
|
bbox: entry.bbox,
|
|
}));
|
|
}
|
|
|
|
const ANNOTATION_OVERLAY_ID = "__hyperframesCheckAnnotations";
|
|
|
|
/**
|
|
* `check --snapshots`'s overview-frame annotation: every audit for this
|
|
* sample time has already run (layout/geometry findings arrive via
|
|
* `annotations`; contrast failures were just measured above), so it's safe
|
|
* to draw labeled boxes and take one more shot without perturbing anything
|
|
* audits read. No-op (returns the plain screenshot) when there's nothing to
|
|
* annotate — the common case stays exactly as before this feature existed.
|
|
*/
|
|
export async function captureOverviewShot(
|
|
page: Page,
|
|
annotations: CheckAnnotationBox[],
|
|
fallbackScreenshot: string,
|
|
): Promise<string> {
|
|
if (annotations.length === 0) return fallbackScreenshot;
|
|
await injectAnnotationOverlay(page, annotations);
|
|
try {
|
|
const shot = await page.screenshot({ encoding: "base64", type: "png" });
|
|
return typeof shot === "string" ? shot : fallbackScreenshot;
|
|
} finally {
|
|
await removeAnnotationOverlay(page);
|
|
}
|
|
}
|
|
|
|
/** One small, self-contained DOM overlay: fixed-position labeled boxes over
|
|
* each finding's bbox. Injected immediately before the annotated overview
|
|
* shot and torn down immediately after (see `captureOverviewShot`), so it
|
|
* never leaks into any audit's DOM reads. */
|
|
async function injectAnnotationOverlay(page: Page, boxes: CheckAnnotationBox[]): Promise<void> {
|
|
await page.evaluate(
|
|
(items: CheckAnnotationBox[], overlayId: string) => {
|
|
const root = document.createElement("div");
|
|
root.id = overlayId;
|
|
root.style.cssText = "position:fixed;inset:0;z-index:2147483647;pointer-events:none;";
|
|
for (const item of items) {
|
|
const box = document.createElement("div");
|
|
box.style.cssText = `position:fixed;left:${item.bbox.x}px;top:${item.bbox.y}px;width:${item.bbox.width}px;height:${item.bbox.height}px;border:2px solid #ff2d55;box-sizing:border-box;`;
|
|
const label = document.createElement("div");
|
|
label.textContent = item.label;
|
|
label.style.cssText =
|
|
"position:absolute;top:-18px;left:0;background:#ff2d55;color:#fff;font:11px/16px monospace;padding:0 4px;white-space:nowrap;";
|
|
box.appendChild(label);
|
|
root.appendChild(box);
|
|
}
|
|
document.body.appendChild(root);
|
|
},
|
|
boxes,
|
|
ANNOTATION_OVERLAY_ID,
|
|
);
|
|
}
|
|
|
|
async function removeAnnotationOverlay(page: Page): Promise<void> {
|
|
await page.evaluate((overlayId: string) => {
|
|
document.getElementById(overlayId)?.remove();
|
|
}, ANNOTATION_OVERLAY_ID);
|
|
}
|
|
|
|
async function prepareContrast(page: Page, time: number): Promise<unknown[]> {
|
|
// Candidate-to-element provenance must be captured while the prepare restore list is live.
|
|
// fallow-ignore-next-line complexity
|
|
return page.evaluate((sampleTime: number) => {
|
|
const prepare = Reflect.get(window, "__contrastAuditPrepare");
|
|
const candidates = typeof prepare === "function" ? Reflect.apply(prepare, window, []) : [];
|
|
if (!Array.isArray(candidates)) return [];
|
|
const restores = Reflect.get(window, "__contrastAuditRestores");
|
|
const restoreList = Array.isArray(restores) ? restores : [];
|
|
const escape = (value: string) =>
|
|
typeof CSS !== "undefined" && typeof CSS.escape === "function"
|
|
? CSS.escape(value)
|
|
: value.replace(/[^a-zA-Z0-9_-]/g, "\\$&");
|
|
const selectorFor = (element: Element | null, fallback: string): string => {
|
|
if (!element) return fallback;
|
|
if (element.id) return `#${escape(element.id)}`;
|
|
const parts: string[] = [];
|
|
for (
|
|
let current: Element | null = element;
|
|
current && current !== document.body;
|
|
current = current.parentElement
|
|
) {
|
|
const tag = current.tagName.toLowerCase();
|
|
const siblings = current.parentElement
|
|
? Array.from(current.parentElement.children).filter(
|
|
(item) => item.tagName === current?.tagName,
|
|
)
|
|
: [];
|
|
parts.push(
|
|
siblings.length > 1 ? `${tag}:nth-of-type(${siblings.indexOf(current) + 1})` : tag,
|
|
);
|
|
}
|
|
return parts.reverse().join(" > ") || fallback;
|
|
};
|
|
// Part of the serialized evaluate body above; cannot delegate to Node helpers.
|
|
// fallow-ignore-next-line complexity
|
|
return candidates.map((candidate, index) => {
|
|
const restore = restoreList[index];
|
|
const candidateObject = typeof candidate === "object" && candidate !== null ? candidate : {};
|
|
const elementValue =
|
|
typeof restore === "object" && restore !== null ? Reflect.get(restore, "el") : null;
|
|
const element = elementValue instanceof Element ? elementValue : null;
|
|
const fallback = Reflect.get(candidateObject, "selector");
|
|
const selector = selectorFor(
|
|
element,
|
|
typeof fallback === "string" ? fallback : "[data-composition-id]",
|
|
);
|
|
const dataAttributes: Record<string, string> = {};
|
|
for (const attribute of Array.from(element?.attributes ?? [])) {
|
|
if (attribute.name.startsWith("data-")) dataAttributes[attribute.name] = attribute.value;
|
|
}
|
|
const source = element
|
|
?.closest("[data-composition-file]")
|
|
?.getAttribute("data-composition-file");
|
|
return {
|
|
candidate: { ...candidateObject, selector },
|
|
anchor: {
|
|
selector,
|
|
dataAttributes,
|
|
sourceFile: source || "index.html",
|
|
bbox: Reflect.get(candidateObject, "bbox"),
|
|
time: sampleTime,
|
|
},
|
|
};
|
|
});
|
|
}, time);
|
|
}
|
|
|
|
interface TextRegion {
|
|
clip: { x: number; y: number; width: number; height: number };
|
|
frameWidth: number;
|
|
frameHeight: number;
|
|
}
|
|
|
|
// The smallest whole-pixel rect holding every box contrast samples; undefined means the full frame.
|
|
function plainFrame(
|
|
viewport: { width: number; height: number; deviceScaleFactor?: number } | null,
|
|
): { width: number; height: number } | undefined {
|
|
if (!viewport || (viewport.deviceScaleFactor ?? 1) !== 1) return undefined;
|
|
return { width: viewport.width, height: viewport.height };
|
|
}
|
|
|
|
function textRegion(
|
|
prepared: PreparedContrast[],
|
|
viewport: { width: number; height: number } | undefined,
|
|
): TextRegion | undefined {
|
|
if (!viewport || prepared.length === 0) return undefined;
|
|
const boxes = prepared.map((entry) => entry.candidate.bbox);
|
|
const x = Math.max(0, Math.floor(Math.min(...boxes.map((box) => box.x))));
|
|
const y = Math.max(0, Math.floor(Math.min(...boxes.map((box) => box.y))));
|
|
const right = Math.min(viewport.width, Math.ceil(Math.max(...boxes.map((b) => b.x + b.width))));
|
|
const bottom = Math.min(
|
|
viewport.height,
|
|
Math.ceil(Math.max(...boxes.map((b) => b.y + b.height))),
|
|
);
|
|
if (right <= x || bottom <= y) return undefined;
|
|
const clip = { x, y, width: right - x, height: bottom - y };
|
|
return { clip, frameWidth: viewport.width, frameHeight: viewport.height };
|
|
}
|
|
|
|
async function finishContrast(
|
|
page: Page,
|
|
screenshot: string | null,
|
|
time: number,
|
|
candidates: unknown[],
|
|
region: TextRegion | undefined,
|
|
): Promise<unknown[]> {
|
|
return page.evaluate(
|
|
async (payload: {
|
|
screenshot: string | null;
|
|
time: number;
|
|
candidates: unknown[];
|
|
region: TextRegion | null;
|
|
}) => {
|
|
const finish = Reflect.get(window, "__contrastAuditFinish");
|
|
if (typeof finish !== "function") return [];
|
|
const result = await Reflect.apply(finish, window, [
|
|
payload.screenshot,
|
|
payload.time,
|
|
payload.candidates,
|
|
payload.region,
|
|
]);
|
|
return Array.isArray(result) ? result : [];
|
|
},
|
|
{ screenshot, time, candidates, region: region ?? null },
|
|
);
|
|
}
|
|
|
|
function parsePreparedContrast(
|
|
raw: unknown[],
|
|
motion: (ContrastMotionSample | null)[],
|
|
): PreparedContrast[] {
|
|
return raw.flatMap((value, index) => {
|
|
if (!isRecord(value)) return [];
|
|
const raw = Reflect.get(value, "candidate");
|
|
const candidate = parseContrastCandidate(raw);
|
|
const anchor = parseAnchor(Reflect.get(value, "anchor"));
|
|
return candidate && anchor
|
|
? [
|
|
{
|
|
raw,
|
|
candidate,
|
|
anchor,
|
|
knownBackdrop: knownBackdrop(raw),
|
|
motion: motion[index] ?? null,
|
|
},
|
|
]
|
|
: [];
|
|
});
|
|
}
|
|
|
|
function knownBackdrop(raw: unknown): boolean {
|
|
if (!isRecord(raw)) return false;
|
|
const own = Reflect.get(raw, "ownBg");
|
|
const solid = Reflect.get(raw, "solidBg");
|
|
return Array.isArray(solid) || (Array.isArray(own) && own.length >= 4 && own[3] >= 0.99);
|
|
}
|
|
|
|
function parseContrastCandidate(value: unknown): ContrastCandidate | null {
|
|
if (!isRecord(value)) return null;
|
|
const selector = stringValue(value, "selector");
|
|
const text = stringValue(value, "text");
|
|
const fg = rgbaValue(Reflect.get(value, "fg"));
|
|
const large = booleanValue(value, "large");
|
|
const bbox = parseBbox(Reflect.get(value, "bbox"));
|
|
return selector && text !== null && fg && large !== null && bbox
|
|
? { selector, text, fg, large, bbox }
|
|
: null;
|
|
}
|
|
|
|
function parseFinishedContrast(value: unknown): FinishedContrast[] {
|
|
if (!isRecord(value)) return [];
|
|
const selector = stringValue(value, "selector");
|
|
const text = stringValue(value, "text");
|
|
const ratio = numberValue(value, "ratio");
|
|
const wcagAA = booleanValue(value, "wcagAA");
|
|
const large = booleanValue(value, "large");
|
|
const fg = stringValue(value, "fg");
|
|
const bg = stringValue(value, "bg");
|
|
return selector &&
|
|
text !== null &&
|
|
ratio !== null &&
|
|
wcagAA !== null &&
|
|
large !== null &&
|
|
fg &&
|
|
bg
|
|
? [{ selector, text, ratio, wcagAA, large, fg, bg }]
|
|
: [];
|
|
}
|
|
|
|
function joinContrastEntries(
|
|
finished: FinishedContrast[],
|
|
prepared: PreparedContrast[],
|
|
): ContrastAuditEntry[] {
|
|
const remaining = [...prepared];
|
|
return finished.flatMap((entry) => {
|
|
const index = remaining.findIndex(
|
|
(candidate) =>
|
|
candidate.candidate.selector === entry.selector && candidate.candidate.text === entry.text,
|
|
);
|
|
const match = index >= 0 ? remaining.splice(index, 1)[0] : undefined;
|
|
if (!match) return [];
|
|
if (!entry.wcagAA && match.motion && measuredInMotion(match.motion)) return [];
|
|
return [{ ...entry, ...match.anchor }];
|
|
});
|
|
}
|
|
|
|
export function parseLayoutIssue(value: unknown): LayoutIssue[] {
|
|
if (!isRecord(value)) return [];
|
|
const code = layoutCodeValue(Reflect.get(value, "code"));
|
|
const severity = severityValue(Reflect.get(value, "severity"));
|
|
const time = numberValue(value, "time");
|
|
const selector = stringValue(value, "selector");
|
|
const message = stringValue(value, "message");
|
|
const rect = parseRect(Reflect.get(value, "rect"));
|
|
if (!code || !severity || time === null || !selector || !message || !rect) return [];
|
|
const issue: LayoutIssue = { code, severity, time, selector, message, rect };
|
|
assignOptionalLayoutFields(issue, value);
|
|
return [issue];
|
|
}
|
|
|
|
function parseGeometryCandidate(value: unknown, time: number): CheckGeometryCandidate[] {
|
|
if (!isRecord(value)) return [];
|
|
const rect = parseRect(Reflect.get(value, "rect"));
|
|
const elementRect = parseRect(Reflect.get(value, "elementRect"));
|
|
if (!rect || !elementRect) return [];
|
|
const identity = parseGeometryIdentity(value);
|
|
if (!identity) return [];
|
|
const anchor = parseGeometryAnchor(value, rect, time);
|
|
if (!anchor) return [];
|
|
const candidate: CheckGeometryCandidate = { ...identity, ...anchor, rect, elementRect };
|
|
const overflow = parseOverflow(Reflect.get(value, "overflow"));
|
|
if (overflow) candidate.overflow = overflow;
|
|
return [candidate];
|
|
}
|
|
|
|
function parseGeometryIdentity(
|
|
value: Record<string, unknown>,
|
|
): Pick<CheckGeometryCandidate, "kind" | "tag" | "text"> | null {
|
|
const kindValue = Reflect.get(value, "kind");
|
|
const kind =
|
|
kindValue === "text" || kindValue === "media" || kindValue === "block" ? kindValue : null;
|
|
if (!kind) return null;
|
|
const tag = stringValue(value, "tag");
|
|
if (!tag) return null;
|
|
const text = stringValue(value, "text");
|
|
return text === null ? null : { kind, tag, text };
|
|
}
|
|
|
|
function parseGeometryAnchor(
|
|
value: Record<string, unknown>,
|
|
rect: LayoutRect,
|
|
time: number,
|
|
): CheckAnchor | null {
|
|
const selector = stringValue(value, "selector");
|
|
if (!selector) return null;
|
|
const sourceFile = stringValue(value, "sourceFile");
|
|
if (!sourceFile) return null;
|
|
const dataAttributes = stringRecord(Reflect.get(value, "dataAttributes"));
|
|
return dataAttributes
|
|
? {
|
|
selector,
|
|
sourceFile,
|
|
dataAttributes,
|
|
bbox: rectToBbox(rect),
|
|
time,
|
|
}
|
|
: null;
|
|
}
|
|
|
|
function assignOptionalLayoutFields(issue: LayoutIssue, value: Record<string, unknown>): void {
|
|
assignOptionalString(issue, value, "containerSelector");
|
|
assignOptionalString(issue, value, "text");
|
|
assignOptionalString(issue, value, "fixHint");
|
|
const containerRect = parseRect(Reflect.get(value, "containerRect"));
|
|
if (containerRect) issue.containerRect = containerRect;
|
|
const overflow = parseOverflow(Reflect.get(value, "overflow"));
|
|
if (overflow) issue.overflow = overflow;
|
|
const coveredFraction = numberValue(value, "coveredFraction");
|
|
if (coveredFraction !== null) issue.coveredFraction = coveredFraction;
|
|
const lifetime = recordField(value, "lifetime");
|
|
const start = lifetime ? numberValue(lifetime, "start") : null;
|
|
const end = lifetime ? numberValue(lifetime, "end") : null;
|
|
if (start !== null && end !== null) issue.lifetime = { start, end };
|
|
}
|
|
|
|
function recordField(value: unknown, key: string): Record<string, unknown> | null {
|
|
if (!isRecord(value)) return null;
|
|
const field = Reflect.get(value, key);
|
|
return isRecord(field) ? field : null;
|
|
}
|
|
|
|
function parseMotionFrame(
|
|
value: unknown,
|
|
time: number,
|
|
selectors: string[],
|
|
scopes: string[],
|
|
): MotionFrame {
|
|
const rawData = recordField(value, "data");
|
|
const rawLiveness = recordField(value, "liveness");
|
|
const data: MotionFrame["data"] = {};
|
|
for (const selector of selectors) {
|
|
data[selector] = rawData ? parseFrameSample(Reflect.get(rawData, selector)) : null;
|
|
}
|
|
const liveness: Record<string, string> = {};
|
|
for (const scope of scopes) {
|
|
const signature = rawLiveness ? Reflect.get(rawLiveness, scope) : "";
|
|
liveness[scope] = typeof signature === "string" ? signature : "";
|
|
}
|
|
return { time, data, liveness };
|
|
}
|
|
|
|
function parseFrameSample(value: unknown): MotionFrame["data"][string] {
|
|
if (!isRecord(value)) return null;
|
|
const rect = parseRect(Reflect.get(value, "rect"));
|
|
const opacity = numberValue(value, "opacity");
|
|
const visible = booleanValue(value, "visible");
|
|
return rect && opacity !== null && visible !== null ? { rect, opacity, visible } : null;
|
|
}
|
|
|
|
function parseAnchor(value: unknown): CheckAnchor | null {
|
|
if (!isRecord(value)) return null;
|
|
const selector = stringValue(value, "selector");
|
|
const sourceFile = stringValue(value, "sourceFile");
|
|
const time = numberValue(value, "time");
|
|
const bbox = parseBbox(Reflect.get(value, "bbox"));
|
|
const dataAttributes = stringRecord(Reflect.get(value, "dataAttributes"));
|
|
return selector && sourceFile && time !== null && bbox && dataAttributes
|
|
? { selector, sourceFile, time, bbox, dataAttributes }
|
|
: null;
|
|
}
|
|
|
|
function runtimeFinding(draft: RuntimeDraft, root: CheckAnchor): CheckFinding {
|
|
return {
|
|
code: draft.code,
|
|
severity: draft.severity,
|
|
message:
|
|
(draft.count ?? 1) > 1 ? `${draft.message} (repeated ${draft.count} times)` : draft.message,
|
|
selector: root.selector,
|
|
dataAttributes: root.dataAttributes,
|
|
sourceFile: root.sourceFile,
|
|
bbox: root.bbox,
|
|
time: draft.time,
|
|
...(draft.timeRange ? { timeRange: draft.timeRange } : {}),
|
|
url: draft.url,
|
|
line: draft.line,
|
|
...(draft.fixHint ? { fixHint: draft.fixHint } : {}),
|
|
};
|
|
}
|
|
|
|
function fallbackAnchor(request: AnchorRequest | undefined): CheckAnchor {
|
|
return {
|
|
selector: request?.selector ?? "[data-composition-id]",
|
|
dataAttributes: {},
|
|
sourceFile: "index.html",
|
|
bbox: request?.bbox ?? { x: 0, y: 0, width: 0, height: 0 },
|
|
time: request?.time ?? 0,
|
|
};
|
|
}
|
|
|
|
function parseBbox(value: unknown): CheckBbox | null {
|
|
if (!isRecord(value)) return null;
|
|
const x = numberValue(value, "x");
|
|
const y = numberValue(value, "y");
|
|
const width = numberValue(value, "width") ?? numberValue(value, "w");
|
|
const height = numberValue(value, "height") ?? numberValue(value, "h");
|
|
return x !== null && y !== null && width !== null && height !== null
|
|
? { x, y, width, height }
|
|
: null;
|
|
}
|
|
|
|
function parseRect(value: unknown): LayoutRect | null {
|
|
if (!isRecord(value)) return null;
|
|
const left = numberValue(value, "left");
|
|
const top = numberValue(value, "top");
|
|
const right = numberValue(value, "right");
|
|
const bottom = numberValue(value, "bottom");
|
|
const width = numberValue(value, "width");
|
|
const height = numberValue(value, "height");
|
|
return left !== null &&
|
|
top !== null &&
|
|
right !== null &&
|
|
bottom !== null &&
|
|
width !== null &&
|
|
height !== null
|
|
? { left, top, right, bottom, width, height }
|
|
: null;
|
|
}
|
|
|
|
function parseOverflow(value: unknown): LayoutIssue["overflow"] | null {
|
|
if (!isRecord(value)) return null;
|
|
const overflow: LayoutIssue["overflow"] = {};
|
|
for (const side of ["left", "right", "top", "bottom"] as const) {
|
|
const amount = numberValue(value, side);
|
|
if (amount !== null) overflow[side] = amount;
|
|
}
|
|
return Object.keys(overflow).length > 0 ? overflow : null;
|
|
}
|
|
|
|
const LAYOUT_ISSUE_CODES: readonly LayoutIssueCode[] = [
|
|
"text_box_overflow",
|
|
"clipped_text",
|
|
"canvas_overflow",
|
|
"container_overflow",
|
|
"content_overlap",
|
|
"visibility_escapes_segment",
|
|
"text_occluded",
|
|
"canvas_covered",
|
|
"video_alpha_unread",
|
|
"text_not_painted",
|
|
"caption_zone_collision",
|
|
"outside_safe_zone",
|
|
"frame_out_of_frame",
|
|
"escaped_container",
|
|
"panel_out_of_canvas",
|
|
"canvas_content_at_edge",
|
|
"connector_detached",
|
|
"connector_orphan",
|
|
"rotation_pivot_drift",
|
|
"off_pivot_rotation",
|
|
"motion_appears_late",
|
|
"motion_out_of_order",
|
|
"motion_off_frame",
|
|
"motion_frozen",
|
|
"motion_selector_missing",
|
|
"motion_selector_ambiguous",
|
|
];
|
|
|
|
function layoutCodeValue(value: unknown): LayoutIssueCode | null {
|
|
return LAYOUT_ISSUE_CODES.find((code) => code === value) ?? null;
|
|
}
|
|
|
|
function severityValue(value: unknown): CheckSeverity | null {
|
|
return value === "error" || value === "warning" || value === "info" ? value : null;
|
|
}
|
|
|
|
function rgbaValue(value: unknown): [number, number, number, number] | null {
|
|
if (!Array.isArray(value) || value.length < 4) return null;
|
|
const [red, green, blue, alpha] = value;
|
|
return [red, green, blue, alpha].every((channel) => typeof channel === "number")
|
|
? [red, green, blue, alpha]
|
|
: null;
|
|
}
|
|
|
|
function stringRecord(value: unknown): Record<string, string> | null {
|
|
if (!isRecord(value)) return null;
|
|
const record: Record<string, string> = {};
|
|
for (const key of Object.keys(value)) {
|
|
const entry = Reflect.get(value, key);
|
|
if (typeof entry !== "string") return null;
|
|
record[key] = entry;
|
|
}
|
|
return record;
|
|
}
|
|
|
|
function assignOptionalString(
|
|
issue: LayoutIssue,
|
|
source: Record<string, unknown>,
|
|
key: "containerSelector" | "text" | "fixHint",
|
|
): void {
|
|
const value = stringValue(source, key);
|
|
if (value !== null) issue[key] = value;
|
|
}
|
|
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
}
|
|
|
|
function stringValue(value: Record<string, unknown>, key: string): string | null {
|
|
const entry = Reflect.get(value, key);
|
|
return typeof entry === "string" ? entry : null;
|
|
}
|
|
|
|
function numberValue(value: Record<string, unknown>, key: string): number | null {
|
|
const entry = Reflect.get(value, key);
|
|
return typeof entry === "number" && Number.isFinite(entry) ? entry : null;
|
|
}
|
|
|
|
function booleanValue(value: Record<string, unknown>, key: string): boolean | null {
|
|
const entry = Reflect.get(value, key);
|
|
return typeof entry === "boolean" ? entry : null;
|
|
}
|
|
|
|
function urlPath(url: string): string {
|
|
try {
|
|
return decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
|
|
} catch {
|
|
return url;
|
|
}
|
|
}
|
|
|
|
export function matchComponentFindings({
|
|
components,
|
|
findings,
|
|
}: {
|
|
components: string[];
|
|
findings: CheckFinding[];
|
|
}): boolean[] {
|
|
const roots = components.flatMap((selector) => {
|
|
const matches = [...document.querySelectorAll(selector)];
|
|
if (!matches.length) throw new Error(`Component selector matched nothing: ${selector}`);
|
|
return matches;
|
|
});
|
|
function matchesSelector(selector: string): boolean | null {
|
|
try {
|
|
const elements = [...document.querySelectorAll(selector)];
|
|
if (!elements.length) return null;
|
|
return elements.some((el) => roots.some((root) => root.contains(el)));
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
return findings.map((finding) => {
|
|
if (!finding.selector || finding.selector === "[data-composition-id]") return true;
|
|
const container = Reflect.get(finding, "containerSelector");
|
|
return (
|
|
matchesSelector(finding.selector) !== false ||
|
|
(typeof container === "string" && matchesSelector(container) !== false)
|
|
);
|
|
});
|
|
}
|