cozyclay 3.1.6 → 3.2.1

package/src/scene-assets.js

@@ -19,6 +19,8 @@
  * adapter is the only part that needs a browser.
  */
 import { isHdrAssetId, normalizeHdrAsset } from "./stage-hdr.js";
+// A `sculpt-` id is a sculpt card on the shelf: the user's own library, never swept.
+import { isSculptAssetId, normalizeSculptAsset } from "./sculpt-shelf-file.js";
 
 /** Content-addressed, so the same bytes always land on the same id. */
 export const ASSET_ID_PREFIX = "img-";
@@ -86,7 +88,7 @@ export function isMeshAssetId(value) {
 }
 
 export function isAssetId(value) {
-	return isImageAssetId(value) || isMeshAssetId(value) || isHdrAssetId(value);
+	return isImageAssetId(value) || isMeshAssetId(value) || isHdrAssetId(value) || isSculptAssetId(value);
 }
 
 async function sha256Hex(bytes, subtle) {
@@ -152,6 +154,7 @@ export function normalizeAsset(record) {
 	if (!bytes || !bytes.byteLength) return null;
 	// An `hdr-` id is an HDR environment file (stage-hdr.js), stored verbatim.
 	if (isHdrAssetId(record.id)) return normalizeHdrAsset(record, bytes);
+	if (isSculptAssetId(record.id)) return normalizeSculptAsset(record, bytes);
 	// Prefix and MIME must agree: a mesh id with an image type (or the reverse)
 	// is a cross-wired record and cannot be drawn as either kind.
 	if (isMeshAssetId(record.id)) {
@@ -378,14 +381,23 @@ export async function deleteAssetWithGraphGuard({
 	return false;
 }
 
-/** Stored ids that nothing points at any more, ready to be swept. */
+// Stored ids that nothing points at any more, ready to be swept. A sculpt card
+// is referenced by no scene on purpose: the shelf, not Manage storage, deletes it.
 export function unreachableAssetIds(storedIds, scenes) {
 	const reachable = referencedAssetIds(scenes);
-	return (Array.isArray(storedIds) ? storedIds : []).filter((id) => isAssetId(id) && !reachable.has(id));
+	return (Array.isArray(storedIds) ? storedIds : []).filter((id) => isAssetId(id) && !isSculptAssetId(id) && !reachable.has(id));
 }
 
 /* ------------------------------------------------------------ storage ---- */
 
+// A readwrite transaction settles on complete, error or abort.
+const committed = (tx) =>
+	new Promise((resolve, reject) => {
+		tx.oncomplete = resolve;
+		tx.onerror = () => reject(tx.error);
+		tx.onabort = () => reject(tx.error);
+	});
+
 const request = (req) =>
 	new Promise((resolve, reject) => {
 		req.onsuccess = () => resolve(req.result);
@@ -416,11 +428,7 @@ export async function putAsset(db, record) {
 	if (!asset) throw new TypeError("putAsset needs a normalizable asset record");
 	const tx = db.transaction(ASSET_STORE_NAME, "readwrite");
 	tx.objectStore(ASSET_STORE_NAME).put(asset);
-	await new Promise((resolve, reject) => {
-		tx.oncomplete = resolve;
-		tx.onerror = () => reject(tx.error);
-		tx.onabort = () => reject(tx.error);
-	});
+	await committed(tx);
 	return asset;
 }
 
@@ -440,10 +448,6 @@ export async function deleteAsset(db, id) {
 	if (!isAssetId(id)) return false;
 	const tx = db.transaction(ASSET_STORE_NAME, "readwrite");
 	tx.objectStore(ASSET_STORE_NAME).delete(id);
-	await new Promise((resolve, reject) => {
-		tx.oncomplete = resolve;
-		tx.onerror = () => reject(tx.error);
-		tx.onabort = () => reject(tx.error);
-	});
+	await committed(tx);
 	return true;
 }

package/src/scenes.js

@@ -52,10 +52,12 @@ export function isProxyFigure(character) {
 export const DEFAULT_SUBJECT_ONE = "a young woman in a tan coat";
 export const DEFAULT_SUBJECT_TWO = "a man in a dark coat";
 
+// The one-character cast every scene used to open with. A new scene now
+// starts on an empty stage; legacy documents that never stored a cast, and
+// fixtures that want a body to work with, still seed this one.
+const SEED_CHARACTER = Object.freeze({ id: "char-a", model: DEFAULT_CHARACTER_MODEL, x: 0, z: 0, rot: 0, hidden: false, pose: null, subject: DEFAULT_SUBJECT_ONE });
 const DEFAULT_SCENE_STAGE = Object.freeze({
-	characters: Object.freeze([
-		Object.freeze({ id: "char-a", model: DEFAULT_CHARACTER_MODEL, x: 0, z: 0, rot: 0, hidden: false, pose: null, subject: DEFAULT_SUBJECT_ONE }),
-	]),
+	characters: Object.freeze([]),
 	hasCharSheet: false,
 	// The look reference for the location: a data URL so it survives save/load
 	environmentImage: null,
@@ -241,16 +243,17 @@ function migrateLegacyCast(source) {
 	return cast;
 }
 
-const STAGE_ENVELOPE_KEYS = new Set([
+const LEGACY_CAST_KEYS = Object.freeze(["charA", "charB", "showB", "poseA", "poseB", "subject", "subject2"]), STAGE_ENVELOPE_KEYS = new Set([
 	"characters", "hasCharSheet", "environmentImage", "environment", "style", "hasEnvSheet", "shotAspect", "cameraPresetId", "sensorId", "keyLight", "lighting",
-	"charA", "charB", "showB", "poseA", "poseB", "subject", "subject2",
+	...LEGACY_CAST_KEYS,
 ]);
 
 export function createSceneStage(stage = null) {
 	const source = plainObject(stage) ? stage : {};
-	const characters = Array.isArray(source.characters) && source.characters.length
+	// With no cast list, a pre-v3 envelope folds its fixed cast in; anything else is an empty stage.
+	const characters = Array.isArray(source.characters)
 		? source.characters.map((entry, index) => createCharacterEntry(entry, index))
-		: migrateLegacyCast(source);
+		: LEGACY_CAST_KEYS.some((key) => Object.hasOwn(source, key)) ? migrateLegacyCast(source) : [];
 	// Unknown extra keys (shotAspect was one, once) ride along so the envelope
 	// stays sealed-but-lossless; legacy cast keys are deliberately dropped.
 	const extras = {};
@@ -359,8 +362,13 @@ export function activeScene(scenes, activeSceneId) {
 	return index < 0 ? null : scenes[index];
 }
 
-export function createSceneDocument() {
-	const scene = createScene();
+// The stage a scene opened with before empty stages: one standing Y Bot.
+export const createSeededSceneStage = () => createSceneStage({ characters: [SEED_CHARACTER] });
+
+// A one-scene document on an empty stage. `{ seedCharacter: true }` gives
+// the scene the old one-character cast instead.
+export function createSceneDocument({ seedCharacter = false } = {}) {
+	const scene = { ...createScene(), ...(seedCharacter === true ? { stage: createSeededSceneStage() } : {}) };
 	return { version: SCENES_VERSION, activeSceneId: scene.id, scenes: [scene] };
 }
 
@@ -410,7 +418,8 @@ export function readSceneDocument(raw, legacyRaw = null) {
 			if (!plainObject(legacy) || legacy.version !== 1 || !Array.isArray(legacy.objects)) {
 				return { status: "corrupt", document: createSceneDocument(), dropped: 0, quarantineRaw: legacyRaw };
 			}
-			const document = createSceneDocument();
+			// A v1 scene had no stored cast; it always opened with the seed character.
+			const document = createSceneDocument({ seedCharacter: true });
 			document.scenes[0].objects = legacy.objects.filter(plainObject).map((object) => retireObjectKind(cloneValue(object)));
 			return { status: "migrated", document, dropped: legacy.objects.length - document.scenes[0].objects.length };
 		}
@@ -432,7 +441,9 @@ export function readSceneDocument(raw, legacyRaw = null) {
 	// v4 → v5 needs no step of its own: every cast member passes through
 	// createCharacterEntry, which fills the missing posture with "stand".
 	const legacyClock = payload.version < 4;
-	const repaired = repairDocument(payload, createSceneStage(payload.stage), legacyClock);
+	// Before v3 the cast lived on one global stage, and a document without one
+	// opened with the seed character.
+	const repaired = repairDocument(payload, payload.version < 3 && !plainObject(payload.stage) ? createSeededSceneStage() : createSceneStage(payload.stage), legacyClock);
 	return { status: migrating ? "migrated" : "valid", ...repaired };
 }
 

package/src/sculpt-blueprint.js

@@ -2,6 +2,7 @@
 // reference picture into an orthographic model sheet, the drawing a sculpt is
 // built from. The template names no subject: everything subject-specific comes
 // from the attached reference and the operator's optional notes.
+import { referenceMask } from "./sculpt-compare.js";
 
 /** The sheet's fixed layout, as fractions of the image: a 2 x 2 grid. FRONT and
  * SIDE share the top row so their head and foot lines are the same pixels;
@@ -63,3 +64,58 @@ export function blueprintErrorMessage(error, fallback) {
 	}
 	return fallback;
 }
+
+/** The camera yaw each compared view was drawn from (sculpt-compare.js: 0 in
+ * front, positive toward the subject's own left). TOP looks straight down and is
+ * cropped but not compared: sculpt.compare's elevation stops at 60 degrees. */
+export const BLUEPRINT_VIEW_YAWS = Object.freeze({ front: 0, side: 90, back: 180 });
+
+/** One panel of an RGBA sheet, cut on whole pixels from the layout fractions. */
+export function cropBlueprintPanel(image, { x, y, width, height }) {
+	const left = Math.round(x * image.width), top = Math.round(y * image.height);
+	const w = Math.round((x + width) * image.width) - left, h = Math.round((y + height) * image.height) - top;
+	const data = new Uint8Array(w * h * 4);
+	for (let row = 0; row < h; row += 1) {
+		const start = ((top + row) * image.width + left) * 4;
+		data.set(image.data.subarray(start, start + w * 4), row * w * 4);
+	}
+	return { width: w, height: h, data };
+}
+
+/**
+ * Cut a generated sheet (RGBA) into its views by BLUEPRINT_LAYOUT and mask each
+ * one. A view whose mask fails (no subject, no background, or a subject that
+ * touches the panel edge and so was cut or spills into its neighbour) is dropped
+ * with a notice. Returns { views: [{ view, label, yaw, image, mask }], notices }.
+ */
+export function cropBlueprintViews(sheet, layout = BLUEPRINT_LAYOUT) {
+	const views = [], notices = [];
+	for (const panel of layout) {
+		const image = cropBlueprintPanel(sheet, panel);
+		try {
+			const { width, height, mask, source } = referenceMask(image);
+			let minX = width, maxX = -1, minY = height, maxY = -1;
+			for (let i = 0; i < mask.length; i += 1) if (mask[i]) {
+				const px = i % width, py = (i - px) / width;
+				minX = Math.min(minX, px); maxX = Math.max(maxX, px); minY = Math.min(minY, py); maxY = Math.max(maxY, py);
+			}
+			if (minX === 0 || minY === 0 || maxX === width - 1 || maxY === height - 1) throw new Error("the subject touches the panel edge");
+			const box = { x: minX / width, y: minY / height, width: (maxX - minX + 1) / width, height: (maxY - minY + 1) / height };
+			views.push({ view: panel.view, label: panel.label, yaw: BLUEPRINT_VIEW_YAWS[panel.view] ?? null, image, mask: { source, box } });
+		} catch (error) {
+			notices.push(`${panel.label} view dropped: ${String(error?.message || error).replace(/\.$/, "")}.`);
+		}
+	}
+	return { views, notices };
+}
+
+/** The cropped views of a generated sheet as PNG data URLs, through an image
+ * port ({ decode, encodePng }: commands/sculpt-images.js in the browser). */
+export async function blueprintViewImages(sheetDataUrl, images) {
+	const { views, notices } = cropBlueprintViews(await images.decode({ dataUrl: sheetDataUrl }));
+	return { notices, views: await Promise.all(views.map(async ({ view, label, yaw, image, mask }) => ({ view, label, yaw, mask, width: image.width, height: image.height, dataUrl: await images.encodePng(image) }))) };
+}
+
+/** What a sculpt run takes from a sheet: its side and back views (the front is the reference itself). */
+export const blueprintRunViews = (sheet) => (sheet?.views ?? []).filter((view) => view.view === "side" || view.view === "back")
+	.map(({ view, yaw, dataUrl }) => ({ view, yaw, dataUrl, name: `blueprint-${view}.png` }));

package/src/sculpt-mode.js

@@ -115,6 +115,11 @@ export function sculptAgentClient(transport, readContext) {
  * signed in, or a provider key held by the sidecar). */
 export const agentSessionReady = (status) => Boolean(status?.signedIn || status?.providersConfigured > 0);
 
+/** Whether the sidecar holds a ChatGPT token: /oauth/status `signedIn` is the
+ * ChatGPT login alone (a provider key only counts in providersConfigured). The
+ * blueprint's image model is ChatGPT-only, so its button needs this (#970). */
+export const chatgptSignedIn = (status) => status?.signedIn === true;
+
 /** A stored image asset as a data URL (the bytes the store holds, so the run
  * scores against exactly the stored, possibly downscaled, picture). */
 export function assetDataUrl(asset) {

package/src/sculpt-part-edit.js

@@ -0,0 +1,115 @@
+// The part gizmo's arithmetic (#740 S8). Pure: no React, no DOM. A part's
+// `position` and `rotation` are written in its PARENT's frame (the object
+// frame for a root part), so a gizmo that moves the part in the world is
+// read back through the parent: world = objectWorld × parent × local. A
+// mirrored copy is edited through the part the recipe holds: the copy's own
+// local values reflected across x = 0 of the same frame, which is how
+// expandSculptParts derived the copy in the first place.
+import * as THREE from "three";
+import { SCULPT_MIRROR_SUFFIX, expandSculptParts } from "./sculpt-recipe.js";
+import { tidy } from "./sculpt-recipe-read.js";
+
+const DEG = Math.PI / 180;
+// The recipe keeps 1e-4 (tidy); a field the drag left within that is unchanged.
+const SAME = 1e-4;
+
+const reflect = (local) => ({ position: [-local.position[0], local.position[1], local.position[2]], rotation: [local.rotation[0], -local.rotation[1], -local.rotation[2]] });
+const wrap = (deg) => { const out = ((((deg + 180) % 360) + 360) % 360) - 180; return out === -180 ? 180 : out; };
+const angleGap = (a, b) => Math.abs(wrap(a - b));
+
+/**
+ * Where the selected part is drawn, as the gizmo needs it: the drawn mesh id,
+ * the object-frame matrix of the frame its values are written in (`parent`,
+ * column-major), and its local position, rotation (deg, XYZ) and size. A
+ * mirrored selection gives the copy's frame and values. Null when the recipe
+ * has no such part.
+ */
+export function sculptPartFrame(recipe, selected) {
+	if (!recipe?.parts || !selected?.partId) return null;
+	// A cutter (op) is never drawn, so it has no mesh for the gizmo to sit on (the tree does not offer it).
+	if (recipe.parts.find((part) => part.id === selected.partId)?.op) return null;
+	const drawn = expandSculptParts(recipe);
+	const meshId = selected.mirrored ? `${selected.partId}${SCULPT_MIRROR_SUFFIX}` : selected.partId;
+	const row = drawn.find((entry) => entry.id === meshId);
+	if (!row) return null;
+	const parent = row.parent === undefined ? new THREE.Matrix4().toArray() : drawn.find((entry) => entry.id === row.parent).matrix;
+	return { meshId, parent, position: [...row.position], rotation: [...row.rotation], size: [...row.size] };
+}
+
+/** A local transform (position, rotation in degrees XYZ, scale) as a matrix. */
+function localMatrix({ position, rotation, scale = [1, 1, 1] }) {
+	const quaternion = new THREE.Quaternion().setFromEuler(new THREE.Euler(rotation[0] * DEG, rotation[1] * DEG, rotation[2] * DEG, "XYZ"));
+	return new THREE.Matrix4().compose(new THREE.Vector3(...position), quaternion, new THREE.Vector3(...scale));
+}
+
+/** The world matrix of the frame a part's values are written in: objectWorld × parent. */
+export function partParentWorld(objectWorld, frame) {
+	return objectWorld.clone().multiply(new THREE.Matrix4().fromArray(frame.parent));
+}
+
+/** Parent space → world: the matrix a part with `local` values draws at. */
+export function partWorldMatrix(objectWorld, frame, local = frame) {
+	return partParentWorld(objectWorld, frame).multiply(localMatrix(local));
+}
+
+/** World → parent space: the position, rotation (deg) and scale `world` has in the part's frame. */
+export function partLocalFromWorld(objectWorld, frame, world) {
+	const local = partParentWorld(objectWorld, frame).invert().multiply(world);
+	const position = new THREE.Vector3(), quaternion = new THREE.Quaternion(), scale = new THREE.Vector3();
+	local.decompose(position, quaternion, scale);
+	return partLocalOf({ position, quaternion, scale });
+}
+
+/** An Object3D-like transform (position, quaternion, scale) as recipe-style local values. */
+export function partLocalOf({ position, quaternion, scale }) {
+	const euler = new THREE.Euler().setFromQuaternion(quaternion, "XYZ");
+	return { position: position.toArray(), rotation: [euler.x / DEG, euler.y / DEG, euler.z / DEG], scale: scale.toArray() };
+}
+
+/** Shift's uniform scale: every axis takes the factor of the axis that moved furthest from 1. */
+export function uniformScale(scale) {
+	const lead = scale.reduce((best, value) => (Math.abs(value - 1) > Math.abs(best - 1) ? value : best), 1);
+	return [lead, lead, lead];
+}
+
+/**
+ * The one `object.sculpt` edit a finished drag writes: `{ set: partId,
+ * position?, rotation?, size? }` with only the fields the drag changed, or
+ * null when it changed nothing. `local` is the gizmo's result in the frame
+ * sculptPartFrame gave (scale multiplies the size). A mirrored selection
+ * writes the reflected values onto the part the recipe holds, so the pair
+ * moves together. Nothing is clamped: an undrawable size goes to the command,
+ * which refuses it with the reason.
+ */
+export function sculptPartEdit(recipe, selected, local) {
+	const frame = sculptPartFrame(recipe, selected);
+	if (!frame) return null;
+	const moved = selected.mirrored ? reflect(local) : local;
+	const authored = selected.mirrored ? reflect(frame) : frame;
+	const edit = { set: selected.partId };
+	const position = moved.position.map(tidy);
+	if (position.some((value, axis) => Math.abs(value - authored.position[axis]) >= SAME)) edit.position = position;
+	const rotation = moved.rotation.map((deg) => tidy(wrap(deg)));
+	if (rotation.some((value, axis) => angleGap(value, authored.rotation[axis]) >= SAME)) edit.rotation = rotation;
+	const size = frame.size.map((value, axis) => tidy(value * (local.scale?.[axis] ?? 1)));
+	if (size.some((value, axis) => Math.abs(value - frame.size[axis]) >= SAME)) edit.size = size;
+	return Object.keys(edit).length > 1 ? edit : null;
+}
+
+/**
+ * The drag's live preview without rebuilding geometry: every drawn part's
+ * object-frame matrix after `edit`, and how much the edited part's size
+ * grew per axis (its meshes scale by that until the rebuilt sculpt lands).
+ * `Map(meshId → { matrix, ratio })`.
+ */
+export function previewSculptParts(recipe, edit) {
+	const parts = recipe.parts.map((part) => (part.id === edit?.set ? { ...part, ...edit } : part));
+	const sizes = new Map(recipe.parts.map((part) => [part.id, part.size]));
+	const out = new Map();
+	for (const row of expandSculptParts({ ...recipe, parts })) {
+		const source = row.id.endsWith(SCULPT_MIRROR_SUFFIX) ? row.id.slice(0, -SCULPT_MIRROR_SUFFIX.length) : row.id;
+		const before = sizes.get(source) ?? row.size;
+		out.set(row.id, { matrix: row.matrix, ratio: row.size.map((value, axis) => (before[axis] ? value / before[axis] : 1)) });
+	}
+	return out;
+}

package/src/sculpt-part-gizmo.jsx

@@ -0,0 +1,159 @@
+// The selected sculpt part's gizmo on the turntable (#740 S8). three.js
+// TransformControls drives a proxy that sits in the part's PARENT frame, so
+// its position, rotation and scale read straight back as the recipe's values
+// (sculpt-part-edit.js). While a drag runs, the meshes follow a preview (no
+// geometry rebuild); the drag's end writes one object.sculpt edit, one undo.
+// A refused edit puts the meshes back and the reason shows under the tree.
+// The gizmo lives on SCULPT_LAYER alone: the shot preview and exports never
+// see it, and its picks use the main pane's rect, as part picking does.
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { TransformControls } from "three/examples/jsm/controls/TransformControls.js";
+import { SCULPT_LAYER } from "./sculpt-mode.js";
+import { partLocalOf, partParentWorld, previewSculptParts, sculptPartEdit, sculptPartFrame, uniformScale } from "./sculpt-part-edit.js";
+
+const MODES = { move: "translate", rotate: "rotate", scale: "scale" };
+const DEG = Math.PI / 180;
+
+function partMeshes(nodes) {
+	const meshes = [];
+	for (const node of nodes) node.traverse((child) => { if (child.isMesh && child.userData?.sculptPart) meshes.push(child); });
+	return meshes;
+}
+
+export function SculptPartGizmo({ camera, orbitRef, nodesRef, gizmoRef, recipe, parts }) {
+	const { gl, scene, invalidate } = useThree();
+	const selected = parts?.selected ?? null;
+	const frame = useMemo(() => sculptPartFrame(recipe, selected), [recipe, selected]);
+	const [rig] = useState(() => {
+		const base = new THREE.Object3D();
+		base.matrixAutoUpdate = false;
+		const proxy = new THREE.Object3D();
+		base.add(proxy);
+		return { base, proxy };
+	});
+	const live = useRef(null);
+	useLayoutEffect(() => { live.current = { recipe, selected, commit: parts?.commit }; });
+	// { meshes: [[mesh, position, quaternion, scale]] } while a drag runs; { held } after a write until its recipe lands.
+	const dragRef = useRef(null);
+	// The controls' restore, for the selection effect: a selection change mid-drag (Esc) puts the meshes back first.
+	const restoreRef = useRef(() => {});
+
+	useEffect(() => {
+		if (!camera) return undefined;
+		const made = new TransformControls(camera, gl.domElement);
+		const canvas = gl.domElement, orbit = orbitRef;
+		// The sculpt camera spans the main pane, not the whole canvas.
+		made._getPointer = (event) => {
+			const pane = (document.querySelector(".vp-pane.vp-main") ?? canvas).getBoundingClientRect();
+			return { x: ((event.clientX - pane.left) / pane.width) * 2 - 1, y: -((event.clientY - pane.top) / pane.height) * 2 + 1, button: event.button };
+		};
+		const ray = made.getRaycaster();
+		const mask = ray.layers.mask;
+		ray.layers.set(SCULPT_LAYER);
+		const helper = made.getHelper();
+		helper.traverse((node) => node.layers.set(SCULPT_LAYER));
+		scene.add(rig.base, helper);
+		let shift = false;
+		const restore = () => {
+			for (const [mesh, position, quaternion, scale] of dragRef.current?.meshes ?? []) {
+				mesh.position.copy(position);
+				mesh.quaternion.copy(quaternion);
+				mesh.scale.copy(scale);
+			}
+			dragRef.current = null;
+			invalidate();
+		};
+		restoreRef.current = restore;
+		const editNow = () => {
+			const { recipe: current, selected: part } = live.current;
+			if (made.mode === "scale" && shift) rig.proxy.scale.fromArray(uniformScale(rig.proxy.scale.toArray()));
+			return sculptPartEdit(current, part, partLocalOf(rig.proxy));
+		};
+		const onDown = () => {
+			dragRef.current = { meshes: partMeshes(nodesRef.current).map((mesh) => [mesh, mesh.position.clone(), mesh.quaternion.clone(), mesh.scale.clone()]) };
+		};
+		const onChange = () => {
+			if (!dragRef.current?.meshes) return;
+			const preview = previewSculptParts(live.current.recipe, editNow());
+			const matrix = new THREE.Matrix4();
+			for (const [mesh] of dragRef.current.meshes) {
+				const entry = preview.get(mesh.userData.sculptPart);
+				if (!entry) continue;
+				matrix.fromArray(entry.matrix).decompose(mesh.position, mesh.quaternion, mesh.scale);
+				mesh.scale.fromArray(entry.ratio);
+			}
+			invalidate();
+		};
+		const onUp = () => {
+			if (!dragRef.current?.meshes) return;
+			const edit = editNow();
+			if (edit && live.current.commit?.(edit)) dragRef.current = { held: true };
+			else restore();
+		};
+		const onDragging = (event) => {
+			if (orbitRef.current) orbitRef.current.enabled = !event.value;
+			invalidate();
+		};
+		// A press on a handle must not also start an orbit: the orbit is off before its own listener runs.
+		const onPress = () => { if (made.axis !== null && orbitRef.current) orbitRef.current.enabled = false; };
+		const onRelease = () => { if (!made.dragging && orbitRef.current) orbitRef.current.enabled = true; };
+		const onShift = (event) => { shift = event.shiftKey; };
+		made.addEventListener("mouseDown", onDown);
+		made.addEventListener("objectChange", onChange);
+		made.addEventListener("mouseUp", onUp);
+		made.addEventListener("dragging-changed", onDragging);
+		made.addEventListener("change", invalidate);
+		canvas.addEventListener("pointerdown", onPress, true);
+		window.addEventListener("pointerup", onRelease);
+		window.addEventListener("pointermove", onShift, true);
+		window.addEventListener("keydown", onShift, true);
+		window.addEventListener("keyup", onShift, true);
+		gizmoRef.current = made;
+		return () => {
+			if (dragRef.current?.meshes) restore();
+			canvas.removeEventListener("pointerdown", onPress, true);
+			window.removeEventListener("pointerup", onRelease);
+			window.removeEventListener("pointermove", onShift, true);
+			window.removeEventListener("keydown", onShift, true);
+			window.removeEventListener("keyup", onShift, true);
+			if (orbit.current) orbit.current.enabled = true;
+			gizmoRef.current = null;
+			made.detach();
+			made.dispose();
+			scene.remove(rig.base, helper);
+			ray.layers.mask = mask;
+		};
+	}, [camera, gl, scene, rig, nodesRef, orbitRef, gizmoRef, invalidate]);
+
+	// Declared after the controls' own effect, so they exist when these run.
+	useEffect(() => { gizmoRef.current?.setMode(MODES[parts?.tool] ?? "translate"); invalidate(); }, [camera, gizmoRef, parts?.tool, invalidate]);
+	// A new recipe (the write landed, or any other edit) or selection ends the hold.
+	useEffect(() => {
+		const controls = gizmoRef.current;
+		if (!controls) return;
+		if (dragRef.current?.held) dragRef.current = null;
+		// A drag the selection change interrupted (Esc before the release) writes nothing and puts the meshes back.
+		if (dragRef.current?.meshes) { restoreRef.current(); if (orbitRef.current) orbitRef.current.enabled = true; }
+		if (frame) controls.attach(rig.proxy);
+		else controls.detach();
+		invalidate();
+	}, [camera, gizmoRef, frame, rig, orbitRef, invalidate]);
+
+	// Between drags the proxy follows the part where it is drawn now.
+	useFrame(() => {
+		const controls = gizmoRef.current;
+		if (!controls || !frame || controls.dragging || dragRef.current) return;
+		const mesh = partMeshes(nodesRef.current).find((node) => node.userData.sculptPart === frame.meshId);
+		if (!mesh?.parent) return;
+		mesh.parent.updateWorldMatrix(true, false);
+		rig.base.matrix.copy(partParentWorld(mesh.parent.matrixWorld, frame));
+		rig.base.updateMatrixWorld(true);
+		rig.proxy.position.fromArray(frame.position);
+		rig.proxy.rotation.set(frame.rotation[0] * DEG, frame.rotation[1] * DEG, frame.rotation[2] * DEG, "XYZ");
+		rig.proxy.scale.set(1, 1, 1);
+		rig.proxy.updateMatrixWorld(true);
+	});
+	return null;
+}

package/src/sculpt-part-outline.jsx

@@ -0,0 +1,72 @@
+// The selected sculpt part's highlight on the turntable (#740 S7): per part
+// mesh, an inverted hull pushed out along the normals and drawn back-faces
+// only (a rim of the selection colour), and a thin see-through tint over its
+// visible surface, which still reads where the part sinks into another. The
+// shells live on SCULPT_LAYER alone: the sculpt camera sees them, the shot
+// preview and every export never do.
+import { useEffect, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { SCULPT_LAYER } from "./sculpt-mode.js";
+import { sculptPartMeshIds } from "./sculpt-pick.js";
+
+// The panel's selection colour (--select), so the part and its tree row match;
+// the dark theme's value stands in until the stylesheet is read.
+const OUTLINE_COLOR = "#e8a33d";
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+const RIM_WIDTH = 0.02;
+const TINT_WIDTH = 0.002;
+
+function inflated(width, options) {
+	const material = new THREE.MeshBasicMaterial({ color: OUTLINE_COLOR, ...options });
+	material.onBeforeCompile = (shader) => {
+		shader.vertexShader = shader.vertexShader.replace("#include <begin_vertex>", `#include <begin_vertex>\n\ttransformed += normal * ${width};`);
+	};
+	return material;
+}
+
+function highlightMaterials() {
+	return [
+		inflated(RIM_WIDTH, { side: THREE.BackSide }),
+		inflated(TINT_WIDTH, { transparent: true, opacity: 0.3, depthWrite: false }),
+	];
+}
+
+function shellFor(source, material) {
+	const shell = source.isInstancedMesh ? new THREE.InstancedMesh(source.geometry, material, source.count) : new THREE.Mesh(source.geometry, material);
+	if (source.isInstancedMesh) shell.instanceMatrix = source.instanceMatrix;
+	shell.userData = { source, noInk: true };
+	shell.matrixAutoUpdate = false;
+	shell.frustumCulled = false;
+	// Never a pick target: a click goes through the rim to the part.
+	shell.raycast = () => {};
+	shell.layers.set(SCULPT_LAYER);
+	return shell;
+}
+
+export function SculptPartOutline({ nodesRef, selected }) {
+	const invalidate = useThree((state) => state.invalidate);
+	const [group] = useState(() => new THREE.Group());
+	const [materials] = useState(highlightMaterials);
+	useEffect(() => () => { for (const material of materials) material.dispose(); }, [materials]);
+	const ids = sculptPartMeshIds(selected);
+	const key = ids.join(" ");
+	useEffect(() => {
+		const css = getComputedStyle(document.documentElement).getPropertyValue("--select").trim();
+		for (const material of materials) material.color.set(HEX_COLOR.test(css) ? css : OUTLINE_COLOR);
+		invalidate();
+	}, [key, materials, invalidate]);
+	// The sculpt rebuilds its meshes when the recipe changes, so the shells
+	// follow whichever meshes carry the selected ids this frame.
+	useFrame(() => {
+		const sources = [];
+		for (const node of nodesRef.current) node.traverse((child) => { if (child.isMesh && ids.includes(child.userData?.sculptPart)) sources.push(child); });
+		const shells = group.children;
+		if (shells.length !== sources.length * materials.length || shells.some((shell, index) => shell.userData.source !== sources[Math.floor(index / materials.length)])) {
+			group.clear();
+			for (const source of sources) for (const material of materials) group.add(shellFor(source, material));
+		}
+		for (const shell of group.children) shell.matrix.copy(shell.userData.source.matrixWorld);
+	});
+	return <primitive object={group} />;
+}

package/src/sculpt-pick.js

@@ -0,0 +1,53 @@
+// Part picking in Sculpt mode (#740 S7). Pure: no React, no DOM. A sculpt's
+// meshes carry their part id as `userData.sculptPart` (sculpt-geometry.js); a
+// mirrored copy's id ends in SCULPT_MIRROR_SUFFIX and resolves to the part the
+// recipe actually holds, because that is the part an edit writes.
+import { SCULPT_MIRROR_SUFFIX } from "./sculpt-recipe.js";
+
+/** `{ partId, mirrored }` for a mesh's part id, or null when it has none. */
+function resolveSculptPart(name) {
+	if (typeof name !== "string" || !name) return null;
+	const mirrored = name.endsWith(SCULPT_MIRROR_SUFFIX);
+	return { partId: mirrored ? name.slice(0, -SCULPT_MIRROR_SUFFIX.length) : name, mirrored };
+}
+
+/**
+ * The part nearest along the raycaster's ray among `roots` and their
+ * descendants, or null on a miss. Only meshes tagged as sculpt parts count:
+ * a hit on anything else (the turntable, an outline shell) is passed over.
+ */
+export function pickSculptPart(raycaster, roots) {
+	const hits = raycaster.intersectObjects(roots, true);
+	const hit = hits.find((entry) => entry.object.userData?.sculptPart);
+	return hit ? resolveSculptPart(hit.object.userData.sculptPart) : null;
+}
+
+/**
+ * The recipe's authored parts as an indented tree, parents before children
+ * in recipe order: `{ id, shape, depth, parent, mirror }`. `mirror` is true
+ * when the part is drawn twice, by its own flag or a mirrored ancestor's.
+ */
+export function sculptPartTree(recipe) {
+	const parts = Array.isArray(recipe?.parts) ? recipe.parts : [];
+	const rows = [];
+	const visit = (parent, depth, mirrored) => {
+		for (const part of parts) {
+			if ((part.parent ?? null) !== parent) continue;
+			const mirror = mirrored || part.mirror === true;
+			rows.push({ id: part.id, shape: part.shape, depth, parent, mirror, cutter: Boolean(part.op) });
+			visit(part.id, depth + 1, mirror);
+		}
+	};
+	visit(null, 0, false);
+	return rows;
+}
+
+/** The mesh ids a selected part draws as: the part and its mirrored copy. */
+export function sculptPartMeshIds(selected) {
+	return selected ? [selected.partId, `${selected.partId}${SCULPT_MIRROR_SUFFIX}`] : [];
+}
+
+/** An open menu or modal dialog owns Escape: the part selection waits until it has closed. */
+export function overlayOwnsEscape(root = globalThis.document) {
+	return Boolean(root?.querySelector?.('[role="menu"], [role="dialog"][aria-modal="true"], dialog[open]'));
+}