@plasius/gpu-lighting 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -20,7 +20,27 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
-## [0.2.5] - 2026-06-15
+## [0.2.7] - 2026-06-16
+
+- **Added**
+  - Extended the wavefront lighting contract with compact medium-state carry,
+    visibility-probe ray helpers, MIS/exclusive-emissive probe controls, and
+    deterministic CPU reference fixtures for continuation validation.
+
+- **Changed**
+  - Wavefront ray-record documentation now mirrors the current renderer payload
+    shape, including medium-stack and spectral-state fields used for transport
+    validation.
+
+- **Fixed**
+  - Wavefront continuation helpers now report total internal reflection
+    explicitly and keep refraction/transparency medium transitions stable in the
+    published reference contract.
+
+- **Security**
+  - (placeholder)
+
+## [0.2.6] - 2026-06-16
 
 - **Added**
   - Added concrete volumetric WGSL kernels for `volumetricShadow` and
@@ -28,14 +48,25 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
     integration for the published realtime and reference profiles.
   - Added concrete HDRI/IBL WGSL kernels for `irradianceConvolution`,
     `specularPrefilter`, and `brdfLut`.
+  - Added a renderer-aligned `wavefront` lighting technique with concrete
+    WGSL jobs for terminal radiance accumulation and continuation scattering.
+  - Added `createWavefrontLightingPlan()`,
+    `evaluateWavefrontTerminalRadiance()`, and
+    `evaluateWavefrontContinuationEvent()` so downstream packages and tests can
+    validate emissive-hit, environment-hit, miss-darkening, reflection,
+    refraction, and transparency behavior without reimplementing the contract.
 
 - **Changed**
   - README now documents the delivered volumetrics and HDRI kernel scope with
     technique-level descriptions instead of leaving those exported jobs implied.
+  - Eames capture helpers now resolve workspace roots correctly from both
+    ordinary repo checkouts and `git worktree` paths.
 
 - **Fixed**
   - Package tests now fail if any exported `hybrid`, `volumetrics`, or `hdri`
     job regresses to placeholder text or an empty/no-op `process_job` body.
+  - Eames asset-path and capture-bridge tests are now worktree-safe instead of
+    assuming the package always lives under a literal `/gpu-lighting/` path.
 
 ## [0.2.2] - 2026-06-11
 
@@ -464,7 +495,8 @@ 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.5...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/gpu-lighting/compare/v0.2.7...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.5]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.5
+[0.2.6]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.6
+[0.2.7]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.7

package/README.md

@@ -162,6 +162,104 @@ const profileManifest = getLightingProfileWorkerManifest("realtime");
 console.log(profileManifest.jobs.map((job) => job.worker.jobType));
 ```
 
+## Wavefront Lighting Contracts
+
+`@plasius/gpu-lighting` now also publishes a renderer-aligned `wavefront`
+technique for the first active-ray lighting slice. It keeps the queue layout,
+buffer contract names, and terminal-hit policy aligned with
+`@plasius/gpu-renderer` while owning the lighting-specific WGSL for terminal
+radiance accumulation and continuation scattering.
+
+```js
+import {
+  createWavefrontLightingPlan,
+  createWavefrontReferenceFixture,
+  createWavefrontVisibilityProbeRay,
+  evaluateWavefrontMaterialReference,
+  evaluateWavefrontTerminalRadiance,
+  evaluateWavefrontVisibilityProbe,
+  loadLightingTechniqueWorkerBundle,
+} from "@plasius/gpu-lighting";
+
+const plan = createWavefrontLightingPlan({
+  maxDepth: 6,
+  queueCapacity: 4096,
+  explicitLightSampling: true,
+  visibilityProbeMode: "mis-balanced",
+});
+
+const bundle = await loadLightingTechniqueWorkerBundle("wavefront");
+const emissive = evaluateWavefrontTerminalRadiance({
+  hitType: "emissive",
+  throughput: [0.5, 0.5, 0.5],
+  emission: [8, 6, 4],
+});
+const material = evaluateWavefrontMaterialReference({
+  hitType: "surface",
+  eventKind: "refraction",
+  throughput: [1, 1, 1],
+  transmission: [0.92, 0.95, 0.98],
+  ior: 1.45,
+  shadingNormal: [0, 1, 0],
+  viewDirection: [0, 1, 0],
+  currentMediumRefId: 0,
+  surfaceMediumRefId: 7,
+});
+const probeRay = createWavefrontVisibilityProbeRay({
+  rayId: 12,
+  parentRayId: 4,
+  sourcePixelId: 9,
+  sampleId: 2,
+  bounce: 1,
+  origin: [0, 1, 0],
+  direction: [0.25, -1, 0.15],
+  throughput: [0.8, 0.7, 0.6],
+  mediumRefId: 7,
+  mediumStack: [7],
+});
+const probe = evaluateWavefrontVisibilityProbe({
+  probeRay,
+  probeMode: "exclusive-emissive",
+  activeEmissiveRadiance: [4, 3, 2],
+  emissiveRadiance: [4, 3, 2],
+  transparentSegments: [[0.8, 0.8, 0.8]],
+});
+const fixture = createWavefrontReferenceFixture({
+  hitType: "emissive",
+  throughput: [0.8, 0.7, 0.6],
+  emission: [4, 3, 2],
+  visibilityProbe: {
+    probeMode: "mis-balanced",
+    emissiveRadiance: [0.6, 0.3, 0.1],
+    transparentSegments: [[0.7, 0.8, 0.9]],
+  },
+});
+
+console.log(plan.requiredRendererPassOrder);
+console.log(plan.visibilityProbeMode);
+console.log(bundle.jobs.map((job) => job.label));
+console.log(emissive.radiance);
+console.log(material.continuation.mediumState);
+console.log(probe.doubleCountPrevented);
+console.log(fixture.tolerance);
+```
+
+This slice keeps emissive hits, environment hits, and environment-miss dark
+fallbacks on the lighting package surface without reintroducing a depth-first
+shader dependency into the renderer-owned wavefront queue model.
+
+The continuation/reference surface now also exposes:
+
+- compact medium-state carry for refraction/transparency events, including
+  total-internal-reflection fallback reporting
+- shared-ray payload helpers where visibility probes reuse the base ray layout
+  and encode their kind through the low bits of `flags`
+- optional probe contribution helpers with `mis-balanced` and
+  `exclusive-emissive` modes so active emissive hits remain correct even when
+  explicit light sampling is enabled
+- deterministic reference fixtures that publish buffer-like accumulation outputs
+  with a documented default tolerance of `0.0005` for CPU-vs-GPU comparisons
+
 ## Distance-Banded Lighting
 
 ```js