cozyclay 3.1.0 → 3.1.2

package/src/sculpt-shapes-curved.js

@@ -0,0 +1,211 @@
+/**
+ * The sculpt shapes that follow points (SCULPT_SHAPE_SPECS entries, same
+ * contract as sculpt-shapes.js). Pure: no three.js.
+ *
+ *   lathe    profile [[r, y]] turned round the part's y axis: vase, pot, bottle
+ *   tube     a round tube swept along path [[x, y, z]]: rope, vine, frame tube
+ *   extrude  a flat outline [[x, y]] pushed through size z: sign, leaf, gable
+ *
+ * Every point is a fraction of the part's size, so `size` stays the box the
+ * record trusts: a tube's centreline is drawn in the box shrunk by its
+ * thickness, and the curves never overshoot their points (sculpt-curve.js).
+ */
+
+import { RecipeError, isFiniteNumber, readUnit, tidy } from "./sculpt-recipe-read.js";
+import { earClip, insideLoop, loopCrossing, monotoneCurve, signedArea } from "./sculpt-curve.js";
+
+/** The thinnest tube: the same floor as a part's extent (SCULPT_LIMITS.minExtent). */
+const MIN_THICKNESS = 0.005;
+const RING = 24;
+const half = (part) => part.size.map((value) => value / 2);
+
+function readFlag(value, path, fallback) {
+	if (value === undefined) return fallback;
+	if (typeof value !== "boolean") throw new RecipeError(path, `must be true or false, got ${JSON.stringify(value)}`);
+	return value;
+}
+
+/** A fresh list of points, each `label`-shaped with every component in [lo, hi]. */
+function readPoints(value, path, label, [min, max], [lo, hi]) {
+	if (!Array.isArray(value) || value.length < min || value.length > max) {
+		throw new RecipeError(path, `must be a list of ${min}-${max} points ${label}, got ${Array.isArray(value) ? `${value.length} points` : JSON.stringify(value)}`);
+	}
+	const dims = label.split(",").length;
+	return value.map((point, i) => {
+		if (!Array.isArray(point) || point.length !== dims || !point.every(isFiniteNumber)) {
+			throw new RecipeError(`${path}[${i}]`, `must be ${dims} numbers ${label}, got ${JSON.stringify(point)}`);
+		}
+		point.forEach((component, axis) => {
+			if (component < lo || component > hi) throw new RecipeError(`${path}[${i}][${axis}]`, `must be from ${lo} to ${hi}, got ${component}`);
+		});
+		return point.map(tidy);
+	});
+}
+
+/** An outline or hole: x and y as fractions of size, any winding, no repeated point. */
+function readLoop(value, path, counts) {
+	const loop = readPoints(value, path, "[x, y]", counts, [-0.5, 0.5]);
+	loop.forEach(([x, y], i) => {
+		const [px, py] = loop[(i + loop.length - 1) % loop.length];
+		if (x === px && y === py) throw new RecipeError(`${path}[${i}]`, i ? "repeats the point before it" : "repeats the last point; the loop closes by itself");
+	});
+	return loop;
+}
+
+/* ------------------------------------------------------------- lathe ---- */
+
+/** The drawn profile: [r fraction, y metres from the part's centre]. */
+export function latheRows(part, steps) {
+	const rows = part.smooth ? monotoneCurve(part.profile, steps) : part.profile;
+	return rows.map(([r, y]) => [r, (y - 0.5) * part.size[1]]);
+}
+
+/** Rings on the drawn profile, one hull per band, so a vase keeps its neck. */
+function latheSamples(part) {
+	const [hx, , hz] = half(part);
+	const rings = latheRows(part, Math.ceil(24 / (part.profile.length - 1))).map(([r, y]) => Array.from({ length: RING }, (_, j) => {
+		const angle = (j / RING) * 2 * Math.PI;
+		return [r * hx * Math.sin(angle), y, r * hz * Math.cos(angle)];
+	}));
+	return rings.slice(1).map((ring, k) => [...rings[k], ...ring]);
+}
+
+const lathe = {
+	keys: ["profile", "smooth"],
+	read(raw, part, where) {
+		const profile = readPoints(raw.profile, `${where}.profile`, "[r, y]", [3, 32], [0, 1]);
+		profile.forEach(([, y], i) => {
+			if (i && y < profile[i - 1][1]) throw new RecipeError(`${where}.profile[${i}][1]`, `y must not go down the profile (${y} after ${profile[i - 1][1]}); list it from bottom (0) to top (1)`);
+		});
+		if (profile.at(-1)[1] === profile[0][1]) throw new RecipeError(`${where}.profile`, "must climb: the last y must be above the first");
+		if (profile.every(([r]) => r === 0)) throw new RecipeError(`${where}.profile`, "has every r at 0, so nothing would be drawn");
+		part.profile = profile;
+		part.smooth = readFlag(raw.smooth, `${where}.smooth`, true);
+	},
+	samples: latheSamples,
+};
+
+/* -------------------------------------------------------------- tube ---- */
+
+/** The path's points in metres: the box shrunk by the thickness, so the round wall fits. */
+const tubeKnots = (part) => part.path.map((point) => point.map((value, axis) => value * (part.size[axis] - part.thickness)));
+
+export const tubeCentre = (part, steps) => monotoneCurve(tubeKnots(part), steps, part.closed);
+
+/** Radius at each centreline sample; taper runs by length, so uneven points taper evenly. */
+export function tubeRadii(part, centre) {
+	const radius = part.thickness / 2;
+	if (!part.taper) return centre.map(() => radius);
+	const run = [0];
+	for (let k = 1; k < centre.length; k += 1) run.push(run[k - 1] + Math.hypot(...centre[k].map((value, axis) => value - centre[k - 1][axis])));
+	return run.map((length) => {
+		const s = length / run.at(-1);
+		return radius * (1 - Math.max(0, part.taper) * s - Math.max(0, -part.taper) * (1 - s));
+	});
+}
+
+/** 26 unit directions (a cube's faces, edges and corners): a ball the hull can trace. */
+const BALL = [];
+for (const x of [-1, 0, 1]) for (const y of [-1, 0, 1]) for (const z of [-1, 0, 1]) {
+	const length = Math.hypot(x, y, z);
+	if (length) BALL.push([x / length, y / length, z / length]);
+}
+
+/** One hull per segment between path points, so a U-shaped rope stays open inside. */
+function tubeSamples(part) {
+	const steps = 4;
+	const centre = tubeCentre(part, steps);
+	const radii = tubeRadii(part, centre);
+	const segments = part.closed ? part.path.length : part.path.length - 1;
+	return Array.from({ length: segments }, (_, segment) => {
+		const points = [];
+		for (let i = segment * steps; i <= (segment + 1) * steps; i += 1) {
+			const k = i % centre.length;
+			for (const direction of BALL) points.push(centre[k].map((value, axis) => value + direction[axis] * radii[k]));
+		}
+		return points;
+	});
+}
+
+const tube = {
+	keys: ["path", "thickness", "taper", "closed"],
+	read(raw, part, where) {
+		part.path = readPoints(raw.path, `${where}.path`, "[x, y, z]", [2, 32], [-0.5, 0.5]);
+		const smallest = Math.min(...part.size);
+		if (!isFiniteNumber(raw.thickness) || raw.thickness < MIN_THICKNESS || raw.thickness > smallest) {
+			throw new RecipeError(`${where}.thickness`, `must be the tube's diameter in metres, from ${MIN_THICKNESS} to the part's smallest size (${tidy(smallest)} m), got ${JSON.stringify(raw.thickness)}`);
+		}
+		part.thickness = tidy(raw.thickness);
+		part.taper = readUnit(raw.taper, `${where}.taper`, 0, -1, 1);
+		part.closed = readFlag(raw.closed, `${where}.closed`, false);
+		if (part.closed && part.taper) throw new RecipeError(`${where}.taper`, "a closed tube cannot taper: its two ends meet");
+		if (part.closed && part.path.length < 3) throw new RecipeError(`${where}.path`, "a closed tube needs at least 3 points");
+		const knots = tubeKnots(part);
+		knots.forEach((point, i) => {
+			if (!i && !part.closed) return;
+			const before = knots[(i + knots.length - 1) % knots.length];
+			if (Math.hypot(...point.map((value, axis) => value - before[axis])) < 1e-6) {
+				throw new RecipeError(`${where}.path[${i}]`, i ? "sits on the point before it once fitted to the size" : "repeats the last point; a closed path joins its ends by itself");
+			}
+		});
+	},
+	mirror(copy) {
+		copy.path = copy.path.map(([x, y, z]) => [tidy(-x), y, z]);
+	},
+	samples: tubeSamples,
+};
+
+/* ----------------------------------------------------------- extrude ---- */
+
+/** One prism per ear-clipped triangle of the outline. The bevel is ignored. */
+function extrudeSamples(part) {
+	const [w, h, d] = part.size;
+	return earClip(part.outline).map((triangle) => triangle.flatMap((k) => {
+		const [x, y] = part.outline[k];
+		return [[x * w, y * h, d / 2], [x * w, y * h, -d / 2]];
+	}));
+}
+
+/** The compare cuts one opening: the largest hole, as its convex hull. */
+function extrudeHole(part) {
+	if (!part.holes) return null;
+	const largest = part.holes.reduce((best, hole) => (Math.abs(signedArea(hole)) > Math.abs(signedArea(best)) ? hole : best));
+	return largest.map(([x, y]) => [x * part.size[0], y * part.size[1], 0]);
+}
+
+const flipX = (loop) => loop.map(([x, y]) => [tidy(-x), y]);
+
+const extrude = {
+	keys: ["outline", "holes", "roundness"],
+	read(raw, part, where) {
+		part.outline = readLoop(raw.outline, `${where}.outline`, [3, 64]);
+		if (raw.holes !== undefined && (!Array.isArray(raw.holes) || raw.holes.length > 4)) {
+			throw new RecipeError(`${where}.holes`, `must be a list of at most 4 hole outlines, got ${JSON.stringify(raw.holes).slice(0, 60)}`);
+		}
+		const holes = (raw.holes ?? []).map((hole, i) => readLoop(hole, `${where}.holes[${i}]`, [3, 32]));
+		const names = [`${where}.outline`, ...holes.map((_, i) => `${where}.holes[${i}]`)];
+		const crossing = loopCrossing([part.outline, ...holes]);
+		if (crossing) {
+			const { a, b } = crossing;
+			const other = a.loop === b.loop ? "another of its edges" : `${names[b.loop]} (edge ${b.edge})`;
+			throw new RecipeError(names[a.loop], `edge ${a.edge} (point ${a.edge} to the next) touches or crosses ${other}; an outline must not cross itself or its holes`);
+		}
+		[part.outline, ...holes].forEach((loop, i) => {
+			if (Math.abs(signedArea(loop)) < 1e-5) throw new RecipeError(names[i], "encloses no area");
+		});
+		holes.forEach((hole, i) => {
+			if (!insideLoop(hole[0], part.outline)) throw new RecipeError(names[i + 1], "must lie inside the outline");
+			if (holes.some((other, j) => j !== i && insideLoop(hole[0], other))) throw new RecipeError(names[i + 1], "must not lie inside another hole");
+		});
+		if (holes.length) part.holes = holes;
+		part.roundness = readUnit(raw.roundness, `${where}.roundness`, 0.1, 0, 1);
+	},
+	mirror(copy) {
+		copy.outline = flipX(copy.outline);
+		if (copy.holes) copy.holes = copy.holes.map(flipX);
+	},
+	samples: extrudeSamples,
+	hole: extrudeHole,
+};
+
+export const CURVED_SHAPE_SPECS = Object.freeze({ lathe, tube, extrude });

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

@@ -0,0 +1,218 @@
+/**
+ * Recipe rules for the `loft` and `convex` sculpt shapes (the contract is the
+ * header of sculpt-shapes.js). Pure: no three.js.
+ *
+ * loft    a skin through 2-12 horizontal sections stacked up the part's own
+ *         y, for things whose section changes along their length: a boat
+ *         hull, a car body, a squared bottle, a loaf. Lay it on its side with
+ *         rotation for a hull or a car. Rings: sculpt-loft-rings.js.
+ * convex  the convex hull of 4-48 points, flat facets by default, for rocks,
+ *         gems and crystals; or `seed` alone for a random rock that fills its
+ *         size, so "a boulder" is one line.
+ *
+ * Every coordinate is a fraction of size (-0.5..0.5, loft y 0..1), so a part
+ * never draws outside its declared box and resizing never rewrites points.
+ */
+
+import { RecipeError, isFiniteNumber, readUnit, tidy } from "./sculpt-recipe-read.js";
+import { loftRings, signedArea } from "./sculpt-loft-rings.js";
+
+const LOFT_SECTIONS = [2, 12];
+const OUTLINE_POINTS = [3, 24];
+const CONVEX_POINTS = [4, 48];
+const FACET_COUNTS = [6, 40];
+const DEFAULT_FACETS = 16;
+const SECTION_ROUNDNESS = 0.25;
+/** A hull thinner than this (as a fraction of size) in any direction is flat. */
+const MIN_DEPTH = 0.02;
+const MAX_SEED = 2147483647;
+
+function readNumber(value, path, min, max) {
+	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);
+}
+
+function readBoolean(value, path, fallback) {
+	if (value === undefined) return fallback;
+	if (typeof value !== "boolean") throw new RecipeError(path, "must be true or false");
+	return value;
+}
+
+function readList(value, path, [min, max], what) {
+	if (!Array.isArray(value) || value.length < min || value.length > max) {
+		throw new RecipeError(path, `must be ${min}-${max} ${what}, got ${Array.isArray(value) ? value.length : JSON.stringify(value)}`);
+	}
+	return value;
+}
+
+function readPoint(value, path, axes) {
+	if (!Array.isArray(value) || value.length !== axes.length || !value.every(isFiniteNumber)) {
+		throw new RecipeError(path, `must be [${axes.join(", ")}] fractions of size, got ${JSON.stringify(value)}`);
+	}
+	return value.map((component, k) => readNumber(component, `${path}[${k}]`, -0.5, 0.5));
+}
+
+const cross2 = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+
+/** An outline that crosses itself has no inside to skin. */
+function crossingEdges(points) {
+	const n = points.length;
+	for (let i = 0; i < n; i += 1) {
+		for (let j = i + 2; j < n; j += 1) {
+			if (i === 0 && j === n - 1) continue;
+			const [a, b, c, d] = [points[i], points[(i + 1) % n], points[j], points[(j + 1) % n]];
+			if (cross2(a, b, c) * cross2(a, b, d) < 0 && cross2(c, d, a) * cross2(c, d, b) < 0) return [i, j];
+		}
+	}
+	return null;
+}
+
+function readSection(raw, path) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new RecipeError(path, "must be { y, points } or { y, w, d }");
+	const outline = raw.points !== undefined;
+	const allowed = outline ? ["y", "points"] : ["y", "w", "d", "x", "z", "roundness"];
+	for (const key of Object.keys(raw)) {
+		if (!allowed.includes(key)) throw new RecipeError(`${path}.${key}`, `unknown key (a section is { y, points } or { y, w, d, x, z, roundness })`);
+	}
+	const y = readNumber(raw.y, `${path}.y`, 0, 1);
+	if (outline) {
+		const points = readList(raw.points, `${path}.points`, OUTLINE_POINTS, "[x, z] points").map((point, i) => readPoint(point, `${path}.points[${i}]`, ["x", "z"]));
+		const crossing = crossingEdges(points);
+		if (crossing) throw new RecipeError(`${path}.points`, `edges ${crossing[0]} and ${crossing[1]} cross; list the outline in order around the section`);
+		if (Math.abs(signedArea(points)) < 1e-6) throw new RecipeError(`${path}.points`, "the outline encloses no area");
+		return { y, points };
+	}
+	const section = { y, w: readNumber(raw.w, `${path}.w`, 0.01, 1), d: readNumber(raw.d, `${path}.d`, 0.01, 1) };
+	for (const [key, span] of [["x", "w"], ["z", "d"]]) {
+		section[key] = readUnit(raw[key], `${path}.${key}`, 0, -0.5, 0.5);
+		if (Math.abs(section[key]) + section[span] / 2 > 0.5 + 1e-9) {
+			throw new RecipeError(`${path}.${key}`, `the section reaches past the part's side: |${key}| + ${span}/2 must be at most 0.5`);
+		}
+	}
+	section.roundness = readUnit(raw.roundness, `${path}.roundness`, SECTION_ROUNDNESS, 0, 1);
+	return section;
+}
+
+function readSections(value, where) {
+	const path = `${where}.sections`;
+	const sections = readList(value, path, LOFT_SECTIONS, "sections").map((section, k) => readSection(section, `${path}[${k}]`));
+	sections.forEach((section, k) => {
+		if (k > 0 && section.y <= sections[k - 1].y) throw new RecipeError(`${path}[${k}].y`, "must be above the section before it (sections run bottom to top)");
+	});
+	if (sections[0].y !== 0 || sections.at(-1).y !== 1) {
+		throw new RecipeError(path, "the first section must sit at y 0 and the last at y 1 (size[1] is the loft's full height)");
+	}
+	return sections;
+}
+
+/** Points [x, y, z] that span no volume would hull into a flat, broken mesh. */
+function hullDepth(points) {
+	const sub = (a, b) => a.map((value, k) => value - b[k]);
+	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 length = (a) => Math.hypot(...a);
+	const spread = (k) => Math.max(...points.map((p) => p[k])) - Math.min(...points.map((p) => p[k]));
+	const axis = [1, 2].reduce((best, k) => (spread(k) > spread(best) ? k : best), 0);
+	const a = points.reduce((best, p) => (p[axis] < best[axis] ? p : best));
+	const b = points.reduce((best, p) => (p[axis] > best[axis] ? p : best));
+	const line = sub(b, a);
+	const off = (p) => length(cross(line, sub(p, a))) / (length(line) || 1);
+	const c = points.reduce((best, p) => (off(p) > off(best) ? p : best));
+	const normal = cross(line, sub(c, a));
+	const plane = (p) => Math.abs(sub(p, a).reduce((sum, value, k) => sum + value * normal[k], 0)) / (length(normal) || 1);
+	return Math.min(length(line), off(c), Math.max(...points.map(plane)));
+}
+
+/** mulberry32: a small seeded PRNG, so a seed is the same rock everywhere. */
+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;
+	};
+}
+
+/**
+ * A rock of about `facetCount` triangles: a jittered Fibonacci sphere of
+ * facetCount / 2 + 2 points (a hull of n points on a sphere has 2n - 4
+ * triangles), tipped to a random pole, pulled in by up to 12%, then stretched
+ * per axis so it touches all six sides of its box: size is the rock's extent.
+ */
+function rockPoints(seed, facetCount) {
+	const random = seededRandom(seed);
+	const count = Math.floor(facetCount / 2) + 2;
+	const tilt = Math.acos(1 - 2 * random()), spin = 2 * Math.PI * random();
+	const golden = Math.PI * (3 - Math.sqrt(5));
+	const raw = [];
+	for (let i = 0; i < count; i += 1) {
+		const y = Math.max(-1, Math.min(1, 1 - (2 * (i + 0.5)) / count + (random() - 0.5) / count));
+		const angle = i * golden + (random() - 0.5) * golden * 0.5;
+		const ring = Math.sqrt(1 - y * y), radius = 0.88 + 0.12 * random();
+		const [x0, y0, z0] = [Math.cos(angle) * ring, y, Math.sin(angle) * ring];
+		const [y1, z1] = [y0 * Math.cos(tilt) - z0 * Math.sin(tilt), y0 * Math.sin(tilt) + z0 * Math.cos(tilt)];
+		raw.push([(x0 * Math.cos(spin) + z1 * Math.sin(spin)) * radius, y1 * radius, (z1 * Math.cos(spin) - x0 * Math.sin(spin)) * radius]);
+	}
+	const ranges = [0, 1, 2].map((k) => [Math.min(...raw.map((p) => p[k])), Math.max(...raw.map((p) => p[k]))]);
+	return raw.map((point) => point.map((value, k) => tidy((value - (ranges[k][0] + ranges[k][1]) / 2) / (ranges[k][1] - ranges[k][0]))));
+}
+
+const convexFractions = (part) => part.points ?? rockPoints(part.seed, part.facetCount);
+
+/** The hull's points in metres, in the part's frame. */
+export function convexPoints(part) {
+	return convexFractions(part).map((point) => point.map((value, k) => value * part.size[k]));
+}
+
+export const LOFT_CONVEX_SPECS = Object.freeze({
+	loft: {
+		keys: ["sections", "smooth"],
+		read(raw, part, where) {
+			part.sections = readSections(raw.sections, where);
+			part.smooth = readBoolean(raw.smooth, `${where}.smooth`, true);
+		},
+		// x flips, and an outline is listed backwards so it keeps its winding.
+		mirror(copy) {
+			copy.sections = copy.sections.map((section) => (section.points
+				? { y: section.y, points: section.points.map(([x, z]) => [tidy(-x), z]).reverse() }
+				: { ...section, x: tidy(-section.x) }));
+		},
+		// One hull per span, so a waist between two wide sections stays a waist.
+		samples(part) {
+			const { rings, at } = loftRings(part);
+			return at.slice(1).map((end, k) => rings.slice(at[k], end + 1).flat());
+		},
+	},
+	convex: {
+		keys: ["points", "seed", "facetCount", "facets"],
+		read(raw, part, where) {
+			// null reads as absent, so an edit can swap a seeded rock for points;
+			// seed: null also clears the facetCount that belonged to it.
+			const has = (key) => raw[key] !== undefined && raw[key] !== null;
+			if (has("points") === has("seed")) throw new RecipeError(`${where}.points`, "give either points: [[x, y, z]...] or seed (a random rock), not both");
+			if (has("points")) {
+				if (has("facetCount") && raw.seed !== null) throw new RecipeError(`${where}.facetCount`, "applies to a seeded rock; points already set the facets");
+				part.points = readList(raw.points, `${where}.points`, CONVEX_POINTS, "[x, y, z] points").map((point, i) => readPoint(point, `${where}.points[${i}]`, ["x", "y", "z"]));
+				if (hullDepth(part.points) < MIN_DEPTH) throw new RecipeError(`${where}.points`, "the points lie (nearly) on one line or plane; a hull needs depth in all three directions");
+			} else {
+				if (!Number.isInteger(raw.seed) || raw.seed < 0 || raw.seed > MAX_SEED) throw new RecipeError(`${where}.seed`, `must be a whole number from 0 to ${MAX_SEED}, got ${JSON.stringify(raw.seed)}`);
+				part.seed = raw.seed;
+				const facetCount = has("facetCount") ? raw.facetCount : DEFAULT_FACETS;
+				if (!Number.isInteger(facetCount) || facetCount < FACET_COUNTS[0] || facetCount > FACET_COUNTS[1]) {
+					throw new RecipeError(`${where}.facetCount`, `must be a whole number from ${FACET_COUNTS[0]} to ${FACET_COUNTS[1]}, got ${JSON.stringify(raw.facetCount)}`);
+				}
+				part.facetCount = facetCount;
+			}
+			part.facets = readBoolean(raw.facets, `${where}.facets`, true);
+		},
+		// A seeded rock is not symmetric either: its copy carries the reflected points.
+		mirror(copy) {
+			copy.points = convexFractions(copy).map(([x, y, z]) => [tidy(-x), y, z]);
+			delete copy.seed;
+			delete copy.facetCount;
+		},
+		samples: (part) => [convexPoints(part)],
+	},
+});

package/src/sculpt-shapes.js

@@ -0,0 +1,138 @@
+/**
+ * Per-shape rules for sculpt recipes: the keys a shape takes and how they are
+ * read, how a mirrored copy reflects the shape's own data, and the local
+ * points the silhouette compare hulls. Pure: no three.js.
+ *
+ * A new shape is one entry here plus a builder in sculpt-geometry.js (a
+ * geometry builder, or a mesh builder for an instanced shape like scatter).
+ * The shapes that follow points (lathe, tube, extrude) live in sculpt-shapes-curved.js.
+ *
+ *   keys     shape-only part keys; any other shape refuses them
+ *   read     (raw, part, where) fills the normalized part's shape fields
+ *   mirror   (copy) optional: reflect shape data across the part's own x = 0,
+ *            for shapes that are not symmetric about their own x
+ *   samples  (part) local sample points, as groups; each group is hulled
+ *            separately, so a bent shape can stay concave in silhouette
+ *   hole     (part) optional: the local front-face outline of a see-through hole
+ */
+
+import { RecipeError, isFiniteNumber, readUnit, tidy } from "./sculpt-recipe-read.js";
+import { LOFT_CONVEX_SPECS } from "./sculpt-shapes-loft-convex.js";
+import { CURVED_SHAPE_SPECS } from "./sculpt-shapes-curved.js";
+import { SCATTER_SHAPE } from "./sculpt-scatter-shape.js";
+
+/** How far a full taper narrows a blob's end; sculpt-geometry.js draws the same. */
+export const BLOB_TAPER = 0.6;
+
+const half = (part) => part.size.map((value) => value / 2);
+
+/** Sample rings from bottom (v = −1) to top (v = 1), `point(v, t)` per ring. */
+function rings(point) {
+	const points = [];
+	for (let i = 0; i <= 16; i += 1) {
+		const v = -1 + (2 * i) / 16;
+		for (let j = 0; j < 24; j += 1) points.push(...point(v, (j / 24) * 2 * Math.PI));
+	}
+	return points;
+}
+
+function blobSamples(part) {
+	const [sx, sy, sz] = half(part);
+	const p = 2 + 6 * part.roundness;
+	const taper = part.taper;
+	return [rings((v, t) => {
+		const k = taper > 0 ? 1 - taper * BLOB_TAPER * ((v + 1) / 2) : taper < 0 ? 1 + taper * BLOB_TAPER * ((1 - v) / 2) : 1;
+		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);
+		return [[(c / norm) * sx * ring * k, v * sy, (s / norm) * sz * ring * k]];
+	})];
+}
+
+function boxSamples(part) {
+	const [sx, sy, sz] = half(part);
+	const points = [];
+	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];
+}
+
+function cylinderSamples(part) {
+	const [sx, sy, sz] = half(part);
+	return [rings((v, t) => {
+		const r = 1 - Math.max(0, part.taper) * ((v + 1) / 2) - Math.max(0, -part.taper) * ((1 - v) / 2);
+		return [[Math.cos(t) * sx * r, v * sy, Math.sin(t) * sz * r]];
+	})];
+}
+
+function ringSamples(part) {
+	const [sx, sy, sz] = half(part);
+	return [rings((v, t) => {
+		const points = [[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]);
+		return points;
+	})];
+}
+
+/** The opening of a torus or frame, as the four corners of its front face. */
+function ringHole(part) {
+	const inset = part.shape === "frame" ? part.border : part.size[2];
+	const ix = part.size[0] / 2 - inset, iy = part.size[1] / 2 - inset;
+	if (ix <= 0 || iy <= 0) return null;
+	const z = -part.size[2] / 2;
+	return [[-ix, -iy, z], [ix, -iy, z], [ix, iy, z], [-ix, iy, z]];
+}
+
+export const SCULPT_SHAPE_SPECS = Object.freeze({
+	blob: {
+		keys: ["roundness", "taper"],
+		read(raw, part, where) {
+			part.roundness = readUnit(raw.roundness, `${where}.roundness`, 0.5, 0, 1);
+			part.taper = readUnit(raw.taper, `${where}.taper`, 0, -1, 1);
+		},
+		samples: blobSamples,
+	},
+	box: {
+		keys: ["roundness"],
+		read(raw, part, where) {
+			part.roundness = readUnit(raw.roundness, `${where}.roundness`, 0.1, 0, 1);
+		},
+		samples: boxSamples,
+	},
+	cylinder: {
+		keys: ["taper"],
+		read(raw, part, where) {
+			part.taper = readUnit(raw.taper, `${where}.taper`, 0, -1, 1);
+		},
+		samples: cylinderSamples,
+	},
+	torus: {
+		keys: [],
+		read(raw, part, where) {
+			if (part.size[2] >= Math.min(part.size[0], part.size[1])) {
+				throw new RecipeError(`${where}.size`, "a torus's tube (size[2]) must be thinner than its outer diameter");
+			}
+		},
+		samples: ringSamples,
+		hole: ringHole,
+	},
+	frame: {
+		keys: ["border"],
+		read(raw, part, where) {
+			const limit = Math.min(part.size[0], part.size[1]) / 2;
+			const border = raw.border === undefined ? tidy(Math.min(part.size[0], part.size[1]) * 0.15) : 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);
+		},
+		samples: ringSamples,
+		hole: ringHole,
+	},
+	...CURVED_SHAPE_SPECS,
+	...LOFT_CONVEX_SPECS,
+	scatter: SCATTER_SHAPE,
+});
+
+export const SCULPT_SHAPES = Object.freeze(Object.keys(SCULPT_SHAPE_SPECS));
+/** Every shape-only key, in first-seen order. */
+export const SCULPT_SHAPE_KEYS = Object.freeze([...new Set(Object.values(SCULPT_SHAPE_SPECS).flatMap((spec) => spec.keys))]);

package/src/sculpt-sketch-state.js

@@ -0,0 +1,76 @@
+// The live sketch of the running agent turn: the sculpt parts a tool call has written so far, as the sidecar's
+// sculpt.sketch frames carry them (bin/agent/sculpt-sketch.mjs), for sculpt-sketch.jsx to draw as ghost clay.
+// In-page only and per turn: nothing here is saved, undone, exported or sent to the agent. A call's sketch goes
+// when its tool.done arrives (the real objects are in the scene by then, or were refused), and everything goes
+// when the turn ends, fails or is stopped (agent-client.js clears it), so no ghost outlives its turn.
+import { expandSculptParts, normalizeSculptRecipe } from "./sculpt-recipe.js";
+
+const MAX_PARTS = 300;
+const EMPTY = Object.freeze([]);
+const sketches = new Map(), finished = new Set(), listeners = new Set();
+let snapshot = EMPTY;
+
+function emit() {
+	snapshot = Object.freeze([...sketches].flatMap(([call, groups]) => groups.map((group) => ({ ...group, key: `${call}/${group.key}` }))));
+	for (const listener of [...listeners]) {
+		try { listener(); } catch { /* a broken view never stops the turn */ }
+	}
+}
+
+/**
+ * sculptSketchFrame(event) takes every frame of the running turn: sculpt.sketch sets (or, with no groups, drops)
+ * one call's sketch; tool.done drops that call's sketch and ignores any sketch of it that arrives later (the final
+ * one can trail a quick tool); done and error end the turn's sketches.
+ */
+export function sculptSketchFrame(event) {
+	if (event?.type === "sculpt.sketch") {
+		const call = typeof event.callId === "string" && event.callId ? event.callId : `#${event.index}`;
+		if (finished.has(call)) return;
+		// The same call sketched before its id was known (bin/agent/sculpt-sketch.mjs).
+		const unnamed = call !== `#${event.index}` && sketches.delete(`#${event.index}`);
+		const groups = (Array.isArray(event.groups) ? event.groups : [])
+			.filter((group) => group && typeof group.key === "string" && Array.isArray(group.parts) && group.parts.length);
+		if (groups.length) sketches.set(call, groups);
+		else if (!sketches.delete(call) && !unnamed) return;
+		emit();
+	} else if (event?.type === "tool.done" && typeof event.callId === "string") {
+		finished.add(event.callId);
+		if (sketches.delete(event.callId)) emit();
+	} else if (event?.type === "done" || event?.type === "error") clearSculptSketch();
+}
+
+/** Forget every sketch of the turn (it ended, failed or was stopped). */
+export function clearSculptSketch() {
+	finished.clear();
+	if (!sketches.size) return;
+	sketches.clear();
+	emit();
+}
+
+/** subscribeSculptSketch(listener) -> unsubscribe; with sculptSketchSnapshot it fits React's useSyncExternalStore. */
+export function subscribeSculptSketch(listener) {
+	listeners.add(listener);
+	return () => { listeners.delete(listener); };
+}
+
+/** Every group being sketched, [{ key, name?, target?, placement?, parts }]; the same array until a frame changes it. */
+export const sculptSketchSnapshot = () => snapshot;
+
+/**
+ * sketchDrawnParts(parts) -> the parts a ghost draws, as expandSculptParts gives them (object-frame matrix, mirrors
+ * expanded). Lenient where the real recipe is strict: each part is checked on its own and a bad one is dropped, not
+ * the whole recipe, and a part whose parent is not written yet waits, because a sketch is a recipe half written.
+ */
+export function sketchDrawnParts(parts) {
+	const drawable = [], ids = new Set();
+	for (const raw of Array.isArray(parts) ? parts.slice(0, MAX_PARTS) : []) {
+		if (!raw || typeof raw !== "object" || ids.has(raw.id)) continue;
+		const { parent, mirror, ...own } = raw;
+		const checked = normalizeSculptRecipe({ version: 1, parts: [own] });
+		if (!checked.ok || checked.recipe.parts[0].op) continue;
+		ids.add(raw.id);
+		drawable.push({ ...checked.recipe.parts[0], ...(typeof parent === "string" && parent ? { parent } : {}), ...(mirror === true ? { mirror: true } : {}) });
+	}
+	// expandSculptParts walks down from the roots, so an orphan (or a parent cycle) is never reached.
+	return expandSculptParts({ version: 1, parts: drawable });
+}