What

Reports why blur is off, and what each render session did, so tooling and logs can tell.

• Reason codes. The runtime's report() carries a stable reasonCode next to the readable reason for every way blur ends up off: a defect code (from feat(core): block capture motion blur on html-in-canvas defects #5971), unsupported-browser, renderer-off and capture-failures.
• probe() (on window.__hfMotionBlur) makes the decision on demand without wrapping or painting; it is cheap once scanned and puts the playhead back.
• suspend() stops all painting for the rest of a session without changing the reported decision (and never sets the page's off switch, which would change the probe's answer). It outlives a re-init of the same root and does nothing where blur is off.
• Engine log line. One line per capture session from what the page reports: [motion-blur] on reasonCode=null movers=N failedFrames=K, after the first frame. The first-frame line cannot know about later failures, so the session end prints the same line with (session end) when any frame fell back to plain DOM (read with a 1.5 s timeout so a stuck page cannot hold up closing); a clean session stays quiet.
• The first test that reads blurred pixels. captureMotionBlur.pixels.browser.test.ts drives a real Chrome with html-in-canvas through the engine's frame order (seek, wait, composite, screenshot) and checks: the trail along the motion line has the hard edges of the sharp frame spread out without adding or losing ink; what does not move matches the sharp frame exactly; a box centered with translate: -50% -50% is blurred around where it really is; a backface-hidden card in a 3D flip renders the plain frame. distributed/chunkFrames.test.ts (moved here from feat(core,producer): decide blur defects once per timeline, off on routes that cannot host it #5990 to keep that PR under 1000 lines): a chunk session stands page blur down and asks for no engine blur. Also a face whose backface-visibility: hidden comes only from @keyframes or element.animate(), next to an ordinary mover, turns blur off with backface-visibility and renders the plain frame; a face that is hidden only between two scan samples renders just that frame plain; a flat animated backface hack stays blurred. It skips when Chrome or html-in-canvas is missing.

Why

Part 8 of 9 in the capture motion blur stack: #5875 → #5967 → #5968 → #5969 → #5970 → #5971 → #5990 → #5991 → #5992. It builds on #5990, whose scan decides the state this reports.

Stack goal: opt-in capture motion blur for compositions, in Studio preview and in renders, drawn with Chrome's html-in-canvas. Blur turns itself off in several cases, and without this an author or an operator cannot tell which; hyperframes check (#5992) builds on probe() and suspend().

Notes

• state stays on while individual frames fall back to plain DOM (a paint timeout, a missed defect, a failed capture): read failedFrames for those. A paint timeout counts in failedFrames but not in failures, which only counts capture exceptions in a row (documented, not fixed).
• Why blur is off is reported three ways after this PR: window.__hfMotionBlur.report() (state, reason, reasonCode, movers, failedFrames), the per-session log line, and, in feat(cli): tell authors in check why motion blur is off #5992, hyperframes check.
• The pixel test runs against the Chrome the engine pins (152 headless shell) with the CanvasDrawElement feature; it is a guard for the pipeline, not a visual-quality benchmark. Limits it does not cover: trails drawn over foreground elements, a halo on transparent movers, trails past overflow:hidden, 2D flips through scaleX = 0.
• Cost: about 1.7x median render time for a blurred composition (20 real compositions, blur on vs off); a few ms of JS per blurred frame in Studio plus a one-time mover scan on first play.

Testing

• Core captureMotionBlur/index.test.ts: reason codes for every off path (the earlier assertions on reason text now check codes too), probe() finds the movers without any paint, wrap or event and restores the playhead, does not rescan unless the timeline changes or while blur is off, reports the defect with its code and capture-failures after three failed frames; suspend() unwraps a wrapped root, stops painting, is idempotent, outlives a re-init, exists but does nothing where blur is off, and lets the probe still decide; plus the guards that need codes (one warning and the first reason stays when unwrapping throws).
• Engine pageMotionBlur.test.ts: the per-session line, the session-end line only when frames fell back (including when the failures ended blur), the timeout for a page that does not answer, and closeCaptureSession logging the closing line once before the page closes (driven through the real function); frameCapture-motionBlur.test.ts: the line is logged once after the session's first captured frame, says why blur is off, and stays silent for a page that never asked for blur.
• Engine captureMotionBlur.pixels.browser.test.ts: 4 pixel tests in Chrome 152 headless shell.
• bun run build, tsc --noEmit in core and engine, and their tests pass; comment ratchet against feat(core,producer): decide blur defects once per timeline, off on routes that cannot host it #5990's branch passes; every package is within its size budget.

🤖 Generated with Claude Code