@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/primitives/erosion.ts

@@ -0,0 +1,183 @@
+// Hydraulic droplet erosion (Beyer 2015, "Implementation of a method for hydraulic erosion"; the
+// Lague variant): thousands of droplets start at random points (from the Rng), roll downhill with
+// inertia, pick up sediment while fast and on steep ground, drop it where they slow or climb, and
+// evaporate. Gullies, carved valleys, alluvial fans and sharp ridges appear: the look of World
+// Machine / Gaea terrain. Heights are normalised to 0..1 while simulating, so the defaults behave
+// the same on any relief; the result is rescaled to metres. Also records flow and deposit maps.
+
+import type { Rng } from '../core/index.ts';
+import { count } from './check.ts';
+import type { TerrainGrid } from './terrain-grid.ts';
+
+export interface ErosionOptions {
+  /** Droplets simulated. ~1 per grid point is mild, 2–3 is strongly carved. Default 70 000. */
+  readonly droplets?: number;
+  /** Steps a droplet lives. Default 30. */
+  readonly lifetime?: number;
+  /** 0 = droplets follow the gradient exactly, 1 = they never turn. Default 0.05. */
+  readonly inertia?: number;
+  /** Sediment a droplet can carry per unit of speed × water × drop. Default 4. */
+  readonly capacity?: number;
+  readonly minCapacity?: number;
+  /** Share of spare capacity eroded per step. Default 0.3. */
+  readonly erode?: number;
+  /** Share of surplus sediment deposited per step. Default 0.3. */
+  readonly deposit?: number;
+  readonly evaporate?: number;
+  readonly gravity?: number;
+  /** Erosion brush radius in grid cells (wider = smoother gullies). Default 3. */
+  readonly radius?: number;
+}
+
+const put = (h: Float64Array, dep: Float64Array, k: number, a: number): void => {
+  h[k] = (h[k] ?? 0) + a;
+  dep[k] = (dep[k] ?? 0) + a;
+};
+
+interface Sim {
+  readonly h: Float64Array;
+  readonly flow: Float64Array;
+  readonly dep: Float64Array;
+  readonly nx: number;
+  readonly ny: number;
+  readonly inertia: number;
+  readonly capK: number;
+  readonly minCap: number;
+  readonly erodeK: number;
+  readonly depositK: number;
+  readonly evap: number;
+  readonly gravity: number;
+  readonly life: number;
+}
+
+interface Brush {
+  readonly dx: Int32Array;
+  readonly dy: Int32Array;
+  readonly w: Float64Array;
+}
+
+/** Cell offsets within the radius, weights falling off linearly, summing to 1. */
+function makeBrush(radius: number): Brush {
+  const dx: number[] = [];
+  const dy: number[] = [];
+  const w: number[] = [];
+  for (let y = -radius; y <= radius; y++)
+    for (let x = -radius; x <= radius; x++) {
+      const d = Math.sqrt(x * x + y * y);
+      if (d < radius) {
+        dx.push(x);
+        dy.push(y);
+        w.push(radius - d);
+      }
+    }
+  const sum = w.reduce((s, v) => s + v, 0);
+  return {
+    dx: Int32Array.from(dx),
+    dy: Int32Array.from(dy),
+    w: Float64Array.from(w, (v) => v / sum),
+  };
+}
+
+/** One droplet's life. Module-level with scalar locals: no closures for the JIT to trip on. */
+function droplet(s: Sim, b: Brush, x0: number, y0: number): void {
+  const { h, nx, ny } = s;
+  let x = x0;
+  let y = y0;
+  let dx = 0;
+  let dy = 0;
+  let speed = 1;
+  let water = 1;
+  let sediment = 0;
+  for (let step = 0; step < s.life; step++) {
+    const i = Math.floor(x);
+    const j = Math.floor(y);
+    const u = x - i;
+    const v = y - j;
+    const k = j * nx + i;
+    const a = h[k] ?? 0;
+    const bb = h[k + 1] ?? 0;
+    const c = h[k + nx] ?? 0;
+    const d = h[k + nx + 1] ?? 0;
+    const height = a * (1 - u) * (1 - v) + bb * u * (1 - v) + c * (1 - u) * v + d * u * v;
+    const gx = (bb - a) * (1 - v) + (d - c) * v;
+    const gy = (c - a) * (1 - u) + (d - bb) * u;
+    dx = dx * s.inertia - gx * (1 - s.inertia);
+    dy = dy * s.inertia - gy * (1 - s.inertia);
+    const len = Math.sqrt(dx * dx + dy * dy);
+    if (len === 0) return;
+    dx /= len;
+    dy /= len;
+    x += dx;
+    y += dy;
+    s.flow[k] = (s.flow[k] ?? 0) + water;
+    if (x < 0 || y < 0 || x >= nx - 1 || y >= ny - 1) return;
+    const dh = bilinear(h, nx, x, y) - height;
+    const cap = Math.max(-dh * speed * water * s.capK, s.minCap);
+    if (sediment > cap || dh > 0) {
+      // Fill the pit we climbed out of, or drop the surplus: split over the 4 corners.
+      const amount = dh > 0 ? Math.min(dh, sediment) : (sediment - cap) * s.depositK;
+      sediment -= amount;
+      put(h, s.dep, k, amount * (1 - u) * (1 - v));
+      put(h, s.dep, k + 1, amount * u * (1 - v));
+      put(h, s.dep, k + nx, amount * (1 - u) * v);
+      put(h, s.dep, k + nx + 1, amount * u * v);
+    } else {
+      const amount = Math.min((cap - sediment) * s.erodeK, -dh);
+      for (let n = 0; n < b.w.length; n++) {
+        const ci = i + (b.dx[n] ?? 0);
+        const cj = j + (b.dy[n] ?? 0);
+        if (ci < 0 || cj < 0 || ci >= nx || cj >= ny) continue;
+        const cell = cj * nx + ci;
+        const take = Math.min(h[cell] ?? 0, amount * (b.w[n] ?? 0));
+        h[cell] = (h[cell] ?? 0) - take;
+        sediment += take;
+      }
+    }
+    speed = Math.sqrt(Math.max(0, speed * speed - dh * s.gravity));
+    water *= 1 - s.evap;
+  }
+}
+
+function bilinear(h: Float64Array, nx: number, x: number, y: number): number {
+  const i = Math.floor(x);
+  const j = Math.floor(y);
+  const u = x - i;
+  const v = y - j;
+  const k = j * nx + i;
+  const a = h[k] ?? 0;
+  const b = h[k + 1] ?? 0;
+  const c = h[k + nx] ?? 0;
+  const d = h[k + nx + 1] ?? 0;
+  return a * (1 - u) * (1 - v) + b * u * (1 - v) + c * (1 - u) * v + d * u * v;
+}
+
+export function hydraulicErosion(g: TerrainGrid, rng: Rng, o: ErosionOptions = {}): TerrainGrid {
+  const drops = count('erosion droplets', o.droplets ?? 70000, 0, 10_000_000);
+  const life = count('erosion lifetime', o.lifetime ?? 30, 1, 1000);
+  const radius = count('erosion radius', o.radius ?? 3, 1, 32);
+  const { nx, ny } = g;
+  let lo = Number.POSITIVE_INFINITY;
+  let hi = Number.NEGATIVE_INFINITY;
+  for (const v of g.z) {
+    lo = Math.min(lo, v);
+    hi = Math.max(hi, v);
+  }
+  const relief = hi - lo || 1;
+  const h = Float64Array.from(g.z, (v) => (v - lo) / relief);
+  const flow = new Float64Array(h.length);
+  const dep = new Float64Array(h.length);
+  const sim: Sim = {
+    ...{ h, flow, dep, nx, ny, life, inertia: o.inertia ?? 0.05, capK: o.capacity ?? 4 },
+    ...{ minCap: o.minCapacity ?? 0.01, erodeK: o.erode ?? 0.3, depositK: o.deposit ?? 0.3 },
+    ...{ evap: o.evaporate ?? 0.01, gravity: o.gravity ?? 4 },
+  };
+  const brush = makeBrush(radius);
+  for (let n = 0; n < drops; n++) droplet(sim, brush, rng.next() * (nx - 2), rng.next() * (ny - 2));
+  const norm = (m: Float64Array): Float64Array => {
+    let top = 0;
+    for (const v of m) top = Math.max(top, v);
+    // Square-root compresses the long tail: a few rivers carry most water.
+    return top > 0 ? m.map((v) => Math.sqrt(v / top)) : m;
+  };
+  return { ...g, z: h.map((v) => lo + v * relief), flow: norm(flow), deposit: norm(dep) };
+}

package/src/primitives/font-5x7.ts

@@ -0,0 +1,117 @@
+// The built-in 5 × 7 glyph table for `text`: Latin A–Z, digits, common punctuation and Cyrillic
+// А–Я + Ё (lower case maps to upper). One entry = 7 rows top → bottom, each a 5-bit number,
+// bit 4 = left column — the classic LCD character-generator shapes, legible down to a few pixels.
+// Primitives (tier 2) cannot import render/font.ts (tier 3), hence this own copy.
+
+const A = [14, 17, 17, 17, 31, 17, 17];
+const B = [30, 17, 17, 30, 17, 17, 30];
+const C = [14, 17, 16, 16, 16, 17, 14];
+const E = [31, 16, 16, 30, 16, 16, 31];
+const H = [17, 17, 17, 31, 17, 17, 17];
+const K = [17, 18, 20, 24, 20, 18, 17];
+const M = [17, 27, 21, 21, 17, 17, 17];
+const O = [14, 17, 17, 17, 17, 17, 14];
+const P = [30, 17, 17, 30, 16, 16, 16];
+const T = [31, 4, 4, 4, 4, 4, 4];
+const X = [17, 17, 10, 4, 10, 17, 17];
+
+export const GLYPHS: Readonly<Record<string, readonly number[]>> = {
+  ' ': [0, 0, 0, 0, 0, 0, 0],
+  A,
+  B,
+  C,
+  D: [28, 18, 17, 17, 17, 18, 28],
+  E,
+  F: [31, 16, 16, 30, 16, 16, 16],
+  G: [14, 17, 16, 23, 17, 17, 15],
+  H,
+  I: [14, 4, 4, 4, 4, 4, 14],
+  J: [7, 2, 2, 2, 2, 18, 12],
+  K,
+  L: [16, 16, 16, 16, 16, 16, 31],
+  M,
+  N: [17, 17, 25, 21, 19, 17, 17],
+  O,
+  P,
+  Q: [14, 17, 17, 17, 21, 18, 13],
+  R: [30, 17, 17, 30, 20, 18, 17],
+  S: [15, 16, 16, 14, 1, 1, 30],
+  T,
+  U: [17, 17, 17, 17, 17, 17, 14],
+  V: [17, 17, 17, 17, 17, 10, 4],
+  W: [17, 17, 17, 21, 21, 21, 10],
+  X,
+  Y: [17, 17, 10, 4, 4, 4, 4],
+  Z: [31, 1, 2, 4, 8, 16, 31],
+  '0': [14, 17, 19, 21, 25, 17, 14],
+  '1': [4, 12, 4, 4, 4, 4, 14],
+  '2': [14, 17, 1, 2, 4, 8, 31],
+  '3': [31, 2, 4, 2, 1, 17, 14],
+  '4': [2, 6, 10, 18, 31, 2, 2],
+  '5': [31, 16, 30, 1, 1, 17, 14],
+  '6': [6, 8, 16, 30, 17, 17, 14],
+  '7': [31, 1, 2, 4, 8, 8, 8],
+  '8': [14, 17, 17, 14, 17, 17, 14],
+  '9': [14, 17, 17, 15, 1, 2, 12],
+  '.': [0, 0, 0, 0, 0, 12, 12],
+  ',': [0, 0, 0, 0, 12, 4, 8],
+  '-': [0, 0, 0, 31, 0, 0, 0],
+  '/': [0, 1, 2, 4, 8, 16, 0],
+  ':': [0, 12, 12, 0, 12, 12, 0],
+  "'": [12, 4, 8, 0, 0, 0, 0],
+  '"': [10, 10, 10, 0, 0, 0, 0],
+  '&': [12, 18, 20, 8, 21, 18, 13],
+  '!': [4, 4, 4, 4, 4, 0, 4],
+  '?': [14, 17, 1, 2, 4, 0, 4],
+  '#': [10, 10, 31, 10, 31, 10, 10],
+  '+': [0, 4, 4, 31, 4, 4, 0],
+  '=': [0, 0, 31, 0, 31, 0, 0],
+  '*': [0, 4, 21, 14, 21, 4, 0],
+  '(': [2, 4, 8, 8, 8, 4, 2],
+  ')': [8, 4, 2, 2, 2, 4, 8],
+  '%': [24, 25, 2, 4, 8, 19, 3],
+  '°': [12, 18, 18, 12, 0, 0, 0],
+  '№': [18, 26, 26, 22, 22, 18, 21],
+  А: A,
+  Б: [31, 16, 16, 30, 17, 17, 30],
+  В: B,
+  Г: [31, 16, 16, 16, 16, 16, 16],
+  Д: [6, 10, 10, 10, 10, 31, 17],
+  Е: E,
+  Ё: [10, 0, 31, 16, 30, 16, 31],
+  Ж: [21, 21, 21, 14, 21, 21, 21],
+  З: [14, 17, 1, 6, 1, 17, 14],
+  И: [17, 17, 19, 21, 25, 17, 17],
+  Й: [10, 4, 17, 19, 21, 25, 17],
+  К: K,
+  Л: [7, 9, 9, 9, 9, 9, 17],
+  М: M,
+  Н: H,
+  О: O,
+  П: [31, 17, 17, 17, 17, 17, 17],
+  Р: P,
+  С: C,
+  Т: T,
+  У: [17, 17, 17, 15, 1, 17, 14],
+  Ф: [4, 14, 21, 21, 21, 14, 4],
+  Х: X,
+  Ц: [18, 18, 18, 18, 18, 31, 1],
+  Ч: [17, 17, 17, 15, 1, 1, 1],
+  Ш: [21, 21, 21, 21, 21, 21, 31],
+  Щ: [21, 21, 21, 21, 21, 31, 1],
+  Ъ: [24, 8, 8, 14, 9, 9, 14],
+  Ы: [17, 17, 17, 29, 19, 19, 29],
+  Ь: [16, 16, 16, 30, 17, 17, 30],
+  Э: [14, 17, 1, 7, 1, 17, 14],
+  Ю: [18, 21, 21, 29, 21, 21, 18],
+  Я: [15, 17, 17, 15, 5, 9, 17],
+};
+
+const group = (c: string): number =>
+  /[A-Z]/.test(c) ? 0 : /[0-9]/.test(c) ? 1 : /[А-ЯЁ]/.test(c) ? 3 : 2;
+/** Every character `text` can set (lower case is accepted and set as upper case). */
+export const SUPPORTED_CHARS = Object.keys(GLYPHS)
+  .filter((c) => c !== ' ')
+  .sort((a, b) => group(a) - group(b) || (a < b ? -1 : a > b ? 1 : 0))
+  .join('')
+  .concat(' and space');

package/src/primitives/heightfield.ts

@@ -0,0 +1,101 @@
+// Terrain from a height function over a rectangle: hills, embankments, spoil heaps, battlefield
+// ground for presentation scenes. Smooth normals by central differences; UVs tile in metres.
+// `cells` is the LOD knob — a recipe passes fewer cells at LOD 1/2. `skirt` drops walls from
+// the edges to a base height: a solid map tile / diorama block that stands on z = 0.
+//   triangles = 2 · cx · cy + (skirt ? 4 · (cx + cy) : 0)
+
+import { type Mesh, MeshBuilder, normalize, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { mirroredV, stripVMetres } from './strip-uv.ts';
+
+export interface HeightfieldOptions {
+  /** [minX, minY, maxX, maxY] in metres. */
+  readonly rect: readonly [number, number, number, number];
+  readonly cells: readonly [number, number];
+  readonly height: (x: number, y: number) => number;
+  /** Vertex colour per point (e.g. darker in ruts, greener on slopes). */
+  readonly color: Vec3 | ((x: number, y: number, z: number) => Vec3);
+  readonly strip?: StripId;
+  /** Close the sides down to this z (e.g. 0): flat-shaded walls, outward normals. */
+  readonly skirt?: number;
+  /** Wall colour; default: the terrain colour at the top edge. */
+  readonly skirtColor?: Vec3;
+}
+
+export function heightfield(o: HeightfieldOptions): Mesh {
+  const [x0, y0, x1, y1] = o.rect;
+  const [nx, ny] = o.cells;
+  const dx = (x1 - x0) / nx;
+  const dy = (y1 - y0) / ny;
+  const rect = stripRect(o.strip ?? 'plain');
+  const vm = stripVMetres(o.strip ?? 'plain');
+  const b = new MeshBuilder();
+  const ids: number[] = [];
+  for (let j = 0; j <= ny; j++) {
+    for (let i = 0; i <= nx; i++) {
+      const x = x0 + i * dx;
+      const y = y0 + j * dy;
+      const z = o.height(x, y);
+      const n = normalize([
+        o.height(x - dx, y) - o.height(x + dx, y),
+        o.height(x, y - dy) - o.height(x, y + dy),
+        2 * Math.min(dx, dy),
+      ]);
+      const color = typeof o.color === 'function' ? o.color(x, y, z) : o.color;
+      const u = (x - x0) / rect.metres;
+      ids.push(
+        b.vertex({
+          p: [x, y, z],
+          n,
+          // V mirrors every band: continuous, so no triangle straddles a wrap and smears the strip.
+          uv: [rect.u0 + u * (rect.u1 - rect.u0), mirroredV(rect, y - y0, vm)],
+          color,
+        }),
+      );
+    }
+  }
+  const at = (i: number, j: number): number => ids[j * (nx + 1) + i] ?? 0;
+  for (let j = 0; j < ny; j++)
+    for (let i = 0; i < nx; i++) b.quad(at(i, j), at(i + 1, j), at(i + 1, j + 1), at(i, j + 1));
+  if (o.skirt !== undefined) skirt(b, o, rect);
+  return b.build();
+}
+
+/** Four walls from the edge vertices down to `o.skirt`, each quad CCW seen from outside. */
+function skirt(b: MeshBuilder, o: HeightfieldOptions, rect: ReturnType<typeof stripRect>): void {
+  const [x0, y0, x1, y1] = o.rect;
+  const [nx, ny] = o.cells;
+  const base = o.skirt ?? 0;
+  // Edge: start corner, step per cell, cell count, outward normal. Walking CCW seen from above,
+  // outside is on the right, so (top a, top b, base b, base a) reversed is CCW from outside.
+  const edges: [number, number, number, number, number, Vec3][] = [
+    [x0, y0, (x1 - x0) / nx, 0, nx, [0, -1, 0]],
+    [x1, y0, 0, (y1 - y0) / ny, ny, [1, 0, 0]],
+    [x1, y1, -(x1 - x0) / nx, 0, nx, [0, 1, 0]],
+    [x0, y1, 0, -(y1 - y0) / ny, ny, [-1, 0, 0]],
+  ];
+  const col = (x: number, y: number, z: number): Vec3 =>
+    o.skirtColor ?? (typeof o.color === 'function' ? o.color(x, y, z) : o.color);
+  const v = (x: number, y: number, z: number, n: Vec3, u: number, color: Vec3): number =>
+    b.vertex({
+      p: [x, y, z],
+      n,
+      uv: [rect.u0 + (u / rect.metres) * (rect.u1 - rect.u0), z > base ? rect.v1 : rect.v0],
+      color,
+    });
+  let run = 0;
+  for (const [sx, sy, dx, dy, n, nrm] of edges) {
+    const step = Math.hypot(dx, dy);
+    for (let k = 0; k < n; k++) {
+      const [ax, ay, bx, by] = [sx + dx * k, sy + dy * k, sx + dx * (k + 1), sy + dy * (k + 1)];
+      const az = o.height(ax, ay);
+      const bz = o.height(bx, by);
+      const ca = col(ax, ay, az);
+      const cb = col(bx, by, bz);
+      const ta = v(ax, ay, az, nrm, run, ca);
+      const tb = v(bx, by, bz, nrm, run + step, cb);
+      b.quad(v(ax, ay, base, nrm, run, ca), v(bx, by, base, nrm, run + step, cb), tb, ta);
+      run += step;
+    }
+  }
+}

package/src/primitives/index.ts

@@ -0,0 +1,56 @@
+// Public API of /primitives: geometry builders, each emitting the core Mesh IR.
+
+export { type BeamOptions, beam } from './beam.ts';
+export { type BoxOptions, box } from './box.ts';
+export { type CellOptions, cell } from './cell.ts';
+export { type ErosionOptions, hydraulicErosion } from './erosion.ts';
+export { type HeightfieldOptions, heightfield } from './heightfield.ts';
+export { cylinder, type LatheOptions, lathe } from './lathe.ts';
+export { type LatticeOptions, lattice, type TrussPattern } from './lattice.ts';
+export { type LoftColor, type LoftOptions, loft, ringXY } from './loft.ts';
+export type { SectionKind } from './member.ts';
+export {
+  billow,
+  type FractalOptions,
+  fbm,
+  gradientNoise2,
+  type Noise2,
+  ridged,
+  terrace,
+  valueNoise2,
+  warp,
+} from './noise.ts';
+export { type PlanarOptions, planar } from './planar.ts';
+export { type PrismOptions, prism } from './prism.ts';
+export {
+  type SculptEdit,
+  type SculptField,
+  type SculptOptions,
+  type SculptShape,
+  sculpt,
+  sculptField,
+} from './sculpt.ts';
+export { type SdfColor, type SdfOptions, sdf } from './sdf.ts';
+export { type Field, sd } from './sdf-ops.ts';
+export { type SweepOptions, sweep } from './sweep.ts';
+export { type TerrainColorOptions, type TerrainPalette, terrainColor } from './terrain-color.ts';
+export {
+  sampler,
+  slopeMap,
+  type TerrainGrid,
+  type TerrainGridOptions,
+  type ThermalOptions,
+  terrainGrid,
+  thermalErosion,
+} from './terrain-grid.ts';
+export {
+  type MeasureOptions,
+  measureText,
+  type TextFont,
+  type TextOptions,
+  text,
+} from './text.ts';
+export { type TiledOptions, tiled } from './tiled.ts';
+export { arcLengths, type SweepFrame, transportFrames } from './transport.ts';
+export { triangulate } from './triangulate.ts';
+export { valueNoise } from './value-noise.ts';

package/src/primitives/lathe-facets.ts

@@ -0,0 +1,45 @@
+// Faceted bands for `lathe({ faceted: true })`: every segment quad gets four vertices of its own
+// and the exact normal of its facet plane, so an n-sided tank, tower or roof shades flat.
+
+import type { Vec2, Vec3 } from '../core/index.ts';
+
+/** The profile and segment count lathe was given. */
+interface Facetable {
+  readonly profile: readonly Vec2[];
+  readonly segments: number;
+}
+
+export /** Flat-shaded bands: four own vertices per segment quad, normal of the facet plane. */
+function facets(
+  o: Facetable,
+  put: (p: Vec3, n: Vec3, uv: Vec2) => number,
+  tri: (a: number, b: number, c: number) => void,
+  sideUv: (s: number, i: number, r: number) => Vec2,
+): void {
+  const half = Math.PI / o.segments;
+  const corner = (s: number): [number, number] => {
+    const t = (s / o.segments) * Math.PI * 2 - Math.PI / 2;
+    return [Math.cos(t), Math.sin(t)];
+  };
+  for (let i = 0; i + 1 < o.profile.length; i++) {
+    const [r0 = 0, z0 = 0] = o.profile[i] ?? [];
+    const [r1 = 0, z1 = 0] = o.profile[i + 1] ?? [];
+    for (let s = 0; s < o.segments; s++) {
+      const tm = ((s + 0.5) / o.segments) * Math.PI * 2 - Math.PI / 2;
+      // The facet's chord sits cos(half) inside the ring, which tilts its normal by that much.
+      const nx = (z1 - z0) * Math.cos(tm);
+      const ny = (z1 - z0) * Math.sin(tm);
+      const nz = -(r1 - r0) * Math.cos(half);
+      const l = Math.hypot(nx, ny, nz) || 1;
+      const n: Vec3 = [nx / l, ny / l, nz / l];
+      const [c0, s0] = corner(s);
+      const [c1, s1] = corner(s + 1);
+      const a = put([r0 * c0, r0 * s0, z0], n, sideUv(s, i, r0));
+      const bb = put([r0 * c1, r0 * s1, z0], n, sideUv(s + 1, i, r0));
+      const c = put([r1 * c1, r1 * s1, z1], n, sideUv(s + 1, i + 1, r1));
+      const d = put([r1 * c0, r1 * s0, z1], n, sideUv(s, i + 1, r1));
+      tri(a, bb, c);
+      tri(a, c, d);
+    }
+  }
+}

package/src/primitives/lathe.ts

@@ -0,0 +1,174 @@
+// Surface of revolution around local Z: boilers, wheels, domes, spires, chimneys, tanks.
+// `segments` is the knob LOD turns down; profiles are (radius, z) pairs bottom→top.
+// Rings start at -90° so a vertex always sits at the contact point: a coarse LOD2 wheel still
+// touches its track (the floating-parts gate caught exactly that).
+// Normals: smooth around the axis, split at profile creases; `faceted` gives every segment its own
+// flat normal (n-sided tanks, towers, roofs). UVs: `uv: 'metres'` maps the strip at true scale
+// (arc length × profile length, staves and shingles at real size); default stretches one strip
+// width around and one strip height along the profile.
+
+import { type Mesh, MeshBuilder, type Vec2, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { facets } from './lathe-facets.ts';
+import { mirroredV, stripU, stripVMetres } from './strip-uv.ts';
+
+export interface LatheOptions {
+  readonly profile: readonly Vec2[];
+  readonly segments: number;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  /** Rotate the lathe axis from Z onto X or Y (wheels spin about Y). */
+  readonly axis?: 'x' | 'y' | 'z';
+  readonly at?: Vec3;
+  /** Close the ends with fans (solid cylinders/wheels). */
+  readonly caps?: boolean;
+  /** Profile turns sharper than this (degrees) get split normals: a hard rim, not a smear
+   *  whose averaged normal opposes one band. Default 50. */
+  readonly creaseDeg?: number;
+  /** 'metres': true-scale strip mapping. Default 'stretch'. */
+  readonly uv?: 'stretch' | 'metres';
+  /** Flat facets: one normal per segment (an n-sided prism of revolution). */
+  readonly faceted?: boolean;
+}
+
+// Swapping two coordinates is a reflection (det −1): normals are swapped with the points so they
+// still point out, but triangle winding flips, so 'x'/'y' lathes emit their indices reversed.
+const orient = (p: Vec3, axis: 'x' | 'y' | 'z'): Vec3 =>
+  axis === 'z' ? p : axis === 'y' ? [p[0], p[2], p[1]] : [p[2], p[1], p[0]];
+
+export function lathe(o: LatheOptions): Mesh {
+  const axis = o.axis ?? 'z';
+  const [ox, oy, oz] = o.at ?? [0, 0, 0];
+  const rect = stripRect(o.strip ?? 'plain');
+  const b = new MeshBuilder();
+  const mirrored = axis !== 'z';
+  const tri = (x: number, y: number, z: number): void => {
+    if (mirrored) b.tri(x, z, y);
+    else b.tri(x, y, z);
+  };
+  const ring: number[][] = [];
+  const put = (p: Vec3, n: Vec3, uv: Vec2): number => {
+    const q = orient(p, axis);
+    return b.vertex({
+      p: [q[0] + ox, q[1] + oy, q[2] + oz],
+      n: orient(n, axis),
+      uv,
+      color: o.color,
+    });
+  };
+  const metres = o.uv === 'metres';
+  const vm = stripVMetres(o.strip ?? 'plain');
+  const run: number[] = [0];
+  for (let i = 1; i < o.profile.length; i++) {
+    const [r0 = 0, z0 = 0] = o.profile[i - 1] ?? [];
+    const [r1 = 0, z1 = 0] = o.profile[i] ?? [];
+    run.push((run[i - 1] ?? 0) + Math.hypot(r1 - r0, z1 - z0));
+  }
+  /** Side UV at segment s of profile point i (radius r). */
+  const sideUv = (s: number, i: number, r: number): Vec2 =>
+    metres
+      ? [stripU(rect, (Math.PI * 2 * r * s) / o.segments), mirroredV(rect, run[i] ?? 0, vm)]
+      : [
+          rect.u0 + (s / o.segments) * (rect.u1 - rect.u0),
+          rect.v0 + (i / Math.max(1, o.profile.length - 1)) * (rect.v1 - rect.v0),
+        ];
+  /** Cap UV at direction (cos, sin) · r on a disc (0, 0 = centre). */
+  const capUv = (c: number, sn: number, r: number): Vec2 =>
+    metres
+      ? [stripU(rect, c * r), mirroredV(rect, (sn + 1) * r, vm)]
+      : [
+          rect.u0 + (0.5 + c / 2) * (rect.u1 - rect.u0),
+          rect.v0 + (0.5 + sn / 2) * (rect.v1 - rect.v0),
+        ];
+  const creaseCos = Math.cos(((o.creaseDeg ?? 50) * Math.PI) / 180);
+  /** One ring of segments + 1 vertices at profile point i with normal along chord (dr, dz). */
+  const emitRing = (i: number, dr: number, dz: number): number[] => {
+    const [r, z] = o.profile[i] ?? [0, 0];
+    const len = Math.hypot(dr, dz) || 1;
+    const row: number[] = [];
+    for (let s = 0; s <= o.segments; s++) {
+      const t = (s / o.segments) * Math.PI * 2 - Math.PI / 2;
+      const c = Math.cos(t);
+      const sn = Math.sin(t);
+      row.push(
+        put([r * c, r * sn, z], [(dz / len) * c, (dz / len) * sn, -dr / len], sideUv(s, i, r)),
+      );
+    }
+    return row;
+  };
+  // Each profile point gives the ring that ends the band below (`top`) and the one that starts
+  // the band above (`ring`); they are the same ring unless the profile creases there.
+  const top: number[][] = [];
+  if (o.faceted) facets(o, put, tri, sideUv);
+  else
+    o.profile.forEach(([r, z], i) => {
+      const prev = o.profile[i - 1] ?? o.profile[i] ?? [r, z];
+      const next = o.profile[i + 1] ?? o.profile[i] ?? [r, z];
+      const ir = r - prev[0];
+      const iz = z - prev[1];
+      const or = next[0] - r;
+      const oz = next[1] - z;
+      const li = Math.hypot(ir, iz);
+      const lo = Math.hypot(or, oz);
+      if (li > 1e-12 && lo > 1e-12 && (ir * or + iz * oz) / (li * lo) < creaseCos) {
+        top.push(emitRing(i, ir, iz));
+        ring.push(emitRing(i, or, oz));
+        return;
+      }
+      // Profile-tangent normal: perpendicular to the neighbour chord in (r, z).
+      const row = emitRing(i, next[0] - prev[0], next[1] - prev[1]);
+      top.push(row);
+      ring.push(row);
+    });
+  for (let i = 0; i + 1 < ring.length; i++) {
+    for (let s = 0; s < o.segments; s++) {
+      const a = ring[i]?.[s] ?? 0;
+      const bb = ring[i]?.[s + 1] ?? 0;
+      const c = top[i + 1]?.[s + 1] ?? 0;
+      const d = top[i + 1]?.[s] ?? 0;
+      tri(a, bb, c);
+      tri(a, c, d);
+    }
+  }
+  if (o.caps) {
+    const ends = [
+      { pt: o.profile[0], n: -1 },
+      { pt: o.profile[o.profile.length - 1], n: 1 },
+    ];
+    for (const { pt, n } of ends) {
+      if (!pt) continue;
+      const centre = put([0, 0, pt[1]], [0, 0, n], capUv(0, 0, pt[0]));
+      const rim: number[] = [];
+      for (let s = 0; s <= o.segments; s++) {
+        const t = (s / o.segments) * Math.PI * 2 - Math.PI / 2;
+        rim.push(
+          put(
+            [pt[0] * Math.cos(t), pt[0] * Math.sin(t), pt[1]],
+            [0, 0, n],
+            capUv(Math.cos(t), Math.sin(t), pt[0]),
+          ),
+        );
+      }
+      for (let s = 0; s < o.segments; s++) {
+        const r0 = rim[s] ?? 0;
+        const r1 = rim[s + 1] ?? 0;
+        if (n > 0) tri(centre, r0, r1);
+        else tri(centre, r1, r0);
+      }
+    }
+  }
+  return b.build();
+}
+
+/** Convenience: a capped cylinder, the most common lathe. */
+export const cylinder = (
+  o: Omit<LatheOptions, 'profile' | 'caps'> & { radius: number; length: number },
+): Mesh =>
+  lathe({
+    ...o,
+    profile: [
+      [o.radius, -o.length / 2],
+      [o.radius, o.length / 2],
+    ],
+    caps: true,
+  });