@codexo/exojs 0.8.2 → 0.8.3

package/dist/exo.esm.js

@@ -1415,6 +1415,74 @@ const getOfflineAudioContext = () => getOrCreateOfflineAudioContext();
  */
 const decodeAudioData = async (arrayBuffer) => getOrCreateOfflineAudioContext().decodeAudioData(arrayBuffer);
 
+/**
+ * Mel-scale filterbank generator.
+ *
+ * Generates `numBands` triangular filters log-spaced from `fMin` to `fMax` Hz
+ * on the mel scale. Each filter is a typed array of weights for the FFT
+ * magnitude bins.
+ *
+ * These helpers are also inlined inside the beat-detector worklet source
+ * string (worklets cannot import modules).
+ */
+/** Convert Hz to mel. */
+function hzToMel(hz) {
+    return 2595 * Math.log10(1 + hz / 700);
+}
+/** Convert mel to Hz. */
+function melToHz(mel) {
+    return 700 * (Math.pow(10, mel / 2595) - 1);
+}
+/**
+ * Build a mel filterbank.
+ *
+ * @param numBands   Number of mel bands (default 24).
+ * @param fMin       Lowest frequency in Hz (default 80).
+ * @param fMax       Highest frequency in Hz (default 8000).
+ * @param fftSize    Number of FFT points (e.g., 2048).
+ * @param sampleRate Audio sample rate in Hz (e.g., 48000).
+ */
+function buildMelFilterbank(bandCount, fMin, fMax, fftSize, sampleRate) {
+    const binCount = fftSize >> 1; // positive frequencies
+    const nyquist = sampleRate / 2;
+    // Equally-spaced mel points: bandCount+2 points spanning fMin..fMax
+    const melMin = hzToMel(fMin);
+    const melMax = hzToMel(fMax);
+    const melPoints = new Float32Array(bandCount + 2);
+    for (let i = 0; i < bandCount + 2; i++) {
+        melPoints[i] = melMin + ((melMax - melMin) * i) / (bandCount + 1);
+    }
+    // Convert mel points to FFT bin indices
+    const binPoints = new Float32Array(bandCount + 2);
+    for (let i = 0; i < bandCount + 2; i++) {
+        const hz = melToHz(melPoints[i]);
+        binPoints[i] = Math.round((hz / nyquist) * (binCount - 1));
+    }
+    const bands = [];
+    for (let b = 0; b < bandCount; b++) {
+        const startBin = Math.max(0, Math.min(binCount - 1, binPoints[b]));
+        const peakBin = Math.max(0, Math.min(binCount - 1, binPoints[b + 1]));
+        const endBin = Math.max(0, Math.min(binCount - 1, binPoints[b + 2]));
+        const len = endBin - startBin + 1;
+        const weights = new Float32Array(len);
+        for (let i = 0; i < len; i++) {
+            const bin = startBin + i;
+            if (bin <= peakBin && peakBin > startBin) {
+                weights[i] = (bin - startBin) / (peakBin - startBin);
+            }
+            else if (bin > peakBin && endBin > peakBin) {
+                weights[i] = (endBin - bin) / (endBin - peakBin);
+            }
+            else {
+                // Degenerate: startBin === peakBin === endBin
+                weights[i] = 1;
+            }
+        }
+        bands.push({ startBin, peakBin, endBin, weights });
+    }
+    return bands;
+}
+
 /**
  * Lightweight visualisation analyser backed by a Web Audio AnalyserNode.
  *
@@ -1435,6 +1503,10 @@ class AudioAnalyser {
     _floatSpectrum;
     _byteWaveform;
     _floatWaveform;
+    // Cached mel/log filterbanks. Key: `${bands}|${fMin}|${fMax}|${fftSize}`.
+    // Filterbank construction is non-trivial; caching avoids per-frame allocation.
+    _melCache = new Map();
+    _logCache = new Map();
     /**
      * Create an `AudioAnalyser` with the given options. The underlying
      * `AnalyserNode` is created immediately if the `AudioContext` is already
@@ -1446,6 +1518,7 @@ class AudioAnalyser {
             smoothingTimeConstant: options?.smoothingTimeConstant ?? 0.8,
             minDecibels: options?.minDecibels ?? -100,
             maxDecibels: options?.maxDecibels ?? -30,
+            source: options?.source ?? null,
         };
         const binCount = this._options.fftSize >> 1;
         this._byteSpectrum = new Uint8Array(binCount);
@@ -1458,6 +1531,9 @@ class AudioAnalyser {
         else {
             onAudioContextReady.once(this._setupAnalyser, this);
         }
+        if (options?.source !== undefined && options.source !== null) {
+            this.source = options.source;
+        }
     }
     // -----------------------------------------------------------------------
     // Source setter
@@ -1613,6 +1689,81 @@ class AudioAnalyser {
         return this.getBandEnergy(0, nyquist);
     }
     // -----------------------------------------------------------------------
+    // Spectrum mapping (mel / log scaling)
+    //
+    // The raw FFT bins from AnalyserNode are linearly distributed across
+    // 0..nyquist, which gives bass a few bins and treble hundreds. For
+    // visualisations you typically want perceptually-weighted spacing.
+    //
+    // Both `getSpectrumMel` and `getSpectrumLog` operate on the byte-domain
+    // spectrum (0..255) and produce byte output by default. The float
+    // variants operate on dBFS values and produce float output.
+    //
+    // Filterbanks are cached on the analyser; they only rebuild when fftSize
+    // or the (bands, fMin, fMax) parameters change.
+    // -----------------------------------------------------------------------
+    /**
+     * Mel-scaled spectrum, byte domain (0..255). Output length = `bands`.
+     * Each output bin is a triangular-weighted sum of the linear FFT bins
+     * underneath it, mel-spaced from `fMin` to `fMax`.
+     */
+    getSpectrumMel(into, options) {
+        const bandCount = options?.bands ?? 32;
+        const out = into ?? new Uint8Array(bandCount);
+        const filterbank = this._getMelFilterbank(bandCount, options?.fMin ?? 20, options?.fMax ?? 20000);
+        if (!this._analyser || filterbank === null) {
+            out.fill(0);
+            return out;
+        }
+        this._analyser.getByteFrequencyData(this._byteSpectrum);
+        applyFilterbank(this._byteSpectrum, filterbank, out);
+        return out;
+    }
+    /** Mel-scaled spectrum, float domain (dBFS values). Output length = `bands`. */
+    getSpectrumMelFloat(into, options) {
+        const bandCount = options?.bands ?? 32;
+        const out = into ?? new Float32Array(bandCount);
+        const filterbank = this._getMelFilterbank(bandCount, options?.fMin ?? 20, options?.fMax ?? 20000);
+        if (!this._analyser || filterbank === null) {
+            out.fill(0);
+            return out;
+        }
+        this._analyser.getFloatFrequencyData(this._floatSpectrum);
+        applyFilterbank(this._floatSpectrum, filterbank, out);
+        return out;
+    }
+    /**
+     * Log-scaled spectrum, byte domain (0..255). Output length = `bands`.
+     * Bins are spaced so each output covers an equal fraction of the
+     * `log2(fMax / fMin)` octave range — useful when you want a
+     * frequency-axis visualization where each octave gets the same width.
+     */
+    getSpectrumLog(into, options) {
+        const bandCount = options?.bands ?? 32;
+        const out = into ?? new Uint8Array(bandCount);
+        const ranges = this._getLogRanges(bandCount, options?.fMin ?? 20, options?.fMax ?? 20000);
+        if (!this._analyser || ranges === null) {
+            out.fill(0);
+            return out;
+        }
+        this._analyser.getByteFrequencyData(this._byteSpectrum);
+        applyLogRanges(this._byteSpectrum, ranges, out);
+        return out;
+    }
+    /** Log-scaled spectrum, float domain (dBFS values). Output length = `bands`. */
+    getSpectrumLogFloat(into, options) {
+        const bandCount = options?.bands ?? 32;
+        const out = into ?? new Float32Array(bandCount);
+        const ranges = this._getLogRanges(bandCount, options?.fMin ?? 20, options?.fMax ?? 20000);
+        if (!this._analyser || ranges === null) {
+            out.fill(0);
+            return out;
+        }
+        this._analyser.getFloatFrequencyData(this._floatSpectrum);
+        applyLogRanges(this._floatSpectrum, ranges, out);
+        return out;
+    }
+    // -----------------------------------------------------------------------
     // Lifecycle
     // -----------------------------------------------------------------------
     /**
@@ -1630,6 +1781,34 @@ class AudioAnalyser {
     // -----------------------------------------------------------------------
     // Private helpers
     // -----------------------------------------------------------------------
+    _getMelFilterbank(bands, fMin, fMax) {
+        if (!this._analyser)
+            return null;
+        const ctx = getAudioContext();
+        const fftSize = this._options.fftSize;
+        const clampedFmax = Math.min(fMax, ctx.sampleRate / 2);
+        const key = `${bands}|${fMin}|${clampedFmax}|${fftSize}`;
+        let cached = this._melCache.get(key);
+        if (cached === undefined) {
+            cached = buildMelFilterbank(bands, fMin, clampedFmax, fftSize, ctx.sampleRate);
+            this._melCache.set(key, cached);
+        }
+        return cached;
+    }
+    _getLogRanges(bands, fMin, fMax) {
+        if (!this._analyser)
+            return null;
+        const ctx = getAudioContext();
+        const fftSize = this._options.fftSize;
+        const clampedFmax = Math.min(fMax, ctx.sampleRate / 2);
+        const key = `${bands}|${fMin}|${clampedFmax}|${fftSize}`;
+        let cached = this._logCache.get(key);
+        if (cached === undefined) {
+            cached = buildLogRanges(bands, fMin, clampedFmax, fftSize, ctx.sampleRate);
+            this._logCache.set(key, cached);
+        }
+        return cached;
+    }
     _setupAnalyser(audioContext) {
         const node = audioContext.createAnalyser();
         node.fftSize = this._options.fftSize;
@@ -1720,6 +1899,42 @@ class AudioAnalyser {
         }
     }
 }
+function buildLogRanges(bandCount, fMin, fMax, fftSize, sampleRate) {
+    const binCount = fftSize >> 1;
+    const nyquist = sampleRate / 2;
+    const logMin = Math.log(fMin);
+    const logMax = Math.log(fMax);
+    const ranges = [];
+    for (let b = 0; b < bandCount; b++) {
+        const lowHz = Math.exp(logMin + ((logMax - logMin) * b) / bandCount);
+        const highHz = Math.exp(logMin + ((logMax - logMin) * (b + 1)) / bandCount);
+        const startBin = Math.max(0, Math.min(binCount - 1, Math.floor((lowHz / nyquist) * binCount)));
+        const endBin = Math.max(startBin, Math.min(binCount - 1, Math.ceil((highHz / nyquist) * binCount) - 1));
+        ranges.push({ startBin, endBin });
+    }
+    return ranges;
+}
+function applyFilterbank(spectrum, bands, out) {
+    for (let b = 0; b < bands.length; b++) {
+        const { startBin, weights } = bands[b];
+        let sum = 0;
+        for (let i = 0; i < weights.length; i++) {
+            sum += spectrum[startBin + i] * weights[i];
+        }
+        out[b] = sum;
+    }
+}
+function applyLogRanges(spectrum, ranges, out) {
+    for (let b = 0; b < ranges.length; b++) {
+        const { startBin, endBin } = ranges[b];
+        let sum = 0;
+        const count = endBin - startBin + 1;
+        for (let i = startBin; i <= endBin; i++) {
+            sum += spectrum[i];
+        }
+        out[b] = sum / count;
+    }
+}
 
 /** τ = 2π, the full-circle radian constant. */
 const tau$2 = Math.PI * 2;
@@ -4504,6 +4719,15 @@ class BeatDetector {
     _timeSignature = { numerator: 4, denominator: 4 };
     _nextDownbeatTime = 0;
     _lookahead = Object.freeze([]);
+    /**
+     * Half-life in seconds for the {@link pulse} envelope. Mutable; default 0.15.
+     * Smaller values give a snappier pulse, larger values a longer afterglow.
+     */
+    pulseHalfLife;
+    /** Half-life for the {@link barPulse} envelope. Mutable; default 0.3. */
+    barPulseHalfLife;
+    /** Time window for {@link justBeat}. Mutable; default 0.03 (30ms). */
+    justBeatWindow;
     constructor(options) {
         this._options = {
             minBpm: options?.minBpm ?? 50,
@@ -4514,13 +4738,25 @@ class BeatDetector {
             settlingMs: options?.settlingMs ?? 1500,
             melBands: options?.melBands ?? 24,
             enableTimeSignatureDetection: options?.enableTimeSignatureDetection ?? true,
+            // Visual-state options aren't part of worklet config; cached in the public
+            // fields below but kept in the Required<> shape for type completeness.
+            source: options?.source ?? null,
+            pulseHalfLife: options?.pulseHalfLife ?? 0.15,
+            barPulseHalfLife: options?.barPulseHalfLife ?? 0.3,
+            justBeatWindow: options?.justBeatWindow ?? 0.03,
         };
+        this.pulseHalfLife = this._options.pulseHalfLife;
+        this.barPulseHalfLife = this._options.barPulseHalfLife;
+        this.justBeatWindow = this._options.justBeatWindow;
         if (isAudioContextReady()) {
             this._setup(getAudioContext());
         }
         else {
             onAudioContextReady.once(this._setup, this);
         }
+        if (options?.source !== undefined && options.source !== null) {
+            this.source = options.source;
+        }
     }
     // -----------------------------------------------------------------------
     // Source setter (polymorphic tap)
@@ -4601,6 +4837,62 @@ class BeatDetector {
         return this._lookahead;
     }
     // -----------------------------------------------------------------------
+    // Visual derived state — pure getters for per-frame polling
+    // -----------------------------------------------------------------------
+    /**
+     * Seconds elapsed since the most recent beat, derived from {@link beatPhase}
+     * and {@link tempo}. Returns 0 when the detector hasn't locked yet.
+     */
+    get secondsSinceLastBeat() {
+        if (this._tempo === 0)
+            return 0;
+        return this._beatPhase * (60 / this._tempo);
+    }
+    /**
+     * 0..1 envelope, peaks at 1.0 the moment a beat fires and halves every
+     * {@link pulseHalfLife} seconds. Drives "pulse on the beat" visuals
+     * with a single multiplication: `sprite.scale = 1 + clock.pulse * 0.3`.
+     */
+    get pulse() {
+        if (this._tempo === 0)
+            return 0;
+        return Math.pow(0.5, this.secondsSinceLastBeat / this.pulseHalfLife);
+    }
+    /**
+     * Like {@link pulse} but resets on downbeats and decays per
+     * {@link barPulseHalfLife}. Useful for emphasizing the first beat of
+     * each bar (e.g. brighter flash on "1" vs "2,3,4").
+     */
+    get barPulse() {
+        if (this._tempo === 0 || this._barLength === 0)
+            return 0;
+        const secondsPerBeat = 60 / this._tempo;
+        const lastDownbeat = this._nextDownbeatTime - this._barLength * secondsPerBeat;
+        const elapsed = Math.max(0, getAudioContext().currentTime - lastDownbeat);
+        return Math.pow(0.5, elapsed / this.barPulseHalfLife);
+    }
+    /**
+     * True for the visual frame(s) within {@link justBeatWindow} seconds of
+     * a beat onset. Use for one-shot triggers (strobe flash, particle burst,
+     * sample retrigger). Default window 30ms covers a typical 60fps frame.
+     */
+    get justBeat() {
+        return this._tempo > 0 && this.secondsSinceLastBeat < this.justBeatWindow;
+    }
+    /**
+     * Phase 0..1 within a subdivision of the current beat. `division` is the
+     * number of subdivisions per beat: 2 for 8th notes, 4 for 16th notes,
+     * 3 for triplets. Use to drive sub-beat-resolution effects:
+     *
+     *   const sixteenth = clock.subdivisionPhase(4);
+     *   if (sixteenth < 0.05) flash();
+     */
+    subdivisionPhase(division) {
+        if (!Number.isFinite(division) || division <= 0)
+            return 0;
+        return (this._beatPhase * division) % 1;
+    }
+    // -----------------------------------------------------------------------
     // Lifecycle
     // -----------------------------------------------------------------------
     destroy() {
@@ -16526,6 +16818,174 @@ const resetRenderStats = (stats) => {
     return stats;
 };
 
+const channelsForFormat = {
+    r8: 1,
+    r32f: 1,
+    rgba8: 4,
+    rgba32f: 4,
+};
+const bytesPerChannelForFormat = {
+    r8: 1,
+    r32f: 4,
+    rgba8: 1,
+    rgba32f: 4,
+};
+/**
+ * A 2D texture whose pixels live in a CPU-side typed array. Mutate the
+ * `buffer` directly and call {@link commit} to upload the whole array, or
+ * {@link commitRect} to upload a sub-region (cheaper for ring-buffer
+ * patterns like spectrograms).
+ *
+ * `DataTexture` extends {@link Texture}, so any API that accepts a
+ * `Texture` (filter uniforms, mesh textures, custom shader uniforms)
+ * accepts a `DataTexture` unchanged.
+ *
+ * # Default sampler
+ *
+ * `DataTexture` defaults to nearest filtering, clamp-to-edge wrap, no mip
+ * generation, and no premultiply. These match the typical "raw data
+ * lookup" use case where bilinear filtering would corrupt sampled values
+ * (e.g. spectrum bins sampled by index).
+ *
+ * # Bring-your-own buffer
+ *
+ * Pass `data` in options to share an external buffer. Useful for:
+ * - SharedArrayBuffer + Worker pipelines (audio DSP off the main thread)
+ * - Buffer pooling across many small textures
+ * - Interop with WebAssembly memory or other APIs that produce typed-array views
+ *
+ * The buffer reference is fixed for the lifetime of the texture (the
+ * `buffer` property is `readonly`); only its contents may be mutated.
+ *
+ * # Format / buffer correspondence
+ *
+ * The TypeScript type system narrows `buffer` based on `format`:
+ *
+ *   const r8 = new DataTexture({ width: 256, height: 1, format: 'r8' });
+ *   r8.buffer  // Uint8Array
+ *
+ *   const r32f = new DataTexture({ width: 256, height: 1, format: 'r32f' });
+ *   r32f.buffer  // Float32Array
+ */
+class DataTexture extends Texture {
+    static defaultSamplerOptions = {
+        scaleMode: ScaleModes.Nearest,
+        wrapMode: WrapModes.ClampToEdge,
+        premultiplyAlpha: false,
+        generateMipMap: false,
+        flipY: false,
+    };
+    format;
+    buffer;
+    _dirty = null;
+    constructor(options) {
+        super(null, { ...DataTexture.defaultSamplerOptions, ...options.samplerOptions });
+        const { width, height, format, data } = options;
+        if (!Number.isInteger(width) || width <= 0) {
+            throw new Error(`DataTexture width must be a positive integer (got ${width}).`);
+        }
+        if (!Number.isInteger(height) || height <= 0) {
+            throw new Error(`DataTexture height must be a positive integer (got ${height}).`);
+        }
+        const channels = channelsForFormat[format];
+        const bpc = bytesPerChannelForFormat[format];
+        const expectedBytes = width * height * channels * bpc;
+        let buffer;
+        if (data === undefined) {
+            buffer = isFloatFormat(format) ? new Float32Array(expectedBytes / 4) : new Uint8Array(expectedBytes);
+        }
+        else if (data instanceof ArrayBuffer) {
+            if (data.byteLength !== expectedBytes) {
+                throw new Error(`DataTexture data byteLength ${data.byteLength} does not match ${width}x${height} ${format} (${expectedBytes} bytes expected).`);
+            }
+            buffer = isFloatFormat(format) ? new Float32Array(data) : new Uint8Array(data);
+        }
+        else if (data instanceof Uint8Array) {
+            if (isFloatFormat(format)) {
+                throw new Error(`DataTexture format '${format}' requires a Float32Array, got Uint8Array.`);
+            }
+            if (data.byteLength !== expectedBytes) {
+                throw new Error(`DataTexture Uint8Array length ${data.length} does not match ${width}x${height} ${format} (${expectedBytes} expected).`);
+            }
+            buffer = data;
+        }
+        else {
+            // Float32Array
+            if (!isFloatFormat(format)) {
+                throw new Error(`DataTexture format '${format}' requires a Uint8Array, got Float32Array.`);
+            }
+            if (data.byteLength !== expectedBytes) {
+                throw new Error(`DataTexture Float32Array byteLength ${data.byteLength} does not match ${width}x${height} ${format} (${expectedBytes} expected).`);
+            }
+            buffer = data;
+        }
+        this.format = format;
+        this.buffer = buffer;
+        this.setSize(width, height);
+        // Mark fully dirty so the first sync uploads the whole buffer.
+        this._dirty = { full: true, x: 0, y: 0, width, height };
+    }
+    /**
+     * Mark the entire buffer for re-upload on next backend sync. Call after
+     * mutating `buffer` contents to flush changes to the GPU.
+     */
+    commit() {
+        this._dirty = { full: true, x: 0, y: 0, width: this.width, height: this.height };
+        this.setSize(this.width, this.height);
+        // setSize is a no-op when dimensions don't change; force version bump for sync detection.
+        this._version++;
+        return this;
+    }
+    /**
+     * Mark a sub-region of the buffer dirty for partial upload. More efficient
+     * than {@link commit} for ring-buffer patterns where only one row or column
+     * changes per frame. If a region was already pending, the union is uploaded.
+     *
+     * Coordinates are pixel-space with origin at the top-left. Bounds are clamped
+     * to the texture dimensions; out-of-range rectangles throw.
+     */
+    commitRect(x, y, width, height) {
+        if (!Number.isInteger(x) || !Number.isInteger(y) || !Number.isInteger(width) || !Number.isInteger(height)) {
+            throw new Error(`DataTexture commitRect requires integer coordinates (got ${x}, ${y}, ${width}, ${height}).`);
+        }
+        if (width <= 0 || height <= 0) {
+            throw new Error(`DataTexture commitRect requires positive width and height (got ${width}, ${height}).`);
+        }
+        if (x < 0 || y < 0 || x + width > this.width || y + height > this.height) {
+            throw new Error(`DataTexture commitRect (${x}, ${y}, ${width}, ${height}) is out of bounds for ${this.width}x${this.height}.`);
+        }
+        if (this._dirty === null) {
+            this._dirty = { full: false, x, y, width, height };
+        }
+        else if (this._dirty.full) ;
+        else {
+            // Union with the existing pending region.
+            const minX = Math.min(this._dirty.x, x);
+            const minY = Math.min(this._dirty.y, y);
+            const maxX = Math.max(this._dirty.x + this._dirty.width, x + width);
+            const maxY = Math.max(this._dirty.y + this._dirty.height, y + height);
+            this._dirty = { full: false, x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+        }
+        this._version++;
+        return this;
+    }
+    /**
+     * Internal: backend reads the pending dirty region and clears it. Returns
+     * `null` when there is nothing pending. Backends call this once per sync
+     * pass to plan their texSubImage2D / writeTexture operations.
+     *
+     * @internal
+     */
+    _consumeDirtyRegion() {
+        const region = this._dirty;
+        this._dirty = null;
+        return region;
+    }
+}
+function isFloatFormat(format) {
+    return format === 'r32f' || format === 'rgba32f';
+}
+
 /**
  * Backend-agnostic shader program descriptor.
  *
@@ -17426,7 +17886,7 @@ const vertexStrideWords = vertexStrideBytes$3 / 4;
 const initialVertexCapacity = 64;
 const initialIndexCapacity = 192;
 const defaultVertexColor = 0xffffffff; // white, full alpha
-const maxCustomTextureSlots = 8;
+const maxCustomTextureSlots$1 = 8;
 class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
     _defaultShader = new Shader(vertexSource$2, fragmentSource$2);
     _customShaders = new Map();
@@ -17434,7 +17894,7 @@ class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
     _textureUnitScratch = new Int32Array([0]);
     // Pre-built texture-unit indices used for custom-shader sampler bindings;
     // pre-allocated so the per-frame uniform path stays allocation-free.
-    _slotScratches = Array.from({ length: maxCustomTextureSlots }, (_, i) => new Int32Array([i]));
+    _slotScratches = Array.from({ length: maxCustomTextureSlots$1 }, (_, i) => new Int32Array([i]));
     _vertexCapacity = initialVertexCapacity;
     _indexCapacity = initialIndexCapacity;
     _vertexData = new ArrayBuffer(initialVertexCapacity * vertexStrideBytes$3);
@@ -17671,11 +18131,22 @@ class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
         if (cached !== undefined) {
             return cached;
         }
-        const shader = new Shader(config.vertexSource, config.fragmentSource);
+        if (config.glsl === null) {
+            throw new Error('MeshShader has no `glsl` source; cannot render through the WebGL2 backend.');
+        }
+        const shader = new Shader(config.glsl.vertex, config.glsl.fragment);
         shader.connect(createWebGl2ShaderProgram(gl));
         // Force first finalize so getUniform()/uniforms.has() are usable below.
         shader.sync();
         this._customShaders.set(config, shader);
+        // Wire shader.destroy() through to evict + dispose the cached program.
+        config._onDispose(() => {
+            const stored = this._customShaders.get(config);
+            if (stored !== undefined) {
+                stored.destroy();
+                this._customShaders.delete(config);
+            }
+        });
         return shader;
     }
     _bindCustomUniforms(shader, uniforms, backend) {
@@ -17689,8 +18160,8 @@ class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
             const value = uniforms[name];
             const uniform = shader.getUniform(name);
             if (value instanceof Texture || value instanceof RenderTexture) {
-                if (textureSlot >= maxCustomTextureSlots) {
-                    throw new Error(`Mesh custom shader requested more than ${maxCustomTextureSlots - 1} texture uniforms.`);
+                if (textureSlot >= maxCustomTextureSlots$1) {
+                    throw new Error(`Mesh custom shader requested more than ${maxCustomTextureSlots$1 - 1} texture uniforms.`);
                 }
                 backend.bindTexture(value, textureSlot);
                 uniform.setValue(this._slotScratches[textureSlot]);
@@ -18830,7 +19301,31 @@ class WebGl2Backend {
             gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, texture.wrapMode);
             gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, texture.wrapMode);
             gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, texture.premultiplyAlpha);
-            if (texture instanceof RenderTexture) {
+            if (texture instanceof DataTexture) {
+                const formatInfo = webgl2DataTextureFormat(texture.format);
+                const region = texture._consumeDirtyRegion();
+                const needsAlloc = state.version === -1 || state.width !== texture.width || state.height !== texture.height;
+                if (needsAlloc || region === null || region.full) {
+                    gl.texImage2D(gl.TEXTURE_2D, 0, formatInfo.internalFormat, texture.width, texture.height, 0, formatInfo.format, formatInfo.type, texture.buffer);
+                }
+                else {
+                    // Partial upload: pack a contiguous sub-region from the row-major
+                    // buffer into a temporary view that gl.texSubImage2D can read.
+                    const channels = formatInfo.channels;
+                    const rowFloats = texture.width * channels;
+                    const subFloats = region.width * channels;
+                    const subView = texture.buffer instanceof Float32Array
+                        ? new Float32Array(region.width * region.height * channels)
+                        : new Uint8Array(region.width * region.height * channels);
+                    for (let row = 0; row < region.height; row++) {
+                        const sourceStart = (region.y + row) * rowFloats + region.x * channels;
+                        const targetStart = row * subFloats;
+                        subView.set(texture.buffer.subarray(sourceStart, sourceStart + subFloats), targetStart);
+                    }
+                    gl.texSubImage2D(gl.TEXTURE_2D, 0, region.x, region.y, region.width, region.height, formatInfo.format, formatInfo.type, subView);
+                }
+            }
+            else if (texture instanceof RenderTexture) {
                 if (state.version === -1 || state.width !== texture.width || state.height !== texture.height || texture.source === null) {
                     gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, texture.width, texture.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, texture.source);
                 }
@@ -18901,6 +19396,22 @@ class WebGl2Backend {
         gl.scissor(clip.x, clip.y, clip.width, clip.height);
     }
 }
+// WebGL2RenderingContext is not defined in jsdom; resolve constants from
+// the live gl context instead of the global class so test environments
+// without WebGL2 still load this module.
+function webgl2DataTextureFormat(format) {
+    const gl = WebGL2RenderingContext;
+    switch (format) {
+        case 'r8':
+            return { internalFormat: gl.R8, format: gl.RED, type: gl.UNSIGNED_BYTE, channels: 1 };
+        case 'r32f':
+            return { internalFormat: gl.R32F, format: gl.RED, type: gl.FLOAT, channels: 1 };
+        case 'rgba8':
+            return { internalFormat: gl.RGBA8, format: gl.RGBA, type: gl.UNSIGNED_BYTE, channels: 4 };
+        case 'rgba32f':
+            return { internalFormat: gl.RGBA32F, format: gl.RGBA, type: gl.FLOAT, channels: 4 };
+    }
+}
 
 /// <reference types="@webgpu/types" />
 /**
@@ -19140,9 +19651,10 @@ class WebGpuMaskCompositor {
         });
         const targetFormat = manager.renderTargetFormat;
         const pipeline = this._getOrCreatePipeline(targetFormat, blendMode);
-        const encoder = device.createCommandEncoder();
+        const encoder = device.createCommandEncoder({ label: 'WebGpuMaskCompositor' });
         const pass = encoder.beginRenderPass({
             colorAttachments: [manager.createColorAttachment()],
+            label: 'WebGpuMaskCompositor pass',
         });
         manager.stats.renderPasses++;
         const scissor = manager.getScissorRect();
@@ -19337,16 +19849,27 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
 }
 `;
 // Per-vertex layout (20 bytes): pos f32x2 + uv f32x2 + color u8x4-norm.
-// CPU bakes the (view * globalTransform) into position so the vertex
-// shader stays branchless and uniform-free except for the per-mesh tint.
+// Default-shader path bakes the (view * globalTransform) into position so the
+// vertex shader stays branchless and uniform-free except for the per-mesh tint.
+// Custom-shader path keeps positions in LOCAL space — the user's vertex
+// shader receives mesh transforms via the auto-bound u_mesh uniform block.
 const vertexStrideBytes$1 = 20;
 const wordsPerVertex = vertexStrideBytes$1 / 4;
 const tintByteLength = 32; // vec4 tint + vec4 flags (only flags.x used)
+// 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;
+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();
     _textureBindGroups = new Map();
+    _customShaders = new Map();
     _device = null;
     _shaderModule = null;
     _uniformBindGroupLayout = null;
@@ -19370,8 +19893,9 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         if (backend === null) {
             throw new Error('WebGpuMeshRenderer is not connected to a backend.');
         }
-        if (mesh.shader !== null) {
-            throw new Error('Mesh custom shaders are currently WebGL2-only. WebGPU support is planned for a future release; in the meantime use the WebGL2 backend or omit `shader` from the Mesh options.');
+        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 vertexCount = mesh.vertexCount;
         if (vertexCount === 0) {
@@ -19380,15 +19904,26 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         const blendMode = mesh.blendMode;
         backend.setBlendMode(blendMode);
         const meshTexture = mesh.texture ?? Texture.white;
-        // Texture.white is a 1x1 canvas-backed Texture; backend.shouldPremultiplyTextureSample
-        // expects RenderTexture-or-Texture. Both branches are valid here.
+        // 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
+        // it so the default path uses the right value.
         const premultiplySample = backend.shouldPremultiplyTextureSample(meshTexture);
         const indexCount = mesh.indexCount;
-        // Plan offsets within the shared per-frame buffers; actual data
-        // packing happens in flush() after all drawcalls are known so a
-        // single writeBuffer per resource covers the whole frame.
+        let customDrawIndex = -1;
+        if (customShader !== null) {
+            const resources = this._getOrCreateCustomShaderResources(customShader);
+            customDrawIndex = resources.drawCount;
+            resources.drawCount++;
+            resources.totalVertices += vertexCount;
+            resources.totalIndices += indexCount;
+        }
+        // Plan offsets within the shared (default) or per-shader (custom) buffers;
+        // actual data packing happens in flush() after all drawcalls are known so
+        // a single writeBuffer per resource covers the whole frame.
         const drawCall = {
             mesh,
+            customShader,
             blendMode,
             texture: meshTexture,
             premultiplySample,
@@ -19396,6 +19931,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             vertexCount,
             indexByteOffset: 0,
             indexCount,
+            customDrawIndex,
         };
         // Use mutable record (interface readonly is for type safety against
         // callers; the renderer fills these slots in flush()).
@@ -19424,88 +19960,194 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 pass.end();
                 backend.submit(encoder.finish());
             }
-            this._drawCallCount = 0;
+            this._resetFrame();
             return;
         }
-        // Phase 1: compute layout offsets for the whole frame.
-        let totalVertices = 0;
-        let totalIndices = 0;
+        // Phase 1: compute layout offsets (default vs. custom paths use separate
+        // 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 customIndexCursors = new Map();
         for (let i = 0; i < this._drawCallCount; i++) {
             const dc = this._drawCalls[i];
-            dc.vertexByteOffset = totalVertices * vertexStrideBytes$1;
-            dc.indexByteOffset = totalIndices * Uint16Array.BYTES_PER_ELEMENT;
-            totalVertices += dc.vertexCount;
-            totalIndices += dc.indexCount;
-        }
-        // Phase 2: ensure capacities for the totals.
-        this._ensureVertexCapacity(totalVertices);
-        this._ensureIndexCapacity(totalIndices);
-        this._ensureUniformCapacity(this._drawCallCount);
-        // Phase 3: pack vertex + index + uniform CPU-side data.
-        const uniformBytes = this._drawCallCount * this._uniformAlignment;
-        const uniformData = new ArrayBuffer(uniformBytes);
-        const uniformF32 = new Float32Array(uniformData);
-        for (let i = 0; i < this._drawCallCount; i++) {
-            const dc = this._drawCalls[i];
-            this._writeMeshVertices(backend, dc.mesh, dc.vertexByteOffset / vertexStrideBytes$1);
-            if (dc.mesh.indices !== null) {
-                this._packedIndexData.set(dc.mesh.indices, dc.indexByteOffset / Uint16Array.BYTES_PER_ELEMENT);
+            if (dc.customShader === null) {
+                dc.vertexByteOffset = defaultVertices * vertexStrideBytes$1;
+                dc.indexByteOffset = defaultIndices * Uint16Array.BYTES_PER_ELEMENT;
+                defaultVertices += dc.vertexCount;
+                defaultIndices += dc.indexCount;
             }
             else {
-                const start = dc.indexByteOffset / Uint16Array.BYTES_PER_ELEMENT;
-                for (let j = 0; j < dc.indexCount; j++) {
-                    this._packedIndexData[start + j] = j;
+                const vCursor = customVertexCursors.get(dc.customShader) ?? 0;
+                const iCursor = customIndexCursors.get(dc.customShader) ?? 0;
+                dc.vertexByteOffset = vCursor * vertexStrideBytes$1;
+                dc.indexByteOffset = iCursor * Uint16Array.BYTES_PER_ELEMENT;
+                customVertexCursors.set(dc.customShader, vCursor + dc.vertexCount);
+                customIndexCursors.set(dc.customShader, iCursor + dc.indexCount);
+            }
+        }
+        // Phase 2: ensure capacities for the totals (default path).
+        this._ensureVertexCapacity(defaultVertices);
+        this._ensureIndexCapacity(defaultIndices);
+        // Default-path uniform buffer holds (tint vec4 + flags vec4) per draw call;
+        // each custom-shader resource manages its own.
+        const defaultDrawCalls = this._drawCallCount - this._totalCustomDraws();
+        this._ensureUniformCapacity(defaultDrawCalls);
+        // Phase 3: pack default-path vertex/index/uniform data.
+        const defaultUniformBytes = defaultDrawCalls * this._uniformAlignment;
+        const defaultUniformData = defaultUniformBytes > 0 ? new ArrayBuffer(defaultUniformBytes) : null;
+        const defaultUniformF32 = defaultUniformData !== null ? new Float32Array(defaultUniformData) : null;
+        let defaultUniformIndex = 0;
+        for (let i = 0; i < this._drawCallCount; i++) {
+            const dc = this._drawCalls[i];
+            if (dc.customShader === null) {
+                // Default path: CPU-bake transform into vertex positions.
+                this._writeMeshVertices(backend, dc.mesh, dc.vertexByteOffset / vertexStrideBytes$1, /* bake */ true);
+                if (dc.mesh.indices !== null) {
+                    this._packedIndexData.set(dc.mesh.indices, dc.indexByteOffset / Uint16Array.BYTES_PER_ELEMENT);
+                }
+                else {
+                    const start = dc.indexByteOffset / Uint16Array.BYTES_PER_ELEMENT;
+                    for (let j = 0; j < dc.indexCount; j++) {
+                        this._packedIndexData[start + j] = j;
+                    }
+                }
+                // Pack tint+flags for default path.
+                if (defaultUniformF32 !== null) {
+                    const offsetWords = (defaultUniformIndex * this._uniformAlignment) / Float32Array.BYTES_PER_ELEMENT;
+                    const tint = dc.mesh.tint;
+                    defaultUniformF32[offsetWords + 0] = tint.red;
+                    defaultUniformF32[offsetWords + 1] = tint.green;
+                    defaultUniformF32[offsetWords + 2] = tint.blue;
+                    defaultUniformF32[offsetWords + 3] = tint.alpha;
+                    defaultUniformF32[offsetWords + 4] = dc.premultiplySample ? 1 : 0;
+                    defaultUniformF32[offsetWords + 5] = 0;
+                    defaultUniformF32[offsetWords + 6] = 0;
+                    defaultUniformF32[offsetWords + 7] = 0;
                 }
+                defaultUniformIndex++;
             }
-            const uniformOffsetWords = (i * this._uniformAlignment) / Float32Array.BYTES_PER_ELEMENT;
-            const tint = dc.mesh.tint;
-            uniformF32[uniformOffsetWords + 0] = tint.red;
-            uniformF32[uniformOffsetWords + 1] = tint.green;
-            uniformF32[uniformOffsetWords + 2] = tint.blue;
-            uniformF32[uniformOffsetWords + 3] = tint.alpha;
-            uniformF32[uniformOffsetWords + 4] = dc.premultiplySample ? 1 : 0;
-            uniformF32[uniformOffsetWords + 5] = 0;
-            uniformF32[uniformOffsetWords + 6] = 0;
-            uniformF32[uniformOffsetWords + 7] = 0;
-        }
-        // Phase 4: single writeBuffer per resource for the whole frame.
-        device.queue.writeBuffer(this._vertexBuffer, 0, this._vertexData, 0, totalVertices * vertexStrideBytes$1);
-        device.queue.writeBuffer(this._indexBuffer, 0, this._packedIndexData.buffer, this._packedIndexData.byteOffset, totalIndices * Uint16Array.BYTES_PER_ELEMENT);
-        device.queue.writeBuffer(this._uniformBuffer, 0, uniformData, 0, uniformBytes);
-        // Phase 5: single render pass with one drawIndexed per mesh.
-        const encoder = device.createCommandEncoder();
+        }
+        // Phase 3b: pack custom-path vertex/index/uniform data per shader.
+        for (const [shader, resources] of this._customShaders) {
+            if (resources.drawCount === 0) {
+                continue;
+            }
+            this._ensureCustomCapacities(resources);
+            // Pack vertices/indices in local space (no CPU bake).
+            let vWritten = 0;
+            let iWritten = 0;
+            let drawCursor = 0;
+            for (let i = 0; i < this._drawCallCount; i++) {
+                const dc = this._drawCalls[i];
+                if (dc.customShader !== shader)
+                    continue;
+                this._writeMeshVerticesIntoBuffer(dc.mesh, vWritten, resources.vertexFloatView, resources.vertexUintView);
+                if (dc.mesh.indices !== null) {
+                    resources.indexData.set(dc.mesh.indices, iWritten);
+                }
+                else {
+                    for (let j = 0; j < dc.indexCount; j++) {
+                        resources.indexData[iWritten + j] = j;
+                    }
+                }
+                // Write mesh-uniform slot (proj/trans/tint) with dynamic offset.
+                this._writeCustomMeshUniform(shader, resources, drawCursor, dc.mesh, backend);
+                vWritten += dc.vertexCount;
+                iWritten += dc.indexCount;
+                drawCursor++;
+            }
+            device.queue.writeBuffer(resources.vertexBuffer, 0, resources.vertexData, 0, resources.totalVertices * vertexStrideBytes$1);
+            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);
+        }
+        // Phase 4: single writeBuffer per resource for the default path.
+        if (defaultVertices > 0) {
+            device.queue.writeBuffer(this._vertexBuffer, 0, this._vertexData, 0, defaultVertices * vertexStrideBytes$1);
+            device.queue.writeBuffer(this._indexBuffer, 0, this._packedIndexData.buffer, this._packedIndexData.byteOffset, defaultIndices * Uint16Array.BYTES_PER_ELEMENT);
+        }
+        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);
         }
+        const renderTargetFormat = backend.renderTargetFormat;
+        let lastShader = null;
         let lastBlendMode = null;
         let lastFormat = null;
         let lastTexture = null;
-        const renderTargetFormat = backend.renderTargetFormat;
+        let defaultDrawCursor = 0;
+        const customDrawCursors = new Map();
         for (let i = 0; i < this._drawCallCount; i++) {
             const dc = this._drawCalls[i];
-            if (dc.blendMode !== lastBlendMode || renderTargetFormat !== lastFormat) {
-                lastBlendMode = dc.blendMode;
-                lastFormat = renderTargetFormat;
-                pass.setPipeline(this._getPipeline({ blendMode: dc.blendMode, format: renderTargetFormat }));
-            }
-            pass.setBindGroup(0, this._uniformBindGroup, [i * this._uniformAlignment]);
-            if (dc.texture !== lastTexture) {
-                lastTexture = dc.texture;
-                pass.setBindGroup(1, this._getTextureBindGroup(backend, dc.texture));
-            }
-            pass.setVertexBuffer(0, this._vertexBuffer, dc.vertexByteOffset);
-            pass.setIndexBuffer(this._indexBuffer, 'uint16', dc.indexByteOffset);
-            pass.drawIndexed(dc.indexCount);
+            if (dc.customShader === null) {
+                // ----- Default path -----
+                const needsPipeline = lastShader !== 'default' || dc.blendMode !== lastBlendMode || renderTargetFormat !== lastFormat;
+                if (needsPipeline) {
+                    pass.setPipeline(this._getPipeline({ blendMode: dc.blendMode, format: renderTargetFormat }));
+                    lastShader = 'default';
+                    lastBlendMode = dc.blendMode;
+                    lastFormat = renderTargetFormat;
+                    // Pipeline switch invalidates bind group state assumptions.
+                    lastTexture = null;
+                }
+                pass.setBindGroup(0, this._uniformBindGroup, [defaultDrawCursor * this._uniformAlignment]);
+                if (dc.texture !== lastTexture) {
+                    lastTexture = dc.texture;
+                    pass.setBindGroup(1, this._getTextureBindGroup(backend, dc.texture));
+                }
+                pass.setVertexBuffer(0, this._vertexBuffer, dc.vertexByteOffset);
+                pass.setIndexBuffer(this._indexBuffer, 'uint16', dc.indexByteOffset);
+                pass.drawIndexed(dc.indexCount);
+                defaultDrawCursor++;
+            }
+            else {
+                // ----- Custom path -----
+                const resources = this._customShaders.get(dc.customShader);
+                const needsPipeline = lastShader !== dc.customShader || dc.blendMode !== lastBlendMode || renderTargetFormat !== lastFormat;
+                // Wrap each custom-shader draw in a debug group so capture tools
+                // (Spector.js, Chrome DevTools' WebGPU panel) show meaningful
+                // labels for the otherwise-anonymous mesh draws inside the
+                // batched render pass.
+                pass.pushDebugGroup('MeshShader (custom)');
+                if (needsPipeline) {
+                    pass.setPipeline(this._getOrCreateCustomPipeline(resources, dc.blendMode, renderTargetFormat));
+                    lastShader = dc.customShader;
+                    lastBlendMode = dc.blendMode;
+                    lastFormat = renderTargetFormat;
+                    lastTexture = null;
+                    // User bind group is shader-scoped; rebind once per shader switch.
+                    pass.setBindGroup(2, this._buildUserBindGroup(backend, dc.customShader, resources));
+                }
+                const cursor = customDrawCursors.get(dc.customShader) ?? 0;
+                pass.setBindGroup(0, resources.meshUniformBindGroup, [cursor * meshUniformAlignment]);
+                if (dc.texture !== lastTexture) {
+                    lastTexture = dc.texture;
+                    pass.setBindGroup(1, this._getOrCreateCustomMeshTextureBindGroup(resources, backend, dc.texture));
+                }
+                pass.setVertexBuffer(0, resources.vertexBuffer, dc.vertexByteOffset);
+                pass.setIndexBuffer(resources.indexBuffer, 'uint16', dc.indexByteOffset);
+                pass.drawIndexed(dc.indexCount);
+                pass.popDebugGroup();
+                customDrawCursors.set(dc.customShader, cursor + 1);
+            }
             backend.stats.batches++;
             backend.stats.drawCalls++;
         }
         pass.end();
         backend.submit(encoder.finish());
-        this._drawCallCount = 0;
+        this._resetFrame();
     }
     destroy() {
         this.disconnect();
@@ -19581,6 +20223,15 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         this._textureBindGroupLayout = null;
         this._uniformBindGroupLayout = null;
         this._shaderModule = null;
+        // Custom shaders are owned by user code (one MeshShader can be shared
+        // across multiple Mesh instances). Their resources are released when the
+        // user calls shader.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.
+        for (const resources of this._customShaders.values()) {
+            this._releaseCustomShaderResources(resources);
+        }
+        this._customShaders.clear();
         this._device = null;
         this._backend = null;
         this._drawCallCount = 0;
@@ -19588,30 +20239,47 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         this._indexBufferCapacity = 0;
         this._uniformBufferCapacity = 0;
     }
-    _writeMeshVertices(backend, mesh, vertexStart) {
-        // Bake (view * globalTransform) into vertex positions on the CPU,
-        // matching the primitive renderer's no-uniforms approach.
-        const matrix = this._combinedTransform.copy(mesh.getGlobalTransform()).combine(backend.view.getTransform());
-        const a = matrix.a;
-        const b = matrix.b;
-        const c = matrix.c;
-        const d = matrix.d;
-        const tx = matrix.x;
-        const ty = matrix.y;
+    // ---------------------------------------------------------------------------
+    // Default-path helpers
+    // ---------------------------------------------------------------------------
+    _writeMeshVertices(backend, mesh, vertexStart, bake) {
         const vertices = mesh.vertices;
         const uvs = mesh.uvs;
         const colors = mesh.colors;
         const vertexCount = mesh.vertexCount;
-        for (let i = 0; i < vertexCount; i++) {
-            const sourceIndex = i * 2;
-            const targetIndex = (vertexStart + i) * wordsPerVertex;
-            const px = vertices[sourceIndex];
-            const py = vertices[sourceIndex + 1];
-            this._float32View[targetIndex + 0] = a * px + b * py + tx;
-            this._float32View[targetIndex + 1] = c * px + d * py + ty;
-            this._float32View[targetIndex + 2] = uvs !== null ? uvs[sourceIndex] : 0;
-            this._float32View[targetIndex + 3] = uvs !== null ? uvs[sourceIndex + 1] : 0;
-            this._uint32View[targetIndex + 4] = colors !== null ? colors[i] : 0xffffffff;
+        if (bake) {
+            // Bake (view * globalTransform) into vertex positions on the CPU,
+            // matching the primitive renderer's no-uniforms approach.
+            const matrix = this._combinedTransform.copy(mesh.getGlobalTransform()).combine(backend.view.getTransform());
+            const a = matrix.a;
+            const b = matrix.b;
+            const c = matrix.c;
+            const d = matrix.d;
+            const tx = matrix.x;
+            const ty = matrix.y;
+            for (let i = 0; i < vertexCount; i++) {
+                const sourceIndex = i * 2;
+                const targetIndex = (vertexStart + i) * wordsPerVertex;
+                const px = vertices[sourceIndex];
+                const py = vertices[sourceIndex + 1];
+                this._float32View[targetIndex + 0] = a * px + b * py + tx;
+                this._float32View[targetIndex + 1] = c * px + d * py + ty;
+                this._float32View[targetIndex + 2] = uvs !== null ? uvs[sourceIndex] : 0;
+                this._float32View[targetIndex + 3] = uvs !== null ? uvs[sourceIndex + 1] : 0;
+                this._uint32View[targetIndex + 4] = colors !== null ? colors[i] : 0xffffffff;
+            }
+        }
+        else {
+            // Should not happen — default path always bakes. Defensive no-op.
+            for (let i = 0; i < vertexCount; i++) {
+                const sourceIndex = i * 2;
+                const targetIndex = (vertexStart + i) * wordsPerVertex;
+                this._float32View[targetIndex + 0] = vertices[sourceIndex];
+                this._float32View[targetIndex + 1] = vertices[sourceIndex + 1];
+                this._float32View[targetIndex + 2] = uvs !== null ? uvs[sourceIndex] : 0;
+                this._float32View[targetIndex + 3] = uvs !== null ? uvs[sourceIndex + 1] : 0;
+                this._uint32View[targetIndex + 4] = colors !== null ? colors[i] : 0xffffffff;
+            }
         }
     }
     _getPipeline(key) {
@@ -19705,6 +20373,9 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
     }
     _ensureUniformCapacity(drawCallCount) {
+        if (drawCallCount === 0) {
+            return;
+        }
         const requiredBytes = drawCallCount * this._uniformAlignment;
         if (requiredBytes > this._uniformBufferCapacity) {
             this._uniformBuffer?.destroy();
@@ -19724,6 +20395,400 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
             });
         }
     }
+    // ---------------------------------------------------------------------------
+    // Custom-path helpers
+    // ---------------------------------------------------------------------------
+    _totalCustomDraws() {
+        let total = 0;
+        for (const resources of this._customShaders.values()) {
+            total += resources.drawCount;
+        }
+        return total;
+    }
+    _resetFrame() {
+        this._drawCallCount = 0;
+        for (const resources of this._customShaders.values()) {
+            resources.drawCount = 0;
+            resources.totalVertices = 0;
+            resources.totalIndices = 0;
+        }
+    }
+    _getOrCreateCustomShaderResources(shader) {
+        let resources = this._customShaders.get(shader);
+        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.');
+        }
+        const device = this._device;
+        const shaderModule = device.createShaderModule({ code: shader.wgsl });
+        const meshUniformLayout = device.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    buffer: { type: 'uniform', hasDynamicOffset: true },
+                },
+            ],
+        });
+        const meshTextureLayout = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
+            ],
+        });
+        const userLayout = this._buildUserBindGroupLayout(device, shader);
+        const pipelineLayout = device.createPipelineLayout({
+            bindGroupLayouts: [meshUniformLayout, meshTextureLayout, userLayout],
+        });
+        const sampler = device.createSampler({
+            magFilter: 'linear',
+            minFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+        const initialVertexCount = 64;
+        const initialIndexCount = 192;
+        const vertexData = new ArrayBuffer(initialVertexCount * vertexStrideBytes$1);
+        resources = {
+            shaderModule,
+            meshUniformLayout,
+            meshTextureLayout,
+            userLayout,
+            pipelineLayout,
+            pipelines: new Map(),
+            vertexBuffer: null,
+            indexBuffer: null,
+            vertexBufferCapacity: 0,
+            indexBufferCapacity: 0,
+            vertexData,
+            vertexFloatView: new Float32Array(vertexData),
+            vertexUintView: new Uint32Array(vertexData),
+            indexData: new Uint16Array(initialIndexCount),
+            meshUniformBuffer: null,
+            meshUniformBufferCapacity: 0,
+            meshUniformBindGroup: null,
+            userUniformBuffer: null,
+            userUniformBufferCapacity: 0,
+            meshTextureBindGroups: new Map(),
+            sampler,
+            drawCount: 0,
+            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);
+            if (r !== undefined) {
+                this._releaseCustomShaderResources(r);
+                this._customShaders.delete(shader);
+            }
+        });
+        return resources;
+    }
+    _ensureCustomCapacities(resources) {
+        const device = this._device;
+        // Vertex buffer
+        const vertexBytes = resources.totalVertices * vertexStrideBytes$1;
+        if (vertexBytes > resources.vertexData.byteLength) {
+            const newSize = Math.max(vertexBytes, resources.vertexData.byteLength * 2);
+            resources.vertexData = new ArrayBuffer(newSize);
+            resources.vertexFloatView = new Float32Array(resources.vertexData);
+            resources.vertexUintView = new Uint32Array(resources.vertexData);
+        }
+        if (vertexBytes > resources.vertexBufferCapacity) {
+            resources.vertexBuffer?.destroy();
+            resources.vertexBufferCapacity = Math.max(vertexBytes, resources.vertexBufferCapacity * 2 || vertexStrideBytes$1);
+            resources.vertexBuffer = device.createBuffer({
+                size: resources.vertexBufferCapacity,
+                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));
+        }
+        if (indexBytes > resources.indexBufferCapacity) {
+            resources.indexBuffer?.destroy();
+            resources.indexBufferCapacity = Math.max(indexBytes, resources.indexBufferCapacity * 2 || Uint16Array.BYTES_PER_ELEMENT);
+            resources.indexBuffer = device.createBuffer({
+                size: resources.indexBufferCapacity,
+                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+            });
+        }
+        // Mesh-uniform UBO (proj/trans/tint per draw, 256-byte aligned).
+        const meshUniformBytes = resources.drawCount * meshUniformAlignment;
+        if (meshUniformBytes > resources.meshUniformBufferCapacity) {
+            resources.meshUniformBuffer?.destroy();
+            resources.meshUniformBufferCapacity = Math.max(meshUniformBytes, resources.meshUniformBufferCapacity * 2 || meshUniformAlignment);
+            resources.meshUniformBuffer = device.createBuffer({
+                size: resources.meshUniformBufferCapacity,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            resources.meshUniformBindGroup = device.createBindGroup({
+                layout: resources.meshUniformLayout,
+                entries: [
+                    {
+                        binding: 0,
+                        resource: { buffer: resources.meshUniformBuffer, size: customMeshUniformBytes },
+                    },
+                ],
+            });
+        }
+    }
+    _writeMeshVerticesIntoBuffer(mesh, vertexStart, floatView, uintView) {
+        const vertices = mesh.vertices;
+        const uvs = mesh.uvs;
+        const colors = mesh.colors;
+        const vertexCount = mesh.vertexCount;
+        for (let i = 0; i < vertexCount; i++) {
+            const sourceIndex = i * 2;
+            const targetIndex = (vertexStart + i) * wordsPerVertex;
+            floatView[targetIndex + 0] = vertices[sourceIndex];
+            floatView[targetIndex + 1] = vertices[sourceIndex + 1];
+            floatView[targetIndex + 2] = uvs !== null ? uvs[sourceIndex] : 0;
+            floatView[targetIndex + 3] = uvs !== null ? uvs[sourceIndex + 1] : 0;
+            uintView[targetIndex + 4] = colors !== null ? colors[i] : 0xffffffff;
+        }
+    }
+    _writeCustomMeshUniform(_shader, 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;
+        const slotFloats = slotBytes / Float32Array.BYTES_PER_ELEMENT;
+        const data = new Float32Array(slotFloats);
+        const proj = backend.view.getTransform();
+        const trans = mesh.getGlobalTransform();
+        // mat3 (column-major): [a, c, tx | b, d, ty | 0, 0, 1] in 2D.
+        // WGSL mat3x3 has each column padded to vec4. Store as:
+        //   col0 = [a, b, 0, 0] / [c, d, 0, 0] / ...
+        // ExoJS Matrix stores: a, b, c, d, x, y. Standard 2D affine is:
+        //   [a  c  tx]
+        //   [b  d  ty]
+        //   [0  0  1 ]
+        // Column-major mat3: col0 = (a, b, 0), col1 = (c, d, 0), col2 = (tx, ty, 1).
+        let off = 0;
+        // projection
+        data[off + 0] = proj.a;
+        data[off + 1] = proj.b;
+        data[off + 2] = 0;
+        data[off + 3] = 0; // pad
+        data[off + 4] = proj.c;
+        data[off + 5] = proj.d;
+        data[off + 6] = 0;
+        data[off + 7] = 0; // pad
+        data[off + 8] = proj.x;
+        data[off + 9] = proj.y;
+        data[off + 10] = 1;
+        data[off + 11] = 0; // pad
+        off += 12;
+        // translation
+        data[off + 0] = trans.a;
+        data[off + 1] = trans.b;
+        data[off + 2] = 0;
+        data[off + 3] = 0;
+        data[off + 4] = trans.c;
+        data[off + 5] = trans.d;
+        data[off + 6] = 0;
+        data[off + 7] = 0;
+        data[off + 8] = trans.x;
+        data[off + 9] = trans.y;
+        data[off + 10] = 1;
+        data[off + 11] = 0;
+        off += 12;
+        // tint (vec4)
+        const tint = mesh.tint;
+        data[off + 0] = tint.red;
+        data[off + 1] = tint.green;
+        data[off + 2] = tint.blue;
+        data[off + 3] = tint.alpha;
+        this._device.queue.writeBuffer(resources.meshUniformBuffer, drawCursor * slotBytes, data);
+    }
+    _getOrCreateCustomPipeline(resources, blendMode, format) {
+        const cacheKey = `${blendMode}:${format}`;
+        let pipeline = resources.pipelines.get(cacheKey);
+        if (pipeline === undefined) {
+            pipeline = this._device.createRenderPipeline({
+                layout: resources.pipelineLayout,
+                vertex: {
+                    module: resources.shaderModule,
+                    entryPoint: 'vertexMain',
+                    buffers: [
+                        {
+                            arrayStride: vertexStrideBytes$1,
+                            stepMode: 'vertex',
+                            attributes: [
+                                { shaderLocation: 0, offset: 0, format: 'float32x2' },
+                                { shaderLocation: 1, offset: 8, format: 'float32x2' },
+                                { shaderLocation: 2, offset: 16, format: 'unorm8x4' },
+                            ],
+                        },
+                    ],
+                },
+                fragment: {
+                    module: resources.shaderModule,
+                    entryPoint: 'fragmentMain',
+                    targets: [
+                        {
+                            format,
+                            blend: getWebGpuBlendState(blendMode),
+                            writeMask: GPUColorWrite.ALL,
+                        },
+                    ],
+                },
+                primitive: {
+                    topology: 'triangle-list',
+                    cullMode: 'none',
+                },
+            });
+            resources.pipelines.set(cacheKey, pipeline);
+        }
+        return pipeline;
+    }
+    _getOrCreateCustomMeshTextureBindGroup(resources, backend, texture) {
+        let group = resources.meshTextureBindGroups.get(texture);
+        if (group === undefined) {
+            const binding = backend.getTextureBinding(texture);
+            group = this._device.createBindGroup({
+                layout: resources.meshTextureLayout,
+                entries: [
+                    { binding: 0, resource: binding.view },
+                    { binding: 1, resource: binding.sampler },
+                ],
+            });
+            resources.meshTextureBindGroups.set(texture, group);
+        }
+        return group;
+    }
+    _buildUserBindGroupLayout(device, shader) {
+        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({
+            binding: 0,
+            visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+            buffer: { type: 'uniform' },
+        });
+        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.`);
+            }
+            entries.push({
+                binding: bindingIndex,
+                visibility: GPUShaderStage.FRAGMENT,
+                texture: { sampleType: 'float' },
+            });
+            bindingIndex++;
+            entries.push({
+                binding: bindingIndex,
+                visibility: GPUShaderStage.FRAGMENT,
+                sampler: { type: 'filtering' },
+            });
+            bindingIndex++;
+            textureCount++;
+        }
+        return device.createBindGroupLayout({ entries });
+    }
+    _uploadUserUniforms(_shader, resources) {
+        const device = this._device;
+        const uniforms = _shader.uniforms;
+        const scalarValues = Object.values(uniforms).filter(v => !isTextureUniform(v));
+        // 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);
+        const bufferBytes = slotCount * 16;
+        if (resources.userUniformBuffer === null || resources.userUniformBufferCapacity < bufferBytes) {
+            resources.userUniformBuffer?.destroy();
+            resources.userUniformBufferCapacity = bufferBytes;
+            resources.userUniformBuffer = device.createBuffer({
+                size: bufferBytes,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+        }
+        const data = new Float32Array(bufferBytes / 4);
+        let slot = 0;
+        for (const value of scalarValues) {
+            const baseFloatIndex = slot * 4;
+            if (typeof value === 'number') {
+                data[baseFloatIndex] = value;
+            }
+            else if (value instanceof Float32Array) {
+                data.set(value, baseFloatIndex);
+            }
+            else if (value instanceof Int32Array) {
+                for (let i = 0; i < value.length; i++) {
+                    data[baseFloatIndex + i] = value[i];
+                }
+            }
+            else {
+                const arr = value;
+                for (let i = 0; i < arr.length; i++) {
+                    data[baseFloatIndex + i] = arr[i];
+                }
+            }
+            slot++;
+        }
+        device.queue.writeBuffer(resources.userUniformBuffer, 0, data);
+    }
+    _buildUserBindGroup(backend, shader, 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);
+            entries.push({ binding: bindingIndex, resource: binding.view });
+            bindingIndex++;
+            entries.push({ binding: bindingIndex, resource: binding.sampler });
+            bindingIndex++;
+        }
+        return device.createBindGroup({
+            layout: resources.userLayout,
+            entries,
+        });
+    }
+    _releaseCustomShaderResources(resources) {
+        resources.vertexBuffer?.destroy();
+        resources.indexBuffer?.destroy();
+        resources.meshUniformBuffer?.destroy();
+        resources.userUniformBuffer?.destroy();
+        resources.pipelines.clear();
+        resources.meshTextureBindGroups.clear();
+        resources.vertexBuffer = null;
+        resources.indexBuffer = null;
+        resources.meshUniformBuffer = null;
+        resources.userUniformBuffer = null;
+        resources.meshUniformBindGroup = null;
+        resources.vertexBufferCapacity = 0;
+        resources.indexBufferCapacity = 0;
+        resources.meshUniformBufferCapacity = 0;
+        resources.userUniformBufferCapacity = 0;
+    }
+}
+function isTextureUniform(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'width' in value &&
+        'height' in value &&
+        !(value instanceof Float32Array) &&
+        !(value instanceof Int32Array) &&
+        !Array.isArray(value));
 }
 
 /// <reference types="@webgpu/types" />
@@ -21413,7 +22478,7 @@ class WebGpuBackend {
                     width: Math.max(texture.width, 1),
                     height: Math.max(texture.height, 1),
                 },
-                format: managedTextureFormat,
+                format: this._getGpuTextureFormat(texture),
                 mipLevelCount: this._getMipLevelCount(texture),
                 usage: this._getTextureUsage(texture),
             });
@@ -21437,7 +22502,7 @@ class WebGpuBackend {
         return state;
     }
     _syncTexture(texture) {
-        if (!(texture instanceof RenderTexture) && (texture.source === null || texture.width === 0 || texture.height === 0)) {
+        if (!(texture instanceof RenderTexture) && !(texture instanceof DataTexture) && (texture.source === null || texture.width === 0 || texture.height === 0)) {
             throw new Error('WebGPU sprite rendering requires a texture with a valid source and non-zero dimensions.');
         }
         const state = this._getTextureState(texture);
@@ -21451,7 +22516,7 @@ class WebGpuBackend {
                         width: texture.width,
                         height: texture.height,
                     },
-                    format: managedTextureFormat,
+                    format: this._getGpuTextureFormat(texture),
                     mipLevelCount,
                     usage: this._getTextureUsage(texture),
                 });
@@ -21463,7 +22528,34 @@ class WebGpuBackend {
                 state.hasContent = false;
             }
             state.sampler = this._createSampler(texture);
-            if (!(texture instanceof RenderTexture)) {
+            if (texture instanceof DataTexture) {
+                const formatInfo = webgpuDataTextureFormat(texture.format);
+                const region = texture._consumeDirtyRegion();
+                const isFullUpload = region === null || region.full || !state.hasContent;
+                if (isFullUpload) {
+                    this.device.queue.writeTexture({ texture: state.texture }, texture.buffer, {
+                        bytesPerRow: texture.width * formatInfo.bytesPerPixel,
+                        rowsPerImage: texture.height,
+                    }, { width: texture.width, height: texture.height });
+                }
+                else {
+                    // Partial upload: pack the dirty region into a contiguous buffer.
+                    const channels = formatInfo.channels;
+                    const bytesPerPixel = formatInfo.bytesPerPixel;
+                    const subBytes = region.width * region.height * bytesPerPixel;
+                    const subBuffer = texture.buffer instanceof Float32Array ? new Float32Array(subBytes / 4) : new Uint8Array(subBytes);
+                    const rowChannels = texture.width * channels;
+                    const subRowChannels = region.width * channels;
+                    for (let row = 0; row < region.height; row++) {
+                        const sourceStart = (region.y + row) * rowChannels + region.x * channels;
+                        const targetStart = row * subRowChannels;
+                        subBuffer.set(texture.buffer.subarray(sourceStart, sourceStart + subRowChannels), targetStart);
+                    }
+                    this.device.queue.writeTexture({ texture: state.texture, origin: { x: region.x, y: region.y } }, subBuffer, { bytesPerRow: region.width * bytesPerPixel, rowsPerImage: region.height }, { width: region.width, height: region.height });
+                }
+                state.hasContent = true;
+            }
+            else if (!(texture instanceof RenderTexture)) {
                 const source = texture.source;
                 this.device.queue.copyExternalImageToTexture({
                     source,
@@ -21546,14 +22638,27 @@ class WebGpuBackend {
         };
     }
     _createSampler(texture) {
+        // Float32 textures (r32float, rgba32float) are non-filterable by default
+        // in WebGPU; force nearest filtering to avoid validation errors. Apps
+        // that need linear filtering on floats can opt into the
+        // 'float32-filterable' device feature and pass linear via samplerOptions
+        // (not yet exposed).
+        const isFloatData = texture instanceof DataTexture && (texture.format === 'r32f' || texture.format === 'rgba32f');
+        const filter = isFloatData ? 'nearest' : this._getFilterMode(texture.scaleMode);
         return this.device.createSampler({
             addressModeU: this._getAddressMode(texture.wrapMode),
             addressModeV: this._getAddressMode(texture.wrapMode),
-            magFilter: this._getFilterMode(texture.scaleMode),
-            minFilter: this._getFilterMode(texture.scaleMode),
-            mipmapFilter: this._getMipmapFilterMode(texture.scaleMode),
+            magFilter: filter,
+            minFilter: filter,
+            mipmapFilter: isFloatData ? 'nearest' : this._getMipmapFilterMode(texture.scaleMode),
         });
     }
+    _getGpuTextureFormat(texture) {
+        if (texture instanceof DataTexture) {
+            return webgpuDataTextureFormat(texture.format).gpuFormat;
+        }
+        return managedTextureFormat;
+    }
     _getTextureUsage(texture) {
         const mipmapUsage = this._getMipLevelCount(texture) > 1 ? GPUTextureUsage.RENDER_ATTACHMENT : 0;
         if (texture instanceof RenderTexture) {
@@ -21747,6 +22852,18 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
         };
     }
 }
+function webgpuDataTextureFormat(format) {
+    switch (format) {
+        case 'r8':
+            return { gpuFormat: 'r8unorm', bytesPerPixel: 1, channels: 1 };
+        case 'r32f':
+            return { gpuFormat: 'r32float', bytesPerPixel: 4, channels: 1 };
+        case 'rgba8':
+            return { gpuFormat: 'rgba8unorm', bytesPerPixel: 4, channels: 4 };
+        case 'rgba32f':
+            return { gpuFormat: 'rgba32float', bytesPerPixel: 16, channels: 4 };
+    }
+}
 
 /**
  * Renders an `HTMLVideoElement` as a live texture on a {@link Sprite}.
@@ -28761,10 +29878,14 @@ class WebGpuShaderFilter extends Filter {
             // ---- Build user bind group (group 1) ----
             const userBindGroup = this._buildUserBindGroup(gpu, conn);
             // ---- Encode render pass ----
+            // Labels are picked up by Spector.js and Chrome DevTools' WebGPU
+            // panel and displayed as the pass name in capture views; ignored
+            // by WebGPU at runtime so they cost nothing in release builds.
             const device2 = gpu.device;
-            const encoder = device2.createCommandEncoder();
+            const encoder = device2.createCommandEncoder({ label: 'WebGpuShaderFilter' });
             const pass = encoder.beginRenderPass({
                 colorAttachments: [gpu.createColorAttachment()],
+                label: 'WebGpuShaderFilter pass',
             });
             gpu.stats.renderPasses++;
             pass.setPipeline(conn.pipeline);
@@ -29268,6 +30389,235 @@ class LutFilter extends Filter {
     }
 }
 
+/**
+ * Custom shader pair attached to a {@link Mesh}.
+ *
+ * One `MeshShader` instance can be shared across many meshes; renderers
+ * cache compiled programs/pipelines on the instance reference. Call
+ * {@link destroy} when the shader is no longer needed to release the
+ * cached GPU resources on every backend the shader was used on.
+ *
+ * # Vertex layout
+ *
+ * The vertex layout is fixed and shared with the default mesh shader,
+ * so custom vertex shaders MUST pin the standard attribute locations:
+ *
+ * ## GLSL (location-qualified)
+ *
+ * ```glsl
+ * layout(location = 0) in vec2 a_position;
+ * layout(location = 1) in vec2 a_texcoord;
+ * layout(location = 2) in vec4 a_color;
+ * ```
+ *
+ * ## WGSL (location-qualified)
+ *
+ * ```wgsl
+ * struct VertexInput {
+ *     @location(0) position: vec2<f32>,
+ *     @location(1) texcoord: vec2<f32>,
+ *     @location(2) color: vec4<f32>,
+ * };
+ * ```
+ *
+ * # Auto-bound uniforms
+ *
+ * The renderer auto-binds these when the shader declares them. Declared
+ * but unused is fine; absent is fine too. Both backends carry the same
+ * logical uniforms, only the binding scheme differs.
+ *
+ * ## GLSL
+ *
+ * ```glsl
+ * uniform mat3 u_projection;   // active view's projection
+ * uniform mat3 u_translation;  // mesh's global transform
+ * uniform vec4 u_tint;         // mesh.tint as RGBA in 0..1
+ * uniform sampler2D u_texture; // bound to texture slot 0
+ * ```
+ *
+ * ## WGSL
+ *
+ * ```wgsl
+ * struct MeshUniforms {
+ *     projection: mat3x3<f32>,
+ *     translation: mat3x3<f32>,
+ *     tint: vec4<f32>,
+ * };
+ *
+ * @group(0) @binding(0) var<uniform> u_mesh: MeshUniforms;
+ *
+ * @group(1) @binding(0) var u_texture: texture_2d<f32>;
+ * @group(1) @binding(1) var u_sampler: sampler;
+ * ```
+ *
+ * # User uniforms
+ *
+ * Anything in {@link uniforms} is set after the auto-binds. `Texture`/
+ * `RenderTexture` values claim slots 1..N (slot 0 belongs to the mesh).
+ *
+ * ## WGSL user-uniform contract
+ *
+ * User uniforms live in `@group(2)`:
+ *
+ * - `@group(2) @binding(0) var<uniform> u_user: <UserUniformsStruct>;`
+ *   for the packed scalar/vector/matrix uniforms.
+ * - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform,
+ *   in declaration order, alongside its sampler at `@binding(N+1)`.
+ */
+class MeshShader {
+    /**
+     * Mutable user uniform values. Mutate between frames to drive animated
+     * effects; the renderer reads from this map every draw.
+     *
+     *   shader.uniforms.uTime = performance.now() / 1000;
+     *   shader.uniforms.uColor = [1, 0.5, 0, 1];
+     */
+    uniforms;
+    /** GLSL source pair for the WebGL2 backend, or `null` if not provided. */
+    glsl;
+    /** WGSL source for the WebGPU backend, or `null` if not provided. */
+    wgsl;
+    _disposeCallbacks = new Set();
+    constructor(options) {
+        if (options.glsl === undefined && options.wgsl === undefined) {
+            throw new Error('MeshShader requires at least one of `glsl` or `wgsl`.');
+        }
+        if (options.glsl !== undefined) {
+            if (typeof options.glsl.vertex !== 'string' || options.glsl.vertex.length === 0) {
+                throw new Error('MeshShader.glsl.vertex must be a non-empty string.');
+            }
+            if (typeof options.glsl.fragment !== 'string' || options.glsl.fragment.length === 0) {
+                throw new Error('MeshShader.glsl.fragment must be a non-empty string.');
+            }
+        }
+        if (options.wgsl !== undefined && (typeof options.wgsl !== 'string' || options.wgsl.length === 0)) {
+            throw new Error('MeshShader.wgsl must be a non-empty string.');
+        }
+        this.glsl = options.glsl ?? null;
+        this.wgsl = options.wgsl ?? null;
+        this.uniforms = { ...(options.uniforms ?? {}) };
+    }
+    /**
+     * Convenience setter equivalent to `shader.uniforms[name] = value`.
+     * Provided for symmetry with engine APIs that prefer explicit methods
+     * over property mutation.
+     */
+    setUniform(name, value) {
+        this.uniforms[name] = value;
+    }
+    /**
+     * Reflect declared uniforms from each language's source. Returns a per-
+     * language map of uniform-name → declared type, parsed from the shader
+     * sources via lightweight regex (not a full GLSL/WGSL grammar). Texture
+     * uniforms (`sampler2D`/`texture_2d`) are included; sampler bindings
+     * are not (they pair with textures by binding index).
+     *
+     * Reflection is best-effort and intended for CI drift-checks and editor
+     * tooling, not for runtime uniform binding decisions. The renderers do
+     * NOT consult this map; they bind uniforms by name from {@link uniforms}
+     * and let the underlying API resolve declared-but-unused entries.
+     */
+    getDeclaredUniforms() {
+        return {
+            glsl: this.glsl !== null ? parseGlslUniforms(this.glsl.vertex, this.glsl.fragment) : {},
+            wgsl: this.wgsl !== null ? parseWgslUniforms(this.wgsl) : {},
+        };
+    }
+    /**
+     * Compare declared uniform names between the GLSL and WGSL sources.
+     * Returns lists of names declared in only one language. Use in CI to
+     * catch drift when both languages should expose the same logical
+     * uniforms. When only one language is provided, returns empty arrays.
+     *
+     * Auto-bound uniforms (`u_projection`, `u_translation`, `u_tint`,
+     * `u_texture`) are excluded from the comparison since the GLSL source
+     * declares them at the top-level uniform scope while the WGSL source
+     * receives them via the `@group(0)` mesh-uniforms struct and the
+     * `@group(1)` texture binding.
+     */
+    detectUniformDrift() {
+        if (this.glsl === null || this.wgsl === null) {
+            return { onlyInGlsl: [], onlyInWgsl: [] };
+        }
+        const declared = this.getDeclaredUniforms();
+        const glslNames = new Set(Object.keys(declared.glsl).filter(n => !autoBoundUniformNames.has(n)));
+        const wgslNames = new Set(Object.keys(declared.wgsl).filter(n => !autoBoundUniformNames.has(n)));
+        const onlyInGlsl = [];
+        const onlyInWgsl = [];
+        for (const name of glslNames) {
+            if (!wgslNames.has(name))
+                onlyInGlsl.push(name);
+        }
+        for (const name of wgslNames) {
+            if (!glslNames.has(name))
+                onlyInWgsl.push(name);
+        }
+        return { onlyInGlsl, onlyInWgsl };
+    }
+    /**
+     * Release GPU resources cached against this `MeshShader` on every
+     * backend that has compiled it. Safe to call multiple times. After
+     * destroy, the shader can still be re-used — renderers will recompile
+     * on next draw — but typical usage is to drop the reference.
+     */
+    destroy() {
+        for (const callback of this._disposeCallbacks) {
+            callback();
+        }
+        this._disposeCallbacks.clear();
+    }
+    /**
+     * Internal hook for renderers to register a per-shader-instance cleanup
+     * callback (release compiled program, pipeline, or bind groups). The
+     * callback fires on {@link destroy}; renderers MUST also tolerate the
+     * shader being garbage-collected without destroy ever being called.
+     *
+     * @internal
+     */
+    _onDispose(callback) {
+        this._disposeCallbacks.add(callback);
+    }
+}
+const autoBoundUniformNames = new Set(['u_projection', 'u_translation', 'u_tint', 'u_texture', 'u_mesh']);
+const glslUniformPattern = /\buniform\s+(?:mediump\s+|highp\s+|lowp\s+|)(\w+)\s+(\w+)[^;]*;/g;
+const wgslUserUniformPattern = /@group\(\s*2\s*\)\s*@binding\(\s*\d+\s*\)\s*var(?:<[^>]+>|)\s+(\w+)\s*:\s*([^;]+);/g;
+/**
+ * Strip line and block comments from a shader source so the uniform
+ * regexes don't match commented-out declarations. Conservative: works
+ * for both GLSL and WGSL syntax (both use `//` and `/* ... *\/`).
+ */
+function stripComments(source) {
+    return source.replaceAll(/\/\*[\s\S]*?\*\//g, '').replaceAll(/\/\/[^\n]*/g, '');
+}
+function parseGlslUniforms(vertex, fragment) {
+    const result = {};
+    for (const source of [vertex, fragment]) {
+        const stripped = stripComments(source);
+        glslUniformPattern.lastIndex = 0;
+        let match;
+        while ((match = glslUniformPattern.exec(stripped)) !== null) {
+            const [, type, name] = match;
+            result[name] = type;
+        }
+    }
+    return result;
+}
+function parseWgslUniforms(source) {
+    const result = {};
+    const stripped = stripComments(source);
+    // User uniforms in @group(2). Each user-uniform binding is either:
+    //   - var<uniform> u_user: SomeStruct;
+    //   - var u_extraTex: texture_2d<f32>;
+    // We extract the name and the (trimmed) type expression.
+    wgslUserUniformPattern.lastIndex = 0;
+    let match;
+    while ((match = wgslUserUniformPattern.exec(stripped)) !== null) {
+        const [, name, type] = match;
+        result[name] = type.trim();
+    }
+    return result;
+}
+
 /**
  * Immediate-mode 2D shape API backed by {@link Mesh} children.
  *
@@ -30796,5 +32146,5 @@ class NetworkOnlyStrategy {
     }
 }
 
-export { AbstractAssetFactory, AbstractMedia, AbstractWebGl2BatchedRenderer, AbstractWebGl2Renderer, AbstractWebGpuRenderer, AlphaFadeOverLifetime, AnimatedSprite, Application, ApplicationStatus, ApplyForce, ArcadeStickGamepadMapping, AttractToPoint, AudioAnalyser, AudioBus, AudioFilter, AudioListener, AudioManager, BeatDetector, BinaryFactory, BlendModes, BlurFilter, Bounds, BoxArea, BufferTypes, BufferUsage, BundleLoadError, BurstSpawn, CacheFirstStrategy, CallbackRenderPass, Capabilities, ChannelOffset, ChannelSize, ChorusFilter, Circle, CircleArea, Clock, CollisionType, Color, ColorFilter, ColorOverLifetime, ColorOverSpeed, CompressorFilter, ConeDirection, Constant, Container, Curve, DeathModule, DelayFilter, Drag, Drawable, DuckingFilter, DynamicGlyphAtlas, Ease, Ellipse, Envelope, EqualizerFilter, FactoryRegistry, Filter, Flags, FontFactory, GameCubeGamepadMapping, Gamepad, GamepadAxis, GamepadButton, GamepadMapping, GamepadMappingFamily, GamepadPromptLayouts, GenericDualAnalogGamepadMapping, Gradient, GranularFilter, Graphics, HighpassFilter, ImageFactory, IndexedDbDatabase, IndexedDbStore, InputBinding, InputManager, InteractionEvent, InteractionManager, Interval, JoyConLeftGamepadMapping, JoyConRightGamepadMapping, Json, JsonFactory, Keyboard, Line, LineSegment, Loader, LowpassFilter, LutFilter, Matrix, Mesh, Music, MusicFactory, NetworkOnlyStrategy, ObservableSize, ObservableVector, OrbitalForce, OscillatorSound, ParticleSystem, PitchShiftFilter, PlayStationGamepadMapping, Pointer, PointerState, PointerStateFlag, PolarVector, Polygon, Quadtree, Random, Range, RateSpawn, Rectangle, RenderBackendType, RenderNode, RenderTarget, RenderTargetPass, RenderTexture, RendererRegistry, RenderingPrimitives, RepelFromPoint, ReverbFilter, RotateOverLifetime, Sampler, ScaleModes, ScaleOverLifetime, Scene, SceneManager, SceneNode, Segment, Shader, ShaderAttribute, ShaderPrimitives, ShaderUniform, Signal, Size, Sound, SoundFactory, SoundPoolStrategy, SpawnModule, SpawnOnDeath, Sprite, SpriteFlags, Spritesheet, SteamControllerGamepadMapping, SteamDeckGamepadMapping, SvgAsset, SvgFactory, SwitchProGamepadMapping, Text, TextAsset, TextFactory, TextStyle, Texture, TextureFactory, Time, Timer, Turbulence, Tween, TweenManager, TweenState, UpdateModule, Vector, VectorRange, VelocityOverLifetime, Video, VideoFactory, View, ViewFlags, VocoderFilter, VoronoiRegion, VttAsset, VttFactory, WasmFactory, WebGl2Backend, WebGl2MeshRenderer, WebGl2ParticleRenderer, WebGl2RenderBuffer, WebGl2ShaderBlock, WebGl2ShaderFilter, WebGl2SpriteRenderer, WebGl2VertexArrayObject, WebGpuBackend, WebGpuMeshRenderer, WebGpuParticleRenderer, WebGpuShaderFilter, WebGpuSpriteRenderer, WorkletFilter, WrapModes, XboxGamepadMapping, bezierCurveTo, buildCircle, buildEllipse, buildLine, buildPath, buildPolygon, buildRectangle, buildStar, builtInGamepadDefinitions, canvasSourceToDataUrl, clamp, createRenderStats, createWebGl2ShaderProgram, crossFade, decodeAudioData, defineAssetManifest, degreesPerRadian, degreesToRadians, determineMimeType, emptyArrayBuffer, getAudioContext, getAudioManager, getCanvasSourceSize, getCollisionCircleCircle, getCollisionCircleRectangle, getCollisionEllipseCircle, getCollisionEllipseRectangle, getCollisionPolygonCircle, getCollisionRectangleRectangle, getCollisionSat, getDistance, getOfflineAudioContext, getPreciseTime, getTextureSourceSize, getVoronoiRegion$1 as getVoronoiRegion, getWebGpuBlendState, hours, inRange, intersectionCircleCircle, intersectionCircleEllipse, intersectionCirclePoly, intersectionEllipseEllipse, intersectionEllipsePoly, intersectionLineCircle, intersectionLineEllipse, intersectionLineLine, intersectionLinePoly, intersectionLineRect, intersectionPointCircle, intersectionPointEllipse, intersectionPointLine, intersectionPointPoint, intersectionPointPoly, intersectionPointRect, intersectionPolyPoly, intersectionRectCircle, intersectionRectEllipse, intersectionRectPoly, intersectionRectRect, intersectionSat, isAudioContextReady, isPowerOfTwo, layoutText, lerp, matchesIds, maxPointers, milliseconds, minutes, noop$1 as noop, onAudioContextReady, parseGamepadDescriptor, pointerSlotSize, quadraticCurveTo, radiansPerDegree, radiansToDegrees, rand, registerWorkletProcessor, removeArrayItems, resetRenderStats, resolveDefinition, resolveGamepadDefinition, seconds, sign, stopEvent, substepSweep, supportsCodec, supportsEventOptions, supportsIndexedDb, supportsPointerEvents, supportsTouchEvents, supportsWebAudio, sweepCircleAgainst, sweepCircleVsCircle, sweepCircleVsRectangle, sweepRectangle, sweepRectangleAgainst, tau$2 as tau, trimRotation, upgradeFragmentShaderToGl300, webGl2PrimitiveArrayConstructors, webGl2PrimitiveByteSizeMapping, webGl2PrimitiveTypeNames, wgslFieldLayout, wgslUniformByteSize };
+export { AbstractAssetFactory, AbstractMedia, AbstractWebGl2BatchedRenderer, AbstractWebGl2Renderer, AbstractWebGpuRenderer, AlphaFadeOverLifetime, AnimatedSprite, Application, ApplicationStatus, ApplyForce, ArcadeStickGamepadMapping, AttractToPoint, AudioAnalyser, AudioBus, AudioFilter, AudioListener, AudioManager, BeatDetector, BinaryFactory, BlendModes, BlurFilter, Bounds, BoxArea, BufferTypes, BufferUsage, BundleLoadError, BurstSpawn, CacheFirstStrategy, CallbackRenderPass, Capabilities, ChannelOffset, ChannelSize, ChorusFilter, Circle, CircleArea, Clock, CollisionType, Color, ColorFilter, ColorOverLifetime, ColorOverSpeed, CompressorFilter, ConeDirection, Constant, Container, Curve, DataTexture, DeathModule, DelayFilter, Drag, Drawable, DuckingFilter, DynamicGlyphAtlas, Ease, Ellipse, Envelope, EqualizerFilter, FactoryRegistry, Filter, Flags, FontFactory, GameCubeGamepadMapping, Gamepad, GamepadAxis, GamepadButton, GamepadMapping, GamepadMappingFamily, GamepadPromptLayouts, GenericDualAnalogGamepadMapping, Gradient, GranularFilter, Graphics, HighpassFilter, ImageFactory, IndexedDbDatabase, IndexedDbStore, InputBinding, InputManager, InteractionEvent, InteractionManager, Interval, JoyConLeftGamepadMapping, JoyConRightGamepadMapping, Json, JsonFactory, Keyboard, Line, LineSegment, Loader, LowpassFilter, LutFilter, Matrix, Mesh, MeshShader, Music, MusicFactory, NetworkOnlyStrategy, ObservableSize, ObservableVector, OrbitalForce, OscillatorSound, ParticleSystem, PitchShiftFilter, PlayStationGamepadMapping, Pointer, PointerState, PointerStateFlag, PolarVector, Polygon, Quadtree, Random, Range, RateSpawn, Rectangle, RenderBackendType, RenderNode, RenderTarget, RenderTargetPass, RenderTexture, RendererRegistry, RenderingPrimitives, RepelFromPoint, ReverbFilter, RotateOverLifetime, Sampler, ScaleModes, ScaleOverLifetime, Scene, SceneManager, SceneNode, Segment, Shader, ShaderAttribute, ShaderPrimitives, ShaderUniform, Signal, Size, Sound, SoundFactory, SoundPoolStrategy, SpawnModule, SpawnOnDeath, Sprite, SpriteFlags, Spritesheet, SteamControllerGamepadMapping, SteamDeckGamepadMapping, SvgAsset, SvgFactory, SwitchProGamepadMapping, Text, TextAsset, TextFactory, TextStyle, Texture, TextureFactory, Time, Timer, Turbulence, Tween, TweenManager, TweenState, UpdateModule, Vector, VectorRange, VelocityOverLifetime, Video, VideoFactory, View, ViewFlags, VocoderFilter, VoronoiRegion, VttAsset, VttFactory, WasmFactory, WebGl2Backend, WebGl2MeshRenderer, WebGl2ParticleRenderer, WebGl2RenderBuffer, WebGl2ShaderBlock, WebGl2ShaderFilter, WebGl2SpriteRenderer, WebGl2VertexArrayObject, WebGpuBackend, WebGpuMeshRenderer, WebGpuParticleRenderer, WebGpuShaderFilter, WebGpuSpriteRenderer, WorkletFilter, WrapModes, XboxGamepadMapping, bezierCurveTo, buildCircle, buildEllipse, buildLine, buildPath, buildPolygon, buildRectangle, buildStar, builtInGamepadDefinitions, canvasSourceToDataUrl, clamp, createRenderStats, createWebGl2ShaderProgram, crossFade, decodeAudioData, defineAssetManifest, degreesPerRadian, degreesToRadians, determineMimeType, emptyArrayBuffer, getAudioContext, getAudioManager, getCanvasSourceSize, getCollisionCircleCircle, getCollisionCircleRectangle, getCollisionEllipseCircle, getCollisionEllipseRectangle, getCollisionPolygonCircle, getCollisionRectangleRectangle, getCollisionSat, getDistance, getOfflineAudioContext, getPreciseTime, getTextureSourceSize, getVoronoiRegion$1 as getVoronoiRegion, getWebGpuBlendState, hours, inRange, intersectionCircleCircle, intersectionCircleEllipse, intersectionCirclePoly, intersectionEllipseEllipse, intersectionEllipsePoly, intersectionLineCircle, intersectionLineEllipse, intersectionLineLine, intersectionLinePoly, intersectionLineRect, intersectionPointCircle, intersectionPointEllipse, intersectionPointLine, intersectionPointPoint, intersectionPointPoly, intersectionPointRect, intersectionPolyPoly, intersectionRectCircle, intersectionRectEllipse, intersectionRectPoly, intersectionRectRect, intersectionSat, isAudioContextReady, isPowerOfTwo, layoutText, lerp, matchesIds, maxPointers, milliseconds, minutes, noop$1 as noop, onAudioContextReady, parseGamepadDescriptor, pointerSlotSize, quadraticCurveTo, radiansPerDegree, radiansToDegrees, rand, registerWorkletProcessor, removeArrayItems, resetRenderStats, resolveDefinition, resolveGamepadDefinition, seconds, sign, stopEvent, substepSweep, supportsCodec, supportsEventOptions, supportsIndexedDb, supportsPointerEvents, supportsTouchEvents, supportsWebAudio, sweepCircleAgainst, sweepCircleVsCircle, sweepCircleVsRectangle, sweepRectangle, sweepRectangleAgainst, tau$2 as tau, trimRotation, upgradeFragmentShaderToGl300, webGl2PrimitiveArrayConstructors, webGl2PrimitiveByteSizeMapping, webGl2PrimitiveTypeNames, wgslFieldLayout, wgslUniformByteSize };
 //# sourceMappingURL=exo.esm.js.map