@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/primitives/planar.ts

@@ -0,0 +1,55 @@
+// A flat polygon in 3D (fan-triangulated in its own plane): panels, decks, hatches, plates,
+// fender tops, sign boards. One-sided; pass `doubleSided` for thin sheets seen from both sides.
+
+import {
+  cross,
+  dot,
+  type Mesh,
+  MeshBuilder,
+  normalize,
+  sub,
+  type Vec2,
+  type Vec3,
+} from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { triangulate } from './triangulate.ts';
+
+export interface PlanarOptions {
+  /** Counter-clockwise as seen from the side the face points to. */
+  readonly points: readonly Vec3[];
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  readonly doubleSided?: boolean;
+}
+
+export function planar(o: PlanarOptions): Mesh {
+  const [a = [0, 0, 0], b = [1, 0, 0], c = [0, 1, 0]] = o.points;
+  const n = normalize(cross(sub(b, a), sub(c, a)));
+  const u = normalize(sub(b, a));
+  const v = cross(n, u);
+  const flat: Vec2[] = o.points.map((p) => [dot(sub(p, a), u), dot(sub(p, a), v)]);
+  const rect = stripRect(o.strip ?? 'plain');
+  const tris = triangulate(flat);
+  const mb = new MeshBuilder();
+  for (const side of o.doubleSided ? [1, -1] : [1]) {
+    const nn: Vec3 = [n[0] * side, n[1] * side, n[2] * side];
+    const ids = o.points.map((p, i) => {
+      const f = flat[i] ?? [0, 0];
+      return mb.vertex({
+        p,
+        n: nn,
+        uv: [
+          rect.u0 + (f[0] / rect.metres) * (rect.u1 - rect.u0),
+          rect.v0 + ((((f[1] / rect.metres) % 1) + 1) % 1) * (rect.v1 - rect.v0),
+        ],
+        color: o.color,
+      });
+    });
+    for (const [x, y, z] of tris) {
+      const [i0 = 0, i1 = 0, i2 = 0] = [ids[x], ids[y], ids[z]];
+      if (side > 0) mb.tri(i0, i1, i2);
+      else mb.tri(i0, i2, i1);
+    }
+  }
+  return mb.build();
+}

package/src/primitives/prism.ts

@@ -0,0 +1,85 @@
+// Extrude a 2D profile into a solid: the workhorse for sloped armour, hull side profiles, gables,
+// fins, wings in plan. The profile lives in a named plane and extrudes along the remaining axis.
+//   plane 'xz' (side profile, extrude along Y) · 'xy' (plan, extrude up Z) · 'yz' (front, along X)
+
+import { type Mesh, MeshBuilder, normalize, type Vec2, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { triangulate } from './triangulate.ts';
+
+export interface PrismOptions {
+  readonly profile: readonly Vec2[];
+  readonly depth: number;
+  readonly plane?: 'xz' | 'xy' | 'yz';
+  /** Extrusion is centred on the plane unless `from` is given (0 = starts at the plane). */
+  readonly centred?: boolean;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  readonly caps?: boolean;
+}
+
+const lift = (plane: 'xz' | 'xy' | 'yz', p: Vec2, d: number): Vec3 =>
+  plane === 'xz' ? [p[0], d, p[1]] : plane === 'xy' ? [p[0], p[1], d] : [d, p[0], p[1]];
+
+export function prism(o: PrismOptions): Mesh {
+  const plane = o.plane ?? 'xy';
+  const d0 = o.centred === false ? 0 : -o.depth / 2;
+  const d1 = d0 + o.depth;
+  const rect = stripRect(o.strip ?? 'plain');
+  const uv = (u: number, v: number): Vec2 => [
+    rect.u0 + (u / rect.metres) * (rect.u1 - rect.u0),
+    rect.v0 + (((v % 1) + 1) % 1) * (rect.v1 - rect.v0),
+  ];
+  const b = new MeshBuilder();
+  const n = o.profile.length;
+  // Sides: one flat quad per edge, outward normal regardless of winding.
+  const sign =
+    o.profile.reduce((s, a, i) => {
+      const c = o.profile[(i + 1) % n] ?? a;
+      return s + a[0] * c[1] - c[0] * a[1];
+    }, 0) > 0
+      ? 1
+      : -1;
+  // The extrusion axis flips handedness for 'xz' (Y = Z × X), so outward flips with it.
+  const hand = plane === 'xz' ? -1 : 1;
+  let run = 0;
+  for (let i = 0; i < n; i++) {
+    const a = o.profile[i] ?? [0, 0];
+    const c = o.profile[(i + 1) % n] ?? a;
+    const e: Vec2 = [c[0] - a[0], c[1] - a[1]];
+    const len = Math.hypot(e[0], e[1]);
+    if (len < 1e-9) continue;
+    const n2: Vec2 = [(e[1] / len) * sign, (-e[0] / len) * sign];
+    const nrm = normalize(lift(plane, n2, 0));
+    const p = [lift(plane, a, d0), lift(plane, c, d0), lift(plane, c, d1), lift(plane, a, d1)];
+    const ids = p.map((q, k) =>
+      b.vertex({
+        p: q,
+        n: nrm,
+        uv: uv(run + (k === 1 || k === 2 ? len : 0), k >= 2 ? o.depth : 0),
+        color: o.color,
+      }),
+    );
+    const [i0 = 0, i1 = 0, i2 = 0, i3 = 0] = ids;
+    if (sign * hand > 0) b.quad(i0, i1, i2, i3);
+    else b.quad(i0, i3, i2, i1);
+    run += len;
+  }
+  if (o.caps !== false) {
+    const tris = triangulate(o.profile);
+    for (const [d, s] of [
+      [d0, -1],
+      [d1, 1],
+    ] as const) {
+      const nrm = normalize(lift(plane, [0, 0], s));
+      const ids = o.profile.map((q) =>
+        b.vertex({ p: lift(plane, q, d), n: nrm, uv: uv(q[0], q[1]), color: o.color }),
+      );
+      for (const [x, y, z] of tris) {
+        const [a = 0, c = 0, e = 0] = [ids[x], ids[y], ids[z]];
+        if (s * hand > 0) b.tri(a, c, e);
+        else b.tri(a, e, c);
+      }
+    }
+  }
+  return b.build();
+}

package/src/primitives/sculpt-edit.ts

@@ -0,0 +1,212 @@
+// One sculpt edit → its distance field (rotated, optionally mirrored across Y) and its bounds.
+// Rotation is precomputed into a 3×3 matrix; evaluation is scalar maths, no allocation.
+
+import type { Vec3 } from '../core/index.ts';
+import { invalid } from './check.ts';
+import { type Field, shapes } from './sdf-ops.ts';
+
+export type SculptShape = 'sphere' | 'ellipsoid' | 'capsule' | 'roundBox' | 'cone' | 'torus';
+
+/** An edit: one shape, or a group of edits folded on their own first (local trims). */
+export type SculptEdit = SculptShapeEdit | SculptGroup;
+
+/**
+ * Edits folded on their own (from nothing), then applied to the sculpt as ONE edit with this
+ * op/blend/colour: subtract or intersect inside the group trims only the group's shapes (a
+ * half-sphere eyelid, a hair cap stopped at the hairline) and leaves earlier edits alone.
+ */
+export interface SculptGroup {
+  readonly group: readonly SculptEdit[];
+  readonly op?: 'add' | 'subtract' | 'intersect';
+  readonly blend?: number;
+  /** Default colour of the group's own edits (and its colour when it carves). */
+  readonly color?: Vec3;
+  /** Default mirror for the group's edits. */
+  readonly mirror?: boolean;
+}
+
+export interface SculptShapeEdit {
+  readonly shape: SculptShape;
+  /** Centre (sphere, ellipsoid, roundBox, torus), base centre (cone) or start (capsule). */
+  readonly at: Vec3;
+  /**
+   * sphere: radius · ellipsoid: [rx, ry, rz] · roundBox: full [x, y, z] · cone: [base radius,
+   * top radius, height] along local +Z · torus: [ring radius, tube radius] in local XY ·
+   * capsule: radius (segment `at` → `to`).
+   */
+  readonly size: number | readonly [number, number] | Vec3;
+  /** Capsule end point. */
+  readonly to?: Vec3;
+  /** Degrees about X, then Y, then Z (world axes), around `at`. */
+  readonly rotate?: Vec3;
+  /** roundBox edge radius, metres. */
+  readonly round?: number;
+  readonly op?: 'add' | 'subtract' | 'intersect' | 'paint';
+  /** Smooth-blend radius in metres (0 = hard edge). For paint: the colour falloff width. */
+  readonly blend?: number;
+  readonly color?: Vec3;
+  /** Override the sculpt's `mirror` for this edit (e.g. one scar). */
+  readonly mirror?: boolean;
+}
+
+const dims = (e: SculptShapeEdit): Vec3 => {
+  if (typeof e.size === 'number') return [e.size, e.size, e.size];
+  const [a, b, c] = e.size;
+  return [a, b, c ?? b];
+};
+
+export function sculptShape(e: SculptShapeEdit, i: number, mirrorAll: boolean): Field {
+  const [a, b, c] = dims(e);
+  const where = `sculpt edit ${i} (${e.shape})`;
+  if (![a, b, c].every((x) => Number.isFinite(x) && x > 0))
+    invalid(`${where}: size has a value ≤ 0`, 'give every size component in metres, > 0');
+  if ((e.blend ?? 0) < 0 || !Number.isFinite(e.blend ?? 0))
+    invalid(`${where}: blend is ${e.blend}`, 'use a blend radius ≥ 0 m (0.01 = 1 cm fillet)');
+  if (e.shape === 'capsule' && !e.to)
+    invalid(`${where}: capsule needs \`to\``, 'add to: [x, y, z], the far end');
+  const [rx, ry, rz] = (e.rotate ?? [0, 0, 0]).map((d) => (d * Math.PI) / 180);
+  const [cx, sx, cy, sy, cz, sz] = [
+    Math.cos(rx ?? 0),
+    Math.sin(rx ?? 0),
+    Math.cos(ry ?? 0),
+    Math.sin(ry ?? 0),
+    Math.cos(rz ?? 0),
+    Math.sin(rz ?? 0),
+  ];
+  // R = Rz · Ry · Rx; local = Rᵀ (p − at).
+  const m = [
+    cz * cy,
+    cz * sy * sx - sz * cx,
+    cz * sy * cx + sz * sx,
+    sz * cy,
+    sz * sy * sx + cz * cx,
+    sz * sy * cx - cz * sx,
+    -sy,
+    cy * sx,
+    cy * cx,
+  ];
+  const [m0 = 1, m1 = 0, m2 = 0, m3 = 0, m4 = 1, m5 = 0, m6 = 0, m7 = 0, m8 = 1] = m;
+  const [ox, oy, oz] = e.at;
+  const to = e.to ?? e.at;
+  const [dx, dy, dz] = [to[0] - ox, to[1] - oy, to[2] - oz];
+  const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+  const round = Math.min(e.round ?? 0, a / 2, b / 2, c / 2);
+  // The shape kernel in local coordinates, chosen once (no per-call switch).
+  const kernel: (x: number, y: number, z: number) => number =
+    e.shape === 'sphere'
+      ? (x, y, z) => shapes.sphere(x, y, z, a)
+      : e.shape === 'ellipsoid'
+        ? (x, y, z) => shapes.ellipsoid(x, y, z, a, b, c)
+        : e.shape === 'roundBox'
+          ? (x, y, z) => shapes.roundBox(x, y, z, a / 2, b / 2, c / 2, round)
+          : e.shape === 'cone'
+            ? (x, y, z) => shapes.cone(x, y, z, a, b, c)
+            : (x, y, z) => shapes.torus(x, y, z, a, b);
+  const rotated = e.rotate?.some((d) => d !== 0) ?? false;
+  const one =
+    e.shape === 'capsule'
+      ? (px: number, py: number, pz: number): number => {
+          // Capsule in world space along at → to.
+          const wx = px - ox;
+          const wy = py - oy;
+          const wz = pz - oz;
+          const t =
+            len > 0 ? Math.min(1, Math.max(0, (wx * dx + wy * dy + wz * dz) / (len * len))) : 0;
+          return Math.sqrt((wx - dx * t) ** 2 + (wy - dy * t) ** 2 + (wz - dz * t) ** 2) - a;
+        }
+      : rotated
+        ? (px: number, py: number, pz: number): number => {
+            const wx = px - ox;
+            const wy = py - oy;
+            const wz = pz - oz;
+            return kernel(
+              m0 * wx + m3 * wy + m6 * wz,
+              m1 * wx + m4 * wy + m7 * wz,
+              m2 * wx + m5 * wy + m8 * wz,
+            );
+          }
+        : // Identity rotation: 1·x + 0·y + 0·z is x, so skipping the product changes no bits.
+          (px: number, py: number, pz: number): number => kernel(px - ox, py - oy, pz - oz);
+  if (!(e.mirror ?? mirrorAll)) return (p) => one(p[0], p[1], p[2]);
+  // Mirrored: min of the shape and its copy across y = 0. Evaluate the nearer copy first; the
+  // other only if its bound could undercut it (min is order-free, so this is exact).
+  const { c: sc, r: sr, scale, inside } = shapeSphere(e);
+  const bound = (dist: number): number => {
+    const out = dist - sr;
+    return out > 0 ? scale * out : inside ? out : Number.NEGATIVE_INFINITY;
+  };
+  return (p) => {
+    const dx0 = p[0] - sc[0];
+    const dz0 = p[2] - sc[2];
+    const near = Math.sqrt(dx0 * dx0 + (p[1] - sc[1]) ** 2 + dz0 * dz0);
+    const far = Math.sqrt(dx0 * dx0 + (p[1] + sc[1]) ** 2 + dz0 * dz0);
+    const [first, second, lb] =
+      near <= far ? [p[1], -p[1], bound(far)] : [-p[1], p[1], bound(near)];
+    const v = one(p[0], first, p[2]);
+    return lb >= v ? v : Math.min(v, one(p[0], second, p[2]));
+  };
+}
+
+/**
+ * A sphere the shape lies in, and how its field compares with the distance to it: every shape's
+ * value v satisfies v ≥ scale · (|p − centre| − radius) outside the sphere (scale 1 = exact SDFs;
+ * the ellipsoid approximation only guarantees (r_min / r_max)², and nothing inside its sphere).
+ */
+export function shapeSphere(e: SculptShapeEdit): {
+  c: Vec3;
+  r: number;
+  scale: number;
+  inside: boolean;
+} {
+  const [a, b, c] = dims(e);
+  const to = e.to ?? e.at;
+  const centre: Vec3 =
+    e.shape === 'capsule'
+      ? [(e.at[0] + to[0]) / 2, (e.at[1] + to[1]) / 2, (e.at[2] + to[2]) / 2]
+      : e.at;
+  const r =
+    e.shape === 'sphere'
+      ? a
+      : e.shape === 'ellipsoid'
+        ? Math.max(a, b, c)
+        : e.shape === 'roundBox'
+          ? Math.hypot(a, b, c) / 2
+          : e.shape === 'cone'
+            ? c + Math.max(a, b) // loose but unchanged: it also sets the grid bounds
+            : e.shape === 'torus'
+              ? a + b
+              : a + Math.hypot(to[0] - e.at[0], to[1] - e.at[1], to[2] - e.at[2]) / 2;
+  const ell = e.shape === 'ellipsoid';
+  const lo = Math.min(a, b, c);
+  return { c: centre, r, scale: ell ? (lo / r) ** 2 : 1, inside: !ell };
+}
+
+/** Conservative world bounds of an add edit (bounding sphere), grown by its blend radius. */
+export function editBounds(e: SculptEdit, mirrorAll: boolean): [Vec3, Vec3] {
+  if ('group' in e) return groupBounds(e, mirrorAll);
+  const { c: centre, r } = shapeSphere(e);
+  const g = r + (e.blend ?? 0);
+  const lo: [number, number, number] = [centre[0] - g, centre[1] - g, centre[2] - g];
+  const hi: [number, number, number] = [centre[0] + g, centre[1] + g, centre[2] + g];
+  if (e.mirror ?? mirrorAll) {
+    const [l, h] = [lo[1], hi[1]];
+    lo[1] = Math.min(l, -h);
+    hi[1] = Math.max(h, -l);
+  }
+  return [lo, hi];
+}
+
+function groupBounds(g: SculptGroup, mirrorAll: boolean): [Vec3, Vec3] {
+  const lo: [number, number, number] = [Infinity, Infinity, Infinity];
+  const hi: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  const k = g.blend ?? 0;
+  for (const e of g.group) {
+    if ((e.op ?? 'add') !== 'add') continue;
+    const [a, b] = editBounds(e, g.mirror ?? mirrorAll);
+    for (let i = 0; i < 3; i++) {
+      lo[i] = Math.min(lo[i] ?? 0, (a[i] ?? 0) - k);
+      hi[i] = Math.max(hi[i] ?? 0, (b[i] ?? 0) + k);
+    }
+  }
+  return [lo, hi];
+}

package/src/primitives/sculpt-tree.ts

@@ -0,0 +1,226 @@
+// Sculpt evaluation: the edit list compiled into a tree (groups fold their own edits first) and
+// folded per query point. Sparse: every node carries a bounding sphere with a proven lower bound
+// on its value, and an edit is skipped only when that bound shows its blend weight would be
+// exactly 1 (nothing changes) — so skipping is bit-identical to evaluating, just faster. A weight
+// of 1 passes the running value through untouched (no `v + (d − v)` rounding).
+
+import type { Vec3 } from '../core/index.ts';
+import { invalid } from './check.ts';
+import { type SculptEdit, sculptShape, shapeSphere } from './sculpt-edit.ts';
+import type { Field } from './sdf-ops.ts';
+
+const ADD = 0;
+const SUB = 1;
+const INTER = 2;
+const PAINT = 3;
+const OPS = { add: ADD, subtract: SUB, intersect: INTER, paint: PAINT } as const;
+
+export interface Node {
+  readonly op: number;
+  readonly k: number;
+  /** The edit's own colour (shapes), or null. */
+  readonly color: Vec3 | null;
+  readonly shape: Field | null;
+  readonly kids: readonly Node[] | null;
+  /** Default colour for this group's edits; its scratch colour buffer. */
+  readonly base: Vec3;
+  readonly rgb: Float64Array;
+  // Bound: value ≥ scale · (|p − c| − r) − under outside the sphere (and ≥ |p − c| − r − under
+  // inside it when `inside`); `mirror` also tests the sphere mirrored across y = 0.
+  readonly c: Vec3;
+  readonly r: number;
+  readonly scale: number;
+  readonly inside: boolean;
+  readonly mirror: boolean;
+  readonly under: number;
+}
+
+export function compile(
+  edits: readonly SculptEdit[],
+  base: Vec3,
+  mirror: boolean,
+  path = 'sculpt',
+): Node[] {
+  if (!edits.some((e) => (e.op ?? 'add') === 'add'))
+    invalid(`${path} has no add edits, so nothing to carve from`, "make the first edit op: 'add'");
+  return edits.map((e, i): Node => {
+    const op = OPS[e.op ?? 'add'];
+    const k = e.blend ?? 0;
+    const m = e.mirror ?? mirror;
+    if ('group' in e) {
+      const kids = compile(e.group, e.color ?? base, m, `${path} group ${i}`);
+      const b = enclose(kids);
+      return node(
+        op,
+        k,
+        e.color ?? null,
+        null,
+        kids,
+        e.color ?? base,
+        3,
+        b.c,
+        b.r,
+        b.scale,
+        b.inside,
+        false,
+        b.under,
+      );
+    }
+    const s = shapeSphere(e);
+    return node(
+      op,
+      k,
+      e.color ?? null,
+      sculptShape(e, i, m),
+      null,
+      base,
+      0,
+      s.c,
+      s.r,
+      s.scale,
+      s.inside,
+      m,
+      0,
+    );
+  });
+}
+
+/** Every node built in one property order: the fold loop stays monomorphic (one hidden class). */
+function node(
+  op: number,
+  k: number,
+  color: Vec3 | null,
+  shape: Field | null,
+  kids: readonly Node[] | null,
+  base: Vec3,
+  rgb: number,
+  c: Vec3,
+  r: number,
+  scale: number,
+  inside: boolean,
+  mirror: boolean,
+  under: number,
+): Node {
+  return {
+    op,
+    k,
+    color,
+    shape,
+    kids,
+    base,
+    rgb: new Float64Array(rgb),
+    c,
+    r,
+    scale,
+    inside,
+    mirror,
+    under,
+  };
+}
+
+/** One sphere around all add children (and their mirror copies), scale = the weakest child's. */
+function enclose(
+  kids: readonly Node[],
+): Pick<Node, 'c' | 'r' | 'scale' | 'inside' | 'mirror' | 'under'> {
+  const adds = kids.filter((n) => n.op === ADD);
+  const spheres = adds.flatMap((n) =>
+    n.mirror ? [n, { ...n, c: [n.c[0], -n.c[1], n.c[2]] as Vec3 }] : [n],
+  );
+  const lo = [0, 1, 2].map((a) => Math.min(...spheres.map((n) => (n.c[a] ?? 0) - n.r)));
+  const hi = [0, 1, 2].map((a) => Math.max(...spheres.map((n) => (n.c[a] ?? 0) + n.r)));
+  const c: Vec3 = [
+    ((lo[0] ?? 0) + (hi[0] ?? 0)) / 2,
+    ((lo[1] ?? 0) + (hi[1] ?? 0)) / 2,
+    ((lo[2] ?? 0) + (hi[2] ?? 0)) / 2,
+  ];
+  const r = Math.max(
+    ...spheres.map((n) => Math.hypot(n.c[0] - c[0], n.c[1] - c[1], n.c[2] - c[2]) + n.r),
+  );
+  return {
+    c,
+    r,
+    scale: Math.min(...adds.map((n) => n.scale)),
+    inside: adds.every((n) => n.inside),
+    mirror: false,
+    // Smooth union undershoots the plain min by at most k/4 per blend; children's own undershoot adds.
+    under: adds.reduce((u, n) => u + n.k / 4 + n.under, 0),
+  };
+}
+
+function lowerBound(n: Node, p: Vec3): number {
+  const dx = p[0] - n.c[0];
+  const dz = p[2] - n.c[2];
+  let dy = p[1] - n.c[1];
+  let q = dx * dx + dy * dy + dz * dz;
+  if (n.mirror) {
+    dy = p[1] + n.c[1];
+    q = Math.min(q, dx * dx + dy * dy + dz * dz);
+  }
+  const out = Math.sqrt(q) - n.r;
+  if (out > 0) return n.scale * out - n.under;
+  return n.inside ? out - n.under : Number.NEGATIVE_INFINITY;
+}
+
+const clamp01 = (x: number): number => (x < 0 ? 0 : Math.min(x, 1));
+/** Smooth-min weight of `a` against `b` (1 = all a). */
+const weight = (a: number, b: number, k: number): number =>
+  k > 0 ? clamp01(0.5 + (0.5 * (b - a)) / k) : a < b ? 1 : 0;
+/** Margin past which a bound proves the weight is exactly 1, rounding included. */
+const slack = (d: number): number => 1e-9 * (1 + Math.abs(d));
+
+/** Fold `nodes` at p; writes the blended colour into `rgb` (seeded with `base`) when given. */
+export function fold(
+  nodes: readonly Node[],
+  p: Vec3,
+  rgb: Float64Array | null,
+  base: Vec3,
+  sparse = true,
+): number {
+  let d = Number.POSITIVE_INFINITY;
+  if (rgb) rgb.set(base);
+  for (const n of nodes) {
+    const k = n.k;
+    if (n.op === PAINT) {
+      if (!rgb || !n.color || !n.shape) continue;
+      const kk = Math.max(k, 1e-9);
+      if (sparse && lowerBound(n, p) > kk / 2 + slack(kk)) continue;
+      const w = 1 - clamp01(0.5 - n.shape(p) / kk);
+      if (w < 1) mix(rgb, n.color, w);
+      continue;
+    }
+    const empty = d === Number.POSITIVE_INFINITY;
+    if (empty && n.op !== ADD) continue;
+    if (sparse && !empty) {
+      if (n.op === ADD && lowerBound(n, p) > d + k + slack(d)) continue;
+      if (n.op === SUB && lowerBound(n, p) > k - d + slack(d)) continue;
+    }
+    const v = n.kids
+      ? fold(n.kids, p, rgb ? n.rgb : null, n.base, sparse)
+      : n.shape
+        ? n.shape(p)
+        : 0;
+    let w = 0;
+    if (empty) d = v;
+    else if (n.op === ADD) {
+      w = weight(d, v, k);
+      if (w !== 1) d = v + (d - v) * w - k * w * (1 - w);
+    } else {
+      // subtract = smooth max(d, −v); intersect = smooth max(d, v).
+      const b = n.op === SUB ? -v : v;
+      w = weight(-d, -b, k);
+      if (w !== 1) d = -(-b + (-d + b) * w - k * w * (1 - w));
+    }
+    if (!rgb || w >= 1) continue;
+    if (n.kids) {
+      if (n.color || n.op === ADD) mixArr(rgb, n.rgb, w);
+    } else if (n.color || n.op === ADD) mix(rgb, n.color ?? base, w);
+  }
+  return d;
+}
+
+const mix = (rgb: Float64Array, c: Vec3, w: number): void => {
+  for (let j = 0; j < 3; j++) rgb[j] = (c[j] ?? 0) + ((rgb[j] ?? 0) - (c[j] ?? 0)) * w;
+};
+const mixArr = (rgb: Float64Array, c: Float64Array, w: number): void => {
+  for (let j = 0; j < 3; j++) rgb[j] = (c[j] ?? 0) + ((rgb[j] ?? 0) - (c[j] ?? 0)) * w;
+};

package/src/primitives/sculpt.ts

@@ -0,0 +1,80 @@
+// Sculpting as an ordered list of SDF edits (the Dreams model): each edit adds, subtracts,
+// intersects or paints a simple shape, blended into everything before it by a smooth-min of
+// radius `blend` metres. Colour rides the same blend weights, so skin, lips, eye whites and tusks
+// come out as vertex colour on ONE mesh. `mirror: 'y'` makes every edit symmetric left/right
+// (Y in our Z-up, +X-front frame); an edit can opt out. Meshed by `sdf` (smooth gradient normals),
+// bounds found from the edits. `resolution` = cell edge in metres: ctx.pick([0.004, 0.012, 0.03]).
+// `sculptField` exposes the field + colour so a recipe can displace it before meshing.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { invalid } from './check.ts';
+import { editBounds, type SculptEdit } from './sculpt-edit.ts';
+import { compile, fold } from './sculpt-tree.ts';
+import { sdf } from './sdf.ts';
+import type { Field } from './sdf-ops.ts';
+
+export type { SculptEdit, SculptGroup, SculptShape, SculptShapeEdit } from './sculpt-edit.ts';
+
+export interface SculptField {
+  readonly field: Field;
+  /** Blended edit colour at a point (call at surface points). */
+  readonly colorAt: (p: Vec3) => Vec3;
+  /** Edits' bounds grown by their blend radii. */
+  readonly bounds: readonly [Vec3, Vec3];
+}
+
+export interface SculptOptions {
+  readonly edits: readonly SculptEdit[];
+  /** Cell edge in metres (the LOD knob). */
+  readonly resolution: number;
+  /** Colour of edits that give none. */
+  readonly color: Vec3;
+  readonly mirror?: 'y';
+  readonly mesher?: 'nets' | 'cubes';
+  readonly strip?: StripId;
+}
+
+export function sculptField(
+  edits: readonly SculptEdit[],
+  o: { readonly color: Vec3; readonly mirror?: 'y' },
+): SculptField {
+  if (edits.length === 0)
+    invalid('sculpt has no edits', "start with an { shape: 'sphere', op: 'add', ... } edit");
+  const nodes = compile(edits, o.color, o.mirror === 'y');
+  const rgb = new Float64Array(3);
+  const adds = edits.filter((e) => (e.op ?? 'add') === 'add');
+  const lo = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const hi = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  for (const e of adds) {
+    const [a, b] = editBounds(e, o.mirror === 'y');
+    for (let k = 0; k < 3; k++) {
+      lo[k] = Math.min(lo[k] ?? 0, a[k] ?? 0);
+      hi[k] = Math.max(hi[k] ?? 0, b[k] ?? 0);
+    }
+  }
+  return {
+    field: (p) => fold(nodes, p, null, o.color),
+    colorAt: (p) => {
+      fold(nodes, p, rgb, o.color);
+      return [rgb[0] ?? 0, rgb[1] ?? 0, rgb[2] ?? 0];
+    },
+    bounds: [
+      [lo[0] ?? 0, lo[1] ?? 0, lo[2] ?? 0],
+      [hi[0] ?? 0, hi[1] ?? 0, hi[2] ?? 0],
+    ],
+  };
+}
+
+export function sculpt(o: SculptOptions): Mesh {
+  const s = sculptField(o.edits, { color: o.color, ...(o.mirror ? { mirror: o.mirror } : {}) });
+  return sdf({
+    field: s.field,
+    bounds: s.bounds,
+    resolution: o.resolution,
+    color: (p) => s.colorAt(p),
+    ...(o.mesher ? { mesher: o.mesher } : {}),
+    ...(o.mirror === 'y' ? { symmetry: 'y' as const } : {}),
+    ...(o.strip ? { strip: o.strip } : {}),
+  });
+}