@woosh/meep-engine 3.56.0 → 3.58.0

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

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { FLOAT16_MAX } from "../../../core/binary/FLOAT16_MAX.js";
 import { FLOAT32_MAX } from "../../../core/binary/FLOAT32_MAX.js";
 import LineBuilder from "../../../core/codegen/LineBuilder.js";
 
@@ -22,6 +23,19 @@ import LineBuilder from "../../../core/codegen/LineBuilder.js";
 const T_UNKNOWN = Object.freeze({ kind: 'unknown' });
 const T_I32 = Object.freeze({ kind: 'primitive', name: 'i32' });
 const T_F32 = Object.freeze({ kind: 'primitive', name: 'f32' });
+const T_F16 = Object.freeze({ kind: 'primitive', name: 'f16' });
+
+const COMPILER_F16_SCRATCH = new Float16Array(1);
+
+/**
+ * Round a number to IEEE 754 binary16 precision at compile time.
+ * @param {number} x
+ * @returns {number}
+ */
+function roundF16(x) {
+    COMPILER_F16_SCRATCH[0] = x;
+    return COMPILER_F16_SCRATCH[0];
+}
 
 /**
  * WGSL's two abstract numeric types. A bare literal has one (`2` is an AbstractInt, `0.5` an
@@ -418,10 +432,43 @@ function classifyType(ident, args, template_list_node) {
  * 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.
  */
+const HEX_FLOAT_RE = /^0[xX](?:([0-9a-fA-F]+)\.?([0-9a-fA-F]*)|\.([0-9a-fA-F]+))(?:[pP]([+-]?\d+)([fh])?)?$/;
+
+/**
+ * Parse a WGSL §3.4.3 hexadecimal floating-point literal (e.g. `0x1.8p-2h`, `0x1.ffcp15h`,
+ * `0x1p0f`, `0x1.5`). Returns `null` for hexadecimal integer literals (`0x10`, `0x1fu`).
+ *
+ * @param {string} t
+ * @returns {{ value: number, suffix: string } | null}
+ */
+function parseWgslHexFloat(t) {
+    if (!/^0[xX]/.test(t) || !/[.pP]/.test(t)) return null;
+    const m = t.match(HEX_FLOAT_RE);
+    if (m === null) return null;
+    const int_hex = m[1] || '';
+    const frac_hex = m[2] !== undefined ? m[2] : (m[3] || '');
+    const exp = m[4] !== undefined ? parseInt(m[4], 10) : 0;
+    const suffix = m[5] || '';
+    const int_val = int_hex.length > 0 ? parseInt(int_hex, 16) : 0;
+    let frac_val = 0;
+    for (let i = frac_hex.length - 1; i >= 0; i--) {
+        frac_val = (frac_val + parseInt(frac_hex[i], 16)) / 16;
+    }
+    return {
+        value: (int_val + frac_val) * Math.pow(2, exp),
+        suffix,
+    };
+}
+
 function literalToJs(text) {
     const t = text.trim();
     if (t === 'true' || t === 'false') return t;
 
+    const hex_float = parseWgslHexFloat(t);
+    if (hex_float !== null) {
+        return String(hex_float.value);
+    }
+
     // Hex int literals: `0xNN[ui]?`. Only `u`/`i` are real suffixes here; trailing `f`/`h` are
     // hex digits.
     if (/^0[xX]/.test(t)) {
@@ -462,6 +509,13 @@ function literalType(text) {
         return { kind: 'primitive', name: 'bool' };
     }
 
+    const hex_float = parseWgslHexFloat(t);
+    if (hex_float !== null) {
+        if (hex_float.suffix === 'f') return T_F32;
+        if (hex_float.suffix === 'h') return T_F16;
+        return T_ABSTRACT_FLOAT;
+    }
+
     if (/[ui]$/.test(t)) {
         return { kind: 'primitive', name: t.endsWith('u') ? 'u32' : 'i32' };
     }
@@ -578,6 +632,17 @@ const F32_SCALAR_OP = {
     '/': 'div_f32',
 };
 
+/**
+ * Scalar arithmetic that has to round to f16, by operator.
+ * @type {Object<string, string>}
+ */
+const F16_SCALAR_OP = {
+    '+': 'add_f16',
+    '-': 'sub_f16',
+    '*': 'mul_f16',
+    '/': 'div_f16',
+};
+
 // =========================================================================
 // Compiler context — central state during compilation
 // =========================================================================
@@ -889,7 +954,7 @@ function defaultValueForType(type) {
         case 'vec':
             return `wgsl.${vecAliasName(type.size, type.scalar)}()`;
         case 'mat':
-            return `new Float32Array(${type.cols * type.rows})`;
+            return `new ${arrayCtorForScalar(type.scalar)}(${type.cols * type.rows})`;
         case 'array': {
             const length = type.count > 0 ? String(type.count)
                 : type.count_name !== undefined ? `Number(${identToJs(type.count_name)})` : null;
@@ -898,9 +963,10 @@ function defaultValueForType(type) {
                     const ctor = arrayCtorForScalar(type.element.name);
                     return `new ${ctor}(${length})`;
                 }
-                // 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: ${length} }, () => ${defaultValueForType(type.element)})`;
+                // For non-primitive elements (vec / mat / struct / atomic / nested array) build the
+                // array eagerly so `out[i]` is a fresh, mutable element rather than `undefined`. The
+                // parentheses keep an atomic's `{ value: 0 }` an object, not the arrow's block.
+                return `Array.from({ length: ${length} }, () => (${defaultValueForType(type.element)}))`;
             }
             return '[]';
         }
@@ -1132,7 +1198,7 @@ function collectGlobalVariable(c, node) {
     // to the type's default value.
     const initializer_node = namedChildByType(node, 'expression');
     const init_code = initializer_node !== null
-        ? compileExpression(c, initializer_node).code
+        ? compileExpressionForType(c, initializer_node, type).code
         : defaultValueForType(type);
     c.privateGlobals.push({
         name,
@@ -1170,7 +1236,7 @@ function collectGlobalValue(c, node) {
 
     const expr = keeps_abstract
         ? compileExpressionAbstract(c, value_node)
-        : compileExpression(c, value_node);
+        : compileExpressionForType(c, value_node, type);
 
     // 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
@@ -1435,7 +1501,7 @@ function emitVariableOrValueStatement(c, node) {
         const keeps_abstract = is_wgsl_const && type_spec === null;
         const expr = keeps_abstract
             ? compileExpressionAbstract(c, expr_node)
-            : compileExpression(c, expr_node);
+            : compileExpressionForType(c, expr_node, type);
         if (type === T_UNKNOWN || type.kind === 'unknown') {
             type = keeps_abstract ? expr.type : concreteDefault(expr.type);
         }
@@ -1492,6 +1558,12 @@ function compoundArithmeticHelper(helper, op_text, lhs_compiled, rhs_compiled) {
         return f32_scalar;
     }
 
+    const f16_scalar = F16_SCALAR_OP[binary_op];
+
+    if (f16_scalar !== undefined && isScalarF16(arith_type)) {
+        return f16_scalar;
+    }
+
     return helper;
 }
 
@@ -1508,7 +1580,7 @@ function emitVariableUpdatingStatement(c, node) {
         const op_text = textBetween(inner, lhs, expr).trim();
 
         const lhs_compiled = compileLhs(c, lhs);
-        const rhs_compiled = compileExpression(c, expr);
+        const rhs_compiled = compileExpressionForType(c, expr, lhs_compiled.type);
 
         if (op_text === '=' || op_text === '') {
             c.out.add(emitWriteStatement(lhs_compiled, ownedValueCode(rhs_compiled)));
@@ -1671,7 +1743,8 @@ function emitReturnStatement(c, node) {
     if (expr === null) {
         c.out.add('return;');
     } else {
-        const e = compileExpression(c, expr);
+        const fn_info = c.function_name !== null ? c.functions.get(c.function_name) : undefined;
+        const e = compileExpressionForType(c, expr, fn_info !== undefined ? fn_info.returnType : T_UNKNOWN);
         // a parameter or a global handed straight back would otherwise reach the caller as itself
         c.out.add(`return ${isReferenceExpression(c, expr) ? ownedValueCode(e) : e.code};`);
     }
@@ -1782,8 +1855,8 @@ function emitForInitInline(c, node) {
         const ident = namedChildByType(opt_ident, 'ident');
         const type_spec = namedChildByType(opt_ident, 'type_specifier');
         const name = ident.text;
-        const init = expr_node !== null ? compileExpression(c, expr_node) : null;
         let type = type_spec !== null ? parseTypeSpecifier(type_spec) : T_UNKNOWN;
+        const init = expr_node !== null ? compileExpressionForType(c, expr_node, type) : null;
         if (type.kind === 'unknown' && init !== null) {
             // `for (var i = 0; ...)`: a bare integer literal concretises to i32, as in a `let`
             type = concreteDefault(init.type);
@@ -1819,7 +1892,7 @@ function emitForUpdateInline(c, node) {
             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);
+            const rhs_compiled = compileExpressionForType(c, expr, lhs_compiled.type);
             if (op_text === '=' || op_text === '') {
                 if (lhs_compiled.through_pointer === true) {
                     return `${lhs_compiled.code} = wgsl.store_ptr(${lhs_compiled.code}, ${ownedValueCode(rhs_compiled)})`;
@@ -2025,6 +2098,25 @@ function compileExpression(c, node) {
     return isAbstractFloat(e.type) ? convertAbstract(e, 'f32') : e;
 }
 
+/**
+ * Compile an expression meeting a known target type (e.g. a typed `let`/`var`/`const` declaration
+ * or an assignment). When the target is `f16` and the expression is abstract (`const LIMIT: f16 = 70000.0;`
+ * or `let x: f16 = 0.1;`), the abstract value converts directly to `f16` via {@link convertAbstract}
+ * (checking the `65504` range and rounding to binary16) rather than defaulting to `f32`.
+ *
+ * @param {Compiler} c
+ * @param {Node} node
+ * @param {WgslType} target_type
+ * @returns {{ code: string, type: WgslType, value?: number }}
+ */
+function compileExpressionForType(c, node, target_type) {
+    if (isScalarF16(target_type)) {
+        const e = compileExpressionAbstract(c, node);
+        return isAbstractType(e.type) ? convertAbstract(e, 'f16') : e;
+    }
+    return compileExpression(c, node);
+}
+
 /**
  * Compile an expression node (any wrapper or specific kind), leaving an abstract result abstract.
  *
@@ -2084,7 +2176,26 @@ function compileExpressionAbstract(c, node) {
         // A bare literal is abstract (see literalType), and takes its concrete type where it is used
         const code = literalToJs(u.text);
         const type = literalType(u.text);
-        return isAbstractType(type) ? { code, type, value: Number(code) } : { code, type };
+        if (isAbstractType(type)) {
+            return { code, type, value: Number(code) };
+        }
+        if (isScalarF16(type)) {
+            const val = Number(code);
+            if (!(Math.abs(val) <= FLOAT16_MAX)) {
+                throw new Error(`WGSL compiler: value ${val} cannot be represented as 'f16' (at ${JSON.stringify(u.text)})`);
+            }
+            const rounded = roundF16(val);
+            return { code: rounded === val ? code : `(${rounded})`, type, value: rounded };
+        }
+        if (isScalarF32(type)) {
+            const val = Number(code);
+            if (!(Math.abs(val) <= FLOAT32_MAX)) {
+                throw new Error(`WGSL compiler: value ${val} cannot be represented as 'f32' (at ${JSON.stringify(u.text)})`);
+            }
+            const rounded = Math.fround(val);
+            return { code: rounded === val ? code : `(${rounded})`, type, value: rounded };
+        }
+        return { code, type };
     }
     if (u.type === 'paren_expression') {
         const inner = namedChildByType(u, 'expression');
@@ -2182,10 +2293,28 @@ function compileBinaryExpression(c, node, op_type, mode) {
             if (f32_scalar !== undefined && isScalarF32(arith_type)) {
                 actual_helper = f32_scalar;
             }
+            const f16_scalar = F16_SCALAR_OP[op_text];
+            if (f16_scalar !== undefined && isScalarF16(arith_type)) {
+                actual_helper = f16_scalar;
+            }
+            let folded_value = undefined;
+            if (isAbstractType(arith_type) && left.value !== undefined && right.value !== undefined) {
+                if (op_text === '+') folded_value = left.value + right.value;
+                else if (op_text === '-') folded_value = left.value - right.value;
+                else if (op_text === '*') folded_value = left.value * right.value;
+                else if (op_text === '/' && right.value !== 0) {
+                    folded_value = isAbstractInt(arith_type)
+                        ? Math.trunc(left.value / right.value)
+                        : left.value / right.value;
+                } else if (op_text === '%' && right.value !== 0) {
+                    folded_value = left.value % right.value;
+                }
+            }
             // arithmetic on two AbstractInts is still AbstractInt, so `(1 + 2) / 2` is 1
             return {
                 code: `wgsl.${actual_helper}(${left.code}, ${right.code})`,
                 type: arith_type,
+                value: folded_value,
             };
         }
     }
@@ -2281,6 +2410,19 @@ function isScalarF32(t) {
     return t !== undefined && t !== null && t.kind === 'primitive' && t.name === 'f32';
 }
 
+/** True if `t` is an `f16` SCALAR — a vec's lanes round through their Float16Array already. */
+function isScalarF16(t) {
+    return t !== undefined && t !== null && t.kind === 'primitive' && t.name === 'f16';
+}
+
+/** True if `t` is `f16` or a `vec`/`mat` whose scalar type is `f16`. */
+function isF16Type(t) {
+    if (!t) return false;
+    if (t.kind === 'primitive') return t.name === 'f16';
+    if (t.kind === 'vec' || t.kind === 'mat') return t.scalar === 'f16';
+    return false;
+}
+
 /** True if `t` is an integer type (scalar or vec/mat of i32/u32). */
 function isIntegerType(t) {
     if (!t) return false;
@@ -2353,7 +2495,14 @@ function convertAbstract(operand, scalar) {
     }
 
     if (scalar === 'f16') {
-        return { code: `wgsl.f16(${operand.code})`, type };
+        if (operand.value === undefined) {
+            return { code: `wgsl.f16(${operand.code})`, type: T_F16 };
+        }
+        if (!(Math.abs(operand.value) <= FLOAT16_MAX)) {
+            throw new Error(`WGSL compiler: value ${operand.value} cannot be represented as 'f16' (at ${JSON.stringify(operand.code)})`);
+        }
+        const rounded = roundF16(operand.value);
+        return { code: rounded === operand.value ? operand.code : `(${rounded})`, type: T_F16 };
     }
 
     return { code: operand.code, type };
@@ -2694,7 +2843,57 @@ function compileCallPhraseTyped(c, node) {
         && arg_results.every(a => isAbstractType(a.type));
 
     if (!const_evaluated) {
-        arg_results = arg_results.map(a => isAbstractFloat(a.type) ? convertAbstract(a, 'f32') : a);
+        let default_float_scalar = 'f32';
+        let explicit_f16_target = false;
+        if (callee_name === 'f16' || (VECTOR_ALIASES.hasOwnProperty(callee_name) && VECTOR_ALIASES[callee_name].scalar === 'f16')) {
+            default_float_scalar = 'f16';
+            explicit_f16_target = true;
+        } else if ((callee_name === 'vec2' || callee_name === 'vec3' || callee_name === 'vec4') && template !== null) {
+            const targs = extractTemplateArgs(template);
+            if (targs[0] === 'f16') {
+                default_float_scalar = 'f16';
+                explicit_f16_target = true;
+            }
+        } else if (/^mat\dx\d/.test(callee_name)) {
+            if (callee_name.endsWith('h') || (template !== null && extractTemplateArgs(template)[0] === 'f16')) {
+                default_float_scalar = 'f16';
+                explicit_f16_target = true;
+            }
+        } else if (callee_name === 'array' && template !== null) {
+            const arr_type = parseTypeSpecifier(ident_node);
+            if (arr_type.kind === 'array' && isF16Type(arr_type.element)) {
+                default_float_scalar = 'f16';
+                explicit_f16_target = true;
+            }
+        } else if (!c.functions.has(callee_name) && !c.structs.has(callee_name)) {
+            for (const a of arg_results) {
+                if (isF16Type(a.type)) {
+                    default_float_scalar = 'f16';
+                    break;
+                }
+            }
+        }
+
+        const fn_info = c.functions.get(callee_name);
+        const struct_info = c.structs.get(callee_name);
+        arg_results = arg_results.map((a, idx) => {
+            if (!isAbstractType(a.type)) return a;
+            let target_scalar = default_float_scalar;
+            let param_is_f16 = explicit_f16_target;
+            if (fn_info !== undefined && idx < fn_info.params.length) {
+                if (isF16Type(fn_info.params[idx].type)) {
+                    target_scalar = 'f16';
+                    param_is_f16 = true;
+                }
+            } else if (struct_info !== undefined && idx < struct_info.fields.length) {
+                if (isF16Type(struct_info.fields[idx].type)) {
+                    target_scalar = 'f16';
+                    param_is_f16 = true;
+                }
+            }
+            if (!isAbstractFloat(a.type) && !param_is_f16) return a;
+            return convertAbstract(a, target_scalar);
+        });
     }
 
     const args = arg_results.map(a => a.code);
@@ -2780,14 +2979,19 @@ function compileCallPhraseTyped(c, node) {
             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.
+        // Parse the target string: `vec3<u32>`, `vec2h`, etc. become a vec type so that downstream
+        // swizzle/component access compiles correctly. Bare `f32` / `u32` / `i32` / `f16` 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] };
+        if (VECTOR_ALIASES.hasOwnProperty(target)) {
+            const a = VECTOR_ALIASES[target];
+            resultType = { kind: 'vec', size: a.size, scalar: a.scalar };
         } else {
-            resultType = { kind: 'primitive', name: target };
+            const vec_match = target.match(/^vec(\d)<\s*([^>\s]+)\s*>$/);
+            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})`,
@@ -2807,6 +3011,10 @@ function compileCallPhraseTyped(c, node) {
         if ((type.kind !== 'array' || type.element === T_UNKNOWN) && arg_results.length > 0 && !isAbstractType(arg_results[0].type)) {
             type = { kind: 'array', element: arg_results[0].type, count: arg_results.length };
         }
+        // `array<T, N>()`, the zero-value constructor: N of T's zero, as a `var` of the type starts
+        if (arg_results.length === 0 && type.kind === 'array') {
+            return { code: defaultValueForType(type), type };
+        }
         return { code: `[${stored_args.join(', ')}]`, type };
     }
 
@@ -2895,9 +3103,19 @@ function compileCallPhraseTyped(c, node) {
         }
     }
 
+    const builtin_return_type = inferBuiltinReturnType(callee_name, arg_results);
+    const builtin_call = `wgsl.${callee_name}(${args.join(', ')})`;
+
+    if (isScalarF16(builtin_return_type)) {
+        return {
+            code: `wgsl.f16(${builtin_call})`,
+            type: builtin_return_type,
+        };
+    }
+
     return {
-        code: `wgsl.${callee_name}(${args.join(', ')})`,
-        type: inferBuiltinReturnType(callee_name, arg_results),
+        code: builtin_call,
+        type: builtin_return_type,
     };
 }
 
@@ -2907,12 +3125,13 @@ function compileCallPhraseTyped(c, node) {
  *
  * `abs` wraps at the most negative i32 and is the identity on u32; `firstLeadingBit` scans for the
  * most significant bit unlike the sign bit on i32 and for the most significant set bit on u32, which
- * are different functions rather than the same one read differently. Taking the JS meaning for both
- * made the emulator answer things no device does, on the oracle the chunk specs are checked against.
+ * are different functions rather than the same one read differently; `extractBits` sign-extends the
+ * field it reads on i32 and zero-extends it on u32. Taking the JS meaning for both made the emulator
+ * answer things no device does, on the oracle the chunk specs are checked against.
  *
  * @type {Set<string>}
  */
-const INTEGER_TYPED_BUILTIN = new Set(['abs', 'firstLeadingBit', 'firstTrailingBit']);
+const INTEGER_TYPED_BUILTIN = new Set(['abs', 'firstLeadingBit', 'firstTrailingBit', 'extractBits']);
 
 /**
  * Element-wise builtins: the result has the type of the arguments. Most are vector-preserving
@@ -2924,8 +3143,11 @@ const ELEMENT_WISE_BUILTIN = 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',
-    'subgroupBroadcastFirst',
+    'normalize', 'reflect', 'fma', 'quantizeToF16',
+    'subgroupBroadcastFirst', 'subgroupAdd', 'subgroupMul', 'subgroupMin', 'subgroupMax',
+    'subgroupAnd', 'subgroupOr', 'subgroupXor',
+    'subgroupExclusiveAdd', 'subgroupExclusiveMul', 'subgroupInclusiveAdd', 'subgroupInclusiveMul',
+    'quadSwapX', 'quadSwapY', 'quadSwapDiagonal',
     'dpdx', 'dpdy', 'fwidth', 'dpdxFine', 'dpdyFine', 'fwidthFine', 'dpdxCoarse', 'dpdyCoarse', 'fwidthCoarse',
 ]);
 
@@ -2959,15 +3181,36 @@ function inferBuiltinReturnType(name, args) {
         return commonArgumentType(args);
     }
     if (name === 'length' || name === 'distance' || name === 'dot' || name === 'determinant') {
+        const t = commonArgumentType(args);
+        if (t && (t.kind === 'vec' || t.kind === 'mat')) {
+            return { kind: 'primitive', name: t.scalar };
+        }
+        if (t && t.kind === 'primitive') {
+            return t;
+        }
         return { kind: 'primitive', name: 'f32' };
     }
+    if (name === 'transpose') {
+        const t = args[0] && args[0].type;
+        if (t && t.kind === 'mat') {
+            return { kind: 'mat', cols: t.rows, rows: t.cols, scalar: t.scalar };
+        }
+        return T_UNKNOWN;
+    }
+    if (name === 'subgroupBroadcast' || name === 'subgroupShuffle' || name === 'subgroupShuffleDown'
+        || name === 'subgroupShuffleUp' || name === 'subgroupShuffleXor' || name === 'quadBroadcast') {
+        return args[0] && args[0].type ? args[0].type : T_UNKNOWN;
+    }
+    if (name === 'subgroupAll' || name === 'subgroupAny' || name === 'subgroupElect') {
+        return { kind: 'primitive', name: 'bool' };
+    }
     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 === 'refract') {
-        // the incident vector's type; the third argument is the scalar ratio of indices
+    if (name === 'refract' || name === 'faceForward') {
+        // the incident vector's type; refract's third argument is the scalar ratio of indices
         return commonArgumentType(args.slice(0, 2));
     }
     if (name === 'all' || name === 'any') return { kind: 'primitive', name: 'bool' };

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

@@ -2,15 +2,14 @@ export namespace WGSLLanguageCore {
     /**
      * Bit-cast (WGSL `bitcast`). Reinterprets a value's bit pattern as a different type.
      *
-     * JS has no separate u32/i32/f32 scalar types — they're all `number` — so the source type
-     * cannot be detected from the value at runtime. The compiler passes it explicitly when known;
-     * otherwise we fall back to a heuristic: integer-targeted casts assume f32 source, float-targeted
-     * casts assume u32 source (the common "interpret bit pattern as float" idiom).
-     *
-     * For typed-array (vector) inputs the source type is auto-detected from the array constructor.
+     * Supports all WGSL §17.3.1 bitcast combinations, including:
+     * - Same-width scalar casts: `u32` ↔ `i32` ↔ `f32`, and `f16` ↔ `f16`
+     * - Same-length vector casts: `vecN<u32>` ↔ `vecN<i32>` ↔ `vecN<f32>`, `vecN<f16>` ↔ `vecN<f16>`
+     * - Width-changing 32-bit packed casts: `vec2<f16>` (`vec2h`) ↔ `u32` / `i32` / `f32`
+     * - Width-changing 64-bit packed casts: `vec4<f16>` (`vec4h`) ↔ `vec2<u32>` / `vec2<i32>` / `vec2<f32>`
      *
      * @param {*} v
-     * @param {string} target — destination type name, e.g. `'f32'` / `'u32'` / `'i32'`
+     * @param {string} target — destination type name, e.g. `'f32'`, `'u32'`, `'vec2<f16>'`, `'vec2h'`, `'vec2u'`
      * @param {string} [source] — source type name; required for unambiguous scalar casts
      * @returns {number | TypedArray}
      */

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":";IA4oDA;;;;;;;;;;;;;;OAcG;IACH,+DAmDC"}
+{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":";IAk0DA;;;;;;;;;;;;;OAaG;IACH,+DAyFC"}