@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/motion.js

@@ -0,0 +1,1476 @@
+import { requireValue } from "./required.js";
+import { linear } from "./compat.js";
+import { AssetCompileError } from "./diagnostics.js";
+import { appendMesh, emptyMesh, meshBounds, sourceHash } from "./mesh.js";
+import { IDENTITY, applyPoint, applyVector, compose, quantize, rotation, translation } from "./math.js";
+/** Motion sets for asset-assembly/0.2 characters. */
+export const MOTION_SCHEMA = "motion-set/0.1";
+/** Lift and ground-penetration tolerance as a fraction of the asset's rest height. */
+export const CONTACT_TOLERANCE = 0.02;
+/** Planted-effector drift tolerance as a fraction of the asset's rest height. */
+export const SLIP_TOLERANCE = 0.04;
+/** Uniform verification samples per clip; contact intervals receive 16 additional samples each. */
+export const VERIFICATION_SAMPLES = 48;
+const pointer = (s) => s.replaceAll("~", "~0").replaceAll("/", "~1");
+/** A string value as itself; anything else as "", without coercion (which can throw or alias). */
+const text = (v) => (typeof v === "string" ? v : "");
+const record = (v) => !!v &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+const has = (v, k) => Object.hasOwn(v, k);
+const idPattern = /^[A-Za-z][A-Za-z0-9_-]{0,79}$/;
+const refPattern = /^[A-Za-z][A-Za-z0-9_-]{0,79}(\/(left|right|0|[1-9][0-9]{0,2}))?$/;
+const finite = (v) => typeof v === "number" && Number.isFinite(v);
+const round = (v, digits = 4) => Math.round(v * 10 ** digits) / 10 ** digits;
+function structural(input) {
+    const diagnostics = [];
+    const fail = (path, message, code = "SCHEMA_ERROR", extra = {}) => diagnostics.push({ code, path, message, ...extra });
+    const obj = (v, path, allowed, required = []) => {
+        if (!record(v)) {
+            fail(path, "Expected a plain JSON object.");
+            return false;
+        }
+        for (const k of Object.keys(v))
+            if (!allowed.includes(k))
+                fail(`${path}/${pointer(k)}`, "Unknown field or unsupported operation.", "UNKNOWN_FIELD");
+        for (const k of required)
+            if (!has(v, k))
+                fail(`${path}/${k}`, "Required field is missing.");
+        return true;
+    };
+    const dictionary = (v, path, fn, pattern = idPattern, min = 0, max = 256) => {
+        if (!record(v)) {
+            fail(path, "Expected a dictionary of named entries.");
+            return;
+        }
+        if (Object.keys(v).length < min || Object.keys(v).length > max)
+            fail(path, `Expected ${min}–${max} entries.`, "GEOMETRY_BUDGET");
+        for (const [id, entry] of Object.entries(v)) {
+            if (!pattern.test(id))
+                fail(`${path}/${pointer(id)}`, pattern === refPattern
+                    ? "Use a joint or part ID, optionally followed by /left, /right or an array copy index such as /0."
+                    : "IDs must start with a letter and contain letters, digits, underscores or hyphens.");
+            fn(entry, `${path}/${pointer(id)}`);
+        }
+    };
+    const values = (v, path) => dictionary(v, path, (dofs, p) => dictionary(dofs, p, (n, dp) => {
+        if (!finite(n))
+            fail(dp, "Angles are finite numbers of degrees.", "NON_FINITE_VALUE");
+    }), refPattern);
+    const states = (v, path) => dictionary(v, path, (state, sp) => {
+        if (typeof state !== "string")
+            fail(sp, "Expected a state name.");
+    });
+    if (!obj(input, "", ["schema", "poses", "expressions", "clips"], ["schema", "clips"]))
+        return diagnostics;
+    const root = input;
+    if (root.schema !== MOTION_SCHEMA)
+        fail("/schema", `Expected ${MOTION_SCHEMA}.`, "UNSUPPORTED_SCHEMA", { received: root.schema });
+    if (root.poses !== undefined)
+        dictionary(root.poses, "/poses", (v, p) => {
+            if (obj(v, p, ["joints"], ["joints"]))
+                values(v.joints, `${p}/joints`);
+        });
+    if (root.expressions !== undefined)
+        dictionary(root.expressions, "/expressions", (v, p) => {
+            if (!obj(v, p, ["joints", "states"]))
+                return;
+            const e = v;
+            if (e.joints !== undefined)
+                values(e.joints, `${p}/joints`);
+            if (e.states !== undefined)
+                states(e.states, `${p}/states`);
+        });
+    const poses = record(root.poses) ? root.poses : {}, expressions = record(root.expressions) ? root.expressions : {};
+    dictionary(root.clips, "/clips", (v, p) => {
+        if (!obj(v, p, [
+            "duration",
+            "loop",
+            "interpolation",
+            "symmetry",
+            "keys",
+            "contacts",
+            "grounding",
+            "travel",
+            "solve",
+        ], ["duration", "loop", "keys"]))
+            return;
+        const clip = v;
+        if (!finite(clip.duration) || clip.duration <= 0 || clip.duration > 600)
+            fail(`${p}/duration`, "Duration is a positive number of seconds, at most 600.");
+        if (typeof clip.loop !== "boolean")
+            fail(`${p}/loop`, "Expected a boolean.");
+        if (clip.interpolation !== undefined &&
+            !["smooth", "linear", "step"].includes(text(clip.interpolation)))
+            fail(`${p}/interpolation`, "Choose smooth, linear or step.", "SCHEMA_ERROR", {
+                received: clip.interpolation,
+                expected: ["smooth", "linear", "step"],
+            });
+        if (clip.symmetry !== undefined && !["none", "alternate"].includes(text(clip.symmetry)))
+            fail(`${p}/symmetry`, "Choose none or alternate.", "SCHEMA_ERROR", {
+                received: clip.symmetry,
+                expected: ["none", "alternate"],
+            });
+        if (!Array.isArray(clip.keys) || clip.keys.length < 1 || clip.keys.length > 256)
+            fail(`${p}/keys`, "Expected an array of 1–256 keys.");
+        else
+            clip.keys.forEach((key, i) => {
+                const kp = `${p}/keys/${i}`;
+                if (!obj(key, kp, ["at", "pose", "expression", "joints", "states"], ["at"]))
+                    return;
+                const k = key;
+                if (!finite(k.at) || k.at < 0 || k.at > 1)
+                    fail(`${kp}/at`, "Key times are normalized from 0 to 1 of the clip duration.");
+                if (Object.keys(k).length < 2)
+                    fail(kp, "A key needs a pose, an expression, joints or states.");
+                if (k.expression !== undefined &&
+                    (typeof k.expression !== "string" || !has(expressions, k.expression)))
+                    fail(`${kp}/expression`, "Unknown expression.", "UNKNOWN_EXPRESSION", {
+                        received: k.expression,
+                        expected: Object.keys(expressions).sort(),
+                    });
+                if (k.states !== undefined)
+                    states(k.states, `${kp}/states`);
+                if (k.pose !== undefined && (typeof k.pose !== "string" || !has(poses, k.pose)))
+                    fail(`${kp}/pose`, "Unknown pose.", "UNKNOWN_POSE", {
+                        received: k.pose,
+                        expected: Object.keys(poses).sort(),
+                    });
+                if (k.joints !== undefined)
+                    values(k.joints, `${kp}/joints`);
+            });
+        if (clip.contacts !== undefined)
+            dictionary(clip.contacts, `${p}/contacts`, (intervals, cp) => {
+                if (!Array.isArray(intervals) || intervals.length < 1 || intervals.length > 16) {
+                    fail(cp, "Expected an array of 1–16 [start, end] intervals.");
+                    return;
+                }
+                intervals.forEach((interval, i) => {
+                    if (!Array.isArray(interval) || interval.length !== 2 || !interval.every(finite))
+                        fail(`${cp}/${i}`, "Expected [start, end] in normalized clip time.");
+                });
+            }, refPattern);
+        const g = clip.grounding;
+        if (g !== undefined && obj(g, `${p}/grounding`, ["type", "part", "anchor"], ["type"])) {
+            const r = g;
+            if (!["none", "contacts", "anchor"].includes(text(r.type)))
+                fail(`${p}/grounding/type`, "Choose none, contacts or anchor.", "SCHEMA_ERROR", {
+                    received: r.type,
+                    expected: ["none", "contacts", "anchor"],
+                });
+            else if (r.type === "anchor") {
+                if (typeof r.part !== "string")
+                    fail(`${p}/grounding/part`, "Expected a part or instance ID.");
+                if (typeof r.anchor !== "string")
+                    fail(`${p}/grounding/anchor`, "Expected an anchor name.");
+            }
+            else
+                for (const k of ["part", "anchor"])
+                    if (r[k] !== undefined)
+                        fail(`${p}/grounding/${k}`, "Only anchor grounding names a part.", "UNKNOWN_FIELD");
+        }
+        if (clip.solve !== undefined && !["none", "planted"].includes(text(clip.solve)))
+            fail(`${p}/solve`, "Choose none or planted.", "SCHEMA_ERROR", {
+                received: clip.solve,
+                expected: ["none", "planted"],
+            });
+        const t = clip.travel;
+        if (t !== undefined && t !== "contacts" && obj(t, `${p}/travel`, ["x", "y", "z"], ["x", "y", "z"]))
+            for (const a of ["x", "y", "z"])
+                if (!finite(t[a]))
+                    fail(`${p}/travel/${a}`, "Travel is a finite displacement per cycle.", "NON_FINITE_VALUE");
+    }, idPattern, 1);
+    return diagnostics;
+}
+/* --------------------------------------------------------------------------- interpolation */
+const sign = (v) => (v > 0 ? 1 : v < 0 ? -1 : 0);
+/** Steffen (1990) monotone tangents: C1, passes through every key and never overshoots a segment. */
+function tangents(times, values, loop, cycle = 0) {
+    const n = times.length;
+    if (n < 2 && !cycle)
+        return new Array(n).fill(0);
+    const at = (i) => {
+        if (!loop)
+            return [requireValue(times[i]), requireValue(values[i])];
+        const wrap = Math.floor(i / n), j = i - wrap * n;
+        // A continuous DOF unwraps: each further cycle adds `cycle` degrees.
+        return [
+            requireValue(times[j]) + wrap,
+            cycle ? requireValue(values[j]) + wrap * cycle : requireValue(values[j]),
+        ];
+    };
+    return times.map((_, i) => {
+        if (!loop && (i === 0 || i === n - 1))
+            return 0;
+        const [x0, y0] = at(i - 1), [x1, y1] = at(i), [x2, y2] = at(i + 1);
+        const h0 = x1 - x0, h1 = x2 - x1, s0 = (y1 - y0) / h0, s1 = (y2 - y1) / h1, p = (s0 * h1 + s1 * h0) / (h0 + h1);
+        return (sign(s0) + sign(s1)) * Math.min(Math.abs(s0), Math.abs(s1), 0.5 * Math.abs(p));
+    });
+}
+function evaluate(channel, u, loop, mode) {
+    const { times: t, values: v, tangents: m } = channel, n = t.length, cycle = loop ? (channel.cycle ?? 0) : 0;
+    if (n === 1 && !cycle)
+        return requireValue(v[0]);
+    let i, x0, x1;
+    let base = 0;
+    if (loop) {
+        if (u < requireValue(t[0])) {
+            u += 1;
+            // Before the first key of a continuous channel, the closing segment ends one cycle earlier.
+            base = -cycle;
+        }
+        i = n - 1;
+        for (let k = 0; k < n - 1; k++)
+            if (u >= requireValue(t[k]) && u < requireValue(t[k + 1])) {
+                i = k;
+                break;
+            }
+        x0 = requireValue(t[i]);
+        x1 = i === n - 1 ? requireValue(t[0]) + 1 : requireValue(t[i + 1]);
+    }
+    else {
+        if (u <= requireValue(t[0]))
+            return requireValue(v[0]);
+        if (u >= requireValue(t[n - 1]))
+            return requireValue(v[n - 1]);
+        i = 0;
+        while (u >= requireValue(t[i + 1]))
+            i++;
+        x0 = requireValue(t[i]);
+        x1 = requireValue(t[i + 1]);
+    }
+    const j = (i + 1) % n, h = x1 - x0, s = (u - x0) / h;
+    if (cycle) {
+        // The closing segment of a continuous channel runs on to the first key plus one cycle.
+        const a = requireValue(v[i]) + base, b = requireValue(v[j]) + base + (j === 0 ? cycle : 0);
+        if (mode === "step")
+            return a;
+        if (mode === "linear")
+            return a + (b - a) * s;
+        const s2 = s * s, s3 = s2 * s;
+        return ((2 * s3 - 3 * s2 + 1) * a +
+            (s3 - 2 * s2 + s) * h * requireValue(m[i]) +
+            (-2 * s3 + 3 * s2) * b +
+            (s3 - s2) * h * requireValue(m[j]));
+    }
+    if (mode === "step")
+        return requireValue(v[i]);
+    if (mode === "linear")
+        return requireValue(v[i]) + (requireValue(v[j]) - requireValue(v[i])) * s;
+    const s2 = s * s, s3 = s2 * s;
+    return ((2 * s3 - 3 * s2 + 1) * requireValue(v[i]) +
+        (s3 - 2 * s2 + s) * h * requireValue(m[i]) +
+        (-2 * s3 + 3 * s2) * requireValue(v[j]) +
+        (s3 - s2) * h * requireValue(m[j]));
+}
+/* --------------------------------------------------------------------------- posing */
+/** Rotation about the joint's pivot: [R | p − R·p]. */
+function localTransform(joint, values) {
+    let r = IDENTITY;
+    for (const dof of joint.dofs) {
+        const degrees = values[joint.id]?.[dof.name] ?? 0;
+        if (degrees !== 0)
+            r = r === IDENTITY ? rotation(dof.axis, degrees) : compose(r, rotation(dof.axis, degrees));
+    }
+    if (r === IDENTITY)
+        return IDENTITY;
+    const [x, y, z] = joint.pivot;
+    return [
+        requireValue(r[0]),
+        requireValue(r[1]),
+        requireValue(r[2]),
+        x - (requireValue(r[0]) * x + requireValue(r[1]) * y + requireValue(r[2]) * z),
+        requireValue(r[4]),
+        requireValue(r[5]),
+        requireValue(r[6]),
+        y - (requireValue(r[4]) * x + requireValue(r[5]) * y + requireValue(r[6]) * z),
+        requireValue(r[8]),
+        requireValue(r[9]),
+        requireValue(r[10]),
+        z - (requireValue(r[8]) * x + requireValue(r[9]) * y + requireValue(r[10]) * z),
+    ];
+}
+function jointTransforms(asset, values) {
+    const world = new Map();
+    for (const joint of requireValue(asset.skeleton).joints) {
+        const local = localTransform(joint, values), parent = joint.parent === null ? IDENTITY : requireValue(world.get(joint.parent));
+        world.set(joint.id, parent === IDENTITY ? local : local === IDENTITY ? parent : compose(parent, local));
+    }
+    return world;
+}
+const chains = new WeakMap();
+/** World transform of one joint, composing only its ancestors (used inside the solver). */
+function chainTransform(asset, values, id) {
+    let cache = chains.get(asset);
+    if (!cache)
+        chains.set(asset, (cache = new Map()));
+    let chain = cache.get(id);
+    if (!chain) {
+        const byId = new Map(requireValue(asset.skeleton).joints.map((j) => [j.id, j]));
+        chain = [];
+        for (let j = id; j !== null; j = requireValue(byId.get(j)).parent)
+            chain.unshift(requireValue(byId.get(j)));
+        cache.set(id, chain);
+    }
+    let m = IDENTITY;
+    for (const joint of chain) {
+        const local = localTransform(joint, values);
+        if (local !== IDENTITY)
+            m = m === IDENTITY ? local : compose(m, local);
+    }
+    return m;
+}
+const transformFor = (instance, world, root) => compose(translation(root), instance.joint ? requireValue(world.get(instance.joint)) : IDENTITY);
+function lowest(instance, m) {
+    let y = Infinity;
+    const p = instance.mesh.positions;
+    for (let i = 0; i < p.length; i += 3)
+        y = Math.min(y, applyPoint(m, [requireValue(p[i]), requireValue(p[i + 1]), requireValue(p[i + 2])])[1]);
+    return y;
+}
+/* --------------------------------------------------------------------------- compilation */
+function compileClips(spec, r) {
+    const { asset, joints, names } = r;
+    const errors = [], fail = (d) => {
+        errors.push(d);
+    };
+    const addressable = [...names.keys()].sort();
+    const channelKey = (joint, dof) => `${joint}\u0000${dof}`;
+    const allChannels = [...joints.values()].flatMap((j) => j.dofs.map((d) => channelKey(j.id, d.name)));
+    const isFace = (key) => requireValue(joints.get(requireValue(key.split("\u0000")[0]))).face === true;
+    const declaredStates = asset.states ?? {};
+    /**
+     * Resolve a values object into explicit channel values. Poses may only set body joints and
+     * expressions only face joints; key `joints` may set either.
+     */
+    const resolveValues = (values, path, alternate, track) => {
+        const out = new Map(), origin = new Map();
+        for (const ref of Object.keys(values).sort()) {
+            const targets = names.get(ref), jp = `${path}/${pointer(ref)}`;
+            if (!targets) {
+                fail({
+                    code: "UNKNOWN_JOINT",
+                    path: jp,
+                    message: "Choose a joint exported by this asset's skeleton.",
+                    received: ref,
+                    expected: addressable,
+                });
+                continue;
+            }
+            const face = requireValue(joints.get(requireValue(targets[0]))).face === true;
+            if (track === "body" && face) {
+                fail({
+                    code: "FACE_JOINT_IN_POSE",
+                    path: jp,
+                    message: "Poses set body joints. Set face joints in an expression or in a key's joints.",
+                    received: ref,
+                });
+                continue;
+            }
+            if (track === "face" && !face) {
+                fail({
+                    code: "BODY_JOINT_IN_EXPRESSION",
+                    path: jp,
+                    message: "Expressions set face joints and states only. Set body joints in a pose.",
+                    received: ref,
+                });
+                continue;
+            }
+            // Alternate symmetry shifts sided body joints; faces stay symmetric.
+            if (alternate && !face && ref.endsWith("/right")) {
+                fail({
+                    code: "SYMMETRY_CONFLICT",
+                    path: jp,
+                    message: "Alternate symmetry derives every right-side value from the left side half a cycle later.",
+                    received: ref,
+                });
+                continue;
+            }
+            // A mirrored pair, not a two-copy array: only the left joint is keyed; the right follows.
+            const sided = targets.length === 2 && requireValue(joints.get(requireValue(targets[0]))).side === "left";
+            for (const id of alternate && sided && !face ? targets.slice(0, 1) : targets) {
+                const joint = requireValue(joints.get(id));
+                for (const dof of Object.keys(requireValue(values[ref])).sort()) {
+                    const value = requireValue(requireValue(values[ref])[dof]), dp = `${jp}/${pointer(dof)}`, spec = joint.dofs.find((d) => d.name === dof);
+                    if (!spec) {
+                        fail({
+                            code: "UNKNOWN_DOF",
+                            path: dp,
+                            message: `Choose a degree of freedom exported by joint ${joint.joint}.`,
+                            received: dof,
+                            expected: joint.dofs.map((d) => d.name),
+                        });
+                        continue;
+                    }
+                    if (value < spec.limits[0] || value > spec.limits[1])
+                        fail({
+                            code: "JOINT_LIMIT",
+                            path: dp,
+                            message: `Joint ${joint.joint} ${dof} accepts ${spec.limits[0]}° to ${spec.limits[1]}°.`,
+                            received: value,
+                            expected: spec.limits.map(String),
+                        });
+                    const key = channelKey(id, dof);
+                    if (origin.has(key) && origin.get(key) !== ref)
+                        fail({
+                            code: "SYMMETRY_CONFLICT",
+                            path: dp,
+                            message: `Both ${origin.get(key)} and ${ref} set this value. Use the bare name for both sides or one side each.`,
+                        });
+                    origin.set(key, ref);
+                    out.set(key, value);
+                }
+            }
+        }
+        return out;
+    };
+    const resolveStates = (values, path) => {
+        const out = new Map();
+        for (const channel of Object.keys(values).sort()) {
+            const sp = `${path}/${pointer(channel)}`, declared = declaredStates[channel];
+            if (!declared)
+                fail({
+                    code: "UNKNOWN_STATE",
+                    path: sp,
+                    message: "Choose a state channel declared by the asset.",
+                    received: channel,
+                    expected: Object.keys(declaredStates).sort(),
+                });
+            else if (!declared.includes(requireValue(values[channel])))
+                fail({
+                    code: "UNKNOWN_STATE_VALUE",
+                    path: sp,
+                    message: `Choose a state of channel ${channel}.`,
+                    received: values[channel],
+                    expected: declared,
+                });
+            else
+                out.set(channel, requireValue(values[channel]));
+        }
+        return out;
+    };
+    const poseSpecs = spec.poses ?? {}, expressionSpecs = spec.expressions ?? {};
+    /** A pose sets every body DOF: listed values, 0 for all others. */
+    const poseValues = (name, alternate, path) => {
+        const explicit = resolveValues(requireValue(poseSpecs[name]).joints, path, alternate, "body"), out = new Map();
+        for (const key of allChannels)
+            if (!isFace(key))
+                out.set(key, explicit.get(key) ?? 0);
+        return out;
+    };
+    /** An expression sets every face DOF and every state: listed values, rest values for all others. */
+    const expressionValues = (name, path) => {
+        const e = requireValue(expressionSpecs[name]), explicit = resolveValues(e.joints ?? {}, `${path}/joints`, false, "face"), listed = resolveStates(e.states ?? {}, `${path}/states`), values = new Map(), states = new Map();
+        for (const key of allChannels)
+            if (isFace(key))
+                values.set(key, explicit.get(key) ?? 0);
+        for (const [channel, options] of Object.entries(declaredStates))
+            states.set(channel, listed.get(channel) ?? requireValue(options[0]));
+        return { values, states };
+    };
+    const everything = [...asset.instances, ...(asset.alternates ?? [])];
+    const resolveEffectors = (ref, path) => {
+        if (everything.some((i) => i.id === ref))
+            return [ref];
+        const sided = [`${ref}/left`, `${ref}/right`];
+        if (sided.every((id) => everything.some((i) => i.id === id)))
+            return sided;
+        fail({
+            code: "UNKNOWN_REFERENCE",
+            path,
+            message: "Contacts name a part instance, or a sided part for both sides.",
+            targetPart: ref,
+            expected: everything.map((i) => i.id).sort(),
+        });
+        return [];
+    };
+    const stateTracks = (keys) => Object.keys(declaredStates)
+        .sort()
+        .flatMap((channel) => {
+        const times = [], values = [];
+        for (const k of keys)
+            if (k.states.has(channel)) {
+                times.push(k.at);
+                values.push(requireValue(k.states.get(channel)));
+            }
+        return times.length ? [{ channel, times, values }] : [];
+    });
+    const faceOnly = (channels) => channels.every((c) => requireValue(joints.get(c.joint)).face === true);
+    const build = (name, clip, path) => {
+        const before = errors.length;
+        const loop = clip.loop, alternate = clip.symmetry === "alternate", interpolation = clip.interpolation ?? "smooth", grounding = clip.grounding ?? { type: "none" };
+        if (alternate && !loop)
+            fail({
+                code: "SYMMETRY_REQUIRES_LOOP",
+                path: `${path}/symmetry`,
+                message: "Alternate symmetry shifts the left side by half a cycle and needs a looping clip.",
+            });
+        const keys = [];
+        clip.keys.forEach((key, index) => {
+            const kp = `${path}/keys/${index}`;
+            if (index > 0 && !(key.at > requireValue(clip.keys[index - 1]).at))
+                fail({
+                    code: "KEY_ORDER",
+                    path: `${kp}/at`,
+                    message: "Key times must increase strictly in array order.",
+                    received: key.at,
+                });
+            const values = key.pose !== undefined
+                ? poseValues(key.pose, alternate, `/poses/${pointer(key.pose)}/joints`)
+                : new Map();
+            let states = new Map();
+            if (key.expression !== undefined) {
+                const e = expressionValues(key.expression, `/expressions/${pointer(key.expression)}`);
+                for (const [k, v] of e.values)
+                    values.set(k, v);
+                states = e.states;
+            }
+            if (key.joints)
+                for (const [k, v] of resolveValues(key.joints, `${kp}/joints`, alternate, "any"))
+                    values.set(k, v);
+            if (key.states)
+                for (const [k, v] of resolveStates(key.states, `${kp}/states`))
+                    states.set(k, v);
+            keys.push({ at: key.at, values, states, index });
+        });
+        /** Degrees per loop for continuous DOFs whose closing key adds whole turns. */
+        const cycles = new Map();
+        if (loop && keys.length && requireValue(keys[keys.length - 1]).at === 1) {
+            const last = requireValue(keys.pop()), first = keys[0];
+            const closes = (k, v) => {
+                if (!first?.values.has(k))
+                    return false;
+                const diff = v - requireValue(first.values.get(k));
+                if (Math.abs(diff) < 1e-9)
+                    return true;
+                const [joint, dof] = k.split("\u0000"), turns = Math.round(diff / 360);
+                if (!joints.get(joint)?.dofs.find((d) => d.name === dof)?.continuous)
+                    return false;
+                if (turns === 0 || Math.abs(diff - turns * 360) >= 1e-9)
+                    return false;
+                cycles.set(k, turns * 360);
+                return true;
+            };
+            const same = first !== undefined &&
+                first.at === 0 &&
+                last.values.size === first.values.size &&
+                last.states.size === first.states.size &&
+                [...last.values].every(([k, v]) => closes(k, v)) &&
+                [...last.states].every(([k, v]) => first.states.get(k) === v);
+            if (!same)
+                fail({
+                    code: "CLIP_LOOP_MISMATCH",
+                    path: `${path}/keys/${last.index}`,
+                    message: "A looping clip closes itself. Remove the key at 1, or make it repeat the key at 0 exactly (a continuous DOF may instead add whole turns).",
+                });
+        }
+        const channels = [];
+        for (const key of allChannels) {
+            const [joint, dof] = key.split("\u0000");
+            const j = requireValue(joints.get(joint));
+            if (alternate && j.side === "right" && !j.face)
+                continue;
+            const times = [], vals = [];
+            for (const k of keys)
+                if (k.values.has(key)) {
+                    times.push(k.at);
+                    vals.push(requireValue(k.values.get(key)));
+                }
+            if (!times.length)
+                continue;
+            const cycle = cycles.get(key) ?? 0;
+            channels.push({
+                joint,
+                dof,
+                times,
+                values: vals,
+                tangents: tangents(times, vals, loop, cycle),
+                ...(cycle ? { cycle } : {}),
+            });
+        }
+        if (alternate)
+            for (const c of [...channels]) {
+                const j = requireValue(joints.get(c.joint));
+                if (j.side !== "left" || j.face)
+                    continue;
+                const cycle = c.cycle ?? 0, pairs = c.times
+                    .map((t, i) => 
+                // Keys moved back across the loop seam lose one cycle so a continuous channel stays unwrapped.
+                t + 0.5 >= 1
+                    ? [t - 0.5, requireValue(c.values[i]) - cycle]
+                    : [t + 0.5, requireValue(c.values[i])])
+                    .sort((a, b) => a[0] - b[0]);
+                const times = pairs.map((p) => p[0]), values = pairs.map((p) => p[1]);
+                channels.push({
+                    joint: `${j.joint}/right`,
+                    dof: c.dof,
+                    times,
+                    values,
+                    tangents: tangents(times, values, true, cycle),
+                    ...(cycle ? { cycle } : {}),
+                });
+            }
+        channels.sort((a, b) => (a.joint < b.joint ? -1 : a.joint > b.joint ? 1 : a.dof < b.dof ? -1 : 1));
+        const contacts = [];
+        for (const ref of Object.keys(clip.contacts ?? {}).sort()) {
+            const cp = `${path}/contacts/${pointer(ref)}`;
+            if (alternate && ref.endsWith("/right")) {
+                fail({
+                    code: "SYMMETRY_CONFLICT",
+                    path: cp,
+                    message: "Alternate symmetry derives right-side contacts from the left side half a cycle later.",
+                });
+                continue;
+            }
+            const intervals = requireValue(requireValue(clip.contacts)[ref]).map(([s, e]) => [s, e]);
+            intervals.forEach(([s, e], i) => {
+                const ok = loop ? s >= 0 && s < 1 && e > s && e <= s + 1 : s >= 0 && e > s && e <= 1;
+                if (!ok)
+                    fail({
+                        code: "INVALID_INTERVAL",
+                        path: `${cp}/${i}`,
+                        message: loop
+                            ? "Looping intervals need 0 ≤ start < 1 and start < end ≤ start + 1; an end past 1 wraps."
+                            : "Intervals need 0 ≤ start < end ≤ 1.",
+                        received: [s, e],
+                    });
+            });
+            const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+            for (let i = 0; i < sorted.length; i++) {
+                const next = sorted[i + 1] ?? (loop ? [requireValue(sorted[0])[0] + 1, 0] : null);
+                if (next && sorted.length > 1 && requireValue(sorted[i])[1] > next[0])
+                    fail({
+                        code: "INVALID_INTERVAL",
+                        path: cp,
+                        message: "Contact intervals of one effector must not overlap.",
+                    });
+            }
+            let effectors = resolveEffectors(ref, cp);
+            // Under alternate symmetry an explicit left side behaves like the bare name, as joint values do.
+            if (alternate && effectors.length === 1 && requireValue(effectors[0]).endsWith("/left")) {
+                const right = `${requireValue(effectors[0]).slice(0, -5)}/right`;
+                if (everything.some((i) => i.id === right))
+                    effectors = [requireValue(effectors[0]), right];
+            }
+            const targets = alternate && effectors.length === 2 ? effectors.slice(0, 1) : effectors;
+            for (const effector of targets)
+                contacts.push({ effector, intervals: sorted });
+            if (alternate && effectors.length === 2)
+                contacts.push({
+                    effector: requireValue(effectors[1]),
+                    intervals: sorted
+                        .map(([s, e]) => (s + 0.5 >= 1 ? [s - 0.5, e - 0.5] : [s + 0.5, e + 0.5]))
+                        .sort((a, b) => a[0] - b[0]),
+                });
+        }
+        contacts.sort((a, b) => (a.effector < b.effector ? -1 : 1));
+        if ((grounding.type === "contacts" || clip.travel === "contacts") && !contacts.length)
+            fail({
+                code: "MISSING_CONTACTS",
+                path: clip.travel === "contacts" && grounding.type !== "contacts"
+                    ? `${path}/travel`
+                    : `${path}/grounding`,
+                message: "Contact grounding and contact-derived travel need declared contacts.",
+            });
+        if (grounding.type === "anchor") {
+            const instance = everything.find((i) => i.id === grounding.part);
+            if (!instance)
+                fail({
+                    code: "UNKNOWN_REFERENCE",
+                    path: `${path}/grounding/part`,
+                    message: "Anchor grounding names a part instance.",
+                    targetPart: grounding.part,
+                    expected: everything.map((i) => i.id).sort(),
+                });
+            else if (!has(instance.anchors, grounding.anchor))
+                fail({
+                    code: "UNKNOWN_ANCHOR",
+                    path: `${path}/grounding/anchor`,
+                    message: "Choose an anchor exported by this part.",
+                    part: instance.id,
+                    received: grounding.anchor,
+                    expected: Object.keys(instance.anchors).sort(),
+                });
+        }
+        const solve = clip.solve ?? "none";
+        if (solve === "planted") {
+            if (!contacts.length)
+                fail({
+                    code: "MISSING_CONTACTS",
+                    path: `${path}/solve`,
+                    message: "The planted solve keeps declared contacts in place; declare contacts first.",
+                });
+            for (const c of contacts)
+                if (!(asset.limbs ?? []).some((l) => l.effector === c.effector))
+                    fail({
+                        code: "NO_LIMB",
+                        path: `${path}/contacts`,
+                        message: `No limb has effector ${c.effector}. Declare a limb in the asset, or set solve to none.`,
+                        part: c.effector,
+                        expected: (asset.limbs ?? []).map((l) => l.effector),
+                    });
+        }
+        if (errors.length > before)
+            return null;
+        const compiled = {
+            name,
+            duration: clip.duration,
+            loop,
+            interpolation,
+            symmetry: alternate ? "alternate" : "none",
+            channels,
+            states: stateTracks(keys),
+            face: faceOnly(channels),
+            contacts,
+            grounding: structuredClone(grounding),
+            solve,
+            travel: [0, 0, 0],
+            metrics: { maxSlip: 0, maxLift: 0, minHeight: 0, speed: 0 },
+        };
+        verify(compiled, clip, path, r, fail);
+        return compiled;
+    };
+    /** Poses and expressions compile to single-key clips that sample the same way as clips. */
+    const still = (name, values, states) => {
+        const channels = [...values]
+            .filter(([, v]) => v !== 0)
+            .map(([key, v]) => {
+            const [joint, dof] = key.split("\u0000");
+            return { joint, dof, times: [0], values: [v], tangents: [0] };
+        });
+        return {
+            name,
+            duration: 1,
+            loop: false,
+            interpolation: "step",
+            symmetry: "none",
+            channels,
+            states: stateTracks([{ at: 0, states }]),
+            face: faceOnly(channels),
+            contacts: [],
+            grounding: { type: "none" },
+            solve: "none",
+            travel: [0, 0, 0],
+            metrics: { maxSlip: 0, maxLift: 0, minHeight: 0, speed: 0 },
+        };
+    };
+    const poses = Object.create(null), expressions = Object.create(null), clips = Object.create(null);
+    for (const name of Object.keys(poseSpecs).sort())
+        poses[name] = still(name, poseValues(name, false, `/poses/${pointer(name)}/joints`), new Map());
+    for (const name of Object.keys(expressionSpecs).sort()) {
+        const e = expressionValues(name, `/expressions/${pointer(name)}`);
+        expressions[name] = { ...still(name, e.values, e.states), face: true };
+    }
+    for (const name of Object.keys(spec.clips).sort()) {
+        const clip = build(name, requireValue(spec.clips[name]), `/clips/${pointer(name)}`);
+        if (clip)
+            clips[name] = clip;
+    }
+    const seen = new Set();
+    return {
+        poses,
+        expressions,
+        clips,
+        errors: errors.filter((d) => {
+            const key = JSON.stringify(d);
+            return seen.has(key) ? false : (seen.add(key), true);
+        }),
+    };
+}
+/** Planted effectors at a phase; intervals are closed and loops wrap. */
+function planted(clip, u) {
+    return clip.contacts
+        .filter(({ intervals }) => intervals.some(([s, e]) => (u >= s && u <= e) || (clip.loop && u + 1 >= s && u + 1 <= e)))
+        .map((c) => c.effector);
+}
+function valuesAt(asset, clip, u) {
+    const out = {};
+    for (const joint of requireValue(asset.skeleton).joints) {
+        out[joint.id] = {};
+        for (const dof of joint.dofs)
+            requireValue(out[joint.id])[dof.name] = 0;
+    }
+    for (const c of clip.channels)
+        requireValue(out[c.joint])[c.dof] = quantize(evaluate(c, u, clip.loop, clip.interpolation));
+    return out;
+}
+function statesAt(asset, clip, u) {
+    const out = {};
+    for (const [channel, options] of Object.entries(asset.states ?? {}))
+        out[channel] = requireValue(options[0]);
+    for (const track of clip.states) {
+        let i = -1;
+        for (let k = 0; k < track.times.length; k++)
+            if (requireValue(track.times[k]) <= u)
+                i = k;
+        // Before the first key a loop holds the last state; a one-shot clip holds the first.
+        out[track.channel] = requireValue(track.values[i >= 0 ? i : clip.loop ? track.values.length - 1 : 0]);
+    }
+    return out;
+}
+/** Instances visible in the given states, in stable ID order. */
+function visibleIn(asset, states) {
+    return [...asset.instances, ...(asset.alternates ?? [])]
+        .filter((i) => Object.entries(i.when ?? {}).every(([channel, values]) => values.includes(requireValue(states[channel]))))
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+const instanceOf = (asset, id) => requireValue(asset.instances.find((i) => i.id === id) ?? asset.alternates?.find((i) => i.id === id));
+/* --------------------------------------------------------------------------- planted solve */
+/** Normalized clip time over which the planted correction blends in before touchdown and out after lift-off. */
+export const SOLVE_BLEND = 0.08;
+const smoothstep = (x) => (x <= 0 ? 0 : x >= 1 ? 1 : x * x * (3 - 2 * x));
+/** The contact interval governing an effector at phase u, with the blend weight and unwrapped time. */
+function plantedWindow(clip, intervals, u) {
+    let best = null;
+    const n = intervals.length;
+    intervals.forEach(([s, e], i) => {
+        const prev = requireValue(intervals[(i + n - 1) % n]), next = requireValue(intervals[(i + 1) % n]);
+        const before = clip.loop ? (n === 1 ? 1 - (e - s) : (s - prev[1] + 1) % 1) : i === 0 ? s : s - prev[1], after = clip.loop ? (n === 1 ? 1 - (e - s) : (next[0] - e + 1) % 1) : i === n - 1 ? 1 - e : next[0] - e;
+        const bin = Math.min(SOLVE_BLEND, before / 2), bout = Math.min(SOLVE_BLEND, after / 2);
+        for (const t of clip.loop ? [u, u + 1, u - 1] : [u]) {
+            let weight = 0;
+            if (t >= s && t <= e)
+                weight = 1;
+            else if (bin > 0 && t >= s - bin && t < s)
+                weight = smoothstep((t - (s - bin)) / bin);
+            else if (bout > 0 && t > e && t <= e + bout)
+                weight = smoothstep(1 - (t - e) / bout);
+            if (weight > 0 && (!best || weight > best.weight))
+                best = { s, t, weight };
+        }
+    });
+    return best;
+}
+const targets = new WeakMap();
+/** Where an effector touched down, in body space (pose + grounding, without travel). */
+function plantTarget(asset, clip, limb, s) {
+    let cache = targets.get(clip);
+    if (!cache)
+        targets.set(clip, (cache = new Map()));
+    const key = `${limb.id}\u0000${s}`;
+    if (cache.has(key))
+        return requireValue(cache.get(key));
+    const u = clip.loop ? s - Math.floor(s) : s, world = jointTransforms(asset, valuesAt(asset, clip, u)), root = rootAt(asset, clip, u, world), instance = instanceOf(asset, limb.effector), rest = requireValue(instance.anchors[limb.anchor]), p = applyPoint(transformFor(instance, world, root), rest);
+    // On the ground, a levelled effector rests at its rest height above its lowest point.
+    const y = clip.grounding.type === "anchor"
+        ? p[1]
+        : limb.level
+            ? rest[1] - instance.bounds.min[1]
+            : p[1] - lowest(instance, transformFor(instance, world, root));
+    const target = [p[0], y, p[2]];
+    cache.set(key, target);
+    return target;
+}
+const roundDegrees = (v) => {
+    const q = Math.round(v * 1e9) / 1e9;
+    return q === 0 ? 0 : q;
+};
+/** Damped normal equations (JᵀJ + λI)Δ = Jᵀr for up to three columns, by Gaussian elimination. */
+function leastSquares(columns, residual) {
+    const n = columns.length, dot3 = (a, b) => requireValue(a[0]) * requireValue(b[0]) +
+        requireValue(a[1]) * requireValue(b[1]) +
+        requireValue(a[2]) * requireValue(b[2]);
+    const m = columns.map((a, i) => [
+        ...columns.map((b, j) => dot3(a, b) + (i === j ? 1e-9 : 0)),
+        dot3(a, residual),
+    ]);
+    for (let c = 0; c < n; c++) {
+        let pivot = c;
+        for (let r = c + 1; r < n; r++)
+            if (Math.abs(requireValue(requireValue(m[r])[c])) > Math.abs(requireValue(requireValue(m[pivot])[c])))
+                pivot = r;
+        [m[c], m[pivot]] = [requireValue(m[pivot]), requireValue(m[c])];
+        if (Math.abs(requireValue(requireValue(m[c])[c])) < 1e-18)
+            return new Array(n).fill(0);
+        for (let r = 0; r < n; r++) {
+            if (r === c)
+                continue;
+            const f = requireValue(requireValue(m[r])[c]) / requireValue(requireValue(m[c])[c]);
+            for (let k = c; k <= n; k++) {
+                const row = requireValue(m[r]);
+                row[k] = requireValue(row[k]) - f * requireValue(requireValue(m[c])[k]);
+            }
+        }
+    }
+    return m.map((row, i) => requireValue(row[n]) / requireValue(row[i]));
+}
+const reaches = new WeakMap();
+/** Rest distance from a limb's first reach pivot to its effector: the rest pose is full extension. */
+function reachLength(asset, limb) {
+    let cache = reaches.get(asset);
+    if (!cache)
+        reaches.set(asset, (cache = new Map()));
+    if (!cache.has(limb.id)) {
+        const pivot = requireValue(requireValue(asset.skeleton).joints.find((j) => j.id === requireValue(limb.reach[0]).joint)).pivot, anchor = requireValue(instanceOf(asset, limb.effector).anchors[limb.anchor]);
+        cache.set(limb.id, Math.hypot(anchor[0] - pivot[0], anchor[1] - pivot[1], anchor[2] - pivot[2]));
+    }
+    return requireValue(cache.get(limb.id));
+}
+/**
+ * Authored values with declared limbs solved so planted effectors stay at their touchdown point, which
+ * recedes at the clip's travel speed. When a planted limb cannot reach at 99.5% of its rest length, the
+ * root drops by the shortfall. Then a deterministic damped Gauss-Newton solves up to three reach DOFs and
+ * a one-DOF level solve keeps the effector flat; results are clamped to limits and rounded to 1e-9°.
+ */
+function solvedPoseAt(asset, clip, u) {
+    const values = valuesAt(asset, clip, u), root = rootAt(asset, clip, u);
+    if (clip.solve !== "planted")
+        return { values, root };
+    const joints = new Map(requireValue(asset.skeleton).joints.map((j) => [j.id, j]));
+    const clamp = (r, v) => {
+        const [lo, hi] = requireValue(requireValue(joints.get(r.joint)).dofs.find((d) => d.name === r.dof)).limits;
+        return Math.max(lo, Math.min(hi, v));
+    };
+    const plans = [];
+    for (const track of clip.contacts) {
+        const limb = requireValue(requireValue(asset.limbs).find((l) => l.effector === track.effector)), hit = plantedWindow(clip, track.intervals, u);
+        if (!hit)
+            continue;
+        const touchdown = plantTarget(asset, clip, limb, hit.s);
+        plans.push({
+            limb,
+            weight: hit.weight,
+            goal: [
+                touchdown[0] - clip.travel[0] * (hit.t - hit.s),
+                touchdown[1],
+                touchdown[2] - clip.travel[2] * (hit.t - hit.s),
+            ],
+        });
+    }
+    if (!plans.length)
+        return clearance(asset, clip, values, root, new Map());
+    const authored = jointTransforms(asset, values);
+    let drop = 0;
+    for (const { limb, goal, weight } of plans) {
+        const upper = requireValue(joints.get(requireValue(limb.reach[0]).joint)), p = applyPoint(requireValue(authored.get(upper.id)), upper.pivot), d = [goal[0] - p[0] - root[0], goal[1] - p[1] - root[1], goal[2] - p[2] - root[2]], reach = 0.995 * reachLength(asset, limb), horizontal = d[0] * d[0] + d[2] * d[2];
+        const needed = reach * reach > horizontal ? d[1] + Math.sqrt(reach * reach - horizontal) : d[1];
+        if (needed < 0)
+            drop = Math.min(drop, weight * needed);
+    }
+    const lowered = [root[0], root[1] + drop, root[2]];
+    const h = 0.01;
+    for (const { limb, goal, weight } of plans) {
+        const instance = instanceOf(asset, limb.effector), rest = requireValue(instance.anchors[limb.anchor]), solved = structuredClone(values);
+        const get = (r) => requireValue(requireValue(solved[r.joint])[r.dof]), set = (r, v) => (requireValue(solved[r.joint])[r.dof] = v);
+        const chain = requireValue(instance.joint), effector = () => applyPoint(compose(translation(lowered), chainTransform(asset, solved, chain)), rest);
+        for (let iteration = 0; iteration < 12; iteration++) {
+            const p = effector(), residual = [goal[0] - p[0], goal[1] - p[1], goal[2] - p[2]];
+            if (Math.hypot(...residual) < 1e-10)
+                break;
+            const columns = limb.reach.map((r) => {
+                const v = get(r);
+                set(r, v + h);
+                const plus = effector();
+                set(r, v - h);
+                const minus = effector();
+                set(r, v);
+                return [0, 1, 2].map((k) => (requireValue(plus[k]) - requireValue(minus[k])) / (2 * h));
+            });
+            const steps = leastSquares(columns, residual);
+            limb.reach.forEach((r, k) => set(r, clamp(r, get(r) + Math.max(-20, Math.min(20, requireValue(steps[k]))))));
+        }
+        if (limb.level) {
+            // Keep the effector part's front (rest −Z) horizontal.
+            const level = limb.level, tilt = () => applyVector(chainTransform(asset, solved, chain), [0, 0, -1])[1];
+            for (let iteration = 0; iteration < 8; iteration++) {
+                const v = get(level), g = tilt();
+                if (Math.abs(g) < 1e-12)
+                    break;
+                set(level, v + h);
+                const plus = tilt();
+                set(level, v - h);
+                const minus = tilt();
+                const slope = (plus - minus) / (2 * h);
+                set(level, Math.abs(slope) < 1e-12 ? v : clamp(level, v - Math.max(-30, Math.min(30, g / slope))));
+            }
+        }
+        for (const r of [...limb.reach, ...(limb.level ? [limb.level] : [])]) {
+            const original = requireValue(requireValue(values[r.joint])[r.dof]);
+            requireValue(values[r.joint])[r.dof] = roundDegrees(original + weight * (get(r) - original));
+        }
+    }
+    return clearance(asset, clip, values, lowered, new Map(plans.map((p) => [p.limb.id, p.weight])));
+}
+/**
+ * Part of the planted solve: an unplanted limb whose effector part would sink below the ground is lifted
+ * by its reach DOFs until its lowest point touches the ground. Only ground-based clips are affected.
+ */
+function clearance(asset, clip, values, root, planted) {
+    if (clip.grounding.type === "anchor")
+        return { values, root };
+    const joints = new Map(requireValue(asset.skeleton).joints.map((j) => [j.id, j]));
+    const clamp = (r, v) => {
+        const [lo, hi] = requireValue(requireValue(joints.get(r.joint)).dofs.find((d) => d.name === r.dof)).limits;
+        return Math.max(lo, Math.min(hi, v));
+    };
+    const get = (r) => requireValue(requireValue(values[r.joint])[r.dof]), set = (r, v) => (requireValue(values[r.joint])[r.dof] = v), h = 0.01;
+    for (const limb of asset.limbs ?? []) {
+        // Clearance fades in as the planted correction fades out, so lift-off stays continuous.
+        const strength = 1 - (planted.get(limb.id) ?? 0);
+        if (strength <= 0)
+            continue;
+        const original = limb.reach.map((r) => get(r));
+        const instance = instanceOf(asset, limb.effector), rest = requireValue(instance.anchors[limb.anchor]), at = () => compose(translation(root), chainTransform(asset, values, requireValue(instance.joint))), effector = () => applyPoint(at(), rest);
+        // Lifting bends the chain, which can pitch the effector part, so re-measure a few times.
+        for (let pass = 0; pass < 4; pass++) {
+            const depth = lowest(instance, at());
+            if (depth >= -1e-6)
+                break;
+            const start = effector(), goal = [start[0], start[1] - depth, start[2]];
+            for (let iteration = 0; iteration < 8; iteration++) {
+                const p = effector(), residual = [goal[0] - p[0], goal[1] - p[1], goal[2] - p[2]];
+                if (Math.hypot(...residual) < 1e-9)
+                    break;
+                const columns = limb.reach.map((r) => {
+                    const v = get(r);
+                    set(r, v + h);
+                    const plus = effector();
+                    set(r, v - h);
+                    const minus = effector();
+                    set(r, v);
+                    return [0, 1, 2].map((k) => (requireValue(plus[k]) - requireValue(minus[k])) / (2 * h));
+                });
+                const steps = leastSquares(columns, residual);
+                limb.reach.forEach((r, k) => set(r, clamp(r, get(r) + Math.max(-20, Math.min(20, requireValue(steps[k]))))));
+            }
+        }
+        limb.reach.forEach((r, k) => set(r, roundDegrees(requireValue(original[k]) + strength * (get(r) - requireValue(original[k])))));
+    }
+    return { values, root };
+}
+function contactHeight(asset, clip, u, world) {
+    const ids = planted(clip, u);
+    if (!ids.length)
+        return null;
+    return Math.min(...ids.map((id) => {
+        const instance = instanceOf(asset, id);
+        return lowest(instance, transformFor(instance, world, [0, 0, 0]));
+    }));
+}
+function rootAt(asset, clip, u, world = jointTransforms(asset, valuesAt(asset, clip, u))) {
+    const g = clip.grounding;
+    if (g.type === "anchor") {
+        const instance = instanceOf(asset, g.part), p = applyPoint(transformFor(instance, world, [0, 0, 0]), requireValue(instance.anchors[g.anchor]));
+        return [-p[0], -p[1], -p[2]];
+    }
+    if (g.type !== "contacts")
+        return [0, 0, 0];
+    const here = contactHeight(asset, clip, u, world);
+    if (here !== null)
+        return [0, -here, 0];
+    // Between contacts the root height interpolates linearly from the last lift-off to the next touchdown.
+    let back = Infinity, forward = Infinity, a = 0, b = 0;
+    for (const { intervals } of clip.contacts)
+        for (const [s, e] of intervals) {
+            const end = e - Math.floor(e), db = clip.loop ? (u - end + 1) % 1 : u - e, df = clip.loop ? (s - u + 1) % 1 : s - u;
+            if (db >= 0 && db < back) {
+                back = db;
+                a = e;
+            }
+            if (df >= 0 && df < forward) {
+                forward = df;
+                b = s;
+            }
+        }
+    const heightAt = (t) => {
+        const p = clip.loop ? t - Math.floor(t) : t;
+        return requireValue(contactHeight(asset, clip, p, jointTransforms(asset, valuesAt(asset, clip, p))));
+    };
+    if (!Number.isFinite(back))
+        return [0, -heightAt(b), 0];
+    if (!Number.isFinite(forward))
+        return [0, -heightAt(a), 0];
+    const w = back / (back + forward);
+    return [0, -(heightAt(a) * (1 - w) + heightAt(b) * w), 0];
+}
+function verify(clip, spec, path, r, fail) {
+    const { asset, height } = r, lift = CONTACT_TOLERANCE * height, slipLimit = SLIP_TOLERANCE * height;
+    const phase = (t) => (clip.loop ? t - Math.floor(t) : t);
+    // Travel derives from the authored stride; slip, lift and penetration measure the solved motion.
+    const point = (id, t, solved = true) => {
+        const instance = instanceOf(asset, id), pose = solved
+            ? solvedPoseAt(asset, clip, phase(t))
+            : { values: valuesAt(asset, clip, phase(t)), root: [0, 0, 0] }, world = jointTransforms(asset, pose.values);
+        // Horizontal drift ignores the root, whose x and z come from anchor grounding only.
+        return applyPoint(transformFor(instance, world, [0, 0, 0]), requireValue(instance.anchors["bottom-center"]));
+    };
+    // Travel per cycle that keeps planted effectors stationary on average.
+    let travel = [0, 0, 0];
+    if (spec.travel === "contacts") {
+        let dx = 0, dz = 0, span = 0;
+        for (const c of clip.contacts)
+            for (const [s, e] of c.intervals) {
+                const a = point(c.effector, s, false), b = point(c.effector, e, false);
+                dx += b[0] - a[0];
+                dz += b[2] - a[2];
+                span += e - s;
+            }
+        travel = [quantize(-dx / span), 0, quantize(-dz / span)];
+    }
+    else if (spec.travel)
+        travel = [spec.travel.x, spec.travel.y, spec.travel.z];
+    clip.travel = travel;
+    let maxSlip = 0, maxLift = 0, minHeight = Infinity;
+    for (const c of clip.contacts)
+        for (const [s, e] of c.intervals) {
+            const start = point(c.effector, s);
+            let worst = 0;
+            for (let k = 1; k <= 16; k++) {
+                const t = s + ((e - s) * k) / 16, p = point(c.effector, t), drift = Math.hypot(p[0] - start[0] + travel[0] * (t - s), p[2] - start[2] + travel[2] * (t - s));
+                worst = Math.max(worst, drift);
+            }
+            maxSlip = Math.max(maxSlip, worst);
+            const original = Object.keys(spec.contacts ?? {}).find((ref) => c.effector === ref || c.effector.startsWith(`${ref}/`));
+            if (worst > slipLimit)
+                fail({
+                    code: "CONTACT_SLIP",
+                    path: `${path}/contacts/${pointer(original ?? c.effector)}`,
+                    message: `Planted ${c.effector} drifts ${round(worst, 3)} ${asset.units} (limit ${round(slipLimit, 3)}) during [${round(s)}, ${round(e)}]. Match the stride to the travel, or shorten the interval.`,
+                    part: c.effector,
+                    received: round(worst, 4),
+                    expected: [String(round(slipLimit, 4))],
+                });
+        }
+    if (clip.grounding.type !== "anchor") {
+        const phases = Array.from({ length: VERIFICATION_SAMPLES }, (_, k) => k / VERIFICATION_SAMPLES);
+        for (const c of clip.contacts)
+            for (const [s, e] of c.intervals)
+                for (let k = 0; k <= 8; k++)
+                    phases.push(s + ((e - s) * k) / 8);
+        for (const raw of phases) {
+            const u = clip.loop ? raw - Math.floor(raw) : Math.min(1, raw), solved = solvedPoseAt(asset, clip, u), world = jointTransforms(asset, solved.values), root = solved.root;
+            for (const instance of visibleIn(asset, statesAt(asset, clip, u))) {
+                const y = lowest(instance, transformFor(instance, world, root));
+                minHeight = Math.min(minHeight, y);
+            }
+            for (const id of planted(clip, u)) {
+                const instance = instanceOf(asset, id), h = lowest(instance, transformFor(instance, world, root));
+                maxLift = Math.max(maxLift, h);
+            }
+        }
+        if (maxLift > lift)
+            fail({
+                code: "CONTACT_LIFT",
+                path: `${path}/contacts`,
+                message: `A planted effector rises ${round(maxLift, 3)} ${asset.units} above the ground (limit ${round(lift, 3)}). Use contact grounding or adjust the pose.`,
+                received: round(maxLift, 4),
+                expected: [String(round(lift, 4))],
+            });
+        if (minHeight < -lift)
+            fail({
+                code: "GROUND_PENETRATION",
+                path,
+                message: `Geometry reaches ${round(minHeight, 3)} ${asset.units}, below the ground (limit −${round(lift, 3)}).`,
+                received: round(minHeight, 4),
+                expected: [String(round(-lift, 4))],
+            });
+    }
+    else
+        minHeight = 0;
+    clip.metrics = {
+        maxSlip: round(maxSlip, 6),
+        maxLift: round(maxLift, 6),
+        minHeight: round(minHeight === Infinity ? 0 : minHeight, 6),
+        speed: round(Math.hypot(...travel) / clip.duration, 6),
+    };
+}
+function prepare(asset) {
+    if (!asset || !asset.skeleton || !asset.skeleton.joints.length)
+        throw new AssetCompileError([
+            {
+                code: "UNRIGGED_ASSET",
+                path: "",
+                message: "Motion needs an asset-assembly/0.2 compilation with at least one joint.",
+            },
+        ]);
+    const joints = new Map(asset.skeleton.joints.map((j) => [j.id, j]));
+    const names = new Map();
+    for (const j of asset.skeleton.joints) {
+        names.set(j.id, [j.id]);
+        if (j.side === "left")
+            names.set(j.joint, [j.id, `${j.joint}/right`]);
+        // A bare copied joint (schema 0.3 arrays) addresses every copy.
+        if (j.copy !== undefined)
+            names.set(j.joint, [...(names.get(j.joint) ?? []), j.id]);
+    }
+    const bounds = asset.bounds;
+    return { asset, joints, names, height: Math.max(1e-9, bounds.max[1] - bounds.min[1]) };
+}
+/**
+ * Validate a motion set against a compiled rigged asset and verify its declared contacts.
+ * Throws AssetCompileError with every diagnostic; use checkMotion to keep measured-only results.
+ */
+export function compileMotion(input, asset) {
+    const diagnostics = structural(input);
+    if (diagnostics.length)
+        throw new AssetCompileError(diagnostics);
+    const { poses, expressions, clips, errors } = compileClips(input, prepare(asset));
+    if (errors.length)
+        throw new AssetCompileError(errors);
+    return {
+        schema: MOTION_SCHEMA,
+        sourceHash: sourceHash(input),
+        assetHash: asset.sourceHash,
+        poses,
+        expressions,
+        clips,
+    };
+}
+/** Diagnostics that measure a valid motion rather than reject its description. */
+export const MEASURED_CODES = ["CONTACT_SLIP", "CONTACT_LIFT", "GROUND_PENETRATION"];
+/**
+ * For editors and repair loops: returns the compiled motion together with its diagnostics whenever
+ * every diagnostic is a measurement (slip, lift, penetration). Structural or semantic errors leave
+ * `motion` undefined. compileMotion remains the strict path.
+ */
+export function checkMotion(input, asset) {
+    const diagnostics = structural(input);
+    if (diagnostics.length)
+        return { diagnostics };
+    let resolved;
+    try {
+        resolved = prepare(asset);
+    }
+    catch (error) {
+        if (error instanceof AssetCompileError)
+            return { diagnostics: error.diagnostics };
+        throw error;
+    }
+    const { poses, expressions, clips, errors } = compileClips(input, resolved);
+    if (errors.some((d) => !MEASURED_CODES.includes(d.code)))
+        return { diagnostics: errors };
+    return {
+        motion: {
+            schema: MOTION_SCHEMA,
+            sourceHash: sourceHash(input),
+            assetHash: asset.sourceHash,
+            poses,
+            expressions,
+            clips,
+        },
+        diagnostics: errors,
+    };
+}
+export function validateMotion(input, asset) {
+    try {
+        compileMotion(input, asset);
+        return [];
+    }
+    catch (error) {
+        if (error instanceof AssetCompileError)
+            return error.diagnostics;
+        throw error;
+    }
+}
+/**
+ * Sample a compiled clip, pose or expression at an integer frame, or at a normalized phase.
+ * `face` overlays a face-only clip (an expression or face clip): it replaces every face DOF and state,
+ * sampled at the same time on its own duration, while body joints, grounding and travel come from `clip`.
+ */
+export function samplePose(asset, clip, time, options = {}) {
+    prepare(asset);
+    if ("frame" in time) {
+        if (!Number.isInteger(time.frame) || time.frame < 0 || !Number.isInteger(time.fps) || time.fps < 1)
+            throw new RangeError("Frames and fps are nonnegative integers; fps is at least 1");
+    }
+    else if (!Number.isFinite(time.phase))
+        throw new RangeError("Phase must be finite");
+    const cyclesOf = (c) => ("frame" in time ? time.frame / time.fps / c.duration : time.phase), phaseOf = (c, cycles) => c.loop ? cycles - Math.floor(cycles) : Math.max(0, Math.min(1, cycles));
+    const cycles = cyclesOf(clip), phase = phaseOf(clip, cycles);
+    const solved = solvedPoseAt(asset, clip, phase), values = solved.values;
+    let states = statesAt(asset, clip, phase);
+    if (options.face) {
+        if (!options.face.face)
+            throw new RangeError(`Clip ${options.face.name} keys body joints and cannot be a face overlay`);
+        const fp = phaseOf(options.face, cyclesOf(options.face)), face = valuesAt(asset, options.face, fp);
+        for (const joint of requireValue(asset.skeleton).joints)
+            if (joint.face)
+                values[joint.id] = requireValue(face[joint.id]);
+        states = statesAt(asset, options.face, fp);
+    }
+    const world = jointTransforms(asset, values), root = solved.root.map(quantize), progress = clip.loop ? cycles : phase;
+    return {
+        clip: clip.name,
+        ...(options.face ? { face: options.face.name } : {}),
+        phase,
+        values,
+        states,
+        root,
+        travel: clip.travel.map((v) => quantize(v * progress)),
+        transforms: Object.fromEntries([...world].map(([id, m]) => [id, m.map(quantize)])),
+        contacts: planted(clip, phase),
+    };
+}
+/**
+ * A new compiled asset with posed geometry, bounds and anchors, containing the instances visible in the
+ * pose's states. Rest `translation` values are kept.
+ */
+export function poseAsset(asset, pose) {
+    prepare(asset);
+    const world = new Map(Object.entries(pose.transforms));
+    const instances = visibleIn(asset, pose.states ?? {}).map((instance) => {
+        const m = transformFor(instance, world, pose.root), src = instance.mesh, mesh = { positions: [], normals: [], colors: [...src.colors], indices: [...src.indices] };
+        for (let i = 0; i < src.positions.length; i += 3) {
+            const p = applyPoint(m, [
+                requireValue(src.positions[i]),
+                requireValue(src.positions[i + 1]),
+                requireValue(src.positions[i + 2]),
+            ]), n = applyVector(m, [
+                requireValue(src.normals[i]),
+                requireValue(src.normals[i + 1]),
+                requireValue(src.normals[i + 2]),
+            ]);
+            mesh.positions.push(quantize(p[0]), quantize(p[1]), quantize(p[2]));
+            mesh.normals.push(quantize(n[0]), quantize(n[1]), quantize(n[2]));
+        }
+        if (src.joints)
+            mesh.joints = [...src.joints];
+        return {
+            ...instance,
+            bounds: meshBounds(mesh),
+            anchors: Object.fromEntries(Object.entries(instance.anchors).map(([k, v]) => [k, applyPoint(m, v).map(quantize)])),
+            mesh,
+        };
+    });
+    const layers = Object.create(null), all = emptyMesh();
+    for (const instance of instances) {
+        if (!has(layers, instance.material))
+            layers[instance.material] = emptyMesh();
+        appendMesh(requireValue(layers[instance.material]), instance.mesh);
+        appendMesh(all, instance.mesh);
+    }
+    return {
+        ...asset,
+        layers,
+        instances,
+        bounds: meshBounds(all),
+        triangles: all.indices.length / 3,
+        ...(asset.alternates ? { alternates: [] } : {}),
+        pose: { clip: pose.clip, phase: pose.phase },
+    };
+}
+/**
+ * Place a character clip that uses anchor grounding on a furniture anchor and measure floor clearance.
+ * Both assets share the frame convention (front is −Z), so no rotation is involved.
+ */
+export function seatOn(character, clip, furniture, seat) {
+    prepare(character);
+    const diagnostics = [];
+    if (clip.grounding.type !== "anchor")
+        throw new AssetCompileError([
+            {
+                code: "SEAT_REQUIRES_ANCHOR_GROUNDING",
+                path: "/grounding",
+                message: "Seated clips use anchor grounding so a character anchor can meet the seat anchor.",
+            },
+        ]);
+    const instance = furniture.instances.find((i) => i.id === seat.part);
+    if (!instance || !has(instance.anchors, seat.anchor))
+        throw new AssetCompileError([
+            {
+                code: instance ? "UNKNOWN_ANCHOR" : "UNKNOWN_REFERENCE",
+                path: instance ? "/anchor" : "/part",
+                message: "Choose a furniture part instance and one of its anchors.",
+                targetPart: seat.part,
+                expected: instance ? Object.keys(instance.anchors).sort() : furniture.instances.map((i) => i.id),
+            },
+        ]);
+    const offset = requireValue(instance.anchors[seat.anchor]).map(quantize), floor = furniture.bounds.min[1], tolerance = CONTACT_TOLERANCE * (character.bounds.max[1] - character.bounds.min[1]);
+    let min = Infinity, max = -Infinity;
+    for (let k = 0; k < VERIFICATION_SAMPLES; k++) {
+        const pose = samplePose(character, clip, { phase: k / VERIFICATION_SAMPLES }), world = new Map(Object.entries(pose.transforms));
+        let y = Infinity;
+        for (const i of character.instances)
+            y = Math.min(y, lowest(i, transformFor(i, world, pose.root)));
+        const clearance = y + offset[1] - floor;
+        min = Math.min(min, clearance);
+        max = Math.max(max, clearance);
+    }
+    if (min > tolerance)
+        diagnostics.push({
+            code: "SEAT_FLOOR_GAP",
+            path: "",
+            message: `The seated character's lowest point stays ${round(min, 3)} ${character.units} above the floor. Lower the seat or lengthen the legs.`,
+            received: round(min, 4),
+            expected: [String(round(tolerance, 4))],
+        });
+    if (min < -tolerance)
+        diagnostics.push({
+            code: "SEAT_FLOOR_PENETRATION",
+            path: "",
+            message: `The seated character reaches ${round(min, 3)} ${character.units} below the floor. Raise the seat or shorten the legs.`,
+            received: round(min, 4),
+            expected: [String(round(-tolerance, 4))],
+        });
+    return { offset, clearance: { min: round(min, 6), max: round(max, 6) }, diagnostics };
+}
+/** Combine visible posed geometry without constructing posed instances, anchors or bounds. */
+export function posedMesh(asset, pose, tint) {
+    prepare(asset);
+    if (tint !== undefined && !/^#[a-fA-F0-9]{6}$/.test(tint))
+        throw new RangeError("Tint must be #rrggbb");
+    const color = tint ? [1, 3, 5].map((i) => linear(parseInt(tint.slice(i, i + 2), 16))) : [1, 1, 1], world = new Map(Object.entries(pose.transforms)), transforms = new Map(), layers = Object.create(null);
+    let coordinates = 0, indices = 0, joints = false;
+    for (const instance of visibleIn(asset, pose.states ?? {})) {
+        if (!instance.mesh.positions.length)
+            throw new RangeError("Bounds require nonempty geometry");
+        (layers[instance.material] ??= []).push(instance);
+        coordinates += instance.mesh.positions.length;
+        indices += instance.mesh.indices.length;
+        joints ||= !!instance.mesh.joints;
+    }
+    if (!coordinates)
+        throw new RangeError("Bounds require nonempty geometry");
+    // Each call owns its output; scratch transforms are shared only within this pose.
+    const result = {
+        positions: new Array(coordinates),
+        normals: new Array(coordinates),
+        colors: new Array(coordinates),
+        indices: new Array(indices),
+    };
+    if (joints)
+        result.joints = new Array(coordinates / 3).fill(-1);
+    let at = 0, index = 0;
+    for (const [material, instances] of Object.entries(layers)) {
+        const first = at / 3, tinted = requireValue(asset.materials[material]).tintable && tint;
+        for (const instance of instances) {
+            let m = transforms.get(instance.joint);
+            if (!m) {
+                m = transformFor(instance, world, pose.root);
+                transforms.set(instance.joint, m);
+            }
+            const src = instance.mesh, layerFirst = at / 3 - first;
+            for (let i = 0; i < src.positions.length; i += 3) {
+                const x = requireValue(src.positions[i]), y = requireValue(src.positions[i + 1]), z = requireValue(src.positions[i + 2]), nx = requireValue(src.normals[i]), ny = requireValue(src.normals[i + 1]), nz = requireValue(src.normals[i + 2]);
+                // Preserve the two zero-offset appends used by poseAsset then meshForAsset.
+                result.positions[at + i] =
+                    quantize(requireValue(m[0]) * x + requireValue(m[1]) * y + requireValue(m[2]) * z + requireValue(m[3])) +
+                        0 +
+                        0;
+                result.positions[at + i + 1] =
+                    quantize(requireValue(m[4]) * x + requireValue(m[5]) * y + requireValue(m[6]) * z + requireValue(m[7])) +
+                        0 +
+                        0;
+                result.positions[at + i + 2] =
+                    quantize(requireValue(m[8]) * x + requireValue(m[9]) * y + requireValue(m[10]) * z + requireValue(m[11])) +
+                        0 +
+                        0;
+                result.normals[at + i] = quantize(requireValue(m[0]) * nx + requireValue(m[1]) * ny + requireValue(m[2]) * nz);
+                result.normals[at + i + 1] = quantize(requireValue(m[4]) * nx + requireValue(m[5]) * ny + requireValue(m[6]) * nz);
+                result.normals[at + i + 2] = quantize(requireValue(m[8]) * nx + requireValue(m[9]) * ny + requireValue(m[10]) * nz);
+                for (let c = 0; c < 3; c++)
+                    result.colors[at + i + c] = tinted
+                        ? requireValue(src.colors[i + c]) * requireValue(color[c])
+                        : requireValue(src.colors[i + c]);
+            }
+            for (const i of src.indices)
+                result.indices[index++] = i + layerFirst + first;
+            if (src.joints)
+                for (let i = 0; i < src.joints.length; i++)
+                    requireValue(result.joints)[at / 3 + i] = requireValue(src.joints[i]);
+            at += src.positions.length;
+        }
+    }
+    return result;
+}