@plasius/gpu-lighting 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -20,7 +20,7 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
-## [0.2.3] - 2026-06-14
+## [0.2.4] - 2026-06-14
 
 - **Added**
   - (placeholder)
@@ -43,14 +43,86 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
   - Added `sunlitBaseline` to environment lighting presets and wavefront
     lighting options so renderers can apply a time-of-day daylight floor at
     terminal path collisions without raising ambient residual colour.
-  - (placeholder)
+  - Added an Eames screenshot capture runbook and browser-runtime helpers so
+    validation scripts can attach to an existing WebGPU-capable Chrome over CDP
+    instead of only launching a fresh Playwright Chromium profile.
+  - Added generic glTF material forwarding in the Eames validation loader so
+    authored specular, sheen, clearcoat, transmission, emissive, and IOR values
+    can flow into the shared wavefront renderer without model-name overrides.
+  - Added Eames validation HUD/result diagnostics for GPU worker-job throughput
+    so validation runs can report compute-dispatch jobs per frame, per second,
+    and per command submission.
+  - Added adaptive Eames validation frame budgeting so motion-oriented runs can
+    request a `frameTimeBudgetMs` and inspect delivered `rendered/target spp`
+    in the HUD and result payload.
+  - Added `@plasius/gpu-performance`-governed adaptive SPP control to the Eames
+    validation harness so frame-budgeted runs degrade and recover through a
+    shared quality-ladder contract instead of a demo-local policy alone.
 
 - **Changed**
   - Reduced ambient residual strength for the grass-field, forest, warehouse,
     and cavern environment preset families to avoid low-sample whitewash.
+  - Eames validation capture scripts now pin deterministic render settings by
+    default and write canvas-only PNG artifacts plus comparable black-pixel and
+    luminance metrics under `output/playwright/eames-environments/`.
+  - Eames validation page and capture entry points now accept up to `256 spp`,
+    and the validation boot timeout now scales with requested render workload
+    instead of failing at a fixed 60-second watchdog.
+  - `gpu-lighting` local typecheck coverage now includes the Eames validation
+    page, loader, and capture helpers instead of checking only the legacy demo
+    entry points.
+  - Eames validation mesh loading now preserves authored UVs and decoded
+    base-colour, metallic-roughness, normal, and occlusion maps so the shared
+    wavefront renderer can evaluate materially richer leather, wood, and chrome
+    surfaces.
+  - Eames validation meshes now forward decoded emissive maps as well so the
+    shared wavefront renderer can keep all material texture evaluation in the
+    GPU render path.
+  - Eames validation mesh building now preserves authored material values
+    generically instead of deriving chrome, leather, and wood behaviour from
+    material names.
+  - Eames validation page can now freeze its own canvas and POST the PNG back
+    to a local bridge endpoint, which provides a browser-driven screenshot
+    fallback when Playwright cannot own the Chromium process directly.
+  - Eames validation capture and reverse-pass debug entry points now share one
+    server-selection helper so port reuse, static serving, and bridge-ready
+    startup rules stay aligned across local runs and CI.
 
 - **Fixed**
-  - (placeholder)
+  - Eames Playwright validation pages and capture scripts now surface import,
+    WebGPU bootstrap, and renderer startup diagnostics instead of hanging on the
+    initial HUD when a browser cannot complete setup.
+  - Eames validation renders now collect optional output-probe figures after the
+    frame render completes instead of coupling probe readback to the heavy
+    high-SPP render submission itself.
+  - Eames capture helpers now resolve browser profile and temporary output paths
+    through the host OS temp directory instead of assuming macOS-only
+    `/private/tmp`, which fixes Linux CI validation.
+  - Eames validation query parsing now preserves documented fallback defaults
+    when numeric URL params are omitted, which keeps standard captures out of
+    accidental reverse-pass debug mode.
+  - Eames validation motion renders now preserve the built-in adaptive
+    `frameTimeBudgetMs` default when the query parameter is omitted, so the
+    shared `@plasius/gpu-performance` quality ladder still engages on the
+    standard animated validation route.
+  - Animated source-marker captures now reuse the injected product-studio scene
+    helper during per-frame rebuilds instead of throwing when motion is enabled.
+  - Eames capture waits now scale with requested resolution, frame count, depth,
+    and SPP so higher-workload validation runs are not aborted at a stale fixed
+    timeout.
+  - Eames glTF validation materials now honor `KHR_texture_transform` offsets,
+    scales, and rotation by baking transformed texture maps during decode so
+    chair screenshots reflect the authored leather and wood layouts.
+  - The capture bridge now rejects non-loopback browser origins and confines
+    capture writes to `output/playwright/eames-environments/`, which closes the
+    browser-driven workspace overwrite path on the local upload endpoint.
+  - The Eames glTF loader now honors interleaved `bufferView.byteStride` values,
+    which keeps positions, normals, and UVs correct for legal strided assets.
+  - The capture bridge now serves static assets without a pre-stat/read race,
+    and browser-driven capture uploads are restricted to loopback bridge URLs.
+  - The standalone repo now ships the Eames demo asset set referenced by the
+    validation page so fresh checkouts can render the chair without external
+    workspace-only files.
 
 - **Security**
   - (placeholder)
@@ -389,7 +461,7 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 [0.1.16]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.16
 [0.1.17]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.17
 [0.1.19]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.19
-[Unreleased]: https://github.com/Plasius-LTD/gpu-lighting/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/gpu-lighting/compare/v0.2.4...HEAD
 [0.2.0]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.0
 [0.2.2]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.2
-[0.2.3]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.3
+[0.2.4]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.4

package/README.md

@@ -42,6 +42,81 @@ For browser-only serving, the demo resolves `@plasius/gpu-shared` through an
 import map so the page stays on the published package surface rather than a
 package-private source path.
 
+## Screenshot Capture
+
+The repo also carries the Eames-chair environment validation harness under
+`demo/eames-environments/` plus tracked Playwright helpers under
+`scripts/eames-environments/`. The referenced chair asset is tracked under
+`data/models/eames-lounge-chair-ottoman/` so fresh repo checkouts can run the
+validation page without depending on a parent monorepo checkout. Build
+`gpu-performance`, `gpu-renderer`, and `gpu-lighting` first, then run:
+
+```bash
+node scripts/eames-environments/capture.mjs
+```
+
+For reverse-pass black-pixel diagnostics, run:
+
+```bash
+node scripts/eames-environments/path-debug-capture.mjs
+```
+
+If fresh Playwright Chromium bootstrap is unstable on macOS, start a
+WebGPU-capable Chrome separately with remote debugging enabled and set
+`PLASIUS_CAPTURE_CDP_URL=http://127.0.0.1:<port>` before running the capture
+script. The validation page now reports bootstrap step, detail, and WebGPU
+availability through `window.__plasiusCaptureState` and
+`window.__plasiusCaptureError` so capture failures stop at a named phase rather
+than hanging on the initial HUD.
+
+For browser-controlled fallbacks, start
+`node scripts/eames-environments/capture-bridge-server.mjs <port>` and open the
+validation page with `captureBitmap=1` plus
+`captureUploadPath=output/playwright/eames-environments/<name>.png`. If the page
+is being served by a plain static server such as `python -m http.server`, also
+pass
+`captureUploadUrl=http://127.0.0.1:<port>/__plasius-capture`. The page will
+freeze its own canvas and POST the PNG back to the bridge server once the
+render completes. The browser-side upload helper now rejects non-loopback
+capture endpoints so this fallback cannot be redirected at arbitrary remote
+origins.
+
+The main capture and reverse-pass debug capture entry points now share the same
+server-selection helper, so local reuse, fresh static-server startup, and
+bridge fallback all follow the same port and readiness rules across macOS and
+Linux.
+
+The capture scripts now pin deterministic validation settings unless explicitly
+overridden:
+
+- `PLASIUS_CAPTURE_MAX_DEPTH=8`
+- `PLASIUS_CAPTURE_SPP=1`
+- `PLASIUS_CAPTURE_FRAMES=1`
+- `PLASIUS_CAPTURE_DENOISE=1`
+- `PLASIUS_CAPTURE_MOTION=0`
+- `PLASIUS_CAPTURE_FRAME_INDEX=777`
+- `PLASIUS_CAPTURE_PROBE=1`
+
+They save canvas-only PNGs plus per-capture JSON under
+`output/playwright/eames-environments/`, including exact-black, near-black, and
+average-luminance metrics so screenshot comparisons stay apples-to-apples. The
+validation page now decouples optional probe readback from the heavy render
+submission itself, which keeps higher-SPP screenshot validation more stable.
+For motion or realtime validation, the page also accepts `frameTimeBudgetMs`
+and will render at least one full-screen sample before adaptively spending the
+rest of the per-frame budget on additional SPP passes. The HUD reports
+`rendered/target spp` whenever the budgeted frame lands below the configured
+ceiling. When `gpu-performance/dist/index.js` is available, the Eames harness
+also routes that target through a `@plasius/gpu-performance` quality ladder fed
+by `gpu-renderer`'s wavefront adaptive-sampling levels, so the requested SPP
+becomes a release-grade ceiling rather than an ungoverned demo-local heuristic.
+The Eames loader also preserves authored UVs, decoded base-colour,
+metallic-roughness, normal, occlusion, and emissive maps, plus authored glTF
+material factors such as clearcoat, sheen colour, specular colour,
+transmission, and IOR when present. That keeps the validation scene on the
+shared renderer path instead of relying on material-name-specific overrides for
+leather, wood, and chrome.
+
 ## Usage (load one technique)
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-lighting",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Advanced lighting WGSL modules and planning profiles for @plasius/gpu-worker.",
   "type": "module",
   "sideEffects": false,
@@ -26,7 +26,7 @@
   "scripts": {
     "build": "tsup && cp -R src/techniques dist/techniques",
     "demo": "python3 -m http.server --directory ..",
-    "typecheck": "node --check src/index.js && node --check demo/lighting-demo-config.js && node --check demo/main.js",
+    "typecheck": "node --check src/index.js && node --check demo/lighting-demo-config.js && node --check demo/main.js && node --check demo/eames-environments/page.js && node --check demo/eames-environments/eames-loader.js && node --check scripts/eames-environments/capture-runtime.mjs && node --check scripts/eames-environments/capture-server.mjs && node --check scripts/eames-environments/capture.mjs && node --check scripts/eames-environments/path-debug-capture.mjs && node --check scripts/eames-environments/capture-bridge-server.mjs",
     "audit:eslint": "eslint . --max-warnings=0",
     "audit:deps": "npm ls --all --omit=optional --omit=peer > /dev/null 2>&1 || true",
     "audit:npm": "npm audit --audit-level=high --omit=dev",