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

package/src/capsule.test.ts

@@ -62,6 +62,49 @@ describe('getClosestPointOnCapsule', () => {
     expect(p.x).toBeCloseTo(1, 5);
     expect(p.y).toBeCloseTo(0, 5);
   });
+
+  it('answers a point on the axis with a surface point, whichever way the axis runs', () => {
+    // A point on the axis has no single nearest surface point, so the answer is a pick from the
+    // ring around it — but it still has to be a point on the surface. Each capsule below is
+    // centered on the origin and queried at the origin, so a correct answer sits one radius out
+    // and square to the axis; an answer pointing along the axis is inside the capsule, not on it.
+    const out = createVector3();
+
+    getClosestPointOnCapsule(out, createCapsule(-5, 0, 0, 5, 0, 0, 1), createVector3(0, 0, 0));
+    expect(Math.hypot(out.x, out.y, out.z)).toBeCloseTo(1, 5);
+    expect(out.x).toBeCloseTo(0, 5);
+
+    getClosestPointOnCapsule(out, createCapsule(0, -5, 0, 0, 5, 0, 1), createVector3(0, 0, 0));
+    expect(Math.hypot(out.x, out.y, out.z)).toBeCloseTo(1, 5);
+    expect(out.y).toBeCloseTo(0, 5);
+
+    getClosestPointOnCapsule(out, createCapsule(0, 0, -5, 0, 0, 5, 1), createVector3(0, 0, 0));
+    expect(Math.hypot(out.x, out.y, out.z)).toBeCloseTo(1, 5);
+    expect(out.z).toBeCloseTo(0, 5);
+
+    // A capsule with no length is a sphere: its center has a whole sphere of nearest points and
+    // every direction is square to a zero-length axis, so only the distance is fixed.
+    getClosestPointOnCapsule(out, createCapsule(0, 0, 0, 0, 0, 0, 1), createVector3(0, 0, 0));
+    expect(Math.hypot(out.x, out.y, out.z)).toBeCloseTo(1, 5);
+  });
+
+  it('answers a point on a diagonal axis with a surface point too', () => {
+    // The axis here lines up with no world direction, so the perpendicular is a genuine cross
+    // product rather than a swap of coordinates. A correct answer is one radius from the axis
+    // point, which for a query at the middle of a centered capsule means square to the axis.
+    const evenlyDiagonal = createCapsule(-3, -3, -3, 3, 3, 3, 2);
+    const out = createVector3();
+    getClosestPointOnCapsule(out, evenlyDiagonal, createVector3(0, 0, 0));
+    expect(Math.hypot(out.x, out.y, out.z)).toBeCloseTo(2, 5);
+    expect(out.x + out.y + out.z).toBeCloseTo(0, 5);
+
+    // An axis leaning mostly along x, least along z, so the direction it is crossed with differs
+    // again — every ordering of the axis components has to produce a perpendicular.
+    const leaningDiagonal = createCapsule(-3, -2, -1, 3, 2, 1, 2);
+    getClosestPointOnCapsule(out, leaningDiagonal, createVector3(0, 0, 0));
+    expect(Math.hypot(out.x, out.y, out.z)).toBeCloseTo(2, 5);
+    expect(out.x * 3 + out.y * 2 + out.z * 1).toBeCloseTo(0, 5);
+  });
 });
 
 describe('intersectRay3DCapsule', () => {
@@ -93,6 +136,60 @@ describe('intersectRay3DCapsule', () => {
     const t = intersectRay3DCapsule(ray, c);
     expect(t).toBeCloseTo(4, 5);
   });
+
+  it('returns -1 for a ray with no direction', () => {
+    // Matches intersectRay3DSphere: a zero-length direction is not a ray and never hits, even
+    // from a point inside the capsule.
+    const c = createCapsule(0, -1, 0, 0, 1, 0, 1);
+    expect(intersectRay3DCapsule(createRay3D(0, 0, 0, 0, 0, 0), c)).toBe(-1);
+    expect(intersectRay3DCapsule(createRay3D(9, 9, 9, 0, 0, 0), c)).toBe(-1);
+  });
+
+  it('returns -1 for an empty capsule with a negative radius', () => {
+    const empty = createCapsule(0, -1, 0, 0, 1, 0, -1);
+    expect(intersectRay3DCapsule(createRay3D(5, 0, 0, -1, 0, 0), empty)).toBe(-1);
+  });
+
+  it('returns -1 for a ray that passes wide of the capsule', () => {
+    // Parallel to nothing and outside the cylinder radius, so neither the body nor either cap has
+    // a real intersection at all — a different miss from a ray aimed away from a capsule in reach.
+    const c = createCapsule(0, -1, 0, 0, 1, 0, 1);
+    expect(intersectRay3DCapsule(createRay3D(5, 0, 5, -1, 0, 0), c)).toBe(-1);
+  });
+
+  it('hits a cap when the ray runs along the capsule axis', () => {
+    // Straight down the axis the body test has nothing to solve — the ray never crosses the
+    // cylinder wall — so the answer has to come from the cap.
+    const c = createCapsule(0, -1, 0, 0, 1, 0, 1);
+    expect(intersectRay3DCapsule(createRay3D(0, 5, 0, 0, -1, 0), c)).toBeCloseTo(3, 5);
+  });
+
+  it('returns 0 for a ray starting inside a cap and pointing away', () => {
+    // Inside the rounded end, heading out. The near root of the cap sphere is behind the origin
+    // and the far one ahead, which is the definition of starting inside.
+    const c = createCapsule(0, -1, 0, 0, 1, 0, 1);
+    expect(intersectRay3DCapsule(createRay3D(0, 1.5, 0, 0, 1, 0), c)).toBe(0);
+  });
+
+  it('falls back to a cap when the body hit lands past the end of the axis', () => {
+    // These rays cross the infinite cylinder, but above or below the segment the cylinder is not
+    // capsule any more, so the body hit must be discarded and the rounded end answered instead.
+    // The capsule spans y in [-1, 1] with radius 1; a ray at y = 1.8 crosses the end sphere at
+    // x = sqrt(1 - 0.8^2) = 0.6, so it enters 4.4 along from x = 5.
+    const c = createCapsule(0, -1, 0, 0, 1, 0, 1);
+    expect(intersectRay3DCapsule(createRay3D(5, 1.8, 0, -1, 0, 0), c)).toBeCloseTo(4.4, 5);
+    expect(intersectRay3DCapsule(createRay3D(5, -1.8, 0, -1, 0, 0), c)).toBeCloseTo(4.4, 5);
+
+    // Beyond the reach of the cap, the same arrangement is a clean miss.
+    expect(intersectRay3DCapsule(createRay3D(5, 2.5, 0, -1, 0, 0), c)).toBe(-1);
+  });
+
+  it('returns -1 from inside the infinite cylinder but past the end cap', () => {
+    // The origin is in line with the capsule body yet beyond its end, so being inside the endless
+    // cylinder means nothing: from a point outside the capsule heading away, there is no hit.
+    const c = createCapsule(0, -1, 0, 0, 1, 0, 1);
+    expect(intersectRay3DCapsule(createRay3D(0, 3, 0, 1, 1, 0), c)).toBe(-1);
+  });
 });
 
 describe('isCapsuleIntersectingCapsule', () => {
@@ -114,6 +211,33 @@ describe('isCapsuleIntersectingCapsule', () => {
     expect(isCapsuleIntersectingCapsule(a, empty)).toBe(false);
     expect(isCapsuleIntersectingCapsule(empty, a)).toBe(false);
   });
+
+  it('switches over at the true axis distance for every segment arrangement', () => {
+    // The segment-to-segment distance behind this test has a separate branch for each way two
+    // segments can be arranged — both degenerate to points, one degenerate, parallel, skew, and
+    // the two cases where the nearest approach falls beyond an endpoint of the second segment.
+    // Each is checked against a distance measured by walking both segments, so a branch that
+    // returns the wrong closest pair shows up as an answer that flips at the wrong radius.
+    const arrangements: Array<[string, readonly number[], readonly number[]]> = [
+      ['two points', [1, 2, 3, 1, 2, 3], [4, 6, 3, 4, 6, 3]],
+      ['point and segment', [0, 5, 0, 0, 5, 0], [-10, 0, 0, 10, 0, 0]],
+      ['segment and point', [-10, 0, 0, 10, 0, 0], [0, 5, 0, 0, 5, 0]],
+      ['parallel', [0, 0, 0, 0, 10, 0], [3, 0, 0, 3, 10, 0]],
+      ['skew, nearest approach inside both', [-5, 0, 0, 5, 0, 0], [0, -5, 2, 0, 5, 2]],
+      ['nearest approach before the second start', [0, 0, 0, 10, 0, 0], [5, 5, 3, 5, 15, 3]],
+      ['nearest approach past the second end', [0, 0, 0, 10, 0, 0], [5, -15, 3, 5, -5, 3]],
+    ];
+
+    for (const [name, first, second] of arrangements) {
+      const gap = measureSegmentDistance(first, second);
+      const tooShort = createCapsule(...(first as SegmentArguments), gap * 0.45);
+      const longEnough = createCapsule(...(first as SegmentArguments), gap * 0.55);
+      const reach = createCapsule(...(second as SegmentArguments), gap * 0.45);
+
+      expect([name, isCapsuleIntersectingCapsule(tooShort, reach)]).toEqual([name, false]);
+      expect([name, isCapsuleIntersectingCapsule(longEnough, reach)]).toEqual([name, true]);
+    }
+  });
 });
 
 describe('isCapsuleIntersectingSphere', () => {
@@ -140,6 +264,14 @@ describe('isCapsuleIntersectingSphere', () => {
     const s = createBoundingSphere(0, 0, 0, 1);
     expect(isCapsuleIntersectingSphere(c, s)).toBe(false);
   });
+
+  it('treats a capsule with no length as a sphere', () => {
+    // Both endpoints in the same place leaves no axis to project onto, and the test reduces to
+    // two spheres: they touch when the centers are closer than the radii add up to.
+    const point = createCapsule(0, 0, 0, 0, 0, 0, 1);
+    expect(isCapsuleIntersectingSphere(point, createBoundingSphere(2.5, 0, 0, 1))).toBe(false);
+    expect(isCapsuleIntersectingSphere(point, createBoundingSphere(1.5, 0, 0, 1))).toBe(true);
+  });
 });
 
 describe('setCapsule', () => {
@@ -155,3 +287,29 @@ describe('setCapsule', () => {
     expect(c.radius).toBe(7);
   });
 });
+
+// The six coordinates of a capsule axis: start x, y, z then end x, y, z.
+type SegmentArguments = [number, number, number, number, number, number];
+
+// The smallest distance between two segments, found by walking both of them. Deliberately not the
+// closed-form solution the source uses — it is slow and approximate, but it is arrived at
+// independently, so it can disagree with the formula it checks.
+function measureSegmentDistance(first: readonly number[], second: readonly number[]): number {
+  const steps = 600;
+  let smallest = Number.POSITIVE_INFINITY;
+  for (let i = 0; i <= steps; i++) {
+    const s = i / steps;
+    const px = first[0] + s * (first[3] - first[0]);
+    const py = first[1] + s * (first[4] - first[1]);
+    const pz = first[2] + s * (first[5] - first[2]);
+    for (let j = 0; j <= steps; j++) {
+      const t = j / steps;
+      const qx = second[0] + t * (second[3] - second[0]);
+      const qy = second[1] + t * (second[4] - second[1]);
+      const qz = second[2] + t * (second[5] - second[2]);
+      const distance = Math.hypot(px - qx, py - qy, pz - qz);
+      if (distance < smallest) smallest = distance;
+    }
+  }
+  return smallest;
+}

package/src/enableGeometryPoolGuards.test.ts

@@ -0,0 +1,121 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+
+import {
+  areGeometryPoolGuardsEnabled,
+  disableGeometryPoolGuards,
+  enableGeometryPoolGuards,
+} from './enableGeometryPoolGuards';
+import { acquireMatrix3, clearMatrix3Pool, releaseMatrix3 } from './matrix3Pool';
+import { acquireMatrix4, clearMatrix4Pool, releaseMatrix4 } from './matrix4Pool';
+import { acquireMatrix, clearMatrixPool, releaseMatrix } from './matrixPool';
+import { acquireQuaternion, clearQuaternionPool, releaseQuaternion } from './quaternionPool';
+import { acquireRectangle, clearRectanglePool, releaseRectangle } from './rectanglePool';
+import { acquireVector2, clearVector2Pool, releaseVector2 } from './vector2Pool';
+import { acquireVector3, clearVector3Pool, releaseVector3 } from './vector3Pool';
+import { acquireVector4, clearVector4Pool, releaseVector4 } from './vector4Pool';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(16);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function clearPools(): void {
+  clearMatrixPool();
+  clearMatrix3Pool();
+  clearMatrix4Pool();
+  clearQuaternionPool();
+  clearRectanglePool();
+  clearVector2Pool();
+  clearVector3Pool();
+  clearVector4Pool();
+}
+
+function doubleRelease<Value>(acquire: () => Value, release: (value: Value) => void): void {
+  const value = acquire();
+  release(value);
+  release(value);
+}
+
+function messageOf(entry: Readonly<LogEntry>): string {
+  const data = entry.data;
+  return typeof data === 'string' ? data : String(data.message);
+}
+
+beforeEach(clearPools);
+
+afterEach(() => {
+  disableGeometryPoolGuards();
+  clearPools();
+});
+
+describe('areGeometryPoolGuardsEnabled', () => {
+  it('reports whether the pool release diagnostic is installed', () => {
+    expect(areGeometryPoolGuardsEnabled()).toBe(false);
+    enableGeometryPoolGuards();
+    expect(areGeometryPoolGuardsEnabled()).toBe(true);
+    disableGeometryPoolGuards();
+    expect(areGeometryPoolGuardsEnabled()).toBe(false);
+  });
+});
+
+describe('disableGeometryPoolGuards', () => {
+  it('restores the production-default silent release path', () => {
+    enableGeometryPoolGuards();
+    disableGeometryPoolGuards();
+    const entries = captureLog(() => doubleRelease(acquireVector2, releaseVector2));
+    expect(entries).toHaveLength(0);
+  });
+});
+
+describe('enableGeometryPoolGuards', () => {
+  // ONE firing test deliberately consumes all eight process-lifetime logOnce keys.
+  it('warns once for a double release from every geometry pool and stays silent for valid brackets', () => {
+    enableGeometryPoolGuards();
+
+    const pairedEntries = captureLog(() => {
+      releaseMatrix(acquireMatrix());
+      releaseMatrix3(acquireMatrix3());
+      releaseMatrix4(acquireMatrix4());
+      releaseQuaternion(acquireQuaternion());
+      releaseRectangle(acquireRectangle());
+      releaseVector2(acquireVector2());
+      releaseVector3(acquireVector3());
+      releaseVector4(acquireVector4());
+    });
+    expect(pairedEntries).toHaveLength(0);
+
+    const entries = captureLog(() => {
+      doubleRelease(acquireMatrix, releaseMatrix);
+      doubleRelease(acquireMatrix3, releaseMatrix3);
+      doubleRelease(acquireMatrix4, releaseMatrix4);
+      doubleRelease(acquireQuaternion, releaseQuaternion);
+      doubleRelease(acquireRectangle, releaseRectangle);
+      doubleRelease(acquireVector2, releaseVector2);
+      doubleRelease(acquireVector3, releaseVector3);
+      doubleRelease(acquireVector4, releaseVector4);
+    });
+
+    expect(entries).toHaveLength(8);
+    expect(entries.every((entry) => entry.channel === 'geometry')).toBe(true);
+    const messages = entries.map(messageOf);
+    for (const releaseFunction of [
+      'releaseMatrix',
+      'releaseMatrix3',
+      'releaseMatrix4',
+      'releaseQuaternion',
+      'releaseRectangle',
+      'releaseVector2',
+      'releaseVector3',
+      'releaseVector4',
+    ]) {
+      expect(messages.some((message) => message.includes(releaseFunction))).toBe(true);
+    }
+  });
+});

package/src/frustum.test.ts

@@ -79,6 +79,19 @@ describe('getFrustumCorners', () => {
     expect(isFinite(corners[0].x)).toBe(true);
     expect(isFinite(corners[1].x)).toBe(true);
   });
+
+  it('writes finite corners for a matrix that divides a corner by zero', () => {
+    // The perspective divide has no answer when the matrix sends a corner to a w of zero — a
+    // point at infinity. Passing the coordinates through undivided keeps the corner finite, so a
+    // caller fitting bounds around these corners gets a wrong box rather than an infinite one.
+    const corners = Array.from({ length: 8 }, () => createVector3());
+    getFrustumCorners(corners, createMatrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0));
+    for (const corner of corners) {
+      expect(Number.isFinite(corner.x)).toBe(true);
+      expect(Number.isFinite(corner.y)).toBe(true);
+      expect(Number.isFinite(corner.z)).toBe(true);
+    }
+  });
 });
 
 describe('isFrustumContainingPoint', () => {
@@ -119,6 +132,16 @@ describe('isFrustumIntersectingAabb', () => {
     setFrustumFromMatrix4(f, createTestViewProjection());
     expect(isFrustumIntersectingAabb(f, createAabb(50, 50, -1, 60, 60, 1))).toBe(false);
   });
+
+  it.each([
+    ['x', createAabb(0.5, -0.5, -0.5, -0.5, 0.5, 0.5)],
+    ['y', createAabb(-0.5, 0.5, -0.5, 0.5, -0.5, 0.5)],
+    ['z', createAabb(-0.5, -0.5, 0.5, 0.5, 0.5, -0.5)],
+  ])('rejects an AABB empty on %s', (_axis, empty) => {
+    const f = createFrustum();
+    setFrustumFromMatrix4(f, createMatrix4());
+    expect(isFrustumIntersectingAabb(f, empty)).toBe(false);
+  });
 });
 
 describe('isFrustumIntersectingSphere', () => {
@@ -157,4 +180,19 @@ describe('setFrustumFromMatrix4', () => {
     const len = Math.sqrt(near.a * near.a + near.b * near.b + near.c * near.c);
     expect(len).toBeCloseTo(1, 5);
   });
+
+  it('writes finite coefficients for a matrix with no frustum in it', () => {
+    // Every plane comes out of a matrix row, and a row of zeros has no direction to scale to unit
+    // length. The coefficients stay as they are rather than dividing by zero, so a caller that
+    // culls against this frustum gets consistent rejections instead of NaN comparisons, which are
+    // false in both directions and would let a box pass and fail the same test.
+    const f = createFrustum();
+    setFrustumFromMatrix4(f, createMatrix4(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0));
+    for (const plane of [f.near, f.far, f.left, f.right, f.top, f.bottom]) {
+      expect(Number.isFinite(plane.a)).toBe(true);
+      expect(Number.isFinite(plane.b)).toBe(true);
+      expect(Number.isFinite(plane.c)).toBe(true);
+      expect(Number.isFinite(plane.d)).toBe(true);
+    }
+  });
 });

package/src/geometryPoolGuards.test.ts

@@ -0,0 +1,16 @@
+import { geometryPoolReleaseGuard, setGeometryPoolReleaseGuard } from './geometryPoolGuards';
+
+afterEach(() => {
+  setGeometryPoolReleaseGuard(null);
+});
+
+describe('setGeometryPoolReleaseGuard', () => {
+  it('installs and removes the internal release callback', () => {
+    const guard = (): void => {};
+    setGeometryPoolReleaseGuard(guard);
+    expect(geometryPoolReleaseGuard).toBe(guard);
+
+    setGeometryPoolReleaseGuard(null);
+    expect(geometryPoolReleaseGuard).toBeNull();
+  });
+});

package/src/matrix.test.ts

@@ -68,6 +68,12 @@ describe('copyMatrix', () => {
     expect(m2.tx).toBe(6);
     expect(m2.ty).toBe(7);
   });
+
+  it('supports out === source', () => {
+    const matrix = createMatrix(2, 3, 4, 5, 6, 7);
+    copyMatrix(matrix, matrix);
+    expect(matrix).toMatchObject({ a: 2, b: 3, c: 4, d: 5, tx: 6, ty: 7 });
+  });
 });
 
 describe('copyMatrixColumnFromVector3', () => {
@@ -95,10 +101,11 @@ describe('copyMatrixColumnFromVector3', () => {
     expect(m.ty).toBe(6);
   });
 
-  it('should throw when column is greater than 2', () => {
+  it('throws when column is outside 0 through 2', () => {
     const m = createMatrix();
     const v = createVector3();
-    expect(() => copyMatrixColumnFromVector3(m, 3, v)).toThrow();
+    expect(() => copyMatrixColumnFromVector3(m, -1, v)).toThrow(RangeError);
+    expect(() => copyMatrixColumnFromVector3(m, 3, v)).toThrow(RangeError);
   });
 });
 
@@ -130,10 +137,11 @@ describe('copyMatrixColumnToVector3', () => {
     expect(v.z).toBe(1);
   });
 
-  it('should throw when column is greater than 2', () => {
+  it('throws when column is outside 0 through 2', () => {
     const m = createMatrix();
     const v = createVector3();
-    expect(() => copyMatrixColumnToVector3(v, 3, m)).toThrow();
+    expect(() => copyMatrixColumnToVector3(v, -1, m)).toThrow(RangeError);
+    expect(() => copyMatrixColumnToVector3(v, 3, m)).toThrow(RangeError);
   });
 });
 
@@ -156,10 +164,17 @@ describe('copyMatrixRowFromVector3', () => {
     expect(m.ty).toBe(6);
   });
 
-  it('should throw when row is greater than 2', () => {
+  it('leaves the fixed identity row unchanged for row 2', () => {
+    const m = createMatrix(1, 2, 3, 4, 5, 6);
+    copyMatrixRowFromVector3(m, 2, createVector3(7, 8, 9));
+    expect(m).toMatchObject({ a: 1, b: 2, c: 3, d: 4, tx: 5, ty: 6 });
+  });
+
+  it('throws when row is outside 0 through 2', () => {
     const m = createMatrix();
     const v = createVector3();
-    expect(() => copyMatrixRowFromVector3(m, 3, v)).toThrow();
+    expect(() => copyMatrixRowFromVector3(m, -1, v)).toThrow(RangeError);
+    expect(() => copyMatrixRowFromVector3(m, 3, v)).toThrow(RangeError);
   });
 });
 
@@ -190,6 +205,13 @@ describe('copyMatrixRowToVector3', () => {
     expect(v.y).toBe(0);
     expect(v.z).toBe(1);
   });
+
+  it('throws when row is outside 0 through 2', () => {
+    const m = createMatrix();
+    const v = createVector3();
+    expect(() => copyMatrixRowToVector3(v, -1, m)).toThrow(RangeError);
+    expect(() => copyMatrixRowToVector3(v, 3, m)).toThrow(RangeError);
+  });
 });
 
 describe('createGradientTransformMatrix', () => {
@@ -472,6 +494,12 @@ describe('inverseMatrixTransformVectorXY', () => {
 });
 
 describe('matrixTransformBounds', () => {
+  it('maps coincident corners to a zero-size rectangle at the matrix translation', () => {
+    const out = createRectangle(1, 2, 3, 4);
+    matrixTransformBounds(out, createMatrix(2, 0, 0, 3, 7, 11), 5, 5, 5, 5);
+    expect(out).toMatchObject({ x: 7, y: 11, width: 0, height: 0 });
+  });
+
   it('should work when ax > bx or ay > by (flipped input)', () => {
     const m = createMatrix();
     const out = createRectangle();
@@ -499,6 +527,18 @@ describe('matrixTransformBounds', () => {
     expect(out.height).toBeCloseTo(10);
   });
 
+  it('tracks the fourth corner as a new minimum after positive skew', () => {
+    const out = createRectangle();
+    matrixTransformBounds(out, createMatrix(1, 1, 1, 1), 0, 1, 1, 0);
+    expect(out).toMatchObject({ x: 0, y: 0, width: 2, height: 2 });
+  });
+
+  it('tracks the second and fourth corners after a reflected skew', () => {
+    const out = createRectangle();
+    matrixTransformBounds(out, createMatrix(-1, -1, 1, 1), 0, 0, 1, 1);
+    expect(out).toMatchObject({ x: -1, y: -1, width: 2, height: 2 });
+  });
+
   it('should handle flipped input coordinates', () => {
     const rect = createRectangle(10, 20, -10, -20);
     const mat = createMatrix();
@@ -1079,6 +1119,12 @@ describe('setMatrixIdentity', () => {
 });
 
 describe('setTransformMatrix', () => {
+  it('builds scale and translation without rotation', () => {
+    const out = createMatrix(9, 9, 9, 9, 9, 9);
+    setTransformMatrix(out, 2, 4, 0, 10, 100);
+    expect(out).toMatchObject({ a: 2, b: 0, c: 0, d: 4, tx: 10, ty: 100 });
+  });
+
   it('should apply rotate, scale and translation', () => {
     const m1 = createMatrix();
     rotateMatrix(m1, m1, 45);

package/src/matrix3.test.ts

@@ -87,6 +87,12 @@ describe('copyMatrix3', () => {
     expect(getMatrix3Element(m2, 2, 1)).toBe(9);
     expect(getMatrix3Element(m2, 2, 2)).toBe(10);
   });
+
+  it('supports out === source', () => {
+    const matrix = createMatrix3(2, 3, 4, 5, 6, 7, 8, 9, 10);
+    copyMatrix3(matrix, matrix);
+    expect(Array.from(matrix.m)).toEqual([2, 5, 8, 3, 6, 9, 4, 7, 10]);
+  });
 });
 
 describe('copyMatrix3ColumnFromVector3', () => {
@@ -117,10 +123,11 @@ describe('copyMatrix3ColumnFromVector3', () => {
     expect(getMatrix3Element(m, 2, 2)).toBe(7);
   });
 
-  it('should throw when column is greater than 2', () => {
+  it('throws when column is outside 0 through 2', () => {
     const m = createMatrix3();
     const v = createVector3();
-    expect(() => copyMatrix3ColumnFromVector3(m, 3, v)).toThrow();
+    expect(() => copyMatrix3ColumnFromVector3(m, -1, v)).toThrow(RangeError);
+    expect(() => copyMatrix3ColumnFromVector3(m, 3, v)).toThrow(RangeError);
   });
 });
 
@@ -152,10 +159,11 @@ describe('copyMatrix3ColumnToVector3', () => {
     expect(v.z).toBe(9);
   });
 
-  it('should throw when column is greater than 2', () => {
+  it('throws when column is outside 0 through 2', () => {
     const m = createMatrix3();
     const v = createVector3();
-    expect(() => copyMatrix3ColumnToVector3(v, 3, m)).toThrow();
+    expect(() => copyMatrix3ColumnToVector3(v, -1, m)).toThrow(RangeError);
+    expect(() => copyMatrix3ColumnToVector3(v, 3, m)).toThrow(RangeError);
   });
 
   it('should allow matrix-like and vector-like objects', () => {
@@ -188,10 +196,11 @@ describe('copyMatrix3RowFromVector3', () => {
     expect(getMatrix3Element(m, 1, 2)).toBe(6);
   });
 
-  it('should throw when row is greater than 2', () => {
+  it('throws when row is outside 0 through 2', () => {
     const m = createMatrix3();
     const v = createVector3();
-    expect(() => copyMatrix3RowFromVector3(m, 3, v)).toThrow();
+    expect(() => copyMatrix3RowFromVector3(m, -1, v)).toThrow(RangeError);
+    expect(() => copyMatrix3RowFromVector3(m, 3, v)).toThrow(RangeError);
   });
 
   it('should allow matrix-like and vector-like objects', () => {
@@ -232,6 +241,13 @@ describe('copyMatrix3RowToVector3', () => {
     expect(v.z).toBe(1);
   });
 
+  it('throws when row is outside 0 through 2', () => {
+    const m = createMatrix3();
+    const v = createVector3();
+    expect(() => copyMatrix3RowToVector3(v, -1, m)).toThrow(RangeError);
+    expect(() => copyMatrix3RowToVector3(v, 3, m)).toThrow(RangeError);
+  });
+
   it('should allow matrix-like and vector-like objects', () => {
     // Column-major storage of rows [1,2,3],[4,5,6],[7,8,9]; row 0 = (1,2,3).
     const m = { m: new Float32Array([1, 4, 7, 2, 5, 8, 3, 6, 9]) };
@@ -458,6 +474,18 @@ describe('isAffineMatrix3', () => {
 });
 
 describe('multiplyMatrix3', () => {
+  it('multiplies a non-affine matrix into distinct and aliased outputs', () => {
+    const a = createMatrix3(1, 2, 3, 4, 5, 6, 7, 8, 10);
+    const b = createMatrix3(2, 0, 1, 1, 3, 0, 0, 2, 4);
+    const expected = createMatrix3(4, 12, 13, 13, 27, 28, 22, 44, 47);
+    const out = createMatrix3();
+    multiplyMatrix3(out, a, b);
+    expect(equalsMatrix3(out, expected)).toBe(true);
+
+    multiplyMatrix3(a, a, b);
+    expect(equalsMatrix3(a, expected)).toBe(true);
+  });
+
   it('should support out === a', () => {
     const a = createMatrix3(2, 3, 4, 5, 7, 8, 0, 0, 1);
     const b = createMatrix3(11, 13, 17, 19, 23, 29, 0, 0, 1);
@@ -556,6 +584,12 @@ describe('scaleMatrix3', () => {
     expect(out.m[0]).toBe(2); // (0,0)
     expect(out.m[4]).toBe(3); // (1,1)
   });
+
+  it('supports out === source', () => {
+    const matrix = createMatrix3(1, 2, 3, 4, 5, 6, 7, 8, 9);
+    scaleMatrix3(matrix, matrix, 2, 3);
+    expect(Array.from(matrix.m)).toEqual([2, 8, 14, 6, 15, 24, 3, 6, 9]);
+  });
 });
 
 describe('setMatrix3', () => {
@@ -766,6 +800,12 @@ describe('translateMatrix3', () => {
     expect(out.m[6]).toBe(2); // (0,2) tx
     expect(out.m[7]).toBe(3); // (1,2) ty
   });
+
+  it('supports out === source', () => {
+    const matrix = createMatrix3(1, 2, 3, 4, 5, 6, 0, 0, 1);
+    translateMatrix3(matrix, matrix, 2, 3);
+    expect(Array.from(matrix.m)).toEqual([1, 4, 0, 2, 5, 0, 11, 29, 1]);
+  });
 });
 
 describe('transposeMatrix3', () => {

package/src/matrix3Pool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import { getMatrix3Element } from '@flighthq/geometry/contract';
 import type { Matrix3 } from '@flighthq/types/contract';
 
@@ -67,6 +68,16 @@ describe('clearMatrix3Pool', () => {
 });
 
 describe('releaseMatrix3', () => {
+  it('detaches the previous owner binding before the matrix is reused', () => {
+    const m = acquireMatrix3();
+    attachEntityBinding(m, { owner: 'first' });
+    releaseMatrix3(m);
+
+    const reused = acquireMatrix3();
+    expect(reused).toBe(m);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('handles null safely', () => {
     expect(() => releaseMatrix3(null as unknown as Matrix3)).not.toThrow();
   });