An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file busy.ts
* @input Uses a Playwright `Page`
* @output `blockMainThread`, a synchronous busy loop on the page's main
* thread that reports exactly when it ran. `startBusyControl`, a plain
* compositor-only control animation recorded in the same window.
* `busyWindowProof`, which reads frame evidence for that window, against
* the control when it has one. `castStep`, the screencast's position step
* read from its frames. `pooledBusyProof`, which judges several short
* blocks as one. `BusyWindowTooLateError`, for a block that began too late
* for the motion it was meant to catch. `BusyFrameUnjudgedError`, for a
* frame the cast could not judge in a proof that judges every frame
* (`judgeEveryFrame`). `BusyPredictionError`, for a window whose motion the
* proof cannot predict.
* `BUSY_PROOF_LOOKAROUND_MS` is how far around its judged part a proof
* reads frames.
* `trackControl` and `controlClock` read the control's box and its own
* clock from the screencast, a second control's too (`ahead`).
* @position The busy-main-thread proof: an animation that runs on the
* compositor keeps advancing at display rate while JavaScript holds the main
* thread; one driven from the main thread (rAF, style writes, layout
* properties) freezes for the whole block. Pair it with ./frames
* (`startScreencast` + `trackMarker`), which observes off the main thread.
*
* SYNC: Keep the README's busy-main-thread section equal to this contract.
*/
import type {Locator, Page} from '@playwright/test';
import {defineAnimatedProperties} from './animated-properties';
import {defineCurveEnd} from './curve-end';
import {
FRAME_STARVATION_MS,
FrameStarvationError,
frameStats,
trackMarker,
type CastFrame,
type FrameShortfall,
type FrameStats,
type TrackedFrame,
} from './frames';
/** The control's colour, apart from the component's marker (`MARKER_RGB`). */
export const CONTROL_RGB: readonly [number, number, number] = [0, 255, 255];
/**
* The control box's side, CSS px: it crosses the page's top `CONTROL_SIDE` px,
* where a proof reads nothing of the component.
*/
export const CONTROL_SIDE = 12;
/** How far the control travels along the top edge, CSS px. */
const CONTROL_TRAVEL = 240;
/** How long the control takes to travel `CONTROL_TRAVEL` one way, ms. */
const CONTROL_LEG_MS = 400;
/**
* The colour of the control ahead (`startBusyControl`'s `ahead`), apart from
* the first control's and the component's marker.
*/
export const AHEAD_CONTROL_RGB: readonly [number, number, number] = [
128, 0, 255,
];
/** Where the strip of the control ahead starts, CSS px: below the first's. */
const AHEAD_TOP = CONTROL_SIDE + 4;
/** How far the control ahead runs ahead of the first, ms: half a leg. */
const AHEAD_MS = CONTROL_LEG_MS / 2;
/**
* The control in each frame (`startBusyControl`'s box): `trackMarker` with
* `CONTROL_RGB`, searching only the strip the box crosses. With `ahead`, the
* control ahead, with `AHEAD_CONTROL_RGB` in its own strip.
*/
export async function trackControl(
page: Page,
frames: readonly CastFrame[],
{ahead = false}: {ahead?: boolean} = {},
): Promise<TrackedFrame[]> {
return trackMarker(page, frames, {
rgb: ahead ? AHEAD_CONTROL_RGB : CONTROL_RGB,
region: {
x: 0,
y: ahead ? AHEAD_TOP - 2 : 0,
width: CONTROL_SIDE + CONTROL_TRAVEL + 4,
height: CONTROL_SIDE + 4,
},
});
}
/**
* Starts a plain compositor-only control animation: a `CONTROL_RGB` box in the
* page's top-left corner whose transform moves it back and forth along the top
* edge (`CONTROL_TRAVEL` px every 400 ms, linear) for as long as the page
* runs. It shows what the compositor presented in a busy window on this
* machine, so a proof can judge a component against it rather than against a
* frame rate: track it from the same screencast (`trackMarker(page, frames,
* {rgb: CONTROL_RGB})`) and pass it to `busyWindowProof` as `control`.
*
* The box is a manual popover, so it shows in the top layer, above a modal
* dialog the page opened before it; `raise()` shows it again on top of one
* opened after. With `within`, it is mounted inside that element instead (an
* open modal dialog), as a plain fixed box with no top-layer entry, for a
* proof of the dialog's `::backdrop`: in WebKit, with the popover above
* BottomSheet's open modal dialog, the sheet's dim held for 155 to 225 ms
* into a block while the control moved. `waitForAnimation` and
* `blockMainThread`'s `during` never count the control's own animation, so
* they still wait for the dialog's. Start it before the block: it
* resolves once the animation is running and past its first frame (on the
* compositor; see `blockMainThread`). Keep the component's marker out of the
* strip it crosses (the top `CONTROL_SIDE` px, `CONTROL_SIDE +
* CONTROL_TRAVEL` px wide).
*
* It resolves with `start`, the animation's start on the page clock (epoch
* ms). The control's own time at a frame, past this start, is that frame's
* time on the page clock (`controlClock`).
*
* With `ahead`, it starts a second control after the first: the same box in
* `AHEAD_CONTROL_RGB`, in the strip below, half a leg (200 ms) ahead.
* `controlClock` reads no frame within `CONTROL_EDGE` px of a turn. Wherever
* the first control is there, the one ahead is mid-leg, so the two read
* every frame. Track it with `trackControl(page, frames, {ahead: true})`, and
* keep the marker out of its strip too (the top `2 * CONTROL_SIDE + 4` px).
*
* A busy proof dates a cast's frames on the controls' clock, in either
* engine, when the frames carry their engine (`trackMarker` keeps it).
* Without the control ahead, a frame stamped late near the first control's
* turn keeps its lateness. A proof that judges every frame near a turn
* starts the one ahead too, and passes its frames to `busyWindowProof` as
* `ahead`.
*/
export async function startBusyControl(
page: Page,
{
ahead = false,
rgb = ahead ? AHEAD_CONTROL_RGB : CONTROL_RGB,
within,
}: {
ahead?: boolean;
rgb?: readonly [number, number, number];
within?: Locator;
} = {},
): Promise<{
/** The control's start on the page clock, epoch ms. */
readonly start: number;
readonly raise: () => Promise<void>;
readonly remove: () => Promise<void>;
}> {
if (within != null) {
await within.evaluate(host =>
host.setAttribute('data-harness-control-host', ''),
);
}
const start = await page.evaluate(
({color, side, travel, legMs, top, aheadMs}) =>
new Promise<number>((resolve, reject) => {
const host = document.querySelector('[data-harness-control-host]');
host?.removeAttribute('data-harness-control-host');
const box = document.createElement('div');
box.setAttribute('data-harness-control', aheadMs > 0 ? 'ahead' : '');
box.style.cssText = `position:fixed;inset:auto;left:0;top:${top}px;margin:0;padding:0;border:0;overflow:visible;width:${side}px;height:${side}px;background:rgb(${color.join(',')});z-index:2147483647;pointer-events:none;`;
if (host == null) {
box.setAttribute('popover', 'manual');
document.body.appendChild(box);
box.showPopover();
} else {
host.appendChild(box);
}
const animation = box.animate(
[
{transform: 'translateX(0px)'},
{transform: `translateX(${travel}px)`},
],
{
duration: legMs,
iterations: Infinity,
direction: 'alternate',
easing: 'linear',
},
);
// The harness's own waits run on the real timers (see blockMainThread).
const gate = (
window as unknown as {
__harnessTimerGate?: {
frame?: typeof requestAnimationFrame;
now?: () => number;
};
}
).__harnessTimerGate;
// A frozen page holds the control's own animation.
if (
(window as unknown as {__harnessFreeze?: {frozen: boolean}})
.__harnessFreeze?.frozen === true
) {
reject(
new Error(
'startBusyControl: the page is frozen; start the control first',
),
);
return;
}
if (aheadMs > 0) {
// Half a leg ahead of the first control, on the same timeline.
const first = [
...document.querySelectorAll('[data-harness-control=""]'),
]
.map(el => el.getAnimations()[0])
.find(running => running?.startTime != null);
if (first == null) {
box.remove();
reject(
new Error(
'startBusyControl: start the first control before the one ahead',
),
);
return;
}
animation.startTime = Number(first.startTime) - aheadMs;
}
const frame = gate?.frame ?? window.requestAnimationFrame.bind(window);
const realNow = gate?.now ?? (() => performance.now());
const deadline = realNow() + 5_000;
// The one ahead starts running at once: give it a frame on the
// compositor too.
let ticks = 0;
const tick = () => {
ticks += 1;
if (
!animation.pending &&
Number(animation.currentTime ?? 0) >= 16 &&
(aheadMs === 0 || ticks >= 2)
) {
const start = performance.timeOrigin + Number(animation.startTime);
// Kept on the page for the block's window, which dates frames on
// the controls' clock (`BlockedWindow.controlStarts`).
const page = window as unknown as {
__harnessControlStarts?: number[];
};
(page.__harnessControlStarts ??= [])[aheadMs > 0 ? 1 : 0] = start;
resolve(start);
} else if (realNow() > deadline) {
reject(new Error('startBusyControl: the control did not start'));
} else {
frame(tick);
}
};
frame(tick);
}),
{
color: [...rgb],
side: CONTROL_SIDE,
travel: CONTROL_TRAVEL,
legMs: CONTROL_LEG_MS,
top: ahead ? AHEAD_TOP : 0,
aheadMs: ahead ? AHEAD_MS : 0,
},
);
return {
start,
raise: () =>
page.evaluate(() => {
for (const box of document.querySelectorAll<HTMLElement>(
'[data-harness-control][popover]',
)) {
box.hidePopover();
box.showPopover();
}
}),
remove: () =>
page.evaluate(() => {
for (const box of document.querySelectorAll('[data-harness-control]')) {
box.remove();
}
}),
};
}
/** How far a frame's stamp may run late and still agree with the others, ms. */
const CONTROL_AGREE_MS = 20;
/**
* Frames this near a turn get no reading. There the two times that a position
* gives are under 120 ms apart, and a stamp 60 ms late could pick either.
*/
const CONTROL_EDGE = 36;
/**
* The least time between two dated frames, ms, far under a frame interval.
* The proof matches frames by time, so no two may share one.
*/
const DATED_GAP_MS = 0.01;
/** One display interval, ms: the compositor presents at most once in one. */
const DISPLAY_FRAME_MS = 1000 / 60;
/** How close the controls' clock reads a time, ms: one px of travel. */
const CONTROL_READ_MS = CONTROL_LEG_MS / CONTROL_TRAVEL;
/**
* The compositor's clock in each frame of `control` (`startBusyControl`'s box,
* tracked with `trackControl`), ms. The compositor samples every animation at
* one time in a frame. So a component can be judged against this clock, not
* the screencast's stamps. A loaded machine can stamp a frame late, and
* `inPresentationOrder` then puts it after frames that it came before.
*
* The box's position gives two times a cycle, on the way out and on the way
* back. The cycle's origin is the one that the most frames agree with, each
* within `CONTROL_AGREE_MS` of one of its two times. So no single frame sets
* it. Each frame's stamp, measured from that origin, then picks its own time.
* A late or reordered frame moves only its own reading, and a gap moves none.
*
* A frame without the box gets no reading, and so does a frame within
* `CONTROL_EDGE` px of a turn. There a control started `ahead` is mid-leg:
* read it with its own clock. A frame that repeats the position before it
* shows no new time, so it gets none either. Readings count up from the
* origin a whole cycle or less before the first reading.
*/
export function controlClock(
control: readonly TrackedFrame[],
): Map<number, number> {
return readControlClock(control).readings;
}
/**
* `controlClock`'s readings, with the origin they count from (epoch ms, the
* stamps' clock), or a null origin when no frame has a reading.
*/
function readControlClock(control: readonly TrackedFrame[]): {
readonly readings: Map<number, number>;
readonly origin: number | null;
} {
const cycle = 2 * CONTROL_LEG_MS;
const usable = control.flatMap((frame, i) => {
const x = frame.box?.x;
const before = i > 0 ? control[i - 1].box?.x : undefined;
if (
x == null ||
x < CONTROL_EDGE ||
x > CONTROL_TRAVEL - CONTROL_EDGE ||
(before != null && Math.abs(x - before) <= 0.25)
) {
return [];
}
const out = (x / CONTROL_TRAVEL) * CONTROL_LEG_MS;
return [{t: frame.t, out, back: cycle - out}];
});
const clock = new Map<number, number>();
if (usable.length === 0) {
return {readings: clock, origin: null};
}
const onCycle = (a: number, b: number) => {
const d = Math.abs(a - b) % cycle;
return Math.min(d, cycle - d);
};
let origin = 0;
let agreeing = -1;
let spread = Number.POSITIVE_INFINITY;
for (let candidate = 0; candidate < cycle; candidate += 1) {
let count = 0;
let sum = 0;
for (const frame of usable) {
const phase = frame.t - candidate;
const d = Math.min(onCycle(phase, frame.out), onCycle(phase, frame.back));
if (d <= CONTROL_AGREE_MS) {
count += 1;
sum += d;
}
}
if (count > agreeing || (count === agreeing && sum < spread)) {
origin = candidate;
agreeing = count;
spread = sum;
}
}
const first = Math.min(...usable.map(frame => frame.t));
const anchored = origin + Math.floor((first - origin) / cycle) * cycle;
for (const frame of usable) {
const expected = frame.t - anchored;
const nearest = (ms: number) =>
ms + Math.round((expected - ms) / cycle) * cycle;
const out = nearest(frame.out);
const back = nearest(frame.back);
clock.set(
frame.t,
Math.abs(out - expected) <= Math.abs(back - expected) ? out : back,
);
}
return {readings: clock, origin: anchored};
}
/**
* Each control frame's time on the page clock, epoch ms, by its cast stamp. It
* is read from the busy controls' positions: the first control's clock, else
* the one `ahead`. The stamp only picks the control's cycle, so a stamp that
* runs late moves no reading. Each control counts from its start
* (`controlStarts`), or else from the origin that most of its frames' stamps
* agree with (`controlClock`). A frame with no reading has no time here.
* Frames tracked from the same screencast share its stamps, so a spec looks
* their times up here. The busy proofs date their frames from these times.
*/
export function pageTimesOnControls(
control: readonly TrackedFrame[],
{
ahead,
controlStarts,
}: {
/** The control started `ahead`, from the same screencast. */
readonly ahead?: readonly TrackedFrame[];
/** When the first control started, then the one ahead (`startBusyControl`). */
readonly controlStarts?: readonly [number, number?];
} = {},
): Map<number, number> {
const cycle = 2 * CONTROL_LEG_MS;
const readers = [
{...readControlClock(control), start: controlStarts?.[0]},
...(ahead == null
? []
: [{...readControlClock(ahead), start: controlStarts?.[1]}]),
].flatMap(({readings, origin, start}) => {
const from = start ?? origin;
return from == null ? [] : [{readings, from}];
});
const times = new Map<number, number>();
for (const {t: stamp} of [...control, ...(ahead ?? [])]) {
if (times.has(stamp)) {
continue;
}
for (const {readings, from} of readers) {
const ms = readings.get(stamp);
if (ms != null) {
times.set(
stamp,
from + ms + Math.round((stamp - from - ms) / cycle) * cycle,
);
break;
}
}
}
return times;
}
/**
* Each stamp's time on the page clock: its own reading where it has one
* (`pageTimesOnControls`).
*
* A stamp with no reading keeps its stamp's distance from the nearest stamp
* whose reading agrees with it, within `CONTROL_AGREE_MS`. Such a stamp is
* near a turn, or repeats a position. A late stamp's distance would carry its
* lateness. Without such a stamp, the nearest stamp with a reading serves.
* Dropping the frame would thin both series every half cycle.
*
* The times keep the stamps' order: a cast delivers frames in the order they
* were drawn. Two agreeing stamps can differ in lateness by twice
* `CONTROL_AGREE_MS`, so the stamps without a reading between them could
* swap. So such a stamp never passes the next stamp with a reading. Each time
* comes at least `DATED_GAP_MS` after the time of the stamp before it, since
* the proof matches frames by time. `read` holds the stamps whose time is
* their own reading. Null when no stamp has a reading.
*/
function controlPageTimes(
stamps: readonly number[],
control: readonly TrackedFrame[],
ahead: readonly TrackedFrame[] | undefined,
controlStarts: readonly [number, number?] | undefined,
): {times: Map<number, number>; read: ReadonlySet<number>} | null {
const own = pageTimesOnControls(control, {ahead, controlStarts});
const read = new Map<number, number>();
for (const stamp of stamps) {
const ms = own.get(stamp);
if (ms != null) {
read.set(stamp, ms);
}
}
if (read.size === 0) {
return null;
}
const dated = [...read.keys()];
// Agreement is read against the run's usual lag: a cast whose stamps all
// trail their content by the same time agrees with itself.
const lags = dated
.map(stamp => stamp - (read.get(stamp) ?? stamp))
.sort((a, b) => a - b);
const lag = lags[Math.floor(lags.length / 2)] ?? 0;
const agreeing = dated.filter(
stamp =>
Math.abs(stamp - (read.get(stamp) ?? stamp) - lag) <= CONTROL_AGREE_MS,
);
const anchors = agreeing.length > 0 ? agreeing : dated;
const times = new Map<number, number>();
for (const stamp of stamps) {
const own = read.get(stamp);
if (own != null) {
times.set(stamp, own);
continue;
}
let nearest = anchors[0];
for (const other of anchors) {
if (Math.abs(other - stamp) < Math.abs(nearest - stamp)) {
nearest = other;
}
}
times.set(stamp, (read.get(nearest) ?? nearest) + stamp - nearest);
}
const order = [...stamps].sort((a, b) => a - b);
let ceiling = Number.POSITIVE_INFINITY;
for (const stamp of [...order].reverse()) {
const own = read.get(stamp);
if (own == null) {
times.set(stamp, Math.min(times.get(stamp) ?? stamp, ceiling));
} else {
ceiling = own;
}
}
let floor = Number.NEGATIVE_INFINITY;
for (const stamp of order) {
floor = Math.max(times.get(stamp) ?? stamp, floor + DATED_GAP_MS);
times.set(stamp, floor);
}
return {times, read: new Set(read.keys())};
}
/**
* The component's and the control's frames dated on the controls' clock
* (`controlPageTimes`), in the cast's order, which those times keep. Both
* series come from one screencast, so each frame takes the same time in both.
* `stampOf` gives each dated time's stamp, and `readTimes` holds the times
* that are a frame's own reading. Null when the controls give no reading:
* the proof then judges the cast's stamps.
*/
function datedOnControlClock(
tracked: readonly TrackedFrame[],
control: readonly TrackedFrame[],
ahead: readonly TrackedFrame[] | undefined,
controlStarts: readonly [number, number?] | undefined,
): {
tracked: TrackedFrame[];
control: TrackedFrame[];
stampOf: ReadonlyMap<number, number>;
readTimes: ReadonlySet<number>;
} | null {
if (control.length === 0) {
return null;
}
const stamps = [...new Set([...tracked, ...control].map(frame => frame.t))];
const dating = controlPageTimes(stamps, control, ahead, controlStarts);
if (dating == null) {
return null;
}
const {times, read} = dating;
const date = (frames: readonly TrackedFrame[]) =>
[...frames]
.sort((a, b) => a.t - b.t)
.map(frame => ({...frame, t: times.get(frame.t) ?? frame.t}));
return {
tracked: date(tracked),
control: date(control),
stampOf: new Map([...times].map(([stamp, time]) => [time, stamp])),
readTimes: new Set([...read].map(stamp => times.get(stamp) ?? Number.NaN)),
};
}
/**
* The dated frames at display rate: at most one each display interval, read
* to the px (`CONTROL_READ_MS`). A frame under one interval after the last one
* kept is left out, and the earlier one stays. WebKit's compositor can draw
* two frames 6 to 9 ms apart, and a curve then shows no new step between them.
* Only frames whose time is their own reading count. A frame dated from a
* neighbour always stays. Its time is too rough to call it early, and leaving
* it out could hide a held frame. Near a turn without the control ahead, such
* a frame can then read as held, a false red that `ahead` removes. Both
* series keep the same frames.
*/
function atDisplayRate<
T extends {
readonly tracked: readonly TrackedFrame[];
readonly control: readonly TrackedFrame[];
readonly readTimes: ReadonlySet<number>;
},
>(dated: T): T {
const times = [
...new Set([...dated.tracked, ...dated.control].map(frame => frame.t)),
].sort((a, b) => a - b);
const kept = new Set<number>();
let last = Number.NEGATIVE_INFINITY;
for (const t of times) {
if (!dated.readTimes.has(t)) {
kept.add(t);
continue;
}
// To a nanosecond, so float error never drops a frame one read early.
if (t - last + 1e-6 >= DISPLAY_FRAME_MS - CONTROL_READ_MS) {
kept.add(t);
last = t;
}
}
return {
...dated,
tracked: dated.tracked.filter(frame => kept.has(frame.t)),
control: dated.control.filter(frame => kept.has(frame.t)),
};
}
/**
* Pairs of judged frames one display interval apart, with the control moved
* between them. On such a pair, a fade that holds every other frame shows no
* step. Each frame finds its control frame by time. A pair without both counts
* as unmatched.
*/
function displayIntervalPairs(
tracked: readonly TrackedFrame[],
control: readonly TrackedFrame[],
judged: {readonly from: number; readonly to: number},
): {pairs: number; unmatched: number} {
const controlAt = new Map(control.map(frame => [frame.t, frame]));
const inside = tracked.filter(
frame => frame.t >= judged.from && frame.t <= judged.to,
);
let pairs = 0;
let unmatched = 0;
for (let i = 1; i < inside.length; i += 1) {
const [a, b] = [inside[i - 1], inside[i]];
if (b.t - a.t >= 2 * DISPLAY_FRAME_MS - CONTROL_READ_MS) {
continue;
}
const [from, to] = [controlAt.get(a.t), controlAt.get(b.t)];
if (from == null || to == null) {
unmatched += 1;
} else if (from.box?.x !== to.box?.x) {
pairs += 1;
}
}
return {pairs, unmatched};
}
/**
* The judged part on the cast's own stamps, from the first frame judged to
* the last. A caller selects the judged frames from its own cast by them.
*/
function judgedOnStamps(
judged: {readonly from: number; readonly to: number},
dated: {
readonly tracked: readonly TrackedFrame[];
readonly stampOf: ReadonlyMap<number, number>;
},
): {readonly from: number; readonly to: number} {
const inside = dated.tracked.filter(
frame =>
frame.box != null && frame.t >= judged.from && frame.t <= judged.to,
);
const from = dated.stampOf.get(inside.at(0)?.t ?? Number.NaN);
const to = dated.stampOf.get(inside.at(-1)?.t ?? Number.NaN);
return from == null || to == null ? judged : {from, to};
}
/** What the control presented in the judged part (see `busyWindowProof`). */
export interface BusyControlRead {
/** Frames in the judged part that presented a new control position. */
readonly moved: number;
/** Of those, the frames that also presented a new component position. */
readonly movedWith: number;
/** The control's longest time without a new position, the edges included. */
readonly longestStallMs: number;
/**
* Of `movedWith`, the frames counted as moved where the cast could not show
* the component's motion: under one cast step per frame, or a frame
* delivered early under two (see `busyWindowProof`).
*/
readonly belowStep: number;
/**
* The component's longest time without a new position, read the same way:
* a run of unchanged frames the cast could not show is motion.
*/
readonly componentStallMs: number;
}
export interface BusyWindow {
/** Epoch ms when the loop started and ended, on the page's own clock. */
readonly from: number;
readonly to: number;
}
/** The window `blockMainThread` held, with the span its loop measured. */
export interface BlockedWindow extends BusyWindow {
/**
* How long the loop held the thread, in ms, between the two clock readings
* it started and ended on. It is never less than the time asked for.
*/
readonly spanMs: number;
/**
* The busy controls' starts on the page clock, epoch ms, when
* `startBusyControl` started any: the first control, then the one ahead.
* A proof dates its frames from them unless its options name others.
*/
readonly controlStarts?: readonly [number, number?];
/**
* With `during`: the animation the block caught, epoch ms on the page's
* clock. `from` is its start, and `to` is where its curve ends, its held
* tail excluded. It is absent when the animation's `playbackRate` is 0 or
* less, since its curve then has no forward end. `holds` says whether the
* element keeps the curve's end value after `to`. A held tail keeps it, and
* so does a fill the engine's compositor honors (not WebKit on Linux). When
* it does not, `busyWindowProof` judges the block up to `to`.
*
* Once the loop ends, the page also replays the caught animation, for the
* proof to predict each frame's move. It reads the replay every 2 ms, from
* `BUSY_PROOF_LOOKAROUND_MS` before the block to as long after its end.
* `geometry` holds the element's box as `[epoch ms, x, y, width, height]`,
* or the marker chip's when the element holds one. For a fade or a
* pseudo-element, `progress` holds one numeric channel scaled from 0 to 1.
* `check` is the replayed box and the element's own at the loop's end, once
* the replay is aligned to it. `unpredictable` says why neither could be
* read, and fails the proof. `notPredicted` says why the cast-step rule
* judges each frame instead. Either the caught element carries no harness
* marker, or the run left the element before its replay.
*/
readonly animation?: {
readonly from: number;
readonly to: number;
readonly holds: boolean;
readonly geometry?: ReadonlyArray<
readonly [number, number, number, number, number]
>;
readonly check?: {
readonly predicted: readonly [number, number, number, number];
readonly actual: readonly [number, number, number, number];
};
readonly progress?: ReadonlyArray<readonly [number, number]>;
readonly unpredictable?: string;
readonly notPredicted?: string;
};
}
/**
* Holds the page's main thread for `ms` (a synchronous loop: no task, frame,
* rAF, event or microtask runs meanwhile). Resolves with the window it held.
*
* Block MID-FLIGHT only: start the gesture or animation first. A touch that
* starts while the main thread is busy does not scroll or begin a gesture in
* headless Chromium, even with only passive listeners, and an animation that
* has not started cannot start (see `waitForAnimation`). Finger tracking
* under a busy main thread is a simulator proof, not a Playwright one.
*
* With `during`, the page itself waits until an animation on that element (or
* inside it) has run `minProgressMs`, then blocks from a task it queues in
* that frame. A round trip from the test would start the block later the
* busier the machine is, leaving less of a short animation to judge. The task
* runs after the frame's rendering update, which is where WebKit hands a newly
* started animation to its compositor: a loop inside the rAF callback itself
* holds that hand-off, and even a compositor animation freezes. To catch a
* settle near its start, call it before the release that starts the settle and
* await it after: the page is already waiting when the animation begins. Any
* animation inside `during` counts but the busy-window control's own
* (`startBusyControl`, mounted inside a dialog with `within`), so pick an
* element that runs nothing else meanwhile.
* With `pseudoElement`, only that pseudo-element's animations on `during`
* itself count, as `sampleCurve` reads them. A child's animation, such as a
* switch thumb's press, then does not start the block.
* With `property`, only animations that set that property count, named as
* CSS names it (`translate`, `background-color`, `--press-strength`), as a
* hold's judged motion names it.
* A thumb's `translate` travel then starts the block, and its press `scale`
* does not.
*
* An animation counts once it is no longer pending and has run at least one
* frame (`minProgressMs` below 16 ms is raised to 16). One created in the
* frame the page looks is still pending, not yet on the compositor
* (Chromium), and in WebKit its start time resolves before its layer is
* flushed: a block that started on it froze it.
* It must also be the same animation the page saw at its frame before. A
* component can rebuild a running animation on its old clock. The page then
* sees it running and not pending, before the compositor shows a frame of it,
* so the block waits one frame more. An animation rebuilt at every frame never
* qualifies: at the timeout the wait rejects and names that.
*
* It counts only while it still moves: before its curve's held tail (where
* its keyframes end in a run of identical values, read as `waitForRest`
* reads it). A block in that tail would judge an animation that has stopped.
* When the only animation running there started while the page waited, or
* the wait times out with only such animations, the page looked too late:
* that rejects with `BusyWindowTooLateError`, with the numbers.
*
* The window it resolves with names the animation it caught (`animation`):
* when it started and where its curve ends. `holds` says whether the element
* keeps the curve's end value after it. These times are on the real clock,
* as the window's own are, after a page freeze too.
*/
/** One display frame, ms: the least progress `blockMainThread` waits for. */
const ONE_FRAME_MS = 16;
/**
* The block began too late for the motion it was meant to catch. So the
* window holds too little to judge: when the block ran, not how the component
* moved. Thrown by `blockMainThread` (with `during`) when the animation under
* test is already in its curve's held tail where the page first looks. Thrown
* by `busyWindowProof` when the tracked value had settled before the judged
* part of the window began. Thrown too when a held curve that keeps no end
* value ends so soon in the block that too few frames are left
* (`curveEndMs`). Always a red, with the numbers; never a pass. Start the
* block earlier: call `blockMainThread` before the action that starts the
* motion, and await it after.
*/
export class BusyWindowTooLateError extends Error {
constructor(
message: string,
/** The times the error is read from, ms. */
readonly numbers: Readonly<Record<string, number>>,
) {
super(message);
this.name = 'BusyWindowTooLateError';
}
}
/** A frame a busy proof could not judge (see `BusyFrameUnjudgedError`). */
export interface UnjudgedFrame {
/** When the frame was presented, ms after the window began. */
readonly atMs: number;
/**
* The component's move per frame there, px. With a prediction, it is the
* predicted move since the frame before. Without one, it is the change
* that ends the run of equal positions that holds the frame, over the
* run's frames.
*/
readonly movePx: number;
/** The cast's position step for the judged value, px. */
readonly stepPx: number;
/**
* With a prediction, why the proof names the frame. `step`: its predicted
* move falls under one cast step. `clock`: it, or the frame before it, has
* no control reading of its own to date it.
*/
readonly why?: 'step' | 'clock';
}
/**
* A frame the cast could not show the component's step on, in a busy proof
* that judges every frame (`judgeEveryFrame`). The control moved on that
* frame. The component moved under two of the cast's steps a frame, and the
* frame shows no change. So the run is too little to judge: it fails by name,
* not as a red on the component. A frozen or main-thread component still
* fails the verdict, since the cast's step does not explain its hold.
*/
export class BusyFrameUnjudgedError extends Error {
constructor(
/** Each frame the proof could not judge. */
readonly frames: readonly UnjudgedFrame[],
summary: string,
) {
super(
`busyWindowProof: too little to judge: ${frames
.map(
frame =>
`at +${frame.atMs.toFixed(1)} ms the component moved about ${frame.movePx.toFixed(2)} px a frame, under two of the cast's ${frame.stepPx} px steps, and the frame shows no step while the control moved`,
)
.join('; ')}. ${summary}`,
);
this.name = 'BusyFrameUnjudgedError';
}
}
/**
* A busy proof could not predict the component's motion. An ancestor moved
* it too, a geometry animation composites onto another, or the replay that
* predicts it disagreed with the element or the cast. The run is not judged.
* It fails by name, never as a pass and never as a red on the component.
*/
export class BusyPredictionError extends Error {
constructor(message: string) {
super(`busyWindowProof: ${message}`);
this.name = 'BusyPredictionError';
}
}
export async function blockMainThread(
page: Page,
ms: number,
{
during,
minProgressMs = 16,
property,
pseudoElement,
timeout = 5_000,
}: {
during?: Locator;
minProgressMs?: number;
property?: string;
pseudoElement?: '::before' | '::after';
timeout?: number;
} = {},
): Promise<BlockedWindow> {
const minProgress = Math.max(minProgressMs, ONE_FRAME_MS);
if (pseudoElement != null && during == null) {
throw new TypeError(
'blockMainThread: pseudoElement names a part of `during`; pass `during` too',
);
}
if (property != null && during == null) {
throw new TypeError(
'blockMainThread: property picks an animation of `during`; pass `during` too',
);
}
if (during == null) {
return page.evaluate(duration => {
// The harness's own work: a trace sets it apart (trace.ts HARNESS_READ).
console.timeStamp('harness-read');
// One reading starts the loop and one ends it. A coarsened clock can
// step back between two reads, so a separate read would end it early.
// The loop tests the span it returns, which a sum rounded down would not.
// It reads the timer gate's real clock: a page freeze stops the page's
// own, which then trails the frames after the thaw.
const read =
(
window as unknown as {
__harnessTimerGate?: {now?: () => number};
}
).__harnessTimerGate?.now ?? (() => performance.now());
const start = read();
let now = start;
let spins = 0;
while (now - start < duration) {
now = read();
spins += 1;
}
return {
from: performance.timeOrigin + start,
to: performance.timeOrigin + now,
spanMs: now - start,
spins,
};
}, ms);
}
// The wait reads the curve end and the property match, defined in the page
// first. Both are sent before the wait and not awaited: the wait starts no
// later than before.
const defined = page.evaluate(
`(${defineCurveEnd.toString()})();(${defineAnimatedProperties.toString()})();`,
);
// WebKit on Linux ignores `fill` on its compositor: a filled move that
// ends during a main-thread block snaps back (motion/animator.ts,
// END_HOLD_MS). Elsewhere a fill holds the end value. Node's platform is
// the browser's: no config connects to a remote browser.
const fillHolds = !(
page.context().browser()?.browserType().name() === 'webkit' &&
process.platform === 'linux'
);
const waited = during.evaluate(
(element, {duration, minProgress, prop, pseudo, wait, fillHolds, look}) =>
new Promise<BlockedWindow>((resolve, reject) => {
// The harness's own waits run on the real timers: a frozen timer gate
// (story.ts) holds only the page's.
const gate = (
window as unknown as {
__harnessTimerGate?: {
frame?: typeof requestAnimationFrame;
now?: () => number;
timeout?: typeof setTimeout;
};
}
).__harnessTimerGate;
const frame = gate?.frame ?? window.requestAnimationFrame.bind(window);
const later = gate?.timeout ?? window.setTimeout.bind(window);
const realNow = gate?.now ?? (() => performance.now());
const deadline = realNow() + wait;
// The busy-window control animates on its own, inside a dialog with
// `within`: it never stands for the animation under test.
const isControl = (a: Animation) => {
const target = (a.effect as KeyframeEffect | null)?.target ?? null;
return (
target instanceof Element &&
target.closest('[data-harness-control]') != null
);
};
// With a pseudo-element, only its own animations on the element; with
// a property, only animations that set it, matched as a hold's judged
// motion is.
const animates = (
window as unknown as {
__harnessAnimates: (a: Animation, property: string) => boolean;
}
).__harnessAnimates;
const counts = (a: Animation) => {
if (isControl(a)) {
return false;
}
const effect = a.effect as KeyframeEffect | null;
if (
pseudo != null &&
(effect?.target !== element ||
(effect.pseudoElement ?? null) !== pseudo)
) {
return false;
}
return prop == null || animates(a, prop);
};
// Where each animation's curve ends, its held tail excluded.
const curveEnd =
(
window as unknown as {
__harnessCurveEnd?: (animation: Animation) => number;
}
).__harnessCurveEnd ??
((a: Animation) => {
const timing = a.effect?.getComputedTiming();
return (
Number(timing?.delay ?? 0) + Number(timing?.activeDuration ?? 0)
);
});
// What already ran when the wait began.
const before = new Set(
element.getAnimations({subtree: true}).filter(counts),
);
const numbersOf = (a: Animation) => ({
currentTimeMs: Number(a.currentTime ?? 0),
curveEndMs: curveEnd(a),
startedWhileWaiting: before.has(a) ? 0 : 1,
});
// The first run the wait saw in its held tail, as it was then: it may
// finish, or be cancelled once its curve ends, before the wait times
// out.
let heldSeen: ReturnType<typeof numbersOf> | null = null;
const tooLate = (numbers: ReturnType<typeof numbersOf>) =>
new Error(`BusyWindowTooLate ${JSON.stringify(numbers)}`);
// The caught animation, replayed once the loop ends, for the proof to
// predict each frame's move (`BlockedWindow.animation`). The element's
// geometry animations replay, paused, on a hidden clone of its box in
// the same parent. A fade or a pseudo-element replays one numeric
// channel instead, on a hidden registered <number>. Each held seek
// reads the browser's own easing, and the element is untouched.
const geometry = ['translate', 'scale', 'rotate', 'transform'];
const keyframesOf = (a: Animation) =>
(a.effect as KeyframeEffect | null)?.getKeyframes() ?? [];
const isGeometry = (a: Animation) =>
keyframesOf(a).some(k => geometry.some(p => p in k));
const realStart = (a: Animation) =>
performance.timeOrigin +
Number(a.startTime) +
((window as unknown as {__harnessFreeze?: {offset: number}})
.__harnessFreeze?.offset ?? 0);
const boxOf = (el: Element): [number, number, number, number] => {
const r = el.getBoundingClientRect();
return [r.x, r.y, r.width, r.height];
};
const replayOf = (
caught: Animation,
fromMs: number,
toMs: number,
): Record<string, unknown> => {
const effect = caught.effect as KeyframeEffect | null;
const target = effect?.target;
if (
target instanceof HTMLElement &&
effect?.pseudoElement == null &&
isGeometry(caught)
) {
// Only the element that carries the harness marker predicts the
// tracked box.
if (!target.hasAttribute('data-harness-marker')) {
return {
notPredicted: 'the tracked marker is not on the caught element',
};
}
for (
let up = target.parentElement;
up != null;
up = up.parentElement
) {
if (
up
.getAnimations()
.some(
a =>
isGeometry(a) &&
a.playState !== 'finished' &&
a.playState !== 'idle',
)
) {
return {
unpredictable:
'an ancestor of the element moves too, so its box cannot be predicted',
};
}
}
const runs = target.getAnimations().filter(isGeometry);
// A run that already left the element shows where it stopped, so a
// replay of the rest cannot place it.
if (!runs.includes(caught)) {
return {
notPredicted: 'the caught animation ended before its replay',
};
}
if (
runs.some(
a =>
a.startTime == null ||
(a.effect as KeyframeEffect).composite !== 'replace' ||
keyframesOf(a).some(
k =>
k.composite != null &&
k.composite !== 'auto' &&
k.composite !== 'replace',
),
)
) {
return {
unpredictable:
'a geometry animation of the element composites onto another or has not started, so its box cannot be predicted',
};
}
if (
getComputedStyle(target).position === 'fixed' ||
target.parentElement == null
) {
return {
unpredictable:
'the element is fixed, so its box cannot be replayed in its parent',
};
}
const style = getComputedStyle(target);
const clone = document.createElement('div');
clone.setAttribute('aria-hidden', 'true');
// The layout box to the sub-pixel: the computed size with its
// padding and border. The offset is in whole px: it is aligned
// below.
const px = (name: string) =>
Number.parseFloat(style.getPropertyValue(name)) || 0;
const contentBox = style.boxSizing === 'content-box';
const width =
px('width') +
(contentBox
? px('padding-left') +
px('padding-right') +
px('border-left-width') +
px('border-right-width')
: 0);
const height =
px('height') +
(contentBox
? px('padding-top') +
px('padding-bottom') +
px('border-top-width') +
px('border-bottom-width')
: 0);
clone.style.cssText = `position:absolute;left:${target.offsetLeft}px;top:${target.offsetTop}px;width:${width}px;height:${height}px;box-sizing:border-box;margin:0;padding:0;border:0;visibility:hidden;pointer-events:none;transform-origin:${style.transformOrigin};transform-box:${style.transformBox}`;
// A geometry property no run animates keeps the element's own value.
for (const name of geometry) {
if (!runs.some(a => keyframesOf(a).some(k => name in k))) {
clone.style.setProperty(name, style.getPropertyValue(name));
}
}
const chip = target.querySelector(
':scope > [data-harness-marker-chip]',
);
let read: Element = clone;
if (chip instanceof HTMLElement) {
const copy = document.createElement('div');
copy.style.cssText = chip.style.cssText;
clone.append(copy);
read = copy;
}
target.parentElement.append(clone);
const replays = runs.map(a => {
const replay = clone.animate(
keyframesOf(a).map(k => {
const {computedOffset, ...rest} = k as ComputedKeyframe;
return {...rest, offset: computedOffset};
}),
(a.effect as KeyframeEffect).getTiming(),
);
replay.pause();
return {
replay,
source: a,
origin: realStart(a),
rate: a.playbackRate,
};
});
const seek = (t: number) => {
for (const {replay, origin, rate} of replays) {
replay.currentTime = (t - origin) * rate;
}
};
// Aligned once: each replay at its own animation's current time,
// which the element's own box is read at, then the clone moved by
// what remains. The cast's frame at rest checks the replay.
for (const {replay, source} of replays) {
replay.currentTime = source.currentTime;
}
const unaligned = boxOf(read);
const actual = boxOf(chip ?? target);
clone.style.left = `${target.offsetLeft + actual[0] - unaligned[0]}px`;
clone.style.top = `${target.offsetTop + actual[1] - unaligned[1]}px`;
const check = {predicted: boxOf(read), actual};
const samples: Array<[number, number, number, number, number]> = [];
for (let t = fromMs; t <= toMs; t += 2) {
seek(t);
samples.push([t, ...boxOf(read)]);
}
for (const {replay} of replays) {
replay.cancel();
}
clone.remove();
return {geometry: samples, check};
}
// One numeric channel: the one that changes the most, for its size.
const keyframes = keyframesOf(caught);
const meta = new Set([
'offset',
'computedOffset',
'easing',
'composite',
]);
const numbers = (value: unknown): number[] =>
(
String(value).match(/-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi) ?? []
).map(Number);
let channel: {
key: string;
index: number;
first: number;
last: number;
} | null = null;
let largest = 0;
for (const key of Object.keys(keyframes[0] ?? {})) {
if (meta.has(key)) {
continue;
}
const values = keyframes.map(k =>
numbers((k as Record<string, unknown>)[key]),
);
const width = Math.min(...values.map(v => v.length));
for (let index = 0; index < width; index += 1) {
const first = values[0][index];
const last = values[values.length - 1][index];
const size =
Math.abs(last - first) /
Math.max(Math.abs(first), Math.abs(last));
if (last !== first && size > largest) {
largest = size;
channel = {key, index, first, last};
}
}
}
if (channel == null || effect == null) {
return {};
}
const {key, index, first, last} = channel;
const name = '--harness-busy-progress';
try {
CSS.registerProperty({
name,
syntax: '<number>',
inherits: false,
initialValue: '0',
});
} catch {
// An earlier block registered it.
}
const probe = document.createElement('div');
probe.setAttribute('aria-hidden', 'true');
probe.style.cssText =
'position:fixed;left:0;top:0;width:0;height:0;visibility:hidden;pointer-events:none';
document.body.append(probe);
const replay = probe.animate(
keyframes.map(k => ({
offset: (k as ComputedKeyframe).computedOffset,
easing: k.easing,
[name]: String(
(numbers((k as Record<string, unknown>)[key])[index] - first) /
(last - first),
),
})),
{...effect.getTiming(), fill: 'both'},
);
replay.pause();
const origin = realStart(caught);
const progress: Array<[number, number]> = [];
for (let t = fromMs; t <= toMs; t += 2) {
replay.currentTime = (t - origin) * caught.playbackRate;
progress.push([
t,
Number(getComputedStyle(probe).getPropertyValue(name)),
]);
}
replay.cancel();
probe.remove();
return {progress};
};
// The animations that counted at the frame before, pending ones too.
let seen = new Set<Animation>();
const tick = () => {
const present = element.getAnimations({subtree: true}).filter(counts);
const ran = present.filter(
a =>
a.playState === 'running' &&
!a.pending &&
Number(a.currentTime ?? 0) >= minProgress,
);
// Still moving: before its curve's held tail. One running backward
// ends at its start, so it moves while it runs.
const moves = (a: Animation) =>
a.playbackRate < 0 || Number(a.currentTime ?? 0) < curveEnd(a);
const running = ran.some(moves);
// One first seen this frame can be rebuilt on its old clock, and not
// on the compositor yet: the block waits for the next frame.
const caught = ran.find(a => moves(a) && seen.has(a));
seen = new Set(present);
if (!running && ran.length > 0) {
heldSeen ??= numbersOf(ran[0]);
}
// In its held tail: started while the page waited, or, when the
// wait times out, what is left there or the first such run it saw.
const late = ran.find(a => !before.has(a));
const timedOut = realNow() > deadline;
const leftover = ran.length > 0 ? numbersOf(ran[0]) : heldSeen;
if (caught != null) {
const startTime = caught.startTime;
// A start time is a page time. It trails the real clock, which the
// window reads, by every span a page freeze stood still.
const frozen =
(window as unknown as {__harnessFreeze?: {offset: number}})
.__harnessFreeze?.offset ?? 0;
const from = performance.timeOrigin + Number(startTime) + frozen;
// Whether the element keeps the curve's end value once it ends. A
// held tail past the curve keeps it, and so does a fill the
// compositor honors. An end delay shows nothing.
const timing = caught.effect?.getComputedTiming();
const keyframesEnd =
Number(timing?.delay ?? 0) + Number(timing?.activeDuration ?? 0);
const holds =
curveEnd(caught) < keyframesEnd ||
(fillHolds &&
(timing?.fill === 'forwards' || timing?.fill === 'both'));
const animation =
startTime != null && caught.playbackRate > 0
? {
from,
to: from + curveEnd(caught) / caught.playbackRate,
holds,
}
: undefined;
// The same loop as above, from a task queued in the frame that saw
// the animation: it runs once that frame's rendering update has
// handed the animation to the compositor.
later(() => {
const read = realNow;
const start = read();
let now = start;
while (now - start < duration) {
now = read();
}
const blockFrom = performance.timeOrigin + start;
const blockTo = performance.timeOrigin + now;
const controlStarts = (
window as unknown as {__harnessControlStarts?: number[]}
).__harnessControlStarts;
resolve({
from: blockFrom,
to: blockTo,
spanMs: now - start,
...(controlStarts?.[0] == null
? {}
: {
controlStarts: [controlStarts[0], controlStarts[1]] as [
number,
number?,
],
}),
...(animation == null
? {}
: {
animation: {
...animation,
...replayOf(
caught,
blockFrom - look,
Math.min(blockTo, animation.to) + look,
),
},
}),
});
}, 0);
} else if (running) {
if (timedOut) {
reject(
new Error(
'blockMainThread: no animation of `during` ran on two frames in a row',
),
);
} else {
frame(tick);
}
} else if (late != null) {
reject(tooLate(numbersOf(late)));
} else if (timedOut && leftover != null) {
reject(tooLate(leftover));
} else if (timedOut) {
reject(new Error('blockMainThread: no animation started'));
} else {
frame(tick);
}
};
frame(tick);
}),
{
duration: ms,
minProgress,
prop: property ?? null,
pseudo: pseudoElement ?? null,
wait: timeout,
fillHolds,
look: BUSY_PROOF_LOOKAROUND_MS,
},
);
try {
const [, held] = await Promise.all([defined, waited]);
return held;
} catch (error) {
const late = /BusyWindowTooLate (\{.*\})/.exec(
error instanceof Error ? error.message : String(error),
);
if (late == null) {
throw error;
}
const numbers = JSON.parse(late[1]) as {
currentTimeMs: number;
curveEndMs: number;
startedWhileWaiting: number;
};
throw new BusyWindowTooLateError(
`blockMainThread: the animation under test was ${numbers.currentTimeMs.toFixed(0)} ms in, past the end of its curve at ${numbers.curveEndMs.toFixed(0)} ms, when the page ${numbers.startedWhileWaiting ? 'first saw it' : 'gave up waiting for one that moves'}: its motion had ended, so a block now holds nothing to judge. Call blockMainThread before the action that starts the motion, and await it after.`,
numbers,
);
}
}
export interface BusyVerdict {
readonly pass: boolean;
/** Each criterion the window missed, with its measured value and limit. */
readonly failures: readonly string[];
}
export interface BusyProof extends FrameStats {
readonly window: BusyWindow;
/**
* The part of the window judged: inside the margins, up to `settledWithin`,
* and from `onScreenFromMs` when that is set. On a cast dated on the
* controls' clock, it runs from the cast's stamp of the first frame judged
* to that of the last. So a caller selects the judged part by its stamps.
* In WebKit, frames the display-rate keep left out fall inside it too.
* Only this part moves back to the stamps. The summary's times, its stall
* and its control read stay on the controls' clock.
*/
readonly judged: {readonly from: number; readonly to: number};
/**
* The ms after the window's start of the tracked value's first presented
* change inside the block, where judging starts. It is set when the value
* was seen at rest before the judged part: a frame there, and no change in
* the `BUSY_PROOF_LOOKAROUND_MS` before it. That is a just-started animation
* not on screen yet. Otherwise it is null.
*/
readonly onScreenFromMs: number | null;
/**
* The cast's position step, CSS px: the largest of 0.5, 1 and 2 that every
* change of the tracked value in the judged part is a multiple of, or 0.5
* when it does not change there (WebKit's casts step 2: see the README).
* A sub-pixel read (`trackMarker` with `subpixel`) uses its own step.
*/
readonly stepPx: number;
/** The tracked value's mean motion per screencast interval in the judged part, px. */
readonly pxPerFrame: number;
/** Facts worth reading beside the verdict, which never fail it. */
readonly notes: readonly string[];
/**
* With a compositor record (`presented`): frames the screencast skipped
* between two moved frames while the compositor presented them, which are
* neither stalls nor misses; 0 without one.
*/
readonly recorderSkipped: number;
/**
* The compositor's frame interval around the window, ms, from `presented`;
* null without a usable record (the screencast alone is judged).
*/
readonly compositorFrameMs: number | null;
/**
* The screencast's frame interval, from the frames around the window as well
* as inside it (a short window has few intervals; a frozen one has none).
*/
readonly cadenceMs: number;
/**
* Whole frame intervals in the judged part at the measured cadence (the
* compositor's, when recorded): the `minJudgedFrames` floor reads it.
*/
readonly expectedFrames: number;
/** Frames the screencast delivered in the judged part, with the marker found. */
readonly deliveredFrames: number;
/**
* Longest time inside the window with no presented change, the window's own
* edges included. A frozen animation presents no new frame at all (nothing
* on screen changed, so the compositor sends none): its stall is the whole
* window.
*/
readonly longestStallMs: number;
/** Where the longest stall starts, ms after the window's start. */
readonly longestStallAtMs: number;
/**
* `longestStallMs` in screencast intervals, rounded: 1 is no frame missed,
* 2 is one dropped frame. Rounding absorbs timestamp jitter.
*/
readonly longestStallFrames: number;
/**
* Frames in the window that presented a new position (the first compared
* with the last frame before the window).
*/
readonly moved: number;
/**
* `moved` (and `recorderSkipped`) over the frames judged: the frames the
* screencast delivered in the judged part, or with a compositor record the
* compositor's frames from the first to the last moved frame;
* `expectedFrames` when nothing moved, or fewer than `minJudgedFrames`
* frames were delivered.
*/
readonly movedFraction: number;
/** With a `control`: what it presented in the judged part; null without one. */
readonly control: BusyControlRead | null;
/**
* The control's frames too little to judge: the component's predicted move
* there fell under one cast step (see `busyWindowProof`).
*/
readonly unjudged: readonly UnjudgedFrame[];
/** The judgment against the limits (see `busyWindowProof`). */
readonly verdict: BusyVerdict;
/** One line with the raw numbers, for an annotation or a failure message. */
readonly summary: string;
}
/**
* The stretches of a judged series that move under `limitPx` per frame,
* read over four frames at a time, merged where they overlap: where the cast
* cannot show a step on every frame.
*/
function slowStretches(
values: readonly {t: number; value: number}[],
cadence: number,
limitPx: number,
): {from: number; to: number; pxPerFrame: number}[] {
const SPAN = 4;
const stretches: {from: number; to: number; pxPerFrame: number}[] = [];
for (let k = 0; k + SPAN < values.length; k += 1) {
const a = values[k];
const b = values[k + SPAN];
const frames = (b.t - a.t) / cadence;
const pxPerFrame = frames > 0 ? Math.abs(b.value - a.value) / frames : 0;
if (pxPerFrame <= 0 || pxPerFrame >= limitPx) {
continue;
}
const last = stretches[stretches.length - 1];
if (last != null && a.t <= last.to) {
last.to = b.t;
last.pxPerFrame = Math.min(last.pxPerFrame, pxPerFrame);
} else {
stretches.push({from: a.t, to: b.t, pxPerFrame});
}
}
return stretches;
}
/**
* The cast's position step along `axis`, CSS px, read from the cast: the
* coarsest `step` the tracked frames carry (`trackMarker` sets it from each
* frame's color resolution and scale, for the default marker only), so 2 px
* in WebKit's 4:2:0 JPEG cast and 1 px in Chromium's PNG cast. Throws when no
* frame carries one, as for a control tracked by another color: a step read
* from the motion would take a run whose changes are all even on a 1 px cast
* for a 2 px cast.
*/
export function castStep(
tracked: readonly TrackedFrame[],
axis: 'x' | 'y' | 'width' | 'height',
): number {
const key = axis === 'x' || axis === 'width' ? 'x' : 'y';
const steps = tracked.flatMap(f => (f.step == null ? [] : [f.step[key]]));
if (steps.length === 0) {
throw new Error(
"castStep: no tracked frame carries the cast's step (trackMarker sets it)",
);
}
return Math.max(...steps);
}
/** Frames too little to judge, as a summary or a failure names them. */
function unjudgedList(frames: readonly UnjudgedFrame[]): string {
return frames
.map(frame =>
frame.why === 'clock'
? `+${frame.atMs.toFixed(0)} ms, no control reading dates it`
: `+${frame.atMs.toFixed(0)} ms, a predicted ${frame.movePx.toFixed(2)} under the ${frame.stepPx} step`,
)
.join('; ');
}
/** A sampled curve read at any time, linear between samples, held at its ends. */
function sampled(
points: ReadonlyArray<readonly [number, number]>,
): (t: number) => number {
return t => {
if (t <= points[0][0]) {
return points[0][1];
}
const last = points[points.length - 1];
if (t >= last[0]) {
return last[1];
}
let lo = 0;
let hi = points.length - 1;
while (hi - lo > 1) {
const mid = (lo + hi) >> 1;
if (points[mid][0] <= t) {
lo = mid;
} else {
hi = mid;
}
}
const [t0, v0] = points[lo];
const [t1, v1] = points[hi];
return v0 + ((v1 - v0) * (t - t0)) / (t1 - t0);
};
}
/**
* What the component should show at each time, from the animation
* `blockMainThread` caught and replayed (`BlockedWindow.animation`). Null
* when the window holds no replay to read. Throws `BusyPredictionError` when
* the replay could not be read, or its end check disagrees with the element
* by more than one cast step. A replay that disagrees with the cast gives a
* `fallback` reason instead: its travel, its first judged position, or a
* fade's fit against its anchors.
*/
function predictionOf(
tracked: readonly TrackedFrame[],
axis: 'x' | 'y' | 'width' | 'height',
window: BusyWindow,
judged: {from: number; to: number},
stepPx: number,
settledAt: number | undefined,
): ((t: number) => number) | {readonly fallback: string} | null {
const animation = (window as BlockedWindow).animation;
if (animation == null) {
return null;
}
if (animation.unpredictable != null) {
throw new BusyPredictionError(
`${animation.unpredictable}. The window is not judged.`,
);
}
const column = {x: 0, y: 1, width: 2, height: 3}[axis];
const shown = tracked.flatMap(f =>
f.box == null ? [] : [{t: f.t, value: f.box[axis]}],
);
const geometry = animation.geometry;
if (geometry != null && geometry.length > 1) {
const value = sampled(
geometry.map(sample => [sample[0], sample[1 + column]]),
);
const check = animation.check;
if (
check != null &&
Math.abs(check.predicted[column] - check.actual[column]) > stepPx
) {
throw new BusyPredictionError(
`the replay drifted from the element: at the block's end it read ${check.predicted[column].toFixed(2)} for the ${axis}, the element ${check.actual[column].toFixed(2)}. The window is not judged.`,
);
}
// Over the judged part, the replay sits and moves as the cast does, to
// within two steps or a tenth of the travel. A replay of another element,
// or of a run the element no longer follows, sits or moves another way.
const judgedShown = shown.filter(
f => f.t >= judged.from && f.t <= judged.to,
);
const first = judgedShown[0];
const last = judgedShown.at(-1);
if (first != null && last != null && last !== first) {
const castTravel = last.value - first.value;
const allowed = Math.max(2 * stepPx, Math.abs(castTravel) / 10);
const replayTravel = value(last.t) - value(first.t);
if (Math.abs(replayTravel - castTravel) > allowed) {
return {
fallback: `over the judged part the replay moved ${replayTravel.toFixed(2)} for the ${axis}, the cast ${castTravel.toFixed(2)}`,
};
}
if (Math.abs(value(first.t) - first.value) > allowed) {
return {
fallback: `at the first judged frame the replay read ${value(first.t).toFixed(2)} for the ${axis}, the cast ${first.value.toFixed(2)}`,
};
}
}
return value;
}
if (animation.progress != null && animation.progress.length > 1) {
const progress = sampled(animation.progress);
// Anchored on frames outside the judged part: the value at rest before
// the motion, and where it ends. Frames judged never shape their own
// prediction.
const start = shown.filter(f => f.t <= animation.from).at(-1)?.value;
const end =
settledAt ?? shown.filter(f => f.t >= animation.to).at(-1)?.value;
if (start == null || end == null) {
return null;
}
const value = (t: number) => start + (end - start) * progress(t);
// A least-squares fit of the same curve checks the anchors.
const points = shown.map(f => [progress(f.t), f.value] as const);
const meanP = points.reduce((sum, [p]) => sum + p, 0) / points.length;
const meanV = points.reduce((sum, [, v]) => sum + v, 0) / points.length;
const spread = points.reduce((sum, [p]) => sum + (p - meanP) ** 2, 0);
if (spread > 0) {
const slope =
points.reduce((sum, [p, v]) => sum + (p - meanP) * (v - meanV), 0) /
spread;
const worst = Math.max(
...shown
.filter(f => f.t >= judged.from && f.t <= judged.to)
.map(f =>
Math.abs(meanV + slope * (progress(f.t) - meanP) - value(f.t)),
),
);
// A component that holds or skips bends the fit too, so a mismatch
// falls back to the cast-step rule, which judges that hold.
if (worst > stepPx) {
return {
fallback: `the fade's fit and its anchors disagree by ${worst.toFixed(2)}, more than one step (${stepPx}), so the component may have held`,
};
}
}
return value;
}
return null;
}
/**
* The step a tracked value's changes share: the largest of 2, 1 and 0.5 CSS
* px that every change between consecutive positions is a multiple of.
* Changes rather than positions: a position the page commits once a block
* ends can sit off that grid. With no change to read, the finest step: a
* coarser one would let a larger jump pass for a single step.
*/
function motionStepPx(values: readonly number[]): number {
const changes = values
.slice(1)
.map((p, i) => Math.abs(p - values[i]))
.filter(d => d > 0.25);
return changes.length === 0
? 0.5
: ([2, 1, 0.5].find(step =>
changes.every(d => Math.abs(d / step - Math.round(d / step)) < 0.01),
) ?? 0.5);
}
/**
* Frame evidence for a busy window: how many frames the screencast presented
* inside it, how many of them moved the tracked axis, and the longest stall.
* The window is trimmed by `marginMs` at both ends so the frame the block
* started on and the one it ended on are not counted.
*
* The verdict judges the frames the screencast delivered, whatever its rate
* (a loaded machine's screencast can deliver one frame in five or six), and
* tolerates nothing a main-thread animation does (it presents no frame for
* the whole block). It passes when:
* - the judged part presented at least one frame, and, only when a proof
* claims display rate and passes `maxMedianFrameMs`, their median interval
* is at most that;
* - no stall spans more than `maxStallFrames` screencast intervals;
* - at least `minMovedFraction` of the frames judged moved the tracked axis
* (a short window may still miss one): the frames the screencast delivered
* in the judged part, so an irregular cast is judged on what it delivered
* and a frame it did not deliver is a gap for the stall check, not a miss
* (unless it delivered fewer than `minJudgedFrames` there: then every frame
* of the judged part's span counts, so one late frame is not 1/1 moved);
* with a compositor record, the compositor's frames from the first to the
* last moved frame (the gaps before and after are the stall check's);
* - the judged part spans at least `minJudgedFrames` frames. Fewer means the
* animation under test was not moving during the block (it settled before
* the block, or the block caught another animation), so there is nothing to
* judge, and that fails rather than passes.
*
* With `window.animation` (`blockMainThread`'s `during`), the judged part
* can end at the held curve's end, when that comes before the block's. It
* does unless the element keeps the end value (`holds`), or a settle bound
* (`settledWithin`, `settledWithinSteps`) already ends judging. Once a
* compositor animation that keeps no end value ends inside a block, WebKit
* presents the value the main thread last committed, not the animation. If
* the part left gives the control fewer than `minJudgedFrames` frames, the
* block started late for the motion. Without a control, the part's span
* counts. That throws `BusyWindowTooLateError`, as a motion that settled
* before the block does. A stall before the curve's end is still judged, and
* fails.
*
* A just-started animation can reach the screen after the block began (its
* hand-off to the compositor lags under load: 50–100 ms in WebKit). The
* tracked value may be seen at rest before the judged part: a frame there, and
* no change in the `BUSY_PROOF_LOOKAROUND_MS` before it. Judging then starts at
* its first presented change inside the block, which the
* proof reports as `onScreenFromMs`. So does a hold that starts before the
* block (two frames at least at one position, the first before it) and ends
* at the first presented change inside it: WebKit presents a just-started
* compositor animation late (a sheet's release held on screen for 130 to
* 300 ms while its timeline ran, and the screencast reaches Node about 0.7 s
* late on a loaded runner, too late to wait on before blocking). Chromium on
* a loaded runner does too. A slider's coast first showed 25–111 ms after
* its start (median 57 ms), with a catch-up on that first frame. Only a hold
* at `setBeforeBlock`, the value the page itself last set before the block,
* is excused. Without it, a window with a caught animation takes the value on
* the cast's last frame before that animation's start. Every frame after that
* first change is judged, so a freeze later in the block fails.
* An element off screen before the judged part is judged from its first
* position inside the part, as a card that enters from an edge. The cast's
* frames before the part must show the screen without it. A main-thread
* entrance shows no frame during the block, so it still fails.
* The judged part still ends with the block, or with the held curve. The
* `minJudgedFrames` floor applies to it, so a start the block itself delays
* fails. Any other animation that was already moving is judged from the
* block's start, and a stall there fails as before.
*
* `stepPx` and `pxPerFrame` say whether a frame's motion is resolvable at
* all: under two position steps per frame, a frame delivered early can show
* no step and read as not moved. The proof notes each stretch of the judged
* part that moves that slowly, read over four frames at a time so a slow tail
* inside a fast window shows (never a failure).
*
* A loaded machine's screencast can skip frames the compositor still presents
* (Chromium). Given the compositor's record (`presented`, from
* `startCompositorTrace`), a gap between two moved frames with no frame
* delivered inside it is measured between the compositor's own frames: it is
* a stall only where the compositor presented nothing, and the frames it did
* present there are neither stalls nor misses (`recorderSkipped`). A gap
* that opens or closes the judged part, or holds a delivered frame that did
* not move, is judged from the screencast as before, so a frozen element
* fails whatever else the compositor draws.
*
* With a `control` (`startBusyControl`'s box, tracked from the same
* screencast), the window is judged against what the compositor presented in
* it rather than against a frame rate: on a two-core runner the software
* compositor and the screencast share the core the block spins on, so every
* compositor animation presents fewer frames there, the control too. The
* component passes when:
* - the control moved on at least `minJudgedFrames` frames of the judged part
* (fewer: the compositor presented too little to judge, as below);
* - the component moved on every frame the control moved: both are read from
* the same screencast frames, so a compositor animation misses none;
* - its longest stall is no longer than the control's.
* A run of frames with no new component position counts as moved when the
* change that ends it is a single cast step (`stepPx`): the component moves
* under one step per frame there, as on an easing tail, which the cast cannot
* show on every frame. Where the component moved under two steps per frame
* over the frames just before the run, or across the run itself (its
* catch-up over the frames it spans) where the curve slows faster than those
* frames show, a frame delivered early can show no step too, so the change
* may carry the motion of every frame the run held at that pace, to the
* nearest step. The run also has to read as a slowing
* curve, at most one frame longer than the component's run before it.
* Under `settledWithinSteps`, a run under one cast step a frame may instead
* last ceil(step ÷ travel) frames, whatever the run before it. The travel is
* the slower moving pace around the run, never less than its own catch-up
* per frame. The run also lasts at most one frame more than the pace into it
* allows: ceil(step ÷ max(pace before, catch-up per frame)) + 1. A
* freeze ends in a larger catch-up, a stall in a frame-counted animation is
* longer than its runs before it, and a run that no change ends stays a miss.
* The component still has to show a new position on at least
* `minJudgedFrames` of the control's frames.
* A main-thread animation still fails: the control moves and it does not.
* `maxMedianFrameMs`, when given, still applies; `minMovedFraction` and the
* absolute stall, frame and motion limits do not.
*
* A WebKit cast with a control is judged on the controls' clock, not on its
* stamps. WebKit stamps the frame after a delivery gap about 60 ms late,
* carrying one frame of motion. So each frame takes its time from the
* controls' positions (`controlClock`), the component's and the control's
* alike. A frame with no reading keeps its stamp's distance from the nearest
* frame whose stamp agrees with its reading. The dated frames keep the cast's
* order. Without the control `ahead`, a late frame near the first control's
* turn keeps its lateness. A Chromium cast with a control is dated the same
* way. Its cast stamps each frame as it arrives. Under load, the stamps
* trail the frames unevenly, so the frame interval read from them is wrong.
* Two frames a whole frame apart can carry stamps 2 ms apart. Without the
* control `ahead`, such a pair near the first control's turn keeps its
* stamps. Only frames that carry their engine, as `trackMarker` reads them,
* are dated. Frames built without it, and a cast with no control, are judged
* on their stamps.
*
* A WebKit proof keeps one dated frame per display interval, the earlier
* one. A frame with no reading always stays. The proof judges motion on every
* kept frame the control moved. Its cast rarely shows two frames one interval
* apart, so it judges no 30 Hz cadence. A note in the summary says so, with
* the count of such pairs.
*
* With a control, a window whose control moved on fewer than
* `minJudgedFrames` frames of the judged part is under the floor. Under the
* floor, a run with no component failure on the frames shown is too little to
* judge. It throws `FrameStarvationError` and returns no verdict. The error
* names the control's moves, the floor, the cast's frames in the block and its
* longest gap. A component that missed a frame the control moved on, or
* stalled longer than it, failed on frames the compositor presented. The
* verdict keeps that red, unless the machine starved the run: no frame for
* longer than `FRAME_STARVATION_MS`. `maxMedianFrameMs` judges the cast's
* pace, not the component, so under the floor it keeps no red. Without a
* control, a block with no frame is a frozen animation's, and it fails the
* verdict. `pooledBusyProof` reads each run without the throw and judges the
* runs together.
*
* With a prediction, each frame the control moved on is judged by the
* component's own predicted move since its last new position. The prediction is
* the caller's (`predicted`), or the animation `blockMainThread` caught,
* replayed once the loop ended (`window.animation`). A replay predicts in
* Chromium when the proof passes the `ahead` control. A geometry replay also
* needs the harness marker on the caught element. A move of one cast step or
* more always changes the cast's reading, whatever the pixel phase. So such a
* frame must show a new position, with no run excused. A predicted move under
* one step may show none: that frame is too little to judge. It is listed in
* `unjudged` and in the summary, and counts neither as moved nor as missed.
* When too few judged frames remain, the proof throws `FrameStarvationError`
* naming them. Where a replay predicts, one it cannot read throws
* `BusyPredictionError`. Every other window falls back by name to the cast-step
* rule above, exactly as without a replay.
*
* With `judgeEveryFrame`, a frame the cast could not show the component's
* step on is too little to judge (the frames `belowStep` counts). When the
* verdict otherwise passes, the proof throws `BusyFrameUnjudgedError` with
* each such frame, the component's move there and the cast's step. A failed
* verdict is returned as it is: it is the component's red. A prediction
* excuses no frame, so then nothing throws: it names such frames instead.
*/
export function busyWindowProof(
...args: Parameters<typeof readBusyWindow>
): BusyProof {
const {proof, starvation, unjudged, componentFailed} = readBusyWindow(
...args,
);
// Under the control's floor, a cast that kept pace still shows a missed
// frame or a longer stall. That failure is the component's red.
if (
starvation != null &&
(starvation.longestGapMs > FRAME_STARVATION_MS || !componentFailed)
) {
throw new FrameStarvationError(starvation);
}
// A failed verdict is the component's red, whatever else the cast hid.
if (unjudged.length > 0 && proof.verdict.failures.length === 0) {
throw new BusyFrameUnjudgedError(unjudged, proof.summary);
}
return proof;
}
/**
* How far around its judged part a busy proof reads frames, ms: the rest
* before it and the frame cadence on both sides. A proof that decodes only
* part of a cast keeps the frames this far after the window.
*/
export const BUSY_PROOF_LOOKAROUND_MS = 250;
/**
* The proof `busyWindowProof` returns, and the starvation it throws. A cast
* with a control, its frames tagged with their engine, is judged on the
* controls' clock (`datedOnControlClock`); any other cast on its stamps.
* WebKit stamps the frame after a delivery gap about 60 ms late, carrying one
* frame of motion. Chromium stamps each frame as it arrives, unevenly behind
* its presentation under load.
*/
function readBusyWindow(
tracked: readonly TrackedFrame[],
window: BusyWindow,
{
ahead,
controlStarts,
...options
}: NonNullable<Parameters<typeof judgeBusyWindow>[2]> & {
/**
* The control started `ahead` (`startBusyControl`), tracked from the same
* screencast (`trackControl` with `ahead`). It dates the frames that
* fall near the first control's turns, where that control gives no time.
*/
ahead?: readonly TrackedFrame[];
/**
* When the first control started, then the one ahead (each
* `startBusyControl`'s `start`). Without them, each control counts from
* the origin that most of its frames' stamps agree with.
*/
controlStarts?: readonly [number, number?];
} = {},
): ReturnType<typeof judgeBusyWindow> {
const {control, predicted} = options;
// A prediction reads each frame at its content's time. The cast's stamps
// trail that time, by 26 to 31 ms at rest in Chromium and unevenly under
// load. So a window with a prediction is dated in every engine.
const animation = (window as BlockedWindow).animation;
const predicts =
predicted != null ||
animation?.geometry != null ||
animation?.progress != null ||
animation?.unpredictable != null;
const fallBack = (why: string) => {
// The replay cannot predict the frames: the cast-step rule judges them
// as if there were no replay, and the notes say why.
const {
from: start,
to: end,
holds,
} = animation ?? {
from: window.from,
to: window.to,
holds: false,
};
const plain: BlockedWindow = {
...(window as BlockedWindow),
animation: {from: start, to: end, holds, notPredicted: why},
};
return readBusyWindow(tracked, plain, {...options, ahead, controlStarts});
};
// WebKit reads the element's box at the loop's end before its animation's
// current time, so the replay cannot be aligned to it there.
if (
animation != null &&
predicted == null &&
predicts &&
tracked.some(frame => frame.engine === 'webkit')
) {
return fallBack(
"the element's box in WebKit lags its animation at the loop's end and cannot align the replay",
);
}
// A prediction reads each frame at its own time, which only a control
// reading gives. Near the first control's turns, only the one ahead reads.
if (
animation != null &&
predicted == null &&
predicts &&
(control == null || ahead == null)
) {
return fallBack(
'the proof starts no ahead control, so a frame near a turn has no time of its own',
);
}
// A prediction is on the page clock, so its frames are dated from the
// controls' own starts. The window keeps them when the options name none.
const starts =
controlStarts ??
(predicts ? (window as BlockedWindow).controlStarts : undefined);
const dated =
control != null &&
(predicts || control.every(frame => frame.engine != null))
? datedOnControlClock(tracked, control, ahead, starts)
: null;
if (dated == null) {
const read = judgeBusyWindow(tracked, window, options);
return read.fallback == null ? read : fallBack(read.fallback);
}
const webkit = control?.every(frame => frame.engine === 'webkit') === true;
const shown = webkit ? atDisplayRate(dated) : dated;
const unread = new Set(
shown.tracked.filter(frame => !shown.readTimes.has(frame.t)),
);
const read = judgeBusyWindow(
shown.tracked,
window,
{...options, control: shown.control},
dated.tracked,
unread,
);
if (read.fallback != null) {
return fallBack(read.fallback);
}
// A WebKit cast rarely shows two frames one interval apart, so the proof
// cannot judge a 30 Hz cadence there. It says so, with the count.
const cadence = webkit
? displayIntervalPairs(shown.tracked, shown.control, read.proof.judged)
: null;
const note =
cadence == null
? null
: `cadence not judged: ${cadence.pairs} display-interval pairs` +
(cadence.unmatched > 0
? `, ${cadence.unmatched} without a control frame at their time`
: '');
return {
...read,
proof: {
...read.proof,
judged: judgedOnStamps(read.proof.judged, shown),
...(note == null
? {}
: {
notes: [...read.proof.notes, note],
summary: `${read.proof.summary}; note: ${note}`,
}),
},
};
}
/** `readBusyWindow` on the frames it judges, dated. */
function judgeBusyWindow(
tracked: readonly TrackedFrame[],
window: BusyWindow,
{
axis = 'y',
marginMs = 20,
settledWithin,
settledWithinSteps,
settledAt,
setBeforeBlock,
maxMedianFrameMs = Infinity,
maxStallFrames = 3,
minMovedFraction = 0.9,
minJudgedFrames = 4,
presented,
control,
judgeEveryFrame = false,
predicted,
}: {
axis?: 'x' | 'y' | 'width' | 'height';
marginMs?: number;
/**
* Opt-in, for a proof that claims display rate: the most the median frame
* interval may be, ms (20 at 60 Hz). Off by default, since it measures the
* screencast's own rate as much as the animation.
*/
maxMedianFrameMs?: number;
/** The most screencast intervals one stall may span (3 = two dropped frames). */
maxStallFrames?: number;
/**
* The least fraction of the expected frames that must move. One missed
* frame is always allowed, so a window of under ten frames is not judged
* stricter than a long one.
*/
minMovedFraction?: number;
/** The fewest whole frame intervals the judged part of the window may span. */
minJudgedFrames?: number;
/**
* Stop judging once the value is within this many px of where it ends.
* The screencast reports whole CSS pixels, so an easing tail that still
* moves shows plateaus (26, 26, 26 against a final 24) that would read
* as a stall: 2 is the usual value.
*/
settledWithin?: number;
/**
* `settledWithin` counted in the cast's own position steps: stop judging
* once the value is within this many steps of where it ends, the step
* read from the cast (`castStep`): 1 px in Chromium's PNG cast, 2 px in
* WebKit's JPEG cast, whose 4:2:0 chroma holds the marker's color in
* 2 by 2 pixel blocks. A coarser cast shows an easing tail's last steps as
* longer plateaus, so a bound in px would read them as a stall in one
* engine and not the other; a freeze further from the end than that is
* still judged. Give this or `settledWithin`, not both.
*/
settledWithinSteps?: number;
/**
* Where the value ends, for `settledWithin`: read it from the page once the
* animation has ended (`waitForRest`). Defaults to the last frame's value,
* which can be stale: once an accelerated animation ends while the main
* thread is still blocked, WebKit presents the layer's last committed
* position until the main thread commits the end state.
*/
settledAt?: number;
/**
* The tracked value the page itself last set before the block, such as a
* drag's last position at its release. It is in the tracked box's
* coordinates: where the box sits at rest, plus the offset the page wrote.
* A hold that starts before the block and ends at its first presented
* change can be a late hand-off. It is one only when it holds this value,
* where the animation starts. Without it, a window that caught an
* animation (`blockMainThread`'s `during`) takes the value on the cast's
* last frame before that animation's start. When the hold shows another
* value, or no value is known, the hold is judged as a stall. An
* animation can freeze at the block's start.
*/
setBeforeBlock?: number;
/**
* When the compositor presented each frame, epoch ms on the page clock
* (`startCompositorTrace`; Chromium). Empty or absent, the screencast is
* judged alone.
*/
presented?: readonly number[];
/**
* The control's frames (`startBusyControl`, tracked from the same
* screencast with `CONTROL_RGB`): judge the component against them.
*/
control?: readonly TrackedFrame[];
/**
* With a control: judge every frame the control moved on by the
* component's own step. A frame the cast could not show that step on
* (`belowStep`) is then too little to judge, and `busyWindowProof` throws
* `BusyFrameUnjudgedError`. Such a frame is never a pass, and never a red
* on the component. With a prediction, no frame is excused, so none
* throws.
*/
judgeEveryFrame?: boolean;
/**
* The tracked value the component should show at an epoch ms (or, after
* a page freeze, on the window's clock). Defaults to the caught
* animation's replay (`window.animation`).
*/
predicted?: (t: number) => number;
} = {},
/**
* The frames the cast drew, dated. In WebKit they are the frames before the
* display-rate keep, so a frame left out never lengthens the cast's gap.
*/
drawn: readonly TrackedFrame[] = tracked,
/** The frames dated from another frame's reading (`datedOnControlClock`). */
unread: ReadonlySet<TrackedFrame> = new Set(),
): {
proof: BusyProof;
starvation: FrameShortfall | null;
/** Under `judgeEveryFrame`, the frames the cast's step excused. */
unjudged: readonly UnjudgedFrame[];
/**
* The component failed on frames the control moved on: it missed one, or
* stalled longer than the control. The cast's median interval is no part
* of it.
*/
componentFailed: boolean;
/** The frames the cast drew in the block, and its longest gap there, ms. */
cast: {frames: number; longestGapMs: number};
/** Why the replay could not predict the frames: the caller judges again. */
fallback?: string;
} {
let end = window.to - marginMs;
if (settledWithin != null && settledWithinSteps != null) {
throw new Error(
'busyWindowProof: give settledWithin or settledWithinSteps, not both',
);
}
// A sub-pixel read (`trackMarker` with `subpixel`) shows changes far under
// a pixel. There a change counts from half its step; on a whole-pixel read,
// from 0.25 px.
const readStepPx = tracked.some(f => f.step != null)
? castStep(tracked, axis)
: null;
const subpixelStepPx =
readStepPx != null && readStepPx < 0.5 ? readStepPx : null;
const epsilon = subpixelStepPx == null ? 0.25 : subpixelStepPx / 2;
// The cast's own position step, for a proof that bounds its settle in it.
const castStepPx =
settledWithinSteps == null ? null : castStep(tracked, axis);
const settledWithinPx =
settledWithinSteps == null || castStepPx == null
? settledWithin
: settledWithinSteps * castStepPx;
if (settledWithinPx != null) {
const valued = tracked.flatMap(f =>
f.box == null ? [] : [{t: f.t, value: f.box[axis]}],
);
const final =
settledAt ?? (valued.length > 0 ? valued[valued.length - 1].value : null);
const arrived = valued.find(
f =>
f.t >= window.from &&
final != null &&
Math.abs(f.value - final) <= settledWithinPx,
);
if (arrived != null) {
end = Math.min(end, arrived.t);
}
// A sparse screencast can deliver the block's first frame after the
// judged part begins. Then the frame before the block shows the settle,
// when it and the block's first frame are both within the bound.
let before: (typeof valued)[number] | undefined;
for (const f of valued) {
if (f.t >= window.from) {
break;
}
before = f;
}
const firstInBlock = valued.find(f => f.t >= window.from);
const settledBy =
arrived != null && arrived.t <= window.from + marginMs
? arrived.t
: before != null &&
arrived != null &&
arrived === firstInBlock &&
final != null &&
Math.abs(before.value - final) <= settledWithinPx
? before.t
: null;
// Within the bound of where it ends before the judged part began: the
// block started after the motion had settled, so the window holds
// nothing to judge. That is when the block ran, not how the component
// moved.
if (settledBy != null) {
const presented = tracked.filter(
f => f.t >= window.from && f.t <= window.to,
).length;
const fromBlock = settledBy - window.from;
const when =
fromBlock < 0
? `${(-fromBlock).toFixed(0)} ms before`
: `${fromBlock.toFixed(0)} ms after`;
throw new BusyWindowTooLateError(
`busyWindowProof: the tracked ${axis} was within ${settledWithinPx} px of where it ends from ${when} the block began, before the judged part began at ${marginMs} ms (${presented} frames presented in the block): the block started after the motion had settled, so there is nothing in it to judge. Start the block earlier.`,
{
settledAtMs: fromBlock,
judgedFromMs: marginMs,
presented,
},
);
}
}
// A held curve that keeps no end value can end inside the block. WebKit's
// compositor then presents the value the main thread last committed, not
// the animation. So the judged part ends at the curve's end, unless a
// settle bound already ends it where the motion arrives.
const heldCurve = (window as Partial<BlockedWindow>).animation;
const curveEnd =
heldCurve?.holds === false && settledWithinPx == null
? heldCurve.to
: undefined;
const endsInBlock = curveEnd != null && curveEnd < end;
const curveTooLate = (framesLeft: number) => {
const presented = tracked.filter(
f => f.t >= window.from && f.t <= window.to,
).length;
const curveEndMs = (curveEnd ?? end) - window.from;
return new BusyWindowTooLateError(
`busyWindowProof: the held animation's curve ended ${curveEndMs.toFixed(0)} ms after the block began, so the part judged from ${marginMs} ms held ${framesLeft} of the frames it needs, ${minJudgedFrames} (${presented} frames presented in the block): the block started late for the motion. Start the block earlier, or play a longer curve.`,
{curveEndMs, judgedFromMs: marginMs, presented},
);
};
// Where judging would end without the curve's end.
const endWithoutCurve = end;
if (curveEnd != null && endsInBlock) {
if (curveEnd <= window.from + marginMs) {
throw curveTooLate(0);
}
end = curveEnd;
}
const inner = {from: window.from + marginMs, to: end};
const values = tracked
.filter(f => f.t >= inner.from && f.t <= inner.to)
.map(f => ({t: f.t, value: f.box == null ? null : f.box[axis]}));
const before = [...tracked].reverse().find(f => f.t < inner.from);
let previous: number | null = before?.box == null ? null : before.box[axis];
const inWindow: number[] = [];
for (const v of values) {
if (
v.value != null &&
previous != null &&
Math.abs(v.value - previous) > epsilon
) {
inWindow.push(v.t);
}
if (v.value != null) {
previous = v.value;
}
}
// Seen at rest before the judged part: a frame there, and no change in the
// `BUSY_PROOF_LOOKAROUND_MS` before it. The first presented change is then
// the animation's on-screen start, and judging starts there. With no frame
// before, nothing is known, and the window is judged from its start.
const prior = tracked.filter(f => f.box != null && f.t < inner.from);
let leadFrom = 0;
prior.forEach((f, i) => {
if (f.t < inner.from - BUSY_PROOF_LOOKAROUND_MS) {
leadFrom = i;
}
});
const lead = prior.flatMap(f => (f.box == null ? [] : [f.box[axis]]));
const movedBefore = lead.some(
(value, i) => i > leadFrom && Math.abs(value - lead[i - 1]) > epsilon,
);
// Held from before the block to its first presented change inside it: in
// WebKit a just-started compositor animation is presented late (a sheet's
// release held on screen for 130 to 300 ms while its timeline ran, and the
// screencast reaches Node about 0.7 s late on a loaded runner, too late to
// wait on before blocking), so a hold that STARTS before the block is the
// engine's, and judging starts at that first change. Only such a hold: from
// that change on every frame is judged, so a freeze later in the block
// still fails. The hold shows on two frames at least, the first before the
// block.
let holdStart = lead.length - 1;
while (
holdStart > 0 &&
Math.abs(lead[holdStart - 1] - lead[lead.length - 1]) <= epsilon
) {
holdStart -= 1;
}
const heldFrames =
lead.length -
holdStart +
values.filter(
v =>
v.value != null &&
v.t < (inWindow[0] ?? -Infinity) &&
Math.abs(v.value - lead[lead.length - 1]) <= epsilon,
).length;
// A late hand-off holds the page's last position. An animation that froze
// at the block's start holds a position of its own. Within one cast step:
// WebKit's cast reads positions on a 2 px grid, so a held position can read
// up to a step off. A cast with no step is read within a pixel, and a
// sub-pixel read within half a pixel.
const matchPx = subpixelStepPx != null ? 0.5 : (readStepPx ?? 1);
// Where the animation starts: the value the page set (`setBeforeBlock`).
// Without it, the caught animation's start dates it: the value on the
// cast's last frame before that start. Unlike the progress replay's
// anchor, a frame that shows no element is not skipped. An earlier value
// can be stale, so the hold then gets no excuse.
const preStart =
setBeforeBlock ??
(heldCurve == null
? undefined
: [...tracked].reverse().find(f => f.t < heldCurve.from)?.box?.[axis]);
const heldFromBeforeBlock =
preStart != null &&
lead.length > 0 &&
holdStart > 0 &&
prior[holdStart].t < window.from &&
heldFrames >= 2 &&
Math.abs(lead[lead.length - 1] - preStart) <= matchPx;
// Off screen before the judged part, as a card that enters from an edge:
// the cast's frames there show the screen without it. Its first position
// inside the part is then its on-screen start, and judging starts there.
// With no frame before at all, nothing is known. A main-thread entrance
// shows no frame during the block, so it has no such position.
const shownWithout = tracked.some(
f =>
f.box == null &&
f.t < inner.from &&
f.t >= inner.from - BUSY_PROOF_LOOKAROUND_MS,
);
const firstShown = values.find(v => v.value != null);
const entersAt =
prior.length === 0 && shownWithout && firstShown != null
? firstShown.t
: null;
const onScreenFrom =
prior.length > 0 &&
(!movedBefore || heldFromBeforeBlock) &&
inWindow.length > 0
? inWindow[0]
: entersAt;
const judged = {from: onScreenFrom ?? inner.from, to: inner.to};
const changes = inWindow.filter(t => t > judged.from || onScreenFrom == null);
const edges = [judged.from, ...changes, judged.to];
const around = tracked
.filter(
f =>
f.t >= inner.from - BUSY_PROOF_LOOKAROUND_MS &&
f.t <= inner.to + BUSY_PROOF_LOOKAROUND_MS,
)
.map(f => f.t);
const intervals = around
.slice(1)
.map((t, i) => t - around[i])
.sort((a, b) => a - b);
const stats = frameStats(
tracked.map(f => ({t: f.t, value: f.box == null ? null : f.box[axis]})),
judged,
epsilon,
);
const cadence =
intervals.length >= 4
? intervals[Math.floor(intervals.length / 2)]
: stats.medianFrameMs || 1000 / 60;
// The compositor's own frames, when recorded: its interval, from the frames
// around the judged part.
const draws = [...(presented ?? [])]
.filter(
t =>
t >= judged.from - BUSY_PROOF_LOOKAROUND_MS &&
t <= judged.to + BUSY_PROOF_LOOKAROUND_MS,
)
.sort((a, b) => a - b);
const drawIntervals = draws
.slice(1)
.map((t, i) => t - draws[i])
.sort((a, b) => a - b);
const compositorFrameMs =
drawIntervals.length >= 4
? drawIntervals[Math.floor(drawIntervals.length / 2)]
: null;
const changed = new Set(inWindow);
const delivered = tracked
.filter(f => f.box != null && f.t > judged.from && f.t < judged.to)
.map(f => f.t);
// Each gap between presented changes, in intervals of the channel that saw
// it: the screencast's, or, for a gap between two moved frames with no
// frame delivered inside it, the compositor's own longest interval there.
const gaps = edges.slice(1).map((to, i) => {
const from = edges[i];
const ms = to - from;
if (
compositorFrameMs == null ||
!changed.has(from) ||
!changed.has(to) ||
delivered.some(t => t > from && t < to)
) {
return {from, ms, frames: Math.round(ms / cadence), skipped: 0};
}
const span = draws.filter(
t => t > from - compositorFrameMs / 2 && t < to + compositorFrameMs / 2,
);
const longest =
span.length >= 2
? Math.min(ms, Math.max(...span.slice(1).map((t, j) => t - span[j])))
: ms;
const frames = Math.round(longest / compositorFrameMs);
return {
from,
ms: longest,
frames,
skipped: Math.max(0, Math.round(ms / compositorFrameMs) - frames),
};
});
const longestGap = gaps.reduce((a, b) =>
b.frames > a.frames || (b.frames === a.frames && b.ms > a.ms) ? b : a,
);
const longestStallMs = longestGap.ms;
// Where the longest stall starts, from the start of the window.
const longestStallAtMs = longestGap.from - window.from;
const longestStallFrames = longestGap.frames;
const skips = gaps.filter(g => g.skipped > 0);
const recorderSkipped = skips.reduce((sum, g) => sum + g.skipped, 0);
// With a compositor record, frames count in its intervals, and the frames
// it presented where the screencast skipped are presented frames.
const expectedFrames = Math.floor(
(judged.to - judged.from) / (compositorFrameMs ?? cadence),
);
const moved = changes.length;
// The frames judged for motion: the screencast's own frames in the judged
// part (each `changes` entry is one of them), or, with a compositor record,
// the compositor's frames from the first to the last moved frame (the gaps
// before and after them are the stall check's). After an on-screen start
// they count from the on-screen frame, which `changes` leaves out, so the
// frames credited as skipped after it are judged too. A part that moved
// nothing, or delivered fewer than `minJudgedFrames` frames, is judged
// against its span, so a frozen animation misses here too (one late frame
// from before the block is not 1/1 moved).
const deliveredFrames = tracked.filter(
f =>
f.box != null &&
(onScreenFrom == null ? f.t >= judged.from : f.t > judged.from) &&
f.t <= judged.to,
).length;
const judgedFrames =
compositorFrameMs != null
? changes.length > 0
? Math.round(
(changes[changes.length - 1] - (onScreenFrom ?? changes[0])) /
compositorFrameMs,
) + (onScreenFrom == null ? 1 : 0)
: expectedFrames
: deliveredFrames < minJudgedFrames
? expectedFrames
: deliveredFrames;
const movedFraction = (moved + recorderSkipped) / Math.max(1, judgedFrames);
// The cast's position step for the tracked value, read from the judged
// part. A sub-pixel read carries its own.
const stepPx =
subpixelStepPx ??
motionStepPx(
tracked.flatMap(f =>
f.box != null && f.t >= judged.from && f.t <= judged.to
? [f.box[axis]]
: [],
),
);
const judgedValues = tracked.flatMap(f =>
f.box != null && f.t >= judged.from && f.t <= judged.to
? [{t: f.t, value: f.box[axis]}]
: [],
);
const first = judgedValues[0];
const last = judgedValues[judgedValues.length - 1];
const pxPerFrame =
first == null || last == null || last.t <= first.t
? 0
: Math.abs(last.value - first.value) / ((last.t - first.t) / cadence);
const notes: string[] = [];
const notPredicted = (window as BlockedWindow).animation?.notPredicted;
if (notPredicted != null) {
notes.push(
`no prediction: ${notPredicted}, so the cast-step rule judges each frame`,
);
}
if (presented != null && compositorFrameMs == null) {
notes.push(
'no compositor frames recorded around the window: judged from the screencast alone',
);
}
if (recorderSkipped > 0) {
notes.push(
`the screencast skipped ${recorderSkipped} frames the compositor presented (at ${skips.map(g => `+${(g.from - window.from).toFixed(0)} ms`).join(', ')})`,
);
}
// Read over a few frames at a time, not the whole part: a fast window can
// end in a slow tail whose frames the cast cannot all show.
for (const stretch of slowStretches(judgedValues, cadence, 2 * stepPx)) {
notes.push(
`${stretch.pxPerFrame.toFixed(1)} px/frame is under two of the cast's ${stepPx} px position steps from +${(stretch.from - window.from).toFixed(0)} ms to +${(stretch.to - window.from).toFixed(0)} ms: a frame delivered early there can show no step and read as not moved`,
);
}
// The control's own new positions in the judged part, against its frame
// before the part, and of those the frames the component moved on too:
// both are tracked from the same screencast frames, so their times match.
// The times of the control's new positions in the judged part, up to `to`.
const controlChangesUpTo = (
frames: readonly TrackedFrame[],
to: number,
): number[] => {
const baseline = [...frames]
.reverse()
.find(f => f.box != null && f.t < inner.from);
let last: number | null = baseline?.box == null ? null : baseline.box.x;
const changes: number[] = [];
for (const f of frames) {
if (f.box == null || f.t < inner.from || f.t > to) {
continue;
}
if (last != null && Math.abs(f.box.x - last) > 0.25) {
if (f.t > judged.from || onScreenFrom == null) {
changes.push(f.t);
}
}
last = f.box.x;
}
return changes;
};
let controlRead: BusyControlRead | null = null;
// The cast step a predicted move is judged against: the coarser of the
// motion's own step and the frames' own (`castStep`).
const judgeStepPx = Math.max(
stepPx,
tracked.some(f => f.step != null) ? castStep(tracked, axis) : 0,
);
const prediction =
predicted ??
predictionOf(
tracked.filter(f => !unread.has(f)),
axis,
window,
judged,
judgeStepPx,
settledAt,
);
if (prediction != null && typeof prediction !== 'function') {
return {
proof: null as unknown as BusyProof,
starvation: null,
unjudged: [],
componentFailed: false,
cast: {frames: 0, longestGapMs: 0},
fallback: prediction.fallback,
};
}
const predictedAt = prediction;
// With a prediction, the frames it names as too little to judge.
const named: UnjudgedFrame[] = [];
// Without one, under `judgeEveryFrame`: the frames the cast's step excused.
let unjudged: UnjudgedFrame[] = [];
if (control != null) {
const controlChanges = controlChangesUpTo(control, judged.to);
const controlEdges = [judged.from, ...controlChanges, judged.to];
// A frame with no new component position, in a run of such frames whose
// next change the cast's step or an early frame explains (`underStep`):
// the cast cannot show every frame there, so the frame counts as moved.
// A freeze ends in a larger catch-up, and a run that no change ends stays
// a miss.
const series = tracked.flatMap(f =>
f.box == null ? [] : [{t: f.t, value: f.box[axis], frame: f}],
);
const seriesIndex = new Map(series.map((f, i) => [f.t, i]));
const same = (a: number, b: number) =>
Math.abs(series[a].value - series[b].value) <= epsilon;
// The first frame of the run of equal positions that holds frame i.
const runStart = (i: number): number => {
let s = i;
while (s > 0 && same(s - 1, i)) {
s -= 1;
}
return s;
};
// The first frame after that run: the change that ends it, or the
// series' length when no change does.
const runEnd = (i: number): number => {
let k = i + 1;
while (k < series.length && same(k, i)) {
k += 1;
}
return k;
};
// The component's motion per frame over up to four frames before frame
// `start`, or null with fewer than two to read.
const pxPerFrameBefore = (start: number): number | null => {
const back = Math.min(4, start);
if (back < 2) {
return null;
}
const frames = (series[start].t - series[start - back].t) / cadence;
return frames > 0
? Math.abs(series[start].value - series[start - back].value) / frames
: null;
};
// The component's motion per frame over up to four frames after frame
// `end`, or null with fewer than two to read.
const pxPerFrameAfter = (end: number): number | null => {
const ahead = Math.min(4, series.length - 1 - end);
if (ahead < 2) {
return null;
}
const frames = (series[end + ahead].t - series[end].t) / cadence;
return frames > 0
? Math.abs(series[end + ahead].value - series[end].value) / frames
: null;
};
const underStep = (t: number): boolean => {
const i = seriesIndex.get(t);
if (i == null || changed.has(t)) {
return false;
}
const start = runStart(i);
const k = runEnd(i);
if (k >= series.length) {
return false;
}
const unchanged = k - 1 - start;
// Under one step a frame the change that ends the run is a single step.
// Under two, a frame delivered early can also show no step. The change
// then carries the motion of every frame the run held, to the nearest
// step, at the pace before the run or across it. An early frame hides
// one frame's motion. At one step a frame or more, the run is one frame
// long. Under one step a frame, it adds at most one step to the
// catch-up.
const catchUp = Math.abs(series[k].value - series[i].value);
// Two readings give the pace at the run, and either can explain the
// run. One is the component's motion over the frames before the run.
// The other is its catch-up across the run itself, from the run's start
// to the change. The run's own reading counts where the curve slows
// faster than the frames before it show. It also counts where a loaded
// runner stamps those frames unevenly, whatever the settle bound. A
// freeze still fails. Its run is longer than one frame at a step a frame
// or more. At a steady pace of two steps a frame, its catch-up carries
// two frames of that pace.
const paceBefore = pxPerFrameBefore(start);
const runFrames = (series[k].t - series[start].t) / cadence;
const explains = (pace: number | null): boolean =>
pace != null &&
pace < 2 * stepPx &&
(pace < stepPx ? catchUp < 2.5 * stepPx : unchanged <= 1) &&
catchUp <= (unchanged + 1) * pace + stepPx;
const shown =
catchUp < 1.5 * stepPx ||
explains(paceBefore) ||
(paceBefore != null && runFrames > 0 && explains(catchUp / runFrames));
if (!shown) {
return false;
}
// Under one step a frame, a proof that bounds its settle in the cast's
// own steps reads the run against the cast: the position changes about
// every step ÷ pace frames, so a run shows one position for at most
// ceil(step ÷ pace) frames, and a frame delivered early adds one. Only a
// longer run is a stall, whatever the run before it was.
// Here the pace is the travel at the run. It is the slower of the moving
// paces around it, and never less than the run's catch-up per frame. A pace of 0 after the change is the settled plateau, not
// motion. So a long hold near rest still fails: the motion before it
// bounds how long one position may show.
const moving = [paceBefore, pxPerFrameAfter(k)].filter(
(value): value is number => value != null && value > 0,
);
const travel =
moving.length === 0
? null
: Math.max(
Math.min(...moving),
runFrames > 0 ? catchUp / runFrames : 0,
);
if (castStepPx != null && travel != null && travel < castStepPx) {
// The ratio is read to a millionth: a pace of 0.5 that sums to
// 0.4999… still allows two frames, not three.
const allowed = Math.ceil(castStepPx / travel - 1e-6);
// A slow tail after the run sets no allowance of its own. So the run
// may last at most one frame more than the pace into it allows.
const into = Math.max(
paceBefore ?? 0,
runFrames > 0 ? catchUp / runFrames : 0,
);
const cap =
into > 0
? Math.ceil(castStepPx / into - 1e-6) + 1
: Number.POSITIVE_INFINITY;
return unchanged <= Math.min(allowed, cap);
}
// A slowing curve lengthens its runs a frame at a time: a run more than
// one frame longer than the one before it is a stall.
const before = start > 0 ? start - 1 - runStart(start - 1) : 0;
return unchanged <= before + 1;
};
// With a prediction, a frame predicted to move under one cast step since
// the last new position is too little to judge. It is named, and counts
// neither as moved nor as missed. Every other frame the control moved on
// must show a new position, so a hold ends once its moves add up to a
// step. Without a prediction, a run the cast's step explains counts as
// moved.
const excluded = new Set<number>();
if (predictedAt != null) {
for (const t of controlChanges) {
const i = seriesIndex.get(t);
if (i == null || i === 0) {
continue;
}
let last = i - 1;
while (
last > 0 &&
Math.abs(series[last].value - series[last - 1].value) <= epsilon
) {
last -= 1;
}
// The run's first frame with a control reading of its own anchors the
// move. A frame dated from another frame's reading has no time of
// its own.
let anchor = last;
while (anchor < i - 1 && unread.has(series[anchor].frame)) {
anchor += 1;
}
const move = Math.abs(predictedAt(t) - predictedAt(series[anchor].t));
const undated =
unread.has(series[i].frame) || unread.has(series[i - 1].frame);
if (undated || move < judgeStepPx) {
excluded.add(t);
named.push({
atMs: t - window.from,
movePx: move,
stepPx: judgeStepPx,
why: undated ? 'clock' : 'step',
});
}
}
}
const excused = (t: number) => predictedAt == null && underStep(t);
const judgedChanges = controlChanges.filter(t => !excluded.has(t));
if (judgeEveryFrame && predictedAt == null) {
unjudged = judgedChanges.filter(excused).map(t => {
const i = seriesIndex.get(t);
if (i == null) {
throw new Error(
'busyWindowProof: an excused frame is missing from the series',
);
}
const start = runStart(i);
const k = runEnd(i);
const runFrames = (series[k].t - series[start].t) / cadence;
return {
atMs: t - window.from,
movePx:
Math.abs(series[k].value - series[i].value) /
Math.max(1, runFrames),
stepPx,
};
});
}
const componentEdges = [
judged.from,
...delivered.filter(t => changed.has(t) || excluded.has(t) || excused(t)),
judged.to,
];
controlRead = {
moved: judgedChanges.length,
movedWith: judgedChanges.filter(t => changed.has(t) || excused(t)).length,
belowStep: judgedChanges.filter(excused).length,
longestStallMs: Math.max(
...controlEdges.slice(1).map((t, i) => t - controlEdges[i]),
),
componentStallMs: Math.max(
...componentEdges.slice(1).map((t, i) => t - componentEdges[i]),
),
};
}
// The curve's end left too little to judge only when the part up to the
// block's end would have held enough. Otherwise the run fails as before,
// as starvation when the cast was starved.
if (endsInBlock) {
const framesLeft =
controlRead == null ? expectedFrames : controlRead.moved + named.length;
const framesWithoutCurve =
control == null
? Math.floor(
(endWithoutCurve - judged.from) / (compositorFrameMs ?? cadence),
)
: controlChangesUpTo(control, endWithoutCurve).length;
if (framesLeft < minJudgedFrames && framesWithoutCurve >= minJudgedFrames) {
throw curveTooLate(framesLeft);
}
}
const failures: string[] = [];
let starvation: FrameShortfall | null = null;
const cast = castFramesIn(drawn, window);
if (stats.frames === 0 && controlRead == null) {
failures.push('no frame presented in the judged part');
} else if (stats.medianFrameMs > maxMedianFrameMs) {
failures.push(
`median frame interval ${stats.medianFrameMs.toFixed(1)} ms > ${maxMedianFrameMs} ms (${stats.frames} frames presented)`,
);
}
if (controlRead != null) {
const visible = controlRead.movedWith - controlRead.belowStep;
if (
controlRead.moved < minJudgedFrames &&
named.length > 0 &&
controlRead.moved + named.length >= minJudgedFrames
) {
// The prediction named too many frames too little to judge, so too
// few are left: the run proves nothing.
starvation = {
by: 'busyWindowProof',
during: `a ${Math.round(window.to - window.from)} ms block held the main thread, and ${named.length} of the control's ${controlRead.moved + named.length} frames were too little to judge (${unjudgedList(named)}), so ${controlRead.moved} were left to judge`,
frames: cast.frames,
min: minJudgedFrames,
longestGapMs: cast.longestGapMs,
cause:
'the motion moved under one cast step, or had no reading of its own, on too many frames, so the run proves nothing about the motion',
};
} else if (controlRead.moved < minJudgedFrames) {
// The control is a compositor animation. When it moved on too few
// frames, the compositor presented too little to judge the component,
// however long the cast's longest gap was.
starvation = {
by: 'busyWindowProof',
during: `a ${Math.round(window.to - window.from)} ms block held the main thread, and the control moved on ${controlRead.moved} of them`,
frames: cast.frames,
min: minJudgedFrames,
longestGapMs: cast.longestGapMs,
...(cast.longestGapMs > FRAME_STARVATION_MS
? {}
: {
cause:
'the compositor presented too little in this window to judge, so the run proves nothing about the motion',
}),
};
} else if (visible < minJudgedFrames) {
failures.push(
`the component showed a new position on ${visible} of the control's frames, under ${minJudgedFrames}: too little motion in this window to judge`,
);
}
if (controlRead.movedWith < controlRead.moved) {
failures.push(
`moved on ${controlRead.movedWith} of the ${controlRead.moved} frames the control moved (${((controlRead.movedWith / Math.max(1, controlRead.moved)) * 100).toFixed(0)}%)`,
);
}
if (controlRead.componentStallMs > controlRead.longestStallMs) {
failures.push(
`longest stall ${controlRead.componentStallMs.toFixed(1)} ms, longer than the control's ${controlRead.longestStallMs.toFixed(1)} ms`,
);
}
} else if (longestStallFrames > maxStallFrames) {
failures.push(
`longest stall ${longestStallMs.toFixed(1)} ms = ${longestStallFrames} intervals > ${maxStallFrames}`,
);
}
if (controlRead == null && expectedFrames < minJudgedFrames) {
failures.push(
`${(judged.to - judged.from).toFixed(0)} ms judged = ${expectedFrames} frames < ${minJudgedFrames}: the animation under test was not moving during the block`,
);
}
const allowedMisses = Math.max(
1,
Math.floor((1 - minMovedFraction) * judgedFrames + 1e-9),
);
if (
controlRead == null &&
judgedFrames - moved - recorderSkipped > allowedMisses
) {
failures.push(
`${moved} of ${judgedFrames} expected frames moved${recorderSkipped > 0 ? ` (and ${recorderSkipped} the screencast skipped)` : ''} (${(movedFraction * 100).toFixed(0)}% < ${(minMovedFraction * 100).toFixed(0)}%)`,
);
}
const onScreenFromMs =
onScreenFrom == null ? null : onScreenFrom - window.from;
const summary =
`${(judged.to - judged.from).toFixed(0)} ms judged at ${cadence.toFixed(1)} ms/frame: ${stats.frames} frames presented, ` +
`${moved}/${judgedFrames} moved${recorderSkipped > 0 ? ` and ${recorderSkipped} skipped by the screencast` : ''} (${(movedFraction * 100).toFixed(0)}%), ` +
`median ${stats.medianFrameMs.toFixed(1)} ms, ` +
`longest stall ${longestStallMs.toFixed(1)} ms (${longestStallFrames} intervals) at +${longestStallAtMs.toFixed(0)} ms, ` +
`${stats.monotonic ? 'monotonic' : 'not monotonic'}, ` +
`${pxPerFrame.toFixed(1)} px/frame in ${stepPx} px steps` +
(compositorFrameMs == null
? ''
: `, compositor presenting every ${compositorFrameMs.toFixed(1)} ms`) +
(onScreenFromMs == null
? ''
: `, on screen from +${onScreenFromMs.toFixed(0)} ms (${entersAt == null ? 'nothing moved before the block' : 'off screen before the block'})`) +
(endsInBlock
? `, judged to the held curve's end at +${(end - window.from).toFixed(0)} ms`
: '') +
(controlRead == null
? ''
: `; against the control: moved on ${controlRead.movedWith} of its ${controlRead.moved} frames${controlRead.belowStep > 0 ? ` (${controlRead.belowStep} where the cast could not show the step)` : ''}, its longest stall ${controlRead.longestStallMs.toFixed(1)} ms`) +
(named.length === 0
? ''
: `; too little to judge: ${unjudgedList(named)}`) +
notes.map(note => `; note: ${note}`).join('');
const proof = {
...stats,
window,
judged,
onScreenFromMs,
stepPx,
pxPerFrame,
notes,
recorderSkipped,
compositorFrameMs,
cadenceMs: cadence,
longestStallMs,
longestStallAtMs,
expectedFrames,
deliveredFrames,
longestStallFrames,
moved,
movedFraction,
control: controlRead,
unjudged: named,
verdict: {pass: failures.length === 0, failures},
summary,
};
const componentFailed =
controlRead != null &&
(controlRead.movedWith < controlRead.moved ||
controlRead.componentStallMs > controlRead.longestStallMs);
return {proof, starvation, unjudged, componentFailed, cast};
}
/**
* The frames the cast delivered inside `window`, with the component on screen
* or not, and the longest gap between them and the window's edges, ms.
*/
function castFramesIn(
tracked: readonly TrackedFrame[],
window: {readonly from: number; readonly to: number},
): {frames: number; longestGapMs: number} {
const inside = tracked
.filter(f => f.t > window.from && f.t < window.to)
.map(f => f.t);
const edges = [window.from, ...inside, window.to];
return {
frames: inside.length,
longestGapMs: Math.max(...edges.slice(1).map((t, k) => t - edges[k])),
};
}
/** One run of a pooled busy proof (see `pooledBusyProof`). */
export interface BusyRun {
/** The component's frames, tracked from the run's screencast. */
readonly tracked: readonly TrackedFrame[];
/** The control's frames (`startBusyControl`), from the same screencast. */
readonly control: readonly TrackedFrame[];
/** The run's block (`blockMainThread`). */
readonly window: BusyWindow;
/** The control started `ahead`, from the same screencast (see `busyWindowProof`). */
readonly ahead?: readonly TrackedFrame[];
/** When the run's controls started (see `busyWindowProof`). */
readonly controlStarts?: readonly [number, number?];
}
export interface PooledBusyProof {
/**
* Each run judged on its own against its control: read its numbers, not its
* verdict (one short run can hold too few frames to judge).
*/
readonly runs: readonly (BusyProof | null)[];
/**
* For each run, the `BusyWindowTooLateError` its window threw, or null. Such
* a run's block began after its motion had settled, so its `runs` entry is
* null: the run holds nothing to judge.
*/
readonly late: readonly (BusyWindowTooLateError | null)[];
/**
* Whether each run was judged. A run whose control moved on fewer than
* `minRunFrames` frames is too little to judge, and so is a run that began
* too late (`late`). The pool leaves both out.
*/
readonly judged: readonly boolean[];
/**
* The control's new positions over the judged runs' judged parts, and those
* the component moved on too.
*/
readonly control: {readonly moved: number; readonly movedWith: number};
/** The judgment over the pool (see `pooledBusyProof`). */
readonly verdict: BusyVerdict;
/** One line with the pooled numbers, then each run's summary. */
readonly summary: string;
}
/**
* A busy proof over several runs of the same short animation, against the
* control. An animation that lasts a fraction of a second leaves a block only
* a few frames to judge: in WebKit, or on a loaded machine, the control can
* present fewer than `minJudgedFrames` in one run, and one run cannot decide.
* A run whose control moved on fewer than `minRunFrames` frames (1 by
* default) is too little to judge: the machine starved it. The summary names
* it, and the pool leaves it out, so it never counts as a pass. A run whose
* window throws `BusyWindowTooLateError` is left out the same way: its block
* began after its motion had settled.
* The judged runs are judged as one long window is:
* - at least `minJudgedRuns` runs are judged (by default, half the runs,
* rounded up);
* - the control moved on at least `minJudgedFrames` frames over them;
* - in each judged run, the component moved on every frame its control moved
* on, so a freeze fails its run and is never pooled. A run of unchanged
* frames counts as motion only where the cast cannot show the motion (see
* `busyWindowProof`).
* - in each judged run, its longest stall is no longer than that run's
* control's.
* `maxMedianFrameMs`, when given, applies to every run. A main-thread
* animation still fails: in every run the control moves and it does not.
*
* With fewer judged runs than `minJudgedRuns`, or a control that moved on
* fewer than `minJudgedFrames` frames over them, the pool is under the floor.
* Under the floor, a pool with no component failure on the frames shown is too
* little to judge, and it throws `FrameStarvationError`. A pool left short of
* judged runs by a run that began too late keeps its failure instead. So does a
* pool whose judged runs show a component red.
*/
export function pooledBusyProof(
runs: readonly BusyRun[],
options: Omit<
NonNullable<Parameters<typeof busyWindowProof>[2]>,
// A prediction belongs to one window, never to the pool.
| 'control'
| 'ahead'
| 'controlStarts'
| 'minMovedFraction'
| 'judgeEveryFrame'
| 'predicted'
> & {
/** The fewest frames a run's control must move on for the run to count. */
minRunFrames?: number;
/** The fewest judged runs the pool needs. */
minJudgedRuns?: number;
} = {},
): PooledBusyProof {
if (runs.length === 0) {
throw new Error('pooledBusyProof: no runs to judge');
}
const {
minRunFrames = 1,
minJudgedRuns = Math.ceil(runs.length / 2),
...windowOptions
} = options;
const {minJudgedFrames = 4, maxMedianFrameMs = Infinity} = windowOptions;
if (minJudgedRuns < 1 || minJudgedRuns > runs.length) {
throw new Error(
`pooledBusyProof: minJudgedRuns ${minJudgedRuns} is not between 1 and the ${runs.length} runs`,
);
}
const late: (BusyWindowTooLateError | null)[] = [];
const failedRuns: boolean[] = [];
const runCasts: ({frames: number; longestGapMs: number} | null)[] = [];
const proofs = runs.map(run => {
try {
const {proof, componentFailed, cast} = readBusyWindow(
run.tracked,
run.window,
{
...windowOptions,
control: run.control,
ahead: run.ahead,
controlStarts: run.controlStarts,
},
);
late.push(null);
failedRuns.push(componentFailed);
runCasts.push(cast);
return proof;
} catch (error) {
if (!(error instanceof BusyWindowTooLateError)) {
throw error;
}
late.push(error);
failedRuns.push(false);
runCasts.push(null);
return null;
}
});
const reads = proofs.map(proof =>
proof == null ? null : (proof.control as BusyControlRead),
);
const judged = reads.map(read => read != null && read.moved >= minRunFrames);
const judgedReads = reads.filter(
(read, i): read is BusyControlRead => judged[i] && read != null,
);
const lateRuns = late.filter(error => error != null).length;
const total = (key: 'moved' | 'movedWith' | 'belowStep') =>
judgedReads.reduce((sum, read) => sum + read[key], 0);
const moved = total('moved');
const movedWith = total('movedWith');
const over =
judgedReads.length === runs.length
? `${runs.length} runs`
: `the ${judgedReads.length} judged runs of ${runs.length}`;
const failures: string[] = [];
if (judgedReads.length < minJudgedRuns && lateRuns > 0) {
failures.push(
`${judgedReads.length} of ${runs.length} runs judged, under ${minJudgedRuns}: ${lateRuns} began too late for their motion, and the compositor presented too little in any other to judge`,
);
}
// Too few control frames or judged runs is too little to judge. A judged
// run's component red still fails: a frame it missed, or a longer stall.
const tooFewFrames = judgedReads.length > 0 && moved < minJudgedFrames;
const tooFewRuns = judgedReads.length < minJudgedRuns && lateRuns === 0;
const visible = movedWith - total('belowStep');
if (!tooFewFrames && judgedReads.length > 0 && visible < minJudgedFrames) {
failures.push(
`the component showed a new position on ${visible} of the control's frames over ${over}, under ${minJudgedFrames}: too little motion in these windows to judge`,
);
}
if (movedWith < moved) {
failures.push(
`moved on ${movedWith} of the ${moved} frames the control moved over ${over} (${((movedWith / Math.max(1, moved)) * 100).toFixed(0)}%)`,
);
}
proofs.forEach((proof, i) => {
if (proof == null) {
return;
}
if (proof.frames > 0 && proof.medianFrameMs > maxMedianFrameMs) {
failures.push(
`run ${i + 1}: median frame interval ${proof.medianFrameMs.toFixed(1)} ms > ${maxMedianFrameMs} ms`,
);
}
const read = reads[i];
if (!judged[i] || read == null) {
return;
}
if (read.movedWith < read.moved) {
failures.push(
`run ${i + 1}: moved on ${read.movedWith} of the ${read.moved} frames its control moved`,
);
}
if (read.componentStallMs > read.longestStallMs) {
failures.push(
`run ${i + 1}: longest stall ${read.componentStallMs.toFixed(1)} ms, longer than the control's ${read.longestStallMs.toFixed(1)} ms`,
);
}
});
// A pool whose compositor presented too little proves nothing about the
// motion, as one starved window does. A run that began too late keeps the
// pool's failure. So does a judged run's component red.
const lateFailure = judgedReads.length < minJudgedRuns && lateRuns > 0;
const componentFailed = failedRuns.some((failed, i) => judged[i] && failed);
if ((tooFewFrames || tooFewRuns) && !lateFailure && !componentFailed) {
const casts = runCasts.filter(
(cast, i): cast is {frames: number; longestGapMs: number} =>
cast != null && (tooFewRuns || judged[i]),
);
const frames = casts.reduce((sum, cast) => sum + cast.frames, 0);
const longestGapMs = Math.max(...casts.map(cast => cast.longestGapMs));
throw new FrameStarvationError(
tooFewRuns
? {
by: 'pooledBusyProof',
during: `${runs.length} blocks held the main thread, and ${judgedReads.length} of them had enough control frames to judge`,
frames,
min: minJudgedRuns,
longestGapMs,
cause: `${judgedReads.length} of ${runs.length} runs judged, under ${minJudgedRuns}, and the control moved on ${moved} frames over them: the compositor presented too little in the others to judge, so the pool proves nothing about the motion`,
}
: {
by: 'pooledBusyProof',
during: `the blocks of ${over} held the main thread, and the control moved on ${moved} of them`,
frames,
min: minJudgedFrames,
longestGapMs,
...(longestGapMs > FRAME_STARVATION_MS
? {}
: {
cause:
'the compositor presented too little in these windows to judge, so the pool proves nothing about the motion',
}),
},
);
}
const summary =
`${runs.length} runs pooled` +
(judgedReads.length === runs.length
? ''
: `, ${judgedReads.length} judged`) +
`: moved on ${movedWith} of the control's ${moved} frames` +
proofs
.map((proof, i) =>
proof == null
? `; run ${i + 1}: too late to judge: ${late[i]?.message ?? ''}`
: judged[i]
? `; run ${i + 1}: ${proof.summary}`
: `; run ${i + 1}: too little to judge, the control moved on ${reads[i]?.moved ?? 0} frames, under ${minRunFrames}: ${proof.summary}`,
)
.join('');
return {
runs: proofs,
late,
judged,
control: {moved, movedWith},
verdict: {pass: failures.length === 0, failures},
summary,
};
}