@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/math/mat4x4/rotation-y.ts

@@ -0,0 +1,12 @@
+import type { Mat4x4 } from "./index.js";
+
+export const rotationY = (angle: number): Mat4x4 => {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return [
+        c, 0, -s, 0,
+        0, 1, 0, 0,
+        s, 0, c, 0,
+        0, 0, 0, 1
+    ];
+};

package/src/interface/math/mat4x4/rotation-z.ts

@@ -0,0 +1,12 @@
+import type { Mat4x4 } from "./index.js";
+
+export const rotationZ = (angle: number): Mat4x4 => {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return [
+        c, s, 0, 0,
+        -s, c, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1
+    ];
+};

package/src/interface/math/mat4x4/rotation.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "vitest";
+import { Mat4x4 } from "./index.js";
+import { Quat } from "../quat/index.js";
+
+const close = (actual: readonly number[], expected: readonly number[]): void =>
+    actual.forEach((value, index) => expect(value).toBeCloseTo(expected[index], 12));
+
+describe("rotations", () => {
+    test("turn counterclockwise about their axis, as the axis-angle quaternion does", () => {
+        close(Mat4x4.rotationX(0.7), Quat.toMat4(Quat.fromAxisAngle([1, 0, 0], 0.7)));
+        close(Mat4x4.rotationY(0.7), Quat.toMat4(Quat.fromAxisAngle([0, 1, 0], 0.7)));
+        close(Mat4x4.rotationZ(0.7), Quat.toMat4(Quat.fromAxisAngle([0, 0, 1], 0.7)));
+        close(Mat4x4.multiplyVec3(Mat4x4.rotationY(Math.PI / 2), [1, 0, 0]), [0, 0, -1]);
+        close(Mat4x4.multiplyVec3(Mat4x4.rotationZ(Math.PI / 2), [1, 0, 0]), [0, 1, 0]);
+    });
+});

package/src/interface/math/mat4x4/scale.ts

@@ -0,0 +1,9 @@
+import type { Mat4x4 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const scale = intrinsic({ wgsl: "*", form: "infix", parameters: ["mat4x4f", "f32"], result: "mat4x4f" }, (m: Mat4x4, s: number): Mat4x4 => [
+    m[0] * s, m[1] * s, m[2] * s, m[3] * s,
+    m[4] * s, m[5] * s, m[6] * s, m[7] * s,
+    m[8] * s, m[9] * s, m[10] * s, m[11] * s,
+    m[12] * s, m[13] * s, m[14] * s, m[15] * s
+]);

package/src/interface/math/mat4x4/scaling.ts

@@ -0,0 +1,8 @@
+import type { Mat4x4 } from "./index.js";
+
+export const scaling = (x: number, y: number, z: number): Mat4x4 => [
+    x, 0, 0, 0,
+    0, y, 0, 0,
+    0, 0, z, 0,
+    0, 0, 0, 1
+];

package/src/interface/math/mat4x4/schema.ts

@@ -0,0 +1,4 @@
+import type { Schema } from "../../schema/schema.js";
+import { schema as item } from "../f32/schema.js";
+
+export const schema = { type: "array", items: item, minItems: 16, maxItems: 16 } as const satisfies Schema;

package/src/interface/math/mat4x4/subtract.ts

@@ -0,0 +1,9 @@
+import type { Mat4x4 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const subtract = intrinsic({ wgsl: "-", form: "infix", parameters: ["mat4x4f", "mat4x4f"], result: "mat4x4f" }, (a: Mat4x4, b: Mat4x4): Mat4x4 => [
+    a[0] - b[0], a[1] - b[1], a[2] - b[2], a[3] - b[3],
+    a[4] - b[4], a[5] - b[5], a[6] - b[6], a[7] - b[7],
+    a[8] - b[8], a[9] - b[9], a[10] - b[10], a[11] - b[11],
+    a[12] - b[12], a[13] - b[13], a[14] - b[14], a[15] - b[15]
+]);

package/src/interface/math/mat4x4/translation.ts

@@ -0,0 +1,8 @@
+import type { Mat4x4 } from "./index.js";
+
+export const translation = (x: number, y: number, z: number): Mat4x4 => [
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    x, y, z, 1
+];

package/src/interface/math/mat4x4/transpose.ts

@@ -0,0 +1,9 @@
+import type { Mat4x4 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const transpose = intrinsic({ wgsl: "transpose", parameters: ["mat4x4f"], result: "mat4x4f" }, (m: Mat4x4): Mat4x4 => [
+    m[0], m[4], m[8], m[12],
+    m[1], m[5], m[9], m[13],
+    m[2], m[6], m[10], m[14],
+    m[3], m[7], m[11], m[15]
+]);

package/src/interface/math/mat4x4/zero.ts

@@ -0,0 +1,8 @@
+import type { Mat4x4 } from "./index.js";
+
+export const zero: Mat4x4 = [
+    0, 0, 0, 0,
+    0, 0, 0, 0,
+    0, 0, 0, 0,
+    0, 0, 0, 0
+];

package/src/interface/math/math.type-test.ts

@@ -0,0 +1,20 @@
+import { Mat4x4, Quat, Vec2, Vec3, Vec4 } from '../index.js';
+
+// Each type is also a namespace of functions; `Vec3` is `Vec3.F32`, with integer vectors nested beside it.
+const position: Vec3 = [1, 2, 3];
+const float: Vec3.F32 = Vec3.F32.add(position, [1, 1, 1]);
+const integer: Vec3.I32 = Vec3.I32.add([1, 2, 3], [4, 5, 6]);
+const unsigned: Vec3.U32 = Vec3.U32.bitwiseAnd([7, 7, 7], [1, 2, 4]);
+const length: number = Vec3.length(float);
+const texel: Vec2 = Vec2.scale([1, 2], 2);
+const color: Vec4 = Vec4.mix([0, 0, 0, 1], [1, 1, 1, 1], 0.5);
+const rotation: Quat = Quat.fromAxisAngle([0, 0, 1], length);
+const transform: Mat4x4 = Mat4x4.multiply(Mat4x4.identity, Quat.toMat4(rotation));
+
+// @ts-expect-error a Vec3 has three elements
+const wrong: Vec3 = [1, 2];
+
+export const used = [integer, unsigned, texel, color, transform, wrong];
+
+// @ts-expect-error vectors are read-only values
+position[0] = 1;

package/src/interface/math/quat/add.ts

@@ -0,0 +1,9 @@
+import type { Quat } from "../index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const add = intrinsic({ wgsl: "+", form: "infix", parameters: ["vec4f", "vec4f"], result: "vec4f" }, ([x1, y1, z1, w1]: Quat, [x2, y2, z2, w2]: Quat): Quat => [
+    x1 + x2,
+    y1 + y2,
+    z1 + z2,
+    w1 + w2
+]);

package/src/interface/math/quat/align-to.ts

@@ -0,0 +1,44 @@
+import type { Quat } from "../index.js";
+import type { Vec3 } from "../vec3/index.js";
+import { Vec3 as Vec3Namespace } from "../vec3/index.js";
+import { fromAxisAngle } from "./from-axis-angle.js";
+import { identity } from "./identity.js";
+import { multiply } from "./multiply.js";
+
+/**
+ * Returns a quaternion that aligns the local Z-axis to the given direction via the shortest arc,
+ * then applies an additional twist around that aligned Z-axis.
+ *
+ * Note: This aligns the Z axis.
+ *
+ * @param direction - Target world-space direction for local Z. If zero-length, returns identity.
+ * @param twistRadians - Extra rotation around the aligned Z-axis, in radians. Defaults to 0.
+ */
+export const alignTo = (direction: Vec3, twistRadians: number = 0): Quat => {
+    const zAxis: Vec3 = [0, 0, 1];
+    const dirLen = Vec3Namespace.length(direction);
+    if (dirLen === 0) return identity;
+
+    const dir = Vec3Namespace.normalize(direction);
+    const dotVal = Vec3Namespace.dot(zAxis, dir);
+
+    let base: Quat;
+    if (dotVal > 0.999999) {
+        base = identity;
+    } else if (dotVal < -0.999999) {
+        // Opposite: 180° around any axis orthogonal to Z
+        const orthoCandidate: Vec3 = [1, 0, 0];
+        const axis = Math.abs(Vec3Namespace.dot(zAxis, orthoCandidate)) > 0.999 ? [0, 1, 0] as Vec3 : orthoCandidate;
+        base = fromAxisAngle(axis, Math.PI);
+    } else {
+        const axis = Vec3Namespace.normalize(Vec3Namespace.cross(zAxis, dir));
+        const angle = Math.acos(dotVal);
+        base = fromAxisAngle(axis, angle);
+    }
+
+    if (twistRadians === 0) return base;
+
+    // Twist around the final aligned Z (which is 'dir' in world space)
+    const twist = fromAxisAngle(dir, twistRadians);
+    return multiply(twist, base);
+};

package/src/interface/math/quat/conjugate.ts

@@ -0,0 +1,3 @@
+import type { Quat } from "../index.js";
+
+export const conjugate = ([x, y, z, w]: Quat): Quat => [-x, -y, -z, w];

package/src/interface/math/quat/distance.ts

@@ -0,0 +1,5 @@
+import type { Quat } from "../index.js";
+import { length } from "./length.js";
+import { subtract } from "./subtract.js";
+
+export const distance = (a: Quat, b: Quat): number => length(subtract(b, a));

package/src/interface/math/quat/dot.ts

@@ -0,0 +1,5 @@
+import type { Quat } from "../index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const dot = intrinsic({ wgsl: "dot", parameters: ["vec4f", "vec4f"], result: "f32" }, ([x1, y1, z1, w1]: Quat, [x2, y2, z2, w2]: Quat): number =>
+    x1 * x2 + y1 * y2 + z1 * z2 + w1 * w2);

package/src/interface/math/quat/from-axis-angle.ts

@@ -0,0 +1,14 @@
+import type { Quat } from "../index.js";
+import type { Vec3 } from "../vec3/index.js";
+import { identity } from "./identity.js";
+
+export const fromAxisAngle = (axis: Vec3, angle: number): Quat => {
+    const halfAngle = angle * 0.5;
+    const s = Math.sin(halfAngle);
+    const c = Math.cos(halfAngle);
+    // Normalize the axis to ensure a unit quaternion
+    const len = Math.sqrt(axis[0] * axis[0] + axis[1] * axis[1] + axis[2] * axis[2]);
+    if (len === 0) return identity;
+    const invLen = 1 / len;
+    return [axis[0] * invLen * s, axis[1] * invLen * s, axis[2] * invLen * s, c];
+};

package/src/interface/math/quat/from-euler.ts

@@ -0,0 +1,17 @@
+import type { Quat } from "../index.js";
+
+export const fromEuler = (x: number, y: number, z: number): Quat => {
+    const cx = Math.cos(x * 0.5);
+    const sx = Math.sin(x * 0.5);
+    const cy = Math.cos(y * 0.5);
+    const sy = Math.sin(y * 0.5);
+    const cz = Math.cos(z * 0.5);
+    const sz = Math.sin(z * 0.5);
+
+    return [
+        sx * cy * cz - cx * sy * sz,
+        cx * sy * cz + sx * cy * sz,
+        cx * cy * sz - sx * sy * cz,
+        cx * cy * cz + sx * sy * sz
+    ];
+};

package/src/interface/math/quat/identity.ts

@@ -0,0 +1,3 @@
+import type { Quat } from "../index.js";
+
+export const identity: Quat = [0, 0, 0, 1];

package/src/interface/math/quat/index.ts

@@ -0,0 +1,3 @@
+export type Quat = readonly [number, number, number, number];
+
+export * as Quat from "./public.js";

package/src/interface/math/quat/inverse.ts

@@ -0,0 +1,10 @@
+import type { Quat } from "../index.js";
+import { conjugate } from "./conjugate.js";
+import { lengthSquared } from "./length-squared.js";
+import { scale } from "./scale.js";
+
+export const inverse = (q: Quat): Quat => {
+    const lenSq = lengthSquared(q);
+    if (lenSq === 0) return [0, 0, 0, 1];
+    return scale(conjugate(q), 1 / lenSq);
+};

package/src/interface/math/quat/length-squared.ts

@@ -0,0 +1,3 @@
+import type { Quat } from "../index.js";
+
+export const lengthSquared = ([x, y, z, w]: Quat): number => x * x + y * y + z * z + w * w;

package/src/interface/math/quat/length.ts

@@ -0,0 +1,4 @@
+import type { Quat } from "../index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const length = intrinsic({ wgsl: "length", parameters: ["vec4f"], result: "f32" }, ([x, y, z, w]: Quat): number => Math.sqrt(x * x + y * y + z * z + w * w));

package/src/interface/math/quat/lerp.ts

@@ -0,0 +1,8 @@
+import type { Quat } from "../index.js";
+import { add } from "./add.js";
+import { normalize } from "./normalize.js";
+import { scale } from "./scale.js";
+
+export const lerp = (q1: Quat, q2: Quat, t: number): Quat => {
+    return normalize(add(scale(q1, 1 - t), scale(q2, t)));
+};

package/src/interface/math/quat/look-at.ts

@@ -0,0 +1,52 @@
+import type { Quat } from "../index.js";
+import type { Vec3 } from "../vec3/index.js";
+import { Vec3 as Vec3Namespace } from "../vec3/index.js";
+
+export const lookAt = (forward: Vec3, up: Vec3): Quat => {
+    // Normalize forward vector
+    const f = Vec3Namespace.length(forward) === 0 ? Vec3Namespace.zero : Vec3Namespace.normalize(forward);
+
+    // Calculate right vector; it is zero when up is parallel to forward
+    const right = Vec3Namespace.cross(f, up);
+    const r = Vec3Namespace.length(right) === 0 ? Vec3Namespace.zero : Vec3Namespace.normalize(right);
+
+    // Recalculate up vector
+    const u = Vec3Namespace.cross(r, f);
+
+    // Convert to quaternion
+    const trace = r[0] + u[1] + f[2];
+
+    if (trace > 0) {
+        const s = Math.sqrt(trace + 1) * 2;
+        return [
+            (u[2] - f[1]) / s,
+            (f[0] - r[2]) / s,
+            (r[1] - u[0]) / s,
+            0.25 * s
+        ];
+    } else if (r[0] > u[1] && r[0] > f[2]) {
+        const s = Math.sqrt(1 + r[0] - u[1] - f[2]) * 2;
+        return [
+            0.25 * s,
+            (u[0] + r[1]) / s,
+            (f[0] + r[2]) / s,
+            (u[2] - f[1]) / s
+        ];
+    } else if (u[1] > f[2]) {
+        const s = Math.sqrt(1 + u[1] - r[0] - f[2]) * 2;
+        return [
+            (u[0] + r[1]) / s,
+            0.25 * s,
+            (f[1] + u[2]) / s,
+            (f[0] - r[2]) / s
+        ];
+    } else {
+        const s = Math.sqrt(1 + f[2] - r[0] - u[1]) * 2;
+        return [
+            (f[0] + r[2]) / s,
+            (f[1] + u[2]) / s,
+            0.25 * s,
+            (r[1] - u[0]) / s
+        ];
+    }
+};

package/src/interface/math/quat/multiply.ts

@@ -0,0 +1,8 @@
+import type { Quat } from "../index.js";
+
+export const multiply = ([x1, y1, z1, w1]: Quat, [x2, y2, z2, w2]: Quat): Quat => [
+    x1 * w2 + w1 * x2 + y1 * z2 - z1 * y2,
+    y1 * w2 + w1 * y2 + z1 * x2 - x1 * z2,
+    z1 * w2 + w1 * z2 + x1 * y2 - y1 * x2,
+    w1 * w2 - x1 * x2 - y1 * y2 - z1 * z2
+];

package/src/interface/math/quat/negate.ts

@@ -0,0 +1,4 @@
+import type { Quat } from "../index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const negate = intrinsic({ wgsl: "-", form: "prefix", parameters: ["vec4f"], result: "vec4f" }, ([x, y, z, w]: Quat): Quat => [-x, -y, -z, -w]);

package/src/interface/math/quat/normalize.ts

@@ -0,0 +1,8 @@
+import type { Quat } from "../index.js";
+import { length } from "./length.js";
+import { scale } from "./scale.js";
+
+export const normalize = (q: Quat): Quat => {
+    const len = length(q);
+    return len === 0 ? [0, 0, 0, 1] : scale(q, 1 / len);
+};

package/src/interface/math/quat/public.ts

@@ -0,0 +1,24 @@
+export * from "./add.js";
+export * from "./align-to.js";
+export * from "./conjugate.js";
+export * from "./distance.js";
+export * from "./dot.js";
+export * from "./from-axis-angle.js";
+export * from "./from-euler.js";
+export * from "./identity.js";
+export * from "./inverse.js";
+export * from "./length-squared.js";
+export * from "./length.js";
+export * from "./lerp.js";
+export * from "./look-at.js";
+export * from "./multiply.js";
+export * from "./negate.js";
+export * from "./normalize.js";
+export * from "./rotate-vec3.js";
+export * from "./scale.js";
+export * from "./slerp.js";
+export * from "./subtract.js";
+export * from "./to-axis-angle.js";
+export * from "./to-euler.js";
+export * from "./to-mat4.js";
+export * from "./schema.js";

package/src/interface/math/quat/rotate-vec3.ts

@@ -0,0 +1,16 @@
+import type { Quat } from "../index.js";
+import type { Vec3 } from "../vec3/index.js";
+import { Vec3 as Vec3Namespace } from "../vec3/index.js";
+
+export const rotateVec3 = ([x, y, z, w]: Quat, v: Vec3): Vec3 => {
+    // q * v * q^-1
+    const qv: Vec3 = [x, y, z];
+    const uv = Vec3Namespace.cross(qv, v);
+    const uuv = Vec3Namespace.cross(qv, uv);
+    const scaleFactor = 2 * w;
+    return [
+        v[0] + scaleFactor * uv[0] + 2 * uuv[0],
+        v[1] + scaleFactor * uv[1] + 2 * uuv[1],
+        v[2] + scaleFactor * uv[2] + 2 * uuv[2]
+    ];
+};

package/src/interface/math/quat/scale.ts

@@ -0,0 +1,4 @@
+import type { Quat } from "../index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const scale = intrinsic({ wgsl: "*", form: "infix", parameters: ["vec4f", "f32"], result: "vec4f" }, ([x, y, z, w]: Quat, s: number): Quat => [x * s, y * s, z * s, w * s]);

package/src/interface/math/quat/schema.ts

@@ -0,0 +1,4 @@
+import type { Schema } from "../../schema/schema.js";
+import { schema as item } from "../f32/schema.js";
+
+export const schema = { type: "array", items: item, minItems: 4, maxItems: 4 } as const satisfies Schema;

package/src/interface/math/quat/slerp.ts

@@ -0,0 +1,26 @@
+import type { Quat } from "../index.js";
+import { add } from "./add.js";
+import { dot } from "./dot.js";
+import { negate } from "./negate.js";
+import { normalize } from "./normalize.js";
+import { scale } from "./scale.js";
+
+export const slerp = (q1: Quat, q2: Quat, t: number): Quat => {
+    const dotProduct = dot(q1, q2);
+
+    // If the dot product is negative, slerp won't take the shorter route
+    const q2Adjusted = dotProduct < 0 ? negate(q2) : q2;
+    const adjustedDot = Math.abs(dotProduct);
+
+    // If the inputs are too close for comfort, linearly interpolate
+    if (adjustedDot > 0.9995) {
+        return normalize(add(scale(q1, 1 - t), scale(q2Adjusted, t)));
+    }
+
+    const theta = Math.acos(adjustedDot);
+    const sinTheta = Math.sin(theta);
+    const factor1 = Math.sin((1 - t) * theta) / sinTheta;
+    const factor2 = Math.sin(t * theta) / sinTheta;
+
+    return normalize(add(scale(q1, factor1), scale(q2Adjusted, factor2)));
+};

package/src/interface/math/quat/subtract.ts

@@ -0,0 +1,9 @@
+import type { Quat } from "../index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const subtract = intrinsic({ wgsl: "-", form: "infix", parameters: ["vec4f", "vec4f"], result: "vec4f" }, ([x1, y1, z1, w1]: Quat, [x2, y2, z2, w2]: Quat): Quat => [
+    x1 - x2,
+    y1 - y2,
+    z1 - z2,
+    w1 - w2
+]);

package/src/interface/math/quat/to-axis-angle.ts

@@ -0,0 +1,14 @@
+import type { Quat } from "../index.js";
+import type { Vec3 } from "../vec3/index.js";
+
+export const toAxisAngle = ([x, y, z, w]: Quat): { axis: Vec3; angle: number } => {
+    const angle = 2 * Math.acos(Math.abs(w));
+    const s = Math.sin(angle * 0.5);
+    if (s === 0) {
+        return { axis: [0, 0, 1], angle: 0 };
+    }
+    return {
+        axis: [x / s, y / s, z / s],
+        angle: w < 0 ? -angle : angle
+    };
+};

package/src/interface/math/quat/to-euler.ts

@@ -0,0 +1,25 @@
+import type { Quat } from "../index.js";
+import type { Vec3 } from "../vec3/index.js";
+
+export const toEuler = ([x, y, z, w]: Quat): Vec3 => {
+    // Roll (x-axis rotation)
+    const sinr_cosp = 2 * (w * x + y * z);
+    const cosr_cosp = 1 - 2 * (x * x + y * y);
+    const roll = Math.atan2(sinr_cosp, cosr_cosp);
+
+    // Pitch (y-axis rotation)
+    const sinp = 2 * (w * y - z * x);
+    let pitch;
+    if (Math.abs(sinp) >= 1) {
+        pitch = Math.sign(sinp) * Math.PI / 2; // use 90 degrees if out of range
+    } else {
+        pitch = Math.asin(sinp);
+    }
+
+    // Yaw (z-axis rotation)
+    const siny_cosp = 2 * (w * z + x * y);
+    const cosy_cosp = 1 - 2 * (y * y + z * z);
+    const yaw = Math.atan2(siny_cosp, cosy_cosp);
+
+    return [roll, pitch, yaw];
+};

package/src/interface/math/quat/to-mat4.ts

@@ -0,0 +1,27 @@
+import type { Quat } from "../index.js";
+import type { Mat4x4 } from "../mat4x4/index.js";
+
+/**
+ * Converts a quaternion to a 4x4 rotation matrix in column-major order.
+ * The resulting matrix is compatible with WebGPU and can be directly used
+ * with Mat4x4 operations.
+ */
+export const toMat4 = ([x, y, z, w]: Quat): Mat4x4 => {
+    const xx = x * x;
+    const yy = y * y;
+    const zz = z * z;
+    const xy = x * y;
+    const xz = x * z;
+    const yz = y * z;
+    const wx = w * x;
+    const wy = w * y;
+    const wz = w * z;
+
+    // Column-major format (WebGPU standard)
+    return [
+        1 - 2 * (yy + zz), 2 * (xy + wz), 2 * (xz - wy), 0,
+        2 * (xy - wz), 1 - 2 * (xx + zz), 2 * (yz + wx), 0,
+        2 * (xz + wy), 2 * (yz - wx), 1 - 2 * (xx + yy), 0,
+        0, 0, 0, 1
+    ];
+};

package/src/interface/math/semantics.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { U32, Vec2, Vec3, Vec4 } from "./index.js";
+
+/** The bit-at-a-time definitions the loop-free versions must agree with. */
+const reference = {
+    countOneBits: (n: number): number => [...(n >>> 0).toString(2)].filter(bit => bit === "1").length,
+    countTrailingZeros: (n: number): number => (n >>> 0) === 0 ? 32 : (n >>> 0).toString(2).length - 1 - (n >>> 0).toString(2).lastIndexOf("1"),
+    reverseBits: (n: number): number => parseInt([...(n >>> 0).toString(2).padStart(32, "0")].reverse().join(""), 2),
+};
+
+describe("math follows WGSL", () => {
+    test("bit counts and reversal agree with their bitwise definitions", () => {
+        let seed = 12345;
+        const values = [0, 1, 2, 3, 0x80000000, 0xFFFFFFFF, 0x7FFFFFFF, 0x55555555, -1, -(2 ** 31)];
+        for (let i = 0; i < 1000; i++) values.push(seed = (Math.imul(seed, 1103515245) + 12345) >>> 0);
+        for (const value of values) {
+            expect(U32.countOneBits(value)).toBe(reference.countOneBits(value));
+            expect(U32.countTrailingZeros(value)).toBe(reference.countTrailingZeros(value));
+            expect(U32.reverseBits(value)).toBe(reference.reverseBits(value));
+        }
+        expect(Vec3.I32.reverseBits([1, 0, 0])).toEqual([-(2 ** 31), 0, 0]);
+    });
+
+    test("round sends halfway values to the even integer", () => {
+        expect(Vec4.round([0.5, 1.5, 2.5, -2.5])).toEqual([0, 2, 2, -2]);
+        expect(Vec3.round([-0.5, 0.49999999999999994, 2.6])).toEqual([-0, 0, 3]);
+        expect(Vec2.round([1e300, -1.5])).toEqual([1e300, -2]);
+    });
+
+    test("mod is x - m * floor(x / m)", () => {
+        expect(Vec3.mod([5.5, -1, -7], 3)).toEqual([2.5, 2, 2]);
+        expect(Vec2.mod([1, -1], -3)).toEqual([-2, -1]);
+    });
+
+    test("integer vectors wrap", () => {
+        expect(Vec3.I32.add([2 ** 31 - 1, -(2 ** 31), 0], [1, -1, 0])).toEqual([-(2 ** 31), 2 ** 31 - 1, 0]);
+        expect(Vec3.I32.subtract([-(2 ** 31), 0, 0], [1, 0, 0])).toEqual([2 ** 31 - 1, 0, 0]);
+        expect(Vec3.I32.multiply([65536, 3, 0], [65536, -4, 0])).toEqual([0, -12, 0]);
+        expect(Vec3.I32.negate([-(2 ** 31), 1, 0])).toEqual([-(2 ** 31), -1, 0]);
+        expect(Vec3.I32.abs([-(2 ** 31), -5, 0])).toEqual([-(2 ** 31), 5, 0]);
+        // Products above 2 ** 53 keep their low bits.
+        expect(Vec3.U32.multiply([0xFFFFFFFF, 0x10001, 0], [0xFFFFFFFF, 0x10001, 0])).toEqual([1, 0x20001, 0]);
+        expect(Vec3.U32.volume([0xFFFFFFFF, 0xFFFFFFFF, 3])).toBe(3);
+    });
+
+    test("normalize is scale by the inverse length", () => {
+        expect(Vec3.normalize([0, 0, 2])).toEqual([0, 0, 1]);
+        expect(Vec3.normalize([0, 0, 0]).every(Number.isNaN)).toBe(true);
+    });
+});

package/src/interface/math/u32/count-leading-zeros.ts

@@ -0,0 +1,4 @@
+import type { U32 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const countLeadingZeros = intrinsic({ wgsl: "countLeadingZeros", parameters: ["u32"], result: "u32" }, (n: U32): U32 => Math.clz32(n >>> 0));

package/src/interface/math/u32/count-one-bits.ts

@@ -0,0 +1,10 @@
+import type { U32 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const countOneBits = intrinsic({ wgsl: "countOneBits", parameters: ["u32"], result: "u32" }, (n: U32): U32 => {
+    let x = n >>> 0;
+    x = x - ((x >>> 1) & 0x55555555);
+    x = (x & 0x33333333) + ((x >>> 2) & 0x33333333);
+    x = (x + (x >>> 4)) & 0x0f0f0f0f;
+    return Math.imul(x, 0x01010101) >>> 24;
+});

package/src/interface/math/u32/count-trailing-zeros.ts

@@ -0,0 +1,7 @@
+import type { U32 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const countTrailingZeros = intrinsic({ wgsl: "countTrailingZeros", parameters: ["u32"], result: "u32" }, (n: U32): U32 => {
+    const v = n >>> 0;
+    return v === 0 ? 32 : 31 - Math.clz32(v & -v);
+});

package/src/interface/math/u32/index.ts

@@ -0,0 +1,4 @@
+/** Integers in [0, 2^32). Functions wrap as WGSL's u32 does; for other values their results are indeterminate. */
+export type U32 = number;
+
+export * as U32 from "./public.js";

package/src/interface/math/u32/public.ts

@@ -0,0 +1,6 @@
+export { schema } from "./schema.js";
+export { countLeadingZeros } from "./count-leading-zeros.js";
+export { countTrailingZeros } from "./count-trailing-zeros.js";
+export { countOneBits } from "./count-one-bits.js";
+export { reverseBits } from "./reverse-bits.js";
+export { shiftRight } from "./shift-right.js";

package/src/interface/math/u32/reverse-bits.ts

@@ -0,0 +1,11 @@
+import type { U32 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const reverseBits = intrinsic({ wgsl: "reverseBits", parameters: ["u32"], result: "u32" }, (n: U32): U32 => {
+    let x = n >>> 0;
+    x = ((x >>> 1) & 0x55555555) | ((x & 0x55555555) << 1);
+    x = ((x >>> 2) & 0x33333333) | ((x & 0x33333333) << 2);
+    x = ((x >>> 4) & 0x0f0f0f0f) | ((x & 0x0f0f0f0f) << 4);
+    x = ((x >>> 8) & 0x00ff00ff) | ((x & 0x00ff00ff) << 8);
+    return ((x >>> 16) | (x << 16)) >>> 0;
+});

package/src/interface/math/u32/schema.ts

@@ -0,0 +1,3 @@
+import type { Schema } from "../../schema/schema.js";
+
+export const schema = { type: "integer", minimum: 0, maximum: 0xFFFFFFFF } as const satisfies Schema;

package/src/interface/math/u32/shift-right.ts

@@ -0,0 +1,3 @@
+import type { U32 } from "./index.js";
+
+export const shiftRight = (n: U32, shift: number): U32 => (n >>> shift) >>> 0;