@pose_flow/babylon 0.1.0 → 0.2.0

package/dist/PUBLISHING.md

@@ -0,0 +1,108 @@
+# Publicar @pose_flow/babylon no npm
+
+Fonte deste documento: `docs/PUBLISHING.md`. O build gera `dist/PUBLISHING.md`, incluído no pacote npm. Atualizar o documento de origem, nunca a cópia.
+
+## Preparar uma atualização
+
+Executar na raiz do repositório da biblioteca. Os comandos abaixo não pertencem ao projeto consumidor.
+
+```powershell
+Set-Location D:\motion_match
+npm ci
+npm run typecheck
+npm test
+```
+
+Antes da versão, atualizar `docs/AI_USAGE.md` para toda implementação/correção e este documento se o processo mudar. Não prosseguir se algum comando falhar.
+
+## Aumentar a versão
+
+### Marco planejado de estabilidade 1.0.0
+
+O roadmap do repositório exige uma release estável 1.0.0 como entrega final. A série atual 0.1.x não recebe essa classificação por esta atualização documental. Não aumentar a versão agora por causa do planejamento.
+
+Antes da 1.0.0, concluir os critérios de docs/ROADMAP.md, preparar candidatos 1.0.0-rc.N e verificar instalação, ferramentas offline e reprodução em consumidor independente. Registrar evidências, matriz de suporte, metas/resultados de desempenho, notas da versão e migração dos contratos 0.x. Defeitos críticos ou de alta severidade no escopo suportado bloqueiam a release. Executar as verificações abaixo para o pacote candidato e novamente para o pacote final; conferir a versão exata instalada, sem presumir que latest aponta para um candidato.
+
+Após aprovação dos critérios, a entrega final deve ser 1.0.0, em vez de aplicar automaticamente o incremento patch descrito para manutenção de 0.x. Publicar somente mediante pedido explícito do mantenedor e conferir instalação da versão publicada. Após 1.0.0, preservar contratos em patch/minor; quebras exigem major e guia de migração. A topologia dos pacotes/CLI será definida na etapa de distribuição; os arquivos e comandos atuais abaixo descrevem somente o pacote existente.
+
+### Mudança de formatos na Fase 1 (ainda sem publicação)
+
+O código local usa banco/perfil v2 e schema v1. Antes da próxima release, escolher uma versão 0.x apropriada à quebra de contrato e publicar as instruções de migração incluídas em AI_USAGE.md; não tratar esta entrega como simples correção patch. A versão em package.json não foi aumentada nesta implementação. Esse era o conteúdo na Fase 1. A Fase 2 abaixo inclui CLI offline; JSON externos e bancos continuam fora do pacote.
+
+### Manutenção da série atual
+
+A publicação de 0.1.0 foi informada pelo mantenedor. Versões já publicadas não podem ser sobrescritas. A inclusão destes documentos exige uma nova publicação para chegar aos consumidores.
+
+Para uma correção ou atualização de documentação, executar **uma única vez**:
+
+```powershell
+npm version patch --no-git-tag-version
+```
+
+Se a versão local ainda for 0.1.0, isso gera 0.1.1 e atualiza package.json/package-lock.json, sem criar commit ou tag. Não repetir o comando se já aumentou a versão para essa entrega. Para funcionalidade compatível, avaliar `npm version minor --no-git-tag-version`; para quebra de contrato, planejar a versão e a migração explicitamente, especialmente enquanto a lib estiver em 0.x.
+
+## Build e inspeção
+
+```powershell
+npm run build
+npm run check:docs
+npm pack --dry-run --ignore-scripts
+```
+
+Conferir a versão e os arquivos listados: biblioteca JS/tipos em dist/, dist/AI_USAGE.md, dist/PUBLISHING.md, README.md, LICENSE e package.json. Personagens, animações, bancos, perfis de exemplo, testes e fontes TypeScript não entram no pacote. Ferramentas compiladas e seu runtime interno em dist/offline/ acompanham a CLI.
+
+O `--ignore-scripts` acima é usado **somente após o build explícito**, para inspecionar sem compilá-lo novamente. No fluxo normal de `npm pack` e `npm publish`, o `prepack` executa o build e copia a documentação atual. Não usar `--ignore-scripts` na publicação normal.
+
+Para gerar um .tgz local e testar a instalação antes de publicar:
+
+```powershell
+npm pack
+```
+
+No projeto de teste, instalar o caminho do .tgz exibido pelo comando anterior. Não assumir o nome/versão do arquivo. Testar imports do núcleo/adaptador e localizar o tutorial em node_modules/@pose_flow/babylon/dist/AI_USAGE.md.
+
+## Autenticar e publicar
+
+```powershell
+npm login
+npm whoami
+npm publish --access public
+```
+
+Verificar a conta e a permissão no escopo `pose_flow`. Concluir a autenticação de dois fatores solicitada pelo npm. Não armazenar senha, token ou códigos de recuperação no repositório/documentos. Uma IA só deve executar a publicação se o mantenedor pedir essa ação explicitamente; a autenticação interativa é feita pelo mantenedor.
+
+Depois, conferir o registro:
+
+```powershell
+npm view @pose_flow/babylon version
+```
+
+No projeto consumidor:
+
+```powershell
+npm install @pose_flow/babylon@latest
+```
+
+Conferir a versão efetivamente instalada no lockfile e ler o tutorial daquela versão. Não copiar dist/ manualmente para node_modules.
+
+## Erros comuns
+
+- E403 com mensagem de 2FA: conferir 2FA da conta e autenticar novamente. Não é erro do conteúdo do tarball.
+- Sem permissão no escopo: conferir acesso à organização pose_flow e nome do pacote.
+- Versão já existente: consultar a versão publicada e preparar uma versão nova; não tentar sobrescrever.
+- Tutorial ausente/desatualizado: editar docs/AI_USAGE.md, executar build e check:docs, inspecionar o pacote.
+
+## Referências oficiais
+
+- [npm publish](https://docs.npmjs.com/cli/v11/commands/npm-publish/): publicação e versões imutáveis.
+- [npm version](https://docs.npmjs.com/cli/v11/commands/npm-version/): incremento de versão e opção sem tag Git.
+- [Lifecycle scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts/): prepack.
+- [Configurar 2FA](https://docs.npmjs.com/configuring-two-factor-authentication/).
+
+## CLI offline — Fase 2, sem publicação
+
+O build agora executa também `tsc -p tsconfig.offline.json`. `bin.pose-flow` aponta para `dist/offline/tools/cli.js`; `dist/offline/src/` contém o runtime interno das ferramentas. Os exports públicos permanecem dist/index.js e dist/babylon.js. Não importar caminhos internos da CLI como API.
+
+`@babylonjs/loaders@7.54.3` passou de devDependency para dependency para permitir inspeção/bake após instalar. Babylon core continua peerDependency. Lockfile atualizado; versão não alterada. Conferir CLI/runtime interno e ambos os guias no dry-run. Testar instalação em diretório independente e executar `npx --no-install pose-flow validate --profile public/profiles/rig.json` e `npx --no-install pose-flow bake --profile public/profiles/rig.json`. O teste deve ficar fora do MMORPG protegido.
+
+A CLI agora inclui `prepare --config preparation.json`, com os módulos compilados prepare/glb/rig. Conferir esses módulos no pacote. Os scripts Python de conversão e o experimento Blender não são distribuídos; Blender não é dependência do runtime nem da CLI GLB. Testar também prepare → validate → bake no pacote instalado com GLB de entrada do consumidor. `--check-bind` é opcional e exige dados de skin/bind suportados. O pacote continua sem assets, perfis, bancos ou publicação automática.

package/dist/babylon.d.ts

@@ -1,5 +1,6 @@
 import { AnimationGroup, TransformNode, type Scene } from '@babylonjs/core';
 import type { Clip, Playback, Pose } from './index.js';
+import { type PoseSchema, type SchemaPose } from './core/schema.js';
 /** Clone onto a target rig. Two playback slots allow crossfade between times of the same clip. */
 export declare class BabylonMotionPlayer {
     private scene;
@@ -11,18 +12,26 @@ export declare class BabylonMotionPlayer {
     private tracks;
     private active?;
     private disposed;
+    private strippedRoot?;
+    private rootRestRotation?;
     constructor(scene: Scene, clips: readonly Clip[], sources: ReadonlyMap<string, AnimationGroup>, nodes: ReadonlyMap<string, TransformNode>, fadeSeconds?: number, rootName?: string);
     private create;
     update(state: Playback, dt: number): void;
     private clear;
     dispose(): void;
 }
-/** Sample AFTER scene animation evaluation. Measures visible feet, including crossfade. */
-export declare class BabylonPoseReader {
+/** Sample AFTER scene animation evaluation. Semantic roles are defined by the schema. */
+export declare class BabylonSchemaPoseReader {
     private root;
-    private left;
-    private right;
     private previous?;
+    private nodes;
+    constructor(root: TransformNode, bones: ReadonlyMap<string, TransformNode>, schema: PoseSchema);
+    reset(): void;
+    read(dt: number): SchemaPose;
+}
+/** Compatibility reader for the original two-foot preset. */
+export declare class BabylonPoseReader {
+    private reader;
     constructor(root: TransformNode, left: TransformNode, right: TransformNode);
     reset(): void;
     read(dt: number): Pose;

package/dist/babylon.js

@@ -1,4 +1,24 @@
-import { AnimationGroup, Matrix, Vector3 } from '@babylonjs/core';
+import { Animation, AnimationGroup, Matrix, Quaternion, Vector3 } from '@babylonjs/core';
+import { compileSchema, LOCOMOTION_SCHEMA } from './core/schema.js';
+import { parseRootOrientation } from './core/profile.js';
+/** Constant authoring orientation belongs to the pose; varying root heading belongs to gameplay. */
+function constantRootRotation(animation) {
+    const keys = animation.getKeys();
+    if (!keys.length || keys.some(k => k.inTangent !== undefined || k.outTangent !== undefined))
+        return undefined;
+    const rotation = (value) => animation.targetProperty === 'rotationQuaternion' && value instanceof Quaternion ? value.clone()
+        : animation.targetProperty === 'rotation' && value instanceof Vector3 ? Quaternion.FromEulerVector(value) : undefined;
+    const first = rotation(keys[0].value);
+    if (!first || !first.asArray().every(Number.isFinite) || first.length() < 1e-8)
+        return undefined;
+    first.normalize();
+    for (const key of keys) {
+        const q = rotation(key.value);
+        if (!q || !q.asArray().every(Number.isFinite) || q.length() < 1e-8 || Math.abs(Quaternion.Dot(first, q.normalize())) < 1 - 1e-8)
+            return undefined;
+    }
+    return first;
+}
 /** Clone onto a target rig. Two playback slots allow crossfade between times of the same clip. */
 export class BabylonMotionPlayer {
     scene;
@@ -10,6 +30,8 @@ export class BabylonMotionPlayer {
     tracks = [];
     active;
     disposed = false;
+    strippedRoot;
+    rootRestRotation;
     constructor(scene, clips, sources, nodes, fadeSeconds = 0.15, rootName = 'root') {
         this.scene = scene;
         this.clips = clips;
@@ -19,27 +41,60 @@ export class BabylonMotionPlayer {
         this.rootName = rootName;
         if (!Number.isFinite(fadeSeconds) || fadeSeconds < 0)
             throw new Error('Invalid crossfade duration');
-        for (const clip of clips)
-            if (!sources.has(clip.id))
+        for (const clip of clips) {
+            const source = sources.get(clip.id);
+            if (!source)
                 throw new Error(`Missing animation source: ${clip.id}`);
+            const fps = source.targetedAnimations[0]?.animation.framePerSecond, start = clip.sourceStart ?? 0;
+            if (!Number.isFinite(start) || start < 0 || !Number.isFinite(clip.duration) || clip.duration <= 0 || !fps
+                || start + clip.duration > (source.to - source.from) / fps + 1e-5)
+                throw new Error(`Invalid source range: ${clip.id}`);
+        }
+        this.strippedRoot = [...nodes.values()].find(n => n.name === rootName);
+        if (this.strippedRoot) {
+            this.strippedRoot.rotationQuaternion ??= Quaternion.FromEulerVector(this.strippedRoot.rotation);
+            this.rootRestRotation = this.strippedRoot.rotationQuaternion.clone();
+        }
+        for (const clip of clips)
+            if (clip.rootOrientation !== undefined) {
+                parseRootOrientation(clip.rootOrientation);
+                if (!this.strippedRoot)
+                    throw new Error('rootOrientation requires a mapped stripped root');
+            }
     }
     create(clip, time) {
         const source = this.sources.get(this.clips[clip].id);
         const group = new AnimationGroup(`mm-${this.clips[clip].id}-${this.tracks.length}`, this.scene);
+        let rootRotation = this.rootRestRotation?.clone();
         for (const targeted of source.targetedAnimations) {
             const node = this.nodes.get(targeted.target.name);
             if (!node)
                 continue;
             const property = targeted.animation.targetProperty;
-            // Gameplay owns horizontal root displacement AND heading. Preserve vertical bob only on other bones.
-            if (node.name === this.rootName && (property === 'position' || property === 'rotationQuaternion' || property === 'rotation'))
-                continue;
+            if (node === this.strippedRoot) {
+                if (property === 'position' || property.startsWith('position.'))
+                    continue;
+                if (property === 'rotationQuaternion' || property === 'rotation' || property.startsWith('rotation.') || property.startsWith('rotationQuaternion.')) {
+                    rootRotation = constantRootRotation(targeted.animation) ?? rootRotation;
+                    continue;
+                }
+            }
             group.addTargetedAnimation(targeted.animation, node);
         }
         if (!group.targetedAnimations.length) {
             group.dispose();
             throw new Error('No matching rig animation tracks');
         }
+        const correction = this.clips[clip].rootOrientation;
+        if (correction)
+            rootRotation = Quaternion.FromArray([...correction]).normalize();
+        if (this.strippedRoot && rootRotation) {
+            // An explicit constant binding also restores the baseline after a clip with
+            // another orientation, and participates in the same weighted crossfade.
+            const rotation = new Animation('mm-root-pose', 'rotationQuaternion', source.targetedAnimations[0].animation.framePerSecond, Animation.ANIMATIONTYPE_QUATERNION);
+            rotation.setKeys([{ frame: source.from, value: rootRotation }, { frame: source.to, value: rootRotation.clone() }]);
+            group.addTargetedAnimation(rotation, this.strippedRoot);
+        }
         // Paused groups still participate in Babylon's late weighted bindings when
         // goToFrame(frame, true) is called. Speed zero alone resets on scene.render().
         group.start(true, 0);
@@ -79,9 +134,10 @@ export class BabylonMotionPlayer {
         const total = this.tracks.reduce((sum, t) => sum + t.weight, 0);
         for (const track of this.tracks) {
             const descriptor = this.clips[track.clip], group = track.group;
-            const time = descriptor.looping ? track.time % descriptor.duration : Math.min(track.time, descriptor.duration);
+            const time = descriptor.looping ? ((track.time % descriptor.duration) + descriptor.duration) % descriptor.duration : Math.max(0, Math.min(track.time, descriptor.duration));
             group.setWeightForAllAnimatables(total > 0 ? track.weight / total : (track === this.active ? 1 : 0));
-            group.goToFrame(group.from + (group.to - group.from) * time / descriptor.duration, true);
+            const source = this.sources.get(descriptor.id), fps = source.targetedAnimations[0].animation.framePerSecond;
+            group.goToFrame(source.from + ((descriptor.sourceStart ?? 0) + time) * fps, true);
         }
         this.tracks = this.tracks.filter(track => {
             if (track !== this.active && track.weight < 0.001) {
@@ -95,32 +151,51 @@ export class BabylonMotionPlayer {
         t.group.dispose(); this.tracks = []; this.active = undefined; }
     dispose() { this.clear(); this.disposed = true; }
 }
-/** Sample AFTER scene animation evaluation. Measures visible feet, including crossfade. */
-export class BabylonPoseReader {
+/** Sample AFTER scene animation evaluation. Semantic roles are defined by the schema. */
+export class BabylonSchemaPoseReader {
     root;
-    left;
-    right;
     previous;
-    constructor(root, left, right) {
+    nodes;
+    constructor(root, bones, schema) {
         this.root = root;
-        this.left = left;
-        this.right = right;
+        const roles = compileSchema(schema).bones;
+        for (const role of roles)
+            if (!bones.has(role))
+                throw new Error('Missing schema bone node: ' + role);
+        this.nodes = new Map(roles.map(role => [role, bones.get(role)]));
     }
     reset() { this.previous = undefined; }
     read(dt) {
         if (!Number.isFinite(dt) || dt < 0)
             throw new Error('Invalid pose delta');
         this.root.computeWorldMatrix(true);
-        this.left.computeWorldMatrix(true);
-        this.right.computeWorldMatrix(true);
-        const root = this.root.getAbsolutePosition().clone(), left = this.left.getAbsolutePosition().clone(), right = this.right.getAbsolutePosition().clone();
+        const root = this.root.getAbsolutePosition().clone(), positions = new Map();
+        for (const [role, node] of this.nodes) {
+            node.computeWorldMatrix(true);
+            positions.set(role, node.getAbsolutePosition().clone());
+        }
         const inverse = Matrix.Invert(this.root.getWorldMatrix());
         // Vector transform through inverse includes inverse model scale: consumers should keep root scale 1.
         const tuple = (v) => [v.x, v.y, v.z];
         const velocity = (value, previous) => previous && dt > 0 ? Vector3.TransformNormal(value.subtract(previous).scale(1 / dt), inverse) : Vector3.Zero();
-        const pose = { leftPosition: tuple(Vector3.TransformCoordinates(left, inverse)), rightPosition: tuple(Vector3.TransformCoordinates(right, inverse)),
-            leftVelocity: tuple(velocity(left, this.previous?.left)), rightVelocity: tuple(velocity(right, this.previous?.right)), rootVelocity: tuple(velocity(root, this.previous?.root)) };
-        this.previous = { left, right, root };
+        const bones = Object.fromEntries([...positions].map(([role, position]) => [role, {
+                position: tuple(Vector3.TransformCoordinates(position, inverse)), velocity: tuple(velocity(position, this.previous?.bones.get(role))),
+            }]));
+        const pose = { bones, rootVelocity: tuple(velocity(root, this.previous?.root)) };
+        this.previous = { bones: positions, root };
         return pose;
     }
 }
+/** Compatibility reader for the original two-foot preset. */
+export class BabylonPoseReader {
+    reader;
+    constructor(root, left, right) {
+        this.reader = new BabylonSchemaPoseReader(root, new Map([['leftFoot', left], ['rightFoot', right]]), LOCOMOTION_SCHEMA);
+    }
+    reset() { this.reader.reset(); }
+    read(dt) {
+        const pose = this.reader.read(dt);
+        return { leftPosition: pose.bones.leftFoot.position, rightPosition: pose.bones.rightFoot.position,
+            leftVelocity: pose.bones.leftFoot.velocity, rightVelocity: pose.bones.rightFoot.velocity, rootVelocity: pose.rootVelocity };
+    }
+}

package/dist/core/controller.js

@@ -25,6 +25,8 @@ export class MotionMatcher {
     update(dt, query) {
         if (!Number.isFinite(dt) || dt < 0)
             throw new Error('Invalid delta time');
+        // Validate identity even while continuity skips a search this frame.
+        this.search.validateQuery(query);
         let switched = false, ended = false;
         for (const [clip, remaining] of this.completed) {
             if (remaining <= dt)
@@ -58,7 +60,10 @@ export class MotionMatcher {
                     gap = Math.min(gap, duration - gap);
                 const distant = best.clip !== this.clip || gap > this.options.timeSeparation;
                 const better = current < 0 || best.cost + this.options.jumpPenalty < this.search.cost(current) * (1 - this.options.improvement);
-                if (current < 0 || !allowed || ended || (distant && better && this.sinceSwitch >= this.options.minimumHold)) {
+                const incompatibleVelocity = current >= 0 && distant && this.sinceSwitch >= this.options.minimumHold && query.velocityTolerance !== undefined
+                    && this.search.rootVelocityError(current, query) > Math.max(query.velocityTolerance, this.search.rootVelocityError(best.index, query) + 1e-6);
+                const mayReselectTime = query.allowTemporalReselection !== false || best.clip !== this.clip || !this.database.manifest.clips[best.clip].looping;
+                if (current < 0 || !allowed || ended || (mayReselectTime && (incompatibleVelocity || (distant && better && this.sinceSwitch >= this.options.minimumHold)))) {
                     this.clip = best.clip;
                     this.time = best.time;
                     this.sinceSwitch = 0;

package/dist/core/database.d.ts

@@ -1,6 +1,12 @@
 import { type Database, type DatabaseManifest } from './types.js';
+import { type PoseSchema } from './schema.js';
 export declare function validateDatabase(db: Database): void;
-export declare function buildDatabase(manifest: Omit<DatabaseManifest, 'version' | 'dimensions' | 'coordinates' | 'horizons' | 'mean' | 'std'>, raw: Float32Array): Database;
+type BuildManifest = Omit<DatabaseManifest, 'version' | 'dimensions' | 'schema' | 'schemaSignature' | 'coordinates' | 'horizons' | 'mean' | 'std'>;
+/** Omitting schema selects the legacy biped preset. New data is always v2. */
+export declare function buildDatabase(manifest: BuildManifest, raw: Float32Array, schema?: PoseSchema): Database;
 /** Binary format is explicitly little endian float32; version/layout live in manifest. */
 export declare function encodeFeatures(db: Database): ArrayBuffer;
-export declare function decodeDatabase(manifest: DatabaseManifest, bytes: ArrayBuffer): Database;
+export declare function decodeDatabase(manifest: unknown, bytes: ArrayBuffer, expectedSchema?: PoseSchema): Database;
+/** Explicit, lossless conversion ONLY for the original v1 27-dimensional preset. */
+export declare function migrateLegacyDatabase(input: unknown, bytes: ArrayBuffer): Database;
+export {};

package/dist/core/database.js

@@ -1,59 +1,95 @@
-import { DIMENSIONS, HORIZONS } from './types.js';
+import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+import { parseRootOrientation } from './profile.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);
+        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/profile.d.ts

@@ -1,6 +1,7 @@
-import type { Gait, Vec3 } from './types.js';
+import type { Gait, Quat, Vec3 } from './types.js';
+import { type PoseSchema } from './schema.js';
 export interface CharacterProfile {
-    version: 1;
+    version: 2;
     id: string;
     label: string;
     assetBase: string;
@@ -10,13 +11,17 @@ 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;
+}
+export interface AnimationSet {
+    version: 1;
+    id: string;
     clips: {
         id: string;
         file: string;
@@ -25,12 +30,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. */