cozyclay 3.0.3 → 3.1.1

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

package/src/sculpt-sketch.jsx

@@ -0,0 +1,124 @@
+// The live sketch in the working views: while the agent is still writing a call that builds sculpts, the parts it
+// has written so far (sculpt-sketch-state.js) stand on the stage as translucent clay in their own colours, so the
+// scene takes shape while the model types instead of after minutes of an empty stage. Each part grows in briefly,
+// so new ones read as new. Everything sits on GIZMO_LAYER and takes no ray: the shot preview card, PlayView,
+// captures the agent reads (verify_result), contact sheets and exports never draw it, and no pick can select it.
+// A part that did not change keeps its mesh; a removed one is disposed with its geometry and material.
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import * as THREE from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { GIZMO_LAYER } from "./dualview.jsx";
+import { sculptPartGeometry } from "./sculpt-geometry.js";
+import { clearSculptSketch, sculptSketchFrame, sculptSketchSnapshot, sketchDrawnParts, subscribeSculptSketch } from "./sculpt-sketch-state.js";
+
+const OPACITY = 0.42;
+/** A scatter is drawn as the soft box it fills: its items are the real sculpt's job. */
+const SCATTER_OPACITY = 0.2;
+const GROW_MS = 420;
+const DEG = Math.PI / 180;
+// After the other see-through things (ghost-set.js draws onion skins at 40).
+const RENDER_ORDER = 44;
+const noRay = () => {};
+const grow = (t) => 1 - (1 - t) ** 3;
+
+/** Where a group stands: its object.sculpt placement, else the sculpt it rebuilds, else the origin (where a new sculpt lands). */
+function placementMatrix(group, objects) {
+	const target = group.target ? objects?.find((object) => object.id === group.target) : null;
+	const at = { x: target?.x ?? 0, y: target?.y ?? 0, z: target?.z ?? 0, rot: target?.rot ?? 0, ...group.placement };
+	return new THREE.Matrix4().compose(new THREE.Vector3(at.x, at.y, at.z), new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), at.rot * DEG), new THREE.Vector3(1, 1, 1));
+}
+
+/** Every part to draw: { identity, part, matrix (world) }. The identity leaves out ids and placement, so a part
+ * the model renamed, or a group that just learned where it stands, keeps its mesh. */
+function sketchItems(groups, objects) {
+	const items = [];
+	for (const group of groups) {
+		const place = placementMatrix(group, objects);
+		for (const part of sketchDrawnParts(group.parts)) {
+			const { id, parent, matrix, ...shape } = part;
+			items.push({ identity: JSON.stringify([shape, matrix.map((value) => Math.round(value * 1e4))]), part, matrix: place.clone().multiply(new THREE.Matrix4().fromArray(matrix)) });
+		}
+	}
+	return items;
+}
+
+/** The meshes of the sketch under one root, keyed by identity. */
+class SketchLayer {
+	root = new THREE.Group();
+	meshes = new Map();
+	constructor() {
+		this.root.name = "sculpt-sketch";
+		this.root.userData.sculptSketch = true;
+	}
+	make(part, now) {
+		const geometry = sculptPartGeometry(part.shape === "scatter" ? { ...part, shape: "blob", roundness: 0.5, taper: 0 } : part);
+		const material = new THREE.MeshStandardMaterial({ color: part.color, emissive: part.color, emissiveIntensity: 0.18, roughness: 0.85, metalness: 0, transparent: true, opacity: 0, depthWrite: false });
+		const mesh = new THREE.Mesh(geometry, material);
+		Object.assign(mesh, { raycast: noRay, castShadow: false, receiveShadow: false, matrixAutoUpdate: false, renderOrder: RENDER_ORDER, frustumCulled: false });
+		mesh.layers.set(GIZMO_LAYER);
+		mesh.userData.sculptSketch = true;
+		this.root.add(mesh);
+		return { mesh, base: new THREE.Matrix4(), born: now, opacity: part.shape === "scatter" ? SCATTER_OPACITY : OPACITY };
+	}
+	drop({ mesh }) {
+		this.root.remove(mesh);
+		mesh.geometry.dispose();
+		mesh.material.dispose();
+	}
+	/** Keep the meshes whose parts are still there, make the new ones, dispose the rest. */
+	update(items, now) {
+		const next = new Map(), seen = new Map();
+		for (const item of items) {
+			const n = (seen.get(item.identity) ?? 0) + 1;
+			seen.set(item.identity, n);
+			const key = `${item.identity}#${n}`;
+			let entry = this.meshes.get(key);
+			if (entry) this.meshes.delete(key);
+			else {
+				try { entry = this.make(item.part, now); } catch { continue; }
+			}
+			entry.base.copy(item.matrix);
+			next.set(key, entry);
+		}
+		for (const entry of this.meshes.values()) this.drop(entry);
+		this.meshes = next;
+		this.frame(now);
+	}
+	/** Grow the new parts in; true while one still grows. */
+	frame(now) {
+		let growing = false;
+		const scale = new THREE.Matrix4();
+		for (const entry of this.meshes.values()) {
+			const t = Math.min(1, Math.max(0, (now - entry.born) / GROW_MS)), k = grow(t);
+			growing ||= t < 1;
+			const s = 0.55 + 0.45 * k;
+			entry.mesh.matrix.copy(entry.base).multiply(scale.makeScale(s, s, s));
+			entry.mesh.material.opacity = entry.opacity * k;
+		}
+		return growing;
+	}
+	dispose() {
+		for (const entry of this.meshes.values()) this.drop(entry);
+		this.meshes.clear();
+	}
+}
+
+/** objects: the authored records, for the placement of a sculpt the agent rebuilds (object.sculpt { id }). */
+export function SculptSketch({ objects }) {
+	const groups = useSyncExternalStore(subscribeSculptSketch, sculptSketchSnapshot, sculptSketchSnapshot);
+	const scene = useThree((state) => state.scene), invalidate = useThree((state) => state.invalidate);
+	const layer = useMemo(() => new SketchLayer(), []);
+	const items = useMemo(() => sketchItems(groups, objects), [groups, objects]);
+	useEffect(() => {
+		scene.add(layer.root);
+		// QA: the browser suite feeds frames and counts what the stage draws.
+		if (typeof window !== "undefined") window.__cozyclaySculptSketch = { frame: sculptSketchFrame, clear: clearSculptSketch, meshes: () => layer.meshes.size, root: layer.root };
+		return () => { scene.remove(layer.root); layer.dispose(); };
+	}, [scene, layer]);
+	useEffect(() => {
+		layer.update(items, performance.now());
+		invalidate();
+	}, [layer, items, invalidate]);
+	useFrame(() => { if (layer.frame(performance.now())) invalidate(); });
+	return null;
+}

package/src/sculpt-surface-fields.js

@@ -0,0 +1,65 @@
+/**
+ * Surface fields any part takes (registered in sculpt-part-fields.js):
+ *
+ *   detail    { amount: 0..1, scale?: 1..12, seed? } lumps a smooth part into
+ *             a cloud, bush, rock, hay bale or loaf. `amount` is the bump
+ *             height (1 = DETAIL_RELIEF of the part's smallest half-extent),
+ *             `scale` about how many bumps fit across its longest side.
+ *   gradient  { color, axis?: y|x|z, from?: 0..1, to?: 0..1 } blends the
+ *             part's colour (at `from`) into `color` (at `to`) along a local
+ *             axis, 0 at its low end and 1 at its high end: a sky-lit cloud,
+ *             a ripening fruit, a sunset wall. On a scatter it colours whole
+ *             items by where they sit.
+ *
+ * The geometry halves are sculpt-detail.js and sculpt-colours.js. Pure: no three.js.
+ */
+
+import { RecipeError, readChoice, readHexColor, readSeed, readUnit } from "./sculpt-recipe-read.js";
+
+/** Bump height at amount 1, as a fraction of the part's smallest half-extent:
+ * past this a rock reads as a crumpled ball. sculpt-detail.js draws the same. */
+export const DETAIL_RELIEF = 0.35;
+const DETAIL_SCALE = { fallback: 4, min: 1, max: 12 };
+const GRADIENT_AXES = ["y", "x", "z"];
+
+function readFields(value, path, keys) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new RecipeError(path, `must be an object { ${keys.join(", ")} }, got ${JSON.stringify(value)}`);
+	}
+	for (const key of Object.keys(value)) {
+		if (!keys.includes(key)) throw new RecipeError(`${path}.${key}`, `unknown key (allowed: ${keys.join(", ")})`);
+	}
+	return value;
+}
+
+const DETAIL_FIELD = {
+	key: "detail",
+	read(raw, part, where) {
+		const at = `${where}.detail`;
+		if (part.shape === "scatter") throw new RecipeError(at, "does not apply to a scatter: its items are already small; lump the part under it instead");
+		const detail = readFields(raw.detail, at, ["amount", "scale", "seed"]);
+		if (detail.amount === undefined) throw new RecipeError(`${at}.amount`, "is required: the bump height from 0 (smooth) to 1 (very lumpy)");
+		part.detail = {
+			amount: readUnit(detail.amount, `${at}.amount`, 0, 0, 1),
+			scale: readUnit(detail.scale, `${at}.scale`, DETAIL_SCALE.fallback, DETAIL_SCALE.min, DETAIL_SCALE.max),
+			seed: readSeed(detail.seed, `${at}.seed`),
+		};
+	},
+};
+
+const GRADIENT_FIELD = {
+	key: "gradient",
+	read(raw, part, where) {
+		const at = `${where}.gradient`;
+		const gradient = readFields(raw.gradient, at, ["color", "axis", "from", "to"]);
+		if (gradient.color === undefined) throw new RecipeError(`${at}.color`, "is required: the #rrggbb colour the part blends into");
+		part.gradient = {
+			color: readHexColor(gradient.color, `${at}.color`),
+			axis: readChoice(gradient.axis, `${at}.axis`, "y", GRADIENT_AXES),
+			from: readUnit(gradient.from, `${at}.from`, 0, 0, 1),
+			to: readUnit(gradient.to, `${at}.to`, 1, 0, 1),
+		};
+	},
+};
+
+export const SURFACE_FIELDS = [DETAIL_FIELD, GRADIENT_FIELD];

package/src/settings-menu.jsx

@@ -7,8 +7,7 @@ import PreferencesDialog from "./shell/PreferencesDialog.jsx";
 // not belong on the Save/Export row as bare toggles.
 //
 // The trigger now opens the v2 Preferences dialog. The old language strings stay
-// here because the locale contract and the camera-tutorial source contract both
-// treat this file as the Settings entry point.
+// here because the locale contract treats this file as the Settings entry point.
 const LANGUAGES = [
 	{ id: "en", label: "English", action: "Switch to English" },
 	{ id: "ko", label: "한국어", action: "한국어로 전환" },
@@ -21,23 +20,6 @@ export default function SettingsMenu() {
 		setOpen(false);
 		triggerRef.current?.focus();
 	}, []);
-	const openCameraTutorial = useCallback(() => {
-		window.dispatchEvent(new CustomEvent("cozyclay:camera-tutorial", { detail: { open: true } }));
-		setOpen(false);
-	}, []);
-	const cameraTutorial = (
-		<>
-			<h4>{ko("Help", "도움말")}</h4>
-			<button
-				type="button"
-				data-testid="settings-camera-tutorial"
-				title={ko("Learn the camera in seven steps", "일곱 단계로 카메라 익히기")}
-				onClick={openCameraTutorial}
-			>
-				{ko("Camera tutorial", "카메라 튜토리얼")}
-			</button>
-		</>
-	);
 
 	// First-run cue: the studio starts in English even on a Korean browser, so
 	// the only visible hint that Korean exists used to be the old locale button.
@@ -64,7 +46,6 @@ export default function SettingsMenu() {
 				open={open}
 				onClose={close}
 				initialSection="Appearance"
-				cameraTutorial={cameraTutorial}
 			/>
 		</div>
 	);