kind: ContactKind;

effector: string;

target: string;

effectorBone: string;

/** Contact activation weight (terminal declarations are 1; blended-out reaches approach 0). */

weight: number;

status: ContactStatus;

/** Final world-space effector/target positions, when they can be resolved. */

effectorPosition: Vec3 | null;

targetPosition: Vec3 | null;

/** Euclidean positional error in metres; null means the evaluator cannot solve it. */

error: number | null;

/** Explicit reason for an unsupported path. Never silently treated as a pass. */

reason?: string;

/** Phase name from the document. */

name: string;

durationSec: number;

easing: TimingMode;

/** Effector groups ground-locked during this phase. */

groundLock: readonly string[];

pins: readonly PinTarget[];

reaches: readonly ReachTarget[];

grips: readonly GripTarget[];

/** Positional truth for every declared reach/pin/grip in this phase. */

contactResiduals: readonly ContactResidual[];

rootOffset: Vec3;

rootYaw: number;

/**

propPush: Vec3;

/** Whether the phase should rest on the floor (no elevated prop/grip support). */

floorBound: boolean;

/**

meshMinY: number;

/** World-space position of every bone at the END of this phase. */

bones: ReadonlyMap<string, Vec3>;

/** World-space orientation of every bone at the end of the phase. */

boneQuaternions: ReadonlyMap<string, Quat>;

ok: boolean;

errors: readonly ParseError[];

warnings: readonly Warning[];

phases: readonly PhasePose[];

propTypes: readonly string[];

/** Flattened contact residuals for scorecards/consumers that do not walk phases. */

contactResiduals: readonly ContactResidual[];

/** Constraint residuals aggregated over regularly sampled solved clip frames. */

diagnostics: ClipDiagnostics;

kind: ContactKind;

effector: string;

target: string;

effectorBone: string;

weight: number;

targetRef: TargetReference | null;

reason?: string;

reaches: readonly ReachTarget[],

pins: readonly PinTarget[],

groundLock: readonly string[],

): Set<"left" | "right"> {

const sides = new Set<"left" | "right">();

const add = (effector: string): void => {

if (effector === "fists" || effector === "fist_left") sides.add("left");

if (effector === "fists" || effector === "fist_right") sides.add("right");

};

for (const reach of reaches) add(reach.effector);

for (const pin of pins) add(pin.effector);

for (const effector of groundLock) add(effector);

return sides;

const sides = new Set<"left" | "right">();

for (const grip of grips) {

if (grip.effector.endsWith("_left") || grip.effector === "hands") sides.add("left");

if (grip.effector.endsWith("_right") || grip.effector === "hands") sides.add("right");

}

return sides;

reaches: readonly { effector: string }[],

pins: readonly { effector: string }[],

grips: readonly { effector: string }[],

groundLock: readonly string[],

): Set<"left" | "right"> {

const sides = gripSidesOf(grips);

const add = (effector: string): void => {

if (/^(?:hand|fist|elbow)_left$/.test(effector)

|| effector === "hands" || effector === "fists" || effector === "forearms") sides.add("left");

if (/^(?:hand|fist|elbow)_right$/.test(effector)

|| effector === "hands" || effector === "fists" || effector === "forearms") sides.add("right");

};

reaches.forEach((contact) => add(contact.effector));

pins.forEach((contact) => add(contact.effector));

groundLock.forEach(add);

return sides;

reaches: readonly { effector: string; target: string }[],

pins: readonly { effector: string; anchor: string }[],

groundLock: readonly string[],

): Set<"left" | "right"> {

const sides = new Set<"left" | "right">();

const add = (effector: string): void => {

if (effector === "hands" || effector === "hand_left") sides.add("left");

if (effector === "hands" || effector === "hand_right") sides.add("right");

};

reaches.filter((reach) => reach.target === "floor").forEach((reach) => add(reach.effector));

pins.filter((pin) => pin.anchor === "floor").forEach((pin) => add(pin.effector));

groundLock.forEach(add);

return sides;

a: ReadonlySet<"left" | "right">,

b: ReadonlySet<"left" | "right">,

): Set<"left" | "right"> {

return new Set([...a, ...b]);

source: string,

proportions?: Proportions,

character?: Character,

options: ProbeOptions = {},

): ProbeResult {

const { ir, errors, warnings } = parse(source);

const requestedDiagnosticSampleRate = options.diagnosticSampleRateHz;

const diagnosticSampleRateHz = Math.max(

1,

Math.min(

120,

requestedDiagnosticSampleRate !== undefined && Number.isFinite(requestedDiagnosticSampleRate)

? requestedDiagnosticSampleRate

: DEFAULT_DIAGNOSTIC_SAMPLE_RATE_HZ,

),

);

if (!ir || errors.length > 0) {

return {

ok: false,

errors,

warnings,

phases: [],

propTypes: [],

contactResiduals: [],

diagnostics: createClipDiagnosticsCollector(diagnosticSampleRateHz).finish(),

};

}

const m = buildMannequin(undefined, proportions);

const tl = buildTimeline(ir);

// Gait clip: authors root travel AND alternates its floor foot-pins between

// both feet. There a floor foot-pin is a stance foot (body travels, leg

// reaches back to the plant) rather than a vertical support / weight-shift

// that translates the whole body onto its anchor. Mirrors Viewer.load().

const clipHasTravel = ir.phases.some(

(phase) =>

phase.travel !== undefined &&

(Math.abs(phase.travel.x) > EPS || Math.abs(phase.travel.z) > EPS),

);

const pinnedFootSides = new Set<string>();

for (const phase of ir.phases) {

for (const pin of phase.pins) {

if (pin.anchor !== "floor") continue;

const bone = effectorBoneId(pin.effector);

if (bone.startsWith("ankle_")) {

pinnedFootSides.add(bone.endsWith("_left") ? "left" : "right");

}

}

}

const clipIsGait = clipHasTravel && pinnedFootSides.size >= 2;

const propScene = buildProps(ir.props);

const authoredFingers = new Set(tl.bonesUsed.filter((id) =>

/^(thumb|index|middle|ring|pinky)_(left|right)$/.test(id),

));

const authoredShoulders = new Set(tl.bonesUsed.filter((id) => id.startsWith("shoulder_")));

const authoredHead = tl.bonesUsed.some((id) => id === "head" || id === "neck");

// Mirror Viewer.load(): reset bones, apply the base-pose root, pose at t=0,

// then drop the figure onto the floor and remember the grounded base root.

for (const bone of m.bones.values()) bone.quaternion.identity();

const base = tl.basePose.root;

m.root.position.set(...(base?.position ?? [0, 0, 0]));

const [rx, ry, rz] = base?.rotationDeg ?? [0, 0, 0];

m.root.rotation.set(rx * DEG, ry * DEG, rz * DEG);

tl.sample(0, m.bones);

m.root.updateMatrixWorld(true);

const initialPhase = ir.phases[0];

const initialFistSides = fistSidesOf(

initialPhase?.reaches ?? [],

initialPhase?.pins ?? [],

initialPhase?.groundLock ?? [],

);

const initialGripSides = gripSidesOf(initialPhase?.grips ?? []);

const initialConstrainedHandSides = contactHandSidesOf(

initialPhase?.reaches ?? [],

initialPhase?.pins ?? [],

initialPhase?.grips ?? [],

initialPhase?.groundLock ?? [],

);

formFists(m, initialFistSides, authoredFingers);

relaxHands(

m,

unionHandSides(initialGripSides, initialFistSides),

authoredFingers,

floorHandSidesOf(

initialPhase?.reaches ?? [],

initialPhase?.pins ?? [],

initialPhase?.groundLock ?? [],

),

);

alignFloorContacts(

m,

ir.phases[0]?.reaches ?? [],

ir.phases[0]?.pins ?? [],

ir.phases[0]?.groundLock ?? [],

);

depenetrate(m);

groundFigure(m);

resolvePropContacts(m, propScene.colliders, propContactExemptions([

...(ir.phases[0]?.pins ?? []),

...(ir.phases[0]?.grips ?? []),

...(ir.phases[0]?.reaches ?? []).map((r) => ({ effector: r.effector, anchor: r.target })),

]));

levelPlantedFeet(m, initialPhase?.groundLock ?? []);

swingArms(m, authoredShoulders, initialConstrainedHandSides);

enforceContactRom(m);

const baseRootPos = m.root.position.clone();

const baseRootQuat = m.root.quaternion.clone();

// Mirror Viewer.captureGroundTargets(): the grounded base-pose effector

// positions are the anchors horizontal foot planting holds feet to.

const groundTargets = new Map<string, THREE.Vector3>();

for (const ids of Object.values(m.effectors)) {

for (const id of ids) {

const node = m.bones.get(id);

if (node) groundTargets.set(id, node.getWorldPosition(new THREE.Vector3()));

}

}

// Precompute world positions of all effectors at start of each segment

const segmentStartEffectors: Map<string, THREE.Vector3>[] = [];

const tempYawQ = new THREE.Quaternion();

const getEffectorId = (eff: string) => effectorBoneId(eff);

let prevEffectorsMap: Map<string, THREE.Vector3> | null = null;

let prevPins: typeof ir.phases[number]["pins"] = [];

for (let i = 0; i < tl.segments.length; i++) {

const seg = tl.segments[i]!;

for (const bone of m.bones.values()) bone.quaternion.identity();

const info = tl.sample(seg.start, m.bones);

const wasPinned = (id: string) => prevPins.some(p => getEffectorId(p.effector) === id && p.anchor === "floor");

const isPinned = (id: string) => info.pins.some(p => getEffectorId(p.effector) === id && p.anchor === "floor");

m.root.position.copy(baseRootPos);

m.root.quaternion.copy(baseRootQuat);

if (info.rootYaw !== 0) {

tempYawQ.setFromAxisAngle(WORLD_Y, info.rootYaw);

m.root.quaternion.premultiply(tempYawQ);

}

m.root.position.x += info.rootOffset.x;

m.root.position.z += info.rootOffset.z;

m.root.updateMatrixWorld(true);

depenetrate(m);

const effectorsMap = new Map<string, THREE.Vector3>();

for (const ids of Object.values(m.effectors)) {

for (const id of ids) {

const node = m.bones.get(id);

if (node) {

if (i > 0 && wasPinned(id) && isPinned(id) && prevEffectorsMap && prevEffectorsMap.has(id)) {

effectorsMap.set(id, prevEffectorsMap.get(id)!);

} else {

effectorsMap.set(id, node.getWorldPosition(new THREE.Vector3()));

}

}

}

}

segmentStartEffectors.push(effectorsMap);

prevEffectorsMap = effectorsMap;

prevPins = info.pins;

}

// Restore initial state

for (const bone of m.bones.values()) bone.quaternion.identity();

tl.sample(0, m.bones);

m.root.position.copy(baseRootPos);

m.root.quaternion.copy(baseRootQuat);

m.root.updateMatrixWorld(true);

depenetrate(m);

groundFigure(m);

const resolveTarget = (

target: string,

effectorName: string,

): { point: THREE.Vector3; ref: TargetReference } | null => {

if (target === "floor") {

const point = floorTargetForEffector(m, effectorName);

if (!point) return null;

return { point, ref: { kind: "floor", point: point.clone() } };

}

const prop = propScene.anchors.get(target);

if (prop) {

const point = prop.clone();

return { point, ref: { kind: "fixed", point: point.clone() } };

}

const landmark = m.bones.get(target);

if (landmark) {

return {

point: landmark.getWorldPosition(new THREE.Vector3()),

ref: { kind: "landmark", boneId: target },

};

}

return null;

};

const applyLookAt = (info: {

grips: readonly GripTarget[];

reaches: readonly ReachTarget[];

}): void => {

if (authoredHead) return;

const points: THREE.Vector3[] = [];

const collect = (effector: string, target: string): void => {

const resolved = resolveTarget(target, effector)

?? resolveTarget(target.replace(/_(left|right)$/, ""), effector);

if (resolved) points.push(resolved.point);

};

info.grips.forEach((grip) => collect(grip.effector, grip.anchor));

info.reaches.forEach((reach) => collect(reach.effector, reach.target));

if (points.length === 0) return;

const focus = new THREE.Vector3();

points.forEach((point) => focus.add(point));

aimHead(m, focus.multiplyScalar(1 / points.length));

};

const unsupported = (

kind: ContactKind,

effector: string,

target: string,

effectorBone: string,

reason: string,

weight = 1,

): PendingContact => ({ kind, effector, target, effectorBone, weight, targetRef: null, reason });

const applyPins = (pins: readonly PinTarget[], phaseIndex: number): PendingContact[] => {

const dipBarPins = pins.filter((pin) => isDipBarGrip(pin.anchor));

prepareGripFrames(m, dipBarPins);

const contacts: PendingContact[] = [];

const solvable: Array<{ contact: PendingContact; effector: THREE.Object3D; point: THREE.Vector3 }> = [];

const stancePlants: Array<{ effector: string; point: THREE.Vector3 }> = [];

for (const pin of pins) {

const effectorBone = getEffectorId(pin.effector);

const effector = m.bones.get(effectorBone);

if (!effector) {

contacts.push(unsupported("pin", pin.effector, pin.anchor, effectorBone, `unknown effector bone "${effectorBone}"`));

continue;

}

let resolved: { point: THREE.Vector3; ref: TargetReference } | null = null;

if (pin.anchor === "floor") {

const start = segmentStartEffectors[phaseIndex]?.get(effectorBone);

if (start) {

const point = start.clone();

point.y = floorTargetForEffector(m, pin.effector)?.y ?? 0;

resolved = { point, ref: { kind: "floor", point: point.clone() } };

}

}

resolved ??= resolveTarget(pin.anchor, pin.effector);

if (!resolved) {

contacts.push(unsupported("pin", pin.effector, pin.anchor, effectorBone, `unknown anchor "${pin.anchor}"`));

continue;

}

const contact: PendingContact = {

kind: "pin",

effector: pin.effector,

target: pin.anchor,

effectorBone,

weight: 1,

targetRef: resolved.ref,

};

contacts.push(contact);

// In a locomotion clip a planted foot is a stance foot: solve it by leg IK

// after the body has travelled, not by translating the body onto the

// anchor (which would cancel the authored travel). Mirrors Viewer.frame().

if (clipIsGait && pin.anchor === "floor" && effectorBone.startsWith("ankle_")) {

stancePlants.push({ effector: pin.effector, point: resolved.point });

} else {

solvable.push({ contact, effector, point: resolved.point });

}

}

if (solvable.length > 0) {

const delta = new THREE.Vector3();

for (const item of solvable) {

delta.add(item.point.clone().sub(item.effector.getWorldPosition(new THREE.Vector3())));

}

m.root.position.add(delta.multiplyScalar(1 / solvable.length));

m.root.updateMatrixWorld(true);

}

for (const plant of stancePlants) {

solveReachToPoint(m, plant.effector, "floor", plant.point, 1);

}

alignGripFrames(m, dipBarPins);

return contacts;

};

const applyGrips = (grips: readonly GripTarget[]): PendingContact[] => {

prepareGripFrames(m, grips);

const contacts: PendingContact[] = [];

const solvable: Array<{

contact: PendingContact;

effector: THREE.Object3D;

point: THREE.Vector3;

}> = [];

for (const grip of grips) {

const effectorBone = getEffectorId(grip.effector);

const effector = m.bones.get(effectorBone);

if (!effector) {

contacts.push(unsupported("grip", grip.effector, grip.anchor, effectorBone, `unknown effector bone "${effectorBone}"`));

continue;

}

const resolved = resolveTarget(grip.anchor, grip.effector)

?? resolveTarget(grip.anchor.replace(/_(left|right)$/, ""), grip.effector);

if (!resolved) {

contacts.push(unsupported("grip", grip.effector, grip.anchor, effectorBone, `unknown anchor "${grip.anchor}"`));

continue;

}

const contact: PendingContact = {

kind: "grip",

effector: grip.effector,

target: grip.anchor,

effectorBone,

weight: 1,

targetRef: resolved.ref,

};

contacts.push(contact);

solvable.push({ contact, effector, point: resolved.point });

}

if (solvable.length > 0) {

const delta = new THREE.Vector3();

for (const item of solvable) {

delta.add(item.point.clone().sub(item.effector.getWorldPosition(new THREE.Vector3())));

}

m.root.position.add(delta.multiplyScalar(1 / solvable.length));

m.root.updateMatrixWorld(true);

}

for (const item of solvable) {

const { joints, limits } = reachChain(m, item.contact.effector);

if (joints.length === 0) {

item.contact.reason = "production IK unsupported: unsupported effector";

item.contact.targetRef = null;

continue;

}

if (isDipBarGrip(item.contact.target)) {

// Viewer parity: keep the elbow's axial solution fixed so a dip-bar

// palm cannot flip between or away from the parallel rails.

for (let i = 0; i < joints.length; i++) {

if (!joints[i]!.name.startsWith("elbow_")) continue;

const limit = limits[i];

if (limit) limits[i] = { ...limit, y: [0, 0] };

}

}

solveCCD({ joints, limits, effector: item.effector, target: item.point }, 12);

}

alignGripFrames(m, grips);

wrapGrip(m, grips);

m.root.updateMatrixWorld(true);

return contacts;

};

const applyReaches = (

reaches: readonly (ReachTarget & { weight: number })[],

): PendingContact[] => {

const contacts: PendingContact[] = [];

for (const reach of reaches) {

const effectorBone = getEffectorId(reach.effector);

const effector = m.bones.get(effectorBone);

if (!effector) {

contacts.push(unsupported("reach", reach.effector, reach.target, effectorBone, `unknown effector bone "${effectorBone}"`, reach.weight));

continue;

}

const resolved = resolveTarget(reach.target, reach.effector);

if (!resolved) {

contacts.push(unsupported("reach", reach.effector, reach.target, effectorBone, `unknown target "${reach.target}"`, reach.weight));

continue;

}

const solved = solveReachToPoint(

m,

reach.effector,

reach.target,

resolved.point,

reach.weight,

);

if (solved.distance === null) {

contacts.push(unsupported(

"reach",

reach.effector,

reach.target,

effectorBone,

`production IK unsupported: ${solved.reason ?? "unknown reason"}`,

reach.weight,

));

continue;

}

contacts.push({

kind: "reach",

effector: reach.effector,

target: reach.target,

effectorBone,

weight: reach.weight,

targetRef: resolved.ref,

});

}

return contacts;

};

const finalizeContacts = (pending: readonly PendingContact[]): ContactResidual[] =>

pending.map((contact) => {

// Contact targets are defined against the calibrated production driver

// surfaces (sole/glute/knuckle offsets differ from raw skinned joint

// origins). The visible character is sampled separately below for actual

// skeleton geometry and exact skinned-mesh floor bounds.

const effectorPoint = m.bones.get(contact.effectorBone)

?.getWorldPosition(new THREE.Vector3()) ?? null;

let targetPoint: THREE.Vector3 | null = null;

if (contact.targetRef?.kind === "fixed") {

targetPoint = contact.targetRef.point.clone();

} else if (contact.targetRef?.kind === "landmark") {

targetPoint = m.bones.get(contact.targetRef.boneId)

?.getWorldPosition(new THREE.Vector3()) ?? null;

} else if (contact.targetRef?.kind === "floor" && effectorPoint) {

const height = floorContactHeight(m, contact.effector);

if (height !== null) {

targetPoint = contact.targetRef.point.clone().setY(effectorPoint.y - height);

}

}

const status: ContactStatus = contact.reason || !effectorPoint || !targetPoint

? "unsupported"

: "resolved";

return {

kind: contact.kind,

effector: contact.effector,

target: contact.target,

effectorBone: contact.effectorBone,

weight: contact.weight,

status,

effectorPosition: effectorPoint ? vectorTuple(effectorPoint) : null,

targetPosition: targetPoint ? vectorTuple(targetPoint) : null,

error: status === "resolved" ? effectorPoint!.distanceTo(targetPoint!) : null,

...(contact.reason ? { reason: contact.reason } : {}),

};

});

const measureGroundLocks = (active: readonly string[]): ContactResidual[] => {

const bones = new Set<string>();

for (const name of active) {

const expanded = m.effectors[name];

if (expanded) expanded.forEach((id) => bones.add(id));

else bones.add(effectorBoneId(name));

}

return [...bones].map((boneId) => {

const effector = m.bones.get(boneId);