melonjs 19.9.0 → 20.0.0

package/build/video/{webgl → effects}/shadereffect.d.ts

@@ -2,9 +2,90 @@
  * A simplified shader class for applying custom fragment effects to renderables.
  * Only requires a fragment `apply()` function — the vertex shader, uniforms, and
  * texture sampling boilerplate are handled automatically.
- * In Canvas mode, the shader is silently disabled (all methods become no-ops).
+ *
+ * ## Dual-language bodies
+ *
+ * An effect body is written in the active renderer's shading language:
+ * GLSL on the WebGL renderer, WGSL on the WebGPU renderer. Pass a plain
+ * string for a GLSL-only effect (the historical form), or one body per
+ * language for an effect that runs on both backends:
+ *
+ * ```js
+ * new ShaderEffect(renderer, { glsl: glslBody, wgsl: wgslBody });
+ * ```
+ *
+ * The renderer compiles the body matching its
+ * {@link Renderer#shaderLanguage}. When no matching body exists — a
+ * GLSL-only effect on the WebGPU renderer, any effect on the Canvas
+ * renderer — the effect warns once and stays **disabled**
+ * (`enabled === false`, every method a safe no-op): the scene renders
+ * without the effect, it never breaks.
+ *
+ * ## The WGSL convention
+ *
+ * A WGSL body mirrors the GLSL one — declarations plus an apply function,
+ * compiled verbatim inside engine boilerplate:
+ *
+ * - `fn apply(color : vec4f, uv : vec2f) -> vec4f` — required; receives
+ *   the sampled, tinted pixel and its UV, returns the modified color.
+ * - Uniforms are the members of ONE struct bound as
+ *   `@group(3) @binding(0) var<uniform> fx : MyUniforms;` — member names
+ *   are the {@link ShaderEffect#setUniform} names, so a dual-language
+ *   effect uses the same uniform names in both bodies and one
+ *   `setUniform` call serves both. Supported member types: `f32`, `i32`,
+ *   `u32`, `vec2f`, `vec3f`, `vec4f`, `mat3x3f`, `mat4x4f`,
+ *   `array<vec4f, N>`.
+ * - Extra {@link ShaderEffect#setTexture} samplers are texture/sampler
+ *   pairs at explicit consecutive group-3 bindings (from 1):
+ *   `@group(3) @binding(1) var uNoise : texture_2d<f32>;`
+ *   `@group(3) @binding(2) var uNoiseSampler : sampler;`
+ * - The source texture is available as `uTexture` with `uSampler`
+ *   (`textureSample(uTexture, uSampler, uv)` — the WGSL spelling of
+ *   GLSL's `texture2D(uSampler, uv)`), and the interpolated tint as
+ *   `vColor`, under the same names as the GLSL side.
+ * - The shader builtins keep their names: `screen_uv`, `noise_uv`, and
+ *   `screen_texture` — sampled through `screen_sampler` (clamped) or
+ *   `screen_sampler_repeat` (wrapping), replacing the GLSL
+ *   `: screen_texture(repeat)` annotation.
+ * - Porting note: a texture sampled after a non-uniform `return` or
+ *   inside a varying branch must use
+ *   `textureSampleLevel(uTexture, uSampler, uv, 0.0)` (a WGSL
+ *   uniform-control-flow rule; identical output for sprite textures).
+ *
+ * ## Directional UV arithmetic (`uUVYDir`)
+ *
+ * The vertical orientation of `apply()`'s UV space depends on the draw
+ * path: sampling the sprite directly, `uv.y` grows downward, but the
+ * WebGL multi-effect (pooled) path composites through capture FBOs whose
+ * rows are bottom-up — there `uv.y` grows upward. A body that offsets its
+ * sampling coordinate vertically (a drop shadow, a directional smear)
+ * would render mirrored on that path. Declare a `float uUVYDir` uniform
+ * (WGSL: `uUVYDir : f32` in the uniform struct) and multiply vertical UV
+ * offsets by it: the renderer feeds `+1` where `uv.y` grows downward —
+ * including every WebGPU path — and `-1` on the WebGL pooled path, so
+ * "down" stays down everywhere. Initialize it to `1.0` with `setUniform`;
+ * bodies that don't declare it are unaffected. The built-in
+ * {@link DropShadowEffect} is the reference use.
  * @category Rendering
  * @example
+ * // one effect, both backends: dual-language body
+ * mySprite.shader = new ShaderEffect(renderer, {
+ *     glsl: `
+ *         uniform float uStrength;
+ *         vec4 apply(vec4 color, vec2 uv) {
+ *             return vec4(color.rgb * uStrength, color.a);
+ *         }
+ *     `,
+ *     wgsl: `
+ *         struct Fx { uStrength : f32, };
+ *         @group(3) @binding(0) var<uniform> fx : Fx;
+ *         fn apply(color : vec4f, uv : vec2f) -> vec4f {
+ *             return vec4f(color.rgb * fx.uStrength, color.a);
+ *         }
+ *     `,
+ * });
+ * mySprite.shader.setUniform("uStrength", 0.5); // sets either backend
+ * @example
  * // create a grayscale effect
  * mySprite.shader = new ShaderEffect(renderer, `
  *     vec4 apply(vec4 color, vec2 uv) {
@@ -44,13 +125,21 @@
  */
 export default class ShaderEffect {
     /**
-     * @param {WebGLRenderer|CanvasRenderer} renderer - the current renderer instance
-     * @param {string} fragmentBody - GLSL code containing a `vec4 apply(vec4 color, vec2 uv)` function
-     *   that receives the sampled pixel color and UV coordinates, and returns the modified color.
-     *   You can declare additional `uniform` variables before the `apply()` function.
-     * @param {string} [precision=auto detected] - float precision ('lowp', 'mediump' or 'highp')
+     * @param {WebGLRenderer|WebGPURenderer|CanvasRenderer} renderer - the current renderer instance
+     * @param {string|{glsl?: string, wgsl?: string}} body - the effect body:
+     *   a GLSL string (containing a `vec4 apply(vec4 color, vec2 uv)` function —
+     *   unchanged from previous versions), or an object carrying one body per
+     *   shading language (`glsl` and/or `wgsl`, the WGSL body defining
+     *   `fn apply(color : vec4f, uv : vec2f) -> vec4f`). The renderer picks the
+     *   body matching its {@link Renderer#shaderLanguage}; when no matching body
+     *   exists the effect warns once and stays disabled (`enabled === false`),
+     *   exactly like the Canvas renderer.
+     * @param {string} [precision=auto detected] - float precision ('lowp', 'mediump' or 'highp'), GLSL only
      */
-    constructor(renderer: WebGLRenderer | CanvasRenderer, fragmentBody: string, precision?: string);
+    constructor(renderer: WebGLRenderer | WebGPURenderer | CanvasRenderer, body: string | {
+        glsl?: string;
+        wgsl?: string;
+    }, precision?: string);
     /**
      * whether this effect is active (false in Canvas mode, false after
      * {@link destroy}, and false while the WebGL context is suspended
@@ -89,14 +178,25 @@ export default class ShaderEffect {
      */
     _renderer: any;
     /**
-     * the construction "recipe" (fragment body + precision), kept so
+     * the construction "recipe" (body + precision), kept VERBATIM so
      * {@link clone} can compile an independent copy. Stored before the
-     * Canvas-mode early return so cloning behaves consistently there too.
+     * disabled-stub early return so cloning behaves consistently there too.
      * @ignore
      */
-    _fragmentBody: string;
+    _fragmentBody: string | {
+        glsl?: string;
+        wgsl?: string;
+    };
     /** @ignore */
     _precision: string | undefined;
+    /**
+     * extra texture samplers bound via {@link setTexture}, keyed by the
+     * uniform name → `{ image, repeat, tex }` (`tex` is the uploaded GL
+     * texture, created lazily on first draw; unused on WebGPU, where the
+     * bind group is built lazily instead)
+     * @ignore
+     */
+    _extraTextures: Map<any, any> | undefined;
     /**
      * samplers annotated `: screen_texture` — the renderer checks this to
      * know when to refresh the shared frame capture before the effect draws
@@ -108,16 +208,11 @@ export default class ShaderEffect {
         repeat: string;
     }>;
     /** @ignore */
-    _hasNoiseUV: boolean | undefined;
+    _hasNoiseUV: any;
     /** @ignore */
     _shader: GLShader | undefined;
-    /**
-     * extra texture samplers bound via {@link setTexture}, keyed by the
-     * uniform name → `{ image, repeat, tex }` (`tex` is the uploaded GL
-     * texture, created lazily on first draw)
-     * @ignore
-     */
-    _extraTextures: Map<any, any> | undefined;
+    /** @ignore */
+    wgslRealization: WGSLEffectRealization | undefined;
     /** @private */
     private _onContextLost;
     _enabledBeforeSuspend: boolean | undefined;
@@ -153,6 +248,20 @@ export default class ShaderEffect {
      * flow.setTime(me.timer.getTime() / 1000);
      */
     setTime(seconds: number): ShaderEffect;
+    /**
+     * Feed the UV y-direction of the space `apply()` is about to run in:
+     * `+1` where `uv.y` grows downward (direct sprite sampling, and every
+     * WebGPU path), `-1` on the WebGL pooled-blit path, whose capture FBOs
+     * are bottom-up — there, y-directional UV arithmetic inside a body
+     * runs vertically mirrored unless compensated. Directional bodies
+     * (DropShadow) declare a `uUVYDir` uniform and multiply their y
+     * offsets with it, so "down" means down on every path of every
+     * backend. A silent no-op for bodies that don't declare the uniform.
+     * @param {number} dir - +1 (uv.y grows downward) or -1 (upward)
+     * @ignore
+     */
+    _setUVYDir(dir: number): void;
+    _uvYDir: any;
     /**
      * Feed the `noise_uv` builtin's frame rect for the object about to draw:
      * the source texture dimensions, the destination (object) dimensions, and
@@ -170,14 +279,12 @@ export default class ShaderEffect {
     _setNoiseUVRect(sourceWidth: number, sourceHeight: number, objectWidth: number, objectHeight: number, u0: number, v0: number): void;
     /**
      * Apply the wrap mode a `: screen_texture(<repeat>)` annotation asked for
-     * onto the live capture handle. Captures are NPOT (canvas-sized), which
-     * WebGL 1 cannot repeat — warn once and keep the clamp there. The unit is
-     * force-activated first: the batcher's bind may have been skipped as
-     * redundant while the GL active unit points elsewhere.
+     * onto the live capture handle. The unit is force-activated first: the
+     * batcher's bind may have been skipped as redundant while the GL active
+     * unit points elsewhere.
      * @ignore
      */
     _applyCaptureWrap(batcher: any, glTex: any, entry: any): void;
-    _captureWrapWarned: boolean | undefined;
     /**
      * Bind an **extra** texture to a named `sampler2D` uniform in this shader, so
      * a custom effect can read a *second* texture — a noise map, mask, gradient,
@@ -192,7 +299,7 @@ export default class ShaderEffect {
      * drawable source. No-op in Canvas mode.
      * @param {string} name - the `sampler2D` uniform name declared in the fragment
      * @param {Texture2d|HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - the texture: an engine texture asset, or a raw drawable source
-     * @param {"repeat"|"repeat-x"|"repeat-y"|"no-repeat"} [repeat="no-repeat"] - wrap mode; use `"repeat"` for a tiled/scrolled texture (power-of-two size under WebGL 1)
+     * @param {"repeat"|"repeat-x"|"repeat-y"|"no-repeat"} [repeat="no-repeat"] - wrap mode; use `"repeat"` for a tiled/scrolled texture
      * @returns {ShaderEffect} this effect for chaining
      * @example
      * // "water": distort the sprite by a static noise texture scrolled over time
@@ -269,6 +376,7 @@ export default class ShaderEffect {
      */
     destroy(): void;
 }
-import GLShader from "./glshader.js";
+import GLShader from "../webgl/glshader.js";
+import WGSLEffectRealization from "./wgsl_realization.js";
 import Texture2d from "../texture/texture2d.ts";
 //# sourceMappingURL=shadereffect.d.ts.map

package/build/video/effects/shadereffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadereffect.d.ts","sourceRoot":"","sources":["../../../src/video/effects/shadereffect.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AACH;IAiCC;;;;;;;;;;;OAWG;IACH,sBAXW,aAAa,GAAC,cAAc,GAAC,cAAc,QAC3C,MAAM,GAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,cAQrC,MAAM,EAqHhB;IA/JD;;;;;;OAMG;IACH,SAFU,OAAO,CAED;IAEhB;;;;;;;OAOG;IACH,oBAHU,OAAO,CAGC;IAElB;;;;;;;;;;OAUG;IACH,QAHU,OAAO,CAGF;IAed;;;;;;OAMG;IACH,eAAyB;IAEzB;;;;;OAKG;IACH;eA1ByB,MAAM;eAAS,MAAM;MA0BrB;IACzB,cAAc;IACd,+BAA2B;IAoB3B;;;;;;OAMG;IACH,0CAA+B;IAQ9B;;;;;OAKG;IACH,wBAHU,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAGK;IACpD,cAAc;IACd,iBAAkC;IAElC,cAAc;IACd,8BAKC;IAyBD,cAAc;IACd,mDAAkC;IAsBpC,eAAe;IACf,uBAkBC;IAbA,2CAAyC;IAe1C,eAAe;IACf,2BAQC;IAED;;;;OAIG;IACH,iBAHW,MAAM,SACN,MAAM,GAAC,YAAY,QAmB7B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAbW,MAAM,GACJ,YAAY,CAuCxB;IAED;;;;;;;;;;;OAWG;IACH,gBAHW,MAAM,QAqBhB;IATC,aAAkB;IAWpB;;;;;;;;;;;;;OAaG;IACH,6BARW,MAAM,gBACN,MAAM,eACN,MAAM,gBACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;IAED;;;;;;OAMG;IACH,8DAaC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,iBAnBW,MAAM,SACN,SAAS,GAAC,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,WACxE,QAAQ,GAAC,UAAU,GAAC,UAAU,GAAC,WAAW,GACxC,YAAY,CA0GxB;IAED;;;;;;;;OAQG;IACH,0BAHW,MAAM,QA2FhB;IA3DI,4CAAkC;IA6DvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SARa,YAAY,CAqDxB;IAKD,cAAc;IACd,aAIC;IAED,cAAc;IACd,qCAIC;IAED,cAAc;IACd,iEAIC;IAED,cAAc;IACd,mCAEC;IAED,cAAc;IACd,kBAEC;IAED,cAAc;IACd,oBAEC;IAED,cAAc;IACd,qBAEC;IAED,cAAc;IACd,uBAEC;IAED;;;;OAIG;IACH,gBAyCC;CACD;qBA34BoB,sBAAsB;kCAET,uBAAuB;sBAHnC,yBAAyB"}

package/build/video/{webgl/effects → effects}/shine.d.ts

@@ -47,7 +47,7 @@ export default class ShineEffect extends ShaderEffect {
      * @param {number} [options.pulseDepth=0.0] - subtle base-brightness pulse amplitude (0 disables the pulse)
      * @param {number} [options.pulseSpeed=3.0] - pulse oscillation rate (radians/second)
      */
-    constructor(renderer: import("../webgl_renderer.js").default, options?: {
+    constructor(renderer: any, options?: {
         color?: number[] | undefined;
         speed?: number | undefined;
         width?: number | undefined;
@@ -78,5 +78,5 @@ export default class ShineEffect extends ShaderEffect {
      */
     setBands(value: number): void;
 }
-import ShaderEffect from "../shadereffect.js";
+import ShaderEffect from "./shadereffect.js";
 //# sourceMappingURL=shine.d.ts.map

package/build/video/effects/shine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shine.d.ts","sourceRoot":"","sources":["../../../src/video/effects/shine.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH;IACC;;;;;;;;;;;OAWG;IACH,qCATG;QAA2B,KAAK;QACP,KAAK;QACL,KAAK;QACL,SAAS;QACT,KAAK;QACL,KAAK;QACL,UAAU;QACV,UAAU;KACrC,EAgEA;IAED;;;OAGG;IACH,gBAFW,MAAM,EAAE,QAIlB;IAED;;;OAGG;IACH,gBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,oBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,gBAFW,MAAM,QAIhB;CACD;yBA5LwB,mBAAmB"}

package/build/video/{webgl/effects → effects}/tintPulse.d.ts

@@ -23,7 +23,7 @@ export default class TintPulseEffect extends ShaderEffect {
      * @param {number} [options.speed=2.0] - pulse speed (oscillations per second)
      * @param {number} [options.intensity=0.3] - maximum tint strength (0.0–1.0)
      */
-    constructor(renderer: import("../webgl_renderer.js").default, options?: {
+    constructor(renderer: any, options?: {
         color?: number[] | undefined;
         speed?: number | undefined;
         intensity?: number | undefined;
@@ -39,5 +39,5 @@ export default class TintPulseEffect extends ShaderEffect {
      */
     setColor(color: number[]): void;
 }
-import ShaderEffect from "../shadereffect.js";
+import ShaderEffect from "./shadereffect.js";
 //# sourceMappingURL=tintPulse.d.ts.map

package/build/video/effects/tintPulse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tintPulse.d.ts","sourceRoot":"","sources":["../../../src/video/effects/tintPulse.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;GAgBG;AACH;IACC;;;;;;OAMG;IACH,qCAJG;QAA2B,KAAK;QACP,KAAK;QACL,SAAS;KACpC,EAqBA;IAED;;;OAGG;IACH,cAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,gBAFW,MAAM,EAAE,QAIlB;CACD;yBAjFwB,mBAAmB"}

package/build/video/{webgl/effects → effects}/vignette.d.ts

@@ -21,7 +21,7 @@ export default class VignetteEffect extends ShaderEffect {
      * @param {number} [options.strength=0.15] - edge darkening power (lower = stronger darkening, higher = softer falloff)
      * @param {number} [options.size=25.0] - vignette spread multiplier (higher = smaller dark area)
      */
-    constructor(renderer: import("../webgl_renderer.js").default, options?: {
+    constructor(renderer: any, options?: {
         strength?: number | undefined;
         size?: number | undefined;
     });
@@ -38,5 +38,5 @@ export default class VignetteEffect extends ShaderEffect {
      */
     setSize(size: number): void;
 }
-import ShaderEffect from "../shadereffect.js";
+import ShaderEffect from "./shadereffect.js";
 //# sourceMappingURL=vignette.d.ts.map

package/build/video/effects/vignette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vignette.d.ts","sourceRoot":"","sources":["../../../src/video/effects/vignette.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;GAeG;AACH;IACC;;;;;OAKG;IACH,qCAHG;QAAyB,QAAQ;QACR,IAAI;KAC/B,EASA;IALA,iBAAwC;IACxC,aAAgC;IAMjC;;;OAGG;IACH,sBAFW,MAAM,QAKhB;IAED;;;OAGG;IACH,cAFW,MAAM,QAKhB;CACD;yBA/EwB,mBAAmB"}

package/build/video/{webgl/effects → effects}/wave.d.ts

@@ -18,7 +18,7 @@ export default class WaveEffect extends ShaderEffect {
      * @param {number} [options.frequency=10.0] - number of waves across the sprite
      * @param {number} [options.speed=2.0] - wave animation speed
      */
-    constructor(renderer: import("../webgl_renderer.js").default, options?: {
+    constructor(renderer: any, options?: {
         amplitude?: number | undefined;
         frequency?: number | undefined;
         speed?: number | undefined;
@@ -39,5 +39,5 @@ export default class WaveEffect extends ShaderEffect {
      */
     setFrequency(frequency: number): void;
 }
-import ShaderEffect from "../shadereffect.js";
+import ShaderEffect from "./shadereffect.js";
 //# sourceMappingURL=wave.d.ts.map

package/build/video/effects/wave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave.d.ts","sourceRoot":"","sources":["../../../src/video/effects/wave.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;GAWG;AACH;IACC;;;;;;OAMG;IACH,qCAJG;QAAyB,SAAS;QACT,SAAS;QACT,KAAK;KAChC,EAqBA;IAED;;;OAGG;IACH,cAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,wBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,wBAFW,MAAM,QAIhB;CACD;yBArFwB,mBAAmB"}

package/build/video/effects/wgsl/layout.d.ts

@@ -0,0 +1,28 @@
+/**
+ * normalize the `vecN<f32>` / `matCxR<f32>` spellings onto the short forms
+ * used as TYPE_LAYOUT keys
+ * @param {string} type - a WGSL type token
+ * @returns {string} the canonical spelling
+ * @ignore
+ */
+export function normalizeWGSLType(type: string): string;
+/**
+ * Compute the uniform-buffer layout for a parsed struct member list.
+ * @param {Array<{name: string, type: string}>} members - struct members in declaration order
+ * @returns {{map: Map<string, {offset: number, size: number, type: string}>, size: number}|null}
+ *   the name → placement map and the total (16-byte-rounded) struct size,
+ *   or `null` when a member type is unsupported
+ * @ignore
+ */
+export function computeUniformLayout(members: Array<{
+    name: string;
+    type: string;
+}>): {
+    map: Map<string, {
+        offset: number;
+        size: number;
+        type: string;
+    }>;
+    size: number;
+} | null;
+//# sourceMappingURL=layout.d.ts.map

package/build/video/effects/wgsl/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../../src/video/effects/wgsl/layout.js"],"names":[],"mappings":"AAqCA;;;;;;GAMG;AACH,wCAJW,MAAM,GACJ,MAAM,CAQlB;AAUD;;;;;;;GAOG;AACH,8CANW,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,GACjC;IAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAuB/F"}

package/build/video/effects/wgsl/parse.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse a WGSL effect body's declarations.
+ * @param {string} body - the user WGSL body
+ * @returns {object} `{ok: true, layout, structSize, uniformVar, textures, builtins, maxUserBinding}`
+ *   or `{ok: false, error}`
+ * @ignore
+ */
+export function parseWGSLBody(body: string): object;
+//# sourceMappingURL=parse.d.ts.map

package/build/video/effects/wgsl/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/video/effects/wgsl/parse.js"],"names":[],"mappings":"AAoHA;;;;;;GAMG;AACH,oCALW,MAAM,GACJ,MAAM,CAqKlB"}

package/build/video/effects/wgsl/scaffold.d.ts

@@ -0,0 +1,43 @@
+/**
+ * WGSL module assembly for a ShaderEffect body — the WGSL counterpart of
+ * `glsl_realization.js`'s source templating. The user body is embedded
+ * VERBATIM (WGSL module-scope declarations are order-independent); the
+ * scaffold contributes the vertex/fragment entry points over the frozen
+ * 28-byte quad layout, the frame-globals and material groups, and the
+ * builtin declarations the parser detected.
+ *
+ * Frozen conventions carried over from the core quad shader:
+ * - clip-z remap `(z + w) * 0.5` (GL-convention [-w, w] → WebGPU [0, w])
+ * - packed-ARGB attribute read as (B,G,R,A) → `.bgr * .a` premultiply
+ * - `screen_uv` is y-down (`0.5 - ndc.y * 0.5`): WebGPU texture row 0 is
+ *   the top, so the capture is sampled without any flip
+ * @ignore
+ */
+/**
+ * builtin group-3 bindings are assigned ABOVE the highest user binding so
+ * they can never collide: ME uniform first, then the capture texture and
+ * its sampler variants
+ * @param {object} parsed - the parseWGSLBody result
+ * @returns {{me: number, screenTexture: number, screenSamplerClamp: number, screenSamplerRepeat: number}}
+ *   assigned binding indices (-1 when the builtin is unused)
+ * @ignore
+ */
+export function assignBuiltinBindings(parsed: object): {
+    me: number;
+    screenTexture: number;
+    screenSamplerClamp: number;
+    screenSamplerRepeat: number;
+};
+/**
+ * Assemble the complete WGSL module for an effect body.
+ * @param {string} body - the user WGSL body (embedded verbatim)
+ * @param {object} parsed - the parseWGSLBody result
+ * @returns {{code: string, bindings: object}} the module text and the
+ *   builtin binding assignment (consumed when building the bind group)
+ * @ignore
+ */
+export function buildWGSLModule(body: string, parsed: object): {
+    code: string;
+    bindings: object;
+};
+//# sourceMappingURL=scaffold.d.ts.map

package/build/video/effects/wgsl/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/video/effects/wgsl/scaffold.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,8CALW,MAAM,GACJ;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAC,CA0BxG;AAED;;;;;;;GAOG;AACH,sCANW,MAAM,UACN,MAAM,GACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAyG5C"}

package/build/video/effects/wgsl_realization.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The WGSL realization of a ShaderEffect — the WebGPU counterpart of the
+ * GLShader the GLSL branch compiles.
+ *
+ * WebGPU has no uniform reflection, so this object carries everything the
+ * backend needs to drive the effect: the parsed uniform layout (name →
+ * byte placement), a CPU-side mirror of the uniform block that
+ * `setUniform` writes into, the texture binding table, and the assembled
+ * module text. GPU objects (shader module, bind group layout, bind group)
+ * are built lazily by the renderer's effect path — uniform VALUES are
+ * snapshotted from the mirror into a per-frame arena at every bind, so a
+ * shared effect bound twice in a frame with different values stays
+ * correct under WebGPU's queue-write-before-draws ordering.
+ * @ignore
+ */
+export default class WGSLEffectRealization {
+    /**
+     * Parse + assemble; on any parse failure `valid` is false and `error`
+     * carries the reason (the effect then warns and stays disabled).
+     * @param {string} body - the user WGSL body
+     */
+    constructor(body: string);
+    /**
+     * whether the body parsed into a realizable shape
+     * @type {boolean}
+     */
+    valid: boolean;
+    /** @type {string|null} */
+    error: string | null;
+    /** name → {offset, size, type} placement in the uniform block */
+    layout: any;
+    /** total uniform block byte size (0 = no uniform struct) */
+    structSize: any;
+    /** user texture/sampler pairs (binding table) */
+    textures: any;
+    /** builtin usage flags */
+    builtins: any;
+    /** the complete assembled WGSL module text */
+    code: string | undefined;
+    /** builtin binding assignment (ME / capture texture / samplers) */
+    builtinBindings: object | undefined;
+    cpu: ArrayBuffer | undefined;
+    f32: Float32Array<ArrayBuffer> | undefined;
+    i32: Int32Array<ArrayBuffer> | undefined;
+    u32: Uint32Array<ArrayBuffer> | undefined;
+    meMirror: Float32Array<ArrayBuffer> | undefined;
+    /**
+     * last user-set value per uniform name — the clone-replay source
+     * (exact values, not mirror read-back)
+     * @type {Map<string, number|number[]>}
+     */
+    values: Map<string, number | number[]>;
+    warned: Set<any> | undefined;
+    /**
+     * device-scoped GPU state, built lazily by the renderer's effect
+     * path and invalidated via the pipeline-cache epoch (device loss)
+     * @type {object|null}
+     */
+    gpu: object | null;
+    /**
+     * Write a uniform value into the CPU mirror.
+     * @param {string} name - a struct member name of the body's uniform block
+     * @param {number|number[]|Float32Array|{val: Float32Array}} value - the value
+     *   (objects exposing `.val` — Matrix2d/3d, ColorMatrix — are unwrapped)
+     * @returns {boolean} true when the name exists and the value was written
+     */
+    setUniform(name: string, value: number | number[] | Float32Array | {
+        val: Float32Array;
+    }): boolean;
+    /**
+     * whether the uniform block declares the given member (the WGSL
+     * counterpart of the GLSL active-uniform check `setTime` relies on)
+     * @param {string} name - member name
+     * @returns {boolean} true when present
+     */
+    hasUniform(name: string): boolean;
+    /**
+     * drop device-scoped state (device loss / destroy) — the CPU mirror
+     * and values survive, so nothing needs replaying on restore
+     */
+    releaseGPU(): void;
+}
+//# sourceMappingURL=wgsl_realization.d.ts.map

package/build/video/effects/wgsl_realization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl_realization.d.ts","sourceRoot":"","sources":["../../../src/video/effects/wgsl_realization.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH;IACC;;;;OAIG;IACH,kBAFW,MAAM,EA2DhB;IAtDA;;;OAGG;IACH,OAFU,OAAO,CAEc;IAC/B,0BAA0B;IAC1B,OADW,MAAM,GAAC,IAAI,CAC+B;IAMrD,iEAAiE;IACjE,YAA2B;IAC3B,4DAA4D;IAC5D,gBAAmC;IACnC,iDAAiD;IACjD,cAA+B;IAC/B,0BAA0B;IAC1B,cAA+B;IAG/B,8CAA8C;IAC9C,yBAAuB;IACvB,mEAAmE;IACnE,oCAAsC;IAGtC,6BAAwD;IACxD,2CAAqC;IACrC,yCAAmC;IACnC,0CAAoC;IAIpC,gDAAmC;IAEnC;;;;OAIG;IACH,QAFU,GAAG,CAAC,MAAM,EAAE,MAAM,GAAC,MAAM,EAAE,CAAC,CAEf;IAIvB,6BAAuB;IAEvB;;;;OAIG;IACH,KAFU,MAAM,GAAC,IAAI,CAEN;IAGhB;;;;;;OAMG;IACH,iBALW,MAAM,SACN,MAAM,GAAC,MAAM,EAAE,GAAC,YAAY,GAAC;QAAC,GAAG,EAAE,YAAY,CAAA;KAAC,GAE9C,OAAO,CAwDnB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAEC;CACD"}

package/build/video/gpu/batcher.d.ts

@@ -0,0 +1,71 @@
+/**
+ * additional import for TypeScript
+ * @import Renderer from "../renderer.js";
+ */
+/**
+ * Default maximum number of vertices per batch.
+ * At 4096 vertices (1024 quads), the vertex buffer is ~80 KB (5 floats × 4 bytes × 4096),
+ * which balances draw call reduction with safe buffer upload sizes on mobile tile-based GPUs.
+ * Within the Uint16 index limit (65,535) — a deliberate capacity choice
+ * (smaller index uploads), not an API constraint.
+ * @ignore
+ */
+export const DEFAULT_MAX_VERTICES: 4096;
+/**
+ * Backend-neutral base class for renderer batchers.
+ *
+ * A batcher accumulates vertices into a CPU staging buffer and turns them
+ * into GPU work in batches — one draw call for many shapes/sprites. This
+ * class defines the lifecycle contract shared by every backend:
+ *
+ * - `init(renderer, settings)` — build (or rebuild after a context/device
+ *   loss) the batcher's GPU-facing state; called by the constructor
+ * - `bind()` / `unbind()` — the renderer switches the active batcher
+ * - `flush()` — turn the pending vertices into GPU work
+ * - `reset()` — drop transient state (game reset / context restore)
+ * - `destroy()` — release every GPU resource the batcher owns
+ *
+ * Custom batchers extend the class matching the renderer they target —
+ * {@link WebGLBatcher} for the WebGL renderer, `WebGPUBatcher` for the
+ * WebGPU renderer — and are registered through `renderer.addBatcher()`,
+ * which accepts any Batcher subclass.
+ * @category Rendering
+ */
+export class Batcher {
+    /**
+     * Initialize (or re-initialize after a context/device loss) this batcher.
+     * Derived classes override this with their full `(renderer, settings)`
+     * signature and own the whole body; the base implementation only stores
+     * the renderer reference.
+     * @param {Renderer} renderer - the owning renderer
+     */
+    init(renderer: Renderer): void;
+    /**
+     * the renderer this batcher is bound to
+     * @type {Renderer}
+     */
+    renderer: Renderer | undefined;
+    /**
+     * called by the renderer when this batcher becomes the current one
+     */
+    bind(): void;
+    /**
+     * called by the renderer when this batcher is being replaced by another
+     */
+    unbind(): void;
+    /**
+     * turn the pending vertices into GPU work
+     */
+    flush(): void;
+    /**
+     * reset the batcher's transient state (game reset / context restore)
+     */
+    reset(): void;
+    /**
+     * release every GPU resource this batcher owns
+     */
+    destroy(): void;
+}
+export default Batcher;
+import type Renderer from "../renderer.js";
+//# sourceMappingURL=batcher.d.ts.map

package/build/video/gpu/batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/batcher.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,mCAAoC,IAAI,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAMC;;;;;;OAMG;IACH,eAFW,QAAQ,QAQlB;IALA;;;OAGG;IACH,+BAAwB;IAGzB;;OAEG;IACH,aAAS;IAET;;OAEG;IACH,eAAW;IAEX;;OAEG;IACH,cAAU;IAEV;;OAEG;IACH,cAAU;IAEV;;OAEG;IACH,gBAAY;CACZ;;0BA9EwB,gBAAgB"}