@pose_flow/babylon 0.1.0 → 0.3.0

package/dist/AI_USAGE.md

@@ -0,0 +1,386 @@
+# Tutorial de integração para IA — @pose_flow/babylon
+
+Contrato local em desenvolvimento, revisado em 28/10/2026: Fases 1/2 e implementações parciais das Fases 3/4, com perfis v2, bancos v2 e schemas v1; package.json local 0.2.0. Não presumir que alterações deste workspace já foram publicadas: conferir a versão instalada, seus .d.ts e a migração antes de integrar. **Ler este documento antes de integrar ou modificar o uso da biblioteca.** Não presumir recursos futuros a partir do nome “motion matching”.
+
+Fonte mantida no repositório: docs/AI_USAGE.md. Build: dist/AI_USAGE.md. Após instalar pelo npm: node_modules/@pose_flow/babylon/dist/AI_USAGE.md. Também pode ser localizado com `import.meta.resolve('@pose_flow/babylon/AI_USAGE.md')` em Node ESM, sem importar o Markdown como JavaScript.
+
+## 1. Escopo e instalação
+
+Biblioteca TypeScript/ESM de busca de poses e reprodução de locomoção, com canais configuráveis de ossos e trajetória; os exemplos validados são bípedes. Não depende de MMORPG, servidor específico ou personagem específico. O núcleo não importa Babylon; o adaptador é uma entrada separada.
+
+```powershell
+npm install @pose_flow/babylon @babylonjs/core@9.32.1 @babylonjs/loaders@9.32.1
+```
+
+A base local migrou para Babylon 9.32.1: core de desenvolvimento e loaders estão fixos nessa versão; a faixa peer de core é ^9.32.1. Manter core/loaders alinhados no consumidor e conferir `npm ls @babylonjs/core @babylonjs/loaders` para evitar versões incompatíveis ou cópias duplicadas. Esta alteração deixa de declarar suporte a Babylon 7/8; não contornar a faixa peer com force/legacy-peer-deps. Outras versões 9.x admitidas pela faixa ainda exigem validação no projeto consumidor. Conferir a versão publicada da biblioteca: o exemplo acima requer uma distribuição que contenha esta migração.
+
+O pacote local distribui runtime JS, tipos, licença, README, estes guias e CLI offline `pose-flow` para inspeção/preparação/validação/bake. Não inclui Blender, assets, perfis ou bancos prontos. A versão publicada ainda deve ser conferida. Os comandos `npm run bake` e `npm run validate:assets` abaixo são do repositório de desenvolvimento, não scripts automaticamente instalados no consumidor.
+
+## 2. Contrato dos dados
+
+Preparar uma vez, offline, um perfil JSON v2, um schema JSON v1, um conjunto de animações JSON v1, os GLB e um banco v2 com manifest.json + poses.bin. Servir esses arquivos pela pasta pública do projeto consumidor. Nunca reconstruir todo o banco em cada carregamento de avatar.
+
+- Metros, segundos, Y acima, frente +Z. Bake/laboratório usam cena right-handed. Yaw positivo gira +Z para +X. +X coincide com a esquerda anatômica dos exemplos olhando +Z; não confundir com direita da câmera.
+- Não mudar a convenção de toda uma cena existente para adaptar esta lib; adaptar os dados/referenciais do personagem ou gerar banco correspondente.
+- Controller raiz deve ter escala 1; aplicar profile.scale nos rootNodes do modelo, não no controller. A escala das fontes no bake deve coincidir com a do modelo.
+- `rig` mapeia papéis semânticos do schema aos nomes de nodes do modelo; `rig.root` continua obrigatório para validar o rig. boneMap associa nomes das fontes aos do modelo; não faz retargeting de bind pose, proporções ou orientação local.
+- Animações são in-place. stripRoot é opcional e remove as trilhas de posição (inclusive componentes) e a variação de rotação do node indicado. Uma rotação constante de autoria integra a pose e é preservada; canais de rotação com tangentes não são considerados constantes. Usar apenas quando essa política reproduzir o que foi indexado no bake. Para clipes já preparados, **omitir stripRoot no perfil JSON**; o parser recusa string vazia no perfil. Somente no argumento rootName do BabylonMotionPlayer passar `profile.stripRoot ?? ''` para desativar essa remoção.
+- Cada clipe usa nominalVelocity OU motionFile. Velocidade nominal é autoria em m/s finais, não uma medida. motionFile é entrada offline com trajetória medida de hips (proxy de pelvis) ou root dedicado; aceita looping com composição de ciclos.
+- Features são definidas pelo schema. O preset `LOCOMOTION_SCHEMA` preserva 27 dimensões: pés XYZ (0–5), velocidades dos pés no mundo expressas localmente (6–11), velocidade do controller local (12–14), posições futuras XZ (15–20) e direções futuras XZ (21–26), em +0,2/+0,4/+0,6 s. Outros schemas usam dimensões/roles/horizontes próprios; usar `SchemaQueryBuilder`, sem offsets fixos.
+- poses.bin guarda float32 normalizados little endian; manifest guarda mean/std usados também pela query. Usar decodeDatabase; não normalizar a query duas vezes.
+
+Perfil v2 para um rig já compatível (trocar nomes e arquivos pelos reais):
+
+```json
+{
+  "version": 2, "id": "hero", "label": "Hero",
+  "assetBase": "/assets/hero/", "model": "Hero.glb", "database": "/mm/hero/",
+  "scale": 1, "sampleRate": 30,
+  "rig": { "root": "root", "leftFoot": "foot.l", "rightFoot": "foot.r" },
+  "stripRoot": "root",
+  "schema": "/schemas/biped-locomotion.json",
+  "animationSet": "/animation-sets/hero.json"
+}
+```
+
+O arquivo do conjunto contém `{ "version": 1, "id": "hero-locomotion", "clips": [...] }`. Cada clipe mantém id/file/animation/gait/looping e nominalVelocity OU motionFile. Pode declarar rootOrientation: [x,y,z,w], quaternion unitário local absoluto para preparar a orientação estática do root indicado por stripRoot. Por exemplo: `{ "id":"walk", "file":"Locomotion.glb", "animation":"Walk", "gait":"walk", "looping":true, "nominalVelocity":[0,0,1.8] }`. Copiar o preset de schema do repositório; para fornecê-lo pelo runtime, serializar `LOCOMOTION_SCHEMA`. Os JSON externos não vêm no npm.
+
+### Canais de schema v1
+
+`{ version: 1, id: 'meu-schema', channels: [...] }`. Cada canal declara `id` único, `kind`, `weight` não negativo por dimensão e `normalization: 'standard' | 'none'`. Pelo menos um peso deve ser positivo.
+
+| kind | Opções | Dimensões |
+| --- | --- | --- |
+| bone-position | bone: papel semântico | XYZ atual, 3 |
+| bone-velocity | bone: papel semântico | Velocidade no mundo em eixos atuais locais, 3 |
+| root-velocity | nenhuma | Velocidade local do controller, 3 |
+| trajectory-position | horizons: segundos futuros | XZ por horizonte, 2 × amostras |
+| trajectory-facing | horizons: segundos futuros | Direção XZ por horizonte, 2 × amostras |
+
+Exemplo de canal: `{ "id":"hand", "kind":"bone-position", "bone":"leftHand", "weight":0.5, "normalization":"standard" }`; mapear `leftHand` em `profile.rig`. Exemplo de trajetória: `{ "id":"path", "kind":"trajectory-position", "horizons":[0.15,0.35,0.75,1], "weight":3, "normalization":"standard" }`.
+
+`standard` usa média/desvio por dimensão; desvio abaixo de 0,0001 recebe escala 1. `none` usa média 0/escala 1. Custo: soma de peso × diferença normalizada². Limites iniciais: até 128 canais, 64 horizontes por canal e na união global, em ordem crescente dentro de (0,10] s. Posição/velocidade de ossos são da pose atual; histórico/offsets temporais de ossos não estão implementados. Opções desconhecidas no schema são rejeitadas.
+
+`compileSchema` deriva dimensões, offsets, roles e a união ordenada dos horizontes de todos os canais. Usar `predictTrajectory(input, builder.layout.horizons)`, inclusive se posição e direção tiverem horizontes distintos. Um schema só de ossos aceita trajetória vazia. `rootMotionFeatures(track,time,step,horizons)` aceita a mesma união no bake medido.
+
+`SchemaQueryBuilder.build(pose, trajectory)` retorna features brutas + schemaSignature. `SchemaPose` contém `rootVelocity` e `bones: { [papel]: {position:[x,y,z], velocity:[x,y,z]} }`. O leitor Babylon genérico recebe `Map<papel, TransformNode>`. O manifest v2 embute schema completo, dimensões, horizontes e identidade canônica, além de mean/std. A identidade considera id, versão e conteúdo ordenado dos canais, incluindo pesos/normalização; não é um hash com perda. Não editá-la manualmente. Carregar com `decodeDatabase(manifest, bytes, expectedSchema)` e manter a assinatura produzida pelo builder na query. A busca rejeita incompatibilidades mesmo se as dimensões coincidirem.
+
+### Migração da base 0.1.0
+
+O decoder rejeita bancos v1: fazer novo bake com perfil v2 ou chamar explicitamente `migrateLegacyDatabase(oldManifest, oldBytes)`. Esse helper valida apenas o antigo preset de 27 dimensões/0,2/0,4/0,6 s e retorna Database v2 sem I/O, preservando estatísticas e features normalizadas. Para salvar, usar db.manifest e encodeFeatures(db). Não migra perfis/fingerprint nem transforma um banco para outro schema. Nunca trocar só a versão ou reinterpretar os bytes. O laboratório com perfil v2 exige novo bake.
+
+Para migrar o perfil: mover clips para o JSON de conjunto v1, remover clips do perfil, declarar version:2, schema e animationSet. No carregamento, chamar parseProfile, carregar as duas referências e chamar resolveProfile; passar o perfil **resolvido** a profileSignature. Regenerar banco se mudar qualquer uma das configurações. O conteúdo dos GLB é registrado separadamente em assetHashes no manifesto.
+
+Os helpers antigos featureVector/BabylonPoseReader e constantes DIMENSIONS/HORIZONS permanecem exclusivos do preset original. buildDatabase sem terceiro argumento e defaultWeights() selecionam esse preset; customizar com buildDatabase(metadata, raw, schema) e defaultWeights(schema). Queries sem schemaSignature só são aceitas no preset original exato. Novas integrações devem usar o builder. Esta mudança de formatos/perfis exige migração e deve ter versão 0.x apropriada antes de publicar; nenhum pacote novo foi publicado por esta implementação.
+
+No repositório da lib, após copiar assets e perfil:
+
+```powershell
+npm run validate:assets -- --inspect public/assets/hero/Hero.glb
+npm run validate:assets -- --profile public/profiles/hero.json
+npm run bake -- --profile public/profiles/hero.json
+```
+
+Inspeção sugere nomes, preserva ambiguidades e não transforma um rig incompatível. Registrar perfis em public/profiles/index.json apenas para o laboratório. Regenerar banco se alterar perfil, GLB, escala ou clipes. A fingerprint identifica configuração, não substitui hash dos arquivos GLB.
+
+## 3. Exemplo completo do adaptador
+
+O exemplo abaixo é um módulo TypeScript para o consumidor. O jogo fornece uma Scene já compatível e um controller TransformNode sem escala que ele próprio movimenta. Usar uma instância de player/matcher/reader por personagem; fontes e banco podem ser compartilhados numa integração mais avançada. Aqui os recursos são próprios para tornar o ciclo de vida explícito.
+
+```ts
+import { SceneLoader, TransformNode, type Scene, type AnimationGroup, type AssetContainer } from '@babylonjs/core';
+import '@babylonjs/loaders/glTF/index.js';
+import {
+  parseProfile, resolveProfile, profileSignature, decodeDatabase, MotionMatcher,
+  SchemaQueryBuilder, predictTrajectory, filterLocomotionGaits, toLocal,
+  type DatabaseManifest, type TrajectoryInput, type Gait,
+} from '@pose_flow/babylon';
+import { BabylonMotionPlayer, BabylonSchemaPoseReader } from '@pose_flow/babylon/babylon';
+
+export async function createMotionAvatar(scene: Scene, controller: TransformNode, profileUrl: string) {
+  if (!scene.useRightHandedSystem) throw new Error('Preparar banco/referencial compatível com a cena antes da integração.');
+  const json = async (url: string) => {
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Falha ao carregar ${url}: ${response.status}`);
+    return response.json();
+  };
+  const config = parseProfile(await json(profileUrl));
+  const [schemaJSON, setJSON] = await Promise.all([json(config.schema), json(config.animationSet)]);
+  const profile = resolveProfile(config, schemaJSON, setJSON);
+  const builder = new SchemaQueryBuilder(profile.schemaDefinition);
+  const manifest = await json(profile.database + 'manifest.json') as DatabaseManifest;
+  if (manifest.profileId !== profile.id || manifest.profileSignature !== profileSignature(profile)) {
+    throw new Error('Banco e perfil divergentes. Regenerar offline.');
+  }
+  const response = await fetch(profile.database + 'poses.bin');
+  if (!response.ok) throw new Error('Banco binário ausente');
+  const db = decodeDatabase(manifest, await response.arrayBuffer(), builder.layout.schema);
+  const owned: AssetContainer[] = [];
+  let player: BabylonMotionPlayer | undefined;
+  try {
+    const body = await SceneLoader.LoadAssetContainerAsync(profile.assetBase, profile.model, scene);
+    owned.push(body); body.animationGroups.forEach(g => g.stop()); body.addAllToScene();
+    for (const node of body.rootNodes) {
+      node.parent = controller;
+      if (node instanceof TransformNode) node.scaling.scaleInPlace(profile.scale);
+    }
+    const nodes = new Map(body.transformNodes.map(n => [n.name, n]));
+    for (const name of Object.values(profile.rig)) if (!nodes.has(name)) throw new Error(`Osso ausente: ${name}`);
+    const targets = new Map(nodes);
+    for (const [source, target] of Object.entries(profile.boneMap ?? {})) {
+      const node = nodes.get(target); if (!node) throw new Error(`Destino ausente: ${target}`);
+      targets.set(source, node);
+    }
+    const sources = new Map<string, AnimationGroup>();
+    for (const file of new Set(manifest.clips.map(c => c.file))) {
+      const asset = await SceneLoader.LoadAssetContainerAsync(profile.assetBase, file, scene);
+      owned.push(asset); asset.animationGroups.forEach(g => g.stop());
+      for (const clip of manifest.clips.filter(c => c.file === file)) {
+        const group = asset.animationGroups.find(g => g.name === clip.animation);
+        if (!group) throw new Error(`Clipe ausente: ${clip.animation}`);
+        sources.set(clip.id, group);
+      }
+    }
+    const playback = new BabylonMotionPlayer(scene, manifest.clips, sources, targets, 0.15, profile.stripRoot ?? '');
+    player = playback;
+    const reader = new BabylonSchemaPoseReader(controller,
+      new Map(builder.layout.bones.map(role => [role, nodes.get(profile.rig[role])!])), builder.layout.schema);
+    const matcher = new MotionMatcher(db);
+    const available = new Set(manifest.clips.map(c => c.gait));
+    const initial = Math.max(0, manifest.clips.findIndex(c => c.gait === 'idle'));
+    playback.update({ clip: initial, time: 0, switched: true, match: null }, 0);
+    // Avaliar uma vez para obter a pose inicial antes de iniciar a query.
+    // Fazer durante inicialização, sem intercalar com um render loop concorrente.
+    scene.render();
+    let pose = reader.read(0);
+    return {
+      beforeRender(dt: number, input: TrajectoryInput, allowStop = false, allowTurn = false) {
+        const gaits = filterLocomotionGaits(available, Math.hypot(...input.velocity));
+        if (!allowStop) gaits.delete('stop'); if (!allowTurn) gaits.delete('turn');
+        const local = toLocal(input.velocity[0], input.velocity[1], input.yaw);
+        const state = matcher.update(dt, {
+          ...builder.build({ ...pose, rootVelocity: [local[0], 0, local[1]] }, predictTrajectory(input, builder.layout.horizons)),
+          gaits: gaits as ReadonlySet<Gait>,
+        });
+        playback.update(state, dt); return state;
+      },
+      afterRender(dt: number) { pose = reader.read(dt); },
+      reset() { matcher.reset(); reader.reset(); pose = reader.read(0); },
+      dispose() { playback.dispose(); owned.forEach(asset => asset.dispose()); },
+    };
+  } catch (error) { player?.dispose(); owned.forEach(asset => asset.dispose()); throw error; }
+}
+```
+
+Ordem obrigatória por frame: **movimentar/rotacionar controller pelo gameplay → beforeRender → scene.render → afterRender**. Registrar afterRender só uma vez por frame lógico, mesmo com múltiplas câmeras. dt é em segundos. input.velocity e desiredVelocity são [X,Z] do mundo; yaw/desiredYaw são radianos; aceleração/frenagem são m/s² e turnSpeed rad/s. Derivar esses valores do controller do jogo, não da animação.
+
+O exemplo não adiciona um render loop: integrar ao loop existente. Não usar setInterval para animação. Definir allowStop durante frenagem e allowTurn para mudança de heading em baixa velocidade conforme as capacidades reais do banco; eles disponibilizam gaits, não forçam um clipe. Não fazer `matcher.reset()` a cada frame. Resetar histórico em teleporte/reconciliação brusca; velocidades espúrias prejudicam a seleção.
+
+## 4. API e comportamento que a IA deve preservar
+
+- `PoseSearch.search({features,schemaSignature,gaits?,excludedClips?,context?})` retorna melhor Match ou null. Features são brutas. Pesos e normalização vêm dos canais do schema; no preset original, pose/velocidade 1 e trajetória/direção 3 por dimensão. Para custo customizado no matcher, seus pesos estão em matcher.search.weights. Filtros de contexto/entrada/exclusão precedem também o fallback físico de velocidade.
+- `MotionMatcher.update(dt, query)` retorna clip/time/switched/match. clip é índice no manifest; clip < 0 indica ausência de playback. match é o último candidato da busca, que pode diferir do playback por continuidade/cooldown; não apresentá-lo sempre como o clipe renderizado.
+- Defaults: searchInterval=0.1 s, minimumHold=0.12 s, improvement=0.1, jumpPenalty=0.5, timeSeparation=0.2 s, reselectDelay=0.6 s. Critérios de tuning locais; não parâmetros oficiais do Unreal.
+- Sem loop: clamp no fim, exclusão temporária do clipe concluído. Loop: tempo circula na duração. Não somar dt novamente ao tempo retornado antes de chamar o player.
+- `filterLocomotionGaits`: acima de 0.2 m/s retira idle se há marcha; abaixo de 0.05 retira marchas se há idle. Preserva fallback em conjuntos incompletos e não decide prioridades de combate.
+- `BabylonMotionPlayer` cria grupos próprios e mistura tempos diferentes do mesmo clipe. Usar update antes de renderizar. Não iniciar as mesmas fontes sobre o personagem em paralelo. Grupos pausados + goToFrame com pesos são intencionais e cobertos por testes em Babylon 9.32.1.
+- `BabylonSchemaPoseReader` lê ossos semânticos visíveis após avaliação/blending; o wrapper BabylonPoseReader continua para dois pés; não substituir por pose pura do banco quando houver crossfade.
+- `parseProfile` valida perfil v2; `parseSchema`/`parseAnimationSet` validam os JSON independentes e `resolveProfile` confere roles requeridos; `suggestRig` só propõe nomes; `profileSignature` identifica configuração. Validar assets offline é uma etapa separada.
+- `rootMotionFeatures` e `sampleRootMotion` operam em trajetórias medidas com yaw contínuo, clamp por padrão e composição de ciclos quando looping=true. Não aplicar seu deslocamento sobre a posição já simulada do controller.
+
+## 5. Combate, multiplayer e recursos
+
+Gameplay/servidor continuam responsáveis por colisões, posição, dano, hitbox, cooldowns e janelas de ação. O runtime implementado hoje é de apresentação de locomoção. Não transmitir clipId como autoridade de ataque/acerto.
+
+**Planejado, ainda sem API implementada:** a etapa 4.1 de docs/ROADMAP.md inclui animação de combate no escopo obrigatório da 1.0.0: ataques/combos, ataques direcionais/em movimento, esquivas/rolamentos, bloqueios/contra-ataques, reações a impactos e transições com locomoção. Pose Search escolherá variante e entrada entre candidatos autorizados pelo consumidor, com intervalos de entrada/saída, progressão temporal protegida, eventos de apresentação e máscaras/camadas. Não cadastrar novos gaits de combate nem presumir que as opções atuais de continuidade garantem execução segura de golpes. Regras de combo, interrupção e relógio de ataque continuarão externos; eventos visuais não aplicarão dano nem controlarão janelas autoritativas. Motion warping segue como expansão posterior, fora do aceite in-place da 1.0.0.
+
+O player usa corpo inteiro por padrão e aceita máscara opcional de nomes exatos dos nodes do modelo no sétimo argumento de opções (ver seção da Fase 4). Players da biblioteca com máscaras sobrepostas são recusados; grupos externos do consumidor não são detectados automaticamente. Não sobrepor grupos nos mesmos nodes. Para transferir controle de corpo inteiro, dispor o player anterior antes de criar o próximo; para camadas, definir propriedade disjunta. Reiniciar a seleção a partir da pose visível ao retornar. Isso não implementa contratos de execução de golpes/combos da etapa 4.1.
+
+Banco e fontes podem ser carregados uma vez por cena; player, matcher e histórico do leitor precisam ser individuais. Liberar grupos do player na remoção do avatar. Não dispor fontes compartilhadas antes de todos os consumidores. O exemplo possui seus próprios assets e não dispõe o controller fornecido pelo jogo.
+
+## 6. Diagnóstico e verificação
+
+| Sintoma | Conferir |
+| --- | --- |
+| Arquivos não encontrados | Perfil e assets devem ser servidos pelo consumidor; não vêm no npm |
+| Banco desatualizado | Perfil/fingerprint e novo bake; substituição de GLB exige bake mesmo sem mudar perfil |
+| Ossos ausentes/deformação | Nomes, boneMap, bind pose, retargeting prévio; não apenas renomear ossos |
+| Sem animação/T-pose | Fontes corretas, bootstrap, update antes do render, leitura depois |
+| Idle andando ou marcha parado | Gaits permitidos por velocidade, unidades, pesos e cobertura do banco |
+| Pés deslizam | Velocidade nominal, escala, velocidade real, direção; não há foot locking/IK |
+| Movimento duplicado | Root motion não removido ou aplicado junto ao controller |
+| Direção invertida | Referencial da cena/câmera, yaw e transformação mundo→local |
+| Muitos saltos | dt/unidades, reset indevido, pesos, minimumHold/improvement e qualidade dos clips |
+
+No consumidor, testar idle, aceleração, walk/run, lados/costas quando disponíveis, frenagem, giro, transições, teleporte, múltiplos avatares e remoção. Medir no navegador alvo; resultados de benchmark Node não são orçamento de renderização. Um sample correto não prova qualidade de todo o ciclo.
+
+Não implementados: retargeting automático, IK/foot locking, contatos de pés, motion warping, movimento autoritativo por root motion, worker, PCA/KD-tree, quadrúpedes ou schema visual configurável. Inertialization opcional está descrita na seção da Fase 4, com limites próprios. Não prometer eliminação de sliding ou paridade com Unreal.
+
+Fase 1 implementa schemas configuráveis e arquivos de conjunto separados. O laboratório oferece biped-locomotion (27 dimensões) e biped-hands (33 dimensões, mãos/horizontes diferentes). A implementação parcial da Fase 3 acrescenta contexto extensível, intervalos, roteamento de bancos e política de idle, conforme a seção abaixo. Não há síntese de olhar, camadas ou comparação conjunta de custos entre bancos independentes. Preparação genérica GLB está implementada na Fase 2; retargeting automático continua futuro; os schemas não adaptam animações de rigs incompatíveis.
+
+## 7. Manutenção obrigatória
+
+Planejamento neural (28/10/2026): `docs/features/animacao-neural/README.md`, no repositório, analisa treinamento offline com animações do projeto, um híbrido de candidatos e a alternativa de síntese neural, com estimativas de esforço e custos separados entre preparação, navegador e servidor. Nada disso está implementado ou distribuído no npm. O plano recomenda execução no cliente, preservando a autoridade de gameplay/servidor; não há modelo inicial, treinamento automático, runtime neural ou novo comando/API disponível. As contas são cenários com premissas, não medições nem garantias de custo/desempenho.
+
+Investigação documental (28/10/2026): no repositório, `docs/features/locomocao-web/README.md` reúne oportunidades de trajetória, transições, diagnóstico, múltiplos personagens e cenários repetíveis, com fontes e critérios de aceite. É planejamento, não uma API disponível; não acrescenta dependências, código externo, modelos neurais ou recursos ao runtime. Inertialization, worker, índices acelerados e novos diagnósticos continuam futuros. A pasta de pesquisa não acompanha o pacote npm atual.
+
+Para toda implementação/correção na biblioteca, revisar e atualizar **este arquivo fonte na mesma alteração**, inclusive registrando correções internas relevantes aqui. Atualizar exemplos, contratos, limitações e diagnóstico afetados. Só descrever como validado o que foi executado. Não editar dist/AI_USAGE.md manualmente.
+
+Rodar typecheck/testes/build conforme a mudança; `npm run check:docs` confirma que dist contém as cópias atuais. `prepack` recompila e copia os documentos antes de empacotar/publicar; isso não substitui a revisão semântica do tutorial. Usar docs/PUBLISHING.md para release; publicação exige pedido explícito do mantenedor.
+
+Registro de manutenção (28/10/2026): tutorial inicial da série 0.1.x, entradas npm atualizadas para @pose_flow/babylon, perfis genéricos, bootstrap por pose animada, filtros de velocidade e políticas de root/blending documentados. Banco e perfis de exemplo continuam fora do npm. Guias passam a acompanhar build/pacote a partir da próxima versão publicada; não assumir que estavam na primeira 0.1.0.
+
+Revisão do roadmap (28/10/2026): documentadas as diferenças entre perfis reutilizáveis atuais e schemas/conjuntos configuráveis planejados. Nenhuma API ou capacidade de animação foi alterada nesta revisão documental.
+
+Complemento do roadmap (28/10/2026, histórico anterior à task-13): explicitados múltiplos idles e a distinção entre deslocamento, corpo e olhar. A task-13 implementa filtros/política descritos abaixo; cobertura visual de olhar lateral permanece pendente.
+
+Marco de estabilidade (28/10/2026): o roadmap passa a exigir uma release estável 1.0.0, com API/dados versionados, migração, pipeline distribuível, múltiplos rigs, cenários visuais, desempenho e instalação em consumidor independente validados. O processo prevê versões candidatas antes da release. A base atual permanece 0.1.0; este marco não declara recursos futuros implementados nem autoriza publicação imediata. Consultar ROADMAP.md para o escopo e PUBLISHING.md para os critérios de release.
+
+Fluxo de testes práticos (28/10/2026): o MMORPG será consumidor durante o desenvolvimento. No repositório da lib, task/summary.md lista relatos por prioridade e status PENDENTE/PARCIAL/CONCLUIDO; task/_modelo/ fornece o relato e pastas de evidências para copiar em task/task-NN/. Registrar versão instalada, perfil/banco, reprodução, esperado/observado e validações executadas. Problemas exclusivos do consumidor aguardam confirmação no cenário original antes de concluir. O acompanhamento é manual, não acompanha o npm e não implica integração já aplicada ou nova API.
+
+Restrição de escopo (28/10/2026): neste projeto/chat é proibido alterar o jogo em D:\MMORP_WEB\mmorpg-polygon-multiplayer\mmorpg-polygon-multiplayer, inclusive assets, dependências, configuração e arquivos gerados, ou executar comandos que escrevam nele. Consultas para análise são somente de leitura. Corrigir a biblioteca aqui; se a causa for do consumidor, registrar diagnóstico/orientação na task. O usuário ou responsável pelo jogo realiza a integração e os testes práticos naquele projeto. Exemplos de integração deste guia são instruções para o consumidor, não autorização para este chat modificar o jogo.
+
+Manutenção — Fase 1 (28/10/2026): formatos de banco/perfil v2; schema v1 com canais/normalização/horizontes configuráveis; identidade canônica e rejeição de incompatibilidades; migração explícita do banco v1; conjunto de animações separado; leitor Babylon genérico; bake usa o mesmo player/modelo alvo e política de root do runtime. Exemplos e ciclo de integração acima atualizados. Ferramentas, schemas/perfis/conjuntos e bancos continuam fora do npm; nenhuma publicação realizada. Evidências e limites da implementação estão em docs/VALIDATION.md no repositório.
+
+Correção de strafe — task-05 (28/10/2026): preservada a orientação constante de autoria do root em bake/player, mantendo remoção de deslocamento e heading variável. Adicionado Clip.rootOrientation (e campo homônimo no conjunto): quaternion unitário local absoluto aplicado como parte da pose, com crossfade, sem alterar o controller. Exige stripRoot mapeado; sem override, preserva a rotação constante da fonte ou usa a orientação inicial do rig quando a rotação da fonte varia. Criar o player antes de animar o rig, para capturar a referência inicial correta. rootOrientation é preparação explícita da pose, não retargeting, IK, motion warping nem comando de yaw do gameplay. Alterá-la exige novo bake. Bancos anteriores desta base que removeram uma orientação constante também devem ser regenerados; a assinatura do schema não identifica mudanças no algoritmo de preparação.
+
+O pack KayKit possui strafes de corrida com orientação de autoria ±60°, inadequada à trajetória lateral pura do exemplo. O conjunto kaykit configura rootOrientation com yaw ±90° para alinhar as pernas à direção lateral. Isso gira a pose do rig; não implementa controle independente de torso/olhar. O laboratório passa a testar strafes à velocidade nominal declarada (3,2 m/s nesses exemplos), inclusive A/D puro com Manter orientação quando houver clipe nominal alinhado. A velocidade é de autoria, não medição automática. A inspeção de pés próximos ao chão é somente diagnóstico offline, não contato/foot locking em runtime; sliding residual ainda pode existir, especialmente em transições e escalas diferentes.
+
+## Manutenção — primeiro incremento da Fase 2 (28/10/2026, histórico)
+
+Clipes aceitam `range: [inicio,fim]` em segundos. O bake guarda `sourceStart` e duração recortada; BabylonMotionPlayer aplica o mesmo intervalo, incluindo o primeiro frame da fonte e loops. Fazer novo bake.
+
+`motionFile` aceita source `root` ou `hips` e looping. `sampleRootMotion(track,time,looping=false)` e `rootMotionFeatures(track,time,derivativeStep,horizons,looping=false)` compõem deslocamento e yaw dos ciclos, inclusive negativos. `cropRootMotion(track,start,end)` interpola limites. Velocidade nominal é autoria. A composição não corrige emenda de pose nem elimina sliding.
+
+O manifesto v2 ganha `assetHashes` SHA-256 por URL de GLB/trajetória. A fingerprint continua somente configuração. O laboratório exige hashes e recusa assets alterados; bancos antigos exigem novo bake. `decodeDatabase` valida o formato, sem ler arquivos/rede. O consumidor externo deve conferir hashes ou controlar identidade dos assets na distribuição. O laboratório faz uma leitura extra dos bytes, além do carregamento Babylon.
+
+CLI Node incluída no pacote local: `pose-flow inspect modelo.glb`, `pose-flow validate --profile public/profiles/rig.json`, `pose-flow bake --profile public/profiles/rig.json`. `--public-dir caminho` muda a raiz dos URLs públicos em validação/bake; `--profile` é caminho de arquivo. Caminhos relativos ao diretório atual do consumidor. A base atual usa Babylon 9.32.1; o loader GLTF 9.32.1 é dependência do pacote. A preparação offline original foi testada com Node 24.21.0 e Babylon 7.54.3; os resultados da migração estão na task-15. Não fazer bake no início do jogo. Assets, perfis e bancos são fornecidos pelo consumidor. Não houve publicação.
+
+Consulte PROFILES.md para remoção de root e roteiro offline. Esse primeiro incremento foi parcial; as pendências de preparação foram atendidas na continuação abaixo. Retargeting automático, IK e inertialization não foram implementados.
+
+## Manutenção — preparação e validação da Fase 2 (28/10/2026)
+
+A CLI distribuída inclui `pose-flow prepare --config preparation.json`. JSON v1: input/output GLB distintos, animation, rootNode, source (`hips`/`root`), sampleRate (1–120), position (`horizontal`/`all`), heading boolean; opcionais unitScale positivo e yawOffset em radianos. Paths relativos ao diretório atual. Ver PROFILES.md para contrato, exemplo e limites. A ferramenta exporta um GLB com trilhas preparadas, `.motion.json` com a trajetória medida e `.preparation.json` com configuração/hash/proveniência técnica. Executar offline. A licença da fonte continua sendo responsabilidade de quem fornece o asset.
+
+A política horizontal retira XZ e preserva bob Y; all fixa XYZ no ponto inicial. heading=true retira variação de yaw, preservando orientação inicial e inclinação. Dados são reamostrados linearmente na taxa configurada. unitScale/yawOffset são aplicados ao GLB e à medida em conjunto; não substituem a escala do perfil. GLB precisa ser autossuficiente, com um buffer, início zero, escalas positivas/uniformes e sem shear. Para scene roots animados, converter eixos/unidades antes. Seleção de osso, eixos e política é explícita, sem inferência por personagem. Não aplicar stripRoot novamente à trilha já retirada.
+
+`pose-flow validate --profile ... --check-bind` compara geometria de bind relativa ao root e cobertura de joints; exige um skin e inverse bind matrices MAT4 float32. Falta de dados falha. Essa checagem detectou Medium → Large incompatível apesar dos mesmos nomes; Large → Large passou. Não equivale a retargeting nem valida contatos.
+
+O descritor pode conter `averageVelocity`, média das velocidades locais medidas das amostras do bake. O laboratório usa essa referência para velocidade de teste de marcha; nominalVelocity continua autoria. O jogo continua responsável pelo deslocamento, colisões e combate. A câmera do laboratório se enquadra pelo tamanho do modelo, sem condições por nome.
+
+Novas demonstrações por JSON: mannequin-large (126 poses, idle/walk/run próprios), paladin-measured (351 poses, caminhada medida em loop e parada sem loop preparada a 2×), mannequin-retarget (32 poses, experimento offline de caminhada Medium → Large). O último usa constraints/bake nativos do Blender configurados explicitamente, com bob sem recalibração de proporção; não é retargeting automático da biblioteca, não tem idle/contatos e não valida rigs arbitrários. A reprodução foi conferida no navegador. Os GLB/JSON/licenças não entram no pacote npm.
+
+A preparação exige novo bake quando mudar bytes ou políticas. Foram comparadas as poses dos sete perfis e a velocidade das poses medidas num controller deslocando/girando, inclusive emenda: erro amostral máximo aproximadamente 0,003 m/s. Isso não garante suavidade de qualquer dataset nem ausência de sliding. Retargeting automático próprio, IK, foot locking e inertialization continuam futuros. Nenhuma alteração ou teste no MMORPG e nenhuma publicação.
+
+## Manutenção — frenagem do laboratório (task-07, 28/10/2026)
+
+`Query.velocityTolerance?: number` ativa uma faixa física de compatibilidade no canal root-velocity, em m/s, antes do custo ponderado de poses. Requer esse canal no schema; valores negativos/não finitos falham. Padrão ausente mantém a busca anterior. Filtros de gait/excludedClips são aplicados antes da faixa. Se nenhum candidato estiver dentro dela, comparar somente os de menor erro de velocidade, preservando fallback sem liberar indiscriminadamente poses paradas. O núcleo continua sem engine/I/O.
+
+Quando o tempo corrente fica incompatível e há um candidato distante melhor em velocidade, MotionMatcher pode trocar após minimumHold, sem exigir a margem de melhora do custo de pose. Mantém searchInterval e timeSeparation; não reinicia por pequenas diferenças entre amostras próximas. A faixa não é garantia frame a frame: cobertura incompleta, avanço entre buscas e retenção podem produzir erro maior. Não altera o controller nem janelas de combate. A nova opção tem uma passagem adicional linear sobre os candidatos; `npm run benchmark -- --velocity-band` mede esse caminho em Node.
+
+O laboratório usa faixa de 0,2 m/s ao frear e crossfade de 0,30 s. Exibe Ritmo do clipe (velocidade indexada, nominal ou medida conforme o descritor) para comparar com Velocidade do controller. Isso não mede contato dos pés.
+
+A preparação aceita `playbackRate` opcional entre 0,25 e 4 (padrão 1). Valores acima de 1 encurtam o GLB e a trajetória, aumentando a velocidade medida, sem mover o controller em runtime. Todos os tempos dos canais LINEAR/STEP são reescalados; CUBICSPLINE em canais retidos exige reamostragem offline anterior quando rate difere de 1. O relatório e o bake registram a duração resultante. A taxa sampleRate é aplicada antes dessa alteração temporal. Alterar rate exige preparar e fazer bake novamente.
+
+No perfil paladin-measured, a parada a 2× substitui a parada lenta no conjunto; o arquivo original e o perfil Paladin legado foram preservados. Não é nominalVelocity disfarçada: os samples e o GLB foram retimados em conjunto e o banco usa velocidades derivadas. O resultado reduz a seleção de poses quase estáticas durante o avanço, mas não implementa contatos, IK ou foot locking e não promete eliminar sliding residual de transições/datasets incompatíveis. Evidências e limites em task/task-07/task.md.
+
+## Manutenção — tremida na saída (task-08, 28/10/2026)
+
+`Query.allowTemporalReselection?: boolean` controla somente saltos de tempo dentro do mesmo clipe looping. O padrão true preserva o comportamento anterior. False deixa o ciclo corrente avançar normalmente e completar a emenda; a busca continua ativa e pode selecionar outro clipe. Não bloqueia trocas obrigatórias por gait/exclusão/término nem replanejamento de one-shots. Também não é uma trava de contatos ou uma escolha manual de clipId.
+
+O laboratório define false quando a intenção está estável (erro de velocidade desejada/atual menor que 0,05 m/s e erro angular menor que 0,08 rad). Em aceleração, frenagem ou giro volta a permitir replanejamento. Esses limiares são política do consumidor de demonstração, não limites universais da biblioteca. Outros consumidores devem considerar também troca de contexto/ação, teleporte e reconciliação; não manter a fase protegida quando o estado da personagem exige uma nova decisão. Resetar matcher/reader nos casos já descritos no tutorial.
+
+A investigação encontrou retrocessos repetidos de aproximadamente 0,7 para 0,5 s na caminhada, com feedback entre crossfade/velocidade da pose visível e nova busca. No cenário reproduzido, proteger a fase removeu 12 retrocessos amostrados em dois ciclos de caminhada. Os testes mantêm busca para outro clipe, retorno ao replanejamento, wrap natural e o cenário de frenagem corrigido. Dados/bancos não mudam por essa opção. Não há inertialization ou foot locking novos.
+
+## Manutenção — planejamento de animação de combate (task-12, 28/10/2026)
+
+Roadmap ampliado por pedido do mantenedor para incluir combate visual como entrega obrigatória da 1.0.0, com contratos e critérios próprios na etapa 4.1. Esta alteração é documental: não adiciona APIs, eventos, máscaras, bancos de combate ou garantias de sincronização ao runtime atual. O procedimento de transferência de controle de corpo inteiro acima continua sendo o contrato disponível. Implementação e validação de combate permanecem pendentes; a task-10 continua acompanhando máscaras. Sem mudança no processo de build/publicação.
+
+## Manutenção — seleção contextual, Fase 3 parcial (task-13, 28/10/2026)
+
+Clipes do conjunto/manifesto aceitam `context?: Record<string,string>` e `entryWindows?`, `exitWindows?`, `excludedWindows?`. As chaves são semântica explícita do consumidor: por exemplo set/equipment/posture/look/action/combo. Não inferir contexto de nomes de arquivos/clipes. Campos opcionais preservam os formatos perfil v2/banco v2/conjunto v1; bibliotecas anteriores não aplicam esses filtros e não devem reproduzir bancos que dependam deles. Alterar metadados exige novo bake/fingerprint.
+
+```ts
+const matcher = new MotionMatcher(db, {
+  idleVariation: { interval: 4, historySize: 2 },
+});
+// A cada frame, após construir features/trajectory no referencial atual:
+const state = matcher.update(dt, {
+  ...builder.build(pose, points),
+  gaits, // Set(['idle']) ativa a política enquanto parado
+  context: { set: 'relaxed', posture: 'standing', look: 'forward' },
+  allowTemporalReselection: false, // usar apenas quando a intenção estiver estável
+});
+player.update(state, dt);
+```
+
+Todas as chaves solicitadas precisam existir com valor igual no candidato; metadado ausente não é curinga. Contexto/gait/excludedClips e intervalos de entrada/exclusão são aplicados antes do custo e do fallback de velocidade. Pool vazio retorna null; matcher sem clipe válido devolve clip=-1 e o player limpa a reprodução. Se a reprodução corrente ainda for compatível mas não houver novas entradas, ela continua naturalmente. O consumidor decide a apresentação alternativa; nunca interpretar ausência como permissão de ação.
+
+Intervalos fechados `[início,fim]` usam segundos relativos ao clipe recortado/retimado, dentro de `[0,duration]`. Ausente libera; entryWindows=[] impede entradas, exitWindows=[] impede saídas discricionárias, excludedWindows=[] não exclui nada. As entradas fora das janelas e dentro das exclusões não concorrem, mas a reprodução atravessa esses trechos. Não há remoção física dos samples. exitWindows limita trocas discricionárias no tempo corrente; término, contexto/gait inválido e excludedClips prevalecem. dt que pula a janela aguarda próxima oportunidade ou término. Não é contrato seguro de golpes/combos nem trava autoritativa de saída.
+
+idleVariation é opt-in e só atua quando gaits contém exclusivamente idle. Antes de interval mantém o clipe, respeitando a política de replanejamento temporal. Depois busca outro idle elegível por custo, sem sortear/forçar clipId ou tempo; historySize controla variantes recentes a evitar. Se necessário relaxa histórico antigo, nunca os filtros do consumidor. Se só existir uma variante, mantém o ciclo. A troca respeita minimumHold e exitWindows; no máximo uma variação por update, sem recuperar múltiplas mudanças após dt longo. Sair de idle reinicia o timer; reset limpa timer/histórico.
+
+O perfil kaykit-context demonstra dois subconjuntos no mesmo banco/normalização com Idle_A/B e Walking_A/B/C. Corpo (yaw), deslocamento (velocidade/trajetória) e olhar (context.look) têm entradas separadas. O olhar apenas filtra clipes preparados; não gera pose de cabeça. Esse dataset cobre somente forward. Caminhada olhando lateralmente, máscaras e cobertura visual integral permanecem pendentes. Não declarar a Fase 3 concluída por esses filtros.
+
+Para bancos independentes, `selectContextBank(banks,context)` recebe `{id,context,database}[]`, retorna o único banco compatível ou null e rejeita ambiguidade/IDs repetidos. Roteia antes da busca, sem comparar custos entre normalizações. O consumidor usa o schema daquele banco, valida rig/preparação e mantém seu matcher/player. Não há transferência automática de pose/tempo entre bancos ou validação de retargeting pelo roteador. Para competição conjunta de variantes, usar um bake compatível com estatísticas comuns.
+
+Task-11: corrigido cabeçalho para identificar a base local sem afirmar a versão publicada atual e distinguido stripRoot do perfil (omitir) e argumento do player (string vazia). Sem alteração do parser, build ou publicação; confirmação no cenário original continua com o responsável pelo consumidor.
+
+## Manutenção — diagnóstico, máscaras e transições, Fase 4 (task-14, 28/10/2026)
+
+### Inspecionar a busca e a continuidade
+
+`PoseSearch.inspect(query,limit=5)` faz uma passagem diagnóstica opt-in e retorna best, candidates (índice/clipe/tempo/custo, custos por canal e erro físico de velocidade quando há esse canal), contagens de rejected, exemplos limitados, eligible/total e velocityLimit. Limit é inteiro de 1 a 50. Usa a mesma busca exata, estatísticas e pesos de search; os custos por canal somam o custo total. Rejeições têm precedência única: excluded-clip, gait, context, entry-window, excluded-window, velocity. Contagens não representam todas as causas simultâneas. O limite físico reflete o fallback do pool elegível; null significa não aplicado ou pool vazio.
+
+`new MotionMatcher(db,{diagnostics:true})` guarda snapshot da query da última busca efetiva, incluindo exclusões internas de término/histórico de idle. `matcher.inspect(limit)` inspeciona esse snapshot; retorna null sem diagnóstico ou antes da primeira busca. Não representa necessariamente a query do frame atual. `matcher.decision` informa se houve busca, motivo da decisão, clipes anterior/atual, custos comparados e parâmetros de continuidade. Entre buscas reason=search-interval. Histórico do laboratório armazena até 32 trocas; o núcleo não acumula um log ilimitado. Inspeção tem custo adicional e deve ficar desligada/menos frequente fora de diagnóstico.
+
+`readCandidateTrajectory(db,index)` reconstrói metros/direções por horizonte com mean/std do banco. Position/facing são opcionais conforme os canais presentes. Não confundir com posição absoluta do controller. O laboratório desenha trajetória desejada em verde e a do candidato em laranja no referencial atual; candidato pode diferir do playback por continuidade.
+
+### Máscaras e propriedade
+
+```ts
+const lowerMask = profile.masks?.['lower-body'];
+const upperMask = profile.masks?.['upper-body'];
+if (!lowerMask || !upperMask) throw new Error('Perfil sem máscaras de pernas/tronco');
+const legs = new BabylonMotionPlayer(scene, clips, sources, targets,
+  0.30, profile.stripRoot ?? '', { mask: lowerMask });
+const torso = new BabylonMotionPlayer(scene, clips, sources, targets,
+  0.30, profile.stripRoot ?? '', { mask: upperMask });
+// Atualizar ambos antes de scene.render(). Não somar dt novamente a state.time.
+legs.update(locomotionState, dt);
+torso.update(presentationState, dt);
+```
+
+Os nomes da máscara são **do modelo**, após boneMap. Não há expansão automática de descendentes. Lista vazia, duplicada, node não mapeado/ambíguo e ausência de trilhas elegíveis falham. A propriedade é por node, incluindo todas as suas propriedades, reservada no construtor e liberada em dispose (não em clip=-1/reset). Dois players da lib sobre o mesmo node são recusados. Não há detecção de AnimationGroups criados fora da lib: o consumidor coordena esses grupos. Partilhar fontes é permitido; grupos de reprodução são próprios e fontes permanecem intactas.
+
+Máscaras respeitam range/sourceStart, loops, rootOrientation/stripRoot e crossfade de tempos do mesmo clipe. O root só recebe a orientação constante se pertencer à máscara; clipes das outras camadas herdam a transformação do pai controlado pela base. Não duplicar root em duas máscaras. Comparar trilhas locais e poses dos ossos selecionados sob a mesma cadeia de pais; combinação de camadas não equivale à pose de corpo inteiro de um único clipe. Uma ação de tronco ainda herda deslocamento/orientação de hips/root da base. Preparar rigs/clipes de acordo.
+
+Perfis v2 aceitam `masks: {nome:[nodes...]}` e `layerPreview:{baseMask,overlayMask,context}` opcional apenas para o laboratório. layerPreview exige duas máscaras disjuntas e contexto explícito; não autoriza ação de gameplay. O novo perfil kaykit-transitions permite pernas em locomoção e Interact no tronco, com entrada escolhida por Pose Search e avanço visual sequencial simples. É uma prévia de apresentação; não entrega ataques, combos, eventos/janelas autoritativas ou todas as garantias da etapa 4.1. Task-10 permanece parcial até confirmação no cenário original pelo responsável do jogo.
+
+### Inertialization opcional
+
+No mesmo argumento de opções: `{transition:'inertialization',inertialHalfLife:0.1}`. Padrão transition=crossfade preserva a reprodução anterior. Inertialization mantém um único grupo ativo e captura pose local visível/velocidade de apresentação ao trocar clipe ou tempo. Calcula residual para a pose/velocidade de entrada, amortecendo-o criticamente sobre posição/escala e log de quaternion. Não continua avaliando o clipe de saída; interrupções partem da pose já corrigida. A meia-vida é em segundos e corresponde a metade do offset com velocidade residual inicial zero. `decayInertialOffset` é a função escalar do núcleo, sem engine.
+
+Suporte atual: trilhas locais position/scaling/rotationQuaternion, inclusive componentes compatíveis. Euler não removido e outras propriedades são recusados no modo inercial. A correção de root constante continua compartilhada com o crossfade/bake. A derivada de entrada é amostrada da animação em ±1/120 s (ou passo menor para clipe curto), com loops/recortes corretos; a de saída vem de poses visíveis consecutivas. Rotação usa aproximação em espaço tangente, sem garantia de continuidade angular exata para grandes giros; velocidades/seams ruins e diferenças grandes de escala podem causar overshoot. Validar conteúdo e meia-vida por rig. Não é IK, foot locking, correção de contato nem garantia de melhor aparência que crossfade.
+
+Manutenção numérica: o residual evita a operação Infinity × 0 após pausas muito longas; elapsed=0 preserva exatamente o offset mesmo com meia-vida positiva muito pequena.
+
+Chamar update antes de scene.render e ler a pose depois. A correção é aplicada em onAfterAnimationsObservable, antes das matrizes mundiais/rendering; respeita a máscara. dt=0 não estima nova velocidade; há no máximo um avanço do residual por update, mesmo se renderizar várias vezes. O primeiro frame após uma troca mantém o offset inicial (sem consumir dt da troca). `player.reset()` limpa grupos/histórico de transição e retém propriedade; chamar também matcher.reset e reader.reset em teleporte/reconciliação brusca. dispose remove observer/grupos e libera propriedade, sem dispor fontes, modelo ou controller. Nenhuma posição autoritativa é alterada.
+
+### Gravar/reproduzir comparações
+
+No laboratório, escolher teste e transição, abrir “Gravar e comparar cenário”, gravar, parar e reproduzir com cada modo. Exportar/importar JSON é local. Query/resultado do matcher, dt, posição/yaw do controller e tempo apresentado (incluindo saltos de fase do teste) são registrados; não são comandos do jogo. A reprodução usa **queries gravadas**, não feedback de uma nova pose visual. Isso isola o efeito do player para comparar modos com as mesmas decisões; não comprova estabilidade de uma simulação fechada diferente. Gestos manuais de tronco não são gravados; usar corpo inteiro para comparar apresentação do cenário base.
+
+Reiniciar a apresentação ou trocar o modo de transição/camada encerra a gravação antes do reset e preserva o trecho válido; não introduz silenciosamente um reset do matcher no meio de um arquivo reproduzível. Ao recriar players, o laboratório restaura a referência local original do modelo antes do bootstrap, para não capturar uma pose já animada como bind/baseline de tracks ausentes.
+
+`captureScenarioFrame`, `scenarioDatabaseIdentity`, `parseMotionScenario` e `restoreScenarioQuery` estão no núcleo. Formato v1 exige identidade do manifesto/features, opções do matcher, filtros e valores finitos. Rejeita dados incompatíveis, gait inválido, tempo/clipe fora dos limites, mais de 6.000 frames ou dois milhões de valores de features; importação do laboratório limita arquivo a 16 MB. Identidade é fingerprint de conteúdo não criptográfica, sem garantia de segurança. JSON é dado; não executa código. Não editar bancos/saídas geradas para satisfazer identidade.
+
+Fase 4 continua acompanhada como PARCIAL até registrar o aceite aplicável e confirmar as limitações de camadas no cenário original; Fase 3 continua parcial por cobertura de olhar/dataset. Schemas atuais usam pose atual e não exigiram histórico temporal de ossos novo nesta entrega. Sem mudança no processo de build/publicação; nenhuma publicação automática.
+
+## Manutenção — migração Babylon 9.32.1 (28/10/2026)
+
+Core/loaders e lockfile atualizados juntos. A API pública e os formatos de perfil v2/banco v2/schema v1 permanecem iguais. Os 95 testes passaram em 9.32.1, incluindo reprodução real em NullEngine, máscaras, crossfade e inertialization. Os nove perfis existentes foram rebaked offline; os 18 arquivos manifest.json/poses.bin ficaram idênticos por SHA-256 à referência 7.54.3, sem necessidade de substituir esses bancos por causa desta migração. Isso não garante equivalência para assets/perfis externos: validar preparo/bake/player com o conteúdo do consumidor e manter exatamente a mesma remoção de root.
+
+Babylon 9 introduz diagnóstico de limite de uniforms de esqueletos; o NullEngine usado offline reporta limites artificiais baixos e emite aviso para os rigs com 65 ossos. Esse aviso não é medição de GPU do jogo e não invalida o bake. Em dispositivos reais, conferir capacidades/renderização; não aplicar configurações de GPU do laboratório indiscriminadamente ao consumidor. A atualização não resolve a conversão LH/RH da task-09 nem confirma as camadas no MMORPG (task-10). Não há mudança em deslocamento autoritativo, combate ou contratos multiplayer.
+
+Laboratório conferido em Edge/WebGL2 com Knight (incluindo camadas), Paladin e Mannequin Large, nos dois modos de transição; sem erros/avisos no roteiro final. Instalação isolada confirmou imports públicos, core único e CLI validate. Evidências e limites da migração: task/task-15/.

package/dist/PUBLISHING.md

@@ -0,0 +1,110 @@
+# 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
+
+Migração Babylon (task-15, 28/10/2026): core peer ^9.32.1, core de desenvolvimento e loaders de produção fixos em 9.32.1. A base anterior era 7.54.3; esta mudança remove o suporte declarado a 7/8 e exige instrução de migração antes de distribuir. A versão local do pacote permanece 0.2.0; escolher nova versão 0.x adequada à quebra antes de publicar, sem sobrescrever uma versão existente. Conferir `npm ls @babylonjs/core @babylonjs/loaders` na biblioteca e em instalação isolada, com core/loaders alinhados. Não copiar o lockfile da biblioteca para o jogo. O processo build/prepack continua igual.
+
+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-inertialization.d.ts

@@ -0,0 +1,29 @@
+import { Quaternion, Vector3, type Scene, type TransformNode } from '@babylonjs/core';
+export interface LocalPose {
+    position: Vector3;
+    rotation: Quaternion;
+    scaling: Vector3;
+}
+export type LocalPoses = Map<TransformNode, LocalPose>;
+export declare function captureLocal(node: TransformNode): LocalPose;
+export declare function rotationVector(q: Quaternion): Vector3;
+export declare function poseVelocity(before: LocalPose, after: LocalPose, dt: number): LocalPose;
+/** Owns local presentation residuals only. Evaluation happens before world matrices/rendering. */
+export declare class BabylonInertializer {
+    private scene;
+    readonly halfLife: number;
+    private observer;
+    private last;
+    private velocity;
+    private residuals;
+    private target;
+    private dt;
+    private elapsed;
+    private revision;
+    private renderedRevision;
+    constructor(scene: Scene, halfLife: number);
+    update(target: LocalPoses, targetVelocity: LocalPoses, dt: number, switched: boolean): void;
+    private render;
+    reset(): void;
+    dispose(): void;
+}