@flighthq/geometry 0.3.0 → 0.3.1-next.1041.35b950c

package/src/matrix4Pool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import { getMatrix4Element } from '@flighthq/geometry/contract';
 import type { Matrix4 } from '@flighthq/types/contract';
 
@@ -65,6 +66,16 @@ describe('clearMatrix4Pool', () => {
 });
 
 describe('releaseMatrix4', () => {
+  it('detaches the previous owner binding before the matrix is reused', () => {
+    const m = acquireMatrix4();
+    attachEntityBinding(m, { owner: 'first' });
+    releaseMatrix4(m);
+
+    const reused = acquireMatrix4();
+    expect(reused).toBe(m);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('handles null safely', () => {
     expect(() => releaseMatrix4(null as unknown as Matrix4)).not.toThrow();
   });

package/src/matrixPool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import type { Matrix } from '@flighthq/types/contract';
 
 import { acquireIdentityMatrix, acquireMatrix, clearMatrixPool, releaseMatrix } from './matrixPool';
@@ -63,6 +64,16 @@ describe('clearMatrixPool', () => {
 });
 
 describe('releaseMatrix', () => {
+  it('detaches the previous owner binding before the matrix is reused', () => {
+    const m = acquireMatrix();
+    attachEntityBinding(m, { owner: 'first' });
+    releaseMatrix(m);
+
+    const reused = acquireMatrix();
+    expect(reused).toBe(m);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('handles null safely', () => {
     expect(() => releaseMatrix(null as unknown as Matrix)).not.toThrow();
   });

package/src/obb.test.ts

@@ -4,14 +4,19 @@ import {
   createObb,
   createRay3D,
   createVector3,
+  crossVector3,
   getClosestPointOnObb,
   intersectRay3DObb,
   isObbIntersectingAabb,
   isObbIntersectingObb,
+  matrix4TransformPoint,
+  normalizeVector3,
+  rotateMatrix4,
   setMatrix4Position,
   setObb,
   transformObbByMatrix4,
 } from '@flighthq/geometry/contract';
+import type { Matrix4, Obb, Vector3 } from '@flighthq/types/contract';
 
 describe('createObb', () => {
   it('stores center, half-extents, and orientation', () => {
@@ -91,6 +96,21 @@ describe('intersectRay3DObb', () => {
     const ray = createRay3D(0, 0, 0, 1, 0, 0);
     expect(intersectRay3DObb(ray, o)).toBe(-1);
   });
+
+  it('returns -1 for a ray with no direction, inside the box or out', () => {
+    // A zero-length direction is not a ray, so it never hits anything — the same answer the
+    // sphere, capsule, plane and triangle tests give, and not a containment test in disguise.
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    expect(intersectRay3DObb(createRay3D(0.5, 0.5, 0.5, 0, 0, 0), o)).toBe(-1);
+    expect(intersectRay3DObb(createRay3D(5, 0, 0, 0, 0, 0), o)).toBe(-1);
+  });
+
+  it('hits a flat OBB whose half-extent along one axis is zero', () => {
+    // A collapsed axis is a plane, not an empty volume: the slab still has a finite entry point.
+    const o = createObb(0, 0, 0, 0, 1, 1, 0, 0, 0, 1);
+    expect(intersectRay3DObb(createRay3D(5, 0, 0, -1, 0, 0), o)).toBeCloseTo(5, 6);
+    expect(intersectRay3DObb(createRay3D(5, 3, 0, -1, 0, 0), o)).toBe(-1);
+  });
 });
 
 describe('isObbIntersectingAabb', () => {
@@ -111,6 +131,15 @@ describe('isObbIntersectingAabb', () => {
     const a = createAabb(-1, -1, -1, 1, 1, 1);
     expect(isObbIntersectingAabb(o, a)).toBe(false);
   });
+
+  it.each([
+    ['x', createAabb(1, 0, 0, 0, 1, 1)],
+    ['y', createAabb(0, 1, 0, 1, 0, 1)],
+    ['z', createAabb(0, 0, 1, 1, 1, 0)],
+  ])('returns false for an AABB empty on %s', (_axis, empty) => {
+    const o = createObb(0, 0, 0, 10, 10, 10, 0, 0, 0, 1);
+    expect(isObbIntersectingAabb(o, empty)).toBe(false);
+  });
 });
 
 describe('isObbIntersectingObb', () => {
@@ -131,6 +160,94 @@ describe('isObbIntersectingObb', () => {
     const b = createObb(10, 0, 0, 1, 1, 1, 0, 0, 0, 1);
     expect(isObbIntersectingObb(a, b)).toBe(false);
   });
+
+  it('remains correct when reading an input reenters another OBB query', () => {
+    const quarterTurn = orientationFromAxisAngle(0, 0, 1, Math.PI * 0.25);
+    const turned = createObb(0, 0, 0, 1, 1, 1, ...quarterTurn);
+    const other = createObb(2.1, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const nestedA = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const nestedB = createObb(10, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    let reentered = false;
+    Object.defineProperty(other, 'orientationY', {
+      get() {
+        if (!reentered) {
+          reentered = true;
+          expect(isObbIntersectingObb(nestedA, nestedB)).toBe(false);
+        }
+        return 0;
+      },
+    });
+
+    // The turned box overlaps at center x=2.1 because its projected radius is sqrt(2). Shared
+    // module scratch lets the nested separated query overwrite its axes and falsely returns false.
+    expect(isObbIntersectingObb(turned, other)).toBe(true);
+    expect(reentered).toBe(true);
+  });
+
+  it('separates on each of the six face axes on its own', () => {
+    // Six of the fifteen candidate axes are the two boxes' own faces. Each case below is tuned so
+    // that ONE named axis is the only one of the fifteen that separates the pair — pushed just
+    // past where that face clears and no further. That is what makes the case pin its axis: drop
+    // that single check and the pair reads as a hit, where a pair separated on several axes at
+    // once would still be rejected by one of the others and hide the loss.
+    const tilt = orientationFromAxisAngle(1, 2, 3, 0.9);
+    const tiltAsMatrix = rotationMatrix4(1, 2, 3, 0.9);
+    const first = createObb(0, 0, 0, 1, 2, 3, 0, 0, 0, 1);
+
+    for (const { axis, ofTurnedBox, extents, clear } of FACE_AXIS_SEPARATIONS) {
+      const direction = createUnitVector3(axis);
+      if (ofTurnedBox) matrix4TransformPoint(direction, tiltAsMatrix, direction);
+
+      const away = createObb(
+        direction.x * clear,
+        direction.y * clear,
+        direction.z * clear,
+        extents[0],
+        extents[1],
+        extents[2],
+        ...tilt,
+      );
+      expect(isObbIntersectingObb(first, away)).toBe(false);
+
+      const concentric = createObb(0, 0, 0, extents[0], extents[1], extents[2], ...tilt);
+      expect(isObbIntersectingObb(first, concentric)).toBe(true);
+    }
+  });
+
+  it('separates on every one of the nine edge-cross axes', () => {
+    // The nine edge axes are nine hand-written index permutations of one cross-product, so a
+    // transposed subscript in any single one is invisible until that exact edge pair decides a
+    // case. Each pair below is a rod along one local axis of each box, thin enough and offset
+    // along their common perpendicular by little enough that its own cross axis is the only
+    // separating axis in the whole set: a wrong expression there reads as a hit.
+    const tilt = orientationFromAxisAngle(1, 2, 3, 0.9);
+    const tiltAsMatrix = rotationMatrix4(1, 2, 3, 0.9);
+    const rodLongDirection = createVector3();
+
+    for (let firstLongAxis = 0; firstLongAxis < 3; firstLongAxis++) {
+      for (let secondLongAxis = 0; secondLongAxis < 3; secondLongAxis++) {
+        const first = createRodObb(0, 0, 0, firstLongAxis, 0, 0, 0, 1);
+        matrix4TransformPoint(rodLongDirection, tiltAsMatrix, createUnitVector3(secondLongAxis));
+
+        const perpendicular = createVector3();
+        crossVector3(perpendicular, createUnitVector3(firstLongAxis), rodLongDirection);
+        normalizeVector3(perpendicular, perpendicular);
+
+        const clear = 0.3;
+        const separated = createRodObb(
+          perpendicular.x * clear,
+          perpendicular.y * clear,
+          perpendicular.z * clear,
+          secondLongAxis,
+          ...tilt,
+        );
+        expect(isObbIntersectingObb(first, separated)).toBe(false);
+
+        const concentric = createRodObb(0, 0, 0, secondLongAxis, ...tilt);
+        expect(isObbIntersectingObb(first, concentric)).toBe(true);
+      }
+    }
+  });
 });
 
 describe('setObb', () => {
@@ -180,4 +297,164 @@ describe('transformObbByMatrix4', () => {
     expect(o.centerY).toBeCloseTo(3, 6);
     expect(o.halfExtentX).toBeCloseTo(1, 6);
   });
+
+  it('rotates the box the same way the matrix rotates points', () => {
+    // The orientation extracted from the matrix must turn the box in the matrix's own direction.
+    // A conjugated extraction turns it by the same angle about the opposite axis, which is
+    // invisible for axis-aligned boxes and half turns but wrong for every general rotation.
+    expectTransformedObbMatchesRotatedPoints(rotationMatrix4(1, 0, 0, 0.7), createTiltedObb());
+    expectTransformedObbMatchesRotatedPoints(rotationMatrix4(1, 2, 3, 0.9), createTiltedObb());
+  });
+
+  it('rotates the box correctly near a half turn about each axis', () => {
+    // A half turn drives the three `trace <= 0` branches of the matrix-to-quaternion extraction,
+    // one per dominant diagonal term. Just short of pi so the conjugate is a different rotation:
+    // at exactly pi the quaternion equals its own conjugate up to sign and hides an error.
+    const nearHalfTurn = Math.PI - 0.01;
+    expectTransformedObbMatchesRotatedPoints(rotationMatrix4(1, 0, 0, nearHalfTurn), createTiltedObb());
+    expectTransformedObbMatchesRotatedPoints(rotationMatrix4(0, 1, 0, nearHalfTurn), createTiltedObb());
+    expectTransformedObbMatchesRotatedPoints(rotationMatrix4(0, 0, 1, nearHalfTurn), createTiltedObb());
+  });
+
+  it('flattens the box along a collapsed matrix column and keeps the other extents', () => {
+    // A zero-length column has no direction to read, so that axis falls back to its identity
+    // direction rather than dividing by zero, and the half-extent along it goes to zero.
+    const o = createObb(0, 0, 0, 2, 3, 4, 0, 0, 0, 1);
+    const m = createMatrix4(0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
+    const out = createObb(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+    transformObbByMatrix4(out, o, m);
+    expect(out.halfExtentX).toBe(0);
+    expect(out.halfExtentY).toBeCloseTo(3, 6);
+    expect(out.halfExtentZ).toBeCloseTo(4, 6);
+    expect(out.orientationW).toBeCloseTo(1, 6);
+  });
+
+  it('collapses the box to a point at the matrix position when every column is zero', () => {
+    // All three columns collapse, so the fallback rotation is the identity and the box keeps the
+    // orientation it came in with — the transform contributes nothing but the translation.
+    const tilt = orientationFromAxisAngle(1, 1, 1, 0.6);
+    const o = createObb(1, 2, 3, 2, 3, 4, ...tilt);
+    const m = createMatrix4(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5, 6, 7, 1);
+    const out = createObb(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+    transformObbByMatrix4(out, o, m);
+    expect(out.centerX).toBeCloseTo(5, 6);
+    expect(out.centerY).toBeCloseTo(6, 6);
+    expect(out.centerZ).toBeCloseTo(7, 6);
+    expect(out.halfExtentX).toBe(0);
+    expect(out.halfExtentY).toBe(0);
+    expect(out.halfExtentZ).toBe(0);
+    expect(out.orientationX).toBeCloseTo(tilt[0], 6);
+    expect(out.orientationY).toBeCloseTo(tilt[1], 6);
+    expect(out.orientationZ).toBeCloseTo(tilt[2], 6);
+    expect(out.orientationW).toBeCloseTo(tilt[3], 6);
+  });
 });
+
+// A thin rod: long along one of its own local axes, barely thick along the other two, so the
+// dominant feature of the box is a single edge direction.
+function createRodObb(
+  centerX: number,
+  centerY: number,
+  centerZ: number,
+  longAxis: number,
+  orientationX: number,
+  orientationY: number,
+  orientationZ: number,
+  orientationW: number,
+): Obb {
+  const thickness = 0.1;
+  return createObb(
+    centerX,
+    centerY,
+    centerZ,
+    longAxis === 0 ? 3 : thickness,
+    longAxis === 1 ? 3 : thickness,
+    longAxis === 2 ? 3 : thickness,
+    orientationX,
+    orientationY,
+    orientationZ,
+    orientationW,
+  );
+}
+
+// An OBB with three distinct half-extents at an orientation that shares no axis with the world,
+// so no box symmetry can mask a wrong rotation. Axis (1, 2, 3) normalized, turned by 0.8 radians.
+function createTiltedObb(): Obb {
+  return createObb(0, 0, 0, 3, 2, 1, ...orientationFromAxisAngle(1, 2, 3, 0.8));
+}
+
+function createUnitVector3(axis: number): Vector3 {
+  return createVector3(axis === 0 ? 1 : 0, axis === 1 ? 1 : 0, axis === 2 ? 1 : 0);
+}
+
+// The `orientationX, orientationY, orientationZ, orientationW` arguments `createObb` and `setObb`
+// take, spelled as a turn about an axis so the test states the rotation rather than four decimals.
+function orientationFromAxisAngle(
+  axisX: number,
+  axisY: number,
+  axisZ: number,
+  radians: number,
+): [number, number, number, number] {
+  const length = Math.sqrt(axisX * axisX + axisY * axisY + axisZ * axisZ);
+  const half = Math.sin(radians / 2);
+  return [(axisX / length) * half, (axisY / length) * half, (axisZ / length) * half, Math.cos(radians / 2)];
+}
+
+// Asserts the transformed OBB sits where the matrix puts the original: for probe points all around
+// it, the closest point on the transformed box equals the transformed closest point on the original.
+// This reads the orientation through the same axes every OBB query uses, so it fails on any
+// orientation error rather than on a chosen quaternion convention.
+function expectTransformedObbMatchesRotatedPoints(m: Readonly<Matrix4>, obb: Readonly<Obb>): void {
+  const transformed = createObb(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+  transformObbByMatrix4(transformed, obb, m);
+
+  const expected = createVector3();
+  const actual = createVector3();
+  const probe = createVector3();
+
+  for (const [px, py, pz] of [
+    [10, 0, 0],
+    [0, 10, 0],
+    [0, 0, 10],
+    [4, -6, 2],
+    [-5, 3, 8],
+    [7, 7, -7],
+  ]) {
+    getClosestPointOnObb(expected, obb, createVector3(px, py, pz));
+    matrix4TransformPoint(expected, m, expected);
+
+    matrix4TransformPoint(probe, m, createVector3(px, py, pz));
+    getClosestPointOnObb(actual, transformed, probe);
+
+    expect(actual.x).toBeCloseTo(expected.x, 4);
+    expect(actual.y).toBeCloseTo(expected.y, 4);
+    expect(actual.z).toBeCloseTo(expected.z, 4);
+  }
+}
+
+// `rotateMatrix4` expects a unit axis, so normalize here rather than at every call site.
+function rotationMatrix4(axisX: number, axisY: number, axisZ: number, radians: number): Matrix4 {
+  const length = Math.sqrt(axisX * axisX + axisY * axisY + axisZ * axisZ);
+  const m = createMatrix4();
+  rotateMatrix4(m, m, createVector3(axisX / length, axisY / length, axisZ / length), radians);
+  return m;
+}
+
+// One case per face axis of the two boxes in `separates on each of the six face axes on its own`.
+// The first box is fixed at half-extents (1, 2, 3); the second carries the listed half-extents and
+// a turn about (1, 2, 3), pushed `clear` along the named axis — `axis` indexes x, y, z, and
+// `ofTurnedBox` says whether that is the second box's own axis rather than a world one. The
+// shapes and distances are the ones for which that axis, and only it, separates the pair.
+const FACE_AXIS_SEPARATIONS: ReadonlyArray<{
+  readonly axis: number;
+  readonly ofTurnedBox: boolean;
+  readonly extents: readonly [number, number, number];
+  readonly clear: number;
+}> = [
+  { axis: 0, clear: 3.8, extents: [2.5, 1.5, 0.5], ofTurnedBox: false },
+  { axis: 1, clear: 4.9, extents: [2.5, 1.5, 0.5], ofTurnedBox: false },
+  { axis: 2, clear: 5.9, extents: [0.5, 1.5, 2.5], ofTurnedBox: false },
+  { axis: 0, clear: 3.6, extents: [0.5, 1.5, 2.5], ofTurnedBox: true },
+  { axis: 1, clear: 4.7, extents: [0.5, 1.5, 2.5], ofTurnedBox: true },
+  { axis: 2, clear: 3.7, extents: [2.5, 1.5, 0.5], ofTurnedBox: true },
+];

package/src/plane.test.ts

@@ -222,4 +222,24 @@ describe('setPlaneFromPoints', () => {
     expect(getPlaneSignedDistanceToPoint(p, b)).toBeCloseTo(0, 5);
     expect(getPlaneSignedDistanceToPoint(p, c)).toBeCloseTo(0, 5);
   });
+
+  it('writes a zero plane for three points that do not span one', () => {
+    // Points in a line — or on top of each other — describe no single plane, and there is no
+    // normal to scale to unit length. The coefficients come out zero rather than dividing by the
+    // zero length, which would put NaN in a plane the caller then culls against.
+    const p = createPlane(1, 1, 1, 1);
+    setPlaneFromPoints(p, createVector3(0, 0, 0), createVector3(1, 1, 1), createVector3(2, 2, 2));
+    expect(p.a).toBe(0);
+    expect(p.b).toBe(0);
+    expect(p.c).toBe(0);
+    expect(p.d).toBe(0);
+
+    const q = createPlane(1, 1, 1, 1);
+    const same = createVector3(4, 5, 6);
+    setPlaneFromPoints(q, same, same, same);
+    expect(q.a).toBe(0);
+    expect(q.b).toBe(0);
+    expect(q.c).toBe(0);
+    expect(q.d).toBe(0);
+  });
 });

package/src/quaternion.test.ts

@@ -13,6 +13,7 @@ import {
   matrix4TransformPoint,
   multiplyQuaternion,
   normalizeQuaternion,
+  normalizeVector3,
   rotateVector3ByQuaternion,
   setMatrix4FromQuaternion,
   setQuaternion,
@@ -221,6 +222,21 @@ describe('getQuaternionEuler', () => {
       expect(Math.abs(getQuaternionDot(q, back))).toBeCloseTo(1, 6);
     },
   );
+  // A Quaternion structurally satisfies Vector3Like, so a caller can pass one object as both the
+  // euler output and the rotation source. All four components must be read before the first write.
+  it('writes the same values whether out aliases source or not', () => {
+    const source = createQuaternion();
+    setQuaternionFromEuler(source, 0.3, 0.4, 0.5);
+    const distinct = createVector3();
+    const aliased = cloneQuaternion(source);
+
+    getQuaternionEuler(distinct, source);
+    getQuaternionEuler(aliased, aliased);
+
+    expect(aliased.x).toBeCloseTo(distinct.x, 12);
+    expect(aliased.y).toBeCloseTo(distinct.y, 12);
+    expect(aliased.z).toBeCloseTo(distinct.z, 12);
+  });
 });
 
 describe('inverseQuaternion', () => {
@@ -242,6 +258,25 @@ describe('inverseQuaternion', () => {
     inverseQuaternion(q, q);
     expectQuaternionClose(q, expected.x, expected.y, expected.z, expected.w);
   });
+
+  // Inverting divides by the squared length, so an all-zero quaternion is the one input that can
+  // reach the caller as NaN. The guard trades it for the identity rotation.
+  it('writes the identity rotation for a zero-length quaternion', () => {
+    const out = createQuaternion(9, 9, 9, 9);
+
+    inverseQuaternion(out, createQuaternion(0, 0, 0, 0));
+
+    expectQuaternionClose(out, 0, 0, 0, 1);
+  });
+
+  it('divides a non-unit quaternion by its squared length', () => {
+    const out = createQuaternion();
+
+    // |q|² = 4, so the inverse is the conjugate scaled by 1/4.
+    inverseQuaternion(out, createQuaternion(0, 2, 0, 0));
+
+    expectQuaternionClose(out, 0, -0.5, 0, 0);
+  });
 });
 
 describe('multiplyQuaternion', () => {
@@ -416,6 +451,42 @@ describe('setQuaternionFromMatrix4', () => {
     setQuaternionFromMatrix4(back, createMatrix4());
     expectQuaternionClose(back, 0, 0, 0, 1);
   });
+
+  // Extraction picks one of four formulas by which diagonal term dominates; only the trace case is
+  // reached by small rotations. A half turn about each axis selects one of the other three, and the
+  // round trip is what proves they agree with setMatrix4FromQuaternion rather than merely running.
+  it.each([
+    ['x', createVector3(1, 0, 0)],
+    ['y', createVector3(0, 1, 0)],
+    ['z', createVector3(0, 0, 1)],
+  ])('round-trips a half turn about %s', (_axis, axis) => {
+    const q = createQuaternion();
+    setQuaternionFromAxisAngle(q, axis, Math.PI);
+    const m = createMatrix4();
+    setMatrix4FromQuaternion(m, q);
+
+    const back = createQuaternion();
+    setQuaternionFromMatrix4(back, m);
+
+    const roundTripped = createMatrix4();
+    setMatrix4FromQuaternion(roundTripped, back);
+    for (let i = 0; i < 16; i++) {
+      expect(roundTripped.m[i]).toBeCloseTo(m.m[i], 6);
+    }
+  });
+  it('writes the same values whether out is fresh or already holds a rotation', () => {
+    const m = createMatrix4();
+    const q = createQuaternion();
+    setQuaternionFromAxisAngle(q, createVector3(0, 1, 0), Math.PI / 3);
+    setMatrix4FromQuaternion(m, q);
+
+    const fresh = createQuaternion();
+    const reused = createQuaternion(9, 9, 9, 9);
+    setQuaternionFromMatrix4(fresh, m);
+    setQuaternionFromMatrix4(reused, m);
+
+    expectQuaternionClose(reused, fresh.x, fresh.y, fresh.z, fresh.w);
+  });
 });
 
 describe('setQuaternionFromUnitVectors', () => {
@@ -459,6 +530,20 @@ describe('setQuaternionFromUnitVectors', () => {
     expect(out.y).toBeCloseTo(-1, 5);
     expect(out.z).toBeCloseTo(0, 5);
   });
+  it('writes the same values whether out aliases an input or not', () => {
+    const from = createVector3(1, 0, 0);
+    const to = createVector3(0, 1, 0);
+    const distinct = createQuaternion();
+    setQuaternionFromUnitVectors(distinct, from, to);
+
+    const aliasedFrom = createQuaternion(from.x, from.y, from.z, 0);
+    setQuaternionFromUnitVectors(aliasedFrom, aliasedFrom, to);
+    expectQuaternionClose(aliasedFrom, distinct.x, distinct.y, distinct.z, distinct.w);
+
+    const aliasedTo = createQuaternion(to.x, to.y, to.z, 0);
+    setQuaternionFromUnitVectors(aliasedTo, from, aliasedTo);
+    expectQuaternionClose(aliasedTo, distinct.x, distinct.y, distinct.z, distinct.w);
+  });
 });
 
 describe('setQuaternionIdentity', () => {
@@ -470,10 +555,21 @@ describe('setQuaternionIdentity', () => {
 });
 
 describe('setQuaternionLookRotation', () => {
-  it('forward parallel to up yields identity (degenerate case)', () => {
-    const q = createQuaternion(1, 2, 3, 4);
-    setQuaternionLookRotation(q, createVector3(0, 1, 0), createVector3(0, 1, 0));
-    expectQuaternionClose(q, 0, 0, 0, 1);
+  it.each([
+    ['non-z-aligned', createVector3(2, 3, 6)],
+    ['z-aligned', createVector3(1, 2, 20)],
+  ])('preserves an asymmetric %s forward direction when up is parallel', (_case, rawForward) => {
+    const length = Math.sqrt(rawForward.x * rawForward.x + rawForward.y * rawForward.y + rawForward.z * rawForward.z);
+    const forward = createVector3(rawForward.x / length, rawForward.y / length, rawForward.z / length);
+    const q = createQuaternion();
+
+    setQuaternionLookRotation(q, forward, forward);
+
+    const rotated = createVector3();
+    rotateVector3ByQuaternion(rotated, createVector3(0, 0, 1), q);
+    expect(rotated.x).toBeCloseTo(forward.x, 6);
+    expect(rotated.y).toBeCloseTo(forward.y, 6);
+    expect(rotated.z).toBeCloseTo(forward.z, 6);
   });
 
   it('zero forward yields identity (degenerate case)', () => {
@@ -495,6 +591,55 @@ describe('setQuaternionLookRotation', () => {
     setQuaternionLookRotation(q, createVector3(0, 0, 1), createVector3(0, 1, 0));
     expectQuaternionClose(q, 0, 0, 0, 1);
   });
+
+  it('rotates +Z onto an asymmetric forward direction', () => {
+    const forward = createVector3(2 / 7, 3 / 7, 6 / 7);
+    const q = createQuaternion();
+
+    setQuaternionLookRotation(q, forward, createVector3(0, 1, 0));
+
+    const rotated = createVector3();
+    rotateVector3ByQuaternion(rotated, createVector3(0, 0, 1), q);
+    expect(rotated.x).toBeCloseTo(forward.x, 6);
+    expect(rotated.y).toBeCloseTo(forward.y, 6);
+    expect(rotated.z).toBeCloseTo(forward.z, 6);
+  });
+
+  // Looking backwards drives the basis trace negative, which selects one of the three
+  // largest-diagonal formulas instead of the trace one. The contract is the same in every case:
+  // the quaternion must rotate +Z onto `forward`. A wrong branch produces a valid-looking unit
+  // quaternion that aims somewhere else entirely, which no NaN check would catch.
+  it.each([
+    ['-Z with +Y up', createVector3(0, 0, -1), createVector3(0, 1, 0)],
+    ['-Z with -Y up', createVector3(0, 0, -1), createVector3(0, -1, 0)],
+    ['+Z with -Y up', createVector3(0, 0, 1), createVector3(0, -1, 0)],
+    ['-X with -Y up', createVector3(-1, 0, 0), createVector3(0, -1, 0)],
+  ])('rotates +Z onto forward for %s', (_case, forward, up) => {
+    const q = createQuaternion();
+    setQuaternionLookRotation(q, forward, up);
+
+    const rotated = createVector3();
+    rotateVector3ByQuaternion(rotated, createVector3(0, 0, 1), q);
+
+    expect(rotated.x).toBeCloseTo(forward.x, 6);
+    expect(rotated.y).toBeCloseTo(forward.y, 6);
+    expect(rotated.z).toBeCloseTo(forward.z, 6);
+  });
+  it('writes the same values whether out aliases an input or not', () => {
+    const forward = createVector3(0, 0, -1);
+    const up = createVector3(0, 1, 0);
+    const distinct = createQuaternion();
+    setQuaternionLookRotation(distinct, forward, up);
+
+    const aliased = createQuaternion(forward.x, forward.y, forward.z, 0);
+    setQuaternionLookRotation(aliased, aliased, up);
+
+    expectQuaternionClose(aliased, distinct.x, distinct.y, distinct.z, distinct.w);
+
+    const aliasedUp = createQuaternion(up.x, up.y, up.z, 0);
+    setQuaternionLookRotation(aliasedUp, forward, aliasedUp);
+    expectQuaternionClose(aliasedUp, distinct.x, distinct.y, distinct.z, distinct.w);
+  });
 });
 
 describe('slerpQuaternion', () => {
@@ -510,6 +655,46 @@ describe('slerpQuaternion', () => {
     expectQuaternionClose(out, b.x, b.y, b.z, b.w);
   });
 
+  it('halfway interpolates about a tilted axis, exercising every component', () => {
+    // Every other slerp case rotates about (0,1,0), which leaves x and z zero in BOTH inputs — so the
+    // x and z arms of the shortest-path negation and of the final blend cannot be observed at all, and
+    // a sign error in either would pass. A tilted, normalized axis gives all four components distinct
+    // non-zero magnitudes. The oracle is independent of slerp: halfway between identity and R(axis, θ)
+    // is R(axis, θ/2) by definition of the axis-angle form.
+    const axis = createVector3(1, 2, 3);
+    normalizeVector3(axis, axis);
+    const a = createQuaternion();
+    const b = createQuaternion();
+    setQuaternionFromAxisAngle(b, axis, Math.PI / 2);
+
+    const out = createQuaternion();
+    slerpQuaternion(out, a, b, 0.5);
+
+    const expected = createQuaternion();
+    setQuaternionFromAxisAngle(expected, axis, Math.PI / 4);
+    expectQuaternionClose(out, expected.x, expected.y, expected.z, expected.w);
+  });
+
+  it('takes the shortest path when the inputs face opposite hemispheres', () => {
+    // A quaternion and its negation are the SAME rotation, so slerping toward either must give the same
+    // result — that is what the cosHalfTheta < 0 branch exists to guarantee. Without an input pair whose
+    // dot product is negative, that branch never runs and its per-component sign flips are unobservable;
+    // the tilted axis then keeps bx and bz non-zero so a dropped flip on either actually moves the answer.
+    const axis = createVector3(1, 2, 3);
+    normalizeVector3(axis, axis);
+    const a = createQuaternion();
+    const far = createQuaternion();
+    setQuaternionFromAxisAngle(far, axis, Math.PI / 2);
+    const negated = createQuaternion(-far.x, -far.y, -far.z, -far.w);
+
+    const out = createQuaternion();
+    slerpQuaternion(out, a, negated, 0.5);
+
+    const expected = createQuaternion();
+    setQuaternionFromAxisAngle(expected, axis, Math.PI / 4);
+    expectQuaternionClose(out, expected.x, expected.y, expected.z, expected.w);
+  });
+
   it('halfway interpolates the angle', () => {
     const a = createQuaternion();
     const b = createQuaternion();
@@ -537,4 +722,37 @@ describe('slerpQuaternion', () => {
     slerpQuaternion(b, a, b, 0);
     expectQuaternionClose(b, a.x, a.y, a.z, a.w);
   });
+
+  // q and -q name the same rotation, so an interpolator that does not flip the sign travels the
+  // long way round: it would pass through a 135-degree pose here instead of a 45-degree one.
+  it('takes the shorter arc when the inputs have a negative dot product', () => {
+    const a = createQuaternion();
+    const quarterTurn = createQuaternion();
+    setQuaternionFromAxisAngle(quarterTurn, createVector3(0, 1, 0), Math.PI / 2);
+    const negated = createQuaternion(-quarterTurn.x, -quarterTurn.y, -quarterTurn.z, -quarterTurn.w);
+
+    const out = createQuaternion();
+    slerpQuaternion(out, a, negated, 0.5);
+
+    const eighthTurn = createQuaternion();
+    setQuaternionFromAxisAngle(eighthTurn, createVector3(0, 1, 0), Math.PI / 4);
+    expect(Math.abs(getQuaternionDot(out, eighthTurn))).toBeCloseTo(1, 6);
+  });
+
+  // Nearly-collinear inputs make sin(halfTheta) approach zero; without the linear fallback both
+  // scale factors divide by it and the caller receives NaN.
+  it('interpolates nearly identical rotations without dividing by zero', () => {
+    const a = createQuaternion();
+    const b = createQuaternion();
+    setQuaternionFromAxisAngle(b, createVector3(0, 1, 0), 1e-7);
+
+    const out = createQuaternion();
+    slerpQuaternion(out, a, b, 0.5);
+
+    expect(Number.isFinite(out.x)).toBe(true);
+    expect(Number.isFinite(out.y)).toBe(true);
+    expect(Number.isFinite(out.z)).toBe(true);
+    expect(Number.isFinite(out.w)).toBe(true);
+    expect(getQuaternionDot(out, out)).toBeCloseTo(1, 6);
+  });
 });