@pose_flow/babylon 0.1.0 → 0.3.0

package/dist/offline/tools/bake.js

@@ -0,0 +1,88 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { FreeCamera, TransformNode, Vector3 } from '@babylonjs/core';
+import { hashProfileAssets, loadProfileAssets, profileArgument, publicPath, readProfile } from './profile-assets.js';
+import { buildDatabase, encodeFeatures, SchemaQueryBuilder, rootMotionFeatures, cropRootMotion, validateRootMotion, profileSignature } from '../src/index.js';
+import { BabylonMotionPlayer, BabylonSchemaPoseReader } from '../src/babylon.js';
+const profile = await readProfile(profileArgument());
+const builder = new SchemaQueryBuilder(profile.schemaDefinition), layout = builder.layout;
+const assets = await loadProfileAssets(profile);
+try {
+    const { scene, containers } = assets, body = containers.get(profile.model);
+    new FreeCamera('bake-camera', new Vector3(0, 2, -5), scene);
+    body.addAllToScene();
+    const controller = new TransformNode('bake-controller', scene);
+    body.rootNodes.forEach(n => n.parent = controller);
+    const nodes = new Map(body.transformNodes.map(n => [n.name, n])), targets = new Map(nodes);
+    for (const [source, target] of Object.entries(profile.boneMap ?? {}))
+        targets.set(source, nodes.get(target));
+    const reader = new BabylonSchemaPoseReader(controller, new Map(layout.bones.map(role => [role, nodes.get(profile.rig[role])])), layout.schema);
+    const clips = [], frames = [], raw = [], sampleRate = profile.sampleRate;
+    for (const spec of profile.clips) {
+        const { id, file, animation, gait, looping } = spec, nominalVelocity = spec.nominalVelocity ?? [0, 0, 0];
+        const source = containers.get(file).animationGroups.find(g => g.name === animation);
+        const fps = source.targetedAnimations[0].animation.framePerSecond, sourceDuration = (source.to - source.from) / fps;
+        const [start, end] = spec.range ?? [0, sourceDuration], duration = end - start;
+        let motion = spec.motionFile ? JSON.parse(await readFile(publicPath(profile.assetBase + spec.motionFile), 'utf8')) : undefined;
+        if (motion) {
+            validateRootMotion(motion);
+            motion.samples = motion.samples.map(sample => ({ ...sample, x: sample.x * profile.scale, z: sample.z * profile.scale }));
+            if (Math.abs(motion.duration - sourceDuration) > 1e-5)
+                throw new Error(`Motion/GLB time mismatch: ${id}`);
+        }
+        if (motion && spec.range)
+            motion = cropRootMotion(motion, start, end);
+        const descriptor = { id, file, animation, duration, looping, gait,
+            ...Object.fromEntries(['context', 'entryWindows', 'exitWindows', 'excludedWindows'].filter(key => key in spec).map(key => [key, spec[key]])),
+            ...(spec.range ? { sourceStart: start } : {}), ...(spec.rootOrientation ? { rootOrientation: spec.rootOrientation } : {}),
+            ...(motion ? { motionSource: motion.source } : { nominalVelocity, motionSource: 'nominal' }) };
+        const player = new BabylonMotionPlayer(scene, [descriptor], new Map([[id, source]]), targets, 0, profile.stripRoot ?? '');
+        const clipTime = (t) => looping ? ((t % duration) + duration) % duration : Math.max(0, Math.min(t, duration));
+        // Sample the same target model/player/root stripping used at runtime.
+        const sample = (t) => {
+            player.update({ clip: 0, time: clipTime(t), switched: false, match: null }, 0);
+            scene.render();
+            return reader.read(0);
+        };
+        try {
+            const clip = clips.length;
+            clips.push(descriptor);
+            const average = [0, 0, 0], count = Math.ceil(duration * sampleRate);
+            for (let i = 0; i < Math.ceil(duration * sampleRate); i++) {
+                const time = i / sampleRate, h = 1 / sampleRate;
+                const before = sample(time - h), after = sample(time + h), now = sample(time);
+                const measured = motion ? rootMotionFeatures(motion, time, h, layout.horizons, looping) : undefined;
+                const rootVelocity = measured?.velocity ?? nominalVelocity;
+                if (measured)
+                    for (let axis = 0; axis < 3; axis++)
+                        average[axis] += rootVelocity[axis] / count;
+                const elapsed = looping ? 2 * h : clipTime(time + h) - clipTime(time - h);
+                const bones = Object.fromEntries(layout.bones.map(role => {
+                    const position = now.bones[role].position;
+                    const velocity = position.map((_, j) => (after.bones[role].position[j] - before.bones[role].position[j]) / elapsed + rootVelocity[j]);
+                    velocity[0] += (measured?.angularVelocity ?? 0) * position[2];
+                    velocity[2] -= (measured?.angularVelocity ?? 0) * position[0];
+                    return [role, { position, velocity: velocity }];
+                }));
+                const pose = { bones, rootVelocity };
+                const future = measured?.trajectory ?? layout.horizons.map(t => ({ position: [nominalVelocity[0] * t, nominalVelocity[2] * t], facing: [0, 1] }));
+                raw.push(...builder.features(pose, future));
+                frames.push({ clip, time });
+            }
+            if (motion)
+                descriptor.averageVelocity = average;
+        }
+        finally {
+            player.dispose();
+        }
+        console.log(`${id}: ${duration.toFixed(3)}s`);
+    }
+    const db = buildDatabase({ profileId: profile.id, profileSignature: profileSignature(profile), assetHashes: await hashProfileAssets(profile), sampleRate, clips, frames }, Float32Array.from(raw), layout.schema);
+    const output = publicPath(profile.database);
+    await mkdir(output, { recursive: true });
+    await writeFile(`${output}/manifest.json`, JSON.stringify(db.manifest, null, 2));
+    await writeFile(`${output}/poses.bin`, new Uint8Array(encodeFeatures(db)));
+    console.log(`Baked ${frames.length} poses × ${layout.dimensions} features (${layout.schema.id}); ${db.features.byteLength} bytes.`);
+}
+finally {
+    assets.dispose();
+}

package/dist/offline/tools/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/** Node-only entry; paths are relative to the caller, never to this installation. */
+const command = process.argv[2];
+try {
+    if (command === 'bake')
+        await import('./bake.js');
+    else if (command === 'prepare') {
+        const at = process.argv.indexOf('--config');
+        if (at < 0 || !process.argv[at + 1])
+            throw new Error('Provide --config preparation.json');
+        const { readFile } = await import('node:fs/promises');
+        const { parsePreparation, prepareGLB } = await import('./prepare.js');
+        console.log(JSON.stringify(await prepareGLB(parsePreparation(JSON.parse(await readFile(process.argv[at + 1], 'utf8')))), null, 2));
+    }
+    else if (command === 'validate' || command === 'inspect') {
+        if (command === 'inspect')
+            process.argv.splice(3, 0, '--inspect');
+        await import('./validate-assets.js');
+    }
+    else {
+        console.log('pose-flow bake|validate --profile public/profiles/rig.json [--public-dir public]\npose-flow inspect model.glb\npose-flow prepare --config preparation.json');
+        if (command && command !== '--help')
+            process.exitCode = 1;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+export {};

package/dist/offline/tools/glb.js

@@ -0,0 +1,54 @@
+export function readGLB(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length < 20 || view.getUint32(0, true) !== 0x46546c67 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.length)
+        throw new Error('Invalid GLB header');
+    let json, binary = new Uint8Array();
+    for (let offset = 12; offset < bytes.length;) {
+        if (offset + 8 > bytes.length)
+            throw new Error('Truncated GLB chunk');
+        const length = view.getUint32(offset, true), kind = view.getUint32(offset + 4, true);
+        offset += 8;
+        if (length % 4 || offset + length > bytes.length)
+            throw new Error('Invalid GLB chunk');
+        if (kind === 0x4e4f534a)
+            json = JSON.parse(new TextDecoder().decode(bytes.subarray(offset, offset + length)));
+        else if (kind === 0x004e4942)
+            binary = bytes.slice(offset, offset + length);
+        offset += length;
+    }
+    if (!json || json.buffers?.length !== 1 || json.buffers[0].uri || json.buffers[0].byteLength > binary.length || json.images?.some(i => i.uri && !i.uri.startsWith('data:')))
+        throw new Error('Preparation requires a self-contained GLB with one embedded buffer/images');
+    return { json, binary };
+}
+export function writeGLB(json, binary) {
+    const data = new TextEncoder().encode(JSON.stringify(json)), jsonLength = Math.ceil(data.length / 4) * 4, binLength = Math.ceil(binary.length / 4) * 4;
+    const output = new Uint8Array(28 + jsonLength + binLength), view = new DataView(output.buffer);
+    view.setUint32(0, 0x46546c67, true);
+    view.setUint32(4, 2, true);
+    view.setUint32(8, output.length, true);
+    view.setUint32(12, jsonLength, true);
+    view.setUint32(16, 0x4e4f534a, true);
+    output.fill(32, 20, 20 + jsonLength);
+    output.set(data, 20);
+    view.setUint32(20 + jsonLength, binLength, true);
+    view.setUint32(24 + jsonLength, 0x004e4942, true);
+    output.set(binary, 28 + jsonLength);
+    return output;
+}
+export function appendFloats(document, values, width) {
+    if (!values.length || values.length % width || !values.every(Number.isFinite))
+        throw new Error('Invalid prepared samples');
+    const { json } = document, offset = Math.ceil(document.binary.length / 4) * 4;
+    const binary = new Uint8Array(offset + values.length * 4);
+    binary.set(document.binary);
+    const view = new DataView(binary.buffer);
+    values.forEach((v, i) => view.setFloat32(offset + i * 4, v, true));
+    const bufferView = (json.bufferViews ??= []).length;
+    json.bufferViews.push({ buffer: 0, byteOffset: offset, byteLength: values.length * 4 });
+    const accessor = (json.accessors ??= []).length;
+    json.accessors.push({ bufferView, componentType: 5126, count: values.length / width, type: width === 1 ? 'SCALAR' : 'VEC' + width,
+        ...(width === 1 ? { min: [values.reduce((min, v) => Math.min(min, v), Infinity)], max: [values.reduce((max, v) => Math.max(max, v), -Infinity)] } : {}) });
+    json.buffers[0].byteLength = binary.length;
+    document.binary = binary;
+    return accessor;
+}

package/dist/offline/tools/prepare.js

@@ -0,0 +1,165 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { FreeCamera, Matrix, NullEngine, Quaternion, Scene, SceneLoader, Vector3 } from '@babylonjs/core';
+import { GLTFFileLoader } from '@babylonjs/loaders/glTF/index.js';
+import { validateRootMotion } from '../src/index.js';
+import { appendFloats, readGLB, writeGLB } from './glb.js';
+export function parsePreparation(input) {
+    if (!input || typeof input !== 'object')
+        throw new Error('Invalid preparation config');
+    const c = input;
+    if (c.version !== 1 || ![c.input, c.output, c.animation, c.rootNode].every(v => typeof v === 'string' && v.trim())
+        || !['root', 'hips'].includes(c.source) || !['horizontal', 'all'].includes(c.position) || typeof c.heading !== 'boolean'
+        || !Number.isFinite(c.sampleRate) || c.sampleRate < 1 || c.sampleRate > 120
+        || (c.unitScale !== undefined && (!Number.isFinite(c.unitScale) || c.unitScale <= 0))
+        || (c.yawOffset !== undefined && !Number.isFinite(c.yawOffset)))
+        throw new Error('Invalid preparation config');
+    if (c.playbackRate !== undefined && (!Number.isFinite(c.playbackRate) || c.playbackRate < .25 || c.playbackRate > 4))
+        throw new Error('Preparation playbackRate must be between .25 and 4');
+    if (!c.input.endsWith('.glb') || !c.output.endsWith('.glb') || resolve(c.input) === resolve(c.output))
+        throw new Error('Preparation requires distinct input/output GLB paths');
+    return structuredClone(c);
+}
+/** Offline only. No character names; the prepared GLB and measured track are a pair. */
+export async function prepareGLB(input) {
+    const config = parsePreparation(input), bytes = new Uint8Array(await readFile(config.input)), document = readGLB(bytes), { json } = document;
+    const matches = json.nodes.flatMap((node, index) => node.name === config.rootNode ? [index] : []);
+    if (matches.length !== 1)
+        throw new Error('Missing/ambiguous preparation root node');
+    const rootIndex = matches[0];
+    const animations = json.animations?.filter(a => a.name === config.animation);
+    if (animations?.length !== 1)
+        throw new Error('Missing/ambiguous preparation animation');
+    const selected = animations[0];
+    json.animations = [selected];
+    // Keep axis/unit conversion in the exported GLB, not only in the measured JSON.
+    const conversion = Matrix.Scaling(config.unitScale ?? 1, config.unitScale ?? 1, config.unitScale ?? 1).multiply(Matrix.RotationY(config.yawOffset ?? 0));
+    for (const index of json.scenes[json.scene ?? 0].nodes) {
+        const node = json.nodes[index];
+        const original = node.matrix ? Matrix.FromArray(node.matrix) : Matrix.Compose(Vector3.FromArray(node.scale ?? [1, 1, 1]), Quaternion.FromArray(node.rotation ?? [0, 0, 0, 1]), Vector3.FromArray(node.translation ?? [0, 0, 0]));
+        if (selected.channels.some(c => c.target.node === index))
+            throw new Error('Animated scene root requires offline axis/unit conversion before preparation');
+        node.matrix = original.multiply(conversion).asArray();
+        delete node.translation;
+        delete node.rotation;
+        delete node.scale;
+    }
+    const engine = new NullEngine(), scene = new Scene(engine);
+    scene.useRightHandedSystem = true;
+    new FreeCamera('preparation-camera', new Vector3(0, 2, -5), scene);
+    const hook = SceneLoader.OnPluginActivatedObservable.add(p => { if (p instanceof GLTFFileLoader)
+        p.skipMaterials = true; });
+    try {
+        const container = await SceneLoader.LoadAssetContainerAsync('', writeGLB(json, document.binary), scene, undefined, '.glb');
+        container.animationGroups.forEach(g => g.stop());
+        container.addAllToScene();
+        const roots = container.transformNodes.filter(n => n.name === config.rootNode);
+        if (roots.length !== 1)
+            throw new Error('Missing/ambiguous evaluated root');
+        const root = roots[0], group = container.animationGroups[0], fps = group.targetedAnimations[0]?.animation.framePerSecond;
+        if (!fps || group.targetedAnimations.some(t => t.animation.framePerSecond !== fps) || group.to <= group.from)
+            throw new Error('Invalid preparation clip/FPS');
+        const duration = (group.to - group.from) / fps, count = Math.ceil(duration * config.sampleRate);
+        if (count > 1_000_000)
+            throw new Error('Preparation clip too long');
+        const times = [], positions = [], rotations = [], motion = { version: 1, source: config.source, duration, samples: [] };
+        let initialPosition, initialRotation, previousYaw = 0, previousQ;
+        group.start(true, 0);
+        group.pause();
+        for (let i = 0; i <= count; i++) {
+            const time = duration * i / count;
+            group.goToFrame(group.from + time * fps, true);
+            scene.render();
+            root.computeWorldMatrix(true);
+            const scale = new Vector3(), rotation = new Quaternion(), position = new Vector3();
+            if (!root.getWorldMatrix().decompose(scale, rotation, position) || Math.min(scale.x, scale.y, scale.z) <= 0 || Math.max(scale.x, scale.y, scale.z) - Math.min(scale.x, scale.y, scale.z) > 1e-4)
+                throw new Error('Preparation requires positive uniform world scale without shear');
+            const recomposed = Matrix.Compose(scale, rotation, position).asArray();
+            if (root.getWorldMatrix().asArray().some((v, j) => Math.abs(v - recomposed[j]) > 1e-4))
+                throw new Error('Preparation does not support shear');
+            if (root.parent) {
+                const parentScale = new Vector3();
+                root.parent.getWorldMatrix().decompose(parentScale);
+                if (Math.min(parentScale.x, parentScale.y, parentScale.z) <= 0 || Math.max(parentScale.x, parentScale.y, parentScale.z) - Math.min(parentScale.x, parentScale.y, parentScale.z) > 1e-4)
+                    throw new Error('Preparation requires a uniformly scaled root parent');
+            }
+            initialPosition ??= position.clone();
+            initialRotation ??= rotation.clone();
+            const relative = rotation.multiply(initialRotation.conjugate()), forward = new Vector3(0, 0, 1).applyRotationQuaternion(relative);
+            if (config.heading && Math.hypot(forward.x, forward.z) < 1e-5)
+                throw new Error('Undefined planar heading');
+            const angle = Math.atan2(forward.x, forward.z), yaw = config.heading ? previousYaw + Math.atan2(Math.sin(angle - previousYaw), Math.cos(angle - previousYaw)) : 0;
+            previousYaw = yaw;
+            motion.samples.push({ time, x: position.x - initialPosition.x, z: position.z - initialPosition.z, yaw });
+            position.x = initialPosition.x;
+            position.z = initialPosition.z;
+            if (config.position === 'all')
+                position.y = initialPosition.y;
+            const corrected = Matrix.Compose(scale, Quaternion.RotationAxis(Vector3.Up(), -yaw).multiply(rotation), position);
+            const local = root.parent ? corrected.multiply(Matrix.Invert(root.parent.getWorldMatrix())) : corrected;
+            const localScale = new Vector3(), q = new Quaternion(), p = new Vector3();
+            if (!local.decompose(localScale, q, p))
+                throw new Error('Cannot decompose prepared root');
+            if (i === 0) {
+                const node = json.nodes[rootIndex];
+                delete node.matrix;
+                node.translation = p.asArray();
+                node.rotation = q.asArray();
+                node.scale = localScale.asArray();
+            }
+            if (previousQ && Quaternion.Dot(previousQ, q) < 0)
+                q.scaleInPlace(-1);
+            previousQ = q;
+            times.push(time);
+            positions.push(p.x, p.y, p.z);
+            rotations.push(q.x, q.y, q.z, q.w);
+        }
+        const rate = config.playbackRate ?? 1;
+        motion.duration /= rate;
+        motion.samples.forEach(s => s.time /= rate);
+        validateRootMotion(motion);
+        const timeAccessor = appendFloats(document, times.map(t => t / rate), 1);
+        selected.channels = selected.channels.filter(c => c.target.node !== rootIndex || !['translation', 'rotation'].includes(c.target.path));
+        if (rate !== 1) {
+            const remapped = new Map();
+            for (const index of new Set(selected.channels.map(c => c.sampler))) {
+                const sampler = selected.samplers[index];
+                if (sampler.interpolation === 'CUBICSPLINE')
+                    throw new Error('Time scaling requires LINEAR/STEP source channels; resample cubic channels offline first');
+                if (!remapped.has(sampler.input)) {
+                    const accessor = json.accessors[sampler.input];
+                    if (accessor.type !== 'SCALAR' || accessor.componentType !== 5126 || accessor.sparse)
+                        throw new Error('Unsupported timeline accessor');
+                    const view = json.bufferViews[accessor.bufferView];
+                    const data = new DataView(document.binary.buffer, document.binary.byteOffset, document.binary.byteLength);
+                    const values = Array.from({ length: accessor.count }, (_, i) => data.getFloat32((view.byteOffset ?? 0) + (accessor.byteOffset ?? 0) + i * (view.byteStride ?? 4), true) / rate);
+                    remapped.set(sampler.input, appendFloats(document, values, 1));
+                }
+                sampler.input = remapped.get(sampler.input);
+            }
+        }
+        for (const [path, values, width] of [['translation', positions, 3], ['rotation', rotations, 4]]) {
+            const sampler = selected.samplers.length;
+            selected.samplers.push({ input: timeAccessor, output: appendFloats(document, [...values], width), interpolation: 'LINEAR' });
+            selected.channels.push({ sampler, target: { node: rootIndex, path } });
+        }
+        // Babylon GLTF frames are seconds × FPS; GLTF accessor times are seconds.
+        // Reject nonzero source origins rather than silently offsetting other channels.
+        if (Math.abs(group.from) > 1e-5)
+            throw new Error('Preparation requires source animation starting at zero; crop/convert offline first');
+        const output = resolve(config.output), motionFile = output.replace(/\.glb$/, '.motion.json');
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, writeGLB(json, document.binary));
+        await writeFile(motionFile, JSON.stringify(motion, null, 2));
+        const report = { config, inputSHA256: createHash('sha256').update(bytes).digest('hex'), duration: motion.duration, samples: times.length,
+            displacement: motion.samples.at(-1), note: 'Paired prepared GLB + measured planar trajectory. No retargeting; preserve source provenance/license. Horizontal policy preserves vertical motion.' };
+        await writeFile(output.replace(/\.glb$/, '.preparation.json'), JSON.stringify(report, null, 2));
+        return report;
+    }
+    finally {
+        SceneLoader.OnPluginActivatedObservable.remove(hook);
+        scene.dispose();
+        engine.dispose();
+    }
+}

package/dist/offline/tools/profile-assets.js

@@ -0,0 +1,90 @@
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { NullEngine, Scene, SceneLoader, TransformNode } from '@babylonjs/core';
+import { GLTFFileLoader } from '@babylonjs/loaders/glTF/index.js';
+import { parseProfile, resolveProfile, validateRootMotion, compileSchema } from '../src/index.js';
+export function profileArgument() {
+    const at = process.argv.indexOf('--profile');
+    if (at >= 0 && !process.argv[at + 1])
+        throw new Error('Missing --profile JSON path');
+    return at >= 0 ? process.argv[at + 1] : `public/profiles/${process.argv.includes('--paladin') ? 'paladin' : 'kaykit'}.json`;
+}
+export const publicPath = (url) => resolve(process.argv.includes('--public-dir') ? process.argv[process.argv.indexOf('--public-dir') + 1] : 'public', '.' + url);
+export async function hashProfileAssets(profile) {
+    const urls = new Set([profile.model, ...profile.clips.flatMap(c => [c.file, ...(c.motionFile ? [c.motionFile] : [])])].map(f => profile.assetBase + f));
+    return Object.fromEntries(await Promise.all([...urls].sort().map(async (url) => [url, createHash('sha256').update(await readFile(publicPath(url))).digest('hex')])));
+}
+export async function readProfile(path) {
+    const profile = parseProfile(JSON.parse(await readFile(path, 'utf8')));
+    const [schema, set] = await Promise.all([profile.schema, profile.animationSet].map(async (url) => JSON.parse(await readFile(publicPath(url), 'utf8'))));
+    return resolveProfile(profile, schema, set);
+}
+export async function loadProfileAssets(profile) {
+    const layout = compileSchema(profile.schemaDefinition);
+    const engine = new NullEngine(), scene = new Scene(engine);
+    scene.useRightHandedSystem = true;
+    const hook = SceneLoader.OnPluginActivatedObservable.add(p => { if (p instanceof GLTFFileLoader)
+        p.skipMaterials = true; });
+    const containers = new Map();
+    const dispose = () => { SceneLoader.OnPluginActivatedObservable.remove(hook); scene.dispose(); engine.dispose(); };
+    try {
+        for (const file of new Set([profile.model, ...profile.clips.map(c => c.file)])) {
+            const data = new Uint8Array(await readFile(publicPath(profile.assetBase + file)));
+            const container = await SceneLoader.LoadAssetContainerAsync('', data, scene, undefined, '.glb');
+            container.animationGroups.forEach(g => g.stop());
+            for (const node of container.rootNodes)
+                if (node instanceof TransformNode)
+                    node.scaling.scaleInPlace(profile.scale);
+            containers.set(file, container);
+        }
+        const body = containers.get(profile.model);
+        const names = body.transformNodes.map(n => n.name);
+        if (new Set(names).size !== names.length)
+            throw new Error('Ambiguous duplicate model node names');
+        for (const node of [...Object.values(profile.rig), ...(profile.stripRoot ? [profile.stripRoot] : [])])
+            if (!names.includes(node))
+                throw new Error(`Model bone missing: ${node}`);
+        const warnings = [];
+        for (const clip of profile.clips) {
+            const container = containers.get(clip.file);
+            const groups = container.animationGroups.filter(g => g.name === clip.animation);
+            if (groups.length !== 1)
+                throw new Error(`${clip.id}: expected one animation named ${clip.animation}`);
+            const group = groups[0], fps = group.targetedAnimations[0]?.animation.framePerSecond;
+            if (!fps || group.to <= group.from || group.targetedAnimations.some(t => t.animation.framePerSecond !== fps))
+                throw new Error(`${clip.id}: empty clip or inconsistent FPS`);
+            if (clip.range && clip.range[1] > (group.to - group.from) / fps + 1e-6)
+                throw new Error(`${clip.id}: range exceeds source duration`);
+            const mapped = new Set();
+            for (const track of group.targetedAnimations) {
+                const target = profile.boneMap?.[track.target.name] ?? track.target.name;
+                if (!names.includes(target))
+                    throw new Error(`${clip.id}: unmapped target ${track.target.name}; provide boneMap or retarget the animation`);
+                mapped.add(target);
+            }
+            for (const role of Object.values(profile.rig)) {
+                const matches = container.transformNodes.filter(n => (profile.boneMap?.[n.name] ?? n.name) === role);
+                if (matches.length !== 1)
+                    throw new Error(`${clip.id}: missing/ambiguous source bone for ${role}`);
+            }
+            if (clip.motionFile) {
+                const motion = JSON.parse(await readFile(publicPath(profile.assetBase + clip.motionFile), 'utf8'));
+                validateRootMotion(motion);
+                if (Math.abs(motion.duration - (group.to - group.from) / fps) > 1e-5)
+                    throw new Error(`${clip.id}: motion/GLB duration mismatch`);
+            }
+            if (layout.bones.some(role => !mapped.has(profile.rig[role])))
+                warnings.push(`${clip.id}: schema bones depend on inherited transforms; verify visible pose`);
+        }
+        for (const gait of ['idle', 'walk', 'run', 'strafe', 'turn', 'stop'])
+            if (!profile.clips.some(c => c.gait === gait))
+                warnings.push(`Coverage absent: ${gait}`);
+        warnings.push('Name compatibility does not validate bind pose, proportions or retargeting. Visually verify a new rig.');
+        return { scene, engine, containers, warnings, dispose };
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+}

package/dist/offline/tools/rig.js

@@ -0,0 +1,47 @@
+import { Matrix, Quaternion, Vector3 } from '@babylonjs/core';
+import { readGLB } from './glb.js';
+/** Validate rest geometry, not animation names. Missing bind data is an error, never a pass. */
+export function compareBindRigs(target, source, rootName, boneMap = {}, tolerance = .001) {
+    const bind = (bytes) => {
+        const { json, binary } = readGLB(bytes);
+        const skins = json.skins;
+        if (skins?.length !== 1)
+            throw new Error('Bind validation requires exactly one skin with inverse bind matrices');
+        const skin = skins[0], accessor = json.accessors[skin.inverseBindMatrices];
+        if (!accessor || accessor.type !== 'MAT4' || accessor.componentType !== 5126 || accessor.count !== skin.joints.length)
+            throw new Error('Unsupported inverse bind accessor');
+        const view = json.bufferViews[accessor.bufferView];
+        const data = new DataView(binary.buffer, binary.byteOffset, binary.byteLength), result = new Map();
+        skin.joints.forEach((node, index) => {
+            const name = json.nodes[node].name;
+            if (!name || result.has(name))
+                throw new Error('Ambiguous skin joint');
+            const offset = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0) + index * (view.byteStride ?? 64);
+            const matrix = Matrix.FromArray(Array.from({ length: 16 }, (_, j) => data.getFloat32(offset + j * 4, true)));
+            if (!matrix.asArray().every(Number.isFinite) || Math.abs(matrix.determinant()) < 1e-12)
+                throw new Error('Invalid inverse bind matrix');
+            result.set(name, Matrix.Invert(matrix));
+        });
+        return result;
+    };
+    const a = bind(target), b = bind(source), sourceRoot = [...b.keys()].filter(name => (boneMap[name] ?? name) === rootName);
+    if (!a.has(rootName) || sourceRoot.length !== 1)
+        throw new Error('Missing/ambiguous bind root');
+    const inverseA = Matrix.Invert(a.get(rootName)), inverseB = Matrix.Invert(b.get(sourceRoot[0])), errors = [];
+    for (const [name, matrix] of b) {
+        const mapped = boneMap[name] ?? name, targetMatrix = a.get(mapped);
+        if (!targetMatrix) {
+            errors.push(`Missing mapped bind joint: ${name} -> ${mapped}`);
+            continue;
+        }
+        const qa = new Quaternion(), qb = new Quaternion(), pa = new Vector3(), pb = new Vector3(), sa = new Vector3(), sb = new Vector3();
+        targetMatrix.multiply(inverseA).decompose(sa, qa, pa);
+        matrix.multiply(inverseB).decompose(sb, qb, pb);
+        if (Vector3.Distance(pa, pb) > tolerance || Vector3.Distance(sa, sb) > tolerance || 1 - Math.abs(Quaternion.Dot(qa, qb)) > 1e-5)
+            errors.push(`Bind mismatch: ${name} -> ${mapped} (position ${Vector3.Distance(pa, pb).toFixed(5)} m)`);
+    }
+    for (const name of a.keys())
+        if (![...b.keys()].some(sourceName => (boneMap[sourceName] ?? sourceName) === name))
+            errors.push('Missing source bind joint: ' + name);
+    return errors;
+}

package/dist/offline/tools/validate-assets.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import { NullEngine, Scene, SceneLoader } from '@babylonjs/core';
+import { GLTFFileLoader } from '@babylonjs/loaders/glTF/index.js';
+import { suggestRig } from '../src/index.js';
+import { loadProfileAssets, profileArgument, publicPath, readProfile } from './profile-assets.js';
+import { compareBindRigs } from './rig.js';
+const inspectAt = process.argv.indexOf('--inspect');
+if (inspectAt >= 0) {
+    const path = process.argv[inspectAt + 1];
+    if (!path)
+        throw new Error('Provide a local GLB path after --inspect');
+    const engine = new NullEngine(), scene = new Scene(engine);
+    scene.useRightHandedSystem = true;
+    const hook = SceneLoader.OnPluginActivatedObservable.add(p => { if (p instanceof GLTFFileLoader)
+        p.skipMaterials = true; });
+    try {
+        const container = await SceneLoader.LoadAssetContainerAsync('', new Uint8Array(await readFile(path)), scene, undefined, '.glb');
+        const nodes = container.transformNodes.map(n => n.name);
+        console.log(JSON.stringify({ nodes, animations: container.animationGroups.map(g => g.name), suggestions: suggestRig(nodes), note: 'Suggestions require explicit confirmation in a profile; ambiguous roots are not selected automatically.' }, null, 2));
+    }
+    finally {
+        SceneLoader.OnPluginActivatedObservable.remove(hook);
+        scene.dispose();
+        engine.dispose();
+    }
+}
+else {
+    const profile = await readProfile(profileArgument()), assets = await loadProfileAssets(profile);
+    try {
+        if (process.argv.includes('--check-bind')) {
+            const target = new Uint8Array(await readFile(publicPath(profile.assetBase + profile.model)));
+            for (const file of new Set(profile.clips.map(c => c.file))) {
+                const errors = compareBindRigs(target, new Uint8Array(await readFile(publicPath(profile.assetBase + file))), profile.rig.root, profile.boneMap);
+                if (errors.length)
+                    throw new Error(`${file}: incompatible bind geometry; retarget offline first\n${errors.join('\n')}`);
+            }
+        }
+        console.log(JSON.stringify({ profile: profile.id, valid: true, bindChecked: process.argv.includes('--check-bind'), clips: profile.clips.length, warnings: assets.warnings }, null, 2));
+    }
+    finally {
+        assets.dispose();
+    }
+}

package/package.json

@@ -1,39 +1,48 @@
-{
-  "name": "@pose_flow/babylon",
-  "version": "0.1.0",
-  "license": "MIT",
-  "type": "module",
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./babylon": {
-      "types": "./dist/babylon.d.ts",
-      "import": "./dist/babylon.js"
-    }
-  },
-  "scripts": {
-    "dev": "vite --host 127.0.0.1",
-    "build": "tsc -p tsconfig.build.json && vite build",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx --test tests/*.test.ts",
-    "bake": "tsx tools/bake.ts",
-    "validate:assets": "tsx tools/validate-assets.ts",
-    "benchmark": "tsx tools/benchmark.ts"
-  },
-  "peerDependencies": {
-    "@babylonjs/core": "^7.54.3"
-  },
-  "devDependencies": {
-    "@babylonjs/core": "7.54.3",
-    "@babylonjs/loaders": "7.54.3",
-    "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vite": "^6.0.0"
-  }
-}
+{
+  "name": "@pose_flow/babylon",
+  "version": "0.3.0",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./babylon": {
+      "types": "./dist/babylon.d.ts",
+      "import": "./dist/babylon.js"
+    },
+    "./AI_USAGE.md": "./dist/AI_USAGE.md",
+    "./PUBLISHING.md": "./dist/PUBLISHING.md"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.offline.json && vite build && node tools/copy-docs.mjs",
+    "prepack": "npm run build",
+    "check:docs": "node tools/copy-docs.mjs --check",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "bake": "tsx tools/bake.ts",
+    "validate:assets": "tsx tools/validate-assets.ts",
+    "benchmark": "tsx tools/benchmark.ts"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": "^9.32.1"
+  },
+  "devDependencies": {
+    "@babylonjs/core": "9.32.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  },
+  "bin": {
+    "pose-flow": "./dist/offline/tools/cli.js"
+  },
+  "dependencies": {
+    "@babylonjs/loaders": "9.32.1"
+  }
+}