cozyclay 3.1.0 → 3.1.2

package/src/sculpt-geometry-shapes.js

@@ -0,0 +1,250 @@
+/**
+ * Geometry for the sculpt shapes that follow points (sculpt-shapes-curved.js):
+ * lathe, tube and extrude, each one indexed mesh with a uv in metres, so a
+ * texture keeps one scale across parts of different sizes.
+ *
+ * Normals are welded per piece: inside a piece, every vertex at one position
+ * shares one normal (a lathe's seam, a tube's round end); between pieces they
+ * stay apart, so a pot's bottom edge and a sign's face edge stay crisp. Like
+ * every sculpt shape, nothing is drawn outside the part's declared size.
+ */
+
+import * as THREE from "three";
+import { signedArea } from "./sculpt-curve.js";
+import { latheRows, tubeCentre, tubeRadii } from "./sculpt-shapes-curved.js";
+
+const AROUND = 48;
+const TUBE_SIDES = 20;
+const CAP_ROWS = 6;
+const BEVEL_ROWS = 4;
+/** An outline corner that turns more than this keeps a hard edge on the side wall. */
+const CREASE = (35 * Math.PI) / 180;
+
+const sub = (a, b) => a.map((value, axis) => value - b[axis]);
+const dot = (a, b) => a.reduce((sum, value, axis) => sum + value * b[axis], 0);
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const unit = (v) => {
+	const length = Math.hypot(...v);
+	return length > 1e-12 ? v.map((value) => value / length) : null;
+};
+const clamp = (value, limit) => Math.min(limit, Math.max(-limit, value));
+
+class Pieces {
+	constructor() {
+		this.position = [];
+		this.uv = [];
+		this.index = [];
+		this.weld = [];
+	}
+
+	/** A rows × cols piece from `at(row, col)` → [x, y, z, u, v]. The column step
+	 * crossed with the row step must point out of the solid. */
+	grid(rows, cols, at) {
+		const keys = new Map();
+		const ids = [];
+		for (let i = 0; i < rows; i += 1) for (let j = 0; j < cols; j += 1) ids.push(this.vertex(keys, at(i, j)));
+		for (let i = 0; i + 1 < rows; i += 1) {
+			for (let j = 0; j + 1 < cols; j += 1) {
+				const a = ids[i * cols + j], b = ids[i * cols + j + 1], c = ids[(i + 1) * cols + j], d = ids[(i + 1) * cols + j + 1];
+				this.index.push(a, b, c, b, d, c);
+			}
+		}
+	}
+
+	/** A flat piece: points [x, y, z, u, v] and triangles over them, wound outward. */
+	fan(points, triangles) {
+		const keys = new Map();
+		const ids = points.map((point) => this.vertex(keys, point));
+		for (const triangle of triangles) this.index.push(...triangle.map((k) => ids[k]));
+	}
+
+	vertex(keys, [x, y, z, u, v]) {
+		const id = this.position.length / 3;
+		const key = `${x},${y},${z}`;
+		if (!keys.has(key)) keys.set(key, id);
+		this.weld.push(keys.get(key));
+		this.position.push(x, y, z);
+		this.uv.push(u, v);
+		return id;
+	}
+
+	/** Area-weighted face normals, summed on each welded position. */
+	build() {
+		const p = this.position, sum = new Float64Array(p.length);
+		for (let t = 0; t < this.index.length; t += 3) {
+			const [a, b, c] = [0, 1, 2].map((k) => this.index[t + k]);
+			const corner = (k) => [p[k * 3], p[k * 3 + 1], p[k * 3 + 2]];
+			const normal = cross(sub(corner(b), corner(a)), sub(corner(c), corner(a)));
+			for (const k of [a, b, c]) for (let axis = 0; axis < 3; axis += 1) sum[this.weld[k] * 3 + axis] += normal[axis];
+		}
+		const normals = new Float32Array(p.length);
+		this.weld.forEach((w, i) => {
+			const n = unit([sum[w * 3], sum[w * 3 + 1], sum[w * 3 + 2]]) ?? [0, 1, 0];
+			normals.set(n, i * 3);
+		});
+		const geometry = new THREE.BufferGeometry();
+		geometry.setAttribute("position", new THREE.Float32BufferAttribute(p, 3));
+		geometry.setAttribute("normal", new THREE.BufferAttribute(normals, 3));
+		geometry.setAttribute("uv", new THREE.Float32BufferAttribute(this.uv, 2));
+		geometry.setIndex(this.index);
+		return geometry;
+	}
+}
+
+/** The profile turned round y with an elliptical section; caps close the ends
+ * that stand off the axis, so a pot has a bottom. */
+export function latheGeometry(part) {
+	const [hx, , hz] = part.size.map((value) => value / 2);
+	const rows = latheRows(part, Math.min(12, Math.ceil(120 / (part.profile.length - 1))));
+	const arc = [0];
+	for (let k = 1; k < rows.length; k += 1) arc.push(arc[k - 1] + Math.hypot(((rows[k][0] - rows[k - 1][0]) * (hx + hz)) / 2, rows[k][1] - rows[k - 1][1]));
+	// `j % AROUND` makes the seam column the very same numbers as the first, so it welds.
+	const ring = ([r, y], j) => {
+		const angle = ((j % AROUND) / AROUND) * 2 * Math.PI;
+		return [r * hx * Math.sin(angle), y, r * hz * Math.cos(angle)];
+	};
+	const mesh = new Pieces();
+	const wall = (from, to) => mesh.grid(to - from + 1, AROUND + 1, (i, j) => [...ring(rows[from + i], j), (j / AROUND) * Math.PI * (hx + hz), arc[from + i]]);
+	if (part.smooth) wall(0, rows.length - 1);
+	else for (let k = 0; k + 1 < rows.length; k += 1) wall(k, k + 1);
+	const cap = (rim, top) => {
+		const order = top ? [rim, [0, rim[1]]] : [[0, rim[1]], rim];
+		mesh.grid(2, AROUND + 1, (i, j) => {
+			const point = ring(order[i], j);
+			return [...point, point[0], point[2]];
+		});
+	};
+	if (rows[0][0] > 0) cap(rows[0], false);
+	if (rows.at(-1)[0] > 0) cap(rows.at(-1), true);
+	return mesh.build();
+}
+
+/** Parallel-transport frames: the ring does not twist where the path bends. On
+ * a loop the leftover twist is spread along it, so the seam meets itself. */
+function tubeFrames(tangents, closed) {
+	const across = (t) => unit(cross(t, Math.abs(t[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0]));
+	let normal = across(tangents[0]);
+	const frames = tangents.map((t) => {
+		normal = unit(sub(normal, t.map((value) => value * dot(normal, t)))) ?? across(t);
+		return [normal, cross(t, normal)];
+	});
+	if (!closed) return frames;
+	const [n0, b0] = frames[0], t0 = tangents[0], last = frames.at(-1)[0];
+	const end = unit(sub(last, t0.map((value) => value * dot(last, t0)))) ?? n0;
+	const twist = Math.atan2(dot(end, b0), dot(end, n0));
+	return frames.map(([n, b], k) => {
+		const angle = (-twist * k) / frames.length;
+		const turned = n.map((value, axis) => Math.cos(angle) * value + Math.sin(angle) * b[axis]);
+		return [turned, cross(tangents[k], turned)];
+	});
+}
+
+/** A round tube along the path; an open one ends in half-balls. */
+export function tubeGeometry(part) {
+	const segments = part.closed ? part.path.length : part.path.length - 1;
+	const centre = tubeCentre(part, Math.min(24, Math.max(4, Math.ceil(128 / segments))));
+	const radii = tubeRadii(part, centre);
+	const n = centre.length;
+	const near = (k) => centre[part.closed ? (k + n) % n : Math.min(n - 1, Math.max(0, k))];
+	let previous = [0, 1, 0];
+	const tangents = centre.map((_, k) => (previous = unit(sub(near(k + 1), near(k - 1))) ?? previous));
+	const frames = tubeFrames(tangents, part.closed);
+	const run = [0];
+	for (let k = 1; k < n; k += 1) run.push(run[k - 1] + Math.hypot(...sub(centre[k], centre[k - 1])));
+	const rows = centre.map((c, k) => ({ c, r: radii[k], frame: frames[k], u: run[k] }));
+	if (part.closed) rows.push({ ...rows[0], u: run[n - 1] + Math.hypot(...sub(centre[0], centre[n - 1])) });
+	else {
+		// Rows of a half-ball from the pole to just short of the end ring.
+		const cap = (k, sign) => Array.from({ length: CAP_ROWS }, (_, i) => {
+			const angle = (((CAP_ROWS - i) / CAP_ROWS) * Math.PI) / 2;
+			const reach = radii[k] * Math.sin(angle);
+			return { c: centre[k].map((value, axis) => value + sign * tangents[k][axis] * reach), r: i ? radii[k] * Math.cos(angle) : 0, frame: frames[k], u: run[k] + sign * reach };
+		});
+		rows.unshift(...cap(0, -1));
+		rows.push(...cap(n - 1, 1).reverse());
+	}
+	const mesh = new Pieces();
+	mesh.grid(rows.length, TUBE_SIDES + 1, (i, j) => {
+		const { c, r, frame: [normal, binormal], u } = rows[i];
+		const angle = ((j % TUBE_SIDES) / TUBE_SIDES) * 2 * Math.PI;
+		const cos = Math.cos(angle), sin = Math.sin(angle);
+		return [...c.map((value, axis) => value + r * (cos * normal[axis] + sin * binormal[axis])), u, (j / TUBE_SIDES) * Math.PI * part.thickness];
+	});
+	return mesh.build();
+}
+
+/** Each corner's inward offset per metre of inset (a mitre, capped at 2× so a
+ * spike cannot shoot far); the solid is on every loop's left. */
+function mitres(loop) {
+	const left = (a, b) => unit([a[1] - b[1], b[0] - a[0]]);
+	return loop.map((p, i) => {
+		const n1 = left(loop[(i + loop.length - 1) % loop.length], p), n2 = left(p, loop[(i + 1) % loop.length]);
+		const m = unit([n1[0] + n2[0], n1[1] + n2[1]]) ?? n1;
+		const scale = 1 / Math.max(0.5, dot(m, n1));
+		return [m[0] * scale, m[1] * scale];
+	});
+}
+
+/** The deepest inset before an edge of the loop turns round, which is where a
+ * thin spike would fold through itself. */
+function insetLimit(loop, offsets) {
+	return loop.reduce((limit, p, i) => {
+		const k = (i + 1) % loop.length, edge = sub(loop[k], p), shrink = dot(sub(offsets[k], offsets[i]), edge);
+		return shrink < 0 ? Math.min(limit, -dot(edge, edge) / shrink) : limit;
+	}, Infinity);
+}
+
+/** The outline pushed through size z, with an optional rounded bevel and holes. */
+export function extrudeGeometry(part) {
+	const [hx, hy, hz] = part.size.map((value) => value / 2);
+	const metres = (loop, ccw) => {
+		const points = loop.map(([x, y]) => [x * part.size[0], y * part.size[1]]);
+		return signedArea(points) > 0 === ccw ? points : points.reverse();
+	};
+	const loops = [metres(part.outline, true), ...(part.holes ?? []).map((hole) => metres(hole, false))];
+	const span = (axis) => Math.max(...loops[0].map((p) => p[axis])) - Math.min(...loops[0].map((p) => p[axis]));
+	const bevel = (part.roundness * Math.min(part.size[2], span(0), span(1))) / 2;
+	const offsets = loops.map(mitres);
+	// Star points and thin arms take a shallower inset than the bevel's depth, so the face never folds.
+	const inset = Math.min(bevel, 0.5 * Math.min(...loops.map((loop, l) => insetLimit(loop, offsets[l]))));
+	// The side's section [inset, z] from the back face round to the front face.
+	const quarter = Array.from({ length: bevel > 0 ? BEVEL_ROWS + 1 : 1 }, (_, i) => {
+		const angle = (i / BEVEL_ROWS) * (Math.PI / 2);
+		return [inset * (1 - Math.sin(angle)), hz - bevel * (1 - Math.cos(angle))];
+	});
+	const back = quarter.map(([offset, z]) => [offset, -z]), front = [...quarter].reverse();
+	const section = back.at(-1)[1] === front[0][1] ? [...back, ...front.slice(1)] : [...back, ...front];
+	// A deep bevel on a thin spike can push a mitre past the outline; the clamp keeps the box honest.
+	const at = (l, i, depth) => [clamp(loops[l][i][0] + offsets[l][i][0] * depth, hx), clamp(loops[l][i][1] + offsets[l][i][1] * depth, hy)];
+	const mesh = new Pieces();
+	loops.forEach((loop, l) => {
+		const n = loop.length;
+		const along = [0];
+		for (let i = 1; i <= n; i += 1) along.push(along[i - 1] + Math.hypot(...sub(loop[i % n], loop[i - 1])));
+		const corners = loop.flatMap((p, i) => {
+			const turn = Math.acos(Math.max(-1, Math.min(1, dot(unit(sub(p, loop[(i + n - 1) % n])), unit(sub(loop[(i + 1) % n], p))))));
+			return turn > CREASE ? [i] : [];
+		});
+		const runs = corners.length ? corners.map((from, k) => [from, k + 1 < corners.length ? corners[k + 1] : corners[0] + n]) : [[0, n]];
+		for (const [from, to] of runs) {
+			mesh.grid(section.length, to - from + 1, (i, j) => {
+				const k = from + j;
+				return [...at(l, k % n, section[i][0]), section[i][1], along[k % n] + (k >= n ? along[n] : 0), section[i][1]];
+			});
+		}
+	});
+	const flat = loops.flatMap((loop, l) => loop.map((_, i) => [l, i]));
+	const vectors = loops.map((loop) => loop.map(([x, y]) => new THREE.Vector2(x, y)));
+	const faces = THREE.ShapeUtils.triangulateShape(vectors[0], vectors.slice(1)).map((face) => {
+		const [a, b, c] = face.map((k) => loops[flat[k][0]][flat[k][1]]);
+		return signedArea([a, b, c]) >= 0 ? face : [face[0], face[2], face[1]];
+	});
+	for (const sign of [1, -1]) {
+		const points = flat.map(([l, i]) => {
+			const [x, y] = at(l, i, inset);
+			return [x, y, sign * hz, x, y];
+		});
+		mesh.fan(points, sign > 0 ? faces : faces.map(([a, b, c]) => [a, c, b]));
+	}
+	return mesh.build();
+}

package/src/sculpt-geometry.js

@@ -12,11 +12,14 @@
 import * as THREE from "three";
 import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";
 import { expandSculptParts } from "./sculpt-recipe.js";
-
-const CLAY_ROUGHNESS = 0.82;
-/** How far a full taper narrows a blob's end. A blob at 1.0 would come to a
- * point, which reads as a cone; 0.6 keeps a pear a pear. */
-const BLOB_TAPER = 0.6;
+import { BLOB_TAPER } from "./sculpt-shapes.js";
+import { cutSculptGeometry } from "./sculpt-csg.js";
+import { LOFT_CONVEX_BUILDERS } from "./sculpt-geometry-loft-convex.js";
+import { extrudeGeometry, latheGeometry, tubeGeometry } from "./sculpt-geometry-shapes.js";
+import { applySculptDetail } from "./sculpt-detail.js";
+import { applySculptColours } from "./sculpt-colours.js";
+import { scatterMesh } from "./sculpt-scatter.js";
+import { lookMaterial } from "./material-look.js";
 
 /** roundness 0..1 → superellipse exponent 2..8 */
 const blobExponent = (roundness) => 2 + 6 * roundness;
@@ -97,32 +100,44 @@ function frameGeometry(part) {
 	return geometry;
 }
 
-const BUILDERS = { blob: blobGeometry, box: boxGeometry, cylinder: cylinderGeometry, torus: torusGeometry, frame: frameGeometry };
+const BUILDERS = { blob: blobGeometry, box: boxGeometry, cylinder: cylinderGeometry, torus: torusGeometry, frame: frameGeometry, lathe: latheGeometry, tube: tubeGeometry, extrude: extrudeGeometry, ...LOFT_CONVEX_BUILDERS };
+/** Shapes that draw their own mesh (many instances) instead of one geometry. */
+const MESH_BUILDERS = { scatter: scatterMesh };
 
+/** The part's geometry, with its surface `detail` applied. */
 export function sculptPartGeometry(part) {
 	const build = BUILDERS[part.shape];
 	if (!build) throw new Error(`unknown sculpt shape "${part.shape}"`);
-	return build(part);
+	return applySculptDetail(build(part), part);
 }
 
 /**
  * The drawable object for a normalized recipe. `materialFor(part)` lets the
- * caller decide the look (clay, auto-colour, depth rank); the default is the
- * matte clay every primitive wears. Meshes carry their part id as the name and
- * as `userData.sculptPart`, so a capture or a raycast can say which part it hit.
+ * caller decide the look (auto-colour, depth rank); the default is the part's
+ * own preset (material-look.js), clay when it names none, with the part's
+ * gradient and a scatter's per-item tint. Meshes (a scatter's InstancedMesh
+ * too) carry their part id as the name and as `userData.sculptPart`, so a
+ * capture or a raycast can say which part it hit. Glass casts no shadow: light
+ * passes through it.
  */
 export function buildSculptGroup(recipe, { materialFor } = {}) {
 	const group = new THREE.Group();
 	group.userData.sculpt = true;
 	const matrix = new THREE.Matrix4();
-	for (const part of expandSculptParts(recipe)) {
-		const material = materialFor ? materialFor(part) : new THREE.MeshStandardMaterial({ color: part.color, roughness: CLAY_ROUGHNESS, metalness: 0 });
-		const mesh = new THREE.Mesh(sculptPartGeometry(part), material);
+	const parts = expandSculptParts(recipe);
+	for (const part of parts) {
+		// A cutter (op) is never drawn: it cuts its parent's geometry instead.
+		if (part.op) continue;
+		const material = materialFor ? materialFor(part) : lookMaterial(part);
+		// A scatter draws its own InstancedMesh and is never cut; every other part is cut by its cutters.
+		const mesh = MESH_BUILDERS[part.shape]?.(part, material) ?? new THREE.Mesh(cutSculptGeometry(sculptPartGeometry(part), part, parts, sculptPartGeometry), material);
+		// Gradients and scatter tints belong to the shaded look; a flat display mode (materialFor) ignores them.
+		if (!materialFor) applySculptColours(mesh, part);
 		mesh.name = part.id;
 		mesh.userData.sculptPart = part.id;
 		matrix.fromArray(part.matrix);
 		matrix.decompose(mesh.position, mesh.quaternion, mesh.scale);
-		mesh.castShadow = true;
+		mesh.castShadow = !(material.transmission > 0);
 		mesh.receiveShadow = true;
 		group.add(mesh);
 	}
@@ -130,11 +145,14 @@ export function buildSculptGroup(recipe, { materialFor } = {}) {
 }
 
 /** Frees what buildSculptGroup allocated. Materials are disposed too, because
- * buildSculptGroup (or the caller's materialFor) minted one per part. */
+ * buildSculptGroup (or the caller's materialFor) minted one per part; a
+ * scatter's instance buffers go with its InstancedMesh. The preset pattern
+ * textures they sample are shared and stay. */
 export function disposeSculptGroup(group) {
 	group?.traverse((node) => {
 		if (!node.isMesh) return;
 		node.geometry.dispose();
+		if (node.isInstancedMesh) node.dispose();
 		const materials = Array.isArray(node.material) ? node.material : [node.material];
 		for (const material of materials) material.dispose();
 	});

package/src/sculpt-loft-rings.js

@@ -0,0 +1,225 @@
+/**
+ * The rings a `loft` sculpt part is skinned through. Pure: no three.js, so the
+ * silhouette compare samples exactly the surface sculpt-geometry draws.
+ *
+ * A section (sculpt-shapes-loft-convex.js reads them) is either an outline,
+ * { y, points: [[x, z]...] }, or a rounded rectangle, { y, w, d, x, z,
+ * roundness }; all of it fractions of the part's size. Every section becomes a
+ * ring of RING_POINTS samples that starts at its front, on the line through
+ * its centroid, and runs the same way round, so sections with different point
+ * counts skin without a twist.
+ *
+ * `smooth` turns an outline into a closed centripetal Catmull-Rom curve and
+ * joins sections with a monotone cubic in y. The curve is fitted back into its
+ * outline's own extents and the monotone cubic never leaves the range of the
+ * sections it joins, so no vertex can overshoot the declared size.
+ */
+
+/** Samples per ring. */
+const RING_POINTS = 48;
+/** Rings per section-to-section span when smooth. */
+const SPAN_STEPS = 6;
+/** Curve samples per outline edge before resampling. */
+const CURVE_STEPS = 8;
+/** Segments per rounded corner of a rectangle section. */
+const CORNER_STEPS = 6;
+/** A corner that turns more than 30 degrees is kept as a sample (cosine). */
+const SHARP_TURN = Math.cos(Math.PI / 6);
+
+const lerp = (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+const distance = (a, b) => Math.hypot(b[0] - a[0], b[1] - a[1]);
+
+/** Twice the signed area in (x, z): positive runs from +x toward +z. */
+export function signedArea(ring) {
+	let sum = 0;
+	for (let i = 0; i < ring.length; i += 1) {
+		const a = ring[i], b = ring[(i + 1) % ring.length];
+		sum += a[0] * b[1] - b[0] * a[1];
+	}
+	return sum;
+}
+
+function centroid(ring) {
+	let cx = 0, cz = 0;
+	for (let i = 0; i < ring.length; i += 1) {
+		const a = ring[i], b = ring[(i + 1) % ring.length];
+		const cross = a[0] * b[1] - b[0] * a[1];
+		cx += (a[0] + b[0]) * cross;
+		cz += (a[1] + b[1]) * cross;
+	}
+	const area = signedArea(ring);
+	return [cx / (3 * area), cz / (3 * area)];
+}
+
+/** Drops repeated points, including a last point that repeats the first. */
+function dedupe(ring) {
+	const out = ring.filter((point, i) => i === 0 || distance(point, ring[i - 1]) > 1e-9);
+	while (out.length > 1 && distance(out[0], out.at(-1)) <= 1e-9) out.pop();
+	return out;
+}
+
+/** w by d, centred on (x, z), corners rounded by roundness × half the short side. */
+function roundedRect({ w, d, x, z, roundness }) {
+	const hx = w / 2, hz = d / 2;
+	const r = roundness * Math.min(hx, hz);
+	const steps = r > 0 ? CORNER_STEPS : 0;
+	const points = [];
+	for (const [cx, cz, start] of [[hx - r, hz - r, 0], [r - hx, hz - r, 1], [r - hx, r - hz, 2], [hx - r, r - hz, 3]]) {
+		for (let i = 0; i <= steps; i += 1) {
+			const angle = (start + (steps ? i / steps : 0.5)) * (Math.PI / 2);
+			points.push([x + cx + r * Math.cos(angle), z + cz + r * Math.sin(angle)]);
+		}
+	}
+	return points;
+}
+
+/** A closed centripetal Catmull-Rom curve through `points` (three.js's formulation). */
+function catmullRom(points) {
+	const n = points.length;
+	const out = [];
+	for (let i = 0; i < n; i += 1) {
+		const p0 = points[(i - 1 + n) % n], p1 = points[i], p2 = points[(i + 1) % n], p3 = points[(i + 2) % n];
+		let dt1 = Math.sqrt(distance(p1, p2));
+		let dt0 = Math.sqrt(distance(p0, p1));
+		let dt2 = Math.sqrt(distance(p2, p3));
+		if (dt1 < 1e-4) dt1 = 1;
+		if (dt0 < 1e-4) dt0 = dt1;
+		if (dt2 < 1e-4) dt2 = dt1;
+		const axis = (k) => {
+			const t1 = ((p1[k] - p0[k]) / dt0 - (p2[k] - p0[k]) / (dt0 + dt1) + (p2[k] - p1[k]) / dt1) * dt1;
+			const t2 = ((p2[k] - p1[k]) / dt1 - (p3[k] - p1[k]) / (dt1 + dt2) + (p3[k] - p2[k]) / dt2) * dt1;
+			return [p1[k], t1, -3 * p1[k] + 3 * p2[k] - 2 * t1 - t2, 2 * p1[k] - 2 * p2[k] + t1 + t2];
+		};
+		const cx = axis(0), cz = axis(1);
+		for (let s = 0; s < CURVE_STEPS; s += 1) {
+			const t = s / CURVE_STEPS;
+			out.push([cx[0] + t * (cx[1] + t * (cx[2] + t * cx[3])), cz[0] + t * (cz[1] + t * (cz[2] + t * cz[3]))]);
+		}
+	}
+	return out;
+}
+
+const extent = (ring, k) => [Math.min(...ring.map((p) => p[k])), Math.max(...ring.map((p) => p[k]))];
+
+/** Maps the curve's box onto the outline's box. The curve passes through every
+ * outline point, so this only ever shrinks it: the extents written are drawn. */
+function fitInto(curve, outline) {
+	const ranges = [0, 1].map((k) => [extent(curve, k), extent(outline, k)]);
+	return curve.map((point) => point.map((value, k) => {
+		const [[from0, from1], [to0, to1]] = ranges[k];
+		return from1 - from0 > 1e-12 ? to0 + ((value - from0) * (to1 - to0)) / (from1 - from0) : value;
+	}));
+}
+
+/** The ring rotated to start where the line x = centroid x leaves its front
+ * (+z). The rule is its own mirror image, so a mirrored loft pairs the same
+ * points across its sections and comes out as the exact reflection. */
+function startAtFront(ring) {
+	const cx = centroid(ring)[0];
+	let best = null;
+	for (let i = 0; i < ring.length; i += 1) {
+		const a = ring[i], b = ring[(i + 1) % ring.length];
+		if ((a[0] - cx) * (b[0] - cx) > 0) continue;
+		const t = a[0] === b[0] ? 0 : (cx - a[0]) / (b[0] - a[0]);
+		const z = a[1] + (b[1] - a[1]) * t;
+		if (!best || z > best.z) best = { i, t, z };
+	}
+	if (!best) return ring;
+	const start = lerp(ring[best.i], ring[(best.i + 1) % ring.length], best.t);
+	return dedupe([start, ...ring.slice(best.i + 1), ...ring.slice(0, best.i + 1)]);
+}
+
+/** `count` samples spaced evenly by arc length, measured with the ring scaled
+ * to a unit box: every rectangle then has its corners at the same fractions
+ * whatever its aspect, so a square base meets a thin ridge side to side and
+ * the gable stays flat. Each sharp corner then takes the place of its nearest
+ * sample, so a box section keeps its edges. */
+function resample(ring, count) {
+	const n = ring.length;
+	const span = [0, 1].map((k) => Math.max(1e-9, extent(ring, k)[1] - extent(ring, k)[0]));
+	const lengths = ring.map((point, i) => Math.hypot((ring[(i + 1) % n][0] - point[0]) / span[0], (ring[(i + 1) % n][1] - point[1]) / span[1]));
+	const total = lengths.reduce((sum, length) => sum + length, 0);
+	const out = [];
+	let edge = 0, walked = 0;
+	for (let j = 0; j < count; j += 1) {
+		const target = (j / count) * total;
+		while (edge < n - 1 && walked + lengths[edge] < target) walked += lengths[edge++];
+		out.push(lerp(ring[edge], ring[(edge + 1) % n], lengths[edge] > 0 ? Math.min(1, (target - walked) / lengths[edge]) : 0));
+	}
+	const taken = new Set();
+	walked = 0;
+	ring.forEach((point, i) => {
+		const before = ring[(i - 1 + n) % n], after = ring[(i + 1) % n];
+		const turn = ((point[0] - before[0]) * (after[0] - point[0]) + (point[1] - before[1]) * (after[1] - point[1])) / (distance(before, point) * distance(point, after));
+		const k = Math.round((walked / total) * count) % count;
+		if (turn < SHARP_TURN && !taken.has(k)) {
+			taken.add(k);
+			out[k] = point;
+		}
+		walked += lengths[i];
+	});
+	return out;
+}
+
+/** One section as RING_POINTS [x, z] fractions, wound the way LoftGeometry
+ * faces outward (negative signed area in x, z). */
+function sectionRing(section, smooth) {
+	const outline = section.points ?? roundedRect(section);
+	let ring = dedupe(section.points && smooth ? fitInto(catmullRom(outline), outline) : outline);
+	if (signedArea(ring) > 0) ring = ring.slice().reverse();
+	return resample(startAtFront(ring), RING_POINTS);
+}
+
+/** Fritsch-Carlson tangents: Catmull-Rom slopes, limited so each span stays
+ * monotone and the curve never passes its two end values. */
+function monotoneSlopes(ys, values) {
+	const n = ys.length;
+	const delta = values.slice(1).map((value, k) => (value - values[k]) / (ys[k + 1] - ys[k]));
+	const slopes = values.map((_, k) => (k === 0 ? delta[0] : k === n - 1 ? delta[n - 2] : delta[k - 1] * delta[k] <= 0 ? 0 : (delta[k - 1] + delta[k]) / 2));
+	delta.forEach((d, k) => {
+		if (d === 0) {
+			slopes[k] = 0;
+			slopes[k + 1] = 0;
+			return;
+		}
+		const a = slopes[k] / d, b = slopes[k + 1] / d, s = a * a + b * b;
+		if (s > 9) {
+			slopes[k] = (3 * a * d) / Math.sqrt(s);
+			slopes[k + 1] = (3 * b * d) / Math.sqrt(s);
+		}
+	});
+	return slopes;
+}
+
+function hermite(y0, y1, v0, v1, m0, m1, y) {
+	const h = y1 - y0, t = (y - y0) / h, t2 = t * t, t3 = t2 * t;
+	return (2 * t3 - 3 * t2 + 1) * v0 + (t3 - 2 * t2 + t) * h * m0 + (-2 * t3 + 3 * t2) * v1 + (t3 - t2) * h * m1;
+}
+
+/**
+ * The loft's rings, bottom to top, as [x, y, z] metres in the part's frame,
+ * plus `at`: the index of the ring each authored section became.
+ */
+export function loftRings(part) {
+	const [sx, sy, sz] = part.size;
+	const ys = part.sections.map((section) => section.y);
+	const sections = part.sections.map((section) => sectionRing(section, part.smooth));
+	const levels = [];
+	const at = [];
+	if (!part.smooth) {
+		sections.forEach((ring, k) => { at.push(levels.length); levels.push({ y: ys[k], ring }); });
+	} else {
+		const slopes = sections[0].map((_, j) => [0, 1].map((axis) => monotoneSlopes(ys, sections.map((ring) => ring[j][axis]))));
+		for (let k = 0; k < ys.length; k += 1) {
+			at.push(levels.length);
+			levels.push({ y: ys[k], ring: sections[k] });
+			if (k === ys.length - 1) break;
+			for (let s = 1; s < SPAN_STEPS; s += 1) {
+				const y = ys[k] + ((ys[k + 1] - ys[k]) * s) / SPAN_STEPS;
+				levels.push({ y, ring: sections[k].map((_, j) => [0, 1].map((axis) => hermite(ys[k], ys[k + 1], sections[k][j][axis], sections[k + 1][j][axis], slopes[j][axis][k], slopes[j][axis][k + 1], y))) });
+			}
+		}
+	}
+	const rings = levels.map(({ y, ring }) => ring.map(([x, z]) => [x * sx, (y - 0.5) * sy, z * sz]));
+	return { rings, at };
+}

package/src/sculpt-noise.js

@@ -0,0 +1,65 @@
+/**
+ * Seeded randomness for sculpt surfaces and scatters. The same recipe always
+ * draws the same lumps and the same blades (nothing here reads Math.random),
+ * and a mirrored copy is seeded by its source part's id, so it draws the
+ * source's pattern reflected instead of a new one. Pure: no three.js.
+ */
+
+import { SCULPT_MIRROR_SUFFIX } from "./sculpt-recipe.js";
+
+/** Whether a drawn part is the reflected copy of a `mirror: true` part. */
+export const isMirrorCopy = (part) => part.id.endsWith(SCULPT_MIRROR_SUFFIX);
+
+function mix(value) {
+	let h = Math.imul(value ^ (value >>> 16), 0x7feb352d);
+	h = Math.imul(h ^ (h >>> 15), 0x846ca68b);
+	return (h ^ (h >>> 16)) >>> 0;
+}
+
+/** A 32-bit seed from the part's source id (FNV-1a) and a recipe seed. */
+export function partSeed(part, seed) {
+	const id = isMirrorCopy(part) ? part.id.slice(0, -SCULPT_MIRROR_SUFFIX.length) : part.id;
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < id.length; i += 1) hash = Math.imul(hash ^ id.charCodeAt(i), 0x01000193);
+	return mix(hash ^ Math.imul(seed + 1, 0x9e3779b1));
+}
+
+/** mulberry32: a uniform [0, 1) stream from a 32-bit seed. */
+export function seededRandom(seed) {
+	let state = seed >>> 0;
+	return () => {
+		state = (state + 0x6d2b79f5) >>> 0;
+		let t = Math.imul(state ^ (state >>> 15), state | 1);
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+	};
+}
+
+const GRADIENTS = [1, 1, 0, -1, 1, 0, 1, -1, 0, -1, -1, 0, 1, 0, 1, -1, 0, 1, 1, 0, -1, -1, 0, -1, 0, 1, 1, 0, -1, 1, 0, 1, -1, 0, -1, -1];
+const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+const lerp = (a, b, t) => a + (b - a) * t;
+
+/** Gradient (Perlin) noise, about −1..1, zero on the integer lattice. */
+function noise3(x, y, z, seed) {
+	const ix = Math.floor(x), iy = Math.floor(y), iz = Math.floor(z);
+	const fx = x - ix, fy = y - iy, fz = z - iz;
+	const corner = (dx, dy, dz) => {
+		const g = (mix(Math.imul(ix + dx, 0x8da6b343) ^ Math.imul(iy + dy, 0xd8163841) ^ Math.imul(iz + dz, 0xcb1ab31f) ^ seed) % 12) * 3;
+		return GRADIENTS[g] * (fx - dx) + GRADIENTS[g + 1] * (fy - dy) + GRADIENTS[g + 2] * (fz - dz);
+	};
+	const u = fade(fx), v = fade(fy), w = fade(fz);
+	return lerp(
+		lerp(lerp(corner(0, 0, 0), corner(1, 0, 0), u), lerp(corner(0, 1, 0), corner(1, 1, 0), u), v),
+		lerp(lerp(corner(0, 0, 1), corner(1, 0, 1), u), lerp(corner(0, 1, 1), corner(1, 1, 1), u), v),
+		w,
+	);
+}
+
+/** Four octaves of noise3: broad lumps with smaller lumps on them, about −1..1. */
+export function fbm3(x, y, z, seed) {
+	let sum = 0;
+	for (let octave = 0, amplitude = 1, frequency = 1; octave < 4; octave += 1, amplitude /= 2, frequency *= 2) {
+		sum += amplitude * noise3(x * frequency, y * frequency, z * frequency, seed + octave);
+	}
+	return sum / 1.875;
+}

package/src/sculpt-part-fields.js

@@ -0,0 +1,27 @@
+/**
+ * Optional sculpt part fields that any shape takes (its look, its surface
+ * detail). Each entry is { key, read(raw, part, where) }: `read` runs only
+ * when raw[key] is present, refuses a bad value with RecipeError
+ * (sculpt-recipe-read.js) and writes the normalized value onto the part.
+ * An edit that sets a field to null clears it. Pure: no three.js.
+ */
+import { SCULPT_OP_FIELD } from "./sculpt-cutters.js";
+import { SURFACE_FIELDS } from "./sculpt-surface-fields.js";
+import { RecipeError } from "./sculpt-recipe-read.js";
+import { MATERIAL_FINISHES, MATERIAL_PRESETS } from "./material-presets.js";
+
+/** A name from `names`; null clears the field (back to the default look),
+ * which is how an edit `{ set: id, material: null }` undoes a preset. */
+const readName = (key, names) => (raw, part, where) => {
+	if (raw[key] === null) return;
+	if (!names.includes(raw[key])) throw new RecipeError(`${where}.${key}`, `must be one of ${names.join(", ")}; got ${JSON.stringify(raw[key])}`);
+	part[key] = raw[key];
+};
+
+export const SCULPT_PART_FIELDS = Object.freeze([
+	// Surface presets (material-presets.js); color stays the tint.
+	{ key: "material", read: readName("material", MATERIAL_PRESETS) },
+	{ key: "finish", read: readName("finish", MATERIAL_FINISHES) },
+	...SURFACE_FIELDS,
+	SCULPT_OP_FIELD,
+]);