cozyclay 2.1.0 → 3.0.0

package/src/motion3/compiler/validate-objects.js

@@ -0,0 +1,143 @@
+// Validation of spec.objects (C3): a hinge { pivot, axis?, channel } or a carry { prop, grab?,
+// release?, at?, along?, visible?, level?, keys? }. Both take a body or a group (Empty) id; at/along
+// pin the palm offset (a group: its root; without them a group keeps its grab-frame offset); keys
+// (C14) pose a carried object while it is in hand (rot, or aim + roll: C16). A switch { visible?,
+// level? } (C15: no prop, no hinge field) takes any record, a light or an effect too, and moves
+// nothing; so does a follow { follow, offset?, aim?, visible?, level? } (C16), which rides a point
+// of the body. A free entry { keys?, fall?, visible?, level? } (C17: no prop, no follow, no hinge field) moves a body or a
+// group on its own: world pose keys over the whole take, and gravity falls; a carry takes fall too, before its grab
+// or from its release on. Fields: schema/fields.js OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS. See validate.js.
+import { isVec3, fmt, didYouMean } from "./vocab.js";
+import { objectOk } from "./validate-common.js";
+import { OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS } from "../schema/fields.js";
+import { isSwitch, isFollow, movesRecord } from "../carried.js";
+import { isFree } from "../free-motion.js";
+import { checkRef } from "../refs.js";
+import { partsOf } from "../object-pose.js";
+
+const KEY = "{ f, pos: [x, y, z], rot: [x, y, z, w] } or { f, pos, aim: [x, y, z], roll? }", FALL = "{ at, onto?, bounce? }";
+const isQuat = q => Array.isArray(q) && q.length === 4 && q.every(Number.isFinite) && Math.abs(Math.hypot(...q) - 1) <= 0.01;
+const isDir = v => isVec3(v) && Math.hypot(...v) > 1e-9;
+
+/** A key's rotation: rot (a unit quaternion) or aim (a world direction for its +Y) with an optional roll (degrees about it), not both. */
+function keyTurnOk(err, kat, k) {
+	if (k.rot !== undefined && k.aim !== undefined) return err(`${kat} gives both rot and aim; give one: rot [x, y, z, w], or aim [x, y, z] (the world direction its +Y points) with roll`);
+	if (k.aim === undefined) {
+		if (k.roll !== undefined) err(`${kat}.roll turns the object about aim; give aim [x, y, z] with it, or leave roll out (rot fixes the roll)`);
+		if (k.lean !== undefined) err(`${kat}.lean lets the compiler lean aim; give aim [x, y, z] with it (rot is used exactly)`);
+		if (!isQuat(k.rot)) err(`${kat}.rot must be a unit quaternion [x, y, z, w], got ${fmt(k.rot)}${k.rot === undefined ? "; or give aim [x, y, z], the world direction its +Y points" : ""}`);
+		return;
+	}
+	if (!isDir(k.aim)) err(`${kat}.aim must be a non-zero world direction [x, y, z] for the object's +Y (a bat: knob to barrel), got ${fmt(k.aim)}`);
+	if (k.roll !== undefined && !Number.isFinite(k.roll)) err(`${kat}.roll must be degrees about aim (a number), got ${fmt(k.roll)}`);
+	if (k.lean !== undefined && !(Number.isFinite(k.lean) && k.lean >= 0 && k.lean <= 45)) err(`${kat}.lean must be the most degrees the compiler may lean aim (0..45), got ${fmt(k.lean)}`);
+}
+
+/** objects.<id>.keys (C14): whole frames inside grab..release (free, C17: the whole take), one per frame, a world position and a unit quaternion. */
+function validateKeys(err, unknown, at, o, frames, free = false) {
+	if (!Array.isArray(o.keys)) return err(`${at}.keys must be an array of ${KEY}`);
+	const last = Number.isInteger(frames) ? frames - 1 : Infinity, lo = free ? 0 : o.grab ?? 0, hi = free ? last : o.release ?? last, seen = new Map();
+	o.keys.forEach((k, i) => {
+		const kat = `${at}.keys[${i}]`;
+		if (!k || typeof k !== "object" || Array.isArray(k)) return err(`${kat} must be ${KEY}, got ${fmt(k)}`);
+		for (const f of Object.keys(k)) if (!OBJECT_KEY_FIELDS.includes(f)) unknown(`${kat} has unknown field "${f}"${didYouMean(f, OBJECT_KEY_FIELDS)}; a key is ${KEY}`);
+		if (!Number.isInteger(k.f)) err(`${kat}.f must be a whole frame, got ${fmt(k.f)}`);
+		else if (k.f < lo || k.f > hi) err(free ? `${kat}.f = ${k.f} is outside the take (0..${hi})` : `${kat}.f = ${k.f} is outside grab..release (${lo}..${hi}); keys pose a carried object only while it is in hand (drop its prop to move it on its own, C17)`);
+		else if (seen.has(k.f)) err(`${kat}.f = ${k.f}: keys[${seen.get(k.f)}] is at that frame already; one key per frame`);
+		else seen.set(k.f, i);
+		if (!isVec3(k.pos)) err(`${kat}.pos must be [x, y, z], the world position of the object's base (a group: its root), got ${fmt(k.pos)}`);
+		keyTurnOk(err, kat, k);
+	});
+}
+
+/** An object: ref a follow entry may use: one no follow entry moves (else it would follow itself). */
+function stillRef(spec, err, scene, at, ref) {
+	const id = /^object:(.+?)(?:\.(?:center|top|base))?$/s.exec(ref)?.[1];
+	if (id === undefined) return;
+	const movers = partsOf(scene, id).flatMap(p => [p, ...(scene.objects[p].ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])) ?? []);
+	const by = movers.find(k => isFollow(spec.objects[k]));
+	if (by) err(`${at} "${ref}": "${id}" moves with the follow entry objects.${by}; a follow entry rides a joint, landmark, prop or anchor point, or an object no follow entry moves`);
+}
+
+/** follow (C16): a point ref, offset along the record's own axes, aim "face" | "up" | [x, y, z] | a point ref. */
+function validateFollow(spec, err, ctx, at, o) {
+	if (checkRef(spec, err, ctx, `${at}.follow`, o.follow)) stillRef(spec, err, ctx.scene, `${at}.follow`, o.follow);
+	if (o.offset !== undefined && !isVec3(o.offset)) err(`${at}.offset must be [x, y, z], metres along the record's own axes after aim (+Y along aim), got ${fmt(o.offset)}`);
+	const aim = o.aim;
+	if (aim === undefined || aim === "face" || aim === "up") return;
+	if (Array.isArray(aim)) { if (!isDir(aim)) err(`${at}.aim must be a non-zero world direction [x, y, z], got ${fmt(aim)}`); return; }
+	if (typeof aim !== "string" || !/^[a-z]+:/.test(aim)) return err(`${at}.aim must be "face", "up", a world direction [x, y, z] or a point ref (toward it), where the record's +Y points; got ${fmt(aim)}`);
+	if (checkRef(spec, err, ctx, `${at}.aim`, aim)) stillRef(spec, err, ctx.scene, `${at}.aim`, aim);
+}
+
+function frameOk(err, at, v, frames) {
+	if (v === undefined) return true;
+	if (Number.isInteger(v) && v >= 0 && (!Number.isInteger(frames) || v < frames)) return true;
+	err(`${at} must be a whole frame 0..${Number.isInteger(frames) ? frames - 1 : "frames-1"}, got ${fmt(v)}`);
+	return false;
+}
+
+/** objects.<id>.fall (C17): { at, onto?, bounce? } or a list, each on its own frame; a carry falls only out of hand. */
+function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
+	const list = Array.isArray(o.fall) ? o.fall : [o.fall], seen = new Set();
+	if (!list.length) err(`${at}.fall is an empty list; give ${FALL} or a list of them`);
+	list.forEach((fl, i) => {
+		const fat = Array.isArray(o.fall) ? `${at}.fall[${i}]` : `${at}.fall`;
+		if (!fl || typeof fl !== "object" || Array.isArray(fl)) return err(`${fat} must be ${FALL} (at: the frame it starts to fall), got ${fmt(fl)}`);
+		for (const k of Object.keys(fl)) if (!FALL_FIELDS.includes(k)) unknown(`${fat} has unknown field "${k}"${didYouMean(k, FALL_FIELDS)}; a fall is ${FALL}`);
+		if (fl.at === undefined) err(`${fat}.at must be the whole frame it starts to fall`);
+		else if (frameOk(err, `${fat}.at`, fl.at, frames)) {
+			if (seen.has(fl.at)) err(`${fat}.at = ${fl.at}: another fall starts on that frame`);
+			seen.add(fl.at);
+			const g = o.grab ?? 0, r = o.release;
+			if (carry && fl.at >= g && (r === undefined || fl.at < r)) err(`${fat}.at = ${fl.at} is while it is in hand (grab ${g}..release ${r ?? "end"}); a carried object falls before its grab or from its release on`);
+		}
+		if (fl.onto !== undefined) objectOk(err, scene, `${fat}.onto`, fl.onto, { groups: true });
+		if (fl.bounce !== undefined && !(Number.isFinite(fl.bounce) && fl.bounce >= 0 && fl.bounce <= 0.6)) err(`${fat}.bounce must be 0..0.6 (the share of its landing speed it bounces back with; 0 lands dead), got ${fmt(fl.bounce)}`);
+	});
+}
+
+/** visible and level name channels (C15): visible shows the record above 0.5, level scales its light, glow and effect rate. */
+function channelsOk(err, at, o) {
+	if (o.visible !== undefined && (typeof o.visible !== "string" || !o.visible)) err(`${at}.visible must name a channel (shown above 0.5)`);
+	if (o.level !== undefined && (typeof o.level !== "string" || !o.level)) err(`${at}.level must name a channel (the record's level 0..4: 0 dark, 1 as authored; it scales its light, glow and effect rate)`);
+}
+
+export function validateObjects(spec, err, { sk, scene, frames = spec.frames, unknown = err }) {
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		const at = `objects.${id}`, kind = o?.prop !== undefined ? "carry" : isFollow(o) ? "follow" : isFree(o) ? "free" : isSwitch(o) ? "switch" : "hinge", fields = OBJECT_FIELDS[kind];
+		// a switch and a follow take any record (a light, an effect); the others a body or a group
+		if ((kind !== "switch" && kind !== "follow") || !scene?.others?.[id]) objectOk(err, scene, at, id, { groups: true });
+		for (const f of Object.keys(o ?? {})) if (!fields.includes(f) && !(kind === "hinge" && (f === "keys" || f === "fall"))) unknown(`${at} (${kind}) has unknown field "${f}"${didYouMean(f, fields)}; fields: ${fields.join(", ")}`);
+		if (kind === "follow") {
+			validateFollow(spec, err, { sk, scene }, at, o);
+			channelsOk(err, at, o);
+			continue;
+		}
+		if (kind === "switch") {
+			if (o.visible === undefined && o.level === undefined) err(`${at} needs visible or level (a channel): a switch shows, hides or dims "${id}" without moving it; a carry needs prop, a hinge pivot and channel`);
+			channelsOk(err, at, o);
+			continue;
+		}
+		if (kind === "free") {
+			if (o.keys !== undefined) validateKeys(err, unknown, at, o, frames, true);
+			if (o.fall !== undefined) validateFalls(err, unknown, at, o, { frames, scene, carry: false });
+			channelsOk(err, at, o);
+			continue;
+		}
+		if (kind === "carry") {
+			if (!spec.props?.[o.prop]) err(`${at}.prop "${o.prop}" is not in spec.props`);
+			for (const f of ["at", "along"]) if (o[f] !== undefined && !isVec3(o[f])) err(`${at}.${f} must be [d, l, n] along the palm axes, got ${fmt(o[f])}`);
+			channelsOk(err, at, o);
+			if (frameOk(err, `${at}.grab`, o.grab, frames) && frameOk(err, `${at}.release`, o.release, frames)
+				&& o.grab !== undefined && o.release !== undefined && !(o.grab < o.release)) err(`${at}: grab (${o.grab}) must come before release (${o.release})`);
+			if (o.keys !== undefined) validateKeys(err, unknown, at, o, frames);
+			if (o.fall !== undefined) validateFalls(err, unknown, at, o, { frames, scene, carry: true });
+			continue;
+		}
+		if (o?.keys !== undefined || o?.fall !== undefined) err(`${at}: a hinge turns by its channel "${o.channel}", keyed in spec.keys; keys and fall move an object with no pivot, axis or channel (C17), or a carried one (prop)`);
+		if (!isVec3(o?.pivot)) err(`${at}.pivot must be [x, y, z] (world hinge point), got ${fmt(o?.pivot)}`);
+		if (o?.axis !== undefined && (!isVec3(o.axis) || Math.hypot(...o.axis) < 1e-9)) err(`${at}.axis must be a non-zero [x, y, z], got ${fmt(o.axis)}`);
+		if (typeof o?.channel !== "string" || !o.channel) err(`${at}.channel must name the angle channel (degrees)`);
+	}
+}

package/src/motion3/compiler/validate-parts.js

@@ -0,0 +1,116 @@
+// Validation of the spec parts other than keys: anchors, props, fits, generators, checks and
+// fix; objects (validate-objects.js) and goals (validate-goals.js) run from here too. Unknown
+// fields go through opts.unknown, which ignores them on a lenient reload. See validate.js.
+import { didYouMean, suggestField, CONVENTIONS, isVec3, fmt } from "./vocab.js";
+import { FIX_KEYS } from "../fix/index.js";
+import { QA_LIMITS } from "../qa/checks.js";
+import { ANCHOR_FIELDS, PROP_FIELDS, FIT_FIELDS, WALK_FIELDS, CHECK_FIELDS, CHECK_ENTRY_FIELDS } from "../schema/fields.js";
+import { boneOk, objectOk, refOk } from "./validate-common.js";
+import { validateObjects } from "./validate-objects.js";
+import { validateGoals } from "./validate-goals.js";
+
+const SIDE = new Set(["l", "r"]);
+const isObject = v => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+
+/** Every field of obj not in fields goes to unknown, with a suggestion and the list. */
+function fieldsOk(unknown, at, obj, fields) {
+	if (!isObject(obj)) return;
+	for (const f of Object.keys(obj)) if (!fields.includes(f)) unknown(`${at} has unknown field "${f}"${suggestField(f, fields)} (fields: ${fields.join(", ")})`);
+}
+
+function validateAnchors(spec, err, { sk, scene, unknown = err }) {
+	for (const [name, a] of Object.entries(spec.anchors ?? {})) {
+		const at = `anchors.${name}`;
+		if (/_[lr]$/.test(name)) err(`${at}: an anchor name may not end in _l or _r (the weight channel w_${name}_l would read as anchor "${name.slice(0, -2)}"); the side goes on the weight channel, so name it "${name.slice(0, -2)}"`);
+		if (!a || !ANCHOR_FIELDS[a.kind]) { err(`${at}.kind must be one of ${Object.keys(ANCHOR_FIELDS).join(", ")}, got ${fmt(a?.kind)}`); continue; }
+		fieldsOk(unknown, `${at} (${a.kind})`, a, ["kind", ...ANCHOR_FIELDS[a.kind]]);
+		for (const f of ["p", "offset", "local"]) if (a[f] !== undefined && !isVec3(a[f])) err(`${at}.${f} must be [x, y, z], got ${fmt(a[f])}`);
+		if ((a.kind === "world" || a.kind === "body") && a.p === undefined) err(`${at} (${a.kind}) needs p: [x, y, z]${a.kind === "body" ? `, ${CONVENTIONS.pole}` : ""}`);
+		if (a.kind === "bone") boneOk(err, sk, at, a.bone);
+		if (a.kind === "segment") { boneOk(err, sk, `${at}.from`, a.from); boneOk(err, sk, `${at}.to`, a.to); if (a.reach !== undefined && !SIDE.has(a.reach)) err(`${at}.reach must be "l" or "r"`); }
+		if (a.kind === "object") objectOk(err, scene, at, a.object, { groups: true });
+		if (a.kind === "landmark" && a.name !== "mouth") err(`${at}: the only landmark is "mouth", got ${fmt(a.name)}`);
+		if (a.kind === "prop" && !spec.props?.[a.prop]?.points?.[a.point] && a.point !== "origin") err(`${at} needs prop point ${a.prop}.${a.point}, which spec.props does not define`);
+	}
+}
+
+function validateProps(spec, err, { sk, unknown = err }) {
+	for (const [name, p] of Object.entries(spec.props ?? {})) {
+		const at = `props.${name}`;
+		fieldsOk(unknown, at, p, PROP_FIELDS);
+		if (!SIDE.has(p?.hand)) err(`${at}.hand must be "l" or "r", got ${fmt(p?.hand)}`);
+		if (!Array.isArray(p?.origin) || !p.origin.length) err(`${at}.origin must list one or more bones`);
+		else p.origin.forEach(b => boneOk(err, sk, `${at}.origin`, b));
+		for (const [pt, v] of Object.entries(p?.points ?? {})) if (!isVec3(v)) err(`${at}.points.${pt} must be [d, l, n] along the palm axes, got ${fmt(v)}`);
+	}
+	(spec.fits ?? []).forEach((fit, i) => {
+		const at = `fits[${i}]`;
+		fieldsOk(unknown, at, fit, FIT_FIELDS);
+		if (!SIDE.has(fit?.side)) err(`${at}.side must be "l" or "r", got ${fmt(fit?.side)}`);
+		if (!spec.anchors?.[fit?.anchor]) err(`${at}.anchor "${fit?.anchor}" is not in spec.anchors${didYouMean(String(fit?.anchor), Object.keys(spec.anchors ?? {}))}`);
+		const e = fit?.effector;
+		if (e?.prop !== undefined) { if (!spec.props?.[e.prop]?.points?.[e.point]) err(`${at}.effector ${e.prop}.${e.point} is not a point of spec.props`); }
+		else if (Array.isArray(e?.joints)) e.joints.forEach(j => boneOk(err, sk, `${at}.effector`, j));
+		else err(`${at}.effector must be { prop, point } or { joints: [bone, ...] }`);
+		if (fit?.offset !== undefined && !isVec3(fit.offset)) err(`${at}.offset must be [x, y, z]`);
+		if (fit?.orient !== undefined && typeof fit.orient !== "boolean") err(`${at}.orient must be true or false (false: the hand takes no grip turn), got ${fmt(fit.orient)}`);
+	});
+}
+
+function validateGenerators(spec, err, { frames, unknown = err, past = "" }) {
+	(spec.generators ?? []).forEach((g, i) => {
+		const at = `generators[${i}]`;
+		if (g?.type !== "walk") return err(`${at}.type must be "walk", got ${fmt(g?.type)}`);
+		fieldsOk(unknown, at, g, WALK_FIELDS);
+		if (!Number.isInteger(g.f0) || g.f0 < 0 || g.f0 > frames - 1) err(`${at}.f0 must be an integer frame within 0..${frames - 1}, got ${fmt(g.f0)}${g.f0 > frames - 1 ? past : ""}`);
+		if (g.heading !== undefined && !(Array.isArray(g.heading) && g.heading.length === 2 && g.heading.every(Number.isFinite))) err(`${at}.heading must be [h0, h1] in degrees (${CONVENTIONS.yaw}), got ${fmt(g.heading)}`);
+		for (const f of WALK_FIELDS.slice(2)) if (f !== "heading" && g[f] !== undefined && !Number.isFinite(g[f])) err(`${at}.${f} must be a finite number, got ${fmt(g[f])}`);
+		if (g.steps !== undefined && !(Number.isInteger(g.steps) && g.steps >= 1)) err(`${at}.steps must be an integer >= 1, got ${fmt(g.steps)}`);
+		if (g.turnDistance !== undefined && !(g.turnDistance > 0)) err(`${at}.turnDistance must be > 0 m, got ${fmt(g.turnDistance)}`);
+	});
+}
+
+function validateChecks(spec, err, { sk, scene, frames, unknown = err, past = "" }) {
+	const c = spec.checks ?? {};
+	for (const k of Object.keys(c)) if (!CHECK_FIELDS.includes(k)) unknown(`checks.${k} is not a check${didYouMean(k, CHECK_FIELDS)} (checks: ${CHECK_FIELDS.join(", ")})`);
+	// each list entry is an object with known fields; a bad entry is named once and skipped
+	const each = (name, check = () => {}) => {
+		const v = c[name], shape = `{ ${CHECK_ENTRY_FIELDS[name].join(", ")} }`;
+		if (v === undefined) return;
+		if (!Array.isArray(v)) return err(`checks.${name} must be an array of ${shape}, got ${fmt(v)}`);
+		v.forEach((k, i) => {
+			if (!isObject(k)) return err(`checks.${name}[${i}] must be ${shape}, got ${fmt(k)}`);
+			fieldsOk(unknown, `checks.${name}[${i}]`, k, CHECK_ENTRY_FIELDS[name]);
+			check(k, i);
+		});
+	};
+	const when = (at, w) => {
+		if (w === undefined || typeof w === "string") return;
+		if (!(Array.isArray(w) && w.length === 2 && w.every(Number.isInteger) && w[0] <= w[1] && w[0] >= 0 && w[1] <= frames - 1)) err(`${at}.when must be a weight channel or [f0, f1] within 0..${frames - 1}, got ${fmt(w)}${Array.isArray(w) && w[1] > frames - 1 ? past : ""}`);
+	};
+	each("contacts", (k, i) => { refOk(spec, err, sk, `checks.contacts[${i}].point`, k.point); refOk(spec, err, sk, `checks.contacts[${i}].target`, k.target); when(`checks.contacts[${i}]`, k.when); });
+	each("orient", (k, i) => {
+		refOk(spec, err, sk, `checks.orient[${i}].from`, k.from); refOk(spec, err, sk, `checks.orient[${i}].to`, k.to); when(`checks.orient[${i}]`, k.when);
+		if (!(k.along === "face" || k.along === "up" || isVec3(k.along))) err(`checks.orient[${i}].along must be "face", "up" or [x, y, z]`);
+	});
+	each("below", (k, i) => { boneOk(err, sk, `checks.below[${i}].joint`, k.joint); boneOk(err, sk, `checks.below[${i}].ref`, k.ref); when(`checks.below[${i}]`, k.when); });
+	each("clearance", (k, i) => { objectOk(err, scene, `checks.clearance[${i}]`, k.object); when(`checks.clearance[${i}]`, k.frames); });
+	each("appear", (k, i) => { boneOk(err, sk, `checks.appear[${i}].joint`, k.joint); if (!spec.anchors?.[k.anchor]) err(`checks.appear[${i}].anchor "${k.anchor}" is not in spec.anchors`); });
+	each("supports", (k, i) => objectOk(err, scene, `checks.supports[${i}]`, k.object));
+	each("allow");
+	for (const name of Object.keys(c.limits ?? {})) if (!(name in QA_LIMITS)) unknown(`checks.limits.${name} is not a QA limit${didYouMean(name, Object.keys(QA_LIMITS))}`);
+	const fix = spec.fix;
+	if (fix !== undefined && fix !== false && (typeof fix !== "object" || fix === null)) err("spec.fix must be false or { reach, slide, penetration, self, retime }");
+	else for (const k of Object.keys(fix || {})) if (!FIX_KEYS.includes(k)) unknown(`spec.fix.${k} is not a fix${didYouMean(k, FIX_KEYS)} (fixes: ${FIX_KEYS.join(", ")})`);
+}
+
+/** opts = { sk, scene, frames, lenient, unknown: err for an unknown field (a no-op when lenient), past: the
+ * advice a frame past the end gets (validate.js) }. */
+export function validateParts(spec, err, opts) {
+	validateAnchors(spec, err, opts);
+	validateProps(spec, err, opts);
+	validateObjects(spec, err, opts);
+	validateGenerators(spec, err, opts);
+	validateChecks(spec, err, opts);
+	validateGoals(spec, err, opts);
+}

package/src/motion3/compiler/validate.js

@@ -0,0 +1,122 @@
+// Strict motion spec validation with exact messages, run before every compile through the
+// pipeline (after skills expand, with open parameters at a trial value). Every problem found is
+// listed at once, one per line, so the agent fixes them in one edit.
+import { VEC_CHANNELS, POLE_CHANNELS, NUM_CHANNELS, MAP_CHANNELS, FINGER_PRESETS, rangeOf, CONVENTIONS, didYouMean, suggestField, isVec3, fmt } from "./vocab.js";
+import { validateParts } from "./validate-parts.js";
+import { SPEC_FIELDS, KEY_FIELDS } from "../schema/fields.js";
+const MAX_ERRORS = 12;
+
+
+/** Channels other than the body's own: hinge channels, visible and level channels (C15), channels a check names, *_vis switches, spec.channels. */
+function customChannels(spec) {
+	const out = new Set(spec.channels ?? []);
+	for (const o of Object.values(spec.objects ?? {})) for (const ch of [o?.channel, o?.visible, o?.level]) if (typeof ch === "string" && ch) out.add(ch);
+	const c = spec.checks ?? {};
+	const list = v => (Array.isArray(v) ? v.filter(k => k && typeof k === "object") : []);
+	for (const k of [c.contacts, c.orient, c.below, c.clearance].flatMap(list)) if (typeof k.when === "string") out.add(k.when);
+	for (const k of list(c.appear)) if (typeof k.channel === "string") out.add(k.channel);
+	return out;
+}
+
+function checkValue(err, at, ch, v) {
+	if (VEC_CHANNELS.has(ch)) {
+		if (!isVec3(v)) return err(`${at} ${ch} must be [x, y, z] (3 finite numbers), got ${fmt(v)}`);
+		if (POLE_CHANNELS.has(ch)) {
+			const l = Math.hypot(...v);
+			if (l < 1e-6) return err(`${at} ${ch} = ${fmt(v)} has no direction; a pole is ${CONVENTIONS.pole}`);
+			if (ch.startsWith("knee") && v[2] < -0.7 * l) err(`${at} ${ch} = ${fmt(v)} points backward; knees bend toward +z. A pole is ${CONVENTIONS.pole}`);
+		}
+		if (ch.startsWith("foot") && v[1] < 0.04) err(`${at} ${ch} y = ${v[1]} puts the ankle into the floor; foot_* is ${CONVENTIONS.foot}`);
+		return;
+	}
+	if (MAP_CHANNELS.has(ch)) {
+		if (!v || typeof v !== "object" || Array.isArray(v)) return err(`${at} ${ch} must be { preset: weight }, presets ${FINGER_PRESETS.join(", ")}; got ${fmt(v)}`);
+		for (const [p, w] of Object.entries(v)) {
+			if (!FINGER_PRESETS.includes(p)) err(`${at} ${ch} preset "${p}" is unknown${didYouMean(p, FINGER_PRESETS)} (presets: ${FINGER_PRESETS.join(", ")})`);
+			else if (!(Number.isFinite(w) && w >= 0 && w <= 1)) err(`${at} ${ch}.${p} must be a weight within 0..1, got ${fmt(w)}`);
+		}
+		return;
+	}
+	if (!Number.isFinite(v)) {
+		const conv = ch === "yaw" ? ` (degrees; ${CONVENTIONS.yaw})` : ch.startsWith("fyaw") ? ` (${CONVENTIONS.fyaw})` : "";
+		return err(`${at} ${ch} must be a finite number${conv}, got ${fmt(v)}`);
+	}
+	const r = rangeOf(ch);
+	if (r && (v < r[1] || v > r[2])) err(`${at} ${ch} = ${v} is outside ${r[1]}..${r[2]} (${r[3]})`);
+}
+
+const list = v => (Array.isArray(v) ? v : []);
+const lastOf = r => (Array.isArray(r) ? r[1] : r);
+
+/**
+ * The advice an "outside 0..frames-1" message ends with: the length every frame the spec names
+ * needs (keys, walk starts, check windows, goals), and frames: "auto" when that covers it ("auto"
+ * counts keys and walks, not check windows or goals; skills/frames-auto.js).
+ */
+function pastEndAdvice(spec, frames) {
+	const counted = [...list(spec.keys).map(k => k?.f), ...list(spec.generators).map(g => g?.f0)].filter(Number.isInteger);
+	const c = spec.checks ?? {};
+	const windows = [...["contacts", "orient", "below"].flatMap(n => list(c[n]).map(k => lastOf(k?.when))), ...list(c.clearance).map(k => lastOf(k?.frames)),
+		...list(spec.goals).map(g => lastOf(g?.at))].filter(Number.isInteger);
+	const need = Math.max(frames - 1, ...counted, ...windows) + 1;
+	return `; set frames >= ${need}${Math.max(0, ...counted) + 1 >= need ? " or frames: \"auto\"" : ""}`;
+}
+
+function validateKeys(spec, err, frames, unknown, past = "") {
+	if (spec.keys !== undefined && !Array.isArray(spec.keys)) return err("spec.keys must be an array of { f, set, step? }");
+	const anchors = Object.keys(spec.anchors ?? {}), custom = customChannels(spec);
+	const known = [...VEC_CHANNELS, ...NUM_CHANNELS, ...MAP_CHANNELS, ...custom, ...anchors.flatMap(a => [`w_${a}_l`, `w_${a}_r`])];
+	(spec.keys ?? []).forEach((key, i) => {
+		const name = key?.src ? (key.src.startsWith("keys[") ? key.src : `${key.src} key`) : `keys[${i}]`;
+		if (!key || typeof key !== "object") return err(`${name} must be { f, set, step? }`);
+		for (const field of Object.keys(key)) if (!KEY_FIELDS.includes(field)) unknown(`${name} has unknown field "${field}"${suggestField(field, KEY_FIELDS)}; a key is { f, set, step? }`);
+		if (!Number.isInteger(key.f)) return err(`${name}.f must be an integer frame, got ${fmt(key.f)}`);
+		if (key.f < 0 || key.f > frames - 1) err(`${name}.f = ${key.f} is outside 0..${frames - 1} (spec.frames ${frames})${key.f > 0 ? past : ""}`);
+		const at = `${name} (f${key.f})`;
+		if (!key.set || typeof key.set !== "object" || Array.isArray(key.set)) return err(`${at} needs set: { channel: value }`);
+		for (const [ch, v] of Object.entries(key.set)) {
+			const w = /^w_(.+)_([lr])$/.exec(ch);
+			if (w && !anchors.includes(w[1])) err(`${at} sets ${ch}, but there is no anchor "${w[1]}"${didYouMean(ch, known)}`);
+			else if (w) checkValue(err, at, ch, v);
+			else if (VEC_CHANNELS.has(ch) || NUM_CHANNELS.has(ch) || MAP_CHANNELS.has(ch)) checkValue(err, at, ch, v);
+			else if (custom.has(ch) || ch.endsWith("_vis")) { if (!Number.isFinite(v)) err(`${at} ${ch} must be a finite number, got ${fmt(v)}`); }
+			else err(`${at} sets unknown channel "${ch}"${didYouMean(ch, known)}`);
+		}
+		for (const ch of key.step ?? []) if (!(ch in key.set)) err(`${at} step names "${ch}", which this key does not set`);
+		if (key.step !== undefined && !Array.isArray(key.step)) err(`${at} step must be an array of channel names`);
+	});
+}
+
+/**
+ * Throws MOTION_SPEC_INVALID listing every problem; scene objects are checked when given.
+ * lenient (a saved take compiled again, take-source.js) ignores unknown fields.
+ */
+/** spec.flow: false, or { smooth?: boolean, lag?: false | 0..6 frames | { spine?, head?, arms? } } (channels.js). */
+function validateFlow(flow, err, unknown) {
+	if (flow === undefined || flow === false) return;
+	if (!flow || typeof flow !== "object" || Array.isArray(flow)) return err(`spec.flow must be false or { smooth?, lag? }, got ${fmt(flow)}`);
+	for (const k of Object.keys(flow)) if (k !== "smooth" && k !== "lag") unknown(`spec.flow has unknown field "${k}" (fields: smooth, lag)`);
+	if (flow.smooth !== undefined && typeof flow.smooth !== "boolean") err(`spec.flow.smooth must be true or false, got ${fmt(flow.smooth)}`);
+	const frames = v => Number.isFinite(v) && v >= 0 && v <= 6, lag = flow.lag, LAG = "false, 0..6 frames or { spine?, head?, arms? }";
+	if (lag === undefined || lag === false || frames(lag)) return;
+	if (!lag || typeof lag !== "object" || Array.isArray(lag)) return err(`spec.flow.lag must be ${LAG}, got ${fmt(lag)}`);
+	for (const [k, v] of Object.entries(lag)) {
+		if (!["spine", "head", "arms"].includes(k)) unknown(`spec.flow.lag has unknown field "${k}" (fields: spine, head, arms)`);
+		else if (!frames(v)) err(`spec.flow.lag.${k} must be 0..6 frames, got ${fmt(v)}`);
+	}
+}
+
+export function validateSpec(spec, { sk, scene, lenient = false } = {}) {
+	const errors = [], err = m => { if (errors.length < MAX_ERRORS) errors.push(m); }, unknown = lenient ? () => {} : err;
+	if (!spec || typeof spec !== "object") throw new Error("MOTION_SPEC_INVALID: spec must be an object");
+	if (spec.schema !== "cozyclay.motion-spec.v1") err(`spec.schema must be "cozyclay.motion-spec.v1", got ${fmt(spec.schema)}`);
+	for (const k of Object.keys(spec)) if (!SPEC_FIELDS.includes(k)) unknown(`spec.${k} is not a spec field${didYouMean(k, SPEC_FIELDS)} (fields: ${SPEC_FIELDS.join(", ")})`);
+	if (spec.fps !== undefined && spec.fps !== 24) err(`spec.fps must be 24, the timeline rate, got ${fmt(spec.fps)}`);
+	validateFlow(spec.flow, err, unknown);
+	const frames = spec.frames;
+	if (!Number.isInteger(frames) || frames < 1 || frames > 20000) err(`spec.frames must be an integer 1..20000 or "auto", got ${fmt(frames)}`);
+	const past = Number.isInteger(frames) ? pastEndAdvice(spec, frames) : "";
+	validateKeys(spec, err, Number.isInteger(frames) ? frames : 20000, unknown, past);
+	validateParts(spec, err, { sk, scene, frames: Number.isInteger(frames) ? frames : 20000, lenient, unknown, past });
+	if (errors.length) throw new Error(`MOTION_SPEC_INVALID: ${errors.join("\n")}${errors.length >= MAX_ERRORS ? "\n(more problems not listed)" : ""}`);
+}

package/src/motion3/compiler/vocab.js

@@ -0,0 +1,73 @@
+// The motion spec's channel vocabulary and sign conventions, shared by the validator (exact
+// error messages) and QA hints. Degrees for angles, metres for points.
+
+const sided = names => names.flatMap(n => [`${n}_l`, `${n}_r`]);
+
+export const VEC_CHANNELS = new Set(["root", ...sided(["foot", "knee", "hand", "elbow"])]);
+export const POLE_CHANNELS = new Set(sided(["knee", "elbow"]));
+export const NUM_CHANNELS = new Set(["yaw", "pitch", "roll", "spine_yaw", "spine_pitch", "spine_roll", "head_yaw", "head_pitch", "head_roll", "arm_rest", "arm_hang",
+	...sided(["fyaw", "fpitch", "armw", "wtwist", "wflex", "aswing", "abend"])]);
+export const MAP_CHANNELS = new Set(sided(["fingers"]));
+// Channels the skills key (standIdle, walks): valid in a spec, left out of motion.describe so a first spec need not read them.
+export const SKILL_CHANNELS = new Set(["arm_hang"]);
+export const FINGER_PRESETS = ["relaxed", "fist", "grip", "cigarette", "point"];
+
+// [min, max, convention] for numeric channels whose values have a hard range.
+const RANGES = [
+	[/^(armw)_[lr]$/, 0, 1, "0 = FK arm, 1 = IK to the hand target"],
+	[/^arm_hang$/, 0, 1, "1 = a free FK forearm hangs plumb"],
+	[/^w_.+_[lr]$/, 0, 1, "a hand-target weight; the weights of one hand add up to at most 1"],
+	[/^wtwist_[lr]$/, -85, 85, "wrist twist about the forearm in degrees"],
+	[/^wflex_[lr]$/, -70, 70, "wrist flex about the knuckle line in degrees"],
+	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch in degrees: + lifts the heel (the toes stay flat), - lifts the toes"],
+	[/^(pitch|spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
+	[/^(roll|spine_roll|head_roll)$/, -90, 90, "degrees"],
+];
+export const rangeOf = ch => RANGES.find(([re]) => re.test(ch)) ?? null;
+
+export const CONVENTIONS = {
+	yaw: "yaw 0 faces +Z and + turns toward +X",
+	fyaw: "foot heading in degrees, as yaw",
+	pole: "a body-frame direction (turned by the root yaw only): +z forward, +x the character's left, +y up",
+	foot: "the ANKLE target in world metres (standing: 0.087 X Bot, 0.105 Y Bot)",
+	hand: "the WRIST target in world metres",
+	root: "the hips joint in world metres (standing: 1.03 X Bot, 0.99 Y Bot)",
+};
+
+/** What each channel family means (a family drops the _l/_r side), for motion.describe "channels". */
+export const CHANNEL_DOCS = {
+	root: CONVENTIONS.root, yaw: `degrees; ${CONVENTIONS.yaw}`, pitch: "whole-body pitch, degrees", roll: "whole-body roll, degrees",
+	spine_yaw: "degrees", spine_pitch: "degrees, + bends forward", spine_roll: "degrees", head_yaw: "degrees", head_pitch: "degrees, + looks down", head_roll: "degrees",
+	arm_rest: "FK arms down from the T-pose (default 72)", arm_hang: "1 = a free FK forearm hangs plumb (standIdle and walks key it)", foot: CONVENTIONS.foot, fyaw: CONVENTIONS.fyaw, fpitch: "toe-down pitch, degrees, + heel up",
+	knee: `knee pole, ${CONVENTIONS.pole}`, armw: "0 = FK arm, 1 = IK to hand_* / the anchors", hand: CONVENTIONS.hand, elbow: `elbow pole, ${CONVENTIONS.pole}`,
+	wtwist: "wrist twist, degrees", wflex: "wrist flex, degrees", aswing: "FK arm swing, degrees, + forward", abend: "FK elbow bend, degrees",
+	fingers: "{ preset: weight 0..1 }",
+};
+export const channelFamily = ch => ch.replace(/_[lr]$/, "");
+
+/** "; did you mean ..." for an unknown field: frame words point at the field that takes frames, distance words at the tolerance. */
+const FIELD_ALIASES = [[["frames", "when", "range", "f", "from", "within", "during", "at"], ["when", "frames", "at", "f"]], [["max", "maxDist", "distance", "tolerance", "limit"], ["tol", "min"]]];
+export function suggestField(name, fields) {
+	for (const [words, targets] of FIELD_ALIASES) {
+		const to = words.includes(name) && targets.find(t => fields.includes(t) && t !== name);
+		if (to) return `; did you mean "${to}"?`;
+	}
+	return didYouMean(name, fields, Math.max(2, Math.floor(name.length / 3)));
+}
+
+export const isVec3 = v => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
+export const fmt = v => JSON.stringify(v)?.slice(0, 60);
+
+/** Levenshtein distance, for "did you mean" suggestions. */
+function editDistance(a, b) {
+	const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+	for (let j = 1; j <= b.length; j++) d[0][j] = j;
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+	return d[a.length][b.length];
+}
+
+export function didYouMean(name, options, maxD = Math.max(3, Math.floor(name.length / 3))) {
+	let best = null, bestD = Infinity;
+	for (const o of options) { const d = editDistance(name, o); if (d < bestD) { best = o; bestD = d; } }
+	return best && bestD <= maxD ? `; did you mean "${best}"?` : "";
+}