@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/passes/weighted-normals.ts

@@ -0,0 +1,125 @@
+// Face-weighted vertex normals with a hard-edge split: the mid-poly hard-surface look. Each corner
+// averages the face normals around its position, weighted by face area × corner angle, but only
+// over faces within `hardAngle` of its own face. Big flat faces dominate, so a bevelled box keeps
+// dead-flat sides while its bevels bend the light into soft highlights — no normal map needed.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+
+export interface WeightedNormalsOptions {
+  /** Faces meeting at more than this many degrees keep a hard edge. Default 40. */
+  readonly hardAngle?: number;
+  /** Positions closer than this (metres) count as one point. Default 1e-5. */
+  readonly epsilon?: number;
+}
+
+interface Corner {
+  readonly n: Vec3;
+  readonly w: number;
+}
+
+function faceData(m: Mesh, t: number): { n: Vec3; area: number; angles: Vec3 } {
+  const p = (k: number): Vec3 => {
+    const i = (m.indices[t * 3 + k] ?? 0) * 3;
+    return [m.positions[i] ?? 0, m.positions[i + 1] ?? 0, m.positions[i + 2] ?? 0];
+  };
+  const v = [p(0), p(1), p(2)] as const;
+  const e = (a: Vec3, b: Vec3): Vec3 => [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+  const u = e(v[0], v[1]);
+  const w = e(v[0], v[2]);
+  const g: Vec3 = [u[1] * w[2] - u[2] * w[1], u[2] * w[0] - u[0] * w[2], u[0] * w[1] - u[1] * w[0]];
+  const len = Math.hypot(...g);
+  const angle = (k: number): number => {
+    const a = e(v[k] ?? v[0], v[(k + 1) % 3] ?? v[0]);
+    const b = e(v[k] ?? v[0], v[(k + 2) % 3] ?? v[0]);
+    const d = Math.hypot(...a) * Math.hypot(...b);
+    return d
+      ? Math.acos(Math.max(-1, Math.min(1, (a[0] * b[0] + a[1] * b[1] + a[2] * b[2]) / d)))
+      : 0;
+  };
+  return {
+    n: len ? [g[0] / len, g[1] / len, g[2] / len] : [0, 0, 0],
+    area: len / 2,
+    angles: [angle(0), angle(1), angle(2)],
+  };
+}
+
+export function weightedNormals(m: Mesh, o: WeightedNormalsOptions = {}): Mesh {
+  const cosHard = Math.cos(((o.hardAngle ?? 40) * Math.PI) / 180);
+  const eps = o.epsilon ?? 1e-5;
+  const tris = m.indices.length / 3;
+  const corners: Corner[] = [];
+  for (let t = 0; t < tris; t++) {
+    const f = faceData(m, t);
+    for (let k = 0; k < 3; k++) corners.push({ n: f.n, w: f.area * (f.angles[k] ?? 0) });
+  }
+  // Group corners by quantised position (insertion order — deterministic).
+  const groups = new Map<string, number[]>();
+  const keyOf = (i: number): string =>
+    [0, 1, 2].map((k) => Math.round((m.positions[i * 3 + k] ?? 0) / eps)).join(',');
+  for (let c = 0; c < corners.length; c++) {
+    const key = keyOf(m.indices[c] ?? 0);
+    const g = groups.get(key);
+    if (g) g.push(c);
+    else groups.set(key, [c]);
+  }
+  const normal = new Float32Array(corners.length * 3);
+  for (const g of groups.values())
+    for (const c of g) {
+      const me = corners[c];
+      if (!me) continue;
+      let x = 0;
+      let y = 0;
+      let z = 0;
+      for (const d of g) {
+        const o2 = corners[d];
+        if (!o2 || me.n[0] * o2.n[0] + me.n[1] * o2.n[1] + me.n[2] * o2.n[2] < cosHard) continue;
+        x += o2.n[0] * o2.w;
+        y += o2.n[1] * o2.w;
+        z += o2.n[2] * o2.w;
+      }
+      const len = Math.hypot(x, y, z);
+      // A degenerate face keeps its original normal.
+      const src = (m.indices[c] ?? 0) * 3;
+      normal.set(
+        len > 1e-12
+          ? [x / len, y / len, z / len]
+          : [m.normals[src] ?? 0, m.normals[src + 1] ?? 0, m.normals[src + 2] ?? 0],
+        c * 3,
+      );
+    }
+  return splitByNormal(m, normal);
+}
+
+/** One output vertex per (input vertex, distinct new normal); first appearance order. */
+function splitByNormal(m: Mesh, cornerNormals: Float32Array): Mesh {
+  const seen = new Map<string, number>();
+  const p: number[] = [];
+  const n: number[] = [];
+  const uv: number[] = [];
+  const col: number[] = [];
+  const idx = new Uint32Array(m.indices.length);
+  for (let c = 0; c < m.indices.length; c++) {
+    const v = m.indices[c] ?? 0;
+    const nx = cornerNormals[c * 3] ?? 0;
+    const ny = cornerNormals[c * 3 + 1] ?? 0;
+    const nz = cornerNormals[c * 3 + 2] ?? 0;
+    const key = `${v}:${Math.round(nx * 1e4)},${Math.round(ny * 1e4)},${Math.round(nz * 1e4)}`;
+    let out = seen.get(key);
+    if (out === undefined) {
+      out = p.length / 3;
+      seen.set(key, out);
+      p.push(m.positions[v * 3] ?? 0, m.positions[v * 3 + 1] ?? 0, m.positions[v * 3 + 2] ?? 0);
+      n.push(nx, ny, nz);
+      uv.push(m.uvs[v * 2] ?? 0, m.uvs[v * 2 + 1] ?? 0);
+      col.push(m.colors[v * 3] ?? 0, m.colors[v * 3 + 1] ?? 0, m.colors[v * 3 + 2] ?? 0);
+    }
+    idx[c] = out;
+  }
+  return {
+    positions: new Float32Array(p),
+    normals: new Float32Array(n),
+    uvs: new Float32Array(uv),
+    colors: new Float32Array(col),
+    indices: idx,
+  };
+}

package/src/primitives/beam.ts

@@ -0,0 +1,60 @@
+// A member between two points: girders, rods, rails, handrails, masts, tow cables, antennae.
+// Square section by default; `segments` ≥ 3 makes it round (pipes, barrels, rods).
+
+import {
+  applyAffine,
+  cross,
+  frame,
+  length,
+  type Mesh,
+  normalize,
+  sub,
+  type Vec3,
+} from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { box } from './box.ts';
+import { lathe } from './lathe.ts';
+
+export interface BeamOptions {
+  readonly from: Vec3;
+  readonly to: Vec3;
+  /** Side of a square section, or diameter of a round one. */
+  readonly width: number;
+  readonly height?: number;
+  readonly segments?: number;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  /** Which way the section's local Y faces (roll). Default: world Z, or X for vertical beams. */
+  readonly up?: Vec3;
+  /** End caps; turn off for lattice members whose ends are buried in joints (−⅓ triangles). */
+  readonly caps?: boolean;
+}
+
+export function beam(o: BeamOptions): Mesh {
+  const dir = sub(o.to, o.from);
+  const len = length(dir);
+  const w = normalize(dir);
+  const ref: Vec3 = o.up ?? (Math.abs(w[2]) > 0.95 ? [1, 0, 0] : [0, 0, 1]);
+  const u = normalize(cross(ref, w));
+  const v = cross(w, u);
+  // Local Z runs from→to, so the section is built standing on the origin.
+  const local =
+    o.segments && o.segments >= 3
+      ? lathe({
+          profile: [
+            [o.width / 2, 0],
+            [o.width / 2, len],
+          ],
+          segments: o.segments,
+          color: o.color,
+          caps: o.caps ?? true,
+          ...(o.strip ? { strip: o.strip } : {}),
+        })
+      : box({
+          size: [o.width, o.height ?? o.width, len],
+          ...(o.caps === false ? { omit: ['top', 'bottom'] as const } : {}),
+          color: o.color,
+          ...(o.strip ? { strip: o.strip } : {}),
+        });
+  return applyAffine(local, frame(u, v, w, o.from));
+}

package/src/primitives/bevel-box.ts

@@ -0,0 +1,140 @@
+// A box with every edge chamfered once (`box({ bevel })`): the hard-surface "mid-poly" look. Six
+// faces shrink by `bevel`, 12 chamfer quads take the 45° normal and 8 corner triangles the
+// 3-axis diagonal, all flat per face (own vertices), so a face-weighted-normal pass turns the
+// chamfers into rounded highlights without a bake. UVs: every vertex keeps its own face's mapping
+// (the box's), so the thin chamfer reuses the nearest face's strip texels.
+//   triangles = 44 − 2 per omitted face
+
+import { type Mesh, MeshBuilder, normalize, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+
+type Sign = 1 | -1;
+type FaceName = 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right';
+
+/** Face axes as in box.ts: index = axis * 2 + (sign > 0 ? 0 : 1). */
+const FACES: readonly { name: FaceName; u: Vec3; v: Vec3 }[] = [
+  { name: 'front', u: [0, 1, 0], v: [0, 0, 1] },
+  { name: 'back', u: [0, -1, 0], v: [0, 0, 1] },
+  { name: 'left', u: [-1, 0, 0], v: [0, 0, 1] },
+  { name: 'right', u: [1, 0, 0], v: [0, 0, 1] },
+  { name: 'top', u: [1, 0, 0], v: [0, 1, 0] },
+  { name: 'bottom', u: [1, 0, 0], v: [0, -1, 0] },
+];
+const SIGNS: readonly Sign[] = [-1, 1];
+
+export interface BevelBoxInput {
+  readonly half: Vec3;
+  readonly centre: Vec3;
+  readonly bevel: number;
+  readonly color: Vec3;
+  readonly strip: StripId;
+  readonly omit: readonly FaceName[];
+}
+
+export function bevelBox(o: BevelBoxInput): Mesh {
+  const { half, centre, bevel: bv } = o;
+  const rect = stripRect(o.strip);
+  const b = new MeshBuilder();
+  const dot3 = (a: Vec3, c: Vec3): number => a[0] * c[0] + a[1] * c[1] + a[2] * c[2];
+  const ext = (a: Vec3): number =>
+    Math.abs(a[0]) * half[0] + Math.abs(a[1]) * half[1] + Math.abs(a[2]) * half[2];
+  /** Corner s on the face of axis k: inset by the bevel on the two other axes. */
+  const point = (s: readonly Sign[], k: number): Vec3 => [
+    centre[0] + (s[0] ?? 1) * (half[0] - (k === 0 ? 0 : bv)),
+    centre[1] + (s[1] ?? 1) * (half[1] - (k === 1 ? 0 : bv)),
+    centre[2] + (s[2] ?? 1) * (half[2] - (k === 2 ? 0 : bv)),
+  ];
+  const put = (s: readonly Sign[], k: number, n: Vec3): number => {
+    const f = FACES[k * 2 + ((s[k] ?? 1) > 0 ? 0 : 1)] ?? { u: n, v: n };
+    const p = point(s, k);
+    const rel: Vec3 = [p[0] - centre[0], p[1] - centre[1], p[2] - centre[2]];
+    const eu = ext(f.u);
+    const ev = ext(f.v);
+    return b.vertex({
+      p,
+      n,
+      uv: [
+        rect.u0 + ((dot3(rel, f.u) + eu) / rect.metres) * (rect.u1 - rect.u0),
+        rect.v0 + ((dot3(rel, f.v) + ev) / (2 * ev)) * (rect.v1 - rect.v0),
+      ],
+      color: o.color,
+    });
+  };
+  /** Emit a polygon, flipping it if its winding disagrees with the outward normal. */
+  const poly = (corners: readonly (readonly [readonly Sign[], number])[], n: Vec3): void => {
+    const pts = corners.map(([s, k]) => point(s, k));
+    const [a = n, c = n, d = n] = pts;
+    const e1: Vec3 = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+    const e2: Vec3 = [d[0] - a[0], d[1] - a[1], d[2] - a[2]];
+    const g: Vec3 = [
+      e1[1] * e2[2] - e1[2] * e2[1],
+      e1[2] * e2[0] - e1[0] * e2[2],
+      e1[0] * e2[1] - e1[1] * e2[0],
+    ];
+    const ids = corners.map(([s, k]) => put(s, k, n));
+    if (dot3(g, n) < 0) ids.reverse();
+    const [i0 = 0, i1 = 0, i2 = 0, i3] = ids;
+    if (i3 === undefined) b.tri(i0, i1, i2);
+    else b.quad(i0, i1, i2, i3);
+  };
+  const unit = (k: number, s: number): Vec3 => [k === 0 ? s : 0, k === 1 ? s : 0, k === 2 ? s : 0];
+  const corner = (k: number, sk: Sign, l: number, sl: Sign, m: number, sm: Sign): Sign[] => {
+    const s: Sign[] = [1, 1, 1];
+    s[k] = sk;
+    s[l] = sl;
+    s[m] = sm;
+    return s;
+  };
+  // Faces (axis k, sign sk): four corners in a ring over the other two axes.
+  for (let k = 0; k < 3; k++) {
+    const [l, m] = [(k + 1) % 3, (k + 2) % 3];
+    for (const sk of SIGNS) {
+      if (o.omit.includes((FACES[k * 2 + (sk > 0 ? 0 : 1)] ?? { name: 'top' }).name)) continue;
+      const ring = (
+        [
+          [-1, -1],
+          [1, -1],
+          [1, 1],
+          [-1, 1],
+        ] as const
+      ).map(([a, c]) => [corner(k, sk, l, a, m, c), k] as const);
+      poly(ring, unit(k, sk));
+    }
+  }
+  // Chamfers along axis m between the faces of axes k and l.
+  for (let m = 0; m < 3; m++) {
+    const [k, l] = [(m + 1) % 3, (m + 2) % 3];
+    for (const sk of SIGNS)
+      for (const sl of SIGNS) {
+        const lo = corner(k, sk, l, sl, m, -1);
+        const hi = corner(k, sk, l, sl, m, 1);
+        const n = normalize(
+          [0, 1, 2].map((j) => (j === k ? sk : j === l ? sl : 0)) as unknown as Vec3,
+        );
+        poly(
+          [
+            [lo, k],
+            [hi, k],
+            [hi, l],
+            [lo, l],
+          ],
+          n,
+        );
+      }
+  }
+  // Corners: one triangle across the three face corners.
+  for (const sx of SIGNS)
+    for (const sy of SIGNS)
+      for (const sz of SIGNS) {
+        const s: Sign[] = [sx, sy, sz];
+        poly(
+          [
+            [s, 0],
+            [s, 1],
+            [s, 2],
+          ],
+          normalize([sx, sy, sz]),
+        );
+      }
+  return b.build();
+}

package/src/primitives/box.ts

@@ -0,0 +1,90 @@
+// Axis-aligned box, base at z=0 (things stand on the ground). UVs tile a trim strip by metres.
+// Flat normals. `bevel` > 0 chamfers every edge once (bevel-box.ts); 0 keeps these exact bytes.
+
+import { type Mesh, MeshBuilder, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { bevelBox } from './bevel-box.ts';
+import { invalid } from './check.ts';
+
+export interface BoxOptions {
+  /** Width (X), depth (Y), height (Z) in metres. */
+  readonly size: Vec3;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  /** Centre of the base face. */
+  readonly at?: Vec3;
+  /** Skip faces nobody sees (e.g. the bottom on the ground). */
+  readonly omit?: readonly ('top' | 'bottom' | 'front' | 'back' | 'left' | 'right')[];
+  /** Chamfer width in metres on every edge (12 + 8 extra faces, 44 triangles). LOD it:
+   *  `bevel: ctx.pick([0.02, 0.01, 0])`. Must stay under half the smallest size. Default 0. */
+  readonly bevel?: number;
+}
+
+type Face = { name: NonNullable<BoxOptions['omit']>[number]; n: Vec3; u: Vec3; v: Vec3 };
+const FACES: readonly Face[] = [
+  { name: 'front', n: [1, 0, 0], u: [0, 1, 0], v: [0, 0, 1] },
+  { name: 'back', n: [-1, 0, 0], u: [0, -1, 0], v: [0, 0, 1] },
+  { name: 'right', n: [0, -1, 0], u: [1, 0, 0], v: [0, 0, 1] },
+  { name: 'left', n: [0, 1, 0], u: [-1, 0, 0], v: [0, 0, 1] },
+  { name: 'top', n: [0, 0, 1], u: [1, 0, 0], v: [0, 1, 0] },
+  { name: 'bottom', n: [0, 0, -1], u: [1, 0, 0], v: [0, -1, 0] },
+];
+
+export function box(o: BoxOptions): Mesh {
+  const [w, d, h] = o.size;
+  const [cx, cy, cz] = o.at ?? [0, 0, 0];
+  const half: Vec3 = [w / 2, d / 2, h / 2];
+  const centre: Vec3 = [cx, cy, cz + h / 2];
+  const bevel = o.bevel ?? 0;
+  if (bevel !== 0) {
+    const limit = Math.min(w, d, h) / 2;
+    if (!(bevel > 0 && bevel < limit))
+      invalid(
+        `box bevel ${bevel} m does not fit a ${w} × ${d} × ${h} m box`,
+        `use 0 < bevel < ${limit} m (half the smallest size), e.g. ${Math.min(0.02, limit / 4)}`,
+      );
+    return bevelBox({
+      half,
+      centre,
+      bevel,
+      color: o.color,
+      strip: o.strip ?? 'plain',
+      omit: o.omit ?? [],
+    });
+  }
+  const rect = stripRect(o.strip ?? 'plain');
+  const b = new MeshBuilder();
+  for (const f of FACES) {
+    if (o.omit?.includes(f.name)) continue;
+    const extent = (axis: Vec3): number =>
+      Math.abs(axis[0]) * half[0] + Math.abs(axis[1]) * half[1] + Math.abs(axis[2]) * half[2];
+    const eu = extent(f.u);
+    const ev = extent(f.v);
+    const en = extent(f.n);
+    const ids = [
+      [-1, -1],
+      [1, -1],
+      [1, 1],
+      [-1, 1],
+    ].map(([su = 0, sv = 0]) => {
+      const p: Vec3 = [0, 1, 2].map(
+        (k) =>
+          (centre[k] ?? 0) + (f.n[k] ?? 0) * en + (f.u[k] ?? 0) * eu * su + (f.v[k] ?? 0) * ev * sv,
+      ) as unknown as Vec3;
+      const uMetres = ((su + 1) / 2) * eu * 2;
+      const vFrac = (sv + 1) / 2;
+      return b.vertex({
+        p,
+        n: f.n,
+        uv: [
+          rect.u0 + (uMetres / rect.metres) * (rect.u1 - rect.u0),
+          rect.v0 + vFrac * (rect.v1 - rect.v0),
+        ],
+        color: o.color,
+      });
+    });
+    const [a = 0, c = 0, e = 0, g = 0] = ids;
+    b.quad(a, c, e, g);
+  }
+  return b.build();
+}

package/src/primitives/cell.ts

@@ -0,0 +1,115 @@
+// A quad mapped to ONE fixed trim-sheet cell: windows, doors, clocks, signs, leaf cards. Flat
+// normal u × v; V grows along `v` (keep `v` world-up so the decal stands upright).
+// `inset` > 0 recesses the panel by that depth behind the face plane and closes the gap with four
+// reveal faces (jambs, head, sill) mapped at true scale onto `reveal`: real depth that catches
+// light and shadow, the cheapest trick that makes a facade read as built. `inset` < 0 raises it
+// proud of the plane instead (plaques, sign boards), sides facing out.
+// The surrounding wall must leave the opening free (build it from tiled pieces around it).
+//   triangles = (doubleSided ? 4 : 2) + (inset ≠ 0 ? 8 : 0)
+
+import { type Mesh, MeshBuilder, normalize, type Vec3 } from '../core/index.ts';
+import { type CellId, cellRect, type StripId, stripRect } from '../material/index.ts';
+import { invalid, spanOf } from './check.ts';
+import { HALF_TEXEL, stripU, stripV, stripVMetres } from './strip-uv.ts';
+
+export interface CellOptions {
+  /** Bottom-left corner as seen from the front. */
+  readonly origin: Vec3;
+  /** Width edge (cell U), metres. */
+  readonly u: Vec3;
+  /** Height edge (cell V, up), metres. */
+  readonly v: Vec3;
+  readonly color: Vec3;
+  readonly cell: CellId;
+  /** Recess depth in metres (> 0 behind the plane, < 0 proud of it). Default 0. */
+  readonly inset?: number;
+  /** Strip the reveal faces tile at true scale. Default 'plain'. */
+  readonly reveal?: StripId;
+  readonly revealColor?: Vec3;
+  /** Both sides (leaf cards, hanging signs). Not with an inset. */
+  readonly doubleSided?: boolean;
+}
+
+const add3 = (a: Vec3, b: Vec3, s: number): Vec3 => [
+  a[0] + b[0] * s,
+  a[1] + b[1] * s,
+  a[2] + b[2] * s,
+];
+
+export function cell(o: CellOptions): Mesh {
+  const { lu, lv, n } = spanOf('cell', o.origin, o.u, o.v);
+  const d = o.inset ?? 0;
+  if (!Number.isFinite(d))
+    invalid(`cell inset is ${d}`, 'use a finite depth in metres (0.1 = a 10 cm recess)');
+  if (d !== 0 && o.doubleSided)
+    invalid(
+      'cell: inset with doubleSided',
+      'drop doubleSided for a recessed/raised panel, or set inset: 0',
+    );
+  const r = cellRect(o.cell);
+  const e = HALF_TEXEL;
+  const rim: Vec3[] = [
+    o.origin,
+    add3(o.origin, o.u, 1),
+    add3(add3(o.origin, o.u, 1), o.v, 1),
+    add3(o.origin, o.v, 1),
+  ];
+  const face = rim.map((p) => add3(p, n, -d));
+  const uvs: [number, number][] = [
+    [r.u0 + e, r.v0 + e],
+    [r.u1 - e, r.v0 + e],
+    [r.u1 - e, r.v1 - e],
+    [r.u0 + e, r.v1 - e],
+  ];
+  const b = new MeshBuilder();
+  for (const side of o.doubleSided ? [1, -1] : [1]) {
+    const nn: Vec3 = [n[0] * side, n[1] * side, n[2] * side];
+    const [i0 = 0, i1 = 0, i2 = 0, i3 = 0] = face.map((p, k) =>
+      b.vertex({ p, n: nn, uv: uvs[k] ?? [0, 0], color: o.color }),
+    );
+    if (side > 0) b.quad(i0, i1, i2, i3);
+    else b.quad(i0, i3, i2, i1);
+  }
+  if (d !== 0) reveals(b, o, rim, face, n, d, [lu, lv, lu, lv]);
+  return b.build();
+}
+
+/** Four side quads rim[i] → rim[i+1] → face[i+1] → face[i]; that order is CCW for either sign. */
+function reveals(
+  b: MeshBuilder,
+  o: CellOptions,
+  rim: readonly Vec3[],
+  face: readonly Vec3[],
+  n: Vec3,
+  d: number,
+  lens: readonly number[],
+): void {
+  const strip = o.reveal ?? 'plain';
+  const rect = stripRect(strip);
+  const fv = Math.min(1, Math.abs(d) / stripVMetres(strip));
+  const color = o.revealColor ?? o.color;
+  for (let i = 0; i < 4; i++) {
+    const a = rim[i] ?? n;
+    const c = rim[(i + 1) % 4] ?? n;
+    const ed: Vec3 = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+    // n × edge points into the opening; a recess faces inward, a plaque's sides outward.
+    const s = Math.sign(d);
+    const nn = normalize([
+      (n[1] * ed[2] - n[2] * ed[1]) * s,
+      (n[2] * ed[0] - n[0] * ed[2]) * s,
+      (n[0] * ed[1] - n[1] * ed[0]) * s,
+    ]);
+    const len = lens[i] ?? 0;
+    const q = [a, c, face[(i + 1) % 4] ?? c, face[i] ?? a];
+    const uv: [number, number][] = [
+      [stripU(rect, 0), stripV(rect, 0)],
+      [stripU(rect, len), stripV(rect, 0)],
+      [stripU(rect, len), stripV(rect, fv)],
+      [stripU(rect, 0), stripV(rect, fv)],
+    ];
+    const [j0 = 0, j1 = 0, j2 = 0, j3 = 0] = q.map((p, k) =>
+      b.vertex({ p, n: nn, uv: uv[k] ?? [0, 0], color }),
+    );
+    b.quad(j0, j1, j2, j3);
+  }
+}

package/src/primitives/check.ts

@@ -0,0 +1,49 @@
+// Input guards shared by primitives: every bad option throws T3D_RECIPE_INVALID with the fix, so
+// an agent reads what to change instead of debugging NaN geometry downstream.
+
+import { cross, length, Ts23dError, type Vec3 } from '../core/index.ts';
+
+export function invalid(cause: string, fix: string): never {
+  throw new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+}
+
+const finite = (v: Vec3): boolean => v.every(Number.isFinite);
+
+/** Two edge vectors spanning a real parallelogram; returns |u|, |v| and the unit normal u×v. */
+export function spanOf(
+  what: string,
+  origin: Vec3,
+  u: Vec3,
+  v: Vec3,
+): { lu: number; lv: number; n: Vec3 } {
+  if (!finite(origin) || !finite(u) || !finite(v))
+    invalid(`${what}: origin/u/v has a NaN or Infinity`, 'pass finite metre vectors');
+  const lu = length(u);
+  const lv = length(v);
+  if (lu < 1e-9 || lv < 1e-9)
+    invalid(
+      `${what}: edge u (${lu} m) or v (${lv} m) has zero length`,
+      'give u and v the face edges in metres, both non-zero (e.g. u: [4, 0, 0], v: [0, 0, 3])',
+    );
+  const c = cross(u, v);
+  const lc = length(c);
+  if (lc < 1e-6 * lu * lv)
+    invalid(
+      `${what}: u and v are parallel, so the face has no area`,
+      'make v perpendicular to u (u along the face, v up it)',
+    );
+  return { lu, lv, n: [c[0] / lc, c[1] / lc, c[2] / lc] };
+}
+
+/** An integer count in [min, max]. */
+export function count(what: string, n: number, min: number, max: number): number {
+  if (!Number.isInteger(n) || n < min || n > max)
+    invalid(`${what} is ${n}`, `use a whole number from ${min} to ${max}`);
+  return n;
+}
+
+/** A finite number > 0. */
+export function positive(what: string, n: number, example: string): number {
+  if (!Number.isFinite(n) || n <= 0) invalid(`${what} is ${n}`, `use a length > 0 m (${example})`);
+  return n;
+}

package/src/primitives/closed.ts

@@ -0,0 +1,74 @@
+// Closed-surface checks for primitives that claim watertight output (bevelled box, sdf). Weld by
+// position (flat faces own their vertices); a surface is closed and consistently wound when every
+// edge is walked as often a→b as b→a. Non-manifold edges (surface nets on sub-cell features) are
+// counted separately. Internal; tests use them.
+
+import type { Mesh } from '../core/index.ts';
+
+/** Undirected edges walked a different number of times a→b than b→a (0 = closed, oriented). */
+export function openEdges(m: Mesh): number {
+  const key = (i: number): string =>
+    `${Math.round((m.positions[i * 3] ?? 0) * 1e4)},${Math.round((m.positions[i * 3 + 1] ?? 0) * 1e4)},${Math.round((m.positions[i * 3 + 2] ?? 0) * 1e4)}`;
+  const edges = new Map<string, number>();
+  for (let t = 0; t < m.indices.length; t += 3) {
+    for (let j = 0; j < 3; j++) {
+      const a = key(m.indices[t + j] ?? 0);
+      const b = key(m.indices[t + ((j + 1) % 3)] ?? 0);
+      if (a !== b) edges.set(`${a}>${b}`, (edges.get(`${a}>${b}`) ?? 0) + 1);
+    }
+  }
+  let open = 0;
+  for (const [e, n] of edges) {
+    const [a, b] = e.split('>');
+    if (edges.get(`${b}>${a}`) !== n) open++;
+  }
+  return open;
+}
+
+/** Directed edges used more than once: 0 = 2-manifold (given openEdges = 0). */
+export function nonManifoldEdges(m: Mesh): number {
+  const key = (i: number): string =>
+    `${Math.round((m.positions[i * 3] ?? 0) * 1e4)},${Math.round((m.positions[i * 3 + 1] ?? 0) * 1e4)},${Math.round((m.positions[i * 3 + 2] ?? 0) * 1e4)}`;
+  const seen = new Map<string, number>();
+  for (let t = 0; t < m.indices.length; t += 3)
+    for (let j = 0; j < 3; j++) {
+      const e = `${key(m.indices[t + j] ?? 0)}>${key(m.indices[t + ((j + 1) % 3)] ?? 0)}`;
+      seen.set(e, (seen.get(e) ?? 0) + 1);
+    }
+  let bad = 0;
+  for (const n of seen.values()) if (n > 1) bad++;
+  return bad;
+}
+
+/**
+ * Triangles whose winding (b − a) × (c − a) clearly disagrees with their mean vertex normal
+ * (cosine < −0.1; inside-out scores ≈ −1). Slivers whose face normal lies in the surface
+ * (cosine ≈ 0, e.g. surface nets at sub-cell features) are orientation-ambiguous, not counted.
+ */
+export function windingFlips(m: Mesh): number {
+  let bad = 0;
+  const P = m.positions;
+  const N = m.normals;
+  for (let t = 0; t < m.indices.length; t += 3) {
+    const a = (m.indices[t] ?? 0) * 3;
+    const b = (m.indices[t + 1] ?? 0) * 3;
+    const c = (m.indices[t + 2] ?? 0) * 3;
+    const e = [0, 1, 2].map((k) => (P[b + k] ?? 0) - (P[a + k] ?? 0));
+    const f = [0, 1, 2].map((k) => (P[c + k] ?? 0) - (P[a + k] ?? 0));
+    const g = [
+      (e[1] ?? 0) * (f[2] ?? 0) - (e[2] ?? 0) * (f[1] ?? 0),
+      (e[2] ?? 0) * (f[0] ?? 0) - (e[0] ?? 0) * (f[2] ?? 0),
+      (e[0] ?? 0) * (f[1] ?? 0) - (e[1] ?? 0) * (f[0] ?? 0),
+    ];
+    let s = 0;
+    let nn = 0;
+    for (let k = 0; k < 3; k++) {
+      const m = (N[a + k] ?? 0) + (N[b + k] ?? 0) + (N[c + k] ?? 0);
+      s += (g[k] ?? 0) * m;
+      nn += m * m;
+    }
+    const gl = Math.hypot(g[0] ?? 0, g[1] ?? 0, g[2] ?? 0);
+    if (gl > 0 && nn > 0 && s / (gl * Math.sqrt(nn)) < -0.1) bad++;
+  }
+  return bad;
+}