@woosh/meep-engine 2.170.0 → 3.0.1

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

@@ -0,0 +1,2151 @@
+import { assert } from "../../../core/assert.js";
+import LineBuilder from "../../../core/codegen/LineBuilder.js";
+
+// =========================================================================
+// Type representation
+// =========================================================================
+
+/**
+ * @typedef {object} WgslType
+ * @property {'primitive' | 'vec' | 'mat' | 'array' | 'struct' | 'texture_2d' | 'sampler' | 'atomic' | 'unknown'} kind
+ * @property {string} [name]
+ * @property {number} [size]
+ * @property {number} [cols]
+ * @property {number} [rows]
+ * @property {string} [scalar]
+ * @property {WgslType} [element]
+ * @property {number} [count]
+ */
+
+const T_UNKNOWN = Object.freeze({ kind: 'unknown' });
+
+const VECTOR_ALIASES = {
+    vec2i: { size: 2, scalar: 'i32' },
+    vec3i: { size: 3, scalar: 'i32' },
+    vec4i: { size: 4, scalar: 'i32' },
+    vec2u: { size: 2, scalar: 'u32' },
+    vec3u: { size: 3, scalar: 'u32' },
+    vec4u: { size: 4, scalar: 'u32' },
+    vec2f: { size: 2, scalar: 'f32' },
+    vec3f: { size: 3, scalar: 'f32' },
+    vec4f: { size: 4, scalar: 'f32' },
+    vec2h: { size: 2, scalar: 'f16' },
+    vec3h: { size: 3, scalar: 'f16' },
+    vec4h: { size: 4, scalar: 'f16' },
+};
+
+const PRIMITIVE_NAMES = new Set(['i32', 'u32', 'f32', 'f16', 'bool']);
+
+const SWIZZLE_LETTERS = new Set(['x', 'y', 'z', 'w', 'r', 'g', 'b', 'a']);
+
+const SWIZZLE_INDEX = { x: 0, y: 1, z: 2, w: 3, r: 0, g: 1, b: 2, a: 3 };
+
+/**
+ * Build a vec type alias name (e.g., {size:3, scalar:'f32'} → 'vec3f').
+ */
+function vecAliasName(size, scalar) {
+    const suffix = { i32: 'i', u32: 'u', f32: 'f', f16: 'h' }[scalar] || 'f';
+    return `vec${size}${suffix}`;
+}
+
+// =========================================================================
+// Scope (symbol table) — tracks variable types for accurate codegen
+// =========================================================================
+
+class Scope {
+    constructor(parent = null) {
+        this.parent = parent;
+        /** @type {Map<string, WgslType>} */
+        this.symbols = new Map();
+    }
+
+    declare(name, type) {
+        this.symbols.set(name, type || T_UNKNOWN);
+    }
+
+    /** @returns {WgslType} */
+    lookup(name) {
+        if (this.symbols.has(name)) return this.symbols.get(name);
+        if (this.parent) return this.parent.lookup(name);
+        return T_UNKNOWN;
+    }
+
+    push() {
+        return new Scope(this);
+    }
+}
+
+// =========================================================================
+// Tree-sitter helpers
+// =========================================================================
+
+/**
+ * Return only the named children of a node (filters out punctuation tokens).
+ */
+function namedChildren(node) {
+    return node.namedChildren;
+}
+
+/**
+ * First named child by type, or null.
+ */
+function namedChildByType(node, type) {
+    for (const c of node.namedChildren) {
+        if (c.type === type) return c;
+    }
+    return null;
+}
+
+/**
+ * All named children with the given type.
+ */
+function namedChildrenByType(node, type) {
+    return node.namedChildren.filter(c => c.type === type);
+}
+
+/**
+ * Extract the source-text slice of `parent` that lies between the end of `left` and the start
+ * of `right`. tree-sitter-web's `node.children` does not include unnamed tokens, so this is the
+ * reliable way to read operator characters that sit between two named children.
+ *
+ * @param {Node} parent
+ * @param {Node} left
+ * @param {Node} right
+ * @returns {string}
+ */
+function textBetween(parent, left, right) {
+    const left_offset = (left.endIndex - parent.startIndex);
+    const right_offset = (right.startIndex - parent.startIndex);
+    return parent.text.slice(left_offset, right_offset);
+}
+
+/**
+ * Extract any leading source text in `parent` that precedes its first named child. Used for
+ * unary operators (e.g. `-x`, `!cond`) where the operator is an unnamed token.
+ *
+ * @param {Node} parent
+ * @returns {string}
+ */
+function textBeforeFirstNamed(parent) {
+    if (parent.namedChildCount === 0) return '';
+    const first = parent.namedChildren[0];
+    const offset = first.startIndex - parent.startIndex;
+    return parent.text.slice(0, offset);
+}
+
+/**
+ * Strip wrapper nodes that have a single named child of an expression-passthrough type.
+ * The WGSL grammar has a long precedence chain: expression > relational > shift > additive > ...
+ * When an expression is "simple" each level just wraps the next.
+ */
+function unwrapExpression(node) {
+    const PASSTHROUGH = new Set([
+        'expression',
+        'relational_expression',
+        'shift_expression',
+        'additive_expression',
+        'multiplicative_expression',
+        'unary_expression',
+        'singular_expression',
+        'primary_expression',
+    ]);
+    while (PASSTHROUGH.has(node.type) && node.namedChildren.length === 1) {
+        // `unary_expression` keeps its operator as an unnamed token before the operand. If there
+        // is one, don't unwrap — the caller needs to see the unary node so it can apply the op.
+        if (node.type === 'unary_expression' && textBeforeFirstNamed(node).trim() !== '') {
+            break;
+        }
+        node = node.namedChildren[0];
+    }
+    return node;
+}
+
+// =========================================================================
+// Type parsing (from `type_specifier` nodes or raw text)
+// =========================================================================
+
+/**
+ * Parse a `type_specifier` tree-sitter node.
+ * @param {Node} node
+ * @returns {WgslType}
+ */
+function parseTypeSpecifier(node) {
+    if (node === null || node === undefined) return T_UNKNOWN;
+    if (node.type === 'type_specifier') {
+        return parseTypeSpecifier(node.namedChildren[0]);
+    }
+    if (node.type === 'template_elaborated_ident') {
+        const ident = namedChildByType(node, 'ident');
+        const ident_text = ident ? ident.text : node.text;
+        const template = namedChildByType(node, 'template_list');
+        const args = template ? extractTemplateArgs(template) : [];
+        return classifyType(ident_text, args, template);
+    }
+    return T_UNKNOWN;
+}
+
+/**
+ * Pull the textual template arguments from a `template_list` node, e.g. `<f32, 256>` → ['f32', '256'].
+ */
+function extractTemplateArgs(template_list_node) {
+    const out = [];
+    const comma_list = namedChildByType(template_list_node, 'template_arg_comma_list');
+    if (comma_list === null) return out;
+    for (const c of comma_list.namedChildren) {
+        if (c.type === 'template_arg_expression') {
+            out.push(c.text.trim());
+        }
+    }
+    return out;
+}
+
+/**
+ * @param {string} ident
+ * @param {string[]} args — textual template args (may be types or numbers)
+ * @param {Node | null} template_list_node — the original node, for parsing nested array element types
+ * @returns {WgslType}
+ */
+function classifyType(ident, args, template_list_node) {
+    if (PRIMITIVE_NAMES.has(ident)) {
+        return { kind: 'primitive', name: ident };
+    }
+    if (VECTOR_ALIASES.hasOwnProperty(ident)) {
+        const a = VECTOR_ALIASES[ident];
+        return { kind: 'vec', size: a.size, scalar: a.scalar };
+    }
+    if (ident === 'vec2' || ident === 'vec3' || ident === 'vec4') {
+        const size = parseInt(ident.slice(3));
+        const scalar = args.length > 0 ? args[0] : 'f32';
+        return { kind: 'vec', size, scalar };
+    }
+    {
+        const m = ident.match(/^mat(\d)x(\d)([ifh]?)$/);
+        if (m !== null) {
+            const cols = parseInt(m[1]);
+            const rows = parseInt(m[2]);
+            const suffix = m[3];
+            let scalar;
+            if (suffix === 'f') scalar = 'f32';
+            else if (suffix === 'i') scalar = 'i32';
+            else if (suffix === 'h') scalar = 'f16';
+            else scalar = (args.length > 0 ? args[0] : 'f32');
+            return { kind: 'mat', cols, rows, scalar };
+        }
+    }
+    if (ident === 'array') {
+        // template arg 0 is the element type (sub-template), arg 1 is the count
+        let element = T_UNKNOWN;
+        let count = -1;
+        if (template_list_node !== null) {
+            const comma_list = namedChildByType(template_list_node, 'template_arg_comma_list');
+            if (comma_list !== null) {
+                const arg_nodes = namedChildrenByType(comma_list, 'template_arg_expression');
+                if (arg_nodes.length > 0) {
+                    // Walk down to find the inner type ident
+                    const inner_expr = unwrapExpression(arg_nodes[0].namedChildren[0]);
+                    element = parseTypeSpecifier(inner_expr);
+                }
+                if (arg_nodes.length > 1) {
+                    const c = parseInt(arg_nodes[1].text.trim());
+                    if (!isNaN(c)) count = c;
+                }
+            }
+        }
+        return { kind: 'array', element, count };
+    }
+    if (ident === 'atomic') {
+        const inner = args.length > 0 ? args[0] : 'i32';
+        return { kind: 'atomic', scalar: inner };
+    }
+    // Texture types - 1D / 2D / 3D, sampled and storage variants. We
+    // collapse all of them to a single kind because the intrinsics in
+    // WGSLLanguageCore dispatch on the bound CPUBitmapData's
+    // `dimensionality`, not on the static WGSL type. (The 'texture_2d'
+    // kind label is preserved for backward compatibility with any
+    // downstream consumer that may grep for it.)
+    if (
+        ident === 'texture_2d' || ident === 'texture_storage_2d'
+        || ident === 'texture_1d' || ident === 'texture_storage_1d'
+        || ident === 'texture_3d' || ident === 'texture_storage_3d'
+        || ident === 'texture_2d_array'
+    ) {
+        const scalar = args.length > 0 ? args[0] : 'f32';
+        return { kind: 'texture_2d', scalar };
+    }
+    if (ident === 'sampler') {
+        return { kind: 'sampler' };
+    }
+    if (ident === 'ptr') {
+        // Pointer — peel off the address space and read the inner type.
+        if (template_list_node !== null) {
+            const comma_list = namedChildByType(template_list_node, 'template_arg_comma_list');
+            if (comma_list !== null) {
+                const arg_nodes = namedChildrenByType(comma_list, 'template_arg_expression');
+                if (arg_nodes.length >= 2) {
+                    const inner_expr = unwrapExpression(arg_nodes[1].namedChildren[0]);
+                    return parseTypeSpecifier(inner_expr);
+                }
+            }
+        }
+        return T_UNKNOWN;
+    }
+    // Otherwise: assume it's a struct name.
+    return { kind: 'struct', name: ident };
+}
+
+// =========================================================================
+// Literal handling — strip WGSL type suffixes for JS
+// =========================================================================
+
+/**
+ * Convert a WGSL literal token (e.g. `7u`, `1.0f`, `true`) to its JS equivalent.
+ *
+ * Stripping the type suffix is shape-sensitive: integer literals only carry `u`/`i`, and float
+ * literals only carry `f`/`h`. Crucially, a hex int like `0x0300f00f` ends in a hex digit `f`
+ * that must NOT be treated as a suffix — only an `f` after a decimal-format float counts.
+ */
+function literalToJs(text) {
+    const t = text.trim();
+    if (t === 'true' || t === 'false') return t;
+
+    // Hex int literals: `0xNN[ui]?`. Only `u`/`i` are real suffixes here; trailing `f`/`h` are
+    // hex digits.
+    if (/^0[xX]/.test(t)) {
+        return t.replace(/[ui]$/, '');
+    }
+
+    // Decimal int / float. Float forms have a `.`, `e`/`E`, or end in `f`/`h`. Int forms don't.
+    if (/[.eE]/.test(t)) {
+        return t.replace(/[fh]$/, '');
+    }
+
+    // Plain integer (no `.`, no exponent): strip `u`/`i`/`f`/`h` (the latter two appear only on
+    // forms like `1f` which WGSL allows as a float written without a decimal point).
+    return t.replace(/[uifh]$/, '');
+}
+
+// =========================================================================
+// Operator handling
+// =========================================================================
+
+/**
+ * Map a WGSL binary operator to a `wgsl.*` runtime helper or to a raw JS operator.
+ * Arithmetic must go through wgsl.* so vectors are handled element-wise.
+ */
+const ARITHMETIC_OP = {
+    '+': 'add',
+    '-': 'sub',
+    '*': 'mul',
+    '/': 'div',
+    '%': 'rem',
+};
+
+const RAW_BINARY_OPS = new Set(['<', '>', '<=', '>=', '==', '!=', '&&', '||', '&', '|', '^', '<<', '>>']);
+
+// =========================================================================
+// Compiler context — central state during compilation
+// =========================================================================
+
+class Compiler {
+    constructor() {
+        /** @type {LineBuilder} */
+        this.out = new LineBuilder();
+
+        /** @type {Scope} */
+        this.scope = new Scope();
+
+        /** @type {Map<string, { name: string, fields: Array<{ name: string, type: WgslType }> }>} */
+        this.structs = new Map();
+
+        /** @type {Map<string, { name: string, returnType: WgslType, params: Array<{ name: string, type: WgslType }> }>} */
+        this.functions = new Map();
+
+        /** @type {Array<{ name: string, type: WgslType, group: number, binding: number, addressSpace: string | null, accessMode: string | null }>} */
+        this.globalBindings = [];
+
+        /** @type {Array<{ name: string, type: WgslType }>} */
+        this.workgroupVars = [];
+
+        /**
+         * 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 }>}
+         */
+        this.privateGlobals = [];
+
+        /** @type {{ name: string, params: Array<{ name: string, type: WgslType, builtin: string | null }>, workgroup_size: number[] } | null} */
+        this.entry = null;
+
+        /**
+         * Label of the enclosing `loop` body block when that loop has a `continuing`
+         * block: WGSL `continue` must transfer control INTO the continuing block, so it
+         * is emitted as `break <label>` out of the labeled body block. `null` when the
+         * nearest enclosing loop has no continuing block (plain JS `continue` suffices).
+         * Loop emitters save/clear/restore this around nested loop bodies.
+         * @type {string | null}
+         */
+        this.continue_label = null;
+
+        /**
+         * Monotonic counter used to generate unique loop-body labels.
+         * @type {number}
+         */
+        this.loop_label_counter = 0;
+    }
+
+    error(node, message) {
+        throw new Error(`WGSL compiler: ${message} (at ${node ? node.type : '<unknown>'} : ${node ? JSON.stringify(node.text.slice(0, 60)) : ''})`);
+    }
+}
+
+// =========================================================================
+// Top-level compile entry point
+// =========================================================================
+
+export class WGSLJavaScriptCompiler {
+
+    /**
+     * Compile a tree-sitter WGSL parse tree to a JS source string.
+     *
+     * The output is a JavaScript expression: a function `factory(wgsl)` that returns
+     * 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`.
+     * - **Compute-shader fields (only when a `@compute` entry is present):**
+     *   ```
+     *   {
+     *       entry_name: string,
+     *       workgroup_size: [x, y, z],
+     *       param_names: string[],
+     *       entry: (bindings, workgroup, ...args) => void,
+     *       create_workgroup_state: () => object,
+     *   }
+     *   ```
+     *
+     * Without a `@compute` entry the result is a "library" module — useful for testing
+     * pure WGSL helper code chunks (hashes, packing, math) one function at a time.
+     *
+     * @param {Tree} ast — tree-sitter WGSL AST (returned by `WGSLParser.parse`)
+     * @returns {string}
+     */
+    compile(ast) {
+        const c = new Compiler();
+        compileTranslationUnit(c, ast.rootNode);
+        return c.out.build();
+    }
+}
+
+// =========================================================================
+// Translation unit (root)
+// =========================================================================
+
+/**
+ * @param {Compiler} c
+ * @param {Node} root
+ */
+function compileTranslationUnit(c, root) {
+    assert.equal(root.type, 'translation_unit', 'root must be translation_unit');
+
+    // First pass — collect top-level decls so forward references and global scope resolve.
+    for (const node of root.namedChildren) {
+        switch (node.type) {
+            case 'struct_decl':
+                collectStruct(c, node);
+                break;
+            case 'function_decl':
+                collectFunction(c, node);
+                break;
+            case 'global_variable_decl':
+                collectGlobalVariable(c, node);
+                break;
+            case 'global_value_decl':
+                collectGlobalValue(c, node);
+                break;
+        }
+    }
+
+    // Emit the wrapper: `(wgsl) => { ... }`
+    c.out.add('(wgsl) => {');
+    c.out.indent();
+
+    // 1) Struct classes — must be defined before any user fn that references them or before
+    //    the workgroup state factory (which may need to construct struct instances).
+    for (const node of root.namedChildren) {
+        if (node.type === 'struct_decl') emitStruct(c, node);
+    }
+
+    // 2) Module-scope `let` slots for bindings and workgroup vars. The entry wrapper assigns
+    //    these on each dispatch so that user functions see them via their enclosing closure
+    //    — WGSL functions can read globals freely.
+    for (const b of c.globalBindings) {
+        c.out.add(`let ${b.name} = undefined;`);
+    }
+    for (const wv of c.workgroupVars) {
+        c.out.add(`let ${wv.name} = undefined;`);
+    }
+
+    // 3) Module-scope `var<private>` and `const` declarations.
+    for (const g of c.privateGlobals) {
+        c.out.add(g.code);
+    }
+
+    // 4) User-defined functions (including the @compute entry, if any).
+    for (const node of root.namedChildren) {
+        if (node.type === 'function_decl') emitFunction(c, node);
+    }
+
+    // 5) 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.
+    if (c.entry !== null) {
+        if (c.entry.stage === 'compute') {
+            emitWorkgroupStateFactory(c);
+        }
+        emitEntryWrapper(c);
+    }
+
+    // 6) Build and return the module object.
+    emitModuleReturn(c);
+
+    c.out.dedent();
+    c.out.add('}');
+}
+
+/**
+ * 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.
+ */
+function emitModuleReturn(c) {
+    c.out.add('const __module__ = {};');
+
+    for (const fn_name of c.functions.keys()) {
+        c.out.add(`__module__.${fn_name} = ${fn_name};`);
+    }
+    for (const struct_name of c.structs.keys()) {
+        c.out.add(`__module__.${struct_name} = ${struct_name};`);
+    }
+
+    for (const g of c.privateGlobals) {
+        if (g.kind === 'let') {
+            c.out.add(`Object.defineProperty(__module__, ${JSON.stringify(g.name)}, { get: () => ${g.name}, set: (v) => { ${g.name} = v; } });`);
+        } else {
+            c.out.add(`Object.defineProperty(__module__, ${JSON.stringify(g.name)}, { get: () => ${g.name} });`);
+        }
+    }
+
+    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)};`);
+        c.out.add(`__module__.param_names = [${c.entry.params.map(p => JSON.stringify(p.name)).join(', ')}];`);
+        c.out.add(`__module__.entry = __entry__;`);
+        if (c.entry.stage === 'compute') {
+            c.out.add(`__module__.workgroup_size = [${c.entry.workgroup_size.join(', ')}];`);
+            c.out.add(`__module__.create_workgroup_state = __create_workgroup_state__;`);
+        }
+    }
+
+    c.out.add('return __module__;');
+}
+
+// =========================================================================
+// Struct collection + emission
+// =========================================================================
+
+/**
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function collectStruct(c, node) {
+    const ident = namedChildByType(node, 'ident');
+    const name = ident.text;
+
+    const body = namedChildByType(node, 'struct_body_decl');
+    const members = namedChildrenByType(body, 'struct_member');
+
+    /** @type {Array<{ name: string, type: WgslType }>} */
+    const fields = [];
+
+    for (const m of members) {
+        const member_ident = namedChildByType(m, 'member_ident');
+        const type_spec = namedChildByType(m, 'type_specifier');
+        fields.push({
+            name: member_ident.text,
+            type: parseTypeSpecifier(type_spec),
+        });
+    }
+
+    c.structs.set(name, { name, fields });
+}
+
+/**
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function emitStruct(c, node) {
+    const ident = namedChildByType(node, 'ident');
+    const name = ident.text;
+    const info = c.structs.get(name);
+
+    c.out.add(`class ${name} {`);
+    c.out.indent();
+    c.out.add('constructor() {');
+    c.out.indent();
+    for (const f of info.fields) {
+        c.out.add(`this.${f.name} = ${defaultValueForType(f.type)};`);
+    }
+    c.out.dedent();
+    c.out.add('}');
+    c.out.dedent();
+    c.out.add('}');
+}
+
+/**
+ * Initialiser expression for a fresh value of the given type.
+ * @param {WgslType} type
+ * @returns {string}
+ */
+function defaultValueForType(type) {
+    if (type === undefined || type === null) return 'undefined';
+    switch (type.kind) {
+        case 'primitive':
+            return type.name === 'bool' ? 'false' : '0';
+        case 'vec':
+            return `wgsl.${vecAliasName(type.size, type.scalar)}()`;
+        case 'mat':
+            return `new Float32Array(${type.cols * type.rows})`;
+        case 'array': {
+            if (type.count > 0) {
+                if (type.element.kind === 'primitive') {
+                    const ctor = arrayCtorForScalar(type.element.name);
+                    return `new ${ctor}(${type.count})`;
+                }
+                // For non-primitive elements (vec / mat / struct / nested array) build the
+                // array eagerly so `out[i]` is a fresh, mutable element rather than `undefined`.
+                return `Array.from({ length: ${type.count} }, () => ${defaultValueForType(type.element)})`;
+            }
+            return '[]';
+        }
+        case 'struct':
+            return `new ${type.name}()`;
+        case 'atomic':
+            return '{ value: 0 }';
+        default:
+            return 'undefined';
+    }
+}
+
+function arrayCtorForScalar(name) {
+    switch (name) {
+        case 'f32':
+            return 'Float32Array';
+        case 'f16':
+            return 'Float16Array';
+        case 'i32':
+            return 'Int32Array';
+        case 'u32':
+            return 'Uint32Array';
+        default:
+            return 'Array';
+    }
+}
+
+// =========================================================================
+// Function collection + emission
+// =========================================================================
+
+/**
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function collectFunction(c, node) {
+    const header = namedChildByType(node, 'function_header');
+    const ident = namedChildByType(header, 'ident');
+    const name = ident.text;
+
+    const param_list_node = namedChildByType(header, 'param_list');
+    /** @type {Array<{ name: string, type: WgslType, builtin: string | null }>} */
+    const params = [];
+    if (param_list_node !== null) {
+        const param_nodes = namedChildrenByType(param_list_node, 'param');
+        for (const p of param_nodes) {
+            const p_ident = namedChildByType(p, 'ident');
+            const p_type = namedChildByType(p, 'type_specifier');
+            const builtin = extractBuiltin(p);
+            params.push({
+                name: p_ident.text,
+                type: parseTypeSpecifier(p_type),
+                builtin,
+            });
+        }
+    }
+
+    // Optional return type — `template_elaborated_ident` directly under the header.
+    let returnType = T_UNKNOWN;
+    for (const child of header.namedChildren) {
+        if (child.type === 'template_elaborated_ident') {
+            returnType = parseTypeSpecifier(child);
+        }
+    }
+
+    c.functions.set(name, { name, returnType, params: params.map(p => ({ name: p.name, type: p.type })) });
+
+    // Detect the entry attribute (@compute, @fragment, or @vertex) and capture stage-specific
+    // metadata. The emulator supports compute and fragment entries; vertex is rejected because
+    // ImageShader testing in the emulator skips the vertex phase intentionally.
+    const attrs = namedChildrenByType(node, 'attribute');
+    let stage = null;
+    let workgroup_size = [1, 1, 1];
+    for (const a of attrs) {
+        const inner = a.namedChildren[0];
+        if (inner.type === 'compute_attr') {
+            stage = 'compute';
+        } else if (inner.type === 'fragment_attr') {
+            stage = 'fragment';
+        } else if (inner.type === 'vertex_attr') {
+            throw new Error(`WGSL compiler: @vertex stage is not supported by the emulator (function '${name}'). For ImageShader testing the vertex phase is skipped — invoke the @fragment entry directly.`);
+        } else if (inner.type === 'workgroup_size_attr') {
+            const sizes = namedChildrenByType(inner, 'expression').map(e => parseInt(e.text.trim()) | 0);
+            for (let i = 0; i < sizes.length && i < 3; i++) {
+                workgroup_size[i] = sizes[i];
+            }
+        }
+    }
+
+    if (stage !== null) {
+        if (c.entry !== null) {
+            throw new Error(`WGSL compiler: multiple @${stage} entry functions found ('${c.entry.name}' and '${name}')`);
+        }
+        c.entry = { name, params, stage, workgroup_size };
+    }
+}
+
+/**
+ * Pull the `@builtin(name)` attribute name from a function param node, if present.
+ */
+function extractBuiltin(param_node) {
+    for (const a of namedChildrenByType(param_node, 'attribute')) {
+        const inner = a.namedChildren[0];
+        if (inner.type === 'builtin_attr') {
+            const name_node = namedChildByType(inner, 'builtin_value_name');
+            if (name_node !== null) return name_node.text;
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function emitFunction(c, node) {
+    const header = namedChildByType(node, 'function_header');
+    const ident = namedChildByType(header, 'ident');
+    const name = ident.text;
+    const info = c.functions.get(name);
+
+    const param_list_node = namedChildByType(header, 'param_list');
+    const param_nodes = param_list_node !== null ? namedChildrenByType(param_list_node, 'param') : [];
+
+    const param_names = param_nodes.map(p => namedChildByType(p, 'ident').text);
+
+    c.out.add(`function ${name}(${param_names.join(', ')}) {`);
+    c.out.indent();
+
+    c.scope = c.scope.push();
+    for (let i = 0; i < param_nodes.length; i++) {
+        c.scope.declare(param_names[i], info.params[i].type);
+    }
+
+    const body = namedChildByType(node, 'compound_statement');
+    emitCompoundStatementBody(c, body);
+
+    c.scope = c.scope.parent;
+
+    c.out.dedent();
+    c.out.add('}');
+}
+
+// =========================================================================
+// Globals — bindings, workgroup vars, private/const
+// =========================================================================
+
+/**
+ * Inspect a `global_variable_decl` and record its metadata.
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function collectGlobalVariable(c, node) {
+    const var_decl = namedChildByType(node, 'variable_decl');
+    if (var_decl === null) {
+        collectGlobalValue(c, node);
+        return;
+    }
+
+    const template = namedChildByType(var_decl, 'template_list');
+    const opt_ident = namedChildByType(var_decl, 'optionally_typed_ident');
+    const var_ident = namedChildByType(opt_ident, 'ident');
+    const type_spec = namedChildByType(opt_ident, 'type_specifier');
+    const name = var_ident.text;
+    const type = parseTypeSpecifier(type_spec);
+
+    let address_space = null;
+    let access_mode = null;
+    if (template !== null) {
+        const args = extractTemplateArgs(template);
+        address_space = args[0] || null;
+        access_mode = args[1] || null;
+    }
+
+    let group = null;
+    let binding = null;
+    for (const a of namedChildrenByType(node, 'attribute')) {
+        const inner = a.namedChildren[0];
+        if (inner.type === 'group_attr') {
+            const expr = namedChildByType(inner, 'expression');
+            group = parseInt(expr.text.trim());
+        } else if (inner.type === 'binding_attr') {
+            const expr = namedChildByType(inner, 'expression');
+            binding = parseInt(expr.text.trim());
+        }
+    }
+
+    c.scope.declare(name, type);
+
+    if (group !== null && binding !== null) {
+        c.globalBindings.push({
+            name, type, group, binding, addressSpace: address_space, accessMode: access_mode,
+        });
+        return;
+    }
+
+    if (address_space === 'workgroup') {
+        c.workgroupVars.push({ name, type });
+        return;
+    }
+
+    // Private / module-scope `var<private>`. If the WGSL has an explicit initializer
+    // (e.g. `var<private> rnd_state: u32 = 2891336453u`), use it; otherwise fall back
+    // to the type's default value.
+    const initializer_node = namedChildByType(node, 'expression');
+    const init_code = initializer_node !== null
+        ? compileExpression(c, initializer_node).code
+        : defaultValueForType(type);
+    c.privateGlobals.push({
+        name,
+        kind: 'let',
+        code: `let ${name} = ${init_code};`,
+    });
+}
+
+/**
+ * Inspect a `global_value_decl` (`const x = …;` / `let x = …;` at module scope) and record it.
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function collectGlobalValue(c, node) {
+    let ident = null;
+    let value_node = null;
+    let type_node = null;
+    for (const child of node.namedChildren) {
+        if (child.type === 'optionally_typed_ident') {
+            ident = namedChildByType(child, 'ident');
+            type_node = namedChildByType(child, 'type_specifier');
+        } else if (child.type === 'expression') {
+            value_node = child;
+        }
+    }
+    if (ident === null || value_node === null) return;
+    const name = ident.text;
+    let type = type_node !== null ? parseTypeSpecifier(type_node) : T_UNKNOWN;
+
+    const expr = compileExpression(c, value_node);
+
+    // Infer the type from the RHS when there's no explicit annotation (mirrors the local
+    // `let`/`var` path). Without this a `const M = mat3x3<f32>(...)` is left T_UNKNOWN, so a
+    // later `M * v` can't tell M is a matrix and emits a vector multiply → length mismatch.
+    if (type === T_UNKNOWN || type.kind === 'unknown') {
+        type = expr.type;
+    }
+
+    c.scope.declare(name, type);
+    c.privateGlobals.push({
+        name,
+        kind: 'const',
+        code: `const ${name} = ${expr.code};`,
+    });
+}
+
+// =========================================================================
+// Workgroup state factory + entry wrapper
+// =========================================================================
+
+function emitWorkgroupStateFactory(c) {
+    c.out.add('function __create_workgroup_state__() {');
+    c.out.indent();
+    c.out.add('return {');
+    c.out.indent();
+    for (const wv of c.workgroupVars) {
+        c.out.add(`${wv.name}: ${defaultValueForType(wv.type)},`);
+    }
+    c.out.dedent();
+    c.out.add('};');
+    c.out.dedent();
+    c.out.add('}');
+}
+
+function emitEntryWrapper(c) {
+    const param_names = c.entry.params.map(p => p.name);
+    const is_compute = c.entry.stage === 'compute';
+    // Compute entries take a per-dispatch workgroup-state object; fragment entries don't have
+    // var<workgroup> at all, so the wrapper signature drops it.
+    const fixed_args = is_compute ? '__bindings__, __workgroup__' : '__bindings__';
+    const all_args = param_names.length > 0 ? `${fixed_args}, ${param_names.join(', ')}` : fixed_args;
+
+    c.out.add(`function __entry__(${all_args}) {`);
+    c.out.indent();
+
+    // Refresh each module-scope binding/workgroup slot before invoking the user's main.
+    // User functions read these via their enclosing closure, so this assignment makes the
+    // current dispatch's bindings visible to every helper they may call.
+    for (const b of c.globalBindings) {
+        c.out.add(`${b.name} = __bindings__.${b.name};`);
+    }
+    if (is_compute) {
+        for (const wv of c.workgroupVars) {
+            c.out.add(`${wv.name} = __workgroup__.${wv.name};`);
+        }
+    }
+
+    c.out.add(`return ${c.entry.name}(${param_names.join(', ')});`);
+
+    c.out.dedent();
+    c.out.add('}');
+}
+
+// =========================================================================
+// Statements
+// =========================================================================
+
+/**
+ * Emit only the inside of a compound_statement (no `{` / `}`).
+ * @param {Compiler} c
+ * @param {Node} node — `compound_statement`
+ */
+function emitCompoundStatementBody(c, node) {
+    for (const child of node.namedChildren) {
+        if (child.type === 'statement') {
+            emitStatement(c, child);
+        }
+    }
+}
+
+function emitCompoundStatement(c, node) {
+    c.out.add('{');
+    c.out.indent();
+    c.scope = c.scope.push();
+    emitCompoundStatementBody(c, node);
+    c.scope = c.scope.parent;
+    c.out.dedent();
+    c.out.add('}');
+}
+
+/**
+ * Emit a single `statement` node (its child is the actual statement kind).
+ * @param {Compiler} c
+ * @param {Node} node
+ */
+function emitStatement(c, node) {
+    const inner = node.namedChildren[0];
+    switch (inner.type) {
+        case 'variable_or_value_statement':
+            emitVariableOrValueStatement(c, inner);
+            break;
+        case 'variable_updating_statement':
+            emitVariableUpdatingStatement(c, inner);
+            break;
+        case 'return_statement':
+            emitReturnStatement(c, inner);
+            break;
+        case 'if_statement':
+            emitIfStatement(c, inner);
+            break;
+        case 'for_statement':
+            emitForStatement(c, inner);
+            break;
+        case 'while_statement':
+            emitWhileStatement(c, inner);
+            break;
+        case 'loop_statement':
+            emitLoopStatement(c, inner);
+            break;
+        case 'switch_statement':
+            emitSwitchStatement(c, inner);
+            break;
+        case 'break_statement':
+            c.out.add('break;');
+            break;
+        case 'continue_statement':
+            // Inside a `loop` with a `continuing` block, `continue` must run the
+            // continuing block: it is emitted as a break out of the labeled body block
+            // (the continuing code follows that block inside the same `while`).
+            if (c.continue_label !== null) {
+                c.out.add(`break ${c.continue_label};`);
+            } else {
+                c.out.add('continue;');
+            }
+            break;
+        case 'discard_statement':
+            c.out.add('return;');
+            break;
+        case 'compound_statement':
+            emitCompoundStatement(c, inner);
+            break;
+        case 'func_call_statement':
+            emitFunctionCallStatement(c, inner);
+            break;
+        case 'const_assert_statement':
+            // Skipped at runtime.
+            break;
+        default:
+            c.error(inner, `unsupported statement: ${inner.type}`);
+    }
+}
+
+/**
+ * `let x = expr;` or `var x: T = expr;` or `var x: T;`
+ */
+function emitVariableOrValueStatement(c, node) {
+    const var_decl = namedChildByType(node, 'variable_decl');
+    const opt_ident_direct = namedChildByType(node, 'optionally_typed_ident');
+    const expr_node = namedChildByType(node, 'expression');
+
+    /** @type {'let' | 'const'} */
+    let kind = 'let';
+    let opt_ident = null;
+    let template = null;
+
+    if (var_decl !== null) {
+        // WGSL `var` is the mutable form → JS `let`.
+        kind = 'let';
+        opt_ident = namedChildByType(var_decl, 'optionally_typed_ident');
+        template = namedChildByType(var_decl, 'template_list');
+    } else {
+        // WGSL `let` and `const` are both immutable bindings → JS `const`.
+        // Tree-sitter exposes the keyword as an unnamed leading token; read it from the source.
+        kind = 'const';
+        opt_ident = opt_ident_direct;
+    }
+
+    const ident = namedChildByType(opt_ident, 'ident');
+    const type_spec = namedChildByType(opt_ident, 'type_specifier');
+    const name = ident.text;
+    let type = type_spec !== null ? parseTypeSpecifier(type_spec) : T_UNKNOWN;
+
+    if (expr_node !== null) {
+        const expr = compileExpression(c, expr_node);
+        // Infer the type from the RHS when no explicit annotation is present.
+        if (type === T_UNKNOWN || type.kind === 'unknown') {
+            type = expr.type;
+        }
+        c.scope.declare(name, type);
+        c.out.add(`${kind} ${name} = ${expr.code};`);
+    } else {
+        c.scope.declare(name, type);
+        c.out.add(`${kind} ${name} = ${defaultValueForType(type)};`);
+    }
+}
+
+/**
+ * Assignment / compound assignment / increment / decrement.
+ */
+function emitVariableUpdatingStatement(c, node) {
+    const inner = node.namedChildren[0];
+    if (inner.type === 'assignment_statement') {
+        const lhs = namedChildByType(inner, 'lhs_expression');
+        const expr = namedChildByType(inner, 'expression');
+
+        // The compound assignment operator sits between the LHS and the RHS as an unnamed token.
+        const op_text = textBetween(inner, lhs, expr).trim();
+
+        const lhs_compiled = compileLhs(c, lhs);
+        const rhs_compiled = compileExpression(c, expr);
+
+        if (op_text === '=' || op_text === '') {
+            c.out.add(emitWriteStatement(lhs_compiled, rhs_compiled.code));
+            return;
+        }
+
+        const arith = {
+            '+=': 'add', '-=': 'sub', '*=': 'mul', '/=': 'div', '%=': 'rem',
+        };
+        if (arith.hasOwnProperty(op_text)) {
+            c.out.add(emitWriteStatement(lhs_compiled, `wgsl.${arith[op_text]}(${lhs_compiled.code}, ${rhs_compiled.code})`));
+            return;
+        }
+        c.out.add(`${lhs_compiled.code} ${op_text} ${rhs_compiled.code};`);
+        return;
+    }
+    if (inner.type === 'increment_statement') {
+        const lhs = namedChildByType(inner, 'lhs_expression');
+        const lhs_compiled = compileLhs(c, lhs);
+        c.out.add(emitWriteStatement(lhs_compiled, `wgsl.add(${lhs_compiled.code}, 1)`));
+        return;
+    }
+    if (inner.type === 'decrement_statement') {
+        const lhs = namedChildByType(inner, 'lhs_expression');
+        const lhs_compiled = compileLhs(c, lhs);
+        c.out.add(emitWriteStatement(lhs_compiled, `wgsl.sub(${lhs_compiled.code}, 1)`));
+        return;
+    }
+    c.error(inner, `unsupported variable_updating_statement: ${inner.type}`);
+}
+
+/**
+ * Emit a write to an LHS. Most LHS expressions are plain JS LValues (`x`, `arr[i]`, `obj.f`) and
+ * are written with `=`. Mat-column LHS — `m[i]` for a mat — is special: the compiler emits it as
+ * `wgsl.mat_col(m, i, rows)`, which is a typed-array view (a function call result, not assignable).
+ * To write through the view we use `Float32Array.prototype.set(rhs)` instead, which copies into
+ * the underlying matrix storage in place.
+ *
+ * @param {{ code: string }} lhs_compiled
+ * @param {string} rhs_code
+ * @returns {string}
+ */
+function emitWriteStatement(lhs_compiled, rhs_code) {
+    // Only the bare `wgsl.mat_col(...)` form (no chained `[i]` / `.x`) needs `.set()` — that's a
+    // typed-array view, an unassignable function-call result. Anything chained off it (e.g.
+    // `wgsl.mat_col(...)[3]` or `wgsl.mat_col(...).x` becoming `[i]`) is a scalar slot and must
+    // use plain `=`.
+    if (lhs_compiled.code.startsWith('wgsl.mat_col(') && lhs_compiled.code.endsWith(')')) {
+        return `${lhs_compiled.code}.set(${rhs_code});`;
+    }
+    return `${lhs_compiled.code} = ${rhs_code};`;
+}
+
+function emitReturnStatement(c, node) {
+    const expr = namedChildByType(node, 'expression');
+    if (expr === null) {
+        c.out.add('return;');
+    } else {
+        const e = compileExpression(c, expr);
+        c.out.add(`return ${e.code};`);
+    }
+}
+
+function emitIfStatement(c, node) {
+    const if_clause = namedChildByType(node, 'if_clause');
+    const cond = namedChildByType(if_clause, 'expression');
+    const if_body = namedChildByType(if_clause, 'compound_statement');
+
+    const cond_compiled = compileExpression(c, cond);
+    c.out.add(`if (${cond_compiled.code}) {`);
+    c.out.indent();
+    c.scope = c.scope.push();
+    emitCompoundStatementBody(c, if_body);
+    c.scope = c.scope.parent;
+    c.out.dedent();
+    c.out.add('}');
+
+    // else-if and else clauses.
+    for (const child of node.namedChildren) {
+        if (child.type === 'else_if_clause') {
+            const eif_cond = namedChildByType(child, 'expression');
+            const eif_body = namedChildByType(child, 'compound_statement');
+            const eif_compiled = compileExpression(c, eif_cond);
+            c.out.add(`else if (${eif_compiled.code}) {`);
+            c.out.indent();
+            c.scope = c.scope.push();
+            emitCompoundStatementBody(c, eif_body);
+            c.scope = c.scope.parent;
+            c.out.dedent();
+            c.out.add('}');
+        } else if (child.type === 'else_clause') {
+            const else_body = namedChildByType(child, 'compound_statement');
+            // else_body may instead be an if_statement (else-if shorthand).
+            const nested_if = namedChildByType(child, 'if_statement');
+            if (else_body !== null) {
+                c.out.add('else {');
+                c.out.indent();
+                c.scope = c.scope.push();
+                emitCompoundStatementBody(c, else_body);
+                c.scope = c.scope.parent;
+                c.out.dedent();
+                c.out.add('}');
+            } else if (nested_if !== null) {
+                c.out.add('else');
+                emitIfStatement(c, nested_if);
+            }
+        }
+    }
+}
+
+function emitForStatement(c, node) {
+    const for_header = namedChildByType(node, 'for_header');
+    const for_init = namedChildByType(for_header, 'for_init');
+    const cond_expr = namedChildByType(for_header, 'expression');
+    const for_update = namedChildByType(for_header, 'for_update');
+    const body = namedChildByType(node, 'compound_statement');
+
+    c.scope = c.scope.push();
+
+    // Init / cond / update parts.
+    let init_str = '';
+    if (for_init !== null) {
+        // Tree-sitter wraps it in a variable_or_value_statement; capture the emission as text.
+        const sub = new Compiler();
+        sub.scope = c.scope;
+        sub.structs = c.structs;
+        sub.functions = c.functions;
+        const inner = for_init.namedChildren[0];
+        emitForInitInline(sub, inner);
+        init_str = sub.out.build().trimEnd();
+        if (init_str.endsWith(';')) init_str = init_str.slice(0, -1);
+    }
+
+    const cond_str = cond_expr !== null ? compileExpression(c, cond_expr).code : '';
+
+    let update_str = '';
+    if (for_update !== null) {
+        const inner = for_update.namedChildren[0];
+        update_str = emitForUpdateInline(c, inner);
+    }
+
+    c.out.add(`for (${init_str}; ${cond_str}; ${update_str}) {`);
+    c.out.indent();
+    // `continue` inside this loop targets this loop, not an outer `loop`'s continuing block
+    const saved_continue_label = c.continue_label;
+    c.continue_label = null;
+    emitCompoundStatementBody(c, body);
+    c.continue_label = saved_continue_label;
+    c.out.dedent();
+    c.out.add('}');
+
+    c.scope = c.scope.parent;
+}
+
+/**
+ * Emit a `variable_or_value_statement` inline (as a single line with no trailing newline structure).
+ * Used by `for(init; ...)`.
+ */
+function emitForInitInline(c, node) {
+    if (node.type === 'variable_or_value_statement') {
+        const var_decl = node.namedChildren[0] && node.namedChildren[0].type === 'variable_decl'
+            ? node.namedChildren[0]
+            : null;
+        const opt_ident = namedChildByType(var_decl !== null ? var_decl : node, 'optionally_typed_ident');
+        const expr_node = namedChildByType(node, 'expression');
+        const ident = namedChildByType(opt_ident, 'ident');
+        const type_spec = namedChildByType(opt_ident, 'type_specifier');
+        const name = ident.text;
+        const type = type_spec !== null ? parseTypeSpecifier(type_spec) : T_UNKNOWN;
+        c.scope.declare(name, type);
+        const value = expr_node !== null ? compileExpression(c, expr_node).code : defaultValueForType(type);
+        // `var i = …` (mutable, common in `for (var i = 0; ...; i = i + 1)`) → JS `let`.
+        // `let i = …` / `const i = …` (immutable) → JS `const`.
+        const kind = var_decl !== null ? 'let' : 'const';
+        c.out.add(`${kind} ${name} = ${value};`);
+        return;
+    }
+    if (node.type === 'variable_updating_statement') {
+        emitVariableUpdatingStatement(c, node);
+        return;
+    }
+    if (node.type === 'func_call_statement') {
+        emitFunctionCallStatement(c, node);
+        return;
+    }
+}
+
+/**
+ * @returns {string} JS update expression (no semicolon).
+ */
+function emitForUpdateInline(c, node) {
+    if (node.type === 'variable_updating_statement') {
+        const inner = node.namedChildren[0];
+        if (inner.type === 'assignment_statement') {
+            const lhs = namedChildByType(inner, 'lhs_expression');
+            const expr = namedChildByType(inner, 'expression');
+            const op_text = textBetween(inner, lhs, expr).trim();
+            const lhs_compiled = compileLhs(c, lhs);
+            const rhs_compiled = compileExpression(c, expr);
+            if (op_text === '=' || op_text === '') {
+                return `${lhs_compiled.code} = ${rhs_compiled.code}`;
+            }
+            const arith = { '+=': 'add', '-=': 'sub', '*=': 'mul', '/=': 'div', '%=': 'rem' };
+            if (arith.hasOwnProperty(op_text)) {
+                return `${lhs_compiled.code} = wgsl.${arith[op_text]}(${lhs_compiled.code}, ${rhs_compiled.code})`;
+            }
+            return `${lhs_compiled.code} ${op_text} ${rhs_compiled.code}`;
+        }
+        if (inner.type === 'increment_statement') {
+            const lhs = namedChildByType(inner, 'lhs_expression');
+            const lhs_compiled = compileLhs(c, lhs);
+            return `${lhs_compiled.code} = wgsl.add(${lhs_compiled.code}, 1)`;
+        }
+        if (inner.type === 'decrement_statement') {
+            const lhs = namedChildByType(inner, 'lhs_expression');
+            const lhs_compiled = compileLhs(c, lhs);
+            return `${lhs_compiled.code} = wgsl.sub(${lhs_compiled.code}, 1)`;
+        }
+    }
+    return '';
+}
+
+function emitWhileStatement(c, node) {
+    const cond = namedChildByType(node, 'expression');
+    const body = namedChildByType(node, 'compound_statement');
+    const cc = compileExpression(c, cond);
+    c.out.add(`while (${cc.code}) {`);
+    c.out.indent();
+    c.scope = c.scope.push();
+    // `continue` inside this loop targets this loop, not an outer `loop`'s continuing block
+    const saved_continue_label = c.continue_label;
+    c.continue_label = null;
+    emitCompoundStatementBody(c, body);
+    c.continue_label = saved_continue_label;
+    c.scope = c.scope.parent;
+    c.out.dedent();
+    c.out.add('}');
+}
+
+function emitLoopStatement(c, node) {
+    // NOTE: the grammar puts the loop's `statement` children and the optional
+    // `continuing_statement` directly on the `loop_statement` node (no
+    // `compound_statement` wrapper); emitCompoundStatementBody visits only the
+    // `statement` children, which is exactly the loop body.
+    const body = node;
+    const continuing = namedChildByType(node, 'continuing_statement');
+
+    const saved_continue_label = c.continue_label;
+
+    c.out.add('while (true) {');
+    c.out.indent();
+    c.scope = c.scope.push();
+
+    if (continuing === null) {
+
+        // no continuing block: JS `continue` already has the right semantics
+        c.continue_label = null;
+        emitCompoundStatementBody(c, body);
+
+    } else {
+
+        // WGSL `continue` transfers control INTO the `continuing` block. Emit the loop
+        // body inside a labeled block: `continue` becomes `break <label>`, which lands on
+        // the continuing code that follows the block (still inside the `while`).
+        const label = `loop_body_${c.loop_label_counter++}`;
+        c.continue_label = label;
+
+        c.out.add(`${label}: {`);
+        c.out.indent();
+        emitCompoundStatementBody(c, body);
+        c.out.dedent();
+        c.out.add('}');
+
+        c.continue_label = null;
+
+        const cont_body = namedChildByType(continuing, 'continuing_compound_statement');
+        if (cont_body !== null) {
+            emitCompoundStatementBody(c, cont_body);
+
+            // `break if expr;` — only legal as the trailing statement of a continuing block.
+            // It is a direct named child of the continuing compound (not wrapped in `statement`),
+            // so emitCompoundStatementBody does not visit it.
+            const break_if = namedChildByType(cont_body, 'break_if_statement');
+            if (break_if !== null) {
+                const break_expr = namedChildByType(break_if, 'expression');
+                const bc = compileExpression(c, break_expr);
+                c.out.add(`if (${bc.code}) { break; }`);
+            }
+        }
+
+    }
+
+    c.continue_label = saved_continue_label;
+    c.scope = c.scope.parent;
+    c.out.dedent();
+    c.out.add('}');
+}
+
+/**
+ * Emit a WGSL `switch`.
+ *
+ * Grammar (tree-sitter-wgsl): `switch_statement { expression, switch_body { switch_clause* } }`,
+ * where each `switch_clause` wraps either a `case_clause { case_selectors { case_selector+ },
+ * compound_statement }` or a `default_alone_clause { compound_statement }`. A `case_selector` holds
+ * either an `expression` (a case value) or the `default` keyword.
+ *
+ * WGSL switch has no fall-through — each selected clause runs its body and stops — so we terminate
+ * every clause body with `break;`. Multiple selectors on one clause become stacked JS `case` labels
+ * over a shared body.
+ */
+function emitSwitchStatement(c, node) {
+    const expr = namedChildByType(node, 'expression');
+    const ec = compileExpression(c, expr);
+    c.out.add(`switch (${ec.code}) {`);
+    c.out.indent();
+
+    const body = namedChildByType(node, 'switch_body');
+    if (body) {
+        for (const clause of namedChildrenByType(body, 'switch_clause')) {
+            const case_clause = namedChildByType(clause, 'case_clause');
+            const default_clause = namedChildByType(clause, 'default_alone_clause');
+            const inner = case_clause ?? default_clause;
+            if (!inner) {
+                continue;
+            }
+
+            if (case_clause) {
+                const case_selectors = namedChildByType(case_clause, 'case_selectors');
+                if (case_selectors) {
+                    for (const sel of namedChildrenByType(case_selectors, 'case_selector')) {
+                        const sel_expr = namedChildByType(sel, 'expression');
+                        if (sel_expr) {
+                            c.out.add(`case ${compileExpression(c, sel_expr).code}:`);
+                        } else {
+                            // a bare `default` used within a case_selectors list
+                            c.out.add('default:');
+                        }
+                    }
+                }
+            } else {
+                c.out.add('default:');
+            }
+
+            // Wrap each clause body in its own JS block. WGSL case clauses are independent scopes,
+            // but JS switch clauses share the switch's block scope — without the braces, `let`
+            // temporaries declared in two clauses collide ("Identifier already declared").
+            const case_body = namedChildByType(inner, 'compound_statement');
+            c.out.add('{');
+            c.out.indent();
+            c.scope = c.scope.push();
+            if (case_body) {
+                emitCompoundStatementBody(c, case_body);
+            }
+            c.out.add('break;');
+            c.scope = c.scope.parent;
+            c.out.dedent();
+            c.out.add('}');
+        }
+    }
+
+    c.out.dedent();
+    c.out.add('}');
+}
+
+function emitFunctionCallStatement(c, node) {
+    const call_phrase = namedChildByType(node, 'call_phrase');
+    const r = compileCallPhraseTyped(c, call_phrase);
+    c.out.add(`${r.code};`);
+}
+
+// =========================================================================
+// Expressions
+// =========================================================================
+
+/**
+ * Compile an expression node (any wrapper or specific kind).
+ * @param {Compiler} c
+ * @param {Node} node
+ * @returns {{ code: string, type: WgslType }}
+ */
+function compileExpression(c, node) {
+    const u = unwrapExpression(node);
+
+    // Binary operations
+    switch (u.type) {
+        case 'expression':
+            // tree-sitter-wgsl can leave `&&` / `||` directly under an `expression` node — i.e.
+            // the operator wraps two operands without a more specific short_circuit_*_expression
+            // wrapper around it. With 2 named children the unnamed operator sits between them.
+            return compileBinaryExpression(c, u, '__shortcircuit_unused__', 'raw');
+        case 'relational_expression':
+            return compileBinaryExpression(c, u, 'relational_operator', 'raw');
+        case 'shift_expression':
+            return compileBinaryExpression(c, u, 'shift_operator', 'raw');
+        case 'additive_expression':
+            return compileBinaryExpression(c, u, 'additive_operator', 'arith');
+        case 'multiplicative_expression':
+            return compileBinaryExpression(c, u, 'multiplicative_operator', 'arith');
+        case 'short_circuit_and_expression':
+        case 'short_circuit_or_expression':
+            return compileBinaryExpression(c, u, '__shortcircuit_unused__', 'raw');
+        case 'bitwise_expression':
+            // Top-level WGSL `^` / `&` / `|` operator. The operator is an unnamed token between
+            // the two named operands; compileBinaryExpression's 2-named-children path picks it up.
+            return compileBinaryExpression(c, u, '__bitwise_unused__', 'raw');
+        case 'binary_and_expression':
+        case 'binary_or_expression':
+        case 'binary_xor_expression':
+            // Inner chain nodes from the WGSL grammar (e.g. `a ^ b ^ c` nests as
+            // `binary_xor_expression(binary_xor_expression(a, b), c)`). When 2 named children
+            // appear, the unnamed operator sits between them; the 1-child case is a passthrough.
+            return compileBinaryExpression(c, u, '__bitwise_unused__', 'raw');
+    }
+
+    // Unary
+    if (u.type === 'unary_expression') {
+        return compileUnaryExpression(c, u);
+    }
+
+    // Singular (primary + chained component access)
+    if (u.type === 'singular_expression') {
+        return compileSingularExpression(c, u);
+    }
+
+    // Primary subkinds
+    if (u.type === 'literal' || u.type === 'int_literal' || u.type === 'float_literal' || u.type === 'bool_literal') {
+        return { code: literalToJs(u.text), type: T_UNKNOWN };
+    }
+    if (u.type === 'paren_expression') {
+        const inner = namedChildByType(u, 'expression');
+        const e = compileExpression(c, inner);
+        return { code: `(${e.code})`, type: e.type };
+    }
+    if (u.type === 'call_expression') {
+        const call_phrase = namedChildByType(u, 'call_phrase');
+        return compileCallPhraseTyped(c, call_phrase);
+    }
+    if (u.type === 'template_elaborated_ident') {
+        const ident = namedChildByType(u, 'ident');
+        const name = ident !== null ? ident.text : u.text;
+        return { code: name, type: c.scope.lookup(name) };
+    }
+    if (u.type === 'ident') {
+        return { code: u.text, type: c.scope.lookup(u.text) };
+    }
+
+    c.error(u, `unsupported expression: ${u.type}`);
+}
+
+/**
+ * Compile a binary expression node. Two grammar shapes are supported:
+ * - 3 named children where the middle child has type `op_type` — used for additive / multiplicative
+ *   where the operator is an explicit named node (`additive_operator`, `multiplicative_operator`).
+ * - 2 named children with an unnamed operator token between them — used for relational / shift,
+ *   where the operator (e.g. `<`, `>=`, `<<`) is a raw token.
+ *
+ * Mode:
+ *   - `'arith'` → use `wgsl.add/sub/mul/div/rem` (handles vectors)
+ *   - `'raw'`   → emit raw JS operator
+ */
+function compileBinaryExpression(c, node, op_type, mode) {
+    const named = node.namedChildren;
+    if (named.length === 1) {
+        return compileExpression(c, named[0]);
+    }
+
+    let op_text = null;
+    let left_node;
+    let right_node;
+
+    if (named.length === 3 && named[1].type === op_type) {
+        op_text = named[1].text;
+        left_node = named[0];
+        right_node = named[2];
+    } else if (named.length === 2) {
+        left_node = named[0];
+        right_node = named[1];
+        // tree-sitter-web doesn't surface unnamed children in `node.children`. Extract the
+        // operator by slicing the original text using the operands' source positions.
+        op_text = textBetween(node, left_node, right_node).trim();
+    } else {
+        return { code: node.text, type: T_UNKNOWN };
+    }
+
+    const left = compileExpression(c, left_node);
+    const right = compileExpression(c, right_node);
+
+    if (mode === 'arith') {
+        const helper = ARITHMETIC_OP[op_text];
+        if (helper !== undefined) {
+            // `*` on matrix/vector operands has WGSL-specific algebra (dot-products and
+            // accumulation) that the element-wise `wgsl.mul` doesn't capture. Route to a
+            // dedicated `mNxR_multiply_*` helper when at least one side is a matrix.
+            if (op_text === '*') {
+                const dispatched = dispatchMatrixMul(left, right);
+                if (dispatched !== null) return dispatched;
+            }
+            // WGSL `/` on integer types is truncated integer division. Detect when both
+            // operands' tracked types are integer (i32 / u32 scalars or matching int vecs)
+            // and route through the integer-truncating helper; otherwise use float div.
+            let actual_helper = helper;
+            if (op_text === '/' && bothOperandsInteger(left.type, right.type)) {
+                actual_helper = 'idiv';
+            }
+            return {
+                code: `wgsl.${actual_helper}(${left.code}, ${right.code})`,
+                type: inferBinaryArithResultType(left.type, right.type),
+            };
+        }
+    }
+
+    // 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.
+    const bitwise_helper = BITWISE_HELPER[op_text];
+    if (bitwise_helper !== undefined) {
+        if (isContainerType(left.type) || isContainerType(right.type)) {
+            return {
+                code: `wgsl.${bitwise_helper}(${left.code}, ${right.code})`,
+                type: inferRawBinaryResultType(left.type, right.type, op_text),
+            };
+        }
+        // For `>>` specifically: any u32-typed scalar operand must use the unsigned shift helper.
+        if (op_text === '>>' && (isScalarUnsigned(left.type) || isScalarUnsigned(right.type))) {
+            return {
+                code: `wgsl.shr(${left.code}, ${right.code})`,
+                type: inferRawBinaryResultType(left.type, right.type, op_text),
+            };
+        }
+    }
+
+    // Comparison operators. JS's raw `==` etc. compare TypedArrays by reference; for WGSL
+    // `vec<T>` operands we need element-wise comparison returning a `vec<bool>`.
+    const cmp_helper = COMPARISON_HELPER[op_text];
+    if (cmp_helper !== undefined && (isContainerType(left.type) || isContainerType(right.type))) {
+        return {
+            code: `wgsl.${cmp_helper}(${left.code}, ${right.code})`,
+            type: inferRawBinaryResultType(left.type, right.type, op_text),
+        };
+    }
+
+    return {
+        code: `${left.code} ${op_text} ${right.code}`,
+        type: inferRawBinaryResultType(left.type, right.type, op_text),
+    };
+}
+
+/** Map WGSL bitwise/shift operators to language-core element-wise helper names. */
+const BITWISE_HELPER = {
+    '&': 'bit_and',
+    '|': 'bit_or',
+    '^': 'bit_xor',
+    '<<': 'shl',
+    '>>': 'shr',
+};
+
+/** Map WGSL comparison operators to language-core element-wise helper names. */
+const COMPARISON_HELPER = {
+    '==': 'eq',
+    '!=': 'ne',
+    '<': 'lt',
+    '>': 'gt',
+    '<=': 'le',
+    '>=': 'ge',
+};
+
+/** True if `t` is a vector or matrix — operand types that need element-wise dispatch. */
+function isContainerType(t) {
+    return t && (t.kind === 'vec' || t.kind === 'mat');
+}
+
+/** True if `t` is a u32 scalar — needed to route `>>` through the unsigned-shift helper. */
+function isScalarUnsigned(t) {
+    return t && t.kind === 'primitive' && t.name === 'u32';
+}
+
+/** True if both operands are integer-typed (scalar or vec of i32/u32). */
+function bothOperandsInteger(a, b) {
+    const isInt = (t) => {
+        if (!t) return false;
+        if (t.kind === 'primitive') return t.name === 'i32' || t.name === 'u32';
+        if (t.kind === 'vec' || t.kind === 'mat') return t.scalar === 'i32' || t.scalar === 'u32';
+        return false;
+    };
+    return isInt(a) && isInt(b);
+}
+
+/**
+ * Dispatch a WGSL `*` expression to the appropriate matrix/vector helper in the language
+ * core when at least one operand is a matrix. Returns `null` to indicate "fall through to the
+ * element-wise multiply" — used for scalar×scalar, vec×scalar, vec×vec (Hadamard product),
+ * matrix×scalar, etc., which `wgsl.mul` already handles correctly.
+ *
+ * Naming includes the scalar type suffix (`f` / `i` / `u` / `h`), e.g.
+ * `m4x4f_multiply_v4f`, `v3f_multiply_m3x3f`, `m4x4f_multiply_m4x4f`. Unsupported
+ * shapes (e.g. mat3x4 × vec3) produce a runtime `TypeError: wgsl.<name> is not a function`
+ * — adding support is a single new function in WGSLLanguageCore.js.
+ *
+ * @param {{ code: string, type: WgslType }} left
+ * @param {{ code: string, type: WgslType }} right
+ * @returns {{ code: string, type: WgslType } | null}
+ */
+function dispatchMatrixMul(left, right) {
+    const lt = left.type;
+    const rt = right.type;
+    const isVec = (t) => t && t.kind === 'vec';
+    const isMat = (t) => t && t.kind === 'mat';
+
+    // mat × mat → mat(b.cols, a.rows). Multiplication is defined only when a.cols == b.rows.
+    if (isMat(lt) && isMat(rt)) {
+        const lh = `m${lt.cols}x${lt.rows}${scalarTypeSuffix(lt.scalar)}`;
+        const rh = `m${rt.cols}x${rt.rows}${scalarTypeSuffix(rt.scalar)}`;
+        return {
+            code: `wgsl.${lh}_multiply_${rh}(${left.code}, ${right.code})`,
+            type: { kind: 'mat', cols: rt.cols, rows: lt.rows, scalar: lt.scalar },
+        };
+    }
+
+    // mat × vec → vec(rows). Vec must have length == cols.
+    if (isMat(lt) && isVec(rt)) {
+        const lh = `m${lt.cols}x${lt.rows}${scalarTypeSuffix(lt.scalar)}`;
+        const rh = `v${rt.size}${scalarTypeSuffix(rt.scalar)}`;
+        return {
+            code: `wgsl.${lh}_multiply_${rh}(${left.code}, ${right.code})`,
+            type: { kind: 'vec', size: lt.rows, scalar: lt.scalar },
+        };
+    }
+
+    // vec × mat → vec(cols). Vec acts as a row vector; vec.length must equal rows.
+    if (isVec(lt) && isMat(rt)) {
+        const lh = `v${lt.size}${scalarTypeSuffix(lt.scalar)}`;
+        const rh = `m${rt.cols}x${rt.rows}${scalarTypeSuffix(rt.scalar)}`;
+        return {
+            code: `wgsl.${lh}_multiply_${rh}(${left.code}, ${right.code})`,
+            type: { kind: 'vec', size: rt.cols, scalar: rt.scalar },
+        };
+    }
+
+    return null;
+}
+
+/** Scalar type → suffix character used in matrix/vector helper names: f / i / u / h. */
+function scalarTypeSuffix(scalar) {
+    return { f32: 'f', i32: 'i', u32: 'u', f16: 'h' }[scalar] || 'f';
+}
+
+/**
+ * Pick the result type of an element-wise arithmetic op given the operand types.
+ * Vec wins over scalar; matrix wins over scalar; scalar otherwise.
+ */
+function inferBinaryArithResultType(a, b) {
+    const isVec = (t) => t && t.kind === 'vec';
+    const isMat = (t) => t && t.kind === 'mat';
+    const isPrim = (t) => t && t.kind === 'primitive';
+
+    if (isVec(a)) return a;
+    if (isVec(b)) return b;
+    if (isMat(a)) return a;
+    if (isMat(b)) return b;
+    if (isPrim(a)) return a;
+    if (isPrim(b)) return b;
+    return T_UNKNOWN;
+}
+
+/**
+ * Pick the result type of a non-arithmetic binary op (comparison / logical / bitwise / shift).
+ * Comparisons return bool; bitwise and shift preserve the leftmost known integer operand type.
+ */
+function inferRawBinaryResultType(a, b, op) {
+    const COMPARISON = new Set(['==', '!=', '<', '>', '<=', '>=']);
+    const LOGICAL = new Set(['&&', '||']);
+    if (COMPARISON.has(op) || LOGICAL.has(op)) {
+        return { kind: 'primitive', name: 'bool' };
+    }
+    // Bitwise / shift: propagate the first known integer-ish operand type. This lets `bitcast`
+    // and other downstream consumers see u32/i32 even when the literal on one side is untyped.
+    if (a && a.kind === 'primitive') return a;
+    if (b && b.kind === 'primitive') return b;
+    if (a && a.kind === 'vec') return a;
+    if (b && b.kind === 'vec') return b;
+    return T_UNKNOWN;
+}
+
+function compileUnaryExpression(c, node) {
+    const named = node.namedChildren;
+    const prefix = textBeforeFirstNamed(node).trim();
+
+    if (prefix === '') {
+        return compileExpression(c, named[0]);
+    }
+
+    const operand = compileExpression(c, named[named.length - 1]);
+
+    if (prefix === '-') return { code: `wgsl.neg(${operand.code})`, type: operand.type };
+    if (prefix === '!') return { code: `!${operand.code}`, type: operand.type };
+    if (prefix === '~') return { code: `wgsl.not(${operand.code})`, type: operand.type };
+    if (prefix === '*' || prefix === '&') return { code: operand.code, type: operand.type };
+
+    return { code: `${prefix}${operand.code}`, type: operand.type };
+}
+
+function compileSingularExpression(c, node) {
+    const named = node.namedChildren;
+    const head = named[0];
+    const head_result = head.type === 'primary_expression'
+        ? compileExpression(c, unwrapExpression(head))
+        : compileExpression(c, head);
+
+    let code = head_result.code;
+    let type = head_result.type;
+
+    for (let i = 1; i < named.length; i++) {
+        const spec = named[i];
+        if (spec.type !== 'component_or_swizzle_specifier') break;
+        const next = applyAccessSpecifier(c, spec, code, type);
+        code = next.code;
+        type = next.type;
+    }
+
+    return { code, type };
+}
+
+/**
+ * Apply a `.member`, `.swizzle`, or `[index]` access to an expression that has already been
+ * compiled to `lhs_code` of type `lhs_type`.
+ */
+function applyAccessSpecifier(c, node, lhs_code, lhs_type) {
+    // tree-sitter-wgsl groups chained access like `[i].x` (or `.foo[i]`) as a SINGLE outer
+    // `component_or_swizzle_specifier` whose first named child is the immediate access (an
+    // `expression` for `[]` or a `member_ident` for `.field`) and whose second named child
+    // is a NESTED `component_or_swizzle_specifier` for the rest of the chain. We apply the
+    // immediate access first, then recurse into any nested specifier.
+    let code = lhs_code;
+    let type = lhs_type;
+
+    const member_ident = namedChildByType(node, 'member_ident');
+    if (member_ident !== null) {
+        const r = applyMemberAccess(c, member_ident.text, code, type);
+        code = r.code;
+        type = r.type;
+    } else {
+        const expr = namedChildByType(node, 'expression');
+        if (expr !== null) {
+            const e = compileExpression(c, expr);
+            // Matrices are stored as flat column-major typed arrays, so the bare `m[i]`
+            // would index a scalar — route through `wgsl.mat_col` to get the column as a vec.
+            if (type && type.kind === 'mat') {
+                code = `wgsl.mat_col(${code}, ${e.code}, ${type.rows})`;
+                type = { kind: 'vec', size: type.rows, scalar: type.scalar };
+            } else {
+                code = `${code}[${e.code}]`;
+                if (type && type.kind === 'array') type = type.element;
+                else if (type && type.kind === 'vec') type = { kind: 'primitive', name: type.scalar };
+                else type = T_UNKNOWN;
+            }
+        }
+    }
+
+    const nested = namedChildByType(node, 'component_or_swizzle_specifier');
+    if (nested !== null) {
+        const r = applyAccessSpecifier(c, nested, code, type);
+        code = r.code;
+        type = r.type;
+    }
+
+    return { code, type };
+}
+
+/** Apply a `.field` / `.swizzle` access to an already-compiled expression of `lhs_type`. */
+function applyMemberAccess(c, name, lhs_code, lhs_type) {
+    if (lhs_type !== null && lhs_type !== undefined && lhs_type.kind === 'vec' && isSwizzlePattern(name)) {
+        if (name.length === 1) {
+            return {
+                code: `${lhs_code}[${SWIZZLE_INDEX[name]}]`,
+                type: { kind: 'primitive', name: lhs_type.scalar },
+            };
+        }
+        const new_size = name.length;
+        const ctor = vecAliasName(new_size, lhs_type.scalar);
+        const elements = Array.from(name).map(ch => `${lhs_code}[${SWIZZLE_INDEX[ch]}]`);
+        return {
+            code: `wgsl.${ctor}(${elements.join(', ')})`,
+            type: { kind: 'vec', size: new_size, scalar: lhs_type.scalar },
+        };
+    }
+    if (lhs_type !== null && lhs_type !== undefined && lhs_type.kind === 'struct') {
+        const struct_info = c.structs.get(lhs_type.name);
+        if (struct_info !== undefined) {
+            const field = struct_info.fields.find(f => f.name === name);
+            if (field !== undefined) {
+                return { code: `${lhs_code}.${name}`, type: field.type };
+            }
+        }
+    }
+    return { code: `${lhs_code}.${name}`, type: T_UNKNOWN };
+}
+
+function isSwizzlePattern(name) {
+    if (name.length === 0 || name.length > 4) return false;
+    for (const ch of name) {
+        if (!SWIZZLE_LETTERS.has(ch)) return false;
+    }
+    return true;
+}
+
+/**
+ * Compile a `call_phrase` and return both the JS code and the inferred result type.
+ *
+ * Special cases:
+ * - `vec3<f32>(a, b, c)` → `wgsl.vec3f(a, b, c)` (vec result)
+ * - `f32(x)` → `wgsl.f32(x)` (scalar result)
+ * - WGSL builtin (mix, clamp, dot, length, ...) → `wgsl.<name>(...)` (best-effort type)
+ * - User function → `name(...)` (uses declared return type)
+ *
+ * @returns {{ code: string, type: WgslType }}
+ */
+function compileCallPhraseTyped(c, node) {
+    const ident_node = namedChildByType(node, 'template_elaborated_ident');
+    const arg_list = namedChildByType(node, 'argument_expression_list');
+
+    const ident_inner = namedChildByType(ident_node, 'ident');
+    const callee_name = ident_inner.text;
+    const template = namedChildByType(ident_node, 'template_list');
+
+    /** @type {Array<{ code: string, type: WgslType }>} */
+    const arg_results = [];
+    if (arg_list !== null) {
+        const comma_list = namedChildByType(arg_list, 'expression_comma_list');
+        if (comma_list !== null) {
+            for (const arg of namedChildrenByType(comma_list, 'expression')) {
+                arg_results.push(compileExpression(c, arg));
+            }
+        }
+    }
+    const args = arg_results.map(a => a.code);
+
+    // 1) Vec aliases: vec3f, vec4i, vec2h, etc.
+    if (VECTOR_ALIASES.hasOwnProperty(callee_name)) {
+        const a = VECTOR_ALIASES[callee_name];
+        return {
+            code: `wgsl.${callee_name}(${args.join(', ')})`,
+            type: { kind: 'vec', size: a.size, scalar: a.scalar },
+        };
+    }
+    // 2) Templated vec: vec3<f32>(...).
+    if (callee_name === 'vec2' || callee_name === 'vec3' || callee_name === 'vec4') {
+        const size = parseInt(callee_name.slice(3));
+        let scalar;
+        if (template !== null) {
+            const targs = extractTemplateArgs(template);
+            if (targs.length > 0) scalar = targs[0];
+        }
+        if (scalar === undefined) {
+            // No explicit template — infer the component type from the arguments, mirroring
+            // WGSL's overload resolution. e.g. `vec4(some_u32)` is `vec4<u32>`, not `vec4<f32>`.
+            for (const a of arg_results) {
+                const t = a.type;
+                if (t && t.kind === 'primitive' && t.name !== 'bool') { scalar = t.name; break; }
+                if (t && (t.kind === 'vec' || t.kind === 'mat')) { scalar = t.scalar; break; }
+            }
+            if (scalar === undefined) scalar = 'f32';
+        }
+        return {
+            code: `wgsl.${vecAliasName(size, scalar)}(${args.join(', ')})`,
+            type: { kind: 'vec', size, scalar },
+        };
+    }
+    // 3) Matrix constructors.
+    {
+        const m = callee_name.match(/^mat(\d)x(\d)([ifh]?)$/);
+        if (m !== null) {
+            const cols = parseInt(m[1]);
+            const rows = parseInt(m[2]);
+            const suffix = m[3];
+            let scalar;
+            if (suffix === 'f') scalar = 'f32';
+            else if (suffix === 'i') scalar = 'i32';
+            else if (suffix === 'h') scalar = 'f16';
+            else if (template !== null) {
+                const targs = extractTemplateArgs(template);
+                scalar = targs[0] || 'f32';
+            } else {
+                scalar = 'f32';
+            }
+            const fn_suffix = suffix !== '' ? '' : ({ f32: 'f', i32: 'i', f16: 'h' }[scalar] || 'f');
+            return {
+                code: `wgsl.${callee_name}${fn_suffix}(${args.join(', ')})`,
+                type: { kind: 'mat', cols, rows, scalar },
+            };
+        }
+    }
+
+    // 4) Scalar casts: f32(x), i32(x), u32(x), f16(x), bool(x).
+    if (PRIMITIVE_NAMES.has(callee_name)) {
+        return {
+            code: `wgsl.${callee_name}(${args.join(', ')})`,
+            type: { kind: 'primitive', name: callee_name },
+        };
+    }
+
+    // 5) `bitcast<T>(x)` — JS can't tell a u32 from an f32 by value alone, so we emit the
+    // source type alongside the target. The compiler infers source from the argument's tracked
+    // type; if that's unknown the runtime falls back to a heuristic.
+    if (callee_name === 'bitcast') {
+        let target = 'f32';
+        if (template !== null) {
+            const targs = extractTemplateArgs(template);
+            if (targs.length > 0) target = targs[0];
+        }
+        const arg_type = arg_results[0] !== undefined ? arg_results[0].type : null;
+        let source = null;
+        if (arg_type) {
+            if (arg_type.kind === 'primitive') source = arg_type.name;
+            else if (arg_type.kind === 'vec') source = arg_type.scalar;
+        }
+        const source_arg = source !== null ? `, ${JSON.stringify(source)}` : '';
+        // Parse the target string: `vec3<u32>` etc. become a vec type so that downstream
+        // swizzle/component access compiles correctly. Bare `f32` / `u32` / `i32` stay primitive.
+        let resultType;
+        const vec_match = target.match(/^vec(\d)<([^>]+)>$/);
+        if (vec_match !== null) {
+            resultType = { kind: 'vec', size: parseInt(vec_match[1]), scalar: vec_match[2] };
+        } else {
+            resultType = { kind: 'primitive', name: target };
+        }
+        return {
+            code: `wgsl.bitcast(${args[0]}, ${JSON.stringify(target)}${source_arg})`,
+            type: resultType,
+        };
+    }
+
+    // 6) array / array<T, N> constructor.
+    if (callee_name === 'array') {
+        return { code: `[${args.join(', ')}]`, type: T_UNKNOWN };
+    }
+
+    // 7) Struct constructor.
+    if (c.structs.has(callee_name)) {
+        const info = c.structs.get(callee_name);
+        const parts = [`(() => { const __s__ = new ${callee_name}();`];
+        for (let i = 0; i < info.fields.length && i < args.length; i++) {
+            parts.push(`__s__.${info.fields[i].name} = ${args[i]};`);
+        }
+        parts.push(`return __s__; })()`);
+        return { code: parts.join(' '), type: { kind: 'struct', name: callee_name } };
+    }
+
+    // 8) User-defined function.
+    if (c.functions.has(callee_name)) {
+        return {
+            code: `${callee_name}(${args.join(', ')})`,
+            type: c.functions.get(callee_name).returnType,
+        };
+    }
+
+    // 9) WGSL builtins — best-effort type inference for common helpers.
+    return {
+        code: `wgsl.${callee_name}(${args.join(', ')})`,
+        type: inferBuiltinReturnType(callee_name, arg_results),
+    };
+}
+
+/**
+ * Best-effort return type for WGSL builtins commonly used in compute shaders.
+ * Handles the cases needed for accurate swizzle / member-access codegen downstream.
+ */
+function inferBuiltinReturnType(name, args) {
+    // Element-wise vector-preserving math: result follows the first vector argument.
+    const ELEMENT_WISE = new Set([
+        'abs', 'sign', 'floor', 'ceil', 'round', 'trunc', 'fract', 'sqrt', 'inverseSqrt',
+        'exp', 'exp2', 'log', 'log2', 'sin', 'cos', 'tan', 'asin', 'acos', 'atan',
+        'pow', 'atan2', 'min', 'max', 'step', 'clamp', 'saturate', 'mix', 'smoothstep',
+        'normalize', 'reflect', 'fma',
+    ]);
+    if (ELEMENT_WISE.has(name)) {
+        for (const a of args) {
+            if (a.type && (a.type.kind === 'vec' || a.type.kind === 'mat')) return a.type;
+        }
+        if (args[0] && args[0].type) return args[0].type;
+        return T_UNKNOWN;
+    }
+    if (name === 'length' || name === 'distance' || name === 'dot' || name === 'determinant') {
+        return { kind: 'primitive', name: 'f32' };
+    }
+    if (name === 'cross') {
+        return args[0] && args[0].type && args[0].type.kind === 'vec'
+            ? args[0].type
+            : { kind: 'vec', size: 3, scalar: 'f32' };
+    }
+    if (name === 'all' || name === 'any') return { kind: 'primitive', name: 'bool' };
+    if (name === 'select') {
+        if (args[0] && args[0].type) return args[0].type;
+        if (args[1] && args[1].type) return args[1].type;
+        return T_UNKNOWN;
+    }
+    if (name === 'textureLoad' || name === 'textureSampleLevel' || name === 'textureSample' || name === 'textureSampleGrad') {
+        return { kind: 'vec', size: 4, scalar: 'f32' };
+    }
+    if (name === 'textureDimensions') {
+        return { kind: 'vec', size: 2, scalar: 'u32' };
+    }
+    if (name === 'atomicLoad') return { kind: 'primitive', name: 'i32' };
+    if (name === 'unpack2x16unorm' || name === 'unpack2x16snorm' || name === 'unpack2x16float') {
+        return { kind: 'vec', size: 2, scalar: 'f32' };
+    }
+    if (name === 'unpack4x8unorm' || name === 'unpack4x8snorm') {
+        return { kind: 'vec', size: 4, scalar: 'f32' };
+    }
+    if (name === 'pack2x16unorm' || name === 'pack2x16snorm' || name === 'pack2x16float'
+        || name === 'pack4x8unorm' || name === 'pack4x8snorm') {
+        return { kind: 'primitive', name: 'u32' };
+    }
+    // extractBits/insertBits return the integer type (scalar or vector) of their first operand.
+    if (name === 'extractBits' || name === 'insertBits') {
+        return args[0] && args[0].type ? args[0].type : T_UNKNOWN;
+    }
+    return T_UNKNOWN;
+}
+
+// =========================================================================
+// LHS expressions (for assignments)
+// =========================================================================
+
+function compileLhs(c, node) {
+    if (node.type !== 'lhs_expression') {
+        return compileExpression(c, node);
+    }
+
+    // Pointer deref / address-of: `*lhs` / `&lhs`. The emulator models pointers as values, so
+    // both collapse to the operand's value. The grammar puts the `*` / `&` as an unnamed leading
+    // token with a nested `lhs_expression` named child.
+    const prefix = textBeforeFirstNamed(node).trim();
+    if (prefix === '*' || prefix === '&') {
+        const nested_lhs = namedChildByType(node, 'lhs_expression');
+        if (nested_lhs !== null) {
+            return compileLhs(c, nested_lhs);
+        }
+    }
+
+    const core = namedChildByType(node, 'core_lhs_expression');
+    let code;
+    let type;
+    if (core !== null) {
+        const ident = namedChildByType(core, 'ident');
+        if (ident !== null) {
+            code = ident.text;
+            type = c.scope.lookup(ident.text);
+        } else {
+            const nested = namedChildByType(core, 'lhs_expression');
+            if (nested !== null) {
+                const r = compileLhs(c, nested);
+                code = `(${r.code})`;
+                type = r.type;
+            } else {
+                code = core.text;
+                type = T_UNKNOWN;
+            }
+        }
+    } else {
+        code = node.text;
+        type = T_UNKNOWN;
+    }
+
+    for (const child of node.namedChildren) {
+        if (child.type === 'component_or_swizzle_specifier') {
+            const next = applyAccessSpecifier(c, child, code, type);
+            code = next.code;
+            type = next.type;
+        }
+    }
+    return { code, type };
+}