cozyclay 3.1.0 → 3.1.1

package/src/props.jsx

@@ -19,6 +19,7 @@ import { CUTOUT_KIND, MESH_KIND, EMPTY_KIND, EMPTY_MARKER_SIZE, SCULPT_KIND } fr
 import { TEXT_KIND } from "./text/text-record.js";
 import { TextObject } from "./text/text-object.jsx";
 import { buildSculptGroup, disposeSculptGroup } from "./sculpt-geometry.js";
+import { depthRankProps, usePrimitiveLook } from "./primitive-look.js";
 import { subscribeToAssetTexture } from "./scene-asset-cache.js";
 import { ImportedMesh } from "./imported-mesh.jsx";
 import { EffectMarker, EffectsLayer } from "./effects/EffectsLayer.jsx";
@@ -30,29 +31,23 @@ import { LIGHT_KIND, capPracticalShadows } from "./object-look.js";
 import { SceneLight, useLookRefresh } from "./scene-lights.jsx";
 import { placeObjectLook } from "./scene-light-place.js";
 
-// Parts of an assembly can share a plane with an earlier part (hood top and
-// grille top). The depth test can't order them and the winner flips as the
-// camera moves, so a ranked part is pulled toward the camera by `rank` steps
-// (negative = nearer). Rank 0 gets nothing: those materials stay untouched.
-function depthRankProps(rank) {
-	return rank > 0 ? { polygonOffset: true, polygonOffsetFactor: -rank, polygonOffsetUnits: -rank } : null;
-}
-
 /**
  * The creatable primitives, Unity's 3D Object menu in clay. Each one is built
  * with its base on the local floor (y = 0), so an object's `y` reads as height
- * above the deck rather than "half of me is underground".
+ * above the deck rather than "half of me is underground". A surface preset
+ * (primitive-look.js) replaces the clay; glass casts no shadow.
  */
-function Primitive({ kind, color, autoColor, depthRank = 0 }) {
+function Primitive({ kind, object, color, autoColor, depthRank = 0 }) {
 	const side = kind === "plane" ? THREE.DoubleSide : THREE.FrontSide;
-	const material = autoColor ? (
+	const look = usePrimitiveLook(object, kind, side, depthRank), cast = !(look?.transmission > 0);
+	const material = look ? <primitive object={look} attach="material" /> : autoColor ? (
 		<meshStandardMaterial {...autoFlat(autoColor)} side={side} {...depthRankProps(depthRank)} />
 	) : (
 		<meshStandardMaterial color={color} roughness={0.82} side={side} {...depthRankProps(depthRank)} />
 	);
 	if (kind === "sphere") {
 		return (
-			<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 				<sphereGeometry args={[0.5, 28, 18]} />
 				{material}
 			</mesh>
@@ -60,7 +55,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	}
 	if (kind === "capsule") {
 		return (
-			<mesh position={[0, 0.7, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.7, 0]} castShadow={cast} receiveShadow>
 				<capsuleGeometry args={[0.35, 0.7, 6, 18]} />
 				{material}
 			</mesh>
@@ -68,7 +63,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	}
 	if (kind === "cylinder") {
 		return (
-			<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 				<cylinderGeometry args={[0.5, 0.5, 1, 26]} />
 				{material}
 			</mesh>
@@ -76,7 +71,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	}
 	if (kind === "cone") {
 		return (
-			<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 				<coneGeometry args={[0.5, 1, 26]} />
 				{material}
 			</mesh>
@@ -91,7 +86,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 		);
 	}
 	return (
-		<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+		<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 			<boxGeometry args={[1, 1, 1]} />
 			{material}
 		</mesh>
@@ -162,20 +157,17 @@ function Cutout({ object }) {
 
 /**
  * A sculpt: the clay parts its recipe describes, rebuilt only when the recipe
- * or the look changes. Each part keeps its own clay colour; auto-colour paints
- * the whole sculpt flat like any other prop, because it is one object.
+ * or the look changes. The shaded look is buildSculptGroup's own clay (part
+ * colours, gradients, scatter tints); auto-colour paints the whole sculpt flat
+ * like any other prop, because it is one object. Depth rank rides on either.
  */
 function Sculpt({ object, depthRank = 0 }) {
 	const { recipe, autoColor } = object;
-	const group = useMemo(
-		() => buildSculptGroup(recipe, {
-			materialFor: (part) => new THREE.MeshStandardMaterial({
-				...(autoColor ? autoFlat(autoColor) : { color: part.color, roughness: 0.82, metalness: 0 }),
-				...depthRankProps(depthRank),
-			}),
-		}),
-		[recipe, autoColor, depthRank],
-	);
+	const group = useMemo(() => {
+		const built = buildSculptGroup(recipe, autoColor ? { materialFor: () => new THREE.MeshStandardMaterial(autoFlat(autoColor)) } : {});
+		built.traverse((node) => node.material && Object.assign(node.material, depthRankProps(depthRank)));
+		return built;
+	}, [recipe, autoColor, depthRank]);
 	useEffect(() => () => disposeSculptGroup(group), [group]);
 	return <primitive object={group} />;
 }
@@ -242,7 +234,7 @@ function SceneObjectContent({ object, depthRank = 0 }) {
 	if (renderer === MESH_KIND) return <ImportedMesh object={object} />;
 	if (renderer === SCULPT_KIND) return <Sculpt object={object} depthRank={depthRank} />;
 	if (renderer === TEXT_KIND) return <TextObject object={object} />;
-	if (PRIMITIVE_KINDS.has(renderer)) return <Primitive kind={renderer} color={color} autoColor={autoColor} depthRank={depthRank} />;
+	if (PRIMITIVE_KINDS.has(renderer)) return <Primitive kind={renderer} object={object} color={color} autoColor={autoColor} depthRank={depthRank} />;
 	return null;
 }
 

package/src/render-passes.js

@@ -47,10 +47,16 @@ export function passFileName(kind) {
 // it spreads the value over four channels and reads as colour noise). This
 // shader is the plain depth-to-grey the deliverable wants, and the range it
 // normalises over is the stage's, not the projection's.
+// An InstancedMesh (a sculpt's scatter) draws every instance through its
+// instanceMatrix; without it all of them would land on the mesh's origin.
 const DEPTH_VERTEX = /* glsl */ `
 varying float vViewDepth;
 void main() {
-	vec4 viewPosition = modelViewMatrix * vec4(position, 1.0);
+	vec4 local = vec4(position, 1.0);
+#ifdef USE_INSTANCING
+	local = instanceMatrix * local;
+#endif
+	vec4 viewPosition = modelViewMatrix * local;
 	vViewDepth = -viewPosition.z;
 	gl_Position = projectionMatrix * viewPosition;
 }

package/src/scene-objects.js

@@ -28,7 +28,7 @@ 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 };
 
@@ -547,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");

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