cozyclay 3.1.0 → 3.1.2

package/src/sculpt-compare.js

@@ -16,6 +16,7 @@
  * Pure: image buffers in, numbers and RGBA out. The MCP tool owns the files.
  */
 import { expandSculptParts, patchSculptRecipe } from "./sculpt-recipe.js";
+import { SCULPT_SHAPE_SPECS } from "./sculpt-shapes.js";
 
 const COMPARE_SIZE = 256;
 
@@ -117,37 +118,6 @@ function applyMatrix(m, [x, y, z]) {
 	return [m[0] * x + m[4] * y + m[8] * z + m[12], m[1] * x + m[5] * y + m[9] * z + m[13], m[2] * x + m[6] * y + m[10] * z + m[14]];
 }
 
-function partSurfaceSamples(part) {
-	const [sx, sy, sz] = part.size.map((v) => v / 2);
-	const points = [];
-	if (part.shape === "box") {
-		for (const x of [-sx, sx]) for (const y of [-sy, sy]) for (const z of [-sz, sz]) points.push([x, y, z]);
-		return points;
-	}
-	const p = 2 + 6 * (part.roundness ?? 0);
-	const taper = part.taper ?? 0;
-	for (let i = 0; i <= 16; i += 1) {
-		const v = -1 + (2 * i) / 16;
-		const k = taper > 0 ? 1 - taper * 0.6 * ((v + 1) / 2) : taper < 0 ? 1 + taper * 0.6 * ((1 - v) / 2) : 1;
-		for (let j = 0; j < 24; j += 1) {
-			const t = (j / 24) * 2 * Math.PI;
-			if (part.shape === "cylinder") {
-				const r = 1 - Math.max(0, part.taper) * ((v + 1) / 2) - Math.max(0, -part.taper) * ((1 - v) / 2);
-				points.push([Math.cos(t) * sx * r, v * sy, Math.sin(t) * sz * r]);
-			} else if (part.shape === "torus" || part.shape === "frame") {
-				points.push([Math.cos(t) * sx, Math.sin(t) * sy, v * sz]);
-				if (part.shape === "frame") points.push([Math.sign(Math.cos(t)) * sx, Math.sign(Math.sin(t)) * sy, v * sz]);
-			} else {
-				const ring = Math.max(0, 1 - Math.abs(v) ** p) ** (1 / p);
-				const c = Math.cos(t), s = Math.sin(t);
-				const norm = (Math.abs(c) ** p + Math.abs(s) ** p) ** (1 / p);
-				points.push([(c / norm) * sx * ring * k, v * sy, (s / norm) * sz * ring * k]);
-			}
-		}
-	}
-	return points;
-}
-
 function convexHull(points) {
 	const pts = points.slice().sort((a, b) => a[0] - b[0] || a[1] - b[1]);
 	const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
@@ -157,26 +127,19 @@ function convexHull(points) {
 	return lower.slice(0, -1).concat(upper.slice(0, -1));
 }
 
-/** Projected convex outline of every drawn part, in view metres. Frames keep their hole. */
+/** Projected convex outline of every drawn part, in view metres. Frames keep their hole. A cutter (op) adds no area and cuts no hole: the reference mask fills enclosed holes anyway, and an intersect's parent keeps its uncut outline. */
 export function sculptViewPolygons(recipe, { yaw = 0, elevation = 0 } = {}) {
-	return expandSculptParts(recipe).map((part) => {
-		const local = partSurfaceSamples(part);
-		const polygon = convexHull(local.map((point) => viewProject(applyMatrix(part.matrix, point), yaw, elevation)));
-		let hole = null;
-		if (part.shape === "frame" || part.shape === "torus") {
-			const ix = part.size[0] / 2 - (part.shape === "frame" ? part.border : part.size[2]);
-			const iy = part.size[1] / 2 - (part.shape === "frame" ? part.border : part.size[2]);
-			if (ix > 0 && iy > 0) {
-				const corners = [[-ix, -iy], [ix, -iy], [ix, iy], [-ix, iy]].flatMap(([x, y]) => [[x, y, -part.size[2] / 2], [x, y, part.size[2] / 2]]);
-				const projected = corners.map((point) => viewProject(applyMatrix(part.matrix, point), yaw, elevation));
-				// See-through only where the front and back openings overlap; the back
-				// face's opening alone is a slightly generous stand-in.
-				const opening = convexHull(projected.filter((_, i) => i % 2 === 0));
-				hole = opening.length >= 3 ? opening : null;
-			}
-		}
-		return { id: part.id, polygon, hole };
-	});
+	return expandSculptParts(recipe).filter((part) => !part.op).map((part) => {
+		const project = (point) => viewProject(applyMatrix(part.matrix, point), yaw, elevation);
+		const spec = SCULPT_SHAPE_SPECS[part.shape];
+		// See-through only where the front and back openings overlap; the front
+		// face's opening alone is a slightly generous stand-in.
+		const opening = spec.hole?.(part);
+		const holeHull = opening ? convexHull(opening.map(project)) : [];
+		const hole = holeHull.length >= 3 ? holeHull : null;
+		// One polygon per sample group, all carrying the part's id.
+		return spec.samples(part).map((group) => ({ id: part.id, polygon: convexHull(group.map(project)), hole }));
+	}).flat();
 }
 
 function insidePolygon(polygon, x, y) {

package/src/sculpt-csg.js

@@ -0,0 +1,112 @@
+/**
+ * Sculpt booleans: the cutters a recipe declares (`op`, sculpt-cutters.js) run
+ * on their parent part's geometry with three-bvh-csg.
+ *
+ * The cut happens in the parent's own frame. The cutter's geometry is moved by
+ * inverse(parent) × cutter, both object-frame matrices from expandSculptParts,
+ * so the result drops straight back into the parent's mesh, and the mesh keeps
+ * its transform, name, shadows and material. A cut only removes (subtract) or
+ * keeps less (intersect), so the stored standing box stays an honest bound.
+ *
+ * A boolean that throws, yields non-finite points or leaves nothing is skipped
+ * with a warning. The part is then drawn as it was before that cut instead of
+ * vanishing or breaking the build, and the same recipe always skips the same
+ * cut.
+ */
+import * as THREE from "three";
+import { Brush, Evaluator, HalfEdgeMap, INTERSECTION, SUBTRACTION } from "three-bvh-csg";
+import { MeshBVH } from "three-mesh-bvh";
+
+const OPERATIONS = { subtract: SUBTRACTION, intersect: INTERSECTION };
+/** Carried through a cut when both sides have them at the same item size. The
+ * evaluator throws on an attribute one side lacks, so the rest are dropped. */
+const CARRIED = ["position", "normal", "uv", "color"];
+
+/**
+ * three-bvh-csg 0.0.18 prepares a brush with the BVH option `maxLeafSize`, and
+ * three-mesh-bvh 0.9 warns about it on every build: two warnings per cut that
+ * would bury a real one. This is the same preparation with the current option.
+ * A sculpt brush is prepared once and evaluated synchronously, so it also
+ * skips the SharedArrayBuffer copy that only the worker path needs.
+ */
+class SculptBrush extends Brush {
+	prepareGeometry() {
+		const { geometry } = this;
+		geometry.boundsTree = new MeshBVH(geometry, { targetLeafSize: 3, indirect: true });
+		geometry.halfEdges = new HalfEdgeMap();
+		geometry.halfEdges.updateFrom(geometry);
+		// Every triangle in group 0: the evaluator runs with useGroups off.
+		geometry.groupIndices = new Uint16Array((geometry.index ?? geometry.getAttribute("position")).count / 3);
+	}
+}
+
+/** A parent with vertex colours (a gradient look) would lose them against a
+ * cutter without any, so the cutter borrows their mean. The parent keeps its
+ * colours, and the cut faces take its average tone. */
+function lendColours(geometry, cutter) {
+	const colour = geometry.getAttribute("color");
+	if (!colour || cutter.hasAttribute("color")) return;
+	const { count, itemSize } = colour;
+	const mean = Array.from({ length: itemSize }, (_, k) => {
+		let sum = 0;
+		for (let i = 0; i < count; i += 1) sum += colour.getComponent(i, k);
+		return sum / count;
+	});
+	const lent = new THREE.BufferAttribute(new colour.array.constructor(cutter.getAttribute("position").count * itemSize), itemSize, colour.normalized);
+	for (let i = 0; i < lent.count; i += 1) for (let k = 0; k < itemSize; k += 1) lent.setComponent(i, k, mean[k]);
+	cutter.setAttribute("color", lent);
+}
+
+/** `geometry` cut by `cutter` (already in the same frame), as a new geometry. Throws when the cut fails. */
+function evaluate(geometry, cutter, operation) {
+	lendColours(geometry, cutter);
+	const evaluator = new Evaluator();
+	evaluator.useGroups = false;
+	// Constrained Delaunay clipping leaves far fewer T-junctions than the legacy
+	// splitter and handles coplanar faces, such as a cutter exactly as deep as its wall.
+	evaluator.useCDTClipping = true;
+	evaluator.attributes = CARRIED.filter((name) => geometry.hasAttribute(name) && geometry.getAttribute(name).itemSize === cutter.getAttribute(name)?.itemSize);
+	const a = new SculptBrush(geometry), b = new SculptBrush(cutter);
+	try {
+		a.updateMatrixWorld();
+		b.updateMatrixWorld();
+		const result = evaluator.evaluate(a, b, operation).geometry;
+		const points = result.getAttribute("position")?.array ?? [];
+		const reason = result.drawRange.count < 3 ? "it leaves nothing" : points.every(Number.isFinite) ? null : "it yields non-finite points";
+		if (reason) {
+			result.dispose();
+			throw new Error(reason);
+		}
+		if (!result.hasAttribute("normal")) result.computeVertexNormals();
+		return result;
+	} finally {
+		a.disposeCacheData();
+		b.disposeCacheData();
+	}
+}
+
+/**
+ * `geometry` (built for `part`, in its own frame) cut by every cutter whose
+ * parent is `part`, in recipe order. `parts` is expandSculptParts' list and
+ * `build(cutter)` makes a cutter's geometry. Whatever the cuts replace is
+ * disposed here; the geometry returned belongs to the caller.
+ */
+export function cutSculptGeometry(geometry, part, parts, build) {
+	let cut = geometry;
+	let parentInverse = null;
+	for (const cutter of parts) {
+		if (!cutter.op || cutter.parent !== part.id) continue;
+		parentInverse ??= new THREE.Matrix4().fromArray(part.matrix).invert();
+		const tool = build(cutter).applyMatrix4(new THREE.Matrix4().fromArray(cutter.matrix).premultiply(parentInverse));
+		try {
+			const next = evaluate(cut, tool, OPERATIONS[cutter.op]);
+			cut.dispose();
+			cut = next;
+		} catch (error) {
+			console.warn(`sculpt: skipped ${cutter.op} "${cutter.id}" on "${part.id}" (${error.message}); the part is drawn without that cut`);
+		} finally {
+			tool.dispose();
+		}
+	}
+	return cut;
+}

package/src/sculpt-curve.js

@@ -0,0 +1,123 @@
+/**
+ * Curve and outline math for the sculpt shapes that follow points (lathe,
+ * tube, extrude). Pure: no three.js. The recipe reader, the silhouette compare
+ * and the geometry builder all sample through here, so the drawn shape and the
+ * scored shape cannot drift apart.
+ */
+
+const EPSILON = 1e-9;
+
+/** Fritsch–Butland slope at a knot: zero where the axis turns, otherwise the
+ * harmonic mean of the two secants, which is never more than twice either. */
+function knotSlope(before, after) {
+	if (before === null) return after;
+	if (after === null) return before;
+	return before * after <= 0 ? 0 : (2 * before * after) / (before + after);
+}
+
+/**
+ * A smooth curve through `points` (arrays of any length), `steps` samples per
+ * segment. Each axis is a monotone cubic: it passes through every point and,
+ * between two points, never leaves the box they span. So a profile with r <= 1
+ * stays <= 1 and a path inside its box stays inside, with no clamping. A
+ * Catmull-Rom spline overshoots instead. `closed` joins the last point back to
+ * the first and returns no repeated end sample.
+ */
+export function monotoneCurve(points, steps, closed = false) {
+	const n = points.length;
+	const at = (i) => points[closed ? (i + n) % n : i];
+	const tangents = points.map((point, k) => point.map((value, axis) => knotSlope(
+		closed || k > 0 ? value - at(k - 1)[axis] : null,
+		closed || k < n - 1 ? at(k + 1)[axis] - value : null,
+	)));
+	const out = [];
+	for (let segment = 0; segment < (closed ? n : n - 1); segment += 1) {
+		const a = at(segment), b = at(segment + 1), ta = tangents[segment], tb = tangents[(segment + 1) % n];
+		for (let i = 0; i < steps; i += 1) {
+			const t = i / steps, t2 = t * t, t3 = t2 * t;
+			const h00 = 2 * t3 - 3 * t2 + 1, h10 = t3 - 2 * t2 + t, h01 = 3 * t2 - 2 * t3, h11 = t3 - t2;
+			out.push(a.map((value, axis) => h00 * value + h10 * ta[axis] + h01 * b[axis] + h11 * tb[axis]));
+		}
+	}
+	if (!closed) out.push([...points[n - 1]]);
+	return out;
+}
+
+/** Signed area: positive when the loop runs counter-clockwise. */
+export function signedArea(loop) {
+	let sum = 0;
+	for (let i = 0, j = loop.length - 1; i < loop.length; j = i, i += 1) sum += loop[j][0] * loop[i][1] - loop[i][0] * loop[j][1];
+	return sum / 2;
+}
+
+const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+const side = (o, a, b) => {
+	const value = cross(o, a, b);
+	return Math.abs(value) <= EPSILON ? 0 : Math.sign(value);
+};
+const within = (a, b, p) => Math.min(a[0], b[0]) - EPSILON <= p[0] && p[0] <= Math.max(a[0], b[0]) + EPSILON
+	&& Math.min(a[1], b[1]) - EPSILON <= p[1] && p[1] <= Math.max(a[1], b[1]) + EPSILON;
+
+function segmentsTouch(a, b, c, d) {
+	const o1 = side(a, b, c), o2 = side(a, b, d), o3 = side(c, d, a), o4 = side(c, d, b);
+	if (o1 !== o2 && o3 !== o4) return true;
+	return (o1 === 0 && within(a, b, c)) || (o2 === 0 && within(a, b, d)) || (o3 === 0 && within(c, d, a)) || (o4 === 0 && within(c, d, b));
+}
+
+/**
+ * The first two edges that touch or cross, across every loop, as
+ * `{ a: { loop, edge }, b: { loop, edge } }`, or null when the loops are simple
+ * and apart. Neighbouring edges of one loop share a point by design; they only
+ * count when the second folds back along the first.
+ */
+export function loopCrossing(loops) {
+	const edges = loops.flatMap((loop, index) => loop.map((p, edge) => ({ loop: index, edge, n: loop.length, a: p, b: loop[(edge + 1) % loop.length] })));
+	for (let i = 0; i < edges.length; i += 1) {
+		for (let j = i + 1; j < edges.length; j += 1) {
+			const e = edges[i], f = edges[j];
+			const follows = e.loop === f.loop && (e.edge + 1) % e.n === f.edge;
+			const precedes = e.loop === f.loop && (f.edge + 1) % f.n === e.edge;
+			let touch;
+			if (follows || precedes) {
+				const [shared, p, q] = follows ? [e.b, e.a, f.b] : [e.a, e.b, f.a];
+				touch = side(shared, p, q) === 0 && (p[0] - shared[0]) * (q[0] - shared[0]) + (p[1] - shared[1]) * (q[1] - shared[1]) > 0;
+			} else touch = segmentsTouch(e.a, e.b, f.a, f.b);
+			if (touch) return { a: { loop: e.loop, edge: e.edge }, b: { loop: f.loop, edge: f.edge } };
+		}
+	}
+	return null;
+}
+
+/** Even-odd test of a point against a closed loop. */
+export function insideLoop([x, y], loop) {
+	let inside = false;
+	for (let i = 0, j = loop.length - 1; i < loop.length; j = i, i += 1) {
+		const [xi, yi] = loop[i], [xj, yj] = loop[j];
+		if ((yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+	}
+	return inside;
+}
+
+/**
+ * Ear clipping: index triples covering a simple loop of either winding. n is
+ * at most 64, so the quadratic search is cheap. A loop left with only
+ * collinear corners is clipped anyway, so the loop always ends.
+ */
+export function earClip(loop) {
+	const ring = loop.map((_, index) => index);
+	if (signedArea(loop) < 0) ring.reverse();
+	const triangles = [];
+	while (ring.length > 3) {
+		const corner = (i) => [ring[(i + ring.length - 1) % ring.length], ring[i], ring[(i + 1) % ring.length]];
+		let cut = ring.findIndex((_, i) => {
+			const [a, b, c] = corner(i).map((k) => loop[k]);
+			if (cross(a, b, c) <= EPSILON) return false;
+			return !ring.some((k) => !corner(i).includes(k) && cross(a, b, loop[k]) >= 0 && cross(b, c, loop[k]) >= 0 && cross(c, a, loop[k]) >= 0);
+		});
+		if (cut < 0) cut = 0;
+		triangles.push(corner(cut));
+		ring.splice(cut, 1);
+	}
+	triangles.push(ring);
+	return triangles;
+}

package/src/sculpt-cutters.js

@@ -0,0 +1,43 @@
+/**
+ * Sculpt cutters: a part with `op` is never drawn. It cuts its `parent` part,
+ * which is how a recipe gets windows, doors and arches in a wall, a hollow
+ * bowl or cup, or a notch in a plank (subtract), and a half-dome or a sliced
+ * fruit (intersect). This module is the pure half: it reads `op` and refuses
+ * the recipes a cutter cannot serve. sculpt-csg.js runs the boolean on the
+ * parent's geometry. Pure: no three.js.
+ *
+ * Several cutters on one parent apply in recipe order, and a mirrored cutter
+ * cuts both sides. A cutter's colour is never seen: the cut faces wear the
+ * parent's look. Each rule below is refused with its path, never bent into a
+ * different shape:
+ *  - a cutter needs a parent, because a cutter at the object level would have
+ *    nothing to cut;
+ *  - a cutter carries no parts. A drawn child would ride a frame nobody sees,
+ *    and a cutter that cuts another cutter is not supported, so two cutters
+ *    that build one opening (an arched door) both cut the wall.
+ */
+import { RecipeError } from "./sculpt-recipe-read.js";
+
+const SCULPT_OPS = ["subtract", "intersect"];
+
+export const SCULPT_OP_FIELD = Object.freeze({
+	key: "op",
+	read(raw, part, where) {
+		if (!SCULPT_OPS.includes(raw.op)) throw new RecipeError(`${where}.op`, `must be "subtract" or "intersect", got ${JSON.stringify(raw.op)}`);
+		if (part.parent === undefined) throw new RecipeError(`${where}.op`, "a cutter needs a parent: the part it cuts");
+		part.op = raw.op;
+	},
+});
+
+/** Refuses any part that names a cutter as its parent. Run it once parents resolve. */
+export function checkSculptCutters(parts) {
+	const byId = new Map(parts.map((part) => [part.id, part]));
+	for (const part of parts) {
+		const parent = byId.get(part.parent);
+		if (part.op && parent?.shape === "scatter") throw new RecipeError(`parts[${part.id}].op`, `"${parent.id}" is a scatter, which is drawn as instances and cannot be cut`);
+		if (!parent?.op) continue;
+		throw new RecipeError(`parts[${part.id}].parent`, part.op
+			? `"${parent.id}" is a cutter, and a cutter only cuts drawn parts; give this one parent "${parent.parent}" so both cut it`
+			: `"${parent.id}" is a cutter (op), which is not drawn and cannot carry parts; use parent "${parent.parent}" instead`);
+	}
+}

package/src/sculpt-detail.js

@@ -0,0 +1,207 @@
+/**
+ * Surface detail: a part's `detail` (sculpt-surface-fields.js) turns a smooth
+ * primitive into a lumpy cloud, bush, rock or loaf by pushing its surface out
+ * along the normals with seeded, billowed fBm noise (|fBm|: rounded lumps with
+ * creases between them, which reads as puffs or stone where plain fBm reads as
+ * a dented ball). It is a post-process on any part's
+ * BufferGeometry, so a shape added later gets it without a line of its own.
+ *
+ * - Bounds: the base is shrunk by the bump height first and no vertex then
+ *   moves further than that, so the lumps end inside the declared size and
+ *   the record's measured box (which trusts size) still holds.
+ * - Seams: vertices are welded by position before anything moves, so both
+ *   sides of a sphere's seam (or a box's edge) move together and never split.
+ * - Tessellation: a box or a one-segment cylinder has too few vertices to
+ *   show a bump, so long edges are halved until they are a fraction of a bump.
+ *   The split test reads only the edge, so both triangles on an edge agree
+ *   and no T-junction cracks open once the surface moves.
+ */
+
+import * as THREE from "three";
+import { DETAIL_RELIEF } from "./sculpt-surface-fields.js";
+import { fbm3, isMirrorCopy, partSeed, seededRandom } from "./sculpt-noise.js";
+
+/** A detailed part stops splitting edges past this many triangles. */
+const MAX_TRIANGLES = 40000;
+/** Edges are split until a bump spans about this many of them. */
+const EDGES_PER_BUMP = 5;
+/** Faces meeting more sharply than this stay creased (a box edge); lumps shade smooth. */
+const CREASE_COS = Math.cos((65 * Math.PI) / 180);
+
+/** Vertex → id shared by every vertex at the same position (within `eps`), via
+ * an open-addressed table on the quantized position. */
+function weld(position, eps) {
+	const count = position.length / 3;
+	const ids = new Int32Array(count);
+	let size = 1;
+	while (size < count * 2) size <<= 1;
+	const table = new Int32Array(size).fill(-1);
+	const keys = new Int32Array(count * 3);
+	let unique = 0;
+	for (let i = 0; i < count; i += 1) {
+		const qx = Math.round(position[3 * i] / eps), qy = Math.round(position[3 * i + 1] / eps), qz = Math.round(position[3 * i + 2] / eps);
+		let slot = (Math.imul(qx, 73856093) ^ Math.imul(qy, 19349663) ^ Math.imul(qz, 83492791)) & (size - 1);
+		for (;;) {
+			const id = table[slot];
+			if (id < 0) {
+				table[slot] = unique;
+				keys[3 * unique] = qx; keys[3 * unique + 1] = qy; keys[3 * unique + 2] = qz;
+				ids[i] = unique++;
+				break;
+			}
+			if (keys[3 * id] === qx && keys[3 * id + 1] === qy && keys[3 * id + 2] === qz) {
+				ids[i] = id;
+				break;
+			}
+			slot = (slot + 1) & (size - 1);
+		}
+	}
+	return { ids, count: unique };
+}
+
+/** Local corners per split mask (bit 0 = edge ab, 1 = bc, 2 = ca); 3, 4, 5 are
+ * the midpoints of ab, bc, ca. Every pattern keeps the source winding. */
+const PATTERNS = [
+	[0, 1, 2],
+	[0, 3, 2, 3, 1, 2],
+	[1, 4, 0, 4, 2, 0],
+	[3, 1, 4, 0, 3, 4, 0, 4, 2],
+	[2, 5, 1, 5, 0, 1],
+	[5, 0, 3, 2, 5, 3, 2, 3, 1],
+	[4, 2, 5, 1, 4, 5, 1, 5, 0],
+	[0, 3, 5, 3, 1, 4, 5, 4, 2, 3, 4, 5],
+];
+
+/** Non-indexed attributes ([position, ...others]) with every edge longer
+ * than `maxEdge` halved, pass by pass, within MAX_TRIANGLES. */
+function subdivide(attributes, maxEdge) {
+	const limit = maxEdge * maxEdge;
+	for (let pass = 0; pass < 10; pass += 1) {
+		const position = attributes[0].array;
+		const triangles = position.length / 9;
+		const masks = new Uint8Array(triangles);
+		let next = 0;
+		for (let t = 0; t < triangles; t += 1) {
+			for (let e = 0; e < 3; e += 1) {
+				const a = 9 * t + 3 * e, b = 9 * t + 3 * ((e + 1) % 3);
+				const dx = position[a] - position[b], dy = position[a + 1] - position[b + 1], dz = position[a + 2] - position[b + 2];
+				if (dx * dx + dy * dy + dz * dz > limit) masks[t] |= 1 << e;
+			}
+			next += PATTERNS[masks[t]].length / 3;
+		}
+		if (next === triangles || next > MAX_TRIANGLES) break;
+		attributes = attributes.map(({ name, size, array }) => {
+			const out = new Float64Array(next * 3 * size);
+			let o = 0;
+			for (let t = 0; t < triangles; t += 1) {
+				const base = 3 * t * size;
+				for (const corner of PATTERNS[masks[t]]) {
+					// (a + b) / 2 is the same bits from either side, so neighbours share the midpoint exactly.
+					const a = corner < 3 ? corner : corner - 3, b = corner < 3 ? corner : (corner - 2) % 3;
+					for (let k = 0; k < size; k += 1) out[o++] = (array[base + a * size + k] + array[base + b * size + k]) / 2;
+				}
+			}
+			return { name, size, array: out };
+		});
+	}
+	return attributes;
+}
+
+/** Area-weighted (unnormalized) normal of every triangle. */
+function faceNormals(position) {
+	const normals = new Float64Array(position.length / 3);
+	for (let f = 0; f < position.length; f += 9) {
+		const ax = position[f + 3] - position[f], ay = position[f + 4] - position[f + 1], az = position[f + 5] - position[f + 2];
+		const bx = position[f + 6] - position[f], by = position[f + 7] - position[f + 1], bz = position[f + 8] - position[f + 2];
+		normals[f / 3] = ay * bz - az * by;
+		normals[f / 3 + 1] = az * bx - ax * bz;
+		normals[f / 3 + 2] = ax * by - ay * bx;
+	}
+	return normals;
+}
+
+/** Per-vertex normals: the faces around the welded vertex that meet the
+ * vertex's own face within the crease angle, area-weighted. */
+function creasedNormals(position, ids, count) {
+	const faces = faceNormals(position);
+	const unit = faces.map((value, i) => value / (Math.hypot(faces[i - (i % 3)], faces[i - (i % 3) + 1], faces[i - (i % 3) + 2]) || 1));
+	const start = new Int32Array(count + 1);
+	for (const id of ids) start[id + 1] += 1;
+	for (let id = 0; id < count; id += 1) start[id + 1] += start[id];
+	const fill = start.slice(0, count), around = new Int32Array(ids.length);
+	ids.forEach((id, v) => { around[fill[id]++] = Math.floor(v / 3); });
+	const normals = new Float32Array(position.length);
+	for (let v = 0; v < ids.length; v += 1) {
+		const own = 3 * Math.floor(v / 3);
+		const flat = unit[own] === 0 && unit[own + 1] === 0 && unit[own + 2] === 0;
+		let x = 0, y = 0, z = 0;
+		for (let k = start[ids[v]]; k < start[ids[v] + 1]; k += 1) {
+			const g = 3 * around[k];
+			if (!flat && unit[g] * unit[own] + unit[g + 1] * unit[own + 1] + unit[g + 2] * unit[own + 2] < CREASE_COS) continue;
+			x += faces[g]; y += faces[g + 1]; z += faces[g + 2];
+		}
+		const length = Math.hypot(x, y, z);
+		if (length > 0) normals.set([x / length, y / length, z / length], 3 * v);
+		else normals[3 * v + 1] = 1;
+	}
+	return normals;
+}
+
+/**
+ * The part's geometry with its `detail` applied, or the geometry untouched
+ * when the part has none. The result is non-indexed and keeps every other
+ * attribute (uv, colour), interpolated where edges were split.
+ */
+export function applySculptDetail(geometry, part) {
+	const amount = part.detail?.amount ?? 0;
+	if (!(amount > 0)) return geometry;
+	const half = part.size.map((value) => value / 2);
+	const longest = Math.max(...part.size);
+	const relief = amount * DETAIL_RELIEF * Math.min(...half);
+	geometry.scale(...half.map((h) => (h - relief) / h));
+	const source = geometry.index ? geometry.toNonIndexed() : geometry;
+	const names = ["position", ...Object.keys(source.attributes).filter((name) => name !== "position" && name !== "normal")];
+	let attributes = names.map((name) => ({ name, size: source.attributes[name].itemSize, array: Float64Array.from(source.attributes[name].array) }));
+	geometry.dispose();
+	source.dispose();
+	// Snap every vertex onto its welded twin so split decisions and midpoints match bit for bit.
+	const eps = longest * 1e-5;
+	let { ids, count } = weld(attributes[0].array, eps);
+	const first = new Int32Array(count).fill(-1);
+	ids.forEach((id, v) => {
+		if (first[id] < 0) first[id] = v;
+		else for (let k = 0; k < 3; k += 1) attributes[0].array[3 * v + k] = attributes[0].array[3 * first[id] + k];
+	});
+	attributes = subdivide(attributes, longest / part.detail.scale / EDGES_PER_BUMP);
+	const position = attributes[0].array;
+	({ ids, count } = weld(position, eps));
+	const faces = faceNormals(position);
+	const normal = new Float64Array(count * 3);
+	ids.forEach((id, v) => {
+		const f = 3 * Math.floor(v / 3);
+		for (let k = 0; k < 3; k += 1) normal[3 * id + k] += faces[f + k];
+	});
+	// Noise per welded vertex. A mirrored copy reads it at −x, so it lumps as its source's reflection.
+	const seed = partSeed(part, part.detail.seed);
+	const random = seededRandom(seed);
+	const offset = [random() * 64, random() * 64, random() * 64];
+	const frequency = part.detail.scale / longest, flip = isMirrorCopy(part) ? -1 : 1;
+	const lift = new Float64Array(count).fill(NaN);
+	ids.forEach((id, v) => {
+		if (Number.isNaN(lift[id])) lift[id] = Math.abs(fbm3(flip * position[3 * v] * frequency + offset[0], position[3 * v + 1] * frequency + offset[1], position[3 * v + 2] * frequency + offset[2], seed));
+	});
+	let low = Infinity, high = -Infinity;
+	for (const value of lift) { low = Math.min(low, value); high = Math.max(high, value); }
+	// Rescaled to 0..1, so the highest lump reaches the declared size and the deepest stays on the shrunk base.
+	const span = high - low || 1;
+	ids.forEach((id, v) => {
+		const n = 3 * id, length = Math.hypot(normal[n], normal[n + 1], normal[n + 2]);
+		if (!(length > 0)) return;
+		const push = (relief * (lift[id] - low)) / span / length;
+		for (let k = 0; k < 3; k += 1) position[3 * v + k] += normal[n + k] * push;
+	});
+	const detailed = new THREE.BufferGeometry();
+	for (const { name, size, array } of attributes) detailed.setAttribute(name, new THREE.BufferAttribute(Float32Array.from(array), size));
+	detailed.setAttribute("normal", new THREE.BufferAttribute(creasedNormals(position, ids, count), 3));
+	return detailed;
+}

package/src/sculpt-geometry-loft-convex.js

@@ -0,0 +1,100 @@
+/**
+ * Geometry for the `loft` and `convex` sculpt shapes. The points come from the
+ * pure modules (sculpt-loft-rings.js, sculpt-shapes-loft-convex.js), so the
+ * silhouette compare hulls exactly what is drawn; three.js only skins them.
+ */
+
+import * as THREE from "three";
+import { ConvexGeometry } from "three/examples/jsm/geometries/ConvexGeometry.js";
+import { LoftGeometry } from "three/examples/jsm/geometries/LoftGeometry.js";
+import { loftRings } from "./sculpt-loft-rings.js";
+import { convexPoints } from "./sculpt-shapes-loft-convex.js";
+
+/** An unsmoothed loft keeps edges sharper than this crisp; a rounded corner's
+ * small steps still shade as one curve. */
+const LOFT_CREASE = (40 * Math.PI) / 180;
+
+/**
+ * Normals for a non-indexed mesh: each corner averages the area-weighted
+ * normals of the faces that share its exact position and turn less than
+ * `crease` from its own face. (BufferGeometryUtils.toCreasedNormals hashes
+ * positions to 1 cm, which merges the corners of a small gem.)
+ */
+function creaseNormals(geometry, crease) {
+	const position = geometry.getAttribute("position");
+	const key = (i) => `${position.getX(i)},${position.getY(i)},${position.getZ(i)}`;
+	const a = new THREE.Vector3(), b = new THREE.Vector3(), c = new THREE.Vector3();
+	const faceNormals = [];
+	const facesAt = new Map();
+	for (let f = 0; f < position.count / 3; f += 1) {
+		a.fromBufferAttribute(position, 3 * f);
+		b.fromBufferAttribute(position, 3 * f + 1);
+		c.fromBufferAttribute(position, 3 * f + 2);
+		faceNormals.push(new THREE.Vector3().subVectors(c, b).cross(a.sub(b)));
+		for (let k = 0; k < 3; k += 1) {
+			const at = key(3 * f + k);
+			if (!facesAt.has(at)) facesAt.set(at, []);
+			facesAt.get(at).push(f);
+		}
+	}
+	const limit = Math.cos(crease);
+	const previous = geometry.getAttribute("normal");
+	const normals = new Float32Array(position.count * 3);
+	const own = new THREE.Vector3(), other = new THREE.Vector3(), sum = new THREE.Vector3();
+	for (let i = 0; i < position.count; i += 1) {
+		own.copy(faceNormals[Math.floor(i / 3)]).normalize();
+		sum.set(0, 0, 0);
+		for (const f of facesAt.get(key(i))) if (other.copy(faceNormals[f]).normalize().dot(own) >= limit) sum.add(faceNormals[f]);
+		// A zero-area face has no direction of its own: it keeps the one it had.
+		if (sum.lengthSq() === 0) sum.fromBufferAttribute(previous, i);
+		sum.normalize().toArray(normals, 3 * i);
+	}
+	geometry.setAttribute("normal", new THREE.BufferAttribute(normals, 3));
+}
+
+/** Box-projected uvs per triangle: each facet maps the two axes it faces
+ * most squarely, scaled by size, so a facet's texture is never smeared. */
+function boxUvs(geometry, size) {
+	const position = geometry.getAttribute("position");
+	const uvs = new Float32Array(position.count * 2);
+	const a = new THREE.Vector3(), b = new THREE.Vector3(), c = new THREE.Vector3();
+	for (let f = 0; f < position.count / 3; f += 1) {
+		a.fromBufferAttribute(position, 3 * f);
+		b.fromBufferAttribute(position, 3 * f + 1);
+		c.fromBufferAttribute(position, 3 * f + 2);
+		const n = c.sub(b).cross(a.sub(b));
+		const facing = [Math.abs(n.x), Math.abs(n.y), Math.abs(n.z)];
+		const axis = facing.indexOf(Math.max(...facing));
+		const [u, v] = [[2, 1], [0, 2], [0, 1]][axis];
+		for (let k = 0; k < 3; k += 1) {
+			uvs[(3 * f + k) * 2] = position.getComponent(3 * f + k, u) / size[u] + 0.5;
+			uvs[(3 * f + k) * 2 + 1] = position.getComponent(3 * f + k, v) / size[v] + 0.5;
+		}
+	}
+	geometry.setAttribute("uv", new THREE.BufferAttribute(uvs, 2));
+}
+
+function loftGeometry(part) {
+	const sections = loftRings(part).rings.map((ring) => ring.map(([x, y, z]) => new THREE.Vector3(x, y, z)));
+	const geometry = new LoftGeometry(sections, { capStart: true, capEnd: true });
+	// The caps come last, one vertex per ring point each, and are level (every
+	// section is horizontal). Earcut leaves zero-area slivers between collinear
+	// samples, whose computed normals can be zero, so the caps are set outright.
+	const normal = geometry.getAttribute("normal"), first = normal.count - 2 * sections[0].length;
+	for (let i = first; i < normal.count; i += 1) normal.setXYZ(i, 0, i < first + sections[0].length ? -1 : 1, 0);
+	if (part.smooth) return geometry;
+	const faceted = geometry.toNonIndexed();
+	geometry.dispose();
+	creaseNormals(faceted, LOFT_CREASE);
+	return faceted;
+}
+
+/** ConvexGeometry gives flat facet normals; `facets: false` smooths them all. */
+function convexGeometry(part) {
+	const geometry = new ConvexGeometry(convexPoints(part).map(([x, y, z]) => new THREE.Vector3(x, y, z)));
+	boxUvs(geometry, part.size);
+	if (!part.facets) creaseNormals(geometry, Math.PI);
+	return geometry;
+}
+
+export const LOFT_CONVEX_BUILDERS = Object.freeze({ loft: loftGeometry, convex: convexGeometry });