cozyclay 3.0.3 → 3.1.1

package/src/retired-kinds.js

@@ -0,0 +1,37 @@
+// Object kinds an old project can carry that this build no longer ships.
+
+/**
+ * Kinds an earlier build shipped and this one does not (hand-built set
+ * pieces), with the standing size they had. They exist only so an old project
+ * still opens: each record becomes a plain cube with the same transform and
+ * the same size, so its blocking, collisions, route and children survive.
+ */
+const RETIRED_KINDS = Object.freeze({
+	chair: { width: 0.6, depth: 0.6, height: 1.15 },
+	car: { width: 1.8, depth: 4.5, height: 1.4 },
+	"small-plane": { width: 3.4, depth: 3.6, height: 1.4 },
+});
+
+/** A stored record of a retired kind as the cube that stands in for it; any
+ * other record is returned untouched. Scale absorbs the retired footprint, the
+ * same single-`scale` fallback normalizeSceneObject reads applies first. */
+export function retireObjectKind(record) {
+	const size = record && typeof record === "object" ? RETIRED_KINDS[record.renderer] : undefined;
+	if (!size) return record;
+	const single = record.scaleX === undefined && record.scaleY === undefined && record.scaleZ === undefined ? Number(record.scale) : NaN;
+	const axis = (value) => {
+		const n = value === undefined ? (Number.isFinite(single) ? single : 1) : Number(value);
+		return Number.isFinite(n) ? n : 1;
+	};
+	const { scale: _scale, ...rest } = record;
+	return {
+		...rest,
+		renderer: "cube",
+		scaleX: axis(record.scaleX) * size.width,
+		scaleY: axis(record.scaleY) * size.height,
+		scaleZ: axis(record.scaleZ) * size.depth,
+		footprint: { width: 1, depth: 1 },
+		height: 1,
+		supportY: 1,
+	};
+}

package/src/scene-objects.js

@@ -24,10 +24,11 @@ import { MESH_DEFAULT_HEIGHT, MESH_HEIGHT_MIN } from "./scene-mesh.js";
 import { normalizeSculptRecipe, sculptStandingBox } from "./sculpt-recipe.js";
 import { GREY_BOX } from "./object-colors.js";
 import { isEffectivelyHidden } from "./object-hidden.js";
+import { retireObjectKind } from "./retired-kinds.js";
 import { objectSize } from "./object-size.js";
 import { EFFECT_ENTRY, effectFields } from "./effects/effect-record.js";
 import { TEXT_ENTRY, TEXT_KIND, textFields, textPatch } from "./text/text-record.js";
-import { LIGHT_KIND, LIGHT_MENU_ENTRIES, lightLibraryEntry, objectLookFields, objectLookPatch, objectGraspFields, objectGraspPatch } from "./object-look.js";
+import { LIGHT_KIND, LIGHT_MENU_ENTRIES, lightLibraryEntry, objectLookFields, objectLookPatch, objectGraspFields, objectGraspPatch, objectMaterialKeys } from "./object-look.js";
 export { OBJECT_COLORS, normalizeObjectColor, rememberObjectColor, readStoredObjectColors, writeStoredObjectColors } from "./object-colors.js";
 export { isEffectivelyHidden };
 
@@ -65,8 +66,7 @@ const snapTo = (value, step) => Number((step > 0 ? Math.round(value / step) * st
  * object stands (used for the selection box and the gizmo's height).
  *
  * Primitives are grey-box grey on purpose: a blockout stands in for something
- * else, and a tinted maquette reads as a finished prop. The hand-built set
- * pieces keep their clay colours because they ARE the thing they depict.
+ * else, and a tinted maquette reads as a finished prop.
  */
 export const OBJECT_LIBRARY = [
 	{ kind: "cube", label: "Cube", group: "Primitives", footprint: { width: 1, depth: 1 }, height: 1, color: GREY_BOX },
@@ -75,11 +75,6 @@ export const OBJECT_LIBRARY = [
 	{ kind: "cylinder", label: "Cylinder", group: "Primitives", footprint: { width: 1, depth: 1 }, height: 1, color: GREY_BOX },
 	{ kind: "cone", label: "Cone", group: "Primitives", footprint: { width: 1, depth: 1 }, height: 1, color: GREY_BOX },
 	{ kind: "plane", label: "Plane", group: "Primitives", footprint: { width: 2, depth: 2 }, height: 0, color: GREY_BOX },
-	// supportY is the walkable surface, which can differ from the object's
-	// bounding height (a chair's back rises above its seat).
-	{ kind: "chair", label: "Chair", group: "Set pieces", footprint: { width: 0.6, depth: 0.6 }, height: 1.15, supportY: 0.495, color: "#b9855d" },
-	{ kind: "car", label: "Car", group: "Set pieces", footprint: { width: 1.8, depth: 4.5 }, height: 1.4, color: "#d98770" },
-	{ kind: "small-plane", label: "Plane (aircraft)", group: "Set pieces", footprint: { width: 3.4, depth: 3.6 }, height: 1.4, color: "#7896a4" },
 ];
 
 /**
@@ -552,7 +547,7 @@ const TRANSFORM_LIMITS = {
 /** The patch keys updateSceneObject reads for this object; any other key is
  * silently ignored there, so callers that must not be silent check against this. */
 export function objectPatchFields(object) {
-	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow", "grasp"];
+	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow", "grasp", ...objectMaterialKeys(object?.renderer)];
 	if (object?.renderer === LIGHT_KIND) fields.push("light");
 	if (object?.renderer === CUTOUT_KIND) fields.push("assetId", "sourceAssetId", "matteAssetId", "matteScale", "height", "aspect", "width", "stretch");
 	if (object?.renderer === MESH_KIND) fields.push("clay", "assetId", "height");
@@ -994,6 +989,7 @@ function objectOpacity(value) {
 
 export function normalizeSceneObject(record) {
 	if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+	record = retireObjectKind(record);
 	const entry = objectLibraryEntry(record.renderer);
 	if (!entry) return null;
 	if (typeof record.id !== "string" || !record.id) return null;

package/src/scenes.js

@@ -6,7 +6,7 @@ import { DEFAULT_SENSOR_FORMAT, SENSOR_FORMATS } from "./shot.js";
 import { normalizeStableItems } from "./stable-items.js";
 
 import { elementByPath } from "./studio-elements.js";
-import { wrapAngle } from "./scene-objects.js";
+import { wrapAngle } from "./scene-objects.js"; import { retireObjectKind } from "./retired-kinds.js";
 import { normalizeTakeSource } from "./domains/motion/take-source.js";
 import { createKeyLight, normalizeLighting } from "./stage-lighting.js";
 // The timeline clock lives in timeline-fps.js (three-free, so the agent
@@ -115,8 +115,6 @@ export function normalizeReferenceImage(value) {
 
 /** Stature band for a cast member: the gizmo's scale handles are a deliberate
  * artistic ask, and a previs giant or child is legitimate. */
-export const CHARACTER_SCALE_MIN = CHARACTER_SCALE_LIMITS.min;
-export const CHARACTER_SCALE_MAX = CHARACTER_SCALE_LIMITS.max;
 const clampScale = (value) => (Number.isFinite(value) && value > 0
 	? Math.max(CHARACTER_SCALE_LIMITS.min, Math.min(CHARACTER_SCALE_LIMITS.max, value))
 	: 1);
@@ -373,7 +371,8 @@ function repairScene(record, existing, fallbackNumber, fallbackStage, legacyCloc
 	return {
 		id: record.id,
 		name: uniqueName(typeof record.name === "string" ? record.name : `SCENE ${String(fallbackNumber).padStart(2, "0")}`, existing),
-		objects: record.objects.filter(plainObject).map((object) => cloneValue(object)),
+		// A kind this build no longer ships opens as the cube that stands in for it.
+		objects: record.objects.filter(plainObject).map((object) => retireObjectKind(cloneValue(object))),
 		// The shot document is a sealed envelope with its OWN version, and it
 		// migrates its own frames when its reader opens it.
 		shotDocument: cloneValue(record.shotDocument ?? null),
@@ -412,7 +411,7 @@ export function readSceneDocument(raw, legacyRaw = null) {
 				return { status: "corrupt", document: createSceneDocument(), dropped: 0, quarantineRaw: legacyRaw };
 			}
 			const document = createSceneDocument();
-			document.scenes[0].objects = legacy.objects.filter(plainObject).map((object) => cloneValue(object));
+			document.scenes[0].objects = legacy.objects.filter(plainObject).map((object) => retireObjectKind(cloneValue(object)));
 			return { status: "migrated", document, dropped: legacy.objects.length - document.scenes[0].objects.length };
 		}
 		return { status: "absent", document: createSceneDocument(), dropped: 0 };

package/src/sculpt-colours.js

@@ -0,0 +1,65 @@
+/**
+ * Sculpt colours for the shaded look, applied once per part by
+ * buildSculptGroup after the part's material exists:
+ *
+ * - a `gradient` (sculpt-surface-fields.js) becomes a per-vertex `color`
+ *   attribute blending the part's colour into the gradient's;
+ * - a scatter's items each get a small seeded hue and brightness jitter (and
+ *   the gradient, by where the item sits), so a field is not one flat swatch.
+ *
+ * The colour then lives in the vertex or instance colours, so the material's
+ * own colour goes white and `vertexColors` turns on (a texture map still
+ * multiplies in). A flat display mode (auto-colour, through materialFor)
+ * skips this, so it ignores gradients and jitter.
+ */
+
+import * as THREE from "three";
+import { isMirrorCopy, partSeed, seededRandom } from "./sculpt-noise.js";
+
+const AXES = { x: 0, y: 1, z: 2 };
+/** Item-to-item spread: hue ± this (of the wheel), brightness × 1 ± this. */
+const JITTER_HUE = 0.025;
+const JITTER_SHADE = 0.16;
+
+/** How far a local point is along the gradient: 0 at `from` (part colour), 1 at `to`. */
+function blend(part, x, y, z) {
+	const { axis, from, to } = part.gradient;
+	const i = AXES[axis];
+	// A mirrored copy reads its x reversed, so an x gradient reflects with the part.
+	const along = [isMirrorCopy(part) ? -x : x, y, z][i] / part.size[i] + 0.5;
+	if (to === from) return along >= to ? 1 : 0;
+	return THREE.MathUtils.clamp((along - from) / (to - from), 0, 1);
+}
+
+export function applySculptColours(mesh, part) {
+	if (!part.gradient && !mesh.isInstancedMesh) return;
+	const base = new THREE.Color(part.color);
+	const end = part.gradient ? new THREE.Color(part.gradient.color) : null;
+	const colour = new THREE.Color();
+	if (mesh.isInstancedMesh) {
+		const random = seededRandom(partSeed(part, part.seed + 1));
+		const matrix = new THREE.Matrix4(), at = new THREE.Vector3();
+		for (let i = 0; i < mesh.count; i += 1) {
+			colour.copy(base);
+			if (end) {
+				at.setFromMatrixPosition(mesh.getMatrixAt(i, matrix));
+				colour.lerp(end, blend(part, at.x, at.y, at.z));
+			}
+			colour.offsetHSL((random() * 2 - 1) * JITTER_HUE, 0, 0).multiplyScalar(1 + (random() * 2 - 1) * JITTER_SHADE);
+			mesh.setColorAt(i, colour);
+		}
+		mesh.instanceColor.needsUpdate = true;
+	} else {
+		const position = mesh.geometry.getAttribute("position");
+		const colours = new Float32Array(position.count * 3);
+		for (let i = 0; i < position.count; i += 1) {
+			colour.copy(base).lerp(end, blend(part, position.getX(i), position.getY(i), position.getZ(i))).toArray(colours, 3 * i);
+		}
+		mesh.geometry.setAttribute("color", new THREE.BufferAttribute(colours, 3));
+	}
+	for (const material of [mesh.material].flat()) {
+		material.color?.set(0xffffff);
+		material.vertexColors = !!mesh.geometry.getAttribute("color");
+		material.needsUpdate = true;
+	}
+}

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