cozyclay 2.1.1 → 3.0.1

package/src/motion3/describe.js

@@ -0,0 +1,177 @@
+// C9. motion.describe { topic, name? }: the spec's schema, a valid example and notes. The field
+// lists come from schema/fields.js, their types from schema/types.js, channels from
+// compiler/vocab.js, FIX_KEYS from fix/index.js, the skills from skills/index.js and
+// skills/info.js; examples and notes from schema/topics.js. Every answer fits DESCRIBE_BUDGET.
+//   topic "essentials"          { topic, types: { <topic or shared shape>: type line }, skills: [{ name, args (type line), needs, frames, adds }], notes }
+//                               (the lines of MEANT parts carry each field's meaning; SHALLOW topics name their parts only)
+//   other topic                 { topic, schema (JSON Schema 2020-12 fragment), example, notes }
+//   topic "skills"              { topic, skills: [{ name, args, needs, frames, adds }] }
+//   topic "skills", name        { topic, name, schema (the skill's args), example (a use entry), notes }
+//   topic "examples"            { topic, examples: [{ name, scene, spec }] (whole specs, schema/spec-examples.js), notes }
+// motion.describe { topics: [{ topic, name? }] } (describeMany): { topics: [those answers, in order], more?: [the asks that
+// did not fit] }, so a request's topics cost one call; the Studio prompt already carries essentials and goals.
+import { SPEC_FIELDS, KEY_FIELDS, USE_FIELDS, ANCHOR_FIELDS, PROP_FIELDS, FIT_FIELDS, OBJECT_FIELDS, WALK_FIELDS, CHECK_FIELDS, CHECK_ENTRY_FIELDS,
+	GOAL_FIELDS, PROBE_FIELDS, REF_KINDS, DESCRIBE_TOPICS } from "./schema/fields.js";
+import { DEFS, SPEC_TYPES, KEY_TYPES, USE_TYPES, WALK_TYPES, ANCHOR_TYPES, ANCHOR_REQUIRED, PROP_TYPES, FIT_TYPES, OBJECT_TYPES, FREE_TYPES, CHECK_ENTRY_TYPES, CHECK_REQUIRED, CHECKS_TYPES,
+	GOAL_TYPES, PROBE_TYPES, FIX_TYPES, REF_DOCS } from "./schema/types.js";
+import { EXAMPLES, NOTES } from "./schema/topics.js";
+import { SPEC_EXAMPLES, EXAMPLE_NOTES } from "./schema/spec-examples.js";
+import { briefType } from "./schema/brief.js";
+import { VEC_CHANNELS, NUM_CHANNELS, MAP_CHANNELS, SKILL_CHANNELS, FINGER_PRESETS, CHANNEL_DOCS, channelFamily, rangeOf, didYouMean } from "./compiler/vocab.js";
+import { FIX_KEYS } from "./fix/index.js";
+import { SKILL_NAMES } from "./skills/index.js";
+import { SKILL_INFO } from "./skills/info.js";
+
+/** Bytes of JSON a describe answer may take: the 8 KiB receipt minus 768 B for a describe receipt's
+ * head (569 B in a live Studio receipt: ids, host, revision, summary; no readback, it changes nothing). */
+export const DESCRIBE_BUDGET = 8192 - 768;
+
+const bad = msg => { throw new Error(`MOTION_SPEC_INVALID: ${msg}`); };
+const typeOf = (types, f, table) => types[f] ?? bad(`describe: ${table}.${f} has no type in schema/types.js`);
+
+/** { type: object } with exactly `fields`, each typed from `types`. */
+const objectOf = (fields, types, table, required = []) => ({ type: "object", properties: Object.fromEntries(fields.map(f => [f, typeOf(types, f, table)])),
+	...(required.length ? { required } : {}), additionalProperties: false });
+const listOf = (items, extra) => ({ type: "array", items, ...extra });
+const oneOfRequired = names => ({ oneOf: names.map(n => ({ required: [n] })) });
+
+const LOCAL_DEFS = {
+	key: () => objectOf(KEY_FIELDS, KEY_TYPES, "key", ["f", "set"]),
+	use: () => { const o = objectOf(USE_FIELDS, USE_TYPES, "use", ["skill", "f0"]); o.properties.skill = { enum: SKILL_NAMES }; return o; },
+	walk: () => objectOf(WALK_FIELDS, WALK_TYPES, "generators[i]", ["type", "f0"]),
+};
+
+/** The schema with $schema and the $defs it (transitively) refers to. */
+function rooted(schema) {
+	const defs = {}, all = { ...DEFS, ...LOCAL_DEFS };
+	for (let more = true; more;) {
+		more = false;
+		const json = JSON.stringify([schema, defs]);
+		for (const [name, d] of Object.entries(all)) if (!defs[name] && json.includes(`"#/$defs/${name}"`)) { defs[name] = typeof d === "function" ? d() : d; more = true; }
+	}
+	return { $schema: "https://json-schema.org/draft/2020-12/schema", ...schema, ...(Object.keys(defs).length ? { $defs: defs } : {}) };
+}
+
+function channelSchema(ch) {
+	const twin = ch.replace(/_r$/, "_l");
+	if (twin !== ch && (VEC_CHANNELS.has(twin) || NUM_CHANNELS.has(twin) || MAP_CHANNELS.has(twin))) return { $ref: `#/properties/${twin}` };
+	const r = rangeOf(ch), d = CHANNEL_DOCS[channelFamily(ch)] ?? bad(`describe: channel ${ch} has no entry in CHANNEL_DOCS`);
+	if (VEC_CHANNELS.has(ch)) return { $ref: "#/$defs/vec3", description: d };
+	if (MAP_CHANNELS.has(ch)) return { type: "object", propertyNames: { enum: FINGER_PRESETS }, additionalProperties: { type: "number", minimum: 0, maximum: 1 } };
+	return r ? { type: "number", minimum: r[1], maximum: r[2], description: r[3] } : { type: "number", description: d };
+}
+
+const SCHEMAS = {
+	spec: () => objectOf(SPEC_FIELDS, SPEC_TYPES, "spec", ["schema", "frames"]),
+	anchors: () => ({ type: "object", description: "name -> anchor", additionalProperties: { oneOf: Object.entries(ANCHOR_FIELDS).map(([kind, fields]) =>
+		objectOf(["kind", ...fields], { ...ANCHOR_TYPES, kind: { const: kind } }, `anchors (${kind})`, ["kind", ...(ANCHOR_REQUIRED[kind] ?? [])])) } }),
+	props: () => ({ type: "object", properties: {
+		props: { type: "object", description: "name -> prop", additionalProperties: objectOf(PROP_FIELDS, PROP_TYPES, "props", ["hand", "origin"]) },
+		fits: listOf(objectOf(FIT_FIELDS, FIT_TYPES, "fits", ["side", "anchor", "effector"])) } }),
+	objects: () => ({ type: "object", description: "object or group id -> hinge, carry, switch, follow or free", additionalProperties: { oneOf: [
+		{ title: "hinge", ...objectOf(OBJECT_FIELDS.hinge, OBJECT_TYPES, "objects (hinge)", ["pivot", "channel"]) },
+		{ title: "carry", ...objectOf(OBJECT_FIELDS.carry, OBJECT_TYPES, "objects (carry)", ["prop"]) },
+		{ title: "switch", ...objectOf(OBJECT_FIELDS.switch, OBJECT_TYPES, "objects (switch)") },
+		{ title: "follow", ...objectOf(OBJECT_FIELDS.follow, OBJECT_TYPES, "objects (follow)", ["follow"]) },
+		{ title: "free", ...objectOf(OBJECT_FIELDS.free, { ...OBJECT_TYPES, ...FREE_TYPES }, "objects (free)") }] } }),
+	checks: () => ({ type: "object", properties: Object.fromEntries(CHECK_FIELDS.map(f => [f, CHECK_ENTRY_FIELDS[f]
+		? listOf(objectOf(CHECK_ENTRY_FIELDS[f], CHECK_ENTRY_TYPES, `checks.${f}`, CHECK_REQUIRED[f]))
+		: typeOf(CHECKS_TYPES, f, "checks")])), additionalProperties: false }),
+	goals: () => listOf({ ...objectOf(GOAL_FIELDS, GOAL_TYPES, "goals", ["name", "at"]), ...oneOfRequired(["near", "above", "moved", "still", "speed"]) }),
+	probes: () => listOf({ ...objectOf(PROBE_FIELDS, PROBE_TYPES, "probes", ["name"]), ...oneOfRequired(["distance", "position"]) }, { maxItems: 16 }),
+	channels: () => ({ type: "object", description: "key.set: channel -> value",
+		properties: Object.fromEntries([...VEC_CHANNELS, ...NUM_CHANNELS, ...MAP_CHANNELS].filter(ch => !SKILL_CHANNELS.has(ch)).map(ch => [ch, channelSchema(ch)])),
+		patternProperties: { "^w_.+_[lr]$": { type: "number", minimum: 0, maximum: 1, description: rangeOf("w_a_l")[3] }, "_vis$": { type: "number", description: "shown > 0.5" } },
+		additionalProperties: { type: "number", description: "spec.channels, an object's or a check's when" } }),
+	refs: () => ({ type: "string", oneOf: REF_KINDS.map(k => ({ pattern: `^${k}:`, description: typeOf(REF_DOCS, k, "refs") })) }),
+	fix: () => ({ oneOf: [{ const: false }, objectOf(FIX_KEYS, FIX_TYPES, "fix")] }),
+};
+
+function skillArgs(name) {
+	const { args, required = [] } = SKILL_INFO[name] ?? bad(`describe: skill ${name} has no entry in skills/info.js`);
+	return Object.entries(args).map(([a, s]) => `${a}${required.includes(a) ? "*" : ""}${s.default !== undefined ? `=${JSON.stringify(s.default)}` : ""}`).join(", ");
+}
+
+function describeSkill(name) {
+	const info = SKILL_INFO[name] ?? bad(`describe: skill ${name} has no entry in skills/info.js`);
+	return { topic: "skills", name, schema: rooted({ type: "object", properties: info.args, ...(info.required ? { required: info.required } : {}), additionalProperties: false }),
+		example: { skill: name, ...info.example }, notes: [`needs: ${info.needs}`, `frames from f0: ${info.frames}`, `adds: ${info.adds.join("; ")}`] };
+}
+
+/** The parts round-2 sessions read again right after essentials (topics objects and channels, skill
+ * reachGrip): in essentials their fields also say what they mean, so a first spec needs no second read. */
+const MEANT = { topics: ["objects", "channels"], skills: ["reachGrip"] };
+/** Topics no round-2 session needed for a first spec: essentials names their parts, the full topic has the fields. */
+const SHALLOW = ["checks"];
+/** Skills essentials leaves to topic skills: a flip or cartwheel is no first spec's need, and essentials has no room. */
+const FIRST_SPEC_SKIP = ["flip"];
+
+/** A shared shape whose fields are mostly a skill's args (walk, walkTo): its own fields and `...<skill> args`. */
+function shapeLine(d) {
+	for (const [skill, { args }] of Object.entries(SKILL_INFO)) {
+		const own = Object.entries(d.properties ?? {}).filter(([k, v]) => JSON.stringify(args[k]) !== JSON.stringify(v)), shared = Object.keys(d.properties ?? {}).length - own.length;
+		if (shared <= own.length) continue;
+		const not = Object.keys(args).filter(a => !d.properties[a]);
+		return briefType({ ...d, properties: Object.fromEntries(own) }).replace(/\}$/, `, ...${skill} args${not.length ? ` but ${not.join(", ")}` : ""}}`);
+	}
+	return briefType(d) + (d.description ? ` (${d.description})` : "");
+}
+
+/** The spec schema with each field a topic spells ("topic anchors") named by that topic's type line: `anchors?: anchors`, `fits?: props.fits`. */
+function pointed(spec) {
+	const at = (f, t) => (t === f && !SCHEMAS[t]().properties?.[f] ? t : `${t}.${f}`);
+	return { ...spec, properties: Object.fromEntries(Object.entries(spec.properties).map(([f, s]) => {
+		const t = s.description?.match(/\btopic (\w+)\)?$/)?.[1];
+		return [f, t && SCHEMAS[t] && t !== "skills" ? { $ref: `#/types/${at(f, t)}` } : s];
+	})) };
+}
+
+/** Every topic's schema and every skill's args as one type line each, and the shared shapes they name. */
+function essentials() {
+	const types = {}, shared = {};
+	for (const topic of DESCRIBE_TOPICS.filter(t => SCHEMAS[t])) {
+		const { $defs = {}, ...schema } = rooted(topic === "spec" ? pointed(SCHEMAS.spec()) : SCHEMAS[topic]());
+		types[topic] = briefType(schema, { means: MEANT.topics.includes(topic), depth: SHALLOW.includes(topic) ? 1 : undefined });
+		Object.assign(shared, $defs);
+	}
+	// use.skill without the enum: the skills list below names them
+	if (shared.use) shared.use = objectOf(USE_FIELDS, USE_TYPES, "use", ["skill", "f0"]);
+	// a skill no first spec needs (FIRST_SPEC_SKIP) is in topic skills only
+	const skills = SKILL_NAMES.filter(n => !FIRST_SPEC_SKIP.includes(n)).map(n => {
+		const { args, required = [], needs, frames, adds } = SKILL_INFO[n] ?? bad(`describe: skill ${n} has no entry in skills/info.js`);
+		return { name: n, args: briefType({ type: "object", properties: args, required }, { means: MEANT.skills.includes(n) }), needs, frames, adds };
+	});
+	// the shared shapes a line names as a type (": vec3", "| frameSpan", "[ref, ref]"); a shallow topic names fewer than its schema has
+	const named = name => new RegExp(`(?:[:|] |[[(])${name}\\b`).test(JSON.stringify([types, skills.map(k => k.args)]));
+	for (let more = true; more;) {
+		more = false;
+		for (const [name, d] of Object.entries(shared)) if (!types[name] && named(name)) { types[name] = shapeLine(d); more = true; }
+	}
+	return { topic: "essentials", types, skills, notes: NOTES.essentials };
+}
+
+/** describe(topic, name?) -> the answer for one topic (see the table above). */
+export function describe(topic, name) {
+	if (!DESCRIBE_TOPICS.includes(topic)) bad(`topic "${topic}" is not a describe topic${didYouMean(String(topic), DESCRIBE_TOPICS)} (topics: ${DESCRIBE_TOPICS.join(", ")})`);
+	if (topic === "essentials") return essentials();
+	if (topic === "examples") return { topic, examples: SPEC_EXAMPLES, notes: EXAMPLE_NOTES };
+	if (topic !== "skills") return { topic, schema: rooted(SCHEMAS[topic]()), example: EXAMPLES[topic], notes: NOTES[topic] };
+	if (name === undefined) return { topic, skills: SKILL_NAMES.map(n => ({ name: n, args: skillArgs(n), needs: SKILL_INFO[n].needs, frames: SKILL_INFO[n].frames, adds: SKILL_INFO[n].adds })) };
+	if (!SKILL_NAMES.includes(name)) bad(`skill "${name}" is not a skill${didYouMean(String(name), SKILL_NAMES)} (skills: ${SKILL_NAMES.join(", ")})`);
+	return describeSkill(name);
+}
+
+const bytes = value => new TextEncoder().encode(JSON.stringify(value)).length;
+
+/** describeMany([{ topic, name? }]) -> { topics, more? }: the answers in order while they fit DESCRIBE_BUDGET (the first
+ * always does), each ask once; the rest are named in `more` for another call. */
+export function describeMany(asks) {
+	const seen = new Set(), wanted = asks.filter(({ topic, name }) => !seen.has(`${topic} ${name ?? ""}`) && seen.add(`${topic} ${name ?? ""}`));
+	const topics = [];
+	for (const [i, { topic, name }] of wanted.entries()) {
+		const answer = describe(topic, name), rest = wanted.slice(i + 1);
+		if (topics.length && bytes({ topics: [...topics, answer], more: rest }) > DESCRIBE_BUDGET) return { topics, more: wanted.slice(i) };
+		topics.push(answer);
+	}
+	return { topics };
+}

package/src/motion3/docs.js

@@ -0,0 +1,27 @@
+// The agent-facing words of the motion actions (src/commands/motion3.js): each action's description.
+// Lane P owns the wording; the code only reads these constants. The procedure lives in the Studio
+// system prompt and the field tables in motion.describe, so these strings say only what each action takes and answers.
+export const MOTION_ACTION_HELP = {
+	compile: "Bake a spec on the character's rig and run QA. install: true installs (default), false or \"never\" changes nothing, \"ifClean\" only if the final qa.ok; output.installed tells. "
+		+ "Send spec, or base (an answered specId) + optional patch (JSON Patch); base alone or patch: [] re-measures (new probes). "
+		+ "spec = { schema: \"cozyclay.motion-spec.v1\", fps: 24, frames (number or \"auto\"), ... } (parts: motion.describe); any number may be { range: [lo, hi] } (searched). "
+		+ "probes (at most 16, request level; spec.probes: measured, not stored): { name, distance: [ref, ref] | position: ref, frames, every? }. "
+		+ "Refs need a prefix (joint: prop: anchor: landmark: object: person:; goals[].moved: a bare id too) and take loose bone names (any case); spec.checks need exact ones. "
+		+ "repair: { rounds } (1-8, default 4) applies group patches while severity drops. "
+		+ "qa judges only what is broken; speed, acceleration, balance, knee bend are observations unless checks.limits names them. "
+		+ "Answers frames, installed, specId, qa { ok, total, goals, groups (GOAL first, then severity; cause, hint, patch?) }, observations, delta (with base), repair, probes, timeline, fixed, search, skills. output.more: motion.report pages the rest.",
+	qa: "Measure the character's installed take again against the scene as it is now (objects may have moved). Optional checks replace the spec's checks and its skills' checks. "
+		+ "Answers specId and qa as motion.compile does (goals, ranked groups with cause, hint and patch); output.more pages with motion.report. Changes nothing.",
+	sample: "World positions (metres) of named bones of the installed take at up to 64 frames. Bone names may be loose (any case, a mixamorig: prefix, aliases such as hips or hand_l); an unknown one answers a did-you-mean. "
+		+ "Before a take is installed, use motion.compile probes instead. Changes nothing.",
+	describe: "The motion spec reference. topic essentials: all a first spec needs, { types (every field of every topic, one line each; objects, channels and reachGrip "
+		+ "say what fields mean), skills (typed args, needs, frames, adds), notes }. topic spec, skills, anchors, props, objects, checks, goals, probes, channels, refs or fix: "
+		+ "{ topic, schema, example, notes }; skills lists the skills, with name one skill's args and a use example. topic examples answers whole specs that compile. "
+		+ "topics: [topic | { topic, name? }] answers several in one call: { topics, more (the asks that did not fit) }. Changes nothing.",
+	keyObject: "Key an object the installed take moves (objectId) at frame, then compile and install it whatever QA says (a user edit, one undo). "
+		+ "A carried object takes pos [x, y, z] and rot [x, y, z, w], or aim [x, y, z] (its +Y) and roll?: its base's world pose (a group: its root), grab..release only (objects.<id>.keys); the hand follows. "
+		+ "A hinge takes angle (degrees) or rot (its turn about the axis). remove: true deletes the key at frame. Refused where the take neither holds nor hinges it (drag it then). "
+		+ "Answers keyed and the motion.compile output; REACH \"<id>: n cm off its keys\": what the hand missed.",
+	report: "Page through the parts of a motion.compile or motion.qa answer that did not fit (output.more): part is groups (the default), timeline or probes, from the item index to start at; "
+		+ "answers { specId, part, from, items, next } (next = the index to ask for next, null at the end). Changes nothing.",
+};

package/src/motion3/edit-carry.js

@@ -0,0 +1,21 @@
+// A take's timing edit (take-edit.js: cuts, segment speeds, removed segments, a trim) carried onto the
+// next take compiled for the same character, so a recompile does not throw away timing the user (or
+// the agent) set on the take it replaces and nobody has to cut and slow it again by hand.
+// The segments keep their source frames (a recompile mostly keeps its beats where they were): the
+// same frame count keeps the edit as it is; on another count a segment that ran to the old last frame
+// runs to the new one, segments past the new end drop out and one across it is clipped.
+import { isIdentityEdit, normalizeTakeEdit } from "./take-edit.js";
+
+const RESET = "motion.resetTiming plays the take as compiled";
+
+/** carryEdit(edit, oldFrames, newFrames) -> null (nothing to carry) | { edit (null: dropped), note }. */
+export function carryEdit(edit, oldFrames, newFrames) {
+	const previous = normalizeTakeEdit(edit, oldFrames);
+	if (!previous || isIdentityEdit(previous, oldFrames)) return null;
+	if (oldFrames === newFrames) return { edit: previous, note: `kept the timing edit of the take it replaced (${previous.length} segments); ${RESET}` };
+	const last = newFrames - 1, final = previous.length - 1;
+	const next = previous.map((segment, i) => ({ ...segment, sourceEnd: i === final && segment.sourceEnd === oldFrames - 1 ? last : Math.min(segment.sourceEnd, last) }))
+		.filter(segment => segment.sourceStart <= segment.sourceEnd);
+	if (!next.length || isIdentityEdit(next, newFrames)) return { edit: null, note: `dropped the timing edit of the take it replaced: nothing of it is left on the new ${newFrames} frames (it had ${oldFrames})` };
+	return { edit: next, note: `kept the timing edit of the take it replaced (${next.length} segments) on the new ${newFrames} frames (it had ${oldFrames}); ${RESET}` };
+}

package/src/motion3/fix/ease.js

@@ -0,0 +1,16 @@
+// Small helpers the auto-fixes share.
+
+/** Eased dilation of a per-frame amount: every frame gets at least amount * ease over +-w frames. */
+export function easeAround(values, w) {
+	const n = values.length, out = new Float64Array(n);
+	for (let i = 0; i < n; i++) {
+		if (!(values[i] > 0)) continue;
+		for (let j = Math.max(0, i - w - 1); j <= Math.min(n - 1, i + w + 1); j++) {
+			const t = 1 - Math.abs(i - j) / (w + 1), e = t * t * (3 - 2 * t);
+			out[j] = Math.max(out[j], values[i] * e);
+		}
+	}
+	return out;
+}
+
+export const round4 = x => Math.round(x * 1e4) / 1e4;

package/src/motion3/fix/ground.js

@@ -0,0 +1,37 @@
+// Soles on the floor: where a foot's lowest sole point (qa/geometry.js solePoints: heel, ball, tip,
+// on the skin's sole, where verify_result measures the floor) is under the floor, its ankle target
+// goes up until that point is on the floor. A squat on the balls of the feet (fpitch +) stands on
+// the balls instead of sinking them. The sole's shape under the ankle depends only on fyaw and
+// fpitch, so the lift is measured at the target, not where an out-of-reach leg left the ankle.
+// The lift eases in and out over EASE frames, so a foot keyed into the floor lands, not stops dead.
+import { solePoints } from "../qa/geometry.js";
+import { SIDES } from "../compiler/pose.js";
+import { easeAround, round4 } from "./ease.js";
+
+/** Depth (m) a sole point may keep under the floor; lifts past MAX_LIFT stop there for QA (GROUND). */
+const GROUND_EPS = 0.001, MAX_LIFT = 0.15, EASE = 2;
+
+export function liftSoles(out, engine) {
+	const { sk } = out.ctx, n = out.frames.length, touched = new Set();
+	let worst = 0;
+	for (const [k, S] of Object.entries(SIDES)) {
+		const ch = out.baked[`foot_${k}`], ankle = sk.index[`${S}Foot`];
+		if (!ch) continue;
+		const need = out.frames.map(({ s }, i) => {
+			const sp = solePoints(sk, s, S), low = Math.min(sp.heel[1], sp.ball[1], sp.tip[1]) - s.P[ankle][1] + ch[out.f0 + i][1];
+			return Math.min(MAX_LIFT, -low - GROUND_EPS);
+		});
+		if (!need.some(d => d > 0)) continue;
+		const lift = easeAround(need, EASE);
+		for (let i = 0; i < n; i++) {
+			if (!(lift[i] > 0)) continue;
+			const f = out.f0 + i;
+			ch[f] = [ch[f][0], ch[f][1] + lift[i], ch[f][2]];
+			worst = Math.max(worst, need[i]);
+			touched.add(f);
+		}
+	}
+	if (!touched.size) return null;
+	engine.solve([...touched]);
+	return { frames: touched.size, max: round4(worst), how: "soles lifted onto the floor" };
+}

package/src/motion3/fix/index.js

@@ -0,0 +1,52 @@
+// Deterministic auto-fixes the compiler applies after the first solve (spec.fix). Each fix edits
+// the baked channels or the per-frame IK offsets and re-solves only the frames it touched, so QA
+// still measures the final frames; every fix reports what it changed (counts, worst amount).
+//
+// spec.fix = { reach: true, slide: true, penetration: 0.02, self: true, retime: false } (false = all off)
+//   reach        wrist targets past the arm's reach go onto it through a soft knee (no snap);
+//                ankle targets past the leg's reach lower the hips just enough, eased in and out
+//   slide        a sole under the floor lifts its ankle onto it (ground.js); a planted heel or ball
+//                that drifts less than 1 cm stays put, and a foot turning on its planted ball (heel
+//                up) or heel pivots about it whatever the drift; a flat planted foot (heel and ball
+//                down) keeps its heading until one of them lifts (turn.js)
+//   penetration  hands pushed out of scene boxes along the box normal when the depth past the
+//                allowance is at most this many metres (true = 0.02), eased in and out
+//   self         arms out of the rest of the body on its fitted skin: the elbow turns about the
+//                shoulder-wrist line, the hand is pushed out along the skin (self.js)
+//   retime       speed spikes get more frames, borrowed from the neighbouring keys
+import { lowerHips, armReach } from "./reach.js";
+import { lockFeet } from "./slide.js";
+import { holdTurns } from "./turn.js";
+import { liftSoles } from "./ground.js";
+import { pushOut } from "./push.js";
+import { retime } from "./retime.js";
+import { selfClear } from "./self.js";
+
+const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime"];
+export { FIX_KEYS };
+
+export function fixOptions(fix) {
+	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false };
+	const f = fix ?? {};
+	const pen = f.penetration === true ? 0.02 : Math.min(0.05, Math.max(0, Number(f.penetration) || 0));
+	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true };
+}
+
+/** The slide report with the flat feet whose turn waited (turn.js): turns { frames, max deg }. */
+const withTurns = (turns, slide) => (turns ? { ...(slide ?? { frames: 0, how: "planted heel/ball held in place" }), turns, how: `${slide?.how ?? "planted heel/ball held in place"}; a flat planted foot keeps its heading until it lifts` } : slide);
+const mergeReach = (a, b) => (a && b ? { frames: Math.max(a.frames, b.frames), eased: Math.max(a.eased, b.eased), max: Math.max(a.max, b.max), how: a.how } : a ?? b);
+
+/** Runs the enabled fixes in order (retime first: it moves keys) and returns their reports. */
+export function applyFixes(out, fix, engine, { whole = true } = {}) {
+	const fixed = {}, put = (name, report) => { if (report) fixed[name] = report; };
+	if (fix.retime && whole) put("retime", retime(out, engine));
+	if (fix.slide) put("ground", liftSoles(out, engine));
+	if (fix.reach) put("reachLegs", lowerHips(out, engine));
+	if (fix.slide) put("slide", withTurns(holdTurns(out, engine), lockFeet(out, engine)));
+	// a pivot can hold a foot past the leg's reach: the hips go down for those frames too
+	if (fix.reach && fixed.slide?.pivots) put("reachLegs", mergeReach(fixed.reachLegs, lowerHips(out, engine)));
+	if (fix.penetration > 0) put("penetration", pushOut(out, engine, fix.penetration));
+	if (fix.self) put("self", selfClear(out, engine));
+	if (fix.reach) put("reachArms", armReach(out));
+	return fixed;
+}

package/src/motion3/fix/push.js

@@ -0,0 +1,71 @@
+// Shallow penetration push-out (spec.fix.penetration = max depth in metres past the allowance):
+// a hand or forearm capsule inside a scene box moves its wrist IK target out along the box
+// normal, eased over neighbouring frames. Deeper hits are staging problems and stay for QA.
+// Frames where that arm is FK (armw 0) cannot be pushed and are counted as skipped.
+import { add, scale, len } from "../compiler/math.js";
+import { QA_LIMITS, allowance } from "../qa/checks.js";
+import { CAPSULES, segPoints, sdBox, boxNormal } from "../qa/geometry.js";
+import { round4 } from "./ease.js";
+
+const EASE = 4, MARGIN = 0.002, PASSES = 3;
+const ARM_PARTS = { l: CAPSULES.filter(c => c[0] === "hand_l" || c[0] === "farm_l"), r: CAPSULES.filter(c => c[0] === "hand_r" || c[0] === "farm_r") };
+
+/** Per-frame push vectors for side k: the needed exit (normal * excess) summed over boxes. */
+function needs(out, k, maxDepth, allow, stats) {
+	const { sk } = out.ctx, I = sk.index, n = out.frames.length, v = Array.from({ length: n }, () => null);
+	for (let i = 0; i < n; i++) {
+		const { s, c } = out.frames[i], objs = out.objectsAt(i);
+		let sum = null;
+		for (const [id, box] of Object.entries(objs)) {
+			if (!box.half || box.ignore) continue;
+			let best = null;
+			for (const [part, a, b, r] of ARM_PARTS[k]) {
+				const lim = allowance(allow, part, id) ?? QA_LIMITS.allow;
+				const pts = segPoints(s.P[I[a]], s.P[I[b]]), ds = pts.map(p => sdBox(p, box)), m = Math.min(...ds);
+				const excess = r - m - lim;
+				if (excess <= 0) continue;
+				if (excess > maxDepth) { stats.deep++; continue; }
+				if (!best || excess > best[0]) best = [excess, pts[ds.indexOf(m)]];
+			}
+			if (best) sum = add(sum ?? [0, 0, 0], scale(boxNormal(best[1], box), best[0] + MARGIN));
+		}
+		if (!sum) continue;
+		if (!(c[`armw_${k}`] > 1e-4)) { stats.skipped++; continue; }
+		v[i] = sum;
+	}
+	return v;
+}
+
+export function pushOut(out, engine, maxDepth) {
+	const allow = out.ctx.spec.checks?.allow, n = out.frames.length, stats = { deep: 0, skipped: 0 };
+	const hit = new Set();
+	let max = 0;
+	for (let pass = 0; pass < PASSES; pass++) {
+		stats.deep = 0; stats.skipped = 0;
+		const touched = new Set();
+		for (const k of ["l", "r"]) {
+			const v = needs(out, k, maxDepth, allow, stats), push = out.ctx.push[k];
+			// eased dilation of the vectors: neighbours get the strongest nearby push, scaled down
+			const eased = Array.from({ length: n }, () => null);
+			for (let i = 0; i < n; i++) {
+				if (!v[i]) continue;
+				hit.add(`${k}${i}`);
+				for (let j = Math.max(0, i - EASE - 1); j <= Math.min(n - 1, i + EASE + 1); j++) {
+					const t = 1 - Math.abs(i - j) / (EASE + 1), w = scale(v[i], t * t * (3 - 2 * t));
+					if (!eased[j] || len(w) > len(eased[j])) eased[j] = w;
+				}
+			}
+			for (let i = 0; i < n; i++) {
+				if (!eased[i]) continue;
+				const f = out.f0 + i, next = add(push.get(f) ?? [0, 0, 0], eased[i]);
+				push.set(f, next);
+				max = Math.max(max, len(next));
+				touched.add(f);
+			}
+		}
+		if (!touched.size) break;
+		engine.solve([...touched]);
+	}
+	if (!hit.size && !stats.skipped) return null;
+	return { frames: hit.size, max: round4(max), skipped: stats.skipped, tooDeep: stats.deep, how: "hand pushed out along the box normal" };
+}

package/src/motion3/fix/reach.js

@@ -0,0 +1,46 @@
+// Reach fixes: the legs lower the hips (eased over neighbouring frames) until every ankle target
+// is reachable; the arms are clamped inline by pose.js (hooks.softReach), counted here. Both only
+// take misses up to 5 cm: anything farther is a staging error that QA must keep reporting.
+import { sub, len, dot } from "../compiler/math.js";
+import { SIDES, REACH_FIX_MAX } from "../compiler/pose.js";
+import { easeAround, round4 } from "./ease.js";
+
+const EASE = 6;
+
+export function lowerHips(out, engine) {
+	const { sk } = out.ctx, I = sk.index, P = sk.restWorldPos, root = out.baked.root;
+	if (!root) return null;
+	const n = out.frames.length, need = new Float64Array(n);
+	for (let i = 0; i < n; i++) {
+		const { s, diag, c } = out.frames[i];
+		for (const [k, side] of Object.entries(SIDES)) {
+			if (!(diag[`leg_miss_${k}`] > 5e-4) || !Array.isArray(c[`foot_${k}`])) continue;
+			const R = 0.999 * (len(sub(P[I[`${side}Leg`]], P[I[`${side}UpLeg`]])) + len(sub(P[I[`${side}Foot`]], P[I[`${side}Leg`]])));
+			const v = sub(c[`foot_${k}`], s.P[I[`${side}UpLeg`]]), disc = v[1] * v[1] - dot(v, v) + R * R;
+			// hips go down by d so that |v + d*up| = R (the smaller root); sideways misses only get closer
+			const d = disc >= 0 ? -v[1] - Math.sqrt(disc) : -v[1];
+			if (d > 0 && d <= REACH_FIX_MAX) need[i] = Math.max(need[i], d + 5e-4);
+		}
+	}
+	const frames = need.filter(d => d > 0).length;
+	if (!frames) return null;
+	const drop = easeAround(need, EASE), touched = [];
+	for (let i = 0; i < n; i++) {
+		if (!(drop[i] > 0)) continue;
+		const f = out.f0 + i, r = root[f];
+		root[f] = [r[0], r[1] - drop[i], r[2]];
+		touched.push(f);
+	}
+	engine.solve(touched);
+	return { frames, eased: touched.length, max: round4(Math.max(...need)), how: "hips lowered" };
+}
+
+/** Frames whose wrist target was past reach and got the soft clamp. */
+export function armReach(out) {
+	let frames = 0, max = 0;
+	for (const fr of out.frames) for (const k of ["l", "r"]) {
+		const over = fr.diag[`reach_over_${k}`] ?? 0;
+		if (over > 1e-3) { frames++; max = Math.max(max, over); }
+	}
+	return frames ? { frames, max: round4(max), how: "wrist target clamped to reach" } : null;
+}

package/src/motion3/fix/retime.js

@@ -0,0 +1,79 @@
+// Retime (spec.fix.retime): where QA reports the motion too fast, the key intervals around it
+// get longer, borrowing the frames from the neighbouring key intervals of the same window
+// (slower or held stretches get shorter). Too fast means a one-frame pop, or a speed or
+// acceleration limit the spec named in checks.limits (qa/style.js speedExcess); a fast but smooth
+// motion is style and keeps its speed. Interpolation between keys scales with their spacing, so
+// each interval is stretched by its own peak excess. The frame count and every key outside the
+// windows stay where they are; the time map is kept on out.timeMap so frame-range checks follow.
+import { QA_LIMITS } from "../qa/checks.js";
+import { speedExcess } from "../qa/style.js";
+
+const HEADROOM = 1.1, MIN_RATE = 0.35, PASSES = 3;
+
+/** e[i] = how many times too fast frame i is (speed ratio, or sqrt of the acceleration ratio). */
+const excess = out => {
+	const own = out.ctx.spec?.checks?.limits;
+	return speedExcess(out.ctx.sk, out, own, { ...QA_LIMITS, ...own });
+};
+
+/** Windows [a, b] (key frames) around each run of too-fast frames, merged where they overlap. */
+function windows(e, keyFrames, n) {
+	const out = [];
+	for (let i = 1; i < n; i++) {
+		if (e[i] <= 1) continue;
+		let j = i;
+		while (j + 1 < n && e[j + 1] > 1) j++;
+		const w = Math.max(6, 2 * (j - i + 1));
+		const a = Math.max(0, ...keyFrames.filter(f => f <= i - 1 - w)), b = Math.min(n - 1, ...keyFrames.filter(f => f >= j + w));
+		if (out.length && a <= out[out.length - 1][1]) out[out.length - 1][1] = Math.max(out[out.length - 1][1], b);
+		else out.push([a, b]);
+		i = j;
+	}
+	return out;
+}
+
+/** New times for the breakpoints of window [a, b]: each interval scaled by max(peak excess, alpha). */
+function spread(e, cuts) {
+	const total = cuts[cuts.length - 1] - cuts[0];
+	const segs = cuts.slice(1).map((k, i) => { let m = 0; for (let f = Math.floor(cuts[i]) + 1; f <= Math.ceil(k); f++) m = Math.max(m, e[f] ?? 0); return { len: k - cuts[i], need: HEADROOM * m }; });
+	const sum = alpha => segs.reduce((acc, s) => acc + s.len * Math.max(s.need, alpha), 0);
+	let lo = MIN_RATE, hi = 1;
+	for (let it = 0; it < 40; it++) { const mid = (lo + hi) / 2; if (sum(mid) > total) hi = mid; else lo = mid; }
+	const dur = segs.map(s => s.len * Math.max(s.need, lo)), scale = total / dur.reduce((acc, d) => acc + d, 0);
+	const T = [cuts[0]];
+	dur.forEach((d, i) => T.push(T[i] + d * scale));
+	T[T.length - 1] = cuts[cuts.length - 1];
+	return { T, stretch: Math.max(...dur.map((d, i) => (d * scale) / segs[i].len)) };
+}
+
+export function retime(out, engine) {
+	const n = out.frames.length, maps = [];
+	let segments = 0, stretch = 1;
+	for (let pass = 0; pass < PASSES; pass++) {
+		const e = excess(out), keyFrames = [...new Set(out.keys.map(k => k.f))].sort((p, q) => p - q);
+		const wins = windows(e, keyFrames, n);
+		if (!wins.length) break;
+		const pieces = wins.map(([a, b]) => {
+			const cuts = [...new Set([a, ...keyFrames.filter(f => f > a && f < b), b])].sort((p, q) => p - q), r = spread(e, cuts);
+			stretch = Math.max(stretch, r.stretch);
+			return { cuts, T: r.T };
+		});
+		segments += wins.length;
+		const map = f => {
+			for (const { cuts, T } of pieces) {
+				if (f < cuts[0] || f > cuts[cuts.length - 1]) continue;
+				let i = 0;
+				while (i < cuts.length - 2 && f > cuts[i + 1]) i++;
+				return T[i] + (T[i + 1] - T[i]) * (f - cuts[i]) / (cuts[i + 1] - cuts[i]);
+			}
+			return f;
+		};
+		maps.push(map);
+		engine.rebake(out.keys.map(k => ({ ...k, f: map(k.f) })));
+		engine.solve(engine.all());
+	}
+	if (!maps.length) return null;
+	out.timeMap = f => maps.reduce((x, m) => m(x), f);
+	const left = excess(out).filter(x => x > 1).length;
+	return { windows: segments, maxStretch: Math.round(stretch * 100) / 100, stillFast: left, how: "key intervals around speed spikes stretched" };
+}