Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(motion): score a clip against a rig and document the package
nirholasf9200d166911
diff --git a/packages/motion/README.md b/packages/motion/README.mdnew file mode 100644index 000000000..c34762db9--- /dev/null+++ b/packages/motion/README.md@@ -0,0 +1,113 @@+# @three-ws/motion++**Text and structure into full-body 3D animation.** A Motion Score in, a+three.js `AnimationClip` out: forward and inverse kinematics, balance, ground+contact, and secondary motion, in plain JavaScript with no model, no GPU, and no+dependencies.++The same score always compiles to the same clip, byte for byte, which is what+makes a motion cacheable, diffable, and safe to regenerate.++## Install++```bash+npm install @three-ws/motion+```++## Two entry points cover almost every use++```js+import { motionFromText } from '@three-ws/motion';++const { clip, score, matched } = motionFromText('wave hello twice, excitedly');+// clip -> an AnimationClip document, ready for THREE.AnimationClip.parse()+// score -> the Motion Score that produced it, so you can edit and recompile+```++```js+import { compileScore } from '@three-ws/motion';++const { clip, warnings } = compileScore(myScore, {+ idle: true, // layer breathing and micro-sway on top (default)+ rootMotion: true, // emit the hip translation track (default)+ fingers: true, // emit the finger bones (default)+});+```++`motionFromText` runs the **model-free lane**: it matches the prompt against a+known action vocabulary. When it does not recognise an action it throws, and the+message lists what it *does* know, so a caller can escalate to a model or tell+the user something useful instead of silently producing a T-pose.++```js+import { motionCapabilities } from '@three-ws/motion';+motionCapabilities(); // what this lane can do, for a capability check or a UI+```++## CLI++```bash+three-ws-motion "wave hello twice, excitedly" -o wave.json+three-ws-motion --score beats.json --loop --no-root -o clip.json+three-ws-motion --schema # the Motion Score JSON Schema+three-ws-motion --actions # every action this lane knows+```++| Option | Meaning |+| --- | --- |+| `-o, --out <file>` | Write the clip here (default: stdout) |+| `--score <file>` | Compile a Motion Score instead of a prompt |+| `--name <name>` | Clip name (default: the prompt, or the score's name) |+| `--loop` | Close the last beat back into the first |+| `--effort <name>` | Override the performance quality for every beat |+| `--no-idle` | Leave out the breathing and micro-sway layer |+| `--no-root` | Leave out the hip translation track, for a clip that plays in place |+| `--no-fingers` | Leave out the finger bones |+| `--score-out <file>` | Also write the Motion Score that produced the clip |++## The Motion Score++A score is a list of beats: what the body is doing, where it is looking, what the+hands are shaped like, and how the performance is played. It is plain JSON with a+published schema (`scoreSchema`), so it can be authored by a person, an editor, or+a model, and validated before anything is compiled.++```js+import { validateScore, normalizeScore, describeScore } from '@three-ws/motion';++const { valid, errors } = validateScore(score);+const normalized = normalizeScore(score); // defaults filled, ranges clamped+describeScore(normalized); // a human-readable summary+```++The vocabulary is exported as data, not hidden behind the compiler:+`POSTURES`, `STANCES`, `HAND_SHAPES`, `ELBOW_POLES`, `ACTION_NAMES`, and their+`*_NAMES` lists. Build a picker straight from them.++## The solver, if you need it directly++An editor, a different score format, or a custom front end is a reasonable thing+to build on this, and should not have to fork it. The rig layer is exported:++| Export | What it does |+| --- | --- |+| `solveArm`, `solveLeg`, `solveSpine`, `solveGaze`, `solveTurn` | The IK chains |+| `shapeHand` | Finger posing from a named hand shape |+| `balanceError`, `balanceOffset`, `centreOfMass`, `supportCentre` | Keeping weight over the feet |+| `Pose`, `restPose`, `blendPose` | The pose representation and blending |+| `ANCHORS`, `anchorPoint`, `restAnchor`, `bodyDirection` | Named points on the body and the directions between them |+| `solveBeat`, `solveScorePoses`, `expressionWeights` | Score to poses |+| `buildClip`, `restClip`, `stableUuid` | Poses to an AnimationClip document |++`MOTION_BONES` is the canonical bone set the clips target; `LIMITS` and+`MOTION_SCORE_VERSION` pin the score contract.++## Related++- [`@three-ws/render`](../render): rasterize the resulting clip to PNG or GIF+ with no GPU, to see what a score actually looks like.+- [`STRUCTURE.md`](../../STRUCTURE.md): where every three.ws surface lives.++## License++Apache-2.0diff --git a/packages/motion/src/compose.js b/packages/motion/src/compose.jsindex d03df4c5e..be1ffc927 100644--- a/packages/motion/src/compose.js+++ b/packages/motion/src/compose.js@@ -313,7 +313,10 @@ export function composeScore(prompt, opts = {}) {const text = String(prompt ?? '').toLowerCase().trim();if (!text) return { score: null, matched: null, reason: 'empty prompt' };- const match = SYNONYMS.find(([phrase]) => text.includes(phrase));+ // Phrases first, longest-intent first, then the bare action names, so+ // "shake head" beats "shake" and "shake" still resolves on its own.+ const match = SYNONYMS.find(([phrase]) => text.includes(phrase))+ ?? ACTION_NAMES.map((a) => [a.replace(/_/g, ' '), a]).find(([phrase]) => text.includes(phrase));if (!match) {return {score: null,@@ -339,7 +342,7 @@ export function composeScore(prompt, opts = {}) {const repeats = readRepeats(text);- const beats = ACTIONS[action]({ side, direction, effort, repeats });+ const beats = ACTIONS[action]({ side, direction, effort, repeats }).map((beat) => paced(beat, effort));return {score: {version: 1,@@ -354,6 +357,22 @@ export function composeScore(prompt, opts = {}) {};}+/**+ * Scale a beat's authored timing by how sudden the effort is. The shapes an+ * action makes are the same whether it is performed sharply or wearily; what+ * changes is how long the body takes to get between them, and an action that+ * ignored that would read as the same motion at the same speed every time.+ */+function paced(beat, effort) {+ const factor = 1.45 - 0.9 * (EFFORTS[effort] ?? EFFORTS.neutral).time;+ const out = { ...beat };+ if (typeof out.in === 'number') out.in = round(out.in * factor);+ if (typeof out.hold === 'number') out.hold = round(out.hold * factor);+ return out;+}++const round = (n) => Math.round(n * 1000) / 1000;+function readRepeats(text) {const digits = text.match(/\b(\d{1,2})\s*(times|x)\b/);if (digits) return Math.min(6, Math.max(1, Number(digits[1])));diff --git a/packages/motion/src/score.js b/packages/motion/src/score.jsindex c5d09e43c..11a653f9c 100644--- a/packages/motion/src/score.js+++ b/packages/motion/src/score.js@@ -33,6 +33,11 @@ export const MOTION_SCORE_VERSION = 1;/** Hard bounds, so a malformed score cannot ask for an hour-long clip. */export const LIMITS = Object.freeze({maxBeats: 64,+ /**+ * A clip shorter than this has nowhere to put the idle layer and nothing for+ * a mixer to interpolate, so a score of one held beat is extended to it.+ */+ minDuration: 0.8,maxDuration: 60,maxBeatSeconds: 12,minBeatSeconds: 0.02,@@ -73,7 +78,7 @@ export function normalizeScore(input) {throw new ScoreError('score.version', `unsupported version ${version}, this build reads ${MOTION_SCORE_VERSION}`);}const name = typeof input.name === 'string' && input.name.trim()- ? input.name.trim().slice(0, LIMITS.maxName ?? LIMITS.maxNameLength)+ ? input.name.trim().slice(0, LIMITS.maxNameLength): 'motion';const beatsIn = Array.isArray(input.beats) ? input.beats : null;if (!beatsIn || !beatsIn.length) throw new ScoreError('score.beats', 'must be a non-empty array');@@ -115,6 +120,12 @@ export function normalizeScore(input) {};});+ // A single beat, or a last beat with no hold, would compile to a clip with no+ // length: hold the final shape long enough to be worth playing.+ const last = beats[beats.length - 1];+ const played = last.at + last.hold;+ if (played < LIMITS.minDuration) last.hold += LIMITS.minDuration - played;+return {version: MOTION_SCORE_VERSION,name,@@ -122,7 +133,7 @@ export function normalizeScore(input) {loop: input.loop === true,effort: defaultEffort,beats,- duration: beats[beats.length - 1].at + beats[beats.length - 1].hold,+ duration: last.at + last.hold,};}diff --git a/packages/motion/test/motion.test.js b/packages/motion/test/motion.test.jsnew file mode 100644index 000000000..b1a16c9e6--- /dev/null+++ b/packages/motion/test/motion.test.js@@ -0,0 +1,343 @@+// The score format, the compiler, and the model-free lane.+//+// The contract these protect: a score either compiles to a clip a mixer can+// play, or it is rejected with the path that was wrong. There is no third+// outcome where it half-compiles, because a half-compiled motion is a body that+// half-moves and nothing downstream can tell that from a bad prompt.++import { describe, it } from 'node:test';+import assert from 'node:assert/strict';++import {+ ACTION_NAMES,+ ANCHOR_NAMES,+ EFFORT_NAMES,+ EXPRESSION_NAMES,+ GAZE_NAMES,+ HAND_SHAPE_NAMES,+ LIMITS,+ MOTION_BONES,+ MOTION_SCORE_VERSION,+ POSTURE_NAMES,+ STANCE_NAMES,+ compileScore,+ composeScore,+ describeScore,+ motionCapabilities,+ motionFromText,+ normalizeScore,+ restClip,+ scoreSchema,+ stableUuid,+ validateScore,+} from '../src/index.js';++const STAND = { beats: [{ posture: 'stand' }] };++describe('score validation', () => {+ it('fills in everything the solver would otherwise have to guess', () => {+ const score = normalizeScore({ name: 'test', beats: [{ posture: 'crouch' }, { posture: 'stand' }] });+ assert.equal(score.version, MOTION_SCORE_VERSION);+ assert.equal(score.seed, 'test');+ assert.equal(score.loop, false);+ for (const beat of score.beats) {+ assert.equal(typeof beat.at, 'number');+ assert.equal(typeof beat.in, 'number');+ assert.equal(typeof beat.hold, 'number');+ assert.ok(beat.ease, 'an ease was chosen');+ assert.ok(beat.effort && typeof beat.effort.time === 'number', 'an effort was resolved');+ }+ assert.ok(score.beats[1].at > score.beats[0].at, 'the clock advanced');+ assert.equal(score.duration, score.beats[1].at + score.beats[1].hold);+ });++ it('runs the clock forward monotonically even when a beat asks to go back', () => {+ const score = normalizeScore({ beats: [{ at: 2, posture: 'stand' }, { at: 0.5, posture: 'crouch' }] });+ assert.ok(score.beats[1].at >= score.beats[0].at, 'time did not run backwards');+ });++ it('lets effort pick the timing and the easing when a beat says neither', () => {+ const sudden = normalizeScore({ effort: 'sharp', beats: [{ posture: 'stand' }, { posture: 'ready' }] });+ const slow = normalizeScore({ effort: 'sustained', beats: [{ posture: 'stand' }, { posture: 'ready' }] });+ assert.ok(sudden.beats[1].in < slow.beats[1].in, 'a sharp beat travels faster than a sustained one');+ assert.equal(slow.beats[1].ease, 'settle');+ assert.ok(['snap', 'overshoot'].includes(sudden.beats[1].ease));+ });++ it('accepts every word in its own vocabulary', () => {+ for (const posture of POSTURE_NAMES) normalizeScore({ beats: [{ posture }] });+ for (const stance of STANCE_NAMES) normalizeScore({ beats: [{ legs: { stance } }] });+ for (const gaze of GAZE_NAMES) normalizeScore({ beats: [{ gaze }] });+ for (const face of EXPRESSION_NAMES) normalizeScore({ beats: [{ face }] });+ for (const effort of EFFORT_NAMES) normalizeScore({ beats: [{ effort }] });+ for (const hand of HAND_SHAPE_NAMES) normalizeScore({ beats: [{ arms: { right: { at: 'front', hand } } }] });+ for (const at of ANCHOR_NAMES) normalizeScore({ beats: [{ arms: { right: { at } } }] });+ });++ it('names the exact path that was wrong', () => {+ const cases = [+ [{ beats: [] }, 'score.beats'],+ [{ beats: [{ posture: 'levitate' }] }, 'score.beats[0].posture'],+ [{ beats: [{ arms: { right: { at: 'elbow' } } }] }, 'score.beats[0].arms.right.at'],+ [{ beats: [{ legs: { stance: 'moonwalk' } }] }, 'score.beats[0].legs.stance'],+ [{ beats: [{ gaze: 'sideways' }] }, 'score.beats[0].gaze'],+ [{ beats: [{ ease: 'bouncy' }] }, 'score.beats[0].ease'],+ [{ beats: [{ effort: 'sassy' }] }, 'score.beats[0].effort'],+ [{ beats: [{ face: 'smug' }] }, 'score.beats[0].face'],+ [{ beats: [{ legs: { left: { plant: 'hover' } } }] }, 'score.beats[0].legs.left.plant'],+ [{ version: 99, beats: [{}] }, 'score.version'],+ ];+ for (const [input, path] of cases) {+ const result = validateScore(input);+ assert.equal(result.ok, false, `${JSON.stringify(input)} should be rejected`);+ assert.equal(result.error.path, path);+ }+ });++ it('clamps a value that is merely out of range rather than rejecting it', () => {+ const score = normalizeScore({+ beats: [{ root: { height: 9, turn: 900 }, torso: { lean: -400 }, arms: { right: { at: 'front', out: 40 } } }],+ });+ const beat = score.beats[0];+ assert.ok(beat.root.height <= 1.15);+ assert.equal(beat.root.turn, LIMITS.maxAngle);+ assert.equal(beat.torso.lean, -LIMITS.maxAngle);+ assert.equal(beat.arms.right.out, LIMITS.maxOffset);+ });++ it('refuses a score longer than the limit rather than emitting an hour of keys', () => {+ const beats = Array.from({ length: 40 }, () => ({ posture: 'stand', hold: 5 }));+ assert.equal(validateScore({ beats }).ok, false);+ assert.equal(validateScore({ beats: Array.from({ length: LIMITS.maxBeats + 1 }, () => ({})) }).ok, false);+ });++ it('takes a shorthand anywhere an object is allowed', () => {+ const score = normalizeScore({+ beats: [{ arms: { right: 'chin' }, legs: 'wide', gaze: 'up', face: 'smile' }],+ });+ assert.deepEqual(score.beats[0].arms.right, { at: 'chin' });+ assert.equal(score.beats[0].legs.stance, 'wide');+ assert.deepEqual(score.beats[0].gaze, { preset: 'up' });+ assert.deepEqual(score.beats[0].face, { smile: 1 });+ });++ it('describes itself in one readable line', () => {+ const score = normalizeScore({ name: 'greeting', beats: [{ label: 'raise' }, { label: 'wave' }] });+ const line = describeScore(score);+ assert.match(line, /greeting/);+ assert.match(line, /2 beats/);+ assert.match(line, /raise > wave/);+ });+});++describe('the schema offered to a model', () => {+ it('offers exactly the words the solver accepts', () => {+ const schema = scoreSchema();+ const beat = schema.properties.beats.items.properties;+ assert.deepEqual(beat.posture.enum, [...POSTURE_NAMES]);+ assert.deepEqual(beat.gaze.enum, [...GAZE_NAMES]);+ assert.deepEqual(beat.face.enum, [...EXPRESSION_NAMES]);+ assert.deepEqual(beat.legs.properties.stance.enum, [...STANCE_NAMES]);+ assert.deepEqual(beat.arms.properties.right.properties.at.enum, [...ANCHOR_NAMES]);+ assert.deepEqual(beat.arms.properties.right.properties.hand.enum, [...HAND_SHAPE_NAMES]);+ });++ it('closes every object, so a hallucinated field is a validation error and not silence', () => {+ const schema = scoreSchema();+ const closed = (node) => {+ if (!node || typeof node !== 'object') return;+ if (node.type === 'object') assert.equal(node.additionalProperties, false);+ for (const child of Object.values(node.properties ?? {})) closed(child);+ if (node.items) closed(node.items);+ };+ closed(schema);+ });++ it('publishes its capabilities in one object', () => {+ const caps = motionCapabilities();+ assert.equal(caps.version, MOTION_SCORE_VERSION);+ assert.ok(caps.schema.properties.beats);+ assert.deepEqual(caps.actions, [...ACTION_NAMES]);+ });+});++describe('compiling to a clip', () => {+ it('emits a document a three.js mixer can parse', () => {+ const { clip } = compileScore({ name: 'stand', beats: [{ posture: 'stand' }, { posture: 'crouch' }] });+ assert.equal(typeof clip.name, 'string');+ assert.equal(clip.blendMode, 2500);+ assert.match(clip.uuid, /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/);+ assert.ok(clip.duration > 0);+ for (const track of clip.tracks) {+ const stride = track.type === 'quaternion' ? 4 : track.type === 'vector' ? 3 : 1;+ assert.equal(track.values.length, track.times.length * stride, `${track.name} stride`);+ assert.ok(track.times.length >= 2, `${track.name} has keys`);+ assert.ok(track.values.every(Number.isFinite), `${track.name} is finite`);+ for (let i = 1; i < track.times.length; i++) {+ assert.ok(track.times[i] > track.times[i - 1], `${track.name} times increase`);+ }+ }+ });++ it('normalizes every quaternion it emits', () => {+ const { clip } = compileScore({ beats: [{ posture: 'squat', arms: { right: { at: 'overhead' } } }] });+ for (const track of clip.tracks) {+ if (track.type !== 'quaternion') continue;+ for (let i = 0; i < track.values.length; i += 4) {+ const len = Math.hypot(track.values[i], track.values[i + 1], track.values[i + 2], track.values[i + 3]);+ assert.ok(Math.abs(len - 1) < 1e-6, `${track.name} key ${i / 4} has length ${len}`);+ }+ }+ });++ it('always drives the full body, so two clips can be crossfaded', () => {+ const { clip } = compileScore({ beats: [{ gaze: 'up' }] });+ const driven = new Set(clip.tracks.filter((t) => t.type === 'quaternion').map((t) => t.name.split('.')[0]));+ for (const bone of MOTION_BONES) assert.ok(driven.has(bone), `${bone} is driven`);+ });++ it('emits root motion only when the body actually travels', () => {+ const still = compileScore({ beats: [{ posture: 'stand' }, { gaze: 'left' }] });+ assert.ok(!still.clip.tracks.some((t) => t.name === 'Hips.position'), 'a gesture in place has no root track');++ const walking = compileScore({ beats: [{ posture: 'stand' }, { root: { forward: 0.8 } }] });+ const track = walking.clip.tracks.find((t) => t.name === 'Hips.position');+ assert.ok(track, 'travel emits a root track');+ const startZ = track.values[2];+ const endZ = track.values[track.values.length - 1];+ assert.ok(Math.abs(endZ - startZ) > 0.5, `the body moved: ${startZ} to ${endZ}`);+ });++ it('leaves the root track out when asked for a clip that plays in place', () => {+ const { clip } = compileScore({ beats: [{ posture: 'stand' }, { root: { forward: 0.8 } }] }, { rootMotion: false });+ assert.ok(!clip.tracks.some((t) => t.name === 'Hips.position'));+ });++ it('drives an expression to zero after the beat that used it', () => {+ const { clip } = compileScore({+ beats: [{ face: 'neutral' }, { face: 'grin', hold: 0.3 }, { face: 'neutral', hold: 0.3 }],+ });+ const smile = clip.tracks.find((t) => t.name.includes('mouthSmileLeft'));+ assert.ok(smile, 'the smile lane exists');+ assert.ok(Math.max(...smile.values) > 0.5, 'it opened');+ assert.ok(smile.values[smile.values.length - 1] < 0.05, 'and it closed again');+ });++ it('closes a looping score back into its first beat', () => {+ const open = compileScore({ beats: [{ posture: 'stand' }, { posture: 'ready', hold: 0.2 }] });+ const looped = compileScore({ loop: true, beats: [{ posture: 'stand' }, { posture: 'ready', hold: 0.2 }] });+ assert.ok(looped.clip.duration > open.clip.duration, 'the return trip is in the clip');+ const track = (clip, name) => clip.tracks.find((t) => t.name === name);+ const first = track(looped.clip, 'LeftUpLeg.quaternion');+ const startKey = first.values.slice(0, 4);+ const endKey = first.values.slice(-4);+ for (let i = 0; i < 4; i++) {+ assert.ok(Math.abs(startKey[i] - endKey[i]) < 0.02, 'the loop lands back where it started');+ }+ });++ it('is deterministic: the same score is the same bytes, forever', () => {+ const score = { name: 'nod', beats: [{ gaze: 'forward' }, { gaze: 'down', hold: 0.2 }, { gaze: 'forward' }] };+ assert.equal(JSON.stringify(compileScore(score).clip), JSON.stringify(compileScore(score).clip));+ assert.notEqual(+ compileScore({ ...score, seed: 'a' }).clip.uuid,+ compileScore({ ...score, seed: 'b' }).clip.uuid,+ );+ assert.equal(stableUuid('x'), stableUuid('x'));+ assert.notEqual(stableUuid('x'), stableUuid('y'));+ });++ it('breathes by default and holds perfectly still when told not to', () => {+ const alive = compileScore(STAND, { idle: true }).clip;+ const still = compileScore(STAND, { idle: false }).clip;+ const spread = (clip) => {+ const track = clip.tracks.find((t) => t.name === 'Spine1.quaternion');+ const xs = track.values.filter((_, i) => i % 4 === 0);+ return Math.max(...xs) - Math.min(...xs);+ };+ assert.ok(spread(alive) > 0, 'a standing body is never perfectly still');+ assert.equal(spread(still), 0, 'unless it is asked to be');+ });++ it('gives a rest clip for a body doing nothing', () => {+ const clip = restClip('rest');+ assert.equal(clip.name, 'rest');+ assert.ok(clip.tracks.length > 0);+ });+});++describe('the model-free lane', () => {+ it('recognizes every action it advertises, and says so when it does not', () => {+ for (const action of ACTION_NAMES) {+ const { matched } = composeScore(action.replace('_', ' '));+ assert.ok(matched, `"${action}" is recognized`);+ }+ const miss = composeScore('perform an interpretive dance about quarterly earnings');+ assert.equal(miss.score, null);+ assert.match(miss.reason, /no known action/);+ assert.match(miss.reason, /wave/, 'the miss says what it does know');+ });++ it('compiles every action it knows into a playable clip with nothing unreachable', () => {+ for (const action of ACTION_NAMES) {+ const result = motionFromText(action.replace('_', ' '));+ assert.ok(result.clip.duration > 0.4, `${action} has a duration`);+ assert.ok(result.clip.tracks.length > 10, `${action} drives a body`);+ assert.deepEqual(result.warnings, [], `${action} solves without warnings`);+ }+ });++ it('reads manner, side, direction, and repetition out of the prompt', () => {+ assert.ok(+ motionFromText('wave quickly').clip.duration < motionFromText('wave slowly').clip.duration,+ 'a quick wave is shorter than a slow one',+ );+ assert.ok(+ motionFromText('clap 4 times').clip.duration > motionFromText('clap once').clip.duration,+ 'more claps take longer',+ );+ const left = composeScore('wave with your left hand').score;+ assert.ok(left.beats.some((b) => b.arms?.left?.at === 'overhead'), 'the left hand did the waving');+ const right = composeScore('wave').score;+ assert.ok(right.beats.some((b) => b.arms?.right?.at === 'overhead'), 'the right hand is the default');+ });++ it('throws something a caller can act on when it does not know the words', () => {+ assert.throws(+ () => motionFromText('reticulate splines'),+ (err) => err.code === 'unrecognized_motion' && /reticulate/.test(err.message),+ );+ });++ it('is stable: the same prompt is the same clip', () => {+ const a = motionFromText('sit down heavily');+ const b = motionFromText('sit down heavily');+ assert.equal(JSON.stringify(a.clip), JSON.stringify(b.clip));+ });+});++describe('the body it produces', () => {+ it('keeps the feet on the floor through a crouch', () => {+ const { clip } = compileScore({+ beats: [{ posture: 'stand' }, { posture: 'squat', hold: 0.3 }, { posture: 'stand' }],+ }, { idle: false });+ const root = clip.tracks.find((t) => t.name === 'Hips.position');+ const heights = root.values.filter((_, i) => i % 3 === 1);+ assert.ok(Math.min(...heights) < Math.max(...heights) - 0.2, 'the hips travelled down and back up');+ assert.ok(Math.min(...heights) > 0.3, 'and never went through the floor');+ });++ it('does not fall over: a standing beat keeps its weight over its feet', async () => {+ const { solveBeat } = await import('../src/solve.js');+ const { balanceError } = await import('../src/rig/ik.js');+ for (const posture of POSTURE_NAMES) {+ const score = normalizeScore({ beats: [{ posture }] });+ const { pose } = solveBeat(score.beats[0]);+ const error = balanceError(pose);+ // Seated and kneeling shapes are held up by something other than the+ // feet, so they are allowed to sit outside their own footprint.+ const supported = ['sit', 'slouch', 'kneel'].includes(posture);+ assert.ok(supported || error < 0.05, `${posture} balance error ${error.toFixed(3)}`);+ }+ });+});