@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/volumetrics/ParticipatingMediaVolume.js

@@ -1,7 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
 import { rgb_to_luminance } from "../../../core/color/rgb_to_luminance.js";
-import { Transform } from "../../../engine/ecs/transform/Transform.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 
 export class VolumetricsParticleSpec {
     /**
@@ -182,8 +182,8 @@ export class ParticipatingMediaVolume {
     /**
      * Defines actual scale, orientation and world position of the volume.
      * The base size of the volume is 1, centered at 0,0,0
-     * @type {Transform}
+     * @type {Transform64}
      */
-    transform = new Transform();
+    transform = new Transform64();
 
 }

package/src/shade/wgsl/emulator/ComputeShaderEmulator.d.ts

@@ -16,6 +16,11 @@
  *   emu.dispatch([0, 0, 0]);   // global_invocation_id = (0,0,0)
  *   emu.dispatch([1, 0, 0]);   // global_invocation_id = (1,0,0)
  *   // ... bindings now contain results
+ *
+ * Each dispatch is a fresh invocation: `var<private>` variables go back to their declared
+ * initializers first, as they do on the GPU. `var<workgroup>` variables do not — they belong to
+ * the workgroup, so lanes dispatched in sequence share them until {@link
+ * ComputeShaderEmulator#resetWorkgroup} is called.
  */
 export class ComputeShaderEmulator {
     /**
@@ -74,7 +79,9 @@ export class ComputeShaderEmulator {
     /**
      * Compile a {@link CodeChunk} (or a raw WGSL string) into a "library" object — every
      * top-level WGSL function becomes a method, every `var<private>` becomes a getter/setter
-     * property, and every module-scope `const` becomes a read-only getter.
+     * property, and every module-scope `const` becomes a read-only getter. `reset_private()`
+     * puts the private variables back to their initial values; there is no dispatch here to do
+     * it for you, so call it between cases that must not see each other's state.
      *
      * No `@compute` entry is required. This is the one-line escape hatch for unit-testing pure
      * helper code (RNGs, hashes, packing, math) without wrapping each chunk in a shader skeleton.
@@ -116,6 +123,17 @@ export class ComputeShaderEmulator {
      * @type {object}
      */
     bindings: object;
+    /**
+     * Whether {@link dispatch} starts each thread with the module's `var<private>` variables
+     * back at their start-of-invocation values. On by default, because that is what a GPU
+     * invocation gets — see {@link resetPrivate}.
+     *
+     * Turn it off to simulate something the hardware cannot, such as watching a private RNG
+     * advance across a run of dispatches.
+     *
+     * @type {boolean}
+     */
+    resetPrivateOnDispatch: boolean;
     /**
      * @returns {string} the WGSL source.
      */
@@ -153,6 +171,21 @@ export class ComputeShaderEmulator {
      * variables start fresh. No-op for fragment-stage entries.
      */
     resetWorkgroup(): void;
+    /**
+     * Return every module-scope `var<private>` to the value it has at the start of a WGSL
+     * invocation — its declared initializer, or zero when it was declared without one.
+     *
+     * {@link dispatch} calls this for you, because that is what the GPU does: private variables
+     * are per-invocation, and one invocation never sees what another left in them. Set
+     * {@link resetPrivateOnDispatch} to `false` for the rare simulation that wants a run of
+     * dispatches to share private state, then call this by hand.
+     *
+     * The private-address-space counterpart of {@link resetWorkgroup} — but note the asymmetry:
+     * `var<workgroup>` state is shared by the lanes of a workgroup, so it is reset per workgroup
+     * and by the caller; `var<private>` state is not shared at all, so it is reset per dispatch
+     * and by default.
+     */
+    resetPrivate(): void;
     /**
      * Dispatch a single thread (point-wise simulation). The arguments are the entry function's
      * parameters, in declaration order — for example a `@builtin(global_invocation_id)` param of

package/src/shade/wgsl/emulator/ComputeShaderEmulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputeShaderEmulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/ComputeShaderEmulator.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAoII;;;;;;;;;;OAUG;IACH,0BANW,MAAM;QAEe,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,qBAAqB,CAAC,CAa1C;IAED;;;;;;;;OAQG;IACH,iCANW,OAAO,wCAAwC,EAAE,aAAa;QAEzC,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,qBAAqB,CAAC,CAM1C;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,+BANW,OAAO,sCAAsC,EAAE,WAAW;QAErC,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,qBAAqB,CAAC,CAM1C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,sCANW,OAAO,6CAA6C,EAAE,SAAS,GAAG,MAAM;QAEnD,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,MAAM,CAAC,CAS3B;IAvMD;;;;;;;;;;OAUG;IACH;QAL2B,MAAM,EAAtB,MAAM;QACU,MAAM,EAAtB,MAAM;QACU,QAAQ,EAAxB,MAAM;QACU,YAAY,EAA5B,MAAM;OAYhB;IA5BD;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAyBd;;OAEG;IACH,qBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,oCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,uBAIC;IAED;;;;;;;;;;;OAWG;IACH,kCAKC;;CA8FJ;2BAvP0B,kBAAkB"}
+{"version":3,"file":"ComputeShaderEmulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/ComputeShaderEmulator.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAqKI;;;;;;;;;;OAUG;IACH,0BANW,MAAM;QAEe,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,qBAAqB,CAAC,CAa1C;IAED;;;;;;;;OAQG;IACH,iCANW,OAAO,wCAAwC,EAAE,aAAa;QAEzC,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,qBAAqB,CAAC,CAM1C;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,+BANW,OAAO,sCAAsC,EAAE,WAAW;QAErC,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,qBAAqB,CAAC,CAM1C;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sCANW,OAAO,6CAA6C,EAAE,SAAS,GAAG,MAAM;QAEnD,MAAM,GAA3B,UAAU;QACO,YAAY,GAA7B,MAAM;QACJ,QAAQ,MAAM,CAAC,CAS3B;IA9ND;;;;;;;;;;OAUG;IACH;QAL2B,MAAM,EAAtB,MAAM;QACU,MAAM,EAAtB,MAAM;QACU,QAAQ,EAAxB,MAAM;QACU,YAAY,EAA5B,MAAM;OAYhB;IAxCD;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;;;;;OASG;IACH,wBAFU,OAAO,CAEa;IAyB9B;;OAEG;IACH,qBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,oCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,uBAIC;IAED;;;;;;;;;;;;;OAaG;IACH,qBAEC;IAED;;;;;;;;;;;OAWG;IACH,kCAQC;;CAgGJ;2BA/R0B,kBAAkB"}

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

@@ -21,6 +21,11 @@ import { WGSLLanguageCore } from "./WGSLLanguageCore.js";
  *   emu.dispatch([0, 0, 0]);   // global_invocation_id = (0,0,0)
  *   emu.dispatch([1, 0, 0]);   // global_invocation_id = (1,0,0)
  *   // ... bindings now contain results
+ *
+ * Each dispatch is a fresh invocation: `var<private>` variables go back to their declared
+ * initializers first, as they do on the GPU. `var<workgroup>` variables do not — they belong to
+ * the workgroup, so lanes dispatched in sequence share them until {@link
+ * ComputeShaderEmulator#resetWorkgroup} is called.
  */
 export class ComputeShaderEmulator {
 
@@ -46,6 +51,18 @@ export class ComputeShaderEmulator {
      */
     bindings = {};
 
+    /**
+     * Whether {@link dispatch} starts each thread with the module's `var<private>` variables
+     * back at their start-of-invocation values. On by default, because that is what a GPU
+     * invocation gets — see {@link resetPrivate}.
+     *
+     * Turn it off to simulate something the hardware cannot, such as watching a private RNG
+     * advance across a run of dispatches.
+     *
+     * @type {boolean}
+     */
+    resetPrivateOnDispatch = true;
+
     /**
      * Construct directly when you already have the WGSL source string.
      *
@@ -135,6 +152,24 @@ export class ComputeShaderEmulator {
         }
     }
 
+    /**
+     * Return every module-scope `var<private>` to the value it has at the start of a WGSL
+     * invocation — its declared initializer, or zero when it was declared without one.
+     *
+     * {@link dispatch} calls this for you, because that is what the GPU does: private variables
+     * are per-invocation, and one invocation never sees what another left in them. Set
+     * {@link resetPrivateOnDispatch} to `false` for the rare simulation that wants a run of
+     * dispatches to share private state, then call this by hand.
+     *
+     * The private-address-space counterpart of {@link resetWorkgroup} — but note the asymmetry:
+     * `var<workgroup>` state is shared by the lanes of a workgroup, so it is reset per workgroup
+     * and by the caller; `var<private>` state is not shared at all, so it is reset per dispatch
+     * and by default.
+     */
+    resetPrivate() {
+        this.#module.reset_private();
+    }
+
     /**
      * Dispatch a single thread (point-wise simulation). The arguments are the entry function's
      * parameters, in declaration order — for example a `@builtin(global_invocation_id)` param of
@@ -148,6 +183,9 @@ export class ComputeShaderEmulator {
      * @returns {*}
      */
     dispatch(...mainArgs) {
+        if (this.resetPrivateOnDispatch) {
+            this.resetPrivate();
+        }
         if (this.#module.stage === 'fragment') {
             return this.#module.entry(this.bindings, ...mainArgs);
         }
@@ -223,7 +261,9 @@ export class ComputeShaderEmulator {
     /**
      * Compile a {@link CodeChunk} (or a raw WGSL string) into a "library" object — every
      * top-level WGSL function becomes a method, every `var<private>` becomes a getter/setter
-     * property, and every module-scope `const` becomes a read-only getter.
+     * property, and every module-scope `const` becomes a read-only getter. `reset_private()`
+     * puts the private variables back to their initial values; there is no dispatch here to do
+     * it for you, so call it between cases that must not see each other's state.
      *
      * No `@compute` entry is required. This is the one-line escape hatch for unit-testing pure
      * helper code (RNGs, hashes, packing, math) without wrapping each chunk in a shader skeleton.

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.d.ts

@@ -6,8 +6,9 @@ export class WGSLJavaScriptCompiler {
      * a shader module object. The shape depends on what the WGSL declared:
      *
      * - **Always present:** every top-level user function (e.g. `module.random()`),
-     *   every struct class (e.g. `module.Foo`), and a getter/setter property for each
-     *   `var<private>` and getter for each module-scope `const`.
+     *   every struct class (e.g. `module.Foo`), a getter/setter property for each
+     *   `var<private>` and getter for each module-scope `const`, and `reset_private()`,
+     *   which returns every `var<private>` to its start-of-invocation value.
      * - **Compute-shader fields (only when a `@compute` entry is present):**
      *   ```
      *   {

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLJavaScriptCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js"],"names":[],"mappings":"AA+bA;IAEI;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,oBAFa,MAAM,CAMlB;CACJ;;UAvda,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS;WAClG,MAAM;WACN,MAAM;WACN,MAAM;WACN,MAAM;aACN,MAAM;cACN,QAAQ;YACR,MAAM"}
+{"version":3,"file":"WGSLJavaScriptCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js"],"names":[],"mappings":"AA2cA;IAEI;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,oBAFa,MAAM,CAMlB;CACJ;;UApea,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS;WAClG,MAAM;WACN,MAAM;WACN,MAAM;WACN,MAAM;aACN,MAAM;cACN,QAAQ;YACR,MAAM"}

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

@@ -383,6 +383,16 @@ const ARITHMETIC_OP = {
 
 const RAW_BINARY_OPS = new Set(['<', '>', '<=', '>=', '==', '!=', '&&', '||', '&', '|', '^', '<<', '>>']);
 
+/**
+ * Arithmetic operators that wrap at 32 bits when WGSL types the result as an integer. Mapped to the
+ * helper-name prefix; the scalar type (`u32` / `i32`) is appended at the call site.
+ */
+const INTEGER_WRAPPING_OP = {
+    '+': 'add',
+    '-': 'sub',
+    '*': 'mul',
+};
+
 // =========================================================================
 // Compiler context — central state during compilation
 // =========================================================================
@@ -409,10 +419,12 @@ class Compiler {
 
         /**
          * Module-scope `var<private>` and `const` declarations, in declaration order.
-         * Each entry is `{ name, kind: 'let' | 'const', code }` — `code` is the JS line emitted
-         * verbatim; `name` and `kind` are also tracked so the returned module object can expose
-         * them as getter/setter (or read-only) properties for testing.
-         * @type {Array<{ name: string, kind: 'let' | 'const', code: string }>}
+         * Each entry is `{ name, kind: 'let' | 'const', code, init }` — `code` is the JS line
+         * emitted verbatim; `name` and `kind` are also tracked so the returned module object can
+         * expose them as getter/setter (or read-only) properties for testing, and `init` is the
+         * initializer expression on its own, which the private-state reset re-emits for the `let`
+         * ones (a `const` cannot be reassigned, and no invocation can disturb it).
+         * @type {Array<{ name: string, kind: 'let' | 'const', code: string, init: string }>}
          */
         this.privateGlobals = [];
 
@@ -454,8 +466,9 @@ export class WGSLJavaScriptCompiler {
      * a shader module object. The shape depends on what the WGSL declared:
      *
      * - **Always present:** every top-level user function (e.g. `module.random()`),
-     *   every struct class (e.g. `module.Foo`), and a getter/setter property for each
-     *   `var<private>` and getter for each module-scope `const`.
+     *   every struct class (e.g. `module.Foo`), a getter/setter property for each
+     *   `var<private>` and getter for each module-scope `const`, and `reset_private()`,
+     *   which returns every `var<private>` to its start-of-invocation value.
      * - **Compute-shader fields (only when a `@compute` entry is present):**
      *   ```
      *   {
@@ -539,7 +552,12 @@ function compileTranslationUnit(c, root) {
         if (node.type === 'function_decl') emitFunction(c, node);
     }
 
-    // 5) Entry-stage support code: the dispatch wrapper for any entry, plus a workgroup-state
+    // 5) The private-state reset. Emitted for every module, library ones included: a
+    //    `var<private>` is per-invocation state on the GPU, and the JS `let` above outlives the
+    //    dispatch that wrote it, so something has to put the initial values back.
+    emitPrivateStateReset(c);
+
+    // 6) Entry-stage support code: the dispatch wrapper for any entry, plus a workgroup-state
     //    factory for @compute entries (fragment shaders have no var<workgroup>). Skipped entirely
     //    in library mode (no entry attribute) so the resulting module is just a bag of pure
     //    functions and globals.
@@ -550,7 +568,7 @@ function compileTranslationUnit(c, root) {
         emitEntryWrapper(c);
     }
 
-    // 6) Build and return the module object.
+    // 7) Build and return the module object.
     emitModuleReturn(c);
 
     c.out.dedent();
@@ -561,8 +579,9 @@ function compileTranslationUnit(c, root) {
  * Emit the `return { ... }` block of the factory. Every top-level user function and struct
  * class is exposed by name; module-scope `var<private>` slots become getter/setter properties
  * (so tests can inspect or seed RNG state etc.), and module-scope `const`s become read-only
- * getters. When the WGSL had a `@compute` entry, the dispatch trio (`entry_name`,
- * `workgroup_size`, `param_names`, `entry`, `create_workgroup_state`) is included.
+ * getters. `reset_private` is always included. When the WGSL had a `@compute` entry, the dispatch
+ * trio (`entry_name`, `workgroup_size`, `param_names`, `entry`, `create_workgroup_state`) is
+ * included too.
  */
 function emitModuleReturn(c) {
     c.out.add('const __module__ = {};');
@@ -582,6 +601,8 @@ function emitModuleReturn(c) {
         }
     }
 
+    c.out.add('__module__.reset_private = __reset_private__;');
+
     if (c.entry !== null) {
         c.out.add(`__module__.entry_name = ${JSON.stringify(c.entry.name)};`);
         c.out.add(`__module__.stage = ${JSON.stringify(c.entry.stage)};`);
@@ -890,6 +911,7 @@ function collectGlobalVariable(c, node) {
         name,
         kind: 'let',
         code: `let ${name} = ${init_code};`,
+        init: init_code,
     });
 }
 
@@ -928,6 +950,7 @@ function collectGlobalValue(c, node) {
         name,
         kind: 'const',
         code: `const ${name} = ${expr.code};`,
+        init: expr.code,
     });
 }
 
@@ -935,6 +958,32 @@ function collectGlobalValue(c, node) {
 // Workgroup state factory + entry wrapper
 // =========================================================================
 
+/**
+ * Emit `__reset_private__()`, which restores every module-scope `var<private>` to the value it
+ * would have at the start of a WGSL invocation — its declared initializer, or the type's zero
+ * value when it was declared without one.
+ *
+ * This is the private-address-space counterpart of {@link emitWorkgroupStateFactory}. The
+ * generated module keeps its private slots in `let` bindings that live as long as the module, so
+ * without this a second dispatch would start from whatever the first one left behind — state the
+ * GPU never carries.
+ *
+ * Module-scope `const`s are skipped: they are immutable in the generated JS and no invocation can
+ * disturb them.
+ *
+ * @param {Compiler} c
+ */
+function emitPrivateStateReset(c) {
+    c.out.add('function __reset_private__() {');
+    c.out.indent();
+    for (const g of c.privateGlobals) {
+        if (g.kind !== 'let') continue;
+        c.out.add(`${g.name} = ${g.init};`);
+    }
+    c.out.dedent();
+    c.out.add('}');
+}
+
 function emitWorkgroupStateFactory(c) {
     c.out.add('function __create_workgroup_state__() {');
     c.out.indent();
@@ -972,7 +1021,20 @@ function emitEntryWrapper(c) {
         }
     }
 
-    c.out.add(`return ${c.entry.name}(${param_names.join(', ')});`);
+    if (is_compute && c.workgroupVars.length > 0) {
+        // The lanes of one workgroup are dispatched one call at a time, and a scalar
+        // `var<workgroup>` a lane assigns lives in the module-scope slot above — a copy of the
+        // state object's field, not the field. Writing it back is what lets the next lane see it,
+        // which is the whole point of workgroup memory (an array slot already persists, since the
+        // slot holds a reference and the lane mutates it in place).
+        c.out.add(`const __result__ = ${c.entry.name}(${param_names.join(', ')});`);
+        for (const wv of c.workgroupVars) {
+            c.out.add(`__workgroup__.${wv.name} = ${wv.name};`);
+        }
+        c.out.add('return __result__;');
+    } else {
+        c.out.add(`return ${c.entry.name}(${param_names.join(', ')});`);
+    }
 
     c.out.dedent();
     c.out.add('}');
@@ -1139,6 +1201,19 @@ function emitVariableUpdatingStatement(c, node) {
             c.out.add(emitWriteStatement(lhs_compiled, `wgsl.${arith[op_text]}(${lhs_compiled.code}, ${rhs_compiled.code})`));
             return;
         }
+
+        // Bitwise / shift compound assignment, routed like the binary operators: through the
+        // element-wise helpers for a vec/mat or bool LHS (raw JS coerces a typed array to NaN and
+        // a bool to 0/1), and for `>>=` on u32 (JS `>>` sign-extends).
+        const bitwise_helper = BITWISE_HELPER[op_text.slice(0, -1)];
+        if (bitwise_helper !== undefined && (
+            isContainerType(lhs_compiled.type)
+            || isScalarBool(lhs_compiled.type)
+            || (op_text === '>>=' && (isScalarUnsigned(lhs_compiled.type) || isScalarUnsigned(rhs_compiled.type)))
+        )) {
+            c.out.add(emitWriteStatement(lhs_compiled, `wgsl.${bitwise_helper}(${lhs_compiled.code}, ${rhs_compiled.code})`));
+            return;
+        }
         c.out.add(`${lhs_compiled.code} ${op_text} ${rhs_compiled.code};`);
         return;
     }
@@ -1648,9 +1723,19 @@ function compileBinaryExpression(c, node, op_type, mode) {
             if (op_text === '/' && integerDivision(left, right)) {
                 actual_helper = 'idiv';
             }
+            // WGSL `+` / `-` / `*` on integer types wrap at 32 bits. JS numbers don't, and the bits
+            // an overflowing f64 drops are the low ones — which silently ruins hashes and PRNGs
+            // (see the wrapping helpers in WGSLLanguageCore.js). Route to the wrapping variant only
+            // when the result type is *known* to be an integer, so anything untyped or float keeps
+            // the plain helper.
+            const arith_type = inferBinaryArithResultType(left.type, right.type);
+            const wrapping = INTEGER_WRAPPING_OP[op_text];
+            if (wrapping !== undefined && isIntegerType(arith_type)) {
+                actual_helper = `${wrapping}_${integerScalarName(arith_type)}`;
+            }
             return {
                 code: `wgsl.${actual_helper}(${left.code}, ${right.code})`,
-                type: inferBinaryArithResultType(left.type, right.type),
+                type: arith_type,
                 // arithmetic on two AbstractInts is still AbstractInt: `(1 + 2) / 2` is 1
                 abstract_int: left.abstract_int === true && right.abstract_int === true,
             };
@@ -1658,11 +1743,13 @@ function compileBinaryExpression(c, node, op_type, mode) {
     }
 
     // Bitwise (`&` / `|` / `^`) and shift (`<<` / `>>`) operators. Routed through element-wise
-    // helpers for vec/mat operands (JS raw operators coerce typed arrays to NaN), AND for `>>`
-    // on u32 scalars — JS's signed `>>` sign-extends, but WGSL u32 shift is logical.
+    // helpers for vec/mat operands (JS raw operators coerce typed arrays to NaN), for bool
+    // operands (raw JS yields 0/1 where WGSL yields a bool), AND for `>>` on u32 scalars — JS's
+    // signed `>>` sign-extends, but WGSL u32 shift is logical.
     const bitwise_helper = BITWISE_HELPER[op_text];
     if (bitwise_helper !== undefined) {
-        if (isContainerType(left.type) || isContainerType(right.type)) {
+        if (isContainerType(left.type) || isContainerType(right.type)
+            || isScalarBool(left.type) || isScalarBool(right.type)) {
             return {
                 code: `wgsl.${bitwise_helper}(${left.code}, ${right.code})`,
                 type: inferRawBinaryResultType(left.type, right.type, op_text),
@@ -1722,6 +1809,17 @@ function isScalarUnsigned(t) {
     return t && t.kind === 'primitive' && t.name === 'u32';
 }
 
+/** True if `t` is a bool scalar — WGSL `&` / `|` / `^` on bools are logical and stay bool. */
+function isScalarBool(t) {
+    return t && t.kind === 'primitive' && t.name === 'bool';
+}
+
+/** The scalar name (`u32` / `i32`) of an integer type, for picking a wrapping arithmetic helper. */
+function integerScalarName(t) {
+    if (t.kind === 'primitive') return t.name;
+    return t.scalar;
+}
+
 /** True if `t` is an integer type (scalar or vec/mat of i32/u32). */
 function isIntegerType(t) {
     if (!t) return false;
@@ -2135,6 +2233,8 @@ function inferBuiltinReturnType(name, args) {
         'exp', 'exp2', 'log', 'log2', 'sin', 'cos', 'tan', 'asin', 'acos', 'atan',
         'pow', 'atan2', 'min', 'max', 'step', 'clamp', 'saturate', 'mix', 'smoothstep',
         'normalize', 'reflect', 'fma',
+        // not math, but the same shape: the result has the type of its one argument
+        'subgroupBroadcastFirst',
     ]);
     if (ELEMENT_WISE.has(name)) {
         for (const a of args) {

package/src/shade/wgsl/emulator/WGSLLanguageCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAm+Bd"}
+{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAkgCd"}

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

@@ -468,13 +468,30 @@ export const WGSLLanguageCore = {
     // The compiler routes `/` through `idiv` when both operands' tracked types are integer.
     idiv: (a, b) => binop(a, b, (x, y) => Math.trunc(x / y)),
 
+    // WGSL integer arithmetic wraps at 32 bits; JS numbers grow instead. Without wrapping, any
+    // hash or PRNG that multiplies by a large odd constant leaves the u32 range within a step or
+    // two, and once the f64 mantissa runs out it is the *low* bits that fall off — exactly the
+    // ones an output permutation exists to mix. A generator would then collapse into a short cycle
+    // under emulation while being perfectly well distributed on device.
+    //
+    // The compiler routes `+` / `-` / `*` here only when the result type is known to be an integer,
+    // so float math never reaches these.
+    add_u32: (a, b) => binop(a, b, (x, y) => (x + y) >>> 0),
+    sub_u32: (a, b) => binop(a, b, (x, y) => (x - y) >>> 0),
+    mul_u32: (a, b) => binop(a, b, (x, y) => Math.imul(x, y) >>> 0),
+
+    add_i32: (a, b) => binop(a, b, (x, y) => (x + y) | 0),
+    sub_i32: (a, b) => binop(a, b, (x, y) => (x - y) | 0),
+    mul_i32: (a, b) => binop(a, b, (x, y) => Math.imul(x, y) | 0),
+
     // 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),
+    // u32 semantics; signed sources should bitcast first. On bools (WGSL's non-short-circuit
+    // logical `&` / `|` / `^`) the result stays a bool rather than JS's 0/1.
+    bit_and: (a, b) => binop(a, b, (x, y) => typeof x === 'boolean' ? x && y : (x & y) >>> 0),
+    bit_or:  (a, b) => binop(a, b, (x, y) => typeof x === 'boolean' ? x || y : (x | y) >>> 0),
+    bit_xor: (a, b) => binop(a, b, (x, y) => typeof x === 'boolean' ? 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),
 
@@ -1162,6 +1179,20 @@ export const WGSLLanguageCore = {
     // modelled as the values they name. The barrier half is the no-op above.
     workgroupUniformLoad(value) { return value; },
 
+    // ---------------------------------------------------------------------
+    // Subgroups — one invocation at a time, so the subgroup is that invocation.
+    // ---------------------------------------------------------------------
+    //
+    // `subgroupBroadcastFirst(e)` returns `e` from the lowest active invocation of the subgroup. Run
+    // pointwise there is exactly one, so the answer is the caller's own value — which is also the
+    // only value a shader can soundly rely on it for: one that broadcasts something its lanes
+    // disagree on has made its result depend on which lane the hardware counts as first, and no
+    // CPU model reproduces that. The rest of the family — ballots, reductions, shuffles — stays
+    // unsupported on purpose: a reduction over one lane would pass tests a real wave fails, which
+    // is worse than throwing.
+
+    subgroupBroadcastFirst(value) { return value; },
+
     // ---------------------------------------------------------------------
     // Fragment-stage derivatives — unsupported because we run a single pixel.
     // ---------------------------------------------------------------------

package/src/view/minimap/Minimap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Minimap.d.ts","sourceRoot":"","sources":["../../../../src/view/minimap/Minimap.js"],"names":[],"mappings":";AAgBA;IAGI;;;;;;OAMG;IACH,yFAFW,+BAA6B,EA8IvC;IArJD,YAAkD;IAY9C;;;OAGG;IACH,sCAAkC;IAWpB,OAFJ,SAAS,CAEiC;IAepD,uBAAyB;IAML,eAFV,iBAAiB,EAAE,CAEc;IA+B3C,+BAAyF;IA+BzE,uBAA2C;IAyC/D;;;;;;;OAOG;IACH,cAUC;CAmCJ;iBAlNgB,YAAY;sBAXP,iCAAiC;sBAUjC,0BAA0B;kCAEd,4BAA4B;+BAV/B,oCAAoC;8BAMrC,6CAA6C"}
+{"version":3,"file":"Minimap.d.ts","sourceRoot":"","sources":["../../../../src/view/minimap/Minimap.js"],"names":[],"mappings":";AAgBA;IAGI;;;;;;OAMG;IACH,yFAFW,+BAA6B,EAgJvC;IAvJD,YAAkD;IAY9C;;;OAGG;IACH,sCAAkC;IAWpB,OAFJ,SAAS,CAEiC;IAepD,uBAAyB;IAML,eAFV,iBAAiB,EAAE,CAEc;IAiC3C,+BAA2F;IA+B3E,uBAA2C;IAyC/D;;;;;;;OAOG;IACH,cAUC;CAmCJ;iBApNgB,YAAY;sBAXP,iCAAiC;sBAUjC,0BAA0B;kCAEd,4BAA4B;+BAV/B,oCAAoC;8BAMrC,6CAA6C"}