@forgeax/engine-math 0.0.0-dev.8d955ade1c79

package/src/__tests__/quat.basis.test.ts

@@ -0,0 +1,134 @@
+// quat.basis.test.ts — value tests for quat.right / up / forward (solo round 20260713-174912)
+//
+// Regression guard for the friction that motivated the accessors: moving an entity "along where
+// it faces" (Bevy `transform.local_x()` / `.forward()`) required hand-wiring
+// `quat.transformVec3(out, q, [0, 0, -1])` AND independently knowing the −Z forward handedness
+// (documented only inside mat4.ts). A demo author who guessed +Z, or forgot to pick the right
+// canonical axis, got a silently-wrong direction. These tests pin:
+//   1. identity rotation → the canonical world axes (right=+X, up=+Y, forward=−Z),
+//   2. a known rotation maps the axes as expected (90° yaw about +Y),
+//   3. the three accessors equal q applied to the canonical axes (transformVec3 SSOT),
+//   4. they agree with the mat4 basis getters on the same rotation (cross-impl witness —
+//      the −Z forward convention is shared, not re-derived),
+//   5. a fromLookAt camera's forward ≈ normalize(target − eye) (the look-convention anchor),
+//   6. results stay unit-length (a unit q in → a unit vector out),
+//   7. aliasing / degrade (zero quat → the natural transformVec3 result, no NaN),
+//   8. right/up/forward stay mutually orthogonal (a valid orthonormal basis).
+
+import { describe, expect, it } from 'vitest';
+import * as mat4 from '../mat4';
+import * as quat from '../quat';
+import type { QuatLike, Vec3Like } from '../types';
+import * as vec3 from '../vec3';
+
+const EPS = 1e-5;
+
+function expectVec3Close(actual: Vec3Like, expected: Vec3Like, eps = EPS): void {
+  expect(actual[0]).toBeCloseTo(expected[0] as number, 5);
+  expect(actual[1]).toBeCloseTo(expected[1] as number, 5);
+  expect(actual[2]).toBeCloseTo(expected[2] as number, 5);
+  void eps;
+}
+
+function dot(a: Vec3Like, b: Vec3Like): number {
+  return (
+    (a[0] as number) * (b[0] as number) +
+    (a[1] as number) * (b[1] as number) +
+    (a[2] as number) * (b[2] as number)
+  );
+}
+
+describe('quat.right / up / forward — local basis accessors', () => {
+  it('identity rotation → canonical world axes (right=+X, up=+Y, forward=−Z)', () => {
+    const id = quat.identity(quat.create());
+    expectVec3Close(quat.right(vec3.create(), id), [1, 0, 0]);
+    expectVec3Close(quat.up(vec3.create(), id), [0, 1, 0]);
+    expectVec3Close(quat.forward(vec3.create(), id), [0, 0, -1]);
+  });
+
+  it('90° yaw about +Y maps the axes as expected', () => {
+    // A left-hand-rule +Y yaw of 90°: +X → −Z, −Z → −X, +Y stays +Y.
+    const q = quat.eulerY(Math.PI / 2);
+    expectVec3Close(quat.right(vec3.create(), q), [0, 0, -1]);
+    expectVec3Close(quat.up(vec3.create(), q), [0, 1, 0]);
+    expectVec3Close(quat.forward(vec3.create(), q), [-1, 0, 0]);
+  });
+
+  it('each accessor equals q applied to its canonical axis (transformVec3 SSOT)', () => {
+    const q = quat.fromEuler(quat.create(), 0.4, -0.7, 1.1, 'XYZ');
+    expectVec3Close(quat.right(vec3.create(), q), quat.transformVec3(vec3.create(), q, [1, 0, 0]));
+    expectVec3Close(quat.up(vec3.create(), q), quat.transformVec3(vec3.create(), q, [0, 1, 0]));
+    expectVec3Close(
+      quat.forward(vec3.create(), q),
+      quat.transformVec3(vec3.create(), q, [0, 0, -1]),
+    );
+  });
+
+  it('WITNESS: agrees with mat4.getRight / getUp / getForward on the same rotation', () => {
+    // The −Z forward convention is shared between quat and mat4 — an independent implementation
+    // (mat4 reads basis columns) must land the same directions. If either side flips a sign this
+    // fails, catching a convention drift the single-namespace tests cannot.
+    const q = quat.fromEuler(quat.create(), 0.9, 0.3, -0.5, 'YXZ');
+    const m = mat4.fromQuat(mat4.create(), q);
+    expectVec3Close(quat.right(vec3.create(), q), mat4.getRight(vec3.create(), m));
+    expectVec3Close(quat.up(vec3.create(), q), mat4.getUp(vec3.create(), m));
+    expectVec3Close(quat.forward(vec3.create(), q), mat4.getForward(vec3.create(), m));
+  });
+
+  it('fromLookAt camera → forward ≈ normalize(target − eye)', () => {
+    // The look-convention anchor: the whole point of the −Z choice is that a camera built with
+    // fromLookAt faces its target. This is the property a demo relies on.
+    const eye: Vec3Like = [5, 3, -2];
+    const target: Vec3Like = [-1, 0, 4];
+    const q = quat.fromLookAt(quat.create(), eye, target, [0, 1, 0]);
+    const expected = vec3.normalize(
+      vec3.create(),
+      vec3.create(
+        (target[0] as number) - (eye[0] as number),
+        (target[1] as number) - (eye[1] as number),
+        (target[2] as number) - (eye[2] as number),
+      ),
+    );
+    expectVec3Close(quat.forward(vec3.create(), q), expected);
+  });
+
+  it('a unit quaternion yields unit-length basis vectors', () => {
+    const q = quat.fromAxisAngle(quat.create(), [0.3, 0.8, -0.5], 2.1);
+    expect(vec3.length(quat.right(vec3.create(), q))).toBeCloseTo(1, 5);
+    expect(vec3.length(quat.up(vec3.create(), q))).toBeCloseTo(1, 5);
+    expect(vec3.length(quat.forward(vec3.create(), q))).toBeCloseTo(1, 5);
+  });
+
+  it('right / up / forward form an orthonormal (mutually perpendicular) basis', () => {
+    const q = quat.fromEuler(quat.create(), 1.2, -0.4, 0.6, 'ZYX');
+    const r = quat.right(vec3.create(), q);
+    const u = quat.up(vec3.create(), q);
+    const f = quat.forward(vec3.create(), q);
+    expect(dot(r, u)).toBeCloseTo(0, 5);
+    expect(dot(r, f)).toBeCloseTo(0, 5);
+    expect(dot(u, f)).toBeCloseTo(0, 5);
+  });
+
+  it('degrade: zero quaternion → natural transformVec3 result, no NaN', () => {
+    const zero: QuatLike = new Float32Array([0, 0, 0, 0]);
+    const r = quat.right(vec3.create(), zero);
+    const u = quat.up(vec3.create(), zero);
+    const f = quat.forward(vec3.create(), zero);
+    // transformVec3 with q=(0,0,0,0) → out = v (the input axis), non-NaN.
+    expectVec3Close(r, [1, 0, 0]);
+    expectVec3Close(u, [0, 1, 0]);
+    expectVec3Close(f, [0, 0, -1]);
+    for (const v of [r, u, f]) {
+      expect(Number.isNaN(v[0])).toBe(false);
+      expect(Number.isNaN(v[1])).toBe(false);
+      expect(Number.isNaN(v[2])).toBe(false);
+    }
+  });
+
+  it('aliasing-safe: out and a fresh vec3 give the same result', () => {
+    const q = quat.eulerY(Math.PI / 3);
+    const a = quat.forward(vec3.create(), q);
+    const b = quat.forward(vec3.create(), q);
+    expectVec3Close(a, b);
+  });
+});

package/src/__tests__/quat.interpolation.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { quat } from '../index';
+
+function expectQuatClose(actual: ArrayLike<number>, expected: ArrayLike<number>): void {
+  for (let i = 0; i < 4; i++) {
+    expect(actual[i]).toBeCloseTo(expected[i] as number, 6);
+  }
+}
+
+describe('quat.slerp endpoint fallback', () => {
+  it('matches nlerp for coincident and anti-parallel inputs', () => {
+    const a = quat.fromAxisAngle(quat.create(), [0, 1, 0], 0.3);
+    const near = quat.fromAxisAngle(quat.create(), [0, 1, 0], 0.3000001);
+    const opposite = new Float32Array([
+      -(a[0] as number),
+      -(a[1] as number),
+      -(a[2] as number),
+      -(a[3] as number),
+    ]);
+    const slerpNear = quat.slerp(quat.create(), a, near, 0.25);
+    const nlerpNear = quat.nlerp(quat.create(), a, near, 0.25);
+    const slerpOpposite = quat.slerp(quat.create(), a, opposite, 0.25);
+    const nlerpOpposite = quat.nlerp(quat.create(), a, opposite, 0.25);
+
+    expectQuatClose(slerpNear, nlerpNear);
+    expectQuatClose(slerpOpposite, nlerpOpposite);
+  });
+
+  it('preserves aliasing-safe endpoint behavior', () => {
+    const a = quat.fromAxisAngle(quat.create(), [1, 0, 0], 0.4);
+    const b = quat.fromAxisAngle(quat.create(), [1, 0, 0], 0.4000001);
+    const expected = quat.slerp(quat.create(), a, b, 0.5);
+    const inPlace = quat.clone(a);
+
+    expect(quat.slerp(inPlace, inPlace, b, 0.5)).toBe(inPlace);
+    expectQuatClose(inPlace, expected);
+  });
+
+  it('keeps the zero-result fallback owned by nlerp', () => {
+    const b = Float32Array.of(1.000001, 0, 0, 0);
+    const result = quat.slerp(quat.create(), [1, 0, 0, 0], b, -1_048_576);
+
+    expect(result).toEqual(quat.identity(quat.create()));
+  });
+});

package/src/__tests__/quat.lookat.test.ts

@@ -0,0 +1,103 @@
+// quat.lookat.test.ts — value tests for quat.fromLookAt (solo round 20260713-141636)
+//
+// Regression guard for the friction that motivated the helper: aiming a camera required
+// hand-wiring `mat4.lookAt → invert → mat3.fromMat4 → quat.fromRotationMatrix`, and because
+// `Mat4Like` ≡ `Mat3Like` ≡ ArrayLike<number>, feeding the mat4 straight into fromRotationMatrix
+// typechecks but reads garbage columns → NaN → nothing renders. These tests pin:
+//   1. fromLookAt matches the correct hand-wired chain,
+//   2. the resulting rotation actually points local -z at the target,
+//   3. the buggy mat4-into-fromRotationMatrix path yields a DIFFERENT (wrong) quaternion,
+//   4. the documented degrade cases (eye≈target, up‖forward).
+
+import { describe, expect, it } from 'vitest';
+import * as mat3 from '../mat3';
+import * as mat4 from '../mat4';
+import * as quat from '../quat';
+import type { Vec3Like } from '../types';
+import * as vec3 from '../vec3';
+
+const EPS = 1e-5;
+
+/** The correct hand-wired chain the helper replaces (round-3 apps/hello/3d-scene lookAtQuat). */
+function handWired(eye: Vec3Like, target: Vec3Like, up: Vec3Like): Float32Array {
+  const view = mat4.lookAt(mat4.create(), eye, target, up);
+  const camWorld = mat4.invert(mat4.create(), view);
+  const rot3 = mat3.fromMat4(mat3.create(), camWorld);
+  return quat.normalize(quat.create(), quat.fromRotationMatrix(quat.create(), rot3));
+}
+
+/** quat double-cover: q and -q are the same rotation. Compare via |dot| ≈ 1. */
+function sameRotation(a: Float32Array, b: Float32Array): boolean {
+  const d =
+    (a[0] as number) * (b[0] as number) +
+    (a[1] as number) * (b[1] as number) +
+    (a[2] as number) * (b[2] as number) +
+    (a[3] as number) * (b[3] as number);
+  return Math.abs(Math.abs(d) - 1) < EPS;
+}
+
+describe('quat.fromLookAt', () => {
+  const cases: Array<{ name: string; eye: Vec3Like; target: Vec3Like; up: Vec3Like }> = [
+    { name: '3d_scene camera', eye: [-2.5, 4.5, 9], target: [0, 0, 0], up: [0, 1, 0] },
+    { name: 'axis-aligned +x view', eye: [5, 0, 0], target: [0, 0, 0], up: [0, 1, 0] },
+    { name: 'above looking down', eye: [0, 10, 0.001], target: [0, 0, 0], up: [0, 1, 0] },
+    { name: 'off-axis', eye: [3, 2, -4], target: [1, 0, 1], up: [0, 1, 0] },
+  ];
+
+  for (const c of cases) {
+    it(`matches the hand-wired lookAt→invert→mat3→fromRotationMatrix chain (${c.name})`, () => {
+      const helper = quat.fromLookAt(quat.create(), c.eye, c.target, c.up);
+      const chain = handWired(c.eye, c.target, c.up);
+      expect(sameRotation(helper, chain)).toBe(true);
+    });
+
+    it(`rotates local -z to point from eye toward target (${c.name})`, () => {
+      const q = quat.fromLookAt(quat.create(), c.eye, c.target, c.up);
+      // world direction the camera faces = rotation applied to local forward (-z)
+      const facing = quat.transformVec3(vec3.create(), q, [0, 0, -1]);
+      const want = vec3.normalize(
+        vec3.create(),
+        vec3.sub(
+          vec3.create(),
+          vec3.create(c.target[0] as number, c.target[1] as number, c.target[2] as number),
+          vec3.create(c.eye[0] as number, c.eye[1] as number, c.eye[2] as number),
+        ),
+      );
+      expect(facing[0]).toBeCloseTo(want[0] as number, 4);
+      expect(facing[1]).toBeCloseTo(want[1] as number, 4);
+      expect(facing[2]).toBeCloseTo(want[2] as number, 4);
+    });
+  }
+
+  it('produces no NaN components (the friction was NaN→black)', () => {
+    const q = quat.fromLookAt(quat.create(), [-2.5, 4.5, 9], [0, 0, 0], [0, 1, 0]);
+    for (let i = 0; i < 4; i++) expect(Number.isNaN(q[i] as number)).toBe(false);
+  });
+
+  it('WITNESS: feeding a mat4 to fromRotationMatrix (the trap) gives a DIFFERENT, wrong result', () => {
+    // This is the exact footgun fromLookAt exists to remove. Mat4Like≡Mat3Like≡ArrayLike<number>,
+    // so this typechecks; it reads mat4 elements 0..8 (garbage columns) instead of a real mat3.
+    const eye: Vec3Like = [-2.5, 4.5, 9];
+    const target: Vec3Like = [0, 0, 0];
+    const up: Vec3Like = [0, 1, 0];
+    const view = mat4.lookAt(mat4.create(), eye, target, up);
+    const camWorld = mat4.invert(mat4.create(), view);
+    // BUG path: pass the 16-element mat4 where a 9-element mat3 is expected.
+    const trap = quat.normalize(quat.create(), quat.fromRotationMatrix(quat.create(), camWorld));
+    const correct = quat.fromLookAt(quat.create(), eye, target, up);
+    expect(sameRotation(trap, correct)).toBe(false);
+  });
+
+  it('degrade: eye ≈ target → identity (no throw)', () => {
+    const q = quat.fromLookAt(quat.create(), [1, 1, 1], [1, 1, 1], [0, 1, 0]);
+    expect(sameRotation(q, quat.identity(quat.create()))).toBe(true);
+  });
+
+  it('degrade: up collinear with forward → still a valid (non-NaN) unit quaternion', () => {
+    // looking straight down with up=(0,1,0): up ‖ forward, alternative-up path engages.
+    const q = quat.fromLookAt(quat.create(), [0, 5, 0], [0, 0, 0], [0, 1, 0]);
+    for (let i = 0; i < 4; i++) expect(Number.isNaN(q[i] as number)).toBe(false);
+    const len = Math.hypot(q[0] as number, q[1] as number, q[2] as number, q[3] as number);
+    expect(len).toBeCloseTo(1, 4);
+  });
+});

package/src/__tests__/quat.property.test.ts

@@ -0,0 +1,150 @@
+// quat.property.test.ts — fast-check property tests (M5 / T-031, AC-11)
+//
+// Category coverage (5 cases / 4 categories):
+//   - identity ×1: q·1 = q (quat multiplicative identity)
+//   - invertibility ×1: q·conjugate(q) ≈ identity (for unit quaternions, conjugate equals inverse)
+//   - normalize idempotence ×1: |normalize(q)| ≈ 1
+//   - slerp endpoints ×2: slerp(a,b,0) ≈ a, slerp(a,b,1) ≈ b
+//
+// quat equivalence: q ≡ -q (same rotation), so endpoint comparison uses |dot(a,b)| ≈ 1 (wiki §4.3).
+//
+// Related: requirements §AC-11; plan-strategy D-P5 / D-P6; wiki/fast-check-property-test §5.5.
+
+import { fc, test } from '@fast-check/vitest';
+import { describe, expect } from 'vitest';
+import * as quat from '../quat';
+import type { Vec3 } from '../types';
+import { EPS_F32, EPS_QUAT, unitQuatArb, unitVec3Arb, vec3Arb, vec4Arb } from './_arbs';
+
+// process.env is read via globalThis to avoid pulling in the @types/node devDep (AC-16 / D-P13).
+const NUM_RUNS = Number.parseInt(
+  (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+    ?.PROPERTY_NUM_RUNS ?? '100',
+  10,
+);
+
+/** quat equivalence comparison: |dot(a,b)| ≈ 1 (double cover q ≡ -q). */
+function quatEquivalent(a: Float32Array, b: Float32Array, eps: number): boolean {
+  const d =
+    (a[0] as number) * (b[0] as number) +
+    (a[1] as number) * (b[1] as number) +
+    (a[2] as number) * (b[2] as number) +
+    (a[3] as number) * (b[3] as number);
+  return Math.abs(Math.abs(d) - 1) < eps;
+}
+
+describe('quat property: identity', () => {
+  test.prop({ q: unitQuatArb() }, { numRuns: NUM_RUNS })('q · identity ≈ q', ({ q }) => {
+    const I = quat.create();
+    quat.identity(I);
+    const out = quat.create();
+    quat.multiply(out, q, I);
+    return quatEquivalent(out, q, EPS_QUAT);
+  });
+});
+
+describe('quat property: invertibility', () => {
+  test.prop({ q: unitQuatArb() }, { numRuns: NUM_RUNS })(
+    'q · conjugate(q) ≈ identity (unit quaternion)',
+    ({ q }) => {
+      const c = quat.create();
+      quat.conjugate(c, q);
+      const out = quat.create();
+      quat.multiply(out, q, c);
+      const expected = quat.create();
+      quat.identity(expected);
+      return quatEquivalent(out, expected, EPS_QUAT);
+    },
+  );
+});
+
+describe('quat property: normalize idempotence', () => {
+  test.prop({ raw: vec4Arb() }, { numRuns: NUM_RUNS })(
+    '|normalize(q)| ≈ 1 (any non-zero quaternion)',
+    ({ raw }) => {
+      // Reuse vec4Arb as un-normalized quat material; the zero vector is mapper-repaired to identity
+      const x = raw[0] as number;
+      const y = raw[1] as number;
+      const z = raw[2] as number;
+      const w = raw[3] as number;
+      const len2 = x * x + y * y + z * z + w * w;
+      const src =
+        len2 < 1e-12
+          ? quat.identity(quat.create())
+          : (Float32Array.of(x, y, z, w) as unknown as ReturnType<typeof quat.create>);
+      const out = quat.create();
+      quat.normalize(out, src);
+      const len = Math.hypot(
+        out[0] as number,
+        out[1] as number,
+        out[2] as number,
+        out[3] as number,
+      );
+      return Math.abs(len - 1) < EPS_F32;
+    },
+  );
+});
+
+describe('quat property: slerp endpoints', () => {
+  test.prop({ a: unitQuatArb(), b: unitQuatArb() }, { numRuns: NUM_RUNS })(
+    'slerp(a, b, 0) ≈ a',
+    ({ a, b }) => {
+      const out = quat.create();
+      quat.slerp(out, a, b, 0);
+      return quatEquivalent(out, a, EPS_QUAT);
+    },
+  );
+
+  test.prop({ a: unitQuatArb(), b: unitQuatArb() }, { numRuns: NUM_RUNS })(
+    'slerp(a, b, 1) ≈ b',
+    ({ a, b }) => {
+      const out = quat.create();
+      quat.slerp(out, a, b, 1);
+      return quatEquivalent(out, b, EPS_QUAT);
+    },
+  );
+});
+
+// M1 / t5 — quat.transformVec3 property +2
+//
+// 2 cases:
+//   - length preservation |q*v*q⁻¹| ≈ |v| (restricted to unitQuatArb, keeps q unit-length premise)
+//   - identity unit transformVec3(quat.identity(), v) ≈ v
+//
+// numRuns: 100 default; EPS 1e-5; use the unitQuatArb factory to avoid random q triggering
+// implicit-scale degeneracy (R-2 countermeasure).
+//
+// Related: requirements §3.3 property +8 (quat contributes 2 cases) + §6 AC-11;
+//          research Finding 5 row 4 + Finding 3 (unit q length preservation 100%);
+//          plan-strategy §3 R-2 + §4.3 key test points table row 4.
+
+describe('quat.transformVec3 property (t5)', () => {
+  test.prop({ q: unitQuatArb(), v: vec3Arb() }, { numRuns: NUM_RUNS })(
+    'length preservation: |q · v · q⁻¹| ≈ |v| (q unit-length premise)',
+    ({ q, v }) => {
+      const out = new Float32Array(3) as Vec3;
+      quat.transformVec3(out, q, v);
+      const lenIn = Math.hypot(v[0] as number, v[1] as number, v[2] as number);
+      const lenOut = Math.hypot(out[0] as number, out[1] as number, out[2] as number);
+      // relative error: scale = max(1, lenIn)
+      const scale = Math.max(1, lenIn);
+      return Math.abs(lenOut - lenIn) < EPS_F32 * scale;
+    },
+  );
+
+  test.prop({ v: unitVec3Arb() }, { numRuns: NUM_RUNS })(
+    'identity unit: transformVec3(identity, v) ≈ v',
+    ({ v }) => {
+      const I = quat.identity(quat.create());
+      const out = new Float32Array(3) as Vec3;
+      quat.transformVec3(out, I, v);
+      const dx = (out[0] as number) - (v[0] as number);
+      const dy = (out[1] as number) - (v[1] as number);
+      const dz = (out[2] as number) - (v[2] as number);
+      return Math.abs(dx) < EPS_F32 && Math.abs(dy) < EPS_F32 && Math.abs(dz) < EPS_F32;
+    },
+  );
+});
+
+void fc;
+void expect;

package/src/__tests__/quat.rotateaxis.test.ts

@@ -0,0 +1,149 @@
+// quat.rotateaxis.test.ts — value tests for quat.rotateAxis (solo round 20260713-164916)
+//
+// Regression guard for the friction that motivated the helper: incrementally rotating an entity
+// each frame required hand-wiring `multiply(q, fromAxisAngle(axis, θ), q)`, and because that loop
+// never re-normalizes, floating-point error accumulates over thousands of frames into a non-unit
+// quaternion (skew / scale artefacts). Demos worked around it (raw sin/cos literals, or an
+// absolute-angle accumulator that can't compose onto an existing orientation). These tests pin:
+//   1. rotateAxis matches the correct hand-wired normalize(multiply(delta, q)) chain,
+//   2. the delta is PRE-multiplied (world-space axis, matching Bevy Transform::rotate order),
+//   3. a full 2π rotation returns to the start orientation,
+//   4. aliasing rotateAxis(q, q, ...) is correct (the common in-place per-frame call),
+//   5. WITNESS: the naive un-normalized multiply loop drifts off unit length; rotateAxis does not,
+//   6. the documented degrade case (zero-length axis → normalize(q), no rotation).
+
+import { describe, expect, it } from 'vitest';
+import * as quat from '../quat';
+import type { QuatLike, Vec3Like } from '../types';
+
+const EPS = 1e-5;
+
+/** quat double-cover: q and -q are the same rotation. Compare via |dot| ≈ 1. */
+function sameRotation(a: QuatLike, b: QuatLike): boolean {
+  const d =
+    (a[0] as number) * (b[0] as number) +
+    (a[1] as number) * (b[1] as number) +
+    (a[2] as number) * (b[2] as number) +
+    (a[3] as number) * (b[3] as number);
+  return Math.abs(Math.abs(d) - 1) < EPS;
+}
+
+/** The correct hand-wired chain the helper replaces: normalize(delta * q). */
+function handWired(q: QuatLike, axis: Vec3Like, angle: number): Float32Array {
+  const delta = quat.fromAxisAngle(quat.create(), axis, angle);
+  return quat.normalize(quat.create(), quat.multiply(quat.create(), delta, q));
+}
+
+const Y: Vec3Like = [0, 1, 0];
+
+describe('quat.rotateAxis', () => {
+  const cases: Array<{ name: string; start: () => Float32Array; axis: Vec3Like; angle: number }> = [
+    {
+      name: 'identity + Y π/2',
+      start: () => quat.identity(quat.create()),
+      axis: Y,
+      angle: Math.PI / 2,
+    },
+    {
+      name: 'identity + X π/3',
+      start: () => quat.identity(quat.create()),
+      axis: [1, 0, 0],
+      angle: Math.PI / 3,
+    },
+    {
+      name: 'non-identity start + Z π/4',
+      start: () => quat.fromAxisAngle(quat.create(), Y, 0.7),
+      axis: [0, 0, 1],
+      angle: Math.PI / 4,
+    },
+    {
+      name: 'unnormalized axis (2Y) π/2',
+      start: () => quat.identity(quat.create()),
+      axis: [0, 2, 0],
+      angle: Math.PI / 2,
+    },
+  ];
+
+  for (const c of cases) {
+    it(`matches the hand-wired normalize(delta * q) chain (${c.name})`, () => {
+      const helper = quat.rotateAxis(quat.create(), c.start(), c.axis, c.angle);
+      const chain = handWired(c.start(), c.axis, c.angle);
+      expect(sameRotation(helper, chain)).toBe(true);
+    });
+
+    it(`stays unit length (${c.name})`, () => {
+      const q = quat.rotateAxis(quat.create(), c.start(), c.axis, c.angle);
+      expect(quat.length(q)).toBeCloseTo(1, 5);
+    });
+  }
+
+  it('PRE-multiplies the delta (world-space axis, Bevy Transform::rotate order): delta*q ≠ q*delta', () => {
+    // Start with a rotation about X, then rotate about Y. Order matters for non-commuting axes.
+    const start = quat.fromAxisAngle(quat.create(), [1, 0, 0], Math.PI / 2);
+    const helper = quat.rotateAxis(quat.create(), start, Y, Math.PI / 2);
+    const pre = quat.normalize(
+      quat.create(),
+      quat.multiply(quat.create(), quat.fromAxisAngle(quat.create(), Y, Math.PI / 2), start),
+    );
+    const post = quat.normalize(
+      quat.create(),
+      quat.multiply(quat.create(), start, quat.fromAxisAngle(quat.create(), Y, Math.PI / 2)),
+    );
+    expect(sameRotation(helper, pre)).toBe(true);
+    // The two orders genuinely differ for these axes — pins that we chose pre, not post.
+    expect(sameRotation(pre, post)).toBe(false);
+  });
+
+  it('a full 2π rotation returns to the starting orientation', () => {
+    const start = quat.fromAxisAngle(quat.create(), [1, 0, 0], 0.9);
+    const out = quat.rotateAxis(quat.create(), start, Y, Math.PI * 2);
+    expect(sameRotation(out, start)).toBe(true);
+  });
+
+  it('is aliasing-safe: rotateAxis(q, q, ...) matches the non-aliased result', () => {
+    const a = quat.fromAxisAngle(quat.create(), Y, 0.3);
+    const b = quat.clone(a);
+    const aliased = quat.rotateAxis(a, a, [1, 0, 0], 0.5);
+    const separate = quat.rotateAxis(quat.create(), b, [1, 0, 0], 0.5);
+    expect(sameRotation(aliased, separate)).toBe(true);
+    expect(quat.length(aliased)).toBeCloseTo(1, 5);
+  });
+
+  it('WITNESS: naive un-normalized multiply loop drifts off unit length; rotateAxis does not', () => {
+    const N = 10000;
+    const step = 0.017; // small per-"frame" angle
+    // Control: the buggy hand-rolled loop demos worked around — multiply only, never normalize.
+    const naive = quat.identity(quat.create());
+    for (let i = 0; i < N; i++) {
+      const delta = quat.fromAxisAngle(quat.create(), Y, step);
+      quat.multiply(naive, delta, naive);
+    }
+    const naiveErr = Math.abs(quat.length(naive) - 1);
+
+    // rotateAxis: identical math + the normalize the naive loop omits.
+    const safe = quat.identity(quat.create());
+    for (let i = 0; i < N; i++) {
+      quat.rotateAxis(safe, safe, Y, step);
+    }
+    const safeErr = Math.abs(quat.length(safe) - 1);
+
+    // The naive loop's unit-length error accumulates; rotateAxis re-normalizes every step so its
+    // error stays at machine epsilon. The friction is real (naive drifts) and the helper removes it:
+    // rotateAxis is strictly tighter to unit length, by orders of magnitude.
+    expect(naiveErr).toBeGreaterThan(1e-6); // measurable drift in the un-normalized loop
+    expect(safeErr).toBeLessThan(1e-6); // rotateAxis holds unit length
+    expect(safeErr).toBeLessThan(naiveErr); // the helper is strictly better
+  });
+
+  it('degrade: zero-length axis → out = normalize(q), no rotation applied (registry #8)', () => {
+    const start = quat.fromAxisAngle(quat.create(), Y, 0.6);
+    const out = quat.rotateAxis(quat.create(), start, [0, 0, 0], 1.23);
+    expect(sameRotation(out, start)).toBe(true);
+    expect(quat.length(out)).toBeCloseTo(1, 5);
+  });
+
+  it('produces no NaN components', () => {
+    const out = quat.rotateAxis(quat.create(), quat.identity(quat.create()), Y, 0.5);
+    for (let i = 0; i < 4; i++) expect(Number.isNaN(out[i] as number)).toBe(false);
+  });
+});