@woosh/meep-engine 3.11.1 → 3.11.2

package/src/shade/wgsl/emulator/WGSLLanguageCore.js

@@ -1,1117 +1,1297 @@
-import { assert } from "../../../core/assert.js";
-import { cpu_texture_sample } from "./cpu_texture_sample.js";
-
-/**
- * Default sampler descriptor for `textureSample` / `textureSampleLevel`
- * calls when the bound sampler is `null` (common in tests). Linear filter,
- * clamp-to-edge on every axis - matches what most engine passes use.
- */
-const FALLBACK_LINEAR_CLAMP_SAMPLER = Object.freeze({
-    addressModeU: "clamp-to-edge",
-    addressModeV: "clamp-to-edge",
-    addressModeW: "clamp-to-edge",
-    magFilter: "linear",
-    minFilter: "linear",
-    mipmapFilter: "nearest",
-});
-
-/**
- * Single-element scratch view used to round a number to IEEE 754 binary16 precision.
- * @type {Float16Array}
- */
-const F16_SCRATCH = new Float16Array(1);
-
-/**
- * Shared scratch buffer for `bitcast` — three views over the same 4 bytes so we can
- * reinterpret one type as another in O(1) without per-call allocation.
- */
-const BITCAST_BUFFER = new ArrayBuffer(4);
-const BITCAST_U32 = new Uint32Array(BITCAST_BUFFER);
-const BITCAST_I32 = new Int32Array(BITCAST_BUFFER);
-const BITCAST_F32 = new Float32Array(BITCAST_BUFFER);
-
-/**
- * Construct a WGSL vector. Mirrors WGSL `vecN<T>(...)` semantics:
- *
- * - **No args** → zero-filled.
- * - **One scalar** → broadcast to all `size` components (`vec3(1.0)` → `[1, 1, 1]`).
- * - **Exactly `size` scalars** → use as components.
- * - **Any mix of scalars and shorter vectors** that flattens to exactly `size` numbers (e.g.
- *   `vec3(vec2_xy, z)` or `vec4(x, vec2_yz, w)`).
- *
- * @param {Float32ArrayConstructor | Float16ArrayConstructor | Int32ArrayConstructor | Uint32ArrayConstructor} TypedArrayCtor
- * @param {number} size
- * @param {*[]} args
- * @returns {*}
- */
-function makeVec(TypedArrayCtor, size, args) {
-    if (args.length === 0) {
-        return new TypedArrayCtor(size);
-    }
-    // Single scalar → broadcast.
-    if (args.length === 1 && typeof args[0] === 'number') {
-        const v = args[0];
-        const out = new TypedArrayCtor(size);
-        for (let i = 0; i < size; i++) out[i] = v;
-        return out;
-    }
-    // Otherwise flatten.
-    const out = new TypedArrayCtor(size);
-    let i = 0;
-    for (const a of args) {
-        if (typeof a === 'number' || typeof a === 'boolean') {
-            out[i++] = +a;
-        } else if (a != null && typeof a.length === 'number') {
-            for (let j = 0; j < a.length; j++) out[i++] = a[j];
-        }
-    }
-    return out;
-}
-
-/**
- * Build a matrix constructor returning a typed array of `total_elements` entries. The returned
- * function accepts (a) no args → zero-filled, (b) `total_elements` scalars in column-major order,
- * (c) one column-vec per matrix column, or (d) any mix that flattens to `total_elements` numbers.
- *
- * @param {Float32ArrayConstructor | Float16ArrayConstructor} TypedArrayCtor
- * @param {number} total_elements
- * @returns {function(...*): Float32Array | Float16Array}
- */
-function makeMatCtor(TypedArrayCtor, total_elements) {
-    return (...args) => {
-        if (args.length === 0) {
-            return new TypedArrayCtor(total_elements);
-        }
-        const flat = new TypedArrayCtor(total_elements);
-        let i = 0;
-        for (const a of args) {
-            if (typeof a === 'number') {
-                flat[i++] = a;
-            } else if (a != null && typeof a.length === 'number') {
-                for (let j = 0; j < a.length; j++) flat[i++] = a[j];
-            }
-        }
-        return flat;
-    };
-}
-
-/**
- * @param {number} a
- * @returns {number}
- */
-function as_i32(a) {
-    return (a | 0);
-}
-
-/**
- * @param {number} a
- * @returns {number}
- */
-function as_u32(a) {
-    return (a >>> 0);
-}
-
-/**
- * Determine if a value is a vector — TypedArray (vec2f / vec3i / etc) or
- * a plain JS Array (returned from comparison ops like `eq` / `ge`, since
- * those produce arrays of bools). Either way, a vec is a length-N
- * iterable of element values, distinguished from a scalar number or a
- * struct.
- * @param {*} v
- * @returns {boolean}
- */
-function is_vec(v) {
-    if (v == null || typeof v !== 'object') return false;
-    if (typeof v.BYTES_PER_ELEMENT === 'number') return true;   // TypedArray (vecNf / vecNi / ...)
-    if (Array.isArray(v)) return true;                          // plain JS Array — vec result from binop_cmp
-    return false;
-}
-
-/**
- * Element-wise apply a binary op over a vector and scalar/vector counterpart.
- * @param {*} a
- * @param {*} b
- * @param {function(number, number): number} op
- * @returns {*}
- */
-function binop(a, b, op) {
-    const a_vec = is_vec(a);
-    const b_vec = is_vec(b);
-
-    if (!a_vec && !b_vec) {
-        return op(a, b);
-    }
-
-    if (a_vec && b_vec) {
-        assert.equal(a.length, b.length, 'vector length mismatch');
-        const out = new a.constructor(a.length);
-        for (let i = 0; i < a.length; i++) {
-            out[i] = op(a[i], b[i]);
-        }
-        return out;
-    }
-
-    if (a_vec) {
-        const out = new a.constructor(a.length);
-        for (let i = 0; i < a.length; i++) {
-            out[i] = op(a[i], b);
-        }
-        return out;
-    }
-
-    // b_vec
-    const out = new b.constructor(b.length);
-    for (let i = 0; i < b.length; i++) {
-        out[i] = op(a, b[i]);
-    }
-    return out;
-}
-
-/**
- * Element-wise apply a comparison op. For scalar operands returns a single boolean; for
- * vector operands returns a plain `Array<boolean>` matching the WGSL `vec<bool>` shape.
- * @param {*} a
- * @param {*} b
- * @param {function(number, number): boolean} op
- * @returns {boolean | boolean[]}
- */
-function binop_cmp(a, b, op) {
-    const a_vec = is_vec(a);
-    const b_vec = is_vec(b);
-
-    if (!a_vec && !b_vec) {
-        return op(a, b);
-    }
-    const length = a_vec ? a.length : b.length;
-    const out = new Array(length);
-    for (let i = 0; i < length; i++) {
-        const ai = a_vec ? a[i] : a;
-        const bi = b_vec ? b[i] : b;
-        out[i] = op(ai, bi);
-    }
-    return out;
-}
-
-/**
- * Element-wise apply a unary op over a scalar/vector.
- * @param {*} a
- * @param {function(number): number} op
- * @returns {*}
- */
-function unop(a, op) {
-    if (!is_vec(a)) {
-        return op(a);
-    }
-    const out = new a.constructor(a.length);
-    for (let i = 0; i < a.length; i++) {
-        out[i] = op(a[i]);
-    }
-    return out;
-}
-
-/**
- * Element-wise apply a ternary op (e.g. mix, clamp).
- * @param {*} a
- * @param {*} b
- * @param {*} c
- * @param {function(number, number, number): number} op
- * @returns {*}
- */
-function ternop(a, b, c, op) {
-    if (is_vec(a) || is_vec(b) || is_vec(c)) {
-        const length = (is_vec(a) ? a.length : (is_vec(b) ? b.length : c.length));
-        const ctor = (is_vec(a) ? a.constructor : (is_vec(b) ? b.constructor : c.constructor));
-        const out = new ctor(length);
-        for (let i = 0; i < length; i++) {
-            const ai = is_vec(a) ? a[i] : a;
-            const bi = is_vec(b) ? b[i] : b;
-            const ci = is_vec(c) ? c[i] : c;
-            out[i] = op(ai, bi, ci);
-        }
-        return out;
-    }
-    return op(a, b, c);
-}
-
-/**
- * The default WGSL language core — the `wgsl` object passed into the generated JS.
- *
- * Provides:
- * - vector / matrix constructors (`vec3f`, `vec2u`, etc.)
- * - scalar constructors / casts (`f32`, `i32`, `u32`, `bool`)
- * - arithmetic helpers (`add`, `sub`, `mul`, `div`, `mod`, `neg`)
- * - WGSL builtins (`mix`, `clamp`, `min`, `max`, `abs`, `floor`, `ceil`, `pow`, ...)
- * - texture intrinsics (`textureLoad`, `textureSampleLevel`)
- * - control flow helpers (`workgroupBarrier`, `storageBarrier`)
- *
- * @type {object}
- */
-export const WGSLLanguageCore = {
-    // ---------------------------------------------------------------------
-    // Scalar casts
-    // ---------------------------------------------------------------------
-
-    /** Cast to i32. */
-    i32(v) {
-        if (typeof v === 'boolean') return v ? 1 : 0;
-        return as_i32(v);
-    },
-
-    /** Cast to u32. */
-    u32(v) {
-        if (typeof v === 'boolean') return v ? 1 : 0;
-        return as_u32(v);
-    },
-
-    /** Cast to f32 (no-op in JS, returns the number). */
-    f32(v) {
-        if (typeof v === 'boolean') return v ? 1 : 0;
-        return Math.fround(+v);
-    },
-
-    /** Cast to f16. Truncates to IEEE 754 binary16 precision via Float16Array. */
-    f16(v) {
-        if (typeof v === 'boolean') return v ? 1 : 0;
-        F16_SCRATCH[0] = +v;
-        return F16_SCRATCH[0];
-    },
-
-    /** Cast to bool. */
-    bool(v) {
-        return !!v;
-    },
-
-    // ---------------------------------------------------------------------
-    // Vector constructors
-    // ---------------------------------------------------------------------
-
-    vec2f: (...args) => makeVec(Float32Array, 2, args),
-    vec3f: (...args) => makeVec(Float32Array, 3, args),
-    vec4f: (...args) => makeVec(Float32Array, 4, args),
-
-    vec2h: (...args) => makeVec(Float16Array, 2, args),
-    vec3h: (...args) => makeVec(Float16Array, 3, args),
-    vec4h: (...args) => makeVec(Float16Array, 4, args),
-
-    vec2i: (...args) => makeVec(Int32Array, 2, args),
-    vec3i: (...args) => makeVec(Int32Array, 3, args),
-    vec4i: (...args) => makeVec(Int32Array, 4, args),
-
-    vec2u: (...args) => makeVec(Uint32Array, 2, args),
-    vec3u: (...args) => makeVec(Uint32Array, 3, args),
-    vec4u: (...args) => makeVec(Uint32Array, 4, args),
-
-    // ---------------------------------------------------------------------
-    // Matrix constructors — column-major flat arrays. matCxR has C columns of R rows each,
-    // for a total of C*R entries. Args may be scalars, column vectors, or a mix.
-    // ---------------------------------------------------------------------
-
-    mat2x2f: makeMatCtor(Float32Array, 4),
-    mat2x3f: makeMatCtor(Float32Array, 6),
-    mat2x4f: makeMatCtor(Float32Array, 8),
-    mat3x2f: makeMatCtor(Float32Array, 6),
-    mat3x3f: makeMatCtor(Float32Array, 9),
-    mat3x4f: makeMatCtor(Float32Array, 12),
-    mat4x2f: makeMatCtor(Float32Array, 8),
-    mat4x3f: makeMatCtor(Float32Array, 12),
-    mat4x4f: makeMatCtor(Float32Array, 16),
-
-    mat2x2h: makeMatCtor(Float16Array, 4),
-    mat2x3h: makeMatCtor(Float16Array, 6),
-    mat2x4h: makeMatCtor(Float16Array, 8),
-    mat3x2h: makeMatCtor(Float16Array, 6),
-    mat3x3h: makeMatCtor(Float16Array, 9),
-    mat3x4h: makeMatCtor(Float16Array, 12),
-    mat4x2h: makeMatCtor(Float16Array, 8),
-    mat4x3h: makeMatCtor(Float16Array, 12),
-    mat4x4h: makeMatCtor(Float16Array, 16),
-
-    /**
-     * Return column `i` of a column-major matrix as a vec view (no copy). Used by the compiler
-     * to translate WGSL `m[i]` — which yields a vec — onto our flat-typed-array storage.
-     * @param {Float32Array|Float16Array} m
-     * @param {number} i
-     * @param {number} rows
-     */
-    mat_col(m, i, rows) {
-        return m.subarray(i * rows, (i + 1) * rows);
-    },
-
-    /**
-     * Store a whole value through a pointer: WGSL's `*p = value`. Returns what the pointer variable
-     * should now hold, which the caller assigns back.
-     *
-     * Pointers are modelled as the pointee itself, so `*p = value` used to compile to a plain
-     * assignment to the parameter binding — which rebinds the callee's local and leaves the
-     * caller's object untouched. Every shader returning a result through an out-parameter then read
-     * back whatever it had initialised the variable to, silently and with nothing raised:
-     * `ray_triangle_compute_intersection_barycentric` reported hits at a distance of zero, which is
-     * a hit the traversal keeps and shades.
-     *
-     * Vectors, matrices and structs are objects, so the store goes through the reference and the
-     * caller sees it. **A pointer to a scalar still cannot**: a JavaScript number has no identity
-     * to write through, so the rebind is all there is, and a caller passing `&some_f32` sees its
-     * variable unchanged. Within the callee the value is right — `*p` reads back what `*p = …`
-     * wrote — so the in-out scalar accumulators in `sample_discrete_wrs_*` behave, and only a
-     * result handed *out* through a scalar pointer is lost. Widen such an out-parameter to a
-     * vector or a struct, or return it, if a test needs to see it.
-     *
-     * @param {Float32Array|Float16Array|Uint32Array|Int32Array|Array|object|number|boolean} target
-     * @param {ArrayLike<number>|object|number|boolean} value
-     * @returns {*} the value the pointer variable should be rebound to
-     */
-    store_ptr(target, value) {
-        if (ArrayBuffer.isView(target) || Array.isArray(target)) {
-            for (let i = 0; i < target.length; i++) {
-                target[i] = value[i];
-            }
-
-            return target;
-        }
-
-        if (target !== null && typeof target === 'object') {
-            Object.assign(target, value);
-
-            return target;
-        }
-
-        return value;
-    },
-
-    /**
-     * Determinant of a square matrix stored as a flat column-major typed array.
-     * Supports the WGSL square-matrix sizes: 2x2, 3x3, 4x4.
-     * @param {Float32Array|Float16Array} m
-     */
-    determinant(m) {
-        if (m.length === 4) {
-            return m[0] * m[3] - m[1] * m[2];
-        }
-        if (m.length === 9) {
-            return m[0] * (m[4] * m[8] - m[5] * m[7])
-                - m[3] * (m[1] * m[8] - m[2] * m[7])
-                + m[6] * (m[1] * m[5] - m[2] * m[4]);
-        }
-        if (m.length === 16) {
-            // 4x4 expansion via 2x2 minors of the bottom rows.
-            const s0 = m[0] * m[5] - m[1] * m[4];
-            const s1 = m[0] * m[6] - m[2] * m[4];
-            const s2 = m[0] * m[7] - m[3] * m[4];
-            const s3 = m[1] * m[6] - m[2] * m[5];
-            const s4 = m[1] * m[7] - m[3] * m[5];
-            const s5 = m[2] * m[7] - m[3] * m[6];
-            const c5 = m[10] * m[15] - m[11] * m[14];
-            const c4 = m[ 9] * m[15] - m[11] * m[13];
-            const c3 = m[ 9] * m[14] - m[10] * m[13];
-            const c2 = m[ 8] * m[15] - m[11] * m[12];
-            const c1 = m[ 8] * m[14] - m[10] * m[12];
-            const c0 = m[ 8] * m[13] - m[ 9] * m[12];
-            return s0 * c5 - s1 * c4 + s2 * c3 + s3 * c2 - s4 * c1 + s5 * c0;
-        }
-        throw new Error(`determinant: unsupported matrix length ${m.length}`);
-    },
-
-    // ---------------------------------------------------------------------
-    // Arithmetic helpers (work on scalars and vectors element-wise)
-    // ---------------------------------------------------------------------
-
-    add: (a, b) => binop(a, b, (x, y) => x + y),
-    sub: (a, b) => binop(a, b, (x, y) => x - y),
-    mul: (a, b) => binop(a, b, (x, y) => x * y),
-    div: (a, b) => binop(a, b, (x, y) => x / y),
-    rem: (a, b) => binop(a, b, (x, y) => x % y),
-
-    // Integer division — truncates toward zero, matching WGSL `/` semantics on integer types.
-    // The compiler routes `/` through `idiv` when both operands' tracked types are integer.
-    idiv: (a, b) => binop(a, b, (x, y) => Math.trunc(x / y)),
-
-    // Element-wise bitwise / shift helpers. JS's raw `&` / `|` / `^` / `<<` / `>>` work on
-    // scalars but not typed arrays (they coerce the array to a number → NaN), so the compiler
-    // routes vec/mat operands through these. Right-shift uses `>>>` (unsigned) to match WGSL
-    // u32 semantics; signed sources should bitcast first.
-    bit_and: (a, b) => binop(a, b, (x, y) => (x & y) >>> 0),
-    bit_or:  (a, b) => binop(a, b, (x, y) => (x | y) >>> 0),
-    bit_xor: (a, b) => binop(a, b, (x, y) => (x ^ y) >>> 0),
-    shl:     (a, b) => binop(a, b, (x, y) => (x << y) >>> 0),
-    shr:     (a, b) => binop(a, b, (x, y) => x >>> y),
-
-    neg: (a) => unop(a, x => -x),
-    not: (a) => unop(a, x => (~x) >>> 0),
-
-    // Bit-field extract / insert (WGSL §17.9). Component-wise over vectors; `offset` and
-    // `count` are scalar u32 even when `e` / `newbits` are vectors, matching the WGSL
-    // signatures. Like `shr`, these implement the UNSIGNED reading — extracted bits are
-    // zero-extended, not sign-extended — so an i32 source needing sign extension should
-    // bitcast first. Per the spec, `o = min(offset, 32)` and `c = min(count, 32 - o)`.
-
-    /** `extractBits(e, offset, count)` — read `count` bits at `offset`, zero-extended. */
-    extractBits(e, offset, count) {
-        const o = Math.min(offset >>> 0, 32);
-        const c = Math.min(count >>> 0, 32 - o);
-        return unop(e, (x) => {
-            if (c === 0) {
-                return 0;
-            }
-            const mask = c >= 32 ? 0xFFFFFFFF : ((1 << c) - 1);
-            return ((x >>> o) & mask) >>> 0;
-        });
-    },
-
-    // Bit counting (WGSL §17.9). Component-wise over vectors. All of these read their operand as
-    // 32 bits regardless of whether the WGSL type was u32 or i32 — which is what the spec says and
-    // what makes `countLeadingZeros` the exact counterpart of JS's `Math.clz32`.
-
-    /** `countLeadingZeros(e)` — number of consecutive zero bits above the most significant set bit; 32 for 0. */
-    countLeadingZeros: (e) => unop(e, x => Math.clz32(x)),
-
-    /** `countTrailingZeros(e)` — number of consecutive zero bits below the least significant set bit; 32 for 0. */
-    countTrailingZeros: (e) => unop(e, x => (x === 0 ? 32 : 31 - Math.clz32(x & -x))),
-
-    /** `countOneBits(e)` — population count. */
-    countOneBits: (e) => unop(e, x => {
-        let bits = x >>> 0;
-        let count = 0;
-
-        while (bits !== 0) {
-            bits &= bits - 1;
-            count += 1;
-        }
-
-        return count;
-    }),
-
-    /** `firstLeadingBit(e)` — index of the most significant set bit; `0xffffffff` for 0 (u32 reading). */
-    firstLeadingBit: (e) => unop(e, x => (x === 0 ? 0xffffffff : 31 - Math.clz32(x))),
-
-    /** `firstTrailingBit(e)` — index of the least significant set bit; `0xffffffff` for 0. */
-    firstTrailingBit: (e) => unop(e, x => (x === 0 ? 0xffffffff : 31 - Math.clz32(x & -x))),
-
-    /** `reverseBits(e)` — reverse the order of all 32 bits. */
-    reverseBits: (e) => unop(e, x => {
-        let source = x >>> 0;
-        let reversed = 0;
-
-        for (let i = 0; i < 32; i++) {
-            reversed = ((reversed << 1) | (source & 1)) >>> 0;
-            source >>>= 1;
-        }
-
-        return reversed;
-    }),
-
-    /** `insertBits(e, newbits, offset, count)` — replace bits `[offset, offset+count)` of `e` with the low `count` bits of `newbits`. */
-    insertBits(e, newbits, offset, count) {
-        const o = Math.min(offset >>> 0, 32);
-        const c = Math.min(count >>> 0, 32 - o);
-        return binop(e, newbits, (x, ins) => {
-            if (c === 0) {
-                return x >>> 0;
-            }
-            const base_mask = c >= 32 ? 0xFFFFFFFF : ((1 << c) - 1);
-            const field_mask = o >= 32 ? 0 : ((base_mask << o) >>> 0);
-            return (((ins << o) & field_mask) | (x & ((~field_mask) >>> 0))) >>> 0;
-        });
-    },
-
-    // ---------------------------------------------------------------------
-    // WGSL math builtins
-    // ---------------------------------------------------------------------
-
-    abs: (a) => unop(a, Math.abs),
-    sign: (a) => unop(a, Math.sign),
-    floor: (a) => unop(a, Math.floor),
-    ceil: (a) => unop(a, Math.ceil),
-    round: (a) => unop(a, Math.round),
-    trunc: (a) => unop(a, Math.trunc),
-    fract: (a) => unop(a, x => x - Math.floor(x)),
-    sqrt: (a) => unop(a, Math.sqrt),
-    inverseSqrt: (a) => unop(a, x => 1 / Math.sqrt(x)),
-    exp: (a) => unop(a, Math.exp),
-    exp2: (a) => unop(a, x => Math.pow(2, x)),
-    log: (a) => unop(a, Math.log),
-    log2: (a) => unop(a, Math.log2),
-    sin: (a) => unop(a, Math.sin),
-    cos: (a) => unop(a, Math.cos),
-    tan: (a) => unop(a, Math.tan),
-    asin: (a) => unop(a, Math.asin),
-    acos: (a) => unop(a, Math.acos),
-    atan: (a) => unop(a, Math.atan),
-
-    pow: (a, b) => binop(a, b, Math.pow),
-    atan2: (a, b) => binop(a, b, Math.atan2),
-    min: (a, b) => binop(a, b, Math.min),
-    max: (a, b) => binop(a, b, Math.max),
-    step: (edge, x) => binop(edge, x, (e, v) => v < e ? 0 : 1),
-
-    clamp: (x, lo, hi) => ternop(x, lo, hi, (v, l, h) => Math.max(l, Math.min(h, v))),
-    // Saturate is `clamp(x, 0, 1)`. WGSL builtin.
-    saturate: (a) => unop(a, x => Math.max(0, Math.min(1, x))),
-    mix: (a, b, t) => ternop(a, b, t, (x, y, k) => x * (1 - k) + y * k),
-    // Fused multiply-add: `a * b + c`. JS lacks a true FMA; this is mathematically equivalent
-    // but loses the single-rounding precision benefit of hardware FMA — fine for testing.
-    fma: (a, b, c) => ternop(a, b, c, (x, y, z) => x * y + z),
-    smoothstep: (edge0, edge1, x) => ternop(edge0, edge1, x, (e0, e1, v) => {
-        const t = Math.max(0, Math.min(1, (v - e0) / (e1 - e0)));
-        return t * t * (3 - 2 * t);
-    }),
-
-    // ---------------------------------------------------------------------
-    // Vector operations
-    // ---------------------------------------------------------------------
-
-    dot(a, b) {
-        assert.equal(a.length, b.length, 'dot vector length mismatch');
-        let s = 0;
-        for (let i = 0; i < a.length; i++) s += a[i] * b[i];
-        return s;
-    },
-
-    length(v) {
-        if (!is_vec(v)) return Math.abs(v);
-        let s = 0;
-        for (let i = 0; i < v.length; i++) s += v[i] * v[i];
-        return Math.sqrt(s);
-    },
-
-    distance(a, b) {
-        return WGSLLanguageCore.length(WGSLLanguageCore.sub(a, b));
-    },
-
-    normalize(v) {
-        const len = WGSLLanguageCore.length(v);
-        if (len === 0) {
-            return new v.constructor(v.length);
-        }
-        const out = new v.constructor(v.length);
-        for (let i = 0; i < v.length; i++) out[i] = v[i] / len;
-        return out;
-    },
-
-    cross(a, b) {
-        assert.equal(a.length, 3, 'cross requires vec3');
-        assert.equal(b.length, 3, 'cross requires vec3');
-        return new a.constructor([
-            a[1] * b[2] - a[2] * b[1],
-            a[2] * b[0] - a[0] * b[2],
-            a[0] * b[1] - a[1] * b[0],
-        ]);
-    },
-
-    reflect(i, n) {
-        const d = WGSLLanguageCore.dot(i, n);
-        const out = new i.constructor(i.length);
-        for (let k = 0; k < i.length; k++) out[k] = i[k] - 2 * d * n[k];
-        return out;
-    },
-
-    // ---------------------------------------------------------------------
-    // Matrix × {matrix, vector} and vector × matrix products.
-    //
-    // WGSL matrices are column-major: `matCxR` has C columns of R rows each, stored as a flat
-    // array of C*R elements where column `c` occupies indices `[c*R, c*R + R)`.
-    //
-    // Naming convention: `m{cols}x{rows}_multiply_{...}`. Only the most common shapes are
-    // implemented. For unsupported shapes the compiler will emit a call to a missing helper —
-    // calling it raises `TypeError: wgsl.<name> is not a function`, which clearly identifies
-    // the shape needed; add a new entry below to support it.
-    // ---------------------------------------------------------------------
-
-    // mat × column-vector
-
-    m2x2f_multiply_v2f(m, v) {
-        const out = new Float32Array(2);
-        out[0] = m[0]*v[0] + m[2]*v[1];
-        out[1] = m[1]*v[0] + m[3]*v[1];
-        return out;
-    },
-
-    m3x3f_multiply_v3f(m, v) {
-        const out = new Float32Array(3);
-        out[0] = m[0]*v[0] + m[3]*v[1] + m[6]*v[2];
-        out[1] = m[1]*v[0] + m[4]*v[1] + m[7]*v[2];
-        out[2] = m[2]*v[0] + m[5]*v[1] + m[8]*v[2];
-        return out;
-    },
-
-    m4x4f_multiply_v4f(m, v) {
-        const out = new Float32Array(4);
-        out[0] = m[0]*v[0] + m[4]*v[1] + m[8] *v[2] + m[12]*v[3];
-        out[1] = m[1]*v[0] + m[5]*v[1] + m[9] *v[2] + m[13]*v[3];
-        out[2] = m[2]*v[0] + m[6]*v[1] + m[10]*v[2] + m[14]*v[3];
-        out[3] = m[3]*v[0] + m[7]*v[1] + m[11]*v[2] + m[15]*v[3];
-        return out;
-    },
-
-    // mat × mat (both square)
-
-    m2x2f_multiply_m2x2f(a, b) {
-        const out = new Float32Array(4);
-        for (let j = 0; j < 2; j++) {
-            const b0 = b[j*2], b1 = b[j*2 + 1];
-            out[j*2]     = a[0]*b0 + a[2]*b1;
-            out[j*2 + 1] = a[1]*b0 + a[3]*b1;
-        }
-        return out;
-    },
-
-    m3x3f_multiply_m3x3f(a, b) {
-        const out = new Float32Array(9);
-        for (let j = 0; j < 3; j++) {
-            const b0 = b[j*3], b1 = b[j*3 + 1], b2 = b[j*3 + 2];
-            out[j*3]     = a[0]*b0 + a[3]*b1 + a[6]*b2;
-            out[j*3 + 1] = a[1]*b0 + a[4]*b1 + a[7]*b2;
-            out[j*3 + 2] = a[2]*b0 + a[5]*b1 + a[8]*b2;
-        }
-        return out;
-    },
-
-    m4x4f_multiply_m4x4f(a, b) {
-        const out = new Float32Array(16);
-        for (let j = 0; j < 4; j++) {
-            const b0 = b[j*4], b1 = b[j*4 + 1], b2 = b[j*4 + 2], b3 = b[j*4 + 3];
-            out[j*4]     = a[0]*b0 + a[4]*b1 + a[8] *b2 + a[12]*b3;
-            out[j*4 + 1] = a[1]*b0 + a[5]*b1 + a[9] *b2 + a[13]*b3;
-            out[j*4 + 2] = a[2]*b0 + a[6]*b1 + a[10]*b2 + a[14]*b3;
-            out[j*4 + 3] = a[3]*b0 + a[7]*b1 + a[11]*b2 + a[15]*b3;
-        }
-        return out;
-    },
-
-    // row-vector × mat (square)
-
-    v2f_multiply_m2x2f(v, m) {
-        const out = new Float32Array(2);
-        out[0] = v[0]*m[0] + v[1]*m[1];
-        out[1] = v[0]*m[2] + v[1]*m[3];
-        return out;
-    },
-
-    v3f_multiply_m3x3f(v, m) {
-        const out = new Float32Array(3);
-        out[0] = v[0]*m[0] + v[1]*m[1] + v[2]*m[2];
-        out[1] = v[0]*m[3] + v[1]*m[4] + v[2]*m[5];
-        out[2] = v[0]*m[6] + v[1]*m[7] + v[2]*m[8];
-        return out;
-    },
-
-    v4f_multiply_m4x4f(v, m) {
-        const out = new Float32Array(4);
-        out[0] = v[0]*m[0]  + v[1]*m[1]  + v[2]*m[2]  + v[3]*m[3];
-        out[1] = v[0]*m[4]  + v[1]*m[5]  + v[2]*m[6]  + v[3]*m[7];
-        out[2] = v[0]*m[8]  + v[1]*m[9]  + v[2]*m[10] + v[3]*m[11];
-        out[3] = v[0]*m[12] + v[1]*m[13] + v[2]*m[14] + v[3]*m[15];
-        return out;
-    },
-
-    // ---------------------------------------------------------------------
-    // Logical / bit helpers
-    // ---------------------------------------------------------------------
-
-    select(a, b, cond) {
-        // WGSL: select(false_value, true_value, cond)
-        // - cond as scalar bool: returns `b` if truthy, `a` otherwise (whole-vector pick).
-        // - cond as a vec<bool>-like array: element-wise pick from `a`/`b`. Both must be
-        //   vectors of matching length.
-        if (cond != null && typeof cond === 'object' && typeof cond.length === 'number') {
-            const ctor = (a && typeof a.length === 'number') ? a.constructor
-                : (b && typeof b.length === 'number') ? b.constructor
-                : Array;
-            const out = new ctor(cond.length);
-            for (let i = 0; i < cond.length; i++) out[i] = cond[i] ? b[i] : a[i];
-            return out;
-        }
-        return cond ? b : a;
-    },
-
-    // Element-wise comparison helpers. Scalar in → boolean out; vector in → Array<boolean> of
-    // matching length (modelling WGSL's vec<bool>). Used by the compiler when at least one
-    // operand of `==` / `!=` / `<` / `>` / `<=` / `>=` is a vector.
-    eq: (a, b) => binop_cmp(a, b, (x, y) => x === y),
-    ne: (a, b) => binop_cmp(a, b, (x, y) => x !== y),
-    lt: (a, b) => binop_cmp(a, b, (x, y) => x < y),
-    gt: (a, b) => binop_cmp(a, b, (x, y) => x > y),
-    le: (a, b) => binop_cmp(a, b, (x, y) => x <= y),
-    ge: (a, b) => binop_cmp(a, b, (x, y) => x >= y),
-
-    all(v) {
-        if (!is_vec(v)) return !!v;
-        for (let i = 0; i < v.length; i++) if (!v[i]) return false;
-        return true;
-    },
-
-    any(v) {
-        if (!is_vec(v)) return !!v;
-        for (let i = 0; i < v.length; i++) if (v[i]) return true;
-        return false;
-    },
-
-    // ---------------------------------------------------------------------
-    // Texture intrinsics - backed by `CPUBitmapData` (1D / 2D / 3D inferred
-    // from the texture's `size`). Sampling routes through
-    // `cpu_texture_sample`, which honours the bound `SamplerDescriptor`'s
-    // address modes and filter. Mipmaps are not modelled (LOD 0 only) -
-    // see cpu_texture_sample header for details.
-    // ---------------------------------------------------------------------
-
-    /**
-     * `textureLoad(t, coords, level) -> vec4<T>`
-     *
-     * Integer-coord fetch. `coords` is i32-vector matching the texture's
-     * dimensionality (1, 2, or 3 entries). Out-of-bounds reads return zero
-     * across all channels (with alpha defaulting to 1.0 for textures with
-     * fewer than 4 channels - matches WGSL semantics).
-     *
-     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
-     * @param {Int32Array | Uint32Array | number[] | number} coords
-     * @param {number} [_level] - ignored, mipmaps are not modelled
-     * @returns {Float32Array}
-     */
-    textureLoad(t, coords, _level_or_index = 0, _array_level = undefined) {
-        assert.defined(t, 'texture');
-        const out = new Float32Array(4);
-        const dim = t.dimensionality;
-        // textureLoad on texture_1d takes a scalar i32 in WGSL (not vec1).
-        const x = (dim >= 1 ? (typeof coords === 'number' ? coords : coords[0]) : 0) | 0;
-        const y = (dim >= 2 ? coords[1] : 0) | 0;
-        /*
-         Four arguments is the texture_2d_array form — (t, coords, array_index, level) — where the
-         third argument is a slice rather than a mip level. A 2d-array is backed by a depth>1
-         CPUBitmapData, exactly like a 3D texture; only the call shape tells them apart.
-        */
-        const z = (_array_level !== undefined ? _level_or_index : (dim >= 3 ? coords[2] : 0)) | 0;
-        const item_size = t.item_size;
-        if (item_size < 4) out[3] = 1.0;
-        if (x < 0 || x >= t.size[0] || y < 0 || y >= t.size[1] || z < 0 || z >= t.size[2]) {
-            return out;
-        }
-        const base = t.pixel_offset(x, y, z);
-        const n = Math.min(item_size, 4);
-        for (let i = 0; i < n; i++) out[i] = t.data[base + i];
-        return out;
-    },
-
-    /**
-     * `textureSampleLevel(t, s, coords, level) -> vec4<T>`
-     *
-     * Filtered sample at normalised UV coords. Honours the sampler's
-     * address modes and `magFilter`. `coords` length matches the texture
-     * dimensionality. The `level` arg is ignored (no mipmaps).
-     *
-     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
-     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor | null} sampler
-     * @param {Float32Array | number[] | number} coords
-     * @param {number} [_level]
-     * @returns {Float32Array}
-     */
-    textureSampleLevel(t, sampler, coords, _level_or_index = 0, _array_level = undefined) {
-        assert.defined(t, 'texture');
-        const dim = t.dimensionality;
-        // Convert UV (normalised) to texel-space coords expected by
-        // cpu_texture_sample. coords for a 1D texture is a scalar in WGSL.
-        const u = dim >= 1 ? (typeof coords === 'number' ? coords : coords[0]) : 0;
-        const v = dim >= 2 ? coords[1] : 0;
-        const tx = u * t.size[0];
-        const ty = v * t.size[1];
-        /**
-         * @type {number[]}
-         */
-        let texel_coord;
-        if (_array_level !== undefined) {
-            /*
-             Five arguments is the texture_2d_array form — (t, s, uv, array_index, level) — where the
-             fourth argument selects a slice. A slice's texel-space centre sits at index + 0.5, which
-             lands the linear filter's z weight on exactly that slice: filtering happens in xy and
-             never crosses into a neighbour.
-            */
-            texel_coord = [tx, ty, (_level_or_index | 0) + 0.5];
-        } else {
-            const w = dim >= 3 ? coords[2] : 0;
-            const tz = w * t.size[2];
-            texel_coord = dim === 1 ? [tx] : (dim === 2 ? [tx, ty] : [tx, ty, tz]);
-        }
-        const result = new Float32Array(4);
-        cpu_texture_sample(result, sampler ?? FALLBACK_LINEAR_CLAMP_SAMPLER, t, texel_coord);
-        return result;
-    },
-
-    /**
-     * `textureSample(t, s, coords) -> vec4<T>` and the texture_2d_array form
-     * `textureSample(t, s, coords, array_index)`.
-     *
-     * Implicit-LOD sample. Without mipmaps, this is just
-     * `textureSampleLevel` at level 0.
-     *
-     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
-     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor | null} sampler
-     * @param {Float32Array | number[] | number} coords
-     * @param {number} [array_index]
-     * @returns {Float32Array}
-     */
-    textureSample(t, sampler, coords, array_index = undefined) {
-        if (array_index !== undefined) {
-            return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, array_index, 0);
-        }
-
-        return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, 0);
-    },
-
-    /**
-     * `textureSampleGrad(t, s, coords, ddx, ddy) -> vec4<T>` and the texture_2d_array form
-     * `textureSampleGrad(t, s, coords, array_index, ddx, ddy)`.
-     *
-     * Explicit-gradient sample. Mipmaps are not modelled (see the header), so the gradients only
-     * disambiguate which call shape this is: six arguments carry an array index, five do not.
-     *
-     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
-     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor | null} sampler
-     * @param {Float32Array | number[] | number} coords
-     * @param {Float32Array | number[] | number} p3 gradient, or the array index
-     * @param {Float32Array | number[]} p4 gradient
-     * @param {Float32Array | number[]} [p5] gradient, in the array form
-     * @returns {Float32Array}
-     */
-    textureSampleGrad(t, sampler, coords, p3, p4, p5 = undefined) {
-        if (p5 !== undefined) {
-            return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, p3, 0);
-        }
-
-        return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, 0);
-    },
-
-    /**
-     * `textureStore(t, coords, value) -> ()`
-     *
-     * Integer-coord write into a storage texture. Out-of-bounds writes are
-     * silently dropped (WGSL semantics). `coords` length matches the
-     * texture dimensionality.
-     *
-     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
-     * @param {Int32Array | Uint32Array | number[] | number} coords
-     * @param {Float32Array | Int32Array | Uint32Array | number[]} value
-     */
-    textureStore(t, coords, value) {
-        assert.defined(t, 'texture');
-        const dim = t.dimensionality;
-        const x = (dim >= 1 ? (typeof coords === 'number' ? coords : coords[0]) : 0) | 0;
-        const y = (dim >= 2 ? coords[1] : 0) | 0;
-        const z = (dim >= 3 ? coords[2] : 0) | 0;
-        t.write(x, y, z, value);
-    },
-
-    /**
-     * `textureDimensions(t, level) -> u32 | vec2<u32> | vec3<u32>`
-     *
-     * Returns the texture's size as a vector matching its dimensionality.
-     * 1D textures return a scalar `u32` in WGSL; we still hand back a
-     * length-1 Uint32Array so the calling shader can swizzle/index it
-     * uniformly with the multi-axis case.
-     *
-     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
-     * @param {number} [_level]
-     * @returns {Uint32Array}
-     */
-    textureDimensions(t, _level = 0) {
-        assert.defined(t, 'texture');
-        const dim = t.dimensionality;
-        if (dim === 1) return new Uint32Array([t.size[0]]);
-        if (dim === 2) return new Uint32Array([t.size[0], t.size[1]]);
-        return new Uint32Array([t.size[0], t.size[1], t.size[2]]);
-    },
-
-    // ---------------------------------------------------------------------
-    // Atomic ops on `atomic<T>` (modeled as { value: number } objects)
-    // ---------------------------------------------------------------------
-
-    atomicLoad(p) { return p.value; },
-    atomicStore(p, v) { p.value = v; },
-    atomicAdd(p, v) { const old = p.value; p.value = (p.value + v) | 0; return old; },
-    atomicSub(p, v) { const old = p.value; p.value = (p.value - v) | 0; return old; },
-    atomicMin(p, v) { const old = p.value; p.value = Math.min(p.value, v); return old; },
-    atomicMax(p, v) { const old = p.value; p.value = Math.max(p.value, v); return old; },
-    atomicAnd(p, v) { const old = p.value; p.value = p.value & v; return old; },
-    atomicOr(p, v) { const old = p.value; p.value = p.value | v; return old; },
-    atomicXor(p, v) { const old = p.value; p.value = p.value ^ v; return old; },
-    atomicExchange(p, v) { const old = p.value; p.value = v; return old; },
-    atomicCompareExchangeWeak(p, expected, v) {
-        const old = p.value;
-        if (old === expected) {
-            p.value = v;
-            return { old_value: old, exchanged: true };
-        }
-        return { old_value: old, exchanged: false };
-    },
-
-    // ---------------------------------------------------------------------
-    // Barriers — no-ops when running pointwise (one thread).
-    // ---------------------------------------------------------------------
-
-    workgroupBarrier() { /* no-op */ },
-    storageBarrier() { /* no-op */ },
-    textureBarrier() { /* no-op */ },
-
-    // A barrier plus a load of the pointed-at workgroup variable, which the compiler has already
-    // reduced to the variable itself — `&x` and `*x` both compile to `x`, since pointers are
-    // modelled as the values they name. The barrier half is the no-op above.
-    workgroupUniformLoad(value) { return value; },
-
-    // ---------------------------------------------------------------------
-    // Fragment-stage derivatives — unsupported because we run a single pixel.
-    // ---------------------------------------------------------------------
-    //
-    // dpdx/dpdy/fwidth and their fine/coarse variants are implicit-derivative builtins that the
-    // GPU computes from a 2x2 quad of neighbouring fragment threads. The emulator dispatches one
-    // pixel at a time, so there's no neighbouring data to take a finite difference against —
-    // any sensible value would be a fabrication. We throw to surface this clearly in tests.
-
-    dpdx() { throw new Error('dpdx is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    dpdy() { throw new Error('dpdy is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    fwidth() { throw new Error('fwidth is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    dpdxFine() { throw new Error('dpdxFine is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    dpdyFine() { throw new Error('dpdyFine is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    fwidthFine() { throw new Error('fwidthFine is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    dpdxCoarse() { throw new Error('dpdxCoarse is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    dpdyCoarse() { throw new Error('dpdyCoarse is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-    fwidthCoarse() { throw new Error('fwidthCoarse is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
-
-    // ---------------------------------------------------------------------
-    // Pack / unpack — fixed-point and float bit-level packers from the WGSL spec.
-    // ---------------------------------------------------------------------
-
-    /** vec2<f32>(low_u16, high_u16) / 65535.0 — components in [0, 1]. */
-    unpack2x16unorm(e) {
-        const u = e >>> 0;
-        return new Float32Array([(u & 0xFFFF) / 65535.0, ((u >>> 16) & 0xFFFF) / 65535.0]);
-    },
-
-    /** vec2<f32>(low_i16, high_i16) / 32767.0 — components in [-1, 1]. */
-    unpack2x16snorm(e) {
-        const u = e >>> 0;
-        const sign16 = (h) => (h & 0x8000) !== 0 ? h - 0x10000 : h;
-        const x = sign16(u & 0xFFFF) / 32767.0;
-        const y = sign16((u >>> 16) & 0xFFFF) / 32767.0;
-        return new Float32Array([Math.max(x, -1), Math.max(y, -1)]);
-    },
-
-    /** vec4<f32>(byte0, byte1, byte2, byte3) / 255.0 — components in [0, 1]. */
-    unpack4x8unorm(e) {
-        const u = e >>> 0;
-        return new Float32Array([
-            (u & 0xFF) / 255.0,
-            ((u >>> 8) & 0xFF) / 255.0,
-            ((u >>> 16) & 0xFF) / 255.0,
-            ((u >>> 24) & 0xFF) / 255.0,
-        ]);
-    },
-
-    /** vec4<f32>(i8 byte0..3) / 127.0 — components in [-1, 1]. */
-    unpack4x8snorm(e) {
-        const u = e >>> 0;
-        const sign8 = (b) => (b & 0x80) !== 0 ? b - 0x100 : b;
-        const out = new Float32Array(4);
-        for (let i = 0; i < 4; i++) {
-            out[i] = Math.max(sign8((u >>> (i * 8)) & 0xFF) / 127.0, -1);
-        }
-        return out;
-    },
-
-    /** Inverse of unpack2x16unorm — clamp to [0, 1] and round to 16-bit integer. */
-    pack2x16unorm(v) {
-        const x = Math.round(Math.min(Math.max(v[0], 0), 1) * 65535.0);
-        const y = Math.round(Math.min(Math.max(v[1], 0), 1) * 65535.0);
-        return ((y << 16) | x) >>> 0;
-    },
-
-    /** Inverse of unpack2x16snorm — clamp to [-1, 1] and round to 16-bit signed integer. */
-    pack2x16snorm(v) {
-        const enc = (f) => Math.round(Math.min(Math.max(f, -1), 1) * 32767.0) & 0xFFFF;
-        return ((enc(v[1]) << 16) | enc(v[0])) >>> 0;
-    },
-
-    /** Inverse of unpack4x8unorm — clamp to [0, 1] and round to 8-bit integer per channel. */
-    pack4x8unorm(v) {
-        let r = 0;
-        for (let i = 0; i < 4; i++) {
-            const b = Math.round(Math.min(Math.max(v[i], 0), 1) * 255.0) & 0xFF;
-            r |= b << (i * 8);
-        }
-        return r >>> 0;
-    },
-
-    /** Inverse of unpack4x8snorm — clamp to [-1, 1] and round to 8-bit signed integer per channel. */
-    pack4x8snorm(v) {
-        let r = 0;
-        for (let i = 0; i < 4; i++) {
-            const b = Math.round(Math.min(Math.max(v[i], -1), 1) * 127.0) & 0xFF;
-            r |= b << (i * 8);
-        }
-        return r >>> 0;
-    },
-};
-
-/**
- * Bit-cast (WGSL `bitcast`). Reinterprets a value's bit pattern as a different type.
- *
- * JS has no separate u32/i32/f32 scalar types — they're all `number` — so the source type
- * cannot be detected from the value at runtime. The compiler passes it explicitly when known;
- * otherwise we fall back to a heuristic: integer-targeted casts assume f32 source, float-targeted
- * casts assume u32 source (the common "interpret bit pattern as float" idiom).
- *
- * For typed-array (vector) inputs the source type is auto-detected from the array constructor.
- *
- * @param {*} v
- * @param {string} target — destination type name, e.g. `'f32'` / `'u32'` / `'i32'`
- * @param {string} [source] — source type name; required for unambiguous scalar casts
- * @returns {number | TypedArray}
- */
-WGSLLanguageCore.bitcast = function (v, target, source) {
-    // Vector targets (`vec3<u32>` etc.) reduce to their scalar type — the runtime stores vectors
-    // as flat typed arrays, so the per-element bitcast is the same as for a scalar of that type.
-    const vec_match = typeof target === 'string' ? target.match(/^vec\d<([^>]+)>$/) : null;
-    if (vec_match !== null) {
-        target = vec_match[1];
-    }
-
-    function convert_scalar(x, t_from, t_to) {
-        if (t_to === 'f32') {
-            if (t_from === 'u32') { BITCAST_U32[0] = x >>> 0; return BITCAST_F32[0]; }
-            if (t_from === 'i32') { BITCAST_I32[0] = x | 0; return BITCAST_F32[0]; }
-        } else if (t_to === 'u32') {
-            if (t_from === 'f32') { BITCAST_F32[0] = x; return BITCAST_U32[0]; }
-            if (t_from === 'i32') { return (x | 0) >>> 0; }
-        } else if (t_to === 'i32') {
-            if (t_from === 'f32') { BITCAST_F32[0] = x; return BITCAST_I32[0]; }
-            if (t_from === 'u32') { return (x >>> 0) | 0; }
-        }
-        return x;
-    }
-
-    if (is_vec(v)) {
-        let from = source;
-        if (from === undefined) {
-            if (v instanceof Float32Array) from = 'f32';
-            else if (v instanceof Float16Array) from = 'f16';
-            else if (v instanceof Uint32Array) from = 'u32';
-            else if (v instanceof Int32Array) from = 'i32';
-            else from = 'f32';
-        }
-
-        let outCtor;
-        if (target === 'f32') outCtor = Float32Array;
-        else if (target === 'f16') outCtor = Float16Array;
-        else if (target === 'u32') outCtor = Uint32Array;
-        else if (target === 'i32') outCtor = Int32Array;
-        else outCtor = v.constructor;
-
-        const out = new outCtor(v.length);
-        for (let i = 0; i < v.length; i++) {
-            out[i] = convert_scalar(v[i], from, target);
-        }
-        return out;
-    }
-
-    let from = source;
-    if (from === undefined) {
-        from = (target === 'f32' || target === 'f16') ? 'u32' : 'f32';
-    }
-    return convert_scalar(v, from, target);
-};
+import { assert } from "../../../core/assert.js";
+import { cpu_texture_gather, evaluate_gpu_compare_function } from "./cpu_texture_gather.js";
+import { cpu_texture_sample } from "./cpu_texture_sample.js";
+
+/**
+ * Default sampler descriptor for `textureSample` / `textureSampleLevel`
+ * calls when the bound sampler is `null` (common in tests). Linear filter,
+ * clamp-to-edge on every axis - matches what most engine passes use.
+ */
+const FALLBACK_LINEAR_CLAMP_SAMPLER = Object.freeze({
+    addressModeU: "clamp-to-edge",
+    addressModeV: "clamp-to-edge",
+    addressModeW: "clamp-to-edge",
+    magFilter: "linear",
+    minFilter: "linear",
+    mipmapFilter: "nearest",
+});
+
+/**
+ * Normalised UV -> texel space, for the gather intrinsics. {@link cpu_texture_gather} takes
+ * texel-space coordinates, the same convention {@link cpu_texture_sample} documents, so the
+ * shader-facing side does the conversion — `textureGather` has no 3D or 1D overload in WGSL,
+ * so only the two axes are ever needed.
+ *
+ * @param {Float32Array | number[]} coords — normalised uv
+ * @param {import("./CPUBitmapData.js").CPUBitmapData} texture
+ * @returns {number[]}
+ */
+function gather_texel_coord(coords, texture) {
+    return [coords[0] * texture.size[0], coords[1] * texture.size[1]];
+}
+
+/**
+ * Single-element scratch view used to round a number to IEEE 754 binary16 precision.
+ * @type {Float16Array}
+ */
+const F16_SCRATCH = new Float16Array(1);
+
+/**
+ * Shared scratch buffer for `bitcast` — three views over the same 4 bytes so we can
+ * reinterpret one type as another in O(1) without per-call allocation.
+ */
+const BITCAST_BUFFER = new ArrayBuffer(4);
+const BITCAST_U32 = new Uint32Array(BITCAST_BUFFER);
+const BITCAST_I32 = new Int32Array(BITCAST_BUFFER);
+const BITCAST_F32 = new Float32Array(BITCAST_BUFFER);
+
+/**
+ * Construct a WGSL vector. Mirrors WGSL `vecN<T>(...)` semantics:
+ *
+ * - **No args** → zero-filled.
+ * - **One scalar** → broadcast to all `size` components (`vec3(1.0)` → `[1, 1, 1]`).
+ * - **Exactly `size` scalars** → use as components.
+ * - **Any mix of scalars and shorter vectors** that flattens to exactly `size` numbers (e.g.
+ *   `vec3(vec2_xy, z)` or `vec4(x, vec2_yz, w)`).
+ *
+ * @param {Float32ArrayConstructor | Float16ArrayConstructor | Int32ArrayConstructor | Uint32ArrayConstructor} TypedArrayCtor
+ * @param {number} size
+ * @param {*[]} args
+ * @returns {*}
+ */
+function makeVec(TypedArrayCtor, size, args) {
+    if (args.length === 0) {
+        return new TypedArrayCtor(size);
+    }
+    // Single scalar → broadcast.
+    if (args.length === 1 && typeof args[0] === 'number') {
+        const v = args[0];
+        const out = new TypedArrayCtor(size);
+        for (let i = 0; i < size; i++) out[i] = v;
+        return out;
+    }
+    // Otherwise flatten.
+    const out = new TypedArrayCtor(size);
+    let i = 0;
+    for (const a of args) {
+        if (typeof a === 'number' || typeof a === 'boolean') {
+            out[i++] = +a;
+        } else if (a != null && typeof a.length === 'number') {
+            for (let j = 0; j < a.length; j++) out[i++] = a[j];
+        }
+    }
+    return out;
+}
+
+/**
+ * Build a matrix constructor returning a typed array of `total_elements` entries. The returned
+ * function accepts (a) no args → zero-filled, (b) `total_elements` scalars in column-major order,
+ * (c) one column-vec per matrix column, or (d) any mix that flattens to `total_elements` numbers.
+ *
+ * @param {Float32ArrayConstructor | Float16ArrayConstructor} TypedArrayCtor
+ * @param {number} total_elements
+ * @returns {function(...*): Float32Array | Float16Array}
+ */
+function makeMatCtor(TypedArrayCtor, total_elements) {
+    return (...args) => {
+        if (args.length === 0) {
+            return new TypedArrayCtor(total_elements);
+        }
+        const flat = new TypedArrayCtor(total_elements);
+        let i = 0;
+        for (const a of args) {
+            if (typeof a === 'number') {
+                flat[i++] = a;
+            } else if (a != null && typeof a.length === 'number') {
+                for (let j = 0; j < a.length; j++) flat[i++] = a[j];
+            }
+        }
+        return flat;
+    };
+}
+
+/**
+ * @param {number} a
+ * @returns {number}
+ */
+function as_i32(a) {
+    return (a | 0);
+}
+
+/**
+ * @param {number} a
+ * @returns {number}
+ */
+function as_u32(a) {
+    return (a >>> 0);
+}
+
+/**
+ * Determine if a value is a vector — TypedArray (vec2f / vec3i / etc) or
+ * a plain JS Array (returned from comparison ops like `eq` / `ge`, since
+ * those produce arrays of bools). Either way, a vec is a length-N
+ * iterable of element values, distinguished from a scalar number or a
+ * struct.
+ * @param {*} v
+ * @returns {boolean}
+ */
+function is_vec(v) {
+    if (v == null || typeof v !== 'object') return false;
+    if (typeof v.BYTES_PER_ELEMENT === 'number') return true;   // TypedArray (vecNf / vecNi / ...)
+    if (Array.isArray(v)) return true;                          // plain JS Array — vec result from binop_cmp
+    return false;
+}
+
+/**
+ * Element-wise apply a binary op over a vector and scalar/vector counterpart.
+ * @param {*} a
+ * @param {*} b
+ * @param {function(number, number): number} op
+ * @returns {*}
+ */
+function binop(a, b, op) {
+    const a_vec = is_vec(a);
+    const b_vec = is_vec(b);
+
+    if (!a_vec && !b_vec) {
+        return op(a, b);
+    }
+
+    if (a_vec && b_vec) {
+        assert.equal(a.length, b.length, 'vector length mismatch');
+        const out = new a.constructor(a.length);
+        for (let i = 0; i < a.length; i++) {
+            out[i] = op(a[i], b[i]);
+        }
+        return out;
+    }
+
+    if (a_vec) {
+        const out = new a.constructor(a.length);
+        for (let i = 0; i < a.length; i++) {
+            out[i] = op(a[i], b);
+        }
+        return out;
+    }
+
+    // b_vec
+    const out = new b.constructor(b.length);
+    for (let i = 0; i < b.length; i++) {
+        out[i] = op(a, b[i]);
+    }
+    return out;
+}
+
+/**
+ * Element-wise apply a comparison op. For scalar operands returns a single boolean; for
+ * vector operands returns a plain `Array<boolean>` matching the WGSL `vec<bool>` shape.
+ * @param {*} a
+ * @param {*} b
+ * @param {function(number, number): boolean} op
+ * @returns {boolean | boolean[]}
+ */
+function binop_cmp(a, b, op) {
+    const a_vec = is_vec(a);
+    const b_vec = is_vec(b);
+
+    if (!a_vec && !b_vec) {
+        return op(a, b);
+    }
+    const length = a_vec ? a.length : b.length;
+    const out = new Array(length);
+    for (let i = 0; i < length; i++) {
+        const ai = a_vec ? a[i] : a;
+        const bi = b_vec ? b[i] : b;
+        out[i] = op(ai, bi);
+    }
+    return out;
+}
+
+/**
+ * Element-wise apply a unary op over a scalar/vector.
+ * @param {*} a
+ * @param {function(number): number} op
+ * @returns {*}
+ */
+function unop(a, op) {
+    if (!is_vec(a)) {
+        return op(a);
+    }
+    const out = new a.constructor(a.length);
+    for (let i = 0; i < a.length; i++) {
+        out[i] = op(a[i]);
+    }
+    return out;
+}
+
+/**
+ * Element-wise apply a ternary op (e.g. mix, clamp).
+ * @param {*} a
+ * @param {*} b
+ * @param {*} c
+ * @param {function(number, number, number): number} op
+ * @returns {*}
+ */
+function ternop(a, b, c, op) {
+    if (is_vec(a) || is_vec(b) || is_vec(c)) {
+        const length = (is_vec(a) ? a.length : (is_vec(b) ? b.length : c.length));
+        const ctor = (is_vec(a) ? a.constructor : (is_vec(b) ? b.constructor : c.constructor));
+        const out = new ctor(length);
+        for (let i = 0; i < length; i++) {
+            const ai = is_vec(a) ? a[i] : a;
+            const bi = is_vec(b) ? b[i] : b;
+            const ci = is_vec(c) ? c[i] : c;
+            out[i] = op(ai, bi, ci);
+        }
+        return out;
+    }
+    return op(a, b, c);
+}
+
+/**
+ * The default WGSL language core — the `wgsl` object passed into the generated JS.
+ *
+ * Provides:
+ * - vector / matrix constructors (`vec3f`, `vec2u`, etc.)
+ * - scalar constructors / casts (`f32`, `i32`, `u32`, `bool`)
+ * - arithmetic helpers (`add`, `sub`, `mul`, `div`, `mod`, `neg`)
+ * - WGSL builtins (`mix`, `clamp`, `min`, `max`, `abs`, `floor`, `ceil`, `pow`, ...)
+ * - texture intrinsics (`textureLoad`, `textureSampleLevel`)
+ * - control flow helpers (`workgroupBarrier`, `storageBarrier`)
+ *
+ * @type {object}
+ */
+export const WGSLLanguageCore = {
+    // ---------------------------------------------------------------------
+    // Scalar casts
+    // ---------------------------------------------------------------------
+
+    /** Cast to i32. */
+    i32(v) {
+        if (typeof v === 'boolean') return v ? 1 : 0;
+        return as_i32(v);
+    },
+
+    /** Cast to u32. */
+    u32(v) {
+        if (typeof v === 'boolean') return v ? 1 : 0;
+        return as_u32(v);
+    },
+
+    /** Cast to f32 (no-op in JS, returns the number). */
+    f32(v) {
+        if (typeof v === 'boolean') return v ? 1 : 0;
+        return Math.fround(+v);
+    },
+
+    /** Cast to f16. Truncates to IEEE 754 binary16 precision via Float16Array. */
+    f16(v) {
+        if (typeof v === 'boolean') return v ? 1 : 0;
+        F16_SCRATCH[0] = +v;
+        return F16_SCRATCH[0];
+    },
+
+    /** Cast to bool. */
+    bool(v) {
+        return !!v;
+    },
+
+    // ---------------------------------------------------------------------
+    // Vector constructors
+    // ---------------------------------------------------------------------
+
+    vec2f: (...args) => makeVec(Float32Array, 2, args),
+    vec3f: (...args) => makeVec(Float32Array, 3, args),
+    vec4f: (...args) => makeVec(Float32Array, 4, args),
+
+    vec2h: (...args) => makeVec(Float16Array, 2, args),
+    vec3h: (...args) => makeVec(Float16Array, 3, args),
+    vec4h: (...args) => makeVec(Float16Array, 4, args),
+
+    vec2i: (...args) => makeVec(Int32Array, 2, args),
+    vec3i: (...args) => makeVec(Int32Array, 3, args),
+    vec4i: (...args) => makeVec(Int32Array, 4, args),
+
+    vec2u: (...args) => makeVec(Uint32Array, 2, args),
+    vec3u: (...args) => makeVec(Uint32Array, 3, args),
+    vec4u: (...args) => makeVec(Uint32Array, 4, args),
+
+    // ---------------------------------------------------------------------
+    // Matrix constructors — column-major flat arrays. matCxR has C columns of R rows each,
+    // for a total of C*R entries. Args may be scalars, column vectors, or a mix.
+    // ---------------------------------------------------------------------
+
+    mat2x2f: makeMatCtor(Float32Array, 4),
+    mat2x3f: makeMatCtor(Float32Array, 6),
+    mat2x4f: makeMatCtor(Float32Array, 8),
+    mat3x2f: makeMatCtor(Float32Array, 6),
+    mat3x3f: makeMatCtor(Float32Array, 9),
+    mat3x4f: makeMatCtor(Float32Array, 12),
+    mat4x2f: makeMatCtor(Float32Array, 8),
+    mat4x3f: makeMatCtor(Float32Array, 12),
+    mat4x4f: makeMatCtor(Float32Array, 16),
+
+    mat2x2h: makeMatCtor(Float16Array, 4),
+    mat2x3h: makeMatCtor(Float16Array, 6),
+    mat2x4h: makeMatCtor(Float16Array, 8),
+    mat3x2h: makeMatCtor(Float16Array, 6),
+    mat3x3h: makeMatCtor(Float16Array, 9),
+    mat3x4h: makeMatCtor(Float16Array, 12),
+    mat4x2h: makeMatCtor(Float16Array, 8),
+    mat4x3h: makeMatCtor(Float16Array, 12),
+    mat4x4h: makeMatCtor(Float16Array, 16),
+
+    /**
+     * Return column `i` of a column-major matrix as a vec view (no copy). Used by the compiler
+     * to translate WGSL `m[i]` — which yields a vec — onto our flat-typed-array storage.
+     * @param {Float32Array|Float16Array} m
+     * @param {number} i
+     * @param {number} rows
+     */
+    mat_col(m, i, rows) {
+        return m.subarray(i * rows, (i + 1) * rows);
+    },
+
+    /**
+     * Store a whole value through a pointer: WGSL's `*p = value`. Returns what the pointer variable
+     * should now hold, which the caller assigns back.
+     *
+     * Pointers are modelled as the pointee itself, so `*p = value` used to compile to a plain
+     * assignment to the parameter binding — which rebinds the callee's local and leaves the
+     * caller's object untouched. Every shader returning a result through an out-parameter then read
+     * back whatever it had initialised the variable to, silently and with nothing raised:
+     * `ray_triangle_compute_intersection_barycentric` reported hits at a distance of zero, which is
+     * a hit the traversal keeps and shades.
+     *
+     * Vectors, matrices and structs are objects, so the store goes through the reference and the
+     * caller sees it. **A pointer to a scalar still cannot**: a JavaScript number has no identity
+     * to write through, so the rebind is all there is, and a caller passing `&some_f32` sees its
+     * variable unchanged. Within the callee the value is right — `*p` reads back what `*p = …`
+     * wrote — so the in-out scalar accumulators in `sample_discrete_wrs_*` behave, and only a
+     * result handed *out* through a scalar pointer is lost. Widen such an out-parameter to a
+     * vector or a struct, or return it, if a test needs to see it.
+     *
+     * @param {Float32Array|Float16Array|Uint32Array|Int32Array|Array|object|number|boolean} target
+     * @param {ArrayLike<number>|object|number|boolean} value
+     * @returns {*} the value the pointer variable should be rebound to
+     */
+    store_ptr(target, value) {
+        if (ArrayBuffer.isView(target) || Array.isArray(target)) {
+            for (let i = 0; i < target.length; i++) {
+                target[i] = value[i];
+            }
+
+            return target;
+        }
+
+        if (target !== null && typeof target === 'object') {
+            Object.assign(target, value);
+
+            return target;
+        }
+
+        return value;
+    },
+
+    /**
+     * Determinant of a square matrix stored as a flat column-major typed array.
+     * Supports the WGSL square-matrix sizes: 2x2, 3x3, 4x4.
+     * @param {Float32Array|Float16Array} m
+     */
+    determinant(m) {
+        if (m.length === 4) {
+            return m[0] * m[3] - m[1] * m[2];
+        }
+        if (m.length === 9) {
+            return m[0] * (m[4] * m[8] - m[5] * m[7])
+                - m[3] * (m[1] * m[8] - m[2] * m[7])
+                + m[6] * (m[1] * m[5] - m[2] * m[4]);
+        }
+        if (m.length === 16) {
+            // 4x4 expansion via 2x2 minors of the bottom rows.
+            const s0 = m[0] * m[5] - m[1] * m[4];
+            const s1 = m[0] * m[6] - m[2] * m[4];
+            const s2 = m[0] * m[7] - m[3] * m[4];
+            const s3 = m[1] * m[6] - m[2] * m[5];
+            const s4 = m[1] * m[7] - m[3] * m[5];
+            const s5 = m[2] * m[7] - m[3] * m[6];
+            const c5 = m[10] * m[15] - m[11] * m[14];
+            const c4 = m[ 9] * m[15] - m[11] * m[13];
+            const c3 = m[ 9] * m[14] - m[10] * m[13];
+            const c2 = m[ 8] * m[15] - m[11] * m[12];
+            const c1 = m[ 8] * m[14] - m[10] * m[12];
+            const c0 = m[ 8] * m[13] - m[ 9] * m[12];
+            return s0 * c5 - s1 * c4 + s2 * c3 + s3 * c2 - s4 * c1 + s5 * c0;
+        }
+        throw new Error(`determinant: unsupported matrix length ${m.length}`);
+    },
+
+    // ---------------------------------------------------------------------
+    // Arithmetic helpers (work on scalars and vectors element-wise)
+    // ---------------------------------------------------------------------
+
+    add: (a, b) => binop(a, b, (x, y) => x + y),
+    sub: (a, b) => binop(a, b, (x, y) => x - y),
+    mul: (a, b) => binop(a, b, (x, y) => x * y),
+    div: (a, b) => binop(a, b, (x, y) => x / y),
+    rem: (a, b) => binop(a, b, (x, y) => x % y),
+
+    // Integer division — truncates toward zero, matching WGSL `/` semantics on integer types.
+    // The compiler routes `/` through `idiv` when both operands' tracked types are integer.
+    idiv: (a, b) => binop(a, b, (x, y) => Math.trunc(x / y)),
+
+    // Element-wise bitwise / shift helpers. JS's raw `&` / `|` / `^` / `<<` / `>>` work on
+    // scalars but not typed arrays (they coerce the array to a number → NaN), so the compiler
+    // routes vec/mat operands through these. Right-shift uses `>>>` (unsigned) to match WGSL
+    // u32 semantics; signed sources should bitcast first.
+    bit_and: (a, b) => binop(a, b, (x, y) => (x & y) >>> 0),
+    bit_or:  (a, b) => binop(a, b, (x, y) => (x | y) >>> 0),
+    bit_xor: (a, b) => binop(a, b, (x, y) => (x ^ y) >>> 0),
+    shl:     (a, b) => binop(a, b, (x, y) => (x << y) >>> 0),
+    shr:     (a, b) => binop(a, b, (x, y) => x >>> y),
+
+    neg: (a) => unop(a, x => -x),
+    not: (a) => unop(a, x => (~x) >>> 0),
+
+    // Bit-field extract / insert (WGSL §17.9). Component-wise over vectors; `offset` and
+    // `count` are scalar u32 even when `e` / `newbits` are vectors, matching the WGSL
+    // signatures. Like `shr`, these implement the UNSIGNED reading — extracted bits are
+    // zero-extended, not sign-extended — so an i32 source needing sign extension should
+    // bitcast first. Per the spec, `o = min(offset, 32)` and `c = min(count, 32 - o)`.
+
+    /** `extractBits(e, offset, count)` — read `count` bits at `offset`, zero-extended. */
+    extractBits(e, offset, count) {
+        const o = Math.min(offset >>> 0, 32);
+        const c = Math.min(count >>> 0, 32 - o);
+        return unop(e, (x) => {
+            if (c === 0) {
+                return 0;
+            }
+            const mask = c >= 32 ? 0xFFFFFFFF : ((1 << c) - 1);
+            return ((x >>> o) & mask) >>> 0;
+        });
+    },
+
+    // Bit counting (WGSL §17.9). Component-wise over vectors. All of these read their operand as
+    // 32 bits regardless of whether the WGSL type was u32 or i32 — which is what the spec says and
+    // what makes `countLeadingZeros` the exact counterpart of JS's `Math.clz32`.
+
+    /** `countLeadingZeros(e)` — number of consecutive zero bits above the most significant set bit; 32 for 0. */
+    countLeadingZeros: (e) => unop(e, x => Math.clz32(x)),
+
+    /** `countTrailingZeros(e)` — number of consecutive zero bits below the least significant set bit; 32 for 0. */
+    countTrailingZeros: (e) => unop(e, x => (x === 0 ? 32 : 31 - Math.clz32(x & -x))),
+
+    /** `countOneBits(e)` — population count. */
+    countOneBits: (e) => unop(e, x => {
+        let bits = x >>> 0;
+        let count = 0;
+
+        while (bits !== 0) {
+            bits &= bits - 1;
+            count += 1;
+        }
+
+        return count;
+    }),
+
+    /** `firstLeadingBit(e)` — index of the most significant set bit; `0xffffffff` for 0 (u32 reading). */
+    firstLeadingBit: (e) => unop(e, x => (x === 0 ? 0xffffffff : 31 - Math.clz32(x))),
+
+    /** `firstTrailingBit(e)` — index of the least significant set bit; `0xffffffff` for 0. */
+    firstTrailingBit: (e) => unop(e, x => (x === 0 ? 0xffffffff : 31 - Math.clz32(x & -x))),
+
+    /** `reverseBits(e)` — reverse the order of all 32 bits. */
+    reverseBits: (e) => unop(e, x => {
+        let source = x >>> 0;
+        let reversed = 0;
+
+        for (let i = 0; i < 32; i++) {
+            reversed = ((reversed << 1) | (source & 1)) >>> 0;
+            source >>>= 1;
+        }
+
+        return reversed;
+    }),
+
+    /** `insertBits(e, newbits, offset, count)` — replace bits `[offset, offset+count)` of `e` with the low `count` bits of `newbits`. */
+    insertBits(e, newbits, offset, count) {
+        const o = Math.min(offset >>> 0, 32);
+        const c = Math.min(count >>> 0, 32 - o);
+        return binop(e, newbits, (x, ins) => {
+            if (c === 0) {
+                return x >>> 0;
+            }
+            const base_mask = c >= 32 ? 0xFFFFFFFF : ((1 << c) - 1);
+            const field_mask = o >= 32 ? 0 : ((base_mask << o) >>> 0);
+            return (((ins << o) & field_mask) | (x & ((~field_mask) >>> 0))) >>> 0;
+        });
+    },
+
+    // ---------------------------------------------------------------------
+    // WGSL math builtins
+    // ---------------------------------------------------------------------
+
+    abs: (a) => unop(a, Math.abs),
+    sign: (a) => unop(a, Math.sign),
+    floor: (a) => unop(a, Math.floor),
+    ceil: (a) => unop(a, Math.ceil),
+    round: (a) => unop(a, Math.round),
+    trunc: (a) => unop(a, Math.trunc),
+    fract: (a) => unop(a, x => x - Math.floor(x)),
+    sqrt: (a) => unop(a, Math.sqrt),
+    inverseSqrt: (a) => unop(a, x => 1 / Math.sqrt(x)),
+    exp: (a) => unop(a, Math.exp),
+    exp2: (a) => unop(a, x => Math.pow(2, x)),
+    log: (a) => unop(a, Math.log),
+    log2: (a) => unop(a, Math.log2),
+    sin: (a) => unop(a, Math.sin),
+    cos: (a) => unop(a, Math.cos),
+    tan: (a) => unop(a, Math.tan),
+    asin: (a) => unop(a, Math.asin),
+    acos: (a) => unop(a, Math.acos),
+    atan: (a) => unop(a, Math.atan),
+
+    pow: (a, b) => binop(a, b, Math.pow),
+    atan2: (a, b) => binop(a, b, Math.atan2),
+    min: (a, b) => binop(a, b, Math.min),
+    max: (a, b) => binop(a, b, Math.max),
+    step: (edge, x) => binop(edge, x, (e, v) => v < e ? 0 : 1),
+
+    clamp: (x, lo, hi) => ternop(x, lo, hi, (v, l, h) => Math.max(l, Math.min(h, v))),
+    // Saturate is `clamp(x, 0, 1)`. WGSL builtin.
+    saturate: (a) => unop(a, x => Math.max(0, Math.min(1, x))),
+    mix: (a, b, t) => ternop(a, b, t, (x, y, k) => x * (1 - k) + y * k),
+    // Fused multiply-add: `a * b + c`. JS lacks a true FMA; this is mathematically equivalent
+    // but loses the single-rounding precision benefit of hardware FMA — fine for testing.
+    fma: (a, b, c) => ternop(a, b, c, (x, y, z) => x * y + z),
+    smoothstep: (edge0, edge1, x) => ternop(edge0, edge1, x, (e0, e1, v) => {
+        const t = Math.max(0, Math.min(1, (v - e0) / (e1 - e0)));
+        return t * t * (3 - 2 * t);
+    }),
+
+    // ---------------------------------------------------------------------
+    // Vector operations
+    // ---------------------------------------------------------------------
+
+    dot(a, b) {
+        assert.equal(a.length, b.length, 'dot vector length mismatch');
+        let s = 0;
+        for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+        return s;
+    },
+
+    length(v) {
+        if (!is_vec(v)) return Math.abs(v);
+        let s = 0;
+        for (let i = 0; i < v.length; i++) s += v[i] * v[i];
+        return Math.sqrt(s);
+    },
+
+    distance(a, b) {
+        return WGSLLanguageCore.length(WGSLLanguageCore.sub(a, b));
+    },
+
+    normalize(v) {
+        const len = WGSLLanguageCore.length(v);
+        if (len === 0) {
+            return new v.constructor(v.length);
+        }
+        const out = new v.constructor(v.length);
+        for (let i = 0; i < v.length; i++) out[i] = v[i] / len;
+        return out;
+    },
+
+    cross(a, b) {
+        assert.equal(a.length, 3, 'cross requires vec3');
+        assert.equal(b.length, 3, 'cross requires vec3');
+        return new a.constructor([
+            a[1] * b[2] - a[2] * b[1],
+            a[2] * b[0] - a[0] * b[2],
+            a[0] * b[1] - a[1] * b[0],
+        ]);
+    },
+
+    reflect(i, n) {
+        const d = WGSLLanguageCore.dot(i, n);
+        const out = new i.constructor(i.length);
+        for (let k = 0; k < i.length; k++) out[k] = i[k] - 2 * d * n[k];
+        return out;
+    },
+
+    // ---------------------------------------------------------------------
+    // Matrix × {matrix, vector} and vector × matrix products.
+    //
+    // WGSL matrices are column-major: `matCxR` has C columns of R rows each, stored as a flat
+    // array of C*R elements where column `c` occupies indices `[c*R, c*R + R)`.
+    //
+    // Naming convention: `m{cols}x{rows}_multiply_{...}`. Only the most common shapes are
+    // implemented. For unsupported shapes the compiler will emit a call to a missing helper —
+    // calling it raises `TypeError: wgsl.<name> is not a function`, which clearly identifies
+    // the shape needed; add a new entry below to support it.
+    // ---------------------------------------------------------------------
+
+    // mat × column-vector
+
+    m2x2f_multiply_v2f(m, v) {
+        const out = new Float32Array(2);
+        out[0] = m[0]*v[0] + m[2]*v[1];
+        out[1] = m[1]*v[0] + m[3]*v[1];
+        return out;
+    },
+
+    m3x3f_multiply_v3f(m, v) {
+        const out = new Float32Array(3);
+        out[0] = m[0]*v[0] + m[3]*v[1] + m[6]*v[2];
+        out[1] = m[1]*v[0] + m[4]*v[1] + m[7]*v[2];
+        out[2] = m[2]*v[0] + m[5]*v[1] + m[8]*v[2];
+        return out;
+    },
+
+    m4x4f_multiply_v4f(m, v) {
+        const out = new Float32Array(4);
+        out[0] = m[0]*v[0] + m[4]*v[1] + m[8] *v[2] + m[12]*v[3];
+        out[1] = m[1]*v[0] + m[5]*v[1] + m[9] *v[2] + m[13]*v[3];
+        out[2] = m[2]*v[0] + m[6]*v[1] + m[10]*v[2] + m[14]*v[3];
+        out[3] = m[3]*v[0] + m[7]*v[1] + m[11]*v[2] + m[15]*v[3];
+        return out;
+    },
+
+    // mat × mat (both square)
+
+    m2x2f_multiply_m2x2f(a, b) {
+        const out = new Float32Array(4);
+        for (let j = 0; j < 2; j++) {
+            const b0 = b[j*2], b1 = b[j*2 + 1];
+            out[j*2]     = a[0]*b0 + a[2]*b1;
+            out[j*2 + 1] = a[1]*b0 + a[3]*b1;
+        }
+        return out;
+    },
+
+    m3x3f_multiply_m3x3f(a, b) {
+        const out = new Float32Array(9);
+        for (let j = 0; j < 3; j++) {
+            const b0 = b[j*3], b1 = b[j*3 + 1], b2 = b[j*3 + 2];
+            out[j*3]     = a[0]*b0 + a[3]*b1 + a[6]*b2;
+            out[j*3 + 1] = a[1]*b0 + a[4]*b1 + a[7]*b2;
+            out[j*3 + 2] = a[2]*b0 + a[5]*b1 + a[8]*b2;
+        }
+        return out;
+    },
+
+    m4x4f_multiply_m4x4f(a, b) {
+        const out = new Float32Array(16);
+        for (let j = 0; j < 4; j++) {
+            const b0 = b[j*4], b1 = b[j*4 + 1], b2 = b[j*4 + 2], b3 = b[j*4 + 3];
+            out[j*4]     = a[0]*b0 + a[4]*b1 + a[8] *b2 + a[12]*b3;
+            out[j*4 + 1] = a[1]*b0 + a[5]*b1 + a[9] *b2 + a[13]*b3;
+            out[j*4 + 2] = a[2]*b0 + a[6]*b1 + a[10]*b2 + a[14]*b3;
+            out[j*4 + 3] = a[3]*b0 + a[7]*b1 + a[11]*b2 + a[15]*b3;
+        }
+        return out;
+    },
+
+    // row-vector × mat (square)
+
+    v2f_multiply_m2x2f(v, m) {
+        const out = new Float32Array(2);
+        out[0] = v[0]*m[0] + v[1]*m[1];
+        out[1] = v[0]*m[2] + v[1]*m[3];
+        return out;
+    },
+
+    v3f_multiply_m3x3f(v, m) {
+        const out = new Float32Array(3);
+        out[0] = v[0]*m[0] + v[1]*m[1] + v[2]*m[2];
+        out[1] = v[0]*m[3] + v[1]*m[4] + v[2]*m[5];
+        out[2] = v[0]*m[6] + v[1]*m[7] + v[2]*m[8];
+        return out;
+    },
+
+    v4f_multiply_m4x4f(v, m) {
+        const out = new Float32Array(4);
+        out[0] = v[0]*m[0]  + v[1]*m[1]  + v[2]*m[2]  + v[3]*m[3];
+        out[1] = v[0]*m[4]  + v[1]*m[5]  + v[2]*m[6]  + v[3]*m[7];
+        out[2] = v[0]*m[8]  + v[1]*m[9]  + v[2]*m[10] + v[3]*m[11];
+        out[3] = v[0]*m[12] + v[1]*m[13] + v[2]*m[14] + v[3]*m[15];
+        return out;
+    },
+
+    // ---------------------------------------------------------------------
+    // Logical / bit helpers
+    // ---------------------------------------------------------------------
+
+    select(a, b, cond) {
+        // WGSL: select(false_value, true_value, cond)
+        // - cond as scalar bool: returns `b` if truthy, `a` otherwise (whole-vector pick).
+        // - cond as a vec<bool>-like array: element-wise pick from `a`/`b`. Both must be
+        //   vectors of matching length.
+        if (cond != null && typeof cond === 'object' && typeof cond.length === 'number') {
+            const ctor = (a && typeof a.length === 'number') ? a.constructor
+                : (b && typeof b.length === 'number') ? b.constructor
+                : Array;
+            const out = new ctor(cond.length);
+            for (let i = 0; i < cond.length; i++) out[i] = cond[i] ? b[i] : a[i];
+            return out;
+        }
+        return cond ? b : a;
+    },
+
+    // Element-wise comparison helpers. Scalar in → boolean out; vector in → Array<boolean> of
+    // matching length (modelling WGSL's vec<bool>). Used by the compiler when at least one
+    // operand of `==` / `!=` / `<` / `>` / `<=` / `>=` is a vector.
+    eq: (a, b) => binop_cmp(a, b, (x, y) => x === y),
+    ne: (a, b) => binop_cmp(a, b, (x, y) => x !== y),
+    lt: (a, b) => binop_cmp(a, b, (x, y) => x < y),
+    gt: (a, b) => binop_cmp(a, b, (x, y) => x > y),
+    le: (a, b) => binop_cmp(a, b, (x, y) => x <= y),
+    ge: (a, b) => binop_cmp(a, b, (x, y) => x >= y),
+
+    all(v) {
+        if (!is_vec(v)) return !!v;
+        for (let i = 0; i < v.length; i++) if (!v[i]) return false;
+        return true;
+    },
+
+    any(v) {
+        if (!is_vec(v)) return !!v;
+        for (let i = 0; i < v.length; i++) if (v[i]) return true;
+        return false;
+    },
+
+    // ---------------------------------------------------------------------
+    // Texture intrinsics - backed by `CPUBitmapData` (1D / 2D / 3D inferred
+    // from the texture's `size`). Sampling routes through
+    // `cpu_texture_sample`, which honours the bound `SamplerDescriptor`'s
+    // address modes and filter. Mipmaps are not modelled (LOD 0 only) -
+    // see cpu_texture_sample header for details.
+    // ---------------------------------------------------------------------
+
+    /**
+     * `textureLoad(t, coords, level) -> vec4<T>`
+     *
+     * Integer-coord fetch. `coords` is i32-vector matching the texture's
+     * dimensionality (1, 2, or 3 entries). Out-of-bounds reads return zero
+     * across all channels (with alpha defaulting to 1.0 for textures with
+     * fewer than 4 channels - matches WGSL semantics).
+     *
+     * A texture flagged `is_depth` returns a bare `f32` instead, matching WGSL: `textureLoad` on a
+     * `texture_depth_*` is declared to yield a scalar, and shader code written against one uses it
+     * as such. Handing that code a vec4 would turn every use into a component-wise broadcast that
+     * neither throws nor matches the device.
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {Int32Array | Uint32Array | number[] | number} coords
+     * @param {number} [_level] - ignored, mipmaps are not modelled
+     * @returns {Float32Array | number}
+     */
+    textureLoad(t, coords, _level_or_index = 0, _array_level = undefined) {
+        assert.defined(t, 'texture');
+        const out = new Float32Array(4);
+        const dim = t.dimensionality;
+        // textureLoad on texture_1d takes a scalar i32 in WGSL (not vec1).
+        const x = (dim >= 1 ? (typeof coords === 'number' ? coords : coords[0]) : 0) | 0;
+        const y = (dim >= 2 ? coords[1] : 0) | 0;
+        /*
+         Four arguments is the texture_2d_array form — (t, coords, array_index, level) — where the
+         third argument is a slice rather than a mip level. A 2d-array is backed by a depth>1
+         CPUBitmapData, exactly like a 3D texture; only the call shape tells them apart.
+        */
+        const z = (_array_level !== undefined ? _level_or_index : (dim >= 3 ? coords[2] : 0)) | 0;
+        const item_size = t.item_size;
+        const out_of_bounds = x < 0 || x >= t.size[0] || y < 0 || y >= t.size[1] || z < 0 || z >= t.size[2];
+
+        if (t.is_depth === true) {
+            return out_of_bounds ? 0.0 : t.data[t.pixel_offset(x, y, z)];
+        }
+
+        if (item_size < 4) out[3] = 1.0;
+        if (out_of_bounds) {
+            return out;
+        }
+        const base = t.pixel_offset(x, y, z);
+        const n = Math.min(item_size, 4);
+        for (let i = 0; i < n; i++) out[i] = t.data[base + i];
+        return out;
+    },
+
+    /**
+     * `textureSampleLevel(t, s, coords, level) -> vec4<T>`
+     *
+     * Filtered sample at normalised UV coords. Honours the sampler's
+     * address modes and `magFilter`. `coords` length matches the texture
+     * dimensionality. The `level` arg is ignored (no mipmaps).
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor | null} sampler
+     * @param {Float32Array | number[] | number} coords
+     * @param {number} [_level]
+     * @returns {Float32Array}
+     */
+    textureSampleLevel(t, sampler, coords, _level_or_index = 0, _array_level = undefined) {
+        assert.defined(t, 'texture');
+        const dim = t.dimensionality;
+        // Convert UV (normalised) to texel-space coords expected by
+        // cpu_texture_sample. coords for a 1D texture is a scalar in WGSL.
+        const u = dim >= 1 ? (typeof coords === 'number' ? coords : coords[0]) : 0;
+        const v = dim >= 2 ? coords[1] : 0;
+        const tx = u * t.size[0];
+        const ty = v * t.size[1];
+        /**
+         * @type {number[]}
+         */
+        let texel_coord;
+        if (_array_level !== undefined) {
+            /*
+             Five arguments is the texture_2d_array form — (t, s, uv, array_index, level) — where the
+             fourth argument selects a slice. A slice's texel-space centre sits at index + 0.5, which
+             lands the linear filter's z weight on exactly that slice: filtering happens in xy and
+             never crosses into a neighbour.
+            */
+            texel_coord = [tx, ty, (_level_or_index | 0) + 0.5];
+        } else {
+            const w = dim >= 3 ? coords[2] : 0;
+            const tz = w * t.size[2];
+            texel_coord = dim === 1 ? [tx] : (dim === 2 ? [tx, ty] : [tx, ty, tz]);
+        }
+        const result = new Float32Array(4);
+        cpu_texture_sample(result, sampler ?? FALLBACK_LINEAR_CLAMP_SAMPLER, t, texel_coord);
+        return result;
+    },
+
+    /**
+     * `textureSample(t, s, coords) -> vec4<T>` and the texture_2d_array form
+     * `textureSample(t, s, coords, array_index)`.
+     *
+     * Implicit-LOD sample. Without mipmaps, this is just
+     * `textureSampleLevel` at level 0.
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor | null} sampler
+     * @param {Float32Array | number[] | number} coords
+     * @param {number} [array_index]
+     * @returns {Float32Array}
+     */
+    textureSample(t, sampler, coords, array_index = undefined) {
+        if (array_index !== undefined) {
+            return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, array_index, 0);
+        }
+
+        return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, 0);
+    },
+
+    /**
+     * `textureSampleGrad(t, s, coords, ddx, ddy) -> vec4<T>` and the texture_2d_array form
+     * `textureSampleGrad(t, s, coords, array_index, ddx, ddy)`.
+     *
+     * Explicit-gradient sample. Mipmaps are not modelled (see the header), so the gradients only
+     * disambiguate which call shape this is: six arguments carry an array index, five do not.
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor | null} sampler
+     * @param {Float32Array | number[] | number} coords
+     * @param {Float32Array | number[] | number} p3 gradient, or the array index
+     * @param {Float32Array | number[]} p4 gradient
+     * @param {Float32Array | number[]} [p5] gradient, in the array form
+     * @returns {Float32Array}
+     */
+    textureSampleGrad(t, sampler, coords, p3, p4, p5 = undefined) {
+        if (p5 !== undefined) {
+            return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, p3, 0);
+        }
+
+        return WGSLLanguageCore.textureSampleLevel(t, sampler, coords, 0);
+    },
+
+    /**
+     * `textureGather(component, t, s, coords[, array_index][, offset]) -> vec4<f32>` and the
+     * depth-texture overloads `textureGather(t, s, coords[, array_index][, offset])`, which carry
+     * no `component` argument because a `texture_depth_*` has a single channel.
+     *
+     * Returns the four texels of the bilinear footprint unblended, in WGSL's order —
+     * counter-clockwise from the lower-left, so `.wzxy` is row-major. See
+     * {@link cpu_texture_gather} for the footprint derivation, the component order in full, and
+     * why `magFilter` is ignored here (a gather never filters).
+     *
+     * Overloads are told apart by argument SHAPE, the way `textureLoad` and `textureSampleLevel`
+     * already tell their array forms apart: a leading number is the `component` of a colour
+     * gather, a leading texture means the depth overload; among the trailing arguments a number
+     * is an `array_index` and a vector is the const `offset`.
+     *
+     * **Cube textures are not supported** and throw rather than returning something. The emulator
+     * models no cube layout at all — {@link CPUBitmapData} is a flat 1D/2D/3D grid — so there is
+     * no face selection to gather across. A cube gather is recognisable by its `vec3` direction
+     * coordinate (`texture_3d` has no gather overload in WGSL at all).
+     *
+     * @param {number | import("./CPUBitmapData.js").CPUBitmapData} p0 — `component`, or the
+     *   texture in the depth overloads
+     * @param {*} p1
+     * @param {*} p2
+     * @param {*} p3
+     * @param {*} [p4]
+     * @param {*} [p5]
+     * @returns {Float32Array}
+     */
+    textureGather(p0, p1, p2, p3, p4 = undefined, p5 = undefined) {
+        const has_component = typeof p0 === 'number';
+
+        const t = has_component ? p1 : p0;
+        const sampler = has_component ? p2 : p1;
+        const coords = has_component ? p3 : p2;
+
+        assert.defined(t, 'texture');
+
+        if (coords !== null && coords !== undefined && coords.length >= 3) {
+            throw new Error("textureGather: cube textures are not supported — the emulator has no cube layout to gather a face out of (CPUBitmapData is a flat 1D/2D/3D grid). Remap to an octahedral or array atlas, as the engine's shadow path does, and gather from that.");
+        }
+
+        const component = has_component ? (p0 | 0) : 0;
+
+        let array_index = 0;
+        let offset_x = 0;
+        let offset_y = 0;
+
+        const extra_a = has_component ? p4 : p3;
+        const extra_b = has_component ? p5 : p4;
+
+        if (typeof extra_a === 'number') array_index = extra_a;
+        else if (extra_a !== undefined) { offset_x = extra_a[0]; offset_y = extra_a[1]; }
+
+        if (extra_b !== undefined) { offset_x = extra_b[0]; offset_y = extra_b[1]; }
+
+        const result = new Float32Array(4);
+
+        cpu_texture_gather(
+            result,
+            sampler ?? FALLBACK_LINEAR_CLAMP_SAMPLER,
+            t,
+            gather_texel_coord(coords, t),
+            component,
+            offset_x,
+            offset_y,
+            array_index
+        );
+
+        return result;
+    },
+
+    /**
+     * `textureGatherCompare(t, s, coords[, array_index], depth_ref[, offset]) -> vec4<f32>`
+     *
+     * The comparison form: each of the four gathered texels is tested against `depth_ref` and
+     * yields 1.0 or 0.0 — unfiltered, per texel. The blend is the shader's job, which is exactly
+     * what `shadowmap_sample_filtered` does with the result (`.wzxy` into
+     * `interpolate_bilinear_f32`).
+     *
+     * The comparison itself comes from the bound sampler's `compare`, evaluated as
+     * `compare(depth_ref, texel)` — see {@link evaluate_gpu_compare_function} for why that order
+     * is load-bearing. A sampler with no `compare` set is an error rather than a defaulted one:
+     * WGSL requires a `sampler_comparison` here, and picking a direction on the caller's behalf
+     * would invert shadows silently.
+     *
+     * Overload disambiguation is by shape, as in {@link textureGather}: a trailing vector is the
+     * const `offset`, and a fourth argument that is followed by another number is the
+     * `array_index` rather than the reference depth.
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor} sampler
+     * @param {Float32Array | number[]} coords
+     * @param {*} p3 — `depth_ref`, or the `array_index` in the array forms
+     * @param {*} [p4]
+     * @param {*} [p5]
+     * @returns {Float32Array}
+     */
+    textureGatherCompare(t, sampler, coords, p3, p4 = undefined, p5 = undefined) {
+        assert.defined(t, 'texture');
+
+        if (coords !== null && coords !== undefined && coords.length >= 3) {
+            throw new Error("textureGatherCompare: cube textures are not supported — the emulator has no cube layout to gather a face out of (CPUBitmapData is a flat 1D/2D/3D grid). Remap to an octahedral or array atlas, as the engine's shadow path does, and gather from that.");
+        }
+
+        let array_index = 0;
+        let depth_ref;
+        let offset = undefined;
+
+        if (p5 !== undefined) {
+            // (t, s, coords, array_index, depth_ref, offset)
+            array_index = p3;
+            depth_ref = p4;
+            offset = p5;
+        } else if (p4 === undefined) {
+            // (t, s, coords, depth_ref)
+            depth_ref = p3;
+        } else if (typeof p4 === 'number') {
+            // (t, s, coords, array_index, depth_ref) — a scalar in the 5th slot is the reference
+            array_index = p3;
+            depth_ref = p4;
+        } else {
+            // (t, s, coords, depth_ref, offset) — a vector in the 5th slot is the offset
+            depth_ref = p3;
+            offset = p4;
+        }
+
+        const effective_sampler = sampler ?? FALLBACK_LINEAR_CLAMP_SAMPLER;
+        const compare = effective_sampler.compare;
+
+        if (compare === undefined || compare === null) {
+            throw new Error("textureGatherCompare: the bound sampler has no 'compare' function — WGSL requires a sampler_comparison here. Bind a SamplerDescriptor with `compare` set (the engine's shadow path uses SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR, `compare: \"greater\"` for reverse-Z).");
+        }
+
+        const result = new Float32Array(4);
+
+        cpu_texture_gather(
+            result,
+            effective_sampler,
+            t,
+            gather_texel_coord(coords, t),
+            0,
+            offset !== undefined ? offset[0] : 0,
+            offset !== undefined ? offset[1] : 0,
+            array_index
+        );
+
+        for (let i = 0; i < 4; i++) {
+            result[i] = evaluate_gpu_compare_function(compare, depth_ref, result[i]);
+        }
+
+        return result;
+    },
+
+    /**
+     * `textureStore(t, coords, value) -> ()`
+     *
+     * Integer-coord write into a storage texture. Out-of-bounds writes are
+     * silently dropped (WGSL semantics). `coords` length matches the
+     * texture dimensionality.
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {Int32Array | Uint32Array | number[] | number} coords
+     * @param {Float32Array | Int32Array | Uint32Array | number[]} value
+     */
+    textureStore(t, coords, value) {
+        assert.defined(t, 'texture');
+        const dim = t.dimensionality;
+        const x = (dim >= 1 ? (typeof coords === 'number' ? coords : coords[0]) : 0) | 0;
+        const y = (dim >= 2 ? coords[1] : 0) | 0;
+        const z = (dim >= 3 ? coords[2] : 0) | 0;
+        t.write(x, y, z, value);
+    },
+
+    /**
+     * `textureDimensions(t, level) -> u32 | vec2<u32> | vec3<u32>`
+     *
+     * Returns the texture's size as a vector matching its dimensionality.
+     * 1D textures return a scalar `u32` in WGSL; we still hand back a
+     * length-1 Uint32Array so the calling shader can swizzle/index it
+     * uniformly with the multi-axis case.
+     *
+     * @param {import("./CPUBitmapData.js").CPUBitmapData} t
+     * @param {number} [_level]
+     * @returns {Uint32Array}
+     */
+    textureDimensions(t, _level = 0) {
+        assert.defined(t, 'texture');
+        const dim = t.dimensionality;
+        if (dim === 1) return new Uint32Array([t.size[0]]);
+        if (dim === 2) return new Uint32Array([t.size[0], t.size[1]]);
+        return new Uint32Array([t.size[0], t.size[1], t.size[2]]);
+    },
+
+    // ---------------------------------------------------------------------
+    // Atomic ops on `atomic<T>` (modeled as { value: number } objects)
+    // ---------------------------------------------------------------------
+
+    atomicLoad(p) { return p.value; },
+    atomicStore(p, v) { p.value = v; },
+    atomicAdd(p, v) { const old = p.value; p.value = (p.value + v) | 0; return old; },
+    atomicSub(p, v) { const old = p.value; p.value = (p.value - v) | 0; return old; },
+    atomicMin(p, v) { const old = p.value; p.value = Math.min(p.value, v); return old; },
+    atomicMax(p, v) { const old = p.value; p.value = Math.max(p.value, v); return old; },
+    atomicAnd(p, v) { const old = p.value; p.value = p.value & v; return old; },
+    atomicOr(p, v) { const old = p.value; p.value = p.value | v; return old; },
+    atomicXor(p, v) { const old = p.value; p.value = p.value ^ v; return old; },
+    atomicExchange(p, v) { const old = p.value; p.value = v; return old; },
+    atomicCompareExchangeWeak(p, expected, v) {
+        const old = p.value;
+        if (old === expected) {
+            p.value = v;
+            return { old_value: old, exchanged: true };
+        }
+        return { old_value: old, exchanged: false };
+    },
+
+    // ---------------------------------------------------------------------
+    // Barriers — no-ops when running pointwise (one thread).
+    // ---------------------------------------------------------------------
+
+    workgroupBarrier() { /* no-op */ },
+    storageBarrier() { /* no-op */ },
+    textureBarrier() { /* no-op */ },
+
+    // A barrier plus a load of the pointed-at workgroup variable, which the compiler has already
+    // reduced to the variable itself — `&x` and `*x` both compile to `x`, since pointers are
+    // modelled as the values they name. The barrier half is the no-op above.
+    workgroupUniformLoad(value) { return value; },
+
+    // ---------------------------------------------------------------------
+    // Fragment-stage derivatives — unsupported because we run a single pixel.
+    // ---------------------------------------------------------------------
+    //
+    // dpdx/dpdy/fwidth and their fine/coarse variants are implicit-derivative builtins that the
+    // GPU computes from a 2x2 quad of neighbouring fragment threads. The emulator dispatches one
+    // pixel at a time, so there's no neighbouring data to take a finite difference against —
+    // any sensible value would be a fabrication. We throw to surface this clearly in tests.
+
+    dpdx() { throw new Error('dpdx is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    dpdy() { throw new Error('dpdy is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    fwidth() { throw new Error('fwidth is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    dpdxFine() { throw new Error('dpdxFine is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    dpdyFine() { throw new Error('dpdyFine is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    fwidthFine() { throw new Error('fwidthFine is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    dpdxCoarse() { throw new Error('dpdxCoarse is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    dpdyCoarse() { throw new Error('dpdyCoarse is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+    fwidthCoarse() { throw new Error('fwidthCoarse is not available in the fragment-shader emulator: derivatives require a 2x2 quad, but the emulator runs a single pixel.'); },
+
+    // ---------------------------------------------------------------------
+    // Pack / unpack — fixed-point and float bit-level packers from the WGSL spec.
+    // ---------------------------------------------------------------------
+
+    /** vec2<f32>(low_u16, high_u16) / 65535.0 — components in [0, 1]. */
+    unpack2x16unorm(e) {
+        const u = e >>> 0;
+        return new Float32Array([(u & 0xFFFF) / 65535.0, ((u >>> 16) & 0xFFFF) / 65535.0]);
+    },
+
+    /** vec2<f32>(low_i16, high_i16) / 32767.0 — components in [-1, 1]. */
+    unpack2x16snorm(e) {
+        const u = e >>> 0;
+        const sign16 = (h) => (h & 0x8000) !== 0 ? h - 0x10000 : h;
+        const x = sign16(u & 0xFFFF) / 32767.0;
+        const y = sign16((u >>> 16) & 0xFFFF) / 32767.0;
+        return new Float32Array([Math.max(x, -1), Math.max(y, -1)]);
+    },
+
+    /** vec4<f32>(byte0, byte1, byte2, byte3) / 255.0 — components in [0, 1]. */
+    unpack4x8unorm(e) {
+        const u = e >>> 0;
+        return new Float32Array([
+            (u & 0xFF) / 255.0,
+            ((u >>> 8) & 0xFF) / 255.0,
+            ((u >>> 16) & 0xFF) / 255.0,
+            ((u >>> 24) & 0xFF) / 255.0,
+        ]);
+    },
+
+    /** vec4<f32>(i8 byte0..3) / 127.0 — components in [-1, 1]. */
+    unpack4x8snorm(e) {
+        const u = e >>> 0;
+        const sign8 = (b) => (b & 0x80) !== 0 ? b - 0x100 : b;
+        const out = new Float32Array(4);
+        for (let i = 0; i < 4; i++) {
+            out[i] = Math.max(sign8((u >>> (i * 8)) & 0xFF) / 127.0, -1);
+        }
+        return out;
+    },
+
+    /** Inverse of unpack2x16unorm — clamp to [0, 1] and round to 16-bit integer. */
+    pack2x16unorm(v) {
+        const x = Math.round(Math.min(Math.max(v[0], 0), 1) * 65535.0);
+        const y = Math.round(Math.min(Math.max(v[1], 0), 1) * 65535.0);
+        return ((y << 16) | x) >>> 0;
+    },
+
+    /** Inverse of unpack2x16snorm — clamp to [-1, 1] and round to 16-bit signed integer. */
+    pack2x16snorm(v) {
+        const enc = (f) => Math.round(Math.min(Math.max(f, -1), 1) * 32767.0) & 0xFFFF;
+        return ((enc(v[1]) << 16) | enc(v[0])) >>> 0;
+    },
+
+    /** Inverse of unpack4x8unorm — clamp to [0, 1] and round to 8-bit integer per channel. */
+    pack4x8unorm(v) {
+        let r = 0;
+        for (let i = 0; i < 4; i++) {
+            const b = Math.round(Math.min(Math.max(v[i], 0), 1) * 255.0) & 0xFF;
+            r |= b << (i * 8);
+        }
+        return r >>> 0;
+    },
+
+    /** Inverse of unpack4x8snorm — clamp to [-1, 1] and round to 8-bit signed integer per channel. */
+    pack4x8snorm(v) {
+        let r = 0;
+        for (let i = 0; i < 4; i++) {
+            const b = Math.round(Math.min(Math.max(v[i], -1), 1) * 127.0) & 0xFF;
+            r |= b << (i * 8);
+        }
+        return r >>> 0;
+    },
+};
+
+/**
+ * Bit-cast (WGSL `bitcast`). Reinterprets a value's bit pattern as a different type.
+ *
+ * JS has no separate u32/i32/f32 scalar types — they're all `number` — so the source type
+ * cannot be detected from the value at runtime. The compiler passes it explicitly when known;
+ * otherwise we fall back to a heuristic: integer-targeted casts assume f32 source, float-targeted
+ * casts assume u32 source (the common "interpret bit pattern as float" idiom).
+ *
+ * For typed-array (vector) inputs the source type is auto-detected from the array constructor.
+ *
+ * @param {*} v
+ * @param {string} target — destination type name, e.g. `'f32'` / `'u32'` / `'i32'`
+ * @param {string} [source] — source type name; required for unambiguous scalar casts
+ * @returns {number | TypedArray}
+ */
+WGSLLanguageCore.bitcast = function (v, target, source) {
+    // Vector targets (`vec3<u32>` etc.) reduce to their scalar type — the runtime stores vectors
+    // as flat typed arrays, so the per-element bitcast is the same as for a scalar of that type.
+    const vec_match = typeof target === 'string' ? target.match(/^vec\d<([^>]+)>$/) : null;
+    if (vec_match !== null) {
+        target = vec_match[1];
+    }
+
+    function convert_scalar(x, t_from, t_to) {
+        if (t_to === 'f32') {
+            if (t_from === 'u32') { BITCAST_U32[0] = x >>> 0; return BITCAST_F32[0]; }
+            if (t_from === 'i32') { BITCAST_I32[0] = x | 0; return BITCAST_F32[0]; }
+        } else if (t_to === 'u32') {
+            if (t_from === 'f32') { BITCAST_F32[0] = x; return BITCAST_U32[0]; }
+            if (t_from === 'i32') { return (x | 0) >>> 0; }
+        } else if (t_to === 'i32') {
+            if (t_from === 'f32') { BITCAST_F32[0] = x; return BITCAST_I32[0]; }
+            if (t_from === 'u32') { return (x >>> 0) | 0; }
+        }
+        return x;
+    }
+
+    if (is_vec(v)) {
+        let from = source;
+        if (from === undefined) {
+            if (v instanceof Float32Array) from = 'f32';
+            else if (v instanceof Float16Array) from = 'f16';
+            else if (v instanceof Uint32Array) from = 'u32';
+            else if (v instanceof Int32Array) from = 'i32';
+            else from = 'f32';
+        }
+
+        let outCtor;
+        if (target === 'f32') outCtor = Float32Array;
+        else if (target === 'f16') outCtor = Float16Array;
+        else if (target === 'u32') outCtor = Uint32Array;
+        else if (target === 'i32') outCtor = Int32Array;
+        else outCtor = v.constructor;
+
+        const out = new outCtor(v.length);
+        for (let i = 0; i < v.length; i++) {
+            out[i] = convert_scalar(v[i], from, target);
+        }
+        return out;
+    }
+
+    let from = source;
+    if (from === undefined) {
+        from = (target === 'f32' || target === 'f16') ? 'u32' : 'f32';
+    }
+    return convert_scalar(v, from, target);
+};