@pose_flow/babylon 0.1.0 → 0.3.0

package/dist/offline/src/babylon.js

@@ -0,0 +1,281 @@
+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;
+    clips;
+    sources;
+    nodes;
+    fadeSeconds;
+    rootName;
+    tracks = [];
+    active;
+    disposed = false;
+    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;
+        this.nodes = nodes;
+        this.fadeSeconds = fadeSeconds;
+        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)
+                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 || !this.owned.has(node))
+                continue;
+            const property = targeted.animation.targetProperty;
+            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);
+        group.pause();
+        group.setWeightForAllAnimatables(0);
+        const track = { group, clip, time, weight: this.tracks.length === 0 ? 1 : 0 };
+        this.tracks.push(track);
+        return track;
+    }
+    update(state, dt) {
+        if (this.disposed)
+            throw new Error('Player already disposed');
+        if (!Number.isFinite(dt) || dt < 0)
+            throw new Error('Invalid player delta');
+        if (state.clip < 0) {
+            this.clear();
+            return;
+        }
+        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) {
+                const oldest = this.tracks.shift();
+                oldest.group.dispose();
+            }
+            this.active = this.create(state.clip, state.time);
+        }
+        this.active.time = state.time;
+        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;
+            track.weight += ((track === this.active ? 1 : 0) - track.weight) * alpha;
+        }
+        // First pose must be fully defined even at dt=0.
+        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) + 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));
+            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) {
+                track.group.dispose();
+                return false;
+            }
+            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; 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 {
+    root;
+    previous;
+    nodes;
+    constructor(root, bones, schema) {
+        this.root = root;
+        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);
+        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 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/offline/src/core/controller.js

@@ -0,0 +1,162 @@
+import { PoseSearch } from './search.js';
+import { withinWindows } from './selection.js';
+/** Owns animation time only. Caller retains movement and action authority. */
+export class MotionMatcher {
+    database;
+    search;
+    options;
+    clip = -1;
+    time = 0;
+    sinceSearch = Infinity;
+    sinceSwitch = Infinity;
+    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 };
+        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(); 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)
+                this.completed.delete(clip);
+            else
+                this.completed.set(clip, remaining - dt);
+        }
+        if (this.clip >= 0) {
+            const clip = this.database.manifest.clips[this.clip];
+            this.time += dt;
+            ended = !clip.looping && this.time >= clip.duration;
+            this.time = clip.looping ? this.time % clip.duration : Math.min(this.time, clip.duration);
+        }
+        this.sinceSearch += dt;
+        this.sinceSwitch += dt;
+        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()]);
+            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;
+                const duration = this.database.manifest.clips[best.clip].duration;
+                let gap = Math.abs(best.time - this.time);
+                if (best.clip === this.clip && this.database.manifest.clips[best.clip].looping)
+                    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;
+                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 {
+                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) {
+        const indices = this.indices[clip];
+        if (!indices?.length)
+            return -1;
+        const { frames, clips } = this.database.manifest;
+        let best = indices[0], distance = Infinity;
+        for (const i of indices) {
+            let delta = Math.abs(frames[i].time - time);
+            if (clips[clip].looping)
+                delta = Math.min(delta, clips[clip].duration - delta);
+            if (delta < distance) {
+                best = i;
+                distance = delta;
+            }
+        }
+        return best;
+    }
+}

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

@@ -0,0 +1,97 @@
+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;
+    if (!record(m) || m.version !== 2)
+        throw new Error('Unsupported pose database version; v1 requires migrateLegacyDatabase or a new bake');
+    const layout = compileSchema(m.schema), dimensions = layout.dimensions;
+    if (m.dimensions !== dimensions || m.schemaSignature !== layout.signature || m.coordinates !== 'meters-y-up-z-forward'
+        || !Array.isArray(m.horizons) || m.horizons.length !== layout.horizons.length || m.horizons.some((v, i) => v !== layout.horizons[i]))
+        throw new Error('Incompatible pose database schema');
+    if (!Number.isFinite(m.sampleRate) || m.sampleRate <= 0 || !Array.isArray(m.frames) || !m.frames.length || !Array.isArray(m.clips) || !m.clips.length
+        || !(db.features instanceof Float32Array) || db.features.length !== m.frames.length * dimensions)
+        throw new Error('Invalid database size/sample rate');
+    if (!Array.isArray(m.mean) || !Array.isArray(m.std) || m.mean.length !== dimensions || m.std.length !== dimensions || ![...m.mean].every(Number.isFinite)
+        || ![...m.std].every(v => Number.isFinite(v) && v >= 1e-4) || !db.features.every(Number.isFinite))
+        throw new Error('Invalid normalization/features');
+    for (const { channel, offset, dimensions: width } of layout.channels)
+        if (channel.normalization === 'none') {
+            for (let j = offset; j < offset + width; j++)
+                if (m.mean[j] !== 0 || m.std[j] !== 1)
+                    throw new Error('Invalid unnormalized channel statistics');
+        }
+    if (m.assetHashes !== undefined && (!record(m.assetHashes) || !Object.entries(m.assetHashes).length || !Object.entries(m.assetHashes).every(([url, hash]) => url.startsWith('/') && typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash))))
+        throw new Error('Invalid asset hashes');
+    const ids = new Set();
+    for (const clip of m.clips) {
+        if (!record(clip) || typeof clip.id !== 'string' || ids.has(clip.id) || !clip.id || typeof clip.file !== 'string' || !clip.file
+            || typeof clip.animation !== 'string' || !clip.animation || !Number.isFinite(clip.duration) || clip.duration <= 0 || typeof clip.looping !== 'boolean'
+            || !['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)))
+            throw new Error('Invalid measured average velocity');
+        if (clip.rootOrientation !== undefined)
+            parseRootOrientation(clip.rootOrientation);
+    }
+    for (const frame of m.frames) {
+        if (!record(frame) || !Number.isInteger(frame.clip) || !m.clips[frame.clip] || !Number.isFinite(frame.time)
+            || frame.time < 0 || frame.time > m.clips[frame.clip].duration + 1e-6)
+            throw new Error('Invalid pose metadata');
+    }
+}
+/** Omitting schema selects the legacy biped preset. New data is always v2. */
+export function buildDatabase(manifest, raw, schema = LOCOMOTION_SCHEMA) {
+    const layout = compileSchema(schema), dimensions = layout.dimensions, count = manifest.frames.length;
+    if (!count || raw.length !== count * dimensions || !raw.every(Number.isFinite))
+        throw new Error('Invalid raw samples');
+    const mean = Array(dimensions).fill(0), std = Array(dimensions).fill(0);
+    for (let i = 0; i < raw.length; i++)
+        mean[i % dimensions] += raw[i] / count;
+    for (let i = 0; i < raw.length; i++)
+        std[i % dimensions] += (raw[i] - mean[i % dimensions]) ** 2 / count;
+    for (let j = 0; j < dimensions; j++)
+        std[j] = Math.sqrt(std[j]) < 1e-4 ? 1 : Math.sqrt(std[j]);
+    for (const { channel, offset, dimensions: width } of layout.channels)
+        if (channel.normalization === 'none') {
+            mean.fill(0, offset, offset + width);
+            std.fill(1, offset, offset + width);
+        }
+    const features = Float32Array.from(raw, (v, i) => (v - mean[i % dimensions]) / std[i % dimensions]);
+    const db = { manifest: { ...manifest, version: 2, dimensions, schema: layout.schema, schemaSignature: layout.signature,
+            coordinates: 'meters-y-up-z-forward', horizons: layout.horizons, mean, std }, features };
+    validateDatabase(db);
+    return db;
+}
+/** Binary format is explicitly little endian float32; version/layout live in manifest. */
+export function encodeFeatures(db) {
+    validateDatabase(db);
+    const bytes = new ArrayBuffer(db.features.length * 4), view = new DataView(bytes);
+    db.features.forEach((v, i) => view.setFloat32(i * 4, v, true));
+    return bytes;
+}
+export function decodeDatabase(manifest, bytes, expectedSchema) {
+    if (bytes.byteLength % 4)
+        throw new Error('Truncated feature binary');
+    const view = new DataView(bytes), features = new Float32Array(bytes.byteLength / 4);
+    for (let i = 0; i < features.length; i++)
+        features[i] = view.getFloat32(i * 4, true);
+    const db = { manifest: manifest, features };
+    validateDatabase(db);
+    if (expectedSchema && db.manifest.schemaSignature !== compileSchema(expectedSchema).signature)
+        throw new Error('Incompatible expected schema; regenerate database');
+    return db;
+}
+/** Explicit, lossless conversion ONLY for the original v1 27-dimensional preset. */
+export function migrateLegacyDatabase(input, bytes) {
+    const layout = compileSchema(LOCOMOTION_SCHEMA);
+    if (!record(input) || input.version !== 1 || input.dimensions !== layout.dimensions || !Array.isArray(input.horizons)
+        || input.horizons.length !== layout.horizons.length || input.horizons.some((h, i) => h !== layout.horizons[i]))
+        throw new Error('Unsupported legacy database schema');
+    return decodeDatabase({ ...input, version: 2, schema: layout.schema, schemaSignature: layout.signature }, bytes);
+}

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

@@ -0,0 +1,41 @@
+import { DIMENSIONS, HORIZONS } from './types.js';
+import { SchemaQueryBuilder, validateHorizons } from './schema.js';
+const legacyBuilder = new SchemaQueryBuilder();
+export function featureVector(pose, trajectory, out = new Float32Array(DIMENSIONS)) {
+    return legacyBuilder.features({ rootVelocity: pose.rootVelocity, bones: {
+            leftFoot: { position: pose.leftPosition, velocity: pose.leftVelocity },
+            rightFoot: { position: pose.rightPosition, velocity: pose.rightVelocity },
+        } }, trajectory, out);
+}
+/** World delta to current character-local XZ (yaw zero looks along +Z). */
+export function toLocal(x, z, yaw) {
+    const c = Math.cos(yaw), s = Math.sin(yaw);
+    return [c * x - s * z, s * x + c * z];
+}
+/** Prediction only: never writes to the gameplay controller. Uses fixed substeps. */
+export function predictTrajectory(input, horizons = HORIZONS) {
+    validateHorizons(horizons);
+    if (![...input.velocity, ...input.desiredVelocity, input.yaw, input.desiredYaw, input.acceleration, input.braking, input.turnSpeed].every(Number.isFinite)
+        || Math.min(input.acceleration, input.braking, input.turnSpeed) < 0)
+        throw new Error('Invalid trajectory input');
+    let [vx, vz] = input.velocity, x = 0, z = 0, yaw = input.yaw, elapsed = 0;
+    const points = [];
+    for (const horizon of horizons) {
+        while (elapsed < horizon - 1e-9) {
+            const dt = Math.min(1 / 60, horizon - elapsed);
+            const dx = input.desiredVelocity[0] - vx, dz = input.desiredVelocity[1] - vz, length = Math.hypot(dx, dz);
+            const rate = Math.hypot(...input.desiredVelocity) < Math.hypot(vx, vz) ? input.braking : input.acceleration;
+            const amount = length > 0 ? Math.min(1, rate * dt / length) : 0;
+            const nx = vx + dx * amount, nz = vz + dz * amount;
+            x += (vx + nx) * 0.5 * dt;
+            z += (vz + nz) * 0.5 * dt;
+            vx = nx;
+            vz = nz;
+            const angle = Math.atan2(Math.sin(input.desiredYaw - yaw), Math.cos(input.desiredYaw - yaw));
+            yaw += Math.sign(angle) * Math.min(Math.abs(angle), input.turnSpeed * dt);
+            elapsed += dt;
+        }
+        points.push({ position: toLocal(x, z, input.yaw), facing: [Math.sin(yaw - input.yaw), Math.cos(yaw - input.yaw)] });
+    }
+    return points;
+}

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);
+}