@its-not-rocket-science/ananke 0.1.0

package/dist/src/bridge/bridge-engine.d.ts

@@ -0,0 +1,46 @@
+import type { BridgeConfig, InterpolatedState } from "./types.js";
+import type { RigSnapshot } from "../model3d.js";
+import type { MotionVector, ConditionSample } from "../debug.js";
+export declare class BridgeEngine {
+    private config;
+    private entities;
+    /** Simulation time of the previous snapshot (seconds) */
+    private prevTime_s;
+    /** Simulation time of the current snapshot (seconds) */
+    private currTime_s;
+    /** Corresponding tick numbers */
+    private prevTick;
+    private currTick;
+    /** Default bone name for unmapped segments */
+    private defaultBoneName;
+    constructor(config: BridgeConfig);
+    /** Update the bridge configuration (does not affect already stored snapshots). */
+    updateConfig(config: BridgeConfig): void;
+    /** Register or update the body plan ID for an entity. */
+    setEntityBodyPlan(entityId: number, bodyPlanId: string): void;
+    /**
+     * Ingests new simulation tick data.
+     * Called at simulation rate (typically 20 Hz).
+     * @param snapshots Rig snapshots from extractRigSnapshots()
+     * @param motion Motion vectors from extractMotionVectors() (optional)
+     * @param condition Condition samples from extractConditionSamples() (optional)
+     */
+    update(snapshots: RigSnapshot[], motion?: MotionVector[], condition?: ConditionSample[]): void;
+    /**
+     * Compute interpolated state for an entity at a given render time.
+     * @param entityId Entity ID
+     * @param renderTime_s Render time in real seconds (monotonically increasing)
+     * @returns Interpolated state, or null if entity not found or insufficient data
+     */
+    getInterpolatedState(entityId: number, renderTime_s: number): InterpolatedState | null;
+    /** Get the simulation time (seconds) of the latest tick. */
+    getLatestSimTime(): number;
+    /** Get the simulation tick of the latest snapshot. */
+    getLatestTick(): number;
+    /** Check if an entity has at least one snapshot. */
+    hasEntity(entityId: number): boolean;
+    /** Remove an entity from the bridge (e.g., after death and removal from sim). */
+    removeEntity(entityId: number): void;
+    /** Clear all stored snapshots (reset). */
+    clear(): void;
+}

package/dist/src/bridge/bridge-engine.js

@@ -0,0 +1,252 @@
+// src/bridge/bridge‑engine.ts — Main bridge engine (double‑buffered, interpolating)
+import { SCALE } from "../units.js";
+import { DT_S } from "../sim/tick.js";
+import { lerpVec3, slerpFacing, interpolatePoseModifiers, interpolateAnimationHints, interpolateCondition } from "./interpolation.js";
+import { findBodyPlanMapping, mapPoseModifiers } from "./mapping.js";
+// ─── BridgeEngine ─────────────────────────────────────────────────────────────
+export class BridgeEngine {
+    config;
+    entities = new Map();
+    /** Simulation time of the previous snapshot (seconds) */
+    prevTime_s = 0;
+    /** Simulation time of the current snapshot (seconds) */
+    currTime_s = 0;
+    /** Corresponding tick numbers */
+    prevTick = 0;
+    currTick = 0;
+    /** Default bone name for unmapped segments */
+    defaultBoneName;
+    constructor(config) {
+        this.config = config;
+        this.defaultBoneName = config.defaultBoneName ?? "root";
+    }
+    // ─── Configuration ───────────────────────────────────────────────────────────
+    /** Update the bridge configuration (does not affect already stored snapshots). */
+    updateConfig(config) {
+        this.config = config;
+        this.defaultBoneName = config.defaultBoneName ?? "root";
+    }
+    /** Register or update the body plan ID for an entity. */
+    setEntityBodyPlan(entityId, bodyPlanId) {
+        let rec = this.entities.get(entityId);
+        if (!rec) {
+            rec = { bodyPlanId, prev: null, curr: null };
+            this.entities.set(entityId, rec);
+        }
+        else {
+            rec.bodyPlanId = bodyPlanId;
+        }
+    }
+    // ─── Tick data ingestion ────────────────────────────────────────────────────
+    /**
+     * Ingests new simulation tick data.
+     * Called at simulation rate (typically 20 Hz).
+     * @param snapshots Rig snapshots from extractRigSnapshots()
+     * @param motion Motion vectors from extractMotionVectors() (optional)
+     * @param condition Condition samples from extractConditionSamples() (optional)
+     */
+    update(snapshots, motion, condition) {
+        // Shift current → previous
+        for (const rec of this.entities.values()) {
+            rec.prev = rec.curr;
+            rec.curr = null;
+        }
+        // Update simulation time: assume each tick advances by DT_S
+        if (this.currTick > 0) {
+            this.prevTime_s = this.currTime_s;
+            this.prevTick = this.currTick;
+        }
+        // Use the first snapshot's tick as reference (all snapshots share same tick)
+        const tick = snapshots[0]?.tick ?? this.currTick + 1;
+        this.currTick = tick;
+        this.currTime_s = tick * (DT_S / SCALE.s); // convert fixed‑point seconds to real seconds
+        // Merge data into TickSnapshot per entity
+        const motionMap = new Map();
+        const conditionMap = new Map();
+        if (motion)
+            for (const m of motion)
+                motionMap.set(m.entityId, m);
+        if (condition)
+            for (const c of condition)
+                conditionMap.set(c.entityId, c);
+        for (const rig of snapshots) {
+            const mv = motionMap.get(rig.entityId);
+            const cond = conditionMap.get(rig.entityId);
+            const snapshot = {
+                entityId: rig.entityId,
+                teamId: rig.teamId,
+                tick: rig.tick,
+                position_m: mv?.position_m ?? { x: 0, y: 0, z: 0 },
+                velocity_mps: mv?.velocity_mps ?? { x: 0, y: 0, z: 0 },
+                facing: mv?.facing ?? { x: SCALE.Q, y: 0, z: 0 }, // default forward
+                animation: rig.animation,
+                poseModifiers: rig.pose,
+                grapple: rig.grapple,
+                condition: {
+                    shockQ: cond?.shock ?? rig.animation.shockQ,
+                    fearQ: cond?.fearQ ?? rig.animation.fearQ,
+                    consciousness: cond?.consciousness ?? SCALE.Q,
+                    fluidLoss: cond?.fluidLoss ?? 0,
+                    dead: cond?.dead ?? rig.animation.dead,
+                },
+            };
+            let rec = this.entities.get(rig.entityId);
+            if (!rec) {
+                // Body plan unknown; default to humanoid (host should call setEntityBodyPlan)
+                rec = { bodyPlanId: "humanoid", prev: null, curr: snapshot };
+                this.entities.set(rig.entityId, rec);
+            }
+            else {
+                rec.curr = snapshot;
+            }
+        }
+        // Cleanup entities that disappeared (optional)
+    }
+    // ─── Interpolated state retrieval ───────────────────────────────────────────
+    /**
+     * Compute interpolated state for an entity at a given render time.
+     * @param entityId Entity ID
+     * @param renderTime_s Render time in real seconds (monotonically increasing)
+     * @returns Interpolated state, or null if entity not found or insufficient data
+     */
+    getInterpolatedState(entityId, renderTime_s) {
+        const rec = this.entities.get(entityId);
+        if (!rec) {
+            return null;
+        }
+        // Determine which snapshots are available
+        const prev = rec.prev;
+        const curr = rec.curr;
+        if (!prev && !curr) {
+            return null;
+        }
+        // If only one snapshot is available, treat it as both prev and curr (hold)
+        const usePrev = prev ?? curr;
+        const useCurr = curr ?? prev;
+        const singleSnapshot = !prev || !curr;
+        // Find mapping; if none, fall back to default bone name (still produce state)
+        const mapping = findBodyPlanMapping(this.config, rec.bodyPlanId);
+        // Determine interpolation factor t ∈ [0, SCALE.Q]
+        let t;
+        let fromTick;
+        let toTick;
+        let mode;
+        if (singleSnapshot) {
+            // Only one snapshot: hold it regardless of render time
+            t = SCALE.Q;
+            fromTick = useCurr.tick;
+            toTick = useCurr.tick;
+            mode = "hold";
+        }
+        else {
+            // Both snapshots available
+            if (renderTime_s <= this.prevTime_s) {
+                // Render time before previous snapshot: hold previous
+                t = 0;
+                fromTick = prev.tick;
+                toTick = prev.tick;
+                mode = "hold";
+            }
+            else if (renderTime_s >= this.currTime_s) {
+                // Render time at or after current snapshot
+                if (this.config.extrapolationAllowed) {
+                    // Extrapolate forward using velocity
+                    const delta = renderTime_s - this.currTime_s;
+                    t = SCALE.Q;
+                    fromTick = curr.tick;
+                    toTick = curr.tick;
+                    mode = "extrapolate";
+                }
+                else {
+                    // Hold current snapshot
+                    t = SCALE.Q;
+                    fromTick = curr.tick;
+                    toTick = curr.tick;
+                    mode = "hold";
+                }
+            }
+            else {
+                // Normal interpolation between prev and curr
+                const interval = this.currTime_s - this.prevTime_s;
+                if (interval <= 0) {
+                    t = SCALE.Q;
+                }
+                else {
+                    const frac = (renderTime_s - this.prevTime_s) / interval;
+                    t = Math.max(0, Math.min(SCALE.Q, Math.round(frac * SCALE.Q)));
+                }
+                fromTick = prev.tick;
+                toTick = curr.tick;
+                mode = "lerp";
+            }
+        }
+        // Interpolate each component (if single snapshot, lerp with t = SCALE.Q yields curr)
+        const position_m = lerpVec3(usePrev.position_m, useCurr.position_m, t);
+        const velocity_mps = lerpVec3(usePrev.velocity_mps, useCurr.velocity_mps, t);
+        const facing = slerpFacing(usePrev.facing, useCurr.facing, t);
+        const animation = interpolateAnimationHints(usePrev.animation, useCurr.animation, t);
+        const pose = interpolatePoseModifiers(usePrev.poseModifiers, useCurr.poseModifiers, t);
+        const condition = interpolateCondition(usePrev.condition, useCurr.condition, t);
+        // Apply extrapolation if needed
+        if (mode === "extrapolate" && this.config.extrapolationAllowed) {
+            const delta = renderTime_s - this.currTime_s;
+            const deltaFixed = Math.round(delta * SCALE.s);
+            const dx = Math.trunc((curr.velocity_mps.x * deltaFixed) / SCALE.s);
+            const dy = Math.trunc((curr.velocity_mps.y * deltaFixed) / SCALE.s);
+            const dz = Math.trunc((curr.velocity_mps.z * deltaFixed) / SCALE.s);
+            position_m.x += dx;
+            position_m.y += dy;
+            position_m.z += dz;
+        }
+        // Map pose modifiers to bone names
+        const mappedPose = mapping
+            ? mapPoseModifiers(pose, mapping, this.defaultBoneName)
+            : pose.map(p => ({
+                segmentId: p.segmentId,
+                boneName: this.defaultBoneName,
+                impairmentQ: p.impairmentQ,
+                structuralQ: p.structuralQ,
+                surfaceQ: p.surfaceQ,
+            }));
+        return {
+            entityId,
+            teamId: usePrev.teamId,
+            position_m,
+            velocity_mps,
+            facing,
+            animation,
+            poseModifiers: mappedPose,
+            grapple: t < SCALE.Q / 2 ? usePrev.grapple : useCurr.grapple,
+            condition,
+            interpolationFactor: t,
+            fromTick,
+            toTick,
+        };
+    }
+    // ─── Utilities ───────────────────────────────────────────────────────────────
+    /** Get the simulation time (seconds) of the latest tick. */
+    getLatestSimTime() {
+        return this.currTime_s;
+    }
+    /** Get the simulation tick of the latest snapshot. */
+    getLatestTick() {
+        return this.currTick;
+    }
+    /** Check if an entity has at least one snapshot. */
+    hasEntity(entityId) {
+        const rec = this.entities.get(entityId);
+        return !!(rec && (rec.prev || rec.curr));
+    }
+    /** Remove an entity from the bridge (e.g., after death and removal from sim). */
+    removeEntity(entityId) {
+        this.entities.delete(entityId);
+    }
+    /** Clear all stored snapshots (reset). */
+    clear() {
+        this.entities.clear();
+        this.prevTime_s = 0;
+        this.currTime_s = 0;
+        this.prevTick = 0;
+        this.currTick = 0;
+    }
+}

package/dist/src/bridge/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./interpolation.js";
+export * from "./mapping.js";
+export * from "./bridge-engine.js";

package/dist/src/bridge/index.js

@@ -0,0 +1,5 @@
+// src/bridge/index.ts — Public API exports
+export * from "./types.js";
+export * from "./interpolation.js";
+export * from "./mapping.js";
+export * from "./bridge-engine.js";

package/dist/src/bridge/interpolation.d.ts

@@ -0,0 +1,64 @@
+import type { Q } from "../units.js";
+import type { Vec3 } from "../sim/vec3.js";
+import type { PoseModifier } from "../model3d.js";
+/**
+ * Linear interpolation between two fixed‑point scalars.
+ * @param prev Value at t = 0
+ * @param curr Value at t = SCALE.Q
+ * @param t Interpolation factor Q ∈ [0, SCALE.Q]
+ * @returns Interpolated value (deterministic, using mulDiv)
+ */
+export declare function lerpQ(prev: Q, curr: Q, t: Q): Q;
+/**
+ * Clamped linear interpolation; result stays within [prev, curr] (or [curr, prev]).
+ */
+export declare function lerpQClamped(prev: Q, curr: Q, t: Q): Q;
+/**
+ * Linear interpolation between two fixed‑point vectors.
+ * @param prev Vec3 at t = 0
+ * @param curr Vec3 at t = SCALE.Q
+ * @param t Interpolation factor Q ∈ [0, SCALE.Q]
+ * @returns Interpolated Vec3 (component‑wise lerp)
+ */
+export declare function lerpVec3(prev: Vec3, curr: Vec3, t: Q): Vec3;
+/**
+ * Cheap spherical interpolation for facing directions (unit vectors in Q‑space).
+ * Uses normaliseDirCheapQ on the linearly interpolated vector.
+ * Not truly slerp but good enough for facing interpolation over small angles.
+ */
+export declare function slerpFacing(prev: Vec3, curr: Vec3, t: Q): Vec3;
+/**
+ * Interpolates two pose modifier arrays by matching segmentId.
+ * If a segment appears only in one snapshot, its weights are held constant
+ * (no cross‑fade). Returns a new array with all segmentIds from both inputs.
+ */
+export declare function interpolatePoseModifiers(prev: PoseModifier[], curr: PoseModifier[], t: Q): PoseModifier[];
+/**
+ * Interpolates between two AnimationHints.
+ * Boolean flags (prone, unconscious, dead) snap at t >= SCALE.Q/2.
+ * Scalar weights are lerpQ.
+ */
+export declare function interpolateAnimationHints(prev: import("../model3d.js").AnimationHints, curr: import("../model3d.js").AnimationHints, t: Q): import("../model3d.js").AnimationHints;
+/**
+ * Interpolates condition fields (shock, fear, consciousness, fluidLoss).
+ * Dead flag snaps at t >= SCALE.Q/2.
+ */
+export declare function interpolateCondition(prev: {
+    shockQ: Q;
+    fearQ: Q;
+    consciousness: Q;
+    fluidLoss: Q;
+    dead: boolean;
+}, curr: {
+    shockQ: Q;
+    fearQ: Q;
+    consciousness: Q;
+    fluidLoss: Q;
+    dead: boolean;
+}, t: Q): {
+    shockQ: number;
+    fearQ: number;
+    consciousness: number;
+    fluidLoss: number;
+    dead: boolean;
+};

package/dist/src/bridge/interpolation.js

@@ -0,0 +1,130 @@
+// src/bridge/interpolation.ts — Deterministic fixed‑point interpolation utilities
+import { SCALE, mulDiv, clampQ } from "../units.js";
+import { normaliseDirCheapQ } from "../sim/vec3.js";
+// ─── Scalar interpolation ──────────────────────────────────────────────────────
+/**
+ * Linear interpolation between two fixed‑point scalars.
+ * @param prev Value at t = 0
+ * @param curr Value at t = SCALE.Q
+ * @param t Interpolation factor Q ∈ [0, SCALE.Q]
+ * @returns Interpolated value (deterministic, using mulDiv)
+ */
+export function lerpQ(prev, curr, t) {
+    // t ∈ [0, SCALE.Q]; compute (prev * (SCALE.Q - t) + curr * t) / SCALE.Q
+    const tInv = SCALE.Q - t;
+    const a = mulDiv(prev, tInv, SCALE.Q);
+    const b = mulDiv(curr, t, SCALE.Q);
+    return a + b;
+}
+/**
+ * Clamped linear interpolation; result stays within [prev, curr] (or [curr, prev]).
+ */
+export function lerpQClamped(prev, curr, t) {
+    const r = lerpQ(prev, curr, t);
+    return prev <= curr
+        ? clampQ(r, prev, curr)
+        : clampQ(r, curr, prev);
+}
+// ─── Vector interpolation ──────────────────────────────────────────────────────
+/**
+ * Linear interpolation between two fixed‑point vectors.
+ * @param prev Vec3 at t = 0
+ * @param curr Vec3 at t = SCALE.Q
+ * @param t Interpolation factor Q ∈ [0, SCALE.Q]
+ * @returns Interpolated Vec3 (component‑wise lerp)
+ */
+export function lerpVec3(prev, curr, t) {
+    const dx = curr.x - prev.x;
+    const dy = curr.y - prev.y;
+    const dz = curr.z - prev.z;
+    return {
+        x: prev.x + mulDiv(dx, t, SCALE.Q),
+        y: prev.y + mulDiv(dy, t, SCALE.Q),
+        z: prev.z + mulDiv(dz, t, SCALE.Q),
+    };
+}
+/**
+ * Cheap spherical interpolation for facing directions (unit vectors in Q‑space).
+ * Uses normaliseDirCheapQ on the linearly interpolated vector.
+ * Not truly slerp but good enough for facing interpolation over small angles.
+ */
+export function slerpFacing(prev, curr, t) {
+    const interp = lerpVec3(prev, curr, t);
+    return normaliseDirCheapQ(interp);
+}
+// ─── Pose modifier interpolation ───────────────────────────────────────────────
+/**
+ * Interpolates two pose modifier arrays by matching segmentId.
+ * If a segment appears only in one snapshot, its weights are held constant
+ * (no cross‑fade). Returns a new array with all segmentIds from both inputs.
+ */
+export function interpolatePoseModifiers(prev, curr, t) {
+    const prevMap = new Map();
+    const currMap = new Map();
+    for (const p of prev)
+        prevMap.set(p.segmentId, p);
+    for (const c of curr)
+        currMap.set(c.segmentId, c);
+    const result = [];
+    const allIds = new Set([...prevMap.keys(), ...currMap.keys()]);
+    for (const id of allIds) {
+        const p = prevMap.get(id);
+        const c = currMap.get(id);
+        if (p && c) {
+            // Both present: interpolate each component
+            result.push({
+                segmentId: id,
+                structuralQ: lerpQ(p.structuralQ, c.structuralQ, t),
+                surfaceQ: lerpQ(p.surfaceQ, c.surfaceQ, t),
+                impairmentQ: lerpQ(p.impairmentQ, c.impairmentQ, t),
+            });
+        }
+        else if (p) {
+            // Only in previous snapshot: hold constant
+            result.push(p);
+        }
+        else {
+            // Only in current snapshot: hold constant (should not happen if t ∈ [0, SCALE.Q])
+            result.push(c);
+        }
+    }
+    return result;
+}
+// ─── Animation hints interpolation ─────────────────────────────────────────────
+/**
+ * Interpolates between two AnimationHints.
+ * Boolean flags (prone, unconscious, dead) snap at t >= SCALE.Q/2.
+ * Scalar weights are lerpQ.
+ */
+export function interpolateAnimationHints(prev, curr, t) {
+    const tMid = SCALE.Q / 2;
+    return {
+        idle: lerpQ(prev.idle, curr.idle, t),
+        walk: lerpQ(prev.walk, curr.walk, t),
+        run: lerpQ(prev.run, curr.run, t),
+        sprint: lerpQ(prev.sprint, curr.sprint, t),
+        crawl: lerpQ(prev.crawl, curr.crawl, t),
+        guardingQ: lerpQ(prev.guardingQ, curr.guardingQ, t),
+        attackingQ: lerpQ(prev.attackingQ, curr.attackingQ, t),
+        shockQ: lerpQ(prev.shockQ, curr.shockQ, t),
+        fearQ: lerpQ(prev.fearQ, curr.fearQ, t),
+        prone: t < tMid ? prev.prone : curr.prone,
+        unconscious: t < tMid ? prev.unconscious : curr.unconscious,
+        dead: t < tMid ? prev.dead : curr.dead,
+    };
+}
+// ─── Condition interpolation ───────────────────────────────────────────────────
+/**
+ * Interpolates condition fields (shock, fear, consciousness, fluidLoss).
+ * Dead flag snaps at t >= SCALE.Q/2.
+ */
+export function interpolateCondition(prev, curr, t) {
+    const tMid = SCALE.Q / 2;
+    return {
+        shockQ: lerpQ(prev.shockQ, curr.shockQ, t),
+        fearQ: lerpQ(prev.fearQ, curr.fearQ, t),
+        consciousness: lerpQ(prev.consciousness, curr.consciousness, t),
+        fluidLoss: lerpQ(prev.fluidLoss, curr.fluidLoss, t),
+        dead: t < tMid ? prev.dead : curr.dead,
+    };
+}

package/dist/src/bridge/mapping.d.ts

@@ -0,0 +1,33 @@
+import type { BodyPlanMapping, BridgeConfig } from "./types.js";
+import type { PoseModifier } from "../model3d.js";
+/**
+ * Find the bone name for a segment ID according to the given mapping.
+ * Falls back to defaultBoneName if not found.
+ */
+export declare function resolveBoneName(segmentId: string, mapping: BodyPlanMapping, defaultBoneName?: string): string;
+/**
+ * Resolve the full mapping for a body plan ID.
+ * Returns the first mapping whose bodyPlanId matches, or undefined.
+ */
+export declare function findBodyPlanMapping(config: BridgeConfig, bodyPlanId: string): BodyPlanMapping | undefined;
+/**
+ * Apply mapping to a pose modifier array, converting segmentId → boneName.
+ * If a segment is not mapped, it is omitted (or can be kept with default bone name).
+ */
+export declare function mapPoseModifiers(poseModifiers: PoseModifier[], mapping: BodyPlanMapping, defaultBoneName?: string): Array<{
+    segmentId: string;
+    boneName: string;
+    impairmentQ: number;
+    structuralQ: number;
+    surfaceQ: number;
+}>;
+/**
+ * Create a default mapping that maps each segment ID to itself as bone name.
+ * Useful for testing or as a fallback when no explicit mapping is provided.
+ */
+export declare function createIdentityMapping(bodyPlanId: string, segmentIds: string[]): BodyPlanMapping;
+/**
+ * Validate that a mapping covers all segment IDs of a body plan.
+ * Returns missing segment IDs.
+ */
+export declare function validateMappingCoverage(mapping: BodyPlanMapping, segmentIds: string[]): string[];

package/dist/src/bridge/mapping.js

@@ -0,0 +1,54 @@
+// src/bridge/mapping.ts — Segment‑to‑bone mapping resolution
+// ─── Mapping resolution ────────────────────────────────────────────────────────
+/**
+ * Find the bone name for a segment ID according to the given mapping.
+ * Falls back to defaultBoneName if not found.
+ */
+export function resolveBoneName(segmentId, mapping, defaultBoneName = "root") {
+    const seg = mapping.segments.find(s => s.segmentId === segmentId);
+    return seg?.boneName ?? defaultBoneName;
+}
+/**
+ * Resolve the full mapping for a body plan ID.
+ * Returns the first mapping whose bodyPlanId matches, or undefined.
+ */
+export function findBodyPlanMapping(config, bodyPlanId) {
+    return config.mappings.find(m => m.bodyPlanId === bodyPlanId);
+}
+/**
+ * Apply mapping to a pose modifier array, converting segmentId → boneName.
+ * If a segment is not mapped, it is omitted (or can be kept with default bone name).
+ */
+export function mapPoseModifiers(poseModifiers, mapping, defaultBoneName = "root") {
+    const result = [];
+    for (const pm of poseModifiers) {
+        const boneName = resolveBoneName(pm.segmentId, mapping, defaultBoneName);
+        result.push({
+            segmentId: pm.segmentId,
+            boneName,
+            impairmentQ: pm.impairmentQ,
+            structuralQ: pm.structuralQ,
+            surfaceQ: pm.surfaceQ,
+        });
+    }
+    return result;
+}
+/**
+ * Create a default mapping that maps each segment ID to itself as bone name.
+ * Useful for testing or as a fallback when no explicit mapping is provided.
+ */
+export function createIdentityMapping(bodyPlanId, segmentIds) {
+    return {
+        bodyPlanId,
+        segments: segmentIds.map(id => ({ segmentId: id, boneName: id })),
+    };
+}
+// ─── Validation ────────────────────────────────────────────────────────────────
+/**
+ * Validate that a mapping covers all segment IDs of a body plan.
+ * Returns missing segment IDs.
+ */
+export function validateMappingCoverage(mapping, segmentIds) {
+    const mapped = new Set(mapping.segments.map(s => s.segmentId));
+    return segmentIds.filter(id => !mapped.has(id));
+}