lecodes-assets 0.1.2 → 0.2.1

package/src/filmstrip.ts

@@ -0,0 +1,263 @@
+// Software-skinned mesh filmstrip — the real silhouette of a GLB clip with no browser, no GPU, no
+// engine and no native dependency. Evaluates the animation, skins the vertices on the CPU, flat-
+// shades and z-buffers the triangles into one PNG strip (own encoder). This is the sanity check for
+// `convert --clips`, `retarget` and `--merge-skins`: "does the character actually walk upright" is
+// not a question a numeric check answers. `probe --filmstrip` and tools/filmstrip.ts both call it.
+
+import { type Document } from "@gltf-transform/core"
+import { rigFromDocument, qnorm, qslerp, type Pose, type Quat, type Vec3 } from "./retarget/rig"
+import { encodePng } from "./textures/resolveImage"
+
+export type FilmstripView = "side" | "front" | "top" | "threequarter" | "lowfront"
+export type FilmstripOptions = {
+  /** clip name; null/undefined = the rest pose (one frame) */
+  clip?: string | null
+  frames?: number
+  view?: FilmstripView
+  /** pixels per frame (default 240) */
+  cell?: number
+  /** overlay the skeleton (joints + bones) */
+  bones?: boolean
+  /** the rest frame shows the BIND pose (from the IBMs) rather than the node TRS */
+  bind?: boolean
+  /** reference frames from other documents, drawn first at the same projection */
+  refs?: { doc: Document, clip?: string | null, time?: number, label?: string }[]
+  /** RGB of the mesh */
+  color?: [number, number, number]
+}
+export type FilmstripResult = { png: Uint8Array, width: number, height: number, label: string, duration: number }
+
+const matMul = (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 compose = (t: Vec3, q: Quat, s: Vec3): number[] => {
+  const [ x, y, z, w ] = q, x2 = x + x, y2 = y + y, z2 = z + z
+  const xx = x * x2, xy = x * y2, xz = x * z2, yy = y * y2, yz = y * z2, zz = z * z2, wx = w * x2, wy = w * y2, wz = w * z2
+  return [ (1 - (yy + zz)) * s[0], (xy + wz) * s[0], (xz - wy) * s[0], 0, (xy - wz) * s[1], (1 - (xx + zz)) * s[1], (yz + wx) * s[1], 0,
+           (xz + wy) * s[2], (yz - wx) * s[2], (1 - (xx + yy)) * s[2], 0, t[0], t[1], t[2], 1 ]
+}
+
+type Frame = { pos: Float32Array, tris: ArrayLike<number> }[]
+type Bone = { a: Vec3, b: Vec3 }
+
+/** Everything needed to pose + skin one document: rig, channels, skinned mesh nodes. */
+const prepare = (doc: Document, clipName: string | null | undefined, label: string) => {
+  const rig: any = rigFromDocument(doc, label)
+  const anim = clipName ? doc.getRoot().listAnimations().find((a) => a.getName() === clipName) ?? null : null
+  if (clipName && !anim) throw new Error(`no clip "${clipName}" in ${label} (has: ${doc.getRoot().listAnimations().map((a) => a.getName()).join(", ") || "none"})`)
+  const chans = (anim?.listChannels() ?? []).map((ch) => ({
+    node: rig.nodes.indexOf(ch.getTargetNode()!), path: ch.getTargetPath(),
+    times: ch.getSampler()!.getInput()!.getArray()!, vals: ch.getSampler()!.getOutput()!.getArray()!,
+  })).filter((c) => c.node >= 0)
+  let duration = 0
+  for (const c of chans) duration = Math.max(duration, c.times[c.times.length - 1])
+  const poseAt = (t: number, base: Pose): Pose => {
+    const p: Pose = { t: base.t.map((v: Vec3) => [ ...v ] as Vec3), r: base.r.map((v: Quat) => [ ...v ] as Quat), s: base.s.map((v: Vec3) => [ ...v ] as Vec3) }
+    for (const c of chans) {
+      const n = c.path === "rotation" ? 4 : 3, last = c.times.length - 1
+      let i = 0; while (i < last && c.times[i + 1] < t) i++
+      const u = i < last ? Math.max(0, Math.min(1, (t - c.times[i]) / (c.times[i + 1] - c.times[i] || 1))) : 0
+      const a = Array.from(c.vals.slice(i * n, i * n + n)) as number[]
+      const b = i < last ? Array.from(c.vals.slice((i + 1) * n, (i + 1) * n + n)) as number[] : a
+      const v = n === 4 ? qslerp(a as Quat, b as Quat, u) : a.map((x, k) => x + (b[k] - x) * u)
+      if (c.path === "rotation") p.r[c.node] = qnorm(v as Quat)
+      else if (c.path === "translation") p.t[c.node] = v as Vec3
+      else p.s[c.node] = v as Vec3
+    }
+    return p
+  }
+  const worldMats = (pose: Pose): number[][] => {
+    const out: number[][] = new Array(rig.names.length)
+    for (const i of rig.order) {
+      const local = compose(pose.t[i], pose.r[i], pose.s[i])
+      out[i] = rig.parents[i] >= 0 ? matMul(out[rig.parents[i]], local) : local
+    }
+    return out
+  }
+  // every skinned mesh node (a modular character has several); static meshes go through their node matrix
+  const skinnedNodes = rig.nodes.filter((n: any) => n.getMesh() && n.getSkin())
+  const staticNodes = rig.nodes.filter((n: any) => n.getMesh() && !n.getSkin())
+  if (skinnedNodes.length === 0 && staticNodes.length === 0) throw new Error(`${label}: no mesh to draw`)
+  const skinned = (pose: Pose): Frame => {
+    const wm = worldMats(pose)
+    const out: Frame = []
+    for (const meshNode of skinnedNodes) {
+      const skin = meshNode.getSkin(), ibmAcc = skin.getInverseBindMatrices()
+      const jointIdx = skin.listJoints().map((j: any) => rig.nodes.indexOf(j))
+      const mats = jointIdx.map((n: number, j: number) => matMul(wm[n], ibmAcc.getElement(j, [])))
+      for (const prim of meshNode.getMesh().listPrimitives()) {
+        const P = prim.getAttribute("POSITION")?.getArray(), J = prim.getAttribute("JOINTS_0")?.getArray(), W = prim.getAttribute("WEIGHTS_0")?.getArray()
+        if (!P || !J || !W) continue
+        const count = prim.getAttribute("POSITION").getCount()
+        const o = new Float32Array(count * 3)
+        for (let v = 0; v < count; v++) {
+          let x = 0, y = 0, z = 0
+          for (let k = 0; k < 4; k++) {
+            const w = W[v * 4 + k]
+            if (!w) continue
+            const m = mats[J[v * 4 + k]]
+            if (!m) continue
+            const px = P[v * 3], py = P[v * 3 + 1], pz = P[v * 3 + 2]
+            x += w * (m[0] * px + m[4] * py + m[8] * pz + m[12]); y += w * (m[1] * px + m[5] * py + m[9] * pz + m[13]); z += w * (m[2] * px + m[6] * py + m[10] * pz + m[14])
+          }
+          o[v * 3] = x; o[v * 3 + 1] = y; o[v * 3 + 2] = z
+        }
+        out.push({ pos: o, tris: prim.getIndices()?.getArray() ?? seq(count) })
+      }
+    }
+    for (const meshNode of staticNodes) {
+      const m = wm[rig.nodes.indexOf(meshNode)]
+      for (const prim of meshNode.getMesh().listPrimitives()) {
+        const P = prim.getAttribute("POSITION")?.getArray()
+        if (!P) continue
+        const count = prim.getAttribute("POSITION").getCount(), o = new Float32Array(count * 3)
+        for (let v = 0; v < count; v++) {
+          const px = P[v * 3], py = P[v * 3 + 1], pz = P[v * 3 + 2]
+          o[v * 3] = m[0] * px + m[4] * py + m[8] * pz + m[12]; o[v * 3 + 1] = m[1] * px + m[5] * py + m[9] * pz + m[13]; o[v * 3 + 2] = m[2] * px + m[6] * py + m[10] * pz + m[14]
+        }
+        out.push({ pos: o, tris: prim.getIndices()?.getArray() ?? seq(count) })
+      }
+    }
+    return out
+  }
+  const bonesOf = (pose: Pose): Bone[] => {
+    const wm = worldMats(pose)
+    const out: Bone[] = []
+    for (let i = 0; i < rig.names.length; i++) {
+      const p = rig.parents[i]
+      if (p < 0 || !rig.bind.fromSkin[i]) continue
+      out.push({ a: [ wm[p][12], wm[p][13], wm[p][14] ], b: [ wm[i][12], wm[i][13], wm[i][14] ] })
+    }
+    return out
+  }
+  return { rig, anim, duration, poseAt, skinned, bonesOf }
+}
+const seq = (n: number): Uint32Array => { const a = new Uint32Array(n); for (let i = 0; i < n; i++) a[i] = i; return a }
+
+// 3×5 glyphs for the time labels ("0.25s") and the header — enough without a font library.
+const FONT: Record<string, number[]> = {
+  "0": [ 7, 5, 5, 5, 7 ], "1": [ 2, 6, 2, 2, 7 ], "2": [ 7, 1, 7, 4, 7 ], "3": [ 7, 1, 7, 1, 7 ], "4": [ 5, 5, 7, 1, 1 ],
+  "5": [ 7, 4, 7, 1, 7 ], "6": [ 7, 4, 7, 5, 7 ], "7": [ 7, 1, 1, 1, 1 ], "8": [ 7, 5, 7, 5, 7 ], "9": [ 7, 5, 7, 1, 7 ],
+  ".": [ 0, 0, 0, 0, 2 ], "s": [ 0, 3, 4, 2, 6 ], " ": [ 0, 0, 0, 0, 0 ], "-": [ 0, 0, 7, 0, 0 ], ":": [ 0, 2, 0, 2, 0 ], "@": [ 7, 5, 7, 4, 7 ],
+}
+const drawText = (img: Uint8Array, W: number, x: number, y: number, text: string, rgb: [number, number, number], scale = 2): void => {
+  for (const ch of text.toLowerCase()) {
+    const g = FONT[ch] ?? FONT[" "]
+    for (let r = 0; r < 5; r++) for (let c = 0; c < 3; c++) if (g[r] & (4 >> c)) {
+      for (let sy = 0; sy < scale; sy++) for (let sx = 0; sx < scale; sx++) {
+        const px = x + c * scale + sx, py = y + r * scale + sy
+        const i = (py * W + px) * 4
+        if (i >= 0 && i + 3 < img.length) { img[i] = rgb[0]; img[i + 1] = rgb[1]; img[i + 2] = rgb[2] }
+      }
+    }
+    x += 4 * scale
+  }
+}
+const drawLine = (img: Uint8Array, W: number, H: number, x0: number, y0: number, x1: number, y1: number, rgb: [number, number, number]): void => {
+  const n = Math.max(1, Math.ceil(Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0))))
+  for (let i = 0; i <= n; i++) {
+    const x = Math.round(x0 + (x1 - x0) * i / n), y = Math.round(y0 + (y1 - y0) * i / n)
+    if (x < 0 || y < 0 || x >= W || y >= H) continue
+    const o = (y * W + x) * 4
+    img[o] = rgb[0]; img[o + 1] = rgb[1]; img[o + 2] = rgb[2]
+  }
+}
+
+export const renderFilmstrip = (doc: Document, opts: FilmstripOptions = {}): FilmstripResult => {
+  const VIEW = opts.view ?? "side"
+  const main = prepare(doc, opts.clip, "model")
+  const N = main.anim ? Math.max(1, Math.floor(opts.frames ?? 8)) : 1   // the rest pose is one frame
+  const restPose: Pose = opts.bind ? main.rig.bind.local : main.rig.rest
+  const times = Array.from({ length: N }, (_, i) => (main.anim ? (i / Math.max(1, N - 1)) * main.duration : 0))
+  const frames: Frame[] = times.map((t) => main.skinned(main.anim ? main.poseAt(t, main.rig.rest) : restPose))
+  const boneLines: Bone[][] = opts.bones ? times.map((t) => main.bonesOf(main.anim ? main.poseAt(t, main.rig.rest) : restPose)) : []
+  const labels = times.map((t) => (main.anim ? `${t.toFixed(2)}s` : "rest"))
+  // reference frames (other files / clips) first, same projection
+  for (const ref of [ ...(opts.refs ?? []) ].reverse()) {
+    const r = prepare(ref.doc, ref.clip, ref.label ?? "ref")
+    frames.unshift(r.skinned(r.anim ? r.poseAt(ref.time ?? 0, r.rig.rest) : r.rig.rest))
+    if (opts.bones) boneLines.unshift([])
+    labels.unshift(ref.label ?? (ref.clip ? `${ref.clip}@${ref.time ?? 0}` : "ref"))
+  }
+  const NF = frames.length
+
+  // one projection for the whole strip, from the union of every frame's bounds
+  const lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+  for (const f of frames) for (const p of f) for (let v = 0; v < p.pos.length; v += 3)
+    for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], p.pos[v + i]); hi[i] = Math.max(hi[i], p.pos[v + i]) }
+  if (!Number.isFinite(lo[0])) { lo[0] = lo[1] = lo[2] = -1; hi[0] = hi[1] = hi[2] = 1 }
+
+  const CELL = opts.cell ?? 240, PAD = 10, HEAD = 20
+  const bases: Record<string, { r: Vec3, u: Vec3, d: Vec3 }> = {
+    side:         { r: [ 0, 0, 1 ], u: [ 0, 1, 0 ], d: [ -1, 0, 0 ] },
+    front:        { r: [ 1, 0, 0 ], u: [ 0, 1, 0 ], d: [ 0, 0, -1 ] },
+    top:          { r: [ 0, 0, 1 ], u: [ 1, 0, 0 ], d: [ 0, -1, 0 ] },
+    threequarter: { r: [ 0.7, 0, 0.71 ], u: [ -0.2, 0.96, 0.2 ], d: [ -0.68, -0.28, 0.68 ] },
+    lowfront:     { r: [ 1, 0, 0 ], u: [ 0, 0.87, -0.5 ], d: [ 0, 0.5, -0.87 ] },
+  }
+  const B = bases[VIEW] ?? bases.side
+  const dot = (a: Vec3, b: ArrayLike<number>): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+  const corners: Vec3[] = []
+  for (let i = 0; i < 8; i++) corners.push([ i & 1 ? hi[0] : lo[0], i & 2 ? hi[1] : lo[1], i & 4 ? hi[2] : lo[2] ])
+  const ru = corners.map((c) => [ dot(B.r, c), dot(B.u, c) ])
+  const rlo = [ Math.min(...ru.map((p) => p[0])), Math.min(...ru.map((p) => p[1])) ]
+  const rhi = [ Math.max(...ru.map((p) => p[0])), Math.max(...ru.map((p) => p[1])) ]
+  const k = (CELL - 2 * PAD) / Math.max(rhi[0] - rlo[0], rhi[1] - rlo[1], 1e-9)
+  const sx = (ox: number, q: ArrayLike<number>): number => ox + PAD + (dot(B.r, q) - rlo[0]) * k + (CELL - 2 * PAD - (rhi[0] - rlo[0]) * k) / 2
+  const sy = (q: ArrayLike<number>): number => HEAD + CELL - PAD - (dot(B.u, q) - rlo[1]) * k
+
+  const W = CELL * NF, H = CELL + HEAD
+  const img = new Uint8Array(W * H * 4)
+  for (let i = 0; i < W * H; i++) { img[i * 4] = 17; img[i * 4 + 1] = 21; img[i * 4 + 2] = 28; img[i * 4 + 3] = 255 }
+  const depth = new Float32Array(W * H).fill(Infinity)
+  const light: Vec3 = [ -0.4, 0.75, 0.53 ]
+  const base = opts.color ?? [ 214, 126, 58 ]
+  frames.forEach((frame, f) => {
+    const ox = f * CELL
+    for (const { pos, tris } of frame) {
+      for (let t = 0; t + 2 < tris.length; t += 3) {
+        const p: number[][] = []
+        for (let c = 0; c < 3; c++) { const v = tris[t + c] * 3; p.push([ pos[v], pos[v + 1], pos[v + 2] ]) }
+        const e1 = [ p[1][0] - p[0][0], p[1][1] - p[0][1], p[1][2] - p[0][2] ], e2 = [ p[2][0] - p[0][0], p[2][1] - p[0][1], p[2][2] - p[0][2] ]
+        const nx = e1[1] * e2[2] - e1[2] * e2[1], ny = e1[2] * e2[0] - e1[0] * e2[2], nz = e1[0] * e2[1] - e1[1] * e2[0]
+        const nl = Math.hypot(nx, ny, nz) || 1
+        const shade = 0.22 + 0.78 * Math.abs((nx / nl) * light[0] + (ny / nl) * light[1] + (nz / nl) * light[2])
+        const col = [ Math.round(base[0] * shade), Math.round(base[1] * shade), Math.round(base[2] * shade) ]
+        const sp = p.map((q) => [ sx(ox, q), sy(q), -dot(B.d, q) ])
+        const minX = Math.max(ox, Math.floor(Math.min(sp[0][0], sp[1][0], sp[2][0]))), maxX = Math.min(ox + CELL - 1, Math.ceil(Math.max(sp[0][0], sp[1][0], sp[2][0])))
+        const minY = Math.max(HEAD, Math.floor(Math.min(sp[0][1], sp[1][1], sp[2][1]))), maxY = Math.min(H - 1, Math.ceil(Math.max(sp[0][1], sp[1][1], sp[2][1])))
+        const d = (sp[1][0] - sp[0][0]) * (sp[2][1] - sp[0][1]) - (sp[2][0] - sp[0][0]) * (sp[1][1] - sp[0][1])
+        if (Math.abs(d) < 1e-12) continue
+        for (let y = minY; y <= maxY; y++) for (let x = minX; x <= maxX; x++) {
+          const px = x + 0.5, py = y + 0.5
+          const w0 = ((sp[1][0] - px) * (sp[2][1] - py) - (sp[2][0] - px) * (sp[1][1] - py)) / d
+          const w1 = ((sp[2][0] - px) * (sp[0][1] - py) - (sp[0][0] - px) * (sp[2][1] - py)) / d
+          const w2 = 1 - w0 - w1
+          if (w0 < 0 || w1 < 0 || w2 < 0) continue
+          const z = w0 * sp[0][2] + w1 * sp[1][2] + w2 * sp[2][2]
+          const i = y * W + x
+          if (z >= depth[i]) continue
+          depth[i] = z
+          img[i * 4] = col[0]; img[i * 4 + 1] = col[1]; img[i * 4 + 2] = col[2]
+        }
+      }
+    }
+  })
+  // overlays: cell borders, bones, labels
+  for (let f = 0; f < NF; f++) {
+    const ox = f * CELL
+    drawLine(img, W, H, ox, HEAD, ox, H - 1, [ 35, 44, 56 ])
+    drawLine(img, W, H, ox, HEAD, ox + CELL - 1, HEAD, [ 35, 44, 56 ])
+    for (const { a, b } of boneLines[f] ?? []) {
+      drawLine(img, W, H, sx(ox, a), sy(a), sx(ox, b), sy(b), [ 127, 224, 255 ])
+      const bx = Math.round(sx(ox, b)), by = Math.round(sy(b))
+      for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) if (bx + dx >= 0 && by + dy >= 0 && bx + dx < W && by + dy < H) { const o = ((by + dy) * W + bx + dx) * 4; img[o] = 255; img[o + 1] = 255; img[o + 2] = 255 }
+    }
+    drawText(img, W, ox + 6, HEAD + 6, labels[f], [ 140, 150, 170 ])
+  }
+  const label = `${main.anim ? main.anim.getName() : "rest pose"} · ${VIEW} view · ${NF} frames`
+  drawText(img, W, 6, 5, main.anim ? `${main.duration.toFixed(2)}s - ${N}` : "-", [ 136, 170, 170 ])   // the 3×5 font has digits, '.', 's', '-' only
+  return { png: encodePng({ width: W, height: H, data: img }), width: W, height: H, label, duration: main.duration }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// lecodes-assets — programmatic API. CLI: src/cli.ts (`lecodes-assets …` / `lecodes assets …`).
+export { mirrorClips, partnerName, type MirrorOptions, type MirrorReport } from './retarget/mirror'
+export { readFbx, type FbxScene } from "./fbx/read"
+export { toDocument, type ToDocumentOptions, type ConvertWarning } from "./fbx/toDocument"
+export { convertFbx, mergeClipScene, writeGlb, makeIO, type ConvertOptions, type ConvertReport, type ConvertResult } from "./fbx/convert"
+export { probeFile, probeFbx, probeDocument } from "./probe"
+export { analyzeDoc, applyPlan, reportPlan, dumpTextures, type DoctorPlan, type DoctorOptions } from "./doctor/doctor"
+export { validateGlb, formatReport } from "./doctor/validateGlb"
+export { measureScale, applyScale, sceneBounds, type ScaleInfo } from "./doctor/normalizeScale"
+export { loadRig, rigFromFbx, rigFromDocument, checkUniformScale, type Rig, type DocRig } from "./retarget/rig"
+export { retarget, analyzeFacing, facingMismatch, bindAccessors, type BoneMap, type RetargetOptions, type RetargetReport, type AlignPolicy, type DonorRef, type LegReport, type ClipContacts, type ContactSpan, type RetargetEvent } from "./retarget/retarget"
+export { makeInPlace, speedProfile, yawProfile, type InPlaceResult, type InPlaceOptions } from "./retarget/inPlace"
+export { detectMarks, fitStaircase, readMarks, stairsMatcher, describeMarks, type ClipMarks, type MarkSpan, type Stairs, type FootTrack, type MarksInput } from "./retarget/marks"
+export { writeMarks, type WriteMarksOptions } from "./retarget/writeMarks"
+export { autoMap, classify, describeSkeleton, type AutoMapResult, type Skeleton } from "./retarget/automap"
+export { packTerrainTextures, resolveTerrainLayer, type TerrainPackLayer, type TerrainPackOptions, type TerrainPackResult } from "./terrainPack"
+export { runAssetsCli } from "./cli"

package/src/mergeSkins.ts

@@ -0,0 +1,117 @@
+// Modular characters: the body, the shirt, the gloves and the boots each come as their OWN skinned
+// FBX over the same skeleton. `mergeSkins` moves the donors' skinned meshes onto the base skeleton
+// (joints matched by name — exact, then the part after the last ':'/'|', the Animator's own rule)
+// and drops the donors' skeleton copies entirely. Leaving those copies in is the classic silent
+// failure: every bone name exists twice, a name-bound Animator finds the unskinned copy first, and
+// the mesh freezes in its rest pose. See docs/animation-plan.md §2.9.
+
+import { Logger, type Document, type Node, type Skin } from "@gltf-transform/core"
+import { mergeDocuments, prune, unpartition } from "@gltf-transform/functions"
+
+export type MergeSkinsWarning = { level: "warn" | "info", message: string }
+export type MergeSkinsReport = {
+  /** per donor: meshes moved, joints that had no counterpart in the base, total skin weight lost to them */
+  donors: { label: string, meshes: number, missingJoints: string[], lostWeight: number }[]
+  joints: number
+}
+
+const shortName = (n: string): string => n.slice(n.search(/[^:|]*$/))
+
+const findSkinnedNode = (doc: Document): Node | null => {
+  let found: Node | null = null
+  for (const scene of doc.getRoot().listScenes()) scene.traverse((n) => { if (!found && n.getSkin() && n.getMesh()) found = n })
+  return found
+}
+
+/** Merge the skinned meshes of `donors` into `base` (mutated). Donor documents are consumed. */
+export const mergeSkins = async (base: Document, donors: { doc: Document, label: string }[], warn: (w: MergeSkinsWarning) => void = () => {}): Promise<MergeSkinsReport> => {
+  const baseSkin: Skin | undefined = base.getRoot().listSkins()[0]
+  if (!baseSkin) throw new Error("the base model has no skin — --merge-skins needs a skinned base (the body)")
+  const baseJoints = baseSkin.listJoints()
+  const byName = new Map<string, number>(), byShort = new Map<string, number>()
+  baseJoints.forEach((j, i) => {
+    const n = j.getName()
+    if (!byName.has(n)) byName.set(n, i)
+    const s = shortName(n)
+    if (!byShort.has(s)) byShort.set(s, i)
+  })
+  const baseScene = base.getRoot().getDefaultScene() ?? base.getRoot().listScenes()[0]
+  const baseMeshNode = findSkinnedNode(base)
+  const homeParent = baseMeshNode?.getParentNode() ?? null
+  const report: MergeSkinsReport = { donors: [], joints: baseJoints.length }
+
+  for (const { doc: donor, label } of donors) {
+    const donorSkins = donor.getRoot().listSkins()
+    if (donorSkins.length === 0) { warn({ level: "warn", message: `${label}: no skin — nothing to merge (static meshes attach at runtime instead)` }); continue }
+    // donor joint index → base joint index, per donor skin
+    const remaps = new Map<Skin, number[]>()
+    const missing = new Set<string>()
+    for (const s of donorSkins) {
+      remaps.set(s, s.listJoints().map((j) => {
+        const n = j.getName()
+        const hit = byName.get(n) ?? byShort.get(shortName(n))
+        if (hit === undefined) missing.add(n)
+        return hit ?? -1
+      }))
+    }
+    const donorMeshNodes: Node[] = []
+    for (const scene of donor.getRoot().listScenes()) scene.traverse((n) => { if (n.getSkin() && n.getMesh()) donorMeshNodes.push(n) })
+    const donorScenes = donor.getRoot().listScenes()
+
+    const map = mergeDocuments(base, donor)
+    let lostWeight = 0
+    for (const src of donorMeshNodes) {
+      const node = map.get(src) as Node | undefined
+      if (!node) continue
+      const remap = remaps.get(src.getSkin()!)!
+      for (const prim of node.getMesh()!.listPrimitives()) {
+        const J = prim.getAttribute("JOINTS_0"), W = prim.getAttribute("WEIGHTS_0")
+        if (!J) continue
+        const ja = J.getArray()!, wa = W?.getArray() ?? null
+        const wNorm = W ? (W.getComponentType() === 5126 ? 1 : W.getComponentType() === 5121 ? 255 : 65535) : 1
+        for (let i = 0; i < ja.length; i++) {
+          const m = remap[ja[i]]
+          if (m >= 0) { ja[i] = m; continue }
+          if (wa) { lostWeight += wa[i] / wNorm; wa[i] = 0 }
+          ja[i] = 0
+        }
+        J.setArray(ja)
+        if (wa) W!.setArray(wa)
+      }
+      node.setSkin(baseSkin)
+      // keep the mesh node's own TRS; it is re-homed next to the base skinned mesh
+      if (homeParent) homeParent.addChild(node)
+      else baseScene.addChild(node)
+    }
+    // drop the donor's skeleton copy: every merged node that is not one of the re-homed mesh nodes
+    const kept = new Set(donorMeshNodes.map((n) => map.get(n)))
+    for (const s of donorSkins) { const ms = map.get(s) as Skin | undefined; if (ms && ms !== baseSkin) ms.dispose() }
+    for (const ds of donorScenes) {
+      const scene = map.get(ds)
+      if (!scene) continue
+      const doomed: Node[] = []
+      for (const root of (scene as typeof baseScene).listChildren()) root.traverse((n) => { if (!kept.has(n)) doomed.push(n) })
+      for (const n of doomed.reverse()) n.dispose()
+      if (scene !== baseScene) (scene as typeof baseScene).dispose()
+    }
+    if (lostWeight > 0.5) warn({ level: "warn", message: `${label}: ${lostWeight.toFixed(1)} of skin weight sat on bones the base skeleton lacks (${[ ...missing ].slice(0, 5).join(", ")}${missing.size > 5 ? "…" : ""}) — those vertices now follow the root` })
+    report.donors.push({ label, meshes: donorMeshNodes.length, missingJoints: [ ...missing ], lostWeight })
+  }
+  await base.setLogger(new Logger(Logger.Verbosity.SILENT)).transform(prune(), unpartition())
+  return report
+}
+
+/** Node names that occur more than once, and whether a skin joint is shadowed by a plain node of the same name. */
+export const duplicateNodeNames = (doc: Document): { name: string, count: number, shadowsJoint: boolean }[] => {
+  const joints = new Set(doc.getRoot().listSkins().flatMap((s) => s.listJoints()))
+  const seen = new Map<string, { count: number, joint: number, plain: number }>()
+  for (const n of doc.getRoot().listNodes()) {
+    const name = n.getName()
+    if (!name) continue
+    const e = seen.get(name) ?? { count: 0, joint: 0, plain: 0 }
+    e.count++
+    if (joints.has(n)) e.joint++; else e.plain++
+    seen.set(name, e)
+  }
+  return [ ...seen ].filter(([ , e ]) => e.count > 1).map(([ name, e ]) => ({ name, count: e.count, shadowsJoint: e.joint > 0 && e.plain > 0 }))
+}

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)
+}