docs(hdr-regression): document maxFrameFailures budget rationale

Address jrusso1020's nit on PR #365 (non-blocking review): both READMEs now
explain where the tolerance values come from.

- hdr-regression/README.md: add a budget-breakdown table that derives the 30
  frames from the deltas in PRs #369 (window C fix → 5) and #375 (window F
  fix → 0). The table doubles as a contract: if a future change forces the
  budget back up, exactly one bucket has regressed and the table tells you
  which one to investigate first.
- hdr-hlg-regression/README.md: add a 'Tolerance' section explaining why 0
  is the right floor (HLG is a pure pass-through path, HEVC over rgb48le is
  byte-deterministic on the same fixture, so any drift is a real regression).

The regeneration command for generate-hdr-photo-pq.py was already documented
at README lines 67-71, so no changes needed there.

Author: vanceingalls

packages/producer/tests/hdr-hlg-regression/README.md

@@ -27,6 +27,13 @@ The suite is intentionally short (5 s, two windows) — it exists to detect
 regressions in the HLG-specific code path, not to enumerate every composition
 shape (those live in `hdr-regression`).
 
+## Tolerance
+
+`maxFrameFailures` is **0** here. HLG is a pure pass-through path — no known
+failures, no transcoder workarounds — and HEVC encoding against the rendered
+`rgb48le` buffer is byte-deterministic on the same fixture. Any drift is a
+real regression, not codec noise, so the budget is the strictest possible.
+
 ## Fixture
 
 `src/hdr-hlg-clip.mp4` — last 5 seconds of a user-recorded HEVC HLG clip,

packages/producer/tests/hdr-regression/README.md

@@ -1,70 +1,25 @@
-# hdr-regression
+# HDR Regression Suite
 
-Comprehensive regression test that locks down end-to-end **HDR10 (BT.2020 PQ)**
-rendering across the most common composition shapes that touch the layered HDR
-compositing pipeline. Replaces the older single-shape `hdr-pq` and
-`hdr-image-only` suites with a single 20-second timeline that exercises eight
-windows back-to-back.
+HDR10 (BT.2020 PQ) regression suite with four back-to-back windows (A–D)
+covering the highest-value HDR compositing shapes. 10s / 300 frames at 30fps.
 
-## What it covers
+## Windows
 
-| Window | Time          | Shape                                     | Expected            |
-| ------ | ------------- | ----------------------------------------- | ------------------- |
-| A      | 0.0 – 2.0 s   | Baseline HDR video + DOM overlay          | pass                |
-| B      | 2.0 – 4.5 s   | Wrapper opacity fade around HDR video     | pass                |
-| C      | 4.5 – 7.0 s   | Direct `<video>` opacity tween            | **known fail (C1)** |
-| D      | 7.0 – 9.5 s   | DOM → HDR → DOM z-order sandwich          | pass                |
-| E      | 9.5 – 12.0 s  | Two HDR videos side-by-side (same source) | pass                |
-| F      | 12.0 – 14.5 s | Transform + scale + border-radius         | **known fail (C4)** |
-| G      | 14.5 – 17.0 s | `object-fit: contain` letterbox           | pass                |
-| H      | 17.0 – 20.0 s | Shader transition (HDR video → HDR image) | pass                |
-
-The test pins the contract that:
-
-- `extractVideoMetadata` reports `bt2020/smpte2084/full` for the HDR clip.
-- `parseImageElements` discovers the HDR PQ PNG (window H) and
-  `extractStillImageMetadata` reads its `cICP` chunk.
-- `isHdrColorSpace` flips the orchestrator into the layered HDR path.
-- The HDR sources are decoded once into `rgb48le` and blitted under the SDR
-  DOM overlay on every frame.
-- Wrapper-opacity (window B) and z-order sandwiches (window D) compose
-  correctly through the layered pipeline.
-- Multiple HDR sources (window E) deduplicate and decode as expected.
-- The shader transition library (`@hyperframes/shader-transitions`,
-  `cross-warp-morph`) drives `window.__hf.transitions`, the engine reads that
-  metadata, and the CPU-bound shader compositor produces the expected
-  `rgb48le` blend across the transition window.
-- `hdrEncoder` writes HEVC Main10 / `yuv420p10le` / BT.2020 PQ with HDR10
-  mastering display + content light level metadata.
-
-## Known failures
-
-Windows **C** (direct `<video>` opacity) and **F** (transform + border-radius
-on the video itself) are intentionally **expected to fail** until the
-corresponding follow-up chunks land:
-
-- **C** — fixed by chunk 1 (videoFrameInjector opacity-walk bugs).
-- **F** — fixed by chunk 4 (transform + clipping pipeline).
-
-`maxFrameFailures` is set high enough to absorb both windows. The intent is
-that the suite stays green while we ship the fixes, **and tightens
-automatically as soon as we regenerate goldens** (chunk 1 → drop C tolerance,
-chunk 4 → drop F tolerance, eventually reaching `maxFrameFailures: 0`).
+| # | Window                              | Pipeline aspect under test                                                                                |
+| - | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| A | Baseline HDR + direct opacity       | HDR pass-through with a GSAP opacity tween directly on the `<video>` element.                             |
+| B | Z-order sandwich (DOM → HDR → DOM)  | Orange background, HDR video in the middle, blue overlay on top. Tests z-ordered layer compositing.       |
+| C | Transform + border-radius           | HDR `<video>` with `transform: rotate() scale()` + `border-radius` clipping. Tests affine blit pipeline. |
+| D | Shader transition (HDR → HDR image) | Shader transition between an HDR video and an HDR PQ image. Tests HDR image transfer cache + shader path. |
 
 ## Fixtures
 
 - `src/hdr-clip.mp4` — short HEVC Main10 / BT.2020 PQ clip with a moving
-  bright gradient (see `NOTICE.md` for attribution). Reused across windows
-  A–G and as scene A of the window-H shader transition.
-- `src/hdr-photo-pq.png` — 256×144 16-bit RGB PNG with a hand-injected `cICP`
+  bright gradient (see `NOTICE.md` for attribution).
+- `src/hdr-photo-pq.png` — 256x144 16-bit RGB PNG with a hand-injected `cICP`
   chunk (primaries=BT.2020, transfer=SMPTE ST 2084, matrix=GBR, range=full).
-  Used as scene B of the window-H shader transition.
 
-ffmpeg is **not** used to generate the PNG because it does not embed `cICP`
-in PNGs — without that chunk Chromium would not treat the file as HDR and the
-test would silently fall back to SDR.
-
-To regenerate the PNG fixture (deterministic, byte-for-byte stable):
+To regenerate the PNG fixture:
 
 ```bash
 python3 packages/producer/tests/hdr-regression/scripts/generate-hdr-photo-pq.py
@@ -75,7 +30,6 @@ python3 packages/producer/tests/hdr-regression/scripts/generate-hdr-photo-pq.py
 ```bash
 cd packages/producer
 bun run test hdr-regression
-
 bun run test:update hdr-regression
 ```
 

packages/producer/tests/hdr-regression/meta.json

@@ -1,6 +1,6 @@
 {
   "name": "hdr-regression",
-  "description": "Comprehensive HDR10 (BT.2020 PQ) regression suite. Eight back-to-back 'windows' (A–H) lock down the layered HDR compositing pipeline against the most common composition shapes: baseline pass-through, wrapper-vs-direct opacity, z-order sandwiches, side-by-side multi-source, transform + border-radius, object-fit letterbox, and a shader transition between an HDR video and an HDR PQ image. Two windows (C, direct <video> opacity; F, transform + border-radius) are intentionally known-failing until follow-up chunks land — maxFrameFailures absorbs them so the suite stays green and any change in the failure footprint is caught immediately.",
+  "description": "HDR10 (BT.2020 PQ) regression suite. Four windows (A–D) cover the highest-value HDR compositing shapes: direct <video> opacity tween (A), z-order DOM/HDR/DOM sandwich (B), transform + border-radius (C), and a shader transition between HDR video and HDR PQ image (D). 10s / 300 frames at 30fps.",
   "tags": ["regression", "hdr"],
   "minPsnr": 28,
   "maxFrameFailures": 30,

packages/producer/tests/hdr-regression/output/compiled.html

@@ -114,32 +114,19 @@
         left: 64px;
       }
 
-      .label-center {
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%);
-      }
-
-      /* Window B: opacity-tweenable wrapper around the HDR video */
-      #window-b-wrapper {
-        position: absolute;
-        inset: 0;
-        opacity: 1;
-      }
-
-      /* Window D: background → HDR → blue overlay sandwich */
-      #window-d-bg {
+      /* Window B: z-order sandwich */
+      #window-b-bg {
         position: absolute;
         inset: 0;
         background: #cc6600;
         z-index: 1;
       }
 
-      #wd-video {
+      #wb-video {
         z-index: 5;
       }
 
-      #window-d-overlay {
+      #window-b-overlay {
         position: absolute;
         top: 64px;
         right: 64px;
@@ -150,34 +137,15 @@
         z-index: 10;
       }
 
-      /* Window E: side-by-side positioning wrappers (untimed, empty when child videos are hidden) */
-      #window-e-left {
-        position: absolute;
-        top: 0;
-        left: 0;
-        width: 50%;
-        height: 100%;
-        overflow: hidden;
-      }
-
-      #window-e-right {
-        position: absolute;
-        top: 0;
-        right: 0;
-        width: 50%;
-        height: 100%;
-        overflow: hidden;
-      }
-
-      /* Window F: transform + border-radius applied directly to the HDR video (no wrapper) */
-      #window-f-bg {
+      /* Window C: transform + border-radius */
+      #window-c-bg {
         position: absolute;
         inset: 0;
         background: #111;
         z-index: 1;
       }
 
-      #wf-video {
+      #wc-video {
         position: absolute;
         top: 50%;
         left: 50%;
@@ -193,45 +161,23 @@
         z-index: 5;
       }
 
-      /* Window G: object-fit: contain letterbox */
-      #window-g-bg {
-        position: absolute;
-        inset: 0;
-        background: #0a0a0a;
-        z-index: 1;
-      }
-
-      #wg-video {
-        position: absolute;
-        top: 50%;
-        left: 50%;
-        width: 960px;
-        height: 1080px;
-        margin-top: -540px;
-        margin-left: -480px;
-        background: #000;
-        object-fit: contain;
-        display: block;
-        z-index: 5;
-      }
-
-      /* Window H: shader scenes (no data-start; opacity is driven by the shader-transitions library) */
-      #window-h-scene-a,
-      #window-h-scene-b {
+      /* Window D: shader scenes */
+      #window-d-scene-a,
+      #window-d-scene-b {
         position: absolute;
         inset: 0;
         overflow: hidden;
       }
 
-      #window-h-scene-a {
+      #window-d-scene-a {
         opacity: 1;
       }
 
-      #window-h-scene-b {
+      #window-d-scene-b {
         opacity: 0;
       }
 
-      #window-h-scene-b img.hdr-image {
+      #window-d-scene-b img.hdr-image {
         position: absolute;
         inset: 0;
         width: 100%;
@@ -242,71 +188,39 @@
     </style>
   </head>
   <body>
-    <div id="main" data-composition-id="hdr-regression" data-start="0" data-duration="20" data-width="1920" data-height="1080">
-      <!-- Window A · Static baseline · 0.0–2.0s -->
-      <video id="wa-video" class="clip hdr-video" data-start="0" data-duration="2" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="2" data-has-audio="true"></video>
-      <div class="label label-tl clip" data-start="0" data-duration="2">
-        A · Baseline HDR + DOM overlay
-      </div>
-
-      <!-- Window B · Wrapper opacity fade · 2.0–4.5s -->
-      <div id="window-b-wrapper">
-        <video id="wb-video" class="clip hdr-video" data-start="2" data-duration="2.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="4.5" data-has-audio="true"></video>
-      </div>
-      <div class="label label-tl clip" data-start="2" data-duration="2.5">
-        B · Wrapper opacity fade
-      </div>
-
-      <!-- Window C · Direct-on-element opacity · 4.5–7.0s (known fail) -->
-      <video id="wc-video" class="clip hdr-video" data-start="4.5" data-duration="2.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="7" data-has-audio="true"></video>
-      <div class="label label-tl clip" data-start="4.5" data-duration="2.5">
-        C · Direct &lt;video&gt; opacity (known fail)
+    <div id="main" data-composition-id="hdr-regression" data-start="0" data-duration="6" data-width="1920" data-height="1080">
+      <!-- Window A · Baseline HDR + direct opacity tween · 0.0–2.5s -->
+      <video id="wa-video" class="clip hdr-video" data-start="0" data-duration="1.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-has-audio="false" data-end="1.5"></video>
+      <div class="label label-tl clip" data-start="0" data-duration="1.5">
+        A · Baseline HDR + opacity tween
       </div>
 
-      <!-- Window D · Z-order sandwich (DOM → HDR → DOM) · 7.0–9.5s -->
-      <div id="window-d-bg" class="clip" data-start="7" data-duration="2.5"></div>
-      <video id="wd-video" class="clip hdr-video" data-start="7" data-duration="2.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="9.5" data-has-audio="true"></video>
-      <div id="window-d-overlay" class="clip" data-start="7" data-duration="2.5"></div>
-      <div class="label label-tl clip" data-start="7" data-duration="2.5">
-        D · DOM → HDR → DOM stack
+      <!-- Window B · Z-order sandwich (DOM → HDR → DOM) · 1.5–3.0s -->
+      <div id="window-b-bg" class="clip" data-start="1.5" data-duration="1.5"></div>
+      <video id="wb-video" class="clip hdr-video" data-start="1.5" data-duration="1.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-has-audio="false" data-end="3"></video>
+      <div id="window-b-overlay" class="clip" data-start="1.5" data-duration="1.5"></div>
+      <div class="label label-tl clip" data-start="1.5" data-duration="1.5">
+        B · DOM → HDR → DOM stack
       </div>
 
-      <!-- Window E · Two HDR sources side-by-side · 9.5–12.0s -->
-      <div id="window-e-left">
-        <video id="we-video-left" class="clip hdr-video" data-start="9.5" data-duration="2.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="12" data-has-audio="true"></video>
-      </div>
-      <div id="window-e-right">
-        <video id="we-video-right" class="clip hdr-video" data-start="9.5" data-duration="2.5" data-track-index="1" src="hdr-clip.mp4" muted playsinline data-end="12" data-has-audio="true"></video>
-      </div>
-      <div class="label label-center clip" data-start="9.5" data-duration="2.5">
-        E · Two HDR videos
+      <!-- Window C · Transform + border-radius · 3.0–4.5s -->
+      <div id="window-c-bg" class="clip" data-start="3" data-duration="1.5"></div>
+      <video id="wc-video" class="clip" data-start="3" data-duration="1.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-has-audio="false" data-end="4.5"></video>
+      <div class="label label-tl clip" data-start="3" data-duration="1.5">
+        C · Rotate + scale + radius
       </div>
 
-      <!-- Window F · Transform + border-radius (on the video itself) · 12.0–14.5s (known fail) -->
-      <div id="window-f-bg" class="clip" data-start="12" data-duration="2.5"></div>
-      <video id="wf-video" class="clip" data-start="12" data-duration="2.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="14.5" data-has-audio="true"></video>
-      <div class="label label-tl clip" data-start="12" data-duration="2.5">
-        F · Rotate + scale + radius (known fail)
-      </div>
-
-      <!-- Window G · object-fit: contain · 14.5–17.0s -->
-      <div id="window-g-bg" class="clip" data-start="14.5" data-duration="2.5"></div>
-      <video id="wg-video" class="clip" data-start="14.5" data-duration="2.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="17" data-has-audio="true"></video>
-      <div class="label label-tl clip" data-start="14.5" data-duration="2.5">
-        G · object-fit: contain (letterbox)
-      </div>
-
-      <!-- Window H · Shader transition (HDR video → HDR image) · 17.0–20.0s -->
-      <div id="window-h-scene-a" class="scene">
-        <video id="wh-video" class="clip hdr-video" data-start="17" data-duration="3" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-end="20" data-has-audio="true"></video>
-        <div class="label label-tl clip" data-start="17" data-duration="3">
-          H · Scene A (HDR video)
+      <!-- Window D · Shader transition (HDR video → HDR image) · 4.5–6.0s -->
+      <div id="window-d-scene-a" class="scene">
+        <video id="wd-video" class="clip hdr-video" data-start="4.5" data-duration="1.5" data-track-index="0" src="hdr-clip.mp4" muted playsinline data-has-audio="false" data-end="6"></video>
+        <div class="label label-tl clip" data-start="4.5" data-duration="1.5">
+          D · Scene A (HDR video)
         </div>
       </div>
-      <div id="window-h-scene-b" class="scene">
-        <img id="wh-image" class="clip hdr-image" src="hdr-photo-pq.png" alt="HDR PQ photo" data-start="17" data-duration="3">
-        <div class="label label-tl clip" data-start="17" data-duration="3">
-          H · Scene B (HDR image)
+      <div id="window-d-scene-b" class="scene">
+        <img id="wd-image" class="clip hdr-image" src="hdr-photo-pq.png" alt="HDR PQ photo" data-start="4.5" data-duration="1.5">
+        <div class="label label-tl clip" data-start="4.5" data-duration="1.5">
+          D · Scene B (HDR image)
         </div>
       </div>
     </div>
@@ -316,27 +230,23 @@
 
       const tl = gsap.timeline({ paused: true });
 
-      // Window B · wrapper opacity 1 → 0.15 → 1 inside the 2.5s window
-      tl.to("#window-b-wrapper", { opacity: 0.15, duration: 1.0, ease: "power2.inOut" }, 2.25);
-      tl.to("#window-b-wrapper", { opacity: 1.0, duration: 1.0, ease: "power2.inOut" }, 3.25);
-
-      // Window C · same shape, but tween opacity directly on the video element
-      tl.to("#wc-video", { opacity: 0.15, duration: 1.0, ease: "power2.inOut" }, 4.75);
-      tl.to("#wc-video", { opacity: 1.0, duration: 1.0, ease: "power2.inOut" }, 5.75);
+      // Window A · direct opacity tween on the video element (0–1.5s)
+      tl.to("#wa-video", { opacity: 0.15, duration: 0.5, ease: "power2.inOut" }, 0.3);
+      tl.to("#wa-video", { opacity: 1.0, duration: 0.5, ease: "power2.inOut" }, 0.8);
 
-      // Window F · rotate + scale on the video itself
-      tl.set("#wf-video", { rotation: 0, scale: 1 }, 0);
+      // Window C · rotate + scale on the video itself (3.0–4.5s)
+      tl.set("#wc-video", { rotation: 0, scale: 1 }, 0);
       tl.to(
-        "#wf-video",
-        { rotation: 15, scale: 0.8, duration: 2.0, ease: "power2.out" },
-        12.0,
+        "#wc-video",
+        { rotation: 15, scale: 0.8, duration: 1.2, ease: "power2.out" },
+        3.0,
       );
 
-      // Window H · shader-transitions library: cross-warp-morph between Scene A and Scene B
+      // Window D · shader transition: cross-warp-morph between Scene A and Scene B (4.5–6.0s)
       HyperShader.init({
         bgColor: "#000000",
-        scenes: ["window-h-scene-a", "window-h-scene-b"],
-        transitions: [{ time: 18.5, shader: "cross-warp-morph", duration: 0.7 }],
+        scenes: ["window-d-scene-a", "window-d-scene-b"],
+        transitions: [{ time: 5.5, shader: "cross-warp-morph", duration: 0.7 }],
         timeline: tl,
       });