cozyclay 3.1.0 → 3.1.2

package/src/motion3/skills/walk-fit.js

@@ -0,0 +1,170 @@
+// walkTo's fit (C21): to with steps walks where the steps walk, so the steps are fitted to end at to in a natural
+// gait for the rig (skills/basic.js walkTo calls fitTo when correct.js fitWalks asks), or the walk is refused.
+import { len, sub } from "../compiler/math.js";
+import { walk, stateAt } from "../compiler/walk.js";
+import { partsOf } from "../object-pose.js";
+import { standClearance } from "./stance.js";
+
+/** The feet's midpoint [x, z] once the walk's keys have played out. */
+export function walkEndAt(keys) {
+	const st = stateAt(keys, Infinity);
+	return [(st.foot_l[0] + st.foot_r[0]) / 2, (st.foot_l[2] + st.foot_r[2]) / 2];
+}
+export const r2 = v => Math.round(v * 100) / 100, xzText = p => `[${p.map(r2).join(", ")}]`;
+// A natural gait for the rig (fitTo): a step STEP of the leg (hip to ankle: 0.25..0.7 m on the Y Bot), the first of a
+// two-step walk FIRST of it (a short shuffle is a natural reposition), CADENCE steps a second, and the step over the cadence
+// within RATIO of WALK_RATIO legs x s: a person's walk ratio (about 6.5 mm per step a minute, 0.39 m x s on a 0.83 m leg)
+// holds from a slow walk to a brisk one, so longer steps come with quicker ones. A stride fitted at a fixed cadence went to
+// 0.87 m at 1.2 steps a second in the agent sessions (a lunge); the walk generator slides or pops in most cadences from a
+// 0.75 m step, and pops above 1.8 steps a second (31 of 47 fitted walks at period 12-13, none at 14-18; a person's brisk walk
+// reaches 2.1).
+const STEP = [0.3, 0.85], FIRST = [0.18, 0.85], CADENCE = [1, 1.8], WALK_RATIO = 0.47, RATIO = [0.7, 1.4], CHANGE = 0.1, HEADING_TOL = 20;
+export const REACH_TOL = 0.1;
+// A walk whose to lies within CLEAR legs (0.41 m on the Y Bot) of a body ahead of it (inside it, or its nearest point within
+// 60 deg of the way the walk goes) stops before the body instead: a low body (top under LOW legs: a box on the floor, a crate)
+// CLEAR from its near side, the feet's midpoint to its footprint, room to bend over it; a higher one (a table, a counter, a
+// wall) where the standing body (stance.js: legs, feet, hips, arms down) clears it by GAP. The bench replay (n=692): steps
+// fitted onto a to the agent had set 0.22-0.30 m from a box it then picked up walked the body into it (COLLIDE frames +58%,
+// first-compile passes 28 -> 10); the build before the fit had stopped those walks 0.40-0.56 m from the box. One clearance
+// for every body (0.41 m from a table too) cut COLLIDE frames as far but cost 59 goals and 127 REACH groups (a cup on the table
+// out of reach); this split keeps the goals the fit gained (996, as 582d0501) with COLLIDE frames 80,853 -> 63,350 and
+// first-compile passes 10 -> 19. A body taller than HEAD m at its foot (a shelf overhead), lower than SUPPORT (a mat), carried
+// during the walk or sat on next is not in the way.
+const CLEAR = 0.5, SUPPORT = 0.12, HEAD = 1.7, AHEAD = Math.cos(Math.PI / 3), LOW = 0.65, GAP = 0.05;
+const legOf = sk => { const P = sk.restWorldPos, I = sk.index; return len(sub(P[I.LeftLeg], P[I.LeftUpLeg])) + len(sub(P[I.LeftFoot], P[I.LeftLeg])); };
+// the bodies a walk may end against, as the still scene has them: what a hand carries during the walk (spec.objects with
+// a grab before its end, not released before it starts), the seat a later sitInSeat sits on, its back, the car, and
+// every part of their groups
+function passable(ctx, end) {
+	const scene = ctx.scene, ids = new Set(), add = id => { const top = scene?.objects?.[id]?.ancestors?.at(-1) ?? id; for (const part of partsOf(scene, top)) ids.add(part); };
+	for (const u of (ctx.use ?? []).filter((x, j) => j !== ctx.index && x?.f0 >= ctx.f0 && x?.skill === "sitInSeat"))
+		for (const id of [u.args?.seat, u.args?.seatBack, u.args?.car].filter(x => typeof x === "string")) add(id);
+	for (const [id, o] of Object.entries(ctx.objects ?? {})) if (Number.isFinite(o?.grab) && o.grab <= end && !(o.release < ctx.f0)) for (const part of partsOf(scene, id)) ids.add(part);
+	return ids;
+}
+// the feet's midpoint p = [x, z] to body o's footprint: [distance, the nearest point]
+function footprint(o, p) {
+	const c = o.R, dx = p[0] - o.pos[0], dz = p[1] - o.pos[2], lx = c[0][0] * dx + c[2][0] * dz, lz = c[0][2] * dx + c[2][2] * dz;
+	const qx = Math.max(-o.half[0], Math.min(o.half[0], lx)), qz = Math.max(-o.half[2], Math.min(o.half[2], lz));
+	const q = [o.pos[0] + c[0][0] * qx + c[0][2] * qz, o.pos[2] + c[2][0] * qx + c[2][2] * qz];
+	return [Math.hypot(p[0] - q[0], p[1] - q[1]), q];
+}
+// the point of the approach from c0 (unit u) where a walk toward a to (at d) stops clear of the bodies ahead: { t, at, near }, or null
+function clearStop(ctx, c0, u, d, skip, clear, h) {
+	const to = [c0[0] + u[0] * d, c0[1] + u[1] * d], leg = legOf(ctx.sk);
+	const ahead = Object.entries(ctx.scene?.objects ?? {}).filter(([id, o]) => !skip.has(id) && o.half && o.pos && o.R && o.pos[1] < HEAD && o.pos[1] + 2 * o.half[1] * o.R[1][1] > SUPPORT)
+		.map(([id, o]) => { const [dist, q] = footprint(o, to); return { id, o, dist, q, low: o.pos[1] + 2 * o.half[1] * o.R[1][1] < LOW * leg }; })
+		.filter(b => b.dist < clear && (b.dist < 1e-6 || ((b.q[0] - to[0]) * u[0] + (b.q[1] - to[1]) * u[1]) >= AHEAD * b.dist)).sort((a, b) => a.dist - b.dist);
+	if (!ahead.length) return null;
+	const at = s => [c0[0] + u[0] * s, c0[1] + u[1] * s], high = new Set(Object.keys(ctx.scene.objects).filter(id => !ahead.some(b => b.id === id && !b.low)));
+	const blocked = s => ahead.some(b => b.low && footprint(b.o, at(s))[0] < clear) || (ahead.some(b => !b.low) && standClearance(ctx.sk, ctx.scene, at(s), h, high) < GAP);
+	if (!blocked(d)) return null;
+	let t = d;
+	while (t > 0 && blocked(t)) t -= 0.01;
+	return t > REACH_TOL ? { t, at: at(t), near: ahead[0].id, gap: footprint(ahead[0].o, at(t))[0] } : null;
+}
+// the last frame a walk whose stepping ends at `from` may end at: the first later frame another skill starts at, a key of the
+// spec (or an object key, grab or release: ctx.fit.busy) after its stepping, or the take's last frame (ctx.fit.last)
+const roomAfter = (ctx, from) => Math.min(ctx.fit.last ?? Infinity, ...(ctx.use ?? []).filter((x, j) => j !== ctx.index && x?.f0 > ctx.f0).map(x => x.f0),
+	...ctx.keys.filter(k => k.f > from && /^keys\[/.test(k.src ?? "")).map(k => k.f), ...(ctx.fit.busy ?? []).filter(f => f > from));
+
+/**
+ * to with steps (C21): the steps walk where they walk, and to only turns the heading, so a walk with both is fitted
+ * when ctx.fit asks (correct.js fitWalks, before the spec is stored), in a natural gait (the bands above):
+ *   the stride (steps >= 3, the first step keeping its share of it) or the first step (steps 2) that makes the steps end
+ *   at to, when it stays in its band and in the walk ratio band at the walk's cadence;
+ *   else the step count whose stride is nearest the walk ratio, its stride and cadence in their bands: in the walk's own
+ *   stepping time (steps x period frames, the period the one that fits, never ending later; fewer steps stand at the end),
+ *   or at the walk's own period when nothing comes after it in a frames "auto" spec (ctx.fit.stretch: it may end later);
+ *   else more steps that end later, into frames nothing uses (roomAfter), at the walk's own cadence or a quicker natural one;
+ *   else the walk's own steps at its band's edge when they still end within REACH_TOL of to (a walk that near is not fitted);
+ *   else, or for a heading that points away from to, a line in ctx.fit.refusals with what the walk would do and needs.
+ * The last two were refusals until the bench (S7, S10: 3 of 7 walkTo refusals in 30 merged runs, 4 walks): each had one in
+ * the bands (step 0.7 m at 1.33-1.5 steps a second ending 0.05-0.07 m short, or 4 steps at 1.71 steps a second ending 2
+ * frames later into free frames) whose whole take had no foot, knee or float problem in the walk the in-band walks lacked.
+ * Deterministic: a walk at a candidate count is estimated (its end is linear in the stride) and the chosen one walked
+ * once more to set its stride. -> { gen, adjust } with the fitted gen.
+ */
+export function fitTo(ctx, gen, c0, d, bearing) {
+	const { args, tag, sk } = ctx, steps = gen.steps, h = Array.isArray(args.heading) ? args.heading[1] : args.heading;
+	const off = h === undefined ? 0 : Math.abs(((h - bearing) % 360 + 540) % 360 - 180);
+	if (off > HEADING_TOL) {
+		ctx.fit.refusals.push(`${tag}: heading ${h} points ${Math.round(off)} deg away from to ${xzText(args.to)} (it lies at heading ${Math.round(bearing)}), so the walk would not go there; with to the walk turns toward it by itself: leave heading out, or give heading without to to walk that way`);
+		return { gen };
+	}
+	const period = gen.period ?? 20, swing = gen.swing ?? 14, was = gen.step ?? 0.5, first = gen.firstStep ?? 0.4;
+	if (args.steps === undefined || args.arrive !== undefined || !(steps >= 2) || ![steps, period, swing, was, first].every(Number.isFinite)) return { gen };
+	const u = [Math.sin(bearing * Math.PI / 180), Math.cos(bearing * Math.PI / 180)];
+	// to against a body: the steps end at the nearest point of the approach where the body stands clear of it; when no
+	// natural gait ends there, the fit to to itself (and its refusal) as before
+	// (ctx.fit.noStop: the walks correct.js fitWalks keeps on to, as a stop would make a later walk refuse; ctx.fit.stopped: the walks that stopped)
+	const stop = !ctx.fit.noStop?.has(ctx.index) && clearStop(ctx, c0, u, d, passable(ctx, ctx.f0 + 16 + steps * period + 18), CLEAR * legOf(sk), bearing);
+	let r = stop && fitSteps(ctx, gen, c0, u, stop.t, stop);
+	if (r && !r.refuse) ctx.fit.stopped?.add(ctx.index);
+	if (!r || r.refuse) r = fitSteps(ctx, gen, c0, u, d, null);
+	if (r.refuse) ctx.fit.refusals.push(r.refuse);
+	return { gen: r.gen, ...(r.adjust ? { adjust: r.adjust } : {}) };
+}
+
+/** fitTo's stride, step count and cadence for a walk ending d along u from c0 (stop: the clear point it ends at) -> { gen, adjust? } or { gen, refuse } */
+function fitSteps(ctx, gen, c0, u, d, stop) {
+	const { args, tag, sk } = ctx, steps = gen.steps, period = gen.period ?? 20, swing = gen.swing ?? 14, was = gen.step ?? 0.5, first = gen.firstStep ?? 0.4;
+	const target = stop ? `${xzText(stop.at)}, ${r2(stop.gap)} m before ${stop.near} (to ${xzText(args.to)} is against it)` : `to ${xzText(args.to)}`;
+	const reach = g => { const e = walkEndAt(walk(g, ctx.keys, sk, tag)); return { end: e, along: (e[0] - c0[0]) * u[0] + (e[1] - c0[1]) * u[1] }; };
+	const { end, along } = reach(gen);
+	if (Math.abs(d - along) <= REACH_TOL) return { gen };
+	const fps = ctx.fps ?? 24, leg = legOf(sk), nat = WALK_RATIO * leg, span = steps * period;
+	const band = n => (n >= 3 ? STEP : FIRST).map(x => r2(x * leg)), pLo = Math.ceil(fps / CADENCE[1]), pHi = Math.floor(fps / CADENCE[0]);
+	const stretch = ctx.fit.stretch === true && !(ctx.use ?? []).some((x, j) => j !== ctx.index && x?.f0 > ctx.f0) && !ctx.keys.some(k => k.f > ctx.f0 && /^keys\[/.test(k.src ?? ""));
+	// n steps: the period (its own, or the one that keeps the stepping time), the stride that ends them at to (the end moves
+	// by the first step and a stride a middle step, rest the closing step's share; with steps 3 and up the first step keeps
+	// its share of the stride unless args give it, as a person's first step is a little shorter), whether they stay in their bands
+	const rest = along - first - (steps - 2) * was, share = args.firstStep === undefined ? first / was : 0;
+	const at = (n, pAt) => {
+		const p = pAt ?? (stretch || n === steps ? period : Math.min(Math.max(pHi, period), Math.floor(span / n))), name = n >= 3 ? "step" : "firstStep";
+		const value = n >= 3 ? (d - rest - (share ? 0 : first)) / (share + n - 2) : d - rest, lead = n >= 3 && share ? share * value : first;
+		const [lo, hi] = band(n), ratio = value * p / fps / nat, inBand = (x, [a, b]) => x >= a && x <= b;
+		return { n, p, name, value, ratio, ok: inBand(value, [lo, hi]) && inBand(lead, band(2)) && (p === period || inBand(p, [pLo, pHi])) };
+	};
+	const own = at(steps), most = Math.min(60, Math.ceil(d / band(3)[0]) + 2);
+	let pick = own.ok && own.ratio >= RATIO[0] && own.ratio <= RATIO[1] ? own : null, room, short;
+	// nearest the walk ratio, a step count further from the one asked costing CHANGE of it a step
+	const cost = c => Math.abs(Math.log(c.ratio)) + CHANGE * Math.abs(c.n - steps), nearest = list => list.filter(c => c.ok).sort((a, b) => cost(a) - cost(b) || a.n - b.n)[0];
+	const counts = Array.from({ length: most - 1 }, (_, i) => i + 2);
+	if (!pick) pick = nearest(counts.map(n => at(n)));
+	if (!pick && !stretch) {
+		// more steps, ending later into frames nothing uses: the walk's own period, or the slowest natural one that ends in time
+		room = roomAfter(ctx, ctx.f0 + 16 + span);
+		pick = nearest(counts.filter(n => n > steps).map(n => at(n, Math.min(period, Math.floor((room - ctx.f0 - 34) / n)))).filter(c => c.p >= pLo && c.n * c.p > span));
+	}
+	if (!pick) {
+		// the walk's own steps at its band's edge, when they end within REACH_TOL of to
+		const [lo, hi] = band(steps), value = Math.min(hi, Math.max(lo, own.value)), ratio = value * period / fps / nat, lead = steps >= 3 && share ? share * value : first;
+		const g = { ...gen, [own.name]: r2(value), ...(steps >= 3 && share ? { firstStep: r2(lead) } : {}) };
+		const left = ratio >= RATIO[0] && ratio <= RATIO[1] && lead >= band(2)[0] && lead <= band(2)[1] ? d - reach(g).along : Infinity;
+		if (Math.abs(left) <= REACH_TOL) ({ pick, short } = { pick: { ...own, value: r2(value), ratio }, short: left });
+	}
+	const [sLo, sHi] = band(3), gait = `a natural gait (step ${sLo}..${sHi} m, ${CADENCE[0]}..${CADENCE[1]} steps a second: period ${pLo}..${pHi} at ${fps} fps`;
+	const miss = `${r2(Math.abs(d - along))} m ${along < d ? "short of" : "past"} ${stop ? `the point ${xzText(stop.at)} clear of ${stop.near} before to ${xzText(args.to)}` : `to ${xzText(args.to)}`} (${r2(d)} m away)`;
+	if (!pick) {
+		// short: the fewest steps at the longest natural step, at the quickest natural cadence (the least stepping time that reaches)
+		const n = 2 + Math.ceil((d - rest - first) / sHi - 1e-9), e = ctx.f0 + 16 + n * pLo + 18;
+		return { gen, refuse: `${tag}: steps ${steps} at period ${period} (${span} frames of stepping) walk ${r2(along)} m and end at ${xzText(end)}, ${miss}; ${along < d
+			? `in ${gait}) that takes ${n} steps and ${n * pLo} frames of stepping or more (the walk would end at f${e} or later, not f${ctx.f0 + 16 + span + 18}): leave steps${args.step === undefined ? "" : " and step"} out (walkTo picks the count), or give steps: ${n} and room for the walk before what follows`
+			: `no natural step count ends there: leave steps out (walkTo picks the count)`}` };
+	}
+	const timed = pick.p === period ? {} : { period: pick.p, swing: Math.max(2, Math.min(pick.p - 1, Math.round(swing * pick.p / period))) };
+	const lead = pick.n >= 3 && share > 0, strides = v => ({ [pick.name]: r2(v), ...(lead ? { firstStep: r2(share * v) } : {}) });
+	let fitted = { ...gen, steps: pick.n, ...timed, ...strides(pick.value) };
+	const left = short ?? d - reach(fitted).along;
+	if (short === undefined && Math.abs(left) > 0.02) fitted = { ...fitted, ...strides(pick.value + left / (pick.n >= 3 ? share + pick.n - 2 : 1)) };
+	const v = fitted[pick.name], dflt = pick.name === "step" ? was : first, e0 = ctx.f0 + 16 + span + 18, e1 = ctx.f0 + 16 + pick.n * pick.p + 18;
+	const changes = [pick.n !== steps && `steps ${steps} -> ${pick.n}`, timed.period && `period ${period} -> ${timed.period} (swing ${swing} -> ${timed.swing})`, `${pick.name} ${dflt} -> ${v} m`,
+		lead && fitted.firstStep !== first && `firstStep ${first} -> ${fitted.firstStep} m`].filter(Boolean).join(", ");
+	const when = e1 === e0 ? "" : `; it ends f${e1}, not f${e0} (${stretch ? "nothing follows it" : e1 > e0 ? `nothing uses f${e0 + 1}-f${e1}` : `the pose holds to f${e0}`})`;
+	const needs = `steps ${steps} would need a ${own.name} of ${r2(own.value)} m at ${r2(fps / period)} steps a second`;
+	const why = short !== undefined ? ` (${gait}; ${needs})` : pick.n === steps && !timed.period ? ` (at ${pick.name} ${dflt} they walk ${r2(along)} of ${r2(d)} m)` : ` in ${gait}; ${needs})${when}`;
+	const ends = short === undefined ? `end at ${target}` : `end ${r2(Math.abs(short))} m ${short > 0 ? "short of" : "past"} ${target}, the ${short > 0 ? "longest" : "shortest"} natural step`;
+	const adjust = { args: { ...(pick.n === steps ? {} : { steps: pick.n }), ...timed, [pick.name]: v, ...(lead && fitted.firstStep !== first ? { firstStep: fitted.firstStep } : {}) }, note: `${tag}: ${changes}, so steps ${pick.n} ${ends}${why}` };
+	return { gen: fitted, adjust };
+}

package/src/object-look.js

@@ -16,6 +16,7 @@
  */
 
 import { normalizeObjectColor } from "./object-colors.js";
+import { objectMaterialFields, objectMaterialPatch } from "./material-presets.js";
 
 export const LIGHT_KIND = "light";
 
@@ -94,8 +95,8 @@ export function normalizeObjectGlow(value) {
 }
 
 /** The light/glow fields a normalized record carries. A light renderer always
- * has a light; any record keeps a glow only when it has one, so records written
- * before glow existed come back byte-for-byte unchanged. */
+ * has a light; any record keeps a glow (and a primitive its surface preset)
+ * only when it has one, so records written before come back unchanged. */
 export function objectLookFields(record, entry) {
 	const out = {};
 	if ((entry.renderer ?? entry.kind) === LIGHT_KIND) out.light = normalizeObjectLight(record.light, record.light?.type ?? entry.light?.type);
@@ -103,12 +104,14 @@ export function objectLookFields(record, entry) {
 	if (glow) out.glow = glow;
 	// A kit part a take switches on (a muzzle flash and its light) stays hidden without one (object-travel.js trackShown).
 	if (record.showOnlyInTake === true) out.showOnlyInTake = true;
-	return out;
+	// A primitive's surface preset (material-presets.js).
+	return Object.assign(out, objectMaterialFields(record, entry.renderer ?? entry.kind));
 }
 
 /** The light/glow part of an object.update patch: each field merges over the
  * record's own and is repaired; `glow: null` removes the glow. Only changes are
- * returned. A light on a record that is not a light is ignored. */
+ * returned. A light on a record that is not a light is ignored. A primitive's
+ * material and finish ride along (material-presets.js). */
 export function objectLookPatch(object, patch) {
 	const update = {};
 	if (patch?.light && typeof patch.light === "object" && object.renderer === LIGHT_KIND) {
@@ -119,7 +122,7 @@ export function objectLookPatch(object, patch) {
 		const next = patch.glow === null ? null : normalizeObjectGlow({ ...(object.glow ?? {}), ...patch.glow });
 		if (JSON.stringify(next) !== JSON.stringify(object.glow ?? null)) update.glow = next;
 	}
-	return update;
+	return Object.assign(update, objectMaterialPatch(object, patch));
 }
 
 /** 32-bit FNV-1a of the record id: the flicker's seed. */
@@ -196,3 +199,4 @@ export function withShadowCapWarnings(result, objects) {
 }
 // A record's grasp sockets ride the same normalize and patch paths (object-grasp.js).
 export { objectGraspFields, objectGraspPatch } from "./object-grasp.js";
+export { objectMaterialKeys } from "./material-presets.js";

package/src/panels/PoseImagePanel.jsx

@@ -4,6 +4,7 @@ import Foldout from "./Foldout.jsx";
 import { ko, isKo } from "../locale.js";
 import { readReferenceImage } from "./ReferenceImageField.jsx";
 import { createHttpTransport } from "../workflow/agent-client.js";
+import { saveExport } from "../export-workspace.js";
 import "./pose-image.css";
 
 // The sidecar accepts at most 6 references per request, shared with the scene's identity and
@@ -145,7 +146,7 @@ export default function PoseImagePanel({ hidden, capturePoseImage }) {
 							<img src={result.dataUrl} alt={result.prompt} />
 						</button>
 						<div className="pose-image-result-actions">
-							<a className="btn ghost small" href={result.dataUrl} download={`cozyclay-pose-${result.at}.png`}>{ko("Download", "다운로드")}</a>
+							<a className="btn ghost small" href={result.dataUrl} download={`cozyclay-pose-${result.at}.png`} onClick={(event) => { event.preventDefault(); void saveExport(result.dataUrl, `cozyclay-pose-${result.at}.png`); }}>{ko("Download", "다운로드")}</a>
 							<button type="button" className="btn ghost small" disabled={refs.length >= USER_REFERENCES_MAX}
 								onClick={() => setPoseImageState({ refs: [...store.refs, result.dataUrl].slice(0, USER_REFERENCES_MAX) })}>
 								{ko("Use as reference", "참조로 쓰기")}
@@ -194,7 +195,7 @@ function PoseImageViewer({ results, selected, onSelect, onClose }) {
 				<figcaption>
 					<span className="pose-image-viewer-prompt">{entry.prompt}</span>
 					{results.length > 1 && <span className="pose-image-viewer-count">{results.length - selected}/{results.length}</span>}
-					<a className="btn ghost small" href={entry.dataUrl} download={`cozyclay-pose-${entry.at}.png`}>{ko("Download", "다운로드")}</a>
+					<a className="btn ghost small" href={entry.dataUrl} download={`cozyclay-pose-${entry.at}.png`} onClick={(event) => { event.preventDefault(); void saveExport(entry.dataUrl, `cozyclay-pose-${entry.at}.png`); }}>{ko("Download", "다운로드")}</a>
 					<button type="button" className="btn ghost small" data-testid="pose-image-viewer-close" onClick={onClose}>{ko("Close", "닫기")}</button>
 				</figcaption>
 			</figure>

package/src/panels/SculptPanel.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import Foldout from "./Foldout.jsx";
 import { ko, isKo } from "../locale.js";
-import { effortOptions } from "../workflow/agent-client.js";
+import { effortOptions } from "../workflow/agent-client.js"; import { saveExport } from "../export-workspace.js";
 import "./sculpt.css";
 
 // Sculpt mode side panel (#739). Pure view: the run controller owns the run state and the
@@ -241,7 +241,7 @@ function BlueprintSection({ blueprint, disabled }) {
 					</a>
 					<figcaption>
 						<span>{sheet.width}×{sheet.height}{Number.isFinite(sheet.ms) ? ` · ${Math.round(sheet.ms / 1000)}s` : ""}</span>
-						<a href={sheet.dataUrl} download="sculpt-blueprint.png" data-testid="sculpt-blueprint-download">{ko("Download", "내려받기")}</a>
+						<a href={sheet.dataUrl} download="sculpt-blueprint.png" data-testid="sculpt-blueprint-download" onClick={(event) => { event.preventDefault(); void saveExport(sheet.dataUrl, "sculpt-blueprint.png"); }}>{ko("Download", "내려받기")}</a>
 					</figcaption>
 				</figure>
 			)}

package/src/primitive-look.js

@@ -0,0 +1,38 @@
+/**
+ * A primitive's surface preset (object.material / object.finish) as the
+ * material props.jsx hangs on its mesh, and the polygon offset every prop
+ * material takes for its depth rank.
+ */
+
+import { useEffect, useMemo } from "react";
+import { lookMaterial } from "./material-look.js";
+
+// Parts of an assembly can share a plane with an earlier part (hood top and
+// grille top). The depth test can't order them and the winner flips as the
+// camera moves, so a ranked part is pulled toward the camera by `rank` steps
+// (negative = nearer). Rank 0 gets nothing: those materials stay untouched.
+export function depthRankProps(rank) {
+	return rank > 0 ? { polygonOffset: true, polygonOffsetFactor: -rank, polygonOffsetUnits: -rank } : null;
+}
+
+/** Each primitive's extent in its mesh frame at scale 1 (props.jsx builds
+ * them); the rest are unit sized. The shader multiplies the record's scale in. */
+const PRIMITIVE_SIZE = { capsule: [0.7, 1.4, 0.7], plane: [2, 2, 0.01] };
+
+/**
+ * The preset material for a primitive record, or null when the record keeps
+ * the plain clay look (no material and no finish) or auto-colour paints it
+ * flat: the caller then draws exactly what it drew before presets. Rebuilt
+ * when the look, the colour or the rank changes; the program and the pattern
+ * textures are shared, so a rebuild is cheap.
+ */
+export function usePrimitiveLook(object, kind, side, depthRank) {
+	const { material, finish, color, autoColor } = object;
+	const active = !autoColor && Boolean(material || finish);
+	const look = useMemo(
+		() => (active ? lookMaterial({ material, finish, color, side, size: PRIMITIVE_SIZE[kind] }, depthRankProps(depthRank)) : null),
+		[active, material, finish, color, side, kind, depthRank],
+	);
+	useEffect(() => () => look?.dispose(), [look]);
+	return look;
+}

package/src/props.jsx

@@ -19,6 +19,7 @@ import { CUTOUT_KIND, MESH_KIND, EMPTY_KIND, EMPTY_MARKER_SIZE, SCULPT_KIND } fr
 import { TEXT_KIND } from "./text/text-record.js";
 import { TextObject } from "./text/text-object.jsx";
 import { buildSculptGroup, disposeSculptGroup } from "./sculpt-geometry.js";
+import { depthRankProps, usePrimitiveLook } from "./primitive-look.js";
 import { subscribeToAssetTexture } from "./scene-asset-cache.js";
 import { ImportedMesh } from "./imported-mesh.jsx";
 import { EffectMarker, EffectsLayer } from "./effects/EffectsLayer.jsx";
@@ -30,29 +31,23 @@ import { LIGHT_KIND, capPracticalShadows } from "./object-look.js";
 import { SceneLight, useLookRefresh } from "./scene-lights.jsx";
 import { placeObjectLook } from "./scene-light-place.js";
 
-// Parts of an assembly can share a plane with an earlier part (hood top and
-// grille top). The depth test can't order them and the winner flips as the
-// camera moves, so a ranked part is pulled toward the camera by `rank` steps
-// (negative = nearer). Rank 0 gets nothing: those materials stay untouched.
-function depthRankProps(rank) {
-	return rank > 0 ? { polygonOffset: true, polygonOffsetFactor: -rank, polygonOffsetUnits: -rank } : null;
-}
-
 /**
  * The creatable primitives, Unity's 3D Object menu in clay. Each one is built
  * with its base on the local floor (y = 0), so an object's `y` reads as height
- * above the deck rather than "half of me is underground".
+ * above the deck rather than "half of me is underground". A surface preset
+ * (primitive-look.js) replaces the clay; glass casts no shadow.
  */
-function Primitive({ kind, color, autoColor, depthRank = 0 }) {
+function Primitive({ kind, object, color, autoColor, depthRank = 0 }) {
 	const side = kind === "plane" ? THREE.DoubleSide : THREE.FrontSide;
-	const material = autoColor ? (
+	const look = usePrimitiveLook(object, kind, side, depthRank), cast = !(look?.transmission > 0);
+	const material = look ? <primitive object={look} attach="material" /> : autoColor ? (
 		<meshStandardMaterial {...autoFlat(autoColor)} side={side} {...depthRankProps(depthRank)} />
 	) : (
 		<meshStandardMaterial color={color} roughness={0.82} side={side} {...depthRankProps(depthRank)} />
 	);
 	if (kind === "sphere") {
 		return (
-			<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 				<sphereGeometry args={[0.5, 28, 18]} />
 				{material}
 			</mesh>
@@ -60,7 +55,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	}
 	if (kind === "capsule") {
 		return (
-			<mesh position={[0, 0.7, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.7, 0]} castShadow={cast} receiveShadow>
 				<capsuleGeometry args={[0.35, 0.7, 6, 18]} />
 				{material}
 			</mesh>
@@ -68,7 +63,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	}
 	if (kind === "cylinder") {
 		return (
-			<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 				<cylinderGeometry args={[0.5, 0.5, 1, 26]} />
 				{material}
 			</mesh>
@@ -76,7 +71,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	}
 	if (kind === "cone") {
 		return (
-			<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+			<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 				<coneGeometry args={[0.5, 1, 26]} />
 				{material}
 			</mesh>
@@ -91,7 +86,7 @@ function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 		);
 	}
 	return (
-		<mesh position={[0, 0.5, 0]} castShadow receiveShadow>
+		<mesh position={[0, 0.5, 0]} castShadow={cast} receiveShadow>
 			<boxGeometry args={[1, 1, 1]} />
 			{material}
 		</mesh>
@@ -162,20 +157,17 @@ function Cutout({ object }) {
 
 /**
  * A sculpt: the clay parts its recipe describes, rebuilt only when the recipe
- * or the look changes. Each part keeps its own clay colour; auto-colour paints
- * the whole sculpt flat like any other prop, because it is one object.
+ * or the look changes. The shaded look is buildSculptGroup's own clay (part
+ * colours, gradients, scatter tints); auto-colour paints the whole sculpt flat
+ * like any other prop, because it is one object. Depth rank rides on either.
  */
 function Sculpt({ object, depthRank = 0 }) {
 	const { recipe, autoColor } = object;
-	const group = useMemo(
-		() => buildSculptGroup(recipe, {
-			materialFor: (part) => new THREE.MeshStandardMaterial({
-				...(autoColor ? autoFlat(autoColor) : { color: part.color, roughness: 0.82, metalness: 0 }),
-				...depthRankProps(depthRank),
-			}),
-		}),
-		[recipe, autoColor, depthRank],
-	);
+	const group = useMemo(() => {
+		const built = buildSculptGroup(recipe, autoColor ? { materialFor: () => new THREE.MeshStandardMaterial(autoFlat(autoColor)) } : {});
+		built.traverse((node) => node.material && Object.assign(node.material, depthRankProps(depthRank)));
+		return built;
+	}, [recipe, autoColor, depthRank]);
 	useEffect(() => () => disposeSculptGroup(group), [group]);
 	return <primitive object={group} />;
 }
@@ -242,7 +234,7 @@ function SceneObjectContent({ object, depthRank = 0 }) {
 	if (renderer === MESH_KIND) return <ImportedMesh object={object} />;
 	if (renderer === SCULPT_KIND) return <Sculpt object={object} depthRank={depthRank} />;
 	if (renderer === TEXT_KIND) return <TextObject object={object} />;
-	if (PRIMITIVE_KINDS.has(renderer)) return <Primitive kind={renderer} color={color} autoColor={autoColor} depthRank={depthRank} />;
+	if (PRIMITIVE_KINDS.has(renderer)) return <Primitive kind={renderer} object={object} color={color} autoColor={autoColor} depthRank={depthRank} />;
 	return null;
 }
 

package/src/render-passes.js

@@ -47,10 +47,16 @@ export function passFileName(kind) {
 // it spreads the value over four channels and reads as colour noise). This
 // shader is the plain depth-to-grey the deliverable wants, and the range it
 // normalises over is the stage's, not the projection's.
+// An InstancedMesh (a sculpt's scatter) draws every instance through its
+// instanceMatrix; without it all of them would land on the mesh's origin.
 const DEPTH_VERTEX = /* glsl */ `
 varying float vViewDepth;
 void main() {
-	vec4 viewPosition = modelViewMatrix * vec4(position, 1.0);
+	vec4 local = vec4(position, 1.0);
+#ifdef USE_INSTANCING
+	local = instanceMatrix * local;
+#endif
+	vec4 viewPosition = modelViewMatrix * local;
 	vViewDepth = -viewPosition.z;
 	gl_Position = projectionMatrix * viewPosition;
 }

package/src/result-modal.jsx

@@ -73,7 +73,7 @@ export default function ResultModal({ result, copied, recordedVideoName, onClose
 					</button>
 					{result.frame && (
 						<button type="button" className="btn" onClick={onDownload} disabled={downloadDisabled}>
-							{result.downloaded ? ko("Download requested", "다운로드 요청됨") : result.frameB ? ko("Download start and end frames", "시작·끝 프레임 다운로드") : ko("Download frame", "프레임 다운로드")}
+							{result.downloaded ? ko("Exported", "내보냄") : result.frameB ? ko("Export start and end frames", "시작·끝 프레임 내보내기") : ko("Export frame", "프레임 내보내기")}
 						</button>
 					)}
 				</div>
@@ -89,8 +89,8 @@ export default function ResultModal({ result, copied, recordedVideoName, onClose
 							<span>{copied ? ko("Copied. Paste it into your AI service's prompt box.", "복사됐어요. AI 서비스의 입력창에 붙여 넣으세요.") : ko("Press “Copy prompt” above, then paste it into your AI service.", "위의 ‘프롬프트 복사’를 누른 뒤 AI 서비스 입력창에 붙여 넣으세요.")}</span>
 						</li>
 						<li>
-							<strong>{ko("Download the frame", "프레임 다운로드")}</strong>
-							<span>{result.frameB ? ko("Press “Download start and end frames” to save both PNGs.", "‘시작·끝 프레임 다운로드’를 눌러 두 PNG를 저장하세요.") : hasFrame ? ko("Press “Download frame” to save the PNG.", "‘프레임 다운로드’를 눌러 PNG를 저장하세요.") : ko("This result has no frame to download.", "이 결과에는 내려받을 프레임이 없어요.")}</span>
+							<strong>{ko("Export the frame", "프레임 내보내기")}</strong>
+							<span>{result.frameB ? ko("Press “Export start and end frames” to save both PNGs.", "‘시작·끝 프레임 내보내기’를 눌러 두 PNG를 저장하세요.") : hasFrame ? ko("Press “Export frame” to save the PNG.", "‘프레임 내보내기’를 눌러 PNG를 저장하세요.") : ko("This result has no frame to export.", "이 결과에는 내보낼 프레임이 없어요.")}</span>
 						</li>
 						<li>
 							<strong>{ko("Attach the image to your AI", "AI에 이미지 첨부")}</strong>

package/src/scene-objects.js

@@ -28,7 +28,7 @@ import { retireObjectKind } from "./retired-kinds.js";
 import { objectSize } from "./object-size.js";
 import { EFFECT_ENTRY, effectFields } from "./effects/effect-record.js";
 import { TEXT_ENTRY, TEXT_KIND, textFields, textPatch } from "./text/text-record.js";
-import { LIGHT_KIND, LIGHT_MENU_ENTRIES, lightLibraryEntry, objectLookFields, objectLookPatch, objectGraspFields, objectGraspPatch } from "./object-look.js";
+import { LIGHT_KIND, LIGHT_MENU_ENTRIES, lightLibraryEntry, objectLookFields, objectLookPatch, objectGraspFields, objectGraspPatch, objectMaterialKeys } from "./object-look.js";
 export { OBJECT_COLORS, normalizeObjectColor, rememberObjectColor, readStoredObjectColors, writeStoredObjectColors } from "./object-colors.js";
 export { isEffectivelyHidden };
 
@@ -547,7 +547,7 @@ const TRANSFORM_LIMITS = {
 /** The patch keys updateSceneObject reads for this object; any other key is
  * silently ignored there, so callers that must not be silent check against this. */
 export function objectPatchFields(object) {
-	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow", "grasp"];
+	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow", "grasp", ...objectMaterialKeys(object?.renderer)];
 	if (object?.renderer === LIGHT_KIND) fields.push("light");
 	if (object?.renderer === CUTOUT_KIND) fields.push("assetId", "sourceAssetId", "matteAssetId", "matteScale", "height", "aspect", "width", "stretch");
 	if (object?.renderer === MESH_KIND) fields.push("clay", "assetId", "height");

package/src/sculpt-colours.js

@@ -0,0 +1,65 @@
+/**
+ * Sculpt colours for the shaded look, applied once per part by
+ * buildSculptGroup after the part's material exists:
+ *
+ * - a `gradient` (sculpt-surface-fields.js) becomes a per-vertex `color`
+ *   attribute blending the part's colour into the gradient's;
+ * - a scatter's items each get a small seeded hue and brightness jitter (and
+ *   the gradient, by where the item sits), so a field is not one flat swatch.
+ *
+ * The colour then lives in the vertex or instance colours, so the material's
+ * own colour goes white and `vertexColors` turns on (a texture map still
+ * multiplies in). A flat display mode (auto-colour, through materialFor)
+ * skips this, so it ignores gradients and jitter.
+ */
+
+import * as THREE from "three";
+import { isMirrorCopy, partSeed, seededRandom } from "./sculpt-noise.js";
+
+const AXES = { x: 0, y: 1, z: 2 };
+/** Item-to-item spread: hue ± this (of the wheel), brightness × 1 ± this. */
+const JITTER_HUE = 0.025;
+const JITTER_SHADE = 0.16;
+
+/** How far a local point is along the gradient: 0 at `from` (part colour), 1 at `to`. */
+function blend(part, x, y, z) {
+	const { axis, from, to } = part.gradient;
+	const i = AXES[axis];
+	// A mirrored copy reads its x reversed, so an x gradient reflects with the part.
+	const along = [isMirrorCopy(part) ? -x : x, y, z][i] / part.size[i] + 0.5;
+	if (to === from) return along >= to ? 1 : 0;
+	return THREE.MathUtils.clamp((along - from) / (to - from), 0, 1);
+}
+
+export function applySculptColours(mesh, part) {
+	if (!part.gradient && !mesh.isInstancedMesh) return;
+	const base = new THREE.Color(part.color);
+	const end = part.gradient ? new THREE.Color(part.gradient.color) : null;
+	const colour = new THREE.Color();
+	if (mesh.isInstancedMesh) {
+		const random = seededRandom(partSeed(part, part.seed + 1));
+		const matrix = new THREE.Matrix4(), at = new THREE.Vector3();
+		for (let i = 0; i < mesh.count; i += 1) {
+			colour.copy(base);
+			if (end) {
+				at.setFromMatrixPosition(mesh.getMatrixAt(i, matrix));
+				colour.lerp(end, blend(part, at.x, at.y, at.z));
+			}
+			colour.offsetHSL((random() * 2 - 1) * JITTER_HUE, 0, 0).multiplyScalar(1 + (random() * 2 - 1) * JITTER_SHADE);
+			mesh.setColorAt(i, colour);
+		}
+		mesh.instanceColor.needsUpdate = true;
+	} else {
+		const position = mesh.geometry.getAttribute("position");
+		const colours = new Float32Array(position.count * 3);
+		for (let i = 0; i < position.count; i += 1) {
+			colour.copy(base).lerp(end, blend(part, position.getX(i), position.getY(i), position.getZ(i))).toArray(colours, 3 * i);
+		}
+		mesh.geometry.setAttribute("color", new THREE.BufferAttribute(colours, 3));
+	}
+	for (const material of [mesh.material].flat()) {
+		material.color?.set(0xffffff);
+		material.vertexColors = !!mesh.geometry.getAttribute("color");
+		material.needsUpdate = true;
+	}
+}