@flighthq/physics2d 0.3.0-next.1021.f5f1ee0

package/src/massProperties.test.ts

@@ -0,0 +1,185 @@
+import type { CollisionShape, Physics2DCollider, Physics2DMassData, RigidBody2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { computePhysics2DColliderMassData, updateRigidBody2DMassData } from './massProperties';
+
+function collider(local: CollisionShape, density = 1): Physics2DCollider {
+  return {
+    local,
+    world: local,
+    material: { density, friction: 0.2, restitution: 0 },
+    sensor: false,
+  };
+}
+
+function body(colliders: Physics2DCollider[], type: RigidBody2D['type'] = 'dynamic'): RigidBody2D {
+  return {
+    index: 0,
+    type,
+    x: 0,
+    y: 0,
+    angle: 0,
+    velocityX: 0,
+    velocityY: 0,
+    angularVelocity: 0,
+    forceX: 0,
+    forceY: 0,
+    torque: 0,
+    mass: 0,
+    inverseMass: 0,
+    inertia: 0,
+    inverseInertia: 0,
+    centerX: 0,
+    centerY: 0,
+    linearDamping: 0,
+    angularDamping: 0,
+    gravityScale: 1,
+    colliders,
+  };
+}
+
+function massData(): Physics2DMassData {
+  return { mass: 0, inertia: 0, centerX: 0, centerY: 0 };
+}
+
+describe('computePhysics2DColliderMassData', () => {
+  it('derives a disc from its area and half its mass-radius-squared', () => {
+    const out = massData();
+    computePhysics2DColliderMassData(collider({ kind: 'circle', x: 3, y: -2, radius: 2 }, 4), out);
+    expect(out.mass).toBeCloseTo(Math.PI * 4 * 4);
+    expect(out.inertia).toBeCloseTo(0.5 * Math.PI * 4 * 4 * 4);
+    expect(out.centerX).toBe(3);
+    expect(out.centerY).toBe(-2);
+  });
+
+  it('derives a box from its extents and centres it on the box', () => {
+    const out = massData();
+    computePhysics2DColliderMassData(collider({ kind: 'aabb', minX: 0, minY: 0, maxX: 4, maxY: 2 }, 3), out);
+    expect(out.mass).toBeCloseTo(24);
+    expect(out.inertia).toBeCloseTo((24 * (16 + 4)) / 12);
+    expect(out.centerX).toBeCloseTo(2);
+    expect(out.centerY).toBeCloseTo(1);
+  });
+
+  it('gives an oriented box the same inertia as the axis-aligned box of equal extents', () => {
+    // Rotation about z does not change a rectangle's second moment about its own centre. Pinned
+    // because assuming otherwise is a natural mistake, and it would make a tilted crate swing wrong.
+    const upright = massData();
+    const tilted = massData();
+    computePhysics2DColliderMassData(collider({ kind: 'aabb', minX: -2, minY: -1, maxX: 2, maxY: 1 }), upright);
+    computePhysics2DColliderMassData(collider({ kind: 'obb', x: 0, y: 0, halfW: 2, halfH: 1, rotation: 0.7 }), tilted);
+    expect(tilted.mass).toBeCloseTo(upright.mass);
+    expect(tilted.inertia).toBeCloseTo(upright.inertia);
+  });
+
+  it('agrees with the box formula when the same square is given as a polygon', () => {
+    // Cross-validation between two independent derivations: the closed-form rectangle expression and
+    // the general polygon accumulation. Agreement is evidence neither is quietly wrong.
+    const asBox = massData();
+    const asPolygon = massData();
+    computePhysics2DColliderMassData(
+      collider({ kind: 'aabb', minX: -1.5, minY: -0.5, maxX: 1.5, maxY: 0.5 }, 2),
+      asBox,
+    );
+    computePhysics2DColliderMassData(
+      collider({ kind: 'polygon', points: [-1.5, -0.5, 1.5, -0.5, 1.5, 0.5, -1.5, 0.5] }, 2),
+      asPolygon,
+    );
+    expect(asPolygon.mass).toBeCloseTo(asBox.mass);
+    expect(asPolygon.inertia).toBeCloseTo(asBox.inertia);
+    expect(asPolygon.centerX).toBeCloseTo(asBox.centerX);
+    expect(asPolygon.centerY).toBeCloseTo(asBox.centerY);
+  });
+
+  it('gives a polygon the same mass whichever winding it is given in', () => {
+    const counterClockwise = massData();
+    const clockwise = massData();
+    computePhysics2DColliderMassData(collider({ kind: 'polygon', points: [0, 0, 4, 0, 4, 2, 0, 2] }), counterClockwise);
+    computePhysics2DColliderMassData(collider({ kind: 'polygon', points: [0, 0, 0, 2, 4, 2, 4, 0] }), clockwise);
+    expect(clockwise.mass).toBeCloseTo(counterClockwise.mass);
+    expect(clockwise.inertia).toBeCloseTo(counterClockwise.inertia);
+    expect(clockwise.centerX).toBeCloseTo(counterClockwise.centerX);
+    expect(clockwise.centerY).toBeCloseTo(counterClockwise.centerY);
+  });
+
+  it('offsets a polygon centroid without changing its inertia about that centroid', () => {
+    // The parallel-axis subtraction is the step most easily got wrong, and the wrongness is invisible
+    // in a shape centred on the origin. Translating the same square must move the centroid and leave
+    // the inertia untouched.
+    const atOrigin = massData();
+    const shifted = massData();
+    computePhysics2DColliderMassData(collider({ kind: 'polygon', points: [-1, -1, 1, -1, 1, 1, -1, 1] }), atOrigin);
+    computePhysics2DColliderMassData(collider({ kind: 'polygon', points: [9, 19, 11, 19, 11, 21, 9, 21] }), shifted);
+    expect(shifted.centerX).toBeCloseTo(10);
+    expect(shifted.centerY).toBeCloseTo(20);
+    expect(shifted.inertia).toBeCloseTo(atOrigin.inertia);
+  });
+
+  it('gives area-less and degenerate shapes no mass', () => {
+    const out = massData();
+    computePhysics2DColliderMassData(collider({ kind: 'segment', x0: 0, y0: 0, x1: 5, y1: 5 }), out);
+    expect(out.mass).toBe(0);
+    computePhysics2DColliderMassData(collider({ kind: 'point', x: 1, y: 1 }), out);
+    expect(out.mass).toBe(0);
+    // Collinear vertices enclose no area; dividing the centroid by it would be a NaN body.
+    computePhysics2DColliderMassData(collider({ kind: 'polygon', points: [0, 0, 1, 1, 2, 2] }), out);
+    expect(out.mass).toBe(0);
+    expect(Number.isNaN(out.centerX)).toBe(false);
+  });
+});
+
+describe('updateRigidBody2DMassData', () => {
+  it('combines two colliders into one centre of mass and shifts their inertia onto it', () => {
+    const left = collider({ kind: 'aabb', minX: -3, minY: -1, maxX: -1, maxY: 1 });
+    const right = collider({ kind: 'aabb', minX: 1, minY: -1, maxX: 3, maxY: 1 });
+    const target = body([left, right]);
+    updateRigidBody2DMassData(target);
+
+    expect(target.mass).toBeCloseTo(8);
+    expect(target.centerX).toBeCloseTo(0);
+    expect(target.centerY).toBeCloseTo(0);
+    // Each 2x2 box contributes its own inertia plus mass times the square of its 2-unit offset.
+    const own = (4 * (4 + 4)) / 12;
+    expect(target.inertia).toBeCloseTo(2 * (own + 4 * 4));
+    expect(target.inverseMass).toBeCloseTo(1 / 8);
+  });
+
+  it('gives a static body zero inverse mass and inertia while keeping its centre', () => {
+    // Zero inverse mass is the arithmetic that makes a static body immovable without a branch in the
+    // solver, so it must hold even though the shape has real area.
+    const ground = body([collider({ kind: 'aabb', minX: -5, minY: -1, maxX: 5, maxY: 0 })], 'static');
+    updateRigidBody2DMassData(ground);
+    expect(ground.inverseMass).toBe(0);
+    expect(ground.inverseInertia).toBe(0);
+    expect(ground.mass).toBe(0);
+    expect(ground.centerX).toBeCloseTo(0);
+    expect(ground.centerY).toBeCloseTo(-0.5);
+  });
+
+  it('gives a kinematic body zero inverse mass even though it moves', () => {
+    const platform = body([collider({ kind: 'aabb', minX: 0, minY: 0, maxX: 4, maxY: 1 })], 'kinematic');
+    updateRigidBody2DMassData(platform);
+    expect(platform.inverseMass).toBe(0);
+    expect(platform.inverseInertia).toBe(0);
+  });
+
+  it('leaves a dynamic body with no area finite rather than dividing by its zero mass', () => {
+    // A body whose only collider is a sensor point has no mass. Inverting it would seed NaN into the
+    // velocity of everything it later touches, which is unrecoverable rather than merely wrong.
+    const ghost = body([collider({ kind: 'point', x: 0, y: 0 })]);
+    updateRigidBody2DMassData(ghost);
+    expect(ghost.inverseMass).toBe(0);
+    expect(ghost.inverseInertia).toBe(0);
+    expect(Number.isFinite(ghost.centerX)).toBe(true);
+  });
+
+  it('scales mass with density but leaves the centre of mass where it was', () => {
+    const light = body([collider({ kind: 'aabb', minX: 0, minY: 0, maxX: 2, maxY: 2 }, 1)]);
+    const heavy = body([collider({ kind: 'aabb', minX: 0, minY: 0, maxX: 2, maxY: 2 }, 7)]);
+    updateRigidBody2DMassData(light);
+    updateRigidBody2DMassData(heavy);
+    expect(heavy.mass).toBeCloseTo(light.mass * 7);
+    expect(heavy.inertia).toBeCloseTo(light.inertia * 7);
+    expect(heavy.centerX).toBeCloseTo(light.centerX);
+  });
+});

package/src/solver.test.ts

@@ -0,0 +1,167 @@
+import type { RigidBody2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import {
+  applyPhysics2DImpulse,
+  relativeNormalVelocity,
+  solvePhysics2DContacts,
+  warmStartPhysics2DContacts,
+} from './solver';
+import { stepPhysics2D } from './step';
+import { addPhysics2DBody, createPhysics2DCollider, createPhysics2DWorld, createRigidBody2D } from './world';
+
+const STONE = { density: 1, friction: 0.3, restitution: 0 };
+
+function body(type: RigidBody2D['type'], x: number, y: number): RigidBody2D {
+  const made = createRigidBody2D(type, x, y);
+  made.colliders.push(createPhysics2DCollider({ kind: 'aabb', minX: -0.5, minY: -0.5, maxX: 0.5, maxY: 0.5 }, STONE));
+  return made;
+}
+
+function restingWorld() {
+  const world = createPhysics2DWorld();
+  const floor = createRigidBody2D('static', 0, 0);
+  floor.colliders.push(createPhysics2DCollider({ kind: 'aabb', minX: -50, minY: -1, maxX: 50, maxY: 0 }, STONE));
+  addPhysics2DBody(world, floor);
+  const crate = addPhysics2DBody(world, body('dynamic', 0, 0.499));
+  return { world, crate };
+}
+
+describe('applyPhysics2DImpulse', () => {
+  it('pushes A along the impulse and B against it, matching the manifold normal direction', () => {
+    // The normal separates A out of B, so a positive impulse must move A along it. Reversed, the solver
+    // drives bodies together and a resting box settles below the floor rather than on it.
+    const world = createPhysics2DWorld();
+    const a = addPhysics2DBody(world, body('dynamic', 0, 0));
+    const b = addPhysics2DBody(world, body('dynamic', 0, 1));
+    applyPhysics2DImpulse(a, b, 0, 0, 0, 0, 0, 1);
+    expect(a.velocityY).toBeGreaterThan(0);
+    expect(b.velocityY).toBeLessThan(0);
+  });
+
+  it('spins a body when the impulse acts off its centre of mass', () => {
+    const world = createPhysics2DWorld();
+    const a = addPhysics2DBody(world, body('dynamic', 0, 0));
+    const b = addPhysics2DBody(world, body('dynamic', 0, 1));
+    applyPhysics2DImpulse(a, b, 0.5, 0, 0, 0, 0, 1);
+    expect(a.angularVelocity).not.toBe(0);
+  });
+
+  it('leaves a static body untouched through its zero inverse mass, with no branch', () => {
+    const world = createPhysics2DWorld();
+    const floor = addPhysics2DBody(world, body('static', 0, 0));
+    const crate = addPhysics2DBody(world, body('dynamic', 0, 1));
+    applyPhysics2DImpulse(floor, crate, 0.3, 0.2, 0, 0, 5, 7);
+    expect(floor.velocityX).toBe(0);
+    expect(floor.velocityY).toBe(0);
+    expect(floor.angularVelocity).toBe(0);
+  });
+});
+
+describe('relativeNormalVelocity', () => {
+  const point = {
+    x: 0,
+    y: 0,
+    depth: 0,
+    featureId: 0,
+    rAX: 0,
+    rAY: 0,
+    rBX: 0,
+    rBY: 0,
+    normalImpulse: 0,
+    tangentImpulse: 0,
+    normalMass: 0,
+    tangentMass: 0,
+    bias: 0,
+  };
+
+  it('is negative while the pair is closing along the separating normal', () => {
+    const world = createPhysics2DWorld();
+    const a = addPhysics2DBody(world, body('dynamic', 0, 0));
+    const b = addPhysics2DBody(world, body('dynamic', 0, 1));
+    b.velocityY = -1; // B falling toward A
+    expect(relativeNormalVelocity(a, b, point, 0, 1)).toBeGreaterThan(0);
+    b.velocityY = 1; // B moving away
+    expect(relativeNormalVelocity(a, b, point, 0, 1)).toBeLessThan(0);
+  });
+
+  it('includes the angular contribution at the lever arm', () => {
+    const world = createPhysics2DWorld();
+    const a = addPhysics2DBody(world, body('dynamic', 0, 0));
+    const b = addPhysics2DBody(world, body('dynamic', 0, 1));
+    const spinning = { ...point, rAX: 1, rAY: 0 };
+    a.angularVelocity = 2;
+    expect(relativeNormalVelocity(a, b, spinning, 0, 1)).toBeCloseTo(2);
+  });
+});
+
+describe('solvePhysics2DContacts', () => {
+  it('removes the closing velocity at a resting contact', () => {
+    const { world, crate } = restingWorld();
+    crate.velocityY = -5;
+    stepPhysics2D(world, 1 / 60);
+    expect(crate.velocityY).toBeGreaterThan(-1);
+  });
+
+  it('accumulates a non-negative normal impulse rather than pulling the pair together', () => {
+    // The clamp is on the ACCUMULATED impulse, not the increment: a contact may never pull.
+    const { world } = restingWorld();
+    for (let i = 0; i < 30; i++) stepPhysics2D(world, 1 / 60);
+    for (const contact of world.contacts) {
+      for (let i = 0; i < contact.pointCount; i++) {
+        expect(contact.points[i].normalImpulse).toBeGreaterThanOrEqual(0);
+      }
+    }
+  });
+
+  it('bounds friction by the Coulomb limit against the normal impulse', () => {
+    const { world, crate } = restingWorld();
+    crate.velocityX = 4;
+    for (let i = 0; i < 20; i++) stepPhysics2D(world, 1 / 60);
+    for (const contact of world.contacts) {
+      for (let i = 0; i < contact.pointCount; i++) {
+        const point = contact.points[i];
+        expect(Math.abs(point.tangentImpulse)).toBeLessThanOrEqual(contact.friction * point.normalImpulse + 1e-9);
+      }
+    }
+  });
+
+  it('slows a sliding box through friction instead of letting it glide forever', () => {
+    const { world, crate } = restingWorld();
+    crate.velocityX = 4;
+    for (let i = 0; i < 60; i++) stepPhysics2D(world, 1 / 60);
+    expect(crate.velocityX).toBeLessThan(4);
+    expect(crate.velocityX).toBeGreaterThan(0);
+  });
+
+  it('does nothing for a world with no contacts', () => {
+    const world = createPhysics2DWorld();
+    expect(() => solvePhysics2DContacts(world)).not.toThrow();
+  });
+});
+
+describe('warmStartPhysics2DContacts', () => {
+  it('reapplies the cached impulse, leaving a converged resting contact deeper than a cold start', () => {
+    // The measurable effect of warm starting: a settled stack keeps its impulses and stays put, where a
+    // cold-started one gives them up each step and sinks into its own slop.
+    const warm = createPhysics2DWorld();
+    const cold = createPhysics2DWorld();
+    cold.config.warmStarting = false;
+    for (const world of [warm, cold]) {
+      const floor = createRigidBody2D('static', 0, 0);
+      floor.colliders.push(createPhysics2DCollider({ kind: 'aabb', minX: -50, minY: -1, maxX: 50, maxY: 0 }, STONE));
+      addPhysics2DBody(world, floor);
+      addPhysics2DBody(world, body('dynamic', 0, 0.5));
+      addPhysics2DBody(world, body('dynamic', 0, 1.5));
+      addPhysics2DBody(world, body('dynamic', 0, 2.5));
+      for (let i = 0; i < 120; i++) stepPhysics2D(world, 1 / 60);
+    }
+    const warmTop = warm.bodies[3].y;
+    const coldTop = cold.bodies[3].y;
+    expect(warmTop).toBeGreaterThanOrEqual(coldTop - 1e-9);
+  });
+
+  it('does nothing for a world with no contacts', () => {
+    expect(() => warmStartPhysics2DContacts(createPhysics2DWorld())).not.toThrow();
+  });
+});

package/src/step.test.ts

@@ -0,0 +1,236 @@
+import { createUniformGridSpatialBackend } from '@flighthq/spatial/contract';
+import type { Physics2DWorld, RigidBody2D, SpatialIndexBackend, SpatialPair } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { stepPhysics2D } from './step';
+import { addPhysics2DBody, createPhysics2DCollider, createPhysics2DWorld, createRigidBody2D } from './world';
+
+const STONE = { density: 1, friction: 0.3, restitution: 0 };
+
+function ground(world: Physics2DWorld): RigidBody2D {
+  const body = createRigidBody2D('static', 0, 0);
+  body.colliders.push(createPhysics2DCollider({ kind: 'aabb', minX: -50, minY: -1, maxX: 50, maxY: 0 }, STONE));
+  return addPhysics2DBody(world, body);
+}
+
+function box(world: Physics2DWorld, x: number, y: number, half = 0.5): RigidBody2D {
+  const body = createRigidBody2D('dynamic', x, y);
+  body.colliders.push(
+    createPhysics2DCollider({ kind: 'aabb', minX: -half, minY: -half, maxX: half, maxY: half }, STONE),
+  );
+  return addPhysics2DBody(world, body);
+}
+
+// A hash of every body's full state, which is what a determinism claim has to be made against — comparing
+// only positions would miss a divergence that has entered the velocities and not yet moved anything.
+function traceWorld(world: Readonly<Physics2DWorld>): string {
+  return world.bodies
+    .slice()
+    .sort((left, right) => left.index - right.index)
+    .map((b) => [b.index, b.x, b.y, b.angle, b.velocityX, b.velocityY, b.angularVelocity].join(':'))
+    .join('|');
+}
+
+// A broadphase that returns its pairs in reverse order, and one that swaps each pair's two ids. Both
+// wrap the real grid, so the candidate SET is identical and only its presentation differs — which is
+// what makes them isolate ordering rather than change the simulation.
+function createReversedPairBackend(): SpatialIndexBackend {
+  const inner = createUniformGridSpatialBackend(1);
+  return {
+    ...inner,
+    querySpatialPairs(out: SpatialPair[]): void {
+      inner.querySpatialPairs(out);
+      out.reverse();
+    },
+  };
+}
+
+function createSwappedPairBackend(): SpatialIndexBackend {
+  const inner = createUniformGridSpatialBackend(1);
+  return {
+    ...inner,
+    querySpatialPairs(out: SpatialPair[]): void {
+      inner.querySpatialPairs(out);
+      for (const pair of out) {
+        const a = pair.a;
+        pair.a = pair.b;
+        pair.b = a;
+      }
+    },
+  };
+}
+
+function runSteps(world: Physics2DWorld, count: number): void {
+  for (let i = 0; i < count; i++) stepPhysics2D(world, 1 / 60);
+}
+
+describe('stepPhysics2D', () => {
+  it('rests a box on the ground instead of sinking through it', () => {
+    const world = createPhysics2DWorld();
+    ground(world);
+    const crate = box(world, 0, 2);
+    runSteps(world, 180);
+
+    // Half-extent 0.5 above a ground surface at y=0: the resting centre is y=0.5, less the solver's
+    // deliberate penetration slop.
+    expect(crate.y).toBeGreaterThan(0.48);
+    expect(crate.y).toBeLessThan(0.52);
+    expect(Math.abs(crate.velocityY)).toBeLessThan(0.05);
+  });
+
+  it('keeps a stack standing rather than letting the lower boxes be compressed through each other', () => {
+    // The case warm starting exists for. Without it the solver restarts from zero impulse every step, so
+    // the bottom box never converges against the weight above it and the stack visibly sinks.
+    const world = createPhysics2DWorld();
+    ground(world);
+    const bottom = box(world, 0, 0.5);
+    const middle = box(world, 0, 1.5);
+    const top = box(world, 0, 2.5);
+    runSteps(world, 240);
+
+    expect(bottom.y).toBeGreaterThan(0.45);
+    expect(middle.y).toBeGreaterThan(1.4);
+    expect(top.y).toBeGreaterThan(2.35);
+    expect(middle.y - bottom.y).toBeGreaterThan(0.9);
+    expect(top.y - middle.y).toBeGreaterThan(0.9);
+  });
+
+  it('produces a bitwise-identical trace for the same scene stepped twice', () => {
+    // The golden-trace harness. Determinism for a fixed engine and input order is exact, not approximate:
+    // every operation on this path is IEEE-754 exact (+ - * / and sqrt), so anything short of bitwise
+    // equality is a real divergence rather than accumulated noise.
+    const first = createPhysics2DWorld();
+    ground(first);
+    box(first, 0.1, 2);
+    box(first, -0.3, 3.2);
+    runSteps(first, 120);
+
+    const second = createPhysics2DWorld();
+    ground(second);
+    box(second, 0.1, 2);
+    box(second, -0.3, 3.2);
+    runSteps(second, 120);
+
+    expect(traceWorld(second)).toBe(traceWorld(first));
+  });
+
+  it('produces the same trace when the broadphase reports its pairs in the opposite order', () => {
+    // ORDER-INDEPENDENCE, OBLIGATION 2 — the contact LIST sort.
+    //
+    // The harness injects a broadphase that reverses its pair list, leaving the bodies and their indices
+    // untouched. That isolates the variable that matters: `querySpatialPairs` walks a Map of Sets, so its
+    // order follows insertion and movement history, and a sequential-impulse solver applies each impulse
+    // against the velocities the previous ones left. Without the canonical sort the answer would depend
+    // on the broadphase's history.
+    //
+    // Note what this does NOT test, and what an insertion-order shuffle would wrongly claim: reordering
+    // INSERTION changes the body indices, hence the canonical solve order, hence — legitimately — the
+    // result. Canonical ordering buys DETERMINISM (same input, same output), not invariance to how the
+    // scene was built. A harness asserting the latter asserts something false about Gauss-Seidel.
+    const plain = createPhysics2DWorld();
+    ground(plain);
+    const plainLeft = box(plain, -0.9, 0.5);
+    const plainRight = box(plain, 0.9, 0.5);
+    const plainTop = box(plain, 0, 1.6);
+
+    const reversed = createPhysics2DWorld(0, -9.81, createReversedPairBackend());
+    ground(reversed);
+    const reversedLeft = box(reversed, -0.9, 0.5);
+    const reversedRight = box(reversed, 0.9, 0.5);
+    const reversedTop = box(reversed, 0, 1.6);
+
+    runSteps(plain, 90);
+    runSteps(reversed, 90);
+
+    expect(traceWorld(reversed)).toBe(traceWorld(plain));
+    expect(reversedLeft.y).toBe(plainLeft.y);
+    expect(reversedRight.y).toBe(plainRight.y);
+    expect(reversedTop.y).toBe(plainTop.y);
+  });
+
+  it('orders every contact pair by body index however the broadphase hands it over', () => {
+    // ORDER-INDEPENDENCE, OBLIGATION 1 — the per-pair BODY sort, which the harness above cannot see.
+    // Reversing the pair LIST does not change which body of a pair reaches the narrow phase first; that
+    // follows the pair's own field order. This backend swaps `a` and `b` within every pair, which is the
+    // only thing that exercises it. Unordered, collision would resolve contact points on the opposite
+    // surface and renumber their feature ids, silently discarding the warm-start cache every step.
+    const swapped = createPhysics2DWorld(0, -9.81, createSwappedPairBackend());
+    ground(swapped);
+    const crate = box(swapped, 0.2, 1.4);
+    runSteps(swapped, 120);
+
+    for (const contact of swapped.contacts) expect(contact.bodyA).toBeLessThan(contact.bodyB);
+
+    const plain = createPhysics2DWorld();
+    ground(plain);
+    const plainCrate = box(plain, 0.2, 1.4);
+    runSteps(plain, 120);
+
+    expect(crate.y).toBe(plainCrate.y);
+    expect(crate.x).toBe(plainCrate.x);
+    expect(crate.angle).toBe(plainCrate.angle);
+  });
+
+  it('keeps the contact list in a canonical order after a step', () => {
+    const world = createPhysics2DWorld();
+    ground(world);
+    box(world, -0.9, 0.5);
+    box(world, 0.9, 0.5);
+    box(world, 0, 1.6);
+    runSteps(world, 60);
+
+    expect(world.contacts.length).toBeGreaterThan(1);
+    for (let i = 1; i < world.contacts.length; i++) {
+      const previous = world.contacts[i - 1];
+      const current = world.contacts[i];
+      const ordered =
+        previous.bodyA < current.bodyA ||
+        (previous.bodyA === current.bodyA &&
+          (previous.bodyB < current.bodyB ||
+            (previous.bodyB === current.bodyB && previous.colliderA <= current.colliderA)));
+      expect(ordered).toBe(true);
+    }
+  });
+
+  it('tips a box that overhangs a ledge instead of sliding off level', () => {
+    // The proof that contact points carry torque. With only a minimum-translation vector and no point,
+    // the lever arm is zero, the angular term vanishes, and an overhanging box slides off perfectly
+    // level — which is what the whole contact-manifold lane exists to prevent.
+    const world = createPhysics2DWorld();
+    const ledge = createRigidBody2D('static', 0, 0);
+    ledge.colliders.push(createPhysics2DCollider({ kind: 'aabb', minX: -5, minY: -1, maxX: 0, maxY: 0 }, STONE));
+    addPhysics2DBody(world, ledge);
+    // The centre of mass must be BEYOND the support edge at x=0 for there to be a tipping moment at
+    // all; a box whose centre still sits over the ledge is supported and correctly stays level.
+    const crate = box(world, 0.2, 0.5);
+    runSteps(world, 120);
+
+    expect(Math.abs(crate.angle)).toBeGreaterThan(0.05);
+  });
+
+  it('leaves a sensor collider overlapping without pushing anything out of it', () => {
+    const world = createPhysics2DWorld();
+    const trigger = createRigidBody2D('static', 0, 0);
+    trigger.colliders.push(
+      createPhysics2DCollider({ kind: 'aabb', minX: -2, minY: -2, maxX: 2, maxY: 2 }, STONE, true),
+    );
+    addPhysics2DBody(world, trigger);
+    const crate = box(world, 0, 0);
+    runSteps(world, 30);
+
+    expect(world.contacts.some((contact) => contact.sensor)).toBe(true);
+    // Gravity keeps pulling it: a sensor reports the overlap and applies no impulse.
+    expect(crate.velocityY).toBeLessThan(-0.1);
+  });
+
+  it('ignores a non-positive timestep rather than integrating backwards', () => {
+    const world = createPhysics2DWorld();
+    ground(world);
+    const crate = box(world, 0, 2);
+    const before = traceWorld(world);
+    stepPhysics2D(world, 0);
+    stepPhysics2D(world, -1 / 60);
+    expect(traceWorld(world)).toBe(before);
+    expect(crate.y).toBe(2);
+  });
+});