cozyclay 2.0.2 → 2.1.1

package/src/sculpt-run.js

@@ -0,0 +1,351 @@
+const INITIAL_MESSAGE = "Measure the reference landmarks before placing parts.";
+
+const initialState = ({ targetIou, maxRounds }) => ({
+	stage: "idle",
+	round: 0,
+	maxRounds,
+	iou: null,
+	targetIou,
+	elapsedMs: 0,
+	sheetDataUrl: null,
+	message: null,
+	error: null,
+	sculptId: null,
+	// What the operator watches while a turn is out: a log, what we wait on, the score history.
+	activity: [],
+	waiting: null,
+	history: [],
+	candidates: null,
+	outline: null,
+	changedParts: null,
+});
+
+const ACTIVITY_LIMIT = 40;
+// How long each wait usually takes, from the live runs in docs/sculpt-from-image.md.
+const EXPECTED_WAIT_MS = Object.freeze({ measure: 1500, draft: 60000, refine: 35000, agent: 20000, tool: 3000, score: 1500 });
+
+function toolLabel(action, args = {}, who = "Agent") {
+	if (action === "object.sculpt") return args.edits ? `${who} is applying the winning edits` : `${who} is building the recipe`;
+	if (action === "sculpt.compare") return Array.isArray(args.candidates) ? `${who} is test-fitting ${args.candidates.length} candidate fixes` : `${who} is scoring the sculpt`;
+	if (action === "inspect_studio" || action === "inspect") return `${who} is reading the editor`;
+	return `${who} is running ${action}`;
+}
+
+const shortError = error => String(error ?? "").replace(/\s*\(inspect, do not retry\)\s*$/, "").slice(0, 140);
+
+const isAsyncIterable = value => value && typeof value[Symbol.asyncIterator] === "function";
+const commandName = event => event?.action ?? event?.command ?? (event?.commandId ? event?.name : undefined) ?? event?.name ?? event?.id;
+const commandArgs = event => event?.args ?? event?.arguments ?? event?.request?.args ?? {};
+const commandResult = event => event?.result ?? event?.receipt ?? event?.output ?? event?.response ?? event?.value;
+const affectedIds = value => Array.isArray(value?.affectedIds) ? value.affectedIds : [];
+
+function dataUrlFromSheet(sheet) {
+	if (typeof sheet === "string") return sheet;
+	// Raw RGBA is no image a browser can show: only sheetDataUrl (a PNG) is displayed.
+	return null;
+}
+
+// The reference as sculpt.compare takes it: the stored asset when there is one.
+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.";
+
+// A compact score for the next turn: what is missing where, and which parts stick out.
+function reportText(report) {
+	if (!report) return "";
+	const extra = Array.isArray(report.extraByPart) ? report.extraByPart.slice(0, 4) : report.extraByPart;
+	return ` Score detail: ${JSON.stringify({ widthToHeight: report.widthToHeight, missingByBand: report.missingByBand, extraByPart: extra })}.`;
+}
+
+function outlineText(outline) {
+	if (!outline) return "";
+	return ` The harness measured the reference outline in pixels (front view; x is a fraction of the subject's height from its centre, + toward image right = the subject's own left; y is a fraction of height from the head top; spans are the filled runs across each slice): ${JSON.stringify(outline)}. Put parts on these measurements.`;
+}
+
+function makeTurnText(reference, sculptId, continuation, outline = null) {
+	const ref = JSON.stringify(referenceArg(reference));
+	if (continuation) {
+		return [
+			`Round ${continuation.round} of ${continuation.maxRounds}. The harness scored sculpt ${sculptId} at IoU ${continuation.iou ?? "unknown"} against the reference.${reportText(continuation.report)}`,
+			`Write 3-6 candidate edit sets that fix the biggest mismatch (proportion first, then placement), rank them with ONE run_action sculpt.compare { "id": "${sculptId}", "reference": ${ref}, "candidates": [{ "label", "edits" }] },`,
+			`apply the best-ranked set with ONE run_action object.sculpt { "id": "${sculptId}", "edits": [...] }, then end the turn with one short line. Do not inspect first; the harness scores the result after your turn.`,
+			RECIPE_RULES,
+		].join(" ");
+	}
+	return [
+		"Sculpt the subject of the attached reference image as a clay recipe.",
+		outline
+			? `Use the measured outline below, scaled to a real-world height in metres.${outlineText(outline)}`
+			: "First measure the visible outline in the image: the subject's bounding box, then where the head top, each limb tip and the feet sit as fractions of its height, and convert them to metres for a real-world height.",
+		sculptId
+			? `Then rewrite sculpt ${sculptId} with ONE run_action object.sculpt { "id": "${sculptId}", "recipe": ... }, keeping parts on the measured landmarks.`
+			: "Then create it with ONE run_action object.sculpt { \"name\", \"recipe\" }, keeping parts on the measured landmarks.",
+		"No inspect calls are needed and do not call sculpt.compare: the harness scores the sculpt after your turn and tells you the result.",
+		"End the turn with one short line naming what the image hides.",
+		RECIPE_RULES,
+	].join(" ");
+}
+
+/**
+ * Adapt the callback-based Studio client into the small port consumed by the
+ * sculpt controller. The controller deliberately owns the session/turn loop.
+ */
+// The sidecar's Studio envelope requires UUIDs for both the session and the turn.
+export function createAgentPort(client, { sessionId = crypto.randomUUID() } = {}) {
+	return {
+		async *sendTurn({ text, attachments = [], signal, model, effort, turnId = crypto.randomUUID() }) {
+			const events = [];
+			let wake;
+			let ended = false;
+			const push = event => { events.push(event); wake?.(); wake = null; };
+			const result = client.turn({
+				surface: "studio",
+				sessionId,
+				turnId,
+				text,
+				...(model ? { model } : {}),
+				...(effort ? { effort } : {}),
+				...(attachments.length ? { attachments } : {}),
+				context: null,
+			}, push, signal);
+			Promise.resolve(result).then(() => { ended = true; wake?.(); wake = null; }, error => { ended = true; push({ type: "error", message: String(error?.message || error) }); });
+			while (!ended || events.length) {
+				if (!events.length) await new Promise(resolve => { wake = resolve; });
+				while (events.length) yield events.shift();
+			}
+		},
+	};
+}
+
+export function createSculptRun({
+	bus,
+	agent,
+	reference,
+	sculptId = null,
+	targetIou = 0.9,
+	maxRounds = 3,
+	timeBudgetMs = 180000,
+	now = Date.now,
+	// Optional ({ id, reference }) -> sculpt.compare result. The harness scores a turn the agent left unscored.
+	score = null,
+	// Optional (reference) -> measureReferenceOutline result, put into the first turn's text.
+	measure = null,
+	// The model every turn runs on (a /agent/models key) and its effort; omitted = the sidecar's defaults.
+	// Measured on the Snorlax reference: effort "high" made the draft twice as slow for no better score.
+	model = undefined,
+	effort = undefined,
+	// How the model is named to the operator ("GPT-6 Astra"); the key when unset.
+	modelLabel = undefined,
+} = {}) {
+	if (!agent?.sendTurn) throw new TypeError("sculpt run requires an agent port");
+	const who = modelLabel || model || "Agent";
+	const listeners = new Set();
+	const controller = new AbortController();
+	let state = { ...initialState({ targetIou, maxRounds }), model: { key: model ?? null, label: who, effort: effort ?? null } };
+	let running = false;
+	let settled = false;
+	let startedAt = 0;
+	let turnSculpted = false;
+	let turnScored = false;
+	let lastReport = null;
+	// A score repeated with no edit in between says nothing new: keep its sheet, skip the log line.
+	let editedSinceScore = true;
+	let retryCount = 0;
+	let turnPromise = null;
+
+	const elapsed = () => Math.max(0, now() - startedAt);
+	const publish = patch => {
+		state = { ...state, ...patch, elapsedMs: elapsed() };
+		// An observer must never stop the run it watches.
+		for (const listener of [...listeners]) {
+			try { listener(state); } catch (error) { console.error("sculpt run listener failed", error); }
+		}
+	};
+	let activitySeq = 0;
+	const entry = (kind, text) => ({ id: ++activitySeq, atMs: elapsed(), kind, text });
+	// One line in the activity log, with whatever else changes at the same moment.
+	const note = (kind, text, patch = {}) => publish({ ...patch, activity: [...state.activity, entry(kind, text)].slice(-ACTIVITY_LIMIT) });
+	const waitFor = (what, label) => ({ what, label, since: now(), expectMs: EXPECTED_WAIT_MS[what] ?? null });
+	const toolCalls = new Map();
+	// The turn's own wait ("writing the recipe", since the turn went out): a tool call interrupts it, never resets it.
+	let turnWait = null;
+	// The turns this run sent: only their commands are the run's. Another turn,
+	// MCP or a UI edit on any sculpt is never claimed.
+	const ownTurns = new Set();
+	const onBus = event => { if (!controller.signal.aborted && ownTurns.has(event?.turnId)) onCommand(event); };
+	const onCommand = event => {
+		const name = commandName(event);
+		const args = commandArgs(event);
+		const result = commandResult(event);
+		const ids = affectedIds(result);
+		if (name === "object.sculpt" || event?.type === "object.sculpt") {
+			const id = args.id ?? ids[0] ?? event?.sculptId ?? state.sculptId;
+			if (id) {
+				turnSculpted = true;
+				turnScored = false; // a score taken before this edit no longer describes the sculpt
+				editedSinceScore = true;
+				const stage = state.round > 1 ? "refine" : "draft";
+				const edits = Array.isArray(args.edits) ? args.edits : null;
+				const ids = edits ? [...new Set(edits.map(edit => edit?.set ?? edit?.add?.id ?? edit?.remove).filter(Boolean))] : "all";
+				const parts = /(\d+) parts/.exec(String(result?.summary ?? ""))?.[1];
+				const text = edits ? `Applied ${edits.length} edit${edits.length === 1 ? "" : "s"}${ids.length ? ` to ${ids.slice(0, 4).join(", ")}${ids.length > 4 ? "…" : ""}` : ""}` : `Draft on the turntable${parts ? `: ${parts} parts` : ""}`;
+				note("ok", text, { sculptId: id, round: Math.max(1, state.round), stage, message: edits ? "Edits applied." : "Draft sculpt applied.", changedParts: { ids, nonce: activitySeq + 1 } });
+			}
+			return;
+		}
+		if (name !== "sculpt.compare" && event?.type !== "sculpt.compare") return;
+		const report = result?.report ?? event?.report;
+		if (result && Number.isFinite(Number(result.report?.iou ?? result.iou))) lastReport = result.report ?? result;
+		const iou = Number(report?.iou ?? result?.iou ?? event?.iou);
+		const sheet = result?.sheetDataUrl ?? event?.sheetDataUrl ?? dataUrlFromSheet(result?.sheet);
+		const ranking = Array.isArray(result?.ranking) ? result.ranking : null;
+		if (ranking) {
+			// A candidate ranking scores the sculpt as it stands; the edit that follows is what counts.
+			const best = ranking.find(row => !row.refused);
+			note("score", best ? `Ranked ${ranking.length} candidate fixes: "${best.label}" leads${Number.isFinite(best.delta) ? ` (${best.delta >= 0 ? "+" : ""}${best.delta.toFixed(3)})` : ""}` : `Ranked ${ranking.length} candidate fixes`, {
+				candidates: ranking.map(row => ({ label: row.label, iou: Number.isFinite(row.iou) ? row.iou : null, delta: Number.isFinite(row.delta) ? row.delta : null, refused: Boolean(row.refused) })),
+				...(sheet ? { sheetDataUrl: sheet } : {}),
+			});
+			return;
+		}
+		if (Number.isFinite(iou)) turnScored = true;
+		if (Number.isFinite(iou) && !editedSinceScore && iou === state.iou) {
+			publish({ stage: "score", ...(sheet ? { sheetDataUrl: sheet } : {}) });
+			return;
+		}
+		if (Number.isFinite(iou)) editedSinceScore = false;
+		const previous = state.history.at(-1)?.iou;
+		const delta = Number.isFinite(iou) && Number.isFinite(previous) ? iou - previous : null;
+		note("score", Number.isFinite(iou) ? `Scored IoU ${iou.toFixed(3)}${delta !== null ? ` (${delta >= 0 ? "+" : ""}${delta.toFixed(3)})` : ""}` : "Scored the sculpt", {
+			stage: "score",
+			...(Number.isFinite(iou) ? { iou, history: [...state.history, { round: state.round, iou, atMs: elapsed() }] } : {}),
+			...(sheet ? { sheetDataUrl: sheet } : {}),
+			message: Number.isFinite(iou) ? `Sculpt comparison scored IoU ${iou}.` : "Sculpt comparison complete.",
+		});
+	};
+	const unsubscribeBus = bus?.subscribe?.(onBus) ?? (() => {});
+
+	const consumeTurn = async text => {
+		turnSculpted = false;
+		turnScored = false;
+		const events = [];
+		let turnError = null;
+		const callback = event => {
+			events.push(event);
+			if (event?.type === "text.delta") publish({ message: `${state.message ?? ""}${event.text ?? ""}` });
+			if (event?.type === "tool.start") {
+				const action = event.args?.action ?? event.name;
+				toolCalls.set(event.callId, action);
+				publish({ waiting: waitFor("tool", toolLabel(action, event.args?.args ?? {}, who)) });
+			}
+			if (event?.type === "tool.done") {
+				const action = toolCalls.get(event.callId);
+				toolCalls.delete(event.callId);
+				// Successes reach the log through the editor's receipts; a refusal only shows up here.
+				const patch = { waiting: turnWait ?? waitFor("agent", `${who} is deciding the next step`) };
+				if (event.ok === false) note("warn", `${action === "object.sculpt" ? "Recipe refused" : `${action ?? "A tool"} failed`}: ${shortError(event.error)}. The agent is fixing it.`, patch);
+				else publish(patch);
+			}
+			// A refused or failed turn is the run's failure, not a turn that forgot to sculpt.
+			if (event?.type === "error") turnError ??= new Error(event.message || event.code || "The agent turn failed.");
+		};
+		const turnId = crypto.randomUUID();
+		ownTurns.add(turnId);
+		const returned = agent.sendTurn({ turnId, text, attachments: reference?.dataUrl ? [{ dataUrl: reference.dataUrl, name: reference.name }] : [], signal: controller.signal, ...(model ? { model } : {}), ...(effort ? { effort } : {}) }, callback);
+		if (isAsyncIterable(returned)) {
+			for await (const event of returned) callback(event);
+		} else await returned;
+		if (turnError) throw turnError;
+		// The agent's own closing words, first line only: what it did or what the image hides.
+		const said = events.filter(event => event?.type === "text.delta").map(event => event.text ?? "").join("").replace(/[*_`#]/g, "").split(/\n+/).map(line => line.trim()).find(Boolean);
+		if (said) note("agent", `${who}: ${said.length > 160 ? `${said.slice(0, 157)}…` : said}`);
+	};
+
+	const loop = async () => {
+		startedAt = now();
+		note("step", "Measuring the reference outline", { stage: "measure", round: 0, message: INITIAL_MESSAGE, error: null, waiting: waitFor("measure", "Measuring the reference outline") });
+		let outline = null;
+		if (measure) {
+			try {
+				outline = await measure(referenceArg(reference));
+				const split = outline?.rows?.filter(row => row.spans.length > 1).length ?? 0;
+				note("ok", `Outline measured: width:height ${outline.widthToHeight}, ${outline.rows.length} slices${split ? `, ${split} with separate limbs` : ""}`, { outline });
+			} catch (error) { note("warn", `Could not measure the reference: ${shortError(error?.message || error)}`, { message: `Could not measure the reference: ${String(error?.message || error)}` }); }
+		}
+		if (controller.signal.aborted) { note("warn", "Cancelled", { stage: "cancelled", message: "Sculpt run cancelled.", waiting: null }); settled = true; return; }
+		let text = makeTurnText(reference, sculptId, false, outline);
+		while (!controller.signal.aborted) {
+			if (elapsed() >= timeBudgetMs) break;
+			const roundBefore = state.round;
+			turnWait = roundBefore === 0 ? waitFor("draft", `${who} is writing the recipe`) : waitFor("refine", `${who} is weighing fixes`);
+			// Measuring is over once the first turn goes out: the stepper moves on to Draft.
+			note("agent", roundBefore === 0 ? `Asked ${who}${effort ? ` (effort ${effort})` : ""} for a first draft` : `Round ${state.round}: asked ${who} for 3-6 candidate fixes`, {
+				waiting: turnWait, ...(roundBefore === 0 ? { stage: "draft" } : {}),
+			});
+			turnPromise = consumeTurn(text);
+			try { await turnPromise; } catch (error) {
+				if (controller.signal.aborted) break;
+				note("error", `Run failed: ${shortError(error?.message || error)}`, { stage: "failed", error: String(error?.message || error), message: "Sculpt run failed.", waiting: null });
+				settled = true;
+				return;
+			} finally { turnPromise = null; }
+			if (controller.signal.aborted) break;
+			if (!turnSculpted) {
+				if (retryCount === 0) {
+					retryCount += 1;
+					note("warn", "The agent ended without sculpting; asking again", { stage: roundBefore > 0 ? "refine" : "measure", message: "No object.sculpt command arrived; retrying with a firm reminder." });
+					text = `${text} Firm reminder: you must execute object.sculpt before ending this turn, then call sculpt.compare.`;
+					continue;
+				}
+				note("error", "No sculpt after one retry", { stage: "failed", error: "The turn ended without an object.sculpt command.", message: "No sculpt was applied after one retry.", waiting: null });
+				settled = true;
+				return;
+			}
+			retryCount = 0;
+			if (!turnScored && score && state.sculptId) {
+				const args = { id: state.sculptId, reference: referenceArg(reference) };
+				publish({ waiting: waitFor("score", "Scoring the silhouette against the reference") });
+				try {
+					const value = await score(args);
+					onCommand({ action: "sculpt.compare", args, result: value?.output ?? value });
+				} catch (error) {
+					note("warn", `Scoring failed: ${shortError(error?.message || error)}`, { message: `Scoring failed: ${String(error?.message || error)}` });
+				}
+				if (controller.signal.aborted) break;
+			}
+			if (state.iou !== null && state.iou >= targetIou) break;
+			if (state.round >= maxRounds || elapsed() >= timeBudgetMs) break;
+			const nextRound = Math.max(1, state.round + 1);
+			publish({ stage: "refine", round: nextRound, message: `Preparing refinement round ${nextRound} of ${maxRounds}.` });
+			// The next turn's note says what was asked; nothing to log in between.
+			text = makeTurnText(reference, state.sculptId, { round: nextRound, maxRounds, iou: state.iou, report: lastReport });
+		}
+		if (controller.signal.aborted) {
+			note("warn", "Cancelled", { stage: "cancelled", message: "Sculpt run cancelled.", waiting: null });
+		} else {
+			const reached = state.iou !== null && state.iou >= targetIou;
+			note(reached ? "done" : "ok", state.iou === null ? "Finished without a score" : `${reached ? "Target reached" : "Finished"} at IoU ${state.iou.toFixed(3)}`, { stage: "done", message: state.iou === null ? "Sculpt run finished without a score." : `Sculpt run finished at IoU ${state.iou}.`, waiting: null });
+		}
+		settled = true;
+	};
+	// A finished run stops listening to the bus, whichever way it ended.
+	const run = async () => {
+		try { await loop(); } finally { unsubscribeBus(); }
+	};
+
+	return {
+		start() {
+			if (running) return turnPromise ?? Promise.resolve();
+			running = true;
+			return run();
+		},
+		cancel() {
+			if (settled) return;
+			controller.abort("sculpt-run-cancelled");
+			if (!running) { unsubscribeBus(); note("warn", "Cancelled", { stage: "cancelled", message: "Sculpt run cancelled.", waiting: null }); }
+		},
+		getState: () => state,
+		subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+	};
+}

package/src/sculpt-stage.jsx

@@ -0,0 +1,221 @@
+// Sculpt mode (#739): the isolated turntable the main viewport shows, and the
+// inspector host the Sculpt panel mounts into.
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { OrbitControls, PerspectiveCamera } from "@react-three/drei";
+import * as THREE from "three";
+import { SCULPT_LAYER, isolatedObjectIds, sculptFraming } from "./sculpt-mode.js";
+
+const SCULPT_FOV = 35;
+// Where a new sculpt lands (object.sculpt without placement): the origin.
+const EMPTY_TARGET = { x: 0, y: 0, z: 0, rot: 0 };
+const EMPTY_SIZE = { width: 1, height: 1.2, depth: 1 };
+// The turntable is set furniture inside the WebGL scene, so its tones are
+// three.js colours chosen against the stage background (grid-view.js).
+const TURNTABLE_TONES = {
+	dark: { floor: "#2c2e34", ring: "#4a4d56" },
+	light: { floor: "#d6d8de", ring: "#b4b7c0" },
+};
+
+function findObjectNodes(scene, ids) {
+	const found = [];
+	if (ids.length) scene.traverse((node) => { if (ids.includes(node.userData?.sceneObjectId)) found.push(node); });
+	return found;
+}
+
+/**
+ * The glass shell's dock floats over the bottom of the main pane, so the
+ * turntable is framed for the part above it: a lens shift (a view offset whose
+ * principal point is the visible region's centre) with the lens widened so
+ * that region spans SCULPT_FOV. DualRender sets aspect = pane w/h every frame,
+ * so the full frame keeps that pixel aspect.
+ */
+function fitVisiblePane(camera) {
+	const pane = document.querySelector(".vp-pane.vp-main")?.getBoundingClientRect();
+	if (!pane || pane.height < 2 || pane.width < 2) return;
+	const dock = document.querySelector(".bottom-window")?.getBoundingClientRect();
+	const covered = dock && dock.left < pane.right && dock.right > pane.left && dock.top < pane.bottom
+		? Math.max(0, pane.bottom - dock.top) : 0;
+	const height = pane.height, width = pane.width;
+	const visible = Math.max(height * 0.4, height - covered);
+	if (visible >= height - 1) {
+		if (camera.view?.enabled) camera.clearViewOffset();
+		camera.fov = SCULPT_FOV;
+		return;
+	}
+	const fullHeight = 2 * height - visible;
+	const fullWidth = (width * fullHeight) / height;
+	camera.fov = (2 * Math.atan(Math.tan(((SCULPT_FOV / 2) * Math.PI) / 180) * (fullHeight / visible)) * 180) / Math.PI;
+	camera.setViewOffset(fullWidth, fullHeight, (fullWidth - width) / 2, height - visible, width, height);
+}
+
+function attached(node, scene) {
+	for (let current = node; current; current = current.parent) if (current === scene) return true;
+	return false;
+}
+
+/**
+ * The sculpt camera, its orbit and the turntable. Rendering is isolated by
+ * layer, never by record: each frame the target's own meshes join
+ * SCULPT_LAYER and the sculpt camera sees that layer alone, so every other
+ * object, the cast and the set drop out of the main pane while the shot
+ * preview (shot camera, layer 0) still draws the scene with the sculpt in it.
+ * Unmounting (leaving the mode by any route) takes the layer back off.
+ */
+/**
+ * A lump of clay that kneads itself on the turntable while a run has no sculpt
+ * yet: squash and stretch, a slow turn. It says "working" in the viewport.
+ */
+function ClayLump({ at }) {
+	const ref = useRef(null);
+	useFrame(({ clock }) => {
+		const mesh = ref.current;
+		if (!mesh) return;
+		const t = clock.getElapsedTime();
+		const squash = Math.sin(t * 3.2) * 0.12;
+		mesh.scale.set(1 + squash, 1 - squash, 1 + squash * 0.6);
+		mesh.rotation.y = t * 0.8;
+		mesh.position.y = at[1] + 0.32 * (1 - squash);
+	});
+	return (
+		<mesh ref={ref} position={[at[0], at[1] + 0.32, at[2]]} castShadow>
+			<icosahedronGeometry args={[0.32, 5]} />
+			<meshStandardMaterial color="#c99a6e" roughness={0.9} metalness={0} />
+		</mesh>
+	);
+}
+
+// How long a changed part glows after an edit lands.
+const FLASH_MS = 1400;
+
+export function SculptTurntable({ camRef, objects, target, size, view, light = false, busy = false, changedParts = null }) {
+	const { scene, raycaster, invalidate } = useThree();
+	const [camera, setCamera] = useState(null);
+	// The key light aims at the sculpt; its target must sit in the scene graph.
+	const [lightTarget] = useState(() => new THREE.Object3D());
+	const controlsRef = useRef(null);
+	const furnitureRef = useRef(null);
+	const nodesRef = useRef([]);
+	const isolated = isolatedObjectIds(objects, target?.id);
+	const taggedRef = useRef(new Set());
+	const framing = sculptFraming(target ?? EMPTY_TARGET, target ? size : EMPTY_SIZE, view.view, SCULPT_FOV);
+	const floorRadius = Math.max(0.9, framing.radius * 1.1);
+	const tones = light ? TURNTABLE_TONES.light : TURNTABLE_TONES.dark;
+	// Refit on a new target, a view button, or a sculpt that grew or shrank by
+	// a step while a run lands; an orbit in between is the operator's own.
+	const sizeStep = Math.round((size?.height ?? 0) * 4);
+	// While a run works the turntable turns slowly; the operator's first grab stops it for that run.
+	const [grabbed, setGrabbed] = useState(false);
+	useEffect(() => { if (busy) setGrabbed(false); }, [busy]);
+	const spinning = busy && !grabbed;
+	// The canvas draws on demand; a spinning turntable and a kneading lump need frames.
+	useEffect(() => {
+		if (!spinning && !(busy && !target)) return undefined;
+		let frame = requestAnimationFrame(function tick() { invalidate(); frame = requestAnimationFrame(tick); });
+		return () => cancelAnimationFrame(frame);
+	}, [spinning, busy, target, invalidate]);
+	const flashRef = useRef({ nonce: null, startedAt: 0, ids: null });
+	useEffect(() => {
+		if (!changedParts?.nonce || changedParts.nonce === flashRef.current.nonce) return undefined;
+		flashRef.current = { nonce: changedParts.nonce, startedAt: performance.now(), ids: changedParts.ids };
+		let frame = requestAnimationFrame(function tick() {
+			invalidate();
+			if (performance.now() - flashRef.current.startedAt < FLASH_MS + 100) frame = requestAnimationFrame(tick);
+		});
+		return () => cancelAnimationFrame(frame);
+	}, [changedParts?.nonce, invalidate]);
+
+	useLayoutEffect(() => {
+		furnitureRef.current?.traverse((node) => node.layers.set(SCULPT_LAYER));
+	});
+
+	useEffect(() => {
+		const controls = controlsRef.current;
+		if (!camera || !controls) return;
+		camera.position.set(...framing.position);
+		controls.target.set(...framing.target);
+		controls.update();
+		invalidate();
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [camera, target?.id, view.nonce, sizeStep]);
+
+	// Picks follow the picture: nothing hidden can be clicked through.
+	useEffect(() => {
+		const mask = raycaster.layers.mask;
+		raycaster.layers.set(SCULPT_LAYER);
+		return () => { raycaster.layers.mask = mask; };
+	}, [raycaster]);
+
+	useEffect(() => () => {
+		for (const node of taggedRef.current) node.layers.disable(SCULPT_LAYER);
+		taggedRef.current = new Set();
+		invalidate();
+	}, [invalidate]);
+
+	// Priority 0 runs before DualRender (priority 1) draws the frame.
+	useFrame(() => {
+		if (camera) {
+			camera.layers.set(SCULPT_LAYER);
+			fitVisiblePane(camera);
+		}
+		let nodes = nodesRef.current;
+		const stale = nodes.length !== isolated.length
+			|| nodes.some((node) => !isolated.includes(node.userData?.sceneObjectId) || !attached(node, scene));
+		if (stale) nodes = findObjectNodes(scene, isolated);
+		nodesRef.current = nodes;
+		const tagged = new Set();
+		for (const node of nodes) node.traverse((child) => {
+			// Editor chrome under the object (its selection cage) is not on layer 0.
+			if (!child.layers.isEnabled(0)) return;
+			child.layers.enable(SCULPT_LAYER);
+			tagged.add(child);
+		});
+		for (const old of taggedRef.current) if (!tagged.has(old)) old.layers.disable(SCULPT_LAYER);
+		taggedRef.current = tagged;
+		// The parts an edit just touched glow warm and fade (each part owns its material).
+		const flash = flashRef.current;
+		if (flash.nonce !== null) {
+			const age = performance.now() - flash.startedAt;
+			const glow = age < FLASH_MS ? Math.sin(Math.min(1, age / FLASH_MS) * Math.PI) * 0.55 : 0;
+			for (const node of nodes) node.traverse((child) => {
+				const part = child.userData?.sculptPart;
+				if (!part || !child.material?.emissive) return;
+				const hit = flash.ids === "all" || flash.ids?.includes(part);
+				child.material.emissive.setRGB(hit ? glow : 0, hit ? glow * 0.62 : 0, hit ? glow * 0.25 : 0);
+			});
+			if (age >= FLASH_MS) flash.nonce = null;
+		}
+	});
+
+	return (
+		<>
+			<PerspectiveCamera ref={(node) => { camRef.current = node; setCamera(node); }} makeDefault fov={SCULPT_FOV} near={0.05} far={100} />
+			{camera && <OrbitControls ref={controlsRef} camera={camera} enableDamping={false} minDistance={0.3} maxDistance={40} autoRotate={spinning} autoRotateSpeed={1.4}
+				onStart={() => setGrabbed(true)} onChange={() => invalidate()} />}
+			<group ref={furnitureRef}>
+				<hemisphereLight args={["#ffffff", "#3a3c42", 0.9]} />
+				<primitive object={lightTarget} position={framing.target} />
+				<directionalLight
+					target={lightTarget}
+					position={[framing.target[0] + 2.5, framing.floorY + 5, framing.target[2] + 3.5]}
+					intensity={1.6}
+					castShadow
+					shadow-mapSize={[1024, 1024]}
+					shadow-camera-left={-floorRadius}
+					shadow-camera-right={floorRadius}
+					shadow-camera-top={floorRadius}
+					shadow-camera-bottom={-floorRadius}
+				/>
+				{busy && !target && <ClayLump at={[framing.target[0], framing.floorY, framing.target[2]]} />}
+				<mesh rotation-x={-Math.PI / 2} position={[framing.target[0], framing.floorY + 0.001, framing.target[2]]} receiveShadow userData={{ noInk: true }}>
+					<circleGeometry args={[floorRadius, 96]} />
+					<meshStandardMaterial color={tones.floor} roughness={0.95} metalness={0} />
+				</mesh>
+				<mesh rotation-x={-Math.PI / 2} position={[framing.target[0], framing.floorY + 0.002, framing.target[2]]} userData={{ noInk: true }}>
+					<ringGeometry args={[floorRadius * 0.985, floorRadius, 96]} />
+					<meshBasicMaterial color={tones.ring} />
+				</mesh>
+			</group>
+		</>
+	);
+}

package/src/settings-menu.jsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { LOCALE, ko, localeChosen, setLocale } from "./locale.js";
+import { ko, localeChosen } from "./locale.js";
 import PreferencesDialog from "./shell/PreferencesDialog.jsx";
 
 // App settings — language and analytics — behind one labelled topbar trigger