cozyclay 3.2.0 → 3.2.1

package/src/project.js

@@ -25,9 +25,12 @@ export const PROJECT_VERSION = 5;
 export const PREVIS_MODES = Object.freeze(["storyboard", "animation"]);
 export const DEFAULT_PREVIS_MODE = "animation";
 
-export function normalizePrevisMode(value) {
-	return PREVIS_MODES.includes(value) ? value : DEFAULT_PREVIS_MODE;
-}
+export const normalizePrevisMode = (value) => (PREVIS_MODES.includes(value) ? value : DEFAULT_PREVIS_MODE);
+// Which bodies the project is cast with: rigged humanoids for detailed previs,
+// capsule figures for simple previs, or a mix. A file without the field
+// predates the choice and already holds a rig character, so it reads as hybrid.
+export const CAST_STYLES = Object.freeze(["rig", "capsule", "hybrid"]), DEFAULT_CAST_STYLE = "hybrid";
+export const normalizeCastStyle = (value) => (CAST_STYLES.includes(value) ? value : DEFAULT_CAST_STYLE);
 export const PROJECT_EXTENSION = ".cclayproject";
 export const WORKFLOW_VERSION = 1;
 export const WORKFLOW_STORAGE_KEY = "cozyclay.workflow.v1";
@@ -301,7 +304,7 @@ function readEmbeddedAssets(value, report) {
  * assetRef references them. Throws `resources-too-large` when the whole
  * manifest exceeds its budget.
  */
-export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name, previsMode, assets, savedAt, workflow }) {
+export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name, previsMode, castStyle, assets, savedAt, workflow }) {
 	const assetRecords = new Map();
 	for (const record of Array.isArray(assets) ? assets : []) {
 		const asset = embeddedAsset(record);
@@ -323,7 +326,7 @@ export function createProjectDocument({ scenesDocument, workspaceLayout, customP
 		kind: "project",
 		version: PROJECT_VERSION,
 		name: typeof name === "string" && name.trim() ? name.trim() : "Untitled",
-		previsMode: normalizePrevisMode(previsMode),
+		previsMode: normalizePrevisMode(previsMode), castStyle: normalizeCastStyle(castStyle),
 		...(Number.isFinite(savedAt) && savedAt > 0 ? { savedAt } : {}),
 		scenes: scenesDocument,
 		workspace: workspaceLayout ?? null,
@@ -355,7 +358,7 @@ export function buildAnimationProjectFromStoryboard(project) {
 		workspaceLayout: structuredClone(project?.workspaceLayout ?? null),
 		customPoses: structuredClone(project?.customPoses ?? []),
 		name: `${project?.name || "Untitled"} - ${ko("Animation", "애니메이션")}`,
-		previsMode: "animation",
+		previsMode: "animation", castStyle: project?.castStyle,
 				assets: project?.assets ?? [],
 		workflow: structuredClone(project?.workflow ?? createWorkflowGraph()),
 		savedAt: Date.now(),
@@ -367,8 +370,8 @@ export function buildAnimationProjectFromStoryboard(project) {
  * problems?, project? }. Invalid embedded records are skipped, each one
  * reported as a warning string and a `{ kind, id, code, message }` problem.
  * v2/v3 files carry images at the top-level `assets`; v4 moves everything
- * under `resources`; v5 adds the top-level `previsMode` (absent or unknown
- * reads as the default). Older files are read as-is, never rewritten.
+ * under `resources`; v5 adds the top-level `previsMode` and `castStyle`
+ * (absent or unknown reads as the default). Older files are read as-is, never rewritten.
  */
 export function readProjectDocument(raw) {
 	let parsed;
@@ -402,7 +405,7 @@ export function readProjectDocument(raw) {
 		problems,
 		project: {
 			name: typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : "Untitled",
-			previsMode: normalizePrevisMode(parsed.previsMode),
+			previsMode: normalizePrevisMode(parsed.previsMode), castStyle: normalizeCastStyle(parsed.castStyle),
 			savedAt: Number.isFinite(parsed.savedAt) && parsed.savedAt > 0 ? parsed.savedAt : null,
 			scenesDocument: { version: scenes.version, activeSceneId: scenes.activeSceneId ?? null, scenes: scenes.scenes },
 			workspaceLayout: parsed.workspace && typeof parsed.workspace === "object" ? parsed.workspace : null,
@@ -549,17 +552,18 @@ export function loadProjectSession(storage = globalThis.localStorage) {
 		const value = JSON.parse(storage?.getItem(PROJECT_SESSION_KEY) || "null");
 		if (!value || typeof value !== "object") return null;
 		const name = typeof value.name === "string" ? value.name.trim() : "";
-		return name ? { name, previsMode: normalizePrevisMode(value.previsMode), updatedAt: Number.isFinite(value.updatedAt) ? value.updatedAt : 0 } : null;
+		return name ? { name, previsMode: normalizePrevisMode(value.previsMode), castStyle: normalizeCastStyle(value.castStyle), updatedAt: Number.isFinite(value.updatedAt) ? value.updatedAt : 0 } : null;
 	} catch {
 		return null;
 	}
 }
 
-export function storeProjectSession(name, previsMode = DEFAULT_PREVIS_MODE, storage = globalThis.localStorage) {
+// `identity` is the previs mode, or `{ previsMode, castStyle }`.
+export function storeProjectSession(name, identity = DEFAULT_PREVIS_MODE, storage = globalThis.localStorage) {
 	const normalized = typeof name === "string" ? name.trim() : "";
 	if (!normalized) return false;
 	try {
-		storage?.setItem(PROJECT_SESSION_KEY, JSON.stringify({ name: normalized, previsMode: normalizePrevisMode(previsMode), updatedAt: Date.now() }));
+		storage?.setItem(PROJECT_SESSION_KEY, JSON.stringify({ name: normalized, previsMode: normalizePrevisMode(identity?.previsMode ?? identity), castStyle: normalizeCastStyle(identity?.castStyle), updatedAt: Date.now() }));
 		return true;
 	} catch {
 		return false;

package/src/proxy-figure-shape.js

@@ -0,0 +1,11 @@
+// Capsule figure dimensions in metres, shared by the renderer
+// (proxy-figure.jsx) and the rig-free bounds (character-kind.js).
+export const PROXY_BODY_RADIUS = 0.22;
+export const PROXY_BODY_HEIGHT = 1.45;
+export const PROXY_HEAD_RADIUS = 0.12;
+// Head centre sits this far above the top of the body or torso.
+export const PROXY_HEAD_LIFT = 0.13;
+// Sit is an L: a vertical torso at the hip and one leg capsule on the floor
+// reaching this far forward of the hip, along the way the figure faces (+z).
+export const PROXY_SIT_TORSO_HEIGHT = 0.85;
+export const PROXY_SIT_LEG_REACH = 0.55;

package/src/proxy-figure.jsx

@@ -1,10 +1,20 @@
 import { memo, useEffect, useMemo } from "react";
 import * as THREE from "three";
 import { defaultCharacterTint } from "./app-stage.jsx";
+import {
+	PROXY_BODY_HEIGHT as BODY_HEIGHT, PROXY_BODY_RADIUS as BODY_RADIUS, PROXY_HEAD_LIFT,
+	PROXY_HEAD_RADIUS as HEAD_RADIUS, PROXY_SIT_LEG_REACH, PROXY_SIT_TORSO_HEIGHT,
+} from "./proxy-figure-shape.js";
 
-const BODY_RADIUS = 0.22;
-const BODY_HEIGHT = 1.45;
-const HEAD_RADIUS = 0.12;
+function addPart(group, geometry, material, position) {
+	const mesh = new THREE.Mesh(geometry, material);
+	mesh.position.set(...position);
+	mesh.castShadow = true;
+	mesh.receiveShadow = true;
+	mesh.frustumCulled = false;
+	group.add(mesh);
+	return mesh;
+}
 
 export function proxyYaw(rot, posture = "stand") {
 	return (rot * Math.PI) / 180 + (posture === "lie" ? Math.PI : 0);
@@ -19,8 +29,8 @@ export const ProxyFigure = memo(function ProxyFigure({
 	pickId,
 	selected,
 }) {
-	const bodyHeight = posture === "sit" ? BODY_HEIGHT * 0.6 : BODY_HEIGHT;
-	const headY = bodyHeight + 0.13;
+	const seated = posture === "sit";
+	const bodyHeight = seated ? PROXY_SIT_TORSO_HEIGHT : BODY_HEIGHT;
 	const model = useMemo(() => {
 		const bodyMaterial = new THREE.MeshStandardMaterial({
 			color: tint ?? defaultCharacterTint({ model: "proxy-figure" }, 0),
@@ -29,20 +39,17 @@ export const ProxyFigure = memo(function ProxyFigure({
 			envMapIntensity: 0.35,
 		});
 		const group = new THREE.Group();
-		const body = new THREE.Mesh(new THREE.CapsuleGeometry(BODY_RADIUS, bodyHeight - BODY_RADIUS * 2, 12, 20), bodyMaterial);
-		body.position.y = bodyHeight / 2;
-		body.castShadow = true;
-		body.receiveShadow = true;
-		body.frustumCulled = false;
-		group.add(body);
-		const head = new THREE.Mesh(new THREE.SphereGeometry(HEAD_RADIUS, 16, 12), bodyMaterial);
-		head.position.y = headY;
-		head.castShadow = true;
-		head.receiveShadow = true;
-		head.frustumCulled = false;
-		group.add(head);
+		addPart(group, new THREE.CapsuleGeometry(BODY_RADIUS, bodyHeight - BODY_RADIUS * 2, 12, 20), bodyMaterial, [0, bodyHeight / 2, 0]);
+		addPart(group, new THREE.SphereGeometry(HEAD_RADIUS, 16, 12), bodyMaterial, [0, bodyHeight + PROXY_HEAD_LIFT, 0]);
+		if (seated) {
+			// Legs on the floor from behind the hip to PROXY_SIT_LEG_REACH ahead of
+			// it, along local +z: the way the figure (and a rig at the same rot) faces.
+			const legs = addPart(group, new THREE.CapsuleGeometry(BODY_RADIUS, PROXY_SIT_LEG_REACH - BODY_RADIUS, 12, 20), bodyMaterial,
+				[0, BODY_RADIUS, (PROXY_SIT_LEG_REACH - BODY_RADIUS) / 2]);
+			legs.rotation.x = Math.PI / 2;
+		}
 		return group;
-	}, [bodyHeight, headY, tint]);
+	}, [bodyHeight, seated, tint]);
 	useEffect(() => () => {
 		const materials = new Set();
 		model.traverse(node => {

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