@plasius/gpu-renderer 0.2.54 → 0.2.56

package/CHANGELOG.md

@@ -23,6 +23,34 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.2.56] - 2026-10-24
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - Reject referenced canonical unlit workflows and declared unlit extension markers until an explicit unlit shading path exists, with a bounded diagnostic that preserves the caller's previous supported rendering path.
+
+- **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**
@@ -1300,3 +1328,5 @@ All notable changes to this project will be documented in this file.
 [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
+[0.2.56]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.56

package/README.md

@@ -74,6 +74,13 @@ 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.
+Referenced canonical unlit workflows and declared `KHR_materials_unlit`/`unlit`
+extension markers are unsupported and fail explicitly. Keep those assets on an
+unlit-capable rendering path; do not drop their markers or reinterpret them as lit.
 For an interactive model viewer with loading, integrity checks, camera gestures
 and quality controls, use the shared package's `model-inspection` entry.
 

package/dist/index.cjs

@@ -1654,14 +1654,6 @@ function textureSample(binding, textures, label, extra = {}) {
 }
 function cloneMaterialExtensions(material, textures) {
   const extensions = { ...material.extensions ?? {} };
-  if (material.workflow === "unlit") {
-    const unlitKey = "KHR_materials_unlit";
-    const unlitValue = extensions[unlitKey] ?? extensions.unlit ?? {};
-    if (typeof unlitValue !== "object" || unlitValue === null || Array.isArray(unlitValue)) {
-      throw new TypeError(`Canonical material extension ${unlitKey} must be an object.`);
-    }
-    extensions[unlitKey] = { ...unlitValue, enabled: true };
-  }
   for (const [bindingName, extensionName, textureKey] of EXTENSION_TEXTURE_BINDINGS) {
     const binding = material.textures?.[bindingName];
     if (!binding) {
@@ -1686,17 +1678,22 @@ function mapMaterial(material, materialRefId, textures) {
   if (material.alphaMode === "mask") {
     throw new Error("Canonical alphaMode mask is unsupported by WavefrontMeshInput.");
   }
-  if (material.workflow !== "metallic-roughness" && material.workflow !== "unlit") {
+  if (material.workflow === "unlit" || Object.hasOwn(material.extensions ?? {}, "KHR_materials_unlit") || Object.hasOwn(material.extensions ?? {}, "unlit")) {
+    throw new Error("Canonical unlit materials are unsupported by WavefrontMeshInput; retain an unlit-capable rendering path.");
+  }
+  if (material.workflow !== "metallic-roughness") {
     throw new Error(`Unsupported canonical material workflow: ${material.workflow}.`);
   }
   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 +8374,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 +9358,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 +9391,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 +9427,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 +9579,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 +9922,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 +10107,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;