@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/primitives/lattice.ts

@@ -0,0 +1,131 @@
+// A truss between two points: bridges, girders, crane jibs, signal gantries, pylons, towers.
+// Planar (two chords) or, with `width`, a box truss (four chords, every face braced). Members are
+// square tubes or angle iron with flat normals, written into one builder. `from → to` is the
+// base chord (or the centreline with `centred`); `depth` rises along `up`. Patterns per bay:
+//   warren  /\/\/\  diagonals only       pratt  |\|\|/|/|  verticals, diagonals down to centre
+//   howe    |/|/|\|\|  the reverse       x      |X|X|X|    verticals + both diagonals
+// Pratt/Howe put an X in the middle bay when `bays` is odd. LOD knobs: `bays`, `section`, and
+// dropping `width` (box → planar), chosen by the recipe with ctx.pick.
+//   triangles = chords·(S + C) + faces·web·S    S = 8 square | 12 angle, C = 4 | 8 (end caps)
+//   chords = 2 | 4, faces = 1 | 4, web = warren k · pratt/howe 2k + 1 + (k odd) · x 3k + 1
+
+import { type Mesh, MeshBuilder, normalize, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { count, invalid, positive } from './check.ts';
+import { emitMember, type SectionKind, section } from './member.ts';
+
+export type TrussPattern = 'warren' | 'pratt' | 'howe' | 'x';
+
+export interface LatticeOptions {
+  readonly from: Vec3;
+  readonly to: Vec3;
+  /** Chord-to-chord height in metres (at `from`; `depthEnd` tapers it toward `to`). */
+  readonly depth: number;
+  readonly depthEnd?: number;
+  /** Box truss: chord spacing across, metres (and `widthEnd`). Omit for a planar truss. */
+  readonly width?: number;
+  readonly widthEnd?: number;
+  /** Which way depth rises. Default world Z (world X for a vertical truss). */
+  readonly up?: Vec3;
+  readonly centred?: boolean;
+  readonly pattern?: TrussPattern;
+  /** Panels along the length. Default ≈ length / depth. */
+  readonly bays?: number;
+  /** Chord member width, metres. */
+  readonly chord: number;
+  /** Web member width. Default 0.6 · chord. */
+  readonly web?: number;
+  readonly section?: SectionKind;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+}
+
+type Line = (t: number) => Vec3;
+
+export function lattice(o: LatticeOptions): Mesh {
+  const d: Vec3 = [o.to[0] - o.from[0], o.to[1] - o.from[1], o.to[2] - o.from[2]];
+  const len = Math.hypot(d[0], d[1], d[2]);
+  if (!(len > 1e-6))
+    invalid('lattice: from and to coincide', 'give the truss two distinct end points in metres');
+  const depth = positive('lattice depth', o.depth, 'e.g. 2 for a 2 m deep girder');
+  const chord = positive('lattice chord', o.chord, 'e.g. 0.2');
+  if (chord >= depth)
+    invalid(
+      `lattice chord ${chord} m ≥ depth ${depth} m`,
+      'make the chord member thinner than the depth',
+    );
+  const web = positive('lattice web', o.web ?? chord * 0.6, 'e.g. 0.6 · chord');
+  const k = count('lattice bays', o.bays ?? Math.max(1, Math.round(len / depth)), 1, 2000);
+  const w = normalize(d);
+  const upHint: Vec3 = o.up ?? (Math.abs(w[2]) > 0.95 ? [1, 0, 0] : [0, 0, 1]);
+  const dotU = upHint[0] * w[0] + upHint[1] * w[1] + upHint[2] * w[2];
+  const upR: Vec3 = [upHint[0] - w[0] * dotU, upHint[1] - w[1] * dotU, upHint[2] - w[2] * dotU];
+  if (Math.hypot(upR[0], upR[1], upR[2]) < 1e-6)
+    invalid('lattice: up is parallel to from → to', 'pass an `up` perpendicular to the truss axis');
+  const up = normalize(upR);
+  const side: Vec3 = [
+    w[1] * up[2] - w[2] * up[1],
+    w[2] * up[0] - w[0] * up[2],
+    w[0] * up[1] - w[1] * up[0],
+  ];
+  const dEnd = positive('lattice depthEnd', o.depthEnd ?? depth, 'e.g. 1');
+  const wid = o.width === undefined ? 0 : positive('lattice width', o.width, 'e.g. 2');
+  const wEnd =
+    o.width === undefined ? 0 : positive('lattice widthEnd', o.widthEnd ?? wid, 'e.g. 1');
+  const c0 = o.centred ? -0.5 : 0;
+  /** A chord line at lateral sign a (−1/0/+1) and height c (0 = base, 1 = top). */
+  const line =
+    (a: number, c: number): Line =>
+    (t) => {
+      const along = len * t;
+      const lat = (a * (wid + (wEnd - wid) * t)) / 2;
+      const h = (c0 + c) * (depth + (dEnd - depth) * t);
+      return [
+        o.from[0] + w[0] * along + side[0] * lat + up[0] * h,
+        o.from[1] + w[1] * along + side[1] * lat + up[1] * h,
+        o.from[2] + w[2] * along + side[2] * lat + up[2] * h,
+      ];
+    };
+  const neg = (v: Vec3): Vec3 => [-v[0], -v[1], -v[2]];
+  // Each face: two chord lines, the face normal (members' section up).
+  const faces: [Line, Line, Vec3][] =
+    o.width === undefined
+      ? [[line(0, 0), line(0, 1), side]]
+      : [
+          [line(-1, 0), line(-1, 1), neg(side)],
+          [line(1, 0), line(1, 1), side],
+          [line(-1, 1), line(1, 1), up],
+          [line(-1, 0), line(1, 0), neg(up)],
+        ];
+  const chords: Line[] =
+    o.width === undefined
+      ? [line(0, 0), line(0, 1)]
+      : [line(-1, 0), line(1, 0), line(-1, 1), line(1, 1)];
+  const rect = stripRect(o.strip ?? 'iron');
+  const sc = section(o.section ?? 'square', chord);
+  const sw = section(o.section ?? 'square', web);
+  const mb = new MeshBuilder();
+  for (const c of chords) emitMember(mb, sc, c(0), c(1), up, true, o.color, rect);
+  for (const [lo, hi, n] of faces)
+    for (const [ta, la, tb, lb] of webMembers(o.pattern ?? 'warren', k))
+      emitMember(mb, sw, (la ? hi : lo)(ta), (lb ? hi : lo)(tb), n, false, o.color, rect);
+  return mb.build();
+}
+
+/** Web members of one face as [t0, onTop0, t1, onTop1], in a fixed order (determinism). */
+export function webMembers(pattern: TrussPattern, k: number): [number, boolean, number, boolean][] {
+  const out: [number, boolean, number, boolean][] = [];
+  const t = (i: number): number => i / k;
+  if (pattern !== 'warren') for (let i = 0; i <= k; i++) out.push([t(i), false, t(i), true]);
+  for (let i = 0; i < k; i++) {
+    const down: [number, boolean, number, boolean] = [t(i), true, t(i + 1), false]; // "\"
+    const rise: [number, boolean, number, boolean] = [t(i), false, t(i + 1), true]; // "/"
+    const middle = k % 2 === 1 && i === (k - 1) / 2;
+    const left = i < k / 2;
+    if (pattern === 'warren') out.push(i % 2 === 0 ? rise : down);
+    else if (pattern === 'x' || middle) out.push(rise, down);
+    else if (pattern === 'pratt') out.push(left ? down : rise);
+    else out.push(left ? rise : down);
+  }
+  return out;
+}

package/src/primitives/loft.ts

@@ -0,0 +1,174 @@
+// Skin ordered closed rings with equal vertex counts: haystacks, grain sacks, wheat stooks, hulls,
+// fuselages, buttressed trunk flares. SMOOTH normals (central differences around and along; caps
+// flat), forced outward whichever way the rings wind. Positions are absolute (no `at`). UVs:
+// 'length' (default) U = metres along the ring centroids, V once around the band; 'row' U =
+// metres around each ring, V along; 'swap' one unscaled wrap (U around 0–1, V along 0–1).
+// Triangles = 2·N·(R−1) + N per cap (N vertices per ring, R rings).
+
+import { type Mesh, MeshBuilder, Ts23dError, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+
+export type LoftColor = Vec3 | ((ring: readonly Vec3[], i: number, p: Vec3) => Vec3);
+
+export interface LoftOptions {
+  readonly rings: readonly (readonly Vec3[])[];
+  /** One colour, or one per vertex from (ring, ring index, point). */
+  readonly color: LoftColor;
+  readonly strip?: StripId;
+  readonly capStart?: boolean;
+  readonly capEnd?: boolean;
+  readonly uv?: 'length' | 'row' | 'swap';
+}
+
+/** An elliptical ring in the plane z = centre.z, CCW seen from +Z; `wobble(angle)` scales radius. */
+export function ringXY(
+  centre: Vec3,
+  rx: number,
+  ry: number,
+  segments: number,
+  wobble?: (angle: number) => number,
+  phase = 0,
+): Vec3[] {
+  const out: Vec3[] = [];
+  for (let k = 0; k < segments; k++) {
+    const a = phase + (k / segments) * Math.PI * 2;
+    const w = wobble ? wobble(a) : 1;
+    out.push([centre[0] + rx * Math.cos(a) * w, centre[1] + ry * Math.sin(a) * w, centre[2]]);
+  }
+  return out;
+}
+
+const invalid = (cause: string, fix: string): Ts23dError =>
+  new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+
+const centroid = (r: readonly Vec3[]): Vec3 => {
+  let x = 0;
+  let y = 0;
+  let z = 0;
+  for (const p of r) {
+    x += p[0];
+    y += p[1];
+    z += p[2];
+  }
+  return [x / r.length, y / r.length, z / r.length];
+};
+
+export function loft(o: LoftOptions): Mesh {
+  const R = o.rings.length;
+  if (R < 2) throw invalid(`loft has ${R} ring(s)`, 'pass at least 2 rings (bottom → top)');
+  const N = o.rings[0]?.length ?? 0;
+  if (N < 3) throw invalid(`loft rings have ${N} vertices`, 'give every ring at least 3 vertices');
+  for (const [i, r] of o.rings.entries()) {
+    if (r.length !== N) {
+      throw invalid(
+        `loft ring ${i} has ${r.length} vertices, ring 0 has ${N}`,
+        'build every ring with the same vertex count (same `segments` in ringXY)',
+      );
+    }
+  }
+  const at = (i: number, k: number): Vec3 => o.rings[i]?.[((k % N) + N) % N] ?? [0, 0, 0];
+  const cents = o.rings.map(centroid);
+  const along = [0];
+  for (let i = 1; i < R; i++) {
+    const a = cents[i - 1] ?? [0, 0, 0];
+    const b = cents[i] ?? a;
+    along.push((along[i - 1] ?? 0) + Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]));
+  }
+  const total = along[R - 1] || 1;
+  // Raw normals (around × along); the sign of their sum against "outward from the centroid"
+  // decides the winding for the whole loft.
+  const raw: Vec3[] = [];
+  let facing = 0;
+  for (let i = 0; i < R; i++) {
+    const c = cents[i] ?? [0, 0, 0];
+    const ax = cents[Math.min(R - 1, i + 1)] ?? c;
+    const bx = cents[Math.max(0, i - 1)] ?? c;
+    const axis: Vec3 = [ax[0] - bx[0], ax[1] - bx[1], ax[2] - bx[2]];
+    for (let k = 0; k < N; k++) {
+      const p = at(i, k);
+      const u0 = at(i, k - 1);
+      const u1 = at(i, k + 1);
+      const v0 = at(Math.max(0, i - 1), k);
+      const v1 = at(Math.min(R - 1, i + 1), k);
+      const tu: Vec3 = [u1[0] - u0[0], u1[1] - u0[1], u1[2] - u0[2]];
+      const tv: Vec3 = [v1[0] - v0[0], v1[1] - v0[1], v1[2] - v0[2]];
+      let n: Vec3 = [
+        tu[1] * tv[2] - tu[2] * tv[1],
+        tu[2] * tv[0] - tu[0] * tv[2],
+        tu[0] * tv[1] - tu[1] * tv[0],
+      ];
+      if (Math.hypot(n[0], n[1], n[2]) < 1e-12) n = i === 0 ? [-axis[0], -axis[1], -axis[2]] : axis;
+      facing += n[0] * (p[0] - c[0]) + n[1] * (p[1] - c[1]) + n[2] * (p[2] - c[2]);
+      raw.push(n);
+    }
+  }
+  const flip = facing < 0 ? -1 : 1;
+  const rect = stripRect(o.strip ?? 'plain');
+  const du = rect.u1 - rect.u0;
+  const dv = rect.v1 - rect.v0;
+  const mode = o.uv ?? 'length';
+  const color = (i: number, p: Vec3): Vec3 =>
+    typeof o.color === 'function' ? o.color(o.rings[i] ?? [], i, p) : o.color;
+  const b = new MeshBuilder();
+  for (let i = 0; i < R; i++) {
+    let around = 0;
+    for (let k = 0; k <= N; k++) {
+      const p = at(i, k);
+      if (k > 0) {
+        const q = at(i, k - 1);
+        around += Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]);
+      }
+      const n = raw[i * N + (k % N)] ?? [0, 0, 1];
+      const l = (Math.hypot(n[0], n[1], n[2]) || 1) * flip;
+      const s = (along[i] ?? 0) / rect.metres;
+      const uv: [number, number] =
+        mode === 'row'
+          ? [rect.u0 + (around / rect.metres) * du, rect.v0 + ((along[i] ?? 0) / total) * dv]
+          : mode === 'swap'
+            ? [rect.u0 + (k / N) * du, rect.v0 + ((along[i] ?? 0) / total) * dv]
+            : [rect.u0 + s * du, rect.v0 + (k / N) * dv];
+      b.vertex({ p, n: [n[0] / l, n[1] / l, n[2] / l], uv, color: color(i, p) });
+    }
+  }
+  for (let i = 0; i + 1 < R; i++) {
+    const r0 = i * (N + 1);
+    const r1 = r0 + N + 1;
+    for (let k = 0; k < N; k++) {
+      if (flip > 0) b.quad(r0 + k, r0 + k + 1, r1 + k + 1, r1 + k);
+      else b.quad(r0 + k, r1 + k, r1 + k + 1, r0 + k + 1);
+    }
+  }
+  const ends: [number, boolean][] = [
+    [0, o.capStart === true],
+    [R - 1, o.capEnd === true],
+  ];
+  for (const [i, on] of ends) {
+    if (!on) continue;
+    const c = cents[i] ?? [0, 0, 0];
+    const other = cents[i === 0 ? 1 : R - 2] ?? c;
+    const d: Vec3 = [c[0] - other[0], c[1] - other[1], c[2] - other[2]];
+    const l = Math.hypot(d[0], d[1], d[2]) || 1;
+    const nn: Vec3 = [d[0] / l, d[1] / l, d[2] / l];
+    const mid = b.vertex({ p: c, n: nn, uv: [rect.u0, rect.v0], color: color(i, c) });
+    for (let k = 0; k < N; k++) {
+      const p = at(i, k);
+      b.vertex({ p, n: nn, uv: [rect.u0, rect.v1], color: color(i, p) });
+    }
+    // Cap winding: CCW seen from outside (along nn). Ring order relative to nn sets the sense.
+    const e1 = at(i, 0);
+    const e2 = at(i, 1);
+    const cr: Vec3 = [
+      (e1[1] - c[1]) * (e2[2] - c[2]) - (e1[2] - c[2]) * (e2[1] - c[1]),
+      (e1[2] - c[2]) * (e2[0] - c[0]) - (e1[0] - c[0]) * (e2[2] - c[2]),
+      (e1[0] - c[0]) * (e2[1] - c[1]) - (e1[1] - c[1]) * (e2[0] - c[0]),
+    ];
+    const ccw = cr[0] * nn[0] + cr[1] * nn[1] + cr[2] * nn[2] >= 0;
+    for (let k = 0; k < N; k++) {
+      const a = mid + 1 + k;
+      const z = mid + 1 + ((k + 1) % N);
+      if (ccw) b.tri(mid, a, z);
+      else b.tri(mid, z, a);
+    }
+  }
+  return b.build();
+}

package/src/primitives/mc-table.ts

@@ -0,0 +1,41 @@
+// Marching-cubes triangle table (Lorensen & Cline 1987; Paul Bourke's public-domain listing,
+// as shipped by three.js): case → edge triples, one hex digit per edge, cases joined by '.'.
+// Corner bit i set = corner i inside. Corners/edges follow Bourke's numbering (marching-cubes.ts).
+
+const PACKED =
+  '.083.019.183981.12a.08312a.92a029.2832a8a98.3b2.0b28b0.19023b.1b219b98b.3a1ba3.0a108a8ba.3' +
+  '903b9ba9.98aa8b.478.430734.019847.419471731.12a847.34730412a.92a902847.2a9297273794.8473b2' +
+  '.b47b24204.90184723b.47b94b9b2921.3a13ba784.1ba14b1047b4.47890b9bab03.47b4b99ba.954.954083' +
+  '.054150.854835315.12a954.30812a495.52a542402.2a5325354348.95423b.0b208b495.05401523b.21525' +
+  '828b485.a3ba13954.4950818a18ba.54050b5bab03.54858aa8b.978579.930953573.078017157.153357.97' +
+  '8957a12.a12950530573.802825857a52.2a5253357.7957893b2.95797292027b.23b018178157.b21b17715.' +
+  '958857a13a3b.5705097b010aba0.ba0b03a50807570.ba57b5.a65.0835a6.9015a6.1831985a6.165261.165' +
+  '126308.965906026.598582526328.23ba65.b08b20a65.01923b5a6.5a61929b298b.63b653513.08b0b50515' +
+  'b6.3b6036065059.65969bb98.5a6478.43047365a.1905a6847.a65197173794.612651478.125526304347.8' +
+  '47905065026.739794329596269.3b2784a65.5a647242027b.01947823b5a6.9219b294b7b45a6.8473b53515' +
+  'b6.51b5b610b7b404b.059065036b63847.65969b4797b9.a4964a.4a649a083.a01a60640.83181686461a.14' +
+  '9124264.308129249264.024426.832824426.a49a64b23.08228b49a4a6.3b201606461a.64161a48121b8b1.' +
+  '964936913b63.8b1810b61914641.3b6360064.648b68.7a678a89a.0730a709a67a.a671a7178180.a67a7117' +
+  '3.126168189867.269291679093739.780706602.732672.23ba68a89867.20727b09767a9a7.1801781a767a2' +
+  '3b.b21b17a61671.896867916b63136.091b67.7807063b0b60.7b6.76b.308b76.019b76.819831b76.a126b7' +
+  '.12a3086b7.2902a96b7.6b72a3a83a98.723627.708760620.276237019.162186198876.a76a17137.a7617a' +
+  '187108.03707a0a96a7.76a7a88a9.684b86.36b306046.86b846901.946963931b36.6846b82a1.12a30b06b0' +
+  '46.4b846b0292a9.a93a32943b36463.823842462.042462.190234246438.194142246.8138618466a1.a10a0' +
+  '6604.4634386a3039a93.a946a4.49576b.083495b76.50154076b.b76834354315.954a1276b.6b712a083495' +
+  '.76b54a42a402.348354325a52b76.723762549.954086062687.362376150540.628687218485158.954a1617' +
+  '6137.16a176107870954.40a4a503a6a737a.76a7a854a48a.6956b9b89.36b063056095.0b805b01556b.6b36' +
+  '35531.12a95b9b8b56.0b306b09656912a.b85b56805a52025.6b36352a3a53.589528562382.956960062.158' +
+  '180568382628.156216.13616a386569896.a10a06950560.03856a.a56.b5a75b.b5ab75830.5b75ab190.a75' +
+  'ab7981831.b12b71751.08312717572b.9759279022b7.75272b592328982.25a235375.820852875a25.9015a' +
+  '35373a2.982921872a25752.135375.087071175.903935537.987597.5845a8ab8.5045b05abb30.01984a8ab' +
+  'a45.ab4a45b34941314.2512852b8458.04b0b345b2b151b.0250592b5458b85.9452b3.25a352345384.5a252' +
+  '4420.3a235a385458019.5a2524192942.845853351.045105.845853905035.945.4b749b9ab.0834979b79ab' +
+  '.1ab1b414074b.3143481a474bab4.4b79b492b912.9749b791b2b1083.b74b42240.b74b42834324.29a27923' +
+  '7749.9a7974a27870207.37a3a274a1a040a.1a2874.491417713.491417081871.403743.487.9a8ab8.30939' +
+  'bb9a.01a0a88ab.31ab3a.12b1b99b8.30939b1292b9.02b80b.32b.23828aa89.9a2092.23828a0181a8.1a2.' +
+  '138918.091.038.';
+
+/** TRI[c] = flat edge-index list for cube case c (length a multiple of 3). */
+export const TRI: readonly (readonly number[])[] = PACKED.split('.').map((c) =>
+  [...c].map((h) => Number.parseInt(h, 16)),
+);

package/src/primitives/member.ts

@@ -0,0 +1,130 @@
+// One straight structural member written into a shared MeshBuilder: a 2D section (square tube or
+// angle iron) extruded from → to with flat normals. Lattice emits hundreds of these, so there is
+// no per-member Mesh or merge; the section and its cap triangulation are computed once.
+
+import type { MeshBuilder, Vec2, Vec3 } from '../core/index.ts';
+import type { UvRect } from '../material/index.ts';
+import { stripU, stripV } from './strip-uv.ts';
+import { triangulate } from './triangulate.ts';
+
+export type SectionKind = 'square' | 'angle';
+
+export interface Section {
+  /** Profile in the member's (x, y) plane, CCW seen from the far end. */
+  readonly ring: readonly Vec2[];
+  readonly caps: readonly (readonly [number, number, number])[];
+  /** Cumulative perimeter run at each ring vertex, as a fraction 0..1 (V across the strip). */
+  readonly run: readonly number[];
+  /** Side triangles per member (caps add 2 · caps.length). */
+  readonly sideTris: number;
+}
+
+/** A section of outside width `w`; angle legs are 15% of the width thick. */
+export function section(kind: SectionKind, w: number): Section {
+  const h = w / 2;
+  const t = w * 0.15;
+  const ring: Vec2[] =
+    kind === 'square'
+      ? [
+          [-h, -h],
+          [h, -h],
+          [h, h],
+          [-h, h],
+        ]
+      : [
+          [-h, -h],
+          [h, -h],
+          [h, -h + t],
+          [-h + t, -h + t],
+          [-h + t, h],
+          [-h, h],
+        ];
+  const lens = ring.map((a, i) => {
+    const b = ring[(i + 1) % ring.length] ?? a;
+    return Math.hypot(b[0] - a[0], b[1] - a[1]);
+  });
+  const total = lens.reduce((s, l) => s + l, 0);
+  let acc = 0;
+  const run = lens.map((l) => {
+    const r = acc / total;
+    acc += l;
+    return r;
+  });
+  return { ring, caps: triangulate(ring), run, sideTris: ring.length * 2 };
+}
+
+/**
+ * Extrude `s` from a to b. `y` is the section's local up (must not be parallel to b − a): put it
+ * on the face normal so members lie flush in their truss plane. Caps close both ends.
+ */
+export function emitMember(
+  mb: MeshBuilder,
+  s: Section,
+  a: Vec3,
+  b: Vec3,
+  y: Vec3,
+  caps: boolean,
+  color: Vec3,
+  rect: UvRect,
+): void {
+  const d: Vec3 = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+  const len = Math.sqrt(d[0] * d[0] + d[1] * d[1] + d[2] * d[2]);
+  const w: Vec3 = [d[0] / len, d[1] / len, d[2] / len];
+  // y ⟂ w (Gram–Schmidt), x = y × w so (x, y, w) is right-handed.
+  const k = y[0] * w[0] + y[1] * w[1] + y[2] * w[2];
+  const yr: Vec3 = [y[0] - w[0] * k, y[1] - w[1] * k, y[2] - w[2] * k];
+  const yl = Math.sqrt(yr[0] * yr[0] + yr[1] * yr[1] + yr[2] * yr[2]);
+  const yy: Vec3 = [yr[0] / yl, yr[1] / yl, yr[2] / yl];
+  const x: Vec3 = [
+    yy[1] * w[2] - yy[2] * w[1],
+    yy[2] * w[0] - yy[0] * w[2],
+    yy[0] * w[1] - yy[1] * w[0],
+  ];
+  const at = (p: Vec2, end: Vec3): Vec3 => [
+    end[0] + x[0] * p[0] + yy[0] * p[1],
+    end[1] + x[1] * p[0] + yy[1] * p[1],
+    end[2] + x[2] * p[0] + yy[2] * p[1],
+  ];
+  const n = s.ring.length;
+  const u1 = stripU(rect, len);
+  const u0 = stripU(rect, 0);
+  for (let i = 0; i < n; i++) {
+    const p = s.ring[i] ?? [0, 0];
+    const q = s.ring[(i + 1) % n] ?? p;
+    const ex = q[0] - p[0];
+    const ey = q[1] - p[1];
+    const el = Math.hypot(ex, ey);
+    // Outward 2D normal of a CCW edge is (ey, −ex).
+    const nx = ey / el;
+    const ny = -ex / el;
+    const nrm: Vec3 = [x[0] * nx + yy[0] * ny, x[1] * nx + yy[1] * ny, x[2] * nx + yy[2] * ny];
+    const v0 = stripV(rect, s.run[i] ?? 0);
+    const v1 = stripV(rect, i + 1 < n ? (s.run[i + 1] ?? 1) : 1);
+    const i0 = mb.vertex({ p: at(p, a), n: nrm, uv: [u0, v0], color });
+    const i1 = mb.vertex({ p: at(q, a), n: nrm, uv: [u0, v1], color });
+    const i2 = mb.vertex({ p: at(q, b), n: nrm, uv: [u1, v1], color });
+    const i3 = mb.vertex({ p: at(p, b), n: nrm, uv: [u1, v0], color });
+    mb.quad(i0, i1, i2, i3);
+  }
+  if (!caps) return;
+  for (const [end, sign] of [
+    [a, -1],
+    [b, 1],
+  ] as const) {
+    const nrm: Vec3 = [w[0] * sign, w[1] * sign, w[2] * sign];
+    const first = mb.vertex({
+      p: at(s.ring[0] ?? [0, 0], end),
+      n: nrm,
+      uv: [u0, stripV(rect, 0)],
+      color,
+    });
+    for (let i = 1; i < n; i++) {
+      const p = s.ring[i] ?? [0, 0];
+      mb.vertex({ p: at(p, end), n: nrm, uv: [u0, stripV(rect, s.run[i] ?? 0)], color });
+    }
+    for (const [i, j, l] of s.caps) {
+      if (sign > 0) mb.tri(first + i, first + j, first + l);
+      else mb.tri(first + i, first + l, first + j);
+    }
+  }
+}

package/src/primitives/noise.ts

@@ -0,0 +1,157 @@
+// Seeded 2D noise kit for terrain and maps: gradient (Perlin) and value noise, fBm, ridged
+// multifractal (Musgrave: sharp ridgelines), billow (rounded hills), domain warp (Quílez: folded,
+// flowing ranges) and terraces. Everything derives from an Rng and uses only + − × ÷ sqrt floor,
+// so the same seed gives the same bits on every engine (no sin/pow/exp in the hot path).
+// A Noise2 takes metres (x, y) and returns roughly [−1, 1] (ridged: [0, 1]).
+
+import type { Rng } from '../core/index.ts';
+
+export type Noise2 = (x: number, y: number) => number;
+
+export interface FractalOptions {
+  /** Metres per base feature (the first octave's wavelength). Default 1. */
+  readonly scale?: number;
+  readonly octaves?: number;
+  /** Frequency multiplier per octave. Default 2. */
+  readonly lacunarity?: number;
+  /** Amplitude multiplier per octave (persistence). Default 0.5. */
+  readonly gain?: number;
+}
+
+const R = Math.SQRT1_2;
+/** Eight unit gradients with exact constants (no trig: bitwise identical everywhere). */
+const GX = [1, -1, 0, 0, R, -R, R, -R];
+const GY = [0, 0, 1, -1, R, R, -R, -R];
+
+function permutation(rng: Rng): Uint8Array {
+  const p = new Uint8Array(512);
+  for (let i = 0; i < 256; i++) p[i] = i;
+  for (let i = 255; i > 0; i--) {
+    const j = rng.int(0, i);
+    const t = p[i] ?? 0;
+    p[i] = p[j] ?? 0;
+    p[j] = t;
+  }
+  for (let i = 0; i < 256; i++) p[i + 256] = p[i] ?? 0;
+  return p;
+}
+
+const fade = (t: number): number => t * t * t * (t * (t * 6 - 15) + 10);
+
+/** Perlin gradient noise, feature size 1 m, ≈ [−1, 1]. */
+export function gradientNoise2(rng: Rng): Noise2 {
+  const p = permutation(rng);
+  const grad = (ix: number, iy: number, dx: number, dy: number): number => {
+    const g = (p[(p[ix & 255] ?? 0) + (iy & 255)] ?? 0) & 7;
+    return (GX[g] ?? 0) * dx + (GY[g] ?? 0) * dy;
+  };
+  return (x, y) => {
+    const ix = Math.floor(x);
+    const iy = Math.floor(y);
+    const fx = x - ix;
+    const fy = y - iy;
+    const u = fade(fx);
+    const v = fade(fy);
+    const a = grad(ix, iy, fx, fy);
+    const b = grad(ix + 1, iy, fx - 1, fy);
+    const c = grad(ix, iy + 1, fx, fy - 1);
+    const d = grad(ix + 1, iy + 1, fx - 1, fy - 1);
+    const top = a + (b - a) * u;
+    return (top + (c + (d - c) * u - top) * v) * Math.SQRT2;
+  };
+}
+
+/** Value noise (smoothed random lattice), feature size 1 m, [−1, 1]. Blobbier than gradient. */
+export function valueNoise2(rng: Rng): Noise2 {
+  const p = permutation(rng);
+  const vals = new Float64Array(256);
+  for (let i = 0; i < 256; i++) vals[i] = rng.next() * 2 - 1;
+  const at = (ix: number, iy: number): number => vals[p[(p[ix & 255] ?? 0) + (iy & 255)] ?? 0] ?? 0;
+  return (x, y) => {
+    const ix = Math.floor(x);
+    const iy = Math.floor(y);
+    const u = fade(x - ix);
+    const v = fade(y - iy);
+    const top = at(ix, iy) + (at(ix + 1, iy) - at(ix, iy)) * u;
+    const bot = at(ix, iy + 1) + (at(ix + 1, iy + 1) - at(ix, iy + 1)) * u;
+    return top + (bot - top) * v;
+  };
+}
+
+/** Sum octaves of `shape(n(x·f, y·f))`, normalised by the amplitude sum. */
+function fractal(n: Noise2, o: FractalOptions, shape: (v: number) => number): Noise2 {
+  const s = 1 / (o.scale ?? 1);
+  const octaves = o.octaves ?? 5;
+  const lac = o.lacunarity ?? 2;
+  const gain = o.gain ?? 0.5;
+  return (x, y) => {
+    let sum = 0;
+    let amp = 1;
+    let norm = 0;
+    let f = s;
+    for (let i = 0; i < octaves; i++) {
+      // Offset each octave so lattice zeros never line up at the origin.
+      sum += amp * shape(n(x * f + i * 17.31, y * f - i * 9.73));
+      norm += amp;
+      amp *= gain;
+      f *= lac;
+    }
+    return sum / norm;
+  };
+}
+
+/** Fractal Brownian motion: the default rolling-hills / rough-surface noise, ≈ [−1, 1]. */
+export const fbm = (n: Noise2, o: FractalOptions = {}): Noise2 => fractal(n, o, (v) => v);
+
+/** Billow: |noise| octaves, rounded domes and sharp creases (hills, clouds), [−1, 1]. */
+export const billow = (n: Noise2, o: FractalOptions = {}): Noise2 =>
+  fractal(n, o, (v) => 2 * Math.abs(v) - 1);
+
+/**
+ * Ridged multifractal (Musgrave): inverted |noise| squared, each octave weighted by the last, so
+ * detail piles up on the ridgelines and valleys stay smooth. [0, 1].
+ */
+export function ridged(n: Noise2, o: FractalOptions & { readonly offset?: number } = {}): Noise2 {
+  const s = 1 / (o.scale ?? 1);
+  const octaves = o.octaves ?? 6;
+  const lac = o.lacunarity ?? 2;
+  const gain = o.gain ?? 0.5;
+  const offset = o.offset ?? 1;
+  return (x, y) => {
+    let sum = 0;
+    let norm = 0;
+    let amp = 1;
+    let weight = 1;
+    let f = s;
+    for (let i = 0; i < octaves; i++) {
+      const crest = offset - Math.abs(n(x * f + i * 17.31, y * f - i * 9.73));
+      const signal = crest * crest * weight;
+      weight = Math.min(1, Math.max(0, signal * 2));
+      sum += signal * amp;
+      norm += amp * offset * offset;
+      amp *= gain;
+      f *= lac;
+    }
+    return sum / norm;
+  };
+}
+
+/** Domain warp: sample `n` at a point pushed by two other noises × `amount` metres (Quílez). */
+export const warp =
+  (n: Noise2, wx: Noise2, wy: Noise2, amount: number): Noise2 =>
+  (x, y) =>
+    n(x + amount * wx(x, y), y + amount * wy(x, y));
+
+/**
+ * Terraces: snap a height to steps of `step` metres. `sharpness` is the share of each step that is
+ * a flat tread (0 = no terracing, 1 = flat treads and vertical risers); the rest is a smooth riser.
+ * Strata, rice paddies, open-pit benches.
+ */
+export function terrace(h: number, step: number, sharpness = 0.5): number {
+  const k = Math.floor(h / step);
+  const t = h / step - k;
+  const s = Math.min(1, Math.max(0, sharpness));
+  const u = s >= 1 ? 0 : Math.min(1, Math.max(0, (t - s) / (1 - s)));
+  const riser = u * u * (3 - 2 * u);
+  return (k + t + (riser - t) * s) * step;
+}