test(producer): add png-sequence distributed fixture

[jrusso1020]

Description

Phase 4 of the distributed rendering plan: test fixtures (see DISTRIBUTED-RENDERING-PLAN.md §11 Phase 4 + §10 test strategy). This is PR 4.4 of the Phase 4 remainder, stacked on PR 4.2 (#845) for the harness discovery + LFS pattern infrastructure.

This PR adds the png-sequence fixture (tests/distributed/png-sequence/) plus the harness extensions required to render and compare a frame-directory output. The composition is a 2-second (60-frame) scene at 30fps with a transparent background, a crossfade transition straddling the frame-30 chunk seam, and a continuously rotating SVG icon. renderConfig.format: "png-sequence" and chunkSize: 15 produces N=4 chunks; assemble() for png-sequence merges chunk frame directories rather than concat-copying mp4 files. The assertion is per-frame byte equality (Buffer.equals) — distributed-simulated produces a frames directory byte-identical to the in-process baseline. All 60 frames match.

Harness extensions:

1. validateMetadata accepts format: "mp4" | "webm" | "mov" | "png-sequence".
2. checkDistributedSupport accepts the same set; only webm is refused at plan time.
3. Output path handling branches on isPngSequence: file vs directory, output.<ext> vs frames/.
4. runDistributedSimulatedRender call passes the user-supplied format through (was previously hardcoded to "mp4").
5. Visual comparison branches: PSNR sampling for video formats, per-frame Buffer.equals for png-sequence. The frame count check fails fast on a frame-count mismatch.
6. Audio comparison skips entirely for png-sequence (no audio in a frame-directory output).
7. Failure-detail extraction branches: copies the failing PNGs directly for png-sequence (extractFrameAsImage would try to invoke ffmpeg on a directory).
8. --update uses cpSync({recursive: true}) for png-sequence to roundtrip the whole frames directory.

LFS:

• .gitattributes adds packages/producer/tests/distributed/*/output/frames/*.png so baseline frames don't bloat the working repo. 60 frames × ~12 KB each ≈ 700 KB; with more fixtures the unfiltered footprint would grow, so LFS-tracking from the first fixture forward keeps the repo lean.

Testing

• bun run --cwd packages/producer docker:test:update png-sequence — baseline generated inside Dockerfile.test (60 RGBA PNGs in output/frames/)
• bun run --cwd packages/producer docker:test png-sequence — in-process passes (60/60 frames byte-identical against baseline)
• bun run --cwd packages/producer docker:test:distributed png-sequence — distributed-simulated passes (60/60 frames byte-identical against baseline)
• bun run --cwd packages/producer docker:test:distributed font-variant-numeric many-cuts gsap-letters-render-compat style-1-prod sub-composition-video mp4-h264-sdr -- --sequential — smoke set + the prior fixture all pass (6/6)
• bunx oxlint + bunx oxfmt --check clean on changed files
• bunx tsc --noEmit (producer package) clean

🤖 Generated with Claude Code

[jrusso1020]

• test(producer): add chunk-boundary fixtures per first-party adapter #852
• test(producer): add mp4 H.265 SDR distributed fixture #851
• feat(producer): add codec knob to DistributedRenderConfig #850
• test(producer): add mov ProRes distributed fixture #848
• test(producer): add png-sequence distributed fixture #847 👈 (View in Graphite)
• test(producer): add mp4 H.264 SDR distributed fixture #845
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

Re-reviewed as part of the fixture stack. LGTM.

[vanceingalls]

Additive review — Miguel already approved; one substantive concern around the byte-identity threshold and a few nits. The PR is solid.

Calibrated strengths:

• The fixture meaningfully stresses chunk boundaries: chunkSize=15 with 60 frames produces 4 chunks ([0-14]/[15-29]/[30-44]/[45-59]); the GSAP crossfade at 0.9s + 0.2s straddles frame 30 (the chunk-1→chunk-2 seam) and the continuous icon rotation spans every seam (tests/distributed/png-sequence/src/index.html:1219-1221). This is a real test of mergePngFrameDirs's global re-numbering correctness, not a smoke test.
• --update is rejected at parse time for --mode=distributed-simulated (regression-harness.ts:176-186). That keeps the invariant "in-process is the source of truth for baselines" enforced — without it, a developer could regenerate baselines from a buggy distributed run and lock in the bug.
• Both naming sites (in-process: encodeStage.ts:134; distributed merge: assemble.ts:255) use the same frame_${(i+1).padStart(6, "0")}.png pattern. The defensive renderedFrameName === snapshotFrameName check at regression-harness.ts:906 will loudly catch any future padding drift on either side — exactly the right shape of defense.

Important:

• nit-leaning-important — maxFrameFailures: 0 is the strictest possible threshold for the first byte-identity fixture in the suite. tests/distributed/png-sequence/meta.json:6 pins zero per-frame drift. The PR comment (regression-harness.ts:866-869) defends this — "metadata-chunk reorder would also be a regression" — and the defense is real. But the upstream inputs (Chrome's CDP screenshot bytes, libpng deflate output) can shift on a Chromium or zlib version change in the Docker image, and when that happens this fixture will fail with no code change. That's the intended invariant, but worth surfacing as a known tradeoff: the day Chromium upgrades, this fixture is the canary that goes red first. A short note in the fixture's description (or a KNOWN-DRIFT-SOURCES.md adjacent to the fixture) flagging that the failure mode on a Chrome bump is "regenerate baselines" rather than "investigate regression" would save a future on-call cycle.

Nits:

• regression-harness.ts:882-890 — the frame-count-mismatch early-return reports failedFrames: Math.abs(rendered - snapshot) and forces result.passed = false regardless of maxFrameFailures. That's correct behavior (count mismatch IS pathological), but the harness now has two unequal contracts for "what maxFrameFailures gates": count-mismatch always fails; per-frame byte drift respects the threshold. A one-line comment at the early-return clarifying that count mismatch is always fatal would prevent a future reader from "fixing" this to honor the threshold.
• tests/distributed/png-sequence/meta.json:8-9 — minAudioCorrelation and maxAudioLagWindows are vestigial for png-sequence (audio path is skipped at regression-harness.ts:999). Schema requires them and keeping the schema uniform is right. No action; flagging for future schema cleanup if other audio-less fixture shapes land.
• regression-harness.ts:887 + 1018-1022 — two sites set the same "audio defaults to pass" result object. If audio handling ever evolves (e.g., a new "audio-required" assertion), both sites would need to change. Small consolidation opportunity, not load-bearing.

Verdict: APPROVE
Reasoning: The fixture exercises real chunk-boundary semantics, naming conventions match between in-process and distributed paths so the byte-equality assertion is sound, and the --update gate prevents the baseline-corruption failure mode. The maxFrameFailures: 0 tradeoff is defensible; the note above is a heads-up, not a blocker.

Review by Vai

[jrusso1020]

Thanks @vanceingalls — addressed in commit 4423ac62. The fixture description now flags that the maxFrameFailures: 0 byte-identity gate will fail on a Chromium or zlib bump in Dockerfile.test and that the recovery is docker:test:update <name> rather than "investigate regression." The other nits (count-mismatch fatal vs threshold comment; vestigial audio fields) are minor — leaving as follow-ups.

The base branch was changed.