Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

46.7 KB
Raw Blame
// GLB bone-name canonicalizer — rewrites joint node names in an uploaded
// humanoid GLB so they match the three.ws canonical bone set, letting the
// pre-baked Mixamo animation library play on any rig variant.
//
// Handled name variants:
//   • Mixamo:          `mixamorig:LeftArm`, `mixamorig1:LeftArm`, `mixamorigLeftArm`
//   • Blender:         `Armature_LeftArm`, `Armature/LeftArm`, `upperarm.L` (.L/.R side)
//   • Rigify:          `DEF-LeftArm`, `ORG-LeftArm`, `MCH-LeftArm`
//   • CharacterStudio: `CH_Hips`, `CH_LeftUpLeg` (CH_ prefix stripped)
//   • HumanIK / Maya:   `Character1:Hips`, `Character1:LeftArm`, `subject:LeftUpLeg` (namespace strip)
//   • Unreal mannequin: `pelvis`, `clavicle_l`, `upperarm_l`, `thigh_l`, `calf_l`, … (alias map)
//   • VRM / VRoid:     `J_Bip_C_Hips`, `J_Bip_L_UpperArm`, `J_Bip_L_Little1` (alias map)
//   • VRM 1.0:         `upperChest`, `leftUpperArm`, `leftLowerLeg`, `leftToes` (camelCase)
//   • MMD (PMX/PMD):   `センター`, `上半身`, `左腕`, `左ひじ`, `左ひざ` (Japanese, 左/右 side prefix)
//   • Apple / ARKit:   `hips_joint`, `left_arm_joint`, `left_upLeg_joint` (`_joint` suffix)
//   • Kinect:          `SpineBase`, `SpineShoulder`, `ShoulderLeft`, `KneeRight`
//   • MediaPipe Pose:  `left_hip`, `left_heel`, `left_foot_index` (landmark joints)
//   • Daz / Genesis:   `hip`, `abdomen`, `lShldr`, `lForeArm`, `lThigh`, `lShin`, `lCollar`
//   • MakeHuman:       `upperarm.L`, `shin.L`, `clavicle.L` (shared with Unreal/Blender stems)
//   • Simple rigs:     `shoulderL`, `elbowL`, `wristL`, `hipL`, `kneeL`, `ankleL`, `chest`
//   • SMPL / SMPL-X:   `left_hip`, `left_knee`, `left_ankle`, `left_elbow`, `left_wrist` (side-word joints)
//   • Roblox R15/R6:   `LowerTorso`, `UpperTorso`, `Torso`, `LeftUpperArm`, `Left Arm`
//   • Second Life:     `mPelvis`, `mTorso`, `mChest`, `mCollarLeft`, `mShoulderLeft`, `mKneeRight`
//   • Anatomical:      `lumbar`, `thoracic`, `cervical`, `cranium`, `humerus.L`,
//                      `ulna.L`, `femur.L`, `tibia.L`, `talus.L` (scan / anatomy-kit rigs)
//   • snake_case:      `left_arm`, `Left_Arm`
//   • kebab-case:      `left-arm`
//   • lowercase:       `leftarm`, `lefthand`
//
// Finger chains are mapped per convention as well, and they are load-bearing: 30
// of the 53 tracks in every clip in /public/animations/clips address a finger
// joint, so a rig whose hands don't name-map scores ~40% retarget coverage, falls
// under MIN_COVERAGE in animation-retarget.js, and gets NO action built at all.
// Covered spellings: `index_01_l` (Unreal), `leftIndexProximal` (VRM 1.0),
// `lIndex1` / `lMid1` (Daz), `f_index.01.L` + `thumb.01.L` (Rigify),
// `finger2-1.L` (MakeHuman), `Index1.L` / `IndexFinger1_R` (Blender / Advanced
// Skeleton), `J_Bip_L_Little1` (VRoid), `index_proximal.L` (anatomical).
// Measured end to end by scripts/animation-dignity-sweep.mjs.
//
// Skeletons that aren't humanoid (quadrupeds, custom prop rigs) deliberately
// fall through unchanged — there's no safe automatic mapping for those, and
// callers fall back to a known-good rig rather than render a bind-pose T-pose.
//
// Constraint-driven CONTROL RIGS also fall through on purpose. Blender rigs of
// the Auto-Rig-Pro / "cwf_ + def_ + tracker" family export a deform layer whose
// bones are LEAVES hanging off tracker nodes, not a chain: `def_arm_1.R` is not
// a child of `def_arm_0.R`, it hangs off `c_arm_1_tracker.R`. In Blender those
// trackers carry Copy-Rotation/Damped-Track constraints; glTF has no constraint
// system, so they export as inert nodes. Rotating a mapped `def_` bone would move
// its own skin while the next segment stayed put — the arm comes apart. Mapping
// that layer is strictly worse than the default-rig fallback, so we do not.
// Verified against real stored avatars; see scripts/audit-rig-coverage.mjs.
// The remedy for these uploads is re-rigging (workers/rig), not name mapping.
//
// This module is pure JS — works in Node (vitest) and in the browser. It
// rewrites the GLB JSON chunk in-place and repacks the binary container so
// the result is a valid GLB that swaps in 1:1 at the same R2 storage key.

import { Matrix4, Quaternion, Vector3 } from 'three';

const GLB_MAGIC      = 0x46546c67; // 'glTF' little-endian
const CHUNK_TYPE_JSON = 0x4e4f534a; // 'JSON'

// Quaternion is "axis-aligned enough" / scale is "uniform enough" below this.
const ORIENT_EPS = 1e-5;
// Joint world-matrix elements must match within this before/after the fold, or
// the fold is reverted (it would have altered the mesh).
const ORIENT_WORLD_EPS = 1e-4;

// Canonical humanoid bone set. Mirrors the rig used by scripts/build-animations.mjs
// (cz.glb / Avaturn reference rig) — every animation clip in /public/animations/clips
// addresses tracks by these exact names.
export const CANONICAL_BONES = Object.freeze([
	'Hips', 'Spine', 'Spine1', 'Spine2', 'Neck', 'Head',
	'LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand',
	'LeftHandIndex1', 'LeftHandIndex2', 'LeftHandIndex3',
	'LeftHandMiddle1', 'LeftHandMiddle2', 'LeftHandMiddle3',
	'LeftHandPinky1', 'LeftHandPinky2', 'LeftHandPinky3',
	'LeftHandRing1', 'LeftHandRing2', 'LeftHandRing3',
	'LeftHandThumb1', 'LeftHandThumb2', 'LeftHandThumb3',
	'RightShoulder', 'RightArm', 'RightForeArm', 'RightHand',
	'RightHandIndex1', 'RightHandIndex2', 'RightHandIndex3',
	'RightHandMiddle1', 'RightHandMiddle2', 'RightHandMiddle3',
	'RightHandPinky1', 'RightHandPinky2', 'RightHandPinky3',
	'RightHandRing1', 'RightHandRing2', 'RightHandRing3',
	'RightHandThumb1', 'RightHandThumb2', 'RightHandThumb3',
	'LeftUpLeg', 'LeftLeg', 'LeftFoot', 'LeftToeBase',
	'RightUpLeg', 'RightLeg', 'RightFoot', 'RightToeBase',
]);

// Lookup map: separator-stripped, lowercased variant → canonical name.
// Built once at module load so canonicalizeBoneName() runs in O(1).
const LOOKUP = (() => {
	const m = new Map();
	for (const canonical of CANONICAL_BONES) {
		m.set(canonical.toLowerCase(), canonical);
	}
	return m;
})();

// Unreal Engine mannequin skeleton → canonical aliases. UE names the same
// joints `pelvis`, `clavicle_l`, `upperarm_l`, `thigh_l`, `calf_l`, `ball_l`,
// … which share no spelling with the canonical/Mixamo set. Keyed by the same
// separator-stripped lowercase form `_lookupBone` produces (`clavicle_l` →
// `claviclel`). The spine chain (`spine_01/02/03`) is deliberately OMITTED:
// its stripped form `spine02` collides with Mixamo's `Spine` + `_02` de-dup
// suffix, which canonicalizeBoneName already resolves to `Spine`. The torso
// then rides on `Hips` while every limb, foot, and the neck retarget cleanly —
// well above the 8-bone floor a readable performance needs.
const UNREAL_ALIASES = new Map(Object.entries({
	pelvis: 'Hips',
	neck01: 'Neck',
	claviclel: 'LeftShoulder', upperarml: 'LeftArm', lowerarml: 'LeftForeArm', handl: 'LeftHand',
	clavicler: 'RightShoulder', upperarmr: 'RightArm', lowerarmr: 'RightForeArm', handr: 'RightHand',
	thighl: 'LeftUpLeg', calfl: 'LeftLeg', footl: 'LeftFoot', balll: 'LeftToeBase',
	thighr: 'RightUpLeg', calfr: 'RightLeg', footr: 'RightFoot', ballr: 'RightToeBase',
}));

// Unreal's finger chain: `index_01_l`, `middle_02_r`, `thumb_03_l`, `pinky_01_l`,
// `ring_02_l`. The zero-padded joint index is what keeps these out of the
// side-suffix finger table below (`Index1L` normalises to `index1l`, never
// `index01l`), so an otherwise-mapped mannequin arrived with 30 of its 52 joints
// unmapped. That is not a cosmetic loss: 30 of the clip library's 53 tracks are
// finger tracks, so a fingerless mannequin scored 40% coverage and fell under the
// MIN_COVERAGE gate in animation-retarget.js: the rig built no action at all and
// stood in its bind pose. Found by scripts/animation-dignity-sweep.mjs.
for (const [uf, cf] of [
	['thumb', 'Thumb'], ['index', 'Index'], ['middle', 'Middle'],
	['ring', 'Ring'], ['pinky', 'Pinky'],
]) {
	for (let n = 1; n <= 3; n++) {
		UNREAL_ALIASES.set(`${uf}0${n}l`, `LeftHand${cf}${n}`);
		UNREAL_ALIASES.set(`${uf}0${n}r`, `RightHand${cf}${n}`);
	}
}

// Extended humanoid alias map: VRM/VRoid, VRM 1.0, Daz/Genesis, MakeHuman, and
// simple/generic rigs. Keyed by the same separator-stripped, lowercased form
// `_lookupBone` produces (e.g. `J_Bip_L_UpperArm` → `jbiplupperarm`,
// `shoulderL` → `shoulderl`). Consulted AFTER the canonical/Mixamo and Unreal
// tables, so it only ever resolves names those don't already cover — it can
// never shadow a canonical spelling. Every entry maps onto the canonical bone
// set the clip library drives, so any rig using these conventions animates
// (idle + walk with legs moving) instead of freezing in its bind-pose T-pose.
const EXTRA_ALIASES = (() => {
	const m = new Map();
	const norm = (s) => s.replace(/[-_.\s]+/g, '').toLowerCase();
	// First spelling wins, so listing-order is the priority.
	const put = (variant, canonical) => { const k = norm(variant); if (!m.has(k)) m.set(k, canonical); };

	// VRM 0.x / VRoid skeletons (`J_Bip_<C|L|R>_<bone>`). The side lives in the
	// prefix, so each is mapped explicitly rather than via the side helper below.
	const VRM = [
		['J_Bip_C_Hips', 'Hips'], ['J_Bip_C_Spine', 'Spine'], ['J_Bip_C_Chest', 'Spine1'],
		['J_Bip_C_UpperChest', 'Spine2'], ['J_Bip_C_Neck', 'Neck'], ['J_Bip_C_Head', 'Head'],
		['J_Bip_L_Shoulder', 'LeftShoulder'], ['J_Bip_L_UpperArm', 'LeftArm'], ['J_Bip_L_LowerArm', 'LeftForeArm'], ['J_Bip_L_Hand', 'LeftHand'],
		['J_Bip_R_Shoulder', 'RightShoulder'], ['J_Bip_R_UpperArm', 'RightArm'], ['J_Bip_R_LowerArm', 'RightForeArm'], ['J_Bip_R_Hand', 'RightHand'],
		['J_Bip_L_UpperLeg', 'LeftUpLeg'], ['J_Bip_L_LowerLeg', 'LeftLeg'], ['J_Bip_L_Foot', 'LeftFoot'], ['J_Bip_L_ToeBase', 'LeftToeBase'], ['J_Bip_L_Toes', 'LeftToeBase'],
		['J_Bip_R_UpperLeg', 'RightUpLeg'], ['J_Bip_R_LowerLeg', 'RightLeg'], ['J_Bip_R_Foot', 'RightFoot'], ['J_Bip_R_ToeBase', 'RightToeBase'], ['J_Bip_R_Toes', 'RightToeBase'],
	];
	for (const [v, c] of VRM) put(v, c);
	// VRoid finger chains: Thumb/Index/Middle/Ring map 1:1; "Little" is the pinky.
	for (const [vf, cf] of [['Thumb', 'Thumb'], ['Index', 'Index'], ['Middle', 'Middle'], ['Ring', 'Ring'], ['Little', 'Pinky']]) {
		for (let n = 1; n <= 3; n++) {
			put(`J_Bip_L_${vf}${n}`, `LeftHand${cf}${n}`);
			put(`J_Bip_R_${vf}${n}`, `RightHand${cf}${n}`);
		}
	}

	// MikuMikuDance (PMX/PMD) skeletons name every bone in Japanese, with the
	// side carried by a leading 左 (left) / 右 (right) character. No spelling
	// here shares a stem with any Latin convention, so the whole rig previously
	// mapped zero joints and animated nothing. Sides are listed explicitly
	// rather than derived, because the SIDED table below swaps Latin side
	// tokens (left→right, l→r, L→R) and cannot reach a Japanese prefix.
	//
	// Deliberately NOT mapped: the IK targets (左足IK, 左つま先IK) and the
	// twist bones (左腕捩, 左手捩). Neither is a chain joint. MMD drives the leg
	// chain from the IK target, so binding a clip to it would fight the chain
	// it is supposed to solve, and the twist bones are secondary deformers that
	// tear the mesh when rotated as if they were the limb.
	for (const [v, c] of [
		['センター', 'Hips'], ['下半身', 'Hips'],
		['上半身', 'Spine'], ['上半身2', 'Spine1'],
		['首', 'Neck'], ['頭', 'Head'],
	]) put(v, c);
	for (const [jp, side] of [['左', 'Left'], ['右', 'Right']]) {
		for (const [v, c] of [
			['肩', 'Shoulder'], ['腕', 'Arm'], ['ひじ', 'ForeArm'], ['手首', 'Hand'],
			['足', 'UpLeg'], ['ひざ', 'Leg'], ['足首', 'Foot'], ['つま先', 'ToeBase'],
		]) put(`${jp}${v}`, `${side}${c}`);
		// MMD finger chains. 親指 (thumb) is numbered 0-2, every other digit 1-3.
		// 人指 is the index finger; some exporters spell it 人差指.
		for (const [jp2, cf] of [['人指', 'Index'], ['人差指', 'Index'], ['中指', 'Middle'], ['薬指', 'Ring'], ['小指', 'Pinky']]) {
			for (let n = 1; n <= 3; n++) put(`${jp}${jp2}${n}`, `${side}Hand${cf}${n}`);
		}
		for (let n = 0; n <= 2; n++) put(`${jp}親指${n}`, `${side}HandThumb${n + 1}`);
	}

	// 3ds Max Biped fingers. Biped numbers fingers instead of naming them: digit
	// 0-4 is thumb, index, middle, ring, pinky. One digit (`Finger1`) is that
	// finger's first segment; two digits are the finger, then the segment minus
	// one (`Finger11` = index segment 2, `Finger42` = pinky segment 3). Keyed
	// after the `Bip<NN>` strip, so `Bip01 L Finger01` and the sanitized
	// `Bip01_L_Finger01` both reach `lfinger01`. Toe0 is the one toe joint.
	for (const [side, long] of [['L', 'Left'], ['R', 'Right']]) {
		['Thumb', 'Index', 'Middle', 'Ring', 'Pinky'].forEach((cf, f) => {
			for (let n = 1; n <= 3; n++) put(`${side} Finger${n === 1 ? f : `${f}${n - 1}`}`, `${long}Hand${cf}${n}`);
		});
		put(`${side} Toe0`, `${long}ToeBase`);
	}

	// Source engine (Valve) skeletons are Biped-derived. Source numbers its
	// four-joint spine Spine, Spine1, Spine2, Spine4 (there is no Spine3) and its
	// neck and head Neck1 / Head1. Spine4 is the top of the chain, so it targets
	// the canonical top spine joint, Spine2. A rig that also has Bip01_Spine2
	// keeps the lower joint: renames are first-wins, parent first.
	for (const [v, c] of [['Spine4', 'Spine2'], ['Neck1', 'Neck'], ['Head1', 'Head']]) put(v, c);

	// Centre / torso bones with no side (VRM 1.0, Daz, generic single-chest rigs).
	for (const [v, c] of [
		['chest', 'Spine1'], ['lowerChest', 'Spine1'], ['chestLower', 'Spine1'],
		['upperChest', 'Spine2'], ['chestUpper', 'Spine2'],
		['abdomen', 'Spine'], ['abdomenLower', 'Spine'], ['abdomenUpper', 'Spine1'],
		['hip', 'Hips'],
		['lowerNeck', 'Neck'], ['upperNeck', 'Neck'], ['neckLower', 'Neck'], ['neckUpper', 'Neck'],
		// Reallusion CC3/CC4 splits the neck into twist joints; either drives the head chain.
		['neckTwist01', 'Neck'], ['neckTwist02', 'Neck'],
		// Roblox R15 (`LowerTorso`/`UpperTorso`) and R6 (`Torso`), plus the generic
		// single-torso spellings simple rigs use. The pelvis IS the lower torso in
		// R15, and the chest maps to Spine1 like VRM's `chest`.
		['torso', 'Spine'], ['waist', 'Spine'],
		['upperTorso', 'Spine1'], ['torsoUpper', 'Spine1'],
		['lowerTorso', 'Hips'], ['torsoLower', 'Hips'],
		['ribcage', 'Spine1'], ['ribs', 'Spine1'],
		// Second Life / OpenSim centre chain (`m`-prefixed body bones).
		['mPelvis', 'Hips'], ['mTorso', 'Spine'], ['mChest', 'Spine1'],
		['mNeck', 'Neck'], ['mHead', 'Head'],
		// Kinect v2 / Azure Kinect body tracking. SpineShoulder is the upper
		// torso joint between SpineMid and Neck, not a shoulder-side joint.
		['SpineBase', 'Hips'], ['SpineMid', 'Spine'], ['SpineShoulder', 'Spine2'],
		// Advanced Skeleton (Maya) tags centre bones with an `_M` side token:
		// `Root_M`, `Spine1_M`, `Spine2_M`, `Chest_M`, `Neck_M`, `Head_M`. Its LIMBS
		// use `_L`/`_R` and already resolve through the sided table, which is why
		// these rigs arrived with working arms and legs but no Hips — and no Hips
		// means the retargeter has no root to anchor to, so nothing animated at all.
		// AS numbers its spine from 1 at the base, one deeper than the canonical
		// chain, hence the shift (`Spine1_M` → Spine, `Spine2_M` → Spine1).
		['root_M', 'Hips'], ['hip_M', 'Hips'], ['pelvis_M', 'Hips'],
		['spine1_M', 'Spine'], ['spine2_M', 'Spine1'], ['spine3_M', 'Spine2'],
		['chest_M', 'Spine2'], ['neck_M', 'Neck'], ['head_M', 'Head'],
		// A zero-indexed spine base (`j_spine_0`, `spine_00`) is the first spine
		// joint; the `_1`/`_2` links already resolve as Spine1/Spine2.
		['spine0', 'Spine'],
		// UniGLTF/VRM-converter root joint.
		['hipMaster', 'Hips'],
		// Anatomical-Latin rigs. Scan pipelines, medical/anatomy kits, and the
		// ZBrush/Blender anatomy libraries name every joint for the bone itself
		// rather than for its role: `pelvis` (already mapped via the Unreal table),
		// `lumbar`, `thoracic`, `sternum`, `cervical`, `cranium`, with `humerus.L`,
		// `femur.L` and friends on the limbs below. The whole convention previously
		// mapped 3 of 52 joints and animated nothing at all.
		['lumbar', 'Spine'], ['thoracic', 'Spine1'], ['sternum', 'Spine2'],
		['cervical', 'Neck'], ['cranium', 'Head'], ['skull', 'Head'],
	]) put(v, c);

	// Side-paired limb bones, given as the LEFT spelling + its canonical; the
	// right twin is derived by swapping the side token (left→right, leading l→r,
	// trailing L→R). Covers VRM 1.0 camelCase, Daz/Genesis (`lShldr`, `lThigh`),
	// and simple rigs (`shoulderL`, `elbowL`, `hipL`).
	const SIDED = [
		['leftUpperArm', 'LeftArm'], ['lUpperArm', 'LeftArm'], ['shoulderL', 'LeftArm'], ['lShldr', 'LeftArm'], ['lShldrBend', 'LeftArm'],
		['leftLowerArm', 'LeftForeArm'], ['lLowerArm', 'LeftForeArm'], ['elbowL', 'LeftForeArm'], ['lForeArm', 'LeftForeArm'], ['lForearmBend', 'LeftForeArm'],
		// Rigify/Blender anatomical spelling (`forearm.L`, `upper_arm.L`) — the side
		// is a `.L`/`.R` SUFFIX, so it normalises to `forearml`, which none of the
		// side-PREFIX spellings above (`lForeArm`, `lLowerArm`) reach. Without this
		// the elbow bone drops and every Rigify-rigged character (Quaternius, many
		// Blender exports) animates with a rigid, unbending forearm.
		['forearmL', 'LeftForeArm'], ['upperArmL', 'LeftArm'],
		['wristL', 'LeftHand'], ['lHand', 'LeftHand'],
		['lCollar', 'LeftShoulder'], ['collarL', 'LeftShoulder'], ['lClavicle', 'LeftShoulder'],
		['leftUpperLeg', 'LeftUpLeg'], ['lUpperLeg', 'LeftUpLeg'], ['hipL', 'LeftUpLeg'], ['lThigh', 'LeftUpLeg'], ['lThighBend', 'LeftUpLeg'],
		['leftLowerLeg', 'LeftLeg'], ['lLowerLeg', 'LeftLeg'], ['kneeL', 'LeftLeg'], ['shinL', 'LeftLeg'], ['lShin', 'LeftLeg'], ['lCalf', 'LeftLeg'],
		['ankleL', 'LeftFoot'], ['lFoot', 'LeftFoot'],
		['leftToes', 'LeftToeBase'], ['toeL', 'LeftToeBase'], ['lToe', 'LeftToeBase'], ['lToeBase', 'LeftToeBase'],
		// Generic side-prefix auto-riggers (some Meshy/Tripo + simple rigs) emit the
		// canonical short bone name behind a bare `L_`/`R_` side token: `L_Arm`,
		// `L_Leg`, `L_UpLeg`, `L_Shoulder`. The right twin is derived by the l→r rule.
		['lArm', 'LeftArm'], ['lShoulder', 'LeftShoulder'], ['lLeg', 'LeftLeg'], ['lUpLeg', 'LeftUpLeg'],
		// SMPL / SMPL-X and other research-pipeline skeletons (text-to-avatar
		// generators, mocap tooling) spell every limb joint as a side word plus the
		// anatomical joint: `left_hip`, `left_knee`, `left_ankle`, `left_elbow`,
		// `left_wrist`, `left_collar`. The same spellings appear in hand-built
		// `leftKnee`-style rigs. Without these the whole lower body drops and a
		// SMPL-derived avatar glides around on frozen legs.
		['leftHip', 'LeftUpLeg'], ['leftThigh', 'LeftUpLeg'],
		['leftKnee', 'LeftLeg'], ['leftShin', 'LeftLeg'], ['leftCalf', 'LeftLeg'],
		['leftAnkle', 'LeftFoot'],
		['leftElbow', 'LeftForeArm'],
		['leftWrist', 'LeftHand'],
		['leftCollar', 'LeftShoulder'], ['leftClavicle', 'LeftShoulder'],
		['leftToe', 'LeftToeBase'],
		// Second Life / OpenSim limb chain: `m`-prefixed with a trailing side word
		// (`mCollarLeft`, `mShoulderLeft`, `mKneeLeft`). `mShoulder` is the upper
		// arm (the clavicle is `mCollar`), and the ankle is the articulating foot
		// joint; `mFoot` (the ball, between ankle and toe) drives the toe bone.
		['mCollarLeft', 'LeftShoulder'], ['mShoulderLeft', 'LeftArm'],
		['mElbowLeft', 'LeftForeArm'], ['mWristLeft', 'LeftHand'],
		['mHipLeft', 'LeftUpLeg'], ['mKneeLeft', 'LeftLeg'],
		['mAnkleLeft', 'LeftFoot'], ['mFootLeft', 'LeftToeBase'], ['mToeLeft', 'LeftToeBase'],
		// Kinect puts the full side word last. ShoulderLeft is the upper-arm
		// joint, while the Kinect skeleton has no separate clavicle joint.
		['ShoulderLeft', 'LeftArm'], ['ElbowLeft', 'LeftForeArm'],
		['WristLeft', 'LeftHand'], ['HipLeft', 'LeftUpLeg'],
		['KneeLeft', 'LeftLeg'], ['AnkleLeft', 'LeftFoot'], ['FootLeft', 'LeftToeBase'],
		// MediaPipe Pose uses its foot-index landmark as the toe endpoint and
		// heel as the articulating foot. Its other limb names already resolve
		// through the side-prefix aliases above.
		['leftHeel', 'LeftFoot'], ['leftFootIndex', 'LeftToeBase'],
		// Side-SUFFIX leg spellings (`UpperLeg.L`, `LowerLeg.R`, `LowerArm.L`). The
		// arm twins were added with the Rigify forearm fix, but the LEG twins were
		// not, and the side-PREFIX entries above (`leftUpperLeg`, `lUpperLeg`) never
		// reach `upperlegl`. Found by scripts/audit-rig-coverage.mjs against real
		// stored avatars: a Blender-exported rig using this convention lost BOTH leg
		// joints on each side and animated gliding on frozen legs.
		['upperLegL', 'LeftUpLeg'], ['lowerLegL', 'LeftLeg'], ['lowerArmL', 'LeftForeArm'],
		// The scapula is the clavicle in Advanced Skeleton / Daz-derived rigs.
		['scapulaL', 'LeftShoulder'],
		// Bare side-PREFIX anatomical joints (`j_L_hip`, `L_knee`, `R_ankle`). The
		// suffix twins (`hipL`, `kneeL`, `ankleL`) exist above but never reach the
		// prefix spelling. Same audit finding as the `j_` strip: Sketchfab-exported
		// rigs using this convention mapped zero bones.
		['lHip', 'LeftUpLeg'], ['lKnee', 'LeftLeg'], ['lAnkle', 'LeftFoot'],
		['lElbow', 'LeftForeArm'], ['lWrist', 'LeftHand'], ['lToes', 'LeftToeBase'],
		// Anatomical-Latin limbs, in both the side-SUFFIX (`humerus.L`) and
		// side-PREFIX (`l_humerus`) spellings these rigs ship in. The clavicle
		// (`scapula`) is already covered above. Radius and ulna are both forearm
		// joints and fibula is a lower-leg joint: whichever the rig actually skins
		// to is the one the retargeter binds (first-bone-wins), and either drives
		// the same limb segment.
		['humerusL', 'LeftArm'], ['lHumerus', 'LeftArm'],
		['ulnaL', 'LeftForeArm'], ['lUlna', 'LeftForeArm'],
		['radiusL', 'LeftForeArm'], ['lRadius', 'LeftForeArm'],
		['carpusL', 'LeftHand'], ['lCarpus', 'LeftHand'],
		['femurL', 'LeftUpLeg'], ['lFemur', 'LeftUpLeg'],
		['tibiaL', 'LeftLeg'], ['lTibia', 'LeftLeg'],
		['fibulaL', 'LeftLeg'], ['lFibula', 'LeftLeg'],
		['talusL', 'LeftFoot'], ['lTalus', 'LeftFoot'],
		['tarsusL', 'LeftFoot'], ['lTarsus', 'LeftFoot'],
		['calcaneusL', 'LeftFoot'], ['lCalcaneus', 'LeftFoot'],
		['metatarsusL', 'LeftToeBase'], ['lMetatarsus', 'LeftToeBase'],
	];

	// Finger conventions the side-suffix `Index1L` family below does not reach.
	// Fingers are 30 of the clip library's 53 tracks, so a rig whose hands don't
	// name-map scores ~40% coverage and falls under animation-retarget.js's
	// MIN_COVERAGE gate: production then builds NO action for it and the avatar
	// stands in its bind pose. Every convention here was measured doing exactly
	// that by scripts/animation-dignity-sweep.mjs before these entries landed.
	for (const [vf, cf] of [
		['Thumb', 'Thumb'], ['Index', 'Index'], ['Middle', 'Middle'],
		['Ring', 'Ring'], ['Pinky', 'Pinky'], ['Little', 'Pinky'],
	]) {
		const lf = vf.toLowerCase();
		for (let n = 1; n <= 3; n++) {
			// Daz / Genesis side-PREFIX numbering: `lIndex1`, `rPinky3`. (Genesis
			// abbreviates the middle finger to `lMid1`, handled just below.)
			SIDED.push([`l${vf}${n}`, `LeftHand${cf}${n}`]);
			// Blender Rigify: `f_index.01.L`, `f_pinky.03.R`, and the thumb's own
			// `thumb.01.L` spelling (Rigify drops the `f_` there).
			SIDED.push([`f_${lf}.0${n}.L`, `LeftHand${cf}${n}`]);
			SIDED.push([`${lf}.0${n}.L`, `LeftHand${cf}${n}`]);
			// MakeHuman numbers the digits 1..5 from the thumb: `finger1-2.L` is the
			// thumb's middle phalanx, `finger5-1.R` the right pinky's first.
			const digit = ['Thumb', 'Index', 'Middle', 'Ring', 'Pinky'].indexOf(cf) + 1;
			if (digit > 0) SIDED.push([`finger${digit}-${n}.L`, `LeftHand${cf}${n}`]);
		}
		// VRM 1.0 and anatomical rigs name the phalanges instead of numbering them:
		// proximal / intermediate / distal, with the thumb starting at its
		// metacarpal (which is the canonical set's `Thumb1`). VRM 1.0 puts the side
		// first (`leftIndexProximal`); anatomy-kit rigs put it last
		// (`index_proximal.L`). Both spellings are listed so either resolves.
		const phalanges =
			cf === 'Thumb'
				? ['Metacarpal', 'Proximal', 'Distal']
				: ['Proximal', 'Intermediate', 'Distal'];
		phalanges.forEach((phalanx, i) => {
			SIDED.push([`left${vf}${phalanx}`, `LeftHand${cf}${i + 1}`]);
			SIDED.push([`${lf}_${phalanx.toLowerCase()}.L`, `LeftHand${cf}${i + 1}`]);
		});
	}
	// Genesis abbreviates only the middle finger.
	for (let n = 1; n <= 3; n++) SIDED.push([`lMid${n}`, `LeftHandMiddle${n}`]);
	// Side-suffix finger chains, both conventions found in real uploaded avatars by
	// scripts/audit-rig-coverage.mjs:
	//   • Blender / MakeHuman:    `Index.L`, `Index2.L`, `Middle1.L`, `Thumb.L`, `Ring2.R`
	//   • Advanced Skeleton/Maya: `IndexFinger1_R`, `MiddleFinger2_L`, `ThumbFinger3_R`
	// The un-numbered spelling (`Thumb.L`, `Index.L`) is the FIRST phalanx — those
	// rigs number only the joints after it. Metacarpals (`Palm1.L`) are deliberately
	// skipped: the canonical set has no metacarpal, so there is nothing to drive.
	for (const [vf, cf] of [
		['Thumb', 'Thumb'], ['Index', 'Index'], ['Middle', 'Middle'],
		['Ring', 'Ring'], ['Pinky', 'Pinky'], ['Little', 'Pinky'],
	]) {
		for (let n = 1; n <= 3; n++) {
			SIDED.push([`${vf}${n}L`, `LeftHand${cf}${n}`]);
			SIDED.push([`${vf}Finger${n}L`, `LeftHand${cf}${n}`]);
		}
		SIDED.push([`${vf}L`, `LeftHand${cf}1`]);
		SIDED.push([`${vf}FingerL`, `LeftHand${cf}1`]);
	}

	for (const [lv, lc] of SIDED) {
		put(lv, lc);
		const rc = lc.replace(/^Left/, 'Right');
		let rv;
		if (/^left/.test(lv)) rv = lv.replace(/^left/, 'right');
		else if (/^l[A-Z]/.test(lv)) rv = 'r' + lv.slice(1);
		else if (/Left$/.test(lv)) rv = lv.replace(/Left$/, 'Right');
		else if (/L$/.test(lv)) rv = lv.replace(/L$/, 'R');
		else rv = lv;
		put(rv, rc);
	}
	return m;
})();

/**
 * Reduce a bone name to its canonical three.ws form, or null if it doesn't
 * correspond to a recognised humanoid bone.
 *
 * @param {string} name
 * @returns {string|null}
 */
export function canonicalizeBoneName(name) {
	if (typeof name !== 'string' || !name) return null;
	const direct = _lookupBone(name);
	if (direct) return direct;
	// Apple Reality Composer, ARKit-to-Maya, and related USD pipelines append
	// `_joint` to every skeleton joint. Retry without that exact trailing token
	// only after the full spelling failed, preserving any future literal alias
	// that legitimately ends in `joint`. `root_joint` stays unmapped because
	// `root` is a transform above the skeleton, not a body joint.
	const appleJoint = name.replace(/_joint$/i, '');
	if (appleJoint !== name) return _lookupBone(appleJoint);
	// glTF/FBX node de-dup suffix: exporters (CharacterStudio, Blender's glTF
	// writer, FBX2glTF) append `_NN` to keep node names unique, producing
	// `mixamorig:Hips_01`, `Spine1_03`, `LeftForeArm_010`. The plain lookup
	// can't see past the suffix, so retry once with a trailing `_<digits>`
	// removed — but only when the un-stripped form didn't already resolve, so a
	// genuinely numbered bone like `left_hand_index_1` still maps to
	// `LeftHandIndex1` before we'd ever strip its index.
	// `_NN` (glTF/FBX) and `.NNN` (Blender) are both node-de-dup suffixes.
	const deduped = name.replace(/[._]\d+$/, '');
	if (deduped !== name) return _lookupBone(deduped);
	return null;
}

// Reduce a single bone-name variant to canonical form via the lookup table.
// Strips vendor prefixes and separators; returns null on no match.
function _lookupBone(name) {
	let s = name;
	// Strip a leading Maya / FBX / MotionBuilder namespace (one or more
	// `identifier:` segments). Autodesk HumanIK exports every joint behind a
	// character namespace — `Character1:Hips`, `Character1:LeftArm`,
	// `Character1:LeftUpLeg` — whose stems are already canonical, so removing the
	// namespace makes the whole HumanIK / MotionBuilder rig drivable. Maya
	// referenced rigs and OptiTrack/mocap subjects use the same `subject:bone`
	// (and nested `char:ns:bone`) convention. Runs first so it also normalises
	// the colon form of any vendor prefix below (`mixamorig:`, `Armature:`).
	// Safe by construction: a stripped name that isn't a real bone (`prop:Sword`
	// → `Sword`) simply falls through to null and is left untouched.
	s = s.replace(/^(?:[A-Za-z][\w]*:)+/, '');
	// Strip well-known vendor prefixes (case-insensitive, in priority order).
	s = s.replace(/^mixamorig\d*[_:]?/i, '');
	s = s.replace(/^Armature[_/]?/i, '');
	s = s.replace(/^(DEF|ORG|MCH)[-_]/i, '');
	// CharacterStudio exports prefix every joint `CH_` (`CH_Hips`, `CH_LeftUpLeg`),
	// whose stems are otherwise canonical — strip it like any other vendor prefix.
	s = s.replace(/^CH[_:]/i, '');
	// Reallusion Character Creator 3/4 prefixes every joint `CC_Base_`
	// (`CC_Base_Hip`, `CC_Base_L_Upperarm`, `CC_Base_L_Calf`, `CC_Base_NeckTwist01`);
	// once the prefix is gone the stems resolve through the sided/centre alias
	// tables below. Without this an entire CC export maps zero bones and lands in
	// a bind-pose T-pose.
	s = s.replace(/^CC_Base_/i, '');
	// Reallusion CC3/CC4 numbered spine: CC_Base_Spine01/02 -> Spine01/02 after
	// the vendor prefix is stripped. Unlike Unreal's spine_01, the CC names have
	// no separator before their digits, so these exact matches cannot collide with
	// Mixamo's de-duplication suffix handling for Spine_02.
	if (/^spine01$/i.test(s)) return 'Spine';
	if (/^spine02$/i.test(s)) return 'Spine1';
	// Sketchfab / Maya joint exports prefix every joint `j_` (`j_pelvis`, `j_L_hip`,
	// `j_spine_0`). Stripping it leaves stems the canonical + sided tables resolve.
	// The negative lookahead protects VRM/VRoid, whose `J_Bip_*` / `J_Sec_*` names
	// are matched WHOLE by the alias table — stripping `J_` there would corrupt the
	// key and drop an entire VRoid rig. Found by scripts/audit-rig-coverage.mjs:
	// these rigs previously mapped ZERO bones and shipped a bind-pose T-pose.
	s = s.replace(/^j_(?!bip|sec|adj)/i, '');
	// UniGLTF / VRM-converter exports number every node and may flag it with `!`:
	// `5.joint_HipMaster`, `10.!joint_LeftToe`, `95.!Root`. Strip the index, the
	// flag, and the `joint_` noun so the residual bone name resolves.
	s = s.replace(/^\d+\./, '').replace(/^!/, '').replace(/^joint[_:]/i, '');
	// 3ds Max Biped names joints `Bip01 Pelvis`, `Bip001 L UpperArm`, … with a
	// space- or underscore-separated `Bip<NN>` prefix (the digits identify the
	// character). Strip it so `Pelvis`/`Spine`/`L UpperArm`/`L Thigh`/`L Calf`
	// reach the canonical + sided tables instead of T-posing.
	// Source engine rigs sit behind a `ValveBiped.` prefix. three.js deletes the
	// `.` when it sanitizes node names at runtime (PropertyBinding.sanitizeNodeName),
	// so the prefix arrives as `ValveBiped.` from a raw glTF and `ValveBiped`
	// from a loaded scene; strip both before the Biped strip below.
	s = s.replace(/^ValveBiped\.?/i, '');
	s = s.replace(/^Bip\d+[\s_]?/i, '');
	// Collapse separators so `Left_Arm`, `left-arm`, `left arm`, `LeftArm`,
	// `upperarm.L` all reach the same lookup key (`.` covers Blender/MakeHuman).
	const key = s.replace(/[-_.\s]+/g, '').toLowerCase();
	// Canonical/Mixamo/Rigify spellings first, then the Unreal-mannequin aliases,
	// then the extended VRM/Daz/MakeHuman/simple-rig table (lowest priority, so it
	// only catches names the first two don't already resolve).
	return LOOKUP.get(key) ?? UNREAL_ALIASES.get(key) ?? EXTRA_ALIASES.get(key) ?? null;
}

// A joint spelled like the shoulder blade / collar bone rather than the limb.
const CLAVICLE_SPELLING = /shoulder|clavicle|collar|scapula/i;
// A joint spelled like the upper arm itself.
const UPPER_ARM_SPELLING = /upper.?arm|humerus/i;
// Clavicle-only spellings: `shoulder` is deliberately absent, because SMPL-style
// rigs use it FOR the upper arm (`left_shoulder`) and name the clavicle
// `left_collar`. Used by the mirror-image pass.
const COLLAR_ONLY_SPELLING = /clavicle|collar|scapula/i;

/**
 * Resolve the clavicle / upper-arm naming collision on a canonicalization plan.
 *
 * Anatomical rigs give the two bones names that normalize onto ONE canonical
 * name, and no name-only table can separate them, because the same spelling
 * means different bones on different rigs:
 *
 *   - Rigify names the clavicle `shoulder.L` and the upper arm `upper_arm.L`;
 *     both resolve to `LeftArm`, so the clip's arm rotation binds to the
 *     clavicle and the arm swings from the shoulder blade.
 *   - SMPL names the clavicle `left_collar` and the upper arm `left_shoulder`;
 *     both resolve to `LeftShoulder`, leaving `LeftArm` vacant and the arm clip
 *     unbound entirely.
 *   - The hand-built hobby rig spells its upper arm `shoulderL` with no clavicle
 *     at all, so re-pointing that spelling would freeze its arms.
 *
 * The collision is therefore resolved by contention, not by spelling: a target
 * is only reassigned when two joints contest it AND the sibling target is free,
 * so a rig without the collision is never touched. When more than one contender
 * is eligible and the caller supplies an `isAncestor` test, skeleton hierarchy
 * breaks the tie: the clavicle is the parent of the upper arm.
 *
 * Mutates each entry's `canonical` in place.
 *
 * @param {Array<{raw: string, canonical: string}>} plan  candidate assignments
 * @param {{ isAncestor?: (a: object, b: object) => boolean }} [opts]
 * @returns {number} entries reassigned
 */
export function resolveArmShoulderCollisions(plan, opts = {}) {
	const isAncestor = typeof opts.isAncestor === 'function' ? opts.isAncestor : null;
	const count = new Map();
	for (const p of plan) count.set(p.canonical, (count.get(p.canonical) || 0) + 1);

	// When spelling leaves more than one entry eligible, hierarchy decides: the
	// clavicle is an ANCESTOR of the upper arm. `related` holds the contenders on
	// the other side of that relation. Falls back to document order when the
	// caller gave us no hierarchy to read (or none of the pairs are related).
	const byHierarchy = (eligible, related, aboveRelated) => {
		if (eligible.length < 2 || !isAncestor) return eligible[0];
		const match = eligible.find((e) =>
			related.some((o) => o !== e && (aboveRelated ? isAncestor(e, o) : isAncestor(o, e))),
		);
		return match || eligible[0];
	};

	const move = (entry, from, to) => {
		entry.canonical = to;
		count.set(from, (count.get(from) || 1) - 1);
		count.set(to, (count.get(to) || 0) + 1);
	};

	let changed = 0;
	// Arm contested (Rigify): demote the clavicle-spelled contender to Shoulder.
	for (const side of ['Left', 'Right']) {
		const arm = `${side}Arm`;
		const shoulder = `${side}Shoulder`;
		if ((count.get(arm) || 0) < 2 || (count.get(shoulder) || 0) > 0) continue;
		const contenders = plan.filter((p) => p.canonical === arm);
		const upperArms = contenders.filter((p) => UPPER_ARM_SPELLING.test(p.raw));
		if (upperArms.length === 0) continue;
		const eligible = contenders.filter(
			(p) => CLAVICLE_SPELLING.test(p.raw) && !UPPER_ARM_SPELLING.test(p.raw),
		);
		const pick = byHierarchy(eligible, upperArms, true);
		if (!pick) continue;
		move(pick, arm, shoulder);
		changed++;
	}

	// Shoulder contested (SMPL): promote the shoulder-spelled contender to Arm.
	for (const side of ['Left', 'Right']) {
		const arm = `${side}Arm`;
		const shoulder = `${side}Shoulder`;
		if ((count.get(shoulder) || 0) < 2 || (count.get(arm) || 0) > 0) continue;
		const contenders = plan.filter((p) => p.canonical === shoulder);
		const collars = contenders.filter((p) => COLLAR_ONLY_SPELLING.test(p.raw));
		if (collars.length === 0) continue;
		const eligible = contenders.filter(
			(p) => /shoulder/i.test(p.raw) && !COLLAR_ONLY_SPELLING.test(p.raw),
		);
		const pick = byHierarchy(eligible, collars, false);
		if (!pick) continue;
		move(pick, shoulder, arm);
		changed++;
	}
	return changed;
}

// Whether glTF node `a` is an ancestor of node `b`, walking up `parentOf`.
// Tolerates the cyclic parentage a malformed GLB can carry: the visited set
// stops the walk instead of looping forever.
function isAncestorNode(parentOf, aIndex, bIndex) {
	if (aIndex == null || bIndex == null || aIndex === bIndex) return false;
	const seen = new Set([bIndex]);
	for (let cur = parentOf.get(bIndex); cur != null && !seen.has(cur); cur = parentOf.get(cur)) {
		if (cur === aIndex) return true;
		seen.add(cur);
	}
	return false;
}

/**
 * Walk a parsed glTF JSON object and canonicalize joint-node names in place.
 * Only nodes referenced from `skins[].joints[]` are touched — non-bone nodes
 * (meshes, cameras, lights) keep their original names.
 *
 * @param {object} json - parsed glTF JSON
 * @returns {{ renamed: number, samples: Array<{ from: string, to: string }> }}
 */
export function canonicalizeJointNodes(json) {
	if (!json || !Array.isArray(json.nodes) || !Array.isArray(json.skins)) {
		return { renamed: 0, samples: [] };
	}
	const jointIndices = new Set();
	for (const skin of json.skins) {
		if (Array.isArray(skin.joints)) {
			for (const idx of skin.joints) jointIndices.add(idx);
		}
	}
	// Pass 1: resolve each joint to a canonical target (or null).
	const plan = [];
	for (const idx of jointIndices) {
		const node = json.nodes[idx];
		if (!node || typeof node.name !== 'string') continue;
		const canonical = canonicalizeBoneName(node.name);
		if (!canonical || canonical === node.name) continue;
		plan.push({ node, index: idx, raw: node.name, canonical });
	}

	// Pass 1.5/1.6: the clavicle/upper-arm collision, resolved by the shared
	// resolver the runtime lane also uses.
	const parentOf = new Map();
	json.nodes.forEach((n, i) => {
		if (Array.isArray(n.children)) for (const c of n.children) parentOf.set(c, i);
	});
	resolveArmShoulderCollisions(plan, {
		isAncestor: (a, b) => isAncestorNode(parentOf, a.index, b.index),
	});

	// Pass 2: apply. A canonical name is assigned at most once — when two joints
	// still resolve to the same target after collision resolution (SMPL's
	// ankle+foot chain, CC's NeckTwist01/02), or the target spelling already
	// belongs to a joint that isn't being renamed, later renames are skipped.
	// Duplicate node names make the animation bind ambiguous (getObjectByName
	// picks an arbitrary twin), which is strictly worse than leaving the extra
	// joint unmapped. glTF joints are listed parent-first, so first-wins keeps
	// the parent joint (the one that actually articulates the limb).
	const planned = new Set(plan.map((p) => p.node));
	const taken = new Set();
	for (const idx of jointIndices) {
		const node = json.nodes[idx];
		if (node && typeof node.name === 'string' && !planned.has(node)) taken.add(node.name);
	}
	let renamed = 0;
	const samples = [];
	for (const p of plan) {
		if (taken.has(p.canonical)) continue;
		taken.add(p.canonical);
		if (samples.length < 5) samples.push({ from: p.raw, to: p.canonical });
		p.node.name = p.canonical;
		renamed++;
	}
	return { renamed, samples };
}

// Local TRS → Matrix4 for a glTF node.
function nodeLocalMatrix(node) {
	const t = new Vector3();
	const r = new Quaternion();
	const s = new Vector3(1, 1, 1);
	if (node.translation) t.fromArray(node.translation);
	if (node.rotation) r.fromArray(node.rotation);
	if (node.scale) s.fromArray(node.scale);
	return new Matrix4().compose(t, r, s);
}

// World matrices for a set of node indices, each walked to its scene root.
function worldMatricesFor(json, indices, parentOf) {
	const local = json.nodes.map(nodeLocalMatrix);
	const cache = new Map();
	const visiting = new Set();
	const world = (idx) => {
		if (cache.has(idx)) return cache.get(idx);
		// Guard against cyclic parentage in malformed GLBs — treat the cycle root
		// as a top-level node (identity parent) rather than blowing the call stack.
		if (visiting.has(idx)) return local[idx].clone();
		visiting.add(idx);
		const p = parentOf.get(idx);
		const m = p == null ? local[idx].clone() : world(p).clone().multiply(local[idx]);
		visiting.delete(idx);
		cache.set(idx, m);
		return m;
	};
	const out = new Map();
	for (const idx of indices) out.set(idx, world(idx));
	return out;
}

/**
 * Fold a Mixamo/FBX up-axis bake out of the rig. Mixamo exports put a +90°X on
 * the armature node and a −90°X on Hips; the net is upright, but a clip authored
 * for an identity-Hips rig overwrites the −90°X and tips the body over (the
 * "lying down" bug). The runtime retargeter (animation-retarget.js) corrects for
 * this on the fly, but normalizing at ingest means stored avatars are already
 * axis-aligned and need no correction.
 *
 * The fold pushes the armature's rotation down into each child (rotating its
 * translation, pre-multiplying its rotation) and zeroes the armature's rotation.
 * Bone *world* matrices are preserved exactly — provided the armature's scale is
 * uniform, so rotation commutes with it — which means the skinned mesh and its
 * inverse-bind matrices (in the untouched BIN chunk) still resolve to the same
 * bind pose. A counter-rotated Hips collapses to identity. Verified by comparing
 * world matrices before/after; reverts on any mismatch. Mutates `json` in place.
 *
 * @param {object} json parsed glTF JSON
 * @returns {{ corrected: boolean, hipsIdentity?: boolean }}
 */
export function canonicalizeArmatureOrientation(json) {
	if (!json || !Array.isArray(json.nodes) || !Array.isArray(json.skins)) {
		return { corrected: false };
	}
	const parentOf = new Map();
	json.nodes.forEach((n, i) => {
		if (Array.isArray(n.children)) for (const c of n.children) parentOf.set(c, i);
	});
	const jointIdx = new Set();
	for (const skin of json.skins) {
		if (Array.isArray(skin.joints)) for (const j of skin.joints) jointIdx.add(j);
	}
	if (jointIdx.size === 0) return { corrected: false };

	let hips = -1;
	for (const idx of jointIdx) {
		const n = json.nodes[idx];
		if (n && typeof n.name === 'string' && canonicalizeBoneName(n.name) === 'Hips') {
			hips = idx;
			break;
		}
	}
	if (hips < 0) return { corrected: false };
	const pIdx = parentOf.get(hips);
	if (pIdx == null) return { corrected: false };
	const parent = json.nodes[pIdx];

	const r = new Quaternion();
	if (parent.rotation) r.fromArray(parent.rotation);
	if (1 - Math.abs(r.w) < ORIENT_EPS) return { corrected: false }; // already axis-aligned

	// Rotation only commutes with the parent's scale when that scale is uniform.
	const s = parent.scale;
	if (s && (Math.abs(s[0] - s[1]) > ORIENT_EPS || Math.abs(s[1] - s[2]) > ORIENT_EPS)) {
		return { corrected: false };
	}

	const children = Array.isArray(parent.children) ? parent.children : [];
	if (children.length === 0) return { corrected: false };

	// Snapshot the children (for revert) and all affected world matrices (to verify
	// the fold didn't move anything the mesh depends on).
	const checkSet = new Set([...jointIdx, ...children]);
	const before = worldMatricesFor(json, checkSet, parentOf);
	const snapshot = children.map((c) => ({
		idx: c,
		translation: json.nodes[c].translation ? json.nodes[c].translation.slice() : null,
		rotation: json.nodes[c].rotation ? json.nodes[c].rotation.slice() : null,
	}));
	const parentRotBefore = parent.rotation ? parent.rotation.slice() : null;

	for (const c of children) {
		const node = json.nodes[c];
		const t = new Vector3();
		if (node.translation) t.fromArray(node.translation);
		t.applyQuaternion(r);
		node.translation = [t.x, t.y, t.z];
		const cr = new Quaternion();
		if (node.rotation) cr.fromArray(node.rotation);
		cr.premultiply(r);
		node.rotation = [cr.x, cr.y, cr.z, cr.w];
	}
	parent.rotation = [0, 0, 0, 1];

	const after = worldMatricesFor(json, checkSet, parentOf);
	let ok = true;
	for (const idx of checkSet) {
		const a = before.get(idx).elements;
		const b = after.get(idx).elements;
		for (let k = 0; k < 16; k++) {
			if (Math.abs(a[k] - b[k]) > ORIENT_WORLD_EPS) {
				ok = false;
				break;
			}
		}
		if (!ok) break;
	}
	if (!ok) {
		for (const snap of snapshot) {
			const node = json.nodes[snap.idx];
			if (snap.translation) node.translation = snap.translation;
			else delete node.translation;
			if (snap.rotation) node.rotation = snap.rotation;
			else delete node.rotation;
		}
		if (parentRotBefore) parent.rotation = parentRotBefore;
		else delete parent.rotation;
		return { corrected: false };
	}

	const hipsQ = new Quaternion();
	if (json.nodes[hips].rotation) hipsQ.fromArray(json.nodes[hips].rotation);
	return { corrected: true, hipsIdentity: 1 - Math.abs(hipsQ.w) < ORIENT_EPS };
}

/**
 * Canonicalize joint bone names in a GLB ArrayBuffer. Returns a new buffer
 * with renamed nodes (and the count of bones rewritten); the original buffer
 * is left untouched. If no bones needed renaming the original buffer is
 * returned by reference so callers can skip a redundant re-upload.
 *
 * Throws on a malformed GLB header so upload code can surface a clear error.
 *
 * @param {ArrayBuffer} arrayBuffer
 * @returns {{ buffer: ArrayBuffer, renamed: number, samples: Array<{from:string,to:string}> }}
 */
export function canonicalizeGLBBones(arrayBuffer) {
	if (!(arrayBuffer instanceof ArrayBuffer)) {
		throw new TypeError('canonicalizeGLBBones: ArrayBuffer required');
	}
	if (arrayBuffer.byteLength < 20) {
		throw new Error('canonicalizeGLBBones: buffer too small to be a GLB');
	}
	const view = new DataView(arrayBuffer);
	if (view.getUint32(0, true) !== GLB_MAGIC) {
		throw new Error('canonicalizeGLBBones: not a GLB (bad magic number)');
	}
	if (view.getUint32(4, true) !== 2) {
		throw new Error('canonicalizeGLBBones: only GLB v2 is supported');
	}

	// Parse chunk 0 (JSON, required by spec).
	const c0Len  = view.getUint32(12, true);
	const c0Type = view.getUint32(16, true);
	if (c0Type !== CHUNK_TYPE_JSON) {
		throw new Error('canonicalizeGLBBones: chunk 0 must be JSON');
	}
	const jsonBytes = new Uint8Array(arrayBuffer, 20, c0Len);
	let json;
	try {
		json = JSON.parse(new TextDecoder().decode(jsonBytes));
	} catch (err) {
		throw new Error('canonicalizeGLBBones: JSON chunk parse failed: ' + err.message);
	}

	const { renamed, samples } = canonicalizeJointNodes(json);
	const orientation = canonicalizeArmatureOrientation(json);
	if (renamed === 0 && !orientation.corrected) {
		return { buffer: arrayBuffer, renamed: 0, samples: [], orientationCorrected: false };
	}

	// Repack. Chunk 1 (BIN) is optional — preserve it verbatim if present.
	const c1Offset = 20 + c0Len;
	let c1Len = 0, c1Type = 0, binBytes = null;
	if (c1Offset + 8 <= arrayBuffer.byteLength) {
		c1Len  = view.getUint32(c1Offset, true);
		c1Type = view.getUint32(c1Offset + 4, true);
		binBytes = new Uint8Array(arrayBuffer, c1Offset + 8, c1Len);
	}

	// Re-serialise JSON; GLB requires each chunk's data to be 4-byte aligned,
	// padded with 0x20 (space) for the JSON chunk per the glTF 2.0 spec.
	let newJsonBytes = new TextEncoder().encode(JSON.stringify(json));
	const jsonPad = (4 - (newJsonBytes.length % 4)) % 4;
	if (jsonPad) {
		const padded = new Uint8Array(newJsonBytes.length + jsonPad);
		padded.set(newJsonBytes);
		for (let i = 0; i < jsonPad; i++) padded[newJsonBytes.length + i] = 0x20;
		newJsonBytes = padded;
	}

	const totalLen = 12 + 8 + newJsonBytes.length + (binBytes ? 8 + binBytes.length : 0);
	const out = new ArrayBuffer(totalLen);
	const outView = new DataView(out);
	const outU8   = new Uint8Array(out);

	outView.setUint32(0, GLB_MAGIC, true);
	outView.setUint32(4, 2, true);
	outView.setUint32(8, totalLen, true);

	outView.setUint32(12, newJsonBytes.length, true);
	outView.setUint32(16, CHUNK_TYPE_JSON, true);
	outU8.set(newJsonBytes, 20);

	if (binBytes) {
		const binOffset = 20 + newJsonBytes.length;
		outView.setUint32(binOffset,     c1Len, true);
		outView.setUint32(binOffset + 4, c1Type, true);
		outU8.set(binBytes, binOffset + 8);
	}

	return { buffer: out, renamed, samples, orientationCorrected: orientation.corrected };
}