feat(producer): report browser-computed reference backgrounds - #7007

What

Add one reference_background field to completed render metadata, describing the browser-computed background of the composition root and surrounding page at the initial film state.

The closed values are:

{"kind":"solid","rgb":[10,46,138]}
{"kind":"none"}
{"kind":"unsupported_non_solid"}
{"kind":"unknown"}

Why

This serves video creators and integrations whose blank-frame checks misclassify colored backgrounds. A flat frame does not establish that its color is the film's background, and an inner panel or a chunk-local still is not an authoritative reference.

Related work

Standalone renderer-result addition. It does not change blank-frame thresholds, release versions, or deploy a service.

How

• One shared type, classifier, recorder and wire-field adapter. The wire name has one production definition.
• Read actual Chromium computed root/ancestor styles at time zero, before transparent capture injects its background-clearing rules. Chromium resolves CSS colors into an isolated sRGB swatch; no film pixels or handwritten CSS color parser are used.
• Preserve images and gradients as unsupported_non_solid. Missing/unresolved computation, translucent paint, and known changing backgrounds stay indeterminate. A transparent computed color alone never yields none; that requires positive CSSOM evidence of an explicit background: none and no effective paint. Unproven cascade structures remain unknown.
• Share one reserved read across an in-process render's existing sessions. A later worker cannot replace an unknown reference or select a chunk-local fallback. Static local renders therefore do not acquire an extra browser session.
• Static distributed planning uses an inspection-only screenshot page: no WebGPU device assertion, BeginFrame liveness check, capture initialization or media reconciliation. Browser/navigation/readiness failures return unknown without rejecting an otherwise valid static plan. Existing browser-required probes keep their original behavior.
• Freeze the reference in composition.json and execution-plan plan.json, which are already content-addressed artifacts. Do not add a field to the hashed v2 transport manifest: its older readers project known keys before checking the hash. The additive v2 result reads the verified execution-plan blob instead. A frozen base-version reader/materializer test exercises this mixed-version contract for both chunk and assembler roles.
• Expose the field on in-process local results, range results, blocking producer JSON and SSE completion. The existing Docker CLI wrapper has no child-result metadata transport; this PR does not invent a sidecar or a new envelope for it.
• Document the contract and the distributed startup tradeoff.

Measured startup cost

Three serial runs per mode on Linux, Chromium 153 software rendering, FFmpeg, browser pooling disabled; a static 320×240, 0.1-second composition. Baseline temporarily disabled only the optional static-plan inspection call and local reader callback, then source was restored before commit. These measurements replace the earlier full-probe implementation measurements.

Full plan samples were [126,24,19] vs [878,608,537] ms; local samples were [1080,980,939] vs [1038,924,935] ms. This small fixture does not predict complex-film latency. There is one new page initialization per previously browser-free static distributed plan, not per chunk, and no additional local page initialization.

Test plan

• 29 engine controls: pure classifier/recorder plus real Chromium cascade, custom property, specificity/important, JS initial state, explicit none, default/declared transparency, gradient/image, unresolved color, known animation, and pre-transparency inspection.
• 5 blocking/SSE response controls, including older renderer output becoming explicit unknown.
• 7 integration controls: all four variants survive assembly; a real static composition matches across local rendering, v1 plan, frozen metadata and v2 result; the hashed v2 manifest has no new field. Static plans also succeed with an unavailable browser and without a WebGPU device.
• 73 existing probe-stage tests; static inspection no longer forces the browser media-probe branch.
• 3 inspection-only unit controls, including startup and navigation failures degrading to unknown.
• 68 v2 tests, including execution of the actual frozen base reader and both legacy materializers against a newly written reference-bearing plan.
• 118 tests in the changed local-render CLI test file, including four result-variant controls.
• Legacy builder/v1 byte-identical plan/hash control.
• Gradient-to-color mutant goes red: removing the image/gradient guard makes both dedicated controls fail by returning solid RGB. Source restored afterward.
• Engine, producer and CLI TypeScript checks; touched-file oxlint/oxfmt; normal commit hooks including scoped fallow audit, with no new complexity suppression.
• Public producer documentation updated.

The existing requiresWebGpu wiring control now gets past planning; its chunk step uses its pre-existing early capability guard because this local browser cannot create a WebGPU device. The new plan-only WebGPU control executes without that guard and passes.

Timed-readiness follow-up

Readiness now uses 100 ms interval polling rather than animation-frame polling, because the render clock parks animation frames until a seek. A real-browser regression becomes ready only after its first check and uses a 750 ms timeout. It passes with interval polling; removing the polling option makes it fail by returning unknown. All seven reference integration controls, the three optional-inspection unit controls, and the master-bus planning control pass on Chromium 153. The table above is re-measured for this implementation.

The retained-node assertion reported by hosted CI (4695 vs <800) is not reproduced locally: the exact case passes in isolation on both base 5e50ac1c475f9446cd17a04f218194b555fa311f and the PR source, and the complete referenced browser test file passes 81/81 on base. Base hosted CI was also green. No claim is made that the failure is confirmed pre-existing; hosted CI on the new head remains the verdict.

No full local test suite, paid service, deployment, Docker render, live cloud job, or HDR/visual-film acceptance run was performed. HTTP/SSE controls use an isolated renderer fixture; the static-plan/local integration uses real Chromium and FFmpeg. Hosted CI remains a separate gate.

Packed-size follow-up

Merged current main (036e41fa09e6670f155fa3f2c361b58b8ed77e02) without rebasing. Compared producer tarballs using the CI build and [email protected] pack: main is 835,006 bytes packed / 3,032,143 unpacked; this branch is 837,234 bytes packed / 3,042,703 unpacked, an increase of 2,228 compressed bytes / 10,560 unpacked bytes.

The added bytes are production reference-background handling: dist/index.js +5,370 bytes, dist/distributed.js +4,013, and dist/public-server.js +1,357; declarations change by −180 bytes net (including the new 533-byte planReferenceBackground.d.ts). The packed manifest has unchanged size. The existing files: ["dist/"] and declaration-build exclusions already keep tests, source maps and the 44,599-byte frozen-reader fixture out of the tarball; no test was removed and no packaging exclusion needs widening.

The old 828,932-byte packed budget allows 837,221.32 bytes with its 1% tolerance, leaving current main almost at the limit. Raise only producer's packed budget to 845,000 bytes, leaving 7,766 bytes (0.93%) above this measured runtime payload. Keep its unpacked budget unchanged at 3,081,613 bytes. bun run verify:packed-manifests passes: all 14 package budgets, 193 resolved exports, 183 executed Node exports, clean consumer installation, declaration checking, Vite resolution and CLI startup. The standalone producer pack was 837,232 bytes; the full verification repack was 837,234 bytes, matching the merge-group failure. The manifests differ only in dependency-key ordering.

— Jerrai