@pose_flow/babylon 0.2.0 → 0.3.0

package/dist/core/types.d.ts

@@ -1,11 +1,12 @@
 import type { PoseSchema } from './schema.js';
+import type { SelectionContext, SelectionMetadata } from './selection.js';
 /** Legacy preset constants; dynamic consumers must use compileSchema. */
 export declare const DIMENSIONS = 27;
 export declare const HORIZONS: readonly [0.2, 0.4, 0.6];
 export type Vec3 = readonly [number, number, number];
 export type Quat = readonly [number, number, number, number];
 export type Gait = 'idle' | 'walk' | 'run' | 'strafe' | 'turn' | 'stop';
-export interface Clip {
+export interface Clip extends SelectionMetadata {
     id: string;
     file: string;
     animation: string;
@@ -53,6 +54,7 @@ export interface Match extends Frame {
     cost: number;
 }
 export interface Query {
+    context?: SelectionContext;
     features: Float32Array;
     schemaSignature?: string;
     gaits?: ReadonlySet<Gait>;

package/dist/index.d.ts

@@ -6,3 +6,6 @@ export * from './core/search.js';
 export * from './core/controller.js';
 export * from './core/root-motion.js';
 export * from './core/profile.js';
+export * from './core/selection.js';
+export * from './core/inertialization.js';
+export * from './core/scenario.js';

package/dist/index.js

@@ -6,3 +6,6 @@ export * from './core/search.js';
 export * from './core/controller.js';
 export * from './core/root-motion.js';
 export * from './core/profile.js';
+export * from './core/selection.js';
+export * from './core/inertialization.js';
+export * from './core/scenario.js';

package/dist/offline/src/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/offline/src/babylon.js

@@ -1,6 +1,8 @@
 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();
@@ -32,7 +34,10 @@ export class BabylonMotionPlayer {
     disposed = false;
     strippedRoot;
     rootRestRotation;
-    constructor(scene, clips, sources, nodes, fadeSeconds = 0.15, rootName = 'root') {
+    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;
@@ -41,6 +46,10 @@ export class BabylonMotionPlayer {
         this.rootName = rootName;
         if (!Number.isFinite(fadeSeconds) || fadeSeconds < 0)
             throw new Error('Invalid crossfade duration');
+        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)
@@ -50,8 +59,23 @@ export class BabylonMotionPlayer {
                 || start + clip.duration > (source.to - source.from) / fps + 1e-5)
                 throw new Error(`Invalid source range: ${clip.id}`);
         }
-        this.strippedRoot = [...nodes.values()].find(n => n.name === rootName);
-        if (this.strippedRoot) {
+        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();
         }
@@ -61,6 +85,18 @@ export class BabylonMotionPlayer {
                 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);
@@ -68,7 +104,7 @@ export class BabylonMotionPlayer {
         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;
             if (node === this.strippedRoot) {
@@ -88,7 +124,7 @@ export class BabylonMotionPlayer {
         const correction = this.clips[clip].rootOrientation;
         if (correction)
             rootRotation = Quaternion.FromArray([...correction]).normalize();
-        if (this.strippedRoot && rootRotation) {
+        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);
@@ -115,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) {
@@ -124,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;
@@ -147,9 +201,35 @@ 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. Semantic roles are defined by the schema. */
 export class BabylonSchemaPoseReader {

package/dist/offline/src/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,22 +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)
@@ -42,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;
@@ -60,21 +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);
+                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;
-                if (current < 0 || !allowed || ended || (mayReselectTime && (incompatibleVelocity || (distant && better && this.sinceSwitch >= this.options.minimumHold)))) {
+                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/offline/src/core/database.js

@@ -1,5 +1,6 @@
 import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
 import { parseRootOrientation } from './profile.js';
+import { validateSelection } from './selection.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 export function validateDatabase(db) {
     const m = db?.manifest;
@@ -30,6 +31,7 @@ export function validateDatabase(db) {
             || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(clip.gait))
             throw new Error('Invalid clip');
         ids.add(clip.id);
+        validateSelection(clip, clip.duration);
         if (clip.sourceStart !== undefined && (!Number.isFinite(clip.sourceStart) || clip.sourceStart < 0))
             throw new Error('Invalid source start');
         if (clip.averageVelocity !== undefined && (!Array.isArray(clip.averageVelocity) || clip.averageVelocity.length !== 3 || !clip.averageVelocity.every(Number.isFinite)))

package/dist/offline/src/core/inertialization.js

@@ -0,0 +1,15 @@
+/** Critically damped residual. With zero initial velocity, offset halves at halfLife.
+ * Does not integrate gameplay/root displacement. */
+export function decayInertialOffset(offset, velocity, elapsed, halfLife) {
+    if (![offset, velocity, elapsed, halfLife].every(Number.isFinite) || elapsed < 0 || halfLife <= 0)
+        throw new Error('Invalid inertial residual');
+    if (elapsed === 0)
+        return offset;
+    const exponent = (1.67834699001666 / halfLife) * elapsed;
+    if (exponent > 745)
+        return 0;
+    const decay = Math.exp(-exponent);
+    // Reassociate products: avoid Infinity * 0 after a long pause, and avoid
+    // overflowing omega*offset while the final damped value is representable.
+    return offset * ((1 + exponent) * decay) + velocity * (elapsed * decay);
+}

package/dist/offline/src/core/profile.js

@@ -1,4 +1,5 @@
 import { compileSchema, parseSchema } from './schema.js';
+import { validateContext, validateSelection } from './selection.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const name = (v) => typeof v === 'string' && v.trim().length > 0;
 const asset = (v) => name(v) && !v.includes('\\') && !v.includes('..') && !/[?#:]/.test(v);
@@ -25,6 +26,18 @@ export function parseProfile(input) {
         throw new Error('Profile: required bones must be distinct');
     if (input.stripRoot !== undefined && !name(input.stripRoot))
         throw new Error('Profile: invalid stripRoot');
+    if (input.masks !== undefined && (!record(input.masks) || !Object.entries(input.masks).length || !Object.entries(input.masks).every(([key, values]) => name(key)
+        && Array.isArray(values) && values.length > 0 && values.every(name) && new Set(values).size === values.length)))
+        throw new Error('Profile: invalid masks');
+    if (input.layerPreview !== undefined) {
+        const preview = input.layerPreview, masks = input.masks;
+        if (!record(preview) || !name(preview.baseMask) || !name(preview.overlayMask) || !masks || !Object.hasOwn(masks, preview.baseMask) || !Object.hasOwn(masks, preview.overlayMask)
+            || masks[preview.baseMask].some(node => masks[preview.overlayMask].includes(node)))
+            throw new Error('Profile: layer preview requires two disjoint masks');
+        validateContext(preview.context);
+        if (!Object.keys(preview.context).length)
+            throw new Error('Profile: layer preview requires explicit context');
+    }
     if (input.boneMap !== undefined && (!record(input.boneMap) || !Object.entries(input.boneMap).every(([k, v]) => name(k) && name(v)) || new Set(Object.values(input.boneMap)).size !== Object.values(input.boneMap).length))
         throw new Error('Profile: boneMap must map distinct nonempty names');
     return structuredClone(input);
@@ -42,6 +55,7 @@ export function parseAnimationSet(input) {
             parseRootOrientation(clip.rootOrientation);
         if (clip.range !== undefined && (!Array.isArray(clip.range) || clip.range.length !== 2 || !clip.range.every(Number.isFinite) || clip.range[0] < 0 || clip.range[1] <= clip.range[0]))
             throw new Error('Invalid clip range');
+        validateSelection(clip, Array.isArray(clip.range) ? clip.range[1] - clip.range[0] : Infinity);
         const nominal = clip.nominalVelocity !== undefined, measured = clip.motionFile !== undefined;
         if (nominal === measured)
             throw new Error(`Profile ${clip.id}: declare exactly one of nominalVelocity or motionFile`);

package/dist/offline/src/core/scenario.js

@@ -0,0 +1,57 @@
+import { encodeFeatures } from './database.js';
+import { MotionMatcher } from './controller.js';
+import { PoseSearch } from './search.js';
+/** Content identity for exact replay, not a cryptographic/security signature. */
+export function scenarioDatabaseIdentity(db) {
+    let hash = 2166136261;
+    for (const char of JSON.stringify(db.manifest))
+        hash = Math.imul(hash ^ char.charCodeAt(0), 16777619);
+    for (const byte of new Uint8Array(encodeFeatures(db)))
+        hash = Math.imul(hash ^ byte, 16777619);
+    return 'scenario-db-v1:' + (hash >>> 0).toString(16).padStart(8, '0');
+}
+export function restoreScenarioQuery(recorded) {
+    return { ...recorded, features: Float32Array.from(recorded.features), gaits: recorded.gaits ? new Set(recorded.gaits) : undefined,
+        excludedClips: recorded.excludedClips ? new Set(recorded.excludedClips) : undefined };
+}
+export function captureScenarioFrame(dt, query, position, yaw, playback, presentation) {
+    return { dt, query: { ...query, features: [...query.features], ...(query.context ? { context: { ...query.context } } : {}),
+            gaits: query.gaits ? [...query.gaits] : undefined, excludedClips: query.excludedClips ? [...query.excludedClips] : undefined },
+        controller: { position: [...position], yaw }, playback: { clip: playback.clip, time: playback.time, switched: playback.switched },
+        ...(presentation ? { presentation: { clip: presentation.clip, time: presentation.time, switched: presentation.switched } } : {}) };
+}
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Import only validated local data, never execute content from a scenario file. */
+export function parseMotionScenario(input, db) {
+    if (!record(input) || input.version !== 1 || input.databaseIdentity !== scenarioDatabaseIdentity(db) || !Array.isArray(input.frames)
+        || !input.frames.length || input.frames.length > 6000 || input.frames.length * db.manifest.dimensions > 2_000_000 || !record(input.matcherOptions))
+        throw new Error('Invalid/incompatible motion scenario');
+    const options = input.matcherOptions;
+    if (Object.keys(options).some(k => !['searchInterval', 'minimumHold', 'improvement', 'jumpPenalty', 'timeSeparation', 'reselectDelay', 'idleVariation', 'diagnostics'].includes(k)))
+        throw new Error('Invalid scenario matcher options');
+    new MotionMatcher(db, options);
+    const search = new PoseSearch(db);
+    for (const frame of input.frames) {
+        if (!record(frame) || typeof frame.dt !== 'number' || !Number.isFinite(frame.dt) || frame.dt < 0 || frame.dt > 10 || !record(frame.query)
+            || !record(frame.controller) || !record(frame.playback))
+            throw new Error('Invalid scenario frame');
+        const q = frame.query, p = frame.playback, controller = frame.controller;
+        if (Object.keys(q).some(k => !['features', 'schemaSignature', 'gaits', 'excludedClips', 'velocityTolerance', 'allowTemporalReselection', 'context'].includes(k))
+            || !Array.isArray(q.features) || q.features.length !== db.manifest.dimensions || !q.features.every(Number.isFinite)
+            || (q.gaits !== undefined && (!Array.isArray(q.gaits) || !q.gaits.every(g => ['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(g))))
+            || (q.excludedClips !== undefined && (!Array.isArray(q.excludedClips) || !q.excludedClips.every(c => Number.isInteger(c) && c >= 0 && c < db.manifest.clips.length))))
+            throw new Error('Invalid scenario query');
+        search.validateQuery(restoreScenarioQuery(q));
+        if (!Array.isArray(controller.position) || controller.position.length !== 3 || !controller.position.every(Number.isFinite) || typeof controller.yaw !== 'number' || !Number.isFinite(controller.yaw)
+            || !Number.isInteger(p.clip) || p.clip < -1 || p.clip >= db.manifest.clips.length || typeof p.time !== 'number' || !Number.isFinite(p.time) || p.time < 0
+            || (p.clip >= 0 && p.time > db.manifest.clips[p.clip].duration + 1e-6) || typeof p.switched !== 'boolean')
+            throw new Error('Invalid scenario playback/controller');
+        if (frame.presentation !== undefined) {
+            const p = frame.presentation;
+            if (!record(p) || !Number.isInteger(p.clip) || p.clip < -1 || p.clip >= db.manifest.clips.length || typeof p.time !== 'number' || !Number.isFinite(p.time) || p.time < 0
+                || (p.clip >= 0 && p.time > db.manifest.clips[p.clip].duration + 1e-6) || typeof p.switched !== 'boolean')
+                throw new Error('Invalid scenario presentation');
+        }
+    }
+    return structuredClone(input);
+}