cozyclay 3.1.1 → 3.1.2

package/src/motion3/skills/index.js

@@ -4,7 +4,7 @@
 // f0. The agent's own keys come after the skill keys (a key of the agent wins on the same
 // frame), and the agent's own anchors/props/fits replace a skill's of the same name.
 import { stateAt } from "../compiler/walk.js";
-import { didYouMean, suggestField } from "../compiler/vocab.js";
+import { didYouMean, suggestField, fmt } from "../compiler/vocab.js";
 import { USE_FIELDS } from "../schema/fields.js";
 import { SKILL_INFO } from "./info.js";
 import { fixOptions } from "../fix/index.js";
@@ -38,32 +38,66 @@ function mergeChecks(into, part) {
 	}
 }
 
-/** use[i].args against the skill's args (skills/info.js); lenient ignores unknown ones. */
-function argsOk(u, i, lenient) {
-	if (u.args !== undefined && (!u.args || typeof u.args !== "object" || Array.isArray(u.args))) bad(`use[${i}].args must be an object, got ${JSON.stringify(u.args)}`);
-	const known = Object.keys(SKILL_INFO[u.skill].args);
-	if (!lenient) for (const a of Object.keys(u.args ?? {})) if (!known.includes(a)) bad(`use[${i}].args.${a} is not an arg of ${u.skill}${suggestField(a, known)} (args: ${known.join(", ")})`);
+const isOpen = v => Boolean(v) && typeof v === "object" && !Array.isArray(v) && (v.range ?? v.search) !== undefined;
+const said = t => (t.description ? ` (${t.description})` : "");
+
+/** What is wrong with one skill arg against its schema fragment (skills/info.js): a value of the wrong kind, an enum miss; null when fine or not checked. */
+function argProblem(at, v, t) {
+	if (!t || v === undefined || isOpen(v)) return null;
+	if (t.enum && !t.enum.includes(v)) return `${at} must be one of ${t.enum.map(e => JSON.stringify(e)).join(", ")}${said(t)}, got ${fmt(v)}${didYouMean(String(v), t.enum.map(String))}`;
+	if ((t.type === "number" || t.type === "integer") && !Number.isFinite(v)) return `${at} must be a number${said(t)}, got ${fmt(v)}`;
+	if (t.type === "string" && typeof v !== "string") return `${at} must be a string${said(t)}, got ${fmt(v)}`;
+	if (t.type === "boolean" && typeof v !== "boolean") return `${at} must be true or false${said(t)}, got ${fmt(v)}`;
+	if (t.type === "array" && t.items?.type === "number" && !(Array.isArray(v) && v.length >= (t.minItems ?? 0) && v.every(x => Number.isFinite(x) || isOpen(x))))
+		return `${at} must be ${t.minItems === 2 ? "[x, z]" : t.minItems === 3 ? "[x, y, z]" : "an array of numbers"}${said(t)}, got ${fmt(v)}`;
+	return null;
+}
+
+/**
+ * Every problem of spec.use that needs no expansion, all at once: the entry's shape, the skill name, unknown fields
+ * and args, args of the wrong kind, required args, f0. lenient (a saved take) checks only what expansion cannot do without.
+ */
+function usageProblems(spec, lenient = false) {
+	if (!Array.isArray(spec.use)) return ["spec.use must be an array of { skill, args, f0 }"];
+	const out = [];
+	spec.use.forEach((u, i) => {
+		if (!u || typeof u !== "object" || Array.isArray(u)) return out.push(`use[${i}] must be { skill, args, f0 }, got ${fmt(u)}`);
+		if (!SKILLS[u.skill]) return out.push(`use[${i}].skill "${u.skill}" is not a skill${didYouMean(String(u.skill), SKILL_NAMES)} (skills: ${SKILL_NAMES.join(", ")})`);
+		if (!lenient) for (const f of Object.keys(u)) if (!USE_FIELDS.includes(f)) out.push(`use[${i}] has unknown field "${f}"${suggestField(f, USE_FIELDS)}; an entry is { skill, args, f0 }`);
+		if (u.args !== undefined && (!u.args || typeof u.args !== "object" || Array.isArray(u.args))) out.push(`use[${i}].args must be an object, got ${JSON.stringify(u.args)}`);
+		else if (!lenient) {
+			const info = SKILL_INFO[u.skill], known = Object.keys(info.args);
+			for (const [a, v] of Object.entries(u.args ?? {})) {
+				if (!known.includes(a)) out.push(`use[${i}].args.${a} is not an arg of ${u.skill}${suggestField(a, known)} (args: ${known.join(", ")})`);
+				else { const p = argProblem(`use[${i}].args.${a}`, v, info.args[a]); if (p) out.push(p); }
+			}
+			for (const a of info.required ?? []) if (u.args?.[a] === undefined) out.push(`use[${i}] ${u.skill} needs args.${a}${said(info.args[a])}`);
+		}
+		// past the last frame is said in order below, beside what an earlier skill needs (set frames >= ...)
+		if (!Number.isInteger(u.f0) || u.f0 < 0) out.push(`use[${i}].f0 must be an integer frame within 0..${spec.frames - 1}, got ${JSON.stringify(u.f0)}`);
+	});
+	return out;
 }
 
 /**
- * spec with `use` -> { spec: plain spec (no use), used: [{ skill, f0, end, paced?, cut? }] }; lenient ignores
- * unknown use[i] fields and args. auto (frames-auto.js) lets a skill that holds to the last
- * frame end where its own motion ends. A skill whose release or settle the last frame cuts ends
+ * spec with `use` -> { spec: plain spec (no use), used: [{ skill, f0, end, paced?, cut?, placed?, adjust? }] }; every
+ * problem of the use entries themselves is refused at once (usageProblems); lenient ignores unknown use[i] fields and
+ * args. fit ({ refusals: [] }, correct.js fitWalks) lets a skill fit its own args to what they ask for (walkTo: the
+ * stride to reach to), as adjust: { args, note }, or refuse into fit.refusals. auto (frames-auto.js) lets a skill
+ * that holds to the last frame end where its own motion ends. A skill whose release or settle the last frame cuts ends
  * there holding (cut says so); one that needs frames past the last for its own motion is refused.
  */
-export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
+export function expandUse(spec, { sk, scene, lenient = false, auto = false, fit }) {
 	if (!spec.use?.length) return { spec, used: [] };
-	if (!Array.isArray(spec.use)) bad("spec.use must be an array of { skill, args, f0 }");
+	const problems = usageProblems(spec, lenient);
+	if (problems.length) bad(problems.join("\n"));
 	const own = (spec.keys ?? []).map((k, i) => ({ ...k, src: `keys[${i}]` }));
 	const merged = { anchors: {}, props: {}, objects: {}, fits: [], checks: {}, channels: [], fills: {}, goals: [] }, skillKeys = [], used = [];
 	spec.use.forEach((u, i) => {
-		const tag = `use[${i}] ${u?.skill}`;
-		if (!SKILLS[u?.skill]) bad(`use[${i}].skill "${u?.skill}" is not a skill${didYouMean(String(u?.skill), SKILL_NAMES)} (skills: ${SKILL_NAMES.join(", ")})`);
-		for (const f of Object.keys(u)) if (!USE_FIELDS.includes(f) && !lenient) bad(`use[${i}] has unknown field "${f}"${suggestField(f, USE_FIELDS)}; an entry is { skill, args, f0 }`);
-		argsOk(u, i, lenient);
-		if (!Number.isInteger(u.f0) || u.f0 < 0 || u.f0 > spec.frames - 1) bad(`use[${i}].f0 must be an integer frame within 0..${spec.frames - 1}, got ${JSON.stringify(u.f0)}`);
+		const tag = `use[${i}] ${u.skill}`;
+		if (u.f0 > spec.frames - 1) bad(`use[${i}].f0 must be an integer frame within 0..${spec.frames - 1}, got ${JSON.stringify(u.f0)}`);
 		const keys = [...skillKeys, ...own];
-		const ctx = { sk, scene, frames: spec.frames, fps: spec.fps ?? 24, auto, props: { ...merged.props, ...spec.props }, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys,
+		const ctx = { sk, scene, frames: spec.frames, fps: spec.fps ?? 24, auto, fit, props: { ...merged.props, ...spec.props }, self: spec.fix !== false && spec.fix?.self !== false, f0: u.f0, args: structuredClone(u.args ?? {}), tag, keys,
 			use: spec.use, index: i, place: fixOptions(spec.fix).stance, state: structuredClone(stateAt(keys, u.f0)), anchors: { ...merged.anchors, ...spec.anchors }, objects: { ...merged.objects, ...spec.objects } };
 		const part = SKILLS[u.skill](ctx), last = Math.max(part.end ?? u.f0, ...part.keys.map(k => k.f));
 		if (last > spec.frames - 1) bad(`${tag} needs ${last - u.f0} frames from f${u.f0} (to f${last}), past the last frame f${spec.frames - 1}; set frames >= ${last + 1} or frames: "auto"`);
@@ -77,7 +111,7 @@ export function expandUse(spec, { sk, scene, lenient = false, auto = false }) {
 		// fields a skill fills into an entry when it leaves them out (throwObject: a carry's release and fall)
 		for (const [id, f] of Object.entries(part.fills ?? {})) merged.fills[id] = { ...merged.fills[id], ...f };
 		merged.goals.push(...(part.goals ?? []));
-		used.push({ skill: u.skill, f0: u.f0, end: part.end, ...(part.paced ? { paced: part.paced } : {}), ...(part.cut ? { cut: part.cut } : {}), ...(part.placed ? { placed: part.placed } : {}) });
+		used.push({ skill: u.skill, f0: u.f0, end: part.end, ...(part.paced ? { paced: part.paced } : {}), ...(part.cut ? { cut: part.cut } : {}), ...(part.placed ? { placed: part.placed } : {}), ...(part.adjust ? { adjust: part.adjust } : {}) });
 	});
 	const out = { ...spec, keys: [...skillKeys, ...own], anchors: { ...merged.anchors, ...spec.anchors }, props: { ...merged.props, ...spec.props },
 		objects: { ...merged.objects, ...spec.objects } };

package/src/motion3/skills/info.js

@@ -25,7 +25,7 @@ export const SKILL_INFO = {
 		place: { at: 0.03 },
 	},
 	walkTo: {
-		args: { to: xz("[x, z] world m: the heading turns toward it and the steps cover the distance"), ...walkArgs,
+		args: { to: xz("[x, z] world m: the heading turns toward it and the steps cover the distance (given steps, the stride or the step count and cadence is fitted to it in a natural gait, or the walk is refused)"), ...walkArgs,
 			heading: { oneOf: [num(), WALK_TYPES.heading], description: "degrees: h1, or [h0, h1]" },
 			arrive: int("with to and no steps/period/step/swing: the frame to end by (feet together); the engine picks the cadence (observations.planned)") },
 		needs: "a standing pose keyed before f0", frames: "16 + steps * period + 18",

package/src/motion3/skills/stance.js

@@ -51,6 +51,12 @@ export function clearStance(sk, scene, c, h) {
 	return null;
 }
 
+
+/** The standing body at c ([x, z]) facing h: its least distance to the bodies (ids not in skip; m, negative inside). */
+export function standClearance(sk, scene, c, h, skip = new Set()) {
+	const boxes = obstacles({ objects: Object.fromEntries(Object.entries(scene?.objects ?? {}).filter(([id]) => !skip.has(id))) });
+	return boxes.length ? clearance(sk, boxes, c, h) : Infinity;
+}
 /**
  * The world point an anchor definition names on the still scene, as anchors.js resolves it: world p; an object's (or a
  * group's) `local` point, its base pivot without one; with `grasp` and no `local`, the centre of its parts (where a

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/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/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/shell/ExportFolderPreference.jsx

@@ -0,0 +1,103 @@
+import { useEffect, useState } from "react";
+import { ko } from "../locale.js";
+import {
+	canChooseExportWorkspace,
+	chooseExportWorkspace,
+	clearExportWorkspace,
+	loadExportWorkspace,
+	requestExportWorkspacePermission,
+} from "../export-workspace.js";
+import { PreferenceRow } from "./preference-controls.jsx";
+
+const SUPPORTED_DESCRIPTION = ko(
+	"When set, exports are written here instead of your browser's Downloads folder.",
+	"설정하면 내보낸 파일이 브라우저 다운로드 폴더 대신 이 폴더에 저장됩니다.",
+);
+
+function statusCopy(permission) {
+	if (permission === "prompt") return ko("Folder access needs to be re-allowed.", "폴더 접근을 다시 허용해야 해요.");
+	if (permission === "denied") return ko("Folder access was denied. Choose another folder or use Downloads.", "폴더 접근이 거부되었어요. 다른 폴더를 선택하거나 다운로드를 사용하세요.");
+	return null;
+}
+
+export default function ExportFolderPreference() {
+	const supported = canChooseExportWorkspace();
+	const [workspace, setWorkspace] = useState(null);
+	const [busy, setBusy] = useState(false);
+	const [error, setError] = useState(null);
+
+	useEffect(() => {
+		let active = true;
+		loadExportWorkspace().then((value) => {
+			if (active) setWorkspace(value);
+		});
+		return () => { active = false; };
+	}, []);
+
+	const choose = async () => {
+		setBusy(true);
+		setError(null);
+		try {
+			const handle = await chooseExportWorkspace();
+			setWorkspace({ handle, permission: "granted" });
+		} catch (cause) {
+			if (cause?.name !== "AbortError") setError(ko("Could not choose the export folder.", "내보내기 폴더를 선택하지 못했어요."));
+		} finally {
+			setBusy(false);
+		}
+	};
+
+	const allow = async () => {
+		if (!workspace?.handle) return;
+		setBusy(true);
+		setError(null);
+		try {
+			const permission = await requestExportWorkspacePermission(workspace.handle);
+			setWorkspace({ ...workspace, permission });
+		} finally {
+			setBusy(false);
+		}
+	};
+
+	const clear = async () => {
+		setBusy(true);
+		setError(null);
+		try {
+			const cleared = await clearExportWorkspace();
+			if (cleared) setWorkspace(null);
+			else setError(ko("Could not clear the export folder.", "내보내기 폴더를 해제하지 못했어요."));
+		} finally {
+			setBusy(false);
+		}
+	};
+
+	const status = workspace ? statusCopy(workspace.permission) : null;
+	const folderName = workspace?.handle?.name ?? ko("Browser downloads", "브라우저 다운로드");
+	const description = supported ? SUPPORTED_DESCRIPTION : ko("This browser cannot choose an export folder; exports continue to Downloads.", "이 브라우저에서는 내보내기 폴더를 선택할 수 없어요. 내보내기는 다운로드 폴더로 이어집니다.");
+
+	return (
+		<PreferenceRow title={ko("Export folder", "내보내기 폴더")} description={description} testid="preferences-export-folder" full>
+			<div className="v2-preferences__export-folder">
+				<span className="v2-preferences__export-folder-name" data-testid="preferences-export-folder-name">{folderName}</span>
+				{status && <span className="v2-preferences__export-folder-status" role="status">{status}</span>}
+				{error && <span className="v2-preferences__export-folder-status" role="alert">{error}</span>}
+				<div className="v2-preferences__language-controls" role="group" aria-label={ko("Export folder actions", "내보내기 폴더 작업")}>
+					{workspace && workspace.permission !== "granted" && (
+						<button type="button" className="v2-preferences__language" data-testid="settings-export-folder-allow" disabled={busy} onClick={allow}>
+							{ko("Allow", "허용")}
+						</button>
+					)}
+					<button type="button" className="v2-preferences__language" data-testid="settings-export-folder-choose" disabled={!supported || busy} onClick={choose}>
+						{busy ? ko("Choosing…", "선택 중…") : ko("Choose folder…", "폴더 선택…")}
+					</button>
+					{workspace && (
+						<button type="button" className="v2-preferences__language" data-testid="settings-export-folder-clear" disabled={busy} onClick={clear}>
+							{ko("Use Downloads", "다운로드 사용")}
+						</button>
+					)}
+				</div>
+			</div>
+			<span className="v2-preferences__export-folder-note">{ko("Existing files are never overwritten; numbered names are used.", "같은 이름의 파일이 있으면 번호가 붙고 덮어쓰지 않아요.")}</span>
+		</PreferenceRow>
+	);
+}