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

package/src/matrix4.test.ts

@@ -26,6 +26,8 @@ import {
   interpolateMatrix4,
   inverseMatrix4,
   isAffineMatrix4,
+  getVector3Dot,
+  getVector3Length,
   matrix4TransformPoint,
   matrix4TransformVector,
   matrix4TransformVectors,
@@ -49,6 +51,7 @@ import {
   setOrthographicMatrix4,
   setPerspectiveMatrix4,
   setQuaternionFromAxisAngle,
+  setVector3,
   translateMatrix4,
   transposeMatrix4,
   writeMatrix4ToFloat32Array,
@@ -59,32 +62,55 @@ const X_AXIS = { x: 1, y: 0, z: 0, w: 0 };
 const Y_AXIS = { x: 0, y: 1, z: 0, w: 0 };
 const Z_AXIS = { x: 0, y: 0, z: 1, w: 0 };
 
+// Rotation AND non-uniform scale AND translation together. A diagonal matrix, a uniform scale, or a
+// zero translation each make two different compositions agree — that coincidence is what hid the
+// inverted operands from the previous suite, so every composition test below starts from this.
+function discriminatingMatrix4(): Matrix4 {
+  const m = createMatrix4();
+  setMatrix4(m, 0, 2, 0, 0, -3, 0, 0, 0, 0, 0, 4, 0, 7, 8, 9, 1);
+  return m;
+}
+
 describe('appendMatrix4', () => {
-  it('is equivalent to multiply(out, source, other)', () => {
-    const a = createMatrix4();
-    translateMatrix4(a, a, 5, 0, 0);
-    const b = createMatrix4();
-    scaleMatrix4(b, b, 2, 2, 2);
+  // OpenFL's Matrix3D.append composes `other` so it applies AFTER everything already in `source`,
+  // which under Flight's column-vector convention is the LEFT operand: out = other · source. Asserting
+  // against a hand-built product rather than a captured result is what keeps this readable as algebra.
+  it('composes other after source: out = other · source', () => {
+    const source = discriminatingMatrix4();
+    const other = createMatrix4();
+    setMatrix4(other, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 0, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, other, source);
+
+    const out = createMatrix4();
+    appendMatrix4(out, source, other);
 
-    const out1 = createMatrix4();
-    appendMatrix4(out1, a, b);
+    expect(Array.from(out.m)).toEqual(Array.from(expected.m));
+  });
+
+  it('is not the other operand order', () => {
+    const source = discriminatingMatrix4();
+    const other = createMatrix4();
+    setMatrix4(other, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 0, 1);
+    const transposedOrder = createMatrix4();
+    multiplyMatrix4(transposedOrder, source, other);
 
-    const out2 = createMatrix4();
-    multiplyMatrix4(out2, a, b);
+    const out = createMatrix4();
+    appendMatrix4(out, source, other);
 
-    expect(equalsMatrix4(out1, out2)).toBe(true);
+    expect(Array.from(out.m)).not.toEqual(Array.from(transposedOrder.m));
   });
 
   it('supports out === source', () => {
-    const a = createMatrix4();
-    translateMatrix4(a, a, 5, 0, 0);
-    const b = createMatrix4();
-    scaleMatrix4(b, b, 2, 3, 4);
+    const source = discriminatingMatrix4();
+    const other = createMatrix4();
+    scaleMatrix4(other, other, 2, 3, 4);
     const expected = createMatrix4();
-    appendMatrix4(expected, a, b);
+    appendMatrix4(expected, source, other);
+
+    appendMatrix4(source, source, other);
 
-    appendMatrix4(a, a, b);
-    expect(equalsMatrix4(a, expected)).toBe(true);
+    expect(Array.from(source.m)).toEqual(Array.from(expected.m));
   });
 });
 
@@ -100,95 +126,173 @@ describe('appendRotationMatrix4', () => {
     expect(m.m[5]).toBeCloseTo(0);
   });
 
-  it('does not rotate existing translation when appending rotation', () => {
+  // A world-frame rotation turns the space the matrix sits in, so the existing translation sweeps
+  // around the origin with it. Before the operand fix this function left the translation in place,
+  // which is the local behavior and belonged to prependRotationMatrix4.
+  it('sweeps the existing translation around the origin', () => {
     const m = createMatrix4();
     translateMatrix4(m, m, 10, 0, 0);
 
     appendRotationMatrix4(m, m, Math.PI / 2, Z_AXIS);
 
-    expect(m.m[12]).toBe(10);
-    expect(m.m[13]).toBe(0);
+    expect(m.m[12]).toBeCloseTo(0, 6);
+    expect(m.m[13]).toBeCloseTo(10, 6);
   });
 
-  it('rotates around pivot point', () => {
-    const m = createMatrix4();
-    translateMatrix4(m, m, 10, 0, 0);
+  it('applies the rotation after source: out = R · source', () => {
+    const source = discriminatingMatrix4();
+    const rotation = createMatrix4();
+    appendRotationMatrix4(rotation, rotation, Math.PI / 3, Z_AXIS);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, rotation, source);
 
-    appendRotationMatrix4(m, m, Math.PI / 2, Z_AXIS, { x: 5, y: 0, z: 0, w: 1 });
+    const out = createMatrix4();
+    appendRotationMatrix4(out, source, Math.PI / 3, Z_AXIS);
 
-    expect(m.m[12]).toBeCloseTo(5);
-    expect(m.m[13]).toBeCloseTo(5);
+    for (let i = 0; i < 16; i++) expect(out.m[i]).toBeCloseTo(expected.m[i], 5);
   });
 
-  it('appendRotation and prependRotation match on identity', () => {
-    const a = createMatrix4();
-    const b = createMatrix4();
+  // The pivot is the point the rotation holds still. Asserting that property rather than a captured
+  // translation is what distinguishes a correct composite from the transposed T(-p)·R·T(p) this
+  // function used to build — the old test asserted the inverted numbers and so could never fail.
+  it('holds the pivot point fixed', () => {
+    const source = createMatrix4();
+    translateMatrix4(source, source, 10, 0, 0);
+    const pivot = { x: 5, y: 0, z: 0, w: 1 };
 
-    appendRotationMatrix4(a, a, Math.PI / 4, Z_AXIS);
-    prependRotationMatrix4(b, b, Math.PI / 4, Z_AXIS);
+    const out = createMatrix4();
+    appendRotationMatrix4(out, source, Math.PI / 2, Z_AXIS, pivot);
 
-    expect(equalsMatrix4(a, b)).toBe(true);
+    // A world-frame rotation about `pivot` fixes the world point `pivot`, so the source point that
+    // already lands there must still land there.
+    const landsOnPivot = createVector3(-5, 0, 0);
+    const before = createVector3();
+    matrix4TransformPoint(before, source, landsOnPivot);
+    expect(before.x).toBeCloseTo(pivot.x, 6);
+
+    const after = createVector3();
+    matrix4TransformPoint(after, out, landsOnPivot);
+    expect(after.x).toBeCloseTo(pivot.x, 6);
+    expect(after.y).toBeCloseTo(pivot.y, 6);
+    expect(after.z).toBeCloseTo(pivot.z, 6);
+  });
+
+  it('differs from the local prependRotationMatrix4 on a translated matrix', () => {
+    const source = discriminatingMatrix4();
+    const world = createMatrix4();
+    const local = createMatrix4();
+
+    appendRotationMatrix4(world, source, Math.PI / 3, Z_AXIS);
+    prependRotationMatrix4(local, source, Math.PI / 3, Z_AXIS);
+
+    expect(Array.from(world.m)).not.toEqual(Array.from(local.m));
+  });
+
+  it('writes the same values whether out aliases source or not', () => {
+    const source = discriminatingMatrix4();
+    const distinct = createMatrix4();
+    const aliased = cloneMatrix4(source);
+
+    appendRotationMatrix4(distinct, source, Math.PI / 3, Z_AXIS, { x: 1, y: 2, z: 3, w: 1 });
+    appendRotationMatrix4(aliased, aliased, Math.PI / 3, Z_AXIS, { x: 1, y: 2, z: 3, w: 1 });
+
+    expect(Array.from(aliased.m)).toEqual(Array.from(distinct.m));
   });
 });
 
 describe('appendScaleMatrix4', () => {
-  it('scales an identity matrix', () => {
-    const m = createMatrix4();
+  // Inherits its composition from appendMatrix4 — it is not implemented separately, so this test also
+  // pins that the wrapper was corrected by inheritance rather than by hand.
+  it('applies the scale after source: out = S · source', () => {
+    const source = discriminatingMatrix4();
+    const scale = createMatrix4();
+    setMatrix4(scale, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 4, 0, 0, 0, 0, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, scale, source);
 
-    appendScaleMatrix4(m, m, 2, 3, 4);
+    const out = createMatrix4();
+    appendScaleMatrix4(out, source, 2, 3, 4);
 
-    expect(m.m[0]).toBe(2);
-    expect(m.m[5]).toBe(3);
-    expect(m.m[10]).toBe(4);
+    expect(Array.from(out.m)).toEqual(Array.from(expected.m));
   });
 
-  it('accumulates scale multiplicatively', () => {
-    const m = createMatrix4();
-    scaleMatrix4(m, m, 2, 2, 2);
+  // A world-frame scale reaches the translation; the local one does not. This is the pair that was
+  // indistinguishable before the operand fix, because both computed source · S.
+  it('scales the translation, unlike the local scaleMatrix4', () => {
+    const source = discriminatingMatrix4();
+    const world = createMatrix4();
+    const local = createMatrix4();
 
-    appendScaleMatrix4(m, m, 3, 4, 5);
+    appendScaleMatrix4(world, source, 2, 3, 4);
+    scaleMatrix4(local, source, 2, 3, 4);
 
-    expect(m.m[0]).toBe(6);
-    expect(m.m[5]).toBe(8);
-    expect(m.m[10]).toBe(10);
+    expect(world.m[12]).toBe(source.m[12] * 2);
+    expect(local.m[12]).toBe(source.m[12]);
+    expect(Array.from(world.m)).not.toEqual(Array.from(local.m));
+  });
+
+  it('supports out === source', () => {
+    const source = discriminatingMatrix4();
+    const expected = createMatrix4();
+    appendScaleMatrix4(expected, source, 2, 3, 4);
+
+    appendScaleMatrix4(source, source, 2, 3, 4);
+
+    expect(Array.from(source.m)).toEqual(Array.from(expected.m));
   });
 });
 
 describe('appendTranslationMatrix4', () => {
-  it('adds translation to an identity matrix', () => {
-    const m = createMatrix4();
+  // The one member of the family that was hand-ported rather than routed through appendMatrix4, which
+  // is why it alone stayed correct while the wrapper was inverted. out = T · source, i.e. the offset is
+  // a bare sum on the translation and the basis is untouched.
+  it('adds the offset to the translation and leaves the basis alone', () => {
+    const source = discriminatingMatrix4();
+    const out = createMatrix4();
 
-    appendTranslationMatrix4(m, m, 1, 2, 3);
+    appendTranslationMatrix4(out, source, 1, 2, 3);
 
-    expect(m.m[12]).toBe(1);
-    expect(m.m[13]).toBe(2);
-    expect(m.m[14]).toBe(3);
+    expect(out.m[12]).toBe(source.m[12] + 1);
+    expect(out.m[13]).toBe(source.m[13] + 2);
+    expect(out.m[14]).toBe(source.m[14] + 3);
+    expect(Array.from(out.m).slice(0, 12)).toEqual(Array.from(source.m).slice(0, 12));
   });
 
-  it('adds to existing translation values', () => {
-    const m = createMatrix4();
-    m.m[12] = 10;
-    m.m[13] = 20;
-    m.m[14] = 30;
+  it('equals composing a translation matrix after source', () => {
+    const source = discriminatingMatrix4();
+    const translation = createMatrix4();
+    setMatrix4(translation, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 2, 3, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, translation, source);
 
-    appendTranslationMatrix4(m, m, 1, 2, 3);
+    const out = createMatrix4();
+    appendTranslationMatrix4(out, source, 1, 2, 3);
 
-    expect(m.m[12]).toBe(11);
-    expect(m.m[13]).toBe(22);
-    expect(m.m[14]).toBe(33);
+    expect(Array.from(out.m)).toEqual(Array.from(expected.m));
   });
 
-  it('does not affect rotation or scale components', () => {
-    const m = createMatrix4();
-    m.m[0] = 2; // scale x
-    m.m[5] = 3; // scale y
-    m.m[10] = 4; // scale z
+  it('differs from the local prependTranslationMatrix4 on a rotated matrix', () => {
+    const source = discriminatingMatrix4();
+    const world = createMatrix4();
+    const local = createMatrix4();
 
-    appendTranslationMatrix4(m, m, 1, 2, 3);
+    appendTranslationMatrix4(world, source, 1, 2, 3);
+    prependTranslationMatrix4(local, source, 1, 2, 3);
 
-    expect(m.m[0]).toBe(2);
-    expect(m.m[5]).toBe(3);
-    expect(m.m[10]).toBe(4);
+    expect(Array.from(world.m)).not.toEqual(Array.from(local.m));
+  });
+
+  it('copies the whole source matrix when out is a distinct object', () => {
+    const source = discriminatingMatrix4();
+    const before = Array.from(source.m);
+    const out = createMatrix4(9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9);
+    const aliased = cloneMatrix4(source);
+
+    appendTranslationMatrix4(out, source, 1, 2, 3);
+    appendTranslationMatrix4(aliased, aliased, 1, 2, 3);
+
+    expect(Array.from(out.m)).toEqual(Array.from(aliased.m));
+    expect(Array.from(source.m)).toEqual(before);
   });
 });
 
@@ -281,6 +385,14 @@ describe('copyMatrix4', () => {
     expect(source.m[0]).toBe(1);
     expect(out.m[0]).toBe(99);
   });
+  it('is a no-op when out aliases source', () => {
+    const m = createMatrix4();
+    setMatrix4(m, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1);
+
+    copyMatrix4(m, m);
+
+    expect(Array.from(m.m)).toEqual([0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1]);
+  });
 });
 
 describe('copyMatrix4ColumnFromVector4', () => {
@@ -315,6 +427,23 @@ describe('copyMatrix4ColumnFromVector4', () => {
     expect(() => copyMatrix4ColumnFromVector4(m, -1, v)).toThrow(RangeError);
     expect(() => copyMatrix4ColumnFromVector4(m, 4, v)).toThrow(RangeError);
   });
+
+  // Column c occupies elements 4c..4c+3 and nothing else moves. Asserting the whole matrix per
+  // column catches a row/column transposition or a stray write that a single-index check misses.
+  it('writes column c into elements 4c..4c+3 for every column', () => {
+    for (let column = 0; column < 4; column++) {
+      const m = createMatrix4(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
+
+      copyMatrix4ColumnFromVector4(m, column, { x: 1, y: 2, z: 3, w: 4 });
+
+      const expected = new Array<number>(16).fill(0);
+      expected[column * 4] = 1;
+      expected[column * 4 + 1] = 2;
+      expected[column * 4 + 2] = 3;
+      expected[column * 4 + 3] = 4;
+      expect(Array.from(m.m)).toEqual(expected);
+    }
+  });
 });
 
 describe('copyMatrix4ColumnToVector4', () => {
@@ -338,6 +467,24 @@ describe('copyMatrix4ColumnToVector4', () => {
     const out = { x: 0, y: 0, z: 0, w: 0 };
 
     expect(() => copyMatrix4ColumnToVector4(out, 99, m)).toThrow(RangeError);
+    expect(() => copyMatrix4ColumnToVector4(out, -1, m)).toThrow(RangeError);
+  });
+
+  it('reads column c from elements 4c..4c+3 for every column', () => {
+    const m = createMatrix4(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16);
+
+    for (let column = 0; column < 4; column++) {
+      const out = { x: 0, y: 0, z: 0, w: 0 };
+
+      copyMatrix4ColumnToVector4(out, column, m);
+
+      expect(out).toEqual({
+        x: column * 4 + 1,
+        y: column * 4 + 2,
+        z: column * 4 + 3,
+        w: column * 4 + 4,
+      });
+    }
   });
 });
 
@@ -373,6 +520,23 @@ describe('copyMatrix4RowFromVector4', () => {
     expect(() => copyMatrix4RowFromVector4(m, -1, v)).toThrow(RangeError);
     expect(() => copyMatrix4RowFromVector4(m, 4, v)).toThrow(RangeError);
   });
+
+  // Row r occupies elements r, r+4, r+8, r+12 — the stride that distinguishes a row write from a
+  // column write in column-major storage.
+  it('writes row r with a stride of four for every row', () => {
+    for (let row = 0; row < 4; row++) {
+      const m = createMatrix4(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
+
+      copyMatrix4RowFromVector4(m, row, { x: 1, y: 2, z: 3, w: 4 });
+
+      const expected = new Array<number>(16).fill(0);
+      expected[row] = 1;
+      expected[row + 4] = 2;
+      expected[row + 8] = 3;
+      expected[row + 12] = 4;
+      expect(Array.from(m.m)).toEqual(expected);
+    }
+  });
 });
 
 describe('copyMatrix4RowToVector4', () => {
@@ -396,6 +560,19 @@ describe('copyMatrix4RowToVector4', () => {
     const out = { x: 0, y: 0, z: 0, w: 0 };
 
     expect(() => copyMatrix4RowToVector4(out, 42, m)).toThrow(RangeError);
+    expect(() => copyMatrix4RowToVector4(out, -1, m)).toThrow(RangeError);
+  });
+
+  it('reads row r with a stride of four for every row', () => {
+    const m = createMatrix4(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16);
+
+    for (let row = 0; row < 4; row++) {
+      const out = { x: 0, y: 0, z: 0, w: 0 };
+
+      copyMatrix4RowToVector4(out, row, m);
+
+      expect(out).toEqual({ x: row + 1, y: row + 5, z: row + 9, w: row + 13 });
+    }
   });
 });
 
@@ -519,6 +696,71 @@ describe('decomposeMatrix4', () => {
     expect(s.z).toBeCloseTo(1, 6);
     expect(r.w).toBeCloseTo(1, 6);
   });
+
+  // Quaternion extraction picks one of four formulas by which diagonal term dominates. A half turn
+  // about each axis drives the trace negative and selects a different one, so recomposing from the
+  // result is the check that all four agree with composeMatrix4 rather than only the trace case.
+  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 rotation = createQuaternion();
+    setQuaternionFromAxisAngle(rotation, axis, Math.PI);
+    const original = createMatrix4();
+    composeMatrix4(original, createVector3(5, 6, 7), rotation, createVector3(2, 3, 4));
+
+    const p = createVector3();
+    const r = createQuaternion();
+    const s = createVector3();
+    decomposeMatrix4(p, r, s, original);
+    const recomposed = createMatrix4();
+    composeMatrix4(recomposed, p, r, s);
+
+    for (let i = 0; i < 16; i++) {
+      expect(recomposed.m[i]).toBeCloseTo(original.m[i], 5);
+    }
+  });
+
+  it('folds a mirrored basis into a negative x scale', () => {
+    const original = createMatrix4();
+    composeMatrix4(original, createVector3(0, 0, 0), createQuaternion(), createVector3(-2, 3, 4));
+
+    const p = createVector3();
+    const r = createQuaternion();
+    const s = createVector3();
+    decomposeMatrix4(p, r, s, original);
+
+    expect(s.x).toBeCloseTo(-2, 5);
+    expect(s.y).toBeCloseTo(3, 5);
+    expect(s.z).toBeCloseTo(4, 5);
+    const recomposed = createMatrix4();
+    composeMatrix4(recomposed, p, r, s);
+    for (let i = 0; i < 16; i++) {
+      expect(recomposed.m[i]).toBeCloseTo(original.m[i], 5);
+    }
+  });
+
+  // A collapsed axis has no recoverable direction, so the guard substitutes zero rather than
+  // dividing by it. The contract is that the caller gets finite numbers and an honest zero scale.
+  it('reports a collapsed axis as zero scale without producing NaN', () => {
+    const original = createMatrix4();
+    composeMatrix4(original, createVector3(1, 2, 3), createQuaternion(), createVector3(0, 0, 0));
+
+    const p = createVector3();
+    const r = createQuaternion();
+    const s = createVector3();
+    decomposeMatrix4(p, r, s, original);
+
+    expect(s.x).toBe(0);
+    expect(s.y).toBe(0);
+    expect(s.z).toBe(0);
+    expect(Number.isFinite(r.x)).toBe(true);
+    expect(Number.isFinite(r.y)).toBe(true);
+    expect(Number.isFinite(r.z)).toBe(true);
+    expect(Number.isFinite(r.w)).toBe(true);
+    expect(p.x).toBe(1);
+  });
 });
 
 describe('equalsMatrix4', () => {
@@ -978,7 +1220,7 @@ describe('multiplyMatrix4', () => {
       expect(equalsMatrix4(m1, m2)).toBe(true);
     });
 
-    it('prependScale equals multiply scale × matrix', () => {
+    it('prependScale equals multiplying the scale on the right', () => {
       const m1 = createMatrix4();
       translateMatrix4(m1, m1, 10, 0, 0);
       const m2 = createMatrix4();
@@ -988,7 +1230,7 @@ describe('multiplyMatrix4', () => {
       scaleMatrix4(s, s, 2, 2, 2);
 
       prependScaleMatrix4(m1, m1, 2, 2, 2);
-      multiplyMatrix4(m2, s, m2);
+      multiplyMatrix4(m2, m2, s);
 
       expect(equalsMatrix4(m1, m2)).toBe(true);
     });
@@ -996,31 +1238,44 @@ describe('multiplyMatrix4', () => {
 });
 
 describe('prependMatrix4', () => {
-  it('is equivalent to multiply(out, other, source)', () => {
-    const a = createMatrix4();
-    translateMatrix4(a, a, 5, 0, 0);
-    const b = createMatrix4();
-    scaleMatrix4(b, b, 2, 2, 2);
+  // The mirror of append: `other` applies BEFORE everything already in `source`, so it is the RIGHT
+  // operand — out = source · other.
+  it('composes other before source: out = source · other', () => {
+    const source = discriminatingMatrix4();
+    const other = createMatrix4();
+    setMatrix4(other, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 0, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, source, other);
 
-    const out1 = createMatrix4();
-    prependMatrix4(out1, a, b);
+    const out = createMatrix4();
+    prependMatrix4(out, source, other);
+
+    expect(Array.from(out.m)).toEqual(Array.from(expected.m));
+  });
 
-    const out2 = createMatrix4();
-    multiplyMatrix4(out2, b, a);
+  it('is the opposite composition from appendMatrix4', () => {
+    const source = discriminatingMatrix4();
+    const other = createMatrix4();
+    setMatrix4(other, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 0, 1);
 
-    expect(equalsMatrix4(out1, out2)).toBe(true);
+    const appended = createMatrix4();
+    appendMatrix4(appended, source, other);
+    const prepended = createMatrix4();
+    prependMatrix4(prepended, source, other);
+
+    expect(Array.from(appended.m)).not.toEqual(Array.from(prepended.m));
   });
 
   it('supports out === source', () => {
-    const a = createMatrix4();
-    translateMatrix4(a, a, 5, 0, 0);
-    const b = createMatrix4();
-    scaleMatrix4(b, b, 2, 3, 4);
+    const source = discriminatingMatrix4();
+    const other = createMatrix4();
+    scaleMatrix4(other, other, 2, 3, 4);
     const expected = createMatrix4();
-    prependMatrix4(expected, a, b);
+    prependMatrix4(expected, source, other);
 
-    prependMatrix4(a, a, b);
-    expect(equalsMatrix4(a, expected)).toBe(true);
+    prependMatrix4(source, source, other);
+
+    expect(Array.from(source.m)).toEqual(Array.from(expected.m));
   });
 });
 
@@ -1034,86 +1289,130 @@ describe('prependRotationMatrix4', () => {
     expect(m.m[1]).toBeCloseTo(1);
   });
 
-  it('rotates translation when prepending rotation', () => {
+  // A local rotation turns the object about its own axes, so its position in the outer space is
+  // unchanged. Before the operand fix this function swept the translation, which is append's job.
+  it('leaves the existing translation in place', () => {
     const m = createMatrix4();
     translateMatrix4(m, m, 10, 0, 0);
 
     prependRotationMatrix4(m, m, Math.PI / 2, Z_AXIS);
 
-    // (10, 0, 0) → (0, 10, 0)
-    expect(m.m[12]).toBeCloseTo(0);
-    expect(m.m[13]).toBeCloseTo(10);
+    expect(m.m[12]).toBeCloseTo(10, 6);
+    expect(m.m[13]).toBeCloseTo(0, 6);
+  });
+
+  it('applies the rotation before source: out = source · R', () => {
+    const source = discriminatingMatrix4();
+    const rotation = createMatrix4();
+    prependRotationMatrix4(rotation, rotation, Math.PI / 3, Z_AXIS);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, source, rotation);
+
+    const out = createMatrix4();
+    prependRotationMatrix4(out, source, Math.PI / 3, Z_AXIS);
+
+    for (let i = 0; i < 16; i++) expect(out.m[i]).toBeCloseTo(expected.m[i], 5);
+  });
+
+  it('holds the pivot point fixed', () => {
+    const source = discriminatingMatrix4();
+    const pivot = { x: 5, y: 0, z: 0, w: 1 };
+    const before = createVector3();
+    matrix4TransformPoint(before, source, createVector3(pivot.x, pivot.y, pivot.z));
+
+    const out = createMatrix4();
+    prependRotationMatrix4(out, source, Math.PI / 2, Z_AXIS, pivot);
+
+    const after = createVector3();
+    matrix4TransformPoint(after, out, createVector3(pivot.x, pivot.y, pivot.z));
+    expect(after.x).toBeCloseTo(before.x, 5);
+    expect(after.y).toBeCloseTo(before.y, 5);
+    expect(after.z).toBeCloseTo(before.z, 5);
+  });
+
+  it('writes the same values whether out aliases source or not', () => {
+    const source = discriminatingMatrix4();
+    const distinct = createMatrix4();
+    const aliased = cloneMatrix4(source);
+
+    prependRotationMatrix4(distinct, source, Math.PI / 3, Z_AXIS, { x: 1, y: 2, z: 3, w: 1 });
+    prependRotationMatrix4(aliased, aliased, Math.PI / 3, Z_AXIS, { x: 1, y: 2, z: 3, w: 1 });
+
+    expect(Array.from(aliased.m)).toEqual(Array.from(distinct.m));
   });
 });
 
 describe('prependScaleMatrix4', () => {
-  it('scales an identity matrix', () => {
-    const m = createMatrix4();
+  it('applies the scale before source: out = source · S', () => {
+    const source = discriminatingMatrix4();
+    const scale = createMatrix4();
+    setMatrix4(scale, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 4, 0, 0, 0, 0, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, source, scale);
 
-    prependScaleMatrix4(m, m, 2, 3, 4);
+    const out = createMatrix4();
+    prependScaleMatrix4(out, source, 2, 3, 4);
 
-    expect(m.m[0]).toBe(2);
-    expect(m.m[5]).toBe(3);
-    expect(m.m[10]).toBe(4);
+    expect(Array.from(out.m)).toEqual(Array.from(expected.m));
   });
 
-  it('scales translation when prepending scale', () => {
-    const m = createMatrix4();
-    translateMatrix4(m, m, 10, 20, 30);
+  it('leaves the translation alone, unlike the world-frame appendScaleMatrix4', () => {
+    const source = discriminatingMatrix4();
+    const out = createMatrix4();
 
-    prependScaleMatrix4(m, m, 2, 3, 4);
+    prependScaleMatrix4(out, source, 2, 3, 4);
 
-    expect(m.m[12]).toBe(20); // 10 * 2
-    expect(m.m[13]).toBe(60); // 20 * 3
-    expect(m.m[14]).toBe(120); // 30 * 4
+    expect(out.m[12]).toBe(source.m[12]);
+    expect(out.m[13]).toBe(source.m[13]);
+    expect(out.m[14]).toBe(source.m[14]);
   });
 
-  it('scale, appendScale, and prependScale behave the same on identity', () => {
-    const a = createMatrix4();
-    const b = createMatrix4();
-    const c = createMatrix4();
+  it('supports out === source', () => {
+    const source = discriminatingMatrix4();
+    const expected = createMatrix4();
+    prependScaleMatrix4(expected, source, 2, 3, 4);
 
-    scaleMatrix4(a, a, 2, 3, 4);
-    appendScaleMatrix4(b, b, 2, 3, 4);
-    prependScaleMatrix4(c, c, 2, 3, 4);
+    prependScaleMatrix4(source, source, 2, 3, 4);
 
-    expect(equalsMatrix4(a, b)).toBe(true);
-    expect(equalsMatrix4(b, c)).toBe(true);
+    expect(Array.from(source.m)).toEqual(Array.from(expected.m));
   });
 });
 
 describe('prependTranslationMatrix4', () => {
-  it('translates an identity matrix by (x, y, z)', () => {
-    const m = createMatrix4();
+  it('applies the offset before source: out = source · T', () => {
+    const source = discriminatingMatrix4();
+    const translation = createMatrix4();
+    setMatrix4(translation, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 2, 3, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, source, translation);
 
-    prependTranslationMatrix4(m, m, 1, 2, 3);
+    const out = createMatrix4();
+    prependTranslationMatrix4(out, source, 1, 2, 3);
 
-    expect(m.m[12]).toBe(1);
-    expect(m.m[13]).toBe(2);
-    expect(m.m[14]).toBe(3);
+    expect(Array.from(out.m)).toEqual(Array.from(expected.m));
   });
 
-  it('prepends translation before existing transforms', () => {
-    const m = createMatrix4();
-    translateMatrix4(m, m, 10, 0, 0);
+  // The local frame carries the offset through source's own basis, so a rotated, scaled source turns
+  // and stretches it — a bare sum would be the world-frame answer.
+  it('carries the offset through the source basis', () => {
+    const source = discriminatingMatrix4();
+    const out = createMatrix4();
 
-    prependTranslationMatrix4(m, m, 5, 0, 0);
+    prependTranslationMatrix4(out, source, 1, 2, 3);
 
-    // world-space prepend: (5 + 10)
-    expect(m.m[12]).toBe(15);
+    expect(out.m[12]).toBe(source.m[0] * 1 + source.m[4] * 2 + source.m[8] * 3 + source.m[12]);
+    expect(out.m[13]).toBe(source.m[1] * 1 + source.m[5] * 2 + source.m[9] * 3 + source.m[13]);
+    expect(out.m[14]).toBe(source.m[2] * 1 + source.m[6] * 2 + source.m[10] * 3 + source.m[14]);
   });
 
-  it('translate, appendTranslation, and prependTranslation behave the same on identity', () => {
-    const a = createMatrix4();
-    const b = createMatrix4();
-    const c = createMatrix4();
+  it('supports out === source', () => {
+    const source = discriminatingMatrix4();
+    const expected = createMatrix4();
+    prependTranslationMatrix4(expected, source, 1, 2, 3);
 
-    translateMatrix4(a, a, 1, 2, 3);
-    appendTranslationMatrix4(b, b, 1, 2, 3);
-    prependTranslationMatrix4(c, c, 1, 2, 3);
+    prependTranslationMatrix4(source, source, 1, 2, 3);
 
-    expect(equalsMatrix4(a, b)).toBe(true);
-    expect(equalsMatrix4(b, c)).toBe(true);
+    expect(Array.from(source.m)).toEqual(Array.from(expected.m));
   });
 });
 
@@ -1128,6 +1427,23 @@ describe('rotateMatrix4', () => {
     expect(equalsMatrix4(a, b)).toBe(true);
   });
 
+  it('matches the quaternion rotation path for an asymmetric unit axis', () => {
+    const inverseLength = 1 / Math.sqrt(14);
+    const axis = createVector3(2 * inverseLength, inverseLength, 3 * inverseLength);
+    const radians = Math.PI / 3;
+    const quaternion = createQuaternion();
+    setQuaternionFromAxisAngle(quaternion, axis, radians);
+    const expected = createMatrix4();
+    setMatrix4FromQuaternion(expected, quaternion);
+
+    const actual = createMatrix4();
+    rotateMatrix4(actual, actual, axis, radians);
+
+    for (let i = 0; i < 16; i++) {
+      expect(actual.m[i]).toBeCloseTo(expected.m[i], 6);
+    }
+  });
+
   it('preserves translation when rotating locally', () => {
     const m = createMatrix4();
     translateMatrix4(m, m, 5, 0, 0);
@@ -1157,6 +1473,17 @@ describe('rotateMatrix4', () => {
     expect(m.m[5]).toBeCloseTo(1);
     expect(m.m[6]).toBeCloseTo(0);
   });
+  it('writes the same values whether out aliases source or not', () => {
+    const source = createMatrix4();
+    setMatrix4(source, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1);
+    const distinct = createMatrix4();
+    const aliased = cloneMatrix4(source);
+
+    rotateMatrix4(distinct, source, createVector3(0, 0, 1), Math.PI / 3);
+    rotateMatrix4(aliased, aliased, createVector3(0, 0, 1), Math.PI / 3);
+
+    expect(Array.from(aliased.m)).toEqual(Array.from(distinct.m));
+  });
 });
 
 describe('scaleMatrix4', () => {
@@ -1191,6 +1518,49 @@ describe('scaleMatrix4', () => {
     expect(m.m[13]).toBe(20);
     expect(m.m[14]).toBe(30);
   });
+
+  // A diagonal matrix cannot tell a column scale from a row scale, so a rotated basis with a
+  // non-uniform scale is the only input that pins the multiplication side down.
+  it('post-multiplies by diag(sx, sy, sz, 1) on a rotated basis', () => {
+    const rotated = createMatrix4();
+    setMatrix4(rotated, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1);
+    const scale = createMatrix4();
+    setMatrix4(scale, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 4, 0, 0, 0, 0, 1);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, rotated, scale);
+
+    const result = createMatrix4();
+    scaleMatrix4(result, rotated, 2, 3, 4);
+
+    expect(Array.from(result.m)).toEqual(Array.from(expected.m));
+    // The discriminating elements: column 0 carries sx, not row 0.
+    expect(result.m[1]).toBe(2);
+    expect(result.m[4]).toBe(-3);
+  });
+
+  it('scales the fourth row of each basis column for a non-affine matrix', () => {
+    const projective = createMatrix4();
+    setMatrix4(projective, 1, 0, 0, 5, 0, 1, 0, 6, 0, 0, 1, 7, 0, 0, 0, 1);
+
+    scaleMatrix4(projective, projective, 2, 3, 4);
+
+    expect(projective.m[3]).toBe(10);
+    expect(projective.m[7]).toBe(18);
+    expect(projective.m[11]).toBe(28);
+    expect(projective.m[15]).toBe(1);
+  });
+
+  it('writes the same values whether out aliases source or not', () => {
+    const source = createMatrix4();
+    setMatrix4(source, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1);
+    const distinct = createMatrix4();
+    const aliased = cloneMatrix4(source);
+
+    scaleMatrix4(distinct, source, 2, 3, 4);
+    scaleMatrix4(aliased, aliased, 2, 3, 4);
+
+    expect(Array.from(aliased.m)).toEqual(Array.from(distinct.m));
+  });
 });
 
 describe('setMatrix4', () => {
@@ -1439,6 +1809,38 @@ describe('setMatrix4LookAt', () => {
     // Target is 5 units in front of the eye => view-space z = -5 (RH).
     expect(out.z).toBeCloseTo(-5, 6);
   });
+
+  // An overhead camera (up parallel to the view direction) and a camera sitting on its own target
+  // are both reachable from ordinary application code. Roll is arbitrary in those cases, but the
+  // basis must stay orthonormal — a singular view matrix cannot be inverted for picking or for
+  // deriving a camera world transform, and it collapses every rendered position onto a plane.
+  it.each([
+    ['up parallel to the view direction', createVector3(0, 5, 0), createVector3(0, 0, 0), createVector3(0, 1, 0)],
+    ['eye at the target', createVector3(2, 2, 2), createVector3(2, 2, 2), createVector3(0, 1, 0)],
+    ['up parallel to a z-aligned view', createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 0, 1)],
+  ])('keeps the basis orthonormal when %s', (_case, eye, target, up) => {
+    const m = createMatrix4();
+
+    setMatrix4LookAt(m, eye, target, up);
+
+    for (let i = 0; i < 16; i++) {
+      expect(Number.isFinite(m.m[i])).toBe(true);
+    }
+    const xAxis = createVector3();
+    const yAxis = createVector3();
+    const zAxis = createVector3();
+    setVector3(xAxis, m.m[0], m.m[4], m.m[8]);
+    setVector3(yAxis, m.m[1], m.m[5], m.m[9]);
+    setVector3(zAxis, m.m[2], m.m[6], m.m[10]);
+
+    expect(getVector3Length(xAxis)).toBeCloseTo(1, 6);
+    expect(getVector3Length(yAxis)).toBeCloseTo(1, 6);
+    expect(getVector3Length(zAxis)).toBeCloseTo(1, 6);
+    expect(getVector3Dot(xAxis, yAxis)).toBeCloseTo(0, 6);
+    expect(getVector3Dot(xAxis, zAxis)).toBeCloseTo(0, 6);
+    expect(getVector3Dot(yAxis, zAxis)).toBeCloseTo(0, 6);
+    expect(Math.abs(getMatrix4Determinant(m))).toBeCloseTo(1, 6);
+  });
 });
 
 describe('setMatrix4Position', () => {
@@ -1548,6 +1950,22 @@ describe('translateMatrix4', () => {
     expect(m.m[13]).toBe(7);
     expect(m.m[14]).toBe(9);
   });
+
+  // The distinct-out path copies the basis across before writing the translation. Only the aliased
+  // path was exercised before, so a broken copy would have left the basis at whatever `out` held.
+  it('copies the whole source matrix when out is a distinct object', () => {
+    const source = createMatrix4();
+    setMatrix4(source, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1);
+    const out = createMatrix4(9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9);
+    const aliased = cloneMatrix4(source);
+
+    translateMatrix4(out, source, 1, 2, 3);
+    translateMatrix4(aliased, aliased, 1, 2, 3);
+
+    expect(Array.from(out.m)).toEqual(Array.from(aliased.m));
+    // The source is left untouched by the distinct-out call.
+    expect(Array.from(source.m)).toEqual([0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 7, 8, 9, 1]);
+  });
 });
 
 describe('transposeMatrix4', () => {