@aura3d/engine 3.0.0 → 4.0.0

package/dist/assets/GLTFRenderResources.js

@@ -1,7 +1,61 @@
-import { Geometry, IndexBuffer, InstancedPBRMaterial, InstancedUnlitMaterial, Material, PBRMaterial, Sampler, SkinnedLitMaterial, Texture, TextureBinding, TexturedPBRMaterial, TexturedUnlitMaterial, UnlitMaterial, VertexBuffer, createExternalParityEnvironmentLighting, computePerspectiveCameraFrame, computeSkinnedMorphTargetEnvelopeBounds, VertexFormat, DEFAULT_PBR_ENVIRONMENT_INTENSITY, isTexturedPbrTextureSlotShaderActive, DEFAULT_TEXTURED_PBR_SHADER_NAME } from "../rendering/index.js";
+import { Geometry, IndexBuffer, InstancedPBRMaterial, InstancedUnlitMaterial, Material, PBRMaterial, Sampler, SkinnedLitMaterial, Texture, TextureBinding, TexturedPBRMaterial, TexturedUnlitMaterial, UnlitMaterial, VertexBuffer, createExternalParityEnvironmentLighting, computePerspectiveCameraFrame, computeSkinnedMorphTargetEnvelopeBounds, VertexFormat, DEFAULT_PBR_ENVIRONMENT_INTENSITY, isTexturedPbrTextureSlotShaderActive, DEFAULT_TEXTURED_PBR_SHADER_NAME, applyTextureBudget } from "../rendering/index.js";
 import { Bounds3 as SceneBounds3, multiplyMat4 } from "../scene/index.js";
-import { parseGLTFRuntimeMaterialKey } from "./GLTFLoader.js";
-import { transcodeKTX2BasisTexture } from "./KTX2BasisTextureTranscoder.js";
+import { gltfRuntimeMaterialKey, parseGLTFRuntimeMaterialKey } from "./GLTFLoader.js";
+import { generateMikkTSpaceTangents, mikkTSpaceAvailable } from "./MikkTSpaceTangents.js";
+import { decodeImageInBrowser } from "./gltf/ImageDecode.js";
+/** Texture slots read sRGB-authored data; every other slot decodes linear. */
+const IMAGE_COLORSPACE_SLOTS = [
+    { slot: "baseColor", colorSpace: "srgb", texture: (material) => material.baseColorTexture },
+    { slot: "emissive", colorSpace: "srgb", texture: (material) => material.emissiveTexture },
+    { slot: "metallicRoughness", colorSpace: "linear", texture: (material) => material.metallicRoughnessTexture },
+    { slot: "normal", colorSpace: "linear", texture: (material) => material.normalTexture },
+    { slot: "occlusion", colorSpace: "linear", texture: (material) => material.occlusionTexture },
+    { slot: "clearcoat", colorSpace: "linear", texture: (material) => material.clearcoat?.texture },
+    { slot: "clearcoatRoughness", colorSpace: "linear", texture: (material) => material.clearcoat?.roughnessTexture },
+    { slot: "clearcoatNormal", colorSpace: "linear", texture: (material) => material.clearcoat?.normalTexture },
+    { slot: "sheenColor", colorSpace: "srgb", texture: (material) => material.sheen?.colorTexture },
+    { slot: "sheenRoughness", colorSpace: "linear", texture: (material) => material.sheen?.roughnessTexture },
+    { slot: "transmission", colorSpace: "linear", texture: (material) => material.transmission?.texture },
+    { slot: "diffuseTransmission", colorSpace: "linear", texture: (material) => material.diffuseTransmission?.texture },
+    { slot: "diffuseTransmissionColor", colorSpace: "srgb", texture: (material) => material.diffuseTransmission?.colorTexture },
+    { slot: "volumeThickness", colorSpace: "linear", texture: (material) => material.volume?.thicknessTexture },
+    { slot: "specular", colorSpace: "linear", texture: (material) => material.specular?.texture },
+    { slot: "specularColor", colorSpace: "srgb", texture: (material) => material.specular?.colorTexture },
+    { slot: "anisotropy", colorSpace: "linear", texture: (material) => material.anisotropy?.texture },
+    { slot: "iridescence", colorSpace: "linear", texture: (material) => material.iridescence?.texture },
+    { slot: "iridescenceThickness", colorSpace: "linear", texture: (material) => material.iridescence?.thicknessTexture },
+    { slot: "sgDiffuse", colorSpace: "srgb", texture: (material) => material.pbrSpecularGlossiness?.diffuseTexture },
+    { slot: "sgSpecularGlossiness", colorSpace: "linear", texture: (material) => material.pbrSpecularGlossiness?.specularGlossinessTexture }
+];
+/**
+ * PRD-04 P5-1: per-image colour-space intent derived from material slot usage, for the C-16
+ * decode path (a KTX2/Basis transcode target must be chosen before any slot samples the
+ * image). An image used both sRGB and linear records a `colorspace-conflict` in
+ * `conflicts`; its intent resolves `"linear"` so no gamma curve is baked into the decoded
+ * payload — the per-slot usage space still applies at the `Texture` level.
+ */
+export function imageColorSpaceIntent(asset) {
+    const usages = new Map();
+    for (const material of asset.materials) {
+        for (const slot of IMAGE_COLORSPACE_SLOTS) {
+            const info = slot.texture(material);
+            if (!info)
+                continue;
+            const usage = usages.get(info.image) ?? { srgb: [], linear: [] };
+            (slot.colorSpace === "srgb" ? usage.srgb : usage.linear).push(`${material.name}:${slot.slot}`);
+            usages.set(info.image, usage);
+        }
+    }
+    const intent = new Map();
+    const conflicts = [];
+    for (const [image, usage] of usages) {
+        const conflict = usage.srgb.length > 0 && usage.linear.length > 0;
+        intent.set(image, usage.linear.length > 0 || !conflict && usage.srgb.length === 0 ? "linear" : "srgb");
+        if (conflict)
+            conflicts.push({ image, srgb: usage.srgb.join(","), linear: usage.linear.join(",") });
+    }
+    return { intent, conflicts };
+}
 const GLTF_DIAGNOSTIC_TEXTURE_BINDINGS = [
     ["baseColor", "u_baseColorTexture", "u_baseColorTextureEnabled"],
     ["normal", "u_normalTexture", "u_normalTextureEnabled"],
@@ -119,6 +173,24 @@ export async function createGLTFRenderResources(asset, options = {}) {
         ...(options.sceneIndex !== undefined ? { sceneIndex: options.sceneIndex } : {}),
         ...(options.sceneName !== undefined ? { sceneName: options.sceneName } : {})
     });
+    // P5-1: per-image colour-space intent, resolved once from material slot usage and passed
+    // into the C-16 decode options (`ktx2BasisTranscoderOptions.colorSpace`) so a
+    // once-per-image transcode knows the intended space. Conflicts become `loadIssues`.
+    const colorSpaceIntent = imageColorSpaceIntent(asset);
+    const loadIssues = colorSpaceIntent.conflicts.map((conflict) => ({
+        code: "colorspace-conflict",
+        detail: `glTF image ${conflict.image} is used as sRGB (${conflict.srgb}) and linear (${conflict.linear}); decoding as linear.`
+    }));
+    const decodeOptionsForImage = (imageIndex) => options.materialsR185 === true
+        ? {
+            ...options,
+            ktx2BasisTranscoderOptions: {
+                ...options.ktx2BasisTranscoderOptions,
+                // Flag-on only: pre-intent decode options stay byte-identical off-flag.
+                colorSpace: colorSpaceIntent.intent.get(imageIndex) ?? "linear"
+            }
+        }
+        : options;
     const getTexture = async (info, colorSpace) => {
         const textureAsset = asset.textures[info.texture];
         const image = asset.images[info.image];
@@ -132,10 +204,10 @@ export async function createGLTFRenderResources(asset, options = {}) {
             setTextureLibraryEntry(textureLibrary, textureAsset.name, colorSpace, texture);
             return texture;
         }
-        const decoder = options.imageDecoder ?? ((sourceImage, imageIndex, sourceAsset) => decodeImageInBrowser(sourceImage, imageIndex, sourceAsset, options));
+        const decoder = options.imageDecoder ?? ((sourceImage, imageIndex, sourceAsset) => decodeImageInBrowser(sourceImage, imageIndex, sourceAsset, decodeOptionsForImage(imageIndex)));
         const texturePromise = (async () => {
             const decoded = await decoder(image, info.image, asset);
-            return new Texture({
+            const texture = new Texture({
                 width: decoded.width,
                 height: decoded.height,
                 ...(decoded.format ? { format: decoded.format } : {}),
@@ -145,6 +217,16 @@ export async function createGLTFRenderResources(asset, options = {}) {
                 ...(decoded.fallbackData ? { fallbackData: decoded.fallbackData } : {}),
                 ...(decoded.fallbackMipLevels ? { fallbackMipLevels: decoded.fallbackMipLevels } : {})
             });
+            // R16/P2-11: the C-27 policy arrives as `textureBudget`/`maxTextureSize` on
+            // GLTFRenderResourceOptions (forwarded by the actor/pipeline). No device exists at
+            // this layer — the shared ledger accounts these uploads.
+            if (options.textureBudget !== undefined || options.maxTextureSize !== undefined) {
+                return applyTextureBudget(texture, {
+                    ...(options.textureBudget !== undefined ? { textureBudgetBytes: options.textureBudget } : {}),
+                    ...(options.maxTextureSize !== undefined ? { maxTextureSize: options.maxTextureSize } : {})
+                });
+            }
+            return texture;
         })();
         textureByImage.set(cacheKey, texturePromise);
         try {
@@ -166,9 +248,37 @@ export async function createGLTFRenderResources(asset, options = {}) {
             return fallback;
         }
     };
+    // When deduplication is enabled, materials with identical definitions share one runtime instance
+    // so renderer static batching (which keys on material identity) can collapse them. Declared before
+    // the try block so `setMaterialVariant` (R11) can rebuild missing contract variants on rebind.
+    const sharedMaterials = options.deduplicateIdenticalMaterials
+        ? new Map()
+        : null;
+    const buildMaterial = (material, contract) => {
+        if (!sharedMaterials) {
+            return createMaterial(asset, material, getTexture, contract, options.materialRenderStateOverrides, options.materialsR185, { materialsTransmission: options.materialsTransmission, transmission: options.transmission });
+        }
+        // The contract participates in the key: the same glTF material under two different runtime
+        // contracts (skinned vs instanced, for example) must not collapse into one instance.
+        const key = identicalMaterialKey(material, contract);
+        const existing = sharedMaterials.get(key);
+        if (existing)
+            return existing;
+        const created = createMaterial(asset, material, getTexture, contract, options.materialRenderStateOverrides, options.materialsR185, { materialsTransmission: options.materialsTransmission, transmission: options.transmission });
+        sharedMaterials.set(key, created);
+        return created;
+    };
     try {
+        // P5-4: under `A3D_QR_MATERIALS` prefer MikkTSpace-generated tangents (r185's frame) over
+        // the legacy triangle-average generator, unless `tangents === "legacy"` or the MikkTSpace
+        // module is not registered. `tangent-derivative-fallback` is reported inside createGeometry
+        // only when a tangent-needing program lands on the derivative frame.
+        const tangentGeneration = {
+            useMikkTSpace: options.materialsR185 === true && options.tangents !== "legacy" && mikkTSpaceAvailable(),
+            mikkTSpaceWanted: options.materialsR185 === true && options.tangents !== "legacy"
+        };
         for (const mesh of asset.meshes) {
-            geometryLibrary.set(mesh.name, createGeometry(mesh, materialForMesh(asset, mesh, options.materialVariant)));
+            geometryLibrary.set(mesh.name, await createGeometry(mesh, materialForMesh(asset, mesh, options.materialVariant), tangentGeneration, loadIssues));
             if (mesh.morphTargets.length > 0) {
                 morphTargetLibrary.set(mesh.name, mesh.morphTargets.map((target) => ({
                     ...(target.name ? { name: target.name } : {}),
@@ -191,25 +301,6 @@ export async function createGLTFRenderResources(asset, options = {}) {
             });
         }
         const materialTasks = [];
-        // When deduplication is enabled, materials with identical definitions share one runtime instance
-        // so renderer static batching (which keys on material identity) can collapse them.
-        const sharedMaterials = options.deduplicateIdenticalMaterials
-            ? new Map()
-            : null;
-        const buildMaterial = (material, contract) => {
-            if (!sharedMaterials) {
-                return createMaterial(asset, material, getTexture, contract, options.materialRenderStateOverrides);
-            }
-            // The contract participates in the key: the same glTF material under two different runtime
-            // contracts (skinned vs instanced, for example) must not collapse into one instance.
-            const key = identicalMaterialKey(material, contract);
-            const existing = sharedMaterials.get(key);
-            if (existing)
-                return existing;
-            const created = createMaterial(asset, material, getTexture, contract, options.materialRenderStateOverrides);
-            sharedMaterials.set(key, created);
-            return created;
-        };
         for (const material of asset.materials) {
             const runtimeKeys = [...runtimeMaterialContracts.entries()].filter(([, runtime]) => runtime.material === material.name);
             if (runtimeKeys.length === 0) {
@@ -228,11 +319,11 @@ export async function createGLTFRenderResources(asset, options = {}) {
         for (const mesh of asset.meshes) {
             for (const [key, runtime] of runtimeMaterialContracts) {
                 if (runtime.material === mesh.material && !materialLibrary.has(key)) {
-                    materialLibrary.set(key, createDefaultGLTFMaterial(mesh, runtime.contract));
+                    materialLibrary.set(key, createDefaultGLTFMaterial(mesh, runtime.contract, options.materialsR185));
                 }
             }
             if (!materialLibrary.has(mesh.material)) {
-                materialLibrary.set(mesh.material, createDefaultGLTFMaterial(mesh));
+                materialLibrary.set(mesh.material, createDefaultGLTFMaterial(mesh, {}, options.materialsR185));
             }
         }
     }
@@ -249,6 +340,7 @@ export async function createGLTFRenderResources(asset, options = {}) {
         materialLibrary,
         renderableBindings,
         materialFidelityDiagnostics,
+        loadIssues,
         morphTargetLibrary,
         textureLibrary,
         bounds,
@@ -287,9 +379,55 @@ export async function createGLTFRenderResources(asset, options = {}) {
                 bounds
             };
         },
+        setMaterialVariant: (variant) => applyGLTFMaterialVariant({ asset, scene, materialLibrary, renderableBindings, buildMaterial, variant }),
         dispose: () => disposeGLTFRenderResourceMaps(geometryLibrary, textureLibrary)
     };
 }
+/**
+ * PRD-04 P2/R11: KHR_materials_variants rebinding without a pipeline rebuild — the actor's variant
+ * switch remaps each renderable's material key. Meshes lacking a mapping for the active variant
+ * keep their authored material per the glTF spec; `null` restores the authored mapping.
+ */
+async function applyGLTFMaterialVariant(options) {
+    const { asset, scene, materialLibrary, renderableBindings, buildMaterial, variant } = options;
+    if (variant !== null
+        && !renderableBindings.some((binding) => binding.materialVariants.some((entry) => entry.variant === variant))) {
+        return "variant-unknown";
+    }
+    const meshByGeometry = new Map(asset.meshes.map((mesh) => [mesh.name, mesh]));
+    const tasks = [];
+    scene.collectRenderables().forEach(({ renderable }, index) => {
+        const binding = renderableBindings[index];
+        const mesh = meshByGeometry.get(renderable.geometry);
+        if (!binding || !mesh)
+            return;
+        const parsed = parseGLTFRuntimeMaterialKey(renderable.material);
+        const contract = {
+            ...parsed.contract,
+            ...(renderable.skinning ? { skinned: true } : {}),
+            ...(renderable.instanceTransforms ? { instanced: true } : {})
+        };
+        const mapping = variant === null
+            ? undefined
+            : mesh.materialVariants.find((entry) => entry.variant === variant);
+        const targetName = mapping?.material ?? binding.sourceMaterialName;
+        const key = gltfRuntimeMaterialKey(targetName, contract);
+        if (key === renderable.material)
+            return;
+        if (!materialLibrary.has(key)) {
+            const materialDef = asset.materials.find((entry) => entry.name === targetName);
+            tasks.push((materialDef
+                ? buildMaterial(materialDef, contract)
+                : Promise.resolve(createDefaultGLTFMaterial({ ...mesh, material: targetName }, contract))).then((runtimeMaterial) => {
+                materialLibrary.set(key, runtimeMaterial);
+            }));
+        }
+        // Renderable.material is readonly at the type level; the rebind mutates the key in place.
+        renderable.material = key;
+    });
+    await Promise.all(tasks);
+    return "applied";
+}
 function createGLTFRenderableBindings(asset, scene) {
     const meshByGeometry = new Map(asset.meshes.map((mesh) => [mesh.name, mesh]));
     return scene.collectRenderables().map(({ node, renderable }) => {
@@ -814,7 +952,7 @@ function materialForMesh(asset, mesh, materialVariant) {
         : mesh.materialIndex;
     return materialIndex === undefined ? undefined : asset.materials[materialIndex];
 }
-function createGeometry(mesh, material) {
+async function createGeometry(mesh, material, tangentGeneration, loadIssues) {
     const usedTexCoordSets = usedRenderTexCoordSets(material);
     const texcoords = selectRenderTexcoords(mesh, material, 0);
     const texcoords1 = usedTexCoordSets.has(1) ? selectRenderTexcoords(mesh, material, 1) : [];
@@ -829,8 +967,20 @@ function createGeometry(mesh, material) {
         ? generateMeshNormals(mesh.positions, mesh.indices, mesh.topology)
         : mesh.normals;
     const renderTangents = needsTangent && mesh.tangents.length === 0
-        ? generateMeshTangents(mesh.positions, texcoords, mesh.indices, mesh.topology, renderNormals)
+        ? await generateRenderTangents(mesh, texcoords, renderNormals, tangentGeneration)
         : mesh.tangents;
+    /*
+     * P5-4: `tangent-derivative-fallback` is reported only when a generated program will
+     * actually use the derivative frame — the material needs a tangent frame but the produced
+     * vertex format carries no tangent attribute (e.g. a normal-mapped mesh without UVs).
+     * A successful MikkTSpace->legacy fallback still produces the generated-attribute path.
+     */
+    if (tangentGeneration.mikkTSpaceWanted && materialNeedsTangents(material) && !format.hasAttribute("tangent")) {
+        loadIssues.push({
+            code: "tangent-derivative-fallback",
+            detail: `glTF mesh ${mesh.name}: material needs a tangent frame but no tangent attribute was produced; the generated program uses the derivative frame.`
+        });
+    }
     const vertices = new VertexBuffer(format, mesh.positions.length);
     for (let index = 0; index < mesh.positions.length; index += 1) {
         vertices.setAttribute(index, "position", mesh.positions[index]);
@@ -879,6 +1029,54 @@ function generateMeshNormals(positions, indices, topology) {
     }
     return normals.map((normal) => normalize3(normal));
 }
+/**
+ * P5-4: tangent generation for a mesh with no authored TANGENT. MikkTSpace when the lane flag
+ * asked for it and the module is registered; otherwise the legacy triangle-average generator.
+ * The `tangent-derivative-fallback` load issue is reported by the caller — only when the
+ * produced vertex format leaves a tangent-needing program on the derivative frame.
+ */
+async function generateRenderTangents(mesh, texcoords, renderNormals, tangentGeneration) {
+    if (tangentGeneration.useMikkTSpace) {
+        try {
+            const generated = await generateMikkTSpaceTangents({
+                positions: flatten3(mesh.positions),
+                normals: flatten3(renderNormals),
+                uvs: flatten2(texcoords),
+                ...(mesh.indices && mesh.indices.length > 0 ? { indices: new Uint32Array(mesh.indices) } : {})
+            });
+            // The MikkTSpace helper unwelds indexed input (output is per-index, xyzw); scatter back
+            // per vertex — last write wins, matching how indexed TANGENT attributes behave.
+            const count = mesh.positions.length;
+            const rows = Array.from({ length: count }, () => [0, 0, 0, 1]);
+            if (mesh.indices && mesh.indices.length > 0) {
+                mesh.indices.forEach((vertexIndex, i) => {
+                    rows[vertexIndex] = [generated[i * 4] ?? 0, generated[i * 4 + 1] ?? 0, generated[i * 4 + 2] ?? 0, generated[i * 4 + 3] ?? 1];
+                });
+            }
+            else {
+                for (let i = 0; i < count; i += 1) {
+                    rows[i] = [generated[i * 4] ?? 0, generated[i * 4 + 1] ?? 0, generated[i * 4 + 2] ?? 0, generated[i * 4 + 3] ?? 1];
+                }
+            }
+            return rows;
+        }
+        catch {
+            // MikkTSpace failure falls back to the legacy generator silently — the program still
+            // runs the generated-attribute path (P5-4 reports the issue only for the derivative path).
+        }
+    }
+    return generateMeshTangents(mesh.positions, texcoords, mesh.indices, mesh.topology, renderNormals);
+}
+function flatten3(rows) {
+    const flat = new Float32Array(rows.length * 3);
+    rows.forEach(([x, y, z], i) => { flat[i * 3] = x; flat[i * 3 + 1] = y; flat[i * 3 + 2] = z; });
+    return flat;
+}
+function flatten2(rows) {
+    const flat = new Float32Array(rows.length * 2);
+    rows.forEach(([x, y], i) => { flat[i * 2] = x; flat[i * 2 + 1] = y; });
+    return flat;
+}
 function generateMeshTangents(positions, texcoords, indices, topology, normals) {
     const tangents = Array.from({ length: positions.length }, () => [0, 0, 0]);
     const bitangents = Array.from({ length: positions.length }, () => [0, 0, 0]);
@@ -1075,8 +1273,9 @@ function stableJson(value) {
         return nested;
     });
 }
-async function createMaterial(asset, material, getTexture, options = {}, renderStateOverrides = []) {
-    const renderState = renderStateForGLTFMaterial(material, renderStateOverrides);
+async function createMaterial(asset, material, getTexture, options = {}, renderStateOverrides = [], materialsR185 = false, qrTransmission) {
+    const qr = { ...qrTransmission, materialsR185 };
+    const renderState = renderStateForGLTFMaterial(material, renderStateOverrides, materialsR185, qrTransmission);
     if (options.skinned && !material.unlit) {
         const [baseColorTexture, normalTexture, metallicRoughnessTexture, occlusionTexture, emissiveTexture, clearcoatTexture, clearcoatNormalTexture, sheenColorTexture, sheenRoughnessTexture, transmissionTexture, iridescenceTexture, iridescenceThicknessTexture, anisotropyTexture, volumeThicknessTexture] = await Promise.all([
             material.baseColorTexture
@@ -1149,10 +1348,10 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
             iridescenceThicknessTexture,
             anisotropyTexture,
             volumeThicknessTexture,
-            ...pbrExtensionScalarOptions(material)
+            ...pbrExtensionScalarOptions(material, qr)
         });
         applyAlphaCutoff(runtimeMaterial, material);
-        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
         return runtimeMaterial;
     }
     if (options.instanced && material.unlit && !material.baseColorTexture) {
@@ -1162,7 +1361,7 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
             renderState
         });
         applyAlphaCutoff(runtimeMaterial, material);
-        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
         return runtimeMaterial;
     }
     if (material.unlit) {
@@ -1177,7 +1376,7 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
                 renderState
             });
             applyAlphaCutoff(runtimeMaterial, material);
-            await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+            await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
             return runtimeMaterial;
         }
         const runtimeMaterial = new UnlitMaterial({
@@ -1186,7 +1385,7 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
             renderState
         });
         applyAlphaCutoff(runtimeMaterial, material);
-        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
         return runtimeMaterial;
     }
     if (options.instanced && !requiresTexturedPBRMaterial(material) && !material.baseColorTexture) {
@@ -1200,7 +1399,7 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
             emissiveStrength: material.emissiveStrength
         });
         applyAlphaCutoff(runtimeMaterial, material);
-        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
         return runtimeMaterial;
     }
     if (requiresTexturedPBRMaterial(material)) {
@@ -1213,13 +1412,13 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
         const runtimeMaterial = new TexturedPBRMaterial({
             name: material.name,
             renderState,
-            baseColor: renderPbrBaseColorFactor(material),
+            baseColor: renderPbrBaseColorFactor(material, qr),
             metallic: material.metallicFactor,
-            roughness: renderPbrRoughnessFactor(material),
+            roughness: renderPbrRoughnessFactor(material, qr),
             emissiveColor: material.emissiveFactor,
             emissiveStrength: material.emissiveStrength,
             textureTexCoords: pbrTextureTexCoords(material),
-            ...pbrExtensionScalarOptions(material),
+            ...pbrExtensionScalarOptions(material, qr),
             ...extensionTextureOptions,
             baseColorTexture,
             baseColorSampler: createSampler(material.baseColorTexture ? asset.textures[material.baseColorTexture.texture] : undefined),
@@ -1240,7 +1439,7 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
             emissiveTextureTransform: material.emissiveTexture?.transform
         });
         applyAlphaCutoff(runtimeMaterial, material);
-        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
         return runtimeMaterial;
     }
     if (material.baseColorTexture) {
@@ -1254,27 +1453,37 @@ async function createMaterial(asset, material, getTexture, options = {}, renderS
             renderState
         });
         applyAlphaCutoff(runtimeMaterial, material);
-        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+        await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
         return runtimeMaterial;
     }
     const runtimeMaterial = new PBRMaterial({
         name: material.name,
         renderState,
-        baseColor: renderPbrBaseColorFactor(material),
+        baseColor: renderPbrBaseColorFactor(material, qr),
         metallic: material.metallicFactor,
-        roughness: renderPbrRoughnessFactor(material),
+        roughness: renderPbrRoughnessFactor(material, qr),
         emissiveColor: material.emissiveFactor,
         emissiveStrength: material.emissiveStrength,
-        ...pbrExtensionScalarOptions(material)
+        ...pbrExtensionScalarOptions(material, qr)
     });
     applyAlphaCutoff(runtimeMaterial, material);
-    await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture);
+    await applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr);
     return runtimeMaterial;
 }
-function createDefaultGLTFMaterial(mesh, options = {}) {
+function createDefaultGLTFMaterial(mesh, options = {}, materialsR185 = false) {
     // Use a neutral light-gray base color instead of glTF-spec white ([1,1,1,1])
     // so missing-material fallbacks do not blow out as bright white artifacts.
-    const defaults = {
+    // PRD-04 P2-12/E23: flag-on uses the glTF-spec default ([1,1,1,1], roughness 1).
+    // T0-18(a): metallic stays 0, not the spec's 1 — a fully metallic surface has
+    // no diffuse response and renders near-black until a C-09 probe/IBL is bound;
+    // restore spec metallic once environment lighting is guaranteed on this path.
+    const defaults = materialsR185 ? {
+        name: mesh.material,
+        baseColor: [1, 1, 1, 1],
+        metallic: 0,
+        roughness: 1,
+        environmentIntensity: DEFAULT_PBR_ENVIRONMENT_INTENSITY
+    } : {
         name: mesh.material,
         baseColor: [0.76, 0.74, 0.72, 1],
         metallic: 0,
@@ -1296,23 +1505,38 @@ function createDefaultGLTFMaterial(mesh, options = {}) {
  * so we allow a small epsilon while still catching genuine fades.
  */
 const BLEND_OPAQUE_ALPHA_THRESHOLD = 0.996;
-export function renderStateForGLTFMaterial(material, overrides = []) {
-    const blend = requiresTransparentRenderState(material);
-    const cullBack = usesUnbackedScalarTransmission(material) || usesOpaqueDoubleSidedClearcoatShell(material);
+export function renderStateForGLTFMaterial(material, overrides = [], materialsR185 = false, qrTransmission) {
+    const qr = { ...qrTransmission, materialsR185 };
+    const blend = requiresTransparentRenderState(material, qr);
+    // PRD-04 P2-12/E23: the double-sided + metallic + clearcoat back-face cull is a fudge;
+    // flag-on honours authored doubleSided.
+    const cullBack = usesUnbackedScalarTransmission(material, qr)
+        || (!materialsR185 && usesOpaqueDoubleSidedClearcoatShell(material));
+    // P5-5 (C-04): under the lane flag a MASK material requests alpha-to-coverage. The material
+    // RenderState type predates C-04's `RenderCommandState.alphaToCoverage`, so the field rides
+    // the state object at runtime (validateRenderState preserves unknown keys); the
+    // `prd04.alphaToCoverage` feature reads it and only honours it when the tier has MSAA
+    // samples. Flag-off omits the key entirely.
     const baseState = {
         cullMode: cullBack ? "back" : material.doubleSided ? "none" : "back",
         blend,
-        depthWrite: !blend
+        depthWrite: !blend,
+        ...(materialsR185 && material.alphaMode === "MASK" ? { alphaToCoverage: true } : {})
     };
     const override = overrides.find((entry) => matchesTextOrPattern(material.name, entry.materialName));
     return override ? { ...baseState, ...override.renderState } : baseState;
 }
-function requiresTransparentRenderState(material) {
+function requiresTransparentRenderState(material, qr) {
     if (material.alphaMode === "BLEND")
         return !isEffectivelyOpaqueBlendMaterial(material);
     if (material.alphaMode !== "OPAQUE")
         return false;
-    if (usesUnbackedScalarTransmission(material))
+    if (usesUnbackedScalarTransmission(material, qr))
+        return false;
+    // E22: on the real path transmissive items ride the C-01 `transmission` phase
+    // queue (blend must stay off — the sorter rejects blended transmission), not
+    // the legacy transparent queue.
+    if (qrTransmissionRealPath(qr))
         return false;
     return materialHasTransmissionOrVolume(material);
 }
@@ -1356,12 +1580,31 @@ function materialHasTransmissionOrVolume(material) {
         || (material.volume?.thicknessFactor ?? 0) > 0.001
         || material.volume?.thicknessTexture !== undefined;
 }
-function usesUnbackedScalarTransmission(material) {
-    return material.alphaMode === "OPAQUE"
+/**
+ * E22 gate (PRD-04 P4-3): real transmission rendering exists — so the legacy
+ * unbacked-scalar-transmission rewrite must not run — exactly when
+ * `A3D_QR_MATERIALS` **and** `A3D_QR_MATERIALS_TRANSMISSION` are on **and**
+ * `renderer.transmission === "env"` (the env-refraction path).
+ * T0-18(b): `programCacheSlot.provided` is not evidence — it is true whenever
+ * the prd01 barrel loaded, which skipped E22 even though the scene-copy path
+ * did not draw. `"auto"` keeps the E22 rewrite until the transmission target
+ * is bound end-to-end on generated programs (04-S10).
+ */
+function qrTransmissionRealPath(qr) {
+    return qr?.materialsR185 === true
+        && qr?.materialsTransmission === true
+        && qr.transmission === "env";
+}
+function usesUnbackedScalarTransmission(material, qr) {
+    const unbacked = material.alphaMode === "OPAQUE"
         && (material.transmission?.factor ?? 0) > 0.001
         && material.transmission?.texture === undefined
         && material.diffuseTransmission === undefined
         && material.volume === undefined;
+    // E22 path-gated skip: real transmission handles the material; no rewrite.
+    if (unbacked && qrTransmissionRealPath(qr))
+        return false;
+    return unbacked;
 }
 function usesOpaqueDoubleSidedClearcoatShell(material) {
     return material.alphaMode === "OPAQUE"
@@ -1370,16 +1613,16 @@ function usesOpaqueDoubleSidedClearcoatShell(material) {
         && material.metallicFactor > 0.35
         && material.roughnessFactor <= 0.42;
 }
-function renderPbrBaseColorFactor(material) {
-    if (!usesUnbackedScalarTransmission(material))
+function renderPbrBaseColorFactor(material, qr) {
+    if (!usesUnbackedScalarTransmission(material, qr))
         return material.baseColorFactor;
     const maxColor = Math.max(material.baseColorFactor[0], material.baseColorFactor[1], material.baseColorFactor[2]);
     if (maxColor < 0.8)
         return material.baseColorFactor;
     return [0.028, 0.036, 0.044, material.baseColorFactor[3]];
 }
-function renderPbrRoughnessFactor(material) {
-    if (!usesUnbackedScalarTransmission(material))
+function renderPbrRoughnessFactor(material, qr) {
+    if (!usesUnbackedScalarTransmission(material, qr))
         return material.roughnessFactor;
     return Math.max(material.roughnessFactor, 0.72);
 }
@@ -1418,15 +1661,15 @@ function usesNearestSampler(texture) {
     const sampler = createSampler(texture);
     return sampler.magFilter === "nearest" || sampler.minFilter.startsWith("nearest");
 }
-function pbrExtensionScalarOptions(material) {
+function pbrExtensionScalarOptions(material, qr) {
     return {
         ...(material.clearcoat ? {
             clearcoatFactor: material.clearcoat.factor,
             clearcoatRoughnessFactor: renderClearcoatRoughnessFactor(material)
         } : {}),
         ...(material.transmission ? {
-            transmissionFactor: usesUnbackedScalarTransmission(material) ? 0 : material.transmission.factor,
-            transmissionFallbackEnergy: renderTransmissionFallbackEnergy(material)
+            transmissionFactor: usesUnbackedScalarTransmission(material, qr) ? 0 : material.transmission.factor,
+            transmissionFallbackEnergy: renderTransmissionFallbackEnergy(material, qr)
         } : {}),
         ...(material.diffuseTransmission ? {
             diffuseTransmissionFactor: material.diffuseTransmission.factor,
@@ -1550,9 +1793,9 @@ async function pbrExtensionTextureOptions(asset, material, getTexture) {
         } : {})
     };
 }
-function renderTransmissionFallbackEnergy(material) {
+function renderTransmissionFallbackEnergy(material, qr) {
     const usesUnbackedCutoutTransmission = material.alphaMode === "MASK" && material.transmission?.texture === undefined && material.volume === undefined;
-    return usesUnbackedCutoutTransmission || usesUnbackedScalarTransmission(material) ? 0 : 0.08;
+    return usesUnbackedCutoutTransmission || usesUnbackedScalarTransmission(material, qr) ? 0 : 0.08;
 }
 function pbrTextureTexCoords(material) {
     return {
@@ -1580,7 +1823,7 @@ function pbrTextureTexCoords(material) {
 function renderTexCoord(texCoord) {
     return texCoord === 1 ? 1 : 0;
 }
-async function applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture) {
+async function applyPBRExtensionParameters(asset, runtimeMaterial, material, getTexture, qr) {
     if (material.clearcoat) {
         runtimeMaterial.setParameter("u_clearcoatFactor", material.clearcoat.factor);
         runtimeMaterial.setParameter("u_clearcoatRoughnessFactor", renderClearcoatRoughnessFactor(material));
@@ -1596,7 +1839,7 @@ async function applyPBRExtensionParameters(asset, runtimeMaterial, material, get
         }
     }
     if (material.transmission) {
-        runtimeMaterial.setParameter("u_transmissionFactor", usesUnbackedScalarTransmission(material) ? 0 : material.transmission.factor);
+        runtimeMaterial.setParameter("u_transmissionFactor", usesUnbackedScalarTransmission(material, qr) ? 0 : material.transmission.factor);
         if (material.transmission.texture) {
             await setTextureParameter(asset, runtimeMaterial, "u_transmissionTexture", material.transmission.texture, "linear", getTexture);
         }
@@ -1758,61 +2001,9 @@ function createSampler(texture) {
         };
     return new Sampler(samplerDescriptor);
 }
-async function decodeImageInBrowser(image, _imageIndex, asset, options = {}) {
-    if (isKTX2BasisImage(image)) {
-        const bytes = await readImageBytes(asset, image);
-        return transcodeKTX2BasisTexture(bytes, {
-            ...options.ktx2BasisTranscoderOptions,
-            targetFormat: options.ktx2BasisTargetFormat ?? options.ktx2BasisTranscoderOptions?.targetFormat
-        });
-    }
-    if (typeof createImageBitmap === "function") {
-        const blob = image.data
-            ? new Blob([image.data], { type: image.mimeType ?? "application/octet-stream" })
-            : await fetchImageBlob(asset, image);
-        const bitmap = await createImageBitmap(blob, {
-            colorSpaceConversion: "none",
-            premultiplyAlpha: "none"
-        });
-        return { width: bitmap.width, height: bitmap.height, source: bitmap, colorSpace: "srgb" };
-    }
-    const ImageCtor = globalThis.Image;
-    if (!ImageCtor || !image.uri) {
-        throw new Error("glTF image decoding requires createImageBitmap, HTMLImageElement, or a custom imageDecoder");
-    }
-    const imageElement = new ImageCtor();
-    const url = resolveImageUrl(asset.url, image.uri);
-    return new Promise((resolve, reject) => {
-        imageElement.onload = () => resolve({ width: imageElement.width, height: imageElement.height, source: imageElement, colorSpace: "srgb" });
-        imageElement.onerror = () => reject(new Error(`glTF image decode failed for ${url}`));
-        imageElement.src = url;
-    });
-}
 function createSamplerForInfo(asset, info) {
     return createSampler(asset.textures[info.texture]);
 }
-async function readImageBytes(asset, image) {
-    if (image.data)
-        return image.data.slice(0);
-    const blob = await fetchImageBlob(asset, image);
-    return blob.arrayBuffer();
-}
-async function fetchImageBlob(asset, image) {
-    if (!image.uri) {
-        throw new Error("glTF image has no uri or embedded data");
-    }
-    if (typeof fetch !== "function") {
-        throw new Error("glTF image fetch requires fetch or a custom imageDecoder");
-    }
-    const response = await fetch(resolveImageUrl(asset.url, image.uri));
-    if (!response.ok) {
-        throw new Error(`glTF image request failed with ${response.status}`);
-    }
-    return response.blob();
-}
-function isKTX2BasisImage(image) {
-    return image.mimeType === "image/ktx2" || /\.ktx2(?:[?#]|$)/i.test(image.uri ?? "");
-}
 function createFallbackTexture(label, colorSpace) {
     return new Texture({
         width: 1,
@@ -1828,38 +2019,4 @@ function warnMissingGLTFTexture(textureName, imageUri, reason) {
     const source = imageUri ? ` (${imageUri})` : "";
     console.warn(`glTF texture "${textureName}"${source} could not be loaded; falling back to baseColorFactor. Reason: ${reason}`);
 }
-function resolveImageUrl(assetUrl, imageUri) {
-    if (/^(?:data:|blob:|https?:|file:)/i.test(imageUri))
-        return imageUri;
-    if (assetUrl.startsWith("data:")) {
-        throw new Error(`Relative glTF image uri ${imageUri} cannot be resolved from a data URL asset`);
-    }
-    return new URL(imageUri, resolveAbsoluteAssetBase(assetUrl)).toString();
-}
-/**
- * Derive an absolute base URL for resolving relative texture URIs.
- *
- * Catalog assets are often loaded from root-relative paths (e.g.
- * `/aura-assets/x.glb`). `new URL(uri, base)` requires `base` to be absolute, so
- * a bare relative `assetUrl` throws `Failed to construct 'URL': Invalid base URL`.
- * If the asset URL is already absolute we use it directly; otherwise we resolve it
- * against the document/origin base when running in a browser, falling back to a
- * synthetic `file:///` origin so resolution never throws in non-browser contexts.
- */
-function resolveAbsoluteAssetBase(assetUrl) {
-    if (/^[a-z][a-z0-9+.-]*:/i.test(assetUrl))
-        return assetUrl;
-    const documentBase = (typeof document !== "undefined" && document.baseURI) ||
-        (typeof location !== "undefined" && location.href) ||
-        undefined;
-    if (documentBase) {
-        try {
-            return new URL(assetUrl, documentBase).toString();
-        }
-        catch {
-            // fall through to synthetic base below
-        }
-    }
-    return new URL(assetUrl, "file:///").toString();
-}
 //# sourceMappingURL=GLTFRenderResources.js.map