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

package/src/quaternionPool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import {
   acquireIdentityQuaternion,
   acquireQuaternion,
@@ -55,6 +56,17 @@ describe('clearQuaternionPool', () => {
 });
 
 describe('releaseQuaternion', () => {
+  it('detaches the previous owner binding before the quaternion is reused', () => {
+    clearQuaternionPool();
+    const q = acquireQuaternion();
+    attachEntityBinding(q, { owner: 'first' });
+    releaseQuaternion(q);
+
+    const reused = acquireQuaternion();
+    expect(reused).toBe(q);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('ignores a falsy value', () => {
     clearQuaternionPool();
 

package/src/ray3d.test.ts

@@ -1,5 +1,7 @@
 import { createAabb } from './aabb';
 import { createBoundingSphere } from './boundingSphere';
+import { createCapsule, intersectRay3DCapsule } from './capsule';
+import { createObb, intersectRay3DObb } from './obb';
 import { createPlane } from './plane';
 import {
   createRay3D,
@@ -73,6 +75,55 @@ describe('getClosestPointBetweenRay3Ds', () => {
     // Gap between the parallel rays is 2 along Y.
     expect(Math.hypot(pa.x - pb.x, pa.y - pb.y, pa.z - pb.z)).toBeCloseTo(2, 6);
   });
+
+  it('clamps to the origin of the first ray when its nearest approach is behind it', () => {
+    // Ray a runs +X from the origin; ray b is a vertical line well behind a's start. The nearest
+    // point on a's infinite line is at x = -5, which is not on the ray, so a's origin is the answer.
+    const a = createRay3D(0, 0, 0, 1, 0, 0);
+    const b = createRay3D(-5, 1, 0, 0, 0, 1);
+    const pa = createVector3();
+    const pb = createVector3();
+    getClosestPointBetweenRay3Ds(pa, pb, a, b);
+    expect(pa.x).toBeCloseTo(0, 6);
+    expect(pa.y).toBeCloseTo(0, 6);
+    expect(pa.z).toBeCloseTo(0, 6);
+    expect(pb.x).toBeCloseTo(-5, 6);
+    expect(pb.y).toBeCloseTo(1, 6);
+    expect(pb.z).toBeCloseTo(0, 6);
+  });
+
+  it('clamps both rays to their origins when each nearest approach is behind the other', () => {
+    // Both rays head away, so both clamps fire: the second to its origin, and then the first,
+    // re-derived from that, to its own.
+    const a = createRay3D(5, 0, 0, 1, 0, 0);
+    const b = createRay3D(0, 3, 0, 0, 1, 0);
+    const pa = createVector3();
+    const pb = createVector3();
+    getClosestPointBetweenRay3Ds(pa, pb, a, b);
+    expect(pa.x).toBeCloseTo(5, 6);
+    expect(pa.y).toBeCloseTo(0, 6);
+    expect(pb.x).toBeCloseTo(0, 6);
+    expect(pb.y).toBeCloseTo(3, 6);
+  });
+
+  it('writes finite points when either direction has no length', () => {
+    // A direction of zero length gives the solver a zero denominator on both the second and the
+    // first ray in turn. Without its guards this writes NaN into the caller's vectors, which is
+    // worse than a poor answer because it spreads silently through whatever consumes it.
+    const pa = createVector3();
+    const pb = createVector3();
+
+    getClosestPointBetweenRay3Ds(pa, pb, createRay3D(0, 0, 0, 1, 0, 0), createRay3D(5, 1, 0, 0, 0, 0));
+    expect(Number.isFinite(pa.x) && Number.isFinite(pa.y) && Number.isFinite(pa.z)).toBe(true);
+    expect(pb.x).toBe(5);
+    expect(pb.y).toBe(1);
+
+    getClosestPointBetweenRay3Ds(pa, pb, createRay3D(0, 0, 0, 0, 0, 0), createRay3D(0, 0, 5, 0, 0, 1));
+    expect(pa.x).toBe(0);
+    expect(pa.y).toBe(0);
+    expect(pa.z).toBe(0);
+    expect(Number.isFinite(pb.x) && Number.isFinite(pb.y) && Number.isFinite(pb.z)).toBe(true);
+  });
 });
 
 describe('getClosestPointOnRay3D', () => {
@@ -110,6 +161,17 @@ describe('getClosestPointOnRay3D', () => {
     expect(p.y).toBeCloseTo(4, 6);
     expect(p.z).toBeCloseTo(0, 6);
   });
+
+  it('writes the origin for a ray with no direction', () => {
+    // A ray with no direction reaches nowhere, so its origin is the only point it has. Dividing
+    // by the zero length instead would put NaN in the caller's vector.
+    const ray = createRay3D(1, 2, 3, 0, 0, 0);
+    const out = createVector3();
+    getClosestPointOnRay3D(out, ray, createVector3(9, 9, 9));
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(2);
+    expect(out.z).toBe(3);
+  });
 });
 
 describe('getRay3DPointAt', () => {
@@ -172,6 +234,52 @@ describe('intersectRay3DAabb', () => {
     const t = intersectRay3DAabb(ray, aabb);
     expect(t).toBeCloseTo(4);
   });
+
+  it.each([
+    ['x', createRay3D(5, 1.5, 1.5, -1, 0, 0), createAabb(2, 1, 1, 1, 2, 2)],
+    ['y', createRay3D(1.5, 5, 1.5, 0, -1, 0), createAabb(1, 2, 1, 2, 1, 2)],
+    ['z', createRay3D(1.5, 1.5, 5, 0, 0, -1), createAabb(1, 1, 2, 2, 2, 1)],
+  ])('returns -1 for an AABB empty on %s', (_axis, ray, empty) => {
+    expect(intersectRay3DAabb(ray, empty)).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 aabb = createAabb(-1, -1, -1, 1, 1, 1);
+    expect(intersectRay3DAabb(createRay3D(0, 0, 0, 0, 0, 0), aabb)).toBe(-1);
+    expect(intersectRay3DAabb(createRay3D(5, 0, 0, 0, 0, 0), aabb)).toBe(-1);
+  });
+
+  it('enters each of the six sides at that side’s own distance', () => {
+    // One slab per axis, written out three times in the source rather than looped, and each one
+    // orders its own pair of crossings. A bound picked up from the block above only shows up on
+    // the axis it was mistyped on, and only in one direction along it — so the box has six
+    // different distances to its sides and each ray is checked against the one it should hit.
+    // A cube would hide exactly the mistake this is here to catch.
+    const lopsided = createAabb(-1, -4, -6, 2, 3, 5);
+    for (const [ox, oy, oz, dx, dy, dz, entry] of RAYS_INTO_LOPSIDED_BOX) {
+      expect(intersectRay3DAabb(createRay3D(ox, oy, oz, dx, dy, dz), lopsided)).toBeCloseTo(entry, 6);
+    }
+  });
+
+  it('returns -1 for a ray aimed away from the box along any axis', () => {
+    // Same six positions, turned around. The box is behind the origin, so both crossings are
+    // behind it and the slab that owns that axis is the one that has to reject.
+    const lopsided = createAabb(-1, -4, -6, 2, 3, 5);
+    for (const [ox, oy, oz, dx, dy, dz] of RAYS_INTO_LOPSIDED_BOX) {
+      expect(intersectRay3DAabb(createRay3D(ox, oy, oz, -dx, -dy, -dz), lopsided)).toBe(-1);
+    }
+  });
+
+  it('returns -1 for a ray running alongside the box on any axis', () => {
+    // No motion on one axis and outside the box on it: the ray stays level with the box forever
+    // and never enters, which each slab has to catch without a crossing to compute.
+    const lopsided = createAabb(-1, -4, -6, 2, 3, 5);
+    expect(intersectRay3DAabb(createRay3D(10, 0, 0, 0, 1, 0), lopsided)).toBe(-1);
+    expect(intersectRay3DAabb(createRay3D(0, 10, 0, 0, 0, 1), lopsided)).toBe(-1);
+    expect(intersectRay3DAabb(createRay3D(0, 0, 10, 1, 0, 0), lopsided)).toBe(-1);
+  });
 });
 
 describe('intersectRay3DPlane', () => {
@@ -193,6 +301,17 @@ describe('intersectRay3DPlane', () => {
     const ray = createRay3D(0, 0, 3, 0, 0, 1); // pointing away from z=0
     expect(intersectRay3DPlane(ray, plane)).toBe(-1);
   });
+
+  it.each([1, 1e-6, 1e-12])('is invariant when the plane equation is scaled by %s', (scale) => {
+    const plane = createPlane(0, 0, scale, 3 * scale);
+    const ray = createRay3D(0, 0, -6, 0, 0, 2);
+    expect(intersectRay3DPlane(ray, plane)).toBeCloseTo(1.5, 10);
+  });
+
+  it('returns -1 for a zero normal or zero direction', () => {
+    expect(intersectRay3DPlane(createRay3D(0, 0, -3, 0, 0, 1), createPlane())).toBe(-1);
+    expect(intersectRay3DPlane(createRay3D(0, 0, -3, 0, 0, 0), createPlane(0, 0, 1, 0))).toBe(-1);
+  });
 });
 
 describe('intersectRay3DSphere', () => {
@@ -220,6 +339,18 @@ describe('intersectRay3DSphere', () => {
     const ray = createRay3D(0, 0, -5, 0, 0, 1);
     expect(intersectRay3DSphere(ray, sphere)).toBe(-1);
   });
+
+  it('returns -1 when the sphere is squarely behind the ray', () => {
+    // Aimed away rather than off to one side: the line through the ray does cross the sphere, so
+    // this is not the miss the other test covers — both crossings are simply behind the origin.
+    const sphere = createBoundingSphere(0, 0, 0, 1);
+    expect(intersectRay3DSphere(createRay3D(5, 0, 0, 1, 0, 0), sphere)).toBe(-1);
+  });
+
+  it('returns -1 for a ray with no direction', () => {
+    const sphere = createBoundingSphere(0, 0, 0, 1);
+    expect(intersectRay3DSphere(createRay3D(0, 0, 0, 0, 0, 0), sphere)).toBe(-1);
+  });
 });
 
 describe('intersectRay3DTriangle', () => {
@@ -255,6 +386,66 @@ describe('intersectRay3DTriangle', () => {
     const ray = createRay3D(0, 0, -1, 0, 0, 1);
     expect(intersectRay3DTriangle(ray, p, p, p)).toBe(-1);
   });
+
+  it.each([1, 1e-6, 1e-12])('accepts a non-normalized direction scaled by %s', (scale) => {
+    const ray = createRay3D(0, 0.3, -3, 0, 0, scale);
+    expect(intersectRay3DTriangle(ray, a, b, c) * scale).toBeCloseTo(3, 10);
+  });
+
+  it.each([1, 1e-3, 1e-6])('does not treat a triangle scaled by %s as degenerate', (scale) => {
+    const scaledA = { x: -scale, y: 0, z: 0 };
+    const scaledB = { x: scale, y: 0, z: 0 };
+    const scaledC = { x: 0, y: scale, z: 0 };
+    const ray = createRay3D(0, 0.3 * scale, -3, 0, 0, 1);
+    expect(intersectRay3DTriangle(ray, scaledA, scaledB, scaledC)).toBeCloseTo(3, 10);
+  });
+
+  it('returns -1 for a zero direction', () => {
+    expect(intersectRay3DTriangle(createRay3D(0, 0.3, -3, 0, 0, 0), a, b, c)).toBe(-1);
+  });
+
+  it('returns -1 for a nonzero direction nearly parallel to the triangle', () => {
+    const nearlyParallel = createRay3D(-1, 0.3, -1e-12, 1, 0, 1e-12);
+    expect(intersectRay3DTriangle(nearlyParallel, a, b, c)).toBe(-1);
+  });
+
+  it('returns -1 for points inside the triangle’s span but past its far edge', () => {
+    // The triangle covers x in [-1, 1] along the base and rises to (0, 1). A ray through
+    // (0.9, 0.9) lands in the corner the hypotenuse cuts off: within the reach of both edges
+    // measured from the first corner, but outside the triangle itself.
+    const ray = createRay3D(0.9, 0.9, -3, 0, 0, 1);
+    expect(intersectRay3DTriangle(ray, a, b, c)).toBe(-1);
+  });
+
+  it('returns -1 for points on the far side of the base', () => {
+    const ray = createRay3D(0, -0.5, -3, 0, 0, 1);
+    expect(intersectRay3DTriangle(ray, a, b, c)).toBe(-1);
+  });
+
+  it('returns -1 for points beyond either end of the first edge', () => {
+    // Off the end of the base in each direction. These are rejected on the first barycentric
+    // coordinate, before the second is worked out at all — a different rejection from the two
+    // above, and the one that stops a point way off the triangle being measured against its far
+    // edge as though it were nearby.
+    expect(intersectRay3DTriangle(createRay3D(3, 0, -3, 0, 0, 1), a, b, c)).toBe(-1);
+    expect(intersectRay3DTriangle(createRay3D(0, 3, -3, 0, 0, 1), a, b, c)).toBe(-1);
+  });
+});
+
+describe('ray-shape direction scale parity', () => {
+  it.each([1, 1e-6, 1e-12])('preserves the hit point across all six shapes at scale %s', (scale) => {
+    const ray = createRay3D(5, 0, 0, -scale, 0, 0);
+    const hits = [
+      intersectRay3DAabb(ray, createAabb(-1, -1, -1, 1, 1, 1)),
+      intersectRay3DSphere(ray, createBoundingSphere(0, 0, 0, 1)),
+      intersectRay3DCapsule(ray, createCapsule(0, -1, 0, 0, 1, 0, 1)),
+      intersectRay3DObb(ray, createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1)),
+      intersectRay3DPlane(ray, createPlane(1, 0, 0, -1)),
+      intersectRay3DTriangle(ray, { x: 1, y: -1, z: -1 }, { x: 1, y: 1, z: -1 }, { x: 1, y: 0, z: 1 }),
+    ];
+
+    for (const t of hits) expect(t * scale).toBeCloseTo(4, 10);
+  });
 });
 
 describe('setRay3D', () => {
@@ -295,3 +486,16 @@ describe('setRay3D', () => {
     expect(ray.direction.z).toBe(0);
   });
 });
+
+// Six rays, one per side of the box spanning (-1, -4, -6) to (2, 3, 5), each starting 10 units out
+// along an axis and aimed at it. The last number is where that ray meets the box: all six differ,
+// so a slab reading another axis' bound gives a different answer rather than the same one.
+// Reversing the direction of each turns the set into six rays aimed away from the box.
+const RAYS_INTO_LOPSIDED_BOX: ReadonlyArray<readonly [number, number, number, number, number, number, number]> = [
+  [-10, 0, 0, 1, 0, 0, 9],
+  [10, 0, 0, -1, 0, 0, 8],
+  [0, -10, 0, 0, 1, 0, 6],
+  [0, 10, 0, 0, -1, 0, 7],
+  [0, 0, -10, 0, 0, 1, 4],
+  [0, 0, 10, 0, 0, -1, 5],
+];

package/src/rectangle.test.ts

@@ -291,6 +291,11 @@ describe('enclosesRectangle', () => {
 });
 
 describe('equalsRectangle', () => {
+  it('returns false when exactly one rectangle is absent', () => {
+    expect(equalsRectangle(r, null)).toBe(false);
+    expect(equalsRectangle(undefined, r)).toBe(false);
+  });
+
   it('returns true for identical rectangles', () => {
     expect(equalsRectangle(r, r)).toBe(true);
     expect(equalsRectangle(r, cloneRectangle(r))).toBe(true);
@@ -307,28 +312,61 @@ describe('equalsRectangle', () => {
     expect(equalsRectangle(r, r)).toBe(true);
     expect(equalsRectangle(r, r2)).toBe(true);
   });
+
+  it('compares every field, not just the position', () => {
+    // Four hand-written comparisons in a row: one left reading the wrong field agrees with the
+    // right answer on every pair that differs in more than one place, so each differs alone here.
+    const base = createRectangle(1, 2, 3, 4);
+    expect(equalsRectangle(base, createRectangle(9, 2, 3, 4))).toBe(false);
+    expect(equalsRectangle(base, createRectangle(1, 9, 3, 4))).toBe(false);
+    expect(equalsRectangle(base, createRectangle(1, 2, 9, 4))).toBe(false);
+    expect(equalsRectangle(base, createRectangle(1, 2, 3, 9))).toBe(false);
+  });
+
+  it('returns false when either side is missing', () => {
+    // The signature accepts null and undefined, so absence is an answerable input rather than
+    // misuse: nothing is equal to a rectangle, including another absence. Two absences are two
+    // unknowns, not one shared value — the same answer the three equalsVector* functions give.
+    const rect = createRectangle(1, 2, 3, 4);
+    expect(equalsRectangle(rect, null)).toBe(false);
+    expect(equalsRectangle(null, rect)).toBe(false);
+    expect(equalsRectangle(rect, undefined)).toBe(false);
+    expect(equalsRectangle(undefined, rect)).toBe(false);
+    expect(equalsRectangle(null, null)).toBe(false);
+    expect(equalsRectangle(undefined, undefined)).toBe(false);
+    expect(equalsRectangle(null, undefined)).toBe(false);
+  });
+
+  it('holds a rectangle equal to itself even with a NaN field', () => {
+    // Comparing field by field would say a rectangle carrying NaN differs from itself, and a
+    // caller watching for changes would then see one every time it looked.
+    const notANumber = createRectangle(NaN, 2, 3, 4);
+    expect(equalsRectangle(notANumber, notANumber)).toBe(true);
+    expect(equalsRectangle(notANumber, createRectangle(NaN, 2, 3, 4))).toBe(false);
+  });
 });
 
 describe('expandRectangleToPoint', () => {
-  it('inflates rectangle by Vector2', () => {
+  it('expands a rectangle to contain an outside point', () => {
+    const source = createRectangle(10, 10, 5, 5);
     const result = createRectangle();
-    expandRectangleToPoint(result, r, createVector2(1, 2));
-    expect(result).not.toBe(r);
-    expect(result.x).toBe(-1);
-    expect(result.y).toBe(-2);
-    expect(result.width).toBe(12);
-    expect(result.height).toBe(24);
+    expandRectangleToPoint(result, source, createVector2(20, 12));
+    expect(result).not.toBe(source);
+    expect(result).toMatchObject({ x: 10, y: 10, width: 10, height: 5 });
   });
 
-  it('allows rectangle- and point-like objects', () => {
-    const r = { x: 0, y: 0, width: 10, height: 20 };
-    const p = { x: 1, y: 2 };
+  it('normalizes flipped bounds while expanding', () => {
+    const r = { x: 10, y: 10, width: -5, height: -5 };
+    const p = { x: 12, y: 4 };
     const result = { x: 0, y: 0, width: 0, height: 0 };
     expandRectangleToPoint(result, r, p);
-    expect(result.x).toBe(-1);
-    expect(result.y).toBe(-2);
-    expect(result.width).toBe(12);
-    expect(result.height).toBe(24);
+    expect(result).toEqual({ x: 5, y: 4, width: 7, height: 6 });
+  });
+
+  it('supports out === sourceRect', () => {
+    const source = createRectangle(10, 10, 5, 5);
+    expandRectangleToPoint(source, source, createVector2(20, 12));
+    expect(source).toMatchObject({ x: 10, y: 10, width: 10, height: 5 });
   });
 });
 
@@ -835,6 +873,12 @@ describe('offsetRectangleByPoint', () => {
     expect(out.x).toBe(3);
     expect(out.y).toBe(4);
   });
+
+  it('supports out === source', () => {
+    const source = createRectangle(1, 2, 10, 20);
+    offsetRectangleByPoint(source, source, createVector2(3, 4));
+    expect(source).toMatchObject({ x: 4, y: 6, width: 10, height: 20 });
+  });
 });
 
 describe('setEmptyRectangle', () => {

package/src/rectanglePool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import type { Rectangle } from '@flighthq/types/contract';
 
 import { acquireEmptyRectangle, acquireRectangle, clearRectanglePool, releaseRectangle } from './rectanglePool';
@@ -65,6 +66,16 @@ describe('clearRectanglePool', () => {
 });
 
 describe('releaseRectangle', () => {
+  it('detaches the previous owner binding before the rectangle is reused', () => {
+    const r = acquireRectangle();
+    attachEntityBinding(r, { owner: 'first' });
+    releaseRectangle(r);
+
+    const reused = acquireRectangle();
+    expect(reused).toBe(r);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('handles null safely', () => {
     expect(() => releaseRectangle(null as unknown as Rectangle)).not.toThrow();
   });

package/src/transform2d.test.ts

@@ -81,4 +81,42 @@ describe('decomposeMatrixToTransform2D', () => {
     expect(out.scaleX).toBeCloseTo(1);
     expect(out.scaleY).toBeCloseTo(-1);
   });
+
+  it('round-trips a mirrored matrix through the forward build', () => {
+    expectRoundTrip(createMatrix(1, 0, 0, -1, 0, 0));
+    expectRoundTrip(createMatrix(-1, 0, 0, 1, 0, 0));
+    expectRoundTrip(createMatrix(0.5, 0.8, 0.8, -0.5, 3, 4));
+  });
+
+  // The failure set is the negative-determinant set on any input, not a mirror-specific shape, so the
+  // property is asserted over a grid spanning both determinant signs rather than at hand-picked cases.
+  it('round-trips every non-degenerate matrix in a grid spanning both determinant signs', () => {
+    const values = [-2, -1, -0.5, 0.5, 1, 2];
+    let negativeDeterminantCount = 0;
+    for (const a of values) {
+      for (const b of values) {
+        for (const c of values) {
+          for (const d of values) {
+            if (Math.abs(a * d - b * c) < 1e-9) continue;
+            if (a * d - b * c < 0) negativeDeterminantCount++;
+            expectRoundTrip(createMatrix(a, b, c, d, 0, 0));
+          }
+        }
+      }
+    }
+    // Guards the guard: a grid that stopped covering reflections would still pass every assertion above.
+    expect(negativeDeterminantCount).toBe(572);
+  });
 });
+
+// Decomposing and rebuilding through the forward convention must reproduce the original cells. This is
+// the losslessness `setNodeLocalMatrix` promises its callers, and it holds for both determinant signs.
+function expectRoundTrip(source: Readonly<ReturnType<typeof createMatrix>>) {
+  const out = createTransform2D();
+  decomposeMatrixToTransform2D(out, source);
+  const rebuilt = buildMatrix(out.x, out.y, out.rotation, out.scaleX, out.scaleY, out.skewX, out.skewY);
+  expect(rebuilt.a).toBeCloseTo(source.a);
+  expect(rebuilt.b).toBeCloseTo(source.b);
+  expect(rebuilt.c).toBeCloseTo(source.c);
+  expect(rebuilt.d).toBeCloseTo(source.d);
+}