@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/primitives/sweep.ts

@@ -0,0 +1,162 @@
+// Sweep a closed 2D section along a 3D polyline: branches, trunks, roots, pipes, cables, handrails.
+// SMOOTH normals (a swept tube reads as round; caps are flat). Parallel-transport frames, so no
+// twist flip. Positions are absolute: the path is in the caller's space (no `at`). UVs: U runs
+// along the path in true metres (the strip's tiling axis, like `planar`/`tiled`); V goes once
+// around the section inside the strip's band. Triangles = 2·S·(P−1) + S per cap (S section
+// points, P path points).
+
+import { type Mesh, MeshBuilder, Ts23dError, type Vec2, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { arcLengths, transportFrames } from './transport.ts';
+
+export interface SweepOptions {
+  /** Closed section in the frame's (normal, binormal) plane, either winding; or a circle. */
+  readonly section: readonly Vec2[] | { readonly radius: number; readonly segments: number };
+  readonly path: readonly Vec3[];
+  /** Section scale per path point (taper). Default 1 everywhere. */
+  readonly scale?: readonly number[];
+  /** Total section rotation from first to last point, degrees, spread by arc length. */
+  readonly twist?: number;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  /** Close the ends with fans about the path point: both, or just one. */
+  readonly caps?: boolean | 'start' | 'end';
+}
+
+interface Section {
+  readonly pts: readonly Vec2[];
+  /** Outward 2D vertex normals. */
+  readonly nrm: readonly Vec2[];
+}
+
+function section(s: SweepOptions['section']): Section {
+  if (!Array.isArray(s)) {
+    const c = s as { radius: number; segments: number };
+    if (c.segments < 3 || !(c.radius > 0)) {
+      throw new Ts23dError('T3D_RECIPE_INVALID', {
+        cause: `sweep circle section has radius ${c.radius} and ${c.segments} segments`,
+        fix: 'use radius > 0 and segments >= 3 (pick segments from ctx.lod: e.g. 8 / 5 / 3)',
+      });
+    }
+    const nrm: Vec2[] = [];
+    for (let k = 0; k < c.segments; k++) {
+      const a = (k / c.segments) * Math.PI * 2;
+      nrm.push([Math.cos(a), Math.sin(a)]);
+    }
+    return { pts: nrm.map(([x, y]) => [x * c.radius, y * c.radius]), nrm };
+  }
+  const poly = s as readonly Vec2[];
+  if (poly.length < 3) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `sweep section has ${poly.length} point(s)`,
+      fix: 'pass a closed polygon of at least 3 points, or { radius, segments }',
+    });
+  }
+  const area = poly.reduce((a, p, i) => {
+    const q = poly[(i + 1) % poly.length] ?? p;
+    return a + p[0] * q[1] - q[0] * p[1];
+  }, 0);
+  const pts = area < 0 ? [...poly].reverse() : poly;
+  const nrm = pts.map((p, i): Vec2 => {
+    const a = pts[(i + pts.length - 1) % pts.length] ?? p;
+    const b = pts[(i + 1) % pts.length] ?? p;
+    const e1 = Math.hypot(p[0] - a[0], p[1] - a[1]) || 1;
+    const e2 = Math.hypot(b[0] - p[0], b[1] - p[1]) || 1;
+    const x = (p[1] - a[1]) / e1 + (b[1] - p[1]) / e2;
+    const y = -(p[0] - a[0]) / e1 - (b[0] - p[0]) / e2;
+    const l = Math.hypot(x, y) || 1;
+    return [x / l, y / l];
+  });
+  return { pts, nrm };
+}
+
+export function sweep(o: SweepOptions): Mesh {
+  const arc = arcLengths(o.path);
+  const frames = transportFrames(o.path);
+  const P = o.path.length;
+  if (o.scale && o.scale.length !== P) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `sweep has ${P} path points but ${o.scale.length} scales`,
+      fix: 'pass exactly one scale per path point (or omit scale for a constant section)',
+    });
+  }
+  const sec = section(o.section);
+  const S = sec.pts.length;
+  const total = arc[P - 1] ?? 1;
+  const rect = stripRect(o.strip ?? 'plain');
+  const du = (rect.u1 - rect.u0) / rect.metres;
+  const twist = ((o.twist ?? 0) * Math.PI) / 180;
+  const b = new MeshBuilder();
+  /** Rim positions per ring (S each), kept for the caps. */
+  const rim = new Float64Array(P * S * 3);
+  for (let i = 0; i < P; i++) {
+    const c = o.path[i] ?? [0, 0, 0];
+    const { t, n, b: bn } = frames[i] ?? { t: [0, 0, 1], n: [1, 0, 0], b: [0, 1, 0] };
+    const k = o.scale?.[i] ?? 1;
+    // Taper slope dk/ds tilts the smooth normal back along the tangent (a cone, not a cylinder).
+    const i0 = Math.max(0, i - 1);
+    const i1 = Math.min(P - 1, i + 1);
+    const slope =
+      ((o.scale?.[i1] ?? 1) - (o.scale?.[i0] ?? 1)) / ((arc[i1] ?? 0) - (arc[i0] ?? 0) || 1);
+    const rot = (twist * (arc[i] ?? 0)) / total;
+    const cr = Math.cos(rot);
+    const sr = Math.sin(rot);
+    const u = rect.u0 + (arc[i] ?? 0) * du;
+    for (let j = 0; j <= S; j++) {
+      const [px, py] = sec.pts[j % S] ?? [0, 0];
+      const [nx, ny] = sec.nrm[j % S] ?? [1, 0];
+      const x = (px * cr - py * sr) * k;
+      const y = (px * sr + py * cr) * k;
+      const mx = nx * cr - ny * sr;
+      const my = nx * sr + ny * cr;
+      const back = -slope * (px * nx + py * ny);
+      const qx = mx * n[0] + my * bn[0] + back * t[0];
+      const qy = mx * n[1] + my * bn[1] + back * t[1];
+      const qz = mx * n[2] + my * bn[2] + back * t[2];
+      const ql = Math.hypot(qx, qy, qz) || 1;
+      const p: Vec3 = [
+        c[0] + x * n[0] + y * bn[0],
+        c[1] + x * n[1] + y * bn[1],
+        c[2] + x * n[2] + y * bn[2],
+      ];
+      if (j < S) rim.set(p, (i * S + j) * 3);
+      b.vertex({
+        p,
+        n: [qx / ql, qy / ql, qz / ql],
+        uv: [u, rect.v0 + (j / S) * (rect.v1 - rect.v0)],
+        color: o.color,
+      });
+    }
+  }
+  for (let i = 0; i + 1 < P; i++) {
+    const r0 = i * (S + 1);
+    const r1 = r0 + S + 1;
+    for (let j = 0; j < S; j++) b.quad(r0 + j, r0 + j + 1, r1 + j + 1, r1 + j);
+  }
+  const caps = o.caps === true ? ['start', 'end'] : o.caps ? [o.caps] : [];
+  for (const end of caps) {
+    const i = end === 'start' ? 0 : P - 1;
+    const f = frames[i]?.t ?? [0, 0, 1];
+    const sign = end === 'start' ? -1 : 1;
+    const nn: Vec3 = [f[0] * sign, f[1] * sign, f[2] * sign];
+    const centre = b.vertex({
+      p: o.path[i] ?? [0, 0, 0],
+      n: nn,
+      uv: [rect.u0, rect.v0],
+      color: o.color,
+    });
+    const first = centre + 1;
+    for (let j = 0; j < S; j++) {
+      const q = (i * S + j) * 3;
+      const p: Vec3 = [rim[q] ?? 0, rim[q + 1] ?? 0, rim[q + 2] ?? 0];
+      b.vertex({ p, n: nn, uv: [rect.u0, rect.v1], color: o.color });
+    }
+    for (let j = 0; j < S; j++) {
+      const a = first + j;
+      const c = first + ((j + 1) % S);
+      if (sign > 0) b.tri(centre, a, c);
+      else b.tri(centre, c, a);
+    }
+  }
+  return b.build();
+}

package/src/primitives/terrain-color.ts

@@ -0,0 +1,85 @@
+// Vertex colour for terrain from what shapes real mountainsides: altitude bands (forest below the
+// treeline, meadow above it, bare debris higher up), slope (rock where it is too steep to hold
+// soil or snow), hydraulic deposit (scree fans and valley gravel) and flow (damp, dark gullies),
+// and snow above the snowline on slopes gentle enough to hold it. Returns `(x, y, z) => colour`
+// for `heightfield`'s `color`. Boundaries are jittered by an optional noise so bands never read as
+// contour lines.
+
+import type { Vec3 } from '../core/index.ts';
+import type { Noise2 } from './noise.ts';
+import { sampler, slopeMap, type TerrainGrid } from './terrain-grid.ts';
+
+export interface TerrainPalette {
+  readonly forest: Vec3;
+  readonly grass: Vec3;
+  /** Alpine debris/tundra above the meadows and on deposits. */
+  readonly scree: Vec3;
+  readonly rock: Vec3;
+  readonly snow: Vec3;
+  /** Damp ground in gullies and river beds. */
+  readonly wet: Vec3;
+}
+
+export interface TerrainColorOptions {
+  readonly palette: TerrainPalette;
+  /** Altitude of z = 0 in metres above sea level (z is relative to it). Default 0. */
+  readonly datum?: number;
+  /** Altitude where forest gives way to meadow, m. */
+  readonly treeline: number;
+  /** Altitude above which snow lies on gentle slopes, m. */
+  readonly snowline: number;
+  /** Slope (rise/run) where bare rock takes over: default 0.8 (≈ 39°). */
+  readonly rockSlope?: number;
+  /** Steepest slope that holds snow: default 1.0 (45°). */
+  readonly snowSlope?: number;
+  /** Noise in [−1, 1] (metres in) jittering every boundary; `jitter` = its altitude reach, m. */
+  readonly noise?: Noise2;
+  readonly jitter?: number;
+}
+
+const ramp = (a: number, b: number, x: number): number => {
+  const t = Math.min(1, Math.max(0, (x - a) / (b - a)));
+  return t * t * (3 - 2 * t);
+};
+
+export function terrainColor(
+  g: TerrainGrid,
+  o: TerrainColorOptions,
+): (x: number, y: number, z: number) => Vec3 {
+  const slope = sampler(g, slopeMap(g));
+  const flow = g.flow ? sampler(g, g.flow) : () => 0;
+  const dep = g.deposit ? sampler(g, g.deposit) : () => 0;
+  const P = o.palette;
+  const datum = o.datum ?? 0;
+  const rockS = o.rockSlope ?? 0.8;
+  const snowS = o.snowSlope ?? 1;
+  const jit = o.jitter ?? 60;
+  const c = [0, 0, 0];
+  const mix = (to: Vec3, w: number): void => {
+    for (let k = 0; k < 3; k++) c[k] = (c[k] ?? 0) + ((to[k] ?? 0) - (c[k] ?? 0)) * w;
+  };
+  return (x, y, z) => {
+    const n = o.noise ? o.noise(x, y) : 0;
+    const alt = z + datum + n * jit;
+    const s = slope(x, y) * (1 + 0.15 * n);
+    c[0] = P.forest[0];
+    c[1] = P.forest[1];
+    c[2] = P.forest[2];
+    mix(P.grass, ramp(o.treeline - 80, o.treeline + 80, alt));
+    mix(P.scree, 0.85 * ramp(o.treeline + 350, o.treeline + 800, alt));
+    // Forest thins on steep ground well below the treeline too.
+    mix(P.grass, ramp(0.55, 0.8, s) * (1 - ramp(o.treeline - 80, o.treeline + 80, alt)) * 0.6);
+    // Scree: sediment dropped on sloping ground (fans, cones); flat floors stay vegetated.
+    mix(
+      P.scree,
+      ramp(0.4, 0.8, dep(x, y)) * ramp(0.2, 0.45, s) * (1 - ramp(rockS, rockS + 0.3, s)),
+    );
+    mix(P.wet, 0.7 * ramp(0.35, 0.8, flow(x, y)) * (1 - ramp(o.snowline - 100, o.snowline, alt)));
+    mix(P.rock, ramp(rockS - 0.15, rockS + 0.15, s));
+    mix(
+      P.snow,
+      ramp(o.snowline - 60, o.snowline + 120, alt) * (1 - ramp(snowS - 0.3, snowS + 0.2, s)),
+    );
+    return [c[0] ?? 0, c[1] ?? 0, c[2] ?? 0];
+  };
+}

package/src/primitives/terrain-grid.ts

@@ -0,0 +1,137 @@
+// A terrain as a regular grid of heights in metres, the working surface for erosion and colouring:
+// sample it from any height function, read it back bilinearly at any (x, y) for `heightfield`
+// (so every LOD meshes the SAME eroded terrain at its own density), and relax it with thermal
+// erosion (material above the talus slope slides down). `flow`/`deposit` come from hydraulic
+// erosion and drive terrain colouring.
+
+import { count, invalid } from './check.ts';
+
+export interface TerrainGrid {
+  /** Points along X and Y (cells + 1). Row-major: index = j · nx + i. */
+  readonly nx: number;
+  readonly ny: number;
+  /** [minX, minY, maxX, maxY] in metres. */
+  readonly rect: readonly [number, number, number, number];
+  readonly z: Float64Array;
+  /** Water passage per point, 0..1 (rivers, gullies). Set by hydraulicErosion. */
+  readonly flow?: Float64Array;
+  /** Sediment laid down per point, 0..1 (scree fans, valley fill). Set by hydraulicErosion. */
+  readonly deposit?: Float64Array;
+}
+
+export interface TerrainGridOptions {
+  readonly rect: readonly [number, number, number, number];
+  /** Cells per side (points = cells + 1); 256 ≈ 8 m on a 2 km tile. */
+  readonly cells: number;
+  readonly height: (x: number, y: number) => number;
+}
+
+export function terrainGrid(o: TerrainGridOptions): TerrainGrid {
+  const [x0, y0, x1, y1] = o.rect;
+  if (!(x1 > x0 && y1 > y0))
+    invalid(
+      `terrain rect [${o.rect.join(', ')}] is empty`,
+      'pass [minX, minY, maxX, maxY] with max > min',
+    );
+  const n = count('terrain cells', o.cells, 2, 4096);
+  const z = new Float64Array((n + 1) * (n + 1));
+  for (let j = 0; j <= n; j++)
+    for (let i = 0; i <= n; i++) {
+      const h = o.height(x0 + ((x1 - x0) * i) / n, y0 + ((y1 - y0) * j) / n);
+      if (!Number.isFinite(h))
+        invalid(`terrain height is ${h} at point (${i}, ${j})`, 'return a finite height in metres');
+      z[j * (n + 1) + i] = h;
+    }
+  return { nx: n + 1, ny: n + 1, rect: o.rect, z };
+}
+
+/** Bilinear reader of any per-point map of the grid, clamped at the edges, in metres. */
+export function sampler(g: TerrainGrid, map: Float64Array = g.z): (x: number, y: number) => number {
+  const [x0, y0, x1, y1] = g.rect;
+  const sx = (g.nx - 1) / (x1 - x0);
+  const sy = (g.ny - 1) / (y1 - y0);
+  return (x, y) => {
+    const fx = Math.min(g.nx - 1, Math.max(0, (x - x0) * sx));
+    const fy = Math.min(g.ny - 1, Math.max(0, (y - y0) * sy));
+    const i = Math.min(g.nx - 2, Math.floor(fx));
+    const j = Math.min(g.ny - 2, Math.floor(fy));
+    const u = fx - i;
+    const v = fy - j;
+    const k = j * g.nx + i;
+    const a = map[k] ?? 0;
+    const b = map[k + 1] ?? 0;
+    const c = map[k + g.nx] ?? 0;
+    const d = map[k + g.nx + 1] ?? 0;
+    return a + (b - a) * u + (c + (d - c) * u - (a + (b - a) * u)) * v;
+  };
+}
+
+/** Slope (rise / run, tan of the angle) at every point, by central differences. */
+export function slopeMap(g: TerrainGrid): Float64Array {
+  const [x0, y0, x1, y1] = g.rect;
+  const dx = (x1 - x0) / (g.nx - 1);
+  const dy = (y1 - y0) / (g.ny - 1);
+  const out = new Float64Array(g.z.length);
+  for (let j = 0; j < g.ny; j++)
+    for (let i = 0; i < g.nx; i++) {
+      const l = g.z[j * g.nx + Math.max(0, i - 1)] ?? 0;
+      const r = g.z[j * g.nx + Math.min(g.nx - 1, i + 1)] ?? 0;
+      const b = g.z[Math.max(0, j - 1) * g.nx + i] ?? 0;
+      const t = g.z[Math.min(g.ny - 1, j + 1) * g.nx + i] ?? 0;
+      const sx = (r - l) / (dx * (Math.min(g.nx - 1, i + 1) - Math.max(0, i - 1)));
+      const sy = (t - b) / (dy * (Math.min(g.ny - 1, j + 1) - Math.max(0, j - 1)));
+      out[j * g.nx + i] = Math.sqrt(sx * sx + sy * sy);
+    }
+  return out;
+}
+
+export interface ThermalOptions {
+  /** Stable slope as rise/run: 0.7 ≈ 35° (scree's angle of repose). Default 0.7. */
+  readonly talus?: number;
+  readonly iterations?: number;
+  /** Share of the excess moved per iteration, 0..0.5. Default 0.4. */
+  readonly rate?: number;
+}
+
+/**
+ * Thermal erosion: wherever a neighbour sits lower than the talus slope allows, part of the
+ * excess slides down to it. Every iteration reads the old heights and writes a new array, so the
+ * result is independent of visiting order.
+ */
+export function thermalErosion(g: TerrainGrid, o: ThermalOptions = {}): TerrainGrid {
+  const talus = o.talus ?? 0.7;
+  const rate = Math.min(0.5, Math.max(0, o.rate ?? 0.4));
+  const iterations = count('thermal iterations', o.iterations ?? 30, 0, 10000);
+  const [x0, , x1] = g.rect;
+  const cell = (x1 - x0) / (g.nx - 1);
+  const D = [-1, 0, 1, 0, 0, -1, 0, 1, -1, -1, 1, -1, -1, 1, 1, 1];
+  const limit = D.map((_, k) => (k < 8 ? talus * cell : talus * cell * Math.SQRT2));
+  let z = Float64Array.from(g.z);
+  for (let it = 0; it < iterations; it++) {
+    const next = Float64Array.from(z);
+    for (let j = 1; j < g.ny - 1; j++)
+      for (let i = 1; i < g.nx - 1; i++) {
+        const k = j * g.nx + i;
+        const h = z[k] ?? 0;
+        let total = 0;
+        let most = 0;
+        for (let d = 0; d < 16; d += 2) {
+          const ex = h - (z[k + (D[d] ?? 0) + (D[d + 1] ?? 0) * g.nx] ?? 0) - (limit[d] ?? 0);
+          if (ex > 0) {
+            total += ex;
+            if (ex > most) most = ex;
+          }
+        }
+        if (total <= 0) continue;
+        const move = rate * most;
+        next[k] = (next[k] ?? 0) - move;
+        for (let d = 0; d < 16; d += 2) {
+          const n = k + (D[d] ?? 0) + (D[d + 1] ?? 0) * g.nx;
+          const ex = h - (z[n] ?? 0) - (limit[d] ?? 0);
+          if (ex > 0) next[n] = (next[n] ?? 0) + (move * ex) / total;
+        }
+      }
+    z = next;
+  }
+  return { ...g, z };
+}

package/src/primitives/text-layout.ts

@@ -0,0 +1,85 @@
+// Lettering layout for `text`: glyph lookup, advances, measureText, and the merge of each glyph's
+// pixels into as few rectangles as possible (runs along a row, then identical runs stacked down
+// the rows), so a stem is one box, not seven. All in pixel units; one pixel = cap height / 7.
+
+import { invalid } from './check.ts';
+import { GLYPHS, SUPPORTED_CHARS } from './font-5x7.ts';
+
+export type TextFont = '5x7' | 'block';
+
+export interface MeasureOptions {
+  /** Cap height in metres (the 7 glyph rows). */
+  readonly height: number;
+  readonly font?: TextFont;
+  /** Gap between glyphs in pixels (1 px = height / 7). Default 1. */
+  readonly tracking?: number;
+}
+
+/** A filled rectangle: columns [c0, c1) from the line start, rows [r0, r1) from the cap line. */
+export interface PixelRect {
+  readonly c0: number;
+  readonly c1: number;
+  readonly r0: number;
+  readonly r1: number;
+}
+
+const SPACE = 3;
+
+/** Rows of one glyph in `font`; block = emboldened (each pixel doubled rightward, 6 wide). */
+function rows(ch: string, font: TextFont): { rows: readonly number[]; width: number } {
+  const g = GLYPHS[ch] ?? GLYPHS[ch.toUpperCase()];
+  if (!g)
+    invalid(
+      `text: no glyph for ${JSON.stringify(ch)} (U+${(ch.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, '0')})`,
+      `use only these characters (lower case is set as upper case): ${SUPPORTED_CHARS}`,
+    );
+  if (ch === ' ') return { rows: g, width: SPACE };
+  return font === 'block' ? { rows: g.map((r) => (r << 1) | r), width: 6 } : { rows: g, width: 5 };
+}
+
+/** Width in pixels of a line. */
+function widthPx(str: string, font: TextFont, tracking: number): number {
+  const chars = [...str];
+  return (
+    chars.reduce((w, ch) => w + rows(ch, font).width, 0) + Math.max(0, chars.length - 1) * tracking
+  );
+}
+
+/** Width of `str` in metres when set at cap `height`. Throws on characters without a glyph. */
+export function measureText(str: string, o: MeasureOptions): number {
+  return (widthPx(str, o.font ?? '5x7', o.tracking ?? 1) * o.height) / 7;
+}
+
+/** The line as merged pixel rectangles, plus its width in pixels. */
+export function layout(
+  str: string,
+  font: TextFont,
+  tracking: number,
+): { rects: PixelRect[]; width: number } {
+  const rects: PixelRect[] = [];
+  let pen = 0;
+  for (const ch of str) {
+    const g = rows(ch, font);
+    let open = new Map<string, { c0: number; c1: number; r0: number }>();
+    for (let r = 0; r <= 7; r++) {
+      const bits = g.rows[r] ?? 0;
+      const next = new Map<string, { c0: number; c1: number; r0: number }>();
+      let c = 0;
+      while (c < g.width) {
+        if (!((bits >> (g.width - 1 - c)) & 1)) {
+          c++;
+          continue;
+        }
+        const start = c;
+        while (c < g.width && (bits >> (g.width - 1 - c)) & 1) c++;
+        const key = `${start},${c}`;
+        next.set(key, open.get(key) ?? { c0: start, c1: c, r0: r });
+      }
+      for (const [key, run] of open)
+        if (!next.has(key)) rects.push({ c0: pen + run.c0, c1: pen + run.c1, r0: run.r0, r1: r });
+      open = next;
+    }
+    pen += g.width + tracking;
+  }
+  return { rects, width: Math.max(0, pen - tracking) };
+}

package/src/primitives/text.ts

@@ -0,0 +1,197 @@
+// Lettering as geometry: name boards, wagon and locomotive lettering, hull markings, signs. Each
+// glyph of the built-in 5 × 7 font (font-5x7.ts; Latin, digits, punctuation, Cyrillic) becomes a
+// few merged rectangles: flush decals lifted 2 mm off the surface (depth 0, 2 triangles each) or
+// raised letters (depth > 0: face + 4 sides, 10 each). Flat normals. `surface(u, v)` gives the
+// face's offset under each letter piece, so lettering stays readable across stepped sheathing,
+// posts and battens (pieces split where the offset changes). Reads along `along`, upright along
+// `up`, facing along × up; `origin` is the baseline point at the `align` anchor.
+
+import { type Mesh, MeshBuilder, normalize, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { invalid } from './check.ts';
+import { stripU, stripV } from './strip-uv.ts';
+import { layout, measureText, type PixelRect, type TextFont } from './text-layout.ts';
+
+export { type MeasureOptions, measureText, type TextFont } from './text-layout.ts';
+
+export interface TextOptions {
+  readonly origin: Vec3;
+  /** Reading direction. Default +Y (a sign read from +X). */
+  readonly along?: Vec3;
+  /** Letter up. Default +Z. */
+  readonly up?: Vec3;
+  /** Cap height in metres. */
+  readonly height: number;
+  readonly color: Vec3;
+  readonly font?: TextFont;
+  /** Raised thickness in metres; 0 = flush decal lifted 2 mm. Default 0. */
+  readonly depth?: number;
+  /** Gap between glyphs in pixels (height / 7). Default 1. */
+  readonly tracking?: number;
+  readonly align?: 'left' | 'centre' | 'right';
+  /** Shrink the cap height so the line fits this width, metres. */
+  readonly maxWidth?: number;
+  /** Offset (m, along the facing normal) of the surface under a letter piece. `u` = metres along
+   *  `along` from `origin` (negative left of a centre/right anchor), `v` = metres up from it. */
+  readonly surface?: (u: number, v: number) => number;
+  readonly strip?: StripId;
+}
+
+const LIFT = 0.002;
+
+export function text(str: string, o: TextOptions): Mesh {
+  if (!(Number.isFinite(o.height) && o.height > 0 && o.height < 1000))
+    invalid(
+      `text height is ${o.height}`,
+      'give the cap height in metres, > 0 (e.g. 0.3 for wagon lettering)',
+    );
+  const depth = o.depth ?? 0;
+  if (!(Number.isFinite(depth) && depth >= 0))
+    invalid(`text depth is ${depth}`, 'use 0 (flush) or a raised thickness > 0 m');
+  const font = o.font ?? '5x7';
+  const tracking = o.tracking ?? 1;
+  let height = o.height;
+  if (o.maxWidth !== undefined) {
+    if (!(o.maxWidth > 0))
+      invalid(`text maxWidth is ${o.maxWidth}`, 'give the panel width in metres, > 0');
+    const w = measureText(str, { height, font, tracking });
+    if (w > o.maxWidth) height *= o.maxWidth / w;
+  }
+  const along = normalize(o.along ?? [0, 1, 0]);
+  const up0 = o.up ?? [0, 0, 1];
+  const k = up0[0] * along[0] + up0[1] * along[1] + up0[2] * along[2];
+  const upR: Vec3 = [up0[0] - along[0] * k, up0[1] - along[1] * k, up0[2] - along[2] * k];
+  if (Math.hypot(upR[0], upR[1], upR[2]) < 1e-9)
+    invalid('text: up is parallel to along', 'pass an `up` perpendicular to the reading direction');
+  const up = normalize(upR);
+  const n: Vec3 = [
+    along[1] * up[2] - along[2] * up[1],
+    along[2] * up[0] - along[0] * up[2],
+    along[0] * up[1] - along[1] * up[0],
+  ];
+  const px = height / 7;
+  const { rects, width } = layout(str, font, tracking);
+  const start = o.align === 'centre' ? (-width * px) / 2 : o.align === 'right' ? -width * px : 0;
+  const rect = stripRect(o.strip ?? 'plain');
+  const b = new MeshBuilder();
+  const at = (u: number, v: number, w: number): Vec3 => [
+    o.origin[0] + along[0] * u + up[0] * v + n[0] * w,
+    o.origin[1] + along[1] * u + up[1] * v + n[1] * w,
+    o.origin[2] + along[2] * u + up[2] * v + n[2] * w,
+  ];
+  /** Quad u0..u1 × v0..v1 at offsets w (per corner), facing `nrm`, CCW from that side. */
+  const quad = (
+    c: readonly Vec3[],
+    nrm: Vec3,
+    us: readonly number[],
+    vs: readonly number[],
+  ): void => {
+    const ids = c.map((p, i) =>
+      b.vertex({
+        p,
+        n: nrm,
+        uv: [
+          stripU(rect, us[i] ?? 0),
+          stripV(rect, Math.min(1, Math.max(0, (vs[i] ?? 0) / height))),
+        ],
+        color: o.color,
+      }),
+    );
+    const [a = n, e = n, f = n] = c;
+    const g = [0, 1, 2].map((j) => {
+      const [x, y] = [(j + 1) % 3, (j + 2) % 3];
+      return (
+        ((e[x] ?? 0) - (a[x] ?? 0)) * ((f[y] ?? 0) - (a[y] ?? 0)) -
+        ((e[y] ?? 0) - (a[y] ?? 0)) * ((f[x] ?? 0) - (a[x] ?? 0))
+      );
+    });
+    const [i0 = 0, i1 = 0, i2 = 0, i3 = 0] = ids;
+    if ((g[0] ?? 0) * nrm[0] + (g[1] ?? 0) * nrm[1] + (g[2] ?? 0) * nrm[2] >= 0)
+      b.quad(i0, i1, i2, i3);
+    else b.quad(i0, i3, i2, i1);
+  };
+  const neg = (v: Vec3): Vec3 => [-v[0], -v[1], -v[2]];
+  for (const piece of pieces(rects, px, start, o.surface)) {
+    const { u0, u1, v0, v1, s } = piece;
+    const lo = depth > 0 ? s : s + LIFT;
+    const hi = depth > 0 ? s + depth : lo;
+    quad(
+      [at(u0, v0, hi), at(u1, v0, hi), at(u1, v1, hi), at(u0, v1, hi)],
+      n,
+      [u0, u1, u1, u0],
+      [v0, v0, v1, v1],
+    );
+    if (depth <= 0) continue;
+    // Sides: bottom, right, top, left.
+    quad(
+      [at(u0, v0, lo), at(u1, v0, lo), at(u1, v0, hi), at(u0, v0, hi)],
+      neg(up),
+      [u0, u1, u1, u0],
+      [0, 0, depth, depth],
+    );
+    quad(
+      [at(u1, v0, lo), at(u1, v1, lo), at(u1, v1, hi), at(u1, v0, hi)],
+      along,
+      [v0, v1, v1, v0],
+      [0, 0, depth, depth],
+    );
+    quad(
+      [at(u1, v1, lo), at(u0, v1, lo), at(u0, v1, hi), at(u1, v1, hi)],
+      up,
+      [u1, u0, u0, u1],
+      [0, 0, depth, depth],
+    );
+    quad(
+      [at(u0, v1, lo), at(u0, v0, lo), at(u0, v0, hi), at(u0, v1, hi)],
+      neg(along),
+      [v1, v0, v0, v1],
+      [0, 0, depth, depth],
+    );
+  }
+  return b.build();
+}
+
+interface Piece {
+  readonly u0: number;
+  readonly u1: number;
+  readonly v0: number;
+  readonly v1: number;
+  /** Surface offset under this piece. */
+  readonly s: number;
+}
+
+/** Rects in metres, split into column groups wherever the surface offset changes. */
+function pieces(
+  rects: readonly PixelRect[],
+  px: number,
+  start: number,
+  surface?: (u: number, v: number) => number,
+): Piece[] {
+  const out: Piece[] = [];
+  for (const r of rects) {
+    const v0 = (7 - r.r1) * px;
+    const v1 = (7 - r.r0) * px;
+    if (!surface) {
+      out.push({ u0: start + r.c0 * px, u1: start + r.c1 * px, v0, v1, s: 0 });
+      continue;
+    }
+    // Each column sits on the highest surface anywhere under it (edges and centre, both ways),
+    // so a pixel half over a post is lifted onto the post, not buried in it.
+    const lift = (c: number): number => {
+      let top = Number.NEGATIVE_INFINITY;
+      for (const fu of [0.02, 0.5, 0.98])
+        for (const v of [v0 + 0.02 * px, (v0 + v1) / 2, v1 - 0.02 * px])
+          top = Math.max(top, surface(start + (c + fu) * px, v));
+      return top;
+    };
+    let c = r.c0;
+    while (c < r.c1) {
+      const s = lift(c);
+      let e = c + 1;
+      while (e < r.c1 && Math.abs(lift(e) - s) < 1e-6) e++;
+      out.push({ u0: start + c * px, u1: start + e * px, v0, v1, s });
+      c = e;
+    }
+  }
+  return out;
+}