lecodes-assets 0.2.0 → 2.4.10

package/src/probe.ts

@@ -0,0 +1,167 @@
+// probe — what's in an FBX or GLB: skeleton, clips + track counts, meshes, materials, textures, and
+// (GLB) a skin bind sanity check. Prints what the AI/dev needs to decide before/after converting.
+
+import { readFileSync } from "node:fs"
+import { extname } from "node:path"
+import type { Document, Node } from "@gltf-transform/core"
+import { readFbx, f32 } from "./fbx/read"
+import { makeIO } from "./fbx/convert"
+import { measureScale } from "./doctor/normalizeScale"
+import { duplicateNodeNames } from "./mergeSkins"
+
+const fmt = (n: number, d = 2): string => n.toFixed(d)
+
+export const probeFbx = async (path: string): Promise<string> => {
+  const s = await readFbx(new Uint8Array(readFileSync(path)))
+  const bones = s.nodes.filter((n) => n.isBone)
+  const meshNodes = s.nodes.filter((n) => n.mesh >= 0)
+  const lines: string[] = []
+  lines.push(`FBX ${path}`)
+  lines.push(`  creator: ${s.meta.creator || "?"} · file unit: ${s.meta.unitMeters} m (converted to meters) · nodes ${s.nodes.length} · bones ${bones.length}`)
+  lines.push(`  meshes ${s.meshes.length} (${meshNodes.map((n) => n.name).join(", ") || "none"}) · skins ${s.skins.length}${s.skins.length ? ` (${s.skins.map((k) => k.joints.length + " joints").join(", ")})` : ""}`)
+  for (const m of s.meshes) for (const p of m.primitives) lines.push(`    ${m.name}: ${p.vertexCount} verts / ${p.indexCount / 3} tris · mat ${p.material >= 0 ? s.materials[p.material]?.name : "-"} · ${p.joints >= 0 ? "skinned" : "static"} · size ${p.max.map((v, i) => fmt(v - p.min[i])).join("×")} m`)
+  lines.push(`  materials ${s.materials.length}: ${s.materials.map((m) => `${m.name}[${m.shader}${m.baseTex >= 0 ? ",tex" : ""}${m.normalTex >= 0 ? ",nrm" : ""}${m.opacityTex >= 0 ? ",alpha" : ""}]`).join(", ") || "none"}`)
+  lines.push(`  textures ${s.textures.length}: ${s.textures.map((t) => `${(t.relative || t.filename).split(/[\\/]/).pop()}${t.content >= 0 ? ` (embedded ${(t.size / 1024).toFixed(0)}KB)` : " (external)"}`).join(", ") || "none"}`)
+  const anims = s.animations.filter((a) => a.tracks.length > 0)
+  lines.push(`  clips ${anims.length}: ${anims.map((a) => `"${a.name}" ${fmt(a.duration)}s ${a.tracks.length} tracks/${a.tracks.reduce((n, t) => n + t.count, 0)} keys${a.tracks.every((t) => t.constant) ? " (STATIC pose)" : ""}`).join(", ") || "none"}`)
+  const rootBones = bones.filter((b) => !(s.nodes[b.parent]?.isBone))
+  if (rootBones.length) lines.push(`  skeleton root(s): ${rootBones.map((b) => b.name || "(unnamed)").join(", ")}`)
+  // per clip: what the root bone(s) do — travel (root motion) and the first frame vs the rest pose
+  for (const a of anims) {
+    for (const rb of rootBones.filter((b) => !b.helper && b.name)) {
+      const idx = s.nodes.indexOf(rb)
+      const tr = a.tracks.find((t) => t.node === idx && t.path === "translation")
+      const rot = a.tracks.find((t) => t.node === idx && t.path === "rotation")
+      if (!tr && !rot) continue
+      const parts: string[] = []
+      if (tr) {
+        const v = f32(s, tr.values, tr.count * 3)
+        const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+        for (let i = 0; i < v.length; i += 3) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], v[i + k]); hi[k] = Math.max(hi[k], v[i + k]) }
+        const start = Math.hypot(v[0] - rb.t[0], v[1] - rb.t[1], v[2] - rb.t[2])
+        parts.push(`moves ${fmt(hi[0] - lo[0])}×${fmt(hi[1] - lo[1])}×${fmt(hi[2] - lo[2])} m`)
+        if (start > 0.02) parts.push(`starts ${fmt(start)} m from rest`)
+      }
+      if (rot) {
+        const q = f32(s, rot.values, rot.count * 4)
+        const d = Math.min(1, Math.abs(q[0] * rb.r[0] + q[1] * rb.r[1] + q[2] * rb.r[2] + q[3] * rb.r[3]))
+        parts.push(`first frame ${(2 * Math.acos(d) * 180 / Math.PI).toFixed(0)}° from rest`)
+      }
+      lines.push(`    🎞 "${a.name}" root '${rb.name || "(unnamed)"}': ${parts.join(" · ")}`)
+    }
+  }
+  const names = new Map<string, number>()
+  for (const n of s.nodes) if (n.name && !n.isRoot) names.set(n.name, (names.get(n.name) ?? 0) + 1)
+  const dups = [ ...names ].filter(([ , c ]) => c > 1)
+  if (dups.length) lines.push(`  ⚠ ${dups.length} duplicate node name(s): ${dups.slice(0, 6).map(([ n, c ]) => `${n} ×${c}`).join(", ")}${dups.length > 6 ? "…" : ""} — clips bind by name to the first one`)
+  return lines.join("\n")
+}
+
+const mul = (a: number[], b: number[]): number[] => {
+  const o = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+
+const worldMatrix = (n: Node, cache: Map<Node, number[]>): number[] => {
+  const hit = cache.get(n)
+  if (hit) return hit
+  const local = n.getMatrix() as unknown as number[]
+  const parent = n.getParentNode()
+  const w = parent ? mul(worldMatrix(parent, cache), Array.from(local)) : Array.from(local)
+  cache.set(n, w)
+  return w
+}
+
+export const probeDocument = (doc: Document, label: string): string => {
+  const root = doc.getRoot()
+  const lines: string[] = []
+  const nodes = root.listNodes()
+  const skins = root.listSkins()
+  const jointSet = new Set(skins.flatMap((s) => s.listJoints()))
+  lines.push(`GLB ${label}`)
+  lines.push(`  nodes ${nodes.length} · joints ${jointSet.size} · meshes ${root.listMeshes().length} · skins ${skins.length}${skins.length ? ` (${skins.map((s) => s.listJoints().length + " joints").join(", ")})` : ""} · materials ${root.listMaterials().length} · textures ${root.listTextures().length}`)
+  for (const m of root.listMeshes()) for (const p of m.listPrimitives()) {
+    const pos = p.getAttribute("POSITION")
+    const idx = p.getIndices()
+    const min = pos?.getMin([]) ?? [ 0, 0, 0 ], max = pos?.getMax([]) ?? [ 0, 0, 0 ]
+    lines.push(`    ${m.getName() || "mesh"}: ${pos?.getCount() ?? 0} verts / ${idx ? idx.getCount() / 3 : "?"} tris · mat ${p.getMaterial()?.getName() || "-"} · ${p.getAttribute("JOINTS_0") ? "skinned" : "static"} · size ${max.map((v, i) => fmt(v - min[i])).join("×")}`)
+  }
+  lines.push(`  materials: ${root.listMaterials().map((m) => `${m.getName() || "?"}[${m.getAlphaMode()}${m.getBaseColorTexture() ? ",tex" : ""}${m.getNormalTexture() ? ",nrm" : ""}${m.getDoubleSided() ? ",2side" : ""} r${fmt(m.getRoughnessFactor(), 2)} m${fmt(m.getMetallicFactor(), 2)}]`).join(", ") || "none"}`)
+  lines.push(`  textures: ${root.listTextures().map((t) => `${t.getName() || "?"} ${t.getMimeType()} ${((t.getImage()?.byteLength ?? 0) / 1024).toFixed(0)}KB`).join(", ") || "none"}`)
+  // Rendered world size — the mesh rows above are LOCAL bounds, which say nothing about how big the
+  // asset lands in a scene once node transforms (or a skin's bind space) are applied.
+  const sc = measureScale(doc)
+  if (sc) lines.push(`  world size: ${sc.dims.map((d) => fmt(d, 3)).join("×")} m${sc.suspicious ? `  ⚠ implausible (${sc.label}) — doctor --fix-scale bakes ×${+sc.suggested.toPrecision(6)}` : ""}`)
+  const anims = root.listAnimations()
+  lines.push(`  clips ${anims.length}: ${anims.map((a) => {
+    let dur = 0
+    for (const s of a.listSamplers()) { const t = s.getInput(); if (t) dur = Math.max(dur, t.getMax([])[0] ?? 0) }
+    return `"${a.getName()}" ${fmt(dur)}s ${a.listChannels().length} channels`
+  }).join(", ") || "none"}`)
+  // Per-clip root summary: how far the skeleton root travels (root motion) and whether the clip's
+  // first frame agrees with the rest pose. A root that starts 90° from rest is the double-axis-turn
+  // symptom (a clip merged from an export with a different wrapper) — the rig plays lying down.
+  const rootJoints = [ ...jointSet ].filter((j) => j.getName() && (() => { const p = j.getParentNode(); return !p || !jointSet.has(p) })())
+  for (const a of anims) {
+    for (const rj of rootJoints) {
+      const tr = a.listChannels().find((c) => c.getTargetNode() === rj && c.getTargetPath() === "translation")
+      const rot = a.listChannels().find((c) => c.getTargetNode() === rj && c.getTargetPath() === "rotation")
+      if (!tr && !rot) continue
+      const parts: string[] = []
+      let bad = false
+      if (tr) {
+        const v = tr.getSampler()!.getOutput()!.getArray()!
+        const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+        for (let i = 0; i < v.length; i += 3) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], v[i + k]); hi[k] = Math.max(hi[k], v[i + k]) }
+        const rest = rj.getTranslation()
+        const start = Math.hypot(v[0] - rest[0], v[1] - rest[1], v[2] - rest[2])
+        parts.push(`moves ${fmt(hi[0] - lo[0])}×${fmt(hi[1] - lo[1])}×${fmt(hi[2] - lo[2])} m`)
+        if (start > 0.02) parts.push(`starts ${fmt(start)} m from rest`)
+        if (start > 0.5) bad = true
+      }
+      if (rot) {
+        const q = rot.getSampler()!.getOutput()!.getArray()!
+        const r = rj.getRotation()
+        const d = Math.min(1, Math.abs(q[0] * r[0] + q[1] * r[1] + q[2] * r[2] + q[3] * r[3]))
+        const deg = 2 * Math.acos(d) * 180 / Math.PI
+        parts.push(`first frame ${deg.toFixed(0)}° from rest`)
+        if (deg > 60) bad = true   // Mixamo hips routinely start 10–45° off a T-pose rest; the double axis turn is 90°
+      }
+      lines.push(`    🎞 "${a.getName()}" root '${rj.getName()}': ${parts.join(" · ")}${bad ? "  ⚠ clip starts far from the rest pose — a parent/axis mismatch with the model (clip from another export?)" : ""}`)
+    }
+  }
+  const dups = duplicateNodeNames(doc)
+  if (dups.length) {
+    const shadow = dups.filter((d) => d.shadowsJoint)
+    lines.push(`  ${shadow.length ? "⚠" : "ℹ"} ${dups.length} duplicate node name(s): ${dups.slice(0, 6).map((d) => `${d.name} ×${d.count}`).join(", ")}${dups.length > 6 ? "…" : ""}${shadow.length ? ` — ${shadow.length} shadow a skinned joint with a plain node: a name-bound Animator drives the copy and the mesh freezes (stray donor skeleton? use convert --merge-skins)` : " — clips and node paths address the first one"}`)
+  }
+  // bind sanity: for each skin, world(joint at rest) × IBM should agree across all joints (= the mesh's bind-space transform)
+  const cache = new Map<Node, number[]>()
+  for (const s of skins) {
+    const ibm = s.getInverseBindMatrices()
+    if (!ibm) continue
+    let ref: number[] | null = null
+    let maxDev = 0
+    const m = new Array(16).fill(0)
+    s.listJoints().forEach((j, i) => {
+      ibm.getElement(i, m)
+      const prod = mul(worldMatrix(j, cache), m.slice())
+      if (!ref) { ref = prod; return }
+      for (let k = 0; k < 16; k++) maxDev = Math.max(maxDev, Math.abs(prod[k] - ref[k]))
+    })
+    const r = ref as number[] | null
+    lines.push(`  skin "${s.getName() || "?"}": bind sanity — joints agree to ${maxDev.toExponential(1)}${r ? `, bind space ≈ ${Math.abs(r[0] - 1) < 1e-3 && Math.abs(r[5] - 1) < 1e-3 && Math.hypot(r[12], r[13], r[14]) < 1e-3 ? "identity" : `[scale ${fmt(Math.hypot(r[0], r[1], r[2]), 3)}, offset ${fmt(r[12])},${fmt(r[13])},${fmt(r[14])}]`}` : ""}${maxDev > 0.1 ? "  ⚠ rest pose ≠ bind pose by a lot — check units/axes/scale" : maxDev > 1e-3 ? "  (rest pose ≠ bind pose slightly — an asset property, harmless)" : ""}`)
+  }
+  const orphans = nodes.filter((n) => !n.getMesh() && !jointSet.has(n) && n.listChildren().length === 0)
+  if (orphans.length) lines.push(`  ${orphans.length} leaf node(s) with no mesh/joint role (e.g. ${orphans.slice(0, 4).map((n) => n.getName()).join(", ")})`)
+  return lines.join("\n")
+}
+
+export const probeFile = async (path: string): Promise<string> => {
+  const ext = extname(path).toLowerCase()
+  if (ext === ".fbx") return probeFbx(path)
+  if (ext === ".uasset") return (await import("./unreal/probe")).probeUnreal(path)
+  const doc = await makeIO().read(path)
+  return probeDocument(doc, path)
+}

package/src/props.ts

@@ -0,0 +1,137 @@
+// Props out of multi-variant files. Asset-store packs ship every LOD, colour set and arrangement of
+// a prop in ONE FBX (`Barrel_v1.FBX` = 15 meshes: Barrel_v1_LD1, _LD2, _S1, _rusty…); a game wants
+// one of them per GLB, sitting on the ground at the origin. `keepNodes` carves the named subtrees
+// out of a Document and re-origins what is left (X/Z centred on its footprint, Y = 0 at the lowest
+// vertex) so a `Model.load` lands the prop exactly where the node is; `splitDoc` does that for every
+// top-level node at once (one Document each). Static geometry only — skinned meshes keep their
+// skeleton's frame and are left where they are.
+
+import { Logger, type Document, type Node } from "@gltf-transform/core"
+import { cloneDocument, prune, unpartition } from "@gltf-transform/functions"
+
+/** prune() narrates what it removed through the document's logger — not news for a deliberate cut. */
+export const quiet = (doc: Document): Document => doc.setLogger(new Logger(Logger.Verbosity.SILENT))
+
+export type Vec3 = [number, number, number]
+export type NodeInfo = { name: string, depth: number, meshes: number, tris: number, size: Vec3, children: number }
+
+const IDENTITY = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+const mul = (a: number[], b: number[]): number[] => {
+  const o = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+const xf = (m: number[], x: number, y: number, z: number): Vec3 =>
+  [ m[0] * x + m[4] * y + m[8] * z + m[12], m[1] * x + m[5] * y + m[9] * z + m[13], m[2] * x + m[6] * y + m[10] * z + m[14] ]
+
+type Bounds = { lo: Vec3, hi: Vec3, tris: number, meshes: number }
+const emptyBounds = (): Bounds => ({ lo: [ Infinity, Infinity, Infinity ], hi: [ -Infinity, -Infinity, -Infinity ], tris: 0, meshes: 0 })
+const grow = (b: Bounds, p: Vec3): void => { for (let k = 0; k < 3; k++) { if (p[k] < b.lo[k]) b.lo[k] = p[k]; if (p[k] > b.hi[k]) b.hi[k] = p[k] } }
+
+/** World-space bounds of a subtree (node transforms applied; skinned primitives measured as-is). */
+export const subtreeBounds = (node: Node, parentWorld: number[] = IDENTITY, into: Bounds = emptyBounds()): Bounds => {
+  const world = mul(parentWorld, Array.from(node.getMatrix()))
+  const mesh = node.getMesh()
+  if (mesh) {
+    into.meshes++
+    for (const prim of mesh.listPrimitives()) {
+      const pos = prim.getAttribute("POSITION")
+      if (!pos) continue
+      const idx = prim.getIndices()
+      into.tris += idx ? idx.getCount() / 3 : pos.getCount() / 3
+      const a = pos.getArray()!
+      for (let i = 0; i < a.length; i += 3) grow(into, xf(world, a[i], a[i + 1], a[i + 2]))
+    }
+  }
+  for (const c of node.listChildren()) subtreeBounds(c, world, into)
+  return into
+}
+
+const sizeOf = (b: Bounds): Vec3 => (b.lo[0] === Infinity ? [ 0, 0, 0 ] : [ b.hi[0] - b.lo[0], b.hi[1] - b.lo[1], b.hi[2] - b.lo[2] ])
+
+/** The scene's nodes down to `depth` levels with mesh counts and world sizes — what `--keep` takes. */
+export const listNodes = (doc: Document, depth = 1): NodeInfo[] => {
+  const out: NodeInfo[] = []
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]
+  if (!scene) return out
+  const walk = (n: Node, d: number, parentWorld: number[]): void => {
+    const b = subtreeBounds(n, parentWorld)
+    out.push({ name: n.getName(), depth: d, meshes: b.meshes, tris: b.tris, size: sizeOf(b), children: n.listChildren().length })
+    if (d + 1 < depth) {
+      const world = mul(parentWorld, Array.from(n.getMatrix()))
+      for (const c of n.listChildren()) walk(c, d + 1, world)
+    }
+  }
+  for (const c of scene.listChildren()) walk(c, 0, IDENTITY)
+  return out
+}
+
+export type KeepResult = { kept: string[], missing: string[], size: Vec3, offset: Vec3 }
+
+/**
+ * Keep only the named nodes (any depth; their ancestors stay as the path to them, their descendants
+ * stay with them), drop everything else, then re-origin: the kept geometry's footprint centre goes to
+ * X/Z = 0 and its lowest point to Y = 0 (`ground: false` keeps the file's own placement).
+ */
+export const keepNodes = async (doc: Document, names: string[], opts: { ground?: boolean } = {}): Promise<KeepResult> => {
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]
+  if (!scene) throw new Error("the file has no scene")
+  const wanted = new Set(names)
+  const found = new Set<string>()
+  const keep = new Set<Node>()
+  // a node survives if it is wanted, sits under a wanted node, or leads to one
+  const mark = (n: Node, underKept: boolean): boolean => {
+    const self = wanted.has(n.getName())
+    if (self) found.add(n.getName())
+    let leads = false
+    for (const c of n.listChildren()) if (mark(c, underKept || self)) leads = true
+    const survives = self || underKept || leads
+    if (survives) keep.add(n)
+    return survives
+  }
+  for (const c of scene.listChildren()) mark(c, false)
+  const doomed: Node[] = []
+  scene.traverse((n) => { if (!keep.has(n)) doomed.push(n) })
+  // children first: disposing a parent detaches its subtree, which is fine, but keeps the order obvious
+  for (const n of doomed.reverse()) n.dispose()
+  const missing = names.filter((n) => !found.has(n))
+
+  const b = emptyBounds()
+  for (const c of scene.listChildren()) subtreeBounds(c, IDENTITY, b)
+  const offset: Vec3 = [ 0, 0, 0 ]
+  if (opts.ground !== false && b.lo[0] !== Infinity) {
+    offset[0] = -(b.lo[0] + b.hi[0]) / 2; offset[1] = -b.lo[1]; offset[2] = -(b.lo[2] + b.hi[2]) / 2
+    for (const c of scene.listChildren()) {
+      const t = c.getTranslation()
+      c.setTranslation([ t[0] + offset[0], t[1] + offset[1], t[2] + offset[2] ])
+    }
+  }
+  await quiet(doc).transform(prune(), unpartition())
+  return { kept: [ ...found ], missing, size: sizeOf(b), offset }
+}
+
+/** One Document per top-level node, each re-origined (see `keepNodes`). Names are de-duplicated with ` (2)`. */
+export const splitDoc = async (doc: Document, opts: { ground?: boolean } = {}): Promise<{ name: string, doc: Document, size: Vec3 }[]> => {
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]
+  if (!scene) return []
+  const out: { name: string, doc: Document, size: Vec3 }[] = []
+  const seen = new Map<string, number>()
+  for (const top of scene.listChildren()) {
+    const name = top.getName() || "node"
+    const n = (seen.get(name) ?? 0) + 1
+    seen.set(name, n)
+    // keepNodes picks by NAME — a duplicate top-level name gets its siblings too; give it a unique one first
+    const unique = n > 1 ? `${name} (${n})` : name
+    const copy = cloneDocument(doc)
+    const copyScene = copy.getRoot().getDefaultScene() ?? copy.getRoot().listScenes()[0]
+    const twin = copyScene.listChildren()[scene.listChildren().indexOf(top)]
+    twin.setName(`__split__${unique}`)
+    const r = await keepNodes(copy, [ `__split__${unique}` ], opts)
+    twin.setName(name)
+    out.push({ name: unique, doc: copy, size: r.size })
+  }
+  return out
+}
+
+/** File-system friendly stem for a node name (`Barrel_v1 (2)` → `Barrel_v1-2`). */
+export const fileStem = (name: string): string => name.replace(/\s*\((\d+)\)$/, "-$1").replace(/[^\w.-]+/g, "_").replace(/^_+|_+$/g, "") || "node"

package/src/retarget/automap.ts

@@ -0,0 +1,276 @@
+// Automatic bone map for a quadruped retarget — from SKELETON SHAPE, not names.
+//
+// Bone names are unreliable across rigs (`backleg0`, `Knee_L`, `actor:skin_backKnee_L`, `joint17`),
+// but every quadruped skeleton has the same shape: a centreline from the tail through the pelvis
+// and chest to the head, four lateral chains hanging down to the ground, ears/jaw/eyes branching off
+// the head. `classify` reads that structure off the bind pose of one rig — root, spine, neck, head,
+// tail, legs (side + end), ears, jaw — and `autoMap` pairs the two structures chain by chain,
+// matching bones within a chain by normalized arc length (a 6-bone spine against a 3-bone spine maps
+// its ends exactly and the middle to the nearest donor bone; leftover target bones stay unmapped and
+// become bridges in the retarget). The result is a starting map the user reads and corrects, with a
+// report of what was and was not recognised — never a silent guess.
+import type { Rig, Vec3 } from './rig'
+import type { BoneMap } from './retarget'
+
+export interface LegInfo { side: 'L' | 'R'; end: 'front' | 'back'; chain: number[] }   // hip → … → ball of foot
+
+export interface Skeleton {
+  root: number
+  forward: Vec3                  // horizontal unit vector, tail → head
+  lateral: Vec3                  // unit vector to the rig's LEFT (+x when facing +z)
+  size: number                   // largest bounding extent
+  spine: number[]                // root … chest (inclusive both ends; length 1 when root == chest)
+  chest: number
+  neck: number[]                 // first bone after chest … head (inclusive)
+  head: number | null
+  jaw: number | null
+  ears: [number, number] | null  // [left, right]
+  tail: number[]                 // first tail bone … tip
+  legs: LegInfo[]
+  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])
+
+/** Structure of one rig from its bind pose. Works on skinned joints only. */
+export const classify = (rig: Rig): Skeleton => {
+  const notes: string[] = []
+  const skinned = (i: number): boolean => rig.bind.fromSkin[i]
+  const pos = rig.bind.worldPos
+  const children: number[][] = rig.names.map(() => [])
+  rig.parents.forEach((p, i) => { if (p >= 0) children[p].push(i) })
+  const skids = (i: number): number[] => {
+    // Skinned descendants reachable without crossing another skinned joint.
+    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 }
+
+  // Root: the skinned joint with no skinned ancestor (the first one in topological order).
+  const root = rig.order.find((i) => skinned(i) && sparent(i) < 0)
+  if (root === undefined) throw new Error(`${rig.label}: no skinned joints`)
+  const joints = rig.order.filter(skinned)
+
+  // Bounds and body frame. Forward = the principal horizontal axis, pointing to the end where the
+  // high joints are (head, ears, neck); lateral = up × forward.
+  let lo: Vec3 = [ Infinity, Infinity, Infinity ], hi: Vec3 = [ -Infinity, -Infinity, -Infinity ]
+  for (const i of joints) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], pos[i][k]); hi[k] = Math.max(hi[k], pos[i][k]) }
+  const size = Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) || 1
+  const height = hi[1] - lo[1] || size
+  const cx = joints.reduce((a, i) => a + pos[i][0], 0) / joints.length, cz = joints.reduce((a, i) => a + pos[i][2], 0) / joints.length
+  let sxx = 0, sxz = 0, szz = 0
+  for (const i of joints) { const x = pos[i][0] - cx, z = pos[i][2] - cz; sxx += x * x; sxz += x * z; szz += z * z }
+  // Largest-eigenvector of the 2×2 covariance [[sxx, sxz], [sxz, szz]].
+  const theta = 0.5 * Math.atan2(2 * sxz, sxx - szz)
+  let forward: Vec3 = [ Math.cos(theta), 0, Math.sin(theta) ]
+  const top = [ ...joints ].sort((a, b) => pos[b][1] - pos[a][1]).slice(0, Math.max(1, Math.ceil(joints.length * 0.1)))
+  const topProj = top.reduce((a, i) => a + dot(sub(pos[i], [ cx, 0, cz ]), forward), 0) / top.length
+  if (topProj < 0) forward = [ -forward[0], 0, -forward[2] ]
+  const lateral: Vec3 = [ forward[2], 0, -forward[0] ]   // up × forward = (0,1,0) × (fx,0,fz) = (fz, 0, -fx)
+  const fwd = (i: number): number => dot(sub(pos[i], pos[root]), forward)
+  const lat = (i: number): number => dot(sub(pos[i], pos[root]), lateral)
+  const centre = (i: number): boolean => Math.abs(lat(i)) < 0.03 * size
+
+  // Legs: chains that hang down from the body to the ground, off the centreline.
+  const legs: LegInfo[] = []
+  {
+    const leaves = joints.filter((i) => skids(i).length === 0)
+    const feet = leaves.filter((i) => pos[i][1] - lo[1] < 0.2 * height && Math.abs(lat(i)) > 0.03 * size)
+    const taken = new Set<number>()
+    for (const f of feet) {
+      // Up to the first centreline joint (the attach point on the body): that is the leg's extent.
+      const chain: number[] = []
+      let b = f
+      while (b >= 0 && !centre(b)) { chain.unshift(b); b = sparent(b) }
+      if (b < 0 || chain.length < 3) continue
+      if (chain.some((i) => taken.has(i))) continue   // toes of a leg already found
+      // Ball of the foot: the first joint from the hip at the chain's lowest level.
+      const lowest = Math.min(...chain.map((i) => pos[i][1]))
+      const ball = chain.findIndex((i) => pos[i][1] - lowest < 0.04 * height)
+      const leg = chain.slice(0, Math.max(2, ball) + 1)
+      for (const i of leg) taken.add(i)
+      legs.push({ side: lat(leg[0]) > 0 ? 'L' : 'R', end: 'back', chain: leg })
+    }
+    // Front/back by where the leg attaches along the body. Two or four legs expected.
+    legs.sort((a, b) => fwd(a.chain[0]) - fwd(b.chain[0]))
+    if (legs.length >= 4) { legs[legs.length - 1].end = 'front'; legs[legs.length - 2].end = 'front' }
+    else if (legs.length === 3) { legs[2].end = 'front'; notes.push('three legs found — check the map') }
+    else if (legs.length === 2) {
+      // A biped, or a quadruped whose other pair was not recognised.
+      const mid = (fwd(legs[0].chain[0]) + fwd(legs[1].chain[0])) / 2
+      const bodyMid = (Math.min(...joints.map(fwd)) + Math.max(...joints.map(fwd))) / 2
+      if (mid > bodyMid) for (const l of legs) l.end = 'front'
+      notes.push('two legs found')
+    } else if (!legs.length) notes.push('no legs recognised')
+  }
+
+  // Chest: the lowest common ancestor of the front legs (or of all legs when there is no front pair).
+  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 => {
+    if (!list.length) return root
+    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] ?? root
+  }
+  const front = legs.filter((l) => l.end === 'front')
+  let chest = front.length ? lca(front.map((l) => sparent(l.chain[0]))) : root
+  // The hip attach of the back legs should be at/near the root; if the root sits far behind the
+  // pelvis (a long "root bone"), the spine still starts at the root.
+  const pathUp = (from: number, to: number): number[] => { const out: number[] = []; for (let a = from; a >= 0; a = sparent(a)) { out.unshift(a); if (a === to) break } return out }
+  if (!ancestors(chest).includes(root)) chest = root
+  const spine = pathUp(chest, root)
+  if (spine[0] !== root) { notes.push('chest is not below the root — spine left as root only'); spine.splice(0, spine.length, root) }
+
+  // Neck/head: from the chest, the centreline path that keeps going forward. The head is the last
+  // joint on it that has side branches (ears/eyes/jaw); otherwise the path's end.
+  const legJoints = new Set(legs.flatMap((l) => l.chain))
+  const tail: number[] = []
+  const neck: number[] = []
+  let head: number | null = null, jaw: number | null = null, ears: [number, number] | null = null
+  {
+    const frontKids = (i: number): number[] => skids(i).filter((c) => !legJoints.has(c) && centre(c) && fwd(c) > fwd(i) - 0.01 * size)
+    let cur = chest
+    const path: number[] = []
+    for (let guard = 0; guard < 64; guard++) {
+      const ks = frontKids(cur).sort((a, b) => fwd(b) - fwd(a))
+      if (!ks.length) break
+      cur = ks[0]; path.push(cur)
+    }
+    if (path.length) {
+      // Head: the furthest joint on the path that branches; jaw/ears hang off it.
+      let h = path.length - 1
+      while (h > 0 && skids(path[h]).length < 2) h--
+      if (skids(path[h]).length < 2) h = path.length - 1
+      head = path[h]
+      neck.push(...path.slice(0, h + 1))
+      const kids = skids(head)
+      const pair = kids.filter((c) => Math.abs(lat(c)) > 0.02 * size)
+      const left = pair.filter((c) => lat(c) > 0).sort((a, b) => pos[b][1] - pos[a][1]), right = pair.filter((c) => lat(c) < 0).sort((a, b) => pos[b][1] - pos[a][1])
+      if (left.length && right.length) ears = [ left[0], right[0] ]   // the highest lateral pair: ears
+      const centreKids = kids.filter((c) => !pair.includes(c))
+      // Jaw (or snout): a centreline child heading forward and DOWN, with its own chain preferably.
+      const j = centreKids.filter((c) => pos[c][1] < pos[head!][1] - 0.01 * size && fwd(c) > fwd(head!)).sort((a, b) => skids(b).length - skids(a).length)[0]
+      if (j !== undefined) jaw = j
+    } else notes.push('no neck/head found forward of the chest')
+
+    // Tail: from the root (or a joint right next to it), the centreline path heading backward. The
+    // first tail bone often sits ON the root, so a candidate counts by where its subtree goes.
+    const subtreeFwd = (i: number): number => { let s = 0, c = 0; const q = [ i ]; while (q.length) { const j = q.shift()!; s += fwd(j); c++; q.push(...skids(j)) } return s / c }
+    const backKids = (i: number): number[] => skids(i).filter((c) => !legJoints.has(c) && !spine.includes(c) && !neck.includes(c) && centre(c) && subtreeFwd(c) < fwd(i) - 0.01 * size)
+    let start = root
+    let ks = backKids(start)
+    if (!ks.length && spine.length > 1) { start = spine[1]; ks = backKids(start) }
+    cur = start
+    for (let guard = 0; guard < 64 && ks.length; guard++) {
+      cur = ks.sort((a, b) => fwd(a) - fwd(b))[0]
+      tail.push(cur)
+      ks = backKids(cur)
+    }
+  }
+
+  return { root, forward, lateral, size, spine, chest, neck, head, jaw, ears, tail, legs, notes }
+}
+
+export interface AutoMapResult {
+  map: BoneMap
+  root: string
+  legs: string[]
+  target: Skeleton
+  donor: Skeleton
+  lines: string[]            // human-readable pairing report
+}
+
+/**
+ * Map two classified skeletons onto each other. Chains pair by role; bones inside a chain pair by
+ * normalized arc length, ends exact, each donor bone used at most once per chain (extra target bones
+ * are left out → bridges).
+ */
+export const autoMap = (target: Rig, donor: Rig): AutoMapResult => {
+  const T = classify(target), D = classify(donor)
+  const map: BoneMap = {}
+  const lines: string[] = []
+  const name = (rig: Rig, i: number): string => rig.names[i]
+
+  const arc = (rig: Rig, chain: number[], anchor: number): number[] => {
+    // Cumulative length from the chain's anchor joint (the joint it hangs off) through each bone,
+    // normalized so the chain's end is 1. A one-bone chain is therefore [1]: it IS the end.
+    const out: number[] = []
+    let acc = 0, prev = anchor
+    for (const c of chain) { acc += len(sub(rig.bind.worldPos[c], rig.bind.worldPos[prev])); out.push(acc); prev = c }
+    const total = acc || 1
+    return out.map((v) => v / total)
+  }
+  // Name hints: bones whose names share an anatomical token (knee/Knee_L, backAnkle/Ankle) pair for
+  // less — names are unreliable across rigs, but when they do agree they beat arc length.
+  const TOKENS = [ 'scapula', 'shoulder', 'elbow', 'wrist', 'finger', 'hand', 'hip', 'thigh', 'knee', 'shin', 'calf', 'ankle', 'toe', 'foot', 'spine', 'chest', 'neck', 'head', 'jaw', 'ear', 'eye', 'tail', 'rump' ]
+  // "frontHip/frontKnee/frontAnkle/frontToes/frontRump" is one rig family's name for the front leg:
+  // translate to the forelimb words so they meet Shoulder/Elbow/Wrist/Fingers/Scapula.
+  const FRONT: Record<string, string> = { hip: 'shoulder', thigh: 'shoulder', knee: 'elbow', shin: 'wrist', ankle: 'wrist', toe: 'finger', foot: 'hand', rump: 'scapula' }
+  const tokensOf = (s: string): Set<string> => {
+    const l = s.toLowerCase()
+    const found = TOKENS.filter((t) => l.includes(t))
+    return new Set(/front|fore/.test(l) ? found.map((t) => FRONT[t] ?? t) : found)
+  }
+  const nameBonus = (t: number, d: number): number => {
+    const a = tokensOf(name(target, t)), b = tokensOf(name(donor, d))
+    for (const x of a) if (b.has(x)) return 0.2
+    return 0
+  }
+  const pairChain = (role: string, tc: number[], dc: number[], tAnchor: number, dAnchor: number): void => {
+    if (!tc.length || !dc.length) { if (tc.length || dc.length) lines.push(`  ${role}: ${tc.length ? 'donor' : 'target'} has none — skipped`); return }
+    const tu = arc(target, tc, tAnchor), du = arc(donor, dc, dAnchor)
+    // Monotone alignment of the two chains (sequence alignment on arc length): pairing costs the
+    // arc-length gap, skipping a bone on either side costs GAP, the two ENDS always pair (foot,
+    // head, tail tip). Extra target bones are left out and become bridges in the retarget.
+    const GAP = 0.12
+    const cost = (k: number, j: number): number => Math.abs(tu[k - 1] - du[j - 1]) - nameBonus(tc[k - 1], dc[j - 1])
+    const nt = tc.length - 1, nd = dc.length - 1   // ends handled separately
+    const Dp: number[][] = Array.from({ length: nt + 1 }, () => new Array(nd + 1).fill(0))
+    for (let k = 1; k <= nt; k++) Dp[k][0] = k * GAP
+    for (let j = 1; j <= nd; j++) Dp[0][j] = j * GAP
+    for (let k = 1; k <= nt; k++) for (let j = 1; j <= nd; j++) {
+      Dp[k][j] = Math.min(Dp[k - 1][j - 1] + cost(k, j), Dp[k - 1][j] + GAP, Dp[k][j - 1] + GAP)
+    }
+    const pairs: [number, number][] = []
+    for (let k = nt, j = nd; k > 0 && j > 0;) {
+      if (Math.abs(Dp[k][j] - (Dp[k - 1][j - 1] + cost(k, j))) < 1e-12) { pairs.unshift([ tc[k - 1], dc[j - 1] ]); k--; j-- }
+      else if (Dp[k][j] === Dp[k - 1][j] + GAP) k--
+      else j--
+    }
+    pairs.push([ tc[tc.length - 1], dc[dc.length - 1] ])
+    for (const [ t, d ] of pairs) map[name(target, t)] = name(donor, d)
+    lines.push(`  ${role}: ${pairs.map(([ t, d ]) => `${name(target, t)}←${name(donor, d)}`).join(', ')}${tc.length > pairs.length ? `  (+${tc.length - pairs.length} target bone(s) bridged)` : ''}`)
+  }
+  const sparentOf = (rig: Rig) => (i: number): number => { let p = rig.parents[i]; while (p >= 0 && !rig.bind.fromSkin[p]) p = rig.parents[p]; return p }
+  const tsp = sparentOf(target), dsp = sparentOf(donor)
+
+  // The root pairs with the root; the rest of the spine hangs off it.
+  map[name(target, T.root)] = name(donor, D.root)
+  lines.push(`  root: ${name(target, T.root)}←${name(donor, D.root)}`)
+  pairChain('spine', T.spine.slice(1), D.spine.slice(1), T.root, D.root)
+  pairChain('neck/head', T.neck, D.neck, T.chest, D.chest)
+  if (T.jaw !== null && D.jaw !== null) { map[name(target, T.jaw)] = name(donor, D.jaw); lines.push(`  jaw: ${name(target, T.jaw)}←${name(donor, D.jaw)}`) }
+  if (T.ears && D.ears) { map[name(target, T.ears[0])] = name(donor, D.ears[0]); map[name(target, T.ears[1])] = name(donor, D.ears[1]); lines.push(`  ears: ${name(target, T.ears[0])}←${name(donor, D.ears[0])}, ${name(target, T.ears[1])}←${name(donor, D.ears[1])}`) }
+  if (T.tail.length && D.tail.length) pairChain('tail', T.tail, D.tail, tsp(T.tail[0]), dsp(D.tail[0]))
+  else if (T.tail.length || D.tail.length) lines.push(`  tail: ${T.tail.length ? 'donor' : 'target'} has none — skipped`)
+  const legNames: string[] = []
+  for (const tl of T.legs) {
+    const dl = D.legs.find((l) => l.side === tl.side && l.end === tl.end)
+    if (!dl) { lines.push(`  leg ${tl.end}-${tl.side}: donor has none — skipped`); continue }
+    pairChain(`leg ${tl.end}-${tl.side}`, tl.chain, dl.chain, tsp(tl.chain[0]), dsp(dl.chain[0]))
+    legNames.push(name(target, tl.chain[tl.chain.length - 1]))
+  }
+  for (const n of [ ...T.notes.map((s) => `target: ${s}`), ...D.notes.map((s) => `donor: ${s}`) ]) lines.push(`  ⚠ ${n}`)
+  return { map, root: name(target, T.root), legs: legNames, target: T, donor: D, lines }
+}
+
+/** One-line summary of a classified skeleton, for the CLI. */
+export const describeSkeleton = (rig: Rig, s: Skeleton): string => {
+  const n = (i: number | null): string => (i === null ? '-' : rig.names[i])
+  return `root ${n(s.root)} · spine ${s.spine.length} · neck ${s.neck.length} · head ${n(s.head)} · jaw ${n(s.jaw)} · ears ${s.ears ? `${n(s.ears[0])}/${n(s.ears[1])}` : '-'} · tail ${s.tail.length} · legs ${s.legs.map((l) => `${l.end[0]}${l.side}:${l.chain.length}`).join(' ')} · facing [${s.forward.map((x) => x.toFixed(2)).join(',')}]`
+}
+

package/src/retarget/ghost.ts

@@ -0,0 +1,23 @@
+// A rig's "ghost": the skeleton alone, posed by ONE of its clips — what a viewport overlays on a
+// retargeted character to compare the transfer against the original. Meshes, skins, materials
+// and the other clips go; the node tree (names = bone names) and the chosen animation stay.
+import type { Document } from '@gltf-transform/core'
+import { prune } from '@gltf-transform/functions'
+
+export const ghostSkeleton = async (doc: Document, clip: number): Promise<Document> => {
+  const root = doc.getRoot()
+  for (const n of root.listNodes()) { n.setMesh(null); n.setSkin(null) }
+  for (const m of root.listMeshes()) { for (const p of m.listPrimitives()) p.dispose(); m.dispose() }
+  for (const s of root.listSkins()) s.dispose()
+  root.listAnimations().forEach((a, i) => { if (i !== clip) a.dispose() })
+  await doc.transform(prune())
+  // One degenerate triangle at the origin: glTF viewers built around meshes (OGL's GLTFLoader) refuse
+  // a file with none, and a mesh-less load leaves the node tree without a scene graph to animate.
+  const pos = doc.createAccessor('ghost_pos').setType('VEC3').setArray(new Float32Array(9))
+  const prim = doc.createPrimitive().setAttribute('POSITION', pos)
+  const mesh = doc.createMesh('ghost_mesh').addPrimitive(prim)
+  const node = doc.createNode('ghost_mesh').setMesh(mesh)
+  const scene = root.listScenes()[0] ?? doc.createScene('ghost')
+  scene.addChild(node)
+  return doc
+}