@plasius/gpu-renderer 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -23,18 +23,40 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
-## [0.2.0] - 2026-06-05
+## [0.2.1] - 2026-06-06
 
 - **Added**
   - Added deterministic wavefront reference helpers for primary-ray creation,
     triangle-hit evaluation, nearest-hit selection, and environment-miss
     fallback alongside regression tests for task-level acceptance coverage.
+  - Added ADR coverage for mesh BVH wavefront path tracing as the display-quality
+    baseline.
 
 - **Changed**
-  - (placeholder)
+  - Promoted the mesh BVH wavefront renderer source into the canonical
+    `src/wavefront-compute.js` module so source, typings, tests, and package
+    builds no longer drift behind generated artifacts.
+  - Changed wavefront mesh tracing to dispatch bounce intersection and
+    surface-resolution work from GPU-authored active-ray counts instead of the
+    fixed tile capacity after queue compaction.
+  - Changed the npm CD workflow to prepare package version and changelog
+    metadata locally, then publish the validated tag while persisting release
+    metadata through an automation PR branch instead of direct protected-main
+    pushes.
 
 - **Fixed**
-  - (placeholder)
+  - Fixed wavefront source ownership so display-quality mesh BVH code is not
+    hidden behind a legacy module split.
+  - Preserved the wavefront mode/workgroup constants, shader-source helper,
+    one-shot frame helper, and `renderFrame(...)` compatibility wrapper while
+    promoting the mesh BVH renderer source.
+  - Fixed a production performance regression where compacted continuation
+    queues still scheduled full-capacity per-bounce workgroups.
+  - Fixed low-sample wavefront surface traces so terminal non-emissive surface
+    collisions use an environment-derived ambient floor instead of a flat or
+    missing fallback.
+  - Fixed release metadata versioning, demo dependencies, and one-shot
+    wavefront cleanup blockers found during PR validation.
 
 - **Security**
   - (placeholder)
@@ -289,4 +311,4 @@ All notable changes to this project will be documented in this file.
 [0.1.11]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.11
 [0.1.12]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.12
 [0.1.14]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.14
-[0.2.0]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.0
+[0.2.1]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.1

package/README.md

@@ -141,6 +141,10 @@ const renderer = await createWavefrontPathTracingComputeRenderer({
 renderer.renderOnce();
 ```
 
+Existing consumers that still call `renderFrame(...)` or
+`renderWavefrontPathTracingComputeFrame(...)` remain supported as compatibility
+wrappers around the canonical mesh renderer.
+
 Analytic scene objects remain available for debug fixtures:
 
 ```js
@@ -203,7 +207,12 @@ sampling, temporal accumulation, and better material PDFs are hardened.
 For static mesh scenes, the GPU acceleration build is submitted once and then
 reused by subsequent frames. Per-frame tracing writes one dynamic uniform slot
 per tile/sample or post-process pass and batches tile tracing, tile output,
-optional denoise, and presentation into a single command submission. WebGPU
+optional denoise, and presentation into a single command submission. After each
+primary-ray or compaction pass, the GPU writes the active-ray workgroup count
+into the counter buffer and the encoder copies it into an indirect-dispatch
+argument buffer. Intersection and surface-resolution passes therefore scale
+with active continuation rays instead of the maximum tile capacity, while still
+avoiding CPU readback between bounces. WebGPU
 still preserves ordering between dependent bounce passes, but the renderer no
 longer forces one CPU queue submission per tile/sample.
 Environment-light portals can additionally guide and gate sky/HDRI contribution
@@ -242,6 +251,8 @@ renderer.bindXrManager(xr, {
 - `createRayTracingRenderPlan(options)`
 - `createWavefrontPathTracingComputeRenderer(options)`
 - `createWavefrontPathTracingComputeConfig(options)`
+- `createWavefrontPathTracingComputeShaderSource(options?)`
+- `renderWavefrontPathTracingComputeFrame(options)`
 - `createWavefrontReferenceRay(config, options?)`
 - `intersectWavefrontReferenceTriangle(ray, triangle, options?)`
 - `traceWavefrontReferenceTriangles(config, ray, triangles, options?)`
@@ -254,6 +265,9 @@ renderer.bindXrManager(xr, {
 - `packWavefrontSceneObjects(sceneObjects, capacity?)`
 - `packWavefrontTriangles(triangles, capacity?)`
 - `packWavefrontBvhNodes(nodes, capacity?)`
+- `rendererWavefrontComputeMode`
+- `rendererWavefrontComputeWorkgroupSize`
+- `rendererWavefrontComputeStatsStride`
 - `bindRendererToXrManager(renderer, xrManager, options)`
 - `defaultRendererClearColor`
 - `rendererDebugOwner`
@@ -298,6 +312,8 @@ npm run pack:check
 ## Files
 
 - `src/index.js`: WebGPU renderer runtime and XR binding helper.
+- `src/wavefront-compute.js`: Canonical WebGPU mesh BVH wavefront renderer,
+  debug scene-object fixtures, and deterministic reference helpers.
 - `src/index.d.ts`: public API typings.
 - `tests/package.test.js`: unit tests for renderer lifecycle behavior.
 - `docs/design/worker-manifest-integration.md`: renderer frame-stage DAG model.

package/dist/index.cjs

@@ -31,6 +31,7 @@ __export(index_exports, {
   createWavefrontMeshAcceleration: () => createWavefrontMeshAcceleration,
   createWavefrontPathTracingComputeConfig: () => createWavefrontPathTracingComputeConfig,
   createWavefrontPathTracingComputeRenderer: () => createWavefrontPathTracingComputeRenderer,
+  createWavefrontPathTracingComputeShaderSource: () => createWavefrontPathTracingComputeShaderSource,
   createWavefrontPathTracingPlan: () => createWavefrontPathTracingPlan,
   createWavefrontReferenceRay: () => createWavefrontReferenceRay,
   defaultRendererClearColor: () => defaultRendererClearColor,
@@ -44,11 +45,15 @@ __export(index_exports, {
   packWavefrontBvhNodes: () => packWavefrontBvhNodes,
   packWavefrontSceneObjects: () => packWavefrontSceneObjects,
   packWavefrontTriangles: () => packWavefrontTriangles,
+  renderWavefrontPathTracingComputeFrame: () => renderWavefrontPathTracingComputeFrame,
   rendererAccelerationStructureUpdateClasses: () => rendererAccelerationStructureUpdateClasses,
   rendererDebugOwner: () => rendererDebugOwner,
   rendererRayTracingStageOrder: () => rendererRayTracingStageOrder,
   rendererRepresentationBands: () => rendererRepresentationBands,
   rendererWavefrontBufferSchemaVersion: () => rendererWavefrontBufferSchemaVersion,
+  rendererWavefrontComputeMode: () => rendererWavefrontComputeMode,
+  rendererWavefrontComputeStatsStride: () => rendererWavefrontComputeStatsStride,
+  rendererWavefrontComputeWorkgroupSize: () => rendererWavefrontComputeWorkgroupSize,
   rendererWavefrontHitTypes: () => rendererWavefrontHitTypes,
   rendererWavefrontPassOrder: () => rendererWavefrontPassOrder,
   rendererWavefrontQueuePairStrategy: () => rendererWavefrontQueuePairStrategy,
@@ -74,6 +79,9 @@ var DEFAULT_SAMPLES_PER_PIXEL = 1;
 var DEFAULT_SCENE_OBJECT_CAPACITY = 128;
 var DEFAULT_ENVIRONMENT_PORTAL_CAPACITY = 32;
 var WORKGROUP_SIZE = 64;
+var rendererWavefrontComputeMode = "webgpu-compute";
+var rendererWavefrontComputeWorkgroupSize = WORKGROUP_SIZE;
+var rendererWavefrontComputeStatsStride = 8;
 var RAY_RECORD_BYTES = 80;
 var HIT_RECORD_BYTES = 208;
 var SCENE_OBJECT_RECORD_BYTES = 96;
@@ -86,7 +94,9 @@ var EMISSIVE_TRIANGLE_INDEX_BYTES = 4;
 var ENVIRONMENT_PORTAL_RECORD_BYTES = 96;
 var ACCUMULATION_RECORD_BYTES = 16;
 var CONFIG_BUFFER_BYTES = 272;
-var COUNTER_BUFFER_BYTES = 16;
+var COUNTER_DISPATCH_ARGS_OFFSET = 16;
+var INDIRECT_DISPATCH_ARGS_BYTES = 12;
+var COUNTER_BUFFER_BYTES = 32;
 var TRACE_STORAGE_BUFFER_BINDINGS = 9;
 var MATERIAL_DIFFUSE = 0;
 var MATERIAL_METAL = 1;
@@ -126,7 +136,9 @@ var wavefrontPathTracingComputeLimits = Object.freeze({
   emissiveTriangleIndexBytes: EMISSIVE_TRIANGLE_INDEX_BYTES,
   emissiveTriangleMetadataRecordBytes: BVH_NODE_RECORD_BYTES,
   environmentPortalRecordBytes: ENVIRONMENT_PORTAL_RECORD_BYTES,
-  accumulationRecordBytes: ACCUMULATION_RECORD_BYTES
+  accumulationRecordBytes: ACCUMULATION_RECORD_BYTES,
+  counterRecordBytes: COUNTER_BUFFER_BYTES,
+  indirectDispatchRecordBytes: INDIRECT_DISPATCH_ARGS_BYTES
 });
 var wavefrontSceneObjectKinds = Object.freeze({
   sphere: OBJECT_KIND_SPHERE,
@@ -1077,7 +1089,8 @@ function estimateWavefrontPathTracingMemory(options = {}) {
     environmentPortalBytes,
     configBytes: CONFIG_BUFFER_BYTES,
     counterBytes: COUNTER_BUFFER_BYTES,
-    totalHotBufferBytes: queueBytes * 2 + hitBytes + accumulationBytes + sceneObjectBytes + triangleBytes + bvhNodeBytes + bvhLeafReferenceBytes + emissiveTriangleMetadataBytes + environmentPortalBytes + CONFIG_BUFFER_BYTES + COUNTER_BUFFER_BYTES
+    indirectDispatchBytes: INDIRECT_DISPATCH_ARGS_BYTES,
+    totalHotBufferBytes: queueBytes * 2 + hitBytes + accumulationBytes + sceneObjectBytes + triangleBytes + bvhNodeBytes + bvhLeafReferenceBytes + emissiveTriangleMetadataBytes + environmentPortalBytes + CONFIG_BUFFER_BYTES + COUNTER_BUFFER_BYTES + INDIRECT_DISPATCH_ARGS_BYTES
   });
 }
 function createWavefrontPathTracingComputeConfig(options = {}) {
@@ -1154,6 +1167,7 @@ function createWavefrontPathTracingComputeConfig(options = {}) {
     environmentPortals.length > 0
   );
   return Object.freeze({
+    mode: rendererWavefrontComputeMode,
     width,
     height,
     maxDepth,
@@ -1208,6 +1222,9 @@ function getGpuUsageConstants() {
   if (typeof GPUBufferUsage === "undefined" || typeof GPUTextureUsage === "undefined" || typeof GPUShaderStage === "undefined") {
     throw new Error("WebGPU runtime unavailable. Required GPU constants are missing.");
   }
+  if (typeof GPUBufferUsage.INDIRECT !== "number") {
+    throw new Error("WebGPU runtime unavailable. GPUBufferUsage.INDIRECT is missing.");
+  }
   return {
     buffer: GPUBufferUsage,
     texture: GPUTextureUsage,
@@ -1844,6 +1861,10 @@ struct Counters {
   nextCount: atomic<u32>,
   terminatedCount: atomic<u32>,
   hitCount: atomic<u32>,
+  dispatchX: u32,
+  dispatchY: u32,
+  dispatchZ: u32,
+  dispatchPad: u32,
 };
 
 struct Candidate {
@@ -2006,6 +2027,18 @@ fn gated_environment_radiance(origin: vec3<f32>, direction: vec3<f32>) -> vec3<f
   return environment_radiance(origin, direction);
 }
 
+fn terminal_surface_environment_contribution(ray: RayRecord, hit: HitRecord) -> vec3<f32> {
+  let normal = safe_normalize(hit.shadingNormal.xyz, vec3<f32>(0.0, 1.0, 0.0));
+  let surfaceColor = max(hit.color.xyz, config.ambientColor.xyz);
+  let normalEnvironment = gated_environment_radiance(
+    hit.position.xyz + normal * 0.003,
+    normal
+  );
+  let environmentFloor = max(config.ambientColor.xyz, normalEnvironment * 0.12);
+  let materialFloor = select(0.7, 1.0, hit.materialKind == 0u || hit.materialKind == 3u);
+  return clamp_sample_radiance(ray.throughput.xyz * surfaceColor * environmentFloor * materialFloor);
+}
+
 fn default_mesh_range() -> MeshRange {
   return MeshRange(
     0u,
@@ -2577,6 +2610,17 @@ fn tone_map_radiance(value: vec3<f32>) -> vec3<f32> {
   return pow(clamp(mapped, vec3<f32>(0.0), vec3<f32>(1.0)), vec3<f32>(1.0 / 2.2));
 }
 
+fn ray_workgroups_for_count(rayCount: u32) -> u32 {
+  return max(1u, (rayCount + 63u) / 64u);
+}
+
+fn write_active_dispatch_args(activeCount: u32) {
+  counters.dispatchX = ray_workgroups_for_count(activeCount);
+  counters.dispatchY = 1u;
+  counters.dispatchZ = 1u;
+  counters.dispatchPad = 0u;
+}
+
 fn denoise_range_space(value: vec3<f32>) -> vec3<f32> {
   return value / (vec3<f32>(1.0) + value);
 }
@@ -2589,6 +2633,7 @@ fn generatePrimaryRays(@builtin(global_invocation_id) globalId: vec3<u32>) {
     atomicStore(&counters.nextCount, 0u);
     atomicStore(&counters.terminatedCount, 0u);
     atomicStore(&counters.hitCount, 0u);
+    write_active_dispatch_args(config.tilePixelCount);
   }
   if (index >= config.tilePixelCount) {
     return;
@@ -2864,9 +2909,9 @@ fn resolveSurfaceRecords(@builtin(global_invocation_id) globalId: vec3<u32>) {
   }
 
   if (ray.bounce + 1u >= config.maxDepth) {
+    let terminalEnvironment = terminal_surface_environment_contribution(ray, hit);
     accumulation[ray.rayId] =
-      accumulation[ray.rayId] +
-      vec4<f32>(ray.throughput.xyz * config.ambientColor.xyz * sample_weight(), 1.0);
+      accumulation[ray.rayId] + vec4<f32>(terminalEnvironment * sample_weight(), 1.0);
     atomicAdd(&counters.terminatedCount, 1u);
     return;
   }
@@ -2875,6 +2920,10 @@ fn resolveSurfaceRecords(@builtin(global_invocation_id) globalId: vec3<u32>) {
   let scatter = scatter_direction(ray, hit, seed);
   let nextIndex = atomicAdd(&counters.nextCount, 1u);
   if (nextIndex >= config.tilePixelCount) {
+    let overflowEnvironment = terminal_surface_environment_contribution(ray, hit);
+    accumulation[ray.rayId] =
+      accumulation[ray.rayId] + vec4<f32>(overflowEnvironment * sample_weight(), 1.0);
+    atomicAdd(&counters.terminatedCount, 1u);
     return;
   }
   let color = clamp(hit.color.xyz, vec3<f32>(0.0), vec3<f32>(1.0));
@@ -2903,8 +2952,10 @@ fn compactAndSwapQueues(@builtin(global_invocation_id) globalId: vec3<u32>) {
     return;
   }
   let nextCount = atomicLoad(&counters.nextCount);
-  atomicStore(&counters.activeCount, min(nextCount, config.tilePixelCount));
+  let activeCount = min(nextCount, config.tilePixelCount);
+  atomicStore(&counters.activeCount, activeCount);
   atomicStore(&counters.nextCount, 0u);
+  write_active_dispatch_args(activeCount);
 }
 
 @compute @workgroup_size(64)
@@ -3182,10 +3233,16 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
   );
   const counterBuffer = createBuffer(
     device,
-    constants.buffer.STORAGE | constants.buffer.COPY_DST,
+    constants.buffer.STORAGE | constants.buffer.COPY_DST | constants.buffer.COPY_SRC,
     COUNTER_BUFFER_BYTES,
     "plasius.wavefront.counters"
   );
+  const activeDispatchBuffer = createBuffer(
+    device,
+    constants.buffer.INDIRECT | constants.buffer.COPY_DST,
+    INDIRECT_DISPATCH_ARGS_BYTES,
+    "plasius.wavefront.activeDispatchArgs"
+  );
   let packedScene = packWavefrontSceneObjects(config.sceneObjects, config.sceneObjectCapacity);
   device.queue.writeBuffer(sceneObjectBuffer, 0, packedScene.buffer);
   const packedTriangles = packWavefrontTriangles(
@@ -3607,24 +3664,34 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     return true;
   }
   function encodeTileSample(encoder, tile, configOffset) {
-    const passEncoder = encoder.beginComputePass({
-      label: "plasius.wavefront.computePass"
+    const generatePass = encoder.beginComputePass({
+      label: "plasius.wavefront.generatePrimaryRaysPass"
     });
     const tileWorkgroups = Math.ceil(tile.width * tile.height / WORKGROUP_SIZE);
-    const capacityWorkgroups = Math.ceil(config.tilePixelCapacity / WORKGROUP_SIZE);
-    passEncoder.setBindGroup(0, bindGroups[0], [configOffset]);
-    passEncoder.setPipeline(pipelines.generatePrimaryRays);
-    passEncoder.dispatchWorkgroups(tileWorkgroups);
+    generatePass.setBindGroup(0, bindGroups[0], [configOffset]);
+    generatePass.setPipeline(pipelines.generatePrimaryRays);
+    generatePass.dispatchWorkgroups(tileWorkgroups);
+    generatePass.end();
     for (let bounceIndex = 0; bounceIndex < config.maxDepth; bounceIndex += 1) {
+      encoder.copyBufferToBuffer(
+        counterBuffer,
+        COUNTER_DISPATCH_ARGS_OFFSET,
+        activeDispatchBuffer,
+        0,
+        INDIRECT_DISPATCH_ARGS_BYTES
+      );
+      const passEncoder = encoder.beginComputePass({
+        label: `plasius.wavefront.bounce.${bounceIndex}`
+      });
       passEncoder.setBindGroup(0, bindGroups[bounceIndex % 2], [configOffset]);
       passEncoder.setPipeline(pipelines.intersectActiveQueue);
-      passEncoder.dispatchWorkgroups(capacityWorkgroups);
+      passEncoder.dispatchWorkgroupsIndirect(activeDispatchBuffer, 0);
       passEncoder.setPipeline(pipelines.resolveSurfaceRecords);
-      passEncoder.dispatchWorkgroups(capacityWorkgroups);
+      passEncoder.dispatchWorkgroupsIndirect(activeDispatchBuffer, 0);
       passEncoder.setPipeline(pipelines.compactAndSwapQueues);
       passEncoder.dispatchWorkgroups(1);
+      passEncoder.end();
     }
-    passEncoder.end();
   }
   function encodeTileOutput(encoder, tile, configOffset) {
     const passEncoder = encoder.beginComputePass({
@@ -3767,6 +3834,28 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
       luminance: (0.2126 * bytes[0] + 0.7152 * bytes[1] + 0.0722 * bytes[2]) / 255
     });
   }
+  async function renderFrame(renderOptions = {}) {
+    const frameStats = renderOnce();
+    const probe = renderOptions.readOutputProbe === false ? null : await readOutputProbe(renderOptions.probe);
+    const maxChannel = probe ? Math.max(...probe.rgba.slice(0, 3)) : 0;
+    return Object.freeze({
+      ...frameStats,
+      outputProbe: probe ? Object.freeze({
+        ...probe,
+        sampledPixels: 1,
+        nonZeroSamples: maxChannel > 0 ? 1 : 0,
+        maxChannel
+      }) : null,
+      bounces: [],
+      termination: Object.freeze({
+        emissive: 0,
+        environment: 0,
+        ambientFallback: 0,
+        maxDepth: 0
+      }),
+      queueOverflow: 0
+    });
+  }
   function updateSceneObjects(sceneObjects) {
     const nextPackedScene = packWavefrontSceneObjects(sceneObjects, config.sceneObjectCapacity);
     packedScene = nextPackedScene;
@@ -3825,6 +3914,7 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     configBuffer.destroy?.();
     bvhBuildConfigBuffer.destroy?.();
     counterBuffer.destroy?.();
+    activeDispatchBuffer.destroy?.();
     radianceTexture.destroy?.();
     denoiseScratchTexture.destroy?.();
     outputTexture.destroy?.();
@@ -3837,12 +3927,32 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     format,
     config,
     renderOnce,
+    renderFrame,
     readOutputProbe,
     updateSceneObjects,
     getSnapshot,
     destroy
   });
 }
+async function renderWavefrontPathTracingComputeFrame(options = {}) {
+  const renderer = await createWavefrontPathTracingComputeRenderer(options);
+  try {
+    return await renderer.renderFrame(options);
+  } finally {
+    renderer.destroy();
+  }
+}
+function createWavefrontPathTracingComputeShaderSource(options = {}) {
+  const workgroupSize = readPositiveInteger(
+    "workgroupSize",
+    options.workgroupSize ?? rendererWavefrontComputeWorkgroupSize,
+    rendererWavefrontComputeWorkgroupSize
+  );
+  if (workgroupSize !== rendererWavefrontComputeWorkgroupSize) {
+    throw new Error(`wavefront mesh compute currently requires workgroupSize=${rendererWavefrontComputeWorkgroupSize}.`);
+  }
+  return WAVEFRONT_COMPUTE_WGSL;
+}
 
 // src/index.js
 var DEFAULT_CLEAR_COLOR = Object.freeze([0.07, 0.11, 0.18, 1]);
@@ -5143,6 +5253,7 @@ var defaultRendererClearColor = DEFAULT_CLEAR_COLOR;
   createWavefrontMeshAcceleration,
   createWavefrontPathTracingComputeConfig,
   createWavefrontPathTracingComputeRenderer,
+  createWavefrontPathTracingComputeShaderSource,
   createWavefrontPathTracingPlan,
   createWavefrontReferenceRay,
   defaultRendererClearColor,
@@ -5156,11 +5267,15 @@ var defaultRendererClearColor = DEFAULT_CLEAR_COLOR;
   packWavefrontBvhNodes,
   packWavefrontSceneObjects,
   packWavefrontTriangles,
+  renderWavefrontPathTracingComputeFrame,
   rendererAccelerationStructureUpdateClasses,
   rendererDebugOwner,
   rendererRayTracingStageOrder,
   rendererRepresentationBands,
   rendererWavefrontBufferSchemaVersion,
+  rendererWavefrontComputeMode,
+  rendererWavefrontComputeStatsStride,
+  rendererWavefrontComputeWorkgroupSize,
   rendererWavefrontHitTypes,
   rendererWavefrontPassOrder,
   rendererWavefrontQueuePairStrategy,