perf(cli): cut wasted waits from the check browser gate

[xiayewang-heygen]

Why

hyperframes check p95 is ~37s in prod (p50 ~10s, min ~8s). This removes three waits that cost time without changing what the gate detects. No detection logic, thresholds, or sample counts change.

What

1. Motion-only grid times skip the paint-flush settle

AUDIT_SEEK_OPTIONS pays an unconditional settleMs: 120 sleep plus a glyph-subset font wait on every seek. A grid time that only feeds collectMotionFrame needs neither — __hyperframesMotionSample reads computed transforms and opacity, which the ordered double-rAF already guarantees are committed. The sleep exists to flush paint, which only matters before a screenshot.

New MOTION_SAMPLE_SEEK_OPTIONS keeps the double-rAF and drops the rest. Times that measure text (layout), photograph the frame (contrast), or read caption/frame geometry keep the full settle. The dense content_overlap pass already does the same thing via DENSE_GEOMETRY_SEEK_OPTIONS.

At MOTION_FPS = 20 / MOTION_MAX_SAMPLES = 300, this is the dominant cost of any run carrying an index.motion.json — a 10s composition is ~201 seeks × ~170ms ≈ 34s, of which ~120ms/seek was this sleep.

2. Adaptive post-ready settle

waitForCompositionSettle slept a flat 1500ms on every page open — after __renderReady, shader pre-render, and document.fonts.ready had all resolved. Replaced with a poll that holds a 400ms floor, then exits on the first pair of consecutive frames with no font subset in flight, capped at the original 1500ms.

Worst case is unchanged. The floor is deliberate: work that lands after __renderReady but signals nothing observable (image decode, late layout) still gets a margin.

3. Skip the discarded contrast overview screenshot

collectContrast always took a second full-page screenshot to build the annotated overview, and the pipeline then discarded it unless --snapshots was set. The bare collectContrast(time) call shape already meant "no snapshots", so that path now skips the shot and its overlay entirely.

Scope note

Fix 1 is a no-op for Zephyr, which generates only index.html and no motion sidecar — so its motion grid never runs. It benefits callers that do ship a motion spec. Fixes 2 and 3 apply to every check.

Per @xuanru, the larger Zephyr-specific wins are caller-side in experiment-framework, not here:

• _build_check_args never passes --no-contrast, yet DROP_ERROR_SECTIONS = ("contrast",) throws the whole contrast section away. The CLI flag already exists — the contrast pass is currently pure waste for Zephyr.
• HYPERFRAMES_CHECK_MAX_CONCURRENCY is unset in prod, so the per-pod Chrome semaphore falls back to the CPU request.

Testing

• 2,265 CLI tests pass (168 files)
• Two new tests in check.test.ts: motion-only times route to seekMotion; layout/contrast times keep seek
• oxlint / oxfmt clean; fallow audit clean on all 5 changed files

Risk

Fix 2 touches every openSettledCompositionPage caller (check, snapshot, compare, validate), not just check — it's the one worth a careful look. It can only return earlier than before, never later, and the 400ms floor plus the two-stable-frame requirement are the guardrails. If a composition turns out to need the full 1500ms, raising CAPTURE_SETTLE_FLOOR_MS restores the old behavior.

Savings figures above are derived from the code paths and the measured 8s floor, not from a before/after benchmark — the check has no per-phase instrumentation today. launch_settle_ms / seek_loop_ms / contrast_ms are already emitted on the check_report telemetry event but not surfaced in Datadog; wiring those up would let us verify this directly.

🤖 Generated with Claude Code