@pose_flow/babylon 0.1.0 → 0.3.0

package/dist/babylon-inertialization.js

@@ -0,0 +1,88 @@
+import { Quaternion, Vector3 } from '@babylonjs/core';
+import { decayInertialOffset } from './core/inertialization.js';
+export function captureLocal(node) {
+    return { position: node.position.clone(), rotation: node.rotationQuaternion?.clone() ?? Quaternion.FromEulerVector(node.rotation), scaling: node.scaling.clone() };
+}
+export function rotationVector(q) {
+    q = q.clone().normalize();
+    if (q.w < 0)
+        q.scaleInPlace(-1);
+    const length = Math.hypot(q.x, q.y, q.z);
+    return length < 1e-8 ? new Vector3(q.x * 2, q.y * 2, q.z * 2) : new Vector3(q.x, q.y, q.z).scale(2 * Math.atan2(length, q.w) / length);
+}
+function rotationFromVector(v) {
+    const angle = v.length();
+    return angle < 1e-8 ? new Quaternion(v.x / 2, v.y / 2, v.z / 2, 1).normalize() : Quaternion.RotationAxis(v.scale(1 / angle), angle);
+}
+export function poseVelocity(before, after, dt) {
+    return { position: after.position.subtract(before.position).scale(1 / dt), scaling: after.scaling.subtract(before.scaling).scale(1 / dt),
+        // rotation stores a tangent vector in XYZ; W is unused for velocities.
+        rotation: Quaternion.FromArray([...rotationVector(after.rotation.multiply(Quaternion.Inverse(before.rotation))).scale(1 / dt).asArray(), 0]) };
+}
+const zeroVelocity = () => ({ position: Vector3.Zero(), scaling: Vector3.Zero(), rotation: new Quaternion(0, 0, 0, 0) });
+/** Owns local presentation residuals only. Evaluation happens before world matrices/rendering. */
+export class BabylonInertializer {
+    scene;
+    halfLife;
+    observer;
+    last = new Map();
+    velocity = new Map();
+    residuals = new Map();
+    target = new Map();
+    dt = 0;
+    elapsed = 0;
+    revision = 0;
+    renderedRevision = -1;
+    constructor(scene, halfLife) {
+        this.scene = scene;
+        this.halfLife = halfLife;
+        this.observer = scene.onAfterAnimationsObservable.add(() => this.render());
+    }
+    update(target, targetVelocity, dt, switched) {
+        if (switched) {
+            this.residuals.clear();
+            this.elapsed = 0;
+            for (const [node, pose] of target) {
+                const before = this.last.get(node);
+                if (!before)
+                    continue;
+                const v = this.velocity.get(node) ?? zeroVelocity(), incoming = targetVelocity.get(node) ?? zeroVelocity();
+                const angular = rotationVector(before.rotation.multiply(Quaternion.Inverse(pose.rotation)));
+                this.residuals.set(node, { offset: { position: before.position.subtract(pose.position), scaling: before.scaling.subtract(pose.scaling), rotation: new Quaternion(angular.x, angular.y, angular.z, 0) },
+                    velocity: { position: v.position.subtract(incoming.position), scaling: v.scaling.subtract(incoming.scaling), rotation: v.rotation.subtract(incoming.rotation) } });
+            }
+        }
+        else
+            this.elapsed += dt;
+        this.target = target;
+        this.dt = dt;
+        this.revision++;
+    }
+    render() {
+        for (const [node, target] of this.target) {
+            const residual = this.residuals.get(node);
+            const decay = (offset, velocity) => new Vector3(...offset.asArray().map((v, i) => decayInertialOffset(v, velocity.asArray()[i], this.elapsed, this.halfLife)));
+            node.position.copyFrom(target.position);
+            node.scaling.copyFrom(target.scaling);
+            node.rotationQuaternion ??= Quaternion.Identity();
+            node.rotationQuaternion.copyFrom(target.rotation);
+            if (residual) {
+                node.position.addInPlace(decay(residual.offset.position, residual.velocity.position));
+                node.scaling.addInPlace(decay(residual.offset.scaling, residual.velocity.scaling));
+                const r = residual.offset.rotation, v = residual.velocity.rotation;
+                node.rotationQuaternion.copyFrom(rotationFromVector(decay(new Vector3(r.x, r.y, r.z), new Vector3(v.x, v.y, v.z))).multiply(target.rotation).normalize());
+            }
+            if (this.renderedRevision !== this.revision) {
+                const pose = captureLocal(node), previous = this.last.get(node);
+                if (previous && this.dt > 0)
+                    this.velocity.set(node, poseVelocity(previous, pose, this.dt));
+                this.last.set(node, pose);
+            }
+        }
+        this.renderedRevision = this.revision;
+        if (this.elapsed > this.halfLife * 40)
+            this.residuals.clear();
+    }
+    reset() { this.last.clear(); this.velocity.clear(); this.residuals.clear(); this.target.clear(); this.elapsed = 0; this.renderedRevision = -1; }
+    dispose() { this.reset(); this.scene.onAfterAnimationsObservable.remove(this.observer); }
+}

package/dist/babylon.d.ts

@@ -1,5 +1,13 @@
 import { AnimationGroup, TransformNode, type Scene } from '@babylonjs/core';
 import type { Clip, Playback, Pose } from './index.js';
+import { type PoseSchema, type SchemaPose } from './core/schema.js';
+export interface BabylonPlayerOptions {
+    /** Exact MODEL node names. No descendant expansion or name mapping is implied. */
+    mask?: readonly string[];
+    transition?: 'crossfade' | 'inertialization';
+    /** Positive seconds. Applies only to inertialization; default 0.1. */
+    inertialHalfLife?: number;
+}
 /** Clone onto a target rig. Two playback slots allow crossfade between times of the same clip. */
 export declare class BabylonMotionPlayer {
     private scene;
@@ -11,18 +19,32 @@ export declare class BabylonMotionPlayer {
     private tracks;
     private active?;
     private disposed;
-    constructor(scene: Scene, clips: readonly Clip[], sources: ReadonlyMap<string, AnimationGroup>, nodes: ReadonlyMap<string, TransformNode>, fadeSeconds?: number, rootName?: string);
+    private strippedRoot?;
+    private rootRestRotation?;
+    private owned;
+    private rest;
+    private inertia?;
+    constructor(scene: Scene, clips: readonly Clip[], sources: ReadonlyMap<string, AnimationGroup>, nodes: ReadonlyMap<string, TransformNode>, fadeSeconds?: number, rootName?: string, options?: BabylonPlayerOptions);
     private create;
     update(state: Playback, dt: number): void;
+    private sampleLocal;
+    /** Clear presentation history after teleport/reconciliation; ownership stays until dispose. */
+    reset(): void;
     private clear;
     dispose(): void;
 }
-/** Sample AFTER scene animation evaluation. Measures visible feet, including crossfade. */
-export declare class BabylonPoseReader {
+/** Sample AFTER scene animation evaluation. Semantic roles are defined by the schema. */
+export declare class BabylonSchemaPoseReader {
     private root;
-    private left;
-    private right;
     private previous?;
+    private nodes;
+    constructor(root: TransformNode, bones: ReadonlyMap<string, TransformNode>, schema: PoseSchema);
+    reset(): void;
+    read(dt: number): SchemaPose;
+}
+/** Compatibility reader for the original two-foot preset. */
+export declare class BabylonPoseReader {
+    private reader;
     constructor(root: TransformNode, left: TransformNode, right: TransformNode);
     reset(): void;
     read(dt: number): Pose;

package/dist/babylon.js

@@ -1,4 +1,26 @@
-import { AnimationGroup, Matrix, Vector3 } from '@babylonjs/core';
+import { Animation, AnimationGroup, Matrix, Quaternion, Vector3 } from '@babylonjs/core';
+import { compileSchema, LOCOMOTION_SCHEMA } from './core/schema.js';
+import { parseRootOrientation } from './core/profile.js';
+import { BabylonInertializer, captureLocal, poseVelocity } from './babylon-inertialization.js';
+const nodeOwners = new WeakMap();
+/** Constant authoring orientation belongs to the pose; varying root heading belongs to gameplay. */
+function constantRootRotation(animation) {
+    const keys = animation.getKeys();
+    if (!keys.length || keys.some(k => k.inTangent !== undefined || k.outTangent !== undefined))
+        return undefined;
+    const rotation = (value) => animation.targetProperty === 'rotationQuaternion' && value instanceof Quaternion ? value.clone()
+        : animation.targetProperty === 'rotation' && value instanceof Vector3 ? Quaternion.FromEulerVector(value) : undefined;
+    const first = rotation(keys[0].value);
+    if (!first || !first.asArray().every(Number.isFinite) || first.length() < 1e-8)
+        return undefined;
+    first.normalize();
+    for (const key of keys) {
+        const q = rotation(key.value);
+        if (!q || !q.asArray().every(Number.isFinite) || q.length() < 1e-8 || Math.abs(Quaternion.Dot(first, q.normalize())) < 1 - 1e-8)
+            return undefined;
+    }
+    return first;
+}
 /** Clone onto a target rig. Two playback slots allow crossfade between times of the same clip. */
 export class BabylonMotionPlayer {
     scene;
@@ -10,7 +32,12 @@ export class BabylonMotionPlayer {
     tracks = [];
     active;
     disposed = false;
-    constructor(scene, clips, sources, nodes, fadeSeconds = 0.15, rootName = 'root') {
+    strippedRoot;
+    rootRestRotation;
+    owned = new Set();
+    rest = new Map();
+    inertia;
+    constructor(scene, clips, sources, nodes, fadeSeconds = 0.15, rootName = 'root', options = {}) {
         this.scene = scene;
         this.clips = clips;
         this.sources = sources;
@@ -19,27 +46,91 @@ export class BabylonMotionPlayer {
         this.rootName = rootName;
         if (!Number.isFinite(fadeSeconds) || fadeSeconds < 0)
             throw new Error('Invalid crossfade duration');
-        for (const clip of clips)
-            if (!sources.has(clip.id))
+        if (options.transition !== undefined && !['crossfade', 'inertialization'].includes(options.transition))
+            throw new Error('Invalid transition mode');
+        if (options.inertialHalfLife !== undefined && (!Number.isFinite(options.inertialHalfLife) || options.inertialHalfLife <= 0))
+            throw new Error('Invalid inertial half life');
+        for (const clip of clips) {
+            const source = sources.get(clip.id);
+            if (!source)
                 throw new Error(`Missing animation source: ${clip.id}`);
+            const fps = source.targetedAnimations[0]?.animation.framePerSecond, start = clip.sourceStart ?? 0;
+            if (!Number.isFinite(start) || start < 0 || !Number.isFinite(clip.duration) || clip.duration <= 0 || !fps
+                || start + clip.duration > (source.to - source.from) / fps + 1e-5)
+                throw new Error(`Invalid source range: ${clip.id}`);
+        }
+        const mapped = new Set(nodes.values());
+        if (options.mask !== undefined && (!Array.isArray(options.mask) || !options.mask.length || new Set(options.mask).size !== options.mask.length
+            || options.mask.some(name => typeof name !== 'string' || [...mapped].filter(n => n.name === name).length !== 1)))
+            throw new Error('Invalid player mask: use unique mapped model node names');
+        const mask = options.mask === undefined ? mapped : new Set([...mapped].filter(n => options.mask.includes(n.name)));
+        for (const clip of clips)
+            for (const targeted of sources.get(clip.id).targetedAnimations) {
+                const node = nodes.get(targeted.target.name);
+                if (node && mask.has(node))
+                    this.owned.add(node);
+            }
+        if (!this.owned.size)
+            throw new Error('No matching rig animation tracks in player mask');
+        if ([...this.owned].some(node => nodeOwners.has(node)))
+            throw new Error('Animation node already owned by another motion player');
+        this.strippedRoot = [...mapped].find(n => n.name === rootName);
+        if (this.strippedRoot && this.owned.has(this.strippedRoot)) {
+            this.strippedRoot.rotationQuaternion ??= Quaternion.FromEulerVector(this.strippedRoot.rotation);
+            this.rootRestRotation = this.strippedRoot.rotationQuaternion.clone();
+        }
+        for (const clip of clips)
+            if (clip.rootOrientation !== undefined) {
+                parseRootOrientation(clip.rootOrientation);
+                if (!this.strippedRoot)
+                    throw new Error('rootOrientation requires a mapped stripped root');
+            }
+        if (options.transition === 'inertialization') {
+            for (const clip of clips)
+                for (const targeted of sources.get(clip.id).targetedAnimations) {
+                    const node = nodes.get(targeted.target.name), property = targeted.animation.targetProperty;
+                    if (node && this.owned.has(node) && node !== this.strippedRoot && !/^(?:(?:position|scaling)(\.[xyz])?|rotationQuaternion(\.[xyzw])?)$/.test(property))
+                        throw new Error('Inertialization supports local position/scaling/quaternion tracks only');
+                }
+            this.rest = new Map([...this.owned].map(node => [node, captureLocal(node)]));
+            this.inertia = new BabylonInertializer(scene, options.inertialHalfLife ?? .1);
+        }
+        for (const node of this.owned)
+            nodeOwners.set(node, this);
     }
     create(clip, time) {
         const source = this.sources.get(this.clips[clip].id);
         const group = new AnimationGroup(`mm-${this.clips[clip].id}-${this.tracks.length}`, this.scene);
+        let rootRotation = this.rootRestRotation?.clone();
         for (const targeted of source.targetedAnimations) {
             const node = this.nodes.get(targeted.target.name);
-            if (!node)
+            if (!node || !this.owned.has(node))
                 continue;
             const property = targeted.animation.targetProperty;
-            // Gameplay owns horizontal root displacement AND heading. Preserve vertical bob only on other bones.
-            if (node.name === this.rootName && (property === 'position' || property === 'rotationQuaternion' || property === 'rotation'))
-                continue;
+            if (node === this.strippedRoot) {
+                if (property === 'position' || property.startsWith('position.'))
+                    continue;
+                if (property === 'rotationQuaternion' || property === 'rotation' || property.startsWith('rotation.') || property.startsWith('rotationQuaternion.')) {
+                    rootRotation = constantRootRotation(targeted.animation) ?? rootRotation;
+                    continue;
+                }
+            }
             group.addTargetedAnimation(targeted.animation, node);
         }
         if (!group.targetedAnimations.length) {
             group.dispose();
             throw new Error('No matching rig animation tracks');
         }
+        const correction = this.clips[clip].rootOrientation;
+        if (correction)
+            rootRotation = Quaternion.FromArray([...correction]).normalize();
+        if (this.strippedRoot && this.owned.has(this.strippedRoot) && rootRotation) {
+            // An explicit constant binding also restores the baseline after a clip with
+            // another orientation, and participates in the same weighted crossfade.
+            const rotation = new Animation('mm-root-pose', 'rotationQuaternion', source.targetedAnimations[0].animation.framePerSecond, Animation.ANIMATIONTYPE_QUATERNION);
+            rotation.setKeys([{ frame: source.from, value: rootRotation }, { frame: source.to, value: rootRotation.clone() }]);
+            group.addTargetedAnimation(rotation, this.strippedRoot);
+        }
         // Paused groups still participate in Babylon's late weighted bindings when
         // goToFrame(frame, true) is called. Speed zero alone resets on scene.render().
         group.start(true, 0);
@@ -60,6 +151,13 @@ export class BabylonMotionPlayer {
         }
         if (!this.clips[state.clip])
             throw new Error('Unknown playback clip');
+        const switched = !this.active || state.switched || this.active.clip !== state.clip;
+        if (switched && this.inertia) {
+            for (const track of this.tracks)
+                track.group.dispose();
+            this.tracks = [];
+            this.active = undefined;
+        }
         if (!this.active || state.switched || this.active.clip !== state.clip) {
             // Bound simultaneous slots during rapid replanning; residual poses retain relative weights.
             if (this.tracks.length >= 4) {
@@ -69,7 +167,18 @@ export class BabylonMotionPlayer {
             this.active = this.create(state.clip, state.time);
         }
         this.active.time = state.time;
-        const alpha = this.fadeSeconds === 0 ? 1 : 1 - Math.exp(-dt * 4 / this.fadeSeconds);
+        if (this.inertia) {
+            const clip = this.clips[state.clip], h = Math.min(1 / 120, clip.duration / 4);
+            const time = clip.looping ? ((state.time % clip.duration) + clip.duration) % clip.duration : Math.max(0, Math.min(state.time, clip.duration));
+            const low = clip.looping ? time - h : Math.max(0, time - h), high = clip.looping ? time + h : Math.min(clip.duration, time + h);
+            let incomingVelocity = new Map();
+            if (switched) {
+                const before = this.sampleLocal(this.active, low), after = this.sampleLocal(this.active, high);
+                incomingVelocity = new Map([...before].map(([node, pose]) => [node, poseVelocity(pose, after.get(node), high - low)]));
+            }
+            this.inertia.update(this.sampleLocal(this.active, time), incomingVelocity, dt, switched);
+        }
+        const alpha = this.inertia || this.fadeSeconds === 0 ? 1 : 1 - Math.exp(-dt * 4 / this.fadeSeconds);
         for (const track of this.tracks) {
             if (track !== this.active)
                 track.time += dt;
@@ -79,9 +188,10 @@ export class BabylonMotionPlayer {
         const total = this.tracks.reduce((sum, t) => sum + t.weight, 0);
         for (const track of this.tracks) {
             const descriptor = this.clips[track.clip], group = track.group;
-            const time = descriptor.looping ? track.time % descriptor.duration : Math.min(track.time, descriptor.duration);
+            const time = descriptor.looping ? ((track.time % descriptor.duration) + descriptor.duration) % descriptor.duration : Math.max(0, Math.min(track.time, descriptor.duration));
             group.setWeightForAllAnimatables(total > 0 ? track.weight / total : (track === this.active ? 1 : 0));
-            group.goToFrame(group.from + (group.to - group.from) * time / descriptor.duration, true);
+            const source = this.sources.get(descriptor.id), fps = source.targetedAnimations[0].animation.framePerSecond;
+            group.goToFrame(source.from + ((descriptor.sourceStart ?? 0) + time) * fps, true);
         }
         this.tracks = this.tracks.filter(track => {
             if (track !== this.active && track.weight < 0.001) {
@@ -91,36 +201,81 @@ export class BabylonMotionPlayer {
             return true;
         });
     }
+    sampleLocal(track, time) {
+        const result = new Map([...this.rest].map(([node, pose]) => [node, { position: pose.position.clone(), scaling: pose.scaling.clone(), rotation: pose.rotation.clone() }]));
+        const clip = this.clips[track.clip], source = this.sources.get(clip.id);
+        time = clip.looping ? ((time % clip.duration) + clip.duration) % clip.duration : Math.max(0, Math.min(time, clip.duration));
+        for (const targeted of track.group.targetedAnimations) {
+            const node = targeted.target, pose = result.get(node);
+            const [property, component] = targeted.animation.targetProperty.split('.');
+            const value = targeted.animation.evaluate(source.from + ((clip.sourceStart ?? 0) + time) * targeted.animation.framePerSecond);
+            const target = property === 'rotationQuaternion' ? pose.rotation : property === 'scaling' ? pose.scaling : pose.position;
+            if (component)
+                target[component] = value;
+            else
+                target.copyFrom(value);
+        }
+        return result;
+    }
+    /** Clear presentation history after teleport/reconciliation; ownership stays until dispose. */
+    reset() { this.clear(); }
     clear() { for (const t of this.tracks)
-        t.group.dispose(); this.tracks = []; this.active = undefined; }
-    dispose() { this.clear(); this.disposed = true; }
+        t.group.dispose(); this.tracks = []; this.active = undefined; this.inertia?.reset(); }
+    dispose() {
+        this.clear();
+        this.disposed = true;
+        this.inertia?.dispose();
+        for (const node of this.owned)
+            if (nodeOwners.get(node) === this)
+                nodeOwners.delete(node);
+        this.owned.clear();
+    }
 }
-/** Sample AFTER scene animation evaluation. Measures visible feet, including crossfade. */
-export class BabylonPoseReader {
+/** Sample AFTER scene animation evaluation. Semantic roles are defined by the schema. */
+export class BabylonSchemaPoseReader {
     root;
-    left;
-    right;
     previous;
-    constructor(root, left, right) {
+    nodes;
+    constructor(root, bones, schema) {
         this.root = root;
-        this.left = left;
-        this.right = right;
+        const roles = compileSchema(schema).bones;
+        for (const role of roles)
+            if (!bones.has(role))
+                throw new Error('Missing schema bone node: ' + role);
+        this.nodes = new Map(roles.map(role => [role, bones.get(role)]));
     }
     reset() { this.previous = undefined; }
     read(dt) {
         if (!Number.isFinite(dt) || dt < 0)
             throw new Error('Invalid pose delta');
         this.root.computeWorldMatrix(true);
-        this.left.computeWorldMatrix(true);
-        this.right.computeWorldMatrix(true);
-        const root = this.root.getAbsolutePosition().clone(), left = this.left.getAbsolutePosition().clone(), right = this.right.getAbsolutePosition().clone();
+        const root = this.root.getAbsolutePosition().clone(), positions = new Map();
+        for (const [role, node] of this.nodes) {
+            node.computeWorldMatrix(true);
+            positions.set(role, node.getAbsolutePosition().clone());
+        }
         const inverse = Matrix.Invert(this.root.getWorldMatrix());
         // Vector transform through inverse includes inverse model scale: consumers should keep root scale 1.
         const tuple = (v) => [v.x, v.y, v.z];
         const velocity = (value, previous) => previous && dt > 0 ? Vector3.TransformNormal(value.subtract(previous).scale(1 / dt), inverse) : Vector3.Zero();
-        const pose = { leftPosition: tuple(Vector3.TransformCoordinates(left, inverse)), rightPosition: tuple(Vector3.TransformCoordinates(right, inverse)),
-            leftVelocity: tuple(velocity(left, this.previous?.left)), rightVelocity: tuple(velocity(right, this.previous?.right)), rootVelocity: tuple(velocity(root, this.previous?.root)) };
-        this.previous = { left, right, root };
+        const bones = Object.fromEntries([...positions].map(([role, position]) => [role, {
+                position: tuple(Vector3.TransformCoordinates(position, inverse)), velocity: tuple(velocity(position, this.previous?.bones.get(role))),
+            }]));
+        const pose = { bones, rootVelocity: tuple(velocity(root, this.previous?.root)) };
+        this.previous = { bones: positions, root };
         return pose;
     }
 }
+/** Compatibility reader for the original two-foot preset. */
+export class BabylonPoseReader {
+    reader;
+    constructor(root, left, right) {
+        this.reader = new BabylonSchemaPoseReader(root, new Map([['leftFoot', left], ['rightFoot', right]]), LOCOMOTION_SCHEMA);
+    }
+    reset() { this.reader.reset(); }
+    read(dt) {
+        const pose = this.reader.read(dt);
+        return { leftPosition: pose.bones.leftFoot.position, rightPosition: pose.bones.rightFoot.position,
+            leftVelocity: pose.bones.leftFoot.velocity, rightVelocity: pose.bones.rightFoot.velocity, rootVelocity: pose.rootVelocity };
+    }
+}

package/dist/core/controller.d.ts

@@ -1,11 +1,24 @@
 import { PoseSearch } from './search.js';
 import type { Database, Match, Query } from './types.js';
+import type { SearchReport } from './search.js';
 export interface Playback {
     clip: number;
     time: number;
     switched: boolean;
     match: Match | null;
 }
+export interface MatcherDecision {
+    searched: boolean;
+    reason: string;
+    previousClip: number;
+    currentClip: number;
+    currentCost: number | null;
+    candidateCost: number | null;
+    sinceSwitch: number;
+    minimumHold: number;
+    jumpPenalty: number;
+    improvement: number;
+}
 export interface MatcherOptions {
     searchInterval: number;
     minimumHold: number;
@@ -13,6 +26,12 @@ export interface MatcherOptions {
     jumpPenalty: number;
     timeSeparation: number;
     reselectDelay: number;
+    /** Active only when the query explicitly requests idle alone. */
+    idleVariation?: {
+        interval: number;
+        historySize: number;
+    };
+    diagnostics?: boolean;
 }
 /** Owns animation time only. Caller retains movement and action authority. */
 export declare class MotionMatcher {
@@ -26,6 +45,13 @@ export declare class MotionMatcher {
     private last;
     private completed;
     private indices;
+    private idleElapsed;
+    private idleHistory;
+    private effectiveQuery?;
+    private decisionState;
+    /** Snapshot of the last continuity decision. Query copying requires diagnostics=true. */
+    get decision(): MatcherDecision | null;
+    inspect(limit?: number): SearchReport | null;
     constructor(database: Database, options?: Partial<MatcherOptions>);
     reset(): void;
     update(dt: number, query: Query): Playback;

package/dist/core/controller.js

@@ -1,4 +1,5 @@
 import { PoseSearch } from './search.js';
+import { withinWindows } from './selection.js';
 /** Owns animation time only. Caller retains movement and action authority. */
 export class MotionMatcher {
     database;
@@ -11,20 +12,36 @@ export class MotionMatcher {
     last = null;
     completed = new Map();
     indices;
+    idleElapsed = 0;
+    idleHistory = [];
+    effectiveQuery;
+    decisionState = null;
+    /** Snapshot of the last continuity decision. Query copying requires diagnostics=true. */
+    get decision() { return this.decisionState ? { ...this.decisionState } : null; }
+    inspect(limit = 5) { return this.options.diagnostics && this.effectiveQuery ? this.search.inspect(this.effectiveQuery, limit) : null; }
     constructor(database, options = {}) {
         this.database = database;
         this.search = new PoseSearch(database);
         this.options = { searchInterval: 0.1, minimumHold: 0.12, improvement: 0.1, jumpPenalty: 0.5, timeSeparation: 0.2, reselectDelay: 0.6, ...options };
-        if (!Object.values(this.options).every(v => Number.isFinite(v) && v >= 0) || this.options.searchInterval === 0 || this.options.improvement >= 1)
+        const { idleVariation, diagnostics, ...numeric } = this.options;
+        if (!Object.values(numeric).every(v => Number.isFinite(v) && v >= 0) || this.options.searchInterval === 0 || this.options.improvement >= 1)
             throw new Error('Invalid matcher options');
+        if (idleVariation && (!Number.isFinite(idleVariation.interval) || idleVariation.interval <= 0 || !Number.isInteger(idleVariation.historySize) || idleVariation.historySize < 1))
+            throw new Error('Invalid idle variation policy');
+        if (diagnostics !== undefined && typeof diagnostics !== 'boolean')
+            throw new Error('Invalid diagnostics option');
         this.indices = database.manifest.clips.map((_, clip) => database.manifest.frames.flatMap((f, i) => f.clip === clip ? [i] : []).sort((a, b) => database.manifest.frames[a].time - database.manifest.frames[b].time));
         if (this.indices.some(i => !i.length))
             throw new Error('Every clip must have indexed samples');
     }
-    reset() { this.clip = -1; this.time = 0; this.sinceSearch = this.sinceSwitch = Infinity; this.last = null; this.completed.clear(); }
+    reset() { this.clip = -1; this.time = 0; this.sinceSearch = this.sinceSwitch = Infinity; this.last = null; this.completed.clear(); this.idleElapsed = 0; this.idleHistory = []; this.effectiveQuery = undefined; this.decisionState = null; }
     update(dt, query) {
         if (!Number.isFinite(dt) || dt < 0)
             throw new Error('Invalid delta time');
+        // Validate identity even while continuity skips a search this frame.
+        this.search.validateQuery(query);
+        const previousClip = this.clip;
+        let reason = 'search-interval', searched = false, currentCost = null, candidateCost = null;
         let switched = false, ended = false;
         for (const [clip, remaining] of this.completed) {
             if (remaining <= dt)
@@ -40,15 +57,47 @@ export class MotionMatcher {
         }
         this.sinceSearch += dt;
         this.sinceSwitch += dt;
-        const allowed = this.clip >= 0 && !query.excludedClips?.has(this.clip) && (!query.gaits || query.gaits.has(this.database.manifest.clips[this.clip].gait));
+        const allowed = this.search.allowsClip(this.clip, query);
+        const idleOnly = query.gaits?.size === 1 && query.gaits.has('idle') && !!this.options.idleVariation;
+        if (idleOnly && allowed)
+            this.idleElapsed += dt;
+        else {
+            this.idleElapsed = 0;
+            this.idleHistory = [];
+        }
         if (this.sinceSearch >= this.options.searchInterval || !allowed || ended) {
+            searched = true;
             this.sinceSearch = 0;
             // A finished one-shot must yield to another clip, rather than selecting
             // its terminal pose and restarting forever. User exclusions still apply.
             if (ended)
                 this.completed.set(this.clip, this.options.reselectDelay);
             const excludedClips = new Set([...(query.excludedClips ?? []), ...this.completed.keys()]);
-            const best = this.search.search({ ...query, excludedClips });
+            let variation = false;
+            let best = null;
+            const runSearch = (effective) => {
+                // Keep the query that actually produced the candidate, including idle
+                // history/completion exclusions. Features are snapshotted for later UI.
+                if (this.options.diagnostics)
+                    this.effectiveQuery = { ...effective, features: effective.features.slice(), context: effective.context ? { ...effective.context } : undefined,
+                        gaits: effective.gaits ? new Set(effective.gaits) : undefined, excludedClips: effective.excludedClips ? new Set(effective.excludedClips) : undefined };
+                return this.search.search(effective);
+            };
+            if (idleOnly && allowed && !ended) {
+                if (this.idleElapsed >= this.options.idleVariation.interval) {
+                    // Relax oldest history first when the pool is small, but never force
+                    // a restart of the current clip or relax the consumer's context.
+                    const history = [...this.idleHistory];
+                    do {
+                        best = runSearch({ ...query, excludedClips: new Set([...excludedClips, this.clip, ...history]) });
+                    } while (!best && history.shift() !== undefined);
+                    variation = best !== null;
+                }
+                if (!best)
+                    best = runSearch({ ...query, excludedClips: new Set([...excludedClips, ...this.database.manifest.clips.flatMap((_, i) => i === this.clip ? [] : [i])]) });
+            }
+            else
+                best = runSearch({ ...query, excludedClips });
             this.last = best;
             if (best) {
                 const current = this.clip >= 0 ? this.nearestFrame(this.clip, this.time) : -1;
@@ -58,18 +107,39 @@ export class MotionMatcher {
                     gap = Math.min(gap, duration - gap);
                 const distant = best.clip !== this.clip || gap > this.options.timeSeparation;
                 const better = current < 0 || best.cost + this.options.jumpPenalty < this.search.cost(current) * (1 - this.options.improvement);
-                if (current < 0 || !allowed || ended || (distant && better && this.sinceSwitch >= this.options.minimumHold)) {
+                currentCost = current < 0 ? null : this.search.cost(current);
+                candidateCost = best.cost;
+                const incompatibleVelocity = current >= 0 && distant && this.sinceSwitch >= this.options.minimumHold && query.velocityTolerance !== undefined
+                    && this.search.rootVelocityError(current, query) > Math.max(query.velocityTolerance, this.search.rootVelocityError(best.index, query) + 1e-6);
+                const mayReselectTime = query.allowTemporalReselection !== false || best.clip !== this.clip || !this.database.manifest.clips[best.clip].looping;
+                const mayExit = this.clip < 0 || withinWindows(this.time, this.database.manifest.clips[this.clip].exitWindows);
+                const shouldSwitch = current < 0 || !allowed || ended || (mayExit && mayReselectTime && (incompatibleVelocity || (distant && (better || variation) && this.sinceSwitch >= this.options.minimumHold)));
+                reason = current < 0 ? 'initial' : !allowed ? 'incompatible-current' : ended ? 'clip-ended' : !mayExit ? 'exit-window' : !mayReselectTime ? 'phase-preserved'
+                    : incompatibleVelocity ? 'velocity-incompatible' : !distant ? 'nearby-candidate' : this.sinceSwitch < this.options.minimumHold ? 'minimum-hold' : variation ? 'idle-variation' : better ? 'better-candidate' : 'insufficient-improvement';
+                if (shouldSwitch) {
                     this.clip = best.clip;
                     this.time = best.time;
                     this.sinceSwitch = 0;
                     switched = true;
+                    this.idleElapsed = 0;
+                    if (this.database.manifest.clips[this.clip].gait === 'idle') {
+                        this.idleHistory.push(this.clip);
+                        this.idleHistory = this.idleHistory.slice(-(this.options.idleVariation?.historySize ?? 1));
+                    }
+                    else
+                        this.idleHistory = [];
                 }
             }
-            else if (!allowed || ended) {
-                this.clip = -1;
-                this.time = 0;
+            else {
+                reason = !allowed || ended ? 'no-candidate-cleared' : 'no-entry-continue';
+                if (!allowed || ended) {
+                    this.clip = -1;
+                    this.time = 0;
+                }
             }
         }
+        this.decisionState = { searched, reason, previousClip, currentClip: this.clip, currentCost, candidateCost, sinceSwitch: this.sinceSwitch,
+            minimumHold: this.options.minimumHold, improvement: this.options.improvement, jumpPenalty: this.options.jumpPenalty };
         return { clip: this.clip, time: this.time, switched, match: this.last };
     }
     nearestFrame(clip, time) {

package/dist/core/database.d.ts

@@ -1,6 +1,12 @@
 import { type Database, type DatabaseManifest } from './types.js';
+import { type PoseSchema } from './schema.js';
 export declare function validateDatabase(db: Database): void;
-export declare function buildDatabase(manifest: Omit<DatabaseManifest, 'version' | 'dimensions' | 'coordinates' | 'horizons' | 'mean' | 'std'>, raw: Float32Array): Database;
+type BuildManifest = Omit<DatabaseManifest, 'version' | 'dimensions' | 'schema' | 'schemaSignature' | 'coordinates' | 'horizons' | 'mean' | 'std'>;
+/** Omitting schema selects the legacy biped preset. New data is always v2. */
+export declare function buildDatabase(manifest: BuildManifest, raw: Float32Array, schema?: PoseSchema): Database;
 /** Binary format is explicitly little endian float32; version/layout live in manifest. */
 export declare function encodeFeatures(db: Database): ArrayBuffer;
-export declare function decodeDatabase(manifest: DatabaseManifest, bytes: ArrayBuffer): Database;
+export declare function decodeDatabase(manifest: unknown, bytes: ArrayBuffer, expectedSchema?: PoseSchema): Database;
+/** Explicit, lossless conversion ONLY for the original v1 27-dimensional preset. */
+export declare function migrateLegacyDatabase(input: unknown, bytes: ArrayBuffer): Database;
+export {};