@pose_flow/babylon 0.1.0 → 0.2.0

package/dist/core/profile.js

@@ -1,42 +1,67 @@
+import { compileSchema, parseSchema } from './schema.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);
+export function parseRootOrientation(value) {
+    if (!Array.isArray(value) || value.length !== 4 || ![...value].every(Number.isFinite) || Math.abs(Math.hypot(...value) - 1) > 1e-5)
+        throw new Error('Invalid rootOrientation: expected unit quaternion [x,y,z,w]');
+    return [...value];
+}
 /** Read untrusted JSON as unknown; report a configuration error before loading assets. */
 export function parseProfile(input) {
-    if (!record(input) || input.version !== 1 || !name(input.id) || !/^[a-z0-9][a-z0-9-]*$/.test(input.id) || !name(input.label))
-        throw new Error('Profile: invalid version/id/label');
+    if (!record(input) || input.version !== 2 || !name(input.id) || !/^[a-z0-9][a-z0-9-]*$/.test(input.id) || !name(input.label))
+        throw new Error('Profile: expected version 2; split v1 clips into animationSet and declare schema');
+    if ('clips' in input || !asset(input.schema) || !input.schema.startsWith('/') || !input.schema.endsWith('.json')
+        || !asset(input.animationSet) || !input.animationSet.startsWith('/') || !input.animationSet.endsWith('.json'))
+        throw new Error('Profile: declare schema and animationSet JSON URLs, without inline clips');
     if (!asset(input.assetBase) || !input.assetBase.startsWith('/') || !input.assetBase.endsWith('/') || !asset(input.database) || !input.database.startsWith('/') || !input.database.endsWith('/')
         || !asset(input.model) || input.model.startsWith('/'))
         throw new Error('Profile: use public URL folders and relative model files');
     if (typeof input.scale !== 'number' || !Number.isFinite(input.scale) || input.scale <= 0 || typeof input.sampleRate !== 'number' || !Number.isFinite(input.sampleRate) || input.sampleRate < 1 || input.sampleRate > 120)
         throw new Error('Profile: invalid scale/sampleRate');
-    if (!record(input.rig) || !name(input.rig.root) || !name(input.rig.leftFoot) || !name(input.rig.rightFoot))
-        throw new Error('Profile: root and both feet must be mapped');
-    const rig = input.rig;
-    if (new Set([rig.root, rig.leftFoot, rig.rightFoot]).size !== 3)
+    if (!record(input.rig) || !name(input.rig.root) || !Object.entries(input.rig).every(([k, v]) => /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(k) && name(v)))
+        throw new Error('Profile: semantic rig roles must be mapped');
+    if (new Set(Object.values(input.rig)).size !== Object.values(input.rig).length)
         throw new Error('Profile: required bones must be distinct');
     if (input.stripRoot !== undefined && !name(input.stripRoot))
         throw new Error('Profile: invalid stripRoot');
     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');
-    if (!Array.isArray(input.clips) || !input.clips.length)
-        throw new Error('Profile: no clips');
+    return structuredClone(input);
+}
+export function parseAnimationSet(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || !Array.isArray(input.clips) || !input.clips.length)
+        throw new Error('AnimationSet: invalid version/id/clips');
     const ids = new Set();
     for (const clip of input.clips) {
         if (!record(clip) || !name(clip.id) || ids.has(clip.id) || !asset(clip.file) || clip.file.startsWith('/') || !name(clip.animation) || typeof clip.looping !== 'boolean'
             || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(String(clip.gait)))
             throw new Error('Profile: invalid/duplicate clip');
         ids.add(clip.id);
+        if (clip.rootOrientation !== undefined)
+            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');
         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`);
         if (nominal && (!Array.isArray(clip.nominalVelocity) || clip.nominalVelocity.length !== 3 || !clip.nominalVelocity.every(Number.isFinite)))
             throw new Error(`Profile ${clip.id}: invalid velocity`);
-        if (measured && (!asset(clip.motionFile) || clip.motionFile.startsWith('/') || clip.looping))
-            throw new Error(`Profile ${clip.id}: measured motion requires a relative file and non-looping clip`);
+        if (measured && (!asset(clip.motionFile) || clip.motionFile.startsWith('/')))
+            throw new Error(`Profile ${clip.id}: measured motion requires a relative file`);
     }
     return structuredClone(input);
 }
+/** Resolve external configuration explicitly; core performs no I/O. */
+export function resolveProfile(profile, schemaInput, setInput) {
+    const config = parseProfile(profile), schemaDefinition = parseSchema(schemaInput), set = parseAnimationSet(setInput);
+    for (const role of compileSchema(schemaDefinition).bones)
+        if (!Object.hasOwn(config.rig, role))
+            throw new Error('Profile: missing schema bone role: ' + role);
+    if (!config.stripRoot && set.clips.some(c => c.rootOrientation !== undefined))
+        throw new Error('Profile: rootOrientation requires stripRoot');
+    return { ...config, schemaDefinition, clips: set.clips, setId: set.id };
+}
 /** Deterministic configuration fingerprint; detects stale banks, not a security signature. */
 export function profileSignature(profile) {
     const sorted = (value) => Array.isArray(value) ? value.map(sorted) : record(value) ? Object.fromEntries(Object.keys(value).sort().map(k => [k, sorted(value[k])])) : value;

package/dist/core/root-motion.d.ts

@@ -9,14 +9,16 @@ export interface RootMotionSample {
 export interface RootMotionTrack {
     version: 1;
     duration: number;
-    source: 'hips';
+    source: 'hips' | 'root';
     samples: RootMotionSample[];
 }
 export declare function validateRootMotion(track: RootMotionTrack): void;
 /** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
-export declare function sampleRootMotion(track: RootMotionTrack, time: number): RootMotionSample;
-export declare function rootMotionFeatures(track: RootMotionTrack, time: number, derivativeStep?: number): {
+export declare function sampleRootMotion(track: RootMotionTrack, time: number, looping?: boolean): RootMotionSample;
+export declare function rootMotionFeatures(track: RootMotionTrack, time: number, derivativeStep?: number, horizons?: readonly number[], looping?: boolean): {
     velocity: readonly [number, number, number];
     angularVelocity: number;
     trajectory: TrajectoryPoint[];
 };
+/** Crop to the same source interval as playback; preserve the source coordinate frame. */
+export declare function cropRootMotion(track: RootMotionTrack, start: number, end: number): RootMotionTrack;

package/dist/core/root-motion.js

@@ -1,11 +1,12 @@
 import { HORIZONS } from './types.js';
 import { toLocal } from './features.js';
+import { validateHorizons } from './schema.js';
 export function validateRootMotion(track) {
-    if (track.version !== 1 || track.source !== 'hips' || !Number.isFinite(track.duration) || track.duration <= 0 || track.samples.length < 2)
+    if (!track || track.version !== 1 || !['hips', 'root'].includes(track.source) || !Number.isFinite(track.duration) || track.duration <= 0 || !Array.isArray(track.samples) || track.samples.length < 2)
         throw new Error('Invalid root motion track');
     let previous = -Infinity;
     for (const sample of track.samples) {
-        if (!Object.values(sample).every(Number.isFinite) || sample.time <= previous || sample.time < 0 || sample.time > track.duration + 1e-6)
+        if (!sample || ![sample.time, sample.x, sample.z, sample.yaw].every(Number.isFinite) || sample.time <= previous || sample.time < 0 || sample.time > track.duration + 1e-6)
             throw new Error('Invalid root motion sample');
         previous = sample.time;
     }
@@ -13,9 +14,34 @@ export function validateRootMotion(track) {
         throw new Error('Incomplete root motion track');
 }
 /** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
-export function sampleRootMotion(track, time) {
+export function sampleRootMotion(track, time, looping = false) {
     if (!Number.isFinite(time))
         throw new Error('Invalid root motion time');
+    if (looping) {
+        const cycle = Math.floor(time / track.duration), phase = time - cycle * track.duration;
+        if (!Number.isSafeInteger(cycle))
+            throw new Error('Root motion cycle out of range');
+        const first = track.samples[0], last = track.samples.at(-1);
+        const delta = toLocal(last.x - first.x, last.z - first.z, first.yaw), angle = last.yaw - first.yaw;
+        // Exponentiate planar rigid transforms, including negative cycles.
+        const compose = (a, b) => ({ time,
+            x: a.x + Math.cos(a.yaw) * b.x + Math.sin(a.yaw) * b.z,
+            z: a.z - Math.sin(a.yaw) * b.x + Math.cos(a.yaw) * b.z, yaw: a.yaw + b.yaw });
+        let power = { time, x: delta[0], z: delta[1], yaw: angle };
+        if (cycle < 0) {
+            const v = toLocal(-power.x, -power.z, angle);
+            power = { time, x: v[0], z: v[1], yaw: -angle };
+        }
+        let result = { time, x: 0, z: 0, yaw: 0 }, count = Math.abs(cycle);
+        while (count > 0) {
+            if (count % 2 === 1)
+                result = compose(result, power);
+            power = compose(power, power);
+            count = Math.floor(count / 2);
+        }
+        const sample = sampleRootMotion(track, phase), local = toLocal(sample.x - first.x, sample.z - first.z, first.yaw);
+        return compose(first, compose(result, { time, x: local[0], z: local[1], yaw: sample.yaw - first.yaw }));
+    }
     const t = Math.max(0, Math.min(time, track.duration)), samples = track.samples;
     let lo = 0, hi = samples.length - 1;
     while (hi - lo > 1) {
@@ -28,15 +54,25 @@ export function sampleRootMotion(track, time) {
     const a = samples[lo], b = samples[hi], alpha = (t - a.time) / (b.time - a.time);
     return { time: t, x: a.x + (b.x - a.x) * alpha, z: a.z + (b.z - a.z) * alpha, yaw: a.yaw + (b.yaw - a.yaw) * alpha };
 }
-export function rootMotionFeatures(track, time, derivativeStep = 1 / 30) {
+export function rootMotionFeatures(track, time, derivativeStep = 1 / 30, horizons = HORIZONS, looping = false) {
+    validateHorizons(horizons);
     if (!Number.isFinite(derivativeStep) || derivativeStep <= 0)
         throw new Error('Invalid derivative step');
-    const now = sampleRootMotion(track, time), a = sampleRootMotion(track, time - derivativeStep), b = sampleRootMotion(track, time + derivativeStep);
+    const now = sampleRootMotion(track, time, looping), a = sampleRootMotion(track, time - derivativeStep, looping), b = sampleRootMotion(track, time + derivativeStep, looping);
     const elapsed = b.time - a.time;
     const v = elapsed > 0 ? toLocal((b.x - a.x) / elapsed, (b.z - a.z) / elapsed, now.yaw) : [0, 0];
     return { velocity: [v[0], 0, v[1]], angularVelocity: elapsed > 0 ? (b.yaw - a.yaw) / elapsed : 0,
-        trajectory: HORIZONS.map(horizon => {
-            const future = sampleRootMotion(track, time + horizon), yaw = future.yaw - now.yaw;
+        trajectory: horizons.map(horizon => {
+            const future = sampleRootMotion(track, time + horizon, looping), yaw = future.yaw - now.yaw;
             return { position: toLocal(future.x - now.x, future.z - now.z, now.yaw), facing: [Math.sin(yaw), Math.cos(yaw)] };
         }) };
 }
+/** Crop to the same source interval as playback; preserve the source coordinate frame. */
+export function cropRootMotion(track, start, end) {
+    validateRootMotion(track);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start || end > track.duration)
+        throw new Error('Invalid root motion range');
+    const samples = [sampleRootMotion(track, start), ...track.samples.filter(s => s.time > start && s.time < end), sampleRootMotion(track, end)]
+        .map(s => ({ ...s, time: s.time - start }));
+    return { version: 1, source: track.source, duration: end - start, samples };
+}

package/dist/core/schema.d.ts

@@ -0,0 +1,56 @@
+import type { Query, Vec3, TrajectoryPoint } from './types.js';
+export type Normalization = 'standard' | 'none';
+interface ChannelBase {
+    id: string;
+    weight: number;
+    normalization: Normalization;
+}
+export type FeatureChannel = ChannelBase & ({
+    kind: 'bone-position' | 'bone-velocity';
+    bone: string;
+} | {
+    kind: 'root-velocity';
+} | {
+    kind: 'trajectory-position' | 'trajectory-facing';
+    horizons: readonly number[];
+});
+export interface PoseSchema {
+    version: 1;
+    id: string;
+    channels: readonly FeatureChannel[];
+}
+export interface SchemaPose {
+    bones: Readonly<Record<string, {
+        position: Vec3;
+        velocity: Vec3;
+    }>>;
+    rootVelocity: Vec3;
+}
+export interface ChannelLayout {
+    channel: FeatureChannel;
+    offset: number;
+    dimensions: number;
+}
+export interface CompiledSchema {
+    schema: PoseSchema;
+    signature: string;
+    dimensions: number;
+    channels: readonly ChannelLayout[];
+    bones: readonly string[];
+    horizons: readonly number[];
+}
+export declare const LOCOMOTION_SCHEMA: PoseSchema;
+export declare function validateHorizons(input: readonly number[]): void;
+/** Strict JSON parsing: unsupported channels/options fail instead of being ignored. */
+export declare function parseSchema(input: unknown): PoseSchema;
+/** Canonical content identity, not a lossy hash. Order of channels is significant. */
+export declare function compileSchema(input: PoseSchema): CompiledSchema;
+/** One encoder shared by bake and runtime. Trajectory points follow the sorted union of horizons. */
+export declare class SchemaQueryBuilder {
+    readonly layout: CompiledSchema;
+    private horizonIndices;
+    constructor(schema?: PoseSchema);
+    features(pose: SchemaPose, trajectory: readonly TrajectoryPoint[], out?: Float32Array<ArrayBuffer>): Float32Array;
+    build(pose: SchemaPose, trajectory: readonly TrajectoryPoint[]): Query;
+}
+export {};

package/dist/core/schema.js

@@ -0,0 +1,123 @@
+export const LOCOMOTION_SCHEMA = {
+    version: 1, id: 'biped-locomotion', channels: [
+        { id: 'left-position', kind: 'bone-position', bone: 'leftFoot', weight: 1, normalization: 'standard' },
+        { id: 'right-position', kind: 'bone-position', bone: 'rightFoot', weight: 1, normalization: 'standard' },
+        { id: 'left-velocity', kind: 'bone-velocity', bone: 'leftFoot', weight: 1, normalization: 'standard' },
+        { id: 'right-velocity', kind: 'bone-velocity', bone: 'rightFoot', weight: 1, normalization: 'standard' },
+        { id: 'root-velocity', kind: 'root-velocity', weight: 1, normalization: 'standard' },
+        { id: 'future-position', kind: 'trajectory-position', horizons: [0.2, 0.4, 0.6], weight: 3, normalization: 'standard' },
+        { id: 'future-facing', kind: 'trajectory-facing', horizons: [0.2, 0.4, 0.6], weight: 3, normalization: 'standard' },
+    ],
+};
+for (const channel of LOCOMOTION_SCHEMA.channels) {
+    if ('horizons' in channel)
+        Object.freeze(channel.horizons);
+    Object.freeze(channel);
+}
+Object.freeze(LOCOMOTION_SCHEMA.channels);
+Object.freeze(LOCOMOTION_SCHEMA);
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const name = (v) => typeof v === 'string' && /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(v);
+export function validateHorizons(input) {
+    if (!Array.isArray(input) || input.length > 64 || [...input].some((v, i) => !Number.isFinite(v) || v <= 0 || v > 10 || (i > 0 && v <= input[i - 1])))
+        throw new Error('Schema: at most 64 horizons, increasing within (0, 10] seconds');
+}
+/** Strict JSON parsing: unsupported channels/options fail instead of being ignored. */
+export function parseSchema(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || Object.keys(input).some(k => !['version', 'id', 'channels'].includes(k))
+        || !Array.isArray(input.channels) || !input.channels.length || input.channels.length > 128)
+        throw new Error('Schema: invalid version/id/channels');
+    const ids = new Set();
+    const channels = [...input.channels].map(value => {
+        if (!record(value) || !name(value.id) || ids.has(value.id) || typeof value.weight !== 'number' || !Number.isFinite(Math.fround(value.weight)) || value.weight < 0 || (value.weight > 0 && Math.fround(value.weight) === 0)
+            || !['standard', 'none'].includes(String(value.normalization)))
+            throw new Error('Schema: invalid channel id/weight/normalization');
+        ids.add(value.id);
+        const common = { id: value.id, kind: value.kind, weight: value.weight, normalization: value.normalization };
+        let result;
+        if (value.kind === 'bone-position' || value.kind === 'bone-velocity') {
+            if (!name(value.bone) || value.bone === 'root')
+                throw new Error('Schema: invalid semantic bone role');
+            result = { ...common, bone: value.bone };
+        }
+        else if (value.kind === 'root-velocity')
+            result = common;
+        else if (value.kind === 'trajectory-position' || value.kind === 'trajectory-facing') {
+            if (!Array.isArray(value.horizons) || !value.horizons.length)
+                throw new Error('Schema: missing horizons');
+            validateHorizons(value.horizons);
+            result = { ...common, horizons: [...value.horizons] };
+        }
+        else
+            throw new Error('Schema: unsupported channel kind');
+        if (Object.keys(value).some(k => !Object.hasOwn(result, k)))
+            throw new Error('Schema: unsupported channel option');
+        return result;
+    });
+    if (!channels.some(c => c.weight > 0))
+        throw new Error('Schema: at least one positive weight required');
+    validateHorizons([...new Set(channels.flatMap(c => 'horizons' in c ? [...c.horizons] : []))].sort((a, b) => a - b));
+    return { version: 1, id: input.id, channels };
+}
+/** Canonical content identity, not a lossy hash. Order of channels is significant. */
+export function compileSchema(input) {
+    const schema = parseSchema(input), bones = new Set(), horizons = new Set();
+    let dimensions = 0;
+    const channels = schema.channels.map(channel => {
+        if ('bone' in channel)
+            bones.add(channel.bone);
+        if ('horizons' in channel)
+            channel.horizons.forEach(h => horizons.add(h));
+        const width = 'horizons' in channel ? 2 * channel.horizons.length : 3;
+        const layout = Object.freeze({ channel, offset: dimensions, dimensions: width });
+        dimensions += width;
+        if ('horizons' in channel)
+            Object.freeze(channel.horizons);
+        Object.freeze(channel);
+        return layout;
+    });
+    Object.freeze(schema.channels);
+    Object.freeze(schema);
+    return Object.freeze({ schema, signature: 'pose-schema-v1:' + JSON.stringify(schema), dimensions,
+        channels: Object.freeze(channels), bones: Object.freeze([...bones]), horizons: Object.freeze([...horizons].sort((a, b) => a - b)) });
+}
+/** One encoder shared by bake and runtime. Trajectory points follow the sorted union of horizons. */
+export class SchemaQueryBuilder {
+    layout;
+    horizonIndices;
+    constructor(schema = LOCOMOTION_SCHEMA) {
+        this.layout = compileSchema(schema);
+        this.horizonIndices = new Map(this.layout.horizons.map((h, i) => [h, i]));
+    }
+    features(pose, trajectory, out = new Float32Array(this.layout.dimensions)) {
+        if (trajectory.length !== this.layout.horizons.length || out.length !== this.layout.dimensions)
+            throw new Error('Invalid schema pose/trajectory dimensions');
+        const put = (values, offset, length) => {
+            if (!values || values.length !== length || !values.every(Number.isFinite))
+                throw new Error('Invalid schema feature values');
+            out.set(values, offset);
+        };
+        for (const { channel, offset } of this.layout.channels) {
+            if ('bone' in channel) {
+                const bone = Object.hasOwn(pose.bones, channel.bone) ? pose.bones[channel.bone] : undefined;
+                if (!bone)
+                    throw new Error('Missing semantic bone: ' + channel.bone);
+                put(channel.kind === 'bone-position' ? bone.position : bone.velocity, offset, 3);
+            }
+            else if ('horizons' in channel) {
+                channel.horizons.forEach((h, i) => {
+                    const point = trajectory[this.horizonIndices.get(h)];
+                    put(channel.kind === 'trajectory-position' ? point?.position : point?.facing, offset + i * 2, 2);
+                });
+            }
+            else
+                put(pose.rootVelocity, offset, 3);
+        }
+        if (!out.every(Number.isFinite))
+            throw new Error('Invalid schema float32 feature values');
+        return out;
+    }
+    build(pose, trajectory) {
+        return { features: this.features(pose, trajectory), schemaSignature: this.layout.signature };
+    }
+}

package/dist/core/search.d.ts

@@ -1,11 +1,17 @@
 import { type Database, type Match, type Query } from './types.js';
-export declare function defaultWeights(): Float32Array;
+import { type PoseSchema } from './schema.js';
+export declare function defaultWeights(schema?: PoseSchema): Float32Array;
 export declare class PoseSearch {
     readonly database: Database;
     private normalized;
+    private dimensions;
+    private rootOffset?;
     readonly weights: Float32Array;
-    constructor(database: Database, weights?: Float32Array<ArrayBufferLike>);
+    constructor(database: Database, weights?: Float32Array);
+    validateQuery(query: Query): void;
     normalize(query: Query): void;
     cost(index: number): number;
+    /** Physical error, independent of normalization/pose weights. Query must have been validated. */
+    rootVelocityError(index: number, query: Query): number;
     search(query: Query): Match | null;
 }

package/dist/core/search.js

@@ -1,44 +1,91 @@
 import { validateDatabase } from './database.js';
-import { DIMENSIONS } from './types.js';
-export function defaultWeights() {
-    const weights = new Float32Array(DIMENSIONS).fill(1);
-    weights.fill(3, 15);
+import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
+    const layout = compileSchema(schema), weights = new Float32Array(layout.dimensions);
+    for (const { channel, offset, dimensions } of layout.channels)
+        weights.fill(channel.weight, offset, offset + dimensions);
+    if (!weights.every(Number.isFinite))
+        throw new Error('Invalid feature weights');
     return weights;
 }
+const legacySignature = compileSchema(LOCOMOTION_SCHEMA).signature;
 export class PoseSearch {
     database;
-    normalized = new Float32Array(DIMENSIONS);
+    normalized;
+    dimensions;
+    rootOffset;
     weights;
-    constructor(database, weights = defaultWeights()) {
+    constructor(database, weights) {
         this.database = database;
         validateDatabase(database);
-        if (weights.length !== DIMENSIONS || !weights.every(v => Number.isFinite(v) && v >= 0))
+        this.dimensions = database.manifest.dimensions;
+        this.rootOffset = compileSchema(database.manifest.schema).channels.find(c => c.channel.kind === 'root-velocity')?.offset;
+        this.normalized = new Float32Array(this.dimensions);
+        weights ??= defaultWeights(database.manifest.schema);
+        if (weights.length !== this.dimensions || !weights.every(v => Number.isFinite(v) && v >= 0))
             throw new Error('Invalid feature weights');
         this.weights = weights.slice();
     }
-    normalize(query) {
-        if (query.features.length !== DIMENSIONS || !query.features.every(Number.isFinite))
+    validateQuery(query) {
+        if (query.schemaSignature !== this.database.manifest.schemaSignature && !(query.schemaSignature === undefined && this.database.manifest.schemaSignature === legacySignature))
+            throw new Error('Incompatible query schema');
+        if (query.features.length !== this.dimensions || !query.features.every(Number.isFinite))
             throw new Error('Invalid pose query');
+        if (query.allowTemporalReselection !== undefined && typeof query.allowTemporalReselection !== 'boolean')
+            throw new Error('Invalid temporal reselection option');
+        if (query.velocityTolerance !== undefined && (!Number.isFinite(query.velocityTolerance) || query.velocityTolerance < 0 || this.rootOffset === undefined))
+            throw new Error('Velocity tolerance requires a root-velocity channel and a finite nonnegative value');
+    }
+    normalize(query) {
+        this.validateQuery(query);
         const { mean, std } = this.database.manifest;
-        for (let j = 0; j < DIMENSIONS; j++)
+        for (let j = 0; j < this.dimensions; j++)
             this.normalized[j] = (query.features[j] - mean[j]) / std[j];
+        if (!this.normalized.every(Number.isFinite))
+            throw new Error('Invalid normalized pose query');
     }
     cost(index) {
         const { features } = this.database;
         let sum = 0;
-        for (let j = 0; j < DIMENSIONS; j++)
-            sum += this.weights[j] * (this.normalized[j] - features[index * DIMENSIONS + j]) ** 2;
+        for (let j = 0; j < this.dimensions; j++)
+            sum += this.weights[j] * (this.normalized[j] - features[index * this.dimensions + j]) ** 2;
         return sum;
     }
+    /** Physical error, independent of normalization/pose weights. Query must have been validated. */
+    rootVelocityError(index, query) {
+        if (this.rootOffset === undefined || !Number.isInteger(index) || index < 0 || index >= this.database.manifest.frames.length)
+            return Infinity;
+        const { mean, std } = this.database.manifest;
+        let squared = 0;
+        for (let axis = 0; axis < 3; axis++) {
+            const j = this.rootOffset + axis, value = this.database.features[index * this.dimensions + j] * std[j] + mean[j];
+            squared += (value - query.features[j]) ** 2;
+        }
+        return Math.sqrt(squared);
+    }
     search(query) {
         this.normalize(query);
         const { frames, clips } = this.database.manifest;
         let index = -1, cost = Infinity;
+        let velocityLimit = Infinity;
+        if (query.velocityTolerance !== undefined) {
+            let nearest = Infinity;
+            for (let i = 0; i < frames.length; i++) {
+                if (query.excludedClips?.has(frames[i].clip) || (query.gaits && !query.gaits.has(clips[frames[i].clip].gait)))
+                    continue;
+                nearest = Math.min(nearest, this.rootVelocityError(i, query));
+            }
+            // Sparse datasets retain a deterministic nearest-velocity fallback. Never
+            // expand the pool to arbitrary stationary poses just because coverage is missing.
+            velocityLimit = Math.max(query.velocityTolerance, nearest + 1e-6);
+        }
         for (let i = 0; i < frames.length; i++) {
             if (query.excludedClips?.has(frames[i].clip))
                 continue;
             if (query.gaits && !query.gaits.has(clips[frames[i].clip].gait))
                 continue;
+            if (query.velocityTolerance !== undefined && this.rootVelocityError(i, query) > velocityLimit)
+                continue;
             const score = this.cost(i);
             if (score < cost) {
                 index = i;

package/dist/core/types.d.ts

@@ -1,6 +1,9 @@
+import type { PoseSchema } from './schema.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 {
     id: string;
@@ -12,7 +15,13 @@ export interface Clip {
     /** Explicit authoring velocity for in-place clips, never inferred root motion. */
     nominalVelocity?: Vec3;
     /** Hips is a measured pelvis proxy, not a dedicated animation root. */
-    motionSource?: 'nominal' | 'hips';
+    motionSource?: 'nominal' | 'hips' | 'root';
+    /** Mean of measured local velocities; reference for demo controls, not gameplay authority. */
+    averageVelocity?: Vec3;
+    /** Source start in seconds; duration is the cropped duration. */
+    sourceStart?: number;
+    /** Optional absolute local orientation of the stripped rig root, as a static pose correction. */
+    rootOrientation?: Quat;
 }
 export interface Frame {
     clip: number;
@@ -21,8 +30,12 @@ export interface Frame {
 export interface DatabaseManifest {
     profileId?: string;
     profileSignature?: string;
-    version: 1;
-    dimensions: 27;
+    /** SHA-256 by public URL; verified by the loader. */
+    assetHashes?: Record<string, string>;
+    version: 2;
+    dimensions: number;
+    schema: PoseSchema;
+    schemaSignature: string;
     sampleRate: number;
     coordinates: 'meters-y-up-z-forward';
     horizons: readonly number[];
@@ -41,8 +54,13 @@ export interface Match extends Frame {
 }
 export interface Query {
     features: Float32Array;
+    schemaSignature?: string;
     gaits?: ReadonlySet<Gait>;
     excludedClips?: ReadonlySet<number>;
+    /** Optional root-velocity compatibility band in m/s. If uncovered, use nearest velocity before pose cost. */
+    velocityTolerance?: number;
+    /** False keeps the phase of the current loop; searches may still select another clip. Default true. */
+    allowTemporalReselection?: boolean;
 }
 export interface Pose {
     leftPosition: Vec3;

package/dist/core/types.js

@@ -1,2 +1,3 @@
+/** Legacy preset constants; dynamic consumers must use compileSchema. */
 export const DIMENSIONS = 27;
 export const HORIZONS = [0.2, 0.4, 0.6];

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './core/types.js';
+export * from './core/schema.js';
 export * from './core/features.js';
 export * from './core/database.js';
 export * from './core/search.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './core/types.js';
+export * from './core/schema.js';
 export * from './core/features.js';
 export * from './core/database.js';
 export * from './core/search.js';