@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { I32 } from "./index.js";
+
+export const shiftRight = (n: I32, shift: number): I32 => n >> shift;

package/src/interface/math/index.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./f32/index.js";
+export * from "./i32/index.js";
+export * from "./u32/index.js";
+export * from "./vec2/index.js";
+export * from "./vec3/index.js";
+export * from "./vec4/index.js";
+export * from "./quat/index.js";
+export * from "./mat4x4/index.js";

package/src/interface/math/intrinsic.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/** A WGSL value type an intrinsic takes or returns, made of one lane per scalar leaf. */
+export type WgslType =
+    | "f32" | "i32" | "u32"
+    | "vec2f" | "vec3f" | "vec4f" | "vec2i" | "vec3i" | "vec4i" | "vec2u" | "vec3u" | "vec4u"
+    | "mat4x4f";
+
+/**
+ * Declares the WGSL builtin a math function matches, so GPU kernels emit `wgsl` for calls to it: a function, or with
+ * `form`, an operator between or before its operands. Other backends inline `implementation`, which is returned as is.
+ * The compiler reads the declaration from source, so it is written as literals.
+ */
+export const intrinsic = <F>(
+    declaration: { readonly wgsl: string; readonly form?: "infix" | "prefix"; readonly parameters: readonly WgslType[]; readonly result: WgslType },
+    implementation: F,
+): F => {
+    void declaration;
+    return implementation;
+};

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

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const add = 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/determinant.ts

@@ -0,0 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const determinant = intrinsic({ wgsl: "determinant", parameters: ["mat4x4f"], result: "f32" }, (m: Mat4x4): number => {
+    const [
+        m00, m01, m02, m03,
+        m10, m11, m12, m13,
+        m20, m21, m22, m23,
+        m30, m31, m32, m33
+    ] = m;
+
+    const b00 = m00 * m11 - m01 * m10;
+    const b01 = m00 * m12 - m02 * m10;
+    const b02 = m00 * m13 - m03 * m10;
+    const b03 = m01 * m12 - m02 * m11;
+    const b04 = m01 * m13 - m03 * m11;
+    const b05 = m02 * m13 - m03 * m12;
+    const b06 = m20 * m31 - m21 * m30;
+    const b07 = m20 * m32 - m22 * m30;
+    const b08 = m20 * m33 - m23 * m30;
+    const b09 = m21 * m32 - m22 * m31;
+    const b10 = m21 * m33 - m23 * m31;
+    const b11 = m22 * m33 - m23 * m32;
+
+    return b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+});

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

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+
+export const identity: Mat4x4 = [
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1
+];

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

@@ -0,0 +1,29 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../schema/schema.js";
+import type { schema } from "./schema.js";
+
+export type Mat4x4 = Schema.Type<typeof schema>;
+
+/**
+ * 4x4 Matrix operations using column-major order (WebGPU standard).
+ * 
+ * Matrix Layout:
+ * Matrices are stored in column-major order as flat arrays of 16 elements.
+ * This matches WebGPU's memory layout and shader expectations.
+ * 
+ * Layout: [m0, m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, m11, m12, m13, m14, m15]
+ * 
+ * Which represents:
+ * ┌                    ┐
+ * │ m0  m4  m8   m12  │  (Column 0, 1, 2, 3)
+ * │ m1  m5  m9   m13  │
+ * │ m2  m6  m10  m14  │
+ * │ m3  m7  m11  m15  │
+ * └                    ┘
+ * 
+ * For transformation matrices (position, rotation, scale):
+ * - Columns 0-2 (m0-m2, m4-m6, m8-m10): Rotation/scale basis vectors (right, up, forward)
+ * - Column 3 (m12, m13, m14): Translation (x, y, z)
+ * - Row 3 (m3, m7, m11, m15): Perspective (usually 0, 0, 0, 1)
+ */
+export * as Mat4x4 from "./public.js";

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

@@ -0,0 +1,50 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import { determinant } from "./determinant.js";
+
+export const inverse = (m: Mat4x4): Mat4x4 => {
+    const det = determinant(m);
+    if (det === 0) {
+        throw new Error('Matrix is not invertible');
+    }
+
+    const [
+        m00, m01, m02, m03,
+        m10, m11, m12, m13,
+        m20, m21, m22, m23,
+        m30, m31, m32, m33
+    ] = m;
+
+    const b00 = m00 * m11 - m01 * m10;
+    const b01 = m00 * m12 - m02 * m10;
+    const b02 = m00 * m13 - m03 * m10;
+    const b03 = m01 * m12 - m02 * m11;
+    const b04 = m01 * m13 - m03 * m11;
+    const b05 = m02 * m13 - m03 * m12;
+    const b06 = m20 * m31 - m21 * m30;
+    const b07 = m20 * m32 - m22 * m30;
+    const b08 = m20 * m33 - m23 * m30;
+    const b09 = m21 * m32 - m22 * m31;
+    const b10 = m21 * m33 - m23 * m31;
+    const b11 = m22 * m33 - m23 * m32;
+
+    const invDet = 1.0 / det;
+    return [
+        (m11 * b11 - m12 * b10 + m13 * b09) * invDet,
+        (m02 * b10 - m01 * b11 - m03 * b09) * invDet,
+        (m31 * b05 - m32 * b04 + m33 * b03) * invDet,
+        (m22 * b04 - m21 * b05 - m23 * b03) * invDet,
+        (m12 * b08 - m10 * b11 - m13 * b07) * invDet,
+        (m00 * b11 - m02 * b08 + m03 * b07) * invDet,
+        (m32 * b02 - m30 * b05 - m33 * b01) * invDet,
+        (m20 * b05 - m22 * b02 + m23 * b01) * invDet,
+        (m10 * b10 - m11 * b08 + m13 * b06) * invDet,
+        (m01 * b08 - m00 * b10 - m03 * b06) * invDet,
+        (m30 * b04 - m31 * b02 + m33 * b00) * invDet,
+        (m21 * b02 - m20 * b04 - m23 * b00) * invDet,
+        (m11 * b07 - m10 * b09 - m12 * b06) * invDet,
+        (m00 * b09 - m01 * b07 + m02 * b06) * invDet,
+        (m31 * b01 - m30 * b03 - m32 * b00) * invDet,
+        (m20 * b03 - m21 * b01 + m22 * b00) * invDet
+    ];
+};

package/src/interface/math/mat4x4/look-at.test.ts

@@ -0,0 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from "vitest";
+import { Mat4x4 } from "./index.js";
+import { Quat } from "../quat/index.js";
+
+describe("lookAt", () => {
+    test("rejects an up vector parallel to the view direction", () => {
+        expect(() => Mat4x4.lookAt([0, 0, 0], [0, 1, 0], [0, 1, 0])).toThrow("Up vector cannot be parallel to view direction");
+    });
+
+    test("as a quaternion, stays finite for an up vector parallel to the view direction", () => {
+        expect(Quat.lookAt([0, 1, 0], [0, 1, 0]).every(Number.isFinite)).toBe(true);
+    });
+});

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

@@ -0,0 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import type { Vec3 } from "../vec3/index.js";
+import { Vec3 as Vec3Namespace } from "../vec3/index.js";
+import { zero } from "./zero.js";
+
+export const lookAt = (eye: Vec3, center: Vec3, up: Vec3): Mat4x4 => {
+    // Validate inputs
+    if (Vec3Namespace.length(up) === 0) throw new Error('Up vector cannot be zero');
+
+    const forward = Vec3Namespace.subtract(center, eye);
+    if (Vec3Namespace.length(forward) === 0) throw new Error('Eye and center cannot be the same position');
+
+    const f = Vec3Namespace.normalize(forward);
+    const right = Vec3Namespace.cross(f, up);
+    if (Vec3Namespace.length(right) === 0) throw new Error('Up vector cannot be parallel to view direction');
+    const s = Vec3Namespace.normalize(right);
+
+    const u = Vec3Namespace.normalize(Vec3Namespace.cross(s, f));
+
+    return [
+        s[0], u[0], -f[0], 0,
+        s[1], u[1], -f[1], 0,
+        s[2], u[2], -f[2], 0,
+        -Vec3Namespace.dot(s, eye), -Vec3Namespace.dot(u, eye), Vec3Namespace.dot(f, eye), 1
+    ];
+};

package/src/interface/math/mat4x4/multiply-vec3.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import type { Vec3 } from "../vec3/index.js";
+
+export const multiplyVec3 = (m: Mat4x4, v: Vec3): Vec3 => [
+    m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12],
+    m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13],
+    m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]
+];

package/src/interface/math/mat4x4/multiply-vec4.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import type { Vec4 } from "../vec4/index.js";
+import { intrinsic } from "../intrinsic.js";
+
+export const multiplyVec4 = intrinsic({ wgsl: "*", form: "infix", parameters: ["mat4x4f", "vec4f"], result: "vec4f" }, (m: Mat4x4, v: Vec4): Vec4 => [
+    m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12] * v[3],
+    m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13] * v[3],
+    m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14] * v[3],
+    m[3] * v[0] + m[7] * v[1] + m[11] * v[2] + m[15] * v[3]
+]);

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

@@ -0,0 +1,23 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+import { intrinsic } from "../intrinsic.js";
+
+/** `a * b`: column `j` row `i` is the dot of row `i` of `a` and column `j` of `b`. */
+export const multiply = intrinsic({ wgsl: "*", form: "infix", parameters: ["mat4x4f", "mat4x4f"], result: "mat4x4f" }, (a: Mat4x4, b: Mat4x4): Mat4x4 => [
+    a[0] * b[0] + a[4] * b[1] + a[8] * b[2] + a[12] * b[3],
+    a[1] * b[0] + a[5] * b[1] + a[9] * b[2] + a[13] * b[3],
+    a[2] * b[0] + a[6] * b[1] + a[10] * b[2] + a[14] * b[3],
+    a[3] * b[0] + a[7] * b[1] + a[11] * b[2] + a[15] * b[3],
+    a[0] * b[4] + a[4] * b[5] + a[8] * b[6] + a[12] * b[7],
+    a[1] * b[4] + a[5] * b[5] + a[9] * b[6] + a[13] * b[7],
+    a[2] * b[4] + a[6] * b[5] + a[10] * b[6] + a[14] * b[7],
+    a[3] * b[4] + a[7] * b[5] + a[11] * b[6] + a[15] * b[7],
+    a[0] * b[8] + a[4] * b[9] + a[8] * b[10] + a[12] * b[11],
+    a[1] * b[8] + a[5] * b[9] + a[9] * b[10] + a[13] * b[11],
+    a[2] * b[8] + a[6] * b[9] + a[10] * b[10] + a[14] * b[11],
+    a[3] * b[8] + a[7] * b[9] + a[11] * b[10] + a[15] * b[11],
+    a[0] * b[12] + a[4] * b[13] + a[8] * b[14] + a[12] * b[15],
+    a[1] * b[12] + a[5] * b[13] + a[9] * b[14] + a[13] * b[15],
+    a[2] * b[12] + a[6] * b[13] + a[10] * b[14] + a[14] * b[15],
+    a[3] * b[12] + a[7] * b[13] + a[11] * b[14] + a[15] * b[15],
+]);

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

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+
+export const orthographic = (
+    left: number,
+    right: number,
+    bottom: number,
+    top: number,
+    near: number,
+    far: number
+): Mat4x4 => {
+    const lr = 1 / (left - right);
+    const bt = 1 / (bottom - top);
+    const nf = 1 / (near - far);
+    return [
+        -2 * lr, 0, 0, 0,
+        0, -2 * bt, 0, 0,
+        0, 0, 2 * nf, 0,
+        (left + right) * lr, (bottom + top) * bt, (far + near) * nf, 1
+    ];
+};

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

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+
+export const perspective = (fovy: number, aspect: number, near: number, far: number): Mat4x4 => {
+    if (fovy <= 0) throw new Error('Field of view must be greater than 0');
+    if (aspect <= 0) throw new Error('Aspect ratio must be greater than 0');
+    if (near <= 0) throw new Error('Near plane must be greater than 0');
+    if (far <= near) throw new Error('Far plane must be greater than near plane');
+
+    const f = 1.0 / Math.tan(fovy / 2);
+    // WebGPU clip-space convention: z_ndc ∈ [0, 1].
+    //   m[2][2] = far / (near - far)   maps z_view = -far → z_ndc = 1
+    //   m[2][3] = (near*far) / (near-far) and m[3][2] = -1 maps z_view = -near → z_ndc = 0
+    const fn = far / (near - far);
+    return [
+        f / aspect, 0, 0, 0,
+        0, f, 0, 0,
+        0, 0, fn, -1,
+        0, 0, near * fn, 0
+    ];
+};

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

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./add.js";
+export * from "./determinant.js";
+export * from "./identity.js";
+export * from "./inverse.js";
+export * from "./look-at.js";
+export * from "./multiply-vec3.js";
+export * from "./multiply-vec4.js";
+export * from "./multiply.js";
+export * from "./orthographic.js";
+export * from "./perspective.js";
+export * from "./rotation-x.js";
+export * from "./rotation-y.js";
+export * from "./rotation-z.js";
+export * from "./scale.js";
+export * from "./scaling.js";
+export * from "./subtract.js";
+export * from "./translation.js";
+export * from "./transpose.js";
+export * from "./zero.js";
+export * from "./schema.js";
+export { identity as default } from "./identity.js";

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

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Mat4x4 } from "./index.js";
+
+export const rotationX = (angle: number): Mat4x4 => {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return [
+        1, 0, 0, 0,
+        0, c, s, 0,
+        0, -s, c, 0,
+        0, 0, 0, 1
+    ];
+};

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

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { F32, I32, Mat4x4, Quat, U32, 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;
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+type Two = readonly [number, number];
+type Three = readonly [number, number, number];
+type Four = readonly [number, number, number, number];
+
+// Each is the plain type its schema describes.
+check<Equal<F32, number>>();
+check<Equal<I32, number>>();
+check<Equal<U32, number>>();
+check<Equal<Vec2, Two>>();
+check<Equal<Vec2.I32, Two>>();
+check<Equal<Vec2.U32, Two>>();
+check<Equal<Vec3, Three>>();
+check<Equal<Vec3.I32, Three>>();
+check<Equal<Vec3.U32, Three>>();
+check<Equal<Vec4, Four>>();
+check<Equal<Vec4.I32, Four>>();
+check<Equal<Vec4.U32, Four>>();
+check<Equal<Quat, Four>>();
+check<Equal<Mat4x4, readonly [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]>>();

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

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Quat } from "../index.js";
+
+export const identity: Quat = [0, 0, 0, 1];

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

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../schema/schema.js";
+import type { schema } from "./schema.js";
+
+export type Quat = Schema.Type<typeof schema>;
+
+export * as Quat from "./public.js";