cozyclay 3.1.0 → 3.1.2

package/src/motion3/repair.js

@@ -3,22 +3,37 @@
 // the patch the latest compile gives that group. When none is kept, the top 2 groups just past
 // their limit with no patch, or a missed goal, get a small local search (repair-tune.js: the
 // responsible skill's args, the key pair of a speed spike, or for a goal where the body stands
-// and how it leans); the best candidate is the round's change. A change
-// is kept only when the summed severity (qa/severity.js) drops and no goal that held fails, else
-// it is undone. A round that keeps nothing ends the repair. The compiler is deterministic and
-// the candidates come in a fixed order, so the repair is too; no new compile starts after 20 s.
+// and how it leans); the best candidate is the round's change. A change is kept only when
+// qa/verdict.js compareQa calls it better (the summed severity drops, no goal that held fails, no
+// more problems, and what got worse costs at most half of what got better), else it is undone, so
+// the result is never worse than the spec as sent. A failure local to an arm (its reach, wrist,
+// elbow, a hand or forearm into something) is tried without moving the body first: a patch or a
+// candidate that moves the root (a stance, a walk's length, the root keys) comes only when nothing
+// else is kept, and the applied entry says so (movedBody). A patch tried and not kept is not tried
+// again, so the groups after it get their turn. A round that keeps nothing ends the repair. The
+// compiler is deterministic and the candidates come in a fixed order, so the repair is too; no new
+// compile starts after 20 s.
 import { applyPatch } from "./json-patch.js";
 import { groupKey } from "./qa/severity.js";
 import { tuneCandidates } from "./repair-tune.js";
+import { compareQa } from "./qa/verdict.js";
 
 const TRIES = 3, TUNE_GROUPS = 2, LIMIT_MS = 20000;
 const groupsOf = r => r?.qa?.groups ?? [];
 const totalOf = r => groupsOf(r).reduce((sum, g) => sum + (g.severity ?? 0), 0);
 const failedOf = r => (r?.qa?.goals ?? []).filter(g => !g.ok).length;
 const groupIn = (r, key) => groupsOf(r).find(g => groupKey(g) === key);
-const heldOf = r => (r?.qa?.goals ?? []).filter(g => g.ok).map(g => g.name);
-/** Lower summed severity, no more failed goals, and every goal that held still holds. */
-const better = (r, than) => totalOf(r) < totalOf(than) - 1e-9 && failedOf(r) <= failedOf(than) && heldOf(than).every(n => heldOf(r).includes(n));
+/** qa/verdict.js: lower summed severity, no goal lost, no more problems, no trade of one failure for worse ones. */
+const better = (r, than) => compareQa(r?.qa, than?.qa).better;
+
+const ARM_PART = /^(hand|farm|uarm)_[lr]\b|^(Left|Right)(Arm|ForeArm|Hand)/;
+/** A failure of one arm: its reach, wrist or elbow, or a hand, forearm or upper arm into something. */
+const armLocal = g => (g.kind === "REACH" && /^arm_miss_[lr]$/.test(g.subject)) || ["WRIST", "ELBOW"].includes(g.kind)
+	|| (["BODY", "FACE", "COLLIDE", "POP", "ACC", "SPEED", "FLIP"].includes(g.kind) && ARM_PART.test(g.subject));
+/** A patch that moves where the body stands: a stance, a walk's length or end, a root key. */
+const movesBody = patch => patch.some(o => /^\/use\/\d+\/args(\/(at|step|firstStep|to))?$/.test(o.path) && (o.path.endsWith("/args") ? ["at", "step", "firstStep", "to"].some(k => o.value?.[k] !== undefined) : true)
+	|| /^\/keys\/\d+\/set\/root$/.test(o.path) || (o.path === "/keys/-" && o.value?.set?.root !== undefined));
+const MOVED = "the body moved: no change that keeps it in place fixed this arm's failure";
 
 /**
  * repairSpec(spec, { rounds }, compile) -> { spec, result, repair }
@@ -26,12 +41,13 @@ const better = (r, than) => totalOf(r) < totalOf(than) - 1e-9 && failedOf(r) <=
  * @param {{ rounds?: number }} opts  1..8 (default 4)
  * @param {(spec: object) => object} compile  spec -> pipeline.js compileSpec result (qa.groups[i].patch)
  * @returns {{ spec: object, result: object, repair: { rounds: number, compiles: number,
- *   applied: { kind: string, subject: string, patch: object[], severity: number[] }[], rejected: number } }}
+ *   applied: { kind: string, subject: string, patch: object[], severity: number[], movedBody?: string }[], rejected: number } }}
  */
 export function repairSpec(spec, opts, compile) {
 	const want = Math.min(8, Math.max(1, Math.round(Number(opts?.rounds ?? 4)) || 4)), t0 = performance.now();
 	const late = () => performance.now() - t0 >= LIMIT_MS;
 	let current = spec, result = compile(spec), compiles = 1, rejected = 0, rounds = 0;
+	const refused = new Set();
 	const applied = [];
 	/** Compiles current + patch; null (counted as rejected) when the patch or the spec fails. */
 	const attempt = patch => {
@@ -45,38 +61,55 @@ export function repairSpec(spec, opts, compile) {
 		}
 	};
 	const keep = (g, key, patch, { next, r }) => {
-		applied.push({ kind: g.kind, subject: g.subject, patch, severity: [g.severity, groupIn(r, key)?.severity ?? 0] });
+		const moved = armLocal(g) && movesBody(patch);
+		applied.push({ kind: g.kind, subject: g.subject, patch, severity: [g.severity, groupIn(r, key)?.severity ?? 0], ...(moved ? { movedBody: MOVED } : {}) });
 		current = next; result = r;
 	};
-	/** The best tune candidate for group g (repair-tune.js); true when it is kept. */
-	const tune = g => {
-		let best = null;
-		for (const patch of tuneCandidates(g, current)) {
+	/** The best of the patches for group g; true when one is kept. */
+	const best = (g, patches) => {
+		let top = null;
+		for (const patch of patches) {
 			if (late()) break;
 			const t = attempt(patch);
 			if (!t) continue;
-			if (better(t.r, best?.r ?? result)) { if (best) rejected += 1; best = { ...t, patch }; } else rejected += 1;
-			if (best && totalOf(best.r) === 0 && !failedOf(best.r)) break;
+			if (better(t.r, top?.r ?? result)) { if (top) rejected += 1; top = { ...t, patch }; } else rejected += 1;
+			if (top && totalOf(top.r) === 0 && !failedOf(top.r)) break;
 		}
-		if (best) keep(g, groupKey(g), best.patch, best);
-		return Boolean(best);
+		if (top) keep(g, groupKey(g), top.patch, top);
+		return Boolean(top);
+	};
+	/** The tune candidates for group g (repair-tune.js); an arm's failure tries those that keep the body in place first. */
+	const tune = g => {
+		const all = tuneCandidates(g, current);
+		if (!armLocal(g)) return best(g, all);
+		return best(g, all.filter(p => !movesBody(p))) || best(g, all.filter(movesBody));
 	};
 	while (rounds < want && !late()) {
-		const keys = groupsOf(result).filter(g => g.patch).slice(0, TRIES).map(groupKey);
+		// a patch already tried and not kept is not tried again: the groups after it get their turn
+		const keys = groupsOf(result).filter(g => g.patch && !refused.has(JSON.stringify(g.patch))).slice(0, TRIES).map(groupKey);
 		const near = groupsOf(result).filter(g => tuneCandidates(g, current).length).slice(0, TUNE_GROUPS).map(groupKey);
 		if (!keys.length && !near.length) break;
 		rounds += 1;
 		let kept = 0;
+		const deferred = [];
 		for (const key of keys) {
 			const g = groupIn(result, key);
 			if (!g?.patch || late()) continue;
+			// an arm's failure whose patch moves the body waits until nothing else is kept this round
+			if (armLocal(g) && movesBody(g.patch)) { deferred.push(key); continue; }
 			const t = attempt(g.patch);
-			if (t && better(t.r, result)) { keep(g, key, g.patch, t); kept += 1; } else if (t) rejected += 1;
+			if (t && better(t.r, result)) { keep(g, key, g.patch, t); kept += 1; } else { refused.add(JSON.stringify(g.patch)); if (t) rejected += 1; }
 		}
 		for (const key of kept ? [] : near) {
 			const g = groupIn(result, key);
 			if (g && !late() && tune(g)) { kept += 1; break; }
 		}
+		for (const key of kept ? [] : deferred) {
+			const g = groupIn(result, key);
+			if (!g?.patch || late()) continue;
+			const t = attempt(g.patch);
+			if (t && better(t.r, result)) { keep(g, key, g.patch, t); kept += 1; break; } else { refused.add(JSON.stringify(g.patch)); if (t) rejected += 1; }
+		}
 		if (!kept) break;
 	}
 	return { spec: current, result, repair: { rounds, compiles, applied, rejected } };

package/src/motion3/report.js

@@ -2,30 +2,55 @@
 // head and readback take about 1.5 KB), so fitOutput keeps the most useful parts within
 // MOTION_OUTPUT_BUDGET bytes of JSON and says what it cut in `more`; the cut parts stay in the
 // spec store (spec-store.js) and motion.report pages through them. Keep order (first = last cut):
-//   1. frames, fps, installed, specId, qa.ok/total/goals, observations, delta, repair  (always;
+//   1. brief, frames, fps, installed, specId, qa.ok/total/goals, observations, delta, repair  (always;
 //      observations are bounded: a fixed set of joints and limbs, about 1 KB)
 //   2. the first MIN_FULL qa.groups in full
 //   3. probes
 //   4. timeline (the planted spans go first, then entries from the end)
 //   5. the other groups as one-liners { kind, subject, count, severity, first, last }
-//   6. fixed, search, skills, ms
-// Room left after that turns one-liners back into full groups, from the top.
+//   6. qa.warnings (qa/arm-checks.js: never failing, so after every group), as many lines as fit
+//   7. fixed, search, skills, ms
+// An answer that does not fit and has a delta (base + patch) says observations.units only by reference: the
+// base's answer gave them. Last resort: observations.asked and the brief lose lines, then full groups become one-liners.
+// Room left after that turns one-liners back into full groups, from the top. A head still too big (a
+// repair that applied many patches) keeps the newest repair.applied entries; more.repair counts the rest.
+// brief (briefOf) is the answer in a few fixed-shape lines, so a script comparing variants returns it as
+// it is instead of mapping qa itself:
+//   "<specId> qa ok|<problems> problems (<total> issues)[, installed|not installed]"
+//   "goals <n ok>/<n>[; MISS <name> <value> f<at> (<= or >= need)]...[; <n> more]"  (when the spec has goals; 3 misses)
+//   "<KIND> <subject> x<count> f<first>-<last>"  (the first 2 groups past the GOAL ones, which MISS names; subject cut to 48)
 
 export const MOTION_OUTPUT_BUDGET = 6000;
-const MIN_FULL = 4;
+const MIN_FULL = 4, BRIEF_GROUPS = 2, BRIEF_MISSES = 3, BRIEF_SUBJECT = 48;
+const AT_MOST = new Set(["near", "still"]), UNITS_SEEN = "as in the base's answer";
 const size = v => new TextEncoder().encode(JSON.stringify(v)).length;
 const oneLine = g => ({ kind: g.kind, subject: g.subject, count: g.count, severity: g.severity, first: g.first, last: g.last });
 
+/** The fixed-shape summary lines of an answer with qa (see the head comment), or null without qa. */
+export function briefOf({ specId, installed, qa }) {
+	if (!qa) return null;
+	const head = `${specId ?? "spec"} qa ${qa.ok ? "ok" : `${qa.problems ?? qa.groups?.length ?? 0} problems (${qa.total} issues)`}${installed === undefined ? "" : installed ? ", installed" : ", not installed"}`;
+	const goals = qa.goals ?? [], failed = goals.filter(g => !g.ok), miss = failed.slice(0, BRIEF_MISSES)
+		.map(g => `; MISS ${g.name} ${g.value ?? "never"}${g.at === null ? "" : ` f${g.at}`} (${AT_MOST.has(g.kind) ? "<=" : ">="} ${g.need})`).join("");
+	const more = failed.length > BRIEF_MISSES ? `; ${failed.length - BRIEF_MISSES} more` : "";
+	const groups = (qa.groups ?? []).filter(g => g.kind !== "GOAL").slice(0, BRIEF_GROUPS).map(g => `${g.kind} ${g.subject.slice(0, BRIEF_SUBJECT)} x${g.count} f${g.first}-${g.last}`);
+	return [head, ...(goals.length ? [`goals ${goals.length - failed.length}/${goals.length}${miss}${more}`] : []), ...groups];
+}
+
 /**
- * full output -> output within `budget` bytes of JSON. When something was cut it carries
+ * full output -> output within `budget` bytes of JSON, with brief (briefOf) first. When something was cut it carries
  * more: { specId, groups, timeline, probes }, how many items of each part are missing or
  * shortened; motion.report { specId, part, from } pages the whole part.
  */
-export function fitOutput(full, budget = MOTION_OUTPUT_BUDGET) {
+export function fitOutput(answer, budget = MOTION_OUTPUT_BUDGET) {
+	const brief = briefOf(answer), full = brief ? { brief, ...answer } : answer;
 	if (size(full) <= budget) return full;
-	const { qa, observations, probes, timeline, fixed, search, skills, ms, ...head } = full;
+	const { qa, observations: all, probes, timeline, fixed, search, skills, ms, ...head } = full;
+	// an answer to base + patch leaves out the units the base's answer gave
+	const observations = all?.units && full.delta ? { ...all, units: UNITS_SEEN } : all;
 	const groups = qa?.groups ?? [], more = { specId: full.specId, groups: 0, timeline: 0, probes: 0 };
-	const out = { ...head, ...(qa ? { qa: { ...qa, groups: [] } } : {}), ...(observations ? { observations } : {}) };
+	const { warnings, ...qaHead } = qa ?? {};
+	const out = { ...head, ...(qa ? { qa: { ...qaHead, groups: [] } } : {}), ...(observations ? { observations } : {}) };
 	// the counts in `more` may still grow by a digit or two after a check
 	const fits = extra => size({ ...out, ...extra, more }) <= budget - 32;
 	const nFull = Math.min(MIN_FULL, groups.length);
@@ -43,10 +68,26 @@ export function fitOutput(full, budget = MOTION_OUTPUT_BUDGET) {
 		more.timeline = list === lean ? timeline.length : timeline.length - n;
 	}
 	for (let i = nFull; i < groups.length && fits({ qa: { ...out.qa, groups: [...out.qa.groups, oneLine(groups[i])] } }); i++) out.qa.groups.push(oneLine(groups[i]));
+	for (let n = warnings?.length ?? 0; n > 0; n--) if (fits({ qa: { ...out.qa, warnings: warnings.slice(0, n) } })) { out.qa.warnings = warnings.slice(0, n); break; }
 	for (const [k, v] of [["fixed", fixed], ["search", search], ["skills", skills], ["ms", ms]]) if (v !== undefined && fits({ [k]: v })) out[k] = v;
 	for (let i = nFull; i < out.qa?.groups.length && fits({ qa: { ...out.qa, groups: out.qa.groups.map((g, j) => (j === i ? groups[i] : g)) } }); i++) out.qa.groups[i] = groups[i];
-	// last resort (huge hints): full groups become one-liners from the end
+	// last resort (huge hints): observations.asked loses its goal and contact lines from the end, the brief its group
+	// lines, then full groups become one-liners from the end, then asked loses its skill lines
+	const asked = out.observations?.asked, cut = keep => { while (out.observations.asked.length > keep && !fits({})) out.observations.asked.pop(); };
+	if (asked) { out.observations = { ...out.observations, asked: [...asked] }; cut(asked.filter(l => l.startsWith("use[")).length); }
+	// the brief's group lines repeat qa.groups
+	while (out.brief?.length > 1 && !out.brief[out.brief.length - 1].startsWith("goals ") && !fits({})) out.brief = out.brief.slice(0, -1);
 	for (let i = nFull - 1; i >= 0 && !fits({}); i--) out.qa.groups[i] = oneLine(groups[i]);
+	// a long repair (each applied patch in full) keeps its newest changes; the stored spec holds them all
+	const applied = out.repair?.applied;
+	if (Array.isArray(applied) && !fits({})) {
+		let n = applied.length;
+		while (n > 0 && !fits({ repair: { ...out.repair, applied: applied.slice(applied.length - n) } })) n--;
+		out.repair = { ...out.repair, applied: applied.slice(applied.length - n) };
+		more.repair = applied.length - n;
+	}
+	if (asked) cut(0);
+	if (asked && !out.observations.asked.length) delete out.observations.asked;
 	more.groups = groups.length - (out.qa?.groups ?? []).filter(g => "worst" in g).length;
 	return { ...out, more };
 }

package/src/motion3/schema/topics.js

@@ -42,7 +42,7 @@ export const EXAMPLES = {
 		{ f: 30, set: { lid: 1 }, step: ["lid"] }] },
 	refs: { props: { cupGrip: GRIP }, anchors: { spot: SPOT }, goals: [
 		{ name: "fingers at the spot", near: ["prop:cupGrip.fingers", "anchor:spot"], at: 30 },
-		{ name: "cup at the mouth", near: ["object:cup.top", "landmark:mouth"], tol: 0.06, at: [40, 50] },
+		{ name: "cup at the mouth", near: ["object:cup.rim", "landmark:mouth"], tol: 0.06, at: [40, 50] },
 		{ name: "hand above the hips", above: ["joint:RightHand", "bone:Hips"], at: 30 }] },
 	fix: { fix: { reach: true, slide: true, penetration: 0.02, self: true, retime: false } },
 };
@@ -99,17 +99,19 @@ export const NOTES = {
 		"at is an absolute frame or [f0, f1]; mode all (every frame; the default) or any (one frame; speed's default). A failed goal is a GOAL group first in qa.groups and makes qa.ok false.",
 		"after / before: another goal's name; at is cut to the frames after (before) the first frame that goal holds, so cause and effect keep their order wherever the event lands (the can moves after the kick). If that goal never holds, this one fails with value null.",
 		"Intent lines as goals: a contact is near between the touching point (joint:RightHandIndex4, joint:RightToeBase) and the object, tol 0.02-0.03; a negative is still on the object before: \"<contact goal>\"; an effect is moved on the object after: \"<contact goal>\" (mode any); a strike is speed of the joint, by m/s, before: \"<contact goal>\"; an effect on something nobody holds (a can that drops, a machine that rocks) moves it by spec.objects keys or fall (topic: \"objects\"), not a hinge or a swapped copy.",
-		"A cup or can brought to the mouth: give its aim keys lean 20-30 so the elbow stays low (observations.wrist raised counts the frames with the elbow over the shoulder)."],
+		"A cup or can brought to the mouth: an aim key with its top at the lips leans 45 by default so the elbow stays low (lean 0 holds aim exactly; observations.wrist raised counts the frames with the elbow over the shoulder). qa.warnings (ARM, never failing) name an elbow over the shoulder, over the head or flared out, its frames and the key or elbow_<side> pole that fixes it."],
 	probes: ["motion.compile { probes } (at most 16); spec.probes are measured too, not stored; answered whether or not it installs.",
 		"distance [a, b] -> { min, minAt, max, maxAt, mean, first, last } in m; a bare object:<id> measures to its surface. position -> { at: [{ f, p }] }, at most 16 rows."],
 	channels: ["key.set names channels; values ease between keys and hold after the last key. step: [channel] jumps at f instead.",
-		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. flow: false turns it off; { smooth: false } or { lag: false } one part.",
+		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); and each change breaks along the body (overlap: the lower spine, chest, head, upper arm, forearm and wrist start and settle a few frames apart, one side trailing the other, the arm's swing settling past its stop; less for a short move, none on an arm's IK or a walk); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. flow: false turns it off; { smooth: false }, { lag: false } or { overlap: false } one part (overlap: a number 0..2 scales it).",
 		"w_<anchor>_<side> (0..1) weights a hand onto an anchor; the weights of one hand add up to at most 1.",
 		"Any other numeric channel must come from spec.channels, a hinge (objects.<id>.channel), a check's when or a visible switch; names ending _vis are visibility switches (shown above 0.5)."],
-	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base], person:<character id>.<Bone> (another character's joint in its installed take).",
+	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base|.rim], person:<character id>.<Bone> (another character's joint in its installed take).",
+		"object .center/.top/.base are points of its world bounding box (a tilted cup's .top is not its rim); .rim is its opening (the top face in its own axes, tilting with it), against another point the nearest edge: drink goals take .rim.",
 		"object:<id> takes a body or a group (the box around its parts); in a distance a bare object:<id> means its surface.",
 		"Goals and probes take every kind; spec.checks keep joint:, prop: and anchor:."],
 	fix: [`spec.fix keys: ${FIX_KEYS.join(", ")}; false turns all off. output.fixed reports what each one changed.`,
 		"reach, slide, self and stance are on by default; penetration and retime are opt-in.",
+		"reach also brings the body to a hand on a world or scene-object anchor the straight arm misses: a lean, a hip shift, lower hips, the feet kept (fixed.reachBody lists each move); farther, place the body. retime is kept only when QA is no worse with it.",
 		"self keeps the arms out of the body on its fitted skin (QA BODY measures the same skin): wrist targets inside it go onto it, elbows turn about the shoulder-wrist line, a hand a little inside is pushed out. A fit's target (the mouth) is never moved; what is left is BODY, with checks.allow { part, object: <body part>, depth } for a contact meant to touch (a hand on a knee)."],
 };

package/src/motion3/schema/types.js

@@ -148,6 +148,6 @@ export const FIX_TYPES = {
 
 export const REF_DOCS = {
 	joint: "joint:<Bone>", bone: "bone:<Bone> (= joint:)", prop: "prop:<prop>.<point> (origin exists)",
-	anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base], a body or group; bare = its surface (distance)",
+	anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base|.rim], a body or group; bare = its surface (distance)",
 	person: "person:<id>.<Bone>",
 };

package/src/motion3/skills/basic.js

@@ -4,6 +4,7 @@ import { add, apply, ry } from "../compiler/math.js";
 import { walk } from "../compiler/walk.js";
 import { keyBook, skillError } from "./book.js";
 import { walkEnd } from "./info.js";
+import { fitTo, walkEndAt, r2, xzText, REACH_TOL } from "./walk-fit.js";
 import { GRASP_FINGERS, GRASP_POINTS } from "../compiler/vocab.js";
 import { clearStance, reachStance } from "./stance.js";
 import { CLOSE, GAZE, gazeAt, headKeyed, earlyTransport, holdsOpen, transportKeys } from "./reach-human.js";
@@ -40,30 +41,36 @@ export function standIdle(ctx) {
 /**
  * walkTo({ to: [x, z] } | { heading: h | [h0, h1] }, steps, step = 0.5, turnDistance, ...): the
  * walk generator from the pose at f0. With `to` the heading turns toward the point and the step
- * count covers the distance. Ends 16 + steps * period + 18 frames after f0, feet together; a
- * take that ends after the last step holds that pose to its end. The steps keep a natural rhythm
- * (compiler/gait-rhythm.js); vary: 0 makes every step the same.
+ * count covers the distance; with steps as well the stride is fitted so they end there (fitTo). Ends
+ * 16 + steps * period + 18 frames after f0, feet together; a take that ends after the last step holds
+ * that pose to its end. A walk with `to` that ends more than 0.1 m from it says where in `placed`. The
+ * steps keep a natural rhythm (compiler/gait-rhythm.js); vary: 0 makes every step the same.
  */
 export function walkTo(ctx) {
 	const { args, state } = ctx;
 	if (!state.foot_l || !state.foot_r || !state.root) skillError(ctx.tag, "needs a standing pose keyed before f0 (use standIdle or another skill first)");
-	const gen = { type: "walk", f0: ctx.f0, ...args };
+	let gen = { type: "walk", f0: ctx.f0, ...args }, adjust, c0, h1;
 	delete gen.to; delete gen.arrive;
 	const h0 = state.yaw ?? 0, step = args.step ?? 0.5, first = args.firstStep ?? 0.4;
 	if (args.to) {
-		const c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2];
+		c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2];
 		const dx = args.to[0] - c0[0], dz = args.to[args.to.length - 1] - c0[1], d = Math.hypot(dx, dz);
-		let h1 = Math.atan2(dx, dz) * 180 / Math.PI;
+		h1 = Math.atan2(dx, dz) * 180 / Math.PI;
 		while (h1 - h0 > 180) h1 -= 360;
 		while (h1 - h0 < -180) h1 += 360;
 		gen.heading = args.heading ?? [h0, h1];
 		gen.steps = args.steps ?? Math.max(2, 2 + Math.round((d - first) / step));
+		if (typeof gen.heading === "number") gen.heading = [h0, gen.heading];
+		if (ctx.fit && d > REACH_TOL) ({ gen, adjust } = fitTo(ctx, gen, c0, d, h1));
 	}
 	if (typeof gen.heading === "number") gen.heading = [h0, gen.heading];
 	const keys = walk(gen, ctx.keys, ctx.sk, ctx.tag), end = walkEnd(gen), last = ctx.frames - 1;
+	const at = args.to && walkEndAt(keys), miss = at ? Math.hypot(at[0] - args.to[0], at[1] - args.to[args.to.length - 1]) : 0;
+	const placed = miss > REACH_TOL ? { placed: { at: at.map(r2), heading: Math.round(gen.heading?.[1] ?? h0), why: `ends ${r2(miss)} m from to ${xzText(args.to)}` } } : {};
+	const more = { ...placed, ...(adjust ? { adjust } : {}) };
 	// the settle after the last step only holds the pose: a take that ends in it ends the walk there
-	if (end > last && Math.max(...keys.filter(k => k.f < end).map(k => k.f)) <= last) return { keys: keys.filter(k => k.f <= last), end: last, cut: `settle cut at f${last} (hold to the end)` };
-	return { keys, end };
+	if (end > last && Math.max(...keys.filter(k => k.f < end).map(k => k.f)) <= last) return { keys: keys.filter(k => k.f <= last), end: last, cut: `settle cut at f${last} (hold to the end)`, ...more };
+	return { keys, end, ...more };
 }
 
 /** base when `props` has no other prop of that name (the same one again is fine), else base_<side>, base_<side>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