@pose_flow/babylon 0.1.0 → 0.3.0

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,49 @@
 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 type RejectionReason = 'excluded-clip' | 'gait' | 'context' | 'entry-window' | 'excluded-window' | 'velocity';
+export interface CandidateCost extends Match {
+    channels: {
+        id: string;
+        cost: number;
+    }[];
+    velocityError: number | null;
+}
+export interface SearchReport {
+    best: Match | null;
+    candidates: CandidateCost[];
+    rejected: Record<RejectionReason, number>;
+    examples: {
+        index: number;
+        clip: number;
+        time: number;
+        reason: RejectionReason;
+    }[];
+    eligible: number;
+    total: number;
+    velocityLimit: number | null;
+}
+export declare function readCandidateTrajectory(database: Database, index: number): {
+    horizon: number;
+    position?: readonly [number, number];
+    facing?: readonly [number, number];
+}[];
 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;
+    /** Context/gait validity is separate from eligibility to enter at a sample. */
+    allowsClip(clip: number, query: Query): boolean;
+    allowsFrame(index: number, query: Query): boolean;
     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;
+    /** Opt-in diagnostic pass. Bounded output, exact ranking, no change to filters/weights. */
+    inspect(query: Query, limit?: number): SearchReport;
 }

package/dist/core/search.js

@@ -1,43 +1,121 @@
 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';
+import { matchesContext, validateContext, withinWindows } from './selection.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 function readCandidateTrajectory(database, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= database.manifest.frames.length)
+        throw new Error('Invalid candidate frame');
+    const { dimensions, mean, std } = database.manifest, layout = compileSchema(database.manifest.schema);
+    const points = new Map(layout.horizons.map(horizon => [horizon, { horizon }]));
+    for (const { channel, offset } of layout.channels)
+        if (channel.kind === 'trajectory-position' || channel.kind === 'trajectory-facing') {
+            channel.horizons.forEach((horizon, h) => {
+                const j = offset + h * 2, value = [database.features[index * dimensions + j] * std[j] + mean[j], database.features[index * dimensions + j + 1] * std[j + 1] + mean[j + 1]];
+                points.get(horizon)[channel.kind === 'trajectory-position' ? 'position' : 'facing'] = value;
+            });
+        }
+    return [...points.values()];
+}
 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.context !== undefined)
+            validateContext(query.context);
+        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');
+    }
+    /** Context/gait validity is separate from eligibility to enter at a sample. */
+    allowsClip(clip, query) {
+        const descriptor = this.database.manifest.clips[clip];
+        return !!descriptor && !query.excludedClips?.has(clip) && (!query.gaits || query.gaits.has(descriptor.gait)) && (!query.context || matchesContext(descriptor.context, query.context));
+    }
+    allowsFrame(index, query) {
+        const frame = this.database.manifest.frames[index], clip = this.database.manifest.clips[frame.clip];
+        return this.allowsClip(frame.clip, query) && withinWindows(frame.time, clip.entryWindows)
+            && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows));
+    }
+    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;
+        // Context is clip-level: resolve it once per clip, rather than once per
+        // sample in each of the velocity and ranking passes.
+        const eligibleClips = clips.map((_, clip) => this.allowsClip(clip, query));
+        const candidates = [];
         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))
+            const frame = frames[i], clip = clips[frame.clip];
+            if (eligibleClips[frame.clip] && withinWindows(frame.time, clip.entryWindows)
+                && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows)))
+                candidates.push(i);
+        }
+        let index = -1, cost = Infinity;
+        let velocityLimit = Infinity;
+        if (query.velocityTolerance !== undefined) {
+            let nearest = Infinity;
+            for (const i of candidates) {
+                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 (const i of candidates) {
+            if (query.velocityTolerance !== undefined && this.rootVelocityError(i, query) > velocityLimit)
                 continue;
             const score = this.cost(i);
             if (score < cost) {
@@ -47,4 +125,57 @@ export class PoseSearch {
         }
         return index < 0 ? null : { ...frames[index], index, cost };
     }
+    /** Opt-in diagnostic pass. Bounded output, exact ranking, no change to filters/weights. */
+    inspect(query, limit = 5) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+            throw new Error('Invalid diagnostic limit');
+        const best = this.search(query), { frames, clips } = this.database.manifest;
+        const rejected = { 'excluded-clip': 0, gait: 0, context: 0, 'entry-window': 0, 'excluded-window': 0, velocity: 0 };
+        const examples = [], candidates = [];
+        const layout = compileSchema(this.database.manifest.schema);
+        let nearest = Infinity, eligible = 0;
+        if (query.velocityTolerance !== undefined)
+            for (let i = 0; i < frames.length; i++)
+                if (this.allowsFrame(i, query))
+                    nearest = Math.min(nearest, this.rootVelocityError(i, query));
+        const velocityLimit = query.velocityTolerance === undefined ? null : Math.max(query.velocityTolerance, nearest + 1e-6);
+        for (let index = 0; index < frames.length; index++) {
+            const frame = frames[index], clip = clips[frame.clip];
+            let reason;
+            if (query.excludedClips?.has(frame.clip))
+                reason = 'excluded-clip';
+            else if (query.gaits && !query.gaits.has(clip.gait))
+                reason = 'gait';
+            else if (!matchesContext(clip.context, query.context))
+                reason = 'context';
+            else if (!withinWindows(frame.time, clip.entryWindows))
+                reason = 'entry-window';
+            else if (clip.excludedWindows !== undefined && withinWindows(frame.time, clip.excludedWindows))
+                reason = 'excluded-window';
+            else if (velocityLimit !== null && this.rootVelocityError(index, query) > velocityLimit)
+                reason = 'velocity';
+            if (reason) {
+                rejected[reason]++;
+                if (examples.length < limit)
+                    examples.push({ index, ...frame, reason });
+                continue;
+            }
+            eligible++;
+            const cost = this.cost(index);
+            if (candidates.length >= limit && cost >= candidates[candidates.length - 1].cost)
+                continue;
+            const channels = layout.channels.map(({ channel, offset, dimensions }) => {
+                let cost = 0;
+                for (let j = offset; j < offset + dimensions; j++)
+                    cost += this.weights[j] * (this.normalized[j] - this.database.features[index * this.dimensions + j]) ** 2;
+                return { id: channel.id, cost };
+            });
+            const candidate = { index, ...frame, cost, channels, velocityError: this.rootOffset === undefined ? null : this.rootVelocityError(index, query) };
+            const at = candidates.findIndex(c => c.cost > cost);
+            candidates.splice(at < 0 ? candidates.length : at, 0, candidate);
+            if (candidates.length > limit)
+                candidates.pop();
+        }
+        return { best, candidates, rejected, examples, eligible, total: frames.length, velocityLimit: Number.isFinite(velocityLimit) ? velocityLimit : null };
+    }
 }

package/dist/core/selection.d.ts

@@ -0,0 +1,24 @@
+/** Exact, consumer-defined semantic values. Missing keys never act as wildcards. */
+export type SelectionContext = Readonly<Record<string, string>>;
+/** Closed intervals, in seconds relative to the cropped playback clip. */
+export type TimeWindow = readonly [number, number];
+export interface SelectionMetadata {
+    context?: SelectionContext;
+    entryWindows?: readonly TimeWindow[];
+    exitWindows?: readonly TimeWindow[];
+    excludedWindows?: readonly TimeWindow[];
+}
+export declare function validateContext(value: unknown): asserts value is SelectionContext;
+export declare function matchesContext(metadata: SelectionContext | undefined, requested?: SelectionContext): boolean;
+export declare function withinWindows(time: number, windows: readonly TimeWindow[] | undefined): boolean;
+export declare function validateSelection(value: SelectionMetadata, duration?: number): void;
+import type { Database } from './types.js';
+export interface ContextBank {
+    id: string;
+    context: SelectionContext;
+    database: Database;
+}
+/** Route before searching; costs from independent normalizations are never compared.
+ * Caller must use the selected bank's schema, compatible rig/player and matcher.
+ */
+export declare function selectContextBank(banks: readonly ContextBank[], context: SelectionContext): ContextBank | null;

package/dist/core/selection.js

@@ -0,0 +1,41 @@
+export function validateContext(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || !Object.entries(value).every(([k, v]) => k.trim().length > 0 && typeof v === 'string' && v.trim().length > 0))
+        throw new Error('Invalid selection context');
+}
+export function matchesContext(metadata, requested = {}) {
+    return Object.entries(requested).every(([key, value]) => metadata !== undefined && Object.hasOwn(metadata, key) && metadata[key] === value);
+}
+export function withinWindows(time, windows) {
+    return windows === undefined || windows.some(([start, end]) => time >= start && time <= end);
+}
+export function validateSelection(value, duration = Infinity) {
+    if (value.context !== undefined)
+        validateContext(value.context);
+    for (const key of ['entryWindows', 'exitWindows', 'excludedWindows']) {
+        const windows = value[key];
+        if (windows !== undefined && (!Array.isArray(windows) || !windows.every(w => Array.isArray(w) && w.length === 2 && w.every(Number.isFinite)
+            && w[0] >= 0 && w[1] >= w[0] && w[1] <= duration)))
+            throw new Error('Invalid selection windows: ' + key);
+    }
+}
+/** Route before searching; costs from independent normalizations are never compared.
+ * Caller must use the selected bank's schema, compatible rig/player and matcher.
+ */
+export function selectContextBank(banks, context) {
+    validateContext(context);
+    const ids = new Set();
+    let selected = null;
+    for (const bank of banks) {
+        if (!bank.id.trim() || ids.has(bank.id))
+            throw new Error('Invalid/duplicate context bank id');
+        ids.add(bank.id);
+        validateContext(bank.context);
+        if (!matchesContext(bank.context, context))
+            continue;
+        if (selected)
+            throw new Error('Ambiguous context bank selection');
+        selected = bank;
+    }
+    return selected;
+}

package/dist/core/types.d.ts

@@ -1,8 +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;
@@ -12,7 +16,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 +31,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[];
@@ -40,9 +54,15 @@ export interface Match extends Frame {
     cost: number;
 }
 export interface Query {
+    context?: SelectionContext;
     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,7 +1,11 @@
 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';
 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

@@ -1,7 +1,11 @@
 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';
 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); }
+}