fix(producer): include webm in plan-time needsAlpha + strengthen alpha smoke

PR review feedback from Miguel and Vai on #951 caught a real bug:
`plan.ts`'s `needsAlpha` disjunction excluded `"webm"`, so the plan
stage froze `forceScreenshot: false` into the `LockedRenderConfig`
even though distributed webm uses `yuva420p`. Every chunk worker
captured opaque RGB via BeginFrame (which doesn't preserve alpha on
Linux headless-shell), and libvpx-vp9 encoded uniformly-opaque alpha
that the encoder then dropped — producing un-keyable webm.

Two changes:

1. **plan.ts**: include `"webm"` in `needsAlpha`. Matches the
   in-process renderer's logic at `renderOrchestrator.ts:1469`
   (`const needsAlpha = isWebm || isMov || isPngSequence`); the two
   sites must stay in sync since the distributed pipeline's PSNR
   regression compares against the in-process baseline.

2. **Smoke test (yuva420p describe)**: source frames now use a real
   alpha gradient (`geq=a='X*255/W'` on top of `testsrc2`) instead of
   `testsrc2 + format=rgba` which was uniformly opaque. The decode-
   pix_fmt assertion is dropped (ffprobe reports `yuv420p` for
   VP9-with-alpha because the alpha lives in a Matroska
   `BlockAdditional` sidecar) and replaced with two stronger checks:
   - `TAG:ALPHA_MODE=1` is present on the stream — proves the
     encoder was actually configured for alpha
   - alpha plane variance after `-c:v libvpx-vp9 -i ... -pix_fmt rgba
     -vf extractplanes=a,signalstats` — proves the alpha sub-stream
     round-trips through concat-copy with spatially-varying content,
     not uniform/dropped alpha
   - decode-test gate is now exit-code-only (was `exitCode || stderr`
     which would flake on chatty ffmpeg `-v error` builds emitting
     non-fatal DTS/container notes)

These checks would have caught the `needsAlpha` bug before review.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jrusso1020

packages/producer/src/services/distributed/plan.ts

@@ -653,10 +653,17 @@ export async function plan(
   // move the contents over once the staged work completes.
   const finalCompiledDir = join(planDir, "compiled");
 
-  // mov + png-sequence carry alpha — flip force-screenshot so compileStage
-  // takes the alpha-aware capture path (BeginFrame doesn't preserve alpha
-  // on Linux headless-shell).
-  const needsAlpha = config.format === "png-sequence" || config.format === "mov";
+  // webm + mov + png-sequence carry alpha — flip force-screenshot so
+  // compileStage takes the alpha-aware capture path (BeginFrame doesn't
+  // preserve alpha on Linux headless-shell). Must match the in-process
+  // renderer's needsAlpha logic in `renderOrchestrator.ts` so chunked
+  // webm output preserves the same alpha plane the in-process baseline
+  // does. Omitting webm here silently freezes `forceScreenshot: false`
+  // into the planDir and every chunk worker captures opaque RGB — the
+  // libvpx-vp9 alpha sub-stream then encodes either uniform alpha or
+  // gets downgraded by the encoder, producing un-keyable webm output.
+  const needsAlpha =
+    config.format === "png-sequence" || config.format === "mov" || config.format === "webm";
 
   // ── Compile ──
   const compileResult = await runCompileStage({

packages/producer/tests/distributed/_smoke/webm-concat-copy.test.ts

@@ -330,9 +330,13 @@ describe("webm VP9 concat-copy smoke (yuva420p alpha)", () => {
     alphaConcatListPath = join(alphaRoot, "concat-list.txt");
     alphaOutputPath = join(alphaRoot, "output.webm");
 
-    // For alpha frames, generate RGBA PNGs with a transparent background
-    // and an animated solid rect. `color` lavfi source supports alpha
-    // via `c=<color>@<alpha>` syntax.
+    // For alpha frames, generate RGBA PNGs with spatially-varying alpha
+    // so the encoder can't drop the alpha plane as uniform/redundant.
+    // `testsrc2 + format=rgba` (the prior shape) produced uniformly-
+    // opaque alpha and the libvpx-vp9 encoder silently downgraded the
+    // output to yuv420p — masking any bug in the alpha pipeline. Here
+    // `geq=a='X*255/W'` writes a horizontal alpha gradient on top of
+    // the testsrc2 RGB so the alpha track has real per-pixel content.
     const frameGen = runFfmpegSync([
       "-hide_banner",
       "-y",
@@ -341,7 +345,7 @@ describe("webm VP9 concat-copy smoke (yuva420p alpha)", () => {
       "-i",
       `testsrc2=s=${WIDTH}x${HEIGHT}:r=${FPS}:d=${TOTAL_FRAMES / FPS}`,
       "-vf",
-      "format=rgba",
+      "format=rgba,geq=r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':a='X*255/W'",
       "-frames:v",
       String(TOTAL_FRAMES),
       join(alphaFramesDir, "frame_%04d.png"),
@@ -439,15 +443,6 @@ describe("webm VP9 concat-copy smoke (yuva420p alpha)", () => {
   });
 
   it("decodes alpha-track WebM cleanly without seam errors", () => {
-    // The decode-test is the load-bearing assertion. The actual pixel
-    // format reported by ffprobe depends on the source's alpha
-    // distribution — an RGBA source whose alpha plane is uniformly
-    // opaque can be encoded as yuva420p but ffprobe may report it as
-    // yuv420p if libvpx-vp9 drops the alpha sub-stream as redundant. The
-    // distributed renderer's real compositions (which have meaningful
-    // alpha) get the alpha branch end-to-end; this smoke test only
-    // proves that the closed-GOP encoder args + alpha-pixel-format flag
-    // combination doesn't break concat-copy.
     const decodeResult = runFfmpegSync([
       "-hide_banner",
       "-v",
@@ -458,7 +453,12 @@ describe("webm VP9 concat-copy smoke (yuva420p alpha)", () => {
       "null",
       "-",
     ]);
-    if (decodeResult.exitCode !== 0 || decodeResult.stderr.length > 0) {
+    // Gate only on exit code — `-v error` ffmpeg builds can emit
+    // non-fatal stderr (DTS warnings, container-quirk notes) and we
+    // don't want the test to flake on chatty stderr in a future
+    // libavformat upgrade. Surface stderr in the failure message for
+    // forensic context.
+    if (decodeResult.exitCode !== 0) {
       throw new Error(
         `[alpha smoke decode-test] failed (exit ${decodeResult.exitCode}). ` +
           `Failure fingerprint: ${decodeResult.stderr.slice(-1000) || "(no stderr)"}`,
@@ -470,17 +470,67 @@ describe("webm VP9 concat-copy smoke (yuva420p alpha)", () => {
       "error",
       "-select_streams",
       "v:0",
-      "-show_entries",
-      "stream=codec_name,pix_fmt",
-      "-of",
-      "default=noprint_wrappers=1",
+      "-show_streams",
       alphaOutputPath,
     ]);
     expect(probeResult.exitCode).toBe(0);
     expect(probeResult.stdout).toMatch(/codec_name=vp9/);
-    // Accept either yuv420p or yuva420p — see the comment above the
-    // decode-test for why libvpx-vp9 may downgrade uniformly-opaque
-    // alpha to yuv420p.
-    expect(probeResult.stdout).toMatch(/pix_fmt=yuva?420p/);
+    // libvpx-vp9 stores the alpha plane as a Matroska `BlockAdditional`
+    // sidecar, NOT in the main stream's `pix_fmt` — so `ffprobe` always
+    // reports `pix_fmt=yuv420p` for VP9-with-alpha. The right signal that
+    // alpha encoding was enabled is the stream-level `TAG:ALPHA_MODE=1`
+    // tag the encoder writes when `-metadata:s:v:0 alpha_mode=1` is set
+    // on a yuva420p input.
+    expect(probeResult.stdout).toMatch(/ALPHA_MODE=1/);
+  });
+
+  it("alpha plane round-trips through concat-copy with spatially-varying content", () => {
+    // Decode the concat-copied WebM via the libvpx-vp9 decoder forced to
+    // RGBA, then extract the alpha plane and check it has real spatial
+    // variance — catches the failure mode where the encoder accepted
+    // yuva420p input but dropped the alpha sub-stream silently
+    // (uniform alpha would mask any plan-time bug like the `needsAlpha`
+    // hole that hid this PR's bug before review caught it). The
+    // gradient source produces YMIN ≈ 0 / YMAX ≈ 255 on the alpha
+    // plane; uniform alpha would give YMIN == YMAX. Spread > 100 is a
+    // generous floor that catches the bad case cleanly.
+    //
+    // `-c:v libvpx-vp9` before `-i` is the load-bearing piece: ffmpeg's
+    // default VP9 decoder path strips the BlockAdditional alpha track
+    // when decoding to non-rgba pixel formats; forcing the libvpx-vp9
+    // decoder + `-pix_fmt rgba` is how we get the alpha plane back.
+    const statsResult = runFfmpegSync([
+      "-hide_banner",
+      "-v",
+      "error",
+      "-c:v",
+      "libvpx-vp9",
+      "-i",
+      alphaOutputPath,
+      "-pix_fmt",
+      "rgba",
+      "-vf",
+      "extractplanes=a,signalstats,metadata=mode=print:file=-",
+      "-f",
+      "null",
+      "-",
+    ]);
+    if (statsResult.exitCode !== 0) {
+      throw new Error(
+        `[alpha smoke signalstats] failed (exit ${statsResult.exitCode}): ` +
+          `${statsResult.stderr.slice(-500)}`,
+      );
+    }
+    const yminMatch = statsResult.stdout.match(/lavfi\.signalstats\.YMIN=(\d+)/);
+    const ymaxMatch = statsResult.stdout.match(/lavfi\.signalstats\.YMAX=(\d+)/);
+    if (!yminMatch || !ymaxMatch) {
+      throw new Error(
+        `[alpha smoke signalstats] could not parse YMIN/YMAX from output: ` +
+          `${statsResult.stdout.slice(0, 500)}`,
+      );
+    }
+    const ymin = Number.parseInt(yminMatch[1], 10);
+    const ymax = Number.parseInt(ymaxMatch[1], 10);
+    expect(ymax - ymin).toBeGreaterThan(100);
   });
 });