@flighthq/physics3d 0.4.0-edge.1908.751021c

package/src/debugGeometry.test.ts

@@ -0,0 +1,288 @@
+import {
+  createCollisionHeightfield3D,
+  createCollisionTriangleMesh3D,
+  registerBuiltInCollisionFaceQueries3D,
+  registerBuiltInCollisionSupports3D,
+} from '@flighthq/collision/contract';
+import type { CollisionBuiltInShape3D, Physics3DWorld, RigidBody3D } from '@flighthq/types/contract';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { buildPhysics3DContacts } from './contactIntake';
+import { createPhysics3DDebugGeometry, writePhysics3DDebugGeometry } from './debugGeometry';
+import { createPhysics3DBallAndSocketJoint } from './jointFactories';
+import { addPhysics3DJoint } from './jointRegistry';
+import { registerBuiltInPhysics3DJointSolvers } from './registerBuiltInPhysics3DJointSolvers';
+import {
+  addPhysics3DBody,
+  addPhysics3DCollider,
+  createPhysics3DCollider,
+  createPhysics3DWorld,
+  createRigidBody3D,
+} from './world';
+
+beforeEach(() => {
+  registerBuiltInCollisionSupports3D();
+  registerBuiltInCollisionFaceQueries3D();
+});
+
+function addBody(world: Physics3DWorld, local: CollisionBuiltInShape3D, y = 0): RigidBody3D {
+  const body = createRigidBody3D('dynamic');
+  body.y = y;
+  addPhysics3DBody(world, body);
+  addPhysics3DCollider(world, body, createPhysics3DCollider(local));
+  return body;
+}
+
+const unitBox: CollisionBuiltInShape3D = {
+  kind: 'aabb',
+  minX: -0.5,
+  minY: -0.5,
+  minZ: -0.5,
+  maxX: 0.5,
+  maxY: 0.5,
+  maxZ: 0.5,
+};
+
+function liveLines(out: ReturnType<typeof createPhysics3DDebugGeometry>) {
+  return out.lines.slice(0, out.lineCount);
+}
+
+function liveSpheres(out: ReturnType<typeof createPhysics3DDebugGeometry>) {
+  return out.spheres.slice(0, out.sphereCount);
+}
+
+describe('createPhysics3DDebugGeometry', () => {
+  it('starts empty', () => {
+    expect(createPhysics3DDebugGeometry()).toEqual({ lines: [], lineCount: 0, spheres: [], sphereCount: 0 });
+  });
+});
+
+describe('writePhysics3DDebugGeometry', () => {
+  it('draws explicit mesh triangles and heightfield grid edges', () => {
+    const world = createPhysics3DWorld();
+    const mesh = createRigidBody3D('static');
+    mesh.colliders.push(createPhysics3DCollider(createCollisionTriangleMesh3D([0, 0, 0, 1, 0, 0, 0, 0, 1], [0, 1, 2])));
+    addPhysics3DBody(world, mesh);
+    const heightfield = createRigidBody3D('static');
+    heightfield.colliders.push(createPhysics3DCollider(createCollisionHeightfield3D(2, 2, [0, 0, 0, 0])));
+    addPhysics3DBody(world, heightfield);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawColliders: true, drawCentersOfMass: false });
+
+    expect(liveLines(out).filter((line) => line.feature === 'collider')).toHaveLength(8);
+  });
+
+  it('draws a box as its twelve edges', () => {
+    const world = createPhysics3DWorld();
+    addBody(world, unitBox);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawColliders: true, drawCentersOfMass: false });
+
+    expect(liveLines(out).filter((line) => line.feature === 'collider')).toHaveLength(12);
+  });
+
+  it('gives every box edge unit length for a unit cube', () => {
+    // Twelve lines that are not all edges — a diagonal, a repeat — would still count twelve.
+    const world = createPhysics3DWorld();
+    addBody(world, unitBox);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false, drawContacts: false });
+
+    for (const line of liveLines(out)) {
+      expect(Math.hypot(line.x1 - line.x0, line.y1 - line.y0, line.z1 - line.z0)).toBeCloseTo(1, 9);
+    }
+  });
+
+  it('follows the body pose rather than drawing at the origin', () => {
+    const world = createPhysics3DWorld();
+    const body = addBody(world, unitBox);
+    const out = createPhysics3DDebugGeometry();
+
+    body.x = 100;
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    for (const line of liveLines(out)) expect(line.x0).toBeGreaterThan(99);
+  });
+
+  it('turns a spun box into edges that are no longer axis-aligned', () => {
+    const world = createPhysics3DWorld();
+    const body = addBody(world, unitBox);
+    body.orientationY = Math.sin(Math.PI / 8);
+    body.orientationW = Math.cos(Math.PI / 8);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    // An eighth turn about Y leaves no edge lying along a world axis in both x and z.
+    const axisAligned = liveLines(out).filter(
+      (line) => Math.abs(line.x1 - line.x0) < 1e-9 && Math.abs(line.z1 - line.z0) < 1e-9,
+    );
+    // Only the four vertical edges stay axis-aligned under a Y rotation.
+    expect(axisAligned).toHaveLength(4);
+  });
+
+  it('draws a sphere collider as one sphere', () => {
+    const world = createPhysics3DWorld();
+    addBody(world, { kind: 'sphere', x: 0, y: 0, z: 0, radius: 2 });
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    const spheres = liveSpheres(out).filter((sphere) => sphere.feature === 'collider');
+    expect(spheres).toHaveLength(1);
+    expect(spheres[0].radius).toBe(2);
+  });
+
+  it('draws a capsule as two caps joined by its axis', () => {
+    const world = createPhysics3DWorld();
+    addBody(world, { kind: 'capsule', x0: -2, y0: 0, z0: 0, x1: 2, y1: 0, z1: 0, radius: 0.5 });
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    expect(liveSpheres(out).filter((sphere) => sphere.feature === 'collider')).toHaveLength(2);
+    const axis = liveLines(out).filter((line) => line.feature === 'collider');
+    expect(axis).toHaveLength(1);
+    expect(Math.hypot(axis[0].x1 - axis[0].x0, axis[0].y1 - axis[0].y0, axis[0].z1 - axis[0].z0)).toBeCloseTo(4, 9);
+  });
+
+  it('draws a hull as the wireframe of its own triangulation', () => {
+    const world = createPhysics3DWorld();
+    addBody(world, { kind: 'convex', points: [0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1] });
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    // A tetrahedron triangulates to four faces, three edges each.
+    expect(liveLines(out).filter((line) => line.feature === 'collider')).toHaveLength(12);
+    expect(liveSpheres(out).filter((sphere) => sphere.feature === 'collider')).toHaveLength(0);
+  });
+
+  it('falls back to vertices for a DEGENERATE hull, which has no surface to wire', () => {
+    // Coplanar: there is no solid, so any edge drawn would bound a face the simulation does not have.
+    const world = createPhysics3DWorld();
+    addBody(world, { kind: 'convex', points: [0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0] });
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    expect(liveLines(out).filter((line) => line.feature === 'collider')).toHaveLength(0);
+    expect(liveSpheres(out).filter((sphere) => sphere.feature === 'collider')).toHaveLength(4);
+  });
+
+  it('draws a contact normal from each contact point', () => {
+    const world = createPhysics3DWorld();
+    const floor = createRigidBody3D('static');
+    floor.y = -1;
+    addPhysics3DBody(world, floor);
+    addPhysics3DCollider(
+      world,
+      floor,
+      createPhysics3DCollider({ kind: 'aabb', minX: -10, minY: -1, minZ: -10, maxX: 10, maxY: 1, maxZ: 10 }),
+    );
+    addBody(world, unitBox, -0.05);
+    buildPhysics3DContacts(world);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, {
+      drawColliders: false,
+      drawCentersOfMass: false,
+      contactNormalLength: 2,
+    });
+
+    const normals = liveLines(out).filter((line) => line.feature === 'contact-normal');
+    expect(normals).toHaveLength(world.contacts[0].pointCount);
+    expect(
+      Math.hypot(normals[0].x1 - normals[0].x0, normals[0].y1 - normals[0].y0, normals[0].z1 - normals[0].z0),
+    ).toBeCloseTo(2, 6);
+    expect(normals[0].bodyB).not.toBe(-1);
+  });
+
+  it('draws a joint as the gap between its two anchors', () => {
+    const world = createPhysics3DWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    const first = addBody(world, unitBox);
+    const second = addBody(world, unitBox);
+    second.x = 5;
+    addPhysics3DJoint(world, createPhysics3DBallAndSocketJoint({ bodyA: first.index, bodyB: second.index }));
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawColliders: false, drawCentersOfMass: false });
+
+    const joints = liveLines(out).filter((line) => line.feature === 'joint');
+    expect(joints).toHaveLength(1);
+    // The two anchors have drifted 5 apart, and the line shows that rather than collapsing to a point.
+    expect(
+      Math.hypot(joints[0].x1 - joints[0].x0, joints[0].y1 - joints[0].y0, joints[0].z1 - joints[0].z0),
+    ).toBeCloseTo(5, 9);
+  });
+
+  it('draws the centre of mass where the body actually balances', () => {
+    const world = createPhysics3DWorld();
+    const body = createRigidBody3D('dynamic');
+    addPhysics3DBody(world, body);
+    addPhysics3DCollider(
+      world,
+      body,
+      createPhysics3DCollider({ kind: 'aabb', minX: 1.5, minY: -0.5, minZ: -0.5, maxX: 2.5, maxY: 0.5, maxZ: 0.5 }),
+    );
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, { drawColliders: false });
+
+    const centers = liveSpheres(out).filter((sphere) => sphere.feature === 'center-of-mass');
+    expect(centers).toHaveLength(1);
+    // The collider sits a full 2 units along +x, so the centre of mass is there and not at the origin.
+    expect(centers[0].x).toBeCloseTo(2, 9);
+  });
+
+  it('honours each feature toggle independently', () => {
+    const world = createPhysics3DWorld();
+    addBody(world, unitBox);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out, {
+      drawColliders: false,
+      drawCentersOfMass: false,
+      drawContacts: false,
+      drawJoints: false,
+    });
+
+    expect(out.lineCount).toBe(0);
+    expect(out.sphereCount).toBe(0);
+  });
+
+  it('reuses its records, so a per-frame debug draw allocates nothing after the first', () => {
+    const world = createPhysics3DWorld();
+    addBody(world, unitBox);
+    const out = createPhysics3DDebugGeometry();
+
+    writePhysics3DDebugGeometry(world, out);
+    const line = out.lines[0];
+    const sphere = out.spheres[0];
+    const lineCapacity = out.lines.length;
+    writePhysics3DDebugGeometry(world, out);
+
+    expect(out.lines[0]).toBe(line);
+    expect(out.spheres[0]).toBe(sphere);
+    expect(out.lines.length).toBe(lineCapacity);
+  });
+
+  it('retains capacity above the live prefix when the scene shrinks', () => {
+    const world = createPhysics3DWorld();
+    const body = addBody(world, unitBox);
+    const out = createPhysics3DDebugGeometry();
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+    const capacity = out.lines.length;
+    expect(capacity).toBe(12);
+
+    body.colliders.length = 0;
+    writePhysics3DDebugGeometry(world, out, { drawCentersOfMass: false });
+
+    expect(out.lineCount).toBe(0);
+    expect(out.lines.length).toBe(capacity);
+  });
+});

package/src/enablePhysics3DGuards.test.ts

@@ -0,0 +1,206 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry, Physics3DWorld } from '@flighthq/types/contract';
+
+import { synchronizePhysics3DBroadphase } from './broadphase';
+import { arePhysics3DGuardsEnabled, disablePhysics3DGuards, enablePhysics3DGuards } from './enablePhysics3DGuards';
+import { createPhysics3DHingeJoint } from './jointFactories';
+import { addPhysics3DJoint } from './jointRegistry';
+import { registerBuiltInPhysics3DJointSolvers } from './registerBuiltInPhysics3DJointSolvers';
+import { stepPhysics3D } from './step';
+import {
+  addPhysics3DBody,
+  addPhysics3DCollider,
+  createPhysics3DCollider,
+  createPhysics3DWorld,
+  createRigidBody3D,
+} from './world';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+afterEach(() => {
+  disablePhysics3DGuards();
+});
+
+describe('arePhysics3DGuardsEnabled', () => {
+  it('reports the current module guard state', () => {
+    expect(arePhysics3DGuardsEnabled()).toBe(false);
+    enablePhysics3DGuards();
+    expect(arePhysics3DGuardsEnabled()).toBe(true);
+  });
+});
+
+describe('disablePhysics3DGuards', () => {
+  it('removes the seam so a declined step is silent again', () => {
+    enablePhysics3DGuards();
+    disablePhysics3DGuards();
+    const world = createTestWorld();
+    world.config.sequentialImpulse.positionIterations = -3;
+
+    const entries = captureLog(() => stepPhysics3D(world, 1 / 60));
+
+    expect(entries).toHaveLength(0);
+  });
+
+  it('removes the unresolved-joint seam', () => {
+    enablePhysics3DGuards();
+    disablePhysics3DGuards();
+    const world = createTestWorld();
+    addPhysics3DJoint(world, createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 }));
+
+    const entries = captureLog(() => stepPhysics3D(world, 1 / 60));
+
+    expect(entries).toHaveLength(0);
+  });
+
+  it('removes the spatial-indexing seam', () => {
+    enablePhysics3DGuards();
+    disablePhysics3DGuards();
+
+    const entries = captureLog(() => addPhysics3DBody(createPhysics3DWorld(), createOverflowBody()));
+
+    expect(entries).toHaveLength(0);
+  });
+});
+
+describe('enablePhysics3DGuards', () => {
+  it('says nothing while the world steps normally', () => {
+    enablePhysics3DGuards();
+
+    const entries = captureLog(() => stepPhysics3D(createTestWorld(), 1 / 60));
+
+    // A guard that fired on a healthy step would be worse than none: the message is supposed to mean the
+    // simulation has stopped advancing.
+    expect(entries).toHaveLength(0);
+  });
+
+  it('names every failing precondition at once, not only the first', () => {
+    enablePhysics3DGuards();
+    const world = createTestWorld();
+    world.gravityY = Number.NaN;
+    world.config.substeps = 0;
+
+    const entries = captureLog(() => stepPhysics3D(world, 0));
+
+    expect(entries).toHaveLength(1);
+    const failing = readFailing(entries[0]);
+    // The step's own condition short-circuits, so one fault per frame would make a caller repair a
+    // three-fault world across three frames, each fix revealing the next.
+    expect([...failing].sort()).toEqual(['gravityValid', 'substepsValid', 'timestepValid']);
+  });
+
+  it('logs once for a repeating fault and again when a different one joins it', () => {
+    enablePhysics3DGuards();
+    const world = createTestWorld();
+    world.config.sequentialImpulse.velocityIterations = -1;
+
+    const repeated = captureLog(() => {
+      for (let frame = 0; frame < 5; frame += 1) stepPhysics3D(world, 1 / 60);
+    });
+    expect(repeated).toHaveLength(1);
+
+    // Keyed on the failing SET rather than on the world, so a frame loop costs one message while a world
+    // that develops a SECOND fault still reports it instead of being swallowed by the first key.
+    const widened = captureLog(() => {
+      world.gravityZ = Number.NaN;
+      stepPhysics3D(world, 1 / 60);
+    });
+    expect(widened).toHaveLength(1);
+    expect(readFailing(widened[0])).toContain('gravityValid');
+  });
+
+  it('names invalid collider state before contact intake can consume it', () => {
+    enablePhysics3DGuards();
+    const world = createTestWorld();
+    const collider = createPhysics3DCollider({ kind: 'sphere', x: 0, y: 0, z: 0, radius: 1 });
+    addPhysics3DCollider(world, world.bodies[0], collider);
+    collider.material.restitution = Number.NaN;
+
+    const entries = captureLog(() => stepPhysics3D(world, 1 / 60));
+
+    expect(entries).toHaveLength(1);
+    expect(readFailing(entries[0])).toEqual(['colliderStateValid']);
+  });
+
+  it('names every joint the solve skips and distinguishes why', () => {
+    enablePhysics3DGuards();
+    const world = createTestWorld();
+    const unregistered = createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 });
+    unregistered.kind = 'guard.unregistered';
+    addPhysics3DJoint(world, unregistered);
+    registerBuiltInPhysics3DJointSolvers(world);
+    const invalidBodies = addPhysics3DJoint(world, createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 }));
+    invalidBodies.bodyB = 99;
+
+    const entries = captureLog(() => {
+      stepPhysics3D(world, 1 / 60);
+      stepPhysics3D(world, 1 / 60);
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(readJointIssues(entries[0])).toEqual([
+      { index: 0, kind: 'guard.unregistered', status: 'unregistered-kind' },
+      { index: 1, kind: 'Hinge', status: 'invalid-bodies' },
+    ]);
+  });
+
+  it('reports a body routed through spatial overflow once and stays silent for ordinary indexing', () => {
+    enablePhysics3DGuards();
+    const world = createPhysics3DWorld();
+
+    const entries = captureLog(() => {
+      const ordinary = createRigidBody3D('dynamic');
+      ordinary.colliders.push(createPhysics3DCollider({ kind: 'sphere', x: 0, y: 0, z: 0, radius: 0.5 }));
+      addPhysics3DBody(world, ordinary);
+      addPhysics3DBody(world, createOverflowBody());
+      addPhysics3DBody(world, createOverflowBody());
+      synchronizePhysics3DBroadphase(world);
+      synchronizePhysics3DBroadphase(world);
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      channel: 'physics3d',
+      data: { bodyIndices: [1], status: 'spatial-overflow' },
+    });
+  });
+});
+
+// `LogData` is deliberately `string | Record<string, unknown>`, so a structured entry's fields are only
+// reachable through a narrowing read rather than a property access.
+function readFailing(entry: Readonly<LogEntry>): readonly string[] {
+  const data = entry.data;
+  if (typeof data === 'string' || data === undefined) return [];
+  return (data.failing as readonly string[] | undefined) ?? [];
+}
+
+function readJointIssues(entry: Readonly<LogEntry>): readonly Record<string, unknown>[] {
+  const data = entry.data;
+  if (typeof data === 'string' || data === undefined) return [];
+  return (data.joints as readonly Record<string, unknown>[] | undefined) ?? [];
+}
+
+// Steppable as built: every fault in these tests is one the test introduces, so a case that expects
+// silence is asserting the guard's judgement rather than a world that happens to be fine.
+function createTestWorld(): Physics3DWorld {
+  const world = createPhysics3DWorld();
+  addPhysics3DBody(world, createRigidBody3D('dynamic'));
+  addPhysics3DBody(world, createRigidBody3D('dynamic'));
+  return world;
+}
+
+function createOverflowBody() {
+  const body = createRigidBody3D('static');
+  body.colliders.push(
+    createPhysics3DCollider({ kind: 'aabb', minX: -16, minY: -16, minZ: -16, maxX: 16, maxY: 16, maxZ: 16 }),
+  );
+  return body;
+}

package/src/explainPhysics3DCollision.test.ts

@@ -0,0 +1,78 @@
+import { registerBuiltInCollisionSupports3D } from '@flighthq/collision/contract';
+import { describe, expect, it } from 'vitest';
+
+import { explainPhysics3DCollision } from './explainPhysics3DCollision';
+import {
+  addPhysics3DBody,
+  addPhysics3DCollider,
+  createPhysics3DCollider,
+  createPhysics3DWorld,
+  createRigidBody3D,
+} from './world';
+
+// This file asserts the state of the collision support registry BEFORE anything registers, which is the
+// exact state a caller who forgot to register is in — and the state that presents as bodies falling
+// through floors with no error anywhere. That claim only holds in a process nobody else has touched, so
+// the file runs isolated; see `scripts/registryIsolatedTests.ts`. The registering tests come last on
+// purpose: registration is process-global and cannot be undone.
+
+function addSphereBody(world: ReturnType<typeof createPhysics3DWorld>, radius = 1): void {
+  const body = createRigidBody3D('dynamic');
+  addPhysics3DBody(world, body);
+  addPhysics3DCollider(world, body, createPhysics3DCollider({ kind: 'sphere', x: 0, y: 0, z: 0, radius }));
+}
+
+describe('explainPhysics3DCollision', () => {
+  it('names the kinds with no registered support', () => {
+    const world = createPhysics3DWorld();
+    addSphereBody(world);
+
+    const explanation = explainPhysics3DCollision(world);
+    expect(explanation.status).toBe('missing-support');
+    expect(explanation.unsupportedKinds).toEqual(['sphere']);
+  });
+
+  it('reports ready for an empty world, which cannot fail to detect anything', () => {
+    expect(explainPhysics3DCollision(createPhysics3DWorld())).toEqual({ unsupportedKinds: [], status: 'ready' });
+  });
+
+  it('deduplicates and sorts, so the value is stable however the bodies were inserted', () => {
+    const world = createPhysics3DWorld();
+    addSphereBody(world, 1);
+    const capsule = createRigidBody3D('dynamic');
+    addPhysics3DBody(world, capsule);
+    addPhysics3DCollider(
+      world,
+      capsule,
+      createPhysics3DCollider({ kind: 'capsule', x0: 0, y0: 0, z0: 0, x1: 0, y1: 1, z1: 0, radius: 1 }),
+    );
+    addSphereBody(world, 2);
+
+    expect(explainPhysics3DCollision(world).unsupportedKinds).toEqual(['capsule', 'sphere']);
+  });
+
+  it('reads the WORLD kind, which is what the narrow phase is actually handed', () => {
+    // An `aabb` local shape carries a `box` world shape, so a world of aabb colliders needs the BOX
+    // support registered. Asking about the local kind would report a world ready that is not.
+    const world = createPhysics3DWorld();
+    const body = createRigidBody3D('dynamic');
+    addPhysics3DBody(world, body);
+    addPhysics3DCollider(
+      world,
+      body,
+      createPhysics3DCollider({ kind: 'aabb', minX: -1, minY: -1, minZ: -1, maxX: 1, maxY: 1, maxZ: 1 }),
+    );
+
+    expect(explainPhysics3DCollision(world).unsupportedKinds).toEqual(['box']);
+  });
+
+  it('reports ready once the built-in supports are registered', () => {
+    const world = createPhysics3DWorld();
+    addSphereBody(world);
+    expect(explainPhysics3DCollision(world).status).toBe('missing-support');
+
+    registerBuiltInCollisionSupports3D();
+
+    expect(explainPhysics3DCollision(world)).toEqual({ unsupportedKinds: [], status: 'ready' });
+  });
+});

package/src/explainPhysics3DJoints.test.ts

@@ -0,0 +1,101 @@
+import type { Physics3DJointSolver, Physics3DWorld } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { explainPhysics3DJoints } from './explainPhysics3DJoints';
+import { createPhysics3DBallAndSocketJoint, createPhysics3DHingeJoint } from './jointFactories';
+import { addPhysics3DJoint, registerPhysics3DJointSolver } from './jointRegistry';
+import { Physics3DBallAndSocketJointKind } from './joints';
+import { registerBuiltInPhysics3DJointSolvers } from './registerBuiltInPhysics3DJointSolvers';
+import { addPhysics3DBody, createPhysics3DWorld, createRigidBody3D } from './world';
+
+describe('explainPhysics3DJoints', () => {
+  it('reports nothing for a world with no joints', () => {
+    expect(explainPhysics3DJoints(createTestWorld())).toEqual([]);
+  });
+
+  it('calls a fully wired joint solvable', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    addPhysics3DJoint(world, createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 }));
+
+    const [explanation] = explainPhysics3DJoints(world);
+
+    expect(explanation.status).toBe('solvable');
+    expect(explanation.hasSolver).toBe(true);
+    expect(explanation.bodiesResolvable).toBe(true);
+    expect(explanation.index).toBe(0);
+    expect(explanation.kind).toBe('Hinge');
+  });
+
+  it('separates an unregistered kind from a broken one', () => {
+    const world = createTestWorld();
+    addPhysics3DJoint(world, createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 }));
+
+    const [explanation] = explainPhysics3DJoints(world);
+
+    // Not a fault: a scene deserialized ahead of the code that solves it is explicitly supported, and the
+    // joint is meant to sit inert until someone registers its solver.
+    expect(explanation.status).toBe('unregistered-kind');
+    expect(explanation.hasSolver).toBe(false);
+  });
+
+  it('reports a joint outliving one of its bodies', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    const joint = addPhysics3DJoint(world, createPhysics3DBallAndSocketJoint({ bodyA: 0, bodyB: 1 }));
+    // Removing a body drops the joints that named it, so this is the state a world reconstructed by a
+    // format layer reaches rather than one the lifecycle produces: an endpoint that resolves to nothing.
+    joint.bodyB = 99;
+
+    const [explanation] = explainPhysics3DJoints(world);
+
+    expect(explanation.status).toBe('invalid-bodies');
+    expect(explanation.hasSolver).toBe(true);
+    expect(explanation.bodiesResolvable).toBe(false);
+  });
+
+  it('does not fault a one-body kind for its unused first end', () => {
+    const world = createTestWorld();
+    const oneBody: Physics3DJointSolver = { prepare(): void {}, solve(): void {}, usesBodyA: false };
+    registerPhysics3DJointSolver(world, Physics3DBallAndSocketJointKind, oneBody);
+    const joint = addPhysics3DJoint(world, createPhysics3DBallAndSocketJoint({ bodyA: 0, bodyB: 1 }));
+    joint.bodyA = 404;
+
+    const [explanation] = explainPhysics3DJoints(world);
+
+    // The solver never reads bodyA, so a placeholder index there is not a fault. Asking the kind rather
+    // than assuming two endpoints is what keeps this honest for a kind the package does not own.
+    expect(explanation.status).toBe('solvable');
+  });
+
+  it('reports one entry per joint, indexed back into the world list', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    addPhysics3DJoint(world, createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 }));
+    addPhysics3DJoint(world, createPhysics3DBallAndSocketJoint({ bodyA: 0, bodyB: 1 }));
+
+    const explanations = explainPhysics3DJoints(world);
+
+    expect(explanations.map((entry) => entry.index)).toEqual([0, 1]);
+    expect(world.joints[explanations[1].index].kind).toBe(explanations[1].kind);
+  });
+
+  it('changes nothing it looks at', () => {
+    const world = createTestWorld();
+    registerBuiltInPhysics3DJointSolvers(world);
+    const joint = addPhysics3DJoint(world, createPhysics3DHingeJoint({ bodyA: 0, bodyB: 1 }));
+    joint.impulse0 = 7;
+
+    explainPhysics3DJoints(world);
+
+    expect(joint.impulse0).toBe(7);
+    expect(world.joints.length).toBe(1);
+  });
+});
+
+function createTestWorld(): Physics3DWorld {
+  const world = createPhysics3DWorld();
+  addPhysics3DBody(world, createRigidBody3D('dynamic'));
+  addPhysics3DBody(world, createRigidBody3D('dynamic'));
+  return world;
+}