melonjs 19.9.1 → 20.0.0

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"}

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

@@ -0,0 +1,164 @@
+import type { Matrix3d } from "../../math/matrix3d.ts";
+/**
+ * The per-instance record shared by both GPU backends (#1508).
+ *
+ * An instance carries a **row-major 3×4 affine transform** — three `vec4`
+ * rows — rather than a full 4×4: the bottom row of an affine matrix is
+ * always `(0, 0, 0, 1)`, so storing it would waste 16 bytes and a fourth
+ * attribute slot per instance. Two further slots are opt-in, declared once
+ * per instanced mesh:
+ *
+ * The transform occupies 12 floats (48 bytes); a colour slot adds 4 more
+ * (16 bytes) when `instanceColors` is declared, and a custom-data slot
+ * another 4 when `instanceData` is.
+ *
+ * Colour is four floats rather than four packed bytes for the same reason
+ * `aColor` is on the mesh vertex layout: a packed 4-byte slot can form a
+ * NaN bit pattern that Apple's Metal-backed driver canonicalizes on upload,
+ * zeroing the bytes the shader reads.
+ *
+ * The custom slot is deliberately **opaque** — the stock lit shader reads
+ * its `rgb` as emissive, while a custom mesh shader is free to read it as a
+ * wind phase, an atlas offset or a random seed.
+ * @ignore
+ */
+/**
+ * floats occupied by the 3×4 transform
+ * @ignore
+ */
+export declare const TRANSFORM_FLOATS = 12;
+/**
+ * floats occupied by an optional `vec4` slot
+ * @ignore
+ */
+export declare const SLOT_FLOATS = 4;
+/**
+ * Describes one instanced mesh's record: how wide it is and where each
+ * optional slot begins. Offsets are in floats; multiply by 4 for bytes.
+ * @ignore
+ */
+export interface InstanceRecordLayout {
+    /** floats per instance */
+    floats: number;
+    /** bytes per instance (the vertex-buffer `arrayStride`) */
+    stride: number;
+    /** float offset of the colour slot, or -1 when absent */
+    colorOffset: number;
+    /** float offset of the custom-data slot, or -1 when absent */
+    dataOffset: number;
+    /** whether the colour slot is present */
+    hasColor: boolean;
+    /** whether the custom-data slot is present */
+    hasData: boolean;
+}
+/**
+ * Build the record layout for the given opt-in slots.
+ * @param hasColor - whether a per-instance colour slot is present
+ * @param hasData - whether a per-instance custom `vec4` slot is present
+ * @returns the resolved layout
+ * @ignore
+ */
+export declare function instanceRecordLayout(hasColor: boolean, hasData: boolean): InstanceRecordLayout;
+/**
+ * Write a matrix into an instance record as three row-major `vec4` rows.
+ *
+ * `Matrix3d` stores its values **column-major** (the GL convention —
+ * translation lives at `val[12..14]`), so this transposes the upper 3×4 on
+ * the way in. The shader transposes back when it rebuilds a `mat4`.
+ * @param target - the CPU-side instance buffer
+ * @param offset - float offset of this instance's record
+ * @param matrix - the transform to write
+ * @ignore
+ */
+export declare function writeInstanceTransform(target: Float32Array, offset: number, matrix: Matrix3d): void;
+/**
+ * Write a translation / rotation / scale triple into an instance record.
+ *
+ * This is the shape authored instancing arrives in: glTF's
+ * `EXT_mesh_gpu_instancing` stores per-instance `TRANSLATION`, `ROTATION`
+ * (a quaternion) and `SCALE` accessors rather than matrices. Composing them
+ * straight into the record avoids building a `Matrix3d` per instance —
+ * a forest of five thousand trees would otherwise allocate five thousand
+ * throwaway matrices at load.
+ *
+ * The rotation is applied first, then scale, then translation (glTF's
+ * `T * R * S` convention), and the result is transposed into the record's
+ * row-major rows.
+ * @param target - the CPU-side instance buffer
+ * @param offset - float offset of this instance's record
+ * @param tx - translation x
+ * @param ty - translation y
+ * @param tz - translation z
+ * @param qx - rotation quaternion x
+ * @param qy - rotation quaternion y
+ * @param qz - rotation quaternion z
+ * @param qw - rotation quaternion w
+ * @param sx - scale x
+ * @param sy - scale y
+ * @param sz - scale z
+ * @ignore
+ */
+export declare function writeInstanceTRS(target: Float32Array, offset: number, tx: number, ty: number, tz: number, qx: number, qy: number, qz: number, qw: number, sx: number, sy: number, sz: number): void;
+/**
+ * Write an identity transform into an instance record — what a freshly
+ * grown slot holds until the caller places it, so an unplaced instance
+ * renders at the group origin rather than collapsing onto a zero matrix.
+ * @param target - the CPU-side instance buffer
+ * @param offset - float offset of this instance's record
+ * @ignore
+ */
+export declare function writeIdentityTransform(target: Float32Array, offset: number): void;
+/**
+ * Read an instance's transform back into a `Matrix3d`, undoing the
+ * row-major packing.
+ * @param source - the CPU-side instance buffer
+ * @param offset - float offset of this instance's record
+ * @param out - the matrix to write into
+ * @returns `out`
+ * @ignore
+ */
+export declare function readInstanceTransform(source: Float32Array, offset: number, out: Matrix3d): Matrix3d;
+/**
+ * The attribute names an instanced shader declares, in record order. Shared
+ * by both backends so the GL attribute records and the WGSL vertex layout
+ * describe the same thing.
+ * @ignore
+ */
+export declare const INSTANCE_ATTRIBUTE_NAMES: {
+    readonly rows: readonly ["aInstanceRow0", "aInstanceRow1", "aInstanceRow2"];
+    readonly color: "aInstanceColor";
+    readonly data: "aInstanceData";
+};
+/**
+ * Shader locations for the instance slots, counted from the first location
+ * after a tier's geometry attributes.
+ *
+ * These are **fixed per slot rather than sequential**, so a variant that
+ * omits the colour slot does not shift the data slot down. On WebGPU that is
+ * what lets one WGSL module text serve every variant — WGSL has no
+ * preprocessor to renumber `@location` with — and on WebGL it keeps the two
+ * backends describing the same thing.
+ * @ignore
+ */
+export declare const INSTANCE_SLOT_OFFSETS: {
+    readonly rows: readonly [0, 1, 2];
+    readonly color: 3;
+    readonly data: 4;
+};
+/**
+ * Backend-neutral attribute descriptors for an instance record, in the
+ * `{name, format, offset}` vocabulary both backends consume.
+ * @param layout - the record layout
+ * @param baseLocation - first shader location for this record (the location
+ * after the tier's geometry attributes). Omit on WebGL, whose attribute
+ * locations come from the shader's own declaration order.
+ * @returns attribute descriptors covering the whole record
+ * @ignore
+ */
+export declare function instanceAttributes(layout: InstanceRecordLayout, baseLocation?: number): {
+    name: string;
+    format: string;
+    offset: number;
+    shaderLocation?: number;
+}[];
+//# sourceMappingURL=instancerecord.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instancerecord.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/instancerecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACpC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,GACd,oBAAoB,CAkBtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,GACd,IAAI,CAiBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACR,IAAI,CA8BN;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,GACZ,IAAI,CAaN;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,QAAQ,GACX,QAAQ,CAoBV;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAC;AAEX;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,YAAY,CAAC,EAAE,MAAM;UASd,MAAM;YACJ,MAAM;YACN,MAAM;qBACG,MAAM;IAsCxB"}

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

@@ -0,0 +1,49 @@
+/**
+ * The versioned-remap vertex dedup shared by the mesh batchers of both
+ * backends — pure CPU code, no GPU references (the `lighting/` modules set
+ * the precedent for cross-backend sharing).
+ *
+ * The accumulated mesh path re-indexes each chunk's triangles against a
+ * chunk-local vertex range. Dedup uses a "versioned" typed-array remap
+ * rather than a `Map`: a `Map` here churned the GC badly, because V8's
+ * `Map.clear()` drops the backing table, so re-filling it each chunk
+ * reallocated as it grew — and the cost scaled with vertex count (a dense
+ * mesh = MBs/sec of garbage). Instead, `remapSlot[orig]` holds the local
+ * index assigned to original-vertex `orig` THIS chunk, valid only when
+ * `remapStamp[orig] === stamp`. Bumping `stamp` per chunk invalidates every
+ * entry in O(1) — no clearing, no allocation. The arrays grow lazily (to a
+ * power of two ≥ the largest mesh's vertex count) and are reused.
+ *
+ * Module-level sharing is safe because a chunk is built synchronously and
+ * never re-enters — only one `addMesh` runs at a time, whichever backend
+ * (or coexisting renderer) drives it, and no remap state persists across
+ * chunks.
+ * @ignore
+ */
+/**
+ * Ensure the versioned-remap scratch arrays can index every vertex of a
+ * mesh with `vertexCount` vertices. Grows to the next power of two and
+ * reuses thereafter (one-time cost when a larger mesh first appears).
+ * @ignore
+ */
+export declare function ensureRemapCapacity(vertexCount: number): void;
+/**
+ * Start a new chunk: invalidate the whole remap in O(1) and hand back the
+ * shared (emptied) chunk-index list. The stamp resets before int32 overflow
+ * (~weeks of continuous rendering away), keeping stored stamps valid.
+ * @returns the shared chunk-index array, emptied
+ * @ignore
+ */
+export declare function beginChunk(): number[];
+/**
+ * The local index assigned to `origIdx` this chunk, or -1 when the vertex
+ * has not been emitted yet.
+ * @ignore
+ */
+export declare function remapIndex(origIdx: number): number;
+/**
+ * Record the local index assigned to `origIdx` for the rest of this chunk.
+ * @ignore
+ */
+export declare function assignIndex(origIdx: number, localIdx: number): void;
+//# sourceMappingURL=meshchunk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meshchunk.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/meshchunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAQrC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGnE"}

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

@@ -0,0 +1,54 @@
+/**
+ * Retained mesh vertex-data assembly shared by the mesh batchers of both
+ * backends — pure CPU code, no GPU references (the `meshchunk.ts` /
+ * `lighting/` precedent). Kept in ONE place because the two layouts exist
+ * in an unlit and a lit variant on each backend, and the subtle parts —
+ * the ARGB unpack order and the lit path's zero-length-normal guard —
+ * must never drift between the four call sites.
+ *
+ * The data deliberately carries no placement, camera or tint information —
+ * those are uniforms — so it stays valid for the lifetime of the geometry.
+ * @ignore
+ */
+/** the minimal mesh surface this module reads — `@ignore` */
+interface RetainedMeshSource {
+    originalVertices: Float32Array;
+    originalNormals?: Float32Array | null;
+    uvs: Float32Array;
+    vertexColors?: Uint32Array | null;
+    vertexCount: number;
+}
+/**
+ * a reusable Float32Array of at least `floatCount` floats
+ * @ignore
+ */
+export declare function retainedScratch(floatCount: number): Float32Array;
+/**
+ * Write one mesh's model-space geometry into `out` in the unlit mesh
+ * layout — `x, y, z, u, v, r, g, b, a` — striding by `vertexSize`.
+ * @param mesh - the mesh to read geometry from
+ * @param out - destination scratch, at least `vertexCount × vertexSize` long
+ * @param vertexSize - floats per vertex in the hosting batcher's layout
+ * @returns number of floats written
+ * @ignore
+ */
+export declare function buildMeshVertexData(mesh: RetainedMeshSource, out: Float32Array, vertexSize: number): number;
+/**
+ * The lit variant: the unlit layout plus the model-space normal —
+ * `…, nx, ny, nz` — so lighting can be evaluated after the shader rotates
+ * it into world space.
+ *
+ * A zero-length normal must not reach the shader: it does
+ * `normalize(vNormal)`, and normalizing a zero vector is NaN — every
+ * fragment touching that vertex goes black or garbage. Degenerate
+ * triangles in OBJ/glTF assets produce these, so substitute a unit
+ * vector, matching what the CPU projection path does.
+ * @param mesh - the mesh to read geometry from
+ * @param out - destination scratch, at least `vertexCount × vertexSize` long
+ * @param vertexSize - floats per vertex in the hosting batcher's layout
+ * @returns number of floats written
+ * @ignore
+ */
+export declare function buildLitMeshVertexData(mesh: RetainedMeshSource, out: Float32Array, vertexSize: number): number;
+export {};
+//# sourceMappingURL=meshvertex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meshvertex.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/meshvertex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,6DAA6D;AAC7D,UAAU,kBAAkB;IAC3B,gBAAgB,EAAE,YAAY,CAAC;IAC/B,eAAe,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACtC,GAAG,EAAE,YAAY,CAAC;IAClB,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;CACpB;AASD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAKhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,GAChB,MAAM,CAsBR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,GAChB,MAAM,CAmCR"}