@aura3d/rendering 2.0.4 → 3.0.1

package/dist/WebGPUDevice.js

@@ -1,5 +1,9 @@
-import { RenderDeviceError, viewBytes } from "./RenderDevice.js";
+import { WEBGPU_EXTENSION_ATLAS_WGSL, webgpuExtensionAtlasUniforms } from "./WebGPUExtensionAtlas.js";
+import { RenderDeviceError, viewBytes, resolveGpuTargetOwner, spreadGpuTargetInventory } from "./RenderDevice.js";
 import { MAX_WEBGPU_SKINNING_JOINTS } from "./WebGPUSkinningLimits.js";
+import { normalizeWebGPUTemporalOptions, WEBGPU_TAA_FRAGMENT, WEBGPU_TAA_OUTPUT_FRAGMENT } from "./webgpu/WebGPUTemporal.js";
+import { defaultWebGPUBloomWeights, normalizeWebGPUColorGradeOptions, normalizeWebGPUBloomOptions, webgpuBlurFragment, webgpuBloomCompositeFragment, webgpuBrightExtractFragment, webgpuColorGradeFragment, webgpuFxaaFragment, WEBGPU_POST_VERTEX_WGSL } from "./webgpu/WebGPUPostShaders.js";
+import { DEFAULT_DEPTH_SHADER_MARKER } from "./ShaderLibraryCore.js";
 import { reflectShaderSources } from "./ShaderReflection.js";
 import { Texture, bytesPerPixel, isCompressedTextureFormat } from "./Texture.js";
 import { isTextureBinding, TextureBinding } from "./TextureBinding.js";
@@ -22,6 +26,26 @@ const TEXTURE_USAGE = {
     TEXTURE_BINDING: 0x0004
 };
 const DEPTH_TEXTURE_FORMAT = "depth24plus";
+const WEBGPU_NATIVE_COPY_FRAGMENT = `
+@group(0) @binding(0) var<uniform> params: vec4<f32>;
+@group(0) @binding(1) var linearSampler: sampler;
+@group(0) @binding(2) var source: texture_2d<f32>;
+@fragment fn fs_copy(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+ return textureSample(source, linearSampler, clamp(uv, params.xy * 0.5, vec2<f32>(1.0) - params.xy * 0.5));
+}`;
+const WEBGPU_NATIVE_TONE_FRAGMENT = `
+@group(0) @binding(0) var<uniform> params: vec4<f32>;
+@group(0) @binding(1) var linearSampler: sampler;
+@group(0) @binding(2) var source: texture_2d<f32>;
+@fragment fn fs_tone(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+ let sample = textureSample(source, linearSampler, uv);
+ var c = max(sample.rgb * params.x / params.w, vec3<f32>(0.0));
+ if (params.y > 2.5) { let toe=max(c-vec3<f32>(0.004),vec3<f32>(0.0)); c=min((toe*(6.2*toe+vec3<f32>(0.5)))/(toe*(6.2*toe+vec3<f32>(1.7))+vec3<f32>(0.06)),c*1.08); }
+ else if (params.y > 1.5) { c = clamp((c * (2.51 * c + vec3<f32>(0.03))) / (c * (2.43 * c + vec3<f32>(0.59)) + vec3<f32>(0.14)), vec3<f32>(0.0), vec3<f32>(1.0)); }
+ else if (params.y > 0.5) { c = c / (vec3<f32>(1.0) + c); }
+ if (params.z > 0.5) { c = select(1.055 * pow(c, vec3<f32>(1.0 / 2.4)) - vec3<f32>(0.055), c * 12.92, c <= vec3<f32>(0.0031308)); }
+ return vec4<f32>(c, sample.a);
+}`;
 class WebGPURenderBuffer {
     id;
     usage;
@@ -56,9 +80,13 @@ class WebGPUShaderProgram {
     entryPoints;
     nativeUniformLayout;
     portableBindings;
+    nativeColorDefaultVertex;
+    nativeAtlasVertex;
     disposed = false;
     renderPipelines = new Map();
-    constructor(id, label, marker, reflection, modules, entryPoints, nativeUniformLayout, portableBindings) {
+    nativeColorDefaultModule;
+    atlasVertexModules = new Map();
+    constructor(id, label, marker, reflection, modules, entryPoints, nativeUniformLayout, portableBindings, nativeColorDefaultVertex, nativeAtlasVertex) {
         this.id = id;
         this.label = label;
         this.marker = marker;
@@ -67,6 +95,8 @@ class WebGPUShaderProgram {
         this.entryPoints = entryPoints;
         this.nativeUniformLayout = nativeUniformLayout;
         this.portableBindings = portableBindings;
+        this.nativeColorDefaultVertex = nativeColorDefaultVertex;
+        this.nativeAtlasVertex = nativeAtlasVertex;
     }
     dispose() {
         this.disposed = true;
@@ -157,6 +187,24 @@ export class WebGPUDevice {
     nativeMorphSubmissions = 0;
     nativeEnvironmentBindings = 0;
     nativeShadowMapBindings = 0;
+    nativeBloomPasses = 0;
+    nativeColorGradePasses = 0;
+    nativeFxaaPasses = 0;
+    nativeTaaPasses = 0;
+    nativeTemporalBindings = 0;
+    webgpuPostPipelines = new Map();
+    webgpuPostLinearSampler = null;
+    lastWebGPUBloom = null;
+    /**
+     * Uniform buffers referenced by submitted-but-maybe-unexecuted post
+     * passes. Destroying them synchronously after submit races the GPU (the
+     * reads happen later), so they retire here and are reclaimed at the start
+     * of the next post run — after any intervening readback fence — or on
+     * dispose.
+     */
+    webgpuPostRetiredUniformBuffers = [];
+    webgpuPostErrorScopePending = [];
+    webgpuPostErrors = [];
     canvasSubmissions = 0;
     buffers = new Set();
     shaders = new Set();
@@ -294,7 +342,7 @@ export class WebGPUDevice {
                 this.device.createShaderModule({ label: `${sources.label}-fragment`, code: nativeSources.fragment })
             ]
             : [];
-        const shader = new WebGPUShaderProgram(this.nextId++, sources.label, sources.marker, reflectShaderSources(sources), modules, nativeSources.entryPoints, nativeSources.uniformLayout, nativeSources.portableBindings ?? []);
+        const shader = new WebGPUShaderProgram(this.nextId++, sources.label, sources.marker, reflectShaderSources(sources), modules, nativeSources.entryPoints, nativeSources.uniformLayout, nativeSources.portableBindings ?? [], nativeSources.colorDefaultVertex, nativeSources.atlasVertex);
         this.shaders.add(shader);
         return shader;
     }
@@ -769,6 +817,13 @@ export class WebGPUDevice {
         this.rasterizeDraw(command, vertexBuffer);
         this.drawCalls += 1;
     }
+    async waitForSubmittedWork() {
+        this.assertAlive();
+        if (!this.device.queue.onSubmittedWorkDone) {
+            throw new RenderDeviceError("Native GPU queue completion is unavailable", "GPU_COMPLETION_UNAVAILABLE");
+        }
+        await this.device.queue.onSubmittedWorkDone();
+    }
     endFrame() {
         this.assertFrame();
         this.frameActive = false;
@@ -800,6 +855,11 @@ export class WebGPUDevice {
             ["nativeMorphSubmissions", this.nativeMorphSubmissions],
             ["nativeEnvironmentBindings", this.nativeEnvironmentBindings],
             ["nativeShadowMapBindings", this.nativeShadowMapBindings],
+            ["nativeBloomPasses", this.nativeBloomPasses],
+            ["nativeColorGradePasses", this.nativeColorGradePasses],
+            ["nativeFxaaPasses", this.nativeFxaaPasses],
+            ["nativeTaaPasses", this.nativeTaaPasses],
+            ["nativeTemporalBindings", this.nativeTemporalBindings],
             ["canvasSubmissions", this.canvasSubmissions]
         ]);
     }
@@ -825,6 +885,12 @@ export class WebGPUDevice {
             disposedShaders: [...this.shaders].filter((shader) => shader.disposed).length,
             disposedRenderTargets: [...this.renderTargets].filter((target) => target.disposed).length,
             disposedTextures: [...this.renderTargets].reduce((total, target) => total + (target.colorTexture.disposed ? 1 : 0) + (target.depthTexture?.disposed ? 1 : 0), 0),
+            ...spreadGpuTargetInventory(liveRenderTargets.map((target) => ({
+                label: target.label,
+                kind: "render-target",
+                bytes: target.colorTexture.byteLength + (target.depthTexture?.byteLength ?? 0),
+                owner: resolveGpuTargetOwner(target.label)
+            }))),
             nativeSubmissions: this.nativeSubmissions,
             nativeRenderPipelinesCreated: this.nativeRenderPipelinesCreated,
             nativeRenderPasses: this.nativeRenderPasses,
@@ -840,13 +906,407 @@ export class WebGPUDevice {
             nativeMorphSubmissions: this.nativeMorphSubmissions,
             nativeEnvironmentBindings: this.nativeEnvironmentBindings,
             nativeShadowMapBindings: this.nativeShadowMapBindings,
+            nativeBloomPasses: this.nativeBloomPasses,
+            nativeColorGradePasses: this.nativeColorGradePasses,
+            nativeFxaaPasses: this.nativeFxaaPasses,
             lastError: this.lastError,
             contextLost: this.contextLost
         };
     }
+    /**
+     * muse3jsparity-PRD J2 — native WebGPU bloom pyramid.
+     *
+     * Renders bright-extract -> separable-blur mip pyramid -> composite over
+     * the source, all as real WGSL fullscreen passes on this device. Returns a
+     * fresh rgba16f target owned by the caller (dispose it); every intermediate
+     * is disposed before return. Throws fail-closed when the native device
+     * cannot run fullscreen passes.
+     */
+    executeWebGPUBloom(source, options = {}) {
+        this.reclaimWebGPUPostUniformBuffers();
+        const normalized = normalizeWebGPUBloomOptions(options);
+        const src = this.requireRenderTarget(source);
+        const srcView = src.nativeView;
+        if (!srcView) {
+            throw new RenderDeviceError("WebGPU bloom source target has no native view", "NATIVE_POST_UNSUPPORTED", { label: src.label });
+        }
+        const width = src.width;
+        const height = src.height;
+        // Preserve HDR source energy even at performance quality. Bloom adds to
+        // scene radiance before tone mapping, so its composite is always floating point.
+        const halfFloat = normalized.halfFloat || src.colorTexture.format === "rgba16f" || src.colorTexture.format === "rgba32f";
+        const mipFormat = halfFloat ? "rgba16f" : "rgba8";
+        const owned = [];
+        const track = (target) => {
+            owned.push(target);
+            return target;
+        };
+        try {
+            const bright = track(this.createRenderTarget({ width, height, format: mipFormat, label: "a3d-webgpu-bloom-bright" }));
+            this.runWebGPUFullscreenPass({
+                label: "webgpu-bloom-bright",
+                fragment: webgpuBrightExtractFragment(),
+                entryPoint: "fs_bright",
+                uniforms: new Float32Array([normalized.threshold, normalized.knee, normalized.strength, 0]),
+                views: [srcView],
+                target: bright
+            });
+            const mips = [];
+            let level = bright;
+            let levelWidth = width;
+            let levelHeight = height;
+            for (let mip = 0; mip < normalized.mipCount; mip += 1) {
+                levelWidth = Math.max(1, levelWidth >> 1);
+                levelHeight = Math.max(1, levelHeight >> 1);
+                const scratch = track(this.createRenderTarget({ width: levelWidth, height: levelHeight, format: mipFormat, label: `a3d-webgpu-bloom-mip${mip}-scratch` }));
+                const mipTarget = track(this.createRenderTarget({ width: levelWidth, height: levelHeight, format: mipFormat, label: `a3d-webgpu-bloom-mip${mip}` }));
+                const levelView = this.requireRenderTarget(level).nativeView;
+                const scratchView = this.requireRenderTarget(scratch).nativeView;
+                if (!levelView || !scratchView) {
+                    throw new RenderDeviceError("WebGPU bloom pyramid target has no native view", "NATIVE_POST_UNSUPPORTED", { mip });
+                }
+                this.runWebGPUFullscreenPass({
+                    label: `webgpu-bloom-mip${mip}-h`,
+                    fragment: webgpuBlurFragment(),
+                    entryPoint: "fs_blur",
+                    uniforms: new Float32Array([1, 0, 1 / levelWidth, 1 / levelHeight]),
+                    views: [levelView],
+                    target: scratch
+                });
+                this.runWebGPUFullscreenPass({
+                    label: `webgpu-bloom-mip${mip}-v`,
+                    fragment: webgpuBlurFragment(),
+                    entryPoint: "fs_blur",
+                    uniforms: new Float32Array([0, 1, 1 / levelWidth, 1 / levelHeight]),
+                    views: [scratchView],
+                    target: mipTarget
+                });
+                mips.push(mipTarget);
+                level = mipTarget;
+            }
+            const weights = defaultWebGPUBloomWeights(normalized.mipCount);
+            const composite = track(this.createRenderTarget({ width, height, format: "rgba16f", label: "a3d-webgpu-bloom-composite" }));
+            const mipViews = mips.map((mipTarget) => {
+                const view = this.requireRenderTarget(mipTarget).nativeView;
+                if (!view)
+                    throw new RenderDeviceError("WebGPU bloom mip has no native view", "NATIVE_POST_UNSUPPORTED", {});
+                return view;
+            });
+            this.runWebGPUFullscreenPass({
+                label: "webgpu-bloom-composite",
+                fragment: webgpuBloomCompositeFragment({ weights, strength: normalized.strength }),
+                entryPoint: "fs_composite",
+                uniforms: new Float32Array([normalized.strength, 0, 0, 0]),
+                views: [srcView, ...mipViews],
+                target: composite
+            });
+            const bytesPerPixel = halfFloat ? 8 : 4;
+            const targetBytes = width * height * bytesPerPixel
+                + mips.reduce((total, mipTarget) => total + mipTarget.width * mipTarget.height * bytesPerPixel * 2, 0)
+                + width * height * 8;
+            this.lastWebGPUBloom = {
+                mipCount: normalized.mipCount,
+                halfFloat,
+                targetBytes,
+                compositeGain: normalized.strength,
+                passes: 1 + normalized.mipCount * 2 + 1,
+                executionMode: "webgpu-native-post"
+            };
+            this.nativeBloomPasses += this.lastWebGPUBloom.passes;
+            for (const target of owned) {
+                if (target !== composite)
+                    target.dispose();
+            }
+            return composite;
+        }
+        catch (error) {
+            for (const target of owned)
+                target.dispose();
+            throw error;
+        }
+    }
+    /** Last native bloom run on this device (null before the first run). */
+    getWebGPUBloomDiagnostics() {
+        return this.lastWebGPUBloom;
+    }
+    /**
+     * Drains GPU validation errors observed by the native post passes.
+     * Empty means every submitted post pass validated clean.
+     */
+    async drainWebGPUPostErrors() {
+        const pending = this.webgpuPostErrorScopePending;
+        this.webgpuPostErrorScopePending = [];
+        await Promise.all(pending);
+        const errors = [...this.webgpuPostErrors];
+        this.webgpuPostErrors = [];
+        return errors;
+    }
+    /**
+     * muse3jsparity-PRD J2 — native WebGPU color grade.
+     * Exposure (stops) -> saturation around luma -> contrast around middle
+     * gray, one WGSL fullscreen pass into a fresh caller-owned rgba8 target.
+     */
+    executeWebGPUColorGrade(source, options = {}) {
+        this.reclaimWebGPUPostUniformBuffers();
+        const normalized = normalizeWebGPUColorGradeOptions(options);
+        const src = this.requireRenderTarget(source);
+        const srcView = src.nativeView;
+        if (!srcView) {
+            throw new RenderDeviceError("WebGPU color-grade source target has no native view", "NATIVE_POST_UNSUPPORTED", { label: src.label });
+        }
+        const out = this.createRenderTarget({ width: src.width, height: src.height, format: "rgba8", label: "a3d-webgpu-color-grade" });
+        try {
+            this.runWebGPUFullscreenPass({
+                label: "webgpu-color-grade",
+                fragment: webgpuColorGradeFragment(),
+                entryPoint: "fs_grade",
+                uniforms: new Float32Array([normalized.exposure, normalized.contrast, normalized.saturation, 0]),
+                views: [srcView],
+                target: out
+            });
+            this.nativeColorGradePasses += 1;
+            return out;
+        }
+        catch (error) {
+            out.dispose();
+            throw error;
+        }
+    }
+    /**
+     * muse3jsparity-PRD J2 — native WebGPU FXAA.
+     * Compact FXAA 3.11 console core (luma neighborhood, one perpendicular
+     * blend tap pair; flat neighborhoods pass through untouched). Temporal
+     * antialiasing has a separate GPU history contract in executeWebGPUTaa.
+     */
+    executeWebGPUFxaa(source) {
+        this.reclaimWebGPUPostUniformBuffers();
+        const src = this.requireRenderTarget(source);
+        const srcView = src.nativeView;
+        if (!srcView) {
+            throw new RenderDeviceError("WebGPU FXAA source target has no native view", "NATIVE_POST_UNSUPPORTED", { label: src.label });
+        }
+        const out = this.createRenderTarget({ width: src.width, height: src.height, format: "rgba8", label: "a3d-webgpu-fxaa" });
+        try {
+            this.runWebGPUFullscreenPass({
+                label: "webgpu-fxaa",
+                fragment: webgpuFxaaFragment(),
+                entryPoint: "fs_fxaa",
+                uniforms: new Float32Array([1 / src.width, 1 / src.height, 0, 0]),
+                views: [srcView],
+                target: out
+            });
+            this.nativeFxaaPasses += 1;
+            return out;
+        }
+        catch (error) {
+            out.dispose();
+            throw error;
+        }
+    }
+    /** Native target-to-target chain. Unsupported passes fail before any submission. */
+    presentLdrPostprocess(source, options) {
+        this.assertAlive();
+        const supported = new Set(["bloom", "tone-mapping", "color-grade", "fxaa", "taa"]);
+        for (const pass of options.passes) {
+            if (!supported.has(pass.name))
+                throw new RenderDeviceError(`Native WebGPU postprocess does not support ${pass.name}`, "WEBGPU_POSTPROCESS_UNSUPPORTED", { pass: pass.name });
+        }
+        const owned = [];
+        let current = source;
+        const track = (target) => { owned.push(target); current = target; };
+        try {
+            for (const pass of options.passes) {
+                if (pass.name === "bloom")
+                    track(this.executeWebGPUBloom(current, pass.options));
+                else if (pass.name === "color-grade")
+                    track(this.executeWebGPUColorGrade(current, pass.options));
+                else if (pass.name === "fxaa")
+                    track(this.executeWebGPUFxaa(current));
+                else if (pass.name === "taa") {
+                    const temporal = pass.options.temporal;
+                    if (!temporal)
+                        throw new RenderDeviceError("Native WebGPU TAA requires GPU temporal bindings", "TEMPORAL_NATIVE_REQUIRED");
+                    track(this.executeWebGPUTaa(current, { ...temporal, ...(typeof pass.options.blend === "number" ? { blend: pass.options.blend } : {}) }));
+                }
+                else if (pass.name === "tone-mapping") {
+                    const tone = { ...options.toneMappingDefaults, ...pass.options };
+                    const operator = tone.operator ?? "reinhard";
+                    const operatorId = operator === "linear" || operator === "none" ? 0 : operator === "reinhard" ? 1 : operator === "aces" || operator === "aces-filmic" ? 2 : operator === "filmic" ? 3 : -1;
+                    if (operatorId < 0)
+                        throw new RenderDeviceError(`Unsupported native WebGPU tone operator ${String(operator)}`, "WEBGPU_POSTPROCESS_UNSUPPORTED");
+                    const exposure = typeof tone.exposure === "number" ? tone.exposure : 1;
+                    const whitePoint = typeof tone.whitePoint === "number" ? tone.whitePoint : 1;
+                    if (!Number.isFinite(whitePoint) || whitePoint <= 0)
+                        throw new RenderDeviceError("Invalid tone white point", "WEBGPU_POSTPROCESS_UNSUPPORTED");
+                    if (!Number.isFinite(exposure) || exposure < 0)
+                        throw new RenderDeviceError("Invalid tone exposure", "WEBGPU_POSTPROCESS_UNSUPPORTED");
+                    const target = this.createRenderTarget({ width: source.width, height: source.height, format: "rgba8", label: "a3d-webgpu-tone" });
+                    owned.push(target);
+                    this.runWebGPUFullscreenPass({ label: "webgpu-tone", fragment: WEBGPU_NATIVE_TONE_FRAGMENT, entryPoint: "fs_tone",
+                        uniforms: new Float32Array([exposure, operatorId, tone.outputColorSpace === "srgb" ? 1 : 0, whitePoint]),
+                        views: [this.requireRenderTarget(current).nativeView], target });
+                    current = target;
+                }
+            }
+            const target = options.outputTarget ?? null;
+            if (target === current)
+                throw new RenderDeviceError("Native WebGPU presentation source/output alias", "INVALID_RESOURCE");
+            this.runWebGPUFullscreenPass({ label: "webgpu-post-present", fragment: WEBGPU_NATIVE_COPY_FRAGMENT, entryPoint: "fs_copy",
+                uniforms: new Float32Array([1 / source.width, 1 / source.height, 0, 0]),
+                views: [this.requireRenderTarget(current).nativeView], target });
+            if (!target) {
+                this.activeRenderTarget = null;
+                this.canvasSubmissions += 1;
+            }
+        }
+        finally {
+            for (const target of owned)
+                target.dispose();
+        }
+    }
+    /** Resolve GPU velocity/history into caller-owned historyOutput, returning scene-alpha color. */
+    executeWebGPUTaa(source, options) {
+        this.assertAlive();
+        const [blend, depthThreshold] = normalizeWebGPUTemporalOptions(options);
+        const targets = [source, options.velocity, options.history, options.historyOutput];
+        if (new Set(targets).size !== targets.length)
+            throw new RenderDeviceError("TAA targets must not alias", "NATIVE_POST_UNSUPPORTED");
+        const native = targets.map((target) => this.requireRenderTarget(target));
+        if (native.some((target) => target.width !== source.width || target.height !== source.height || !target.nativeView)) {
+            throw new RenderDeviceError("TAA requires same-size native source, velocity and history targets", "NATIVE_POST_UNSUPPORTED");
+        }
+        if (targets.slice(1).some((target) => target.colorTexture.format !== "rgba16f")) {
+            throw new RenderDeviceError("TAA velocity/history targets require rgba16f", "NATIVE_POST_UNSUPPORTED");
+        }
+        const out = this.createRenderTarget({ width: source.width, height: source.height, format: "rgba16f", label: "a3d-webgpu-taa-color" });
+        try {
+            this.runWebGPUFullscreenPass({ label: "webgpu-taa", fragment: WEBGPU_TAA_FRAGMENT, entryPoint: "fs_taa",
+                uniforms: new Float32Array([1 / source.width, 1 / source.height, blend, options.historyValid ? 1 : 0, depthThreshold, 0, 0, 0]),
+                views: native.slice(0, 3).map((target) => target.nativeView), target: options.historyOutput });
+            this.runWebGPUFullscreenPass({ label: "webgpu-taa-output", fragment: WEBGPU_TAA_OUTPUT_FRAGMENT, entryPoint: "fs_taa_output",
+                uniforms: new Float32Array([1 / source.width, 1 / source.height, 0, 0]),
+                views: [native[3].nativeView, native[0].nativeView], target: out });
+            this.nativeTaaPasses += 2;
+            this.nativeTemporalBindings += 3;
+            return out;
+        }
+        catch (error) {
+            out.dispose();
+            throw error;
+        }
+    }
+    runWebGPUFullscreenPass(args) {
+        // No assertFrame here on purpose: these are target-to-target passes with
+        // their own encoders, so they run both inside a Renderer frame (scene ->
+        // post chaining) and after it closed (proof harnesses that render, then
+        // post, then read back).
+        this.assertAlive();
+        const target = args.target ? this.requireRenderTarget(args.target) : null;
+        const targetView = target ? target.nativeView : this.canvasContext?.getCurrentTexture().createView();
+        if (!targetView) {
+            throw new RenderDeviceError("WebGPU post target has no native view", "NATIVE_POST_UNSUPPORTED", { label: target?.label ?? "canvas" });
+        }
+        if (!this.device.createShaderModule || !this.device.createRenderPipeline || !this.device.createCommandEncoder
+            || !this.device.createSampler || !this.device.createBuffer || !this.device.createBindGroup) {
+            throw new RenderDeviceError("WebGPU fullscreen post requires shader/pipeline/sampler/buffer natives", "NATIVE_POST_UNSUPPORTED", { label: args.label });
+        }
+        const scopeDevice = this.device;
+        const scopedErrors = Boolean(scopeDevice.pushErrorScope && scopeDevice.popErrorScope);
+        if (scopedErrors) {
+            // Bracket everything below (module/pipeline/bind-group creation plus
+            // the submit) so per-pass validation failures land here labeled.
+            scopeDevice.pushErrorScope?.("validation");
+        }
+        const format = target ? webgpuTextureFormat(target.colorTexture.format) : this.presentationFormat;
+        // Bloom quality changes the fragment binding layout (one texture per mip).
+        // A label/format-only key can reuse the wrong native pipeline after a quality change.
+        const cacheKey = `${args.label}:${args.entryPoint}:${format}:${args.fragment}`;
+        let pipeline = this.webgpuPostPipelines.get(cacheKey);
+        if (!pipeline) {
+            const vertexModule = this.device.createShaderModule({ label: `${args.label}-vs`, code: WEBGPU_POST_VERTEX_WGSL });
+            const fragmentModule = this.device.createShaderModule({ label: `${args.label}-fs`, code: args.fragment });
+            pipeline = this.device.createRenderPipeline({
+                label: `${args.label}-pipeline`,
+                layout: "auto",
+                vertex: { module: vertexModule, entryPoint: "vs_post" },
+                fragment: { module: fragmentModule, entryPoint: args.entryPoint, targets: [{ format }] },
+                primitive: { topology: "triangle-list" }
+            });
+            this.nativeRenderPipelinesCreated += 1;
+            this.webgpuPostPipelines.set(cacheKey, pipeline);
+        }
+        if (!this.webgpuPostLinearSampler) {
+            this.webgpuPostLinearSampler = this.device.createSampler({
+                minFilter: "linear",
+                magFilter: "linear",
+                addressModeU: "clamp-to-edge",
+                addressModeV: "clamp-to-edge"
+            });
+        }
+        const uniformBuffer = this.device.createBuffer({
+            label: `${args.label}-uniforms`,
+            size: args.uniforms.byteLength,
+            usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST
+        });
+        let submitted = false;
+        try {
+            this.device.queue.writeBuffer(uniformBuffer, 0, args.uniforms);
+            const layout = pipeline.getBindGroupLayout?.(0);
+            if (!layout)
+                throw new RenderDeviceError("WebGPU post pipeline has no bind-group layout", "NATIVE_POST_UNSUPPORTED", { label: args.label });
+            const group = this.device.createBindGroup({
+                label: `${args.label}-bind`,
+                layout,
+                entries: [
+                    { binding: 0, resource: { buffer: uniformBuffer } },
+                    { binding: 1, resource: this.webgpuPostLinearSampler },
+                    ...args.views.map((view, index) => ({ binding: 2 + index, resource: view }))
+                ]
+            });
+            const encoder = this.device.createCommandEncoder({ label: `${args.label}-encoder` });
+            const pass = encoder.beginRenderPass({
+                label: `${args.label}-pass`,
+                colorAttachments: [{ view: targetView, loadOp: "load", storeOp: "store" }]
+            });
+            pass.setPipeline(pipeline);
+            pass.setBindGroup?.(0, group);
+            pass.draw(3, 1, 0);
+            pass.end();
+            this.device.queue.submit([encoder.finish()]);
+            submitted = true;
+            // The pass owns every pixel (fullscreen triangle), so a later
+            // readPixelsAsync must NOT flush a stale pending clear over it.
+            if (target)
+                target.nativeNeedsClear = false;
+            this.nativeRenderPasses += 1;
+            // Retired, not destroyed: the submit only enqueues; the pass reads
+            // these uniforms when the GPU gets to it.
+            this.webgpuPostRetiredUniformBuffers.push(uniformBuffer);
+        }
+        catch (error) {
+            if (!submitted)
+                uniformBuffer.destroy();
+            throw error;
+        }
+        finally {
+            if (scopedErrors && scopeDevice.popErrorScope) {
+                const pending = scopeDevice.popErrorScope().then((info) => {
+                    if (info?.message)
+                        this.webgpuPostErrors.push(`[${args.label}] ${info.message}`);
+                }, () => undefined);
+                this.webgpuPostErrorScopePending.push(pending);
+            }
+        }
+    }
+    reclaimWebGPUPostUniformBuffers() {
+        for (const buffer of this.webgpuPostRetiredUniformBuffers)
+            buffer.destroy();
+        this.webgpuPostRetiredUniformBuffers = [];
+    }
     dispose() {
         if (this.disposed)
             return;
+        this.reclaimWebGPUPostUniformBuffers();
         for (const buffer of this.buffers)
             buffer.dispose();
         for (const shader of this.shaders)
@@ -878,6 +1338,8 @@ export class WebGPUDevice {
             throw new RenderDeviceError("No active frame", "NO_ACTIVE_FRAME");
         }
     }
+    temporalLossListeners = new Set();
+    onDeviceLost(listener) { this.temporalLossListeners.add(listener); return () => this.temporalLossListeners.delete(listener); }
     observeDeviceLost() {
         const lost = this.device.lost;
         if (!lost || typeof lost.then !== "function")
@@ -886,12 +1348,24 @@ export class WebGPUDevice {
             if (this.disposed)
                 return;
             this.contextLost = true;
+            for (const listener of this.temporalLossListeners) {
+                try {
+                    listener();
+                }
+                catch { /* Continue notifying owners. */ }
+            }
             const detail = [info.reason, info.message].filter(Boolean).join(": ");
             this.lastError = detail ? `WebGPU device lost: ${detail}` : "WebGPU device lost";
         }).catch((error) => {
             if (this.disposed)
                 return;
             this.contextLost = true;
+            for (const listener of this.temporalLossListeners) {
+                try {
+                    listener();
+                }
+                catch { /* Continue notifying owners. */ }
+            }
             this.lastError = `WebGPU device lost promise rejected: ${error instanceof Error ? error.message : String(error)}`;
         });
     }
@@ -965,9 +1439,9 @@ export class WebGPUDevice {
                     const worldA = transformPosition(localA, modelMatrix);
                     const worldB = transformPosition(localB, modelMatrix);
                     const worldC = transformPosition(localC, modelMatrix);
-                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA);
-                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB);
-                    const colorC = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexC);
+                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA, colorAttribute?.components);
+                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB, colorAttribute?.components);
+                    const colorC = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexC, colorAttribute?.components);
                     const uvA = readVertexUv(vertexBuffer.bytes, command.vertexFormat.stride, uvAttribute?.offset, indexA);
                     const uvB = readVertexUv(vertexBuffer.bytes, command.vertexFormat.stride, uvAttribute?.offset, indexB);
                     const uvC = readVertexUv(vertexBuffer.bytes, command.vertexFormat.stride, uvAttribute?.offset, indexC);
@@ -980,15 +1454,15 @@ export class WebGPUDevice {
                     const indexB = indices[offset + 1];
                     const a = transformPosition(readLocal(indexA), matrix);
                     const b = transformPosition(readLocal(indexB), matrix);
-                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA);
-                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB);
+                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA, colorAttribute?.components);
+                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB, colorAttribute?.components);
                     rasterizeLine(this.activeRenderTarget, a, b, color, colorA, colorB, depthTest, depthWrite);
                 }
             }
             else {
                 for (const index of indices) {
                     const point = transformPosition(readLocal(index), matrix);
-                    const vertexColor = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, index);
+                    const vertexColor = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, index, colorAttribute?.components);
                     rasterizePoint(this.activeRenderTarget, point, multiplyColor(color, vertexColor), depthTest, depthWrite);
                 }
             }
@@ -1002,7 +1476,27 @@ export class WebGPUDevice {
         if (!hasNativeRenderPipeline(this.device))
             return;
         const shader = this.requireShader(command.shader);
-        const vertexModule = shader.modules[0];
+        // GL supplies an opaque white default for an absent vertex color. Native
+        // WGSL inputs must instead match the actual vertex buffer layout.
+        const useDefaultColor = shader.nativeColorDefaultVertex && !command.vertexFormat?.attributes.some(attribute => attribute.semantic === "color");
+        if (useDefaultColor && !shader.nativeColorDefaultModule) {
+            shader.nativeColorDefaultModule = this.device.createShaderModule?.({ label: `${shader.label}-vertex-default-color`, code: shader.nativeColorDefaultVertex });
+        }
+        let vertexModule = useDefaultColor ? shader.nativeColorDefaultModule : shader.modules[0];
+        if (shader.nativeAtlasVertex) {
+            const hasColor = command.vertexFormat?.attributes.some(attribute => attribute.shaderLocation === 4) ?? false;
+            const hasUv1 = command.vertexFormat?.attributes.some(attribute => attribute.shaderLocation === 7) ?? false;
+            const key = `${hasColor}:${hasUv1}`;
+            if (!shader.atlasVertexModules.has(key)) {
+                let source = shader.nativeAtlasVertex;
+                if (!hasColor)
+                    source = source.replace(", @location(4) color: vec4<f32>", "").replace("output.color = color;", "output.color = vec4<f32>(1.0);");
+                if (!hasUv1)
+                    source = source.replace(", @location(7) uv1: vec2<f32>", "").replace("output.uv1 = uv1;", "output.uv1 = vec2<f32>(0.0);");
+                shader.atlasVertexModules.set(key, this.device.createShaderModule?.({ label: `${shader.label}-atlas-vertex-${key}`, code: source }));
+            }
+            vertexModule = shader.atlasVertexModules.get(key);
+        }
         const fragmentModule = shader.modules[1] ?? vertexModule;
         if (!vertexModule || !fragmentModule)
             return;
@@ -1062,12 +1556,19 @@ export class WebGPUDevice {
         const uniformBuffer = usesNativeDrawUniforms(shader.nativeUniformLayout) ? this.createNativeDrawUniformBuffer(command) : null;
         const sampledTexture = shader.nativeUniformLayout === "generated-texture" ? this.createNativeSampledTextureBinding(uniformBaseColorTextureBinding(command.uniforms)) : null;
         const materialTextures = usesNativePbrTextureBindings(shader.nativeUniformLayout) ? this.createNativePbrTextureBindings(command) : null;
+        const atlasResources = shader.nativeUniformLayout === "generated-atlas-pbr" ? this.createNativeAtlasBindings(command) : null;
+        if (shader.nativeUniformLayout === "generated-atlas-pbr" && !atlasResources) {
+            uniformBuffer?.destroy();
+            return;
+        }
         if (shader.nativeUniformLayout === "generated-texture" && !sampledTexture) {
             uniformBuffer?.destroy();
+            atlasResources?.buffer.destroy();
             return;
         }
         if (usesNativePbrTextureBindings(shader.nativeUniformLayout) && !materialTextures) {
             uniformBuffer?.destroy();
+            atlasResources?.buffer.destroy();
             return;
         }
         if (shader.nativeUniformLayout === "portable" && !portableResources)
@@ -1078,6 +1579,7 @@ export class WebGPUDevice {
                 layout: pipeline.getBindGroupLayout(0),
                 entries: portableResources?.entries ?? [
                     { binding: 0, resource: { buffer: uniformBuffer } },
+                    ...(atlasResources?.entries ?? []),
                     ...(sampledTexture ? [
                         { binding: 1, resource: sampledTexture.sampler },
                         { binding: 2, resource: sampledTexture.view }
@@ -1098,7 +1600,9 @@ export class WebGPUDevice {
                         { binding: 13, resource: materialTextures.occlusion.sampler },
                         { binding: 14, resource: materialTextures.occlusion.view },
                         { binding: 15, resource: materialTextures.clusterLightData.view },
-                        { binding: 16, resource: materialTextures.clusterLightIndices.view }
+                        { binding: 16, resource: materialTextures.clusterLightIndices.view },
+                        { binding: 17, resource: materialTextures.spotShadow.sampler },
+                        { binding: 18, resource: materialTextures.spotShadow.view }
                     ] : [])
                 ]
             })
@@ -1132,6 +1636,7 @@ export class WebGPUDevice {
             if (!pass.setIndexBuffer || !pass.drawIndexed) {
                 pass.end();
                 uniformBuffer?.destroy();
+                atlasResources?.buffer.destroy();
                 portableResources?.buffer.destroy();
                 this.lastError = "Native WebGPU indexed draw skipped because the render-pass encoder does not expose indexed draw APIs.";
                 return;
@@ -1148,6 +1653,7 @@ export class WebGPUDevice {
         if (this.activeRenderTarget)
             this.activeRenderTarget.nativeNeedsClear = false;
         uniformBuffer?.destroy();
+        atlasResources?.buffer.destroy();
         portableResources?.buffer.destroy();
         this.nativeSubmissions += 1;
         if (sampledTexture)
@@ -1162,7 +1668,7 @@ export class WebGPUDevice {
             this.nativePassthroughSubmissions += 1;
             this.nativeTextureBindings += portableResources?.actualTextureCount ?? 0;
         }
-        if (shader.nativeUniformLayout === "generated-pbr" || shader.nativeUniformLayout === "generated-textured-pbr" || shader.nativeUniformLayout === "generated-instanced-pbr")
+        if (shader.nativeUniformLayout === "generated-pbr" || shader.nativeUniformLayout === "generated-atlas-pbr" || shader.nativeUniformLayout === "generated-textured-pbr" || shader.nativeUniformLayout === "generated-instanced-pbr")
             this.nativePbrSubmissions += 1;
         if (shader.nativeUniformLayout === "generated-instanced-pbr")
             this.nativeInstancedSubmissions += 1;
@@ -1170,6 +1676,7 @@ export class WebGPUDevice {
             this.nativeSkinnedSubmissions += 1;
         if (shader.nativeUniformLayout === "generated-morph-unlit")
             this.nativeMorphSubmissions += 1;
+        this.nativeTextureBindings += atlasResources?.actualTextureCount ?? 0;
         if (materialTextures?.actualBaseColor)
             this.nativeTextureBindings += 1;
         if (materialTextures?.actualNormal)
@@ -1184,6 +1691,8 @@ export class WebGPUDevice {
             this.nativeEnvironmentBindings += 1;
         if (materialTextures?.actualShadow)
             this.nativeShadowMapBindings += 1;
+        if (materialTextures?.actualSpotShadow)
+            this.nativeShadowMapBindings += 1;
         if (!this.activeRenderTarget)
             this.canvasSubmissions += 1;
     }
@@ -1221,6 +1730,20 @@ export class WebGPUDevice {
         if (!binding?.texture || binding.texture.disposed || !binding.validate().ok || !hasNativeSampledTextureBinding(this.device))
             return null;
         const texture = binding.texture;
+        // J2 zero-copy shadow path: a render target's native color texture is
+        // created with TEXTURE_BINDING usage, so a shadow map rendered natively
+        // (ShadowPass "encoded-color-depth") samples directly — no CPU readback
+        // round-trip. Same-queue submission order guarantees the depth writes
+        // are visible to the later lit pass.
+        for (const target of this.renderTargets) {
+            if (target.disposed || target.sampleCount !== 1 || target.colorTexture !== texture || !target.nativeView)
+                continue;
+            return {
+                view: target.nativeView,
+                sampler: this.device.createSampler(webgpuSamplerDescriptor(binding.sampler)),
+                actual: true
+            };
+        }
         let resource = this.nativeSampledTextures.get(texture);
         if (!resource) {
             if (texture.source) {
@@ -1290,6 +1813,7 @@ export class WebGPUDevice {
         const environmentBinding = uniformTextureBinding(command.uniforms, "u_environmentMapTexture");
         const brdfBinding = uniformTextureBinding(command.uniforms, "u_environmentBrdfLutTexture");
         const shadowBinding = uniformTextureBinding(command.uniforms, "u_shadowMapTexture");
+        const spotShadowBinding = uniformTextureBinding(command.uniforms, "u_spotShadowMapTexture");
         const normalBinding = uniformTextureBinding(command.uniforms, "u_normalTexture");
         const metallicRoughnessBinding = uniformTextureBinding(command.uniforms, "u_metallicRoughnessTexture");
         const occlusionBinding = uniformTextureBinding(command.uniforms, "u_occlusionTexture");
@@ -1299,18 +1823,20 @@ export class WebGPUDevice {
         const environment = this.createNativeSampledTextureBinding(environmentBinding) ?? this.createNativeFallbackSampledTextureBinding("environment-srgb", [92, 116, 156, 255], "srgb");
         const brdf = this.createNativeSampledTextureBinding(brdfBinding) ?? this.createNativeFallbackSampledTextureBinding("brdf-linear", [180, 180, 255, 255], "linear");
         const shadow = this.createNativeSampledTextureBinding(shadowBinding) ?? this.createNativeFallbackSampledTextureBinding("shadow-lit-linear", [255, 255, 255, 255], "linear");
+        const spotShadow = this.createNativeSampledTextureBinding(spotShadowBinding) ?? this.createNativeFallbackSampledTextureBinding("spot-shadow-lit-linear", [255, 255, 255, 255], "linear");
         const normal = this.createNativeSampledTextureBinding(normalBinding) ?? this.createNativeFallbackSampledTextureBinding("flat-normal-linear", [128, 128, 255, 255], "linear");
         const metallicRoughness = this.createNativeSampledTextureBinding(metallicRoughnessBinding) ?? this.createNativeFallbackSampledTextureBinding("metallic-roughness-linear", [255, 255, 255, 255], "linear");
         const occlusion = this.createNativeSampledTextureBinding(occlusionBinding) ?? this.createNativeFallbackSampledTextureBinding("occlusion-linear", [255, 255, 255, 255], "linear");
         const clusterLightData = this.createNativeSampledTextureBinding(clusterLightDataBinding) ?? this.createNativeFallbackSampledTextureBinding("cluster-light-data-linear", [0, 0, 0, 0], "linear");
         const clusterLightIndices = this.createNativeSampledTextureBinding(clusterLightIndicesBinding) ?? this.createNativeFallbackSampledTextureBinding("cluster-light-indices-linear", [0, 0, 0, 0], "linear");
-        if (!base || !environment || !brdf || !shadow || !normal || !metallicRoughness || !occlusion || !clusterLightData || !clusterLightIndices)
+        if (!base || !environment || !brdf || !shadow || !spotShadow || !normal || !metallicRoughness || !occlusion || !clusterLightData || !clusterLightIndices)
             return null;
         return {
             base,
             environment,
             brdf,
             shadow,
+            spotShadow,
             normal,
             metallicRoughness,
             occlusion,
@@ -1320,6 +1846,7 @@ export class WebGPUDevice {
             actualEnvironment: environmentBinding !== null && environment.actual,
             actualBrdf: brdfBinding !== null && brdf.actual,
             actualShadow: shadowBinding !== null && shadow.actual,
+            actualSpotShadow: spotShadowBinding !== null && spotShadow.actual,
             actualNormal: normalBinding !== null && normal.actual,
             actualMetallicRoughness: metallicRoughnessBinding !== null && metallicRoughness.actual,
             actualOcclusion: occlusionBinding !== null && occlusion.actual
@@ -1355,8 +1882,10 @@ export class WebGPUDevice {
     createNativeDrawUniformBuffer(command) {
         if (!this.device.createBindGroup)
             return null;
-        // 188 floats for the scalar/matrix fields + 96 joint matrices (16 floats each) appended at 188.
-        const data = new Float32Array(188 + MAX_WEBGPU_SKINNING_JOINTS * 16);
+        // 188 floats for the scalar/matrix fields + 96 joint matrices (16 floats each) appended at 188
+        // + J2 native shadow projections (312 floats at 1724: directional matrix/params/PCF, then spot)
+        // + model matrix (16 floats at 2036) for instanced world composition.
+        const data = new Float32Array(2052);
         const baseColorBinding = uniformBaseColorTextureBinding(command.uniforms);
         const environmentBinding = uniformTextureBinding(command.uniforms, "u_environmentMapTexture");
         const normalBinding = uniformTextureBinding(command.uniforms, "u_normalTexture");
@@ -1408,6 +1937,37 @@ export class WebGPUDevice {
         for (let index = 0; index < MAX_WEBGPU_SKINNING_JOINTS; index += 1) {
             data.set(jointMatrices[index] ?? identityMatrix(), 188 + index * 16);
         }
+        // J2 native shadow projections (WGSL parity with a3dForwardShadowFactor /
+        // a3dSpotShadowFactor). Identity matrices + zero enabled flags keep every
+        // shadow factor at exactly 1.0 (lit) when the ForwardPass gates stay shut.
+        data.set(uniformMat4(command.uniforms?.get("u_shadowMapMatrix")) ?? identityMatrix(), 1724);
+        const shadowTexel = uniformVec2(command.uniforms?.get("u_shadowMapTexelSize")) ?? [1, 1];
+        data.set([
+            uniformNumber(command.uniforms?.get("u_shadowMapBias"), 0.001),
+            uniformNumber(command.uniforms?.get("u_shadowMapSlopeBias"), 1),
+            shadowTexel[0],
+            shadowTexel[1]
+        ], 1740);
+        data.set([uniformNumber(command.uniforms?.get("u_shadowPcfSampleCount"), 1), 0, 0, 0], 1744);
+        setNativeShadowPcfSamples(data, command.uniforms?.get("u_shadowPcfSamples"), 1748);
+        data.set(uniformMat4(command.uniforms?.get("u_spotShadowMatrix")) ?? identityMatrix(), 1876);
+        const spotLightPosition = uniformVec3(command.uniforms?.get("u_spotShadowLightPosition")) ?? [0, 0, 0];
+        data.set([spotLightPosition[0], spotLightPosition[1], spotLightPosition[2], uniformNumber(command.uniforms?.get("u_spotShadowRange"), 1)], 1892);
+        const spotLightDirection = uniformVec3(command.uniforms?.get("u_spotShadowLightDirection")) ?? [0, -1, 0];
+        data.set([spotLightDirection[0], spotLightDirection[1], spotLightDirection[2], 0], 1896);
+        data.set([
+            uniformNumber(command.uniforms?.get("u_spotShadowMapEnabled"), 0),
+            uniformNumber(command.uniforms?.get("u_spotShadowStrength"), 0.65),
+            uniformNumber(command.uniforms?.get("u_spotShadowBias"), 0.001),
+            uniformNumber(command.uniforms?.get("u_spotShadowSlopeBias"), 1)
+        ], 1900);
+        const spotTexel = uniformVec2(command.uniforms?.get("u_spotShadowTexelSize")) ?? [1, 1];
+        const spotCone = uniformVec2(command.uniforms?.get("u_spotShadowCone")) ?? [Math.PI / 4, 0];
+        data.set([spotTexel[0], spotTexel[1], uniformNumber(command.uniforms?.get("u_spotShadowPcfSampleCount"), 1), spotCone[0]], 1904);
+        setNativeShadowPcfSamples(data, command.uniforms?.get("u_spotShadowPcfSamples"), 1908);
+        // Model matrix for the instanced vertex world composition
+        // (u_modelMatrix * instanceMatrix * position, GLSL parity).
+        data.set(modelMatrix, 2036);
         const morphDeltas = command.uniforms?.get("u_morphPositionDeltas");
         const morphNumbers = morphDeltas instanceof Float32Array || Array.isArray(morphDeltas) ? Array.from(morphDeltas).slice(0, 32) : [];
         if (morphNumbers.length > 0)
@@ -1420,6 +1980,36 @@ export class WebGPUDevice {
         this.device.queue.writeBuffer(buffer, 0, data);
         return buffer;
     }
+    createNativeAtlasBindings(command) {
+        const definitions = [
+            ["u_extensionScalarAtlas", 20, 0, "linear"],
+            ["u_clearcoatNormalTexture", 22, 21, "linear"],
+            ["u_sheenColorTexture", 24, 23, "srgb"],
+            ["u_anisotropyTexture", 26, 25, "linear"],
+            ["u_emissiveTexture", 28, 27, "srgb"]
+        ];
+        const entries = [];
+        let actualTextureCount = 0;
+        for (const [name, textureIndex, samplerIndex, colorSpace] of definitions) {
+            const actualTexture = this.createNativeSampledTextureBinding(uniformTextureBinding(command.uniforms, name));
+            if (textureIndex === 20 && !actualTexture)
+                throw new RenderDeviceError("Native extension atlas requires a resolved scalar atlas texture", "TEXTURE_BINDING_MISSING");
+            const texture = actualTexture
+                ?? this.createNativeFallbackSampledTextureBinding(`atlas-${name}`, name.includes("Normal") ? [128, 128, 255, 255] : [255, 255, 255, 255], colorSpace);
+            if (!texture)
+                return null;
+            if (texture.actual)
+                actualTextureCount += 1;
+            entries.push({ binding: textureIndex, resource: texture.view });
+            if (samplerIndex)
+                entries.push({ binding: samplerIndex, resource: texture.sampler });
+        }
+        const data = webgpuExtensionAtlasUniforms(command.uniforms);
+        const buffer = this.device.createBuffer({ label: "extension-atlas-uniforms", size: data.byteLength, usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST });
+        this.device.queue.writeBuffer(buffer, 0, data);
+        entries.push({ binding: 19, resource: { buffer } });
+        return { buffer, entries, actualTextureCount };
+    }
     createNativePortableBindings(command, bindings) {
         if (!this.device.createBindGroup)
             return null;
@@ -1726,6 +2316,7 @@ function usesNativeDrawUniforms(layout) {
 }
 function usesNativePbrTextureBindings(layout) {
     return layout === "generated-pbr" ||
+        layout === "generated-atlas-pbr" ||
         layout === "generated-textured-pbr" ||
         layout === "generated-instanced-pbr";
 }
@@ -1806,6 +2397,15 @@ function uniformVec2(value) {
         ? [components[0], components[1]]
         : null;
 }
+function setNativeShadowPcfSamples(data, value, offset) {
+    const numbers = value instanceof Float32Array || Array.isArray(value) ? Array.from(value) : [];
+    for (let index = 0; index < 32; index += 1) {
+        const quad = numbers.slice(index * 4, index * 4 + 4);
+        // Default single center tap (weight 1) so an enabled shadow map without
+        // an explicit kernel still occludes instead of dividing by zero weight.
+        data.set(quad.length === 4 && quad.every(Number.isFinite) ? quad : [0, 0, 1, 0], offset + index * 4);
+    }
+}
 function uniformMat4Array(value, count) {
     const numbers = value instanceof Float32Array || Array.isArray(value) ? Array.from(value) : [];
     return Array.from({ length: count }, (_, index) => {
@@ -1972,7 +2572,7 @@ function jointPaletteFor(uniforms) {
     const count = Math.min(MAX_WEBGPU_SKINNING_JOINTS, Math.floor(length / 16));
     return count > 0 ? uniformMat4Array(value, count) : [];
 }
-function readVertexColor(bytes, stride, offset, vertexIndex) {
+function readVertexColor(bytes, stride, offset, vertexIndex, components = 4) {
     if (offset === undefined)
         return [1, 1, 1, 1];
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -1981,7 +2581,7 @@ function readVertexColor(bytes, stride, offset, vertexIndex) {
         view.getFloat32(base, true),
         view.getFloat32(base + 4, true),
         view.getFloat32(base + 8, true),
-        view.getFloat32(base + 12, true)
+        components >= 4 ? view.getFloat32(base + 12, true) : 1
     ];
 }
 function readVertexUv(bytes, stride, offset, vertexIndex) {
@@ -2166,7 +2766,9 @@ function createNativeShaderSources(sources) {
         return { ...nativeInstancedPbrShader(vertexEntry, fragmentEntry, sources.marker), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: "generated-instanced-pbr" };
     }
     if (sources.marker.includes("pbr-textured")) {
-        return { ...nativeTexturedPbrShader(vertexEntry, fragmentEntry, sources.marker, nativeShaderUsesTangent(sources.vertex)), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: "generated-textured-pbr" };
+        const atlas = /uniform\s+sampler2D\s+u_extensionScalarAtlas/.test(sources.fragment);
+        const native = nativeTexturedPbrShader(vertexEntry, fragmentEntry, sources.marker, nativeShaderUsesTangent(sources.vertex), atlas);
+        return { ...native, ...(atlas ? { atlasVertex: native.vertex } : {}), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: atlas ? "generated-atlas-pbr" : "generated-textured-pbr" };
     }
     if (sources.marker.includes("pbr-direct")) {
         return sources.fragment.includes("u_baseColorTexture")
@@ -2180,22 +2782,100 @@ function createNativeShaderSources(sources) {
         return { ...nativeMorphUnlitShader(vertexEntry, fragmentEntry, sources.marker), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: "generated-morph-unlit" };
     }
     if (/sampler2D/.test(sources.fragment) && /layout\s*\(\s*location\s*=\s*2\s*\)\s*in\s+vec2/.test(sources.vertex)) {
+        const colorInput = /layout\s*\(\s*location\s*=\s*(\d+)\s*\)\s*in\s+(?:lowp\s+|mediump\s+|highp\s+)?vec([34])\s+(?:a_color|color)\s*;/.exec(sources.vertex);
+        const colorParameter = colorInput ? `, @location(${colorInput[1]}) vertexColor: vec${colorInput[2]}<f32>` : "";
+        const drawUniforms = `struct DrawUniforms {
+  modelViewProjection: mat4x4<f32>,
+  color: vec4<f32>,
+};
+@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;`;
+        const vertexOutput = `struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+  ${colorInput ? "@location(1) color: vec4<f32>," : ""}
+};`;
+        const vertex = `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@vertex
+fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(2) uv: vec2<f32>${colorParameter}) -> VertexOutput {
+  var output: VertexOutput;
+  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
+  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);
+  output.uv = uv;
+  ${colorInput ? `output.color = ${colorInput[2] === "3" ? "vec4<f32>(vertexColor, 1.0)" : "vertexColor"};` : ""}
+  return output;
+}
+`;
         return {
-            vertex: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n  @location(0) uv: vec2<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@vertex\nfn ${vertexEntry}(@location(0) position: vec3<f32>, @location(2) uv: vec2<f32>) -> VertexOutput {\n  var output: VertexOutput;\n  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
-  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);\n  output.uv = uv;\n  return output;\n}\n`,
-            fragment: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n  @location(0) uv: vec2<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n@group(0) @binding(1) var u_textureSampler: sampler;\n@group(0) @binding(2) var u_texture: texture_2d<f32>;\n\n@fragment\nfn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {\n  return u_draw.color * textureSample(u_texture, u_textureSampler, input.uv);\n}\n`,
+            vertex,
+            colorDefaultVertex: colorInput ? vertex.replace(colorParameter, "").replace(/output\.color = [^;]+;/, "output.color = vec4<f32>(1.0);") : undefined,
+            fragment: `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@group(0) @binding(1) var u_textureSampler: sampler;
+@group(0) @binding(2) var u_texture: texture_2d<f32>;
+@fragment
+fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
+  return u_draw.color * textureSample(u_texture, u_textureSampler, input.uv)${colorInput ? " * input.color" : ""};
+}
+`,
             entryPoints: [vertexEntry, fragmentEntry],
             uniformLayout: "generated-texture"
         };
     }
+    // Basic GLSL programs (including unlit primitives and particle sprites)
+    // declare their color input explicitly. Preserve that location and component
+    // count; RGB inputs use opaque alpha, while RGBA alpha modulates the material.
+    // Depth programs intentionally do not consume material/vertex color.
+    const colorInput = sources.marker.includes(DEFAULT_DEPTH_SHADER_MARKER) ? null
+        : /layout\s*\(\s*location\s*=\s*(\d+)\s*\)\s*in\s+(?:lowp\s+|mediump\s+|highp\s+)?vec([34])\s+(?:a_color|color)\s*;/.exec(sources.vertex);
+    const colorParameter = colorInput ? `, @location(${colorInput[1]}) vertexColor: vec${colorInput[2]}<f32>` : "";
+    const vertexOutput = `struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  ${colorInput ? "@location(0) color: vec4<f32>," : ""}
+};`;
+    const drawUniforms = `struct DrawUniforms {
+  modelViewProjection: mat4x4<f32>,
+  color: vec4<f32>,
+};
+@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;`;
+    const vertex = `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@vertex
+fn ${vertexEntry}(@location(0) position: vec3<f32>${colorParameter}) -> VertexOutput {
+  var output: VertexOutput;
+  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
+  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);
+  ${colorInput ? `output.color = ${colorInput[2] === "3" ? "vec4<f32>(vertexColor, 1.0)" : "vertexColor"};` : ""}
+  return output;
+}
+`;
     return {
-        vertex: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@vertex\nfn ${vertexEntry}(@location(0) position: vec3<f32>) -> VertexOutput {\n  var output: VertexOutput;\n  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
-  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);\n  return output;\n}\n`,
-        fragment: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@fragment\nfn ${fragmentEntry}() -> @location(0) vec4<f32> {\n  return u_draw.color;\n}\n`,
+        vertex,
+        colorDefaultVertex: colorInput ? vertex.replace(colorParameter, "").replace(/output\.color = [^;]+;/, "output.color = vec4<f32>(1.0);") : undefined,
+        fragment: sources.marker.includes(DEFAULT_DEPTH_SHADER_MARKER)
+            ? nativeDepthFragment(sources.marker, fragmentEntry)
+            : `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@fragment
+fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
+  return u_draw.color${colorInput ? " * input.color" : ""};
+}
+`,
         entryPoints: [vertexEntry, fragmentEntry],
         uniformLayout: "generated-basic"
     };
 }
+function nativeDepthFragment(marker, fragmentEntry) {
+    // J2 native depth encoding: the GLSL depth program writes gl_FragCoord.z
+    // into an rgba8 shadow target ("encoded-color-depth"). The framebuffer
+    // depth @builtin(position).z is already 0..1 in WebGPU, so packing it
+    // samples identically to the GL path through the projective PCF reader.
+    return `// ${marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@fragment\nfn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {\n  return vec4<f32>(input.position.z, input.position.z, input.position.z, 1.0);\n}\n`;
+}
 const PORTABLE_BINDINGS_MARKER = "/* @aura3d-bindings */";
 function injectPortableBindings(source, bindings) {
     if (!source.includes(PORTABLE_BINDINGS_MARKER)) {
@@ -2299,6 +2979,23 @@ function nativeUniformStruct() {
   // 96-joint skinning palette (WebGL2 \`u_jointMatrices[96]\` parity). Appended at the struct end so
   // the existing field offsets are unchanged.
   joints: array<mat4x4<f32>, 96>,
+  // J2 native shadow projections (float offsets 1724+, after the 96-joint
+  // palette). Directional block mirrors GLSL \`a3dForwardShadowFactor\`;
+  // spot block mirrors \`a3dSpotShadowFactor\` (cone/range pre-check inside
+  // the helper). Appended here so no existing field offset moves.
+  shadowMapMatrix: mat4x4<f32>,
+  shadowParams0: vec4<f32>,
+  shadowParams1: vec4<f32>,
+  shadowPcf: array<vec4<f32>, 32>,
+  spotShadowMatrix: mat4x4<f32>,
+  spotShadowParams0: vec4<f32>,
+  spotShadowParams1: vec4<f32>,
+  spotShadowParams2: vec4<f32>,
+  spotShadowParams3: vec4<f32>,
+  spotShadowPcf: array<vec4<f32>, 32>,
+  // Model matrix for GLSL-parity world composition on the instanced path
+  // (\`u_modelMatrix * instanceMatrix * position\`; float offset 2036).
+  modelMatrix: mat4x4<f32>,
 };
 
 @group(0) @binding(0) var<uniform> u_draw: DrawUniforms;
@@ -2311,7 +3008,7 @@ fn a3dWebGPUClipPosition(clipPosition: vec4<f32>) -> vec4<f32> {
 function nativeShaderUsesTangent(vertexSource) {
     return /\ba_tangent\b/.test(vertexSource) || /layout\s*\(\s*location\s*=\s*3\s*\)\s*in\s+vec4/.test(vertexSource);
 }
-function nativePbrFragmentPrelude(marker) {
+function nativePbrFragmentPrelude(marker, atlas = false) {
     return `// ${marker}
 ${nativeUniformStruct()}
 @group(0) @binding(1) var u_baseSampler: sampler;
@@ -2330,6 +3027,10 @@ ${nativeUniformStruct()}
 @group(0) @binding(14) var u_occlusionTexture: texture_2d<f32>;
 @group(0) @binding(15) var u_clusterLightData: texture_2d<f32>;
 @group(0) @binding(16) var u_clusterLightIndices: texture_2d<f32>;
+@group(0) @binding(17) var u_spotShadowSampler: sampler;
+@group(0) @binding(18) var u_spotShadowTexture: texture_2d<f32>;
+
+${atlas ? WEBGPU_EXTENSION_ATLAS_WGSL : ""}
 
 struct VertexOutput {
   @builtin(position) position: vec4<f32>,
@@ -2337,6 +3038,7 @@ struct VertexOutput {
   @location(1) uv: vec2<f32>,
   @location(2) worldPosition: vec3<f32>,
   @location(3) tangent: vec4<f32>,
+  ${atlas ? "@location(4) uv1: vec2<f32>, @location(5) color: vec4<f32>," : ""}
 };
 
 fn fresnelSchlick(cosTheta: f32, f0: vec3<f32>) -> vec3<f32> {
@@ -2349,14 +3051,16 @@ fn fresnelSchlickRoughness(cosTheta: f32, f0: vec3<f32>, roughness: f32) -> vec3
 }
 
 fn ggxDistribution(nDotH: f32, roughness: f32) -> f32 {
-  let a = max(roughness * roughness, 0.045);
+  let a = ${atlas ? "max(roughness, 0.045) * max(roughness, 0.045)" : "max(roughness * roughness, 0.045)"};
   let a2 = a * a;
-  let denom = max((nDotH * nDotH) * (a2 - 1.0) + 1.0, 0.001);
-  return a2 / max(3.14159265 * denom * denom, 0.001);
+  // At roughness .045 the true denominator before squaring is ~4.1e-6.
+  // A .001/.00001 floor destroys the normalized low-roughness GGX lobe.
+  let denom = max((nDotH * nDotH) * (a2 - 1.0) + 1.0, ${atlas ? "0.00000001" : "0.001"});
+  return a2 / max(3.14159265 * denom * denom, ${atlas ? "0.0000000000000001" : "0.001"});
 }
 
 fn ggxVisibilitySmithCorrelated(nDotV: f32, nDotL: f32, roughness: f32) -> f32 {
-  let a = max(roughness * roughness, 0.045);
+  let a = ${atlas ? "max(roughness, 0.045) * max(roughness, 0.045)" : "max(roughness * roughness, 0.045)"};
   let a2 = a * a;
   let lambdaV = nDotL * sqrt(max((nDotV - a2 * nDotV) * nDotV + a2, 0.00001));
   let lambdaL = nDotV * sqrt(max((nDotL - a2 * nDotL) * nDotL + a2, 0.00001));
@@ -2421,18 +3125,79 @@ fn perturbNormal(normalInput: vec3<f32>, tangentFrame: vec4<f32>, normalSample:
   return normalize(tangent * mapped.x + bitangent * mapped.y + n * max(mapped.z, 0.001));
 }
 
-fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worldPosition: vec3<f32>, fragmentPosition: vec2<f32>) -> vec4<f32> {
+fn a3dNativeShadowFactor(worldPosition: vec3<f32>, normal: vec3<f32>, lightDirection: vec3<f32>, useSpot: bool, shadowSampler: sampler, shadowTexture: texture_2d<f32>) -> f32 {
+  var shadowMatrix = u_draw.shadowMapMatrix;
+  var bias = u_draw.shadowParams0.x;
+  var slopeBias = u_draw.shadowParams0.y;
+  var texelSize = u_draw.shadowParams0.zw;
+  var strength = u_draw.flags.z;
+  var sampleCount = i32(u_draw.shadowParams1.x + 0.5);
+  var receiverLightDirection = lightDirection;
+  if (useSpot) {
+    if (u_draw.spotShadowParams2.x < 0.5) { return 1.0; }
+    let toFragment = worldPosition - u_draw.spotShadowParams0.xyz;
+    let distanceToLight = max(length(toFragment), 0.0001);
+    if (distanceToLight > u_draw.spotShadowParams0.w) { return 1.0; }
+    let coneAxis = u_draw.spotShadowParams1.xyz / max(length(u_draw.spotShadowParams1.xyz), 0.0001);
+    if (dot(toFragment / distanceToLight, coneAxis) < cos(u_draw.spotShadowParams3.w)) { return 1.0; }
+    receiverLightDirection = coneAxis * -1.0;
+    shadowMatrix = u_draw.spotShadowMatrix;
+    bias = u_draw.spotShadowParams2.z;
+    slopeBias = u_draw.spotShadowParams2.w;
+    texelSize = u_draw.spotShadowParams3.xy;
+    strength = u_draw.spotShadowParams2.y;
+    sampleCount = i32(u_draw.spotShadowParams3.z + 0.5);
+  }
+  let lightPosition = shadowMatrix * vec4<f32>(worldPosition, 1.0);
+  let projected = lightPosition.xyz / max(lightPosition.w, 0.0001);
+  let uv = projected.xy * 0.5 + vec2<f32>(0.5, 0.5);
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) { return 1.0; }
+  // Native render targets store framebuffer row 0 at the top while the CPU
+  // projection math addresses texels GL-style (row 0 at the bottom), so the
+  // sample V must be mirrored to land on the texel the projection means.
+  // Display and readback paths already account for the row order, which is
+  // why screenshots and readPixels match GL while direct sampling does not.
+  let sampleUv = vec2<f32>(uv.x, 1.0 - uv.y);
+  let receiverNormal = normalize(normal);
+  let shadowLightDirection = receiverLightDirection / max(length(receiverLightDirection), 0.0001);
+  let normalDotLight = clamp(abs(dot(receiverNormal, shadowLightDirection)), 0.0, 1.0);
+  // Shared bias-table policy (GLSL parity): per-sample tangent-scaled slope
+  // bias — a centre-only bias under-compensates outer PCF taps on sloped
+  // receivers, so each tap scales by its own texel distance.
+  let slopeTangent = min(sqrt(max(1.0 - normalDotLight * normalDotLight, 0.0)) / max(normalDotLight, 0.05), 8.0);
+  let slopeTexelBias = slopeTangent * slopeBias * max(texelSize.x, texelSize.y);
+  let projectedDepth = projected.z * 0.5 + 0.5;
+  var shadowed = 0.0;
+  var totalWeight = 0.0;
+  let taps = clamp(sampleCount, 1, 32);
+  for (var i = 0; i < 32; i = i + 1) {
+    if (i >= taps) { break; }
+    var sampleData = u_draw.shadowPcf[i];
+    if (useSpot) { sampleData = u_draw.spotShadowPcf[i]; }
+    let weight = max(sampleData.z, 0.0);
+    let offset = sampleData.xy * texelSize;
+    let storedDepth = textureSampleLevel(shadowTexture, shadowSampler, sampleUv + offset, 0.0).r;
+    let sampleTexelDistance = max(1.0, length(sampleData.xy));
+    let receiverDepth = projectedDepth - bias - slopeTexelBias * sampleTexelDistance;
+    shadowed = shadowed + select(0.0, 1.0, receiverDepth > storedDepth) * weight;
+    totalWeight = totalWeight + weight;
+  }
+  let occlusion = select(0.0, shadowed / totalWeight, totalWeight > 0.0);
+  return mix(1.0, 1.0 - occlusion, clamp(strength, 0.0, 1.0));
+}
+
+fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worldPosition: vec3<f32>, fragmentPosition: vec2<f32>${atlas ? ", uv1: vec2<f32>, vertexColor: vec4<f32>" : ""}) -> vec4<f32> {
   var normal = normalize(normalInput);
   if (u_draw.morph0.x > 0.5) {
-    normal = perturbNormal(normal, tangentFrame, textureSample(u_normalTexture, u_normalSampler, uv).rgb, u_draw.morph0.y);
+    normal = perturbNormal(normal, tangentFrame, textureSample(u_normalTexture, u_normalSampler, ${atlas ? "atlasUv(1u, uv, uv1)" : "uv"}).rgb, u_draw.morph0.y);
   }
   let viewDirection = normalize(u_draw.camera.xyz - worldPosition);
   let lightDirection = normalize(vec3<f32>(0.36, 0.52, 0.78));
   let halfVector = normalize(lightDirection + viewDirection);
-  var baseColor = u_draw.color.rgb;
-  var materialAlpha = u_draw.color.a;
+  var baseColor = u_draw.color.rgb${atlas ? " * vertexColor.rgb" : ""};
+  var materialAlpha = u_draw.color.a${atlas ? " * vertexColor.a" : ""};
   if (u_draw.flags.x > 0.5) {
-    let baseSample = textureSample(u_baseTexture, u_baseSampler, uv);
+    let baseSample = textureSample(u_baseTexture, u_baseSampler, ${atlas ? "atlasUv(0u, uv, uv1)" : "uv"});
     baseColor = baseColor * baseSample.rgb;
     materialAlpha = materialAlpha * baseSample.a;
   }
@@ -2441,16 +3206,14 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
   let productBodyGate = productPropBodyGate(sourceProductBaseColor, u_draw.materialFlags.z) * (1.0 - productOrangeGate * 0.92);
   let productSurfaceGate = clamp(productBodyGate + productOrangeGate * 0.72, 0.0, 1.0);
   baseColor = productPropAlbedo(sourceProductBaseColor, u_draw.materialFlags.z);
-  if (materialAlpha < u_draw.material.x) {
-    discard;
-  }
+  ${atlas ? "" : "if (materialAlpha < u_draw.material.x) { discard; }"}
   let transmission = clamp(max(u_draw.material.y, u_draw.material.z), 0.0, 1.0);
-  let metallicRoughnessSample = textureSample(u_metallicRoughnessTexture, u_metallicRoughnessSampler, uv);
+  let metallicRoughnessSample = textureSample(u_metallicRoughnessTexture, u_metallicRoughnessSampler, ${atlas ? "atlasUv(2u, uv, uv1)" : "uv"});
   let metallicRoughnessEnabled = step(0.5, u_draw.materialFlags.x);
   let occlusionEnabled = step(0.5, u_draw.materialFlags.y);
   let sampledMetallic = clamp(u_draw.params.x * metallicRoughnessSample.b, 0.0, 1.0);
   let sampledRoughness = clamp(u_draw.params.y * metallicRoughnessSample.g, 0.045, 1.0);
-  let sampledOcclusion = mix(1.0, textureSample(u_occlusionTexture, u_occlusionSampler, uv).r, clamp(u_draw.morph0.z, 0.0, 1.0));
+  let sampledOcclusion = mix(1.0, textureSample(u_occlusionTexture, u_occlusionSampler, ${atlas ? "atlasUv(3u, uv, uv1)" : "uv"}).r, clamp(u_draw.morph0.z, 0.0, 1.0));
   let metallic = mix(clamp(u_draw.params.x, 0.0, 1.0), sampledMetallic, metallicRoughnessEnabled);
   let roughness = mix(clamp(u_draw.params.y, 0.045, 1.0), sampledRoughness, metallicRoughnessEnabled);
   let occlusion = mix(1.0, sampledOcclusion, occlusionEnabled);
@@ -2460,16 +3223,23 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
   let nDotV = max(dot(normal, viewDirection), 0.001);
   let nDotH = max(dot(normal, halfVector), 0.001);
   let vDotH = max(dot(viewDirection, halfVector), 0.001);
-  let f0 = mix(vec3<f32>(0.04, 0.04, 0.04), baseColor, metallic);
+  let dielectricF0 = ${atlas ? "vec3<f32>(pow((u_atlas.substrate.x-1.0)/(u_atlas.substrate.x+1.0),2.0)) * clamp(u_atlas.specularColor.rgb,vec3<f32>(0.0),vec3<f32>(1.0)) * clamp(u_atlas.substrate.y,0.0,1.0)" : "vec3<f32>(0.04, 0.04, 0.04)"};
+  let f0 = mix(dielectricF0, baseColor, metallic);
   let fresnel = fresnelSchlick(vDotH, f0);
   let distribution = ggxDistribution(nDotH, roughness);
   let visibility = ggxVisibilitySmithCorrelated(nDotV, nDotL, roughness);
   let lDotH = max(dot(lightDirection, halfVector), 0.0);
-  let kd = (vec3<f32>(1.0, 1.0, 1.0) - fresnel) * (1.0 - metallic);
+  ${atlas ? `// The film replaces the substrate Fresnel in the dielectric energy split.
+  // Retaining the old kd while adding film specular creates or loses energy.
+  let filmFresnel = atlasIridescenceFresnel(f0, vDotH, uv, uv1);
+  let filmMaximum = max(max(filmFresnel.r, filmFresnel.g), filmFresnel.b);
+  let diffuseFresnel = select(fresnel, vec3<f32>(filmMaximum), u_atlas.iridescence.y > 0.0);
+  let kd = (vec3<f32>(1.0) - diffuseFresnel) * (1.0 - metallic);` : "let kd = (vec3<f32>(1.0, 1.0, 1.0) - fresnel) * (1.0 - metallic);"}
   let specular = fresnel * distribution * visibility;
   let diffuse = kd * baseColor * diffuseBurley(nDotV, nDotL, lDotH, roughness) / 3.14159265;
   var environment = baseColor * u_draw.params.z * (0.28 + 0.72 * clamp(normal.y * 0.5 + 0.5, 0.0, 1.0)) * occlusion;
   var environmentSpecularContribution = vec3<f32>(0.0, 0.0, 0.0);
+  var environmentExtensionRadiance = vec3<f32>(0.0);
   if (u_draw.flags.w > 0.5) {
     let reflectionDirection = reflect(-viewDirection, normal);
     let diffuseUv = vec2<f32>(fract(atan2(normal.z, normal.x) / 6.2831853 + 0.5), acos(clamp(normal.y, -1.0, 1.0)) / 3.14159265);
@@ -2480,15 +3250,20 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
     let brdf = textureSampleLevel(u_brdfTexture, u_brdfSampler, vec2<f32>(nDotV, roughness), 0.0).rg;
     let environmentFresnel = fresnelSchlickRoughness(nDotV, f0, roughness);
     let environmentDiffuse = (vec3<f32>(1.0, 1.0, 1.0) - environmentFresnel) * (1.0 - metallic) * diffuseEnv * baseColor * u_draw.params.w * occlusion;
-    let environmentSpecular = specularEnv * (f0 * brdf.x + vec3<f32>(brdf.y, brdf.y, brdf.y)) * max(u_draw.reserved0.w, 0.0);
+    ${atlas ? "let environmentF0 = atlasIridescenceEnvironmentF0(f0, nDotV, uv, uv1);" : "let environmentF0 = f0;"}
+    let environmentSpecular = specularEnv * (environmentF0 * brdf.x + vec3<f32>(brdf.y, brdf.y, brdf.y)) * max(u_draw.reserved0.w, 0.0);
     environmentSpecularContribution = environmentSpecular;
+    environmentExtensionRadiance = specularEnv * max(u_draw.reserved0.w, 0.0);
     environment = environment + environmentDiffuse + environmentSpecular;
   }
+  // J2 native shadow projections: directional PCF mirrors GLSL
+  // a3dForwardShadowFactor; spot PCF mirrors a3dSpotShadowFactor. Both
+  // default to 1.0 (lit) when disabled or outside the shadow frustum.
   var shadow = 1.0;
   if (u_draw.flags.y > 0.5) {
-    let shadowDepth = textureSampleLevel(u_shadowTexture, u_shadowSampler, vec2<f32>(0.5, 0.5), 0.0).r;
-    shadow = mix(1.0, shadowDepth, clamp(u_draw.flags.z, 0.0, 1.0));
+    shadow = a3dNativeShadowFactor(worldPosition, normal, lightDirection, false, u_shadowSampler, u_shadowTexture);
   }
+  shadow = shadow * a3dNativeShadowFactor(worldPosition, normal, lightDirection, true, u_spotShadowSampler, u_spotShadowTexture);
   var clusteredDirect = vec3<f32>(0.0, 0.0, 0.0);
   if (u_draw.materialFlags.w > 0.5) {
     let indexDimensions = textureDimensions(u_clusterLightIndices);
@@ -2518,7 +3293,8 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
     }
   }
   let legacyDirect = (diffuse + specular) * nDotL * 2.25 * shadow;
-  let litOpaqueLinearColor = environment + select(legacyDirect, clusteredDirect, u_draw.materialFlags.w > 0.5);
+  let litOpaqueLinearColor = environment + select(legacyDirect, clusteredDirect, u_draw.materialFlags.w > 0.5)
+    ${atlas ? "+ atlasExtensionLighting(normal, tangentFrame, viewDirection, lightDirection, uv, uv1, shadow, environmentExtensionRadiance, f0, roughness) + u_atlas.emissive.rgb * u_atlas.factors.y * mix(vec3<f32>(1.0), textureSample(u_emissiveTexture, u_emissiveSampler, atlasUv(4u, uv, uv1)).rgb, u_atlas.maps[4].control.z)" : ""};
   let smoothedBodyColor = mix(baseColor, vec3<f32>(1.0, 0.88, 0.012), productBodyGate * 0.32);
   let smoothedBeakColor = mix(baseColor, vec3<f32>(1.0, 0.24, 0.018), productOrangeGate * 0.82);
   let softBodyProduct = smoothedBodyColor * (1.5 + 0.06 * nDotL) + specular * nDotL * 0.018;
@@ -2528,6 +3304,7 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
   let transmittedTint = baseColor * u_draw.params.w * (0.18 + 0.42 * clamp(1.0 - roughness, 0.0, 1.0)) + environmentSpecularContribution * 1.35;
   let linearColor = mix(opaqueLinearColor, opaqueLinearColor * 0.22 + transmittedTint, transmission);
   let outputAlpha = mix(materialAlpha, min(materialAlpha, 0.22), transmission);
+  ${atlas ? "if (materialAlpha < u_draw.material.x) { discard; }" : ""}
   return vec4<f32>(encodePbrOutput(linearColor), outputAlpha);
 }
 `;
@@ -2564,7 +3341,7 @@ fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
 `
     };
 }
-function nativeTexturedPbrShader(vertexEntry, fragmentEntry, marker, usesTangent) {
+function nativeTexturedPbrShader(vertexEntry, fragmentEntry, marker, usesTangent, atlas = false) {
     return {
         vertex: `// ${marker}
 ${nativeUniformStruct()}
@@ -2574,24 +3351,26 @@ struct VertexOutput {
   @location(1) uv: vec2<f32>,
   @location(2) worldPosition: vec3<f32>,
   @location(3) tangent: vec4<f32>,
+  ${atlas ? "@location(4) uv1: vec2<f32>, @location(5) color: vec4<f32>," : ""}
 };
 
 @vertex
-fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(1) normal: vec3<f32>, @location(2) uv: vec2<f32>${usesTangent ? ", @location(3) tangent: vec4<f32>" : ""}) -> VertexOutput {
+fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(1) normal: vec3<f32>, @location(2) uv: vec2<f32>${usesTangent ? ", @location(3) tangent: vec4<f32>" : ""}${atlas ? ", @location(4) color: vec4<f32>, @location(7) uv1: vec2<f32>" : ""}) -> VertexOutput {
   var output: VertexOutput;
   let worldPosition = (u_draw.instance0 * vec4<f32>(position, 1.0)).xyz;
   output.position = a3dWebGPUClipPosition(u_draw.modelViewProjection * vec4<f32>(position, 1.0));
   output.normal = normalize((u_draw.normalMatrix * vec4<f32>(normal, 0.0)).xyz);
   output.uv = uv;
+  ${atlas ? "output.uv1 = uv1; output.color = color;" : ""}
   output.worldPosition = worldPosition;
   ${usesTangent ? "output.tangent = vec4<f32>(normalize((u_draw.normalMatrix * vec4<f32>(tangent.xyz, 0.0)).xyz), tangent.w);" : "output.tangent = vec4<f32>(1.0, 0.0, 0.0, 1.0);"}
   return output;
 }
 `,
-        fragment: `${nativePbrFragmentPrelude(marker)}
+        fragment: `${nativePbrFragmentPrelude(marker, atlas)}
 @fragment
 fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
-  return shadePbr(input.normal, input.tangent, input.uv, input.worldPosition, input.position.xy);
+  return shadePbr(input.normal, input.tangent, input.uv, input.worldPosition, input.position.xy${atlas ? ", input.uv1, input.color" : ""});
 }
 `
     };
@@ -2615,13 +3394,27 @@ fn instanceMatrix(index: u32) -> mat4x4<f32> {
   return u_draw.instance0;
 }
 
+fn a3dInstanceNormalMatrix(model: mat4x4<f32>) -> mat3x3<f32> {
+  // GLSL parity: v_normal = u_normalMatrix * transpose(inverse(mat3(instance))) * a_normal.
+  let m = mat3x3<f32>(model[0].xyz, model[1].xyz, model[2].xyz);
+  let adj0 = cross(m[1], m[2]);
+  let adj1 = cross(m[2], m[0]);
+  let adj2 = cross(m[0], m[1]);
+  let det = dot(m[0], adj0);
+  let safeDet = select(det, 1.0, abs(det) < 0.00001);
+  return mat3x3<f32>(
+    vec3<f32>(adj0.x, adj1.x, adj2.x) / safeDet,
+    vec3<f32>(adj0.y, adj1.y, adj2.y) / safeDet,
+    vec3<f32>(adj0.z, adj1.z, adj2.z) / safeDet);
+}
+
 @vertex
 fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(1) normal: vec3<f32>, @builtin(instance_index) instanceIndex: u32) -> VertexOutput {
   var output: VertexOutput;
   let model = instanceMatrix(instanceIndex);
-  let worldPosition = (model * vec4<f32>(position, 1.0)).xyz;
+  let worldPosition = (u_draw.modelMatrix * model * vec4<f32>(position, 1.0)).xyz;
   output.position = a3dWebGPUClipPosition(u_draw.modelViewProjection * model * vec4<f32>(position, 1.0));
-  output.normal = normalize((model * vec4<f32>(normal, 0.0)).xyz);
+  output.normal = normalize((u_draw.normalMatrix * vec4<f32>(a3dInstanceNormalMatrix(model) * normal, 0.0)).xyz);
   output.uv = vec2<f32>(0.5, 0.5);
   output.worldPosition = worldPosition;
   output.tangent = vec4<f32>(1.0, 0.0, 0.0, 1.0);