@codexo/exojs 0.9.0 → 0.11.0

package/dist/esm/rendering/webgpu/WebGpuMeshRenderer.js

@@ -3,7 +3,9 @@ import { Texture } from '../texture/Texture.js';
 import { BlendModes } from '../types.js';
 import { AbstractWebGpuRenderer } from './AbstractWebGpuRenderer.js';
 import { getWebGpuBlendState } from './WebGpuBlendState.js';
+import { stencilContentDepthStencilState } from './WebGpuStencilState.js';
 
+/* eslint-disable max-lines */
 /// <reference types="@webgpu/types" />
 const meshShaderSource = `
 struct VertexInput {
@@ -47,6 +49,65 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
     return vec4<f32>(modulated.rgb * modulated.a, modulated.a);
 }
 `;
+const instancedMeshShaderSource = `
+struct VertexInput {
+    @location(0) position: vec2<f32>,
+    @location(1) texcoord: vec2<f32>,
+    @location(2) color: vec4<f32>,
+    @location(6) nodeIndex: u32,
+};
+
+struct VertexOutput {
+    @builtin(position) position: vec4<f32>,
+    @location(0) texcoord: vec2<f32>,
+    @location(1) color: vec4<f32>,
+    @location(2) tint: vec4<f32>,
+    @location(3) @interpolate(flat) premultiplySample: u32,
+};
+
+struct TransformSlot {
+    m0: vec4<f32>,
+    m1: vec4<f32>,
+    m2: vec4<f32>,
+};
+
+struct TransformUniforms {
+    projection: mat3x3<f32>,
+    flags: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> uniforms: TransformUniforms;
+@group(0) @binding(1) var<storage, read> transforms: array<TransformSlot>;
+
+@group(1) @binding(0) var meshTexture: texture_2d<f32>;
+@group(1) @binding(1) var meshSampler: sampler;
+
+@vertex
+fn vertexMain(input: VertexInput) -> VertexOutput {
+    let slot = transforms[input.nodeIndex];
+    let world = vec3<f32>(
+        slot.m0.x * input.position.x + slot.m0.z * input.position.y + slot.m1.x,
+        slot.m0.y * input.position.x + slot.m0.w * input.position.y + slot.m1.y,
+        1.0
+    );
+
+    var output: VertexOutput;
+    output.position = vec4<f32>((uniforms.projection * world).xy, 0.0, 1.0);
+    output.texcoord = input.texcoord;
+    output.color = input.color;
+    output.tint = slot.m2;
+    output.premultiplySample = u32(uniforms.flags.x);
+    return output;
+}
+
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
+    let sample = textureSample(meshTexture, meshSampler, input.texcoord);
+    let resolvedSample = select(sample, vec4(sample.rgb * sample.a, sample.a), input.premultiplySample == 1u);
+    let modulated = resolvedSample * input.color * input.tint;
+    return vec4<f32>(modulated.rgb * modulated.a, modulated.a);
+}
+`;
 // Per-vertex layout (20 bytes): pos f32x2 + uv f32x2 + color u8x4-norm.
 // Default-shader path bakes the (view * globalTransform) into position so the
 // vertex shader stays branchless and uniform-free except for the per-mesh tint.
@@ -55,29 +116,53 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
 const vertexStrideBytes = 20;
 const wordsPerVertex = vertexStrideBytes / 4;
 const tintByteLength = 32; // vec4 tint + vec4 flags (only flags.x used)
+const transformUniformByteLength = 64; // mat3x3<f32> (48B) + vec4<f32> flags (16B)
 // Custom-shader uniform layout:
 //   mat3x3<f32> projection   — 48 bytes (3 vec3 columns padded to vec4 in WGSL)
 //   mat3x3<f32> translation  — 48 bytes
 //   vec4<f32>   tint         — 16 bytes
 // Total: 112 bytes; aligned up to 256 for dynamic offset.
 const customMeshUniformBytes = 112;
+/**
+ * Cache key for the default + instanced (static-batch) pipeline maps. The
+ * stencil dimension keeps the clip and no-clip variants distinct, mirroring the
+ * sprite renderer: a stencil pipeline carries depth/stencil state and is only
+ * valid in a pass with the matching attachment, so the two are never
+ * interchangeable.
+ */
+function meshPipelineCacheKey(blendMode, format, stencil) {
+    return `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
+}
 const meshUniformAlignment = 256;
 const maxCustomTextureSlots = 7; // user texture uniforms; group 2 binding 1..N
 class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
     _combinedTransform = new Matrix();
     _drawCalls = [];
     _pipelines = new Map();
+    _instancedPipelines = new Map();
+    _staticGeometryCache = new Map();
     _textureBindGroups = new WeakMap();
     _customShaders = new Map();
     _device = null;
     _shaderModule = null;
+    _instancedShaderModule = null;
     _uniformBindGroupLayout = null;
+    _instancedTransformBindGroupLayout = null;
     _textureBindGroupLayout = null;
     _pipelineLayout = null;
+    _instancedPipelineLayout = null;
     _vertexBuffer = null;
     _indexBuffer = null;
     _uniformBuffer = null;
     _uniformBindGroup = null;
+    _instancedUniformBuffer = null;
+    _instancedUniformBufferCapacity = 0;
+    _instancedUniformScratch = new Float32Array(transformUniformByteLength / Float32Array.BYTES_PER_ELEMENT);
+    _instancedNodeIndexBuffer = null;
+    _instancedNodeIndexBufferCapacity = 0;
+    _instancedNodeIndexData = new Uint32Array(0);
+    _instancedTransformBindGroup = null;
+    _instancedTransformStorageBuffer = null;
     _uniformAlignment = 256;
     _vertexBufferCapacity = 0;
     _indexBufferCapacity = 0;
@@ -92,17 +177,21 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         if (backend === null) {
             throw new Error('WebGpuMeshRenderer is not connected to a backend.');
         }
-        const customShader = mesh.shader;
-        if (customShader !== null && customShader.wgsl === null) {
-            throw new Error('MeshShader has no `wgsl` source; cannot render through the WebGPU backend.');
+        const customShader = mesh.material;
+        if (customShader !== null && customShader.shader.wgsl === null) {
+            throw new Error('Mesh material shader has no `wgsl` source; cannot render through the WebGPU backend.');
         }
         const vertexCount = mesh.vertexCount;
         if (vertexCount === 0) {
             return;
         }
-        const blendMode = mesh.blendMode;
+        // The material owns its blend mode; the mesh's own blendMode overrides it
+        // when set away from the default (Normal). Default-path meshes keep their
+        // own blendMode verbatim.
+        const blendMode = customShader !== null && mesh.blendMode === BlendModes.Normal ? customShader.blendMode : mesh.blendMode;
         backend.setBlendMode(blendMode);
         const meshTexture = mesh.texture ?? Texture.white;
+        const command = backend.activeDrawCommand;
         // backend.shouldPremultiplyTextureSample expects RenderTexture-or-Texture.
         // Both branches are valid here. Premultiply flag is ignored by custom
         // shaders (they handle premultiplication themselves), but we still record
@@ -123,6 +212,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         const drawCall = {
             mesh,
             customShader,
+            command,
             blendMode,
             texture: meshTexture,
             premultiplySample,
@@ -151,13 +241,8 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             // Honor a pending clear with an empty pass so createColorAttachment
             // consumes the clear-state once.
             if (backend.clearRequested) {
-                const encoder = device.createCommandEncoder();
-                const pass = encoder.beginRenderPass({
-                    colorAttachments: [backend.createColorAttachment()],
-                });
-                backend.stats.renderPasses++;
-                pass.end();
-                backend.submit(encoder.finish());
+                backend._passCoordinator.acquirePass();
+                backend._passCoordinator.endPass();
             }
             this._resetFrame();
             return;
@@ -166,7 +251,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         // buffers, so default offsets are independent of custom offsets).
         let defaultVertices = 0;
         let defaultIndices = 0;
-        const customVertexCursors = new Map(); // running vertex count per shader
+        const customVertexCursors = new Map(); // running vertex count per material
         const customIndexCursors = new Map();
         for (let i = 0; i < this._drawCallCount; i++) {
             const dc = this._drawCalls[i];
@@ -192,6 +277,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         // each custom-shader resource manages its own.
         const defaultDrawCalls = this._drawCallCount - this._totalCustomDraws();
         this._ensureUniformCapacity(defaultDrawCalls);
+        this._ensureInstancedUniformCapacity(this._drawCallCount);
         // Phase 3: pack default-path vertex/index/uniform data.
         const defaultUniformBytes = defaultDrawCalls * this._uniformAlignment;
         const defaultUniformData = defaultUniformBytes > 0 ? new ArrayBuffer(defaultUniformBytes) : null;
@@ -211,13 +297,17 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                         this._packedIndexData[start + j] = j;
                     }
                 }
-                // Pack tint+flags for default path.
+                // Pack tint+flags for default path. Color RGB channels are 0..255; the
+                // shader multiplies the sampled texel by this tint, so normalize to
+                // 0..1 (matching TransformBuffer and the WebGL2 mesh shader). Leaving
+                // them at 0..255 scales every non-zero texel channel past 1.0, which
+                // clamps intermediate colors (gradients, photos) to full saturation.
                 if (defaultUniformF32 !== null) {
                     const offsetWords = (defaultUniformIndex * this._uniformAlignment) / Float32Array.BYTES_PER_ELEMENT;
                     const tint = dc.mesh.tint;
-                    defaultUniformF32[offsetWords + 0] = tint.r;
-                    defaultUniformF32[offsetWords + 1] = tint.g;
-                    defaultUniformF32[offsetWords + 2] = tint.b;
+                    defaultUniformF32[offsetWords + 0] = tint.r / 255;
+                    defaultUniformF32[offsetWords + 1] = tint.g / 255;
+                    defaultUniformF32[offsetWords + 2] = tint.b / 255;
                     defaultUniformF32[offsetWords + 3] = tint.a;
                     defaultUniformF32[offsetWords + 4] = dc.premultiplySample ? 1 : 0;
                     defaultUniformF32[offsetWords + 5] = 0;
@@ -227,8 +317,8 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 defaultUniformIndex++;
             }
         }
-        // Phase 3b: pack custom-path vertex/index/uniform data per shader.
-        for (const [shader, resources] of this._customShaders) {
+        // Phase 3b: pack custom-path vertex/index/uniform data per material.
+        for (const [material, resources] of this._customShaders) {
             if (resources.drawCount === 0) {
                 continue;
             }
@@ -239,7 +329,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             let drawCursor = 0;
             for (let i = 0; i < this._drawCallCount; i++) {
                 const dc = this._drawCalls[i];
-                if (dc.customShader !== shader)
+                if (dc.customShader !== material)
                     continue;
                 this._writeMeshVerticesIntoBuffer(dc.mesh, vWritten, resources.vertexFloatView, resources.vertexUintView);
                 if (dc.mesh.indices !== null) {
@@ -251,50 +341,85 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                     }
                 }
                 // Write mesh-uniform slot (proj/trans/tint) with dynamic offset.
-                this._writeCustomMeshUniform(shader, resources, drawCursor, dc.mesh, backend);
+                this._writeCustomMeshUniform(material, resources, drawCursor, dc.mesh, backend);
                 vWritten += dc.vertexCount;
                 iWritten += dc.indexCount;
                 drawCursor++;
             }
             device.queue.writeBuffer(resources.vertexBuffer, 0, resources.vertexData, 0, resources.totalVertices * vertexStrideBytes);
-            device.queue.writeBuffer(resources.indexBuffer, 0, resources.indexData.buffer, resources.indexData.byteOffset, resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT);
-            // Build/refresh user uniform UBO from shader.uniforms (re-built every
-            // frame so mutations to shader.uniforms.X are picked up).
-            this._uploadUserUniforms(shader, resources);
+            device.queue.writeBuffer(resources.indexBuffer, 0, resources.indexData.buffer, resources.indexData.byteOffset, (resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT + 3) & -4);
+            // Build/refresh user uniform UBO from the material (re-built every frame
+            // so mutations to material.uniforms.X are picked up).
+            this._uploadUserUniforms(material, resources);
         }
         // Phase 4: single writeBuffer per resource for the default path.
         if (defaultVertices > 0) {
             device.queue.writeBuffer(this._vertexBuffer, 0, this._vertexData, 0, defaultVertices * vertexStrideBytes);
-            device.queue.writeBuffer(this._indexBuffer, 0, this._packedIndexData.buffer, this._packedIndexData.byteOffset, defaultIndices * Uint16Array.BYTES_PER_ELEMENT);
+            device.queue.writeBuffer(this._indexBuffer, 0, this._packedIndexData.buffer, this._packedIndexData.byteOffset, (defaultIndices * Uint16Array.BYTES_PER_ELEMENT + 3) & -4);
         }
         if (defaultUniformData !== null) {
             device.queue.writeBuffer(this._uniformBuffer, 0, defaultUniformData, 0, defaultUniformBytes);
         }
         // Phase 5: single render pass with one drawIndexed per mesh, switching
-        // pipeline+bind groups between default and custom paths as needed.
-        const encoder = device.createCommandEncoder({ label: 'WebGpuMeshRenderer' });
-        const pass = encoder.beginRenderPass({
-            colorAttachments: [backend.createColorAttachment()],
-            label: 'WebGpuMeshRenderer pass',
-        });
-        backend.stats.renderPasses++;
-        if (scissor !== null) {
-            pass.setScissorRect(scissor.x, scissor.y, scissor.width, scissor.height);
-        }
+        // pipeline+bind groups between default and custom paths as needed. The
+        // coordinator owns the GPU pass (load/clear resolution, pass count and
+        // scissor are applied there) and ends + submits it below.
+        const pass = backend._passCoordinator.acquirePass().pass;
         const renderTargetFormat = backend.renderTargetFormat;
+        // A clip scope flushes the active renderer on push/pop, so every draw call
+        // in this batch shares one stencil state — read it once. While active, the
+        // coordinator's pass carries a depth/stencil attachment, so the default,
+        // static-batch, and custom-material pipelines must all select their
+        // stencil-enabled variants to match it.
+        const stencil = backend._passCoordinator.stencilActive;
         let lastShader = null;
         let lastBlendMode = null;
         let lastFormat = null;
         let lastTexture = null;
         let defaultDrawCursor = 0;
+        let instancedDrawCursor = 0;
         const customDrawCursors = new Map();
         for (let i = 0; i < this._drawCallCount; i++) {
             const dc = this._drawCalls[i];
             if (dc.customShader === null) {
+                const batchLength = this._getStaticBatchLength(i);
+                if (batchLength >= 2) {
+                    const needsPipeline = lastShader !== 'instanced' || dc.blendMode !== lastBlendMode || renderTargetFormat !== lastFormat;
+                    if (needsPipeline) {
+                        pass.setPipeline(this._getInstancedPipeline({ blendMode: dc.blendMode, format: renderTargetFormat, stencil }));
+                        lastShader = 'instanced';
+                        lastBlendMode = dc.blendMode;
+                        lastFormat = renderTargetFormat;
+                        lastTexture = null;
+                    }
+                    const maxNodeIndex = this._uploadInstancedNodeIndices(i, batchLength);
+                    const storage = backend.getTransformStorageBuffer(maxNodeIndex + 1);
+                    this._writeInstancedUniformSlot(instancedDrawCursor, backend, dc.premultiplySample);
+                    pass.setBindGroup(0, this._getOrCreateInstancedTransformBindGroup(storage.buffer), [instancedDrawCursor * this._uniformAlignment]);
+                    if (dc.texture !== lastTexture) {
+                        lastTexture = dc.texture;
+                        pass.setBindGroup(1, this._getTextureBindGroup(backend, dc.texture));
+                    }
+                    const staticGeometry = this._getOrCreateStaticGeometryEntry(dc.mesh);
+                    const instanceNodeIndexBuffer = this._instancedNodeIndexBuffer;
+                    if (instanceNodeIndexBuffer === null) {
+                        throw new Error('Instanced node-index buffer must be initialized before drawing.');
+                    }
+                    pass.setVertexBuffer(0, staticGeometry.vertexBuffer);
+                    pass.setVertexBuffer(1, instanceNodeIndexBuffer);
+                    pass.setIndexBuffer(staticGeometry.indexBuffer, 'uint16');
+                    pass.drawIndexed(staticGeometry.indexCount, batchLength);
+                    backend.stats.batches++;
+                    backend.stats.drawCalls++;
+                    defaultDrawCursor += batchLength;
+                    instancedDrawCursor++;
+                    i += batchLength - 1;
+                    continue;
+                }
                 // ----- Default path -----
                 const needsPipeline = lastShader !== 'default' || dc.blendMode !== lastBlendMode || renderTargetFormat !== lastFormat;
                 if (needsPipeline) {
-                    pass.setPipeline(this._getPipeline({ blendMode: dc.blendMode, format: renderTargetFormat }));
+                    pass.setPipeline(this._getPipeline({ blendMode: dc.blendMode, format: renderTargetFormat, stencil }));
                     lastShader = 'default';
                     lastBlendMode = dc.blendMode;
                     lastFormat = renderTargetFormat;
@@ -319,9 +444,9 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 // (Spector.js, Chrome DevTools' WebGPU panel) show meaningful
                 // labels for the otherwise-anonymous mesh draws inside the
                 // batched render pass.
-                pass.pushDebugGroup('MeshShader (custom)');
+                pass.pushDebugGroup('MeshMaterial (custom)');
                 if (needsPipeline) {
-                    pass.setPipeline(this._getOrCreateCustomPipeline(resources, dc.blendMode, renderTargetFormat));
+                    pass.setPipeline(this._getOrCreateCustomPipeline(resources, dc.blendMode, renderTargetFormat, stencil));
                     lastShader = dc.customShader;
                     lastBlendMode = dc.blendMode;
                     lastFormat = renderTargetFormat;
@@ -344,8 +469,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             backend.stats.batches++;
             backend.stats.drawCalls++;
         }
-        pass.end();
-        backend.submit(encoder.finish());
+        backend._passCoordinator.endPass();
         this._resetFrame();
     }
     destroy() {
@@ -372,12 +496,20 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         const promises = [];
         for (const blendMode of blendModes) {
             for (const format of formats) {
-                const key = `${blendMode}:${format}`;
+                // Prewarm only the no-clip variants; the stencil pipelines are created
+                // lazily on the first clipped draw (a rare path not worth the upfront
+                // compile cost for every blend-mode × format combination).
+                const key = meshPipelineCacheKey(blendMode, format, false);
                 if (this._pipelines.has(key))
                     continue;
                 promises.push(device.createRenderPipelineAsync(this._buildPipelineDescriptor(blendMode, format)).then(pipeline => {
                     this._pipelines.set(key, pipeline);
                 }));
+                if (!this._instancedPipelines.has(key)) {
+                    promises.push(device.createRenderPipelineAsync(this._buildInstancedPipelineDescriptor(blendMode, format)).then(pipeline => {
+                        this._instancedPipelines.set(key, pipeline);
+                    }));
+                }
             }
         }
         await Promise.all(promises);
@@ -388,6 +520,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
         this._device = backend.device;
         this._shaderModule = this._device.createShaderModule({ code: meshShaderSource });
+        this._instancedShaderModule = this._device.createShaderModule({ code: instancedMeshShaderSource });
         this._uniformBindGroupLayout = this._device.createBindGroupLayout({
             entries: [
                 {
@@ -414,27 +547,59 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         this._pipelineLayout = this._device.createPipelineLayout({
             bindGroupLayouts: [this._uniformBindGroupLayout, this._textureBindGroupLayout],
         });
+        this._instancedTransformBindGroupLayout = this._device.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    buffer: { type: 'uniform', hasDynamicOffset: true },
+                },
+                {
+                    binding: 1,
+                    visibility: GPUShaderStage.VERTEX,
+                    buffer: { type: 'read-only-storage' },
+                },
+            ],
+        });
+        this._instancedPipelineLayout = this._device.createPipelineLayout({
+            bindGroupLayouts: [this._instancedTransformBindGroupLayout, this._textureBindGroupLayout],
+        });
     }
     onDisconnect() {
         this.flush();
         this._vertexBuffer?.destroy();
         this._indexBuffer?.destroy();
         this._uniformBuffer?.destroy();
+        this._instancedUniformBuffer?.destroy();
+        this._instancedNodeIndexBuffer?.destroy();
         this._pipelines.clear();
+        this._instancedPipelines.clear();
         this._textureBindGroups = new WeakMap();
+        for (const entry of this._staticGeometryCache.values()) {
+            entry.vertexBuffer.destroy();
+            entry.indexBuffer.destroy();
+        }
+        this._staticGeometryCache.clear();
         this._vertexBuffer = null;
         this._indexBuffer = null;
         this._uniformBuffer = null;
         this._uniformBindGroup = null;
+        this._instancedUniformBuffer = null;
+        this._instancedNodeIndexBuffer = null;
+        this._instancedTransformBindGroup = null;
+        this._instancedTransformStorageBuffer = null;
         this._pipelineLayout = null;
+        this._instancedPipelineLayout = null;
         this._textureBindGroupLayout = null;
         this._uniformBindGroupLayout = null;
+        this._instancedTransformBindGroupLayout = null;
         this._shaderModule = null;
-        // Custom shaders are owned by user code (one MeshShader can be shared
+        this._instancedShaderModule = null;
+        // Custom materials are owned by user code (one MeshMaterial can be shared
         // across multiple Mesh instances). Their resources are released when the
-        // user calls shader.destroy(), which fires our _onDispose callback. On
+        // user calls material.destroy(), which fires our _onDispose callback. On
         // backend disconnect we eagerly release everything to avoid GPU leaks
-        // even if the user keeps the shader reference around.
+        // even if the user keeps the material reference around.
         for (const resources of this._customShaders.values()) {
             this._releaseCustomShaderResources(resources);
         }
@@ -445,6 +610,9 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         this._vertexBufferCapacity = 0;
         this._indexBufferCapacity = 0;
         this._uniformBufferCapacity = 0;
+        this._instancedUniformBufferCapacity = 0;
+        this._instancedNodeIndexBufferCapacity = 0;
+        this._instancedNodeIndexData = new Uint32Array(0);
     }
     // ---------------------------------------------------------------------------
     // Default-path helpers
@@ -490,16 +658,16 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
     }
     _getPipeline(key) {
-        const cacheKey = `${key.blendMode}:${key.format}`;
+        const cacheKey = meshPipelineCacheKey(key.blendMode, key.format, key.stencil);
         let pipeline = this._pipelines.get(cacheKey);
         if (!pipeline) {
-            pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(key.blendMode, key.format));
+            pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(key.blendMode, key.format, key.stencil));
             this._pipelines.set(cacheKey, pipeline);
         }
         return pipeline;
     }
-    _buildPipelineDescriptor(blendMode, format) {
-        return {
+    _buildPipelineDescriptor(blendMode, format, stencil = false) {
+        const descriptor = {
             layout: this._pipelineLayout,
             vertex: {
                 module: this._shaderModule,
@@ -532,6 +700,10 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 cullMode: 'none',
             },
         };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        return descriptor;
     }
     _getTextureBindGroup(backend, texture) {
         let group = this._textureBindGroups.get(texture);
@@ -548,6 +720,227 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
         return group;
     }
+    _getStaticBatchLength(startIndex) {
+        const first = this._drawCalls[startIndex];
+        if (!this._isStaticBatchCandidate(first)) {
+            return 1;
+        }
+        let length = 1;
+        for (let i = startIndex + 1; i < this._drawCallCount; i++) {
+            const next = this._drawCalls[i];
+            if (!this._isSameStaticBatch(first, next)) {
+                break;
+            }
+            length++;
+        }
+        return length;
+    }
+    _isStaticBatchCandidate(drawCall) {
+        const command = drawCall.command;
+        return drawCall.customShader === null && command?.groupIndex !== undefined && drawCall.mesh.geometry?.usage === 'static';
+    }
+    _isSameStaticBatch(left, right) {
+        if (!this._isStaticBatchCandidate(left) || !this._isStaticBatchCandidate(right)) {
+            return false;
+        }
+        return (left.command.groupIndex === right.command.groupIndex &&
+            left.mesh.geometry === right.mesh.geometry &&
+            left.texture === right.texture &&
+            left.blendMode === right.blendMode &&
+            left.command.material.pipelineKey === right.command.material.pipelineKey &&
+            left.command.material.bindKey === right.command.material.bindKey);
+    }
+    _uploadInstancedNodeIndices(startIndex, batchLength) {
+        this._ensureInstancedNodeIndexCapacity(batchLength);
+        let maxNodeIndex = 0;
+        for (let i = 0; i < batchLength; i++) {
+            const nodeIndex = this._drawCalls[startIndex + i].command.nodeIndex >>> 0;
+            this._instancedNodeIndexData[i] = nodeIndex;
+            if (nodeIndex > maxNodeIndex) {
+                maxNodeIndex = nodeIndex;
+            }
+        }
+        this._device.queue.writeBuffer(this._instancedNodeIndexBuffer, 0, this._instancedNodeIndexData.buffer, this._instancedNodeIndexData.byteOffset, batchLength * Uint32Array.BYTES_PER_ELEMENT);
+        return maxNodeIndex;
+    }
+    _ensureInstancedNodeIndexCapacity(instanceCount) {
+        const requiredBytes = instanceCount * Uint32Array.BYTES_PER_ELEMENT;
+        if (this._instancedNodeIndexData.length < instanceCount) {
+            this._instancedNodeIndexData = new Uint32Array(Math.max(instanceCount, this._instancedNodeIndexData.length * 2 || 1));
+        }
+        if (requiredBytes > this._instancedNodeIndexBufferCapacity) {
+            this._instancedNodeIndexBuffer?.destroy();
+            this._instancedNodeIndexBufferCapacity = Math.max(requiredBytes, this._instancedNodeIndexBufferCapacity * 2 || Uint32Array.BYTES_PER_ELEMENT);
+            this._instancedNodeIndexBuffer = this._device.createBuffer({
+                size: this._instancedNodeIndexBufferCapacity,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+        }
+    }
+    _ensureInstancedUniformCapacity(drawCallCount) {
+        if (drawCallCount === 0) {
+            return;
+        }
+        const requiredBytes = drawCallCount * this._uniformAlignment;
+        if (requiredBytes > this._instancedUniformBufferCapacity) {
+            this._instancedUniformBuffer?.destroy();
+            this._instancedUniformBufferCapacity = Math.max(requiredBytes, this._instancedUniformBufferCapacity * 2 || this._uniformAlignment);
+            this._instancedUniformBuffer = this._device.createBuffer({
+                size: this._instancedUniformBufferCapacity,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            this._instancedTransformBindGroup = null;
+            this._instancedTransformStorageBuffer = null;
+        }
+    }
+    _writeInstancedUniformSlot(slot, backend, premultiplySample) {
+        const data = this._instancedUniformScratch;
+        const projection = backend.view.getTransform();
+        data.fill(0);
+        data[0] = projection.a;
+        data[1] = projection.b;
+        data[4] = projection.c;
+        data[5] = projection.d;
+        data[8] = projection.x;
+        data[9] = projection.y;
+        data[10] = 1;
+        data[12] = premultiplySample ? 1 : 0;
+        this._device.queue.writeBuffer(this._instancedUniformBuffer, slot * this._uniformAlignment, data.buffer, data.byteOffset, transformUniformByteLength);
+    }
+    _getOrCreateInstancedTransformBindGroup(storageBuffer) {
+        if (this._instancedTransformBindGroup !== null && this._instancedTransformStorageBuffer === storageBuffer) {
+            return this._instancedTransformBindGroup;
+        }
+        this._instancedTransformStorageBuffer = storageBuffer;
+        this._instancedTransformBindGroup = this._device.createBindGroup({
+            layout: this._instancedTransformBindGroupLayout,
+            entries: [
+                {
+                    binding: 0,
+                    resource: {
+                        buffer: this._instancedUniformBuffer,
+                        size: transformUniformByteLength,
+                    },
+                },
+                {
+                    binding: 1,
+                    resource: {
+                        buffer: storageBuffer,
+                    },
+                },
+            ],
+        });
+        return this._instancedTransformBindGroup;
+    }
+    _getInstancedPipeline(key) {
+        const cacheKey = meshPipelineCacheKey(key.blendMode, key.format, key.stencil);
+        let pipeline = this._instancedPipelines.get(cacheKey);
+        if (!pipeline) {
+            pipeline = this._device.createRenderPipeline(this._buildInstancedPipelineDescriptor(key.blendMode, key.format, key.stencil));
+            this._instancedPipelines.set(cacheKey, pipeline);
+        }
+        return pipeline;
+    }
+    _buildInstancedPipelineDescriptor(blendMode, format, stencil = false) {
+        const descriptor = {
+            layout: this._instancedPipelineLayout,
+            vertex: {
+                module: this._instancedShaderModule,
+                entryPoint: 'vertexMain',
+                buffers: [
+                    {
+                        arrayStride: vertexStrideBytes,
+                        stepMode: 'vertex',
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: 'float32x2' },
+                            { shaderLocation: 1, offset: 8, format: 'float32x2' },
+                            { shaderLocation: 2, offset: 16, format: 'unorm8x4' },
+                        ],
+                    },
+                    {
+                        arrayStride: Uint32Array.BYTES_PER_ELEMENT,
+                        stepMode: 'instance',
+                        attributes: [{ shaderLocation: 6, offset: 0, format: 'uint32' }],
+                    },
+                ],
+            },
+            fragment: {
+                module: this._instancedShaderModule,
+                entryPoint: 'fragmentMain',
+                targets: [
+                    {
+                        format,
+                        blend: getWebGpuBlendState(blendMode),
+                        writeMask: GPUColorWrite.ALL,
+                    },
+                ],
+            },
+            primitive: {
+                topology: 'triangle-list',
+                cullMode: 'none',
+            },
+        };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        return descriptor;
+    }
+    _getOrCreateStaticGeometryEntry(mesh) {
+        const geometry = mesh.geometry;
+        if (geometry?.usage !== 'static') {
+            throw new Error('Static mesh batching requires Geometry with usage="static".');
+        }
+        const existing = this._staticGeometryCache.get(geometry);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const vertexData = new ArrayBuffer(mesh.vertexCount * vertexStrideBytes);
+        const vertexFloatView = new Float32Array(vertexData);
+        const vertexUintView = new Uint32Array(vertexData);
+        this._writeMeshVerticesIntoBuffer(mesh, 0, vertexFloatView, vertexUintView);
+        // Allocate one extra element when indexCount is odd so the GPU buffer and
+        // writeBuffer byte count can be rounded up to 4 without a buffer overread.
+        const indexData = new Uint16Array(mesh.indexCount + (mesh.indexCount & 1));
+        if (mesh.indices !== null) {
+            indexData.set(mesh.indices, 0);
+        }
+        else {
+            for (let i = 0; i < mesh.indexCount; i++) {
+                indexData[i] = i;
+            }
+        }
+        const indexByteLen = mesh.indexCount * Uint16Array.BYTES_PER_ELEMENT;
+        const alignedIndexByteLen = (indexByteLen + 3) & -4;
+        const vertexBuffer = this._device.createBuffer({
+            size: vertexData.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        const indexBuffer = this._device.createBuffer({
+            size: alignedIndexByteLen,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        this._device.queue.writeBuffer(vertexBuffer, 0, vertexData, 0, vertexData.byteLength);
+        this._device.queue.writeBuffer(indexBuffer, 0, indexData.buffer, indexData.byteOffset, alignedIndexByteLen);
+        const disposeListener = () => {
+            const entry = this._staticGeometryCache.get(geometry);
+            if (entry === undefined) {
+                return;
+            }
+            entry.vertexBuffer.destroy();
+            entry.indexBuffer.destroy();
+            this._staticGeometryCache.delete(geometry);
+        };
+        geometry._onDispose(disposeListener);
+        const created = {
+            geometry,
+            vertexBuffer,
+            indexBuffer,
+            indexCount: mesh.indexCount,
+            disposeListener,
+        };
+        this._staticGeometryCache.set(geometry, created);
+        return created;
+    }
     _ensureVertexCapacity(vertexCount) {
         const requiredBytes = vertexCount * vertexStrideBytes;
         if (requiredBytes > this._vertexData.byteLength) {
@@ -566,13 +959,16 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
     }
     _ensureIndexCapacity(indexCount) {
-        const requiredBytes = indexCount * Uint16Array.BYTES_PER_ELEMENT;
-        if (this._packedIndexData.length < indexCount) {
-            this._packedIndexData = new Uint16Array(Math.max(indexCount, this._packedIndexData.length === 0 ? 1 : this._packedIndexData.length * 2));
+        // GPUQueue.writeBuffer requires the byte count to be a multiple of 4.
+        // Round up: odd Uint16 counts (e.g. a 3-index triangle) would otherwise
+        // produce 6-byte writes which the WebGPU validation layer rejects.
+        const requiredBytes = (indexCount * Uint16Array.BYTES_PER_ELEMENT + 3) & -4;
+        if (this._packedIndexData.length * Uint16Array.BYTES_PER_ELEMENT < requiredBytes) {
+            this._packedIndexData = new Uint16Array(Math.max(requiredBytes / Uint16Array.BYTES_PER_ELEMENT, this._packedIndexData.length === 0 ? 2 : this._packedIndexData.length * 2));
         }
         if (requiredBytes > this._indexBufferCapacity) {
             this._indexBuffer?.destroy();
-            this._indexBufferCapacity = Math.max(requiredBytes, this._indexBufferCapacity === 0 ? Uint16Array.BYTES_PER_ELEMENT : this._indexBufferCapacity * 2);
+            this._indexBufferCapacity = Math.max(requiredBytes, this._indexBufferCapacity === 0 ? 4 : this._indexBufferCapacity * 2);
             this._indexBuffer = this._device.createBuffer({
                 size: this._indexBufferCapacity,
                 usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
@@ -620,19 +1016,19 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             resources.totalIndices = 0;
         }
     }
-    _getOrCreateCustomShaderResources(shader) {
-        let resources = this._customShaders.get(shader);
+    _getOrCreateCustomShaderResources(material) {
+        let resources = this._customShaders.get(material);
         if (resources !== undefined) {
             return resources;
         }
         if (this._device === null) {
             throw new Error('WebGpuMeshRenderer is not connected to a backend.');
         }
-        if (shader.wgsl === null) {
-            throw new Error('MeshShader has no `wgsl` source; cannot render through the WebGPU backend.');
+        if (material.shader.wgsl === null) {
+            throw new Error('Mesh material shader has no `wgsl` source; cannot render through the WebGPU backend.');
         }
         const device = this._device;
-        const shaderModule = device.createShaderModule({ code: shader.wgsl });
+        const shaderModule = device.createShaderModule({ code: material.shader.wgsl });
         const meshUniformLayout = device.createBindGroupLayout({
             entries: [
                 {
@@ -648,7 +1044,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
             ],
         });
-        const userLayout = this._buildUserBindGroupLayout(device, shader);
+        const userLayout = this._buildUserBindGroupLayout(device, material);
         const pipelineLayout = device.createPipelineLayout({
             bindGroupLayouts: [meshUniformLayout, meshTextureLayout, userLayout],
         });
@@ -687,13 +1083,13 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             totalVertices: 0,
             totalIndices: 0,
         };
-        this._customShaders.set(shader, resources);
-        // When the user calls shader.destroy(), evict and release.
-        shader._onDispose(() => {
-            const r = this._customShaders.get(shader);
+        this._customShaders.set(material, resources);
+        // When the user calls material.destroy(), evict and release.
+        material._onDispose(() => {
+            const r = this._customShaders.get(material);
             if (r !== undefined) {
                 this._releaseCustomShaderResources(r);
-                this._customShaders.delete(shader);
+                this._customShaders.delete(material);
             }
         });
         return resources;
@@ -716,14 +1112,14 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
             });
         }
-        // Index buffer
-        const indexBytes = resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT;
-        if (resources.indexData.length < resources.totalIndices) {
-            resources.indexData = new Uint16Array(Math.max(resources.totalIndices, resources.indexData.length * 2));
+        // Index buffer — capacity must be 4-byte aligned for GPUQueue.writeBuffer.
+        const indexBytes = (resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT + 3) & -4;
+        if (resources.indexData.length * Uint16Array.BYTES_PER_ELEMENT < indexBytes) {
+            resources.indexData = new Uint16Array(Math.max(indexBytes / Uint16Array.BYTES_PER_ELEMENT, resources.indexData.length * 2));
         }
         if (indexBytes > resources.indexBufferCapacity) {
             resources.indexBuffer?.destroy();
-            resources.indexBufferCapacity = Math.max(indexBytes, resources.indexBufferCapacity * 2 || Uint16Array.BYTES_PER_ELEMENT);
+            resources.indexBufferCapacity = Math.max(indexBytes, resources.indexBufferCapacity * 2 || 4);
             resources.indexBuffer = device.createBuffer({
                 size: resources.indexBufferCapacity,
                 usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
@@ -764,7 +1160,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             uintView[targetIndex + 4] = colors !== null ? colors[i] : 0xffffffff;
         }
     }
-    _writeCustomMeshUniform(_shader, resources, drawCursor, mesh, backend) {
+    _writeCustomMeshUniform(_material, resources, drawCursor, mesh, backend) {
         // Layout: mat3x3 projection (48B) + mat3x3 translation (48B) + vec4 tint (16B) = 112B.
         // WGSL mat3x3 stores 3 vec3 columns padded to vec4 alignment.
         const slotBytes = meshUniformAlignment;
@@ -809,19 +1205,24 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         data[off + 10] = 1;
         data[off + 11] = 0;
         off += 12;
-        // tint (vec4)
+        // tint (vec4). RGB are 0..255; normalize to 0..1 for the shader multiply
+        // (u_mesh.tint is documented as 0..1, matching the default path above).
         const tint = mesh.tint;
-        data[off + 0] = tint.r;
-        data[off + 1] = tint.g;
-        data[off + 2] = tint.b;
+        data[off + 0] = tint.r / 255;
+        data[off + 1] = tint.g / 255;
+        data[off + 2] = tint.b / 255;
         data[off + 3] = tint.a;
         this._device.queue.writeBuffer(resources.meshUniformBuffer, drawCursor * slotBytes, data);
     }
-    _getOrCreateCustomPipeline(resources, blendMode, format) {
-        const cacheKey = `${blendMode}:${format}`;
+    _getOrCreateCustomPipeline(resources, blendMode, format, stencil) {
+        // The stencil dimension keeps the clip and no-clip variants distinct,
+        // mirroring the default and static-batch caches: a stencil pipeline carries
+        // depth/stencil state and is only valid in a pass with the matching
+        // attachment, so the two are never interchangeable.
+        const cacheKey = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
         let pipeline = resources.pipelines.get(cacheKey);
         if (pipeline === undefined) {
-            pipeline = this._device.createRenderPipeline({
+            const descriptor = {
                 layout: resources.pipelineLayout,
                 vertex: {
                     module: resources.shaderModule,
@@ -853,7 +1254,14 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                     topology: 'triangle-list',
                     cullMode: 'none',
                 },
-            });
+            };
+            // While a geometric clip is active the coordinator's pass carries a
+            // depth/stencil attachment; the content pipeline must test stencil ==
+            // reference and leave depth/stencil otherwise inert to match it.
+            if (stencil) {
+                descriptor.depthStencil = stencilContentDepthStencilState();
+            }
+            pipeline = this._device.createRenderPipeline(descriptor);
             resources.pipelines.set(cacheKey, pipeline);
         }
         return pipeline;
@@ -873,10 +1281,8 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
         return group;
     }
-    _buildUserBindGroupLayout(device, shader) {
+    _buildUserBindGroupLayout(device, material) {
         const entries = [];
-        const userUniforms = shader.uniforms;
-        Object.values(userUniforms).some(v => !isTextureUniform(v));
         // Binding 0 always reserved for the user UBO (even if empty), so the
         // bind-group layout is stable across user-uniform mutations.
         entries.push({
@@ -884,15 +1290,12 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
             buffer: { type: 'uniform' },
         });
+        const textureBindings = collectTextureBindings(material);
+        if (textureBindings.length > maxCustomTextureSlots) {
+            throw new Error(`Mesh material requested more than ${maxCustomTextureSlots} user texture bindings.`);
+        }
         let bindingIndex = 1;
-        let textureCount = 0;
-        for (const value of Object.values(userUniforms)) {
-            if (!isTextureUniform(value)) {
-                continue;
-            }
-            if (textureCount >= maxCustomTextureSlots) {
-                throw new Error(`MeshShader requested more than ${maxCustomTextureSlots} user texture uniforms.`);
-            }
+        for (let t = 0; t < textureBindings.length; t++) {
             entries.push({
                 binding: bindingIndex,
                 visibility: GPUShaderStage.FRAGMENT,
@@ -905,14 +1308,12 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 sampler: { type: 'filtering' },
             });
             bindingIndex++;
-            textureCount++;
         }
         return device.createBindGroupLayout({ entries });
     }
-    _uploadUserUniforms(_shader, resources) {
+    _uploadUserUniforms(material, resources) {
         const device = this._device;
-        const uniforms = _shader.uniforms;
-        const scalarValues = Object.values(uniforms).filter(v => !isTextureUniform(v));
+        const scalarValues = collectScalarUniforms(material);
         // Always create a UBO (even if empty) since binding 0 of the user layout
         // is fixed. Min size 16 bytes to satisfy WebGPU's minimum buffer size.
         const slotCount = Math.max(scalarValues.length, 1);
@@ -950,16 +1351,13 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
         device.queue.writeBuffer(resources.userUniformBuffer, 0, data);
     }
-    _buildUserBindGroup(backend, shader, resources) {
+    _buildUserBindGroup(backend, material, resources) {
         const device = this._device;
         const entries = [];
         entries.push({ binding: 0, resource: { buffer: resources.userUniformBuffer } });
         let bindingIndex = 1;
-        for (const value of Object.values(shader.uniforms)) {
-            if (!isTextureUniform(value)) {
-                continue;
-            }
-            const binding = backend.getTextureBinding(value);
+        for (const texture of collectTextureBindings(material)) {
+            const binding = backend.getTextureBinding(texture);
             entries.push({ binding: bindingIndex, resource: binding.view });
             bindingIndex++;
             entries.push({ binding: bindingIndex, resource: binding.sampler });
@@ -997,6 +1395,34 @@ function isTextureUniform(value) {
         !(value instanceof Int32Array) &&
         !Array.isArray(value));
 }
+/** Scalar/vector/matrix uniforms (texture values excluded) in declaration order. */
+function collectScalarUniforms(material) {
+    const result = [];
+    for (const value of Object.values(material.uniforms)) {
+        if (!isTextureUniform(value)) {
+            result.push(value);
+        }
+    }
+    return result;
+}
+/**
+ * Texture bindings claimed by the material, in a stable order: texture-valued
+ * entries of `uniforms` first (declaration order), then the dedicated
+ * `textures` map (declaration order). The WGSL source must declare its
+ * `@group(2)` texture/sampler pairs in this same order.
+ */
+function collectTextureBindings(material) {
+    const result = [];
+    for (const value of Object.values(material.uniforms)) {
+        if (isTextureUniform(value)) {
+            result.push(value);
+        }
+    }
+    for (const texture of Object.values(material.textures)) {
+        result.push(texture);
+    }
+    return result;
+}
 
 export { WebGpuMeshRenderer };
 //# sourceMappingURL=WebGpuMeshRenderer.js.map