@flighthq/collision 0.4.0-next.1663.d9c5746 → 0.4.0-next.1694.598ef6f

package/src/collisionSupport2D.test.ts

@@ -0,0 +1,166 @@
+import type { CollisionShape2D } from '@flighthq/types/contract';
+
+import {
+  getCollisionPairTest2D,
+  getCollisionSupport2D,
+  registerBuiltInCollisionSupports2D,
+  registerCollisionPairTest2D,
+  registerCollisionSupport2D,
+  supportCollisionAabb2D,
+  supportCollisionCircle2D,
+  supportCollisionObb2D,
+  supportCollisionPolygon2D,
+  writeVertexListSupport2D,
+} from './collisionSupport2D';
+
+registerBuiltInCollisionSupports2D();
+
+describe('getCollisionPairTest2D', () => {
+  it('is null for a pair nobody registered', () => {
+    expect(getCollisionPairTest2D('circle', 'acme.capsule')).toBeNull();
+  });
+
+  it('keys on the ORDERED pair, so the reverse is a separate entry', () => {
+    const test = () => false;
+    registerCollisionPairTest2D('acme.left', 'acme.right', test);
+
+    expect(getCollisionPairTest2D('acme.left', 'acme.right')).toBe(test);
+    expect(getCollisionPairTest2D('acme.right', 'acme.left')).toBeNull();
+  });
+
+  it('cannot confuse two pairs whose names run together the same way', () => {
+    const first = () => false;
+    const second = () => true;
+    registerCollisionPairTest2D('ab', 'c', first);
+    registerCollisionPairTest2D('a', 'bc', second);
+
+    // Concatenating the kinds without a separator lands both on `abc`. The collision cannot occur among
+    // the built-ins and appears the first time a vendor kind is a prefix of another.
+    expect(getCollisionPairTest2D('ab', 'c')).toBe(first);
+    expect(getCollisionPairTest2D('a', 'bc')).toBe(second);
+  });
+});
+
+describe('getCollisionSupport2D', () => {
+  it('is null for a kind nobody registered', () => {
+    expect(getCollisionSupport2D('acme.unregistered')).toBeNull();
+  });
+
+  it('resolves each built-in area kind', () => {
+    expect(getCollisionSupport2D('aabb')).toBe(supportCollisionAabb2D);
+    expect(getCollisionSupport2D('circle')).toBe(supportCollisionCircle2D);
+    expect(getCollisionSupport2D('obb')).toBe(supportCollisionObb2D);
+    expect(getCollisionSupport2D('polygon')).toBe(supportCollisionPolygon2D);
+  });
+
+  it('leaves the area-less kinds unregistered', () => {
+    // Deliberate: a support function could be written for either, and GJK would then report a
+    // penetration depth against a shape that has no interior for one to mean anything in.
+    expect(getCollisionSupport2D('point')).toBeNull();
+    expect(getCollisionSupport2D('segment')).toBeNull();
+  });
+});
+
+describe('registerBuiltInCollisionSupports2D', () => {
+  it('registers exactly the four area kinds', () => {
+    registerBuiltInCollisionSupports2D();
+
+    const registered = ['aabb', 'circle', 'obb', 'polygon', 'point', 'segment'].filter(
+      (kind) => getCollisionSupport2D(kind) !== null,
+    );
+    expect(registered).toEqual(['aabb', 'circle', 'obb', 'polygon']);
+  });
+});
+
+describe('registerCollisionPairTest2D', () => {
+  it('lets a later registration replace an earlier one', () => {
+    const first = () => false;
+    const second = () => true;
+    registerCollisionPairTest2D('acme.a', 'acme.b', first);
+    registerCollisionPairTest2D('acme.a', 'acme.b', second);
+
+    expect(getCollisionPairTest2D('acme.a', 'acme.b')).toBe(second);
+  });
+});
+
+describe('registerCollisionSupport2D', () => {
+  it('lets a caller override a built-in, last write wins', () => {
+    const replacement = supportCollisionCircle2D;
+    registerCollisionSupport2D('acme.override', replacement);
+
+    expect(getCollisionSupport2D('acme.override')).toBe(replacement);
+  });
+});
+
+describe('supportCollisionAabb2D', () => {
+  it('picks the corner the direction signs name', () => {
+    const box: CollisionShape2D = { kind: 'aabb', maxX: 2, maxY: 3, minX: -1, minY: -4 };
+    const out = [0, 0];
+
+    supportCollisionAabb2D(box, 1, 1, out);
+    expect(out).toEqual([2, 3]);
+    supportCollisionAabb2D(box, -1, -1, out);
+    expect(out).toEqual([-1, -4]);
+    supportCollisionAabb2D(box, -1, 1, out);
+    expect(out).toEqual([-1, 3]);
+  });
+});
+
+describe('supportCollisionCircle2D', () => {
+  it('pushes the centre one radius along the direction, whatever its length', () => {
+    const circle: CollisionShape2D = { kind: 'circle', radius: 2, x: 1, y: 1 };
+    const unit = [0, 0];
+    const long = [0, 0];
+
+    supportCollisionCircle2D(circle, 1, 0, unit);
+    supportCollisionCircle2D(circle, 50, 0, long);
+
+    expect(unit[0]).toBeCloseTo(3, 12);
+    expect(unit[1]).toBeCloseTo(1, 12);
+    // A support direction is not required to be unit length; normalizing is the function's job.
+    expect(long).toEqual(unit);
+  });
+
+  it('answers a zero direction with the centre rather than a NaN', () => {
+    const out = [0, 0];
+
+    supportCollisionCircle2D({ kind: 'circle', radius: 2, x: 1, y: -1 }, 0, 0, out);
+
+    expect(out).toEqual([1, -1]);
+  });
+});
+
+describe('supportCollisionObb2D', () => {
+  it('picks the furthest rotated corner', () => {
+    const out = [0, 0];
+    // A quarter turn maps the box's local +x onto world +y, so the furthest corner along +y is the one
+    // the unrotated box would have reached along +x.
+    supportCollisionObb2D({ halfH: 1, halfW: 2, kind: 'obb', rotation: Math.PI / 2, x: 0, y: 0 }, 0, 1, out);
+
+    expect(out[1]).toBeCloseTo(2, 9);
+  });
+});
+
+describe('supportCollisionPolygon2D', () => {
+  it('picks the furthest vertex', () => {
+    const out = [0, 0];
+    const triangle: CollisionShape2D = { kind: 'polygon', points: [0, 0, 4, 0, 0, 3] };
+
+    supportCollisionPolygon2D(triangle, 1, 0, out);
+    expect(out).toEqual([4, 0]);
+    supportCollisionPolygon2D(triangle, 0, 1, out);
+    expect(out).toEqual([0, 3]);
+  });
+});
+
+describe('writeVertexListSupport2D', () => {
+  it('reads a flat coordinate list and keeps the first of an exact tie', () => {
+    const out = [0, 0];
+
+    // Two vertices project identically along +y; a strict `>` keeps the first, which is what makes the
+    // scan deterministic for a caller feeding the same shape twice.
+    writeVertexListSupport2D([0, 1, 5, 1, 0, -1], 3, 0, 1, out);
+
+    expect(out).toEqual([0, 1]);
+  });
+});

package/src/contactManifold.test.ts

@@ -1,17 +1,17 @@
 import { describe, expect, it } from 'vitest';
 
-import { clearCollisionContactManifold, createCollisionContactManifold } from './contactManifold';
+import { clearCollisionContactManifold2D, createCollisionContactManifold2D } from './contactManifold';
 
-describe('clearCollisionContactManifold', () => {
+describe('clearCollisionContactManifold2D', () => {
   it('resets the manifold to the non-overlapping state', () => {
-    const manifold = createCollisionContactManifold();
+    const manifold = createCollisionContactManifold2D();
     manifold.overlapping = true;
     manifold.normalX = 1;
     manifold.normalY = -1;
     manifold.depth = 4;
     manifold.pointCount = 2;
 
-    clearCollisionContactManifold(manifold);
+    clearCollisionContactManifold2D(manifold);
     expect(manifold.overlapping).toBe(false);
     expect(manifold.normalX).toBe(0);
     expect(manifold.normalY).toBe(0);
@@ -20,17 +20,17 @@ describe('clearCollisionContactManifold', () => {
   });
 
   it('keeps the point array allocated so a cleared manifold stays reusable', () => {
-    const manifold = createCollisionContactManifold();
+    const manifold = createCollisionContactManifold2D();
     const points = manifold.points;
-    clearCollisionContactManifold(manifold);
+    clearCollisionContactManifold2D(manifold);
     expect(manifold.points).toBe(points);
     expect(manifold.points).toHaveLength(2);
   });
 });
 
-describe('createCollisionContactManifold', () => {
+describe('createCollisionContactManifold2D', () => {
   it('starts non-overlapping with zeroed normal, depth, and point count', () => {
-    const manifold = createCollisionContactManifold();
+    const manifold = createCollisionContactManifold2D();
     expect(manifold.overlapping).toBe(false);
     expect(manifold.normalX).toBe(0);
     expect(manifold.normalY).toBe(0);
@@ -39,7 +39,7 @@ describe('createCollisionContactManifold', () => {
   });
 
   it('preallocates both contact points so the hot path never allocates', () => {
-    const manifold = createCollisionContactManifold();
+    const manifold = createCollisionContactManifold2D();
     expect(manifold.points).toHaveLength(2);
     for (const point of manifold.points) {
       expect(point).toEqual({ x: 0, y: 0, depth: 0, featureId: 0 });
@@ -47,8 +47,8 @@ describe('createCollisionContactManifold', () => {
   });
 
   it('gives each manifold its own points rather than sharing one array', () => {
-    const first = createCollisionContactManifold();
-    const second = createCollisionContactManifold();
+    const first = createCollisionContactManifold2D();
+    const second = createCollisionContactManifold2D();
     expect(first.points).not.toBe(second.points);
     expect(first.points[0]).not.toBe(second.points[0]);
   });

package/src/convexVertices.test.ts

@@ -1,4 +1,4 @@
-import type { CollisionAabb, CollisionObb } from '@flighthq/types/contract';
+import type { CollisionAabb2D, CollisionObb2D } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import { writeAabbVertices, writeObbVertices } from './convexVertices';
@@ -6,14 +6,14 @@ import { writeAabbVertices, writeObbVertices } from './convexVertices';
 describe('writeAabbVertices', () => {
   it('writes the four corners counter-clockwise from the min corner', () => {
     const out = new Float64Array(8);
-    const aabb: CollisionAabb = { minX: 1, minY: 2, maxX: 5, maxY: 8 };
+    const aabb: CollisionAabb2D = { minX: 1, minY: 2, maxX: 5, maxY: 8 };
     writeAabbVertices(aabb, out);
     expect(Array.from(out)).toEqual([1, 2, 5, 2, 5, 8, 1, 8]);
   });
 
   it('writes a degenerate box as four coincident corners rather than skipping any', () => {
     const out = new Float64Array(8);
-    const aabb: CollisionAabb = { minX: 3, minY: 3, maxX: 3, maxY: 3 };
+    const aabb: CollisionAabb2D = { minX: 3, minY: 3, maxX: 3, maxY: 3 };
     writeAabbVertices(aabb, out);
     expect(Array.from(out)).toEqual([3, 3, 3, 3, 3, 3, 3, 3]);
   });
@@ -30,7 +30,7 @@ describe('writeObbVertices', () => {
 
   it('rotates the corners about the center, preserving the distance to it', () => {
     const out = new Float64Array(8);
-    const obb: CollisionObb = { x: 0, y: 0, halfW: 3, halfH: 4, rotation: Math.PI / 3 };
+    const obb: CollisionObb2D = { x: 0, y: 0, halfW: 3, halfH: 4, rotation: Math.PI / 3 };
     writeObbVertices(obb, out);
     const expected = Math.sqrt(3 * 3 + 4 * 4);
     for (let i = 0; i < 4; i++) {

package/src/enableCollisionGuards.test.ts

@@ -1,9 +1,9 @@
 import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
-import type { CollisionShape, LogEntry } from '@flighthq/types/contract';
+import type { CollisionShape2D, LogEntry } from '@flighthq/types/contract';
 
 import { areCollisionGuardsEnabled, disableCollisionGuards, enableCollisionGuards } from './enableCollisionGuards';
-import { createCollisionManifold } from './manifold';
-import { testCollision } from './testCollision';
+import { createCollisionManifold2D } from './manifold';
+import { testCollision2D } from './testCollision2D';
 
 function captureLog(run: () => void): readonly LogEntry[] {
   const sink = createMemoryLogSink(8);
@@ -33,10 +33,10 @@ describe('disableCollisionGuards', () => {
     enableCollisionGuards();
     disableCollisionGuards();
     const entries = captureLog(() => {
-      testCollision(
+      testCollision2D(
         { kind: 'circle', radius: 0, x: 0, y: 0 },
         { kind: 'circle', radius: 1, x: 0, y: 0 },
-        createCollisionManifold(),
+        createCollisionManifold2D(),
       );
     });
     expect(entries).toHaveLength(0);
@@ -44,29 +44,64 @@ describe('disableCollisionGuards', () => {
 });
 
 describe('enableCollisionGuards', () => {
-  it('stays silent for supported inputs, then warns once for a degenerate shape through testCollision', () => {
+  it('stays silent for a supported pair, and warns once for a degenerate shape', () => {
     enableCollisionGuards();
-    const out = createCollisionManifold();
-    const valid: CollisionShape = { kind: 'circle', radius: 1, x: 0, y: 0 };
+    const out = createCollisionManifold2D();
+    const valid: CollisionShape2D = { kind: 'circle', radius: 1, x: 0, y: 0 };
     const entries = captureLog(() => {
-      testCollision(valid, { kind: 'circle', radius: 1, x: 4, y: 0 }, out);
-      testCollision({ kind: 'point', x: 0, y: 0 }, valid, out);
-      testCollision({ kind: 'circle', radius: 0, x: 0, y: 0 }, valid, out);
-      testCollision({ kind: 'circle', radius: 0, x: 0, y: 0 }, valid, out);
+      testCollision2D(valid, { kind: 'circle', radius: 1, x: 4, y: 0 }, out);
+      testCollision2D({ kind: 'circle', radius: 0, x: 0, y: 0 }, valid, out);
+      testCollision2D({ kind: 'circle', radius: 0, x: 0, y: 0 }, valid, out);
     });
     expect(entries).toHaveLength(1);
     expect(entries[0].channel).toBe('collision');
     expect(entries[0].data).toMatchObject({ kind: 'circle', shapeIndex: 0, status: 'degenerate-shape' });
-    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('explainCollisionTest');
+    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('explainCollisionTest2D');
+  });
+
+  it('warns for an area-less kind the manifold path cannot answer', () => {
+    enableCollisionGuards();
+    const entries = captureLog(() => {
+      testCollision2D(
+        { kind: 'point', x: 0, y: 0 },
+        { kind: 'circle', radius: 1, x: 0, y: 0 },
+        createCollisionManifold2D(),
+      );
+    });
+
+    // The point is INSIDE the circle, and the manifold path reports them as not overlapping. That
+    // silent false used to be the one refusal the guard stayed quiet about, and it is the worst
+    // sentinel available: indistinguishable from two shapes genuinely not touching.
+    expect(entries).toHaveLength(1);
+    expect(entries[0].data).toMatchObject({ kind: 'point', shapeIndex: 0, status: 'unsupported-shape-kind' });
+    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('area-less');
+  });
+
+  it('warns for a vendor kind nothing has registered', () => {
+    enableCollisionGuards();
+    const entries = captureLog(() => {
+      testCollision2D(
+        { kind: 'circle', radius: 1, x: 0, y: 0 },
+        // Cast through `unknown` because `CollisionShape2D` is still a CLOSED tagged union while
+        // `CollisionShapeKind2D` is open — the mismatch the collision charter's open direction 2
+        // names. A vendor kind is not constructible without this, which is the compile-time half of
+        // the same lie the guard arm above fixes at runtime.
+        { kind: 'acme.capsule' } as unknown as CollisionShape2D,
+        createCollisionManifold2D(),
+      );
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].data).toMatchObject({ kind: 'acme.capsule', shapeIndex: 1, status: 'unsupported-shape-kind' });
   });
 
   it('warns for a non-convex polygon and identifies its argument index', () => {
     enableCollisionGuards();
     const entries = captureLog(() => {
-      testCollision(
+      testCollision2D(
         { kind: 'circle', radius: 1, x: 0, y: 0 },
         { kind: 'polygon', points: [0, 0, 2, 0, 1, 1, 2, 2, 0, 2] },
-        createCollisionManifold(),
+        createCollisionManifold2D(),
       );
     });
     expect(entries).toHaveLength(1);

package/src/explainCollisionTest2D.test.ts

@@ -0,0 +1,75 @@
+import type { CollisionShape2D } from '@flighthq/types/contract';
+
+import { explainCollisionTest2D } from './explainCollisionTest2D';
+import { registerBuiltInCollisionPairTests2D } from './registerBuiltInCollisionPairTests2D';
+
+registerBuiltInCollisionPairTests2D();
+
+describe('explainCollisionTest2D', () => {
+  it('names an unregistered kind rather than calling the pair separated', async () => {
+    // A fresh module registry, so the two collision registries are genuinely empty — the state a caller
+    // who forgot to register is in. Reached this way rather than by ordering this test before the
+    // registrar above, so it cannot be silently broken by moving tests around.
+    vi.resetModules();
+    const { explainCollisionTest2D: explainUnregistered } = await import('./explainCollisionTest2D');
+
+    // A circle is a valid circle whether or not anything is registered for it, so shape validation passes
+    // and the dispatcher returns its silent false. Reporting `separated` for two clearly overlapping
+    // circles would be the seam repeating the dispatcher's silence instead of explaining it.
+    expect(
+      explainUnregistered({ kind: 'circle', radius: 2, x: 0, y: 0 }, { kind: 'circle', radius: 2, x: 1, y: 0 }),
+    ).toEqual({
+      kind: 'circle',
+      overlapping: false,
+      shapeIndex: 0,
+      status: 'unsupported-shape-kind',
+    });
+  });
+
+  it('distinguishes overlap from ordinary separation', () => {
+    const circle: CollisionShape2D = { kind: 'circle', radius: 2, x: 0, y: 0 };
+    expect(explainCollisionTest2D(circle, { kind: 'circle', radius: 2, x: 1, y: 0 })).toEqual({
+      kind: null,
+      overlapping: true,
+      shapeIndex: null,
+      status: 'overlapping',
+    });
+    expect(explainCollisionTest2D(circle, { kind: 'circle', radius: 2, x: 10, y: 0 })).toEqual({
+      kind: null,
+      overlapping: false,
+      shapeIndex: null,
+      status: 'separated',
+    });
+  });
+
+  it('identifies which input is degenerate or non-convex', () => {
+    const circle: CollisionShape2D = { kind: 'circle', radius: 2, x: 0, y: 0 };
+    expect(explainCollisionTest2D(circle, { kind: 'circle', radius: 0, x: 0, y: 0 })).toEqual({
+      kind: 'circle',
+      overlapping: false,
+      shapeIndex: 1,
+      status: 'degenerate-shape',
+    });
+    expect(explainCollisionTest2D({ kind: 'polygon', points: [0, 0, 2, 0, 1, 1, 2, 2, 0, 2] }, circle)).toEqual({
+      kind: 'polygon',
+      overlapping: false,
+      shapeIndex: 0,
+      status: 'non-convex-polygon',
+    });
+  });
+
+  it('explains the silent false sentinel for area-less and unknown kinds', () => {
+    const circle: CollisionShape2D = { kind: 'circle', radius: 2, x: 0, y: 0 };
+    expect(explainCollisionTest2D({ kind: 'point', x: 0, y: 0 }, circle)).toMatchObject({
+      kind: 'point',
+      shapeIndex: 0,
+      status: 'unsupported-shape-kind',
+    });
+    const custom = { kind: 'acme.capsule' } as unknown as CollisionShape2D;
+    expect(explainCollisionTest2D(circle, custom)).toMatchObject({
+      kind: 'acme.capsule',
+      shapeIndex: 1,
+      status: 'unsupported-shape-kind',
+    });
+  });
+});

package/src/gjk2D.test.ts

@@ -0,0 +1,219 @@
+import type { CollisionShape2D } from '@flighthq/types/contract';
+
+import { registerBuiltInCollisionSupports2D } from './collisionSupport2D';
+import { testCollisionSupport2D, testCollisionSupportOverlap2D } from './gjk2D';
+import { createCollisionManifold2D } from './manifold';
+import { testCollision2D } from './testCollision2D';
+
+registerBuiltInCollisionSupports2D();
+
+// The widest gap between the generic core's normal and the incumbent's over this corpus, measured
+// rather than chosen: 3.3e-3, entirely from EPA's angular resolution on a curved boundary. Set just
+// above it so the bound is a real ceiling and a genuine regression cannot hide under a round number.
+const MAX_NORMAL_DEVIATION = 4e-3;
+
+describe('testCollisionSupport2D', () => {
+  it('agrees with every incumbent SAT pair, on overlap and on the manifold itself', () => {
+    // The differential test the collision charter sequences this work behind: ten hand-written pair
+    // functions already encode years of degeneracy and orientation decisions, so the generic core is
+    // measured against them rather than against a fresh set of expectations that could be wrong the
+    // same way it is.
+    //
+    // It earned its keep. It found a real defect in the incumbent — the SAT paths oriented their normal
+    // by comparing shape centroids, which is only a heuristic and picks the wrong side whenever one
+    // projection nests inside the other asymmetrically. Both now read the side that actually won the
+    // penetration comparison, and the two agree exactly: NO exemptions, no tolerated boundary band.
+    const random = createSeededRandom(0x5eed);
+    const generic = createCollisionManifold2D();
+    const incumbent = createCollisionManifold2D();
+    let overlaps = 0;
+    let trials = 0;
+
+    for (let i = 0; i < 4000; i += 1) {
+      const a = createRandomShape(random);
+      const b = createRandomShape(random);
+      trials += 1;
+
+      const genericOverlapping = testCollisionSupport2D(a, b, generic);
+      const incumbentOverlapping = testCollision2D(a, b, incumbent);
+      expect({ i, overlapping: genericOverlapping }).toEqual({ i, overlapping: incumbentOverlapping });
+      if (!genericOverlapping) continue;
+
+      overlaps += 1;
+      expect(generic.depth).toBeCloseTo(incumbent.depth, 5);
+      // The normal is held looser than the depth, and only because of EPA's own geometry: it terminates
+      // on a distance, and distance is second-order insensitive to angular error on a curved boundary,
+      // so a depth converged to 1e-10 still leaves a circle's normal a few parts in a thousand out. The
+      // SIGN is exact, which is what a solver acts on.
+      // Measured as one distance between the two unit normals rather than per component, so the bound
+      // means the same thing whichever way the axis happens to lie.
+      expect(Math.hypot(generic.normalX - incumbent.normalX, generic.normalY - incumbent.normalY)).toBeLessThan(
+        MAX_NORMAL_DEVIATION,
+      );
+    }
+
+    // A differential test that never overlapped would pass while proving nothing.
+    expect(overlaps).toBeGreaterThan(trials / 10);
+  });
+
+  it('orients the normal to push A out of B', () => {
+    const out = createCollisionManifold2D();
+    const a: CollisionShape2D = { kind: 'circle', radius: 1, x: 0, y: 0 };
+    const b: CollisionShape2D = { kind: 'circle', radius: 1, x: 1.5, y: 0 };
+
+    expect(testCollisionSupport2D(a, b, out)).toBe(true);
+
+    // A is left of B, so separating A means moving it further left. The depth is exact to 1e-9; the
+    // direction is a circle's, so it is held to the accuracy EPA can actually reach.
+    expect(out.normalX).toBeCloseTo(-1, 4);
+    expect(out.normalY).toBeCloseTo(0, 4);
+    expect(out.depth).toBeCloseTo(0.5, 9);
+  });
+
+  it('reverses the normal when the arguments are reversed', () => {
+    const forward = createCollisionManifold2D();
+    const reverse = createCollisionManifold2D();
+    const a: CollisionShape2D = { kind: 'aabb', maxX: 1, maxY: 1, minX: -1, minY: -1 };
+    const b: CollisionShape2D = { kind: 'aabb', maxX: 2.5, maxY: 1, minX: 0.5, minY: -1 };
+
+    testCollisionSupport2D(a, b, forward);
+    testCollisionSupport2D(b, a, reverse);
+
+    expect(reverse.normalX).toBeCloseTo(-forward.normalX, 9);
+    expect(reverse.normalY).toBeCloseTo(-forward.normalY, 9);
+    expect(reverse.depth).toBeCloseTo(forward.depth, 9);
+  });
+
+  it('reports a clear manifold for a kind with no registered support', () => {
+    const out = createCollisionManifold2D();
+    out.overlapping = true;
+    out.depth = 5;
+
+    // A point is INSIDE the circle, and is refused anyway: area-less kinds are deliberately absent
+    // from the support registry, because a penetration depth against one means nothing.
+    const overlapping = testCollisionSupport2D(
+      { kind: 'point', x: 0, y: 0 },
+      { kind: 'circle', radius: 1, x: 0, y: 0 },
+      out,
+    );
+
+    expect(overlapping).toBe(false);
+    expect(out.overlapping).toBe(false);
+    expect(out.depth).toBe(0);
+  });
+
+  it('treats a pair that only touches as not overlapping', () => {
+    const out = createCollisionManifold2D();
+
+    const overlapping = testCollisionSupport2D(
+      { kind: 'circle', radius: 1, x: 0, y: 0 },
+      { kind: 'circle', radius: 1, x: 2, y: 0 },
+      out,
+    );
+
+    expect(overlapping).toBe(false);
+  });
+
+  it('takes the shallow axis out of a pair that overlaps on both', () => {
+    const out = createCollisionManifold2D();
+    // Overlapping by 0.2 vertically and by 3 horizontally. The minimum translation is the SHALLOW one,
+    // which is what makes a manifold usable: separating along the deep axis would shove a body across
+    // the room to resolve a graze.
+    testCollisionSupport2D(
+      { kind: 'aabb', maxX: 2, maxY: 1, minX: -2, minY: -1 },
+      { kind: 'aabb', maxX: 1, maxY: 3, minX: -1, minY: 0.8 },
+      out,
+    );
+
+    expect(Math.abs(out.normalX)).toBeCloseTo(0, 6);
+    expect(out.normalY).toBeCloseTo(-1, 6);
+    expect(out.depth).toBeCloseTo(0.2, 6);
+  });
+});
+
+describe('testCollisionSupportOverlap2D', () => {
+  it('agrees with the manifold path about whether a pair overlaps', () => {
+    const random = createSeededRandom(0xc0ffee);
+    const out = createCollisionManifold2D();
+
+    for (let i = 0; i < 1000; i += 1) {
+      const a = createRandomShape(random);
+      const b = createRandomShape(random);
+      expect({ i, overlapping: testCollisionSupportOverlap2D(a, b) }).toEqual({
+        i,
+        overlapping: testCollisionSupport2D(a, b, out),
+      });
+    }
+  });
+
+  it('returns false for an unregistered kind rather than throwing', () => {
+    expect(
+      testCollisionSupportOverlap2D({ kind: 'acme.capsule' } as unknown as CollisionShape2D, {
+        kind: 'circle',
+        radius: 1,
+        x: 0,
+        y: 0,
+      }),
+    ).toBe(false);
+  });
+});
+
+// A small deterministic generator. Reproducibility is the point: a differential test that shuffles
+// differently each run reports a failure nobody can reproduce from the output.
+function createSeededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+}
+
+function createRandomShape(random: () => number): CollisionShape2D {
+  const spread = 4;
+  const x = (random() - 0.5) * spread;
+  const y = (random() - 0.5) * spread;
+  switch (Math.floor(random() * 4)) {
+    case 0:
+      return { kind: 'circle', radius: 0.25 + random() * 1.25, x, y };
+    case 1: {
+      const halfW = 0.25 + random() * 1.25;
+      const halfH = 0.25 + random() * 1.25;
+      return { kind: 'aabb', maxX: x + halfW, maxY: y + halfH, minX: x - halfW, minY: y - halfH };
+    }
+    case 2:
+      return {
+        halfH: 0.25 + random() * 1.25,
+        halfW: 0.25 + random() * 1.25,
+        kind: 'obb',
+        rotation: random() * Math.PI * 2,
+        x,
+        y,
+      };
+    default: {
+      // A convex polygon by construction: vertices on an ellipse at angles that advance by random but
+      // strictly positive steps summing to EXACTLY one turn.
+      //
+      // Normalizing the steps is the whole trick, and skipping it is a real trap — stepping by a random
+      // multiple of `2*pi/count` lets the total overshoot 2*pi, so the last vertices wrap past the first
+      // and the polygon self-intersects. The incumbent documents that it does not answer for a
+      // non-convex polygon, so every such shape becomes a mismatch that looks exactly like a solver bug.
+      const radiusX = 0.3 + random() * 1.2;
+      const radiusY = 0.3 + random() * 1.2;
+      const count = 3 + Math.floor(random() * 4);
+      const steps: number[] = [];
+      let total = 0;
+      for (let i = 0; i < count; i += 1) {
+        const step = 0.4 + random();
+        steps.push(step);
+        total += step;
+      }
+      const points: number[] = [];
+      let angle = random() * Math.PI * 2;
+      for (let i = 0; i < count; i += 1) {
+        points.push(x + Math.cos(angle) * radiusX, y + Math.sin(angle) * radiusY);
+        angle += (steps[i] / total) * Math.PI * 2;
+      }
+      return { kind: 'polygon', points };
+    }
+  }
+}