@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/morph.js

@@ -0,0 +1,94 @@
+/**
+ * Morph targets (blend shapes) on the CPU: `base + Σ weight × delta` per vertex, written into
+ * the position and normal lanes of an interleaved vertex buffer the mesh then uploads
+ * (`Mesh.update`). The arithmetic is here; the parser (`assets/gltf.ts`) fills `MorphTarget`s
+ * and the loader (`assets/gltf-load.ts`) owns the buffers and the upload. Nothing allocates
+ * after `createMorphBlender`.
+ */
+/**
+ * A blender over `base` (the primitive's interleaved vertices in `layout`) and its `targets`.
+ * `weights` may be the array the blender should read (shared between the primitives of a mesh);
+ * it defaults to zeros, `targets.length` long. Throws when a target's deltas do not cover
+ * `base`'s vertices or `weights` is shorter than `targets`.
+ */
+export function createMorphBlender(base, targets, layout, weights = new Float32Array(targets.length)) {
+    const floats = layout.floats;
+    const vertexCount = Math.floor(base.length / floats);
+    const po = layout.positionOffset ?? 0;
+    const no = layout.normalOffset === undefined ? 3 : layout.normalOffset;
+    const targetCount = targets.length;
+    if (weights.length < targetCount) {
+        throw new RangeError(`morph: ${weights.length} weights for ${targetCount} targets`);
+    }
+    for (let i = 0; i < targetCount; i++) {
+        const t = targets[i];
+        for (const d of [t.position, t.normal]) {
+            if (d && d.length < vertexCount * 3) {
+                throw new RangeError(`morph: target ${i} has ${d.length / 3} deltas for ${vertexCount} vertices`);
+            }
+        }
+    }
+    const applied = new Float32Array(targetCount);
+    let lastOut = null;
+    return {
+        weights,
+        targetCount,
+        vertexCount,
+        apply(out) {
+            let changed = out !== lastOut;
+            for (let i = 0; i < targetCount && !changed; i++)
+                changed = weights[i] !== applied[i];
+            if (!changed)
+                return false;
+            if (out !== lastOut) {
+                out.set(base);
+                lastOut = out;
+            }
+            for (let i = 0; i < targetCount; i++)
+                applied[i] = weights[i];
+            for (let v = 0; v < vertexCount; v++) {
+                const o = v * floats;
+                const d = v * 3;
+                let px = base[o + po];
+                let py = base[o + po + 1];
+                let pz = base[o + po + 2];
+                for (let i = 0; i < targetCount; i++) {
+                    const w = applied[i];
+                    const t = targets[i].position;
+                    if (w === 0 || !t)
+                        continue;
+                    px += w * t[d];
+                    py += w * t[d + 1];
+                    pz += w * t[d + 2];
+                }
+                out[o + po] = px;
+                out[o + po + 1] = py;
+                out[o + po + 2] = pz;
+                if (no === null)
+                    continue;
+                let nx = base[o + no];
+                let ny = base[o + no + 1];
+                let nz = base[o + no + 2];
+                for (let i = 0; i < targetCount; i++) {
+                    const w = applied[i];
+                    const t = targets[i].normal;
+                    if (w === 0 || !t)
+                        continue;
+                    nx += w * t[d];
+                    ny += w * t[d + 1];
+                    nz += w * t[d + 2];
+                }
+                const len = Math.hypot(nx, ny, nz);
+                if (len > 1e-12) {
+                    nx /= len;
+                    ny /= len;
+                    nz /= len;
+                }
+                out[o + no] = nx;
+                out[o + no + 1] = ny;
+                out[o + no + 2] = nz;
+            }
+            return true;
+        },
+    };
+}

package/dist/anim/pose.d.ts

@@ -0,0 +1,74 @@
+/** Floats per node in a `Pose` and in `Skeleton.rest`: `tx ty tz qx qy qz qw sx sy sz`. */
+export declare const POSE_NODE_FLOATS = 10;
+/** Floats per node in a world array and per joint in a skin array (3×4 row-major). */
+export declare const WORLD_NODE_FLOATS = 12;
+/**
+ * A node hierarchy with a rest pose and, when it skins a mesh, the joint list and its inverse
+ * bind matrices. Nodes are in parent-before-child order: `parents[i] < i`, or `-1` for a root
+ * (`validateSkeleton` checks it; a glTF importer reorders nodes to satisfy it).
+ */
+export interface Skeleton {
+    /** Parent node index per node, `-1` for a root. `parents[i] < i`. */
+    parents: Int16Array;
+    /** Rest pose, `POSE_NODE_FLOATS` per node. */
+    rest: Float32Array;
+    /**
+     * Inverse bind matrix per joint: 12 floats (3×4 row-major, this module's layout) or 16 floats
+     * (4×4 column-major, as glTF stores them; the last column is read as the translation).
+     */
+    inverseBind?: Float32Array;
+    /** Node index per joint. Absent: joint `j` is node `j`. */
+    joints?: Uint16Array;
+    /** Node name per node (glTF `node.name`), so `createSocket` can take a joint by name. */
+    names?: string[];
+}
+/** Local transforms per node, `POSE_NODE_FLOATS` floats each. */
+export type Pose = Float32Array;
+/** Number of nodes in a skeleton. */
+export declare function nodeCount(skeleton: Skeleton): number;
+/** Number of joints: `joints.length` when given, else every node is a joint. */
+export declare function jointCount(skeleton: Skeleton): number;
+/**
+ * Throw if the skeleton is inconsistent: `rest` length, parent order (`parents[i] < i`), joint
+ * indices in range, `inverseBind` length (12 or 16 per joint).
+ */
+export declare function validateSkeleton(skeleton: Skeleton): void;
+/** A new pose holding a copy of the rest pose. */
+export declare function createPose(skeleton: Skeleton): Pose;
+/** Copy `src` into `dst` (same length). */
+export declare function copyPose(src: Pose, dst: Pose): void;
+/**
+ * `out = lerp(a, b, t)` per node: translation and scale linearly, rotation by slerp along the
+ * shorter arc. `out` may alias `a` or `b`. No allocation.
+ */
+export declare function blendPose(a: Pose, b: Pose, t: number, out: Pose): void;
+/** Write the 3×4 row-major matrix `T · R · S` of the node at `pose[po..po+10)` to `out[o..o+12)`. */
+export declare function writeNodeMatrix(out: Float32Array, o: number, pose: ArrayLike<number>, po: number): void;
+/**
+ * `out[oo..] = a[ao..] · b[bo..]` for 3×4 affine matrices (implicit last row `0 0 0 1`).
+ * `out` may alias neither input.
+ */
+export declare function multiplyAffine(out: Float32Array, oo: number, a: ArrayLike<number>, ao: number, b: ArrayLike<number>, bo: number): void;
+/**
+ * Invert the 3×4 affine matrix at `m[mo..]` into `out[oo..]` (general 3×3 inverse plus
+ * translation). A singular matrix (a zero scale) yields the identity. `out` may not alias `m`.
+ */
+export declare function invertAffine(out: Float32Array, oo: number, m: ArrayLike<number>, mo: number): void;
+/**
+ * Resolve a pose into world matrices: `out[i]` (12 floats, 3×4 row-major) is
+ * `world[parent] · T·R·S(pose[i])`, in node order. `out` needs `WORLD_NODE_FLOATS × nodes`.
+ * No allocation.
+ */
+export declare function poseToWorld(skeleton: Skeleton, pose: Pose, out3x4: Float32Array): void;
+/**
+ * Joint matrices for skinning: `out[j]` (12 floats, 3×4 row-major) is
+ * `world[joints[j]] · inverseBind[j]`, the layout `render/skin.ts` uploads. Without
+ * `inverseBind` the world matrix is copied. `out` needs `WORLD_NODE_FLOATS × joints`. No
+ * allocation.
+ */
+export declare function skinMatrices(skeleton: Skeleton, world3x4: Float32Array, out: Float32Array): void;
+/**
+ * Inverse bind matrices (12 floats per joint, 3×4 row-major) from the skeleton's rest pose, for
+ * procedural rigs: with them `skinMatrices` of the rest pose is the identity. Allocates.
+ */
+export declare function inverseBindFromRest(skeleton: Skeleton): Float32Array;

package/dist/anim/pose.js

@@ -0,0 +1,254 @@
+/**
+ * Skeletons, poses and the two resolutions a renderer needs: node world matrices and skin joint
+ * matrices. Pure arithmetic on flat `Float32Array`s; nothing here allocates after setup.
+ *
+ * Layouts:
+ * - A `Pose` is `POSE_NODE_FLOATS` (10) floats per node: translation `t3`, rotation `q4`
+ *   (`x y z w`), scale `s3`. `Skeleton.rest` has the same layout.
+ * - World matrices are **3×4 row-major**, 12 floats per node (`render/transform.ts`):
+ *   `[r0 | tx, r1 | ty, r2 | tz]`, local = `T · R · S`, world = `parent.world · local`.
+ * - Skin matrices are the same 3×4 layout, 12 floats per joint, `world[joint] · inverseBind[j]`:
+ *   what `render/skin.ts` (`SkinPalette`) consumes.
+ */
+import { quatSlerp } from './quat.js';
+/** Floats per node in a `Pose` and in `Skeleton.rest`: `tx ty tz qx qy qz qw sx sy sz`. */
+export const POSE_NODE_FLOATS = 10;
+/** Floats per node in a world array and per joint in a skin array (3×4 row-major). */
+export const WORLD_NODE_FLOATS = 12;
+/** Number of nodes in a skeleton. */
+export function nodeCount(skeleton) {
+    return skeleton.parents.length;
+}
+/** Number of joints: `joints.length` when given, else every node is a joint. */
+export function jointCount(skeleton) {
+    return skeleton.joints ? skeleton.joints.length : skeleton.parents.length;
+}
+/**
+ * Throw if the skeleton is inconsistent: `rest` length, parent order (`parents[i] < i`), joint
+ * indices in range, `inverseBind` length (12 or 16 per joint).
+ */
+export function validateSkeleton(skeleton) {
+    const n = skeleton.parents.length;
+    if (skeleton.rest.length !== n * POSE_NODE_FLOATS) {
+        throw new Error(`Skeleton: rest has ${skeleton.rest.length} floats, expected ${n * POSE_NODE_FLOATS} (${n} nodes × ${POSE_NODE_FLOATS})`);
+    }
+    for (let i = 0; i < n; i++) {
+        const p = skeleton.parents[i];
+        if (p >= i || p < -1) {
+            throw new Error(`Skeleton: parents[${i}] = ${p}; parents must come before children (-1 = root)`);
+        }
+    }
+    const joints = jointCount(skeleton);
+    if (skeleton.joints) {
+        for (let j = 0; j < joints; j++) {
+            const node = skeleton.joints[j];
+            if (node >= n)
+                throw new Error(`Skeleton: joints[${j}] = ${node} is not a node (${n} nodes)`);
+        }
+    }
+    if (skeleton.names && skeleton.names.length !== n) {
+        throw new Error(`Skeleton: names has ${skeleton.names.length} entries, expected ${n} (one per node)`);
+    }
+    const ib = skeleton.inverseBind;
+    if (ib && ib.length !== joints * 12 && ib.length !== joints * 16) {
+        throw new Error(`Skeleton: inverseBind has ${ib.length} floats, expected ${joints * 12} or ${joints * 16} for ${joints} joints`);
+    }
+}
+/** A new pose holding a copy of the rest pose. */
+export function createPose(skeleton) {
+    return new Float32Array(skeleton.rest);
+}
+/** Copy `src` into `dst` (same length). */
+export function copyPose(src, dst) {
+    dst.set(src);
+}
+/**
+ * `out = lerp(a, b, t)` per node: translation and scale linearly, rotation by slerp along the
+ * shorter arc. `out` may alias `a` or `b`. No allocation.
+ */
+export function blendPose(a, b, t, out) {
+    const s = 1 - t;
+    const n = a.length;
+    for (let o = 0; o + POSE_NODE_FLOATS <= n; o += POSE_NODE_FLOATS) {
+        out[o] = s * a[o] + t * b[o];
+        out[o + 1] = s * a[o + 1] + t * b[o + 1];
+        out[o + 2] = s * a[o + 2] + t * b[o + 2];
+        quatSlerp(out, o + 3, a, o + 3, b, o + 3, t);
+        out[o + 7] = s * a[o + 7] + t * b[o + 7];
+        out[o + 8] = s * a[o + 8] + t * b[o + 8];
+        out[o + 9] = s * a[o + 9] + t * b[o + 9];
+    }
+}
+/** Write the 3×4 row-major matrix `T · R · S` of the node at `pose[po..po+10)` to `out[o..o+12)`. */
+export function writeNodeMatrix(out, o, pose, po) {
+    const x = pose[po + 3];
+    const y = pose[po + 4];
+    const z = pose[po + 5];
+    const w = pose[po + 6];
+    const sx = pose[po + 7];
+    const sy = pose[po + 8];
+    const sz = pose[po + 9];
+    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;
+    out[o] = (1 - 2 * (yy + zz)) * sx;
+    out[o + 1] = 2 * (xy - wz) * sy;
+    out[o + 2] = 2 * (xz + wy) * sz;
+    out[o + 3] = pose[po];
+    out[o + 4] = 2 * (xy + wz) * sx;
+    out[o + 5] = (1 - 2 * (xx + zz)) * sy;
+    out[o + 6] = 2 * (yz - wx) * sz;
+    out[o + 7] = pose[po + 1];
+    out[o + 8] = 2 * (xz - wy) * sx;
+    out[o + 9] = 2 * (yz + wx) * sy;
+    out[o + 10] = (1 - 2 * (xx + yy)) * sz;
+    out[o + 11] = pose[po + 2];
+}
+/**
+ * `out[oo..] = a[ao..] · b[bo..]` for 3×4 affine matrices (implicit last row `0 0 0 1`).
+ * `out` may alias neither input.
+ */
+export function multiplyAffine(out, oo, a, ao, b, bo) {
+    for (let r = 0; r < 3; r++) {
+        const a0 = a[ao + r * 4];
+        const a1 = a[ao + r * 4 + 1];
+        const a2 = a[ao + r * 4 + 2];
+        const a3 = a[ao + r * 4 + 3];
+        out[oo + r * 4] = a0 * b[bo] + a1 * b[bo + 4] + a2 * b[bo + 8];
+        out[oo + r * 4 + 1] = a0 * b[bo + 1] + a1 * b[bo + 5] + a2 * b[bo + 9];
+        out[oo + r * 4 + 2] = a0 * b[bo + 2] + a1 * b[bo + 6] + a2 * b[bo + 10];
+        out[oo + r * 4 + 3] = a0 * b[bo + 3] + a1 * b[bo + 7] + a2 * b[bo + 11] + a3;
+    }
+}
+/**
+ * Invert the 3×4 affine matrix at `m[mo..]` into `out[oo..]` (general 3×3 inverse plus
+ * translation). A singular matrix (a zero scale) yields the identity. `out` may not alias `m`.
+ */
+export function invertAffine(out, oo, m, mo) {
+    const a00 = m[mo];
+    const a01 = m[mo + 1];
+    const a02 = m[mo + 2];
+    const tx = m[mo + 3];
+    const a10 = m[mo + 4];
+    const a11 = m[mo + 5];
+    const a12 = m[mo + 6];
+    const ty = m[mo + 7];
+    const a20 = m[mo + 8];
+    const a21 = m[mo + 9];
+    const a22 = m[mo + 10];
+    const tz = m[mo + 11];
+    const c00 = a11 * a22 - a12 * a21;
+    const c01 = a02 * a21 - a01 * a22;
+    const c02 = a01 * a12 - a02 * a11;
+    const det = a00 * c00 + a10 * c01 + a20 * c02;
+    if (det === 0) {
+        out.fill(0, oo, oo + 12);
+        out[oo] = 1;
+        out[oo + 5] = 1;
+        out[oo + 10] = 1;
+        return;
+    }
+    const inv = 1 / det;
+    const i00 = c00 * inv;
+    const i01 = c01 * inv;
+    const i02 = c02 * inv;
+    const i10 = (a12 * a20 - a10 * a22) * inv;
+    const i11 = (a00 * a22 - a02 * a20) * inv;
+    const i12 = (a02 * a10 - a00 * a12) * inv;
+    const i20 = (a10 * a21 - a11 * a20) * inv;
+    const i21 = (a01 * a20 - a00 * a21) * inv;
+    const i22 = (a00 * a11 - a01 * a10) * inv;
+    out[oo] = i00;
+    out[oo + 1] = i01;
+    out[oo + 2] = i02;
+    out[oo + 3] = -(i00 * tx + i01 * ty + i02 * tz);
+    out[oo + 4] = i10;
+    out[oo + 5] = i11;
+    out[oo + 6] = i12;
+    out[oo + 7] = -(i10 * tx + i11 * ty + i12 * tz);
+    out[oo + 8] = i20;
+    out[oo + 9] = i21;
+    out[oo + 10] = i22;
+    out[oo + 11] = -(i20 * tx + i21 * ty + i22 * tz);
+}
+/**
+ * Resolve a pose into world matrices: `out[i]` (12 floats, 3×4 row-major) is
+ * `world[parent] · T·R·S(pose[i])`, in node order. `out` needs `WORLD_NODE_FLOATS × nodes`.
+ * No allocation.
+ */
+export function poseToWorld(skeleton, pose, out3x4) {
+    const parents = skeleton.parents;
+    const n = parents.length;
+    for (let i = 0; i < n; i++) {
+        const o = i * WORLD_NODE_FLOATS;
+        const p = parents[i];
+        if (p < 0) {
+            writeNodeMatrix(out3x4, o, pose, i * POSE_NODE_FLOATS);
+        }
+        else {
+            writeNodeMatrix(scratchLocal, 0, pose, i * POSE_NODE_FLOATS);
+            multiplyAffine(out3x4, o, out3x4, p * WORLD_NODE_FLOATS, scratchLocal, 0);
+        }
+    }
+}
+const scratchLocal = new Float32Array(WORLD_NODE_FLOATS);
+const scratchBind = new Float32Array(WORLD_NODE_FLOATS);
+/**
+ * Joint matrices for skinning: `out[j]` (12 floats, 3×4 row-major) is
+ * `world[joints[j]] · inverseBind[j]`, the layout `render/skin.ts` uploads. Without
+ * `inverseBind` the world matrix is copied. `out` needs `WORLD_NODE_FLOATS × joints`. No
+ * allocation.
+ */
+export function skinMatrices(skeleton, world3x4, out) {
+    const joints = jointCount(skeleton);
+    const map = skeleton.joints;
+    const ib = skeleton.inverseBind;
+    const stride = ib ? ib.length / joints : 0;
+    for (let j = 0; j < joints; j++) {
+        const node = map ? map[j] : j;
+        const wo = node * WORLD_NODE_FLOATS;
+        const oo = j * WORLD_NODE_FLOATS;
+        if (!ib) {
+            // A plain copy, not `set(subarray(...))`: no view allocated per joint.
+            for (let k = 0; k < WORLD_NODE_FLOATS; k++)
+                out[oo + k] = world3x4[wo + k];
+            continue;
+        }
+        if (stride === 16) {
+            // glTF column-major 4×4 → our row-major 3×4.
+            const b = j * 16;
+            for (let r = 0; r < 3; r++) {
+                scratchBind[r * 4] = ib[b + r];
+                scratchBind[r * 4 + 1] = ib[b + 4 + r];
+                scratchBind[r * 4 + 2] = ib[b + 8 + r];
+                scratchBind[r * 4 + 3] = ib[b + 12 + r];
+            }
+            multiplyAffine(out, oo, world3x4, wo, scratchBind, 0);
+        }
+        else {
+            multiplyAffine(out, oo, world3x4, wo, ib, j * 12);
+        }
+    }
+}
+/**
+ * Inverse bind matrices (12 floats per joint, 3×4 row-major) from the skeleton's rest pose, for
+ * procedural rigs: with them `skinMatrices` of the rest pose is the identity. Allocates.
+ */
+export function inverseBindFromRest(skeleton) {
+    const n = skeleton.parents.length;
+    const world = new Float32Array(n * WORLD_NODE_FLOATS);
+    poseToWorld(skeleton, skeleton.rest, world);
+    const joints = skeleton.joints ? skeleton.joints.length : n;
+    const out = new Float32Array(joints * WORLD_NODE_FLOATS);
+    for (let j = 0; j < joints; j++) {
+        const node = skeleton.joints ? skeleton.joints[j] : j;
+        invertAffine(out, j * WORLD_NODE_FLOATS, world, node * WORLD_NODE_FLOATS);
+    }
+    return out;
+}

package/dist/anim/quat.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Quaternion helpers on flat arrays: every function reads and writes `(x, y, z, w)` at an
+ * offset into a `Float32Array` (or any `ArrayLike`), so poses and keyframe buffers are handled in
+ * place and nothing allocates. No dependency on `render/`.
+ *
+ * Conventions match `render/transform.ts`: unit quaternions `(x, y, z, w)`, right-handed, and
+ * `quatMultiply(out, a, b)` is "apply `b`, then `a`" (the same order as matrix products).
+ */
+/** Write the identity rotation at `out[o..o+4)`. */
+export declare function quatIdentity(out: Float32Array, o?: number): void;
+/** Normalise the quaternion at `q[o..o+4)` in place. A zero quaternion becomes the identity. */
+export declare function quatNormalize(q: Float32Array, o?: number): void;
+/** Dot product of the quaternions at `a[ao..]` and `b[bo..]`. */
+export declare function quatDot(a: ArrayLike<number>, ao: number, b: ArrayLike<number>, bo: number): number;
+/**
+ * `out = a · b`: the rotation that applies `b` first, then `a`. `out` may alias either input.
+ */
+export declare function quatMultiply(out: Float32Array, oo: number, a: ArrayLike<number>, ao: number, b: ArrayLike<number>, bo: number): void;
+/**
+ * Normalised linear interpolation from `a` to `b` by `t` along the shorter arc. Cheaper than
+ * `quatSlerp`, not constant speed; fine for blending nearby poses. `out` may alias an input.
+ */
+export declare function quatNlerp(out: Float32Array, oo: number, a: ArrayLike<number>, ao: number, b: ArrayLike<number>, bo: number, t: number): void;
+/**
+ * Spherical linear interpolation from `a` to `b` by `t` along the shorter arc (glTF `LINEAR`
+ * rotation semantics). Falls back to a normalised lerp when the inputs are nearly parallel.
+ * `out` may alias an input.
+ */
+export declare function quatSlerp(out: Float32Array, oo: number, a: ArrayLike<number>, ao: number, b: ArrayLike<number>, bo: number, t: number): void;
+/** Rotation about an axis (need not be unit length) by `radians`, written at `out[o..o+4)`. */
+export declare function quatFromAxisAngle(out: Float32Array, o: number, ax: number, ay: number, az: number, radians: number): void;
+/**
+ * Rotation from Euler angles in radians: about X, then Y, then Z in the parent frame
+ * (`q = qz · qy · qx`). Written at `out[o..o+4)`.
+ */
+export declare function quatFromEuler(out: Float32Array, o: number, x: number, y: number, z: number): void;
+/**
+ * The rotation of a 3×3 matrix (or the 3×3 part of a 3×4 affine, with `stride` 4) read
+ * row-major at `m[mo..]` (rows `r0 r1 r2`, `stride` floats apart; default 3 for a packed
+ * mat3), written as a unit quaternion at `out[o..o+4)`. Shepperd's method: the largest
+ * diagonal term picks the stable branch. A scaled matrix is normalised first (uniform scale
+ * drops out; non-uniform scale gives the nearest rotation only approximately). Allocation-free.
+ */
+export declare function quatFromMat3(m: ArrayLike<number>, out: Float32Array, o?: number, mo?: number, stride?: number): void;

package/dist/anim/quat.js

@@ -0,0 +1,187 @@
+/**
+ * Quaternion helpers on flat arrays: every function reads and writes `(x, y, z, w)` at an
+ * offset into a `Float32Array` (or any `ArrayLike`), so poses and keyframe buffers are handled in
+ * place and nothing allocates. No dependency on `render/`.
+ *
+ * Conventions match `render/transform.ts`: unit quaternions `(x, y, z, w)`, right-handed, and
+ * `quatMultiply(out, a, b)` is "apply `b`, then `a`" (the same order as matrix products).
+ */
+/** Write the identity rotation at `out[o..o+4)`. */
+export function quatIdentity(out, o = 0) {
+    out[o] = 0;
+    out[o + 1] = 0;
+    out[o + 2] = 0;
+    out[o + 3] = 1;
+}
+/** Normalise the quaternion at `q[o..o+4)` in place. A zero quaternion becomes the identity. */
+export function quatNormalize(q, o = 0) {
+    const x = q[o];
+    const y = q[o + 1];
+    const z = q[o + 2];
+    const w = q[o + 3];
+    const len = Math.hypot(x, y, z, w);
+    if (len === 0) {
+        quatIdentity(q, o);
+        return;
+    }
+    const inv = 1 / len;
+    q[o] = x * inv;
+    q[o + 1] = y * inv;
+    q[o + 2] = z * inv;
+    q[o + 3] = w * inv;
+}
+/** Dot product of the quaternions at `a[ao..]` and `b[bo..]`. */
+export function quatDot(a, ao, b, bo) {
+    return (a[ao] * b[bo] + a[ao + 1] * b[bo + 1] + a[ao + 2] * b[bo + 2] + a[ao + 3] * b[bo + 3]);
+}
+/**
+ * `out = a · b`: the rotation that applies `b` first, then `a`. `out` may alias either input.
+ */
+export function quatMultiply(out, oo, a, ao, b, bo) {
+    const ax = a[ao];
+    const ay = a[ao + 1];
+    const az = a[ao + 2];
+    const aw = a[ao + 3];
+    const bx = b[bo];
+    const by = b[bo + 1];
+    const bz = b[bo + 2];
+    const bw = b[bo + 3];
+    out[oo] = aw * bx + ax * bw + ay * bz - az * by;
+    out[oo + 1] = aw * by - ax * bz + ay * bw + az * bx;
+    out[oo + 2] = aw * bz + ax * by - ay * bx + az * bw;
+    out[oo + 3] = aw * bw - ax * bx - ay * by - az * bz;
+}
+/**
+ * Normalised linear interpolation from `a` to `b` by `t` along the shorter arc. Cheaper than
+ * `quatSlerp`, not constant speed; fine for blending nearby poses. `out` may alias an input.
+ */
+export function quatNlerp(out, oo, a, ao, b, bo, t) {
+    const sign = quatDot(a, ao, b, bo) < 0 ? -1 : 1;
+    const s = 1 - t;
+    const u = t * sign;
+    out[oo] = s * a[ao] + u * b[bo];
+    out[oo + 1] = s * a[ao + 1] + u * b[bo + 1];
+    out[oo + 2] = s * a[ao + 2] + u * b[bo + 2];
+    out[oo + 3] = s * a[ao + 3] + u * b[bo + 3];
+    quatNormalize(out, oo);
+}
+/**
+ * Spherical linear interpolation from `a` to `b` by `t` along the shorter arc (glTF `LINEAR`
+ * rotation semantics). Falls back to a normalised lerp when the inputs are nearly parallel.
+ * `out` may alias an input.
+ */
+export function quatSlerp(out, oo, a, ao, b, bo, t) {
+    let cos = quatDot(a, ao, b, bo);
+    let sign = 1;
+    if (cos < 0) {
+        cos = -cos;
+        sign = -1;
+    }
+    if (cos > 0.9995) {
+        quatNlerp(out, oo, a, ao, b, bo, t);
+        return;
+    }
+    const theta = Math.acos(cos);
+    const sinTheta = Math.sin(theta);
+    const s = Math.sin((1 - t) * theta) / sinTheta;
+    const u = (Math.sin(t * theta) / sinTheta) * sign;
+    out[oo] = s * a[ao] + u * b[bo];
+    out[oo + 1] = s * a[ao + 1] + u * b[bo + 1];
+    out[oo + 2] = s * a[ao + 2] + u * b[bo + 2];
+    out[oo + 3] = s * a[ao + 3] + u * b[bo + 3];
+}
+/** Rotation about an axis (need not be unit length) by `radians`, written at `out[o..o+4)`. */
+export function quatFromAxisAngle(out, o, ax, ay, az, radians) {
+    const len = Math.hypot(ax, ay, az) || 1;
+    const s = Math.sin(radians / 2) / len;
+    out[o] = ax * s;
+    out[o + 1] = ay * s;
+    out[o + 2] = az * s;
+    out[o + 3] = Math.cos(radians / 2);
+}
+/**
+ * Rotation from Euler angles in radians: about X, then Y, then Z in the parent frame
+ * (`q = qz · qy · qx`). Written at `out[o..o+4)`.
+ */
+export function quatFromEuler(out, o, x, y, z) {
+    const cx = Math.cos(x / 2);
+    const sx = Math.sin(x / 2);
+    const cy = Math.cos(y / 2);
+    const sy = Math.sin(y / 2);
+    const cz = Math.cos(z / 2);
+    const sz = Math.sin(z / 2);
+    out[o] = sx * cy * cz - cx * sy * sz;
+    out[o + 1] = cx * sy * cz + sx * cy * sz;
+    out[o + 2] = cx * cy * sz - sx * sy * cz;
+    out[o + 3] = cx * cy * cz + sx * sy * sz;
+}
+/**
+ * The rotation of a 3×3 matrix (or the 3×3 part of a 3×4 affine, with `stride` 4) read
+ * row-major at `m[mo..]` (rows `r0 r1 r2`, `stride` floats apart; default 3 for a packed
+ * mat3), written as a unit quaternion at `out[o..o+4)`. Shepperd's method: the largest
+ * diagonal term picks the stable branch. A scaled matrix is normalised first (uniform scale
+ * drops out; non-uniform scale gives the nearest rotation only approximately). Allocation-free.
+ */
+export function quatFromMat3(m, out, o = 0, mo = 0, stride = 3) {
+    // Normalise each row so a scaled matrix yields a unit quaternion.
+    let m00 = m[mo];
+    let m01 = m[mo + 1];
+    let m02 = m[mo + 2];
+    let m10 = m[mo + stride];
+    let m11 = m[mo + stride + 1];
+    let m12 = m[mo + stride + 2];
+    let m20 = m[mo + 2 * stride];
+    let m21 = m[mo + 2 * stride + 1];
+    let m22 = m[mo + 2 * stride + 2];
+    // Columns are the rotated basis vectors; their lengths are the scale.
+    const sx = Math.hypot(m00, m10, m20) || 1;
+    const sy = Math.hypot(m01, m11, m21) || 1;
+    const sz = Math.hypot(m02, m12, m22) || 1;
+    m00 /= sx;
+    m10 /= sx;
+    m20 /= sx;
+    m01 /= sy;
+    m11 /= sy;
+    m21 /= sy;
+    m02 /= sz;
+    m12 /= sz;
+    m22 /= sz;
+    const trace = m00 + m11 + m22;
+    let x;
+    let y;
+    let z;
+    let w;
+    if (trace > 0) {
+        const s = Math.sqrt(trace + 1) * 2;
+        w = s / 4;
+        x = (m21 - m12) / s;
+        y = (m02 - m20) / s;
+        z = (m10 - m01) / s;
+    }
+    else if (m00 > m11 && m00 > m22) {
+        const s = Math.sqrt(1 + m00 - m11 - m22) * 2;
+        w = (m21 - m12) / s;
+        x = s / 4;
+        y = (m01 + m10) / s;
+        z = (m02 + m20) / s;
+    }
+    else if (m11 > m22) {
+        const s = Math.sqrt(1 + m11 - m00 - m22) * 2;
+        w = (m02 - m20) / s;
+        x = (m01 + m10) / s;
+        y = s / 4;
+        z = (m12 + m21) / s;
+    }
+    else {
+        const s = Math.sqrt(1 + m22 - m00 - m11) * 2;
+        w = (m10 - m01) / s;
+        x = (m02 + m20) / s;
+        y = (m12 + m21) / s;
+        z = s / 4;
+    }
+    out[o] = x;
+    out[o + 1] = y;
+    out[o + 2] = z;
+    out[o + 3] = w;
+    quatNormalize(out, o);
+}