@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/kinds/head-rim.ts

@@ -0,0 +1,128 @@
+// Seamless split: a mesher rounds the edge where the jaw cut meets the skin by about one cell, so
+// the head and jaw would show a groove along the cut. This pass snaps every vertex near that rim
+// back onto the exact surfaces — skin vertices onto skull = 0, cut-face vertices onto cut = 0, both
+// clamped to their side — and gives skin vertices the skull's own normal, so the two parts meet on
+// one crease line with matching shading.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+
+/** A mutable point/vector (core's Vec3 is readonly). */
+type P3 = [number, number, number];
+
+import type { Field } from '../primitives/index.ts';
+
+function grad(f: Field, p: Vec3, e: number, out: P3): number {
+  const q: P3 = [p[0], p[1], p[2]];
+  const at = (dx: number, dy: number, dz: number): number => {
+    q[0] = p[0] + dx;
+    q[1] = p[1] + dy;
+    q[2] = p[2] + dz;
+    return f(q);
+  };
+  out[0] = (at(e, 0, 0) - at(-e, 0, 0)) / (2 * e);
+  out[1] = (at(0, e, 0) - at(0, -e, 0)) / (2 * e);
+  out[2] = (at(0, 0, e) - at(0, 0, -e)) / (2 * e);
+  return f(p);
+}
+
+/** Newton step of `p` towards f = 0 (only when f > 0 if `onlyOutside`). */
+function project(f: Field, p: P3, e: number, onlyOutside: boolean): void {
+  const g: P3 = [0, 0, 0];
+  const v = grad(f, p, e, g);
+  if (onlyOutside && v <= 0) return;
+  const gg = g[0] * g[0] + g[1] * g[1] + g[2] * g[2];
+  if (gg < 1e-12) return;
+  for (let k = 0; k < 3; k++) p[k] = (p[k] ?? 0) - (v * (g[k] ?? 0)) / gg;
+}
+
+/** Part ≈ max(skull, side); `side` is the cut field signed so the part is where side < 0;
+ *  `part` is the part's full field (with ears/tusks), so their vertices are left alone. */
+export function sharpenRim(m: Mesh, skull: Field, side: Field, part: Field, res: number): Mesh {
+  const positions = new Float32Array(m.positions);
+  const normals = new Float32Array(m.normals);
+  const e = res * 0.25;
+  const gs: P3 = [0, 0, 0];
+  const gc: P3 = [0, 0, 0];
+  for (let i = 0; i < positions.length; i += 3) {
+    const p: P3 = [positions[i] ?? 0, positions[i + 1] ?? 0, positions[i + 2] ?? 0];
+    // The cut is cheap and analytic; the skull is the costly sculpt — test the cut first.
+    if (Math.abs(side(p)) > res * 2) continue;
+    const c = grad(side, p, e, gc);
+    const s = grad(skull, p, e, gs);
+    if (Math.abs(s) > res * 2) continue;
+    // Skip where an extra (ear, tusk) owns the surface.
+    if (part(p) < Math.max(s, c) - res * 0.5) continue;
+    const n: Vec3 = [normals[i] ?? 0, normals[i + 1] ?? 0, normals[i + 2] ?? 0];
+    const ls = Math.hypot(...gs) || 1;
+    const lc = Math.hypot(...gc) || 1;
+    const onSkin =
+      (n[0] * gs[0] + n[1] * gs[1] + n[2] * gs[2]) / ls >=
+      (n[0] * gc[0] + n[1] * gc[1] + n[2] * gc[2]) / lc;
+    for (let k = 0; k < 4; k++) {
+      if (onSkin) {
+        project(skull, p, e, false);
+        project(side, p, e, true);
+      } else {
+        project(side, p, e, false);
+        project(skull, p, e, true);
+      }
+    }
+    // Within ~half a cell of the other surface: snap onto the crease line itself, so no bevel
+    // strip (seen from outside as a dark groove) is left between skin and cut face.
+    const other = onSkin ? side(p) : skull(p);
+    if (other > -res * 0.6)
+      for (let k = 0; k < 6; k++) {
+        project(skull, p, e, false);
+        project(side, p, e, false);
+      }
+    positions[i] = p[0];
+    positions[i + 1] = p[1];
+    positions[i + 2] = p[2];
+    if (onSkin) {
+      grad(skull, p, e, gs);
+      const l = Math.hypot(...gs) || 1;
+      normals[i] = gs[0] / l;
+      normals[i + 1] = gs[1] / l;
+      normals[i + 2] = gs[2] / l;
+    }
+  }
+  return { ...m, positions, normals };
+}
+
+/**
+ * Where a field gradient smears across a hard crease (the jaw cut at coarse cells), a vertex
+ * normal can oppose its triangles; those vertices take their area-weighted face normal instead.
+ */
+export function creaseNormals(m: Mesh, minDot = 0.2): Mesh {
+  const P = m.positions;
+  const acc = new Float64Array(P.length);
+  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 ux = (P[b] ?? 0) - (P[a] ?? 0);
+    const uy = (P[b + 1] ?? 0) - (P[a + 1] ?? 0);
+    const uz = (P[b + 2] ?? 0) - (P[a + 2] ?? 0);
+    const vx = (P[c] ?? 0) - (P[a] ?? 0);
+    const vy = (P[c + 1] ?? 0) - (P[a + 1] ?? 0);
+    const vz = (P[c + 2] ?? 0) - (P[a + 2] ?? 0);
+    const n = [uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx];
+    for (const v of [a, b, c])
+      for (let k = 0; k < 3; k++) acc[v + k] = (acc[v + k] ?? 0) + (n[k] ?? 0);
+  }
+  const normals = new Float32Array(m.normals);
+  for (let i = 0; i < normals.length; i += 3) {
+    const l = Math.hypot(acc[i] ?? 0, acc[i + 1] ?? 0, acc[i + 2] ?? 0);
+    if (l < 1e-20) continue;
+    const f = [(acc[i] ?? 0) / l, (acc[i + 1] ?? 0) / l, (acc[i + 2] ?? 0) / l];
+    const d =
+      (normals[i] ?? 0) * (f[0] ?? 0) +
+      (normals[i + 1] ?? 0) * (f[1] ?? 0) +
+      (normals[i + 2] ?? 0) * (f[2] ?? 0);
+    if (d >= minDot) continue;
+    normals[i] = f[0] ?? 0;
+    normals[i + 1] = f[1] ?? 0;
+    normals[i + 2] = f[2] ?? 0;
+  }
+  return { ...m, normals };
+}

package/src/kinds/head.ts

@@ -0,0 +1,171 @@
+// Head kind: `head(ctx, …)` sculpts a stylised fantasy head + bust from a race preset (orc, goblin,
+// human, dwarf, elf) or a full `HeadParams`, and emits the engine contract: `bust` (on z = 0),
+// `head`, `jaw` (pivot at the hinge, opens about Y), `eye_l` / `eye_r` (pivots at the eyeball
+// centres, gaze +X so an engine can aim them). Head units are scaled by `height` metres.
+// LOD policy: sculpt cell 2 % / 4.5 % / 14 % of the head height (HEAD_RES); LOD2 drops warts, wiry
+// tufts and the AO bake and floors ear/tusk thickness at about a cell so they survive. Vertex AO is
+// baked across all parts at LOD0/1 (creases, under the jaw, eye sockets).
+
+import {
+  type BuildContext,
+  type Mesh,
+  merge,
+  place,
+  type Rng,
+  Ts23dError,
+  type Vec3,
+} from '../core/index.ts';
+import { bakeAo } from '../passes/index.ts';
+import { sculptField } from '../primitives/index.ts';
+import { beardEdits, browEdits } from './head-beard.ts';
+import { bustEdits } from './head-bust.ts';
+import { earEdits, paintEdits, tuskEdits, wartEdits } from './head-extras.ts';
+import { primaryEdits, skullEdits } from './head-face.ts';
+import { hairEdits } from './head-hair.ts';
+import { type HeadLayout, headLayout } from './head-layout.ts';
+import { bustMesh, eyeMesh, type HeadEditSet, headAndJaw } from './head-mesh.ts';
+import { checkHead, type HeadParams } from './head-params.ts';
+import { HEADS, type HeadPreset } from './head-presets.ts';
+
+/** Overrides: top-level keys replace, nested objects merge one level (`{ jaw: { underbite: 0.1 } }`). */
+export type HeadOverrides = { readonly [K in keyof HeadParams]?: Partial<HeadParams[K]> };
+
+export interface HeadOptions {
+  readonly race?: HeadPreset | HeadParams;
+  readonly params?: HeadOverrides;
+  /** Part-name prefix: `orc` → `orc_head`, `orc_jaw`, `orc_eye_l` … Default none. */
+  readonly prefix?: string;
+  /** Where the bust base sits, metres. */
+  readonly at?: Vec3;
+  /** Baked jaw motion (degrees either side of rest, 0 = static pivot). Default 0. */
+  readonly jawSway?: number;
+}
+
+export interface HeadInfo {
+  readonly parts: { bust: string; head: string; jaw: string; eyeL: string; eyeR: string };
+  /** Overall height of bust + head, metres. */
+  readonly height: number;
+  readonly params: HeadParams;
+}
+
+export function headParams(o: Pick<HeadOptions, 'race' | 'params'> = {}): HeadParams {
+  const r = o.race ?? 'human';
+  const base = typeof r === 'string' ? HEADS[r] : r;
+  if (!base)
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `unknown head race '${String(r)}'`,
+      fix: `use one of ${Object.keys(HEADS).join(', ')} or pass a HeadParams object`,
+    });
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(o.params ?? {})) {
+    const was = out[k];
+    out[k] =
+      v && typeof v === 'object' && !Array.isArray(v) && was && typeof was === 'object'
+        ? { ...was, ...v }
+        : v;
+  }
+  return checkHead(out as unknown as HeadParams);
+}
+
+/** Moves the eyes forward/back so they sit in the face surface: probe the brain case + face
+ *  plate along −X at the eye, then sink the eyeball by `brow.overhang`. */
+function seatEyes(p: HeadParams, l: HeadLayout): HeadLayout {
+  const f = sculptField(primaryEdits(l), { color: p.colors.skin }).field;
+  const [, ey, ez] = l.eye;
+  let x = l.faceX + 0.4;
+  for (let i = 0; i < 400 && f([x, ey, ez]) > 0; i++) x -= 0.002;
+  const r = l.eyeR;
+  return { ...l, eye: [x - r * 0.7 - p.brow.overhang * 0.3, ey, ez] };
+}
+
+/** Sculpt cell edge per LOD, in head units (× height = metres). */
+export const HEAD_RES = [0.02, 0.045, 0.14] as const;
+
+/** Every edit list of a head, in head units (pure: same params + rng state → same edits). */
+export function headEdits(
+  p: HeadParams,
+  rng: Rng,
+  lod: 0 | 1 | 2 = 0,
+): HeadEditSet & { layout: HeadLayout } {
+  const l = seatEyes(p, headLayout(p));
+  const res = HEAD_RES[lod];
+  const warts = lod < 2 ? wartEdits(p, l, rng) : [];
+  const hair = lod < 2 || p.hair !== 'tufts' ? hairEdits(p, l) : [];
+  return {
+    layout: l,
+    skull: [
+      ...skullEdits(p, l),
+      ...hair,
+      ...browEdits(p, l),
+      ...beardEdits(p, l),
+      ...warts,
+      ...paintEdits(p, l),
+    ],
+    ears: earEdits(p, l, res * 0.7),
+    tusks: tuskEdits(p, l, res * 0.45),
+    bust: bustEdits(p, l),
+  };
+}
+
+export function head(ctx: BuildContext, o: HeadOptions = {}): HeadInfo {
+  const p = headParams(o);
+  const set = headEdits(p, ctx.rng.fork('head'), ctx.lod);
+  const l = set.layout;
+  const H = p.height;
+  const res = HEAD_RES[ctx.lod];
+  const { head: hm, jaw: jm } = headAndJaw(p, l, set, res);
+  const bm = bustMesh(p, set, res * 1.6);
+  const eye = eyeMesh(p, l.eyeR, l.eyeR / ctx.pick([7, 3.5, 2.2]));
+  const [ox, oy, oz] = o.at ?? [0, 0, 0];
+  const toWorld = (m: Mesh, at: Vec3 = [0, 0, 0]): Mesh =>
+    place(m, { scale: H, at: [ox + at[0] * H, oy + at[1] * H, oz + (at[2] - l.base) * H] });
+  // Coarse LODs: the coarse socket would swallow the eyeball, so it sits a little proud.
+  const ex = l.eye[0] + (ctx.lod > 0 ? res * 0.4 : 0);
+  const [, ey, ez] = l.eye;
+  const world = {
+    bust: toWorld(bm),
+    head: toWorld(hm),
+    jaw: toWorld(jm),
+    eye_l: toWorld(eye, [ex, ey, ez]),
+    eye_r: toWorld(eye, [ex, -ey, ez]),
+  };
+  // AO occluders leave out the other half of the jaw split: its cut face lies flush against ours
+  // and would draw a dark line along the seam.
+  const occ = (skip: Mesh): Mesh => merge(Object.values(world).filter((m) => m !== skip));
+  const occHead = occ(world.jaw);
+  const occJaw = occ(world.head);
+  const ao = (m: Mesh, by: Mesh = occHead): Mesh =>
+    ctx.lod < 2
+      ? bakeAo(m, { samples: ctx.pick([16, 10, 8]), radius: (0.12 * H) / 0.23, strength: 0.55 }, by)
+      : m;
+  const pre = o.prefix ? `${o.prefix}_` : '';
+  const pivot = (x: number, y: number, z: number): Vec3 => [
+    ox + x * H,
+    oy + y * H,
+    oz + (z - l.base) * H,
+  ];
+  const local = (m: Mesh, at: Vec3, by?: Mesh): Mesh =>
+    place(ao(m, by), { at: [-at[0], -at[1], -at[2]] });
+  const hinge = pivot(l.hinge[0], 0, l.hinge[1]);
+  const eyeL = pivot(ex, ey, ez);
+  const eyeR = pivot(ex, -ey, ez);
+  const names = {
+    bust: `${pre}bust`,
+    head: `${pre}head`,
+    jaw: `${pre}jaw`,
+    eyeL: `${pre}eye_l`,
+    eyeR: `${pre}eye_r`,
+  };
+  ctx.part(names.bust, ao(world.bust));
+  ctx.part(names.head, ao(world.head));
+  const sway = o.jawSway ?? 0;
+  ctx.part(names.jaw, local(world.jaw, hinge, occJaw), {
+    at: hinge,
+    ...(sway > 0
+      ? { motion: { kind: 'sway', axis: [0, 1, 0], degrees: sway, hz: 0.5 }, clearOf: [names.head] }
+      : {}),
+  });
+  ctx.part(names.eyeL, local(world.eye_l, eyeL), { at: eyeL });
+  ctx.part(names.eyeR, local(world.eye_r, eyeR), { at: eyeR });
+  return { parts: names, height: (l.crown - l.base) * H, params: p };
+}

package/src/kinds/hull-lines.ts

@@ -0,0 +1,160 @@
+// A hull's lines plan as functions, no mesh: deck-edge plan (half-breadth), sheer (deck-edge
+// height), keel/stem/counter profile and the section shape at any station. Waterline at z = 0,
+// bow toward +X, x = 0 amidships. Sections are superellipse quarters (n = 2 round bilge, 4 hard
+// bilge), going V toward the ends; the stem is where the keel line rises to meet the sheer.
+
+import { Ts23dError, type Vec3 } from '../core/index.ts';
+
+export interface HullColors {
+  /** Above the boot-top. */
+  readonly topsides: Vec3;
+  /** Below the waterline (antifouling). */
+  readonly bottom: Vec3;
+  /** The boot-top band at the waterline. Default near-black. */
+  readonly boot?: Vec3;
+  readonly deck: Vec3;
+  /** Inside of the bulwarks and the cap rail. Default = topsides. */
+  readonly bulwark?: Vec3;
+}
+
+export interface HullOptions {
+  /** Length overall at the deck, metres. */
+  readonly length: number;
+  /** Maximum beam at the deck edge. */
+  readonly beam: number;
+  /** Keel below the waterline. */
+  readonly draft: number;
+  /** Deck edge above the waterline amidships (lowest point of the sheer). */
+  readonly freeboard: number;
+  /** Sheer rise of the deck edge at [bow, stern] above amidships. Default [0.035, 0.012]·L. */
+  readonly sheer?: readonly [number, number];
+  /** 'round' (cruiser / tug) or 'transom' (flat stern). Default 'round'. */
+  readonly stern?: 'round' | 'transom';
+  /** Transom half-width as a share of the half-beam. Default 0.75. */
+  readonly transomWidth?: number;
+  /** Bilge: section superellipse exponent, 1.5 (soft V) … 5 (barge). Default 3. */
+  readonly fullness?: number;
+  /** Plan entrance exponent at the bow: 1.4 sharp … 3 bluff. Default 2. */
+  readonly entrance?: number;
+  /** Deck-edge breadth over waterline breadth − 1. Default 0.06. */
+  readonly flare?: number;
+  /** Bottom deadrise, degrees. Default 5. */
+  readonly deadriseDeg?: number;
+  /** Bulwark height above the deck, metres; 0 = none. Default 0. */
+  readonly bulwark?: number;
+  /** Deck camber at the centreline, metres. Default beam / 50. */
+  readonly camber?: number;
+  /** Height of the boot-top band above the waterline. Default 0.3. */
+  readonly bootTop?: number;
+  readonly colors: HullColors;
+  /** A rubbing strake / fender along each side just below the sheer (LOD0/1). */
+  readonly fender?: { readonly color: Vec3; readonly radius?: number };
+  /** Waterline amidships. Default [0, 0, 0]. */
+  readonly at?: Vec3;
+}
+
+export interface HullLines {
+  readonly L: number;
+  /** Deck-edge half-breadth at x (outer hull). */
+  readonly halfBreadth: (x: number) => number;
+  /** Deck-edge height at x (sheer line), relative to the waterline. */
+  readonly deck: (x: number) => number;
+  /** Keel / stem / counter height at x. */
+  readonly keel: (x: number) => number;
+  /** Section point at x for θ ∈ [0, π/2] (0 = keel, π/2 = deck edge), starboard (y ≥ 0). */
+  readonly section: (x: number, theta: number) => [number, number];
+}
+
+const bad = (cause: string, fix: string): Ts23dError =>
+  new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+
+export function validateHull(o: HullOptions): void {
+  const dims = [o.length, o.beam, o.draft, o.freeboard];
+  if (!dims.every((v) => v > 0 && Number.isFinite(v)))
+    throw bad(
+      `hull length/beam/draft/freeboard = ${dims.join(' / ')}`,
+      'give all four in metres, > 0 (a harbour tug: 30 / 9 / 4 / 1.2)',
+    );
+  if (o.beam > o.length * 0.8)
+    throw bad(
+      `hull beam ${o.beam} is over 0.8 × length ${o.length}`,
+      'check the numbers: length/beam is 2.5–4 for tugs, 6–9 for ships',
+    );
+  const n = o.fullness ?? 3;
+  if (!(n >= 1.2 && n <= 8)) throw bad(`hull fullness is ${n}`, 'use 1.5 (soft V) … 5 (barge)');
+  const tw = o.transomWidth ?? 0.75;
+  if (!(tw > 0 && tw <= 1))
+    throw bad(`hull transomWidth is ${tw}`, 'use a share 0.3–1 of the half-beam');
+}
+
+const smooth = (t: number): number => (t <= 0 ? 0 : t >= 1 ? 1 : t * t * (3 - 2 * t));
+
+export function hullLines(o: HullOptions): HullLines {
+  validateHull(o);
+  const L = o.length;
+  const half = L / 2;
+  const [sb, ss] = o.sheer ?? [0.035 * L, 0.012 * L];
+  const round = (o.stern ?? 'round') === 'round';
+  const tw = o.transomWidth ?? 0.75;
+  const pe = o.entrance ?? 2;
+  const n = o.fullness ?? 3;
+  const flare = o.flare ?? 0.06;
+  const dead = Math.tan(((o.deadriseDeg ?? 5) * Math.PI) / 180);
+  // Parallel middle body and where the keel starts to rise, as shares of L.
+  const xf = 0.1 * L;
+  const xa = -0.15 * L;
+  const kf = 0.22 * L;
+  const ka = -0.25 * L;
+  const deck = (x: number): number => {
+    const u = x / half;
+    return o.freeboard + (u > 0 ? sb : ss) * u * u;
+  };
+  const plan = (x: number): number => {
+    if (x > xf) return 1 - ((x - xf) / (half - xf)) ** pe;
+    if (x < xa) {
+      const v = Math.min(1, (xa - x) / (xa + half));
+      return round ? Math.sqrt(Math.max(0, 1 - v * v)) : 1 - (1 - tw) * v * v;
+    }
+    return 1;
+  };
+  const halfBreadth = (x: number): number => (o.beam / 2) * Math.max(0, plan(x));
+  const counter = round ? 0.35 * o.freeboard : 0.15 * o.freeboard;
+  const keel = (x: number): number => {
+    if (x > kf) {
+      const u = Math.min(1, (x - kf) / (half - kf));
+      return -o.draft + (deck(half) + o.draft) * u ** 2;
+    }
+    if (x < ka) {
+      const v = Math.min(1, (ka - x) / (ka + half));
+      return -o.draft + (counter + o.draft) * v ** 1.6;
+    }
+    return -o.draft;
+  };
+  const section = (x: number, theta: number): [number, number] => {
+    const f = plan(x);
+    // Fine ends go V-sectioned; the middle body keeps the full bilge.
+    const ns = 1.2 + (n - 1.2) * smooth(f / 0.8);
+    const s = Math.sin(theta) ** (2 / ns);
+    const c = Math.cos(theta) ** (2 / ns);
+    const zk = keel(x);
+    const zd = deck(x);
+    const zf = 1 - c;
+    const y = halfBreadth(x) * (1 - flare + flare * zf * zf) * s;
+    return [y, zk + (zd - zk) * zf + dead * y * c];
+  };
+  return { L, halfBreadth, deck, keel, section };
+}
+
+/** θ where the section crosses height z (bisection; the section rises monotonically). */
+export function thetaAt(lines: HullLines, x: number, z: number): number {
+  let lo = 0;
+  let hi = Math.PI / 2;
+  if (lines.section(x, lo)[1] >= z) return lo;
+  if (lines.section(x, hi)[1] <= z) return hi;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    if (lines.section(x, mid)[1] < z) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}

package/src/kinds/hull-skin.ts

@@ -0,0 +1,83 @@
+// Skinning for hull-like surfaces: a station × column grid of points becomes quads with smooth
+// normals (central differences; collapsed rows such as a stem head borrow their neighbour's), and
+// any column range can be emitted as its own colour band, mirrored to port for a symmetric hull.
+
+import type { MeshBuilder, Vec3 } from '../core/index.ts';
+import { stripRect } from '../material/index.ts';
+
+export type Grid = Vec3[][];
+const sub3 = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const cross3 = (a: Vec3, b: Vec3): Vec3 => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+
+/** Smooth normals over a station × column grid (outward = tj × ti for the starboard side). */
+export function normalsOf(g: Grid): Grid {
+  const R = g.length;
+  const out: Grid = g.map((row, i) =>
+    row.map((p, j) => {
+      const r = (k: number): Vec3[] => g[Math.max(0, Math.min(R - 1, k))] ?? row;
+      const ti = sub3(r(i + 1)[j] ?? p, r(i - 1)[j] ?? p);
+      const tj = sub3(row[Math.min(row.length - 1, j + 1)] ?? p, row[Math.max(0, j - 1)] ?? p);
+      const n = cross3(tj, ti);
+      const l = Math.hypot(...n);
+      return l < 1e-9 ? ([0, 0, 0] as Vec3) : ([n[0] / l, n[1] / l, n[2] / l] as Vec3);
+    }),
+  );
+  // Collapsed rows (stem head, round stern post) borrow the nearest row's normals.
+  for (let i = 0; i < R; i++) {
+    const row = out[i] ?? [];
+    row.forEach((n, j) => {
+      if (n[0] || n[1] || n[2]) return;
+      for (let d = 1; d < R; d++) {
+        const m = out[i - d]?.[j] ?? out[i + d]?.[j];
+        if (m && (m[0] || m[1] || m[2])) {
+          row[j] = m;
+          return;
+        }
+      }
+    });
+  }
+  return out;
+}
+
+/** Emit columns [j0, j1] of a starboard grid and its port mirror. */
+export function emitBand(
+  b: MeshBuilder,
+  g: Grid,
+  nrm: Grid,
+  j0: number,
+  j1: number,
+  color: Vec3,
+  mirror: boolean,
+): void {
+  const rect = stripRect('plain');
+  for (const side of mirror ? [1, -1] : [1]) {
+    const ids = g.map((row, i) =>
+      row.slice(j0, j1 + 1).map((p, k) => {
+        const n = nrm[i]?.[j0 + k] ?? [0, 0, 1];
+        return b.vertex({
+          p: [p[0], p[1] * side, p[2]],
+          n: [n[0], n[1] * side, n[2]],
+          uv: [
+            rect.u0 + p[0] / rect.metres,
+            rect.v0 + (k / Math.max(1, j1 - j0)) * (rect.v1 - rect.v0),
+          ],
+          color,
+        });
+      }),
+    );
+    for (let i = 0; i + 1 < ids.length; i++) {
+      for (let k = 0; k < j1 - j0; k++) {
+        const a = ids[i]?.[k] ?? 0;
+        const c = ids[i]?.[k + 1] ?? 0;
+        const e = ids[i + 1]?.[k + 1] ?? 0;
+        const d = ids[i + 1]?.[k] ?? 0;
+        if (side > 0) b.quad(a, c, e, d);
+        else b.quad(a, d, e, c);
+      }
+    }
+  }
+}