@pose_flow/babylon 0.1.0 → 0.3.0

package/dist/core/database.js

@@ -1,59 +1,97 @@
-import { DIMENSIONS, HORIZONS } from './types.js';
+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 (m.version !== 1 || m.dimensions !== DIMENSIONS || m.coordinates !== 'meters-y-up-z-forward'
-        || m.horizons.length !== 3 || m.horizons.some((v, i) => v !== HORIZONS[i]))
-        throw new Error('Unsupported pose database schema');
-    if (!Number.isFinite(m.sampleRate) || m.sampleRate <= 0 || !m.frames.length || !m.clips.length
-        || db.features.length !== m.frames.length * DIMENSIONS)
+    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 (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))
+    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 (ids.has(clip.id) || !clip.id || !clip.file || !clip.animation || !Number.isFinite(clip.duration) || clip.duration <= 0
+        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 (!Number.isInteger(frame.clip) || !m.clips[frame.clip] || !Number.isFinite(frame.time)
+        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');
     }
 }
-export function buildDatabase(manifest, raw) {
-    const count = manifest.frames.length;
-    if (!count || raw.length !== count * DIMENSIONS || !raw.every(Number.isFinite))
+/** 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);
+    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;
+        mean[i % dimensions] += raw[i] / count;
     for (let i = 0; i < raw.length; i++)
-        std[i % DIMENSIONS] += (raw[i] - mean[i % DIMENSIONS]) ** 2 / count;
-    // Constant channels carry no measured variation. A unit scale avoids amplifying
-    // unsupported trajectories (e.g. turns absent from the dataset) by 10,000×.
-    for (let j = 0; j < DIMENSIONS; j++)
+        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]);
-    const features = Float32Array.from(raw, (v, i) => (v - mean[i % DIMENSIONS]) / std[i % DIMENSIONS]);
-    const db = { manifest: { ...manifest, version: 1, dimensions: DIMENSIONS, coordinates: 'meters-y-up-z-forward', horizons: HORIZONS, mean, std }, features };
+    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) {
+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, features };
+    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/core/features.d.ts

@@ -12,4 +12,4 @@ export interface TrajectoryInput {
     turnSpeed: number;
 }
 /** Prediction only: never writes to the gameplay controller. Uses fixed substeps. */
-export declare function predictTrajectory(input: TrajectoryInput): TrajectoryPoint[];
+export declare function predictTrajectory(input: TrajectoryInput, horizons?: readonly number[]): TrajectoryPoint[];

package/dist/core/features.js

@@ -1,14 +1,11 @@
 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)) {
-    if (trajectory.length !== 3 || out.length !== DIMENSIONS)
-        throw new Error('Expected 3 trajectory points and 27 features');
-    out.set(pose.leftPosition, 0);
-    out.set(pose.rightPosition, 3);
-    out.set(pose.leftVelocity, 6);
-    out.set(pose.rightVelocity, 9);
-    out.set(pose.rootVelocity, 12);
-    trajectory.forEach((point, i) => { out.set(point.position, 15 + i * 2); out.set(point.facing, 21 + i * 2); });
-    return out;
+    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) {
@@ -16,13 +13,14 @@ export function toLocal(x, z, 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) {
+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) {
+    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);

package/dist/core/inertialization.d.ts

@@ -0,0 +1,3 @@
+/** Critically damped residual. With zero initial velocity, offset halves at halfLife.
+ * Does not integrate gameplay/root displacement. */
+export declare function decayInertialOffset(offset: number, velocity: number, elapsed: number, halfLife: number): number;

package/dist/core/inertialization.js

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

package/dist/core/profile.d.ts

@@ -1,6 +1,8 @@
-import type { Gait, Vec3 } from './types.js';
+import type { Gait, Quat, Vec3 } from './types.js';
+import { type PoseSchema } from './schema.js';
+import { type SelectionMetadata, type SelectionContext } from './selection.js';
 export interface CharacterProfile {
-    version: 1;
+    version: 2;
     id: string;
     label: string;
     assetBase: string;
@@ -10,14 +12,26 @@ export interface CharacterProfile {
     sampleRate: number;
     rig: {
         root: string;
-        leftFoot: string;
-        rightFoot: string;
-    };
+    } & Record<string, string>;
+    schema: string;
+    animationSet: string;
     /** Source animation node -> model node; name mapping does not perform retargeting. */
     boneMap?: Record<string, string>;
     /** Model node whose position/heading tracks are excluded by the player. */
     stripRoot?: string;
-    clips: {
+    /** Exact model node names for optional runtime layers. */
+    masks?: Record<string, readonly string[]>;
+    /** Lab-only presentation preview. Does not authorize a gameplay action. */
+    layerPreview?: {
+        baseMask: string;
+        overlayMask: string;
+        context: SelectionContext;
+    };
+}
+export interface AnimationSet {
+    version: 1;
+    id: string;
+    clips: (SelectionMetadata & {
         id: string;
         file: string;
         animation: string;
@@ -25,12 +39,24 @@ export interface CharacterProfile {
         looping: boolean;
         nominalVelocity?: Vec3;
         motionFile?: string;
-    }[];
+        rootOrientation?: Quat;
+        /** Source interval in seconds. */
+        range?: readonly [number, number];
+    })[];
+}
+export interface ResolvedProfile extends CharacterProfile {
+    schemaDefinition: PoseSchema;
+    clips: AnimationSet['clips'];
+    setId: string;
 }
+export declare function parseRootOrientation(value: unknown): Quat;
 /** Read untrusted JSON as unknown; report a configuration error before loading assets. */
 export declare function parseProfile(input: unknown): CharacterProfile;
+export declare function parseAnimationSet(input: unknown): AnimationSet;
+/** Resolve external configuration explicitly; core performs no I/O. */
+export declare function resolveProfile(profile: CharacterProfile, schemaInput: unknown, setInput: unknown): ResolvedProfile;
 /** Deterministic configuration fingerprint; detects stale banks, not a security signature. */
-export declare function profileSignature(profile: CharacterProfile): string;
+export declare function profileSignature(profile: ResolvedProfile): string;
 /** Suggestions only: ambiguity is returned to the caller, never silently resolved. */
 export declare function suggestRig(names: readonly string[]): Record<'root' | 'leftFoot' | 'rightFoot', string[]>;
 /** Semantic availability, independent of character/clip names. Preserve optional actions. */

package/dist/core/profile.js

@@ -1,42 +1,81 @@
+import { compileSchema, parseSchema } from './schema.js';
+import { validateContext, validateSelection } from './selection.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const name = (v) => typeof v === 'string' && v.trim().length > 0;
 const asset = (v) => name(v) && !v.includes('\\') && !v.includes('..') && !/[?#:]/.test(v);
+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.masks !== undefined && (!record(input.masks) || !Object.entries(input.masks).length || !Object.entries(input.masks).every(([key, values]) => name(key)
+        && Array.isArray(values) && values.length > 0 && values.every(name) && new Set(values).size === values.length)))
+        throw new Error('Profile: invalid masks');
+    if (input.layerPreview !== undefined) {
+        const preview = input.layerPreview, masks = input.masks;
+        if (!record(preview) || !name(preview.baseMask) || !name(preview.overlayMask) || !masks || !Object.hasOwn(masks, preview.baseMask) || !Object.hasOwn(masks, preview.overlayMask)
+            || masks[preview.baseMask].some(node => masks[preview.overlayMask].includes(node)))
+            throw new Error('Profile: layer preview requires two disjoint masks');
+        validateContext(preview.context);
+        if (!Object.keys(preview.context).length)
+            throw new Error('Profile: layer preview requires explicit context');
+    }
     if (input.boneMap !== undefined && (!record(input.boneMap) || !Object.entries(input.boneMap).every(([k, v]) => name(k) && name(v)) || new Set(Object.values(input.boneMap)).size !== Object.values(input.boneMap).length))
         throw new Error('Profile: boneMap must map distinct nonempty names');
-    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');
+        validateSelection(clip, Array.isArray(clip.range) ? clip.range[1] - clip.range[0] : Infinity);
         const nominal = clip.nominalVelocity !== undefined, measured = clip.motionFile !== undefined;
         if (nominal === measured)
             throw new Error(`Profile ${clip.id}: declare exactly one of nominalVelocity or motionFile`);
         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/scenario.d.ts

@@ -0,0 +1,29 @@
+import { type MatcherOptions, type Playback } from './controller.js';
+import type { Database, Gait, Query, Vec3 } from './types.js';
+export interface RecordedQuery extends Omit<Query, 'features' | 'gaits' | 'excludedClips'> {
+    features: number[];
+    gaits?: Gait[];
+    excludedClips?: number[];
+}
+export interface ScenarioFrame {
+    dt: number;
+    query: RecordedQuery;
+    controller: {
+        position: Vec3;
+        yaw: number;
+    };
+    playback: Omit<Playback, 'match'>;
+    presentation?: Omit<Playback, 'match'>;
+}
+export interface MotionScenario {
+    version: 1;
+    databaseIdentity: string;
+    matcherOptions: Partial<MatcherOptions>;
+    frames: ScenarioFrame[];
+}
+/** Content identity for exact replay, not a cryptographic/security signature. */
+export declare function scenarioDatabaseIdentity(db: Database): string;
+export declare function restoreScenarioQuery(recorded: RecordedQuery): Query;
+export declare function captureScenarioFrame(dt: number, query: Query, position: Vec3, yaw: number, playback: Playback, presentation?: Playback): ScenarioFrame;
+/** Import only validated local data, never execute content from a scenario file. */
+export declare function parseMotionScenario(input: unknown, db: Database): MotionScenario;

package/dist/core/scenario.js

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

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 {};