cozyclay 3.0.3 → 3.1.1

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,
+]);

package/src/sculpt-recipe-read.js

@@ -0,0 +1,65 @@
+/**
+ * Readers shared by the sculpt recipe modules (sculpt-recipe.js, sculpt-shapes.js,
+ * sculpt-part-fields.js). Each one refuses a bad value with the field's path
+ * instead of clamping it. Pure: no three.js.
+ */
+
+export const tidy = (value) => {
+	const rounded = Math.round(value * 1e4) / 1e4;
+	return rounded === 0 ? 0 : rounded;
+};
+export const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+
+export class RecipeError extends Error {
+	constructor(path, message) {
+		super(`${path}: ${message}`);
+		this.path = path;
+	}
+}
+
+export function readVector(value, path, fallback, check) {
+	if (value === undefined && fallback) return [...fallback];
+	if (!Array.isArray(value) || value.length !== 3 || !value.every(isFiniteNumber)) {
+		throw new RecipeError(path, `must be three numbers [x, y, z], got ${JSON.stringify(value)}`);
+	}
+	value.forEach((component, axis) => check(component, `${path}[${axis}]`));
+	return value.map(tidy);
+}
+
+export function readUnit(value, path, fallback, min, max) {
+	if (value === undefined) return fallback;
+	if (!isFiniteNumber(value) || value < min || value > max) {
+		throw new RecipeError(path, `must be a number from ${min} to ${max}, got ${JSON.stringify(value)}`);
+	}
+	return tidy(value);
+}
+
+export function readInteger(value, path, fallback, min, max) {
+	if (value === undefined && fallback !== undefined) return fallback;
+	if (!Number.isInteger(value) || value < min || value > max) {
+		throw new RecipeError(path, `must be a whole number from ${min} to ${max}, got ${JSON.stringify(value)}`);
+	}
+	return value;
+}
+
+/** A pattern seed (detail bumps, scatter layout): 0 unless the recipe picks another. */
+export const readSeed = (value, path) => readInteger(value, path, 0, 0, 999999);
+
+export function readChoice(value, path, fallback, choices) {
+	if (value === undefined && fallback !== undefined) return fallback;
+	if (!choices.includes(value)) throw new RecipeError(path, `must be one of ${choices.join(", ")}; got ${JSON.stringify(value)}`);
+	return value;
+}
+
+const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
+const HEX_LONG = /^#?([0-9a-f]{6})$/i;
+
+/** `#rgb` or `#rrggbb` (the `#` optional), as lower-case `#rrggbb`. */
+export function readHexColor(value, path) {
+	const text = typeof value === "string" ? value.trim() : "";
+	const short = HEX_SHORT.exec(text);
+	if (short) return `#${short[1].toLowerCase().replace(/./g, (digit) => digit + digit)}`;
+	const long = HEX_LONG.exec(text);
+	if (long) return `#${long[1].toLowerCase()}`;
+	throw new RecipeError(path, `colour must be #rgb or #rrggbb, got ${JSON.stringify(value)}`);
+}

package/src/sculpt-recipe.js

@@ -15,8 +15,12 @@
  * Contract: docs/sculpt-from-image.md.
  */
 
+import { RecipeError, readHexColor, readVector, tidy } from "./sculpt-recipe-read.js";
+import { SCULPT_SHAPES, SCULPT_SHAPE_KEYS, SCULPT_SHAPE_SPECS } from "./sculpt-shapes.js";
+import { SCULPT_PART_FIELDS } from "./sculpt-part-fields.js";
+import { checkSculptCutters } from "./sculpt-cutters.js";
+
 const SCULPT_RECIPE_VERSION = 1;
-const SCULPT_SHAPES = Object.freeze(["blob", "box", "cylinder", "torus", "frame"]);
 export const SCULPT_LIMITS = Object.freeze({
 	/** after mirrors are expanded */
 	maxParts: 48,
@@ -24,6 +28,8 @@ export const SCULPT_LIMITS = Object.freeze({
 	maxExtent: 20,
 	maxOffset: 20,
 	maxDepth: 8,
+	/** scatter items across the whole recipe, after mirrors */
+	maxScatterItems: 12000,
 });
 const SCULPT_DEFAULT_COLOR = "#c2c6c8";
 /** The suffix a mirrored copy's id gets. `.` is outside the id alphabet, so a
@@ -32,61 +38,13 @@ export const SCULPT_MIRROR_SUFFIX = ".mirror";
 const MIN_HEIGHT = 0.05;
 
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
-const HEX_LONG = /^#?([0-9a-f]{6})$/i;
-const PART_KEYS = new Set(["id", "shape", "size", "position", "rotation", "color", "parent", "mirror", "roundness", "taper", "border"]);
-const SHAPE_KEYS = {
-	blob: new Set(["roundness", "taper"]),
-	box: new Set(["roundness"]),
-	cylinder: new Set(["taper"]),
-	torus: new Set(),
-	frame: new Set(["border"]),
-};
-const DEFAULT_ROUNDNESS = { blob: 0.5, box: 0.1 };
-
-const tidy = (value) => {
-	const rounded = Math.round(value * 1e4) / 1e4;
-	return rounded === 0 ? 0 : rounded;
-};
-const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const PART_KEYS = new Set(["id", "shape", "size", "position", "rotation", "color", "parent", "mirror", ...SCULPT_SHAPE_KEYS, ...SCULPT_PART_FIELDS.map((field) => field.key)]);
 const wrapDegrees = (deg) => {
 	const wrapped = ((((deg + 180) % 360) + 360) % 360) - 180;
 	return wrapped === -180 ? 180 : wrapped;
 };
 
-class RecipeError extends Error {
-	constructor(path, message) {
-		super(`${path}: ${message}`);
-		this.path = path;
-	}
-}
-
-function readColor(value, path) {
-	if (value === undefined) return SCULPT_DEFAULT_COLOR;
-	const text = typeof value === "string" ? value.trim() : "";
-	const short = HEX_SHORT.exec(text);
-	if (short) return `#${short[1].toLowerCase().replace(/./g, (digit) => digit + digit)}`;
-	const long = HEX_LONG.exec(text);
-	if (long) return `#${long[1].toLowerCase()}`;
-	throw new RecipeError(path, `colour must be #rgb or #rrggbb, got ${JSON.stringify(value)}`);
-}
-
-function readVector(value, path, fallback, check) {
-	if (value === undefined && fallback) return [...fallback];
-	if (!Array.isArray(value) || value.length !== 3 || !value.every(isFiniteNumber)) {
-		throw new RecipeError(path, `must be three numbers [x, y, z], got ${JSON.stringify(value)}`);
-	}
-	value.forEach((component, axis) => check(component, `${path}[${axis}]`));
-	return value.map(tidy);
-}
-
-function readUnit(value, path, fallback, min, max) {
-	if (value === undefined) return fallback;
-	if (!isFiniteNumber(value) || value < min || value > max) {
-		throw new RecipeError(path, `must be a number from ${min} to ${max}, got ${JSON.stringify(value)}`);
-	}
-	return tidy(value);
-}
+const readColor = (value, path) => (value === undefined ? SCULPT_DEFAULT_COLOR : readHexColor(value, path));
 
 function normalizePart(raw, index) {
 	const at = `parts[${index}]`;
@@ -101,8 +59,9 @@ function normalizePart(raw, index) {
 	if (!SCULPT_SHAPES.includes(raw.shape)) {
 		throw new RecipeError(`${where}.shape`, `must be one of ${SCULPT_SHAPES.join(", ")}; got ${JSON.stringify(raw.shape)}`);
 	}
-	for (const key of ["roundness", "taper", "border"]) {
-		if (raw[key] !== undefined && !SHAPE_KEYS[raw.shape].has(key)) {
+	const spec = SCULPT_SHAPE_SPECS[raw.shape];
+	for (const key of SCULPT_SHAPE_KEYS) {
+		if (raw[key] !== undefined && !spec.keys.includes(key)) {
 			throw new RecipeError(`${where}.${key}`, `does not apply to a ${raw.shape}`);
 		}
 	}
@@ -129,20 +88,8 @@ function normalizePart(raw, index) {
 	};
 	if (raw.parent !== undefined) part.parent = raw.parent;
 	if (raw.mirror === true) part.mirror = true;
-	if (SHAPE_KEYS[raw.shape].has("roundness")) part.roundness = readUnit(raw.roundness, `${where}.roundness`, DEFAULT_ROUNDNESS[raw.shape], 0, 1);
-	if (SHAPE_KEYS[raw.shape].has("taper")) part.taper = readUnit(raw.taper, `${where}.taper`, 0, -1, 1);
-	if (raw.shape === "frame") {
-		const limit = Math.min(size[0], size[1]) / 2;
-		const fallback = tidy(Math.min(size[0], size[1]) * 0.15);
-		const border = raw.border === undefined ? fallback : raw.border;
-		if (!isFiniteNumber(border) || border <= 0 || border >= limit) {
-			throw new RecipeError(`${where}.border`, `must be above 0 and below half the frame's smaller side (${tidy(limit)} m), got ${JSON.stringify(raw.border)}`);
-		}
-		part.border = tidy(border);
-	}
-	if (raw.shape === "torus" && size[2] >= Math.min(size[0], size[1])) {
-		throw new RecipeError(`${where}.size`, "a torus's tube (size[2]) must be thinner than its outer diameter");
-	}
+	spec.read(raw, part, where);
+	for (const field of SCULPT_PART_FIELDS) if (raw[field.key] !== undefined) field.read(raw, part, where);
 	return part;
 }
 
@@ -196,10 +143,16 @@ export function normalizeSculptRecipe(input) {
 			seen.add(part.id);
 		}
 		partDepths(parts);
+		checkSculptCutters(parts);
 		const recipe = { version: SCULPT_RECIPE_VERSION, parts };
-		const count = expandSculptParts(recipe).length;
-		if (count > SCULPT_LIMITS.maxParts) {
-			throw new RecipeError("recipe.parts", `expands to ${count} parts with mirrors; the limit is ${SCULPT_LIMITS.maxParts}`);
+		const drawn = expandSculptParts(recipe);
+		if (drawn.length > SCULPT_LIMITS.maxParts) {
+			throw new RecipeError("recipe.parts", `expands to ${drawn.length} parts with mirrors; the limit is ${SCULPT_LIMITS.maxParts}`);
+		}
+		// A scatter is one part but many drawn items; the frame rate pays per item.
+		const items = drawn.reduce((sum, part) => sum + (part.shape === "scatter" ? part.count : 0), 0);
+		if (items > SCULPT_LIMITS.maxScatterItems) {
+			throw new RecipeError("recipe.parts", `scatter parts draw ${items} items with mirrors; the limit is ${SCULPT_LIMITS.maxScatterItems}`);
 		}
 		return { ok: true, recipe };
 	} catch (error) {
@@ -210,8 +163,9 @@ export function normalizeSculptRecipe(input) {
 
 /**
  * A recipe edited part by part instead of rewritten. `edits` are applied in
- * order: `{ set: id, ...fields }` merges fields into one part (`parent: null`
- * and `mirror: false` clear), `{ add: part }` appends, `{ remove: id }` drops a
+ * order: `{ set: id, ...fields }` merges fields into one part (`parent: null`,
+ * `mirror: false` and null for an optional field such as `detail` clear),
+ * `{ add: part }` appends, `{ remove: id }` drops a
  * part and every part below it. The result is normalized as a whole, so an edit
  * that leaves the recipe undrawable is refused with the usual path.
  * Returns `{ ok: true, recipe, changed: [ids] }` or `{ ok: false, error, path }`.
@@ -249,8 +203,9 @@ export function patchSculptRecipe(recipe, edits) {
 		const next = { ...parts[found], ...fields };
 		if (fields.parent === null) delete next.parent;
 		if (fields.mirror === false) delete next.mirror;
+		for (const field of SCULPT_PART_FIELDS) if (fields[field.key] === null) delete next[field.key];
 		// Shape-specific defaults belong to the old shape, not the new one.
-		if ("shape" in fields) for (const key of ["roundness", "taper", "border"]) if (!(key in fields)) delete next[key];
+		if ("shape" in fields) for (const key of SCULPT_SHAPE_KEYS) if (!(key in fields)) delete next[key];
 		parts[found] = next;
 		changed.add(id);
 	}
@@ -298,7 +253,8 @@ function applyMatrix(m, [x, y, z]) {
 
 /** A reflection across x = 0 of the parent frame keeps the part's shape and
  * negates the lateral axis only: position.x flips, and the yaw and roll turn
- * the other way. All five shapes are symmetric about their own x, so no
+ * the other way. Shapes symmetric about their own x need nothing more; the
+ * others reflect their own data (SCULPT_SHAPE_SPECS[shape].mirror), so no
  * negative scale (and no winding flip) is needed. */
 function mirroredPart(part, parentId) {
 	const copy = {
@@ -308,6 +264,7 @@ function mirroredPart(part, parentId) {
 		rotation: [part.rotation[0], tidy(-part.rotation[1]), tidy(-part.rotation[2])],
 	};
 	delete copy.mirror;
+	SCULPT_SHAPE_SPECS[copy.shape].mirror?.(copy);
 	if (parentId !== undefined) copy.parent = parentId;
 	return copy;
 }
@@ -352,10 +309,11 @@ function localCorners(part) {
 	return corners;
 }
 
+/** A cutter (op) is not drawn and only takes from its parent, so it never widens the box. */
 export function sculptBounds(recipe) {
 	const min = [Infinity, Infinity, Infinity];
 	const max = [-Infinity, -Infinity, -Infinity];
-	for (const part of expandSculptParts(recipe)) {
+	for (const part of expandSculptParts(recipe).filter((drawn) => !drawn.op)) {
 		for (const corner of localCorners(part)) {
 			const point = applyMatrix(part.matrix, corner);
 			for (let axis = 0; axis < 3; axis += 1) {

package/src/sculpt-run.js

@@ -49,7 +49,7 @@ function dataUrlFromSheet(sheet) {
 const referenceArg = reference => (reference?.assetId ? { assetId: reference.assetId } : { dataUrl: reference?.dataUrl });
 
 // The recipe rules the agent needs to get object.sculpt right the first time (sculpt-recipe.js).
-const RECIPE_RULES = "Recipe: { \"version\": 1, \"parts\": [{ \"id\", \"shape\", \"size\": [x,y,z] metres, \"position\": [x,y,z] centre, \"rotation\": [x,y,z] degrees, \"color\": \"#rrggbb\", \"parent\"?, \"mirror\"?, \"roundness\"? 0-1, \"taper\"? }] }. id: lowercase a-z, 0-9 and -, starting with a letter or digit, at most 40 characters. shape is exactly one of blob, box, cylinder, torus, frame (no cone, sphere or other names). Up to 48 parts after mirrors. Floor is y=0 (feet touch it), front is +z, the subject's left is +x, mirror: true adds the reflection across x=0. roundness works backwards from its name: 0 is a smooth ellipsoid and 1 is a rounded box. roundness belongs only on blob and box, taper only on blob: leave both off cylinder, torus and frame. Keep roundness at 0.2 or below on every organic part (body, belly, head, face, limbs); go above 0.3 only for hard-edged objects. Use box only for hard-edged things.";
+const RECIPE_RULES = "Recipe: { \"version\": 1, \"parts\": [{ \"id\", \"shape\", \"size\": [x,y,z] metres, \"position\": [x,y,z] centre, \"rotation\": [x,y,z] degrees, \"color\": \"#rrggbb\", \"parent\"?, \"mirror\"?, \"roundness\"? 0-1, \"taper\"? }] }. id: lowercase a-z, 0-9 and -, starting with a letter or digit, at most 40 characters. shape is exactly one of blob, box, cylinder, torus, frame, lathe, tube, extrude, loft, convex, scatter (no cone, sphere or other names): lathe { \"profile\": [[r 0-1, y 0-1], ...] } for turned forms (pot, bottle, bowl), tube { \"path\": [[x,y,z] each -0.5..0.5 of size], \"thickness\" m } for ropes, tails, handles and limbs that bend, extrude { \"outline\": [[x,y] -0.5..0.5] } for flat cut shapes (ears, fins, leaves, signs), loft { \"sections\": [{ \"y\", \"w\", \"d\" }, ...] } for bodies whose cross-section changes, convex { \"seed\" } for rocks. Any part may add \"detail\": { \"amount\": 0-1 } for a lumpy surface, \"gradient\": { \"color\" } for a two-tone blend, or \"op\": \"subtract\" to cut its parent (a mouth, a hollow). Up to 48 parts after mirrors. Floor is y=0 (feet touch it), front is +z, the subject's left is +x, mirror: true adds the reflection across x=0. roundness works backwards from its name: 0 is a smooth ellipsoid and 1 is a rounded box. roundness belongs only on blob, box and extrude, taper only on blob, cylinder and tube: leave both off the other shapes. Keep roundness at 0.2 or below on every organic part (body, belly, head, face, limbs); go above 0.3 only for hard-edged objects. Use box only for hard-edged things.";
 
 // A compact score for the next turn: what is missing where, and which parts stick out.
 function reportText(report) {