@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/primitives/tiled.ts

@@ -0,0 +1,93 @@
+// A flat quad tiling one trim strip at TRUE SCALE: walls, roofs, decks, floors. Flat normal u × v
+// (front = the side u × v points to, CCW). U runs along `u` in metres (the sampler repeats it); V
+// runs up `v` and is cut into one band per `vMetres`, so brick courses keep their real height on a
+// 3 m wall. `uOffset`/`vOffset` phase the pattern so adjacent faces line up.
+//   triangles = 2 · segments · bands · (doubleSided ? 2 : 1),  bands = ⌈|v| / vMetres⌉ at offset 0
+
+import { type Mesh, MeshBuilder, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { count, positive, spanOf } from './check.ts';
+import { stripU, stripV, stripVMetres } from './strip-uv.ts';
+
+export interface TiledOptions {
+  /** One corner of the face. */
+  readonly origin: Vec3;
+  /** Edge along the strip (texture U), metres. */
+  readonly u: Vec3;
+  /** The other edge, texture "up" (V), metres. */
+  readonly v: Vec3;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  /** Columns along `u` (vertex density for grime/bending); the LOD knob. Default 1. */
+  readonly segments?: number;
+  /** Metres the pattern is shifted along U / V (continue a course round a corner). */
+  readonly uOffset?: number;
+  readonly vOffset?: number;
+  /** World metres one strip band spans along V. Default: the house sheet's `scaleMetres`.
+   *  Raise it to stretch the strip (fewer bands, fewer triangles on a far LOD). */
+  readonly vMetres?: number;
+  readonly doubleSided?: boolean;
+}
+
+export function tiled(o: TiledOptions): Mesh {
+  const { lu, lv, n } = spanOf('tiled', o.origin, o.u, o.v);
+  const strip = o.strip ?? 'plain';
+  const segs = count('tiled segments', o.segments ?? 1, 1, 4096);
+  const vm = positive('tiled vMetres', o.vMetres ?? stripVMetres(strip), 'e.g. 0.45 for brick');
+  const rect = stripRect(strip);
+  const uOff = o.uOffset ?? 0;
+  const b = new MeshBuilder();
+  const sides = o.doubleSided ? [1, -1] : [1];
+  let t = 0;
+  while (t < lv - 1e-9) {
+    let local = (o.vOffset ?? 0) + t;
+    local -= Math.floor(local / vm) * vm;
+    if (vm - local < 1e-9) local = 0;
+    const step = Math.min(lv - t, vm - local);
+    const fv0 = local / vm;
+    const fv1 = (local + step) / vm;
+    for (const side of sides) {
+      const nn: Vec3 = [n[0] * side, n[1] * side, n[2] * side];
+      const first = row(b, o, nn, rect, uOff, lu, segs, t / lv, stripV(rect, fv0));
+      row(b, o, nn, rect, uOff, lu, segs, (t + step) / lv, stripV(rect, fv1));
+      for (let j = 0; j < segs; j++) {
+        const a = first + j;
+        const c = first + segs + 1 + j;
+        if (side > 0) b.quad(a, a + 1, c + 1, c);
+        else b.quad(a, c, c + 1, a + 1);
+      }
+    }
+    t += step;
+  }
+  return b.build();
+}
+
+/** One row of segs + 1 vertices at fraction `fv` up the face; returns the first index. */
+function row(
+  b: MeshBuilder,
+  o: TiledOptions,
+  n: Vec3,
+  rect: ReturnType<typeof stripRect>,
+  uOff: number,
+  lu: number,
+  segs: number,
+  fv: number,
+  v: number,
+): number {
+  let first = -1;
+  for (let j = 0; j <= segs; j++) {
+    const fu = j / segs;
+    const id = b.vertex({
+      p: [
+        o.origin[0] + o.u[0] * fu + o.v[0] * fv,
+        o.origin[1] + o.u[1] * fu + o.v[1] * fv,
+        o.origin[2] + o.u[2] * fu + o.v[2] * fv,
+      ],
+      n,
+      uv: [stripU(rect, uOff + lu * fu), v],
+      color: o.color,
+    });
+    if (first < 0) first = id;
+  }
+  return first;
+}

package/src/primitives/transport.ts

@@ -0,0 +1,85 @@
+// Parallel-transport frames along a polyline (double reflection, Wang et al. 2008): the section
+// never twist-flips at inflections the way Frenet frames do. Shared by `sweep` and by kinds that
+// must place things exactly on a swept surface (leaves on twigs, children on branches).
+
+import { Ts23dError, type Vec3 } from '../core/index.ts';
+
+export interface SweepFrame {
+  /** Unit tangent. */
+  readonly t: Vec3;
+  /** Unit normal: section X. */
+  readonly n: Vec3;
+  /** Unit binormal t × n: section Y. */
+  readonly b: Vec3;
+}
+
+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 unit = (a: Vec3): Vec3 => {
+  const l = Math.hypot(a[0], a[1], a[2]) || 1;
+  return [a[0] / l, a[1] / l, a[2] / l];
+};
+const cross = (a: Vec3, b: Vec3): Vec3 => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+const reflect = (v: Vec3, axis: Vec3, c: number): Vec3 => {
+  const k = (2 / c) * dot(axis, v);
+  return [v[0] - k * axis[0], v[1] - k * axis[1], v[2] - k * axis[2]];
+};
+
+/** Throws unless the path has ≥ 2 points and no zero-length segment. Returns cumulative lengths. */
+export function arcLengths(path: readonly Vec3[]): number[] {
+  if (path.length < 2) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `sweep path has ${path.length} point(s)`,
+      fix: 'pass at least 2 path points (from → to); a single point has no direction to sweep along',
+    });
+  }
+  const s = [0];
+  for (let i = 1; i < path.length; i++) {
+    const d = Math.hypot(...sub(path[i] ?? [0, 0, 0], path[i - 1] ?? [0, 0, 0]));
+    if (d < 1e-9) {
+      throw new Ts23dError('T3D_RECIPE_INVALID', {
+        cause: `sweep path points ${i - 1} and ${i} coincide (zero-length segment)`,
+        fix: 'make consecutive path points distinct — drop duplicates before sweeping',
+      });
+    }
+    s.push((s[i - 1] ?? 0) + d);
+  }
+  return s;
+}
+
+/**
+ * One frame per path point. The first normal comes from world X when the path starts near
+ * vertical, else world Z, so a path in the XZ plane keeps b = ±Y all the way (trunk widths
+ * measured across Y stay exact).
+ */
+export function transportFrames(path: readonly Vec3[]): SweepFrame[] {
+  arcLengths(path);
+  const last = path.length - 1;
+  const tangents = path.map((_, i) =>
+    unit(sub(path[Math.min(last, i + 1)] ?? [0, 0, 0], path[Math.max(0, i - 1)] ?? [0, 0, 0])),
+  );
+  const t0 = tangents[0] ?? [0, 0, 1];
+  const ref: Vec3 = Math.abs(t0[2]) > 0.9 ? [1, 0, 0] : [0, 0, 1];
+  const k = dot(ref, t0);
+  let n = unit([ref[0] - k * t0[0], ref[1] - k * t0[1], ref[2] - k * t0[2]]);
+  const out: SweepFrame[] = [{ t: t0, n, b: cross(t0, n) }];
+  for (let i = 1; i <= last; i++) {
+    const p0 = path[i - 1] ?? [0, 0, 0];
+    const p1 = path[i] ?? [0, 0, 0];
+    const ti = tangents[i - 1] ?? t0;
+    const tj = tangents[i] ?? t0;
+    const v1 = sub(p1, p0);
+    const c1 = dot(v1, v1);
+    const nL = reflect(n, v1, c1);
+    const tL = reflect(ti, v1, c1);
+    const v2 = sub(tj, tL);
+    const c2 = dot(v2, v2);
+    n = unit(c2 < 1e-12 ? nL : reflect(nL, v2, c2));
+    out.push({ t: tj, n, b: cross(tj, n) });
+  }
+  return out;
+}

package/src/primitives/triangulate.ts

@@ -0,0 +1,42 @@
+// Ear-clipping triangulation of a simple 2D polygon (convex or concave, either winding).
+// Returns index triples into the input, counter-clockwise.
+
+import type { Vec2 } from '../core/index.ts';
+
+const area = (p: readonly Vec2[]): number =>
+  p.reduce((s, a, i) => {
+    const b = p[(i + 1) % p.length] ?? a;
+    return s + a[0] * b[1] - b[0] * a[1];
+  }, 0) / 2;
+
+const cross = (a: Vec2, b: Vec2, c: Vec2): number =>
+  (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+
+function inside(p: Vec2, a: Vec2, b: Vec2, c: Vec2): boolean {
+  return cross(a, b, p) >= 0 && cross(b, c, p) >= 0 && cross(c, a, p) >= 0;
+}
+
+export function triangulate(poly: readonly Vec2[]): [number, number, number][] {
+  const idx = poly.map((_, i) => i);
+  if (area(poly) < 0) idx.reverse();
+  const out: [number, number, number][] = [];
+  let guard = idx.length * idx.length;
+  while (idx.length > 3 && guard-- > 0) {
+    for (let i = 0; i < idx.length; i++) {
+      const ia = idx[(i + idx.length - 1) % idx.length] ?? 0;
+      const ib = idx[i] ?? 0;
+      const ic = idx[(i + 1) % idx.length] ?? 0;
+      const a = poly[ia] ?? [0, 0];
+      const b = poly[ib] ?? [0, 0];
+      const c = poly[ic] ?? [0, 0];
+      if (cross(a, b, c) <= 0) continue;
+      if (idx.some((j) => j !== ia && j !== ib && j !== ic && inside(poly[j] ?? [0, 0], a, b, c)))
+        continue;
+      out.push([ia, ib, ic]);
+      idx.splice(i, 1);
+      break;
+    }
+  }
+  if (idx.length === 3) out.push([idx[0] ?? 0, idx[1] ?? 0, idx[2] ?? 0]);
+  return out;
+}

package/src/primitives/value-noise.ts

@@ -0,0 +1,62 @@
+// Seeded 3D value noise for SDF displacement (rock pitting, skin wrinkles): a shuffled lattice
+// from the recipe's Rng, quintic-faded trilinear interpolation, fractal octaves. Deterministic.
+
+import type { Rng } from '../core/index.ts';
+import type { Field } from './sdf-ops.ts';
+
+/**
+ * Seeded fractal value noise in [−1, 1]: `scale` = metres per feature, `octaves` halve the scale
+ * and amplitude each time. Same Rng state → same field, bit for bit.
+ */
+export function valueNoise(
+  rng: Rng,
+  o: { readonly scale?: number; readonly octaves?: number } = {},
+): Field {
+  const perm = new Uint8Array(512);
+  const vals = new Float64Array(256);
+  for (let i = 0; i < 256; i++) {
+    perm[i] = i;
+    vals[i] = rng.next() * 2 - 1;
+  }
+  for (let i = 255; i > 0; i--) {
+    const j = rng.int(0, i);
+    const t = perm[i] ?? 0;
+    perm[i] = perm[j] ?? 0;
+    perm[j] = t;
+  }
+  for (let i = 0; i < 256; i++) perm[i + 256] = perm[i] ?? 0;
+  const at = (x: number, y: number, z: number): number =>
+    vals[perm[(perm[(perm[x & 255] ?? 0) + (y & 255)] ?? 0) + (z & 255)] ?? 0] ?? 0;
+  const fade = (t: number): number => t * t * t * (t * (t * 6 - 15) + 10);
+  const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
+  const one = (x: number, y: number, z: number): number => {
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    const zi = Math.floor(z);
+    const u = fade(x - xi);
+    const v = fade(y - yi);
+    const w = fade(z - zi);
+    const plane = (k: number): number =>
+      lerp(
+        lerp(at(xi, yi, k), at(xi + 1, yi, k), u),
+        lerp(at(xi, yi + 1, k), at(xi + 1, yi + 1, k), u),
+        v,
+      );
+    return lerp(plane(zi), plane(zi + 1), w);
+  };
+  const s = 1 / (o.scale ?? 1);
+  const octaves = o.octaves ?? 3;
+  return (p) => {
+    let sum = 0;
+    let amp = 1;
+    let norm = 0;
+    let f = s;
+    for (let i = 0; i < octaves; i++) {
+      sum += amp * one(p[0] * f, p[1] * f, p[2] * f);
+      norm += amp;
+      amp *= 0.5;
+      f *= 2;
+    }
+    return sum / norm;
+  };
+}

package/src/qa/checks.ts

@@ -0,0 +1,110 @@
+// Check builders: a recipe states its physical intent in code and QA enforces it at every LOD.
+//   checks: [clear('track_*', 'hull_*'), noOverlap('road_wheel_l_*'), touches('turret_body', 'hull_top'),
+//            symmetric('_l', '_r', 'y')]
+// Each returns a core `Check`; write your own the same way: (asset) => CheckFinding[].
+
+import type { Check, CheckFinding } from '../core/index.ts';
+import { type Inspector, inspect } from './inspect.ts';
+
+// One inspector per compiled asset, shared by every check (its caches are the speed).
+const inspectors = new WeakMap<object, Inspector>();
+const inspectorFor = (asset: Parameters<Check>[0]): Inspector => {
+  const hit = inspectors.get(asset);
+  if (hit) return hit;
+  const made = inspect(asset);
+  inspectors.set(asset, made);
+  return made;
+};
+
+const CLASH = 0.01;
+
+/** Nothing matching `a` sinks into anything matching `b` (closed solids), with optional min gap. */
+export const clear =
+  (a: string, b: string, minGap = 0): Check =>
+  (asset) => {
+    const q = inspectorFor(asset);
+    const out: CheckFinding[] = [];
+    for (const pa of q.parts(a)) {
+      for (const pb of q.parts(b)) {
+        if (pa === pb) continue;
+        const pen = q.penetration(pa, pb);
+        if (pen.depth > CLASH) {
+          out.push({
+            part: pa,
+            message: `'${pa}' sinks ${(pen.depth * 100).toFixed(1)} cm into '${pb}'`,
+            fix: `move '${pa}' out of '${pb}' (or shrink one); they are declared clear of each other`,
+          });
+        } else if (minGap > 0) {
+          const d = q.distance(pa, pb, minGap);
+          if (d < minGap)
+            out.push({
+              part: pa,
+              message: `'${pa}' is ${(d * 100).toFixed(1)} cm from '${pb}', needs ≥ ${minGap * 100} cm`,
+              fix: 'open the gap — running clearance, mud, suspension travel',
+            });
+        }
+      }
+    }
+    return out;
+  };
+
+/** No two parts matching the selector interpenetrate (interleaved wheels, stacked crates). */
+export const noOverlap =
+  (selector: string): Check =>
+  (asset) => {
+    const names = inspectorFor(asset).parts(selector);
+    return names.flatMap((a, i) => names.slice(i + 1).flatMap((b) => clear(a, b)(asset)));
+  };
+
+/** `a` must touch `b` (surface within 2 cm): a turret sits on its ring, a lamp on its post. */
+export const touches =
+  (a: string, b: string, eps = 0.02): Check =>
+  (asset) => {
+    const q = inspectorFor(asset);
+    // A part dropped at this LOD (detail gating) has nothing to touch: the check doesn't apply.
+    if (q.parts(a).length === 0 || q.parts(b).length === 0) return [];
+    const d = q.distance(a, b, 1);
+    return d <= eps
+      ? []
+      : [
+          {
+            part: a,
+            message: `'${a}' should touch '${b}' but is ${(d * 100).toFixed(1)} cm away`,
+            fix: `seat '${a}' on '${b}'`,
+          },
+        ];
+  };
+
+/** Every part containing `left` has a mirror part (with `right`) reflected across the axis plane. */
+export const symmetric =
+  (left: string, right: string, axis: 'x' | 'y' | 'z' = 'y', tol = 0.02): Check =>
+  (asset) => {
+    const q = inspectorFor(asset);
+    const k = ({ x: 0, y: 1, z: 2 } as const)[axis];
+    // Side tokens are whole name segments: `_l` matches `wheel_l_3` and `rod_l`, never `axle_lead`.
+    const token = new RegExp(`${left.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=_|$)`);
+    return q
+      .parts('*')
+      .filter((n) => token.test(n))
+      .flatMap((l): CheckFinding[] => {
+        const r = l.replace(token, right);
+        const bl = q.bounds(l);
+        const br = q.bounds(r);
+        if (!bl || !br)
+          return [{ part: l, message: `'${l}' has no mirror '${r}'`, fix: `add '${r}' or rename` }];
+        const off = Math.abs(bl.min[k] + br.max[k]) + Math.abs(bl.max[k] + br.min[k]);
+        return off > tol * 2
+          ? [
+              {
+                part: l,
+                message: `'${l}' and '${r}' are not mirrored across ${axis}=0 (off by ${(off * 50).toFixed(1)} cm)`,
+                fix: 'build one side and mirror it — place(mesh, { scale: [1, -1, 1] }) flips winding; prefer reusing the same builder with a sign',
+              },
+            ]
+          : [];
+      });
+  };
+
+/** Run a recipe's checks; the QA gate calls this. */
+export const runChecks = (asset: Parameters<Check>[0]): CheckFinding[] =>
+  asset.checks.flatMap((c) => [...c(asset)]);

package/src/qa/clash.ts

@@ -0,0 +1,177 @@
+// Gate: moving parts never cut through anything. Each motion root (a spinning wheel/axle group, a
+// rotor, a sliding crosshead) is swept through its whole motion; any other part whose surface goes
+// deeper than CLASH_EPS into that swept volume fails — wheel vs fender, prop vs cowling, rod vs frame.
+// Spins sweep a solid of revolution (radius profile per axial slice); sways sweep only their
+// sector (the same profile, kept per 5° angular bin and widened by the swing); slides use the
+// moving mesh's bounds extended along the stroke (one side only for `oneWay`).
+
+import {
+  boundsOf,
+  type CompiledAsset,
+  type Mesh,
+  merge,
+  type Part,
+  type Vec3,
+  worldMeshes,
+  worldTransforms,
+} from '../core/index.ts';
+import { surfaceSamples } from './geometry.ts';
+import { CLASH_EPS, type Finding, type Gate } from './types.ts';
+
+const SLICES = 24;
+
+function subtree(parts: readonly Part[], root: string): Set<string> {
+  const out = new Set([root]);
+  for (const p of parts) if (p.parent && out.has(p.parent)) out.add(p.name);
+  return out;
+}
+
+type Inside = (p: Vec3) => boolean;
+
+/** A swept volume plus its conservative world AABB, so far-away parts and samples skip the test. */
+interface Volume {
+  readonly inside: Inside;
+  readonly min: Vec3;
+  readonly max: Vec3;
+}
+
+const BINS = 72;
+const TAU = Math.PI * 2;
+
+/**
+ * Swept volume of `mesh` rotating about `axis` through `pivot`. `range` (radians, rest = 0)
+ * limits it to a sector; omitted = a full revolution.
+ */
+function spinVolume(
+  mesh: Mesh,
+  pivot: Vec3,
+  axis: Vec3,
+  range?: readonly [number, number],
+): Volume {
+  const len = Math.hypot(...axis) || 1;
+  const u: Vec3 = [axis[0] / len, axis[1] / len, axis[2] / len];
+  // A frame around the axis, for the angle of each point.
+  const ref: Vec3 = Math.abs(u[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0];
+  const dotRef = ref[0] * u[0] + ref[1] * u[1] + ref[2] * u[2];
+  const e1raw: Vec3 = [ref[0] - dotRef * u[0], ref[1] - dotRef * u[1], ref[2] - dotRef * u[2]];
+  const e1l = Math.hypot(...e1raw) || 1;
+  const e1: Vec3 = [e1raw[0] / e1l, e1raw[1] / e1l, e1raw[2] / e1l];
+  const e2: Vec3 = [
+    u[1] * e1[2] - u[2] * e1[1],
+    u[2] * e1[0] - u[0] * e1[2],
+    u[0] * e1[1] - u[1] * e1[0],
+  ];
+  const coords = (p: Vec3): [number, number, number] => {
+    const d: Vec3 = [p[0] - pivot[0], p[1] - pivot[1], p[2] - pivot[2]];
+    const a = d[0] * u[0] + d[1] * u[1] + d[2] * u[2];
+    const x = d[0] * e1[0] + d[1] * e1[1] + d[2] * e1[2];
+    const y = d[0] * e2[0] + d[1] * e2[1] + d[2] * e2[2];
+    return [a, Math.hypot(x, y), Math.atan2(y, x)];
+  };
+  const bin = (phi: number): number =>
+    Math.floor((((phi % TAU) + TAU) % TAU) / (TAU / BINS)) % BINS;
+  const pts = surfaceSamples(mesh, 0.05, 8).map(coords);
+  const lo = Math.min(...pts.map((p) => p[0]));
+  const hi = Math.max(...pts.map((p) => p[0]));
+  const span = Math.max(hi - lo, 1e-6);
+  const slice = (a: number): number => Math.min(SLICES - 1, Math.floor(((a - lo) / span) * SLICES));
+  // radius[slice * BINS + bin]: farthest body sample in that slice and angular bin (rest pose).
+  const radius = new Float64Array(SLICES * BINS).fill(-1);
+  for (const [a, r, phi] of pts) {
+    const k = slice(a) * BINS + bin(phi);
+    radius[k] = Math.max(radius[k] ?? -1, r);
+  }
+  // Bins a rest-pose bin sweeps into: the swing plus one bin of slack either side.
+  const [from, to] = range ?? [0, TAU];
+  const steps = range ? Math.ceil((to - from) / (TAU / BINS)) + 2 : BINS;
+  const reach = Math.max(...radius) + Math.max(Math.abs(lo), Math.abs(hi));
+  return {
+    min: [pivot[0] - reach, pivot[1] - reach, pivot[2] - reach],
+    max: [pivot[0] + reach, pivot[1] + reach, pivot[2] + reach],
+    inside: (p) => {
+      const [a, r, phi] = coords(p);
+      if (a < lo + CLASH_EPS || a > hi - CLASH_EPS) return false;
+      const base = slice(a) * BINS;
+      // p is swept if some rest-pose bin, rotated by θ ∈ [from, to], lands on p's angle.
+      for (let i = 0; i < Math.min(steps, BINS); i++) {
+        const theta = range ? from - TAU / BINS + i * (TAU / BINS) : i * (TAU / BINS);
+        if (r < (radius[base + bin(phi - theta)] ?? -1) - CLASH_EPS) return true;
+      }
+      return false;
+    },
+  };
+}
+
+function slideVolume(mesh: Mesh, offset: Vec3, oneWay = false): Volume {
+  const b = boundsOf(mesh);
+  // Two-sided strokes reach ±offset; one-way strokes reach rest..rest + offset.
+  const neg = (k: number): number =>
+    oneWay ? Math.min(0, offset[k] ?? 0) : -Math.abs(offset[k] ?? 0);
+  const pos = (k: number): number =>
+    oneWay ? Math.max(0, offset[k] ?? 0) : Math.abs(offset[k] ?? 0);
+  const lo = [0, 1, 2].map((k) => (b.min[k] ?? 0) + neg(k) + CLASH_EPS);
+  const hi = [0, 1, 2].map((k) => (b.max[k] ?? 0) + pos(k) - CLASH_EPS);
+  return {
+    min: [lo[0] ?? 0, lo[1] ?? 0, lo[2] ?? 0],
+    max: [hi[0] ?? 0, hi[1] ?? 0, hi[2] ?? 0],
+    inside: (p) => [0, 1, 2].every((k) => (p[k] ?? 0) > (lo[k] ?? 0) && (p[k] ?? 0) < (hi[k] ?? 0)),
+  };
+}
+
+const inBox = (p: Vec3, v: Volume): boolean =>
+  p[0] >= v.min[0] &&
+  p[0] <= v.max[0] &&
+  p[1] >= v.min[1] &&
+  p[1] <= v.max[1] &&
+  p[2] >= v.min[2] &&
+  p[2] <= v.max[2];
+
+export const clashes: Gate = (asset: CompiledAsset): Finding[] => {
+  const meshes = worldMeshes(asset.parts);
+  const xf = worldTransforms(asset.parts);
+  const findings: Finding[] = [];
+  for (const root of asset.parts.filter((p) => p.motion)) {
+    const moving = subtree(asset.parts, root.name);
+    const body = merge([...moving].flatMap((n) => meshes.get(n) ?? []));
+    const t = xf.get(root.name);
+    if (!t || body.indices.length === 0 || !root.motion) continue;
+    const c = Math.cos(t.yaw);
+    const s = Math.sin(t.yaw);
+    const rot = (v: Vec3): Vec3 => [v[0] * c - v[1] * s, v[0] * s + v[1] * c, v[2]];
+    const m = root.motion;
+    const peak = m.kind === 'sway' ? (m.degrees * Math.PI) / 180 : 0;
+    const vol =
+      m.kind === 'slide'
+        ? slideVolume(body, rot(m.offset), m.oneWay)
+        : m.kind === 'sway'
+          ? spinVolume(body, t.origin, rot(m.axis), m.oneWay ? [0, peak] : [-peak, peak])
+          : spinVolume(body, t.origin, rot(m.axis));
+    for (const [name, mesh] of meshes) {
+      if (moving.has(name) || root.clearOf?.includes(name)) continue;
+      const b = boundsOf(mesh);
+      if (
+        !inBox(b.min, {
+          ...vol,
+          min: [
+            vol.min[0] - (b.max[0] - b.min[0]),
+            vol.min[1] - (b.max[1] - b.min[1]),
+            vol.min[2] - (b.max[2] - b.min[2]),
+          ],
+        })
+      )
+        continue;
+      const hits = surfaceSamples(mesh, 0.1, 4).filter(
+        (p) => inBox(p, vol) && vol.inside(p),
+      ).length;
+      if (hits > 0) {
+        findings.push({
+          gate: 'clashes',
+          part: name,
+          message: `'${name}' cuts into the swept ${root.motion.kind} of '${root.name}' (${hits} sample${hits === 1 ? '' : 's'} deeper than ${CLASH_EPS * 100} cm)`,
+          fix: `move/trim '${name}' or '${root.name}' for running clearance; if they are meant to interlock (an axle through its bearing), list it: clearOf: ['${name}'] on '${root.name}'`,
+        });
+      }
+    }
+  }
+  return findings;
+};

package/src/qa/floating.ts

@@ -0,0 +1,63 @@
+// Gate: everything is attached. A part is grounded if it reaches z≈0 or its SURFACE comes within
+// CONTACT_EPS of a grounded part's surface — transitively. Bounding boxes are only the prefilter.
+
+import {
+  type Bounds,
+  boundsOf,
+  type CompiledAsset,
+  type Mesh,
+  worldMeshes,
+} from '../core/index.ts';
+import { surfaceSamples, TriangleGrid } from './geometry.ts';
+import { CONTACT_EPS, type Finding, type Gate } from './types.ts';
+
+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,
+  );
+
+export function touching(a: Mesh, b: Mesh, grid: TriangleGrid, eps = CONTACT_EPS): boolean {
+  const bb = boundsOf(b);
+  for (const p of surfaceSamples(a, 0.1, 4)) {
+    if (!near({ min: p, max: p }, bb, eps)) continue;
+    if (grid.nearest(p, eps) <= eps) return true;
+  }
+  return false;
+}
+
+export const floatingParts: Gate = (asset: CompiledAsset): Finding[] => {
+  const meshes = [...worldMeshes(asset.parts)];
+  const bounds = new Map(meshes.map(([n, m]) => [n, boundsOf(m)]));
+  const grids = new Map<string, TriangleGrid>();
+  const grid = (n: string, m: Mesh): TriangleGrid => {
+    const g = grids.get(n) ?? new TriangleGrid(m);
+    grids.set(n, g);
+    return g;
+  };
+  const grounded = new Set(
+    meshes.filter(([n]) => (bounds.get(n)?.min[2] ?? 1) <= CONTACT_EPS).map(([n]) => n),
+  );
+  const frontier = [...grounded];
+  while (frontier.length > 0) {
+    const g = frontier.pop() ?? '';
+    const gm = meshes.find(([n]) => n === g)?.[1];
+    const gb = bounds.get(g);
+    if (!gm || !gb) continue;
+    for (const [n, m] of meshes) {
+      const b = bounds.get(n);
+      if (grounded.has(n) || !b || !near(b, gb, CONTACT_EPS)) continue;
+      if (touching(m, gm, grid(g, gm)) || touching(gm, m, grid(n, m))) {
+        grounded.add(n);
+        frontier.push(n);
+      }
+    }
+  }
+  return meshes
+    .filter(([n]) => !grounded.has(n))
+    .map(([n]) => ({
+      gate: 'floating-parts',
+      part: n,
+      message: `'${n}' has no surface within ${CONTACT_EPS * 100} cm of anything attached to the ground`,
+      fix: 'move it onto what holds it (check `at`, parent and the LOD-gated detail around it) — bounding boxes touching is not enough',
+    }));
+};