@developerz.ai/ts23d 0.0.0-stage → 0.2.0

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);
+}

package/src/kinds/vegetation-impostor.ts

@@ -0,0 +1,118 @@
+// LOD2 stand-ins, < 300 triangles. 'blob': a lathe of the real crown envelope (binned from the
+// full skeleton, so it is THIS tree's silhouette) whose top apex is the trunk's tip — one shared
+// point, so the crown provably touches the trunk. 'cards': a dozen coarse folded frond strips
+// rooted on the trunk's top cap centre (palms). Smooth normals on the blob, flat on the cards.
+
+import { type Mesh, MeshBuilder, type Rng, type Vec3 } from '../core/index.ts';
+import { lathe, sweep, transportFrames } from '../primitives/index.ts';
+import type { TreeParams } from './vegetation-params.ts';
+import type { Stem } from './vegetation-skeleton.ts';
+
+export interface Impostor {
+  readonly trunk: Mesh;
+  readonly leaves: Mesh;
+}
+
+/** Trunk at 4 path points; `apex` extends it straight up to a point (blob's top). */
+function coarseTrunk(trunk: Stem, p: TreeParams, apex: number | null): Mesh {
+  const n = trunk.pts.length - 1;
+  const idx = [...new Set([0, Math.round(n / 3), Math.round((2 * n) / 3), n])];
+  const pts = idx.map((i): Vec3 => trunk.pts[i] ?? [0, 0, 0]);
+  const radii = idx.map((i) => trunk.radii[i] ?? 0.1);
+  const last = pts.length - 1;
+  const tip = pts[last] ?? [0, 0, 1];
+  if (apex !== null && apex > tip[2] + 1e-6) {
+    pts.push([tip[0], tip[1], apex]);
+    radii.push(0);
+  } else radii[last] = 0;
+  return sweep({
+    section: { radius: 1, segments: 5 },
+    path: pts,
+    scale: radii,
+    color: p.bark,
+    strip: 'wood',
+    caps: apex === null ? 'end' : false,
+  });
+}
+
+export function blob(stems: readonly Stem[], p: TreeParams, rng: Rng): Impostor {
+  const trunk = stems[0];
+  if (!trunk) return { trunk: new MeshBuilder().build(), leaves: new MeshBuilder().build() };
+  const tip = trunk.pts[trunk.pts.length - 1] ?? [0, 0, 1];
+  const margin = p.leaves.size * 0.6;
+  let z0 = Infinity;
+  let z1 = tip[2];
+  for (const s of stems)
+    for (const q of s.level > 0 ? s.pts : []) {
+      z0 = Math.min(z0, q[2] - margin * (1 + (p.leaves.hang ?? 0) * 2));
+      z1 = Math.max(z1, q[2] + margin);
+    }
+  if (!Number.isFinite(z0)) z0 = tip[2] * 0.5;
+  const BINS = 6;
+  const r = new Array<number>(BINS).fill(0.2);
+  for (const s of stems)
+    for (const q of s.level > 0 ? s.pts : []) {
+      const b = Math.min(BINS - 1, Math.max(0, Math.floor(((q[2] - z0) / (z1 - z0)) * BINS)));
+      r[b] = Math.max(r[b] ?? 0, Math.hypot(q[0] - tip[0], q[1] - tip[1]) + margin);
+    }
+  const profile: [number, number][] = [[0, z0]];
+  for (let b = 0; b < BINS; b++) profile.push([r[b] ?? 0.2, z0 + ((b + 0.5) / BINS) * (z1 - z0)]);
+  profile.push([0, z1]);
+  const leaves = lathe({ profile, segments: 10, color: p.leaves.color, at: [tip[0], tip[1], 0] });
+  const [cr, cg, cb] = p.leaves.color;
+  for (let i = 0; i < leaves.colors.length / 3; i++) {
+    const t = ((leaves.positions[i * 3 + 2] ?? 0) - z0) / (z1 - z0);
+    const k = (0.55 + 0.5 * t) * (1 + rng.range(-0.08, 0.08));
+    leaves.colors.set([cr * k, cg * k, cb * k], i * 3);
+  }
+  return { trunk: coarseTrunk(trunk, p, z1), leaves };
+}
+
+export function frondCards(stems: readonly Stem[], p: TreeParams, level: number): Impostor {
+  const trunk = stems[0];
+  const mb = new MeshBuilder();
+  if (!trunk) return { trunk: mb.build(), leaves: mb.build() };
+  const top = trunk.pts[trunk.pts.length - 1] ?? [0, 0, 1];
+  const fronds = stems.filter((s) => s.level === level);
+  const every = Math.max(1, Math.ceil(fronds.length / 12));
+  const [cr, cg, cb] = p.leaves.color;
+  for (const [fi, st] of fronds.entries()) {
+    if (fi % every !== 0) continue;
+    const n = st.pts.length - 1;
+    const pts = [top, st.pts[Math.round(n / 2)] ?? top, st.pts[n] ?? top];
+    const fr = transportFrames(pts);
+    const w = [0.25, 1, 0.35].map((k) => k * st.length * p.leaves.width);
+    for (const side of [1, -1]) {
+      const edge = pts.map((c, j): Vec3 => {
+        const f = fr[j];
+        const ww = (w[j] ?? 0) * side;
+        if (!f) return c;
+        return [
+          c[0] + (f.b[0] * 0.85 - f.n[0] * 0.45 * side) * ww,
+          c[1] + (f.b[1] * 0.85 - f.n[1] * 0.45 * side) * ww,
+          c[2] + (f.b[2] * 0.85 - f.n[2] * 0.45 * side) * ww,
+        ];
+      });
+      for (let j = 0; j < 2; j++) {
+        const q = [pts[j], pts[j + 1], edge[j + 1], edge[j]] as Vec3[];
+        const [a, b, c] = [q[0] ?? top, q[1] ?? top, q[2] ?? top];
+        const e1 = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+        const e2 = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+        const nx = (e1[1] ?? 0) * (e2[2] ?? 0) - (e1[2] ?? 0) * (e2[1] ?? 0);
+        const ny = (e1[2] ?? 0) * (e2[0] ?? 0) - (e1[0] ?? 0) * (e2[2] ?? 0);
+        const nz = (e1[0] ?? 0) * (e2[1] ?? 0) - (e1[1] ?? 0) * (e2[0] ?? 0);
+        const l = Math.hypot(nx, ny, nz) || 1;
+        for (const s of [1, -1]) {
+          const nn: Vec3 = [(nx / l) * s, (ny / l) * s, (nz / l) * s];
+          const ids = q.map((v, k) => {
+            const sh = k < 2 ? 0.7 : 1;
+            return mb.vertex({ p: v, n: nn, uv: [0, 0], color: [cr * sh, cg * sh, cb * sh] });
+          });
+          const [i0 = 0, i1 = 0, i2 = 0, i3 = 0] = s > 0 ? ids : [...ids].reverse();
+          mb.quad(i0, i1, i2, i3);
+        }
+      }
+    }
+  }
+  return { trunk: coarseTrunk(trunk, p, null), leaves: mb.build() };
+}

package/src/kinds/vegetation-leaves.ts

@@ -0,0 +1,168 @@
+// Leaf cards: double-sided `planar` polygons, each standing for a cluster of leaves, with per-vertex
+// colour (darker at the stem, lighter at the tip, darker deep inside the crown). LOD0 roots every
+// card on an exact twig vertex (`transportFrames` = the sweep's own frames); LOD1 replaces each
+// twig by one bigger cluster card rooted on its parent's bark.
+
+import { type Mesh, merge, type Rng, type Vec3 } from '../core/index.ts';
+import { planar, transportFrames } from '../primitives/index.ts';
+import { type LeafParams, OUTLINES } from './vegetation-params.ts';
+import type { Stem } from './vegetation-skeleton.ts';
+
+const unit = (a: Vec3): Vec3 => {
+  const l = Math.hypot(a[0], a[1], a[2]) || 1;
+  return [a[0] / l, a[1] / l, a[2] / l];
+};
+
+/** Crown occlusion: cards deep inside / low in the crown are darker. */
+export interface CrownShade {
+  readonly centre: Vec3;
+  readonly radius: number;
+  readonly zMin: number;
+  readonly zMax: number;
+}
+
+export function crownShade(stems: readonly Stem[], level: number): CrownShade {
+  let r = 0.1;
+  let z0 = Infinity;
+  let z1 = -Infinity;
+  const t = stems[0]?.pts;
+  const c = t?.[t.length - 1] ?? [0, 0, 0];
+  for (const s of stems) {
+    if (s.level < level) continue;
+    for (const p of s.pts) {
+      r = Math.max(r, Math.hypot(p[0] - c[0], p[1] - c[1]));
+      z0 = Math.min(z0, p[2]);
+      z1 = Math.max(z1, p[2]);
+    }
+  }
+  return { centre: c, radius: r, zMin: z0, zMax: Math.max(z1, z0 + 0.1) };
+}
+
+function card(
+  leaf: LeafParams,
+  base: Vec3,
+  dir: Vec3,
+  side: Vec3,
+  len: number,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const outline = OUTLINES[leaf.shape === 'frond' ? 'oval' : leaf.shape];
+  const w = len * leaf.width;
+  const points = outline.map(
+    ([u, v]): Vec3 => [
+      base[0] + dir[0] * u * len + side[0] * v * w,
+      base[1] + dir[1] * u * len + side[1] * v * w,
+      base[2] + dir[2] * u * len + side[2] * v * w,
+    ],
+  );
+  const m = planar({ points, color: leaf.color, doubleSided: true });
+  const k = 1 + rng.range(-leaf.colorVar, leaf.colorVar);
+  const hue = rng.range(-leaf.colorVar, leaf.colorVar) * 0.6;
+  const radial = Math.hypot(base[0] - shade.centre[0], base[1] - shade.centre[1]) / shade.radius;
+  const up = (base[2] - shade.zMin) / (shade.zMax - shade.zMin);
+  const ao = 0.5 + 0.35 * Math.min(1, radial) ** 0.8 + 0.2 * Math.max(0, Math.min(1, up));
+  const [r, g, b] = leaf.color;
+  for (let i = 0; i < m.colors.length / 3; i++) {
+    const u = outline[i % outline.length]?.[0] ?? 0;
+    const s = ao * k * (0.7 + 0.4 * u);
+    m.colors[i * 3] = r * s * (1 + hue);
+    m.colors[i * 3 + 1] = g * s;
+    m.colors[i * 3 + 2] = b * s * (1 - hue);
+  }
+  return m;
+}
+
+/** Splay outward from the stem, lift a little, then droop towards the ground by `hang`. */
+function aim(radial: Vec3, along: Vec3, leaf: LeafParams, rng: Rng): { dir: Vec3; side: Vec3 } {
+  const hang = leaf.hang ?? 0;
+  const flat = leaf.flat ?? 0;
+  const lift = rng.range(-0.3, 0.5);
+  const out = unit([
+    radial[0] * 0.9 + along[0] * 0.7,
+    radial[1] * 0.9 + along[1] * 0.7,
+    radial[2] * 0.9 + along[2] * 0.7 + lift,
+  ]);
+  const d0 = unit([out[0] * (1 - hang), out[1] * (1 - hang), out[2] * (1 - hang) - hang]);
+  const dir = unit([d0[0], d0[1], d0[2] * (1 - flat)]);
+  const level = unit([-dir[1], dir[0], 0]);
+  const s1 = unit([
+    dir[1] * radial[2] - dir[2] * radial[1],
+    dir[2] * radial[0] - dir[0] * radial[2],
+    dir[0] * radial[1] - dir[1] * radial[0],
+  ]);
+  const s0 = Math.hypot(...s1) < 0.5 ? level : s1;
+  // Flat cards (pine pads) lie level: side goes horizontal, roll fades out.
+  const side = unit([
+    s0[0] + (level[0] - s0[0]) * flat,
+    s0[1] + (level[1] - s0[1]) * flat,
+    s0[2] + (level[2] - s0[2]) * flat,
+  ]);
+  const roll = rng.range(-0.7, 0.7) * (1 - flat);
+  const t: Vec3 = [
+    dir[1] * side[2] - dir[2] * side[1],
+    dir[2] * side[0] - dir[0] * side[2],
+    dir[0] * side[1] - dir[1] * side[0],
+  ];
+  const c = Math.cos(roll);
+  const s = Math.sin(roll);
+  return { dir, side: [side[0] * c + t[0] * s, side[1] * c + t[1] * s, side[2] * c + t[2] * s] };
+}
+
+/** LOD0: `perStem` cards along the outer 70% of every terminal stem, rooted on a ring vertex. */
+export function leafCards(
+  stems: readonly Stem[],
+  level: number,
+  ringSegments: number,
+  leaf: LeafParams,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const out: Mesh[] = [];
+  for (const st of stems) {
+    if (st.level !== level) continue;
+    const frames = transportFrames(st.pts);
+    const res = st.pts.length - 1;
+    for (let i = 0; i < leaf.perStem; i++) {
+      const from = leaf.from ?? 0.3;
+      const t = from + ((1 - from) * (i + 1)) / leaf.perStem;
+      const j = Math.max(1, Math.min(res, Math.round(t * res)));
+      const f = frames[j];
+      const c = st.pts[j];
+      if (!f || !c) continue;
+      const a = (rng.int(0, ringSegments - 1) / ringSegments) * Math.PI * 2;
+      const radial: Vec3 = [
+        Math.cos(a) * f.n[0] + Math.sin(a) * f.b[0],
+        Math.cos(a) * f.n[1] + Math.sin(a) * f.b[1],
+        Math.cos(a) * f.n[2] + Math.sin(a) * f.b[2],
+      ];
+      const r = st.radii[j] ?? 0;
+      const base: Vec3 = [c[0] + radial[0] * r, c[1] + radial[1] * r, c[2] + radial[2] * r];
+      const { dir, side } = aim(radial, f.t, leaf, rng);
+      out.push(card(leaf, base, dir, side, leaf.size * rng.range(0.8, 1.2), shade, rng));
+    }
+  }
+  return merge(out);
+}
+
+/** LOD1: one cluster card per (unemitted) twig, rooted where the twig would leave its parent. */
+export function clusterCards(
+  stems: readonly Stem[],
+  level: number,
+  leaf: LeafParams,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const out: Mesh[] = [];
+  for (const st of stems) {
+    if (st.level !== level) continue;
+    const tip = st.pts[st.pts.length - 1] ?? st.surface;
+    const p0 = st.pts[0] ?? st.surface;
+    const along = unit([tip[0] - p0[0], tip[1] - p0[1], tip[2] - p0[2]]);
+    const radial = unit([st.surface[0] - p0[0], st.surface[1] - p0[1], st.surface[2] - p0[2]]);
+    const { dir, side } = aim(radial, along, leaf, rng);
+    const len = st.length * 1.1 + leaf.size;
+    out.push(card(leaf, st.surface, dir, side, len, shade, rng));
+  }
+  return merge(out);
+}