@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/kinds/roof-shape.ts

@@ -0,0 +1,230 @@
+// Roof geometry as maths, no mesh: every pitched roof here is convex, so its surface is the LOWER
+// ENVELOPE (min) of a few planes over a plan outline. Gable = 2 planes, hip/pyramid = 4, gambrel =
+// 4, mansard = 8, shed = 1. Facets are the plan cells where one plane is lowest; ridges and hips
+// fall out as the creases between them. Local frame: `a` along the ridge, `b` across it, z up from
+// the wall plate; the roof UNDERSIDE passes through the top outer edge of every wall.
+
+import { Ts23dError, type Vec2, type Vec3 } from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { area2, clipPoly } from './faces.ts';
+
+export type RoofType = 'gable' | 'hip' | 'pyramid' | 'mansard' | 'gambrel' | 'shed';
+export type RoofSide = 'front' | 'back' | 'left' | 'right';
+
+export interface RoofOptions {
+  readonly type: RoofType;
+  /** Wall-line width (X) and depth (Y) of the mass the roof sits on, metres. */
+  readonly footprint: readonly [number, number];
+  /** Main slope, degrees (the lower, steep slope of a mansard or gambrel). */
+  readonly pitchDeg: number;
+  /** Centre of the footprint at wall-plate height (top of the walls). */
+  readonly at: Vec3;
+  readonly color: Vec3;
+  /** Roofing strip, laid in true-scale courses down the slope. Default 'slate'. */
+  readonly strip?: StripId;
+  /** Eave overhang past the walls, metres. Default 0.35. */
+  readonly overhang?: number;
+  /** Gable-end (rake) overhang; default = overhang. Hipped roofs ignore it. */
+  readonly rake?: number;
+  /** Slab thickness perpendicular to the slope (rafter + battens + slate). Default 0.18. */
+  readonly thickness?: number;
+  /** Ridge direction; default along the longer side. */
+  readonly ridge?: 'x' | 'y';
+  /** Shed only: the side the single slope falls toward. Default 'front' (+X). */
+  readonly low?: RoofSide;
+  /** Mansard / gambrel upper slope, degrees. Default 20 (mansard), 30 (gambrel). */
+  readonly upperPitchDeg?: number;
+  /** Mansard / gambrel: share of the half-span the lower slope covers in plan. Default 0.3 / 0.45. */
+  readonly knee?: number;
+}
+
+export interface Plane {
+  /** z = c + ga·a + gb·b (local, relative to the wall plate). */
+  readonly c: number;
+  readonly ga: number;
+  readonly gb: number;
+}
+
+export interface RoofShape {
+  readonly L: number;
+  readonly D: number;
+  /** Underside planes and the matching top planes (offset by the perpendicular thickness). */
+  readonly under: readonly Plane[];
+  readonly top: readonly Plane[];
+  /** Plan outline at the eaves (CCW, local a/b). */
+  readonly outline: readonly Vec2[];
+  /** Local unit axes in world XY: a → ex, b → ey (ex × ey = +Z). */
+  readonly ex: Vec2;
+  readonly ey: Vec2;
+  readonly thickness: number;
+}
+
+const RAD = Math.PI / 180;
+const FRAMES: Record<RoofSide, [Vec2, Vec2]> = {
+  // Frame whose −b side faces the named world side.
+  front: [
+    [0, 1],
+    [-1, 0],
+  ],
+  back: [
+    [0, -1],
+    [1, 0],
+  ],
+  left: [
+    [-1, 0],
+    [0, -1],
+  ],
+  right: [
+    [1, 0],
+    [0, 1],
+  ],
+};
+
+const bad = (cause: string, fix: string): Ts23dError =>
+  new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+
+export function validateRoof(o: RoofOptions): void {
+  const [w, d] = o.footprint;
+  if (!(w > 0 && d > 0 && Number.isFinite(w) && Number.isFinite(d)))
+    throw bad(
+      `roof footprint is [${w}, ${d}]`,
+      'pass the wall-line [width X, depth Y] in metres, both > 0',
+    );
+  const maxPitch = o.type === 'mansard' || o.type === 'gambrel' ? 85 : 75;
+  if (!(o.pitchDeg >= 3 && o.pitchDeg <= maxPitch))
+    throw bad(
+      `${o.type} roof pitchDeg is ${o.pitchDeg}`,
+      `use 3–${maxPitch}° (slate ≥ 20°, tile 30–45°, sheet metal ≥ 3°); for a flat roof use a box`,
+    );
+  const t = o.thickness ?? 0.18;
+  if (!(t > 0 && t < 1))
+    throw bad(`roof thickness is ${t}`, 'use 0.1–0.3 m (rafter + battens + slate)');
+  const ov = o.overhang ?? 0.35;
+  if (!(ov >= 0 && ov < 3) || !((o.rake ?? ov) >= 0))
+    throw bad(`roof overhang is ${ov}`, 'use 0–1.5 m past the wall line (0 for a party wall)');
+  if (o.type === 'mansard' || o.type === 'gambrel') {
+    const up = o.upperPitchDeg ?? (o.type === 'mansard' ? 20 : 30);
+    if (!(up > 0 && up < o.pitchDeg))
+      throw bad(
+        `${o.type} upperPitchDeg ${up} is not below pitchDeg ${o.pitchDeg}`,
+        'the upper slope must be shallower than the lower one (mansard 70°/20°, gambrel 60°/30°)',
+      );
+    const k = o.knee ?? 0.3;
+    if (!(k > 0 && k < 1))
+      throw bad(`${o.type} knee is ${k}`, 'use a fraction 0.15–0.6 of the half-span');
+  }
+}
+
+/** Planes of the roof UNDERSIDE for a type, in the local frame. */
+function underPlanes(o: RoofOptions, L: number, D: number): Plane[] {
+  const tp = Math.tan(o.pitchDeg * RAD);
+  const side = (s: number, c = 0, k = s): Plane[] => [
+    { c: c + D * k, ga: 0, gb: -s },
+    { c: c + D * k, ga: 0, gb: s },
+  ];
+  const ends = (s: number, c = 0, k = s): Plane[] => [
+    { c: c + L * k, ga: -s, gb: 0 },
+    { c: c + L * k, ga: s, gb: 0 },
+  ];
+  switch (o.type) {
+    case 'gable':
+      return side(tp);
+    case 'shed':
+      return [{ c: D * tp, ga: 0, gb: tp }];
+    case 'hip':
+      return [...side(tp), ...ends(tp)];
+    case 'pyramid': {
+      const h = Math.min(L, D) * tp;
+      return [...side(h / D), ...ends(h / L)];
+    }
+    case 'gambrel':
+    case 'mansard': {
+      const t2 = Math.tan((o.upperPitchDeg ?? (o.type === 'mansard' ? 20 : 30)) * RAD);
+      const r = (o.knee ?? (o.type === 'mansard' ? 0.3 : 0.45)) * Math.min(L, D);
+      // Upper plane: z = r·tp + (D − r − |b|)·t2 → c = r·tp + (D − r)·t2 with slope t2.
+      const upper = (half: number): number => r * tp + (half - r) * t2 - half * t2;
+      const lower = [...side(tp), ...(o.type === 'mansard' ? ends(tp) : [])];
+      const top = [
+        ...side(t2, upper(D), t2),
+        ...(o.type === 'mansard' ? ends(t2, upper(L), t2) : []),
+      ];
+      return [...lower, ...top];
+    }
+  }
+}
+
+export function roofShape(o: RoofOptions): RoofShape {
+  validateRoof(o);
+  const [w, d] = o.footprint;
+  const ridge = o.ridge ?? (w >= d ? 'x' : 'y');
+  const low: RoofSide = o.type === 'shed' ? (o.low ?? 'front') : ridge === 'x' ? 'right' : 'front';
+  const [ex, ey] = FRAMES[low];
+  const L = (Math.abs(ex[0]) > 0.5 ? w : d) / 2;
+  const D = (Math.abs(ex[0]) > 0.5 ? d : w) / 2;
+  const ov = o.overhang ?? 0.35;
+  const t = o.thickness ?? 0.18;
+  const under = underPlanes(o, L, D);
+  const top = under.map((p) => ({ ...p, c: p.c + t * Math.hypot(1, p.ga, p.gb) }));
+  const hipped = o.type === 'hip' || o.type === 'pyramid' || o.type === 'mansard';
+  const A = hipped ? 4 * (L + D + ov) : L + (o.rake ?? ov);
+  const B = D + ov;
+  // Eave height: the steepest-falling b-plane at the eave line; every plane must stay above it.
+  const g0 = under[0] ?? { c: 0, ga: 0, gb: 1 };
+  const zEave = -ov * Math.hypot(g0.ga, g0.gb);
+  let outline: Vec2[] = [
+    [-A, -B],
+    [A, -B],
+    [A, B],
+    [-A, B],
+  ];
+  for (const p of under) outline = clipPoly(outline, (q) => zEave - zAt(p, q));
+  return { L, D, under, top, outline, ex, ey, thickness: t };
+}
+
+export const zAt = (p: Plane, q: Vec2): number => p.c + p.ga * q[0] + p.gb * q[1];
+
+/** Envelope height (min of planes) at a local plan point. */
+export const envelope = (planes: readonly Plane[], q: Vec2): number =>
+  Math.min(...planes.map((p) => zAt(p, q)));
+
+/** The plan cell of each plane on the envelope (empty cells dropped), with its plane. */
+export function facets(planes: readonly Plane[], outline: readonly Vec2[]): [Plane, Vec2[]][] {
+  const out: [Plane, Vec2[]][] = [];
+  planes.forEach((p, i) => {
+    let cell: Vec2[] = [...outline];
+    planes.forEach((q, j) => {
+      if (j !== i && cell.length >= 3) cell = clipPoly(cell, (r) => zAt(p, r) - zAt(q, r));
+    });
+    if (cell.length >= 3 && Math.abs(area2(cell)) > 1e-6) out.push([p, cell]);
+  });
+  return out;
+}
+
+/** Local plan → world XY offset (add `at`). */
+export const toWorld = (s: RoofShape, q: Vec2, z: number, at: Vec3): Vec3 => [
+  at[0] + s.ex[0] * q[0] + s.ey[0] * q[1],
+  at[1] + s.ex[1] * q[0] + s.ey[1] * q[1],
+  at[2] + z,
+];
+
+/** World XY → local plan. */
+export const toLocal = (s: RoofShape, x: number, y: number, at: Vec3): Vec2 => {
+  const dx = x - at[0];
+  const dy = y - at[1];
+  return [dx * s.ex[0] + dy * s.ex[1], dx * s.ey[0] + dy * s.ey[1]];
+};
+
+/** World z of the roof's top surface at world (x, y) — chimneys, dormers, aerials sit on this. */
+export function roofHeightAt(o: RoofOptions, x: number, y: number): number {
+  const s = roofShape(o);
+  return o.at[2] + envelope(s.top, toLocal(s, x, y, o.at));
+}
+
+/** World z of the highest point of the roof surface (ridge or apex), slab included. */
+export function ridgeHeight(o: RoofOptions): number {
+  const s = roofShape(o);
+  let z = -Infinity;
+  for (const [p, cell] of facets(s.top, s.outline))
+    for (const q of cell) z = Math.max(z, zAt(p, q));
+  return o.at[2] + z;
+}

package/src/kinds/roof.ts

@@ -0,0 +1,250 @@
+// Pitched roofs as one mesh: true-scale roofing courses down every slope, a slab with real
+// thickness (soffit + fascia/bargeboards around the eaves), ridge and hip caps, gable infill walls
+// where the roof leaves a wall open, chimneys that stand on the attic floor and clear the slope.
+// LOD0/1 keep thickness, fascia and caps; LOD2 is the bare slopes + gables (a few dozen triangles).
+
+import {
+  type BuildContext,
+  type Lod,
+  type Mesh,
+  MeshBuilder,
+  merge,
+  type Vec2,
+  type Vec3,
+} from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { beam } from '../primitives/index.ts';
+import { emitFace } from './faces.ts';
+import { chimney, type RoofChimney } from './roof-chimney.ts';
+import {
+  envelope,
+  facets,
+  type Plane,
+  type RoofOptions,
+  type RoofShape,
+  ridgeHeight,
+  roofHeightAt,
+  roofShape,
+  toWorld,
+  zAt,
+} from './roof-shape.ts';
+
+export interface RoofMeshOptions extends RoofOptions {
+  /** Fascia, bargeboards, soffit and ridge caps. Default: the roof colour, darkened. */
+  readonly trim?: Vec3;
+  /** Gable / shed end infill walls. Default pale render. */
+  readonly wall?: { readonly color: Vec3; readonly strip?: StripId };
+  /** Ridge and hip caps (LOD0/1). Default true. */
+  readonly caps?: boolean;
+  readonly chimneys?: readonly RoofChimney[];
+}
+
+export interface RoofInfo {
+  /** World z of the ridge / apex top. */
+  readonly ridge: number;
+  /** World z of the lowest eave edge (underside). */
+  readonly eave: number;
+  /** World z of the top surface at world (x, y). */
+  readonly heightAt: (x: number, y: number) => number;
+}
+
+const W = (s: RoofShape, q: Vec2, z: number, at: Vec3): Vec3 => toWorld(s, q, z, at);
+const dirW = (s: RoofShape, a: number, b: number, z: number): Vec3 => [
+  s.ex[0] * a + s.ey[0] * b,
+  s.ex[1] * a + s.ey[1] * b,
+  z,
+];
+
+const onOutline = (outline: readonly Vec2[], q: Vec2): boolean =>
+  outline.some((a, i) => {
+    const b = outline[(i + 1) % outline.length] ?? a;
+    const ex = b[0] - a[0];
+    const ey = b[1] - a[1];
+    const l2 = ex * ex + ey * ey || 1;
+    const t = Math.max(0, Math.min(1, ((q[0] - a[0]) * ex + (q[1] - a[1]) * ey) / l2));
+    return Math.hypot(a[0] + ex * t - q[0], a[1] + ey * t - q[1]) < 1e-6;
+  });
+
+/** Slopes of one envelope: top (normal up) or underside (normal down). */
+function slopes(
+  b: MeshBuilder,
+  s: RoofShape,
+  planes: readonly Plane[],
+  o: RoofMeshOptions,
+  face: { down: boolean; color: Vec3; strip: StripId; banded: boolean },
+): [Plane, Vec2[]][] {
+  const cells = facets(planes, s.outline);
+  for (const [p, cell] of cells) {
+    const pts = cell.map((q) => W(s, q, zAt(p, q), o.at));
+    const low = pts.reduce((m, q) => (q[2] < m[2] ? q : m), pts[0] ?? o.at);
+    const k = face.down ? -1 : 1;
+    emitFace(b, {
+      points: pts,
+      normal: dirW(s, -p.ga * k, -p.gb * k, k),
+      up: [0, 0, 1],
+      vOrigin: low,
+      color: face.color,
+      strip: face.strip,
+      banded: face.banded,
+    });
+  }
+  return cells;
+}
+
+/** Vertical fascia / bargeboard band round the outline, between the two envelopes. */
+function fascia(b: MeshBuilder, s: RoofShape, o: RoofMeshOptions, trim: Vec3, verts: Vec2[]): void {
+  const n = s.outline.length;
+  for (let i = 0; i < n; i++) {
+    const a = s.outline[i] ?? [0, 0];
+    const c = s.outline[(i + 1) % n] ?? a;
+    const ex = c[0] - a[0];
+    const ey = c[1] - a[1];
+    const len2 = ex * ex + ey * ey;
+    if (len2 < 1e-12) continue;
+    const ts = [0, 1];
+    for (const q of verts) {
+      const t = ((q[0] - a[0]) * ex + (q[1] - a[1]) * ey) / len2;
+      const off = Math.abs((q[0] - a[0]) * ey - (q[1] - a[1]) * ex) / Math.sqrt(len2);
+      if (t > 1e-6 && t < 1 - 1e-6 && off < 1e-6) ts.push(t);
+    }
+    ts.sort((x, y) => x - y);
+    const out = dirW(s, ey, -ex, 0);
+    for (let k = 0; k + 1 < ts.length; k++) {
+      const q0: Vec2 = [a[0] + ex * (ts[k] ?? 0), a[1] + ey * (ts[k] ?? 0)];
+      const q1: Vec2 = [a[0] + ex * (ts[k + 1] ?? 1), a[1] + ey * (ts[k + 1] ?? 1)];
+      if (Math.hypot(q1[0] - q0[0], q1[1] - q0[1]) < 1e-6) continue;
+      emitFace(b, {
+        points: [
+          W(s, q0, envelope(s.under, q0), o.at),
+          W(s, q1, envelope(s.under, q1), o.at),
+          W(s, q1, envelope(s.top, q1), o.at),
+          W(s, q0, envelope(s.top, q0), o.at),
+        ],
+        normal: out,
+        up: [0, 0, 1],
+        vOrigin: o.at,
+        color: trim,
+        strip: 'plain',
+      });
+    }
+  }
+}
+
+/** Infill under the roof on each wall line where the underside rises above the plate. */
+function gableWalls(b: MeshBuilder, s: RoofShape, o: RoofMeshOptions, banded: boolean): void {
+  const wall = o.wall ?? { color: [0.8, 0.76, 0.68] as Vec3 };
+  const lines: [Vec2, Vec2, Vec3][] = [
+    [[s.L, -s.D], [s.L, s.D], dirW(s, 1, 0, 0)],
+    [[-s.L, s.D], [-s.L, -s.D], dirW(s, -1, 0, 0)],
+    [[s.L, s.D], [-s.L, s.D], dirW(s, 0, 1, 0)],
+    [[-s.L, -s.D], [s.L, -s.D], dirW(s, 0, -1, 0)],
+  ];
+  for (const [q0, q1, out] of lines) {
+    const at = (t: number): Vec2 => [q0[0] + (q1[0] - q0[0]) * t, q0[1] + (q1[1] - q0[1]) * t];
+    const ts = new Set([0, 1]);
+    s.under.forEach((p, i) => {
+      s.under.forEach((q, j) => {
+        if (j <= i) return;
+        const d0 = zAt(p, q0) - zAt(q, q0);
+        const d1 = zAt(p, q1) - zAt(q, q1);
+        if (Math.abs(d0 - d1) < 1e-12) return;
+        const t = d0 / (d0 - d1);
+        if (t > 1e-6 && t < 1 - 1e-6 && Math.abs(envelope(s.under, at(t)) - zAt(p, at(t))) < 1e-7)
+          ts.add(t);
+      });
+    });
+    const prof = [...ts]
+      .sort((x, y) => x - y)
+      .map((t) => [at(t), envelope(s.under, at(t))] as const);
+    if (Math.max(...prof.map(([, z]) => z)) < 0.01) continue;
+    const pts: Vec3[] = [W(s, q0, 0, o.at)];
+    for (const [q, z] of prof) pts.push(W(s, q, Math.max(0, z), o.at));
+    pts.push(W(s, q1, 0, o.at));
+    emitFace(b, {
+      points: pts,
+      normal: out,
+      up: [0, 0, 1],
+      vOrigin: o.at,
+      color: wall.color,
+      strip: wall.strip ?? 'plain',
+      banded,
+    });
+  }
+}
+
+/** Ridge / hip / knee caps: a round roll on every crease between two top facets. */
+function caps(s: RoofShape, o: RoofMeshOptions, cells: [Plane, Vec2[]][], trim: Vec3, lod: Lod) {
+  const seen = new Set<string>();
+  const out: Mesh[] = [];
+  const r = Math.max(0.06, s.thickness * 0.5);
+  for (const [p, cell] of cells) {
+    cell.forEach((q0, i) => {
+      const q1 = cell[(i + 1) % cell.length] ?? q0;
+      const mid: Vec2 = [(q0[0] + q1[0]) / 2, (q0[1] + q1[1]) / 2];
+      if (onOutline(s.outline, mid) || Math.hypot(q1[0] - q0[0], q1[1] - q0[1]) < 1e-3) return;
+      const key = [q0, q1]
+        .map((q) => `${q[0].toFixed(4)},${q[1].toFixed(4)}`)
+        .sort()
+        .join('|');
+      if (seen.has(key)) return;
+      seen.add(key);
+      const lift = r * 0.3;
+      out.push(
+        beam({
+          from: W(s, q0, zAt(p, q0) + lift, o.at),
+          to: W(s, q1, zAt(p, q1) + lift, o.at),
+          width: r * 2,
+          segments: lod === 0 ? 8 : 5,
+          color: trim,
+          strip: 'plain',
+        }),
+      );
+    });
+  }
+  return out;
+}
+
+/** The roof as one mesh at a detail level. Pure: compose with place/merge or pass to ctx.part. */
+export function roofMesh(o: RoofMeshOptions, lod: Lod = 0): Mesh {
+  const s = roofShape(o);
+  const trim = o.trim ?? [o.color[0] * 0.55, o.color[1] * 0.55, o.color[2] * 0.55];
+  const strip = o.strip ?? 'slate';
+  const b = new MeshBuilder();
+  const extra: Mesh[] = [];
+  if (lod === 2) {
+    // Bare slopes on the underside envelope: it rests on the walls with no slab.
+    slopes(b, s, s.under, o, { down: false, color: o.color, strip, banded: false });
+  } else {
+    const top = slopes(b, s, s.top, o, { down: false, color: o.color, strip, banded: true });
+    const under = slopes(b, s, s.under, o, {
+      down: true,
+      color: trim,
+      strip: 'wood',
+      banded: lod === 0,
+    });
+    const verts = [...top, ...under].flatMap(([, cell]) => cell);
+    fascia(b, s, o, trim, verts);
+    if (o.caps !== false) extra.push(...caps(s, o, top, trim, lod));
+  }
+  gableWalls(b, s, o, lod < 2);
+  for (const c of o.chimneys ?? []) {
+    extra.push(chimney(c, (x, y) => roofHeightAt(o, x, y), o.at, lod));
+  }
+  return merge([b.build(), ...extra]);
+}
+
+/** Add the roof as part `name` (default 'roof') at the context's LOD; returns its heights. */
+export function roof(ctx: BuildContext, o: RoofMeshOptions & { readonly name?: string }): RoofInfo {
+  ctx.part(o.name ?? 'roof', roofMesh(o, ctx.lod));
+  return roofInfo(o);
+}
+
+export function roofInfo(o: RoofOptions): RoofInfo {
+  const s = roofShape(o);
+  const eave = Math.min(...s.outline.map((q) => envelope(s.under, q)));
+  return {
+    ridge: ridgeHeight(o),
+    eave: o.at[2] + eave,
+    heightAt: (x, y) => roofHeightAt(o, x, y),
+  };
+}

package/src/kinds/vegetation-fronds.ts

@@ -0,0 +1,126 @@
+// Palm fronds: pinnate leaves as curved card strips — narrow double-sided leaflets either side of
+// each rachis, folded into a V and drooping, longest mid-frond. Plus coconuts tucked under the
+// crown. The rachis itself is a swept stem (in `branches`); leaflets root on its bark.
+
+import { type Mesh, MeshBuilder, merge, type Rng, type Vec3 } from '../core/index.ts';
+import { arcLengths, lathe, transportFrames } from '../primitives/index.ts';
+import type { CrownShade } from './vegetation-leaves.ts';
+import type { LeafParams } from './vegetation-params.ts';
+import type { Stem } from './vegetation-skeleton.ts';
+
+type V = [number, number, number];
+
+function tri(mb: MeshBuilder, a: Vec3, b: Vec3, c: Vec3, col: Vec3, tipCol: Vec3): void {
+  const e1: V = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+  const e2: V = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+  const n: V = [
+    e1[1] * e2[2] - e1[2] * e2[1],
+    e1[2] * e2[0] - e1[0] * e2[2],
+    e1[0] * e2[1] - e1[1] * e2[0],
+  ];
+  const l = Math.hypot(n[0], n[1], n[2]) || 1;
+  for (const s of [1, -1]) {
+    const nn: Vec3 = [(n[0] / l) * s, (n[1] / l) * s, (n[2] / l) * s];
+    const i = mb.vertex({ p: a, n: nn, uv: [0, 0], color: col });
+    const j = mb.vertex({ p: b, n: nn, uv: [0, 0], color: col });
+    const k = mb.vertex({ p: c, n: nn, uv: [0, 0], color: tipCol });
+    if (s > 0) mb.tri(i, j, k);
+    else mb.tri(i, k, j);
+  }
+}
+
+/**
+ * Leaflets along every frond (stem at `level`). `perSide` leaflets each side; `from` overrides
+ * each frond's first rachis point (LOD2 roots them all on the trunk's top cap centre).
+ */
+export function frondLeaflets(
+  stems: readonly Stem[],
+  level: number,
+  leaf: LeafParams,
+  perSide: number,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const mb = new MeshBuilder();
+  for (const st of stems) {
+    if (st.level !== level) continue;
+    const arc = arcLengths(st.pts);
+    const frames = transportFrames(st.pts);
+    const k = 1 + rng.range(-leaf.colorVar, leaf.colorVar);
+    const step = (st.length * 0.9) / perSide;
+    for (let i = 0; i < perSide; i++) {
+      const u = 0.1 + (0.9 * (i + 0.5)) / perSide;
+      const s = u * st.length;
+      let j = 0;
+      while (j < arc.length - 2 && (arc[j + 1] ?? 0) < s) j++;
+      const a = st.pts[j] ?? [0, 0, 0];
+      const b = st.pts[j + 1] ?? a;
+      const f = (s - (arc[j] ?? 0)) / ((arc[j + 1] ?? 1) - (arc[j] ?? 0) || 1);
+      const fr = frames[j] ?? { t: [1, 0, 0] as Vec3, n: [0, 0, 1] as Vec3, b: [0, 1, 0] as Vec3 };
+      const r = (st.radii[j] ?? 0) * (1 - f) + (st.radii[j + 1] ?? 0) * f;
+      const c: Vec3 = [
+        a[0] + (b[0] - a[0]) * f,
+        a[1] + (b[1] - a[1]) * f,
+        a[2] + (b[2] - a[2]) * f,
+      ];
+      const len = st.length * leaf.width * Math.sin(Math.PI * (0.12 + 0.88 * u)) ** 0.6;
+      const ao =
+        0.6 +
+        0.4 *
+          Math.min(1, Math.hypot(c[0] - shade.centre[0], c[1] - shade.centre[1]) / shade.radius);
+      const col: Vec3 = [
+        leaf.color[0] * k * ao * 0.75,
+        leaf.color[1] * k * ao * 0.75,
+        leaf.color[2] * k * ao * 0.75,
+      ];
+      const tipCol: Vec3 = [col[0] * 1.45, col[1] * 1.35, col[2] * 1.2];
+      for (const side of [1, -1]) {
+        const o: Vec3 = [fr.b[0] * side, fr.b[1] * side, fr.b[2] * side];
+        const root = (d: number): Vec3 => [
+          c[0] + o[0] * r + fr.t[0] * d,
+          c[1] + o[1] * r + fr.t[1] * d,
+          c[2] + o[2] * r + fr.t[2] * d,
+        ];
+        const tip: Vec3 = [
+          c[0] + (o[0] * 0.8 + fr.t[0] * 0.45 - fr.n[0] * 0.35) * len,
+          c[1] + (o[1] * 0.8 + fr.t[1] * 0.45 - fr.n[1] * 0.35) * len,
+          c[2] + (o[2] * 0.8 + fr.t[2] * 0.45 - fr.n[2] * 0.35) * len - 0.2 * len,
+        ];
+        tri(mb, root(-step * 0.35), root(step * 0.35), tip, col, tipCol);
+      }
+    }
+  }
+  return mb.build();
+}
+
+/** Coconuts: `count` spheres hugging the trunk just below the frond bases. */
+export function fruit(
+  trunk: Stem,
+  at: number,
+  o: { count: number; radius: number; color: Vec3 },
+  rng: Rng,
+): Mesh {
+  const j = Math.max(0, Math.min(trunk.pts.length - 1, Math.round(at * (trunk.pts.length - 1))));
+  const c = trunk.pts[j] ?? [0, 0, 0];
+  const rt = trunk.radii[j] ?? 0.2;
+  const profile = [0, 1, 2, 3, 4].map((i): [number, number] => {
+    const a = -Math.PI / 2 + (i / 4) * Math.PI;
+    return [Math.max(0.0001, Math.cos(a)) * o.radius, Math.sin(a) * o.radius];
+  });
+  const out: Mesh[] = [];
+  for (let i = 0; i < o.count; i++) {
+    const a = (i / o.count) * Math.PI * 2 + rng.range(-0.3, 0.3);
+    const d = rt + o.radius * 0.6;
+    const dz = rng.range(-1, 0.5) * o.radius;
+    out.push(
+      lathe({
+        profile,
+        segments: 6,
+        caps: false,
+        at: [c[0] + Math.cos(a) * d, c[1] + Math.sin(a) * d, c[2] + dz],
+        color: o.color,
+      }),
+    );
+  }
+  return merge(out);
+}