@pose_flow/babylon 0.1.0 → 0.3.0

package/dist/offline/src/core/profile.js

@@ -0,0 +1,103 @@
+import { compileSchema, parseSchema } from './schema.js';
+import { validateContext, validateSelection } from './selection.js';
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const name = (v) => typeof v === 'string' && v.trim().length > 0;
+const asset = (v) => name(v) && !v.includes('\\') && !v.includes('..') && !/[?#:]/.test(v);
+export function parseRootOrientation(value) {
+    if (!Array.isArray(value) || value.length !== 4 || ![...value].every(Number.isFinite) || Math.abs(Math.hypot(...value) - 1) > 1e-5)
+        throw new Error('Invalid rootOrientation: expected unit quaternion [x,y,z,w]');
+    return [...value];
+}
+/** Read untrusted JSON as unknown; report a configuration error before loading assets. */
+export function parseProfile(input) {
+    if (!record(input) || input.version !== 2 || !name(input.id) || !/^[a-z0-9][a-z0-9-]*$/.test(input.id) || !name(input.label))
+        throw new Error('Profile: expected version 2; split v1 clips into animationSet and declare schema');
+    if ('clips' in input || !asset(input.schema) || !input.schema.startsWith('/') || !input.schema.endsWith('.json')
+        || !asset(input.animationSet) || !input.animationSet.startsWith('/') || !input.animationSet.endsWith('.json'))
+        throw new Error('Profile: declare schema and animationSet JSON URLs, without inline clips');
+    if (!asset(input.assetBase) || !input.assetBase.startsWith('/') || !input.assetBase.endsWith('/') || !asset(input.database) || !input.database.startsWith('/') || !input.database.endsWith('/')
+        || !asset(input.model) || input.model.startsWith('/'))
+        throw new Error('Profile: use public URL folders and relative model files');
+    if (typeof input.scale !== 'number' || !Number.isFinite(input.scale) || input.scale <= 0 || typeof input.sampleRate !== 'number' || !Number.isFinite(input.sampleRate) || input.sampleRate < 1 || input.sampleRate > 120)
+        throw new Error('Profile: invalid scale/sampleRate');
+    if (!record(input.rig) || !name(input.rig.root) || !Object.entries(input.rig).every(([k, v]) => /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(k) && name(v)))
+        throw new Error('Profile: semantic rig roles must be mapped');
+    if (new Set(Object.values(input.rig)).size !== Object.values(input.rig).length)
+        throw new Error('Profile: required bones must be distinct');
+    if (input.stripRoot !== undefined && !name(input.stripRoot))
+        throw new Error('Profile: invalid stripRoot');
+    if (input.masks !== undefined && (!record(input.masks) || !Object.entries(input.masks).length || !Object.entries(input.masks).every(([key, values]) => name(key)
+        && Array.isArray(values) && values.length > 0 && values.every(name) && new Set(values).size === values.length)))
+        throw new Error('Profile: invalid masks');
+    if (input.layerPreview !== undefined) {
+        const preview = input.layerPreview, masks = input.masks;
+        if (!record(preview) || !name(preview.baseMask) || !name(preview.overlayMask) || !masks || !Object.hasOwn(masks, preview.baseMask) || !Object.hasOwn(masks, preview.overlayMask)
+            || masks[preview.baseMask].some(node => masks[preview.overlayMask].includes(node)))
+            throw new Error('Profile: layer preview requires two disjoint masks');
+        validateContext(preview.context);
+        if (!Object.keys(preview.context).length)
+            throw new Error('Profile: layer preview requires explicit context');
+    }
+    if (input.boneMap !== undefined && (!record(input.boneMap) || !Object.entries(input.boneMap).every(([k, v]) => name(k) && name(v)) || new Set(Object.values(input.boneMap)).size !== Object.values(input.boneMap).length))
+        throw new Error('Profile: boneMap must map distinct nonempty names');
+    return structuredClone(input);
+}
+export function parseAnimationSet(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || !Array.isArray(input.clips) || !input.clips.length)
+        throw new Error('AnimationSet: invalid version/id/clips');
+    const ids = new Set();
+    for (const clip of input.clips) {
+        if (!record(clip) || !name(clip.id) || ids.has(clip.id) || !asset(clip.file) || clip.file.startsWith('/') || !name(clip.animation) || typeof clip.looping !== 'boolean'
+            || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(String(clip.gait)))
+            throw new Error('Profile: invalid/duplicate clip');
+        ids.add(clip.id);
+        if (clip.rootOrientation !== undefined)
+            parseRootOrientation(clip.rootOrientation);
+        if (clip.range !== undefined && (!Array.isArray(clip.range) || clip.range.length !== 2 || !clip.range.every(Number.isFinite) || clip.range[0] < 0 || clip.range[1] <= clip.range[0]))
+            throw new Error('Invalid clip range');
+        validateSelection(clip, Array.isArray(clip.range) ? clip.range[1] - clip.range[0] : Infinity);
+        const nominal = clip.nominalVelocity !== undefined, measured = clip.motionFile !== undefined;
+        if (nominal === measured)
+            throw new Error(`Profile ${clip.id}: declare exactly one of nominalVelocity or motionFile`);
+        if (nominal && (!Array.isArray(clip.nominalVelocity) || clip.nominalVelocity.length !== 3 || !clip.nominalVelocity.every(Number.isFinite)))
+            throw new Error(`Profile ${clip.id}: invalid velocity`);
+        if (measured && (!asset(clip.motionFile) || clip.motionFile.startsWith('/')))
+            throw new Error(`Profile ${clip.id}: measured motion requires a relative file`);
+    }
+    return structuredClone(input);
+}
+/** Resolve external configuration explicitly; core performs no I/O. */
+export function resolveProfile(profile, schemaInput, setInput) {
+    const config = parseProfile(profile), schemaDefinition = parseSchema(schemaInput), set = parseAnimationSet(setInput);
+    for (const role of compileSchema(schemaDefinition).bones)
+        if (!Object.hasOwn(config.rig, role))
+            throw new Error('Profile: missing schema bone role: ' + role);
+    if (!config.stripRoot && set.clips.some(c => c.rootOrientation !== undefined))
+        throw new Error('Profile: rootOrientation requires stripRoot');
+    return { ...config, schemaDefinition, clips: set.clips, setId: set.id };
+}
+/** Deterministic configuration fingerprint; detects stale banks, not a security signature. */
+export function profileSignature(profile) {
+    const sorted = (value) => Array.isArray(value) ? value.map(sorted) : record(value) ? Object.fromEntries(Object.keys(value).sort().map(k => [k, sorted(value[k])])) : value;
+    const text = JSON.stringify(sorted(profile));
+    let hash = 2166136261;
+    for (let i = 0; i < text.length; i++)
+        hash = Math.imul(hash ^ text.charCodeAt(i), 16777619);
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/** Suggestions only: ambiguity is returned to the caller, never silently resolved. */
+export function suggestRig(names) {
+    const aliases = { root: ['root', 'hips', 'pelvis'], leftFoot: ['footl', 'leftfoot', 'lfoot'], rightFoot: ['footr', 'rightfoot', 'rfoot'] };
+    return Object.fromEntries(Object.entries(aliases).map(([role, values]) => [role, names.filter(n => values.includes(n.split(':').at(-1).toLowerCase().replace(/[^a-z]/g, '')))]));
+}
+/** Semantic availability, independent of character/clip names. Preserve optional actions. */
+export function filterLocomotionGaits(available, speed) {
+    if (!Number.isFinite(speed) || speed < 0)
+        throw new Error('Invalid locomotion speed');
+    const result = new Set(available), movement = ['walk', 'run', 'strafe'];
+    if (speed > 0.2 && movement.some(g => result.has(g)))
+        result.delete('idle');
+    else if (speed < 0.05 && result.has('idle'))
+        movement.forEach(g => result.delete(g));
+    return result;
+}

package/dist/offline/src/core/root-motion.js

@@ -0,0 +1,78 @@
+import { HORIZONS } from './types.js';
+import { toLocal } from './features.js';
+import { validateHorizons } from './schema.js';
+export function validateRootMotion(track) {
+    if (!track || track.version !== 1 || !['hips', 'root'].includes(track.source) || !Number.isFinite(track.duration) || track.duration <= 0 || !Array.isArray(track.samples) || track.samples.length < 2)
+        throw new Error('Invalid root motion track');
+    let previous = -Infinity;
+    for (const sample of track.samples) {
+        if (!sample || ![sample.time, sample.x, sample.z, sample.yaw].every(Number.isFinite) || sample.time <= previous || sample.time < 0 || sample.time > track.duration + 1e-6)
+            throw new Error('Invalid root motion sample');
+        previous = sample.time;
+    }
+    if (track.samples[0].time !== 0 || Math.abs(track.samples.at(-1).time - track.duration) > 1e-6)
+        throw new Error('Incomplete root motion track');
+}
+/** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
+export function sampleRootMotion(track, time, looping = false) {
+    if (!Number.isFinite(time))
+        throw new Error('Invalid root motion time');
+    if (looping) {
+        const cycle = Math.floor(time / track.duration), phase = time - cycle * track.duration;
+        if (!Number.isSafeInteger(cycle))
+            throw new Error('Root motion cycle out of range');
+        const first = track.samples[0], last = track.samples.at(-1);
+        const delta = toLocal(last.x - first.x, last.z - first.z, first.yaw), angle = last.yaw - first.yaw;
+        // Exponentiate planar rigid transforms, including negative cycles.
+        const compose = (a, b) => ({ time,
+            x: a.x + Math.cos(a.yaw) * b.x + Math.sin(a.yaw) * b.z,
+            z: a.z - Math.sin(a.yaw) * b.x + Math.cos(a.yaw) * b.z, yaw: a.yaw + b.yaw });
+        let power = { time, x: delta[0], z: delta[1], yaw: angle };
+        if (cycle < 0) {
+            const v = toLocal(-power.x, -power.z, angle);
+            power = { time, x: v[0], z: v[1], yaw: -angle };
+        }
+        let result = { time, x: 0, z: 0, yaw: 0 }, count = Math.abs(cycle);
+        while (count > 0) {
+            if (count % 2 === 1)
+                result = compose(result, power);
+            power = compose(power, power);
+            count = Math.floor(count / 2);
+        }
+        const sample = sampleRootMotion(track, phase), local = toLocal(sample.x - first.x, sample.z - first.z, first.yaw);
+        return compose(first, compose(result, { time, x: local[0], z: local[1], yaw: sample.yaw - first.yaw }));
+    }
+    const t = Math.max(0, Math.min(time, track.duration)), samples = track.samples;
+    let lo = 0, hi = samples.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >>> 1;
+        if (samples[mid].time <= t)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = samples[lo], b = samples[hi], alpha = (t - a.time) / (b.time - a.time);
+    return { time: t, x: a.x + (b.x - a.x) * alpha, z: a.z + (b.z - a.z) * alpha, yaw: a.yaw + (b.yaw - a.yaw) * alpha };
+}
+export function rootMotionFeatures(track, time, derivativeStep = 1 / 30, horizons = HORIZONS, looping = false) {
+    validateHorizons(horizons);
+    if (!Number.isFinite(derivativeStep) || derivativeStep <= 0)
+        throw new Error('Invalid derivative step');
+    const now = sampleRootMotion(track, time, looping), a = sampleRootMotion(track, time - derivativeStep, looping), b = sampleRootMotion(track, time + derivativeStep, looping);
+    const elapsed = b.time - a.time;
+    const v = elapsed > 0 ? toLocal((b.x - a.x) / elapsed, (b.z - a.z) / elapsed, now.yaw) : [0, 0];
+    return { velocity: [v[0], 0, v[1]], angularVelocity: elapsed > 0 ? (b.yaw - a.yaw) / elapsed : 0,
+        trajectory: horizons.map(horizon => {
+            const future = sampleRootMotion(track, time + horizon, looping), yaw = future.yaw - now.yaw;
+            return { position: toLocal(future.x - now.x, future.z - now.z, now.yaw), facing: [Math.sin(yaw), Math.cos(yaw)] };
+        }) };
+}
+/** Crop to the same source interval as playback; preserve the source coordinate frame. */
+export function cropRootMotion(track, start, end) {
+    validateRootMotion(track);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start || end > track.duration)
+        throw new Error('Invalid root motion range');
+    const samples = [sampleRootMotion(track, start), ...track.samples.filter(s => s.time > start && s.time < end), sampleRootMotion(track, end)]
+        .map(s => ({ ...s, time: s.time - start }));
+    return { version: 1, source: track.source, duration: end - start, samples };
+}

package/dist/offline/src/core/scenario.js

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

package/dist/offline/src/core/schema.js

@@ -0,0 +1,123 @@
+export const LOCOMOTION_SCHEMA = {
+    version: 1, id: 'biped-locomotion', channels: [
+        { id: 'left-position', kind: 'bone-position', bone: 'leftFoot', weight: 1, normalization: 'standard' },
+        { id: 'right-position', kind: 'bone-position', bone: 'rightFoot', weight: 1, normalization: 'standard' },
+        { id: 'left-velocity', kind: 'bone-velocity', bone: 'leftFoot', weight: 1, normalization: 'standard' },
+        { id: 'right-velocity', kind: 'bone-velocity', bone: 'rightFoot', weight: 1, normalization: 'standard' },
+        { id: 'root-velocity', kind: 'root-velocity', weight: 1, normalization: 'standard' },
+        { id: 'future-position', kind: 'trajectory-position', horizons: [0.2, 0.4, 0.6], weight: 3, normalization: 'standard' },
+        { id: 'future-facing', kind: 'trajectory-facing', horizons: [0.2, 0.4, 0.6], weight: 3, normalization: 'standard' },
+    ],
+};
+for (const channel of LOCOMOTION_SCHEMA.channels) {
+    if ('horizons' in channel)
+        Object.freeze(channel.horizons);
+    Object.freeze(channel);
+}
+Object.freeze(LOCOMOTION_SCHEMA.channels);
+Object.freeze(LOCOMOTION_SCHEMA);
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const name = (v) => typeof v === 'string' && /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(v);
+export function validateHorizons(input) {
+    if (!Array.isArray(input) || input.length > 64 || [...input].some((v, i) => !Number.isFinite(v) || v <= 0 || v > 10 || (i > 0 && v <= input[i - 1])))
+        throw new Error('Schema: at most 64 horizons, increasing within (0, 10] seconds');
+}
+/** Strict JSON parsing: unsupported channels/options fail instead of being ignored. */
+export function parseSchema(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || Object.keys(input).some(k => !['version', 'id', 'channels'].includes(k))
+        || !Array.isArray(input.channels) || !input.channels.length || input.channels.length > 128)
+        throw new Error('Schema: invalid version/id/channels');
+    const ids = new Set();
+    const channels = [...input.channels].map(value => {
+        if (!record(value) || !name(value.id) || ids.has(value.id) || typeof value.weight !== 'number' || !Number.isFinite(Math.fround(value.weight)) || value.weight < 0 || (value.weight > 0 && Math.fround(value.weight) === 0)
+            || !['standard', 'none'].includes(String(value.normalization)))
+            throw new Error('Schema: invalid channel id/weight/normalization');
+        ids.add(value.id);
+        const common = { id: value.id, kind: value.kind, weight: value.weight, normalization: value.normalization };
+        let result;
+        if (value.kind === 'bone-position' || value.kind === 'bone-velocity') {
+            if (!name(value.bone) || value.bone === 'root')
+                throw new Error('Schema: invalid semantic bone role');
+            result = { ...common, bone: value.bone };
+        }
+        else if (value.kind === 'root-velocity')
+            result = common;
+        else if (value.kind === 'trajectory-position' || value.kind === 'trajectory-facing') {
+            if (!Array.isArray(value.horizons) || !value.horizons.length)
+                throw new Error('Schema: missing horizons');
+            validateHorizons(value.horizons);
+            result = { ...common, horizons: [...value.horizons] };
+        }
+        else
+            throw new Error('Schema: unsupported channel kind');
+        if (Object.keys(value).some(k => !Object.hasOwn(result, k)))
+            throw new Error('Schema: unsupported channel option');
+        return result;
+    });
+    if (!channels.some(c => c.weight > 0))
+        throw new Error('Schema: at least one positive weight required');
+    validateHorizons([...new Set(channels.flatMap(c => 'horizons' in c ? [...c.horizons] : []))].sort((a, b) => a - b));
+    return { version: 1, id: input.id, channels };
+}
+/** Canonical content identity, not a lossy hash. Order of channels is significant. */
+export function compileSchema(input) {
+    const schema = parseSchema(input), bones = new Set(), horizons = new Set();
+    let dimensions = 0;
+    const channels = schema.channels.map(channel => {
+        if ('bone' in channel)
+            bones.add(channel.bone);
+        if ('horizons' in channel)
+            channel.horizons.forEach(h => horizons.add(h));
+        const width = 'horizons' in channel ? 2 * channel.horizons.length : 3;
+        const layout = Object.freeze({ channel, offset: dimensions, dimensions: width });
+        dimensions += width;
+        if ('horizons' in channel)
+            Object.freeze(channel.horizons);
+        Object.freeze(channel);
+        return layout;
+    });
+    Object.freeze(schema.channels);
+    Object.freeze(schema);
+    return Object.freeze({ schema, signature: 'pose-schema-v1:' + JSON.stringify(schema), dimensions,
+        channels: Object.freeze(channels), bones: Object.freeze([...bones]), horizons: Object.freeze([...horizons].sort((a, b) => a - b)) });
+}
+/** One encoder shared by bake and runtime. Trajectory points follow the sorted union of horizons. */
+export class SchemaQueryBuilder {
+    layout;
+    horizonIndices;
+    constructor(schema = LOCOMOTION_SCHEMA) {
+        this.layout = compileSchema(schema);
+        this.horizonIndices = new Map(this.layout.horizons.map((h, i) => [h, i]));
+    }
+    features(pose, trajectory, out = new Float32Array(this.layout.dimensions)) {
+        if (trajectory.length !== this.layout.horizons.length || out.length !== this.layout.dimensions)
+            throw new Error('Invalid schema pose/trajectory dimensions');
+        const put = (values, offset, length) => {
+            if (!values || values.length !== length || !values.every(Number.isFinite))
+                throw new Error('Invalid schema feature values');
+            out.set(values, offset);
+        };
+        for (const { channel, offset } of this.layout.channels) {
+            if ('bone' in channel) {
+                const bone = Object.hasOwn(pose.bones, channel.bone) ? pose.bones[channel.bone] : undefined;
+                if (!bone)
+                    throw new Error('Missing semantic bone: ' + channel.bone);
+                put(channel.kind === 'bone-position' ? bone.position : bone.velocity, offset, 3);
+            }
+            else if ('horizons' in channel) {
+                channel.horizons.forEach((h, i) => {
+                    const point = trajectory[this.horizonIndices.get(h)];
+                    put(channel.kind === 'trajectory-position' ? point?.position : point?.facing, offset + i * 2, 2);
+                });
+            }
+            else
+                put(pose.rootVelocity, offset, 3);
+        }
+        if (!out.every(Number.isFinite))
+            throw new Error('Invalid schema float32 feature values');
+        return out;
+    }
+    build(pose, trajectory) {
+        return { features: this.features(pose, trajectory), schemaSignature: this.layout.signature };
+    }
+}

package/dist/offline/src/core/search.js

@@ -0,0 +1,181 @@
+import { validateDatabase } from './database.js';
+import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+import { matchesContext, validateContext, withinWindows } from './selection.js';
+export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
+    const layout = compileSchema(schema), weights = new Float32Array(layout.dimensions);
+    for (const { channel, offset, dimensions } of layout.channels)
+        weights.fill(channel.weight, offset, offset + dimensions);
+    if (!weights.every(Number.isFinite))
+        throw new Error('Invalid feature weights');
+    return weights;
+}
+const legacySignature = compileSchema(LOCOMOTION_SCHEMA).signature;
+export function readCandidateTrajectory(database, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= database.manifest.frames.length)
+        throw new Error('Invalid candidate frame');
+    const { dimensions, mean, std } = database.manifest, layout = compileSchema(database.manifest.schema);
+    const points = new Map(layout.horizons.map(horizon => [horizon, { horizon }]));
+    for (const { channel, offset } of layout.channels)
+        if (channel.kind === 'trajectory-position' || channel.kind === 'trajectory-facing') {
+            channel.horizons.forEach((horizon, h) => {
+                const j = offset + h * 2, value = [database.features[index * dimensions + j] * std[j] + mean[j], database.features[index * dimensions + j + 1] * std[j + 1] + mean[j + 1]];
+                points.get(horizon)[channel.kind === 'trajectory-position' ? 'position' : 'facing'] = value;
+            });
+        }
+    return [...points.values()];
+}
+export class PoseSearch {
+    database;
+    normalized;
+    dimensions;
+    rootOffset;
+    weights;
+    constructor(database, weights) {
+        this.database = database;
+        validateDatabase(database);
+        this.dimensions = database.manifest.dimensions;
+        this.rootOffset = compileSchema(database.manifest.schema).channels.find(c => c.channel.kind === 'root-velocity')?.offset;
+        this.normalized = new Float32Array(this.dimensions);
+        weights ??= defaultWeights(database.manifest.schema);
+        if (weights.length !== this.dimensions || !weights.every(v => Number.isFinite(v) && v >= 0))
+            throw new Error('Invalid feature weights');
+        this.weights = weights.slice();
+    }
+    validateQuery(query) {
+        if (query.context !== undefined)
+            validateContext(query.context);
+        if (query.schemaSignature !== this.database.manifest.schemaSignature && !(query.schemaSignature === undefined && this.database.manifest.schemaSignature === legacySignature))
+            throw new Error('Incompatible query schema');
+        if (query.features.length !== this.dimensions || !query.features.every(Number.isFinite))
+            throw new Error('Invalid pose query');
+        if (query.allowTemporalReselection !== undefined && typeof query.allowTemporalReselection !== 'boolean')
+            throw new Error('Invalid temporal reselection option');
+        if (query.velocityTolerance !== undefined && (!Number.isFinite(query.velocityTolerance) || query.velocityTolerance < 0 || this.rootOffset === undefined))
+            throw new Error('Velocity tolerance requires a root-velocity channel and a finite nonnegative value');
+    }
+    /** Context/gait validity is separate from eligibility to enter at a sample. */
+    allowsClip(clip, query) {
+        const descriptor = this.database.manifest.clips[clip];
+        return !!descriptor && !query.excludedClips?.has(clip) && (!query.gaits || query.gaits.has(descriptor.gait)) && (!query.context || matchesContext(descriptor.context, query.context));
+    }
+    allowsFrame(index, query) {
+        const frame = this.database.manifest.frames[index], clip = this.database.manifest.clips[frame.clip];
+        return this.allowsClip(frame.clip, query) && withinWindows(frame.time, clip.entryWindows)
+            && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows));
+    }
+    normalize(query) {
+        this.validateQuery(query);
+        const { mean, std } = this.database.manifest;
+        for (let j = 0; j < this.dimensions; j++)
+            this.normalized[j] = (query.features[j] - mean[j]) / std[j];
+        if (!this.normalized.every(Number.isFinite))
+            throw new Error('Invalid normalized pose query');
+    }
+    cost(index) {
+        const { features } = this.database;
+        let sum = 0;
+        for (let j = 0; j < this.dimensions; j++)
+            sum += this.weights[j] * (this.normalized[j] - features[index * this.dimensions + j]) ** 2;
+        return sum;
+    }
+    /** Physical error, independent of normalization/pose weights. Query must have been validated. */
+    rootVelocityError(index, query) {
+        if (this.rootOffset === undefined || !Number.isInteger(index) || index < 0 || index >= this.database.manifest.frames.length)
+            return Infinity;
+        const { mean, std } = this.database.manifest;
+        let squared = 0;
+        for (let axis = 0; axis < 3; axis++) {
+            const j = this.rootOffset + axis, value = this.database.features[index * this.dimensions + j] * std[j] + mean[j];
+            squared += (value - query.features[j]) ** 2;
+        }
+        return Math.sqrt(squared);
+    }
+    search(query) {
+        this.normalize(query);
+        const { frames, clips } = this.database.manifest;
+        // Context is clip-level: resolve it once per clip, rather than once per
+        // sample in each of the velocity and ranking passes.
+        const eligibleClips = clips.map((_, clip) => this.allowsClip(clip, query));
+        const candidates = [];
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i], clip = clips[frame.clip];
+            if (eligibleClips[frame.clip] && withinWindows(frame.time, clip.entryWindows)
+                && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows)))
+                candidates.push(i);
+        }
+        let index = -1, cost = Infinity;
+        let velocityLimit = Infinity;
+        if (query.velocityTolerance !== undefined) {
+            let nearest = Infinity;
+            for (const i of candidates) {
+                nearest = Math.min(nearest, this.rootVelocityError(i, query));
+            }
+            // Sparse datasets retain a deterministic nearest-velocity fallback. Never
+            // expand the pool to arbitrary stationary poses just because coverage is missing.
+            velocityLimit = Math.max(query.velocityTolerance, nearest + 1e-6);
+        }
+        for (const i of candidates) {
+            if (query.velocityTolerance !== undefined && this.rootVelocityError(i, query) > velocityLimit)
+                continue;
+            const score = this.cost(i);
+            if (score < cost) {
+                index = i;
+                cost = score;
+            }
+        }
+        return index < 0 ? null : { ...frames[index], index, cost };
+    }
+    /** Opt-in diagnostic pass. Bounded output, exact ranking, no change to filters/weights. */
+    inspect(query, limit = 5) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+            throw new Error('Invalid diagnostic limit');
+        const best = this.search(query), { frames, clips } = this.database.manifest;
+        const rejected = { 'excluded-clip': 0, gait: 0, context: 0, 'entry-window': 0, 'excluded-window': 0, velocity: 0 };
+        const examples = [], candidates = [];
+        const layout = compileSchema(this.database.manifest.schema);
+        let nearest = Infinity, eligible = 0;
+        if (query.velocityTolerance !== undefined)
+            for (let i = 0; i < frames.length; i++)
+                if (this.allowsFrame(i, query))
+                    nearest = Math.min(nearest, this.rootVelocityError(i, query));
+        const velocityLimit = query.velocityTolerance === undefined ? null : Math.max(query.velocityTolerance, nearest + 1e-6);
+        for (let index = 0; index < frames.length; index++) {
+            const frame = frames[index], clip = clips[frame.clip];
+            let reason;
+            if (query.excludedClips?.has(frame.clip))
+                reason = 'excluded-clip';
+            else if (query.gaits && !query.gaits.has(clip.gait))
+                reason = 'gait';
+            else if (!matchesContext(clip.context, query.context))
+                reason = 'context';
+            else if (!withinWindows(frame.time, clip.entryWindows))
+                reason = 'entry-window';
+            else if (clip.excludedWindows !== undefined && withinWindows(frame.time, clip.excludedWindows))
+                reason = 'excluded-window';
+            else if (velocityLimit !== null && this.rootVelocityError(index, query) > velocityLimit)
+                reason = 'velocity';
+            if (reason) {
+                rejected[reason]++;
+                if (examples.length < limit)
+                    examples.push({ index, ...frame, reason });
+                continue;
+            }
+            eligible++;
+            const cost = this.cost(index);
+            if (candidates.length >= limit && cost >= candidates[candidates.length - 1].cost)
+                continue;
+            const channels = layout.channels.map(({ channel, offset, dimensions }) => {
+                let cost = 0;
+                for (let j = offset; j < offset + dimensions; j++)
+                    cost += this.weights[j] * (this.normalized[j] - this.database.features[index * this.dimensions + j]) ** 2;
+                return { id: channel.id, cost };
+            });
+            const candidate = { index, ...frame, cost, channels, velocityError: this.rootOffset === undefined ? null : this.rootVelocityError(index, query) };
+            const at = candidates.findIndex(c => c.cost > cost);
+            candidates.splice(at < 0 ? candidates.length : at, 0, candidate);
+            if (candidates.length > limit)
+                candidates.pop();
+        }
+        return { best, candidates, rejected, examples, eligible, total: frames.length, velocityLimit: Number.isFinite(velocityLimit) ? velocityLimit : null };
+    }
+}

package/dist/offline/src/core/selection.js

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

package/dist/offline/src/core/types.js

@@ -0,0 +1,3 @@
+/** Legacy preset constants; dynamic consumers must use compileSchema. */
+export const DIMENSIONS = 27;
+export const HORIZONS = [0.2, 0.4, 0.6];

package/dist/offline/src/index.js

@@ -0,0 +1,11 @@
+export * from './core/types.js';
+export * from './core/schema.js';
+export * from './core/features.js';
+export * from './core/database.js';
+export * from './core/search.js';
+export * from './core/controller.js';
+export * from './core/root-motion.js';
+export * from './core/profile.js';
+export * from './core/selection.js';
+export * from './core/inertialization.js';
+export * from './core/scenario.js';