cozyclay 3.1.6 → 3.2.1

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

package/src/sculpt-shelf.js

@@ -0,0 +1,108 @@
+// The sculpt shelf (#740 S9 + S13): sculpt cards in the shared asset store
+// (`cozyclay.assets`, scene-assets.js) under `sculpt-` ids. The store belongs to
+// this browser, not to a project, so every project and every scene sees the
+// same cards: that is the cross-project library. Nothing here leaves the
+// machine; a card travels only as a `.cozysculpt.json` the user saves.
+//
+// The Content pane's Sculpts folder subscribes here; Save to shelf, import and
+// delete publish the new list. `openDb` is injectable for the node tests.
+import { deleteAsset, getAsset, listAssetIds, openAssetDb, putAsset } from "./scene-assets.js";
+import { isSculptAssetId, parseCard, readSculptCard, sculptCardFileName, sculptCardRecord, SCULPT_CARD_TYPE } from "./sculpt-shelf-file.js";
+import { renderSculptThumb } from "./sculpt-thumb.js";
+import { saveExport } from "./export-workspace.js";
+import { ko } from "./locale.js";
+
+const listeners = new Set();
+// null until the first read: the folder shows skeletons, not "no cards".
+let cards = null;
+
+function publish(next) {
+	cards = Object.freeze(next);
+	for (const listener of listeners) listener();
+}
+
+/** The cards, newest name order: [{ id, name, recipe, thumb }] or null before the first read. */
+export const sculptShelfCards = () => cards;
+export function subscribeSculptShelf(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+async function withDb(openDb, work) {
+	const db = await openDb();
+	try {
+		return await work(db);
+	} finally {
+		db?.close?.();
+	}
+}
+
+/** Re-read every card from the store. Without IndexedDB the shelf is empty. */
+export async function refreshSculptShelf({ openDb = openAssetDb } = {}) {
+	try {
+		const read = await withDb(openDb, async (db) => {
+			const ids = (await listAssetIds(db)).filter(isSculptAssetId);
+			return (await Promise.all(ids.map((id) => getAsset(db, id)))).map(readSculptCard).filter(Boolean);
+		});
+		publish(read.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id)));
+	} catch {
+		publish([]);
+	}
+	return cards;
+}
+
+/** Store one card { name, recipe, thumb }; the same recipe overwrites its card. Answers its id. */
+export async function putSculptCard(card, { openDb = openAssetDb, subtle } = {}) {
+	const record = await sculptCardRecord(card, subtle);
+	await withDb(openDb, (db) => putAsset(db, record));
+	await refreshSculptShelf({ openDb });
+	return record.id;
+}
+
+export async function deleteSculptCard(id, { openDb = openAssetDb } = {}) {
+	if (!isSculptAssetId(id)) return false;
+	await withDb(openDb, (db) => deleteAsset(db, id));
+	await refreshSculptShelf({ openDb });
+	return true;
+}
+
+/** The stored `.cozysculpt.json` text of a card, or null when it is gone. */
+async function sculptCardText(id, { openDb = openAssetDb } = {}) {
+	const record = await withDb(openDb, (db) => getAsset(db, id));
+	return record ? new TextDecoder().decode(record.bytes) : null;
+}
+
+/** Sculpt panel's Save to shelf: a copy of the recipe, its name and a thumbnail. Answers a toast line. */
+export async function saveSculptToShelf(sculpt, { openDb = openAssetDb, renderThumb = renderSculptThumb } = {}) {
+	if (!sculpt?.recipe) return ko("Select a sculpt to save it to the shelf.", "선반에 저장할 조형물을 선택하세요.");
+	try {
+		const thumb = await renderThumb(sculpt.recipe);
+		await putSculptCard({ name: sculpt.name, recipe: sculpt.recipe, thumb }, { openDb });
+		return ko(`${sculpt.name} saved to the shelf — Content › Sculpts`, `${sculpt.name} 선반에 저장됨 — 콘텐츠 › 조형물`, `${sculpt.name} 已保存到架子 — 内容 › 雕塑`);
+	} catch (error) {
+		return ko(`Could not save to the shelf: ${error.message}`, `선반에 저장하지 못했어요: ${error.message}`, `无法保存到架子：${error.message}`);
+	}
+}
+
+/** Import `.cozysculpt.json` files as cards. Answers a toast line naming what came in or why not. */
+export async function importSculptCardFiles(files, { openDb = openAssetDb } = {}) {
+	const names = [], problems = [];
+	for (const file of Array.from(files ?? [])) {
+		const parsed = parseCard(await file.text());
+		if (!parsed.ok) problems.push(`${file.name}: ${parsed.error}`);
+		else {
+			await putSculptCard(parsed.card, { openDb });
+			names.push(parsed.card.name);
+		}
+	}
+	if (problems.length) return ko(`Not imported — ${problems.join("; ")}`, `가져오지 못했어요 — ${problems.join("; ")}`, `未导入 — ${problems.join("; ")}`);
+	return names.length ? ko(`Imported ${names.join(", ")}`, `가져옴: ${names.join(", ")}`, `已导入 ${names.join("、")}`) : "";
+}
+
+/** Save one card as `<name>.cozysculpt.json` through the export workspace (or a download). */
+export async function exportSculptCard(card, { openDb = openAssetDb } = {}) {
+	const text = await sculptCardText(card.id, { openDb });
+	if (!text) return ko("That card is no longer on the shelf.", "이 카드는 이미 선반에 없어요.");
+	const result = await saveExport(new Blob([text], { type: SCULPT_CARD_TYPE }), sculptCardFileName(card.name));
+	return ko(`Saved ${result.name ?? sculptCardFileName(card.name)}`, `${result.name ?? sculptCardFileName(card.name)} 저장됨`, `已保存 ${result.name ?? sculptCardFileName(card.name)}`);
+}

package/src/sculpt-stage.jsx

@@ -5,6 +5,9 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { OrbitControls, PerspectiveCamera } from "@react-three/drei";
 import * as THREE from "three";
 import { SCULPT_LAYER, isolatedObjectIds, sculptFraming } from "./sculpt-mode.js";
+import { pickSculptPart } from "./sculpt-pick.js";
+import { SculptPartOutline } from "./sculpt-part-outline.jsx";
+import { SculptPartGizmo } from "./sculpt-part-gizmo.jsx";
 
 const SCULPT_FOV = 35;
 // Where a new sculpt lands (object.sculpt without placement): the origin.
@@ -87,9 +90,11 @@ function ClayLump({ at }) {
 
 // How long a changed part glows after an edit lands.
 const FLASH_MS = 1400;
+// A press that travels further than this is an orbit, not a click.
+const CLICK_SLOP_PX = 4;
 
-export function SculptTurntable({ camRef, objects, target, size, view, light = false, busy = false, changedParts = null }) {
-	const { scene, raycaster, invalidate } = useThree();
+export function SculptTurntable({ camRef, objects, target, size, view, light = false, busy = false, changedParts = null, parts = null }) {
+	const { scene, raycaster, invalidate, gl } = useThree();
 	const [camera, setCamera] = useState(null);
 	// The key light aims at the sculpt; its target must sit in the scene graph.
 	const [lightTarget] = useState(() => new THREE.Object3D());
@@ -146,6 +151,36 @@ export function SculptTurntable({ camRef, objects, target, size, view, light = f
 		return () => { raycaster.layers.mask = mask; };
 	}, [raycaster]);
 
+	// Part picking (#740 S7): a left click (not an orbit drag) on the sculpt
+	// selects the part under it, on empty space clears. The pointer maps into
+	// the main pane, the rect the sculpt camera's projection spans.
+	const partsRef = useRef(parts);
+	partsRef.current = parts;
+	const [pickRay] = useState(() => { const ray = new THREE.Raycaster(); ray.layers.set(SCULPT_LAYER); return ray; });
+	// The part gizmo's controls (#740 S8): a still click on one of its handles
+	// picks the part under it, but never clears the selection.
+	const gizmoRef = useRef(null);
+	useEffect(() => {
+		if (!camera) return undefined;
+		const canvas = gl.domElement;
+		let down = null;
+		const onDown = (event) => { down = event.button === 0 && event.target === canvas ? [event.clientX, event.clientY, Boolean(gizmoRef.current?.axis)] : null; };
+		const onUp = (event) => {
+			const start = down;
+			down = null;
+			if (!start || !partsRef.current?.onSelect || Math.hypot(event.clientX - start[0], event.clientY - start[1]) > CLICK_SLOP_PX) return;
+			const pane = (document.querySelector(".vp-pane.vp-main") ?? canvas).getBoundingClientRect();
+			if (pane.width < 2 || pane.height < 2) return;
+			camera.updateMatrixWorld();
+			pickRay.setFromCamera(new THREE.Vector2(((event.clientX - pane.left) / pane.width) * 2 - 1, -((event.clientY - pane.top) / pane.height) * 2 + 1), camera);
+			const hit = pickSculptPart(pickRay, nodesRef.current);
+			if (hit || !start[2]) partsRef.current.onSelect(hit);
+		};
+		canvas.addEventListener("pointerdown", onDown);
+		window.addEventListener("pointerup", onUp);
+		return () => { canvas.removeEventListener("pointerdown", onDown); window.removeEventListener("pointerup", onUp); };
+	}, [camera, gl, pickRay]);
+
 	useEffect(() => () => {
 		for (const node of taggedRef.current) node.layers.disable(SCULPT_LAYER);
 		taggedRef.current = new Set();
@@ -192,6 +227,8 @@ export function SculptTurntable({ camRef, objects, target, size, view, light = f
 			<PerspectiveCamera ref={(node) => { camRef.current = node; setCamera(node); }} makeDefault fov={SCULPT_FOV} near={0.05} far={100} />
 			{camera && <OrbitControls ref={controlsRef} camera={camera} enableDamping={false} minDistance={0.3} maxDistance={40} autoRotate={spinning} autoRotateSpeed={1.4}
 				onStart={() => setGrabbed(true)} onChange={() => invalidate()} />}
+			<SculptPartOutline nodesRef={nodesRef} selected={parts?.selected ?? null} />
+			<SculptPartGizmo camera={camera} orbitRef={controlsRef} nodesRef={nodesRef} gizmoRef={gizmoRef} recipe={target?.recipe} parts={parts} />
 			<group ref={furnitureRef}>
 				<hemisphereLight args={["#ffffff", "#3a3c42", 0.9]} />
 				<primitive object={lightTarget} position={framing.target} />

package/src/sculpt-thumb.js

@@ -0,0 +1,72 @@
+// The sculpt card's picture (#740 S9): one 256 px frame of the recipe from the
+// front three-quarter view, the turntable's look without the turntable. The
+// camera fit is pure (sculptThumbCamera, node-tested); the render needs WebGL.
+//
+// Each render gets its own small WebGLRenderer and loses its context right
+// after, so a save never holds a second context next to the viewport's. Renders
+// are serialized: two quick saves never build two scatter-heavy groups at once.
+import * as THREE from "three";
+import { buildSculptGroup, disposeSculptGroup } from "./sculpt-geometry.js";
+
+const SCULPT_THUMB_SIZE = 256;
+// Target values: SCULPT_VIEWS (sculpt-mode.js) has front, side and back only.
+const THUMB_YAW = 35;
+const THUMB_ELEVATION = 15;
+const THUMB_FOV = 30;
+
+/**
+ * Where the thumbnail camera stands for a bounding box { min: [x,y,z], max }.
+ * Yaw turns toward the subject's own left (+x) from the front (+z), elevation
+ * lifts it; the distance fits the box's bounding sphere inside the field of
+ * view with a small margin, so any recipe size fills the same frame.
+ */
+export function sculptThumbCamera(box, { yaw = THUMB_YAW, elevation = THUMB_ELEVATION, fov = THUMB_FOV } = {}) {
+	const min = box?.min ?? [0, 0, 0], max = box?.max ?? [0, 0, 0];
+	const target = [0, 1, 2].map((axis) => (min[axis] + max[axis]) / 2);
+	const radius = Math.max(0.05, Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) / 2);
+	const distance = (radius / Math.sin(THREE.MathUtils.degToRad(fov) / 2)) * 1.08;
+	const y = THREE.MathUtils.degToRad(yaw), e = THREE.MathUtils.degToRad(elevation);
+	const position = [target[0] + distance * Math.sin(y) * Math.cos(e), target[1] + distance * Math.sin(e), target[2] + distance * Math.cos(y) * Math.cos(e)];
+	return { position, target, fov, near: Math.max(0.01, distance - radius * 2), far: distance + radius * 2 };
+}
+
+let queue = Promise.resolve();
+
+function renderNow(recipe) {
+	const canvas = document.createElement("canvas");
+	canvas.width = SCULPT_THUMB_SIZE;
+	canvas.height = SCULPT_THUMB_SIZE;
+	const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true, preserveDrawingBuffer: true });
+	const group = buildSculptGroup(recipe);
+	try {
+		renderer.setSize(SCULPT_THUMB_SIZE, SCULPT_THUMB_SIZE, false);
+		renderer.setClearColor(0x000000, 0);
+		renderer.outputColorSpace = THREE.SRGBColorSpace;
+		const scene = new THREE.Scene();
+		scene.add(new THREE.HemisphereLight(0xfff6ea, 0x5a5048, 1.6));
+		const key = new THREE.DirectionalLight(0xffffff, 2.2);
+		key.position.set(2, 4, 3);
+		scene.add(key, group);
+		const box = new THREE.Box3().setFromObject(group);
+		const fit = sculptThumbCamera(box.isEmpty() ? null : { min: box.min.toArray(), max: box.max.toArray() });
+		const camera = new THREE.PerspectiveCamera(fit.fov, 1, fit.near, fit.far);
+		camera.position.fromArray(fit.position);
+		camera.lookAt(...fit.target);
+		renderer.render(scene, camera);
+		return canvas.toDataURL("image/png");
+	} finally {
+		disposeSculptGroup(group);
+		renderer.dispose();
+		renderer.forceContextLoss();
+	}
+}
+
+/** A PNG data URL of the recipe, or null when this browser cannot draw it. */
+export function renderSculptThumb(recipe) {
+	const run = queue.then(() => renderNow(recipe));
+	queue = run.catch(() => {});
+	return run.catch((error) => {
+		console.warn("[cozyclay] could not draw the sculpt card thumbnail", error);
+		return null;
+	});
+}