@woosh/meep-engine 3.56.0 → 3.57.0

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

@@ -49,13 +49,26 @@ function gather_texel_coord(coords, texture) {
 const F16_SCRATCH = new Float16Array(1);
 
 /**
- * Shared scratch buffer for `bitcast` — three views over the same 4 bytes so we can
- * reinterpret one type as another in O(1) without per-call allocation.
+ * Round a number to IEEE 754 binary16 precision via Float16Array.
+ * @param {number} x
+ * @returns {number}
  */
-const BITCAST_BUFFER = new ArrayBuffer(4);
+function round_f16(x) {
+    F16_SCRATCH[0] = x;
+    return F16_SCRATCH[0];
+}
+
+/**
+ * Shared scratch buffer for `bitcast` and `pack2x16float` / `unpack2x16float` — four views over
+ * the same 16 bytes so we can reinterpret any 16- to 128-bit scalar or vector bit pattern (including
+ * width-changing `vec2<f16>` ↔ `u32`/`i32`/`f32` and `vec4<f16>` ↔ `vec2<u32>`/`vec2<i32>`/`vec2<f32>`)
+ * in O(1) without per-call allocation.
+ */
+const BITCAST_BUFFER = new ArrayBuffer(16);
 const BITCAST_U32 = new Uint32Array(BITCAST_BUFFER);
 const BITCAST_I32 = new Int32Array(BITCAST_BUFFER);
 const BITCAST_F32 = new Float32Array(BITCAST_BUFFER);
+const BITCAST_F16 = new Float16Array(BITCAST_BUFFER);
 
 /**
  * Construct a WGSL vector. Mirrors WGSL `vecN<T>(...)` semantics:
@@ -508,29 +521,41 @@ export const WGSLLanguageCore = {
      * @param {Float32Array|Float16Array} m
      */
     determinant(m) {
+        const is_f16 = m instanceof Float16Array;
+        const round = is_f16 ? round_f16 : Math.fround;
         if (m.length === 4) {
-            return m[0] * m[3] - m[1] * m[2];
+            return round(round(m[0] * m[3]) - round(m[1] * m[2]));
         }
         if (m.length === 9) {
-            return m[0] * (m[4] * m[8] - m[5] * m[7])
-                - m[3] * (m[1] * m[8] - m[2] * m[7])
-                + m[6] * (m[1] * m[5] - m[2] * m[4]);
+            const t0 = round(m[0] * round(round(m[4] * m[8]) - round(m[5] * m[7])));
+            const t1 = round(m[3] * round(round(m[1] * m[8]) - round(m[2] * m[7])));
+            const t2 = round(m[6] * round(round(m[1] * m[5]) - round(m[2] * m[4])));
+            return round(round(t0 - t1) + t2);
         }
         if (m.length === 16) {
             // 4x4 expansion via 2x2 minors of the bottom rows.
-            const s0 = m[0] * m[5] - m[1] * m[4];
-            const s1 = m[0] * m[6] - m[2] * m[4];
-            const s2 = m[0] * m[7] - m[3] * m[4];
-            const s3 = m[1] * m[6] - m[2] * m[5];
-            const s4 = m[1] * m[7] - m[3] * m[5];
-            const s5 = m[2] * m[7] - m[3] * m[6];
-            const c5 = m[10] * m[15] - m[11] * m[14];
-            const c4 = m[ 9] * m[15] - m[11] * m[13];
-            const c3 = m[ 9] * m[14] - m[10] * m[13];
-            const c2 = m[ 8] * m[15] - m[11] * m[12];
-            const c1 = m[ 8] * m[14] - m[10] * m[12];
-            const c0 = m[ 8] * m[13] - m[ 9] * m[12];
-            return s0 * c5 - s1 * c4 + s2 * c3 + s3 * c2 - s4 * c1 + s5 * c0;
+            const s0 = round(round(m[0] * m[5]) - round(m[1] * m[4]));
+            const s1 = round(round(m[0] * m[6]) - round(m[2] * m[4]));
+            const s2 = round(round(m[0] * m[7]) - round(m[3] * m[4]));
+            const s3 = round(round(m[1] * m[6]) - round(m[2] * m[5]));
+            const s4 = round(round(m[1] * m[7]) - round(m[3] * m[5]));
+            const s5 = round(round(m[2] * m[7]) - round(m[3] * m[6]));
+            const c5 = round(round(m[10] * m[15]) - round(m[11] * m[14]));
+            const c4 = round(round(m[ 9] * m[15]) - round(m[11] * m[13]));
+            const c3 = round(round(m[ 9] * m[14]) - round(m[10] * m[13]));
+            const c2 = round(round(m[ 8] * m[15]) - round(m[11] * m[12]));
+            const c1 = round(round(m[ 8] * m[14]) - round(m[10] * m[12]));
+            const c0 = round(round(m[ 8] * m[13]) - round(m[ 9] * m[12]));
+            return round(
+                round(
+                    round(
+                        round(round(round(s0 * c5) - round(s1 * c4)) + round(s2 * c3))
+                        + round(s3 * c2)
+                    )
+                    - round(s4 * c1)
+                )
+                + round(s5 * c0)
+            );
         }
         throw new Error(`determinant: unsupported matrix length ${m.length}`);
     },
@@ -597,6 +622,14 @@ export const WGSLLanguageCore = {
     sub_f32: (a, b) => binop(a, b, (x, y) => Math.fround(x - y)),
     mul_f32: (a, b) => binop(a, b, (x, y) => Math.fround(x * y)),
     div_f32: (a, b) => binop(a, b, (x, y) => Math.fround(x / y)),
+
+    // The same four at f16, for a SCALAR whose type the compiler knows is f16. Without these,
+    // scalar f16 arithmetic ran in f64 (`16000.0h * 8.0h` evaluated to 128000 instead of +Infinity,
+    // and `1e-3h * 1e-3h` evaluated to 1e-6 instead of underflowing in binary16).
+    add_f16: (a, b) => binop(a, b, (x, y) => round_f16(x + y)),
+    sub_f16: (a, b) => binop(a, b, (x, y) => round_f16(x - y)),
+    mul_f16: (a, b) => binop(a, b, (x, y) => round_f16(x * y)),
+    div_f16: (a, b) => binop(a, b, (x, y) => round_f16(x / y)),
     rem: (a, b) => binop(a, b, (x, y) => x % y),
 
     // Integer division — truncates toward zero, matching WGSL `/` semantics on integer types.
@@ -784,6 +817,7 @@ export const WGSLLanguageCore = {
     clamp: (x, lo, hi) => ternop(x, lo, hi, (v, l, h) => Math.max(l, Math.min(h, v))),
     // Saturate is `clamp(x, 0, 1)`. WGSL builtin.
     saturate: (a) => unop(a, x => Math.max(0, Math.min(1, x))),
+    quantizeToF16: (a) => unop(a, round_f16),
     mix: (a, b, t) => ternop(a, b, t, (x, y, k) => x * (1 - k) + y * k),
     // Fused multiply-add: `a * b + c`. JS lacks a true FMA; this is mathematically equivalent
     // but loses the single-rounding precision benefit of hardware FMA — fine for testing.
@@ -810,6 +844,21 @@ export const WGSLLanguageCore = {
     */
     dot(a, b) {
         assert.equal(a.length, b.length, 'dot vector length mismatch');
+        if (a instanceof Float16Array || b instanceof Float16Array) {
+            let s = 0;
+            for (let i = 0; i < a.length; i++) s = round_f16(s + round_f16(a[i] * b[i]));
+            return s;
+        }
+        if (a instanceof Int32Array || b instanceof Int32Array) {
+            let s = 0;
+            for (let i = 0; i < a.length; i++) s = (s + Math.imul(a[i], b[i])) | 0;
+            return s;
+        }
+        if (a instanceof Uint32Array || b instanceof Uint32Array) {
+            let s = 0;
+            for (let i = 0; i < a.length; i++) s = (s + Math.imul(a[i], b[i])) >>> 0;
+            return s;
+        }
         let s = 0;
         for (let i = 0; i < a.length; i++) s = Math.fround(s + Math.fround(a[i] * b[i]));
         return s;
@@ -817,6 +866,11 @@ export const WGSLLanguageCore = {
 
     length(v) {
         if (!is_vec(v)) return Math.abs(v);
+        if (v instanceof Float16Array) {
+            let s = 0;
+            for (let i = 0; i < v.length; i++) s = round_f16(s + round_f16(v[i] * v[i]));
+            return round_f16(Math.sqrt(s));
+        }
         let s = 0;
         for (let i = 0; i < v.length; i++) s = Math.fround(s + Math.fround(v[i] * v[i]));
         return Math.fround(Math.sqrt(s));
@@ -843,6 +897,13 @@ export const WGSLLanguageCore = {
     cross(a, b) {
         assert.equal(a.length, 3, 'cross requires vec3');
         assert.equal(b.length, 3, 'cross requires vec3');
+        if (a instanceof Float16Array) {
+            return new Float16Array([
+                round_f16(a[1] * b[2]) - round_f16(a[2] * b[1]),
+                round_f16(a[2] * b[0]) - round_f16(a[0] * b[2]),
+                round_f16(a[0] * b[1]) - round_f16(a[1] * b[0]),
+            ]);
+        }
         return new a.constructor([
             a[1] * b[2] - a[2] * b[1],
             a[2] * b[0] - a[0] * b[2],
@@ -850,20 +911,26 @@ export const WGSLLanguageCore = {
         ]);
     },
 
+    faceForward(e1, e2, e3) {
+        return WGSLLanguageCore.dot(e3, e2) < 0 ? copy_value(e1) : WGSLLanguageCore.neg(e1);
+    },
+
     reflect(i, n) {
-        const d = WGSLLanguageCore.dot(i, n);
+        const round = i instanceof Float16Array ? round_f16 : Math.fround;
+        const two_d = round(2 * WGSLLanguageCore.dot(i, n));
         const out = new i.constructor(i.length);
-        for (let k = 0; k < i.length; k++) out[k] = i[k] - 2 * d * n[k];
+        for (let k = 0; k < i.length; k++) out[k] = round(i[k] - round(two_d * n[k]));
         return out;
     },
 
     refract(i, n, eta) {
+        const round = i instanceof Float16Array ? round_f16 : Math.fround;
         const d = WGSLLanguageCore.dot(n, i);
-        const k = 1 - eta * eta * (1 - d * d);
+        const k = round(1 - round(round(eta * eta) * round(1 - round(d * d))));
         const out = new i.constructor(i.length);
         if (k < 0) { out.fill(0); return out; }
-        const normal_scale = eta * d + Math.sqrt(k);
-        for (let j = 0; j < i.length; j++) out[j] = eta * i[j] - normal_scale * n[j];
+        const normal_scale = round(round(eta * d) + round(Math.sqrt(k)));
+        for (let j = 0; j < i.length; j++) out[j] = round(round(eta * i[j]) - round(normal_scale * n[j]));
         return out;
     },
 
@@ -966,6 +1033,89 @@ export const WGSLLanguageCore = {
         return out;
     },
 
+    // f16 (half-precision) mat × column-vector, mat × mat, and row-vector × mat
+
+    m2x2h_multiply_v2h(m, v) {
+        const out = new Float16Array(2);
+        out[0] = round_f16(round_f16(m[0] * v[0]) + round_f16(m[2] * v[1]));
+        out[1] = round_f16(round_f16(m[1] * v[0]) + round_f16(m[3] * v[1]));
+        return out;
+    },
+
+    m3x3h_multiply_v3h(m, v) {
+        const out = new Float16Array(3);
+        out[0] = round_f16(round_f16(round_f16(m[0] * v[0]) + round_f16(m[3] * v[1])) + round_f16(m[6] * v[2]));
+        out[1] = round_f16(round_f16(round_f16(m[1] * v[0]) + round_f16(m[4] * v[1])) + round_f16(m[7] * v[2]));
+        out[2] = round_f16(round_f16(round_f16(m[2] * v[0]) + round_f16(m[5] * v[1])) + round_f16(m[8] * v[2]));
+        return out;
+    },
+
+    m4x4h_multiply_v4h(m, v) {
+        const out = new Float16Array(4);
+        out[0] = round_f16(round_f16(round_f16(round_f16(m[0] * v[0]) + round_f16(m[4] * v[1])) + round_f16(m[8]  * v[2])) + round_f16(m[12] * v[3]));
+        out[1] = round_f16(round_f16(round_f16(round_f16(m[1] * v[0]) + round_f16(m[5] * v[1])) + round_f16(m[9]  * v[2])) + round_f16(m[13] * v[3]));
+        out[2] = round_f16(round_f16(round_f16(round_f16(m[2] * v[0]) + round_f16(m[6] * v[1])) + round_f16(m[10] * v[2])) + round_f16(m[14] * v[3]));
+        out[3] = round_f16(round_f16(round_f16(round_f16(m[3] * v[0]) + round_f16(m[7] * v[1])) + round_f16(m[11] * v[2])) + round_f16(m[15] * v[3]));
+        return out;
+    },
+
+    m2x2h_multiply_m2x2h(a, b) {
+        const out = new Float16Array(4);
+        for (let j = 0; j < 2; j++) {
+            const b0 = b[j * 2], b1 = b[j * 2 + 1];
+            out[j * 2]     = round_f16(round_f16(a[0] * b0) + round_f16(a[2] * b1));
+            out[j * 2 + 1] = round_f16(round_f16(a[1] * b0) + round_f16(a[3] * b1));
+        }
+        return out;
+    },
+
+    m3x3h_multiply_m3x3h(a, b) {
+        const out = new Float16Array(9);
+        for (let j = 0; j < 3; j++) {
+            const b0 = b[j * 3], b1 = b[j * 3 + 1], b2 = b[j * 3 + 2];
+            out[j * 3]     = round_f16(round_f16(round_f16(a[0] * b0) + round_f16(a[3] * b1)) + round_f16(a[6] * b2));
+            out[j * 3 + 1] = round_f16(round_f16(round_f16(a[1] * b0) + round_f16(a[4] * b1)) + round_f16(a[7] * b2));
+            out[j * 3 + 2] = round_f16(round_f16(round_f16(a[2] * b0) + round_f16(a[5] * b1)) + round_f16(a[8] * b2));
+        }
+        return out;
+    },
+
+    m4x4h_multiply_m4x4h(a, b) {
+        const out = new Float16Array(16);
+        for (let j = 0; j < 4; j++) {
+            const b0 = b[j * 4], b1 = b[j * 4 + 1], b2 = b[j * 4 + 2], b3 = b[j * 4 + 3];
+            out[j * 4]     = round_f16(round_f16(round_f16(round_f16(a[0] * b0) + round_f16(a[4] * b1)) + round_f16(a[8]  * b2)) + round_f16(a[12] * b3));
+            out[j * 4 + 1] = round_f16(round_f16(round_f16(round_f16(a[1] * b0) + round_f16(a[5] * b1)) + round_f16(a[9]  * b2)) + round_f16(a[13] * b3));
+            out[j * 4 + 2] = round_f16(round_f16(round_f16(round_f16(a[2] * b0) + round_f16(a[6] * b1)) + round_f16(a[10] * b2)) + round_f16(a[14] * b3));
+            out[j * 4 + 3] = round_f16(round_f16(round_f16(round_f16(a[3] * b0) + round_f16(a[7] * b1)) + round_f16(a[11] * b2)) + round_f16(a[15] * b3));
+        }
+        return out;
+    },
+
+    v2h_multiply_m2x2h(v, m) {
+        const out = new Float16Array(2);
+        out[0] = round_f16(round_f16(v[0] * m[0]) + round_f16(v[1] * m[1]));
+        out[1] = round_f16(round_f16(v[0] * m[2]) + round_f16(v[1] * m[3]));
+        return out;
+    },
+
+    v3h_multiply_m3x3h(v, m) {
+        const out = new Float16Array(3);
+        out[0] = round_f16(round_f16(round_f16(v[0] * m[0]) + round_f16(v[1] * m[1])) + round_f16(v[2] * m[2]));
+        out[1] = round_f16(round_f16(round_f16(v[0] * m[3]) + round_f16(v[1] * m[4])) + round_f16(v[2] * m[5]));
+        out[2] = round_f16(round_f16(round_f16(v[0] * m[6]) + round_f16(v[1] * m[7])) + round_f16(v[2] * m[8]));
+        return out;
+    },
+
+    v4h_multiply_m4x4h(v, m) {
+        const out = new Float16Array(4);
+        out[0] = round_f16(round_f16(round_f16(round_f16(v[0] * m[0])  + round_f16(v[1] * m[1]))  + round_f16(v[2] * m[2]))  + round_f16(v[3] * m[3]));
+        out[1] = round_f16(round_f16(round_f16(round_f16(v[0] * m[4])  + round_f16(v[1] * m[5]))  + round_f16(v[2] * m[6]))  + round_f16(v[3] * m[7]));
+        out[2] = round_f16(round_f16(round_f16(round_f16(v[0] * m[8])  + round_f16(v[1] * m[9]))  + round_f16(v[2] * m[10])) + round_f16(v[3] * m[11]));
+        out[3] = round_f16(round_f16(round_f16(round_f16(v[0] * m[12]) + round_f16(v[1] * m[13])) + round_f16(v[2] * m[14])) + round_f16(v[3] * m[15]));
+        return out;
+    },
+
     // ---------------------------------------------------------------------
     // Logical / bit helpers
     // ---------------------------------------------------------------------
@@ -1603,6 +1753,19 @@ export const WGSLLanguageCore = {
     // Pack / unpack — fixed-point and float bit-level packers from the WGSL spec.
     // ---------------------------------------------------------------------
 
+    /** vec2<f32>(low_f16, high_f16) — unpacks two IEEE 754 binary16 values from a u32. */
+    unpack2x16float(e) {
+        BITCAST_U32[0] = e >>> 0;
+        return new Float32Array([BITCAST_F16[0], BITCAST_F16[1]]);
+    },
+
+    /** Inverse of unpack2x16float — rounds two f32/f16 components to binary16 and packs into a u32. */
+    pack2x16float(v) {
+        BITCAST_F16[0] = v[0];
+        BITCAST_F16[1] = v[1];
+        return BITCAST_U32[0];
+    },
+
     /** vec2<f32>(low_u16, high_u16) / 65535.0 — components in [0, 1]. */
     unpack2x16unorm(e) {
         const u = e >>> 0;
@@ -1677,67 +1840,104 @@ export const 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}
  */
 WGSLLanguageCore.bitcast = function (v, target, source) {
-    // Vector targets (`vec3<u32>` etc.) reduce to their scalar type — the runtime stores vectors
-    // as flat typed arrays, so the per-element bitcast is the same as for a scalar of that type.
-    const vec_match = typeof target === 'string' ? target.match(/^vec\d<([^>]+)>$/) : null;
-    if (vec_match !== null) {
-        target = vec_match[1];
-    }
+    const ALIAS_VEC = {
+        vec2i: [2, 'i32'], vec3i: [3, 'i32'], vec4i: [4, 'i32'],
+        vec2u: [2, 'u32'], vec3u: [3, 'u32'], vec4u: [4, 'u32'],
+        vec2f: [2, 'f32'], vec3f: [3, 'f32'], vec4f: [4, 'f32'],
+        vec2h: [2, 'f16'], vec3h: [3, 'f16'], vec4h: [4, 'f16'],
+    };
 
-    function convert_scalar(x, t_from, t_to) {
-        if (t_to === 'f32') {
-            if (t_from === 'u32') { BITCAST_U32[0] = x >>> 0; return BITCAST_F32[0]; }
-            if (t_from === 'i32') { BITCAST_I32[0] = x | 0; return BITCAST_F32[0]; }
-        } else if (t_to === 'u32') {
-            if (t_from === 'f32') { BITCAST_F32[0] = x; return BITCAST_U32[0]; }
-            if (t_from === 'i32') { return (x | 0) >>> 0; }
-        } else if (t_to === 'i32') {
-            if (t_from === 'f32') { BITCAST_F32[0] = x; return BITCAST_I32[0]; }
-            if (t_from === 'u32') { return (x >>> 0) | 0; }
+    let target_is_vec = false;
+    let target_len = 1;
+    let target_scalar = typeof target === 'string' ? target.trim() : 'f32';
+
+    if (ALIAS_VEC.hasOwnProperty(target_scalar)) {
+        target_is_vec = true;
+        [target_len, target_scalar] = ALIAS_VEC[target_scalar];
+    } else {
+        const vec_match = target_scalar.match(/^vec(\d)<\s*([^>\s]+)\s*>$/);
+        if (vec_match !== null) {
+            target_is_vec = true;
+            target_len = parseInt(vec_match[1]);
+            target_scalar = vec_match[2];
         }
-        return x;
     }
 
+    const viewFor = (s) => (
+        s === 'u32' ? BITCAST_U32
+        : s === 'i32' ? BITCAST_I32
+        : s === 'f16' ? BITCAST_F16
+        : BITCAST_F32
+    );
+    const ctorFor = (s) => (
+        s === 'u32' ? Uint32Array
+        : s === 'i32' ? Int32Array
+        : s === 'f16' ? Float16Array
+        : Float32Array
+    );
+
     if (is_vec(v)) {
-        let from = source;
-        if (from === undefined) {
-            if (v instanceof Float32Array) from = 'f32';
-            else if (v instanceof Float16Array) from = 'f16';
-            else if (v instanceof Uint32Array) from = 'u32';
-            else if (v instanceof Int32Array) from = 'i32';
-            else from = 'f32';
+        let from_scalar = source;
+        if (v instanceof Float16Array) from_scalar = 'f16';
+        else if (v instanceof Float32Array) from_scalar = 'f32';
+        else if (v instanceof Uint32Array) from_scalar = 'u32';
+        else if (v instanceof Int32Array) from_scalar = 'i32';
+        else if (from_scalar === undefined) from_scalar = 'f32';
+
+        const src_view = viewFor(from_scalar);
+        for (let i = 0; i < v.length; i++) {
+            src_view[i] = v[i];
         }
 
-        let outCtor;
-        if (target === 'f32') outCtor = Float32Array;
-        else if (target === 'f16') outCtor = Float16Array;
-        else if (target === 'u32') outCtor = Uint32Array;
-        else if (target === 'i32') outCtor = Int32Array;
-        else outCtor = v.constructor;
+        const dst_view = viewFor(target_scalar);
 
-        const out = new outCtor(v.length);
-        for (let i = 0; i < v.length; i++) {
-            out[i] = convert_scalar(v[i], from, target);
+        // Width-changing 32-bit pack: `bitcast<u32|i32|f32>(vec2<f16>)` returns a 32-bit scalar.
+        if (!target_is_vec && from_scalar === 'f16' && v.length === 2 && target_scalar !== 'f16') {
+            return dst_view[0];
+        }
+
+        // Otherwise return a vector (either target_len if target was explicitly a vec, or v.length
+        // if the caller passed a bare scalar name for an element-wise vector bitcast).
+        const out_len = target_is_vec ? target_len : v.length;
+        const out_ctor = ctorFor(target_scalar);
+        const out = new out_ctor(out_len);
+        for (let i = 0; i < out_len; i++) {
+            out[i] = dst_view[i];
         }
         return out;
     }
 
-    let from = source;
-    if (from === undefined) {
-        from = (target === 'f32' || target === 'f16') ? 'u32' : 'f32';
+    // Scalar input `v`
+    let from_scalar = source;
+    if (from_scalar === undefined) {
+        from_scalar = (target_scalar === 'f32' || target_scalar === 'f16') ? 'u32' : 'f32';
+    }
+
+    const src_view = viewFor(from_scalar);
+    src_view[0] = v;
+
+    const dst_view = viewFor(target_scalar);
+    if (target_is_vec) {
+        // Width-changing 32-bit unpack: `bitcast<vec2<f16>>(u32|i32|f32)` returns Float16Array(2).
+        const out_ctor = ctorFor(target_scalar);
+        const out = new out_ctor(target_len);
+        for (let i = 0; i < target_len; i++) {
+            out[i] = dst_view[i];
+        }
+        return out;
     }
-    return convert_scalar(v, from, target);
+
+    return dst_view[0];
 };

package/src/shade/wgsl/validate_wgsl_source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate_wgsl_source.d.ts","sourceRoot":"","sources":["../../../../src/shade/wgsl/validate_wgsl_source.js"],"names":[],"mappings":"AAqMA;;;;;;GAMG;AACH,6CAJW,MAAM,UACN,OAAO,iBAAiB,EAAE,UAAU,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAsP7D"}
+{"version":3,"file":"validate_wgsl_source.d.ts","sourceRoot":"","sources":["../../../../src/shade/wgsl/validate_wgsl_source.js"],"names":[],"mappings":"AAmNA;;;;;;GAMG;AACH,6CAJW,MAAM,UACN,OAAO,iBAAiB,EAAE,UAAU,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAkQ7D"}

package/src/shade/wgsl/validate_wgsl_source.js

@@ -25,6 +25,11 @@ import { WGSLLanguageCore } from "./emulator/WGSLLanguageCore.js";
  *    parameter, a `var` or a `let`. WGSL requires a const-declaration's initializer to be a
  *    const-expression, so these are rejected at `createShaderModule`; the emulator does not
  *    enforce const-ness, so a chunk written against it passes every spec and then cannot compile.
+ *  - unenabled-f16: using `f16`, a half-precision vector/matrix alias (`vec2h`..`vec4h`,
+ *    `mat2x2h`..`mat4x4h`), or a half-precision float literal (`1.0h`, `1e-4h`, `0x1p0h`) without
+ *    an `enable f16;` directive. The emulator parses and runs these without requiring `enable f16;`,
+ *    so a chunk that forgets `chunk.addExtension(WebGPUExtensionType.ShaderF16)` would otherwise
+ *    pass every emulator test and fail `createShaderModule` on a device.
  *
  * NOT yet enforced (would need full type inference; tracked under REVIEW_002 9.1): scalar
  * type mixing (u32/i32/f32), AbstractInt conversion failures, const-evaluability of
@@ -135,6 +140,15 @@ const WGSL_RESERVED_WORDS = [
 
 const RESERVED_WORD_RE = new RegExp(`\\b(?:${WGSL_RESERVED_WORDS.join('|')})\\b`, 'g');
 
+// Half-precision (`f16`) enable directive and tokens (WGSL §14.1.1, §3.4.3, §6.2.4–6.2.6).
+// Matches `enable f16;`, `enable subgroups, f16;`, etc.
+const F16_ENABLE_DIRECTIVE_RE = /\benable\s+[^;]*\bf16\b/;
+
+// Matches `f16`, `vec2h`..`vec4h`, `mat2x2h`..`mat4x4h`, hex float literals ending in `h`
+// (`0x1.8p-2h`), and decimal float literals ending in `h` (`1.0h`, `.5h`, `1e-4h`, `0h`) when not
+// preceded by an identifier/number character (`(?<![A-Za-z0-9_])` prevents matching `w1h` or `0x1h`).
+const F16_TOKEN_RE = /\b(?:f16|(?:vec[234]|mat[234]x[234])h|0[xX](?:[0-9a-fA-F]+\.[0-9a-fA-F]*|\.[0-9a-fA-F]+|[0-9a-fA-F]+)[pP][+-]?\d+h)\b|(?<![A-Za-z0-9_])(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?h\b/;
+
 /**
  * @param {Node} node
  * @returns {Node[]}
@@ -421,8 +435,9 @@ export function validate_wgsl_source(source, parser) {
         });
     }
 
-    // ── foreign-token (lexical) ──
+    // ── foreign-token, reserved-keyword, & unenabled-f16 (lexical) ──
     const stripped = strip_comments(source);
+    const f16_enabled = F16_ENABLE_DIRECTIVE_RE.test(stripped);
     const lines = stripped.split('\n');
     for (let i = 0; i < lines.length; i++) {
         for (const [pattern, label] of FOREIGN_TOKENS) {
@@ -443,6 +458,17 @@ export function validate_wgsl_source(source, parser) {
                 line: i + 1,
             });
         }
+
+        if (!f16_enabled) {
+            const f16_match = lines[i].match(F16_TOKEN_RE);
+            if (f16_match !== null) {
+                diagnostics.push({
+                    rule: 'unenabled-f16',
+                    message: `'${f16_match[0]}' requires 'enable f16;' (call chunk.addExtension(WebGPUExtensionType.ShaderF16))`,
+                    line: i + 1,
+                });
+            }
+        }
     }
 
     return diagnostics;

package/src/view/controller/controls/ListController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ListController.d.ts","sourceRoot":"","sources":["../../../../../src/view/controller/controls/ListController.js"],"names":[],"mappings":";AAIA;IACI;;;;;OAKG;IACH,gEAHuB,UAAU,EAoGhC;CACJ;uBA7GsB,iBAAiB"}
+{"version":3,"file":"ListController.d.ts","sourceRoot":"","sources":["../../../../../src/view/controller/controls/ListController.js"],"names":[],"mappings":";AAIA;IACI;;;;;OAKG;IACH,gEAHuB,UAAU,EAyGhC;CACJ;uBAlHsB,iBAAiB"}