cozyclay 3.2.0 → 3.2.1

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

package/src/sculpt-run-text.js

@@ -0,0 +1,51 @@
+// The text of a sculpt run's turns (sculpt-run.js): the first turn's draft
+// request, each refinement round's request, and the recipe rules both carry.
+
+// The reference as sculpt.compare takes it: the stored asset when there is one.
+export 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, lathe, tube, extrude, loft, convex, scatter (no cone, sphere or other names): lathe { \"profile\": [[r 0-1, y 0-1], ...] } for turned forms (pot, bottle, bowl), tube { \"path\": [[x,y,z] each -0.5..0.5 of size], \"thickness\" m } for ropes, tails, handles and limbs that bend, extrude { \"outline\": [[x,y] -0.5..0.5] } for flat cut shapes (ears, fins, leaves, signs), loft { \"sections\": [{ \"y\", \"w\", \"d\" }, ...] } for bodies whose cross-section changes, convex { \"seed\" } for rocks. Any part may add \"detail\": { \"amount\": 0-1 } for a lumpy surface, \"gradient\": { \"color\" } for a two-tone blend, or \"op\": \"subtract\" to cut its parent (a mouth, a hollow). 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, box and extrude, taper only on blob, cylinder and tube: leave both off the other shapes. 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.`;
+}
+
+// The blueprint views attached after the reference (#970), named the way sculpt.compare reads yaw.
+const VIEW_WORDS = { side: "camera on the subject's own left, so it faces image left", back: "camera behind the subject" };
+function viewsText(views) {
+	if (!views?.length) return "";
+	return ` Also attached, after the reference: the blueprint's ${views.map(view => `${view.view} view (yaw ${view.yaw}, ${VIEW_WORDS[view.view] ?? "orthographic"})`).join(" and ")}. Take depth and what the front hides from them; the harness scores against the front and these views together, by weight.`;
+}
+
+export function makeTurnText(reference, sculptId, continuation, outline = null, views = []) {
+	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${views.length ? ` and the blueprint's ${views.map(view => view.view).join(" and ")} views (weighted)` : ""}.${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.${viewsText(views)}`,
+		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(" ");
+}

package/src/sculpt-run.js

@@ -1,3 +1,5 @@
+import { makeTurnText, referenceArg } from "./sculpt-run-text.js";
+
 const INITIAL_MESSAGE = "Measure the reference landmarks before placing parts.";
 
 const initialState = ({ targetIou, maxRounds }) => ({
@@ -45,48 +47,6 @@ function dataUrlFromSheet(sheet) {
 	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, lathe, tube, extrude, loft, convex, scatter (no cone, sphere or other names): lathe { \"profile\": [[r 0-1, y 0-1], ...] } for turned forms (pot, bottle, bowl), tube { \"path\": [[x,y,z] each -0.5..0.5 of size], \"thickness\" m } for ropes, tails, handles and limbs that bend, extrude { \"outline\": [[x,y] -0.5..0.5] } for flat cut shapes (ears, fins, leaves, signs), loft { \"sections\": [{ \"y\", \"w\", \"d\" }, ...] } for bodies whose cross-section changes, convex { \"seed\" } for rocks. Any part may add \"detail\": { \"amount\": 0-1 } for a lumpy surface, \"gradient\": { \"color\" } for a two-tone blend, or \"op\": \"subtract\" to cut its parent (a mouth, a hollow). 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, box and extrude, taper only on blob, cylinder and tube: leave both off the other shapes. 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.
@@ -131,6 +91,8 @@ export function createSculptRun({
 	score = null,
 	// Optional (reference) -> measureReferenceOutline result, put into the first turn's text.
 	measure = null,
+	// The blueprint's cropped views ([{ view, yaw, dataUrl, name? }], #970): attached next to the reference and scored with it.
+	views = [],
 	// 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,
@@ -252,7 +214,8 @@ export function createSculptRun({
 		};
 		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);
+		const attachments = [...(reference?.dataUrl ? [{ dataUrl: reference.dataUrl, name: reference.name }] : []), ...views.map(view => ({ dataUrl: view.dataUrl, name: view.name ?? `blueprint-${view.view}.png` }))];
+		const returned = agent.sendTurn({ turnId, text, attachments, signal: controller.signal, ...(model ? { model } : {}), ...(effort ? { effort } : {}) }, callback);
 		if (isAsyncIterable(returned)) {
 			for await (const event of returned) callback(event);
 		} else await returned;
@@ -274,7 +237,8 @@ export function createSculptRun({
 			} 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);
+		if (views.length) note("ok", `Using the blueprint's ${views.map(view => view.view).join(" and ")} view${views.length > 1 ? "s" : ""} next to the reference`);
+		let text = makeTurnText(reference, sculptId, false, outline, views);
 		while (!controller.signal.aborted) {
 			if (elapsed() >= timeBudgetMs) break;
 			const roundBefore = state.round;
@@ -304,7 +268,7 @@ export function createSculptRun({
 			}
 			retryCount = 0;
 			if (!turnScored && score && state.sculptId) {
-				const args = { id: state.sculptId, reference: referenceArg(reference) };
+				const args = views.length ? { id: state.sculptId, views: [{ yaw: 0, reference: referenceArg(reference) }, ...views.map(view => ({ yaw: view.yaw, reference: { dataUrl: view.dataUrl } }))] } : { id: state.sculptId, reference: referenceArg(reference) };
 				publish({ waiting: waitFor("score", "Scoring the silhouette against the reference") });
 				try {
 					const value = await score(args);
@@ -319,7 +283,7 @@ export function createSculptRun({
 			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 });
+			text = makeTurnText(reference, state.sculptId, { round: nextRound, maxRounds, iou: state.iou, report: lastReport }, null, views);
 		}
 		if (controller.signal.aborted) {
 			note("warn", "Cancelled", { stage: "cancelled", message: "Sculpt run cancelled.", waiting: null });

package/src/sculpt-shelf-file.js

@@ -0,0 +1,92 @@
+// A sculpt card on the asset shelf (#740 S9 + S13), and the `.cozysculpt.json`
+// file that carries one between browsers. Pure: no IndexedDB, no three.js, so
+// scene-assets.js, the node tests and the shelf all read one truth.
+//
+// A card is a record in the shared asset store (`cozyclay.assets`) under a
+// `sculpt-` id. Its bytes ARE the file: the UTF-8 JSON
+//   { "format": "cozysculpt", "version": 1, "name", "recipe", "thumb"? }
+// so export writes the stored bytes and import stores what it parsed. The id is
+// the SHA-256 of the normalized recipe, so saving the same sculpt twice keeps
+// one card (the later name and thumbnail win). The store is origin-wide, so a
+// card shows in every project; it is never part of a project export.
+import { normalizeSculptRecipe } from "./sculpt-recipe.js";
+
+const SCULPT_CARD_FORMAT = "cozysculpt";
+const SCULPT_CARD_VERSION = 1;
+export const SCULPT_CARD_TYPE = "application/vnd.cozyclay.sculpt+json";
+export const SCULPT_FILE_SUFFIX = ".cozysculpt.json";
+const SCULPT_ID = /^sculpt-[0-9a-f]{32}$/;
+// A card file is a recipe and a 256 px picture; anything far bigger is not one.
+const MAX_FILE_CHARS = 4 * 1024 * 1024;
+const MAX_THUMB_CHARS = 1024 * 1024;
+const THUMB = /^data:image\/(png|jpeg|webp);base64,[A-Za-z0-9+/]+=*$/;
+const MAX_NAME = 120;
+
+export const isSculptAssetId = (value) => typeof value === "string" && SCULPT_ID.test(value);
+
+const cleanName = (name) => (typeof name === "string" ? name.trim().slice(0, MAX_NAME) : "");
+const cleanThumb = (thumb) => (typeof thumb === "string" && thumb.length <= MAX_THUMB_CHARS && THUMB.test(thumb) ? thumb : null);
+
+/** The `.cozysculpt.json` text of a card. Throws when the recipe is refused. */
+export function serializeCard({ name, recipe, thumb = null }) {
+	const normalized = normalizeSculptRecipe(recipe);
+	if (!normalized.ok) throw new TypeError(`Recipe refused at ${normalized.error}`);
+	const picture = cleanThumb(thumb);
+	return JSON.stringify({ format: SCULPT_CARD_FORMAT, version: SCULPT_CARD_VERSION, name: cleanName(name) || "Sculpt", recipe: normalized.recipe, ...(picture ? { thumb: picture } : {}) });
+}
+
+/**
+ * Read a `.cozysculpt.json` text: { ok: true, card: { name, recipe, thumb } }
+ * or { ok: false, error } with a sentence for the user. The recipe is checked
+ * as a whole, never repaired; a bad thumbnail is dropped, not fatal.
+ */
+export function parseCard(text) {
+	if (typeof text !== "string" || !text.trim()) return { ok: false, error: "the file is empty" };
+	if (text.length > MAX_FILE_CHARS) return { ok: false, error: "the file is too large to be a sculpt card" };
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		return { ok: false, error: "the file is not JSON" };
+	}
+	if (!data || typeof data !== "object" || Array.isArray(data) || data.format !== SCULPT_CARD_FORMAT) return { ok: false, error: "the file is not a .cozysculpt.json sculpt card" };
+	if (data.version !== SCULPT_CARD_VERSION) return { ok: false, error: `card version ${JSON.stringify(data.version)} is not supported (expected ${SCULPT_CARD_VERSION})` };
+	const normalized = normalizeSculptRecipe(data.recipe);
+	if (!normalized.ok) return { ok: false, error: `the recipe is refused at ${normalized.error}` };
+	return { ok: true, card: { name: cleanName(data.name) || "Sculpt", recipe: normalized.recipe, thumb: cleanThumb(data.thumb) } };
+}
+
+async function sha256Hex(text, subtle) {
+	if (!subtle?.digest) throw new Error("SubtleCrypto is unavailable — a secure context is required to save a sculpt card");
+	const digest = await subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** The asset-store record of a card: the file text as bytes, under its recipe's id. */
+export async function sculptCardRecord(card, subtle = globalThis.crypto?.subtle) {
+	const text = serializeCard(card);
+	const { name, recipe } = JSON.parse(text);
+	const id = `sculpt-${(await sha256Hex(JSON.stringify(recipe), subtle)).slice(0, 32)}`;
+	const bytes = new TextEncoder().encode(text);
+	return { id, type: SCULPT_CARD_TYPE, name, bytes: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) };
+}
+
+/** normalizeAsset's branch for a `sculpt-` id: the bytes must parse as a card. */
+export function normalizeSculptAsset(record, bytes) {
+	if (record.type !== SCULPT_CARD_TYPE) return null;
+	const parsed = parseCard(new TextDecoder().decode(bytes));
+	return parsed.ok ? { id: record.id, type: SCULPT_CARD_TYPE, bytes, name: parsed.card.name } : null;
+}
+
+/** A stored card record as the shelf shows it, or null when it does not read. */
+export function readSculptCard(record) {
+	if (!isSculptAssetId(record?.id) || !(record.bytes instanceof ArrayBuffer)) return null;
+	const parsed = parseCard(new TextDecoder().decode(record.bytes));
+	return parsed.ok ? { id: record.id, ...parsed.card } : null;
+}
+
+/** A file name for the card's export: its name, kept to safe characters. */
+export function sculptCardFileName(name) {
+	const stem = cleanName(name).replace(/[^\p{L}\p{N} _-]+/gu, "").trim().replace(/\s+/g, "-") || "sculpt";
+	return `${stem}${SCULPT_FILE_SUFFIX}`;
+}

package/src/sculpt-shelf-tiles.jsx

@@ -0,0 +1,69 @@
+// The Content pane's Sculpts folder (#740 S9 + S13): one tile per sculpt card
+// on the shelf (sculpt-shelf.js). A tile drags into the scene like any other
+// asset and carries its recipe, so a drop needs no store read. A selected card
+// can be exported as `.cozysculpt.json` or deleted; Import (or dropping card
+// files on the folder) brings cards in.
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { ko } from "./locale.js";
+import { ContentTile, grabProps } from "./content-tile.jsx";
+import { SearchEmpty } from "./search-friction.js";
+import { deleteSculptCard, exportSculptCard, importSculptCardFiles, refreshSculptShelf, sculptShelfCards, subscribeSculptShelf } from "./sculpt-shelf.js";
+import { SCULPT_FILE_SUFFIX } from "./sculpt-shelf-file.js";
+
+const sculptKey = (id) => `sculpt:${id}`;
+
+export default function SculptShelf({ query, selectedKey, onSelect, onAssetGrab, onAssetPlace }) {
+	const cards = useSyncExternalStore(subscribeSculptShelf, sculptShelfCards, sculptShelfCards);
+	const [note, setNote] = useState("");
+	const [confirmDelete, setConfirmDelete] = useState(null);
+	const fileRef = useRef(null);
+	useEffect(() => { void refreshSculptShelf(); }, []);
+	const selected = cards?.find((card) => sculptKey(card.id) === selectedKey) ?? null;
+	const visible = (cards ?? []).filter((card) => !query || card.name.toLowerCase().includes(query));
+	const importFiles = async (files) => setNote(await importSculptCardFiles(files));
+	const tiles = cards === null
+		? [0, 1, 2].map((n) => <span className="content-tile is-loading" key={`loading-${n}`} aria-hidden="true"><span className="content-tile-thumb"><span className="content-tile-skeleton" /></span></span>)
+		: visible.map((card) => {
+			const key = sculptKey(card.id);
+			const payload = { kind: "sculpt", id: card.id, label: card.name, name: card.name, recipe: card.recipe, thumb: card.thumb };
+			return (
+				<ContentTile key={key} assetKey={key} label={card.name} type={ko("Sculpt", "조형물", "雕塑")}
+					title={ko(`Drag ${card.name} into the scene, or double-click to place it at the origin`, `${card.name}을(를) 씬에 드래그하거나 더블클릭해 원점에 놓으세요`, `将 ${card.name} 拖入场景，或双击将其放在原点`)}
+					preview={card.thumb ? <img className="content-tile-img" src={card.thumb} alt="" draggable={false} /> : <span className="content-tile-skeleton" aria-hidden="true" />}
+					selected={selectedKey === key} onSelect={onSelect} grab={grabProps(onAssetGrab, payload)} onPlace={() => onAssetPlace?.(payload)} />
+			);
+		});
+	return (
+		<div className="sculpt-shelf" data-testid="sculpt-shelf"
+			onDragOver={(event) => { if (event.dataTransfer?.types?.includes("Files")) event.preventDefault(); }}
+			onDrop={(event) => {
+				const files = [...(event.dataTransfer?.files ?? [])].filter((file) => file.name.toLowerCase().endsWith(".json"));
+				if (!files.length) return;
+				event.preventDefault();
+				event.stopPropagation();
+				void importFiles(files);
+			}}>
+			<div className="sculpt-shelf-actions">
+				<button type="button" data-testid="sculpt-shelf-import" onClick={() => fileRef.current?.click()}>{ko("Import…", "가져오기…", "导入…")}</button>
+				<input ref={fileRef} type="file" hidden multiple accept={`${SCULPT_FILE_SUFFIX},.json,application/json`} data-testid="sculpt-shelf-file"
+					onChange={(event) => { const files = [...event.target.files]; event.target.value = ""; void importFiles(files); }} />
+				{selected && <>
+					<button type="button" data-testid="sculpt-shelf-export" onClick={async () => setNote(await exportSculptCard(selected))}>{ko("Export", "내보내기", "导出")}</button>
+					{confirmDelete === selected.id ? <>
+						<button type="button" className="sculpt-shelf-delete" data-testid="sculpt-shelf-delete-confirm"
+							onClick={async () => { setConfirmDelete(null); onSelect(null); await deleteSculptCard(selected.id); setNote(ko(`Deleted ${selected.name} from the shelf`, `${selected.name} 선반에서 삭제함`, `已从架子删除 ${selected.name}`)); }}>
+							{ko(`Delete ${selected.name}?`, `${selected.name} 삭제할까요?`, `删除 ${selected.name}？`)}
+						</button>
+						<button type="button" onClick={() => setConfirmDelete(null)}>{ko("Cancel", "취소")}</button>
+					</> : <button type="button" data-testid="sculpt-shelf-delete" onClick={() => setConfirmDelete(selected.id)}>{ko("Delete", "삭제")}</button>}
+				</>}
+				{note && <span className="sculpt-shelf-note" role="status" data-testid="sculpt-shelf-note">{note}</span>}
+			</div>
+			{cards !== null && !cards.length
+				? <p className="content-empty">{ko("No sculpts on the shelf yet. Press Save to shelf in Sculpt mode (5), or import a .cozysculpt.json.", "선반에 조형물이 아직 없어요. 조형 모드(5)에서 선반에 저장을 누르거나 .cozysculpt.json을 가져오세요.")}</p>
+				: query && !visible.length
+					? <SearchEmpty surface="assets" query={query}><p className="content-empty">{ko("Nothing matches this search.", "검색 결과가 없어요.")}</p></SearchEmpty>
+					: <div className="content-grid" role="list">{tiles}</div>}
+		</div>
+	);
+}