@aura3d/engine 3.0.0 → 4.0.0

package/dist/rendering/ForwardPass.js

@@ -2,23 +2,41 @@ import { Geometry } from "./Geometry.js";
 import {} from "./LightCollector.js";
 import { LightUniforms } from "./LightUniforms.js";
 import { Material } from "./Material.js";
-import { MaterialBinding } from "./MaterialBinding.js";
+import { MaterialBinding, MaterialBindingError } from "./MaterialBinding.js";
 import { MaterialInstance } from "./MaterialInstance.js";
-import { applyMorphTargets } from "./MorphTarget.js";
 import { RenderDeviceError } from "./RenderDevice.js";
 import { RenderPipeline } from "./RenderPipeline.js";
 import { BaseRenderPass } from "./RenderPass.js";
 import { MAX_UNIFORM_SKINNING_JOINTS as SHADER_MAX_UNIFORM_SKINNING_JOINTS } from "./ShaderChunks.js";
-import { decideSkinningPalettePath } from "./WebGPUSkinningLimits.js";
+import {} from "./WebGPUSkinningLimits.js";
 import { ShaderModule } from "./ShaderModule.js";
 import { createLeanCoreShaderLibrary } from "./ShaderLibraryCore.js";
-import { createShadowFilterKernel } from "./ShadowMap.js";
-import { Sampler } from "./Sampler.js";
-import { Texture } from "./Texture.js";
+import {} from "./ShadowMap.js";
 import { TextureBinding } from "./TextureBinding.js";
 import { UnlitMaterial } from "./UnlitMaterial.js";
 import { sortRenderQueueItems } from "./performance/RenderItemSorting.js";
-import { createClusteredForwardLighting } from "./ClusteredForwardLighting.js";
+import { blendQueueForState, blendStateIsTransparent } from "./BlendModes.js";
+import { renderStateKey } from "./contracts/blend.js";
+import {} from "./contracts/renderItem.js";
+import { instanceBufferSlot } from "./contracts/geometry.js";
+import {} from "./VertexFormat.js";
+import {} from "./ClusteredForwardLighting.js";
+import { programCacheSlot } from "./contracts/program.js";
+import { normalizeProgramFeatures } from "./program/ProgramFeatures.js";
+import { featuresForGeometry, geometryHasSkin, materialFeatureWarning, materialRoutesToGeneratedProgram } from "./program/MaterialFeatures.js";
+import { bindShaderFeatureUniforms, selectShaderFeatureBits } from "./program/FeatureSelect.js";
+import { bindMaterialLobeUniforms } from "./materials/PhysicalFeatures.js";
+import { QUALITY_TIERS } from "./contracts/quality.js";
+import { rendererQrFlags } from "./renderer/FrameGraph.js";
+import { qrCoreGeneratorOn, qrE3CompilerLightingOn, qrGeneratedProgramsOn, qrMaterialsLobeProgramsOn, rendererProgramCache, rendererAuraFrame } from "./renderer/qrSubFlags.js";
+import { PRD02_IBL_FEATURE } from "./contracts/environment.js";
+import { packA3DEnvironmentUniforms } from "./environment/EnvUniforms.js";
+import { dfgLutBinding, dfgLutTexture } from "./program/DFGLut.js";
+// PR 0b-2 re-imports for moved carve-out modules (CONTRACTS.md §3.3).
+import { SkinningPaletteUploadManager, applyGpuMorphUniforms, resolveRenderGeometry } from "./forward/Deform.js";
+import { FORWARD_DIRECT_LIGHT_CAPACITY, applyClusteredLightingUniforms, applyForwardShadowMapUniforms, resolveForwardClusteredLighting, selectForwardShadowMap } from "./forward/Lighting.js";
+import { flushMultiDrawQueue, submitDraw } from "./forward/DrawSubmit.js";
+import { bindVelocityUniforms } from "./forward/Velocity.js";
 /** Joints addressable through the uniform-array palette. Re-exported for shaders. */
 export const MAX_UNIFORM_SKINNING_JOINTS = SHADER_MAX_UNIFORM_SKINNING_JOINTS;
 /**
@@ -28,12 +46,10 @@ export const MAX_UNIFORM_SKINNING_JOINTS = SHADER_MAX_UNIFORM_SKINNING_JOINTS;
  * a 1024x4 texture) while covering rigs far beyond anything the uniform path allows.
  */
 export const MAX_SKINNING_JOINTS = 1024;
-const SKINNING_PALETTE_TEXTURE_MAX_WIDTH = 1024;
 export const MAX_GPU_MORPH_VERTICES = 64;
 export const MAX_GPU_MORPH_TARGETS = 4;
 export const MAX_GPU_INSTANCES = 64;
-const MAX_FORWARD_SHADOW_PCF_SAMPLES = 32;
-const DEFAULT_FORWARD_SHADOW_FILTER_KERNEL = createShadowFilterKernel({ filter: "pcf", pcfRadius: 1, pcfSamples: 9 });
+export const MAX_FORWARD_SHADOW_PCF_SAMPLES = 32;
 const INSTANCE_MATRIX_ATTRIBUTE_NAMES = [
     "a_instanceMatrix0",
     "a_instanceMatrix1",
@@ -47,20 +63,61 @@ export class ForwardPass extends BaseRenderPass {
     shaderLibrary;
     skinningPaletteUploads = new SkinningPaletteUploadManager();
     clusteredLighting = null;
+    generatorProgramCache;
+    // PRD-01 Phase 6 (submission performance): device-keyed pools — ForwardPass
+    // instances are rebuilt per frame/segment, so pass-level caches would never
+    // hit. Keyed by device they survive pass reconstruction (same precedent as
+    // `shaderCaches`) and die with the device.
+    static pipelineCaches = new WeakMap();
+    static uniformPacketPools = new WeakMap();
+    static instanceSlotPools = new WeakMap();
+    instanceSlotCursor = 0;
+    static vertexFormatIds = new WeakMap();
+    static nextVertexFormatId = 1;
+    static renderStateIds = new WeakMap();
+    static nextRenderStateId = 1;
+    static requiredAttributeIds = new WeakMap();
+    static nextRequiredAttributeId = 1;
     constructor(options) {
-        super("forward", options.inputColorResource ? [options.inputColorResource] : [], ["color"]);
+        super(options.framePass?.name ?? "forward", [...(options.inputColorResource ? [options.inputColorResource] : []), ...(options.framePass?.reads ?? [])], options.framePass?.writes ?? ["color"]);
         this.options = options;
         this.shaderLibrary = options.shaderLibrary ?? createLeanCoreShaderLibrary();
     }
     execute(context) {
         this.skinningPaletteUploads.beginFrame();
-        this.clusteredLighting = (this.options.lights?.length ?? 0) > 16
-            ? createClusteredForwardLighting(this.options.lights ?? [], context.width, context.height, this.options.cameraViewProjectionMatrix)
-            : null;
+        this.beginFramePools(context.device);
+        this.clusteredLighting = resolveForwardClusteredLighting(this.options.lights, context.width, context.height, this.options.cameraViewProjectionMatrix);
+        const flags = rendererQrFlags(context.device);
+        if (qrGeneratedProgramsOn(flags)) {
+            const auraFrame = rendererAuraFrame(context.device, flags);
+            if ("viewport" in auraFrame) {
+                auraFrame.viewport = { width: context.width, height: context.height };
+            }
+            const vp = this.options.cameraViewProjectionMatrix ?? identityMatrix();
+            auraFrame.update({
+                viewMatrix: toMat4Uniform(this.options.cameraViewMatrix ?? identityMatrix(), "cameraViewMatrix"),
+                projectionMatrix: toMat4Uniform(this.options.auraFrameCamera?.projectionMatrix ?? identityMatrix(), "auraFrameCamera.projectionMatrix"),
+                viewProjectionMatrix: toMat4Uniform(vp, "cameraViewProjectionMatrix"),
+                previousViewProjectionMatrix: this.options.auraFrameCamera?.previousViewProjectionMatrix
+                    ? toMat4Uniform(this.options.auraFrameCamera.previousViewProjectionMatrix, "auraFrameCamera.previousViewProjectionMatrix")
+                    : null,
+                near: this.options.auraFrameCamera?.near ?? 0.1,
+                far: this.options.auraFrameCamera?.far ?? 1000,
+                projection: this.options.auraFrameCamera?.projection ?? "perspective",
+                position: this.options.cameraPosition ?? [0, 0, 0]
+            }, this.options.timeSeconds ?? 0, this.options.exposure ?? 1, 0);
+            // The device binds the AuraFrame block to point 0 at link time
+            // (`uniformBlockBinding`), so one global buffer bind covers every
+            // generated draw this frame.
+            if (auraFrame.buffer)
+                context.device.bindUniformBuffer?.(auraFrame.buffer, 0);
+        }
         try {
             for (const item of sortForwardRenderItems(this.options.items, this.options.cameraPosition)) {
                 this.drawItem(context.device, item);
             }
+            // #181: issue any trailing multi-draw run deferred by `submitDraw`.
+            flushMultiDrawQueue(context.device);
         }
         finally {
             this.clusteredLighting?.dispose();
@@ -71,73 +128,128 @@ export class ForwardPass extends BaseRenderPass {
         const material = item.material ?? new UnlitMaterial();
         const baseMaterial = getBaseMaterial(material);
         this.applyLightUniforms(material);
-        const shader = this.getShader(baseMaterial, device);
+        let shader = this.getShader(baseMaterial, device, item);
+        if (shader === undefined)
+            return; // A3D_QR_CORE_GENERATOR async-skip (C-02 §A.2)
+        // Generated iff getShader resolved a generated program for this draw (a
+        // compile-failed fallback or an unskinnable skinned item is a legacy draw).
+        let generated = this.lastProgramFeatures !== undefined;
         if (item.instanceTransforms && baseMaterial.renderState.cullMode !== "none" && instancedItemNeedsPerInstanceCullState(item)) {
             for (const expanded of expandInstancedRenderItem(item)) {
                 this.drawItem(device, expanded);
             }
             return;
         }
-        if (item.instanceTransforms && !supportsInstanceAttributes(shader) && instanceTransformCount(item) > MAX_GPU_INSTANCES) {
+        // Phase 6: generated programs only know attribute-matrix instancing — the
+        // uniform fallback (`u_instanceMatrices[64]`) exists only in the frozen
+        // legacy library, so the >64 split and no-support expansion never apply
+        // on this path.
+        if (item.instanceTransforms && !generated && !supportsInstanceAttributes(shader) && instanceTransformCount(item) > MAX_GPU_INSTANCES) {
             for (const batch of splitInstanceTransforms(item.instanceTransforms)) {
                 this.drawItem(device, { ...item, instanceTransforms: batch });
             }
             return;
         }
-        if (item.instanceTransforms && !supportsInstanceAttributes(shader) && !supportsInstanceUniforms(shader)) {
+        if (item.instanceTransforms && !generated && !supportsInstanceAttributes(shader) && !supportsInstanceUniforms(shader)) {
             for (const expanded of expandInstancedRenderItem(item)) {
                 this.drawItem(device, expanded);
             }
             return;
         }
-        const binding = this.materialBinding.bind(material, shader);
-        const uniforms = new Map(binding.uniforms);
+        let uniforms = generated ? this.acquireUniformPacket(device) : new Map();
+        // #867 (games): binding validation never kills the frame. A generated
+        // draw that fails validation falls back to the legacy shaderKey program;
+        // a legacy draw that fails is skipped with one warning. Strict throws.
+        let binding = null;
+        try {
+            binding = generated
+                ? this.materialBinding.bindGenerated(material, shader, this.lastProgramFeatures, uniforms)
+                : this.materialBinding.bind(material, shader);
+        }
+        catch (error) {
+            if (!(error instanceof MaterialBindingError) || rendererQrFlags(device).on("A3D_QR_STRICT"))
+                throw error;
+            warnBindingOnce(item, baseMaterial, error, generated);
+            if (!generated)
+                return;
+            this.lastProgramFeatures = undefined;
+            generated = false;
+            shader = this.legacyShader(baseMaterial, device);
+            uniforms = new Map();
+            try {
+                binding = this.materialBinding.bind(material, shader);
+            }
+            catch (legacyError) {
+                if (!(legacyError instanceof MaterialBindingError))
+                    throw legacyError;
+                warnBindingOnce(item, baseMaterial, legacyError, false);
+                return;
+            }
+        }
+        if (!generated)
+            for (const [k, v] of binding.uniforms)
+                uniforms.set(k, v);
         applyClusteredLightingUniforms(this.clusteredLighting, shader, uniforms);
-        applyEnvironmentLightingUniforms(this.options.environmentLighting, item, shader, uniforms);
+        // E3 stage-2b: under the conjunction a generated draw that selected
+        // `prd02.ibl` shades indirect from the C-09 probe pack below (single
+        // knob), so its other environment binds stop competing for the same
+        // intensity names. E3 step 4/5: frozen draws under the conjunction get
+        // bind-level suppression of their stacked terms (and of the stale 0.18
+        // material default on no-environment draws) inside
+        // applyEnvironmentLightingUniforms — see its header note.
+        const drawFlags = rendererQrFlags(device);
+        const e3Conjunction = qrE3CompilerLightingOn(drawFlags);
+        const prd02Ibl = generated && e3Conjunction && this.lastProgramFeatures?.features[PRD02_IBL_FEATURE] !== undefined;
+        applyEnvironmentLightingUniforms(this.options.environmentLighting, item, shader, uniforms, { conjunction: e3Conjunction, generated });
+        if (generated)
+            applyGeneratedEnvironmentMapUniforms(this.options.environmentLighting, item, shader, uniforms, drawFlags);
+        if (generated)
+            applyGeneratedProceduralEnvironmentUniforms(this.options.environmentLighting, item, shader, uniforms, prd02Ibl);
         applyEnvironmentFogUniforms(this.options.environmentFog, item, shader, uniforms);
+        if (generated)
+            applyGeneratedFogUniforms(this.options.environmentFog, shader, uniforms);
         applyForwardShadowMapUniforms(selectForwardShadowMap(this.options.shadowMap, item, this.options.cameraViewMatrix, this.options.cameraPosition), item, shader, uniforms);
         applyOutputColorSpaceUniform(this.options.outputColorSpace ?? "srgb", item, shader, uniforms);
         applyCameraUniforms(this.options.cameraPosition, item, shader, uniforms);
         applyAlphaCutoffUniform(item, shader, uniforms);
         applyWrinkleUniform(item, shader, uniforms);
         applyTransformUniforms(item, shader, uniforms);
-        if (item.skinning) {
-            this.skinningPaletteUploads.bind(item, item.skinning, baseMaterial, shader, uniforms);
+        bindVelocityUniforms?.(item, uniforms);
+        if (generated && this.lastProgramFeatures) {
+            // C-02 `ShaderFeature.bindUniforms` for the features this draw selected.
+            bindShaderFeatureUniforms(this.lastProgramFeatures.features, rendererQrFlags(device), item, (name, value) => uniforms.set(name, value));
+            // E3 stage-2b bind site: `prd02.ibl` has no feature-local bind (the
+            // probe, knob and ambient are pass state, not item state), so the
+            // PRD-02 environment pack is bound here, in the feature-bind slot.
+            if (prd02Ibl)
+                applyPrd02EnvironmentUniforms(this.options.environmentLighting, item, material, uniforms);
+            // C-03 `lobe.bind` (04-LOBES): descriptor factors and lobe textures for the
+            // lobes this record carries. Material parameters stay authoritative.
+            bindMaterialLobeUniforms(this.lastProgramFeatures.extensions, baseMaterial, rendererQrFlags(device), (name, value) => {
+                if (!uniforms.has(name))
+                    uniforms.set(name, value);
+            });
+        }
+        if (item.skinning && !generated) {
+            // Legacy skinned programs take the u_jointMatrices palette; on the
+            // generated path prd06.deform's bindUniforms binds the bone texture, and
+            // a generated draw without it has no skin attributes (featuresForGeometry).
+            this.skinningPaletteUploads.bind(item, item.skinning, baseMaterial, shader, uniforms, device);
         }
-        const instanceBinding = item.instanceTransforms ? applyInstanceBinding(device, item, shader, uniforms) : { count: 1 };
+        const instanceBinding = item.instanceTransforms ? this.applyInstanceBinding(device, item, shader, uniforms, generated) : { count: 1 };
         const gpuMorph = item.morphTargets || item.morphWeights ? applyGpuMorphUniforms(item, shader, uniforms) : false;
         const geometry = gpuMorph ? item.geometry : resolveRenderGeometry(item);
-        validateMaterialGeometryContract(item, baseMaterial, geometry);
+        // Generated programs validate their selected attributes in MaterialBinding.
+        // The legacy descriptor can require maps/tangents deliberately masked out
+        // for this geometry, so it is not the generated program contract.
+        if (!generated)
+            validateMaterialGeometryContract(item, baseMaterial, geometry);
         try {
             const vertexBuffer = geometry.vertexBuffer.upload(device);
             const indexBuffer = geometry.indexBuffer?.upload(device);
             const drawRange = resolveDrawRange(geometry, item.drawRange);
-            const pipeline = new RenderPipeline({
-                label: item.label ?? baseMaterial.name,
-                shader,
-                vertexFormat: geometry.vertexBuffer.format,
-                topology: geometry.topology,
-                renderState: renderStateForItem(baseMaterial.renderState, item),
-                requiredAttributes: baseMaterial.requiredAttributes
-            });
-            const command = pipeline.createDrawCommand({
-                label: item.label,
-                vertexBuffer,
-                vertexCount: indexBuffer !== undefined ? geometry.vertexBuffer.vertexCount : drawRange.count,
-                ...(indexBuffer === undefined && drawRange.start > 0 ? { firstVertex: drawRange.start } : {}),
-                uniforms,
-                ...(item.instanceTransforms ? { instanceCount: instanceBinding.count } : {}),
-                ...(instanceBinding.attributes ? { instanceAttributes: instanceBinding.attributes } : {})
-            });
-            if (indexBuffer !== undefined) {
-                Object.assign(command, {
-                    indexBuffer,
-                    indexType: geometry.indexBuffer?.type,
-                    indexCount: drawRange.count,
-                    ...(drawRange.start > 0 ? { firstIndex: drawRange.start } : {})
-                });
-            }
-            device.draw(command);
+            const pipeline = this.pipelineFor(device, item, baseMaterial, shader, geometry);
+            submitDraw(device, pipeline, geometry, instanceBinding.count, drawRange, { item, vertexBuffer, indexBuffer, drawRange, uniforms, instanceBinding });
         }
         finally {
             for (const buffer of instanceBinding.buffers ?? [])
@@ -147,6 +259,49 @@ export class ForwardPass extends BaseRenderPass {
             }
         }
     }
+    /**
+     * Generated-path instancing (Phase 6): attribute matrices only — the
+     * `u_instanceMatrices[64]` uniform path exists solely in the frozen legacy
+     * library. Matrices (and colors) ride a persistent per-slot `InstanceBuffer`;
+     * `buffers` carries only transient extra-attribute buffers, which the draw
+     * finally-block disposes.
+     */
+    applyInstanceBinding(device, item, shader, uniforms, generated) {
+        if (!generated)
+            return applyInstanceBinding(device, item, shader, uniforms);
+        const source = validateInstanceTransformSource(item);
+        const count = source.length / 16;
+        const slot = this.instanceSlotFor(device, count, item.instanceColors !== undefined);
+        slot.buffer.setMatrices(source instanceof Float32Array ? source : new Float32Array(source), count);
+        if (item.instanceColors) {
+            slot.buffer.setColors(item.instanceColors instanceof Float32Array ? item.instanceColors : new Float32Array(item.instanceColors));
+        }
+        const bound = slot.buffer.bind();
+        const extra = createExtraInstanceAttributeBindings(device, item, count, false);
+        return {
+            count,
+            attributes: [
+                ...INSTANCE_MATRIX_ATTRIBUTE_NAMES.map((shaderName, column) => ({
+                    buffer: bound.matrixBuffer,
+                    shaderName,
+                    components: 4,
+                    offset: column * 16,
+                    stride: 64,
+                    divisor: 1
+                })),
+                ...(bound.colorBuffer ? [{
+                        buffer: bound.colorBuffer,
+                        shaderName: "a_instanceColor",
+                        components: 4,
+                        offset: 0,
+                        stride: 16,
+                        divisor: 1
+                    }] : []),
+                ...extra.attributes
+            ],
+            ...(extra.buffers.length > 0 ? { buffers: extra.buffers } : {})
+        };
+    }
     applyLightUniforms(material) {
         const baseMaterial = getBaseMaterial(material);
         if (!baseMaterial.requiredUniforms.includes("u_lightCount") || !baseMaterial.requiredUniforms.includes("u_lightData")) {
@@ -162,7 +317,53 @@ export class ForwardPass extends BaseRenderPass {
             material.setParameter("u_lightData", packed.data);
         }
     }
-    getShader(material, device) {
+    getShader(material, device, item) {
+        const flags = rendererQrFlags(device);
+        this.lastProgramFeatures = undefined;
+        // PRD-04: under `materials` without the core generator, lobe-bearing
+        // materials still take the generated program (the legacy shader has no
+        // lobe code). That program writes linear HDR, so the lobe route only runs
+        // into a linear target (postprocess / OutputPass encodes).
+        const route = {
+            core: qrCoreGeneratorOn(flags),
+            lobes: qrMaterialsLobeProgramsOn(flags) && this.options.outputColorSpace === "linear"
+        };
+        if ((route.core || route.lobes) && materialRoutesToGeneratedProgram(material, route, { flags, tier: this.options.qualityTier ?? QUALITY_TIERS.high })) {
+            const warning = materialFeatureWarning(material);
+            if (warning)
+                console.warn(`[prd01] ${warning}`);
+            this.lastProgramFeatures = this.programFeaturesFor(material, device, item);
+            // #867: a skinned draw needs its program to skin. When no registered
+            // deform feature (prd06.deform, A3D_QR_ANIMATION) selected this item,
+            // the generated program has no skinning, so the draw keeps the legacy
+            // skinned shaderKey program instead of rendering the bind pose.
+            // A skinned item whose geometry has no joints/weights draws unskinned on
+            // the generated program (features follow the geometry, #867 games).
+            if (item?.skinning && geometryHasSkin((a) => geometryHasAttribute(item.geometry, a)) && this.lastProgramFeatures.features["prd06.deform"] === undefined) {
+                this.lastProgramFeatures = undefined;
+                return this.legacyShader(material, device);
+            }
+            const handle = this.programCache(device).acquire(this.lastProgramFeatures);
+            if (handle.status === "failed") {
+                // T0-03: the cache already emitted `program-compile-failed` (C-36) +
+                // console.error. Strict escalates to a throw; otherwise the draw falls
+                // back to the legacy shaderKey path below.
+                if (flags.on("A3D_QR_STRICT")) {
+                    throw new RenderDeviceError(`generated program failed to compile: ${handle.error ?? handle.key}`, "PROGRAM_COMPILE_FAILED", { key: handle.key });
+                }
+                // The fallback draw is a legacy draw: bind it as one.
+                this.lastProgramFeatures = undefined;
+            }
+            else {
+                // async-skip: a not-yet-ready program skips the draw this frame
+                // (C-02 §A.2 semantics; warm-then-block warmup renders them ready up front).
+                return handle.status === "ready" ? handle.program : undefined;
+            }
+        }
+        return this.legacyShader(material, device);
+    }
+    /** Frozen legacy shaderKey program (flag-off path, and generated-path fallbacks). */
+    legacyShader(material, device) {
         const cacheKey = shaderCacheKey(material);
         const shaderCache = getForwardPassShaderCache(device, this.shaderLibrary);
         let module = shaderCache.get(cacheKey);
@@ -174,97 +375,199 @@ export class ForwardPass extends BaseRenderPass {
         }
         return module.compile(device);
     }
-}
-export class SkinningPaletteUploadManager {
-    static validatedGeometryJointCounts = new WeakMap();
-    static maxRecordedDecisions = 64;
-    submissions = 0;
-    jointsUploaded = 0;
-    maxJointCount = 0;
-    uniformArraySubmissions = 0;
-    dataTextureSubmissions = 0;
-    eightInfluenceSubmissions = 0;
-    cpuFallbackCount = 0;
-    decisions = [];
-    decisionOverflow = 0;
-    beginFrame() {
-        this.submissions = 0;
-        this.jointsUploaded = 0;
-        this.maxJointCount = 0;
-        this.uniformArraySubmissions = 0;
-        this.dataTextureSubmissions = 0;
-        this.eightInfluenceSubmissions = 0;
-        this.cpuFallbackCount = 0;
-        this.decisions = [];
-        this.decisionOverflow = 0;
+    /** Feature record for the program `getShader` most recently resolved (C-02). */
+    lastProgramFeatures;
+    programCache(device) {
+        this.generatorProgramCache ??= rendererProgramCache(device, rendererQrFlags(device));
+        return this.generatorProgramCache;
+    }
+    programFeaturesFor(material, device, item) {
+        const flags = rendererQrFlags(device);
+        const tier = this.options.qualityTier ?? QUALITY_TIERS.high;
+        const mf = material.programFeatures({ flags, tier });
+        const axes = forwardPassFeatureAxes(this.options, this.clusteredLighting !== null);
+        // T0-05: registered ShaderFeatures select their bits per draw (C-02 §A.2:
+        // at acquire time); the warmup applies the same selection per item.
+        const selected = item ? selectShaderFeatureBits({ item, pass: "forward", tier, flags }) : {};
+        // E3 stage-2b: `prd02.ibl` shades from a C-09 probe cube; without one
+        // (bare preset/procedural lighting) the default indirect body stays.
+        if (selected[PRD02_IBL_FEATURE] !== undefined && !prd02IblEnvironmentAvailable(this.options.environmentLighting, item)) {
+            delete selected[PRD02_IBL_FEATURE];
+        }
+        // #867 (games): the feature set follows what the geometry carries
+        // (three.js semantics): no uv → no uv maps, no joints/weights → no skin.
+        const record = item ? featuresForGeometry({ ...mf, features: { ...mf.features, ...selected } }, (a) => geometryHasAttribute(item.geometry, a)) : { ...mf, features: { ...mf.features, ...selected } };
+        return normalizeProgramFeatures({
+            ...record,
+            ...axes,
+            // Phase 6: instancing is item-driven — a material's own feature record
+            // only declares it when authored instanced; the draw's program must
+            // cover the union (attribute matrices are the only generated path).
+            ...(item?.instanceTransforms ? { instancing: { color: item.instanceColors !== undefined } } : {}),
+            // #1140: a per-item probe cube (PRD-02 S12) is sampled as a cube.
+            ...(item?.environmentCube?.texture?.dimension === "cube" ? { environment: "pmrem-cube" } : {}),
+            backgroundCoverage: this.options.backgroundCoverage === true,
+            pass: "forward",
+            target: "glsl300es"
+        });
+    }
+    // ── Phase 6 submission-perf pools ──────────────────────────────────────
+    static packetPoolFor(device) {
+        let pool = ForwardPass.uniformPacketPools.get(device);
+        if (!pool) {
+            pool = { free: [], used: [] };
+            ForwardPass.uniformPacketPools.set(device, pool);
+        }
+        return pool;
+    }
+    beginFramePools(device) {
+        const pool = ForwardPass.packetPoolFor(device);
+        if (pool.used.length > 0) {
+            pool.free.push(...pool.used);
+            pool.used = [];
+        }
+        this.instanceSlotCursor = 0;
+    }
+    /** A cleared per-item scratch map; recycled after the next execute begins. */
+    acquireUniformPacket(device) {
+        const pool = ForwardPass.packetPoolFor(device);
+        const packet = pool.free.pop() ?? new Map();
+        packet.clear();
+        pool.used.push(packet);
+        return packet;
+    }
+    /** Identity ids for the pipeline key — avoids serializing descriptors per draw. */
+    static weakId(map, next, key) {
+        const existing = map.get(key);
+        if (existing !== undefined)
+            return existing;
+        const id = next();
+        map.set(key, id);
+        return id;
     }
     /**
-     * Which palette paths this frame actually used. Published rather than inferred so a
-     * claim about data-texture or eight-influence skinning rests on observed submissions.
-     * Each submission also records its `decideSkinningPalettePath` decision (same inputs the
-     * upload path used) so the CPU-fallback reason code travels with the diagnostics.
+     * One `RenderPipeline` per (shader, vertex format, topology, render state,
+     * required attributes) — previously constructed per item per frame. The
+     * pipeline is a pure descriptor: no GL resources, safe to reuse.
      */
-    diagnostics() {
-        return {
-            submissions: this.submissions,
-            jointsUploaded: this.jointsUploaded,
-            maxJointCount: this.maxJointCount,
-            uniformArraySubmissions: this.uniformArraySubmissions,
-            dataTextureSubmissions: this.dataTextureSubmissions,
-            eightInfluenceSubmissions: this.eightInfluenceSubmissions,
-            cpuFallbackCount: this.cpuFallbackCount,
-            maxUniformJoints: MAX_UNIFORM_SKINNING_JOINTS,
-            decisions: [...this.decisions],
-            decisionOverflow: this.decisionOverflow
-        };
-    }
-    bind(item, skinning, material, shader, uniforms) {
-        // Recorded before the upload so a contract throw still leaves its reason code behind.
-        this.recordDecision(item, skinning, shader);
-        const path = applySkinningUniforms(skinning, material, shader, uniforms);
-        if (path === "data-texture")
-            this.dataTextureSubmissions += 1;
-        else
-            this.uniformArraySubmissions += 1;
-        const eightInfluence = item.geometry.vertexBuffer.format.hasAttribute("joints1")
-            && item.geometry.vertexBuffer.format.hasAttribute("weights1");
-        if (eightInfluence)
-            this.eightInfluenceSubmissions += 1;
-        const validatedJointCounts = SkinningPaletteUploadManager.validatedGeometryJointCounts.get(item.geometry) ?? new Set();
-        if (!validatedJointCounts.has(skinning.jointCount)) {
-            validateSkinningGeometryContract(item, skinning);
-            validatedJointCounts.add(skinning.jointCount);
-            SkinningPaletteUploadManager.validatedGeometryJointCounts.set(item.geometry, validatedJointCounts);
+    pipelineFor(device, item, baseMaterial, shader, geometry) {
+        const renderState = renderStateForItem(baseMaterial.renderState, item);
+        const vertexFormatId = ForwardPass.weakId(ForwardPass.vertexFormatIds, () => ForwardPass.nextVertexFormatId++, geometry.vertexBuffer.format);
+        const renderStateId = ForwardPass.weakId(ForwardPass.renderStateIds, () => ForwardPass.nextRenderStateId++, baseMaterial.renderState);
+        const attrsId = ForwardPass.weakId(ForwardPass.requiredAttributeIds, () => ForwardPass.nextRequiredAttributeId++, baseMaterial.requiredAttributes);
+        // `renderStateForItem` returns the SAME object for the unflipped case, so
+        // the flip bit is the only per-item term needed in the key.
+        const key = `${shader.id}|${vertexFormatId}|${geometry.topology ?? "triangles"}|${renderStateId}:${renderState === baseMaterial.renderState ? 0 : 1}|${attrsId}`;
+        let cache = ForwardPass.pipelineCaches.get(device);
+        if (!cache) {
+            cache = new Map();
+            ForwardPass.pipelineCaches.set(device, cache);
         }
-        this.submissions += 1;
-        this.jointsUploaded += skinning.jointCount;
-        this.maxJointCount = Math.max(this.maxJointCount, skinning.jointCount);
-    }
-    recordDecision(item, skinning, shader) {
-        const reflection = shader.reflection.uniforms;
-        const decision = decideSkinningPalettePath({
-            jointCount: skinning.jointCount,
-            maxUniformJoints: MAX_UNIFORM_SKINNING_JOINTS,
-            maxDataTextureJoints: MAX_SKINNING_JOINTS,
-            shaderHasSkinningUniforms: reflection.has("u_jointMatrices") && reflection.has("u_jointCount"),
-            shaderHasDataTexturePalette: reflection.has("u_jointPaletteTexture") && reflection.has("u_jointPaletteMode")
-        });
-        if (decision.cpuFallback)
-            this.cpuFallbackCount += 1;
-        if (this.decisions.length < SkinningPaletteUploadManager.maxRecordedDecisions) {
-            this.decisions.push({
-                label: item.label ?? "skinned-item",
-                jointCount: skinning.jointCount,
-                path: decision.path,
-                reason: decision.reason,
-                cpuFallback: decision.cpuFallback
+        let pipeline = cache.get(key);
+        if (!pipeline || pipeline.shader !== shader) {
+            pipeline = new RenderPipeline({
+                label: item.label ?? baseMaterial.name,
+                shader,
+                vertexFormat: geometry.vertexBuffer.format,
+                topology: geometry.topology,
+                renderState,
+                requiredAttributes: this.lastProgramFeatures
+                    ? baseMaterial.requiredAttributes.filter((attribute) => !["a_uv", "a_uv1", "a_color", "a_tangent", "a_joints", "a_weights", "a_joints1", "a_weights1"].includes(attribute)
+                        || geometry.vertexBuffer.format.attributes.some((a) => a.semantic === attribute || a.shaderName === attribute))
+                    : baseMaterial.requiredAttributes
             });
+            cache.set(key, pipeline);
         }
-        else {
-            this.decisionOverflow += 1;
+        return pipeline;
+    }
+    /**
+     * Persistent attribute-matrix slot for the generated path (Phase 6): slots
+     * are reused in draw order; capacity/colors mismatches retire the old
+     * buffer (its VAOs are evicted by the §6.1 dispose fix).
+     */
+    instanceSlotFor(device, count, colors) {
+        const index = this.instanceSlotCursor;
+        this.instanceSlotCursor += 1;
+        const capacity = Math.max(64, 2 ** Math.ceil(Math.log2(Math.max(1, count))));
+        let slots = ForwardPass.instanceSlotPools.get(device);
+        if (!slots) {
+            slots = [];
+            ForwardPass.instanceSlotPools.set(device, slots);
+        }
+        const existing = slots[index];
+        if (existing && existing.colors === colors && existing.capacity >= count) {
+            return existing;
         }
+        existing?.buffer.dispose();
+        const buffer = instanceBufferSlot.get(rendererQrFlags(device))(device, capacity, { colors });
+        const slot = { buffer, colors, capacity };
+        slots[index] = slot;
+        if (slots.length > index + 64)
+            slots.length = index + 64;
+        return slot;
     }
 }
+function lightBucket(count, max = 8) {
+    return count <= 0 ? 0 : count === 1 ? 1 : count === 2 ? 2 : count <= 4 ? 4 : max;
+}
+/**
+ * Pass-owned feature axes (C-02): lights/shadows/environment/fog shared by every
+ * material in the pass. `clustered` is the pass's resolved state; above
+ * FORWARD_DIRECT_LIGHT_CAPACITY lights the axes report clustered regardless.
+ */
+export function forwardPassFeatureAxes(options, clustered) {
+    let directional = 0;
+    let point = 0;
+    let spot = 0;
+    let rect = 0;
+    for (const light of options.lights ?? []) {
+        if (light.kind === "directional")
+            directional += 1;
+        else if (light.kind === "point")
+            point += 1;
+        else if (light.kind === "spot")
+            spot += 1;
+        else
+            rect += 1;
+    }
+    const fog = options.environmentFog;
+    const fogMode = fog === undefined || fog === false
+        ? "none"
+        : fog.mode === "linear"
+            ? "linear"
+            : fog.heightFalloff !== undefined
+                ? "height"
+                : "exp2";
+    const env = options.environmentLighting;
+    return {
+        lights: {
+            dir: lightBucket(directional),
+            point: lightBucket(point),
+            spot: lightBucket(spot),
+            rect: lightBucket(rect, 4),
+            // #1140: mirrors resolveForwardClusteredLighting (clusters above the
+            // u_lightData capacity), not the per-kind key bucket.
+            clustered: clustered || directional + point + spot + rect > FORWARD_DIRECT_LIGHT_CAPACITY,
+            hemisphere: env?.proceduralMap !== undefined
+        },
+        shadows: options.shadowMap
+            ? { cascades: Math.max(1, Math.min(4, options.shadowMap.cascades?.length ?? 1)), pcfTaps: 4, localShadows: 0, contact: false }
+            : { cascades: 0, pcfTaps: 4, localShadows: 0, contact: false },
+        environment: 
+        // #1140: the generated env chunk samples exactly the texture it was
+        // selected for. The prefiltered cube wins when present (the flag-off
+        // shader mixes to the cube whenever it is enabled); otherwise the 2D
+        // `environmentMapTexture`. Procedural-only → no sampler at all.
+        env?.environmentCubeMapTexture?.texture?.dimension === "cube"
+            ? "pmrem-cube"
+            : env?.environmentMapTexture?.texture !== undefined
+                ? "equirect"
+                : "none",
+        fog: fogMode
+    };
+}
+export { SkinningPaletteUploadManager, releaseMorphScratchGeometry } from "./forward/Deform.js";
+export { ensureMorphTargetTexture, releaseMorphTargetTexture, morphTextureDiagnostics } from "./shaders/deform/forwardFeature.js";
 function getForwardPassShaderCache(device, library) {
     let libraryCaches = ForwardPass["shaderCaches"].get(device);
     if (!libraryCaches) {
@@ -296,6 +599,47 @@ function applyOutputColorSpaceUniform(outputColorSpace, item, shader, uniforms)
     }
     uniforms.set("u_outputColorSpace", outputColorSpace === "srgb" ? 1 : 0);
 }
+/**
+ * C-02 generated-program fog. `fog_default` declares `u_fogColor`,
+ * `u_fogRange`, `u_fogDensity` and `u_fogHeightFalloff` under FOG_LINEAR /
+ * FOG_EXP2 / FOG_HEIGHT, and `forwardProgramFeatures` selects those defines
+ * whenever the frame has fog. Nothing bound them, so every uniform read 0:
+ * the exp2 factor was 1 - exp(0) = 0 and generated programs drew no fog at all
+ * (scenes 09/17/18 under A3D_QR_CORE: distant surfaces kept their own colour
+ * instead of blending to the fog colour).
+ *
+ * The values are the legacy `u_environmentFog*` inputs. The generated chunk
+ * follows three.js FogExp2/Fog: view depth, and no opacity cap (legacy
+ * `maxOpacity` is a legacy-only clamp). Lane 07's PRD-07 fog chunk shares
+ * `u_fogColor` (#880); a value it already set is kept.
+ */
+export function generatedFogUniformValues(fog) {
+    if (!fog)
+        return undefined;
+    return new Map([
+        ["u_fogColor", Array.from(fog.color)],
+        ["u_fogRange", [fog.near, fog.far]],
+        ["u_fogDensity", fog.density],
+        ["u_fogHeightFalloff", fog.heightFalloff ?? 0]
+    ]);
+}
+export function applyGeneratedFogUniforms(fog, shader, uniforms) {
+    // Reflection lists ACTIVE uniforms only: exp2 programs drop the unused
+    // `u_fogRange`, linear ones drop `u_fogDensity`. Either marks fog_default
+    // (forward programs declare neither otherwise; lane 07 uses u_fogA/u_fogB).
+    if (!shader.reflection.uniforms.has("u_fogRange") && !shader.reflection.uniforms.has("u_fogDensity"))
+        return;
+    const values = generatedFogUniformValues(fog);
+    if (!values)
+        return;
+    for (const [name, value] of values) {
+        if (!shader.reflection.uniforms.has(name))
+            continue;
+        if (name === "u_fogColor" && uniforms.has(name))
+            continue;
+        uniforms.set(name, value);
+    }
+}
 function applyEnvironmentFogUniforms(fog, item, shader, uniforms) {
     const requiredUniforms = [
         "u_environmentFogEnabled",
@@ -446,6 +790,17 @@ function resolveDrawRange(geometry, range) {
     }
     return range;
 }
+const warnedBindings = new WeakMap();
+/** One console warning per (material, item label, path) for a non-fatal binding failure. */
+function warnBindingOnce(item, material, error, generated) {
+    const key = `${item.label ?? ""}|${generated ? "generated" : "legacy"}`;
+    const seen = warnedBindings.get(material) ?? new Set();
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    warnedBindings.set(material, seen);
+    console.warn(`[prd01] ${generated ? "generated draw falls back to the legacy program" : "draw skipped"} for "${item.label ?? material.name}": ${error.message}`);
+}
 function geometryHasAttribute(geometry, attribute) {
     return geometry.vertexBuffer.format.attributes.some((candidate) => candidate.semantic === attribute || candidate.shaderName === attribute);
 }
@@ -588,444 +943,304 @@ function invertMat4(matrix) {
         (a20 * b03 - a21 * b01 + a22 * b00) * invDet
     ];
 }
-export function selectForwardShadowMap(shadowMap, item, cameraViewMatrix, cameraPosition) {
-    const cascades = shadowMap?.cascades;
-    if (!shadowMap || !cascades || cascades.length === 0)
-        return shadowMap;
-    const center = renderItemWorldCenter(item);
-    const depth = cameraViewMatrix && cameraViewMatrix.length >= 16
-        ? Math.max(0, -(cameraViewMatrix[2] * center[0]
-            + cameraViewMatrix[6] * center[1]
-            + cameraViewMatrix[10] * center[2]
-            + cameraViewMatrix[14]))
-        : cameraPosition
-            ? Math.hypot(center[0] - cameraPosition[0], center[1] - cameraPosition[1], center[2] - cameraPosition[2])
-            : cascades[0].near;
-    const selected = cascades.find((cascade) => depth <= cascade.far) ?? cascades[cascades.length - 1];
-    return selected.shadowMap;
-}
-function renderItemWorldCenter(item) {
-    const local = item.boundingBoxCenter ?? [
-        (item.geometry.bounds.min[0] + item.geometry.bounds.max[0]) / 2,
-        (item.geometry.bounds.min[1] + item.geometry.bounds.max[1]) / 2,
-        (item.geometry.bounds.min[2] + item.geometry.bounds.max[2]) / 2
-    ];
-    const matrix = item.modelMatrix;
-    if (!matrix || matrix.length < 16)
-        return local;
-    return [
-        matrix[0] * local[0] + matrix[4] * local[1] + matrix[8] * local[2] + matrix[12],
-        matrix[1] * local[0] + matrix[5] * local[1] + matrix[9] * local[2] + matrix[13],
-        matrix[2] * local[0] + matrix[6] * local[1] + matrix[10] * local[2] + matrix[14]
-    ];
-}
-function applyForwardShadowMapUniforms(shadowMap, item, shader, uniforms) {
-    const requiredUniforms = [
-        "u_shadowMapTexture",
-        "u_shadowMapEnabled",
-        "u_shadowMapMatrix",
-        "u_shadowMapStrength",
-        "u_shadowMapBias",
-        "u_shadowMapSlopeBias",
-        "u_shadowMapTexelSize",
-        "u_shadowPcfSampleCount",
-        "u_shadowPcfSamples"
-    ];
-    if (!requiredUniforms.every((uniform) => shader.reflection.uniforms.has(uniform))) {
+export { selectForwardShadowMap } from "./forward/Lighting.js";
+export { applyForwardSpotShadowMapUniforms } from "./forward/Lighting.js";
+/**
+ * Frozen-namespace environment binds (`u_environmentColor` /
+ * `u_environmentIntensity` / procedural / sampled), shared by both program
+ * families.
+ *
+ * E3 step 4 (frozen family, bind-level by design): the frozen shaders
+ * (ShaderLibraryCore lean PBR + ShaderLibrary duplicates) are fallback-only
+ * and their sources must stay byte-identical flag-off, so under the
+ * conjunction a frozen draw's stacked terms are suppressed here instead of
+ * by shader-body surgery: the procedural diffuse+specular are zeroed, the
+ * duplicated ambient is zeroed when a sampled term shades from a
+ * non-probe bundle, and absent sampled intensities read 0 (step-3 parity
+ * with the generated binder). The sampled term — the single knob under the
+ * conjunction — is kept. NOT bind-removable, so deliberately left and
+ * UNVERIFIED until the L4 capture: the shader-constant sampled-specular
+ * fudges (ShaderLibraryCore `mix(1.1, 0.65, roughness)`, ShaderLibrary
+ * `mix(0.84, 0.58, …)` variants) and the extension environment re-add
+ * (`a3dPbrExtensionEnvironmentLight` reuses the sampled radiance for its
+ * lobes; zeroing it at the bind layer would mean zeroing the material
+ * extension factors that also drive direct extension light). Its input is
+ * de-stacked (procedural removed) by the zeroing above.
+ *
+ * E3 step 5 (0.18 at the bind layer): `DEFAULT_PBR_ENVIRONMENT_INTENSITY`
+ * (PBRLightingDefaults, public API at index.ts) is a material-constructor
+ * default for `u_environmentIntensity`. With an environment present this
+ * function overwrites it per draw — always the case on production engine
+ * paths, where compileScene's RenderSource resolves through
+ * `collectEnvironmentLighting`, which never returns undefined for a
+ * RenderSource. It otherwise survives only when the pass has no
+ * environment at all: Renderer `Scene`/iterable sources and direct
+ * ForwardPass use (both public `@aura3d/rendering` surfaces, not
+ * production engine paths). Under the conjunction that branch now binds
+ * `u_environmentIntensity = 0` (absent knob means zero, step-3 rule), so
+ * the stale constructor default never reaches a conjunction draw; the
+ * public constant and every conjunction-off packet are unchanged.
+ */
+export function applyEnvironmentLightingUniforms(environment, item, shader, uniforms, e3 = {}) {
+    const generatedE3Conjunction = e3.conjunction === true && e3.generated === true;
+    const frozenE3Conjunction = e3.conjunction === true && e3.generated !== true;
+    if (!environment) {
+        clearProceduralEnvironmentMapUniforms(shader, uniforms);
+        clearSampledEnvironmentMapUniforms(shader, uniforms);
+        clearEnvironmentBrdfLutUniforms(shader, uniforms);
+        // E3 step 5: see header note — never let the 0.18 constructor default
+        // (or any material-side ambient scalar) survive a no-environment
+        // conjunction draw. Conjunction-off the packet is untouched.
+        if (e3.conjunction === true && shader.reflection.uniforms.has("u_environmentIntensity")) {
+            uniforms.set("u_environmentIntensity", 0);
+        }
         return;
     }
-    applyForwardPointShadowMapUniforms(shadowMap?.pointLight, item, shader, uniforms);
-    applyForwardSpotShadowMapUniforms(shadowMap?.spotLight, item, shader, uniforms);
-    if (!shadowMap) {
-        uniforms.set("u_shadowMapTexture", new TextureBinding({ name: "u_shadowMapTexture", required: false }));
-        uniforms.set("u_shadowMapEnabled", 0);
-        uniforms.set("u_shadowMapMatrix", new Float32Array(identityMatrix()));
-        uniforms.set("u_shadowMapStrength", 0);
-        uniforms.set("u_shadowMapBias", 0);
-        uniforms.set("u_shadowMapSlopeBias", 0);
-        uniforms.set("u_shadowMapTexelSize", [1, 1]);
-        uniforms.set("u_shadowPcfSampleCount", 1);
-        uniforms.set("u_shadowPcfSamples", new Float32Array(MAX_FORWARD_SHADOW_PCF_SAMPLES * 4));
+    if (!shader.reflection.uniforms.has("u_environmentColor") || !shader.reflection.uniforms.has("u_environmentIntensity")) {
         return;
     }
-    const validation = shadowMap.texture.validate();
-    if (!validation.ok) {
-        throw new RenderDeviceError("Forward shadow-map texture binding validation failed", "FORWARD_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            diagnostics: validation.diagnostics
-        });
-    }
-    const strength = shadowMap.strength ?? 0.65;
-    const bias = shadowMap.bias ?? 0.001;
-    const slopeBias = shadowMap.slopeBias ?? 1;
-    const texelSize = shadowMap.texelSize ?? [
-        1 / Math.max(1, shadowMap.texture.texture?.width ?? 1),
-        1 / Math.max(1, shadowMap.texture.texture?.height ?? 1)
-    ];
-    if (!Number.isFinite(strength) || strength < 0 || strength > 1) {
-        throw new RenderDeviceError("Forward shadow-map strength must be finite in [0, 1]", "FORWARD_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            strength
-        });
-    }
-    if (!Number.isFinite(bias) || bias < 0) {
-        throw new RenderDeviceError("Forward shadow-map bias must be finite and non-negative", "FORWARD_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            bias
-        });
-    }
-    if (!Number.isFinite(slopeBias) || slopeBias < 0) {
-        throw new RenderDeviceError("Forward shadow-map slopeBias must be finite and non-negative", "FORWARD_SHADOW_MAP_CONTRACT", {
+    const color = environment.color;
+    if (color.length !== 3 || !isFiniteColor(color)) {
+        throw new RenderDeviceError("Environment lighting color must contain three finite values in [0, 1]", "ENVIRONMENT_LIGHTING_CONTRACT", {
             label: item.label,
-            slopeBias
+            color
         });
     }
-    if (texelSize.length !== 2 || !texelSize.every((value) => Number.isFinite(value) && value > 0)) {
-        throw new RenderDeviceError("Forward shadow-map texelSize must contain two finite positive values", "FORWARD_SHADOW_MAP_CONTRACT", {
+    if (!Number.isFinite(environment.intensity) || environment.intensity < 0) {
+        throw new RenderDeviceError("Environment lighting intensity must be finite and non-negative", "ENVIRONMENT_LIGHTING_CONTRACT", {
             label: item.label,
-            texelSize: Array.from(texelSize)
+            intensity: environment.intensity
         });
     }
-    const filterKernel = shadowMap.filterKernel ?? DEFAULT_FORWARD_SHADOW_FILTER_KERNEL;
-    const pcfSamples = packForwardShadowPcfSamples(filterKernel, item.label);
-    uniforms.set("u_shadowMapTexture", shadowMap.texture);
-    uniforms.set("u_shadowMapEnabled", 1);
-    uniforms.set("u_shadowMapMatrix", toMat4Uniform(shadowMap.lightMatrix, "shadowMap.lightMatrix", item.label));
-    uniforms.set("u_shadowMapStrength", strength);
-    uniforms.set("u_shadowMapBias", bias);
-    uniforms.set("u_shadowMapSlopeBias", slopeBias);
-    uniforms.set("u_shadowMapTexelSize", texelSize);
-    uniforms.set("u_shadowPcfSampleCount", filterKernel.samples.length);
-    uniforms.set("u_shadowPcfSamples", pcfSamples);
-}
-function applyClusteredLightingUniforms(clustered, shader, uniforms) {
-    const required = [
-        "u_clusteredLightEnabled",
-        "u_clusterGridSize",
-        "u_clusterViewportSize",
-        "u_clusterLightData",
-        "u_clusterLightIndices"
-    ];
-    if (!required.every((name) => shader.reflection.uniforms.has(name)))
-        return;
-    if (!clustered) {
-        uniforms.set("u_clusteredLightEnabled", 0);
-        uniforms.set("u_clusterGridSize", [1, 1]);
-        uniforms.set("u_clusterViewportSize", [1, 1]);
-        uniforms.set("u_clusterLightData", new TextureBinding({ name: "u_clusterLightData", required: false }));
-        uniforms.set("u_clusterLightIndices", new TextureBinding({ name: "u_clusterLightIndices", required: false }));
-        return;
+    uniforms.set("u_environmentColor", color);
+    uniforms.set("u_environmentIntensity", environment.intensity);
+    applyProceduralEnvironmentMapUniforms(environment.proceduralMap, item, shader, uniforms, generatedE3Conjunction);
+    const sampledEnvironment = withItemEnvironmentCube(environment, item);
+    applySampledEnvironmentMapUniforms(sampledEnvironment, item, shader, uniforms, frozenE3Conjunction);
+    if (frozenE3Conjunction) {
+        // E3 step 4 frozen suppression (see header note): when a sampled
+        // environment is present, procedural terms are zeroed after their
+        // validating bind (matching `#ifndef A3D_ENV_SAMPLE` in the generated
+        // shader), so conjunction-off packets, procedural-only fallbacks, and
+        // error behavior are unchanged. The ambient scalar is a stacked
+        // duplicate of the sampled knob only for non-probe bundles with a
+        // sampled term: probe-path lighting carries the authored ambient in
+        // `intensity` (additive outside IBL, F-02-01), and with no sampled
+        // term the ambient and procedural terms remain active.
+        const sampledPresent = sampledEnvironment.environmentMapTexture !== undefined
+            || sampledEnvironment.environmentCubeMapTexture !== undefined;
+        if (sampledPresent) {
+            clearProceduralEnvironmentMapUniforms(shader, uniforms);
+        }
+        if (sampledPresent && !environment.environmentProbe) {
+            uniforms.set("u_environmentIntensity", 0);
+        }
     }
-    uniforms.set("u_clusteredLightEnabled", 1);
-    uniforms.set("u_clusterGridSize", [clustered.diagnostics.gridWidth, clustered.diagnostics.gridHeight]);
-    uniforms.set("u_clusterViewportSize", [
-        clustered.diagnostics.viewportWidth,
-        clustered.diagnostics.viewportHeight
-    ]);
-    uniforms.set("u_clusterLightData", clustered.lightData);
-    uniforms.set("u_clusterLightIndices", clustered.lightIndices);
 }
-function applyForwardPointShadowMapUniforms(pointShadowMap, item, shader, uniforms) {
-    const requiredUniforms = [
-        "u_pointShadowMapTexture",
-        "u_pointShadowMapEnabled",
-        "u_pointShadowLightPosition",
-        "u_pointShadowRange",
-        "u_pointShadowFaceMatrices",
-        "u_pointShadowFaceRects",
-        "u_pointShadowStrength",
-        "u_pointShadowBias",
-        "u_pointShadowSlopeBias",
-        "u_pointShadowTexelSize",
-        "u_pointShadowPcfSampleCount",
-        "u_pointShadowPcfSamples"
-    ];
-    if (!requiredUniforms.every((uniform) => shader.reflection.uniforms.has(uniform))) {
+/**
+ * #1140: generated-program environment map (`indirect_default` chunk). The
+ * legacy binder above only fills the frozen library's `u_environmentMapTexture*`
+ * names, so a generated program's sampler used to stay unbound (sampling
+ * whatever its texture unit held). Binds whichever sampler the program
+ * declares: `u_environmentCubeMap` (ENVMAP_TYPE_CUBE_UV — the prefiltered
+ * cube, honouring the per-item probe cube) or `u_environmentMap`
+ * (ENVMAP_TYPE_EQUIRECT — the 2D map), plus the shared intensity / rotation /
+ * mip range / encoding uniforms.
+ */
+export function applyGeneratedEnvironmentMapUniforms(environment, item, shader, uniforms, flags) {
+    const cube = shader.reflection.uniforms.has("u_environmentCubeMap");
+    if (!cube && !shader.reflection.uniforms.has("u_environmentMap"))
         return;
-    }
-    if (!pointShadowMap) {
-        uniforms.set("u_pointShadowMapTexture", new TextureBinding({ name: "u_pointShadowMapTexture", required: false }));
-        uniforms.set("u_pointShadowMapEnabled", 0);
-        uniforms.set("u_pointShadowLightPosition", [0, 0, 0]);
-        uniforms.set("u_pointShadowRange", 1);
-        uniforms.set("u_pointShadowFaceMatrices", new Float32Array(6 * 16));
-        uniforms.set("u_pointShadowFaceRects", new Float32Array(6 * 4));
-        uniforms.set("u_pointShadowStrength", 0);
-        uniforms.set("u_pointShadowBias", 0);
-        uniforms.set("u_pointShadowSlopeBias", 0);
-        uniforms.set("u_pointShadowTexelSize", [1, 1]);
-        uniforms.set("u_pointShadowPcfSampleCount", 1);
-        uniforms.set("u_pointShadowPcfSamples", new Float32Array(MAX_FORWARD_SHADOW_PCF_SAMPLES * 4));
+    const env = environment ? withItemEnvironmentCube(environment, item) : undefined;
+    const binding = cube ? env?.environmentCubeMapTexture : env?.environmentMapTexture;
+    if (!env || !binding?.texture) {
+        // forwardPassFeatureAxes never selects a sampler whose texture is absent;
+        // a stale program draws with no environment contribution, never garbage.
+        uniforms.set("u_environmentMapIntensity", 0);
         return;
     }
-    const validation = pointShadowMap.texture.validate();
-    if (!validation.ok) {
-        throw new RenderDeviceError("Forward point-shadow atlas texture binding validation failed", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            diagnostics: validation.diagnostics
-        });
-    }
-    if (pointShadowMap.lightPosition.length !== 3 || !isFiniteArrayLike(pointShadowMap.lightPosition)) {
-        throw new RenderDeviceError("Forward point-shadow lightPosition must contain three finite values", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            lightPosition: pointShadowMap.lightPosition
-        });
-    }
-    if (!Number.isFinite(pointShadowMap.range) || pointShadowMap.range <= 0) {
-        throw new RenderDeviceError("Forward point-shadow range must be finite and positive", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            range: pointShadowMap.range
-        });
-    }
-    const faceMatrices = toFloat32Array(pointShadowMap.faceMatrices, 6 * 16, "pointShadowMap.faceMatrices", item.label);
-    const faceRects = toFloat32Array(pointShadowMap.faceRects, 6 * 4, "pointShadowMap.faceRects", item.label);
-    validatePointShadowFaceRects(faceRects, item.label);
-    const strength = pointShadowMap.strength ?? 0.65;
-    const bias = pointShadowMap.bias ?? 0.001;
-    const slopeBias = pointShadowMap.slopeBias ?? 1;
-    const texelSize = pointShadowMap.texelSize ?? [
-        1 / Math.max(1, pointShadowMap.texture.texture?.width ?? 1),
-        1 / Math.max(1, pointShadowMap.texture.texture?.height ?? 1)
-    ];
-    if (!Number.isFinite(strength) || strength < 0 || strength > 1) {
-        throw new RenderDeviceError("Forward point-shadow strength must be finite in [0, 1]", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            strength
-        });
-    }
-    if (!Number.isFinite(bias) || bias < 0) {
-        throw new RenderDeviceError("Forward point-shadow bias must be finite and non-negative", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            bias
-        });
-    }
-    if (!Number.isFinite(slopeBias) || slopeBias < 0) {
-        throw new RenderDeviceError("Forward point-shadow slopeBias must be finite and non-negative", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
+    const dimension = cube ? "cube" : "2d";
+    validateEnvironmentTextureBinding(cube ? "Environment cube map texture" : "Environment map texture", binding, dimension, item);
+    // E3 stage-2b (step 3): under the conjunction the stage-2a knob is the
+    // only IBL intensity source — an absent field means zero, never the
+    // legacy absent-field default of 1. Conjunction-off keeps `?? 1`.
+    const intensity = flags !== undefined && qrE3CompilerLightingOn(flags)
+        ? env.environmentMapIntensity ?? 0
+        : env.environmentMapIntensity ?? 1;
+    const rotation = env.environmentMapRotation ?? 0;
+    const mipCount = env.environmentMapMipCount ?? 1;
+    const encoding = env.environmentMapEncoding ?? "srgb";
+    if (!Number.isFinite(intensity) || intensity < 0 || !Number.isFinite(rotation) || !Number.isInteger(mipCount) || mipCount < 1) {
+        throw new RenderDeviceError("Sampled environment map options are invalid", "ENVIRONMENT_LIGHTING_CONTRACT", {
             label: item.label,
-            slopeBias
-        });
-    }
-    if (texelSize.length !== 2 || !texelSize.every((value) => Number.isFinite(value) && value > 0)) {
-        throw new RenderDeviceError("Forward point-shadow texelSize must contain two finite positive values", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            texelSize: Array.from(texelSize)
+            intensity,
+            rotation,
+            mipCount
         });
     }
-    const filterKernel = pointShadowMap.filterKernel ?? DEFAULT_FORWARD_SHADOW_FILTER_KERNEL;
-    uniforms.set("u_pointShadowMapTexture", pointShadowMap.texture);
-    uniforms.set("u_pointShadowMapEnabled", 1);
-    uniforms.set("u_pointShadowLightPosition", pointShadowMap.lightPosition);
-    uniforms.set("u_pointShadowRange", pointShadowMap.range);
-    uniforms.set("u_pointShadowFaceMatrices", faceMatrices);
-    uniforms.set("u_pointShadowFaceRects", faceRects);
-    uniforms.set("u_pointShadowStrength", strength);
-    uniforms.set("u_pointShadowBias", bias);
-    uniforms.set("u_pointShadowSlopeBias", slopeBias);
-    uniforms.set("u_pointShadowTexelSize", texelSize);
-    uniforms.set("u_pointShadowPcfSampleCount", filterKernel.samples.length);
-    uniforms.set("u_pointShadowPcfSamples", packForwardShadowPcfSamples(filterKernel, item.label));
-}
-export function applyForwardSpotShadowMapUniforms(spotShadowMap, item, shader, uniforms) {
-    const requiredUniforms = [
-        "u_spotShadowMapTexture",
-        "u_spotShadowMapEnabled",
-        "u_spotShadowLightPosition",
-        "u_spotShadowLightDirection",
-        "u_spotShadowMatrix",
-        "u_spotShadowCone",
-        "u_spotShadowRange",
-        "u_spotShadowStrength",
-        "u_spotShadowBias",
-        "u_spotShadowSlopeBias",
-        "u_spotShadowTexelSize",
-        "u_spotShadowPcfSampleCount",
-        "u_spotShadowPcfSamples"
-    ];
-    if (!requiredUniforms.every((uniform) => shader.reflection.uniforms.has(uniform))) {
+    const name = cube ? "u_environmentCubeMap" : "u_environmentMap";
+    uniforms.set(name, new TextureBinding({
+        name,
+        texture: binding.texture,
+        sampler: binding.sampler,
+        required: true,
+        ready: binding.ready,
+        expectedColorSpace: binding.expectedColorSpace,
+        expectedDimension: dimension
+    }));
+    uniforms.set("u_environmentMapIntensity", intensity);
+    uniforms.set("u_environmentMapRotation", rotation);
+    uniforms.set("u_environmentMapMaxLod", Math.max(mipCount - 1, 0));
+    uniforms.set("u_environmentMapEncoding", encoding === "rgbe" ? 1 : encoding === "linear" ? 2 : 0);
+}
+/**
+ * Generated-program procedural environment (`indirect_default` LIGHT_HEMISPHERE
+ * block). Same validation as the frozen binder below, under the generator's
+ * own `u_a3dProcedural*` names; a program compiled for a procedural map whose
+ * environment no longer has one draws with zero procedural contribution.
+ */
+export function applyGeneratedProceduralEnvironmentUniforms(environment, item, shader, uniforms, suppressProcedural = false) {
+    if (!shader.reflection.uniforms.has("u_a3dProceduralIntensity"))
         return;
-    }
-    if (!spotShadowMap) {
-        uniforms.set("u_spotShadowMapTexture", new TextureBinding({ name: "u_spotShadowMapTexture", required: false }));
-        uniforms.set("u_spotShadowMapEnabled", 0);
-        uniforms.set("u_spotShadowLightPosition", [0, 0, 0]);
-        uniforms.set("u_spotShadowLightDirection", [0, -1, 0]);
-        uniforms.set("u_spotShadowMatrix", new Float32Array(identityMatrix()));
-        uniforms.set("u_spotShadowCone", [Math.PI / 4, 0]);
-        uniforms.set("u_spotShadowRange", 1);
-        uniforms.set("u_spotShadowStrength", 0);
-        uniforms.set("u_spotShadowBias", 0);
-        uniforms.set("u_spotShadowSlopeBias", 0);
-        uniforms.set("u_spotShadowTexelSize", [1, 1]);
-        uniforms.set("u_spotShadowPcfSampleCount", 1);
-        uniforms.set("u_spotShadowPcfSamples", new Float32Array(MAX_FORWARD_SHADOW_PCF_SAMPLES * 4));
+    // E3 stage-2b: a PRD-02-IBL draw takes no procedural term at all (the
+    // stage-2a knob already zeroed it in the bundle; bare-path bundles are
+    // zeroed here so the sampled/probe term can never double-count).
+    if (suppressProcedural) {
+        uniforms.set("u_a3dProceduralIntensity", 0);
+        uniforms.set("u_a3dProceduralSpecularIntensity", 0);
         return;
     }
-    const validation = spotShadowMap.texture.validate();
-    if (!validation.ok) {
-        throw new RenderDeviceError("Forward spot-shadow texture binding validation failed", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            diagnostics: validation.diagnostics
-        });
-    }
-    if (spotShadowMap.lightPosition.length !== 3 || !isFiniteArrayLike(spotShadowMap.lightPosition)) {
-        throw new RenderDeviceError("Forward spot-shadow lightPosition must contain three finite values", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            lightPosition: spotShadowMap.lightPosition
-        });
-    }
-    if (spotShadowMap.lightDirection.length !== 3 || !isFiniteArrayLike(spotShadowMap.lightDirection)) {
-        throw new RenderDeviceError("Forward spot-shadow lightDirection must contain three finite values", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            lightDirection: spotShadowMap.lightDirection
-        });
-    }
-    if (!Number.isFinite(spotShadowMap.angle) || spotShadowMap.angle <= 0 || spotShadowMap.angle >= Math.PI / 2) {
-        throw new RenderDeviceError("Forward spot-shadow angle must be within (0, PI / 2)", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            angle: spotShadowMap.angle
-        });
-    }
-    if (spotShadowMap.penumbra !== undefined && (!Number.isFinite(spotShadowMap.penumbra) || spotShadowMap.penumbra < 0 || spotShadowMap.penumbra > 1)) {
-        throw new RenderDeviceError("Forward spot-shadow penumbra must be in [0, 1]", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            penumbra: spotShadowMap.penumbra
-        });
-    }
-    if (!Number.isFinite(spotShadowMap.range) || spotShadowMap.range <= 0) {
-        throw new RenderDeviceError("Forward spot-shadow range must be finite and positive", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            range: spotShadowMap.range
-        });
-    }
-    const shadowMatrix = toFloat32Array(spotShadowMap.shadowMatrix, 16, "spotShadowMap.shadowMatrix", item.label);
-    const strength = spotShadowMap.strength ?? 0.65;
-    const bias = spotShadowMap.bias ?? 0.001;
-    const slopeBias = spotShadowMap.slopeBias ?? 1;
-    const texelSize = spotShadowMap.texelSize ?? [
-        1 / Math.max(1, spotShadowMap.texture.texture?.width ?? 1),
-        1 / Math.max(1, spotShadowMap.texture.texture?.height ?? 1)
-    ];
-    if (!Number.isFinite(strength) || strength < 0 || strength > 1) {
-        throw new RenderDeviceError("Forward spot-shadow strength must be finite in [0, 1]", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            strength
-        });
-    }
-    if (!Number.isFinite(bias) || bias < 0) {
-        throw new RenderDeviceError("Forward spot-shadow bias must be finite and non-negative", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            bias
-        });
-    }
-    if (!Number.isFinite(slopeBias) || slopeBias < 0) {
-        throw new RenderDeviceError("Forward spot-shadow slopeBias must be finite and non-negative", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
-            label: item.label,
-            slopeBias
-        });
+    const proceduralMap = environment?.proceduralMap;
+    if (!proceduralMap) {
+        uniforms.set("u_a3dProceduralIntensity", 0);
+        uniforms.set("u_a3dProceduralSpecularIntensity", 0);
+        return;
     }
-    if (texelSize.length !== 2 || !texelSize.every((value) => Number.isFinite(value) && value > 0)) {
-        throw new RenderDeviceError("Forward spot-shadow texelSize must contain two finite positive values", "FORWARD_SPOT_SHADOW_MAP_CONTRACT", {
+    if (!Number.isFinite(proceduralMap.intensity) || proceduralMap.intensity < 0
+        || !Number.isFinite(proceduralMap.specularIntensity) || proceduralMap.specularIntensity < 0) {
+        throw new RenderDeviceError("Procedural environment map intensities must be finite and non-negative", "ENVIRONMENT_LIGHTING_CONTRACT", {
             label: item.label,
-            texelSize: Array.from(texelSize)
-        });
-    }
-    const filterKernel = spotShadowMap.filterKernel ?? DEFAULT_FORWARD_SHADOW_FILTER_KERNEL;
-    uniforms.set("u_spotShadowMapTexture", spotShadowMap.texture);
-    uniforms.set("u_spotShadowMapEnabled", 1);
-    uniforms.set("u_spotShadowLightPosition", spotShadowMap.lightPosition);
-    uniforms.set("u_spotShadowLightDirection", spotShadowMap.lightDirection);
-    uniforms.set("u_spotShadowMatrix", shadowMatrix);
-    uniforms.set("u_spotShadowCone", [spotShadowMap.angle, spotShadowMap.penumbra ?? 0]);
-    uniforms.set("u_spotShadowRange", spotShadowMap.range);
-    uniforms.set("u_spotShadowStrength", strength);
-    uniforms.set("u_spotShadowBias", bias);
-    uniforms.set("u_spotShadowSlopeBias", slopeBias);
-    uniforms.set("u_spotShadowTexelSize", texelSize);
-    uniforms.set("u_spotShadowPcfSampleCount", filterKernel.samples.length);
-    uniforms.set("u_spotShadowPcfSamples", packForwardShadowPcfSamples(filterKernel, item.label));
-}
-function toFloat32Array(values, expectedLength, name, label) {
-    const source = values instanceof Float32Array ? values : new Float32Array(values);
-    if (source.length !== expectedLength || !isFiniteArrayLike(source)) {
-        throw new RenderDeviceError(`${name} must contain ${expectedLength} finite values`, "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-            label,
-            length: source.length,
-            expectedLength
+            intensity: proceduralMap.intensity,
+            specularIntensity: proceduralMap.specularIntensity
         });
     }
-    return source;
+    uniforms.set("u_a3dProceduralSkyColor", toEnvironmentColor(proceduralMap.skyColor, "proceduralMap.skyColor", item.label));
+    uniforms.set("u_a3dProceduralHorizonColor", toEnvironmentColor(proceduralMap.horizonColor, "proceduralMap.horizonColor", item.label));
+    uniforms.set("u_a3dProceduralGroundColor", toEnvironmentColor(proceduralMap.groundColor, "proceduralMap.groundColor", item.label));
+    uniforms.set("u_a3dProceduralSpecularColor", toEnvironmentColor(proceduralMap.specularColor, "proceduralMap.specularColor", item.label));
+    uniforms.set("u_a3dProceduralIntensity", proceduralMap.intensity);
+    uniforms.set("u_a3dProceduralSpecularIntensity", proceduralMap.specularIntensity);
 }
-function validatePointShadowFaceRects(faceRects, label) {
-    for (let offset = 0; offset < faceRects.length; offset += 4) {
-        const rect = [faceRects[offset], faceRects[offset + 1], faceRects[offset + 2], faceRects[offset + 3]];
-        if (!rect.every((value) => Number.isFinite(value) && value >= 0 && value <= 1) || rect[2] <= 0 || rect[3] <= 0) {
-            throw new RenderDeviceError("Forward point-shadow face rects must be normalized atlas rectangles", "FORWARD_POINT_SHADOW_MAP_CONTRACT", {
-                label,
-                face: offset / 4,
-                rect
-            });
-        }
-    }
+/**
+ * E3 stage-2b: `prd02.ibl` can only shade when a real SH-bearing C-09
+ * probe exists (27-float `sh9`, the probe contract length). A cube-only
+ * source — a scene `environmentCubeMapTexture` or a per-item
+ * `environmentCube` with no SH — must NOT select the replacement body:
+ * the pack would bind zeroed SH and diffuse IBL would vanish, where the
+ * default indirect body samples that cube for diffuse. Such draws keep
+ * the default body (which already honours the selected cube via
+ * `withItemEnvironmentCube`). A per-item cube still wins for specular
+ * when a scene SH probe exists (see the pack below); `_item` is kept in
+ * the signature so the draw path and the Renderer warmup share one gate
+ * and their program keys agree on the feature bit.
+ */
+export function prd02IblEnvironmentAvailable(environment, _item) {
+    return environment?.environmentProbe?.sh9?.length === 27;
 }
-function packForwardShadowPcfSamples(filterKernel, label) {
-    if (filterKernel.samples.length < 1 || filterKernel.samples.length > MAX_FORWARD_SHADOW_PCF_SAMPLES) {
-        throw new RenderDeviceError("Forward shadow-map PCF kernel must contain 1 to 32 samples", "FORWARD_SHADOW_MAP_CONTRACT", {
-            label,
-            samples: filterKernel.samples.length
-        });
-    }
-    const packed = new Float32Array(MAX_FORWARD_SHADOW_PCF_SAMPLES * 4);
-    let weightSum = 0;
-    for (const [index, sample] of filterKernel.samples.entries()) {
-        if (![sample.x, sample.y, sample.weight].every(Number.isFinite) || sample.weight < 0) {
-            throw new RenderDeviceError("Forward shadow-map PCF samples must contain finite offsets and non-negative weights", "FORWARD_SHADOW_MAP_CONTRACT", {
-                label,
-                sample
-            });
+/**
+ * E3 stage-2b bind site for the PRD-02 IBL chunk: packs
+ * `packA3DEnvironmentUniforms` (previously zero production callers) from the
+ * pass environment and writes it into the draw's uniform packet.
+ *
+ * Single intensity source (step 3): diffuse/specular intensities are the
+ * stage-2a knob (`environmentMapIntensity` /
+ * `environmentMapSpecularIntensity`, authored-equal under the conjunction;
+ * an absent field is 0, never a legacy default), multiplied ONCE by the
+ * per-material `envMapIntensity` (`u_materialEnvironmentIntensity`, kept as
+ * a multiplier pending the owner decision). No preset scalar stack is read
+ * here. Ambient rides `color`/`intensity` (under the probe path these are
+ * the authored-ambient term, additive outside IBL per F-02-01); hemisphere
+ * is not passed — the probe SH already carries sky/ground, and the
+ * procedural map is suppressed on this path.
+ *
+ * Frozen-family scoping (step 1): this bind runs only for generated draws
+ * that selected `prd02.ibl`. The frozen shader family (ShaderLibraryCore
+ * lean PBR + ShaderLibrary duplicates) serves fallback-only draws
+ * (unskinnable skinned items, compile failure, binding failure); since
+ * step 4 those draws get bind-level suppression of their stacked terms in
+ * `applyEnvironmentLightingUniforms` under the conjunction, while
+ * conjunction-off every draw stays byte-identical.
+ */
+export function applyPrd02EnvironmentUniforms(environment, item, material, uniforms) {
+    const env = environment ? withItemEnvironmentCube(environment, item) : undefined;
+    const cubeTexture = env?.environmentCubeMapTexture?.texture ?? undefined;
+    const sceneProbe = env?.environmentProbe ?? null;
+    // A selected per-item cube (`withItemEnvironmentCube` already folded it
+    // into `env.environmentCubeMapTexture`, e.g. from
+    // `applyProbeEnvironmentCubes`) wins for specular; diffuse SH still
+    // comes from the scene probe — the item cube carries no SH of its own.
+    const selectedCubeMips = cubeTexture?.cubeFaces[0]?.mipLevels.length;
+    const probe = sceneProbe && cubeTexture && cubeTexture.dimension === "cube" && cubeTexture !== sceneProbe.specularCube
+        ? {
+            specularCube: cubeTexture,
+            mipCount: item.environmentCubeMip
+                ?? (selectedCubeMips !== undefined && selectedCubeMips > 0
+                    ? selectedCubeMips
+                    : env?.environmentMapMipCount ?? sceneProbe.mipCount),
+            sh9: sceneProbe.sh9
         }
-        const offset = index * 4;
-        packed[offset] = sample.x;
-        packed[offset + 1] = sample.y;
-        packed[offset + 2] = sample.weight;
-        weightSum += sample.weight;
-    }
-    if (weightSum <= 0) {
-        throw new RenderDeviceError("Forward shadow-map PCF sample weights must sum to a positive value", "FORWARD_SHADOW_MAP_CONTRACT", {
-            label,
-            weightSum
-        });
-    }
-    return packed;
-}
-function applyEnvironmentLightingUniforms(environment, item, shader, uniforms) {
-    if (!environment) {
-        clearProceduralEnvironmentMapUniforms(shader, uniforms);
-        clearSampledEnvironmentMapUniforms(shader, uniforms);
-        clearEnvironmentBrdfLutUniforms(shader, uniforms);
-        return;
-    }
-    if (!shader.reflection.uniforms.has("u_environmentColor") || !shader.reflection.uniforms.has("u_environmentIntensity")) {
-        return;
-    }
-    const color = environment.color;
-    if (color.length !== 3 || !isFiniteColor(color)) {
-        throw new RenderDeviceError("Environment lighting color must contain three finite values in [0, 1]", "ENVIRONMENT_LIGHTING_CONTRACT", {
-            label: item.label,
-            color
-        });
-    }
-    if (!Number.isFinite(environment.intensity) || environment.intensity < 0) {
-        throw new RenderDeviceError("Environment lighting intensity must be finite and non-negative", "ENVIRONMENT_LIGHTING_CONTRACT", {
+        : sceneProbe
+            ?? (cubeTexture
+                ? {
+                    specularCube: cubeTexture,
+                    mipCount: env?.environmentMapMipCount ?? Math.max(1, cubeTexture.cubeFaces[0]?.mipLevels.length ?? 1),
+                    sh9: new Float32Array(0)
+                }
+                : null);
+    const knobDiffuse = env?.environmentMapIntensity ?? 0;
+    const knobSpecular = env?.environmentMapSpecularIntensity ?? knobDiffuse;
+    // Effective (instance-overridden) multiplier, resolved the way the
+    // generated binding resolved it: `MaterialBinding.bindGenerated` fills
+    // this packet from `materialLike.getParameters()`, and
+    // `MaterialInstance.getParameter` is override-first. Prefer the value
+    // already bound into the packet; fall back to asking the material
+    // itself (never the stripped base material) for direct callers.
+    const boundMultiplier = uniforms.get("u_materialEnvironmentIntensity");
+    const materialMultiplierRaw = typeof boundMultiplier === "number"
+        ? boundMultiplier
+        : material.getParameter?.("u_materialEnvironmentIntensity");
+    const materialMultiplier = typeof materialMultiplierRaw === "number" && Number.isFinite(materialMultiplierRaw) && materialMultiplierRaw >= 0
+        ? materialMultiplierRaw
+        : 1;
+    if (!Number.isFinite(knobDiffuse) || knobDiffuse < 0 || !Number.isFinite(knobSpecular) || knobSpecular < 0) {
+        throw new RenderDeviceError("PRD-02 IBL knob intensities must be finite and non-negative", "ENVIRONMENT_LIGHTING_CONTRACT", {
             label: item.label,
-            intensity: environment.intensity
-        });
-    }
-    uniforms.set("u_environmentColor", color);
-    uniforms.set("u_environmentIntensity", environment.intensity);
-    applyProceduralEnvironmentMapUniforms(environment.proceduralMap, item, shader, uniforms);
-    applySampledEnvironmentMapUniforms(environment, item, shader, uniforms);
-}
-function applyProceduralEnvironmentMapUniforms(proceduralMap, item, shader, uniforms) {
+            knobDiffuse,
+            knobSpecular
+        });
+    }
+    const packed = packA3DEnvironmentUniforms({
+        probe,
+        ...(env ? { ambient: { color: env.color, intensity: env.intensity } } : {}),
+        // EnvironmentLightingOptions rotation is in turns (indirect_default);
+        // the PRD-02 chunk's u_envRotation is radians.
+        rotation: (env?.environmentMapRotation ?? 0) * Math.PI * 2,
+        diffuseIntensity: knobDiffuse * materialMultiplier,
+        specularIntensity: knobSpecular * materialMultiplier
+    });
+    for (const [name, value] of packed.uniforms)
+        uniforms.set(name, value);
+    // The chunk declares `u_envDfgLut` (its own split-sum entry, unused by the
+    // stage-2b call body, which routes through the r185 multiscatter helpers);
+    // bind the renderer DFG LUT so the sampler never reads a stale unit.
+    uniforms.set("u_envDfgLut", new TextureBinding({
+        name: "u_envDfgLut",
+        texture: dfgLutTexture(),
+        sampler: dfgLutBinding().sampler,
+        expectedColorSpace: "linear"
+    }));
+}
+function applyProceduralEnvironmentMapUniforms(proceduralMap, item, shader, uniforms, generatedE3Conjunction = false) {
     if (!proceduralMap) {
         clearProceduralEnvironmentMapUniforms(shader, uniforms);
         return;
@@ -1061,7 +1276,15 @@ function applyProceduralEnvironmentMapUniforms(proceduralMap, item, shader, unif
     uniforms.set("u_environmentHorizonColor", horizonColor);
     uniforms.set("u_environmentGroundColor", groundColor);
     uniforms.set("u_environmentSpecularColor", specularColor);
-    uniforms.set("u_environmentMapIntensity", proceduralMap.intensity);
+    // E3 stage-2b (step 3): `u_environmentMapIntensity` is the generated
+    // program's SAMPLED-map (knob) uniform; the frozen namespace reuses the
+    // same name for its procedural diffuse. On a generated conjunction draw
+    // the procedural write is dropped so the knob owns the name outright.
+    // Frozen draws keep this legacy write here; step 4 zeroes it afterwards
+    // in applyEnvironmentLightingUniforms on frozen conjunction draws.
+    if (!generatedE3Conjunction) {
+        uniforms.set("u_environmentMapIntensity", proceduralMap.intensity);
+    }
     uniforms.set("u_environmentSpecularIntensity", proceduralMap.specularIntensity);
 }
 function clearProceduralEnvironmentMapUniforms(shader, uniforms) {
@@ -1072,7 +1295,21 @@ function clearProceduralEnvironmentMapUniforms(shader, uniforms) {
         uniforms.set("u_environmentSpecularIntensity", 0);
     }
 }
-function applySampledEnvironmentMapUniforms(environment, item, shader, uniforms) {
+/**
+ * PRD-02 S12 (lane-01 half): a RenderItem's `environmentCube` (a captured
+ * reflection probe) replaces the scene environment's cube for that draw only.
+ * Items without one get `environment` back unchanged (same object).
+ */
+function withItemEnvironmentCube(environment, item) {
+    if (!item.environmentCube)
+        return environment;
+    return {
+        ...environment,
+        environmentCubeMapTexture: item.environmentCube,
+        ...(item.environmentCubeMip !== undefined ? { environmentMapMipCount: item.environmentCubeMip } : {})
+    };
+}
+function applySampledEnvironmentMapUniforms(environment, item, shader, uniforms, frozenE3Conjunction = false) {
     const environmentMapTexture = environment.environmentMapTexture;
     const environmentCubeMapTexture = environment.environmentCubeMapTexture;
     if (!environmentMapTexture && !environmentCubeMapTexture) {
@@ -1097,8 +1334,11 @@ function applySampledEnvironmentMapUniforms(environment, item, shader, uniforms)
     if (environmentCubeMapTexture) {
         validateEnvironmentTextureBinding("Environment cube map texture", environmentCubeMapTexture, "cube", item);
     }
-    const intensity = environment.environmentMapIntensity ?? 1;
-    const specularIntensity = environment.environmentMapSpecularIntensity ?? 0.5;
+    // E3 step 4: on a frozen conjunction draw an absent sampled intensity
+    // is zero (single-knob rule, step-3 parity with the generated binder),
+    // never the legacy absent-field defaults of 1 / 0.5.
+    const intensity = frozenE3Conjunction ? environment.environmentMapIntensity ?? 0 : environment.environmentMapIntensity ?? 1;
+    const specularIntensity = frozenE3Conjunction ? environment.environmentMapSpecularIntensity ?? 0 : environment.environmentMapSpecularIntensity ?? 0.5;
     const rotation = environment.environmentMapRotation ?? 0;
     const mipCount = environment.environmentMapMipCount ?? 1;
     const encoding = environment.environmentMapEncoding ?? "srgb";
@@ -1263,13 +1503,16 @@ function applyTransformUniforms(item, shader, uniforms) {
     if (modelMatrix && shader.reflection.uniforms.has("u_modelMatrix")) {
         uniforms.set("u_modelMatrix", modelMatrix);
     }
+    if (shader.reflection.uniforms.has("u_geometryMatrix")) {
+        uniforms.set("u_geometryMatrix", toMat4Uniform(item.geometryMatrix ?? identityMatrix(), "geometryMatrix", item.label));
+    }
     if (shader.reflection.uniforms.has("u_normalMatrix")) {
         uniforms.set("u_normalMatrix", item.normalMatrix
             ? toMat4Uniform(item.normalMatrix, "normalMatrix", item.label)
             : new Float32Array(normalMatrixFromModel(toMat4Values(modelMatrix ?? identityMatrix(), "modelMatrix", item.label))));
     }
 }
-function toMat4Uniform(value, field, label) {
+export function toMat4Uniform(value, field, label) {
     if (value.length !== 16 || !isFiniteArrayLike(value)) {
         throw new RenderDeviceError("Render item transform uniforms must be finite mat4 values", "RENDER_ITEM_TRANSFORM_CONTRACT", {
             label,
@@ -1289,7 +1532,7 @@ function toMat4Values(value, field, label) {
     }
     return mat4FromArrayLike(value, 0);
 }
-function identityMatrix() {
+export function identityMatrix() {
     return [
         1, 0, 0, 0,
         0, 1, 0, 0,
@@ -1301,18 +1544,56 @@ function getBaseMaterial(material) {
     return material instanceof MaterialInstance ? material.baseMaterial : material;
 }
 function sortForwardRenderItems(items, cameraPosition) {
-    return sortRenderQueueItems(items.map((item) => ({
-        item,
-        bucket: isTransparentRenderItem(item) ? "transparent" : isTransmissionRenderItem(item) ? "transmission" : "opaque",
-        depth: cameraPosition ? distanceSquaredFromCamera(item, cameraPosition) : 0,
-        pipelineKey: renderItemPipelineKey(item),
-        batchKey: renderItemPipelineKey(item),
-        instanceCount: item.instanceTransforms ? instanceTransformCount(item) : 1
-    }))).items;
+    return sortRenderQueueItems(items.map((item) => {
+        const queue = blendQueueForState(getBaseMaterial(item.material ?? new UnlitMaterial()).renderState);
+        return {
+            item,
+            bucket: queue !== "opaque" ? "transparent" : isTransmissionRenderItem(item) ? "transmission" : "opaque",
+            depth: cameraPosition ? distanceSquaredFromCamera(item, cameraPosition) : 0,
+            pipelineKey: renderItemPipelineKey(item),
+            batchKey: renderItemPipelineKey(item),
+            blendRank: queue === "transparent-unordered" ? 1 : 0,
+            instanceCount: item.instanceTransforms ? instanceTransformCount(item) : 1
+        };
+    })).items;
 }
 function isTransparentRenderItem(item) {
     const material = item.material ?? new UnlitMaterial();
-    return getBaseMaterial(material).renderState.blend;
+    return blendStateIsTransparent(getBaseMaterial(material).renderState);
+}
+/** Bucket one item the same way `sortForwardRenderItems` does. */
+export function forwardItemBucket(item) {
+    const material = item.material ?? new UnlitMaterial();
+    const queue = blendQueueForState(getBaseMaterial(material).renderState);
+    if (queue !== "opaque")
+        return "transparent";
+    return isTransmissionRenderItem(item) ? "transmission" : "opaque";
+}
+/**
+ * §9.1 split: `opaque` feeds the opaque phase, `transmission` the transmissive
+ * draw after contributor `transmission` passes, and `transparent` the
+ * interleaved transparent phase (each item carries its view-space distance as
+ * `sortDepth`, larger = farther, matching `TransparentQueueItem` semantics).
+ */
+export function splitForwardItems(items, cameraPosition) {
+    const opaque = [];
+    const transmission = [];
+    const transparent = [];
+    for (const item of items) {
+        const bucket = forwardItemBucket(item);
+        if (bucket === "opaque") {
+            opaque.push(item);
+        }
+        else if (bucket === "transmission") {
+            transmission.push(item);
+        }
+        else {
+            transparent.push({ item, sortDepth: cameraPosition ? Math.sqrt(distanceSquaredFromCamera(item, cameraPosition)) : 0 });
+        }
+    }
+    // Transparents are drawn back-to-front (farther first), matching the queue sort.
+    transparent.sort((a, b) => b.sortDepth - a.sortDepth);
+    return { opaque, transmission, transparent };
 }
 function materialNumericParameter(material, name, fallback) {
     const value = material.getParameter(name);
@@ -1342,7 +1623,10 @@ function renderItemPipelineKey(item) {
     const material = item.material ?? new UnlitMaterial();
     const baseMaterial = getBaseMaterial(material);
     const state = baseMaterial.renderState;
-    return `${baseMaterial.name}|${state.depthTest ? "dt" : "ndt"}|${state.depthWrite ? "dw" : "ndw"}|${state.cullMode}|${state.blend ? "blend" : "opaque"}`;
+    const blendToken = state.blendMode === undefined
+        ? (state.blend ? "blend" : "opaque")
+        : typeof state.blendMode === "string" ? state.blendMode : `custom:${renderStateKey(state)}`;
+    return `${baseMaterial.name}|${state.depthTest ? "dt" : "ndt"}|${state.depthWrite ? "dw" : "ndw"}|${state.cullMode}|${blendToken}`;
 }
 function instanceTransformCount(item) {
     return validateInstanceTransformSource(item).length / 16;
@@ -1408,9 +1692,9 @@ function applyInstanceBinding(device, item, shader, uniforms) {
         ...(extraBindings.buffers.length > 0 ? { buffers: extraBindings.buffers } : {})
     };
 }
-function createExtraInstanceAttributeBindings(device, item, instanceCount) {
+function createExtraInstanceAttributeBindings(device, item, instanceCount, includeColors = true) {
     const descriptors = [];
-    if (item.instanceColors) {
+    if (item.instanceColors && includeColors) {
         descriptors.push({
             shaderName: "a_instanceColor",
             components: 4,
@@ -1463,317 +1747,12 @@ function validateInstanceAttributeDescriptor(descriptor, instanceCount, label) {
         });
     }
 }
-function resolveRenderGeometry(item) {
-    if (item.morphTargets === undefined && item.morphWeights === undefined) {
-        return item.geometry;
-    }
-    if (!item.morphTargets || !item.morphWeights) {
-        throw new RenderDeviceError("Morph render items require both morphTargets and morphWeights", "MORPH_TARGET_CONTRACT", {
-            label: item.label,
-            targetCount: item.morphTargets?.length ?? 0,
-            weightCount: item.morphWeights?.length ?? 0
-        });
-    }
-    return applyMorphTargets(item.geometry, item.morphTargets, item.morphWeights);
-}
-function applyGpuMorphUniforms(item, shader, uniforms) {
-    if (!shader.reflection.uniforms.has("u_morphPositionDeltas") ||
-        !shader.reflection.uniforms.has("u_morphWeights") ||
-        !shader.reflection.uniforms.has("u_morphTargetCount")) {
-        return false;
-    }
-    if (!item.morphTargets || !item.morphWeights) {
-        throw new RenderDeviceError("Morph render items require both morphTargets and morphWeights", "MORPH_TARGET_CONTRACT", {
-            label: item.label,
-            targetCount: item.morphTargets?.length ?? 0,
-            weightCount: item.morphWeights?.length ?? 0
-        });
-    }
-    if (item.morphTargets.length !== item.morphWeights.length) {
-        throw new RenderDeviceError("Morph target count must match morph weight count", "MORPH_TARGET_CONTRACT", {
-            label: item.label,
-            targetCount: item.morphTargets.length,
-            weightCount: item.morphWeights.length
-        });
-    }
-    // Counts beyond the uniform fast-path capacity are not an error: fall back to the CPU morph
-    // (resolveRenderGeometry -> applyMorphTargets), which is unlimited and morphs normals + tangents
-    // so lighting follows the deformation. The texture-backed GPU plan (createMorphTargetPlan) packs
-    // the same data for the texture path; see MorphTargetPlan.ts.
-    if (item.morphTargets.length > MAX_GPU_MORPH_TARGETS || item.geometry.vertexBuffer.vertexCount > MAX_GPU_MORPH_VERTICES) {
-        return false;
-    }
-    const packed = new Float32Array(MAX_GPU_MORPH_TARGETS * MAX_GPU_MORPH_VERTICES * 4);
-    const packedNormals = new Float32Array(MAX_GPU_MORPH_TARGETS * MAX_GPU_MORPH_VERTICES * 4);
-    const weights = new Float32Array(MAX_GPU_MORPH_TARGETS);
-    for (let targetIndex = 0; targetIndex < item.morphTargets.length; targetIndex += 1) {
-        const target = item.morphTargets[targetIndex];
-        if (!target.positions || target.positions.length < item.geometry.vertexBuffer.vertexCount) {
-            throw new RenderDeviceError("GPU morph shader path requires position deltas for every source vertex", "GPU_MORPH_TARGET_CONTRACT", {
-                label: item.label,
-                targetIndex,
-                vertexCount: item.geometry.vertexBuffer.vertexCount,
-                deltaCount: target.positions?.length ?? 0
-            });
-        }
-        const weight = item.morphWeights[targetIndex] ?? 0;
-        if (!Number.isFinite(weight)) {
-            throw new RenderDeviceError("GPU morph weights must be finite", "GPU_MORPH_TARGET_CONTRACT", {
-                label: item.label,
-                targetIndex,
-                weight
-            });
-        }
-        weights[targetIndex] = weight;
-        for (let vertex = 0; vertex < item.geometry.vertexBuffer.vertexCount; vertex += 1) {
-            const delta = target.positions[vertex];
-            if (delta.length !== 3 || !Number.isFinite(delta[0]) || !Number.isFinite(delta[1]) || !Number.isFinite(delta[2])) {
-                throw new RenderDeviceError("GPU morph position deltas must be finite vec3 values", "GPU_MORPH_TARGET_CONTRACT", {
-                    label: item.label,
-                    targetIndex,
-                    vertex
-                });
-            }
-            const offset = (targetIndex * MAX_GPU_MORPH_VERTICES + vertex) * 4;
-            packed[offset] = delta[0];
-            packed[offset + 1] = delta[1];
-            packed[offset + 2] = delta[2];
-            const normal = target.normals?.[vertex];
-            if (normal && normal.length === 3) {
-                packedNormals[offset] = normal[0];
-                packedNormals[offset + 1] = normal[1];
-                packedNormals[offset + 2] = normal[2];
-            }
-        }
-    }
-    uniforms.set("u_morphPositionDeltas", packed);
-    uniforms.set("u_morphWeights", weights);
-    uniforms.set("u_morphTargetCount", item.morphTargets.length);
-    // Normal deltas are uploaded only when the bound shader declares the uniform (lit morph variants);
-    // the default unlit morph shader ignores them.
-    if (shader.reflection.uniforms.has("u_morphNormalDeltas")) {
-        uniforms.set("u_morphNormalDeltas", packedNormals);
-    }
-    return true;
-}
-function applySkinningUniforms(skinning, material, shader, uniforms) {
-    if (!shader.reflection.uniforms.has("u_jointMatrices") || !shader.reflection.uniforms.has("u_jointCount")) {
-        throw new RenderDeviceError("Skinned render item requires a shader with joint palette uniforms", "SKINNING_SHADER_CONTRACT", {
-            material: material.name
-        });
-    }
-    if (!Number.isInteger(skinning.jointCount) || skinning.jointCount <= 0 || skinning.jointCount > MAX_SKINNING_JOINTS) {
-        throw new RenderDeviceError(`Skinning jointCount must be an integer in [1, ${MAX_SKINNING_JOINTS}]`, "INVALID_SKINNING_PALETTE", {
-            jointCount: skinning.jointCount,
-            maxUniformJoints: MAX_UNIFORM_SKINNING_JOINTS,
-            maxJoints: MAX_SKINNING_JOINTS
-        });
-    }
-    if (skinning.matrices.length !== skinning.jointCount * 16) {
-        throw new RenderDeviceError("Skinning matrix palette length must equal jointCount * 16", "INVALID_SKINNING_PALETTE", {
-            jointCount: skinning.jointCount,
-            matrixScalars: skinning.matrices.length
-        });
-    }
-    if (!isFiniteArrayLike(skinning.matrices)) {
-        throw new RenderDeviceError("Skinning matrix palette must contain finite values", "INVALID_SKINNING_PALETTE", {
-            jointCount: skinning.jointCount
-        });
-    }
-    uniforms.set("u_jointCount", skinning.jointCount);
-    // Over the uniform-array limit the palette travels as an RGBA32F data texture, four
-    // texels per matrix. A mat4 uniform costs four vec4 slots, so a uniform array cannot
-    // be grown far enough for large rigs without exhausting MAX_VERTEX_UNIFORM_VECTORS.
-    const path = skinning.jointCount > MAX_UNIFORM_SKINNING_JOINTS ? "data-texture" : "uniform-array";
-    if (path === "data-texture") {
-        if (!shader.reflection.uniforms.has("u_jointPaletteTexture") || !shader.reflection.uniforms.has("u_jointPaletteMode")) {
-            throw new RenderDeviceError(`Skinning palettes above ${MAX_UNIFORM_SKINNING_JOINTS} joints require a shader with data-texture palette uniforms`, "SKINNING_SHADER_CONTRACT", { material: material.name, jointCount: skinning.jointCount });
-        }
-        const texture = createSkinningPaletteTexture(skinning, material.name);
-        uniforms.set("u_jointPaletteMode", 1);
-        uniforms.set("u_jointPaletteTexture", new TextureBinding({
-            name: "u_jointPaletteTexture",
-            texture,
-            sampler: new Sampler({ minFilter: "nearest", magFilter: "nearest", addressU: "clamp-to-edge", addressV: "clamp-to-edge" }),
-            required: true
-        }));
-        uniforms.set("u_jointPaletteTextureSize", [texture.width, texture.height]);
-        // The uniform array is still declared by the shader, so give it a valid value.
-        uniforms.set("u_jointMatrices", new Float32Array(MAX_UNIFORM_SKINNING_JOINTS * 16));
-        return path;
-    }
-    if (shader.reflection.uniforms.has("u_jointPaletteMode")) {
-        uniforms.set("u_jointPaletteMode", 0);
-        if (shader.reflection.uniforms.has("u_jointPaletteTextureSize"))
-            uniforms.set("u_jointPaletteTextureSize", [1, 1]);
-        if (shader.reflection.uniforms.has("u_jointPaletteTexture")) {
-            uniforms.set("u_jointPaletteTexture", new TextureBinding({ name: "u_jointPaletteTexture", required: false }));
-        }
-    }
-    uniforms.set("u_jointMatrices", skinning.matrices);
-    return path;
-}
 /**
  * Packs a joint palette into an RGBA32F texture, one texel per matrix column.
  *
  * Width is a multiple of four so no matrix straddles a row boundary, which keeps the
  * shader's texel addressing a simple divide and avoids per-column row recomputation.
  */
-function createSkinningPaletteTexture(skinning, materialName) {
-    const texelsPerMatrix = 4;
-    const totalTexels = skinning.jointCount * texelsPerMatrix;
-    const width = Math.min(SKINNING_PALETTE_TEXTURE_MAX_WIDTH, Math.max(texelsPerMatrix, ceilToMultiple(Math.ceil(Math.sqrt(totalTexels)), texelsPerMatrix)));
-    const height = Math.ceil(totalTexels / width);
-    const data = new Float32Array(width * height * 4);
-    data.set(skinning.matrices.subarray(0, Math.min(skinning.matrices.length, data.length)));
-    if (skinning.matrices.length > data.length) {
-        throw new RenderDeviceError("Skinning palette does not fit the data texture", "INVALID_SKINNING_PALETTE", {
-            material: materialName,
-            jointCount: skinning.jointCount
-        });
-    }
-    return new Texture({
-        width,
-        height,
-        format: "rgba32f",
-        colorSpace: "linear",
-        label: `aura3d-skinning-palette-${skinning.jointCount}-joints`,
-        data
-    });
-}
-function ceilToMultiple(value, multiple) {
-    return Math.ceil(value / multiple) * multiple;
-}
-function validateSkinningGeometryContract(item, skinning) {
-    const format = item.geometry.vertexBuffer.format;
-    if (!format.hasAttribute("joints") || !format.hasAttribute("weights")) {
-        throw new RenderDeviceError("Skinned render item geometry must include joints and weights attributes", "SKINNING_GEOMETRY_CONTRACT", {
-            label: item.label,
-            jointCount: skinning.jointCount,
-            vertexFormat: format.attributes.map((attribute) => attribute.shaderName),
-            missingAttributes: [
-                ...(format.hasAttribute("joints") ? [] : ["a_joints"]),
-                ...(format.hasAttribute("weights") ? [] : ["a_weights"])
-            ]
-        });
-    }
-    const jointsAttribute = format.getAttribute("joints");
-    const weightsAttribute = format.getAttribute("weights");
-    if (jointsAttribute.components !== 4 || weightsAttribute.components !== 4) {
-        throw new RenderDeviceError("Skinned render item geometry must use four joint and four weight influences per vertex", "SKINNING_GEOMETRY_CONTRACT", {
-            label: item.label,
-            jointCount: skinning.jointCount,
-            jointComponents: jointsAttribute.components,
-            weightComponents: weightsAttribute.components
-        });
-    }
-    // Eight-influence geometry must supply both halves of the second set, and both must
-    // be vec4. A half-declared second set would silently drop influences at draw time.
-    const hasJoints1 = format.hasAttribute("joints1");
-    const hasWeights1 = format.hasAttribute("weights1");
-    if (hasJoints1 !== hasWeights1) {
-        throw new RenderDeviceError("Eight-influence skinned geometry must declare both joints1 and weights1", "SKINNING_GEOMETRY_CONTRACT", {
-            label: item.label,
-            hasJoints1,
-            hasWeights1
-        });
-    }
-    const eightInfluence = hasJoints1 && hasWeights1;
-    if (eightInfluence) {
-        const joints1Attribute = format.getAttribute("joints1");
-        const weights1Attribute = format.getAttribute("weights1");
-        if (joints1Attribute.components !== 4 || weights1Attribute.components !== 4) {
-            throw new RenderDeviceError("Eight-influence skinned geometry must use four components per second-set attribute", "SKINNING_GEOMETRY_CONTRACT", {
-                label: item.label,
-                joints1Components: joints1Attribute.components,
-                weights1Components: weights1Attribute.components
-            });
-        }
-    }
-    for (let vertex = 0; vertex < item.geometry.vertexBuffer.vertexCount; vertex += 1) {
-        const joints = item.geometry.vertexBuffer.getAttribute(vertex, "joints");
-        const weights = item.geometry.vertexBuffer.getAttribute(vertex, "weights");
-        let weightSum = 0;
-        if (eightInfluence) {
-            // Validate the second set with the same rules, and fold it into the weight sum so
-            // a vertex whose influence is split across both sets is not reported as unweighted.
-            const joints1 = item.geometry.vertexBuffer.getAttribute(vertex, "joints1");
-            const weights1 = item.geometry.vertexBuffer.getAttribute(vertex, "weights1");
-            for (let influence = 0; influence < 4; influence += 1) {
-                const joint = joints1[influence] ?? 0;
-                const weight = weights1[influence] ?? 0;
-                if (!Number.isFinite(weight) || weight < 0) {
-                    throw new RenderDeviceError("Skinned render item weights must be finite non-negative values", "SKINNING_GEOMETRY_CONTRACT", {
-                        label: item.label,
-                        jointCount: skinning.jointCount,
-                        vertex,
-                        influence: influence + 4,
-                        weight
-                    });
-                }
-                if (!Number.isInteger(joint) || joint < 0 || joint >= skinning.jointCount) {
-                    throw new RenderDeviceError("Skinned render item joint indices must reference palette joints", "SKINNING_GEOMETRY_CONTRACT", {
-                        label: item.label,
-                        jointCount: skinning.jointCount,
-                        vertex,
-                        influence: influence + 4,
-                        joint
-                    });
-                }
-                weightSum += weight;
-            }
-        }
-        for (let influence = 0; influence < 4; influence += 1) {
-            const joint = joints[influence] ?? 0;
-            const weight = weights[influence] ?? 0;
-            if (!Number.isFinite(weight) || weight < 0) {
-                throw new RenderDeviceError("Skinned render item weights must be finite non-negative values", "SKINNING_GEOMETRY_CONTRACT", {
-                    label: item.label,
-                    jointCount: skinning.jointCount,
-                    vertex,
-                    influence,
-                    weight
-                });
-            }
-            if (!Number.isFinite(joint) || !Number.isInteger(joint) || joint < 0) {
-                throw new RenderDeviceError("Skinned render item joints must be finite non-negative integer indices", "SKINNING_GEOMETRY_CONTRACT", {
-                    label: item.label,
-                    jointCount: skinning.jointCount,
-                    vertex,
-                    influence,
-                    joint
-                });
-            }
-            if (weight > 0 && joint >= skinning.jointCount) {
-                throw new RenderDeviceError("Skinned render item joint indices must be within the uploaded skinning palette", "SKINNING_GEOMETRY_CONTRACT", {
-                    label: item.label,
-                    jointCount: skinning.jointCount,
-                    vertex,
-                    influence,
-                    joint,
-                    weight
-                });
-            }
-            weightSum += weight;
-        }
-        if (weightSum <= 0) {
-            throw new RenderDeviceError("Skinned render item weights must sum to a positive value", "SKINNING_GEOMETRY_CONTRACT", {
-                label: item.label,
-                jointCount: skinning.jointCount,
-                vertex,
-                weightSum
-            });
-        }
-        if (Math.abs(weightSum - 1) > 0.02) {
-            throw new RenderDeviceError("Skinned render item weights must be normalized before GPU skinning", "SKINNING_GEOMETRY_CONTRACT", {
-                label: item.label,
-                jointCount: skinning.jointCount,
-                vertex,
-                weightSum
-            });
-        }
-    }
-}
 function validateInstanceTransformSource(item) {
     const source = item.instanceTransforms ?? [];
     if (source.length === 0 || source.length % 16 !== 0) {
@@ -1789,7 +1768,7 @@ function validateInstanceTransformSource(item) {
     }
     return source;
 }
-function isFiniteArrayLike(values) {
+export function isFiniteArrayLike(values) {
     for (let index = 0; index < values.length; index += 1) {
         if (!Number.isFinite(values[index]))
             return false;