@plasius/gpu-renderer 0.2.53 → 0.2.55

package/CHANGELOG.md

@@ -23,6 +23,34 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.2.55] - 2026-10-24
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - Preserve canonical blend alpha exactly once and ignore factor/texture alpha for opaque materials through CPU/GPU packing and material sampling; retain legacy Wavefront alpha composition when mode is omitted.
+
+- **Security**
+  - (placeholder)
+
+## [0.2.54] - 2026-10-21
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - Explain direct WebGPU control in the public README and keep dependency admission guidance in the development guide.
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.2.53] - 2026-10-20
 
 - **Added**
@@ -1285,3 +1313,5 @@ All notable changes to this project will be documented in this file.
 [0.2.51]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.51
 [0.2.52]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.52
 [0.2.53]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.53
+[0.2.54]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.54
+[0.2.55]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.55

package/README.md

@@ -12,6 +12,10 @@ Framework-independent WebGPU rendering for browser applications. Render triangle
 meshes with the wavefront path tracer, draw native raster surfaces, or use the
 frame lifecycle and XR integration APIs in your own rendering pipeline.
 
+The APIs expose GPU resource ownership, render passes and sample accumulation
+directly. Use them from JavaScript or TypeScript when you want explicit control
+over your application's WebGPU pipeline.
+
 Apache-2.0 · ESM and CommonJS · TypeScript declarations included.
 
 ## Install
@@ -70,6 +74,10 @@ The canonical adapter maps the core 0.5 material texture slots; it currently
 accepts UV0 and identity texture transforms. Other selections/transforms fail
 explicitly so authored appearance is not silently changed. See the
 [canonical integration contract](docs/guides/integration.md#canonical-model-ingestion).
+Canonical blend materials multiply authored factor alpha by texture alpha once;
+opaque materials ignore both alpha channels. Direct `WavefrontMeshInput` callers
+can select `alphaMode: "opaque" | "blend"`; omitting it preserves legacy opacity
+composition. Alpha masks remain unsupported by the canonical adapter.
 For an interactive model viewer with loading, integrity checks, camera gestures
 and quality controls, use the shared package's `model-inspection` entry.
 
@@ -145,29 +153,14 @@ route capabilities and rollout policy before mounting a scene.
 
 ## Development
 
-From a checkout, using the repository's Node.js version:
-
-```sh
-npm ci --legacy-peer-deps
-npm run lint
-npm run typecheck
-npm run test:coverage
-npm run build
-npm run pack:check
-npm run zero-three
-```
+For checkout setup and required validation, start with the
+[development guide](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/development.md).
 
 `npm run demo` requires Python 3 and serves the parent workspace. With the checkout
 named `gpu-renderer`, visit `http://localhost:8000/gpu-renderer/demo/`.
-See the [development guide](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/development.md)
-for sibling-package requirements and source layout, and
+The development guide also describes the source layout. See
 [CONTRIBUTING.md](https://github.com/Plasius-LTD/gpu-renderer/blob/main/CONTRIBUTING.md).
 
-Three.js and dependency paths reaching it are prohibited across runtime,
-development tooling and published artifacts. `npm run zero-three:source` checks
-source admission before installation; `npm run zero-three` validates the installed
-and built package evidence.
-
 <!-- BEGIN PLASIUS RELEASE INTEGRITY -->
 ## Release integrity
 

package/dist/index.cjs

@@ -1691,12 +1691,14 @@ function mapMaterial(material, materialRefId, textures) {
   }
   const mapped = {
     materialRefId,
+    alphaMode: material.alphaMode,
     ...material.alphaMode === "blend" ? { materialKind: "transparent" } : {},
     baseColor: material.baseColorFactor,
     emission: material.emissiveFactor ? [...material.emissiveFactor, 1] : [0, 0, 0, 1],
     roughness: material.roughnessFactor,
     metallic: material.metallicFactor,
-    opacity: material.alphaMode === "opaque" ? 1 : material.baseColorFactor?.[3],
+    // The authored factor remains in baseColor.a; do not multiply it twice.
+    opacity: 1,
     clearcoat: material.clearcoatFactor,
     clearcoatRoughness: material.clearcoatRoughnessFactor,
     transmission: material.transmissionFactor,
@@ -8377,7 +8379,7 @@ fn sample_surface_material(
   let baseColorTexel = sample_atlas(baseColorAtlasTexture, triangle.baseColorAtlas, uv);
   let baseColor = vec4<f32>(
     clamp(triangle.color.rgb * srgb_to_linear_vec3(baseColorTexel.rgb), vec3<f32>(0.0), vec3<f32>(1.0)),
-    clamp(triangle.color.a * baseColorTexel.a, 0.0, 1.0)
+    select(clamp(triangle.color.a * baseColorTexel.a, 0.0, 1.0), 1.0, triangle.textureSettings.w > 0.5)
   );
   let metallicRoughnessTexel = sample_atlas(
     metallicRoughnessAtlasTexture,
@@ -9361,6 +9363,10 @@ function createDefaultWavefrontSceneObjects() {
   ]);
 }
 function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
+  const alphaMode = input.alphaMode;
+  if (alphaMode !== void 0 && alphaMode !== "opaque" && alphaMode !== "blend") {
+    throw new TypeError("mesh alphaMode must be opaque or blend.");
+  }
   const positions = input.positions;
   const positionLength = getArrayLikeLength(positions);
   if (positionLength < 9 || positionLength % 3 !== 0) {
@@ -9390,7 +9396,11 @@ function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
     input.emission ?? input.emissive ?? input.material?.emission ?? input.material?.emissive,
     [0, 0, 0, 1]
   );
-  const opacity = clamp2(readFiniteNumber("opacity", input.opacity ?? input.material?.opacity, color[3] ?? 1), 0, 1);
+  const opacity = alphaMode === "opaque" ? 1 : clamp2(
+    readFiniteNumber("opacity", input.opacity ?? input.material?.opacity, alphaMode === "blend" ? 1 : color[3] ?? 1),
+    0,
+    1
+  );
   const transmission = clamp2(
     readFiniteNumber("transmission", input.transmission ?? input.material?.transmission, materialExtensions.transmission),
     0,
@@ -9422,6 +9432,7 @@ function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
       0
     ),
     medium,
+    alphaMode,
     color: Object.freeze(color),
     emission: Object.freeze(emission),
     roughness: clamp2(readFiniteNumber("roughness", input.roughness ?? input.material?.roughness, 0.72), 0, 1),
@@ -9573,7 +9584,7 @@ function createMeshTriangleRecords(meshes, gpuMaterialSource = null) {
             clampUnit(mesh.normalTexture?.scale ?? mesh.normalTexture?.strength ?? 1),
             clampUnit(mesh.occlusionTexture?.strength ?? 1),
             clampUnit(mesh.emissiveTexture?.strength ?? 1),
-            0
+            mesh.alphaMode === "opaque" ? 1 : 0
           ]),
           extensionTextures: Object.freeze(
             Object.fromEntries(
@@ -9916,7 +9927,7 @@ function createWavefrontGpuMaterialSource(meshes = []) {
       clampUnit(mesh.normalTexture?.scale ?? mesh.normalTexture?.strength ?? 1),
       clampUnit(mesh.occlusionTexture?.strength ?? 1),
       clampUnit(mesh.emissiveTexture?.strength ?? 1),
-      0
+      mesh.alphaMode === "opaque" ? 1 : 0
     ]);
   });
   return Object.freeze({
@@ -10101,7 +10112,7 @@ function createWavefrontGpuMeshSource(meshes = [], gpuMaterialSourceInput = null
       clampUnit(mesh.normalTexture?.scale ?? mesh.normalTexture?.strength ?? 1),
       clampUnit(mesh.occlusionTexture?.strength ?? 1),
       clampUnit(mesh.emissiveTexture?.strength ?? 1),
-      0
+      mesh.alphaMode === "opaque" ? 1 : 0
     ]);
     vertexCursor += meshVertexCount;
     indexCursor += mesh.indices.length;