@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/qa/gates.ts

@@ -0,0 +1,126 @@
+// The QA gate: checks a compiled asset must pass before it ships. A failing gate is a build
+// error (exit 1), not a warning — an agent iterates until it prints PASS.
+
+import {
+  type Bounds,
+  boundsOf,
+  type CompiledAsset,
+  notImplemented,
+  toWorld,
+  triangleCount,
+  worldTransforms,
+} from '../core/index.ts';
+import { runChecks } from './checks.ts';
+import { clashes } from './clash.ts';
+import { floatingParts } from './floating.ts';
+import { measures } from './measures.ts';
+import { hiddenParts } from './occlusion.ts';
+import { nonFinite, normalsMatchWinding, vertexColors } from './sanity.ts';
+import type { Finding, Gate } from './types.ts';
+
+const worldBounds = (asset: CompiledAsset): Map<string, Bounds> => {
+  const xf = worldTransforms(asset.parts);
+  const out = new Map<string, Bounds>();
+  for (const p of asset.parts) {
+    const t = xf.get(p.name);
+    if (!t || !p.mesh || p.mesh.indices.length === 0) continue;
+    const b = boundsOf(p.mesh);
+    const corners = [0, 1, 2, 3, 4, 5, 6, 7].map((i) =>
+      toWorld(t, [
+        i & 1 ? b.max[0] : b.min[0],
+        i & 2 ? b.max[1] : b.min[1],
+        i & 4 ? b.max[2] : b.min[2],
+      ]),
+    );
+    const axis = (k: 0 | 1 | 2, f: (...v: number[]) => number): number =>
+      f(...corners.map((c) => c[k]));
+    out.set(p.name, {
+      min: [axis(0, Math.min), axis(1, Math.min), axis(2, Math.min)],
+      max: [axis(0, Math.max), axis(1, Math.max), axis(2, Math.max)],
+    });
+  }
+  return out;
+};
+
+export const triangleBudget: Gate = (asset) => {
+  const tris = asset.parts.reduce((s, p) => s + (p.mesh ? triangleCount(p.mesh) : 0), 0);
+  const cap = asset.budget.triangles[asset.lod];
+  return tris > cap
+    ? [
+        {
+          gate: 'triangle-budget',
+          message: `LOD${asset.lod} has ${tris} triangles, budget ${cap}`,
+          fix: 'drop detail at this LOD (read ctx.lod) or raise the budget with a reason',
+        },
+      ]
+    : [];
+};
+
+export const partNames: Gate = (asset) =>
+  asset.parts
+    .filter((p) => !/^[a-z][a-z0-9_]*$/.test(p.name))
+    .map((p) => ({
+      gate: 'part-names',
+      part: p.name,
+      message: `part '${p.name}' is not snake_case`,
+      fix: 'rename it — engines bind to node names like axle_0, door_l',
+    }));
+
+/** Overall bounding box vs the recipe's `real` dimensions: catches a 6 m tank modelled at 7.4 m. */
+export const proportions: Gate = (asset) => {
+  const real = asset.real;
+  if (!real || asset.lod !== 0) return [];
+  const boxes = [...worldBounds(asset).values()];
+  const span = (k: 0 | 1 | 2): number =>
+    Math.max(...boxes.map((b) => b.max[k])) - Math.min(...boxes.map((b) => b.min[k]));
+  const tol = real.tolerance ?? 0.05;
+  return (
+    [
+      ['length', 0, real.length],
+      ['width', 1, real.width],
+      ['height', 2, real.height],
+    ] as const
+  ).flatMap(([axis, k, want]) => {
+    const got = span(k);
+    return Math.abs(got - want) / want > tol
+      ? [
+          {
+            gate: 'proportions',
+            message: `${axis} ${got.toFixed(2)} m vs real ${want} m (±${tol * 100}%)`,
+            fix: `rescale along ${'XYZ'[k]} — re-derive the lengths from the sources, don't fudge the tolerance`,
+          },
+        ]
+      : [];
+  });
+};
+
+/** Planned gates, signatures fixed: docs/idea/06-qa.md. */
+export const silhouetteIoU = (_asset: CompiledAsset, _referencePng: Uint8Array): number =>
+  notImplemented('silhouette IoU gate');
+
+/** The recipe's own `checks`, each finding reported under the gate name `check`. */
+export const recipeChecks: Gate = (asset) =>
+  runChecks(asset).map((f) => ({
+    gate: 'check',
+    ...(f.part ? { part: f.part } : {}),
+    message: f.message,
+    fix: f.fix,
+  }));
+
+export const DEFAULT_GATES: readonly Gate[] = [
+  triangleBudget,
+  floatingParts,
+  clashes,
+  partNames,
+  proportions,
+  measures,
+  recipeChecks,
+  nonFinite,
+  vertexColors,
+  hiddenParts,
+  normalsMatchWinding,
+];
+
+export function runQa(asset: CompiledAsset, gates: readonly Gate[] = DEFAULT_GATES): Finding[] {
+  return gates.flatMap((g) => g(asset));
+}

package/src/qa/geometry.ts

@@ -0,0 +1,187 @@
+// Exact-enough geometry for QA: point↔triangle distance, a triangle spatial hash, and surface
+// samples. Bounding boxes lie (a diagonal strut's box touches everything); surfaces don't.
+
+import { boundsOf, type Mesh, type Vec3 } from '../core/index.ts';
+
+const at = (m: Mesh, i: number): Vec3 => [
+  m.positions[i * 3] ?? 0,
+  m.positions[i * 3 + 1] ?? 0,
+  m.positions[i * 3 + 2] ?? 0,
+];
+const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const lerp = (a: Vec3, b: Vec3, t: number): Vec3 => [
+  a[0] + (b[0] - a[0]) * t,
+  a[1] + (b[1] - a[1]) * t,
+  a[2] + (b[2] - a[2]) * t,
+];
+
+export function triangle(m: Mesh, t: number): [Vec3, Vec3, Vec3] {
+  return [
+    at(m, m.indices[t * 3] ?? 0),
+    at(m, m.indices[t * 3 + 1] ?? 0),
+    at(m, m.indices[t * 3 + 2] ?? 0),
+  ];
+}
+
+/** Distance from p to triangle abc (Ericson, Real-Time Collision Detection §5.1.5). */
+export function pointTriangleDistance(p: Vec3, a: Vec3, b: Vec3, c: Vec3): number {
+  const ab = sub(b, a);
+  const ac = sub(c, a);
+  const ap = sub(p, a);
+  const d1 = dot(ab, ap);
+  const d2 = dot(ac, ap);
+  if (d1 <= 0 && d2 <= 0) return Math.hypot(...ap);
+  const bp = sub(p, b);
+  const d3 = dot(ab, bp);
+  const d4 = dot(ac, bp);
+  if (d3 >= 0 && d4 <= d3) return Math.hypot(...bp);
+  const vc = d1 * d4 - d3 * d2;
+  if (vc <= 0 && d1 >= 0 && d3 <= 0) return Math.hypot(...sub(p, lerp(a, b, d1 / (d1 - d3))));
+  const cp = sub(p, c);
+  const d5 = dot(ab, cp);
+  const d6 = dot(ac, cp);
+  if (d6 >= 0 && d5 <= d6) return Math.hypot(...cp);
+  const vb = d5 * d2 - d1 * d6;
+  if (vb <= 0 && d2 >= 0 && d6 <= 0) return Math.hypot(...sub(p, lerp(a, c, d2 / (d2 - d6))));
+  const va = d3 * d6 - d5 * d4;
+  if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0)
+    return Math.hypot(...sub(p, lerp(b, c, (d4 - d3) / (d4 - d3 + (d5 - d6)))));
+  const den = 1 / (va + vb + vc);
+  const v = vb * den;
+  const w = vc * den;
+  return Math.hypot(
+    ...sub(p, [
+      a[0] + ab[0] * v + ac[0] * w,
+      a[1] + ab[1] * v + ac[1] * w,
+      a[2] + ab[2] * v + ac[2] * w,
+    ]),
+  );
+}
+
+// Numeric cell keys (no string building per query) — collisions only add candidates, never drop.
+const key = (x: number, y: number, z: number): number =>
+  ((x * 73856093) ^ (y * 19349663) ^ (z * 83492791)) | 0;
+
+/** Triangles bucketed by a uniform grid, so a point only tests its neighbourhood. */
+export class TriangleGrid {
+  private readonly cells = new Map<number, number[]>();
+  /** Cell edge: 25 cm for props and vehicles, growing with big meshes (a 330 m tower) so one
+   *  long triangle never lands in 10⁵ cells. */
+  private readonly cell: number;
+  private readonly tris: Float64Array;
+  /** Per-triangle AABB (min xyz, max xyz) for a cheap reject before the exact distance. */
+  private readonly boxes: Float64Array;
+  private readonly stamp: Int32Array;
+  private query = 0;
+
+  constructor(mesh: Mesh) {
+    const n = mesh.indices.length / 3;
+    this.tris = new Float64Array(n * 9);
+    this.boxes = new Float64Array(n * 6);
+    this.stamp = new Int32Array(n);
+    const b = boundsOf(mesh);
+    const diag = Math.hypot(b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]);
+    this.cell = Math.max(0.25, diag / 256);
+    const CELL = this.cell;
+    for (let t = 0; t < n; t++) {
+      const [a, b, c] = triangle(mesh, t);
+      this.tris.set([...a, ...b, ...c], t * 9);
+      for (let k = 0; k < 3; k++) {
+        this.boxes[t * 6 + k] = Math.min(a[k] ?? 0, b[k] ?? 0, c[k] ?? 0);
+        this.boxes[t * 6 + 3 + k] = Math.max(a[k] ?? 0, b[k] ?? 0, c[k] ?? 0);
+      }
+      const lo = [0, 1, 2].map((k) => Math.floor(Math.min(a[k] ?? 0, b[k] ?? 0, c[k] ?? 0) / CELL));
+      const hi = [0, 1, 2].map((k) => Math.floor(Math.max(a[k] ?? 0, b[k] ?? 0, c[k] ?? 0) / CELL));
+      for (let x = lo[0] ?? 0; x <= (hi[0] ?? 0); x++)
+        for (let y = lo[1] ?? 0; y <= (hi[1] ?? 0); y++)
+          for (let z = lo[2] ?? 0; z <= (hi[2] ?? 0); z++) {
+            const k = key(x, y, z);
+            const list = this.cells.get(k);
+            if (list) list.push(t);
+            else this.cells.set(k, [t]);
+          }
+    }
+  }
+
+  /** Distance from p to the nearest triangle, if one is within `radius`; else Infinity. */
+  nearest(p: Vec3, radius: number): number {
+    const CELL = this.cell;
+    // Only the cells the query sphere overlaps — usually 1–8, not a fixed 27.
+    const [x0, y0, z0] = [
+      Math.floor((p[0] - radius) / CELL),
+      Math.floor((p[1] - radius) / CELL),
+      Math.floor((p[2] - radius) / CELL),
+    ];
+    const [x1, y1, z1] = [
+      Math.floor((p[0] + radius) / CELL),
+      Math.floor((p[1] + radius) / CELL),
+      Math.floor((p[2] + radius) / CELL),
+    ];
+    const q = ++this.query;
+    const T = this.tris;
+    const B = this.boxes;
+    let best = Infinity;
+    for (let x = x0; x <= x1; x++)
+      for (let y = y0; y <= y1; y++)
+        for (let z = z0; z <= z1; z++) {
+          const list = this.cells.get(key(x, y, z));
+          if (!list) continue;
+          for (const t of list) {
+            if (this.stamp[t] === q) continue;
+            this.stamp[t] = q;
+            const lim = Math.min(best, radius);
+            const o6 = t * 6;
+            if (
+              p[0] < (B[o6] ?? 0) - lim ||
+              p[0] > (B[o6 + 3] ?? 0) + lim ||
+              p[1] < (B[o6 + 1] ?? 0) - lim ||
+              p[1] > (B[o6 + 4] ?? 0) + lim ||
+              p[2] < (B[o6 + 2] ?? 0) - lim ||
+              p[2] > (B[o6 + 5] ?? 0) + lim
+            )
+              continue;
+            const o = t * 9;
+            const d = pointTriangleDistance(
+              p,
+              [T[o] ?? 0, T[o + 1] ?? 0, T[o + 2] ?? 0],
+              [T[o + 3] ?? 0, T[o + 4] ?? 0, T[o + 5] ?? 0],
+              [T[o + 6] ?? 0, T[o + 7] ?? 0, T[o + 8] ?? 0],
+            );
+            if (d < best) best = d;
+          }
+        }
+    return best <= radius ? best : Infinity;
+  }
+}
+
+// Gates and checks ask for the same mesh's samples many times; compute each (mesh, density) once.
+const sampleCache = new WeakMap<Mesh, Map<string, Vec3[]>>();
+
+/** Vertices plus points along every edge every `step` metres (catches crossing members). */
+export function surfaceSamples(m: Mesh, step = 0.05, maxPerEdge = 16): Vec3[] {
+  const key = `${step}:${maxPerEdge}`;
+  const byMesh = sampleCache.get(m) ?? new Map<string, Vec3[]>();
+  sampleCache.set(m, byMesh);
+  const hit = byMesh.get(key);
+  if (hit) return hit;
+  const out = sampleMesh(m, step, maxPerEdge);
+  byMesh.set(key, out);
+  return out;
+}
+
+function sampleMesh(m: Mesh, step: number, maxPerEdge: number): Vec3[] {
+  const out: Vec3[] = [];
+  for (let i = 0; i < m.positions.length / 3; i++) out.push(at(m, i));
+  for (let t = 0; t < m.indices.length / 3; t++) {
+    const tri = triangle(m, t);
+    for (let e = 0; e < 3; e++) {
+      const a = tri[e] ?? tri[0];
+      const b = tri[(e + 1) % 3] ?? tri[0];
+      const n = Math.min(maxPerEdge, Math.floor(Math.hypot(...sub(b, a)) / step));
+      for (let s = 1; s < n; s++) out.push(lerp(a, b, s / n));
+    }
+    out.push(lerp(lerp(tri[0], tri[1], 0.5), tri[2], 1 / 3));
+  }
+  return out;
+}

package/src/qa/index.ts

@@ -0,0 +1,28 @@
+// Public API of /qa: the gate every compiled asset passes before it ships.
+
+export { clear, noOverlap, runChecks, symmetric, touches } from './checks.ts';
+export { clashes } from './clash.ts';
+export { floatingParts, touching } from './floating.ts';
+export {
+  DEFAULT_GATES,
+  partNames,
+  proportions,
+  runQa,
+  silhouetteIoU,
+  triangleBudget,
+} from './gates.ts';
+export { pointTriangleDistance, surfaceSamples, TriangleGrid } from './geometry.ts';
+export { insideSolid } from './inside.ts';
+export { glob, type Inspector, inspect, type Penetration } from './inspect.ts';
+export {
+  DEFAULT_LOD_GATES,
+  type LodGate,
+  lodPivots,
+  lodSilhouette,
+  lodTriangles,
+  runLodQa,
+} from './lods.ts';
+export { measure, measures } from './measures.ts';
+export { hiddenParts, zFighting } from './occlusion.ts';
+export { degenerateTriangles, nonFinite, normalsMatchWinding, vertexColors } from './sanity.ts';
+export { CLASH_EPS, CONTACT_EPS, type Finding, type Gate } from './types.ts';

package/src/qa/inside.ts

@@ -0,0 +1,114 @@
+// Point-in-solid for closed meshes, indexed and allocation-free: axis-aligned rays (+Z, +Y, +X)
+// against triangles bucketed in a 2D grid perpendicular to each ray. An axis-aligned ray hitting a
+// triangle is a 2D point-in-triangle test in the other two axes plus one interpolated depth.
+// Majority of the three rays (short-circuited), so grazing an edge cannot flip the answer.
+// Open sheets (planar decals) are never "solid"; penetration only means something vs closed parts.
+
+import { boundsOf, type Mesh, type Vec3 } from '../core/index.ts';
+
+/** Column size: 20 cm for props and vehicles, growing with the mesh so a 330 m tower's long
+ *  members don't land in thousands of columns each (answers never depend on the cell size). */
+const cellFor = (m: Mesh): number => {
+  const b = boundsOf(m);
+  return Math.max(
+    0.2,
+    Math.hypot(b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]) / 256,
+  );
+};
+// A tiny fixed offset keeps the query point off shared edges/vertices of axis-aligned geometry.
+const NUDGE: Vec3 = [1.37e-5, 2.91e-5, 3.73e-5];
+const OTHER = [
+  [1, 2],
+  [0, 2],
+  [0, 1],
+] as const;
+
+export class SolidIndex {
+  private readonly tri: Float64Array;
+  private readonly columns: Map<number, number[]>[] = [new Map(), new Map(), new Map()];
+  private readonly cell: number;
+
+  constructor(mesh: Mesh) {
+    this.cell = cellFor(mesh);
+    const CELL = this.cell;
+    const n = mesh.indices.length / 3;
+    this.tri = new Float64Array(n * 9);
+    for (let t = 0; t < n; t++) {
+      for (let v = 0; v < 3; v++) {
+        const idx = mesh.indices[t * 3 + v] ?? 0;
+        for (let k = 0; k < 3; k++) this.tri[t * 9 + v * 3 + k] = mesh.positions[idx * 3 + k] ?? 0;
+      }
+      for (const axis of [0, 1, 2] as const) {
+        const [i, j] = OTHER[axis];
+        const T = this.tri;
+        const o = t * 9;
+        const a = T[o + i] ?? 0;
+        const b = T[o + 3 + i] ?? 0;
+        const c = T[o + 6 + i] ?? 0;
+        const d = T[o + j] ?? 0;
+        const e = T[o + 3 + j] ?? 0;
+        const f = T[o + 6 + j] ?? 0;
+        const u0 = Math.floor(Math.min(a, b, c) / CELL);
+        const u1 = Math.floor(Math.max(a, b, c) / CELL);
+        const v0 = Math.floor(Math.min(d, e, f) / CELL);
+        const v1 = Math.floor(Math.max(d, e, f) / CELL);
+        const map = this.columns[axis];
+        if (!map) continue;
+        for (let u = u0; u <= u1; u++)
+          for (let v = v0; v <= v1; v++) {
+            const k = (u * 92837111) ^ (v * 689287499);
+            const list = map.get(k);
+            if (list) list.push(t);
+            else map.set(k, [t]);
+          }
+      }
+    }
+  }
+
+  /** Odd number of crossings of the ray from p along +axis ⇒ inside (for that ray). */
+  private parity(px: number, py: number, pz: number, axis: 0 | 1 | 2): boolean {
+    const [i, j] = OTHER[axis];
+    const p = [px, py, pz];
+    const pi = p[i] ?? 0;
+    const pj = p[j] ?? 0;
+    const pk = p[axis] ?? 0;
+    const CELL = this.cell;
+    const list = this.columns[axis]?.get(
+      (Math.floor(pi / CELL) * 92837111) ^ (Math.floor(pj / CELL) * 689287499),
+    );
+    if (!list) return false;
+    const T = this.tri;
+    let n = 0;
+    for (const t of list) {
+      const o = t * 9;
+      const ai = T[o + i] ?? 0;
+      const aj = T[o + j] ?? 0;
+      const bi = T[o + 3 + i] ?? 0;
+      const bj = T[o + 3 + j] ?? 0;
+      const ci = T[o + 6 + i] ?? 0;
+      const cj = T[o + 6 + j] ?? 0;
+      const area = (bi - ai) * (cj - aj) - (bj - aj) * (ci - ai);
+      if (Math.abs(area) < 1e-14) continue;
+      const w0 = ((bi - pi) * (cj - pj) - (bj - pj) * (ci - pi)) / area;
+      const w1 = ((ci - pi) * (aj - pj) - (cj - pj) * (ai - pi)) / area;
+      const w2 = 1 - w0 - w1;
+      if (w0 < 0 || w1 < 0 || w2 < 0) continue;
+      const depth =
+        w0 * (T[o + axis] ?? 0) + w1 * (T[o + 3 + axis] ?? 0) + w2 * (T[o + 6 + axis] ?? 0);
+      if (depth > pk) n++;
+    }
+    return n % 2 === 1;
+  }
+
+  inside(point: Vec3): boolean {
+    const x = point[0] + NUDGE[0];
+    const y = point[1] + NUDGE[1];
+    const z = point[2] + NUDGE[2];
+    const vz = this.parity(x, y, z, 2);
+    const vy = this.parity(x, y, z, 1);
+    return vz === vy ? vz : this.parity(x, y, z, 0);
+  }
+}
+
+/** One-off query; build a SolidIndex yourself when testing many points against one mesh. */
+export const insideSolid = (p: Vec3, m: Mesh): boolean => new SolidIndex(m).inside(p);

package/src/qa/inspect.ts

@@ -0,0 +1,107 @@
+// Inspector: geometry queries over a compiled asset in world space, for checks, scripts and
+// agents ("how far is the track from the hull?", "does the wheel sink into the fender?").
+// Part selectors are names or globs: 'track_l_*', 'road_wheel_*_3', '*_hatch'.
+
+import {
+  type Bounds,
+  boundsOf,
+  type CompiledAsset,
+  type Mesh,
+  merge,
+  worldMeshes,
+} from '../core/index.ts';
+import { surfaceSamples, TriangleGrid } from './geometry.ts';
+import { SolidIndex } from './inside.ts';
+
+export const glob = (pattern: string): RegExp =>
+  new RegExp(
+    `^${pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replaceAll('*', '.*')
+      .replaceAll('?', '.')}$`,
+  );
+
+export interface Penetration {
+  /** Deepest sampled point of A inside B's solid, metres (0 = none). */
+  readonly depth: number;
+  readonly samples: number;
+}
+
+export interface Inspector {
+  readonly asset: CompiledAsset;
+  parts(selector: string): string[];
+  mesh(selector: string): Mesh | null;
+  bounds(selector: string): Bounds | null;
+  /** Smallest surface-to-surface distance (0 when touching or intersecting), capped at `max`. */
+  distance(a: string, b: string, max?: number): number;
+  /** How deep A's surface goes inside B's closed solid. */
+  penetration(a: string, b: string): Penetration;
+}
+
+export function inspect(asset: CompiledAsset): Inspector {
+  const world = worldMeshes(asset.parts);
+  const parts = (sel: string): string[] => [...world.keys()].filter((n) => glob(sel).test(n));
+  // Checks ask about the same parts over and over: build each merged mesh and index once.
+  const meshes = new Map<string, Mesh | null>();
+  const grids = new Map<string, TriangleGrid>();
+  const solids = new Map<string, SolidIndex>();
+  const samples = new Map<string, ReturnType<typeof surfaceSamples>>();
+  const mesh = (sel: string): Mesh | null => {
+    if (!meshes.has(sel)) {
+      const ms = parts(sel).flatMap((n) => world.get(n) ?? []);
+      meshes.set(sel, ms.length ? merge(ms) : null);
+    }
+    return meshes.get(sel) ?? null;
+  };
+  const cached = <T>(map: Map<string, T>, key: string, make: () => T): T => {
+    const hit = map.get(key);
+    if (hit !== undefined) return hit;
+    const v = make();
+    map.set(key, v);
+    return v;
+  };
+  const near = (a: Bounds, b: Bounds, eps: number): boolean =>
+    [0, 1, 2].every(
+      (k) => (a.min[k] ?? 0) <= (b.max[k] ?? 0) + eps && (b.min[k] ?? 0) <= (a.max[k] ?? 0) + eps,
+    );
+  return {
+    asset,
+    parts,
+    mesh,
+    bounds: (sel) => {
+      const m = mesh(sel);
+      return m ? boundsOf(m) : null;
+    },
+    distance(a, b, max = 1) {
+      const ma = mesh(a);
+      const mb = mesh(b);
+      if (!ma || !mb || !near(boundsOf(ma), boundsOf(mb), max)) return max;
+      const grid = cached(grids, b, () => new TriangleGrid(mb));
+      const pts = cached(samples, a, () => surfaceSamples(ma, 0.05, 8));
+      // Grow the search radius: "do they touch?" is answered at 2 cm without scanning metres.
+      for (const r of [0.02, 0.1, 0.5, max].filter((x) => x <= max)) {
+        let best = Infinity;
+        for (const p of pts) best = Math.min(best, grid.nearest(p, Math.min(r, best)));
+        if (best <= r) return best;
+      }
+      return max;
+    },
+    penetration(a, b) {
+      const ma = mesh(a);
+      const mb = mesh(b);
+      if (!ma || !mb) return { depth: 0, samples: 0 };
+      const bb = boundsOf(mb);
+      if (!near(boundsOf(ma), bb, 0)) return { depth: 0, samples: 0 };
+      const grid = cached(grids, b, () => new TriangleGrid(mb));
+      const solid = cached(solids, b, () => new SolidIndex(mb));
+      let depth = 0;
+      let count = 0;
+      for (const p of cached(samples, `${a}#pen`, () => surfaceSamples(ma, 0.1, 3))) {
+        if (!near({ min: p, max: p }, bb, 0) || !solid.inside(p)) continue;
+        count++;
+        depth = Math.max(depth, grid.nearest(p, 0.5));
+      }
+      return { depth, samples: count };
+    },
+  };
+}

package/src/qa/lods.ts

@@ -0,0 +1,97 @@
+// Gates across the LOD chain (they need all three compiled LODs at once): triangle counts fall
+// LOD0 ≥ LOD1 ≥ LOD2, the far LODs keep the near one's silhouette box (no popping when the engine
+// switches), and every pivot the engine binds to (groups, moving parts) survives at every LOD.
+
+import { type Bounds, boundsOf, type CompiledAsset, worldMeshes } from '../core/index.ts';
+import type { Finding } from './types.ts';
+
+/** A gate over the whole LOD chain, index = LOD. */
+export type LodGate = (lods: readonly CompiledAsset[]) => Finding[];
+
+const tris = (a: CompiledAsset): number =>
+  a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+
+export const lodTriangles: LodGate = (lods) =>
+  lods.slice(1).flatMap((a, i): Finding[] => {
+    const prev = lods[i];
+    if (!prev || tris(a) <= tris(prev)) return [];
+    return [
+      {
+        gate: 'lod-triangles',
+        message: `LOD${a.lod} has ${tris(a)} triangles, more than LOD${prev.lod} (${tris(prev)})`,
+        fix: 'each LOD must be cheaper than the one before: read ctx.lod / ctx.pick([...]) and drop segments or detail parts',
+      },
+    ];
+  });
+
+function assetBounds(a: CompiledAsset): Bounds | null {
+  const all = [...worldMeshes(a.parts).values()].map(boundsOf);
+  if (all.length === 0) return null;
+  const k = [0, 1, 2] as const;
+  const lo = k.map((i) => Math.min(...all.map((b) => b.min[i])));
+  const hi = k.map((i) => Math.max(...all.map((b) => b.max[i])));
+  return {
+    min: [lo[0] ?? 0, lo[1] ?? 0, lo[2] ?? 0],
+    max: [hi[0] ?? 0, hi[1] ?? 0, hi[2] ?? 0],
+  };
+}
+
+/** LOD1/LOD2 overall box within `tol` of LOD0's span per side (min 5 cm). */
+export const lodSilhouette =
+  (tol = 0.05): LodGate =>
+  (lods) => {
+    const ref = lods[0] ? assetBounds(lods[0]) : null;
+    if (!ref) return [];
+    return lods.slice(1).flatMap((a): Finding[] => {
+      const b = assetBounds(a);
+      if (!b) return [];
+      const off = ([0, 1, 2] as const).flatMap((k) => {
+        const lim = Math.max(0.05, (ref.max[k] - ref.min[k]) * tol);
+        const d = Math.max(Math.abs(b.min[k] - ref.min[k]), Math.abs(b.max[k] - ref.max[k]));
+        return d > lim ? [`${'XYZ'[k]} by ${(d * 100).toFixed(0)} cm`] : [];
+      });
+      return off.length
+        ? [
+            {
+              gate: 'lod-silhouette',
+              message: `LOD${a.lod} outline differs from LOD0 on ${off.join(', ')} — it will pop on LOD switch`,
+              fix: 'keep the big masses at every LOD (drop detail, not extent): a far LOD is the same shape with fewer segments',
+            },
+          ]
+        : [];
+    });
+  };
+
+/** Pivots = what an engine binds code to: empty groups and parts with motion. */
+const pivots = (a: CompiledAsset): string[] =>
+  a.parts.filter((p) => p.mesh === null || p.motion !== null).map((p) => p.name);
+
+export const lodPivots: LodGate = (lods) => {
+  const ref = lods[0];
+  if (!ref) return [];
+  const want = pivots(ref);
+  return lods.slice(1).flatMap((a): Finding[] => {
+    const have = new Set(a.parts.map((p) => p.name));
+    const missing = want.filter((n) => !have.has(n));
+    return missing.length
+      ? [
+          {
+            gate: 'lod-pivots',
+            message: `LOD${a.lod} drops pivot(s) ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ` (+${missing.length - 6})` : ''} that LOD0 has — game code driving them breaks at that LOD`,
+            fix: 'keep the group/moving part at every LOD and gate only its geometry: ctx.group(name) always, detail meshes behind ctx.lod',
+          },
+        ]
+      : [];
+  });
+};
+
+/** Default chain gates: only what every gallery recipe passes today. `lodSilhouette` and
+ *  `lodPivots` are opt-in until the recipes they flag are fixed (see their findings). */
+export const DEFAULT_LOD_GATES: readonly LodGate[] = [lodTriangles];
+
+export function runLodQa(
+  lods: readonly CompiledAsset[],
+  gates: readonly LodGate[] = DEFAULT_LOD_GATES,
+): Finding[] {
+  return gates.flatMap((g) => g(lods));
+}