lecodes-assets 0.2.0 → 0.2.1

package/src/retarget/humanoid.ts

@@ -0,0 +1,561 @@
+// Humanoid rigs: the canonical skeleton ("avatar"), the biped classifier that derives a rig's
+// avatar from its SHAPE, the Unity `.meta` avatar reader, and the map between two avatars.
+//
+// The canon is Unity's Humanoid / VRM bone list, so a Unity `.meta` humanoid block imports verbatim
+// and doubles as the oracle for the classifier. An avatar is a property of ONE rig (map each rig
+// once, retarget any pair through the canon), never of a (donor, target) pair.
+//
+// Classification is shape-first, in the bind pose (Y-up, meters — `rig.ts` folds any mesh-space
+// turn in): legs are the two chains from one joint that reach the ground on opposite sides, hands
+// are the lateral joints fanning out into finger chains, the spine is the centre path between them,
+// the head is where the path above the arms last branches. Names only break ties (thumb vs index,
+// a `head` joint under a hair rig) and are quoted in the report when they did. Twist/roll helpers
+// (leaf children collinear with their parent) are recorded, never mapped: they take a fraction of
+// the parent's twist at retarget time.
+import type { Rig, Vec3 } from './rig'
+import type { BoneMap } from './retarget'
+
+// ---- canon ---------------------------------------------------------------------------------------
+
+export const SIDES = [ 'Left', 'Right' ] as const
+export type Side = typeof SIDES[number]
+export const FINGERS = [ 'Thumb', 'Index', 'Middle', 'Ring', 'Little' ] as const
+export type Finger = typeof FINGERS[number]
+export const PHALANGES = [ 'Proximal', 'Intermediate', 'Distal' ] as const
+
+const BODY = [ 'Hips', 'Spine', 'Chest', 'UpperChest', 'Neck', 'Head', 'Jaw', 'LeftEye', 'RightEye' ] as const
+const LIMB = [ 'Shoulder', 'UpperArm', 'LowerArm', 'Hand', 'UpperLeg', 'LowerLeg', 'Foot', 'Toes' ] as const
+export const HUMAN_BONES = [
+  ...BODY,
+  ...SIDES.flatMap((s) => LIMB.map((l) => `${s}${l}`)),
+  ...SIDES.flatMap((s) => FINGERS.flatMap((f) => PHALANGES.map((p) => `${s} ${f} ${p}`))),
+] as const
+export type HumanBone = typeof HUMAN_BONES[number]
+const HUMAN_SET = new Set<string>(HUMAN_BONES)
+export const isHumanBone = (s: string): s is HumanBone => HUMAN_SET.has(s)
+
+/** The canonical description of one rig. `bones` = canonical name → the rig's bone name. */
+/**
+ * What a person decided about THIS rig's transfer, riding in its `.avatar.json` so the studio's
+ * clicks and `lecodes assets retarget --avatar` agree: per canonical bone whether it is built that
+ * way (`keep` the bind) or posed (`align` to the donor, the 8° threshold notwithstanding); degrees
+ * added to the measured palm roll per arm; and the transfer settings the CLI takes as defaults.
+ */
+export interface AvatarTransfer {
+  align?: Partial<Record<HumanBone, 'keep' | 'align'>>
+  roll?: { Left?: number; Right?: number }
+  rootMotion?: 'auto' | 'hips' | 'root' | 'none'
+  plant?: boolean
+  hands?: boolean
+  twist?: number
+}
+
+export interface Avatar {
+  /** Bone that receives root motion: the skinned ancestor of Hips when the rig has one, else Hips. */
+  root: string
+  bones: Partial<Record<HumanBone, string>>
+  /** Twist/roll helpers → the canonical bone whose twist they follow. */
+  twist: Record<string, HumanBone>
+  /** Overrides and defaults from the avatar file (see `AvatarTransfer`). */
+  transfer?: AvatarTransfer
+  /** Rig bones sitting between two mapped ones (extra spine/neck links, metacarpals) — bridged. */
+  bridged: string[]
+  notes: string[]
+}
+
+// ---- Unity `.meta` avatar ----------------------------------------------------------------------
+
+export interface UnityAvatar { bones: Partial<Record<HumanBone, string>>; rootMotionBone: string | null; unknown: string[] }
+
+/** The `humanDescription.human` block of a Unity model importer `.meta` (YAML) — boneName ↔ humanName. */
+export const parseUnityAvatar = (yaml: string): UnityAvatar => {
+  const bones: Partial<Record<HumanBone, string>> = {}
+  const unknown: string[] = []
+  const unq = (s: string): string => s.trim().replace(/^'(.*)'$/, '$1').replace(/^"(.*)"$/, '$1')
+  const re = /boneName:\s*([^\n]+)\n\s*humanName:\s*([^\n]+)/g
+  for (let m = re.exec(yaml); m; m = re.exec(yaml)) {
+    const bone = unq(m[1]), human = unq(m[2])
+    if (isHumanBone(human)) bones[human] = bone
+    else unknown.push(human)
+  }
+  const rm = /rootMotionBoneName:\s*([^\n]*)/.exec(yaml)
+  const rootMotionBone = rm && unq(rm[1]) ? unq(rm[1]) : null
+  return { bones, rootMotionBone, unknown }
+}
+
+// ---- classifier ----------------------------------------------------------------------------------
+
+export interface BipedLeg { side: Side; upper: number; extra: number[]; lower: number; foot: number; toes: number | null; chain: number[] }
+export interface BipedArm { side: Side; attach: number; shoulder: number | null; extra: number[]; upper: number; lower: number; hand: number; fingers: Partial<Record<Finger, number[]>>; metacarpals: number[] }
+
+export interface Biped {
+  root: number | null
+  hips: number
+  forward: Vec3; lateral: Vec3; up: Vec3
+  height: number; ground: number
+  spine: number[]                 // hips (excl) … chest (incl), in order
+  chest: number
+  neck: number[]                  // chest (excl) … head (excl)
+  head: number
+  jaw: number | null
+  eyes: [number, number] | null   // [left, right]
+  legs: BipedLeg[]
+  arms: BipedArm[]
+  twist: { bone: number; of: number }[]
+  helpers: number[]               // skinned joints not part of the structure (hair, cloth, ik_*)
+  notes: string[]
+}
+
+const sub = (a: Vec3, b: Vec3): Vec3 => [ a[0] - b[0], a[1] - b[1], a[2] - b[2] ]
+const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+const len = (v: Vec3): number => Math.hypot(v[0], v[1], v[2])
+const norm = (v: Vec3): Vec3 => { const l = len(v) || 1; return [ v[0] / l, v[1] / l, v[2] / l ] }
+const cross = (a: Vec3, b: Vec3): Vec3 => [ a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0] ]
+const angleDeg = (a: Vec3, b: Vec3): number => Math.acos(Math.max(-1, Math.min(1, dot(norm(a), norm(b))))) * 180 / Math.PI
+
+const TOKEN: Record<string, RegExp> = {
+  head: /head/i, neck: /neck/i, jaw: /jaw/i, eye: /eye(?!.*(brow|lash|lid))/i,
+  thumb: /thumb/i, index: /index/i, middle: /middle/i, ring: /ring(?!.*(ear|fore))/i, little: /pinky|little/i,
+  twist: /twist|roll/i,
+}
+
+/** Structure of a biped rig from its bind pose. Throws when the shape is not a biped. */
+export const classifyBiped = (rig: Rig): Biped => {
+  const notes: string[] = []
+  const N = rig.names.length
+  const pos = rig.bind.worldPos
+  const skinned = (i: number): boolean => rig.bind.fromSkin[i]
+  const children: number[][] = rig.names.map(() => [])
+  rig.parents.forEach((p, i) => { if (p >= 0) children[p].push(i) })
+  /** Skinned descendants reachable without crossing another skinned joint. */
+  const skids = (i: number): number[] => {
+    const out: number[] = []
+    const q = [ ...children[i] ]
+    while (q.length) { const c = q.shift()!; if (skinned(c)) out.push(c); else q.push(...children[c]) }
+    return out
+  }
+  const sparent = (i: number): number => { let p = rig.parents[i]; while (p >= 0 && !skinned(p)) p = rig.parents[p]; return p }
+  const joints = rig.order.filter(skinned)
+  if (joints.length < 12) throw new Error(`${rig.label}: ${joints.length} skinned joints — not a humanoid`)
+  const subtree = (i: number): number[] => { const out: number[] = []; const q = [ i ]; while (q.length) { const j = q.shift()!; out.push(j); q.push(...skids(j)) } return out }
+  const minY = (i: number): number => Math.min(...subtree(i).map((j) => pos[j][1]))
+  const maxY = (i: number): number => Math.max(...subtree(i).map((j) => pos[j][1]))
+  const extent = (i: number): number => { const s = subtree(i); let e = 0; for (const j of s) e = Math.max(e, len(sub(pos[j], pos[i]))); return e }
+
+  let lo = Infinity, hi = -Infinity
+  for (const i of joints) { lo = Math.min(lo, pos[i][1]); hi = Math.max(hi, pos[i][1]) }
+  const height = hi - lo || 1, ground = lo
+  const up: Vec3 = [ 0, 1, 0 ]
+  const horiz = (v: Vec3): Vec3 => [ v[0], 0, v[2] ]
+
+  // --- legs: from one joint, two chains reaching the ground on opposite sides ---------------------
+  /** Greedy descent: at each joint take the child whose subtree goes lowest. */
+  const descend = (from: number): number[] => {
+    const chain = [ from ]
+    for (let guard = 0; guard < 64; guard++) {
+      const ks = skids(chain[chain.length - 1])
+      if (!ks.length) break
+      chain.push(ks.sort((a, b) => minY(a) - minY(b))[0])
+    }
+    return chain
+  }
+  let hips = -1
+  let legChains: number[][] = []
+  for (const h of joints) {
+    const cands = skids(h)
+      .map((c) => descend(c))
+      .filter((ch) => ch.length >= 3 && minY(ch[0]) < ground + 0.12 * height && len(horiz(sub(pos[ch[0]], pos[h]))) > 0.02 * height)
+    // Opposite sides of h, horizontally.
+    let best: [number[], number[]] | null = null, bestScore = -Infinity
+    for (let a = 0; a < cands.length; a++) for (let b = a + 1; b < cands.length; b++) {
+      const oa = horiz(sub(pos[cands[a][0]], pos[h])), ob = horiz(sub(pos[cands[b][0]], pos[h]))
+      if (dot(oa, ob) >= 0) continue
+      const score = cands[a].length + cands[b].length + len(sub(oa, ob)) / height * 10
+      if (score > bestScore) { bestScore = score; best = [ cands[a], cands[b] ] }
+    }
+    if (!best) continue
+    // The lowest joint that owns such a pair is the pelvis (a root above it also "owns" the legs).
+    if (hips < 0 || pos[h][1] < pos[hips][1]) { hips = h; legChains = best }
+  }
+  if (hips < 0) throw new Error(`${rig.label}: no pelvis with two legs reaching the ground — not a biped`)
+  const legJoints = new Set(legChains.flat())
+
+  // --- hands: lateral joints fanning into finger chains ---------------------------------------
+  const centreX = pos[hips]
+  const handScore = (i: number): number => {
+    if (legJoints.has(i) || i === hips) return -1
+    const ks = skids(i).filter((c) => subtree(c).length <= 6 && extent(c) < 0.12 * height)
+    if (ks.length < 3) return -1
+    const lat = len(horiz(sub(pos[i], centreX)))
+    return lat > 0.12 * height ? lat : -1
+  }
+  const handCands = joints.filter((i) => handScore(i) > 0)
+
+  // --- spine: hips → the joint the arms hang off; head: last branch above it ------------------
+  const ancestors = (i: number): number[] => { const out: number[] = []; for (let a = i; a >= 0; a = sparent(a)) out.push(a); return out }
+  const lca = (list: number[]): number => {
+    let common = ancestors(list[0])
+    for (const i of list.slice(1)) { const set = new Set(ancestors(i)); common = common.filter((a) => set.has(a)) }
+    return common[0]
+  }
+  // Provisional forward from the legs' feet (toes − ankle) so sides can be told apart; refined below.
+  const footOf = (chain: number[]): { foot: number; toes: number | null } => {
+    const last = chain[chain.length - 1]
+    // An END SITE (Mixamo `LeftToe_End`, a `_end` / `Nub` leaf): the link before it is already on
+    // the ground — the ball — so the foot is one link higher. Without this a 5-link Mixamo leg
+    // reads as upper · (extra) · lower = Foot · foot = ToeBase, and the ankle's motion leaks into
+    // the knee through the leg IK (the knee locks straight at every toe-off).
+    if (chain.length >= 5) {
+      const ball = chain[chain.length - 2], ankle = chain[chain.length - 3]
+      const endSite = /(_end|end|nub|tip)$/i.test(rig.names[last]) && children[last].length === 0
+      if ((endSite || pos[ball][1] - ground < 0.03 * height) && pos[ball][1] - ground < 0.06 * height && pos[ankle][1] - ground < 0.14 * height) return { foot: ankle, toes: ball }
+    }
+    if (chain.length >= 4 && pos[last][1] - ground < 0.06 * height && pos[chain[chain.length - 2]][1] - ground < 0.14 * height) return { foot: chain[chain.length - 2], toes: last }
+    return { foot: last, toes: null }
+  }
+  let forward: Vec3 = [ 0, 0, 1 ]
+  {
+    const dirs = legChains.map(footOf).filter((f) => f.toes !== null).map((f) => horiz(sub(pos[f.toes!], pos[f.foot])))
+    if (dirs.length) forward = norm(dirs.reduce((a, d) => [ a[0] + d[0], 0, a[2] + d[2] ], [ 0, 0, 0 ] as Vec3))
+    else notes.push('no toe bones — facing assumed +Z')
+  }
+  let lateral: Vec3 = norm(cross(up, forward))   // +lateral = the rig's LEFT
+  const latOf = (i: number): number => dot(sub(pos[i], pos[hips]), lateral)
+
+  // Hands: on each side the candidate furthest out; fall back to the furthest lateral leaf off the torso.
+  const handOn = (sign: 1 | -1): number | null => {
+    const side = handCands.filter((i) => Math.sign(latOf(i)) === sign).sort((a, b) => Math.abs(latOf(b)) - Math.abs(latOf(a)))
+    if (side.length) return side[0]
+    const leaves = joints.filter((i) => !legJoints.has(i) && skids(i).length === 0 && Math.sign(latOf(i)) === sign && Math.abs(latOf(i)) > 0.15 * height && pos[i][1] > pos[hips][1])
+      .sort((a, b) => Math.abs(latOf(b)) - Math.abs(latOf(a)))
+    if (leaves.length) { notes.push(`no finger chains on the ${sign > 0 ? 'left' : 'right'} — hand = furthest lateral joint ${rig.names[leaves[0]]}`); return leaves[0] }
+    return null
+  }
+  const handL = handOn(1), handR = handOn(-1)
+  if (handL === null || handR === null) throw new Error(`${rig.label}: ${handL === null ? 'left' : 'right'} hand not found — not a biped`)
+
+  // Arm chains up to the spine; the chest is where they meet.
+  const upTo = (from: number, stop: (j: number) => boolean): number[] => { const out: number[] = []; for (let a = from; a >= 0 && !stop(a); a = sparent(a)) out.unshift(a); return out }
+  const chest = lca([ handL, handR ])
+  if (chest === hips || !ancestors(chest).includes(hips)) throw new Error(`${rig.label}: arms meet at ${rig.names[chest]}, not above the pelvis — not a biped`)
+  const spine = upTo(chest, (j) => j === hips)   // hips excl … chest incl
+  const spineSet = new Set(spine)
+  const armOf = (hand: number, side: Side): BipedArm => {
+    const path = upTo(hand, (j) => spineSet.has(j))   // attach excl … hand incl
+    const attach = sparent(path[0])
+    const links = path.slice(0, -1)                  // clavicle?, upper, lower (+ extras)
+    if (links.length < 2) notes.push(`${side} arm has ${links.length} link(s) between ${rig.names[attach]} and the hand — check the map`)
+    const lower = links[links.length - 1], upper = links[links.length - 2] ?? lower
+    const shoulder = links.length >= 3 ? links[0] : null
+    const extra = links.length > 3 ? links.slice(1, -2) : []
+    return { side, attach, shoulder, extra, upper, lower, hand, fingers: {}, metacarpals: [] }
+  }
+  const arms = [ armOf(handL, 'Left'), armOf(handR, 'Right') ]
+  const armJoints = new Set(arms.flatMap((a) => [ a.shoulder ?? -1, ...a.extra, a.upper, a.lower, a.hand ].filter((i) => i >= 0)))
+
+  // Head: up the centre path from the chest, past the arms; the last branching joint, else the end.
+  const centred = (i: number): boolean => Math.abs(latOf(i)) < 0.05 * height
+  const path: number[] = []
+  {
+    let cur = chest
+    for (let guard = 0; guard < 64; guard++) {
+      const ks = skids(cur).filter((c) => !armJoints.has(c) && !legJoints.has(c) && centred(c) && pos[c][1] > pos[cur][1] - 0.01 * height)
+      if (!ks.length) break
+      cur = ks.sort((a, b) => maxY(b) - maxY(a))[0]
+      path.push(cur)
+    }
+  }
+  if (!path.length) throw new Error(`${rig.label}: nothing above ${rig.names[chest]} — no neck/head`)
+  let h = path.length - 1
+  while (h > 0 && skids(path[h]).length < 2) h--
+  if (skids(path[h]).length < 2) h = path.length - 1
+  const named = path.findIndex((i) => TOKEN.head.test(rig.names[i]))
+  if (named >= 0 && named !== h) { notes.push(`head: shape picked ${rig.names[path[h]]}, name says ${rig.names[path[named]]} — using the name`); h = named }
+  const head = path[h]
+  const neck = path.slice(0, h)
+
+  // Eyes: a lateral pair of head children with the largest forward offset; jaw: centred, forward-down.
+  let eyes: [number, number] | null = null, jaw: number | null = null
+  {
+    const kids = skids(head)
+    const pair = kids.filter((c) => Math.abs(latOf(c) - latOf(head)) > 0.01 * height)
+    const fwdOf = (c: number): number => dot(sub(pos[c], pos[head]), forward)
+    let best = -Infinity
+    for (const a of pair) for (const b of pair) {
+      if (latOf(a) - latOf(head) <= 0 || latOf(b) - latOf(head) >= 0) continue
+      if (Math.abs(pos[a][1] - pos[b][1]) > 0.03 * height) continue
+      const score = fwdOf(a) + fwdOf(b) + (TOKEN.eye.test(rig.names[a]) && TOKEN.eye.test(rig.names[b]) ? height : 0)
+      if (score > best) { best = score; eyes = [ a, b ] }
+    }
+    if (eyes && best < 0.005 * height) eyes = null
+    // Jaw: a centred child forward of the head joint (it hinges at the skull base, level with the
+    // head joint, and hangs forward-down) — the lowest such; a `jaw` name wins outright.
+    const eyeSet = new Set(eyes ?? [])
+    const byName = kids.find((c) => !eyeSet.has(c) && TOKEN.jaw.test(rig.names[c]))
+    const j = byName ?? kids.filter((c) => !eyeSet.has(c) && Math.abs(latOf(c) - latOf(head)) < 0.03 * height && fwdOf(c) > 0.01 * height && pos[c][1] < pos[head][1] + 0.03 * height)
+      .sort((a, b) => pos[a][1] - pos[b][1])[0]
+    if (j !== undefined) jaw = j
+  }
+
+  // Legs: segment each chain into upper / (extra) / lower / foot / toes and side them.
+  const legs: BipedLeg[] = legChains.map((chain) => {
+    const { foot, toes } = footOf(chain)
+    const body = chain.slice(0, chain.indexOf(foot))   // upper … lower
+    const side: Side = latOf(chain[0]) > 0 ? 'Left' : 'Right'
+    if (body.length < 2) { notes.push(`${side} leg has ${body.length} link(s) above the foot — check the map`); return { side, upper: body[0] ?? foot, extra: [], lower: body[body.length - 1] ?? foot, foot, toes, chain } }
+    return { side, upper: body[0], extra: body.slice(1, -1), lower: body[body.length - 1], foot, toes, chain }
+  }).sort((a, b) => (a.side === 'Left' ? 0 : 1) - (b.side === 'Left' ? 0 : 1))
+  if (legs[0].side === legs[1].side) notes.push('both legs on the same side — facing is wrong')
+  const rootAbove = ancestors(hips).slice(1)
+  const root = rootAbove.length ? rootAbove[rootAbove.length - 1] : null
+
+  // Fingers: chains off the hand; a trailing unskinned leaf completes a short chain (a low-poly
+  // hand's distal phalanx often carries no weights), a 4th link ahead of three is a metacarpal.
+  const fingerChain = (from: number): number[] => {
+    const chain = [ from ]
+    for (let guard = 0; guard < 8; guard++) {
+      const cur = chain[chain.length - 1]
+      const ks = skids(cur)
+      if (ks.length) { chain.push(ks.sort((a, b) => extent(b) - extent(a))[0]); continue }
+      const raw = children[cur].filter((c) => !skinned(c))
+      if (chain.length < 3 && raw.length === 1 && !/end|nub|tip|leaf/i.test(rig.names[raw[0]])) chain.push(raw[0])
+      break
+    }
+    return chain
+  }
+  for (const arm of arms) {
+    let chains = skids(arm.hand).filter((c) => subtree(c).length <= 6 && extent(c) < 0.12 * height).map(fingerChain)
+    if (!chains.length) continue
+    // Identity: names when they single out five chains (a weapon socket or an IK target on the hand
+    // is then just dropped), else the thumb = the base nearest the wrist and the rest ordered from
+    // the thumb outward, after shedding the shortest extra chains (sockets are one joint).
+    const FINGER_TOKENS = [ 'thumb', 'index', 'middle', 'ring', 'little' ]
+    const nameOf = (c: number[]): string | undefined => FINGER_TOKENS.find((t) => c.some((i) => TOKEN[t].test(rig.names[i])))
+    const named = chains.map(nameOf)
+    const namedSet = new Set(named.filter(Boolean))
+    let useNames = false
+    if (namedSet.size === 5 && named.filter(Boolean).length === 5) { chains = chains.filter((_, k) => named[k]); useNames = true }
+    else if (chains.length > 5) {
+      chains = [ ...chains ].sort((a, b) => b.length - a.length || extent(b[0]) - extent(a[0])).slice(0, 5)
+    }
+    const meta: number[] = []
+    const phal = chains.map((c) => (c.length >= 4 ? (meta.push(c[0]), c.slice(1, 4)) : c.slice(0, 3)))
+    arm.metacarpals = meta
+    const byName = chains.map(nameOf)
+    const assigned: Partial<Record<Finger, number[]>> = {}
+    if (useNames) {
+      byName.forEach((t, k) => { assigned[(t!.charAt(0).toUpperCase() + t!.slice(1)) as Finger] = phal[k] })
+    } else {
+      const order = phal.map((c, k) => ({ k, d: len(sub(pos[c[0]], pos[arm.hand])) })).sort((a, b) => a.d - b.d)
+      const thumb = order[0].k
+      const rest = phal.map((_, k) => k).filter((k) => k !== thumb)
+      const mean = rest.reduce((a, k) => [ a[0] + pos[phal[k][0]][0], a[1] + pos[phal[k][0]][1], a[2] + pos[phal[k][0]][2] ] as Vec3, [ 0, 0, 0 ] as Vec3).map((v) => v / (rest.length || 1)) as Vec3
+      const axis = norm(sub(pos[phal[thumb][0]], mean))
+      rest.sort((a, b) => dot(sub(pos[phal[b][0]], mean), axis) - dot(sub(pos[phal[a][0]], mean), axis))
+      assigned.Thumb = phal[thumb]
+      const names: Finger[] = [ 'Index', 'Middle', 'Ring', 'Little' ]
+      rest.slice(0, 4).forEach((k, n) => { assigned[names[n]] = phal[k] })
+      if (phal.length !== 5) notes.push(`${arm.side} hand has ${phal.length} finger chains — identities by position`)
+      else notes.push(`${arm.side} fingers identified by position (no finger names)`)
+    }
+    arm.fingers = assigned
+  }
+
+  // Twist helpers: extra children of a limb bone that are leaves (or tiny chains) collinear with it.
+  const twist: { bone: number; of: number }[] = []
+  const limbLinks: [number, number][] = []
+  for (const l of legs) { const seq = [ l.upper, ...l.extra, l.lower, l.foot ]; for (let k = 0; k + 1 < seq.length; k++) limbLinks.push([ seq[k], seq[k + 1] ]) }
+  for (const a of arms) { const seq = [ ...(a.shoulder !== null ? [ a.shoulder ] : []), ...a.extra, a.upper, a.lower, a.hand ]; for (let k = 0; k + 1 < seq.length; k++) limbLinks.push([ seq[k], seq[k + 1] ]) }
+  const structural = new Set<number>([ hips, ...spine, ...neck, head, ...(jaw !== null ? [ jaw ] : []), ...(eyes ?? []), ...legs.flatMap((l) => l.chain), ...armJoints, ...arms.flatMap((a) => [ ...a.metacarpals, ...Object.values(a.fingers).flat() ]), ...(root !== null ? [ root ] : []) ])
+  for (const [ b, c ] of limbLinks) {
+    const dir = sub(pos[c], pos[b])
+    for (const t of skids(b)) {
+      if (structural.has(t) || subtree(t).length > 2) continue
+      const d = sub(pos[t], pos[b])
+      const onAxis = len(d) < 1e-6 || angleDeg(d, dir) < 25
+      if (onAxis && (TOKEN.twist.test(rig.names[t]) || subtree(t).length === 1)) { twist.push({ bone: t, of: b }); structural.add(t) }
+    }
+  }
+  const helpers = joints.filter((i) => !structural.has(i))
+
+  // Final frame: forward from the toes (or eyes), lateral from it.
+  if (eyes) {
+    const eyeFwd = horiz(sub([ (pos[eyes[0]][0] + pos[eyes[1]][0]) / 2, 0, (pos[eyes[0]][2] + pos[eyes[1]][2]) / 2 ], pos[head]))
+    if (len(eyeFwd) > 0.005 * height && angleDeg(eyeFwd, forward) > 90) notes.push('eyes look the other way than the toes point — check facing')
+  }
+  lateral = norm(cross(up, forward))
+  return { root, hips, forward, lateral, up, height, ground, spine, chest, neck, head, jaw, eyes, legs, arms, twist, helpers, notes }
+}
+
+/** A cheap "is this a biped" probe for callers that must choose a classifier. */
+export const isBiped = (rig: Rig): boolean => {
+  try { classifyBiped(rig); return true } catch { return false }
+}
+
+// ---- avatar from a classification / from Unity ----------------------------------------------------
+
+export const avatarFromBiped = (rig: Rig, b: Biped): Avatar => {
+  const n = (i: number): string => rig.names[i]
+  const bones: Partial<Record<HumanBone, string>> = {}
+  const bridged: string[] = []
+  bones.Hips = n(b.hips)
+  // Spine: 1 → Spine; 2 → Spine, Chest; 3 → Spine, Chest, UpperChest; more → first, middle-by-arc, last.
+  const s = b.spine
+  if (s.length === 1) bones.Spine = n(s[0])
+  else if (s.length === 2) { bones.Spine = n(s[0]); bones.Chest = n(s[1]) }
+  else if (s.length === 3) { bones.Spine = n(s[0]); bones.Chest = n(s[1]); bones.UpperChest = n(s[2]) }
+  else if (s.length > 3) {
+    const pos = rig.bind.worldPos
+    let acc = 0
+    const arc = s.map((i, k) => (acc += len(sub(pos[i], pos[k ? s[k - 1] : b.hips]))))
+    const mid = arc.slice(1, -1).map((v, k) => ({ k: k + 1, d: Math.abs(v - acc / 2) })).sort((a, c) => a.d - c.d)[0].k
+    bones.Spine = n(s[0]); bones.Chest = n(s[mid]); bones.UpperChest = n(s[s.length - 1])
+    s.forEach((i, k) => { if (k !== 0 && k !== mid && k !== s.length - 1) bridged.push(n(i)) })
+  }
+  if (b.neck.length) { bones.Neck = n(b.neck[0]); bridged.push(...b.neck.slice(1).map(n)) }
+  bones.Head = n(b.head)
+  if (b.jaw !== null) bones.Jaw = n(b.jaw)
+  if (b.eyes) { bones.LeftEye = n(b.eyes[0]); bones.RightEye = n(b.eyes[1]) }
+  for (const l of b.legs) {
+    bones[`${l.side}UpperLeg`] = n(l.upper); bones[`${l.side}LowerLeg`] = n(l.lower); bones[`${l.side}Foot`] = n(l.foot)
+    if (l.toes !== null) bones[`${l.side}Toes`] = n(l.toes)
+    bridged.push(...l.extra.map(n))
+  }
+  for (const a of b.arms) {
+    if (a.shoulder !== null) bones[`${a.side}Shoulder`] = n(a.shoulder)
+    bones[`${a.side}UpperArm`] = n(a.upper); bones[`${a.side}LowerArm`] = n(a.lower); bones[`${a.side}Hand`] = n(a.hand)
+    bridged.push(...a.extra.map(n), ...a.metacarpals.map(n))
+    for (const f of FINGERS) {
+      const chain = a.fingers[f]
+      if (!chain) continue
+      chain.forEach((i, k) => { if (k < 3) bones[`${a.side} ${f} ${PHALANGES[k]}`] = n(i) })
+    }
+  }
+  const byIndex = new Map<number, HumanBone>()
+  for (const [ k, v ] of Object.entries(bones)) byIndex.set(rig.index.get(v!)!, k as HumanBone)
+  const twist: Record<string, HumanBone> = {}
+  for (const t of b.twist) { const of = byIndex.get(t.of); if (of) twist[n(t.bone)] = of }
+  return { root: b.root !== null ? n(b.root) : n(b.hips), bones, twist, bridged, notes: [ ...b.notes ] }
+}
+
+/** Derive a rig's avatar from its shape. */
+export const avatarFromRig = (rig: Rig): Avatar => avatarFromBiped(rig, classifyBiped(rig))
+
+/**
+ * Avatar from a Unity `.meta` humanoid block, checked against the rig; the root and the twist
+ * helpers come from the rig's shape when it classifies (a `.meta` has neither).
+ */
+export const avatarFromUnity = (rig: Rig, unity: UnityAvatar): Avatar => {
+  const notes: string[] = []
+  const bones: Partial<Record<HumanBone, string>> = {}
+  for (const [ k, v ] of Object.entries(unity.bones)) {
+    if (rig.index.has(v!)) bones[k as HumanBone] = v
+    else notes.push(`.meta maps ${k} to '${v}', which the rig does not have — dropped`)
+  }
+  if (unity.unknown.length) notes.push(`.meta human names not in the canon: ${unity.unknown.join(', ')}`)
+  if (!bones.Hips) throw new Error(`${rig.label}: the .meta avatar has no Hips`)
+  let shape: Biped | null = null
+  try { shape = classifyBiped(rig) } catch (e) { notes.push(`shape classification failed (${(e as Error).message}) — no twist helpers, root = skinned ancestor of Hips`) }
+  const hips = rig.index.get(bones.Hips)!
+  let root = bones.Hips
+  if (unity.rootMotionBone && rig.index.has(unity.rootMotionBone)) root = unity.rootMotionBone
+  else { let top = -1; for (let a = rig.parents[hips]; a >= 0; a = rig.parents[a]) if (rig.bind.fromSkin[a]) top = a; if (top >= 0) root = rig.names[top] }
+  const twist: Record<string, HumanBone> = {}
+  if (shape) {
+    const byIndex = new Map<number, HumanBone>()
+    for (const [ k, v ] of Object.entries(bones)) byIndex.set(rig.index.get(v!)!, k as HumanBone)
+    for (const t of shape.twist) { const of = byIndex.get(t.of); if (of) twist[rig.names[t.bone]] = of }
+  }
+  return { root, bones, twist, bridged: [], notes }
+}
+
+/** The `.avatar.json` file shape — what `--auto-map` writes for a humanoid and `--avatar` reads. */
+export interface AvatarFile { root?: string; bones: Record<string, string>; twist?: Record<string, string>; transfer?: AvatarTransfer }
+
+export const avatarFromFile = (rig: Rig, file: AvatarFile): Avatar => {
+  const bones: Partial<Record<HumanBone, string>> = {}
+  const notes: string[] = []
+  for (const [ k, v ] of Object.entries(file.bones)) {
+    if (!isHumanBone(k)) { notes.push(`'${k}' is not a canonical humanoid bone — ignored`); continue }
+    if (!rig.index.has(v)) { notes.push(`${k} → '${v}': the rig has no such bone — dropped`); continue }
+    bones[k] = v
+  }
+  if (!bones.Hips) throw new Error(`${rig.label}: avatar has no Hips`)
+  const twist: Record<string, HumanBone> = {}
+  for (const [ t, of ] of Object.entries(file.twist ?? {})) if (isHumanBone(of) && rig.index.has(t)) twist[t] = of
+  let transfer: AvatarTransfer | undefined
+  if (file.transfer && typeof file.transfer === 'object') {
+    transfer = { ...file.transfer }
+    if (transfer.align) {
+      const align: AvatarTransfer['align'] = {}
+      for (const [ k, v ] of Object.entries(transfer.align)) {
+        if (!isHumanBone(k)) { notes.push(`transfer.align: '${k}' is not a canonical bone — ignored`); continue }
+        if (v === 'keep' || v === 'align') align[k] = v
+      }
+      transfer.align = align
+    }
+  }
+  return { root: file.root && rig.index.has(file.root) ? file.root : bones.Hips, bones, twist, bridged: [], notes, ...(transfer ? { transfer } : {}) }
+}
+
+export const avatarToFile = (a: Avatar): AvatarFile => ({ root: a.root, bones: { ...a.bones } as Record<string, string>, twist: Object.keys(a.twist).length ? { ...a.twist } : undefined, ...(a.transfer && Object.keys(a.transfer).length ? { transfer: { ...a.transfer } } : {}) })
+
+// ---- map between two avatars --------------------------------------------------------------------
+
+export interface HumanoidMap { map: BoneMap; root: string; legs: string[]; shared: HumanBone[]; targetOnly: HumanBone[]; donorOnly: HumanBone[] }
+
+/** target bone → donor bone for every canonical bone both avatars have. */
+export const mapAvatars = (target: Avatar, donor: Avatar): HumanoidMap => {
+  const map: BoneMap = {}
+  const shared: HumanBone[] = [], targetOnly: HumanBone[] = [], donorOnly: HumanBone[] = []
+  for (const k of HUMAN_BONES) {
+    const t = target.bones[k], d = donor.bones[k]
+    if (t && d) { map[t] = d; shared.push(k) }
+    else if (t) targetOnly.push(k)
+    else if (d) donorOnly.push(k)
+  }
+  // Root motion: the target's root receives the donor's root; when only one side has a root above
+  // the hips the hips carry it (the retarget scales and re-expresses it either way).
+  map[target.root] = donor.root
+  if (target.root !== target.bones.Hips && donor.root === donor.bones.Hips) map[target.bones.Hips!] = donor.bones.Hips!
+  // Leg effectors: the ANKLES. The foot's orientation is the donor's rotation on the target's own
+  // flat bind — a boot whose foot bone dives steeply to the ball (Swat: −56°, X-bot: −27° for the
+  // same flat sole) must not become an IK link, or the solver decides its pitch (up to 50° off the
+  // donor in the swing). Toes stay FK below the foot.
+  const legs = SIDES.map((s) => target.bones[`${s}Foot`]).filter((x): x is string => !!x)
+  return { map, root: target.root, legs, shared, targetOnly, donorOnly }
+}
+
+// ---- reports -------------------------------------------------------------------------------------
+
+export const describeBiped = (rig: Rig, b: Biped): string => {
+  const n = (i: number | null): string => (i === null ? '-' : rig.names[i])
+  const fingers = b.arms.map((a) => Object.keys(a.fingers).length).join('/')
+  return `hips ${n(b.hips)}${b.root !== null ? ` (root ${n(b.root)})` : ''} · spine ${b.spine.length} · neck ${b.neck.length} · head ${n(b.head)} · jaw ${n(b.jaw)} · eyes ${b.eyes ? `${n(b.eyes[0])}/${n(b.eyes[1])}` : '-'} · arms ${b.arms.map((a) => `${a.side[0]}:${(a.shoulder !== null ? 1 : 0) + 2 + a.extra.length}`).join(' ')} · fingers ${fingers} · legs ${b.legs.map((l) => `${l.side[0]}:${2 + l.extra.length}${l.toes !== null ? '+toes' : ''}`).join(' ')} · twist ${b.twist.length} · helpers ${b.helpers.length} · facing [${b.forward.map((x) => x.toFixed(2)).join(',')}]`
+}
+
+/** The pairing report for a humanoid map: one line per canonical group. */
+export const describeHumanoidMap = (target: Avatar, donor: Avatar, hm: HumanoidMap): string[] => {
+  const lines: string[] = []
+  const pair = (k: HumanBone): string => `${target.bones[k]}←${donor.bones[k]}`
+  const group = (label: string, keys: HumanBone[]): void => {
+    const have = keys.filter((k) => hm.shared.includes(k))
+    if (have.length) lines.push(`  ${label}: ${have.map(pair).join(', ')}`)
+  }
+  lines.push(`  root: ${target.root}←${donor.root}`)
+  group('torso', [ 'Hips', 'Spine', 'Chest', 'UpperChest', 'Neck', 'Head', 'Jaw', 'LeftEye', 'RightEye' ])
+  for (const s of SIDES) group(`${s.toLowerCase()} arm`, [ `${s}Shoulder`, `${s}UpperArm`, `${s}LowerArm`, `${s}Hand` ])
+  for (const s of SIDES) group(`${s.toLowerCase()} leg`, [ `${s}UpperLeg`, `${s}LowerLeg`, `${s}Foot`, `${s}Toes` ])
+  for (const s of SIDES) {
+    const fs = FINGERS.filter((f) => hm.shared.includes(`${s} ${f} Proximal`))
+    if (fs.length) lines.push(`  ${s.toLowerCase()} fingers: ${fs.map((f) => `${f.toLowerCase()} ×${PHALANGES.filter((p) => hm.shared.includes(`${s} ${f} ${p}`)).length}`).join(', ')}`)
+  }
+  if (hm.targetOnly.length) lines.push(`  target only (kept at bind): ${hm.targetOnly.join(', ')}`)
+  if (hm.donorOnly.length) lines.push(`  donor only (dropped): ${hm.donorOnly.join(', ')}`)
+  const tw = Object.entries(target.twist)
+  if (tw.length) lines.push(`  target twist helpers: ${tw.map(([ b, of ]) => `${b}→${of}`).join(', ')}`)
+  if (target.bridged.length) lines.push(`  target bridged: ${target.bridged.join(', ')}`)
+  for (const n of target.notes) lines.push(`  ⚠ target: ${n}`)
+  for (const n of donor.notes) lines.push(`  ⚠ donor: ${n}`)
+  return lines
+}