lecodes-assets 0.1.2 → 0.2.1

package/src/retarget/retarget.ts

@@ -0,0 +1,2272 @@
+// Cross-rig animation retargeting: take clips authored on one skeleton and drive a different one.
+//
+// The `--clips` merge in `convert` binds tracks by BONE NAME and copies them verbatim. That only
+// works when both files came from the same rig (the Mixamo case). Between two unrelated rigs it is
+// hopeless — the bone names differ, the chains have different lengths, and, worst of all, the local
+// axis conventions differ (this repo's fox runs its bones down local +Y, a Maya/AdvancedSkeleton
+// wolf runs them down local +X), so the same local rotation means two different things.
+//
+// So work in WORLD space instead, where a rotation means the same thing in both rigs:
+//
+//   ΔR(t)    = Rsrc_world(t) · Rsrc_bind_world⁻¹     how far the donor bone turned from ITS bind
+//   Rdst_world(t) = ΔR(t) · Rdst_ref_world            apply that turn to the target's REFERENCE
+//   Rdst_local(t) = Rdst_parent_world(t)⁻¹ · Rdst_world(t)
+//
+// Because the target's reference pose is the anchor, nothing about the target's proportions, chain
+// lengths or axis conventions has to match the donor's — only the two reference poses have to
+// describe the same thing (both animals standing, facing the same way, same up axis).
+// `analyzeFacing` checks that precondition instead of leaving it to be discovered as a mangled result.
+//
+// The transfer itself is exact: with matching references, every mapped bone's world DIRECTION on
+// the target equals the donor's at every frame. Everything below is about the four things that
+// formula alone gets wrong on real assets, in the order they matter:
+//
+// 1. THE TWO REFERENCE POSES. Deltas are measured from the donor's reference and applied to the
+//    target's; both default to the BIND pose (inverse of the skin's inverse-bind matrices — never
+//    the TRS on the nodes, which an exporter routinely leaves at some junk frame), but two bind
+//    poses rarely describe the same posture, and the whole retarget hinges on them doing so.
+//    - Donor side (`donorReference`): a bind is often a posture the clips never visit — the
+//      polyperfect wolf binds upright on vertical thighs and walks 10% lower with its thighs 30°
+//      forward. Measured from such a bind every clip reads "crouch and lean", and a target keeping
+//      its own stance inherits the crouch. So when the two binds put the LEGS differently (>12°,
+//      i.e. different conventions), the donor is referenced to the MEAN pose of its idle/walk — its
+//      actual neutral posture — and the deltas are pure motion. When the binds agree, bind-to-bind
+//      is the faithful transfer (an identity retarget reproduces the donor exactly).
+//    - Target side (`alignReference`), per mapped bone: `keep` its own bind orientation, or
+//      `direction` — turn it so the bone POINTS the way the donor's does, measured to the nearest
+//      mapped descendant on each side (an auto-T-pose step per bone). Core bones — the root and
+//      every branch point (pelvis, chest, head) — keep: artists put "Hips" and "chest" wherever the
+//      weights want them, so the pelvis→chest joint line is +3° on one wolf and −12° on one fox
+//      while both stand level, and forcing them equal pitched the whole fox nose-up. Legs keep when
+//      the target binds in a STANCE (feet level, legs hanging) — that is its natural posture and the
+//      donor's deltas ride on it — and align when it binds posed (T-pose, folded). Everything else
+//      (tail, neck, ears, spine members) aligns. `align` in the map overrides per bone.
+//    Straightening a crouched rig lifts it off the ground, so the root is put back down
+//    (`groundOffset`) and every foot is planted in the reference pose.
+//
+// 2. PROPORTIONS (`placeLeg`). Directions transfer, positions do not: when the target's front and
+//    hind legs have a different length ratio than the donor's, the feet float or sink by a few
+//    percent of body height — exactly what the eye catches first. Leg chains are detected from the
+//    map (`detectLegs`), each foot gets a goal built as THE TARGET'S OWN STANCE plus the donor's
+//    departure from ITS stance, scaled by that leg's length ratio, on all three axes — height above
+//    each rig's own stance level, and the horizontal offset each rig plants its foot at under its
+//    own hip — and a FABRIK pass from the FK pose bends the chain onto it. Using the donor's
+//    absolute foot-under-hip offset instead overwrites the target's build with the donor's: this
+//    fox tucks each foot ~8% of body height inboard while every polyperfect animal stands on
+//    vertical legs, and copying that planted the fox bow-legged in every clip. Because the goal IS
+//    the FK result whenever the two legs are scaled copies, IK only ever spends the proportion
+//    residual. Root motion is scaled by the mean leg ratio (a stride is leg length, not body
+//    height), so stance feet that were still on the donor stay still on the target.
+//
+// 3. CHAIN LENGTH (`findBridges`). A donor chain LONGER than the target's collapses for free (the
+//    target's `chest` mapped to `Chest_M` picks up Spine1+Spine2, because a world rotation already
+//    contains everything above it). A target chain longer than the donor's — unmapped bones between
+//    two mapped ones — interpolates the world delta along the chain instead of bending at one joint.
+//
+// 4. SPACES. A donor facing another way is turned first (`donorYawDeg`, from `analyzeFacing`); a
+//    skin whose bind space is scaled against node space is rescaled in `rig.ts` (`bind.scale`).
+//
+// 5. HUMANOIDS (`opts.humanoid`, the two rigs' avatars from humanoid.ts). The same transfer, with
+//    the reference policy decided by canonical ROLE instead of by tree shape: torso, head, legs and
+//    feet keep their bind (a standing bind is build — ankle height, spine joint placement — not
+//    posture), arms and fingers align to the donor's bind directions with explicit references
+//    (hand → the finger bases, not "the heaviest subtree") and a THRESHOLD: a mismatch under 8° is
+//    build noise and stays, above it is posture (an A-pose against a T-pose, a bent elbow) and turns.
+//    Direction fixes two of a bone's three degrees of freedom; the third, the ROLL about the arm, is
+//    what decides where the palm faces, and no direction can see it. It is read off the hand's
+//    KNUCKLE LINE (index base → little base): after alignment the whole forearm chain — forearm,
+//    hand, fingers — is turned about the forearm axis until the target's knuckle line lies where the
+//    donor's does. A Mixamo T-pose (palms down) against an A-pose rig whose palms face back is a
+//    ~90° roll that would otherwise ride every clip as a twisted wrist. An identity retarget is
+//    still exact: equal directions and equal knuckle lines leave every correction at zero.
+//    The donor is referenced to its bind (its clips are authored on it); a target root bone that
+//    shares the donor's hips gets the hips' TRAVEL only, never their rotation, so helpers parented
+//    to the root stay put.
+//
+// 6. PROPORTIONS, SECOND PASS (`opts.rootMotion`, `opts.plant`, `ik: 'legs+hands'`, `opts.twist`).
+//    - Where the travel goes: a rig with a root ABOVE the hips gets the donor's horizontal travel on
+//      the root and the vertical bob on the hips (`'root'`, the default when such a root exists — a
+//      character controller reads the root's travel and must not bob with it); `'hips'` puts all of
+//      it on the hips as the donor had it; `'none'` strips the travel for an in-place clip (feet
+//      still planted in the travelling frame, so they slide back under the body like a treadmill).
+//      A donor whose hips bob RELATIVE to their own root (MoCap Central: `root` travels, `pelvis`
+//      bobs) has that bob re-applied on the target's hips — the one donor translation besides the
+//      root's that carries motion.
+//    - Feet as CONTACT + ORIENTATION (humanoid): the leg's effector is the ankle, but its goal is
+//      derived from the BALL of the foot (the canonical `Toes` bone) — the ball goes where the
+//      donor's ball goes (scaled, stance-corrected), the foot itself keeps the donor's rotation on
+//      the target's own flat bind, and the ankle follows from the two. Rigs disagree about where the
+//      ankle sits over the ball (a boot's foot bone dives 56° to the ball, X-bot's 27°, both soles
+//      flat): transferring the ankle's position AND the foot's rotation lifts such a boot 10 cm off
+//      the ground at toe-off, while driving the ball with the foot as an IK link (the old way) lets
+//      the solver pick the foot's pitch — 50° off the donor in the swing. Planting holds the ball.
+//    - Foot planting: the donor's foot MARKS (marks.ts) drive two constraints on the target's foot.
+//      Through a STILL window the ball is LOCKED to one world point (the mean of where the FK put
+//      it, at the height the foot's clearance rule below gives) and the foot keeps one rotation,
+//      fading in and out over a few frames inside the touch. On every frame of a flat-ground clip
+//      (every TOUCH frame of a stair / platform clip) the foot's CLEARANCE — the lowest of its heel
+//      (virtual: the ankle's bind height hung under the ankle), its ball and its toe (real, or a
+//      virtual one off the ball's rotation) over its level — is matched to the donor's, scaled by
+//      the leg ratio; the whole foot shifts vertically, x/z and rotation stay the FK's. So a heel
+//      strike lands on the ground, a toe-off lifts with the donor's, a hang dangles, and a foot the
+//      transfer left 7 cm up in a lunge comes down. The BODY follows: while a foot touches, the
+//      hips drop until the leg reaches its anchor at the donor's extension (up to 10 cm; a swing
+//      foot asks nothing — its knee bends), so the knees never straighten past the donor's.
+//    - Platform takes (`stairs` → 'platform'): a HANG — both hands still and overhead, no foot on
+//      the floor — names the top when the feet never stand on it (the grip's height + what a hand
+//      holds under a lip), and every such take gets a `platform` block beside the contacts
+//      (marks.ts `fitPlatform`, fitted again on the OUTPUT): the top's height and the ledge's EDGE
+//      — a point on it relative to the root at frame 0 and the face's outward normal — from the
+//      plants on the top, the hands resting on it, the wrists gripping under it and the body's
+//      envelope, so a runtime can stand the character against a real ledge at clip start.
+//    - Hands as effectors (`'legs+hands'`): the same ratio-scaled goal as a foot, measured from the
+//      upper arm, chain capped at the upper + lower arm, for clips where the hands meet or hold.
+//    - Twist helpers (the avatar's `twist` map): a helper at fraction `t` along its limb bone takes
+//      `f·(t·twistOut − (1 − t)·twistIn)` about the bone's axis on top of riding it — near the joint
+//      it counter-rotates the bone's own axial turn (the shoulder skin stays with the clavicle), near
+//      the far end it follows the child's (the wrist skin follows the hand's pronation). `f` = 0.5
+//      like Unity's arm/leg twist defaults.
+//
+// Bone lengths always come from the TARGET — donor translation tracks are ignored except the root's
+// (and the hips' bob relative to it, see 6).
+import type { Document } from '@gltf-transform/core'
+import { qmul, qinv, qnorm, qslerp, qrot, worldOf, bindVsRest, rotateRig, type Quat, type Vec3, type Rig, type DocRig, type Pose, type Clip } from './rig'
+import type { Avatar, HumanBone } from './humanoid'
+import { describeMarks, detectMarks, fitPlatform, fitStaircase, type FootTrack, type LevelKind, type MarkSpan, type MarksInput, type PlatformMark, type Stairs } from './marks'
+import { headingCurve } from './heading'
+
+export interface BoneMap { [targetBone: string]: string }   // target bone name -> donor bone name
+
+export type Align = 'none' | 'bone-direction'
+/** Per-bone reference policy: keep the bind orientation, align the bone direction to the donor's
+ *  (measured to the heuristic descendant), or align it measured to these named descendants. */
+export type AlignPolicy = 'keep' | 'direction' | string[]
+
+export interface RetargetOptions {
+  align?: Align                // global switch (default 'bone-direction'; 'none' = keep everything)
+  alignBones?: Record<string, AlignPolicy>   // per-bone policy, overriding the core/chain default
+  alignTo?: Record<string, string[]>   // legacy spelling of `alignBones` with reference lists
+  ik?: 'none' | 'legs' | 'legs+hands'   // foot placement (default 'legs'); '+hands' = the hands as effectors too (humanoid)
+  rootMotion?: RootMotion      // where the donor's travel lands (default 'auto': root when the rig has one above the hips, else hips)
+  headingEnd?: number          // the baked heading curve must end here (degrees, + = left): a stop that turns (heading.ts `endAt`)
+  plant?: boolean              // foot planting (default true): each foot LOCKED through its still windows (marks.ts)
+  /** The horizontal stance a planted foot keeps: 'target' (default) = the target rig's own foot-under-hip
+   *  offset plus only the donor's DEPARTURE from its bind (a quadruped's build — header §2); 'donor' = the
+   *  donor's foot-under-hip offset transfers whole, scaled. A humanoid whose A-pose bind stands legs apart
+   *  loses that width on every clip otherwise (MC_RunFast: 25 → 14 cm of step width, 2026-09-04). The
+   *  height stays stance-relative either way. */
+  footStance?: 'target' | 'donor'
+  stairs?: (clip: string) => LevelKind   // which donor clips carry LEVELS: a staircase, a platform (two levels), or none
+  twist?: number | false       // twist-helper fraction (default 0.5; false = helpers ride their bone rigidly)
+  donorYawDeg?: number         // turn the donor about +Y by this much first (facing mismatch fix)
+  donorRef?: DonorRef          // pose the donor's deltas are measured from (default 'auto': mean of its idle/walk)
+  legs?: string[]              // target effector bones (feet) — overrides auto-detection
+  fps?: number                 // sampling rate of the produced clips (default 30, the FBX bake rate)
+  rootScale?: number           // override the automatic root-motion scale
+  /** `'yaw'`: a target root bone that takes the donor hips' TRAVEL also takes their HEADING — the
+   *  hips' turn about the up axis since the clip's first frame — so a turn-start / turn-in-place /
+   *  arc clip carries its turn on the root, where the engine's root rotation reads it (the hips keep
+   *  everything else). Default `'none'`: the root never rotates (a walk cycle's hip sway stays a
+   *  pose). No effect on a donor with its own root bone (the root follows it as any bone). */
+  rootRotation?: 'none' | 'yaw'
+  clips?: string[]             // donor clip names to take (default: all)
+  rename?: (name: string) => string
+  epsilon?: number             // key-reduction tolerance for translations, metres (default 1e-4; 0 disables)
+  epsilonDeg?: number          // key-reduction tolerance for rotations, degrees (default 0.2; 0 disables)
+  epsilonLegDeg?: number       // …for the hips and the leg chains (default 0.01: a planted toe stays within a millimetre)
+  /** BODY ON THE GROUND: a joint the donor has on its floor (within 5 cm) is brought to the same height
+   *  over the target's ground PLUS this clearance (metres, default 0.05) — a roll on the back, a
+   *  knock-down; the clearance is the skin the joint has under it */
+  bodyClearance?: number
+  humanoid?: { target: Avatar; donor: Avatar }   // both rigs' avatars → role-based references + palm roll (see header §5)
+  warn?: (message: string) => void
+}
+
+export type RootMotion = 'auto' | 'hips' | 'root' | 'none'
+
+export interface LegReport {
+  effector: string; donorEffector: string; chain: string[]
+  ratio: number                // target leg length / donor leg length
+  shortfall: number            // worst distance (m) a goal was out of reach, over all clips
+  isFoot: boolean              // stands on the ground (else a hand)
+  contact: string              // the bone whose position is matched to the donor's (the ball of a humanoid foot; else the effector)
+  planted: number              // frames the goal was locked to a planted position, over all clips
+}
+
+/** Something worth a marker on a timeline: a span of a clip, on one bone. */
+export interface RetargetEvent {
+  kind: 'plant' | 'reach' | 'below'   // foot planted · goal out of reach (value = m) · toe under the ground (value = m)
+  bone: string
+  from: number; to: number     // seconds
+  value?: number
+  /** plant: where the contact bone stood when the span began — x/z relative to the root's horizontal
+   *  position that frame (i.e. under the character, valid for an in-place clip too), y absolute */
+  at?: Vec3
+}
+
+/** A foot on the ground: the touch span, the still window inside it (null: never still), where the
+ *  contact bone stood at the strike, and the tread index on a stair clip. */
+export interface ContactSpan { from: number; to: number; still: [ number, number ] | null; at: Vec3; step?: number }
+/**
+ * The clip's foot contacts — what a runtime needs for phase matching, foot-aware transitions and
+ * foot IK: per side the spans a foot stands (`from`/`to` seconds, `at` = the contact bone's position
+ * at the strike, x/z relative to the root, y absolute), and which foot is down at the first frame.
+ * Written to the GLB animation's `extras.lecodes.contacts` as well.
+ */
+export interface ClipContacts {
+  feet: { l: string | null; r: string | null }   // the contact bones (a humanoid's balls)
+  l: ContactSpan[]
+  r: ContactSpan[]
+  first: 'l' | 'r' | 'both' | null               // planted at t = 0
+  /** a stair clip's staircase, in the target's space (tread k at base + k · riser) */
+  stairs?: Stairs
+  /** the hands' contact bones and their ground contacts (a cartwheel's, a roll's, a vault's) */
+  hands?: { l: string | null; r: string | null }
+  hl?: ContactSpan[]
+  hr?: ContactSpan[]
+}
+
+export interface TwistReport { bone: string; of: string; at: number }   // helper, its limb bone, fraction along it
+
+export interface RetargetReport {
+  bindGap: { donor: { worst: number; bone: string; skinned: number }; target: { worst: number; bone: string; skinned: number } }
+  align: { bone: string; degrees: number; via: string }[]
+  kept: string[]               // mapped bones whose reference is the bind orientation
+  bridges: string[]            // unmapped target bones interpolated between mapped ones
+  groundOffset: number
+  ground: { target: number; donor: number } | null
+  legs: LegReport[]
+  clips: {
+    name: string; duration: number; frames: number; keys: number; events: RetargetEvent[]
+    turn: number               // the root's net yaw over the clip, degrees (rootRotation 'yaw')
+    contacts: ClipContacts     // the feet on the ground (see ClipContacts)
+    travel: [ number, number ] // the root's horizontal displacement over the clip, target metres (x, z) — before any in-place conversion
+    /** a platform take's ledge in the target's space (see PlatformMark) + the root's x/z at frame 0 */
+    platform?: PlatformMark & { root0: [ number, number ] }
+  }[]
+  mapped: { target: string; donor: string }[]
+  unmappedTarget: string[]
+  rootScale: number
+  rootScaleFrom: 'legs' | 'height' | 'option' | 'none'
+  donorRef: string             // what the donor deltas are measured from
+  legDisagreement: number      // mean angle (°) between the two binds' leg bone directions
+  stance: boolean              // the target binds standing (legs kept) rather than posed (legs aligned)
+  root: { target: string; donor: string } | null
+  rootTranslateOnly: boolean   // the root took the donor's travel but not its rotation (it shares the donor's hips)
+  roll: { side: string; degrees: number; via: string }[]   // humanoid palm-roll corrections per arm (nudges from the avatar included)
+  underThreshold: { bone: string; degrees: number; via: string }[]   // bones that would have aligned but sat under the threshold: the bind kept
+  rootMotion: Exclude<RootMotion, 'auto'>   // where the travel went
+  rootRotation: 'none' | 'yaw'              // whether the root carries the hips' heading (see RetargetOptions.rootRotation)
+  hipsBob: 'root' | 'donor' | null          // the hips got a translation track: the travel's vertical part / the donor's own hips bob
+  twist: TwistReport[]                       // twist helpers driven (humanoid)
+}
+
+const DEG = 180 / Math.PI
+const IDENT: Quat = [ 0, 0, 0, 1 ]
+
+/** Which way a rig faces and how big it is, from its rest pose — the retarget precondition. */
+export const analyzeFacing = (rig: Rig, boneNames: string[]): { forward: Vec3; up: Vec3; height: number; length: number } => {
+  const pick = (n: string): Vec3 | null => { const i = rig.index.get(n); return i === undefined ? null : rig.bind.worldPos[i] }
+  const head = pick(boneNames[0]), tail = pick(boneNames[1])
+  let lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+  for (const p of rig.bind.worldPos) for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], p[i]); hi[i] = Math.max(hi[i], p[i]) }
+  // Flattened to the ground plane: a head held higher than the tail is posture, not facing.
+  const fwd: Vec3 = head && tail ? [ head[0] - tail[0], 0, head[2] - tail[2] ] : [ 0, 0, 1 ]
+  const len = Math.hypot(...fwd) || 1
+  return {
+    forward: [ fwd[0] / len, fwd[1] / len, fwd[2] / len ],
+    up: [ 0, 1, 0 ],
+    height: hi[1] - lo[1],
+    length: Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]),
+  }
+}
+
+/**
+ * Angle between the two rigs' forward directions, in degrees. Anything much above zero means the
+ * rest poses disagree about which way is front and every clip will come out rotated.
+ */
+export const facingMismatch = (a: Vec3, b: Vec3): number =>
+  Math.acos(Math.max(-1, Math.min(1, a[0] * b[0] + a[1] * b[1] + a[2] * b[2]))) * DEG
+
+interface Channel { node: number; times: number[]; rot?: Quat[]; pos?: Vec3[] }
+
+/** Drop keys a linear/slerp interpolation would have reproduced anyway. */
+const reduce = (ch: Channel, eps: number, epsDeg: number): void => {
+  if ((eps <= 0 && epsDeg <= 0) || ch.times.length < 3) return
+  // A slerp guess within epsDeg of the real key: |dot| > cos(epsDeg/2).
+  const minDot = Math.cos((epsDeg / 2) * Math.PI / 180)
+  const keepT: number[] = [ ch.times[0] ]
+  const keepR: Quat[] | undefined = ch.rot ? [ ch.rot[0] ] : undefined
+  const keepP: Vec3[] | undefined = ch.pos ? [ ch.pos[0] ] : undefined
+  for (let i = 1; i < ch.times.length - 1; i++) {
+    const t0 = keepT[keepT.length - 1], t1 = ch.times[i + 1]
+    const u = (ch.times[i] - t0) / (t1 - t0 || 1)
+    let flat = true
+    if (ch.rot && keepR) {
+      const guess = qslerp(keepR[keepR.length - 1], ch.rot[i + 1], u), got = ch.rot[i]
+      const dot = Math.abs(guess[0] * got[0] + guess[1] * got[1] + guess[2] * got[2] + guess[3] * got[3])
+      if (epsDeg <= 0 ? dot < 1 - 1e-12 : dot < minDot) flat = false
+    }
+    if (ch.pos && keepP) {
+      const a = keepP[keepP.length - 1], b = ch.pos[i + 1], got = ch.pos[i]
+      for (let k = 0; k < 3; k++) if (Math.abs(a[k] + (b[k] - a[k]) * u - got[k]) > (eps <= 0 ? 1e-12 : eps)) flat = false
+    }
+    if (!flat) { keepT.push(ch.times[i]); keepR?.push(ch.rot![i]); keepP?.push(ch.pos![i]) }
+  }
+  keepT.push(ch.times[ch.times.length - 1])
+  keepR?.push(ch.rot![ch.rot!.length - 1])
+  keepP?.push(ch.pos![ch.pos!.length - 1])
+  ch.times = keepT
+  if (keepR) ch.rot = keepR
+  if (keepP) ch.pos = keepP
+}
+
+const sub = (a: Vec3, b: Vec3): Vec3 => [ a[0] - b[0], a[1] - b[1], a[2] - b[2] ]
+const add = (a: Vec3, b: Vec3): Vec3 => [ a[0] + b[0], a[1] + b[1], a[2] + b[2] ]
+const scl = (a: Vec3, k: number): Vec3 => [ a[0] * k, a[1] * k, a[2] * k ]
+const len = (v: Vec3): number => Math.hypot(v[0], v[1], v[2])
+const unit = (v: Vec3): Vec3 | null => { const l = len(v); return l > 1e-12 ? [ v[0] / l, v[1] / l, v[2] / l ] : null }
+
+/** Shortest-arc rotation taking `from` onto `to` (both unit). */
+const arc = (from: Vec3, to: Vec3): Quat => {
+  const d = from[0] * to[0] + from[1] * to[1] + from[2] * to[2]
+  if (d > 0.999999) return IDENT
+  if (d < -0.999999) {
+    // Opposite directions: any perpendicular axis is a valid 180° turn; take the most stable one.
+    const ax: Vec3 = Math.abs(from[0]) < 0.9 ? [ 1, 0, 0 ] : [ 0, 1, 0 ]
+    const c: Vec3 = [ from[1] * ax[2] - from[2] * ax[1], from[2] * ax[0] - from[0] * ax[2], from[0] * ax[1] - from[1] * ax[0] ]
+    const u = unit(c)!
+    return [ u[0], u[1], u[2], 0 ]
+  }
+  const c: Vec3 = [ from[1] * to[2] - from[2] * to[1], from[2] * to[0] - from[0] * to[2], from[0] * to[1] - from[1] * to[0] ]
+  return qnorm([ c[0], c[1], c[2], 1 + d ])
+}
+
+/** Children lists for a rig. */
+const childrenOf = (rig: Rig): number[][] => {
+  const children: number[][] = rig.names.map(() => [])
+  rig.parents.forEach((p, i) => { if (p >= 0) children[p].push(i) })
+  return children
+}
+
+/**
+ * Reference orientation per target bone — see the header. `byTarget` maps target bone index → donor
+ * bone index for every mapped bone; `rootIdx` is the root-motion bone (always core).
+ */
+const alignReference = (
+  target: DocRig, donor: Rig, byTarget: Map<number, number>, rootIdx: number, align: Align,
+  policies: Record<string, AlignPolicy>, minDeg = 0, force: Set<number> = new Set(),
+): { ref: Quat[]; A: Quat[]; log: { bone: string; degrees: number; via: string }[]; kept: string[]; under: { bone: string; degrees: number; via: string }[] } => {
+  const ref: Quat[] = target.bind.worldRot.map((q) => [ ...q ] as Quat)
+  const A: Quat[] = target.names.map(() => IDENT)
+  const log: { bone: string; degrees: number; via: string }[] = []
+  const under: { bone: string; degrees: number; via: string }[] = []
+  const kept: string[] = []
+  if (align === 'none') { for (const i of byTarget.keys()) kept.push(target.names[i]); return { ref, A, log, kept, under } }
+
+  const children = childrenOf(target)
+  const mappedChildCount = (i: number): number => {
+    // Mapped descendants reachable without crossing another mapped bone, per branch.
+    let n = 0
+    const queue = [ ...children[i] ]
+    while (queue.length) { const c = queue.shift()!; if (byTarget.has(c)) n++; else queue.push(...children[c]) }
+    return n
+  }
+
+  // Explicit policies from the map win over the core/chain default.
+  const explicit = new Map<number, AlignPolicy>()
+  for (const [ bone, pol ] of Object.entries(policies)) {
+    const i = target.index.get(bone)
+    if (i !== undefined && byTarget.has(i)) explicit.set(i, pol)
+  }
+
+  const subtreeSize = new Array(target.names.length).fill(1)
+  for (let k = target.order.length - 1; k >= 0; k--) {
+    const i = target.order[k]
+    if (target.parents[i] >= 0) subtreeSize[target.parents[i]] += subtreeSize[i]
+  }
+
+  /**
+   * Mapped descendants that define this bone's direction. At a branch point the heaviest subtree
+   * wins — that is the spine, not the tail — and a symmetric tie (a head between two ears) averages,
+   * which is the only stable answer when neither side is "the" continuation.
+   */
+  const directionRefs = (i: number): number[] => {
+    const found: number[] = []
+    const queue = [ ...children[i] ]
+    while (queue.length) {
+      const c = queue.shift()!
+      if (byTarget.has(c)) { found.push(c); continue }   // stop at the first mapped bone per branch
+      queue.push(...children[c])
+    }
+    if (!found.length) return []
+    const best = Math.max(...found.map((c) => subtreeSize[c]))
+    const heaviest = found.filter((c) => subtreeSize[c] === best)
+    if (heaviest.length < 2) return heaviest
+    // Tie: the spine continues along the CENTRELINE, so a chest whose head and front legs all weigh
+    // the same must follow the head. A symmetric pair (two ears off a head) stays tied and averages.
+    const lateral = (c: number): number => Math.abs(target.bind.worldPos[c][0] - target.bind.worldPos[i][0])
+    const nearest = Math.min(...heaviest.map(lateral))
+    const tol = Math.max(nearest * 1.05, 1e-6)
+    return heaviest.filter((c) => lateral(c) <= tol)
+  }
+
+  const meanDir = (from: Vec3, tos: Vec3[]): Vec3 | null => {
+    const acc: Vec3 = [ 0, 0, 0 ]
+    let n = 0
+    for (const to of tos) {
+      const u = unit(sub(to, from))
+      if (!u) continue
+      acc[0] += u[0]; acc[1] += u[1]; acc[2] += u[2]; n++
+    }
+    return n ? unit(acc) : null
+  }
+
+  for (const i of target.order) {
+    const s = byTarget.get(i)
+    if (s === undefined) continue
+    // Default policy: the root and every branch point are core → keep; chain members → direction.
+    let pol: AlignPolicy = explicit.get(i) ?? (i === rootIdx || mappedChildCount(i) >= 2 ? 'keep' : 'direction')
+    if (pol === 'keep') { kept.push(target.names[i]); continue }
+
+    let refs: number[]
+    if (Array.isArray(pol)) {
+      refs = pol.map((r) => target.index.get(r)).filter((x): x is number => x !== undefined && byTarget.has(x))
+      if (!refs.length) refs = directionRefs(i)
+    } else refs = directionRefs(i)
+
+    let ut: Vec3 | null = null, us: Vec3 | null = null, via = ''
+    if (refs.length) {
+      ut = meanDir(target.bind.worldPos[i], refs.map((c) => target.bind.worldPos[c]))
+      us = meanDir(donor.bind.worldPos[s], refs.map((c) => donor.bind.worldPos[byTarget.get(c)!]))
+      via = refs.map((c) => target.names[c]).join("+")
+    } else if (children[i].length) {
+      // Leaf on the map but not in the rig: fall back to any child on each side.
+      const donorKids = donor.parents.map((p, k) => [ p, k ] as const).filter(([ p ]) => p === s).map(([ , k ]) => k)
+      if (donorKids.length) {
+        ut = unit(sub(target.bind.worldPos[children[i][0]], target.bind.worldPos[i]))
+        us = unit(sub(donor.bind.worldPos[donorKids[0]], donor.bind.worldPos[s]))
+        via = `${target.names[children[i][0]]} (unmapped child)`
+      }
+    }
+    let a: Quat
+    if (ut && us) {
+      a = arc(ut, us)
+      // Under the threshold the mismatch is build (joint placement), not posture: keep the bind —
+      // unless a person said this bone IS posed (`force`).
+      const off = 2 * Math.acos(Math.min(1, Math.abs(a[3]))) * DEG
+      if (minDeg > 0 && off < minDeg && !force.has(i)) { if (off > 0.5) under.push({ bone: target.names[i], degrees: off, via }); a = IDENT; kept.push(target.names[i]); A[i] = a; continue }
+    } else {
+      // True leaf (a tail tip, an ear end): inherit whatever its parent was corrected by.
+      a = A[target.parents[i]] ?? IDENT
+      via = 'inherited from parent'
+    }
+    A[i] = a
+    ref[i] = qnorm(qmul(a, target.bind.worldRot[i]))
+    const deg = 2 * Math.acos(Math.min(1, Math.abs(a[3]))) * DEG
+    if (deg > 0.5) log.push({ bone: target.names[i], degrees: deg, via })
+  }
+  log.sort((a, b) => b.degrees - a.degrees)
+  under.sort((a, b) => b.degrees - a.degrees)
+  return { ref, A, log, kept, under }
+}
+
+/** A target bone sandwiched between mapped bones: its delta interpolates between theirs. */
+interface Bridge { above: number; below: number; u: number }
+
+const findBridges = (target: Rig, byTarget: Map<number, number>): Map<number, Bridge> => {
+  const children = childrenOf(target)
+  const subtreeSize = new Array(target.names.length).fill(1)
+  for (let k = target.order.length - 1; k >= 0; k--) {
+    const i = target.order[k]
+    if (target.parents[i] >= 0) subtreeSize[target.parents[i]] += subtreeSize[i]
+  }
+  // Nearest mapped descendant per bone — heaviest branch wins, like the direction heuristic.
+  const below = new Map<number, { idx: number; depth: number }>()
+  for (let k = target.order.length - 1; k >= 0; k--) {
+    const i = target.order[k]
+    let best: { idx: number; depth: number; size: number } | null = null
+    for (const c of children[i]) {
+      const cand = byTarget.has(c) ? { idx: c, depth: 1, size: subtreeSize[c] } : (() => { const b = below.get(c); return b ? { idx: b.idx, depth: b.depth + 1, size: subtreeSize[b.idx] } : null })()
+      if (cand && (!best || cand.size > best.size)) best = cand
+    }
+    if (best) below.set(i, { idx: best.idx, depth: best.depth })
+  }
+  const out = new Map<number, Bridge>()
+  for (const i of target.order) {
+    if (byTarget.has(i)) continue
+    const b = below.get(i)
+    if (!b) continue
+    // Nearest mapped ancestor, counting the steps.
+    let a = target.parents[i], up = 1
+    while (a >= 0 && !byTarget.has(a)) { a = target.parents[a]; up++ }
+    if (a < 0) continue
+    out.set(i, { above: a, below: b.idx, u: up / (up + b.depth) })
+  }
+  return out
+}
+
+/** A leg: the chain from the hip (child of a core bone) down to the bone that stands on the ground. */
+interface Leg {
+  chain: number[]        // target bones hip → … → parent of effector (at most 4)
+  effector: number       // target foot bone whose position is driven
+  donorHip: number; donorEffector: number
+  contact: number        // the bone whose position is matched to the donor's — the ball of a humanoid foot (a child of the effector), else the effector
+  donorContact: number
+  contactRatio: number   // target effector→contact length / the donor's (1 when the contact is the effector)
+  lengths: number[]      // target segment lengths along chain + effector (bind)
+  pole: Vec3 | null      // which way the chain bends in the bind pose (knee off the hip→foot line), world
+  ratio: number          // target leg length / donor leg length
+  name: string
+  isFoot: boolean        // the donor's effector stands on the donor's ground (else: a wrist-style end)
+  lockOnly?: boolean     // a hand that is an effector only while LOCKED to a ground contact (else FK)
+  baseTarget: number     // effector height in the grounded reference pose (its stance height)
+  baseDonor: number      // lowest the donor's effector gets over the clips taken (its stance height)
+  // Horizontal foot-under-hip offset in each rig's OWN reference pose. Rigs disagree about where a
+  // foot belongs under its hip — this fox tucks its feet 8% of body height inboard, every polyperfect
+  // animal stands on vertical legs — and that is build, not motion, so it must not transfer.
+  stanceTarget: Vec3
+  stanceDonor: Vec3      // the donor's, already scaled segment by segment (`donorReach`)
+  refReach: number       // hip→effector distance in the target's grounded reference pose (its stance extension)
+}
+
+/** How far off the hip→foot line the middle joints must sit (a fraction of the chain's length) before
+ *  the FK pose's own bend direction is trusted over the bind pose's — ~12° of knee for two equal segments. */
+const BEND_TRUST = 0.05
+/** The most a foot pitches about its ankle to lift its toes back onto the floor (rad). */
+const FOOT_PITCH_CAP = 20 * Math.PI / 180
+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] ]
+
+/**
+ * Leg chains from the map. A leg is a lateral chain of ≥3 mapped bones hanging off a core bone that
+ * reaches down into the lower half of the body (tails hang low too, but on the midline; ears and
+ * raised arms stay up). Its effector is the first bone from the hip that sits at the chain's lowest
+ * level — the ball of the foot, with any toes beyond it left to FK — or, on a chain that never
+ * reaches the ground on the donor (a horse whose front leg ends at the wrist), the chain's end.
+ * The chain above the effector is capped at four bones (scapula, thigh, shin, metatarsus) — anything
+ * further up stays FK and keeps the donor's motion instead of soaking up IK corrections. IK only
+ * ever spends the proportion residual, so how many joints share it is not visible.
+ */
+const detectLegs = (
+  target: Rig, donor: Rig, byTarget: Map<number, number>, refPos: Vec3[], explicit: string[] | undefined, warn: (m: string) => void, maxAbove = 4,
+): Leg[] => {
+  const children = childrenOf(target)
+  const mappedKids = (i: number): number[] => {
+    const out: number[] = []
+    const queue = [ ...children[i] ]
+    while (queue.length) { const c = queue.shift()!; if (byTarget.has(c)) out.push(c); else queue.push(...children[c]) }
+    return out
+  }
+  const mappedParent = (i: number): number => { let p = target.parents[i]; while (p >= 0 && !byTarget.has(p)) p = target.parents[p]; return p }
+  /** Mapped bones from the first bone below a branch point down to `leaf`. */
+  const chainTo = (leaf: number): number[] => {
+    const chain = [ leaf ]
+    let b = mappedParent(leaf)
+    while (b >= 0 && mappedKids(b).length === 1) { chain.unshift(b); b = mappedParent(b) }
+    return chain
+  }
+
+  let lo = [ Infinity, Infinity, Infinity ], hi = [ -Infinity, -Infinity, -Infinity ]
+  for (const p of refPos) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], p[k]); hi[k] = Math.max(hi[k], p[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
+
+  let candidates: { full: number[]; effector?: number }[]
+  if (explicit?.length) {
+    candidates = []
+    for (const n of explicit) {
+      const i = target.index.get(n)
+      if (i === undefined || !byTarget.has(i)) { warn(`legs: "${n}" is not a mapped target bone — skipped`); continue }
+      const full = chainTo(i)
+      if (full.length < 3) { warn(`legs: "${n}" has no chain of ≥2 mapped bones above it — skipped`); continue }
+      candidates.push({ full, effector: i })
+    }
+  } else {
+    const leaves = [ ...byTarget.keys() ].filter((i) => mappedKids(i).length === 0)
+    candidates = leaves
+      .filter((i) => Math.abs(refPos[i][0] - (lo[0] + hi[0]) / 2) > 0.02 * size)
+      .map((i) => ({ full: chainTo(i) }))
+      .filter((c) => c.full.length >= 3 && Math.min(...c.full.map((i) => refPos[i][1])) - lo[1] < 0.45 * height)
+  }
+
+  const legs: Leg[] = []
+  const seen = new Set<number>()
+  for (const cand of candidates) {
+    const full = cand.full
+    // Effector: the first bone at the chain's lowest level (ball of the foot), toes beyond it stay FK.
+    const lowest = Math.min(...full.map((i) => refPos[i][1]))
+    const e = cand.effector ?? full.find((i) => refPos[i][1] - lowest < 0.04 * height)!
+    if (seen.has(e)) continue
+    seen.add(e)
+    const k = full.indexOf(e)
+    if (k < 2) continue   // needs at least two bones above it to bend
+    // The IK chain is the ACTUAL skeleton path from the mapped hip down to the effector — unmapped
+    // (bridged) bones in between are real joints with real lengths and bend with the rest — capped
+    // at four bones above the effector.
+    const hipMapped = full[0]
+    const path: number[] = []
+    for (let b = target.parents[e]; b >= 0 && b !== target.parents[hipMapped]; b = target.parents[b]) path.unshift(b)
+    const chain = path.slice(Math.max(0, path.length - maxAbove))
+    const legFull = [ ...chain, e ]
+    const lengths: number[] = []
+    for (let j = 1; j < legFull.length; j++) lengths.push(len(sub(target.bind.worldPos[legFull[j]], target.bind.worldPos[legFull[j - 1]])))
+    // Donor counterpart of the chain root: the nearest mapped bone at or above it; donor length is
+    // measured along the donor's own skeleton path between the two.
+    let hipRef = chain[0]
+    while (hipRef >= 0 && !byTarget.has(hipRef)) hipRef = target.parents[hipRef]
+    const donorHip = byTarget.get(hipRef)!, donorEffector = byTarget.get(e)!
+    let dlen = 0
+    for (let b = donorEffector; b >= 0 && b !== donorHip; b = donor.parents[b]) {
+      const p = donor.parents[b]
+      if (p < 0) { dlen = 0; break }
+      dlen += len(sub(donor.bind.worldPos[b], donor.bind.worldPos[p]))
+    }
+    const dfull = [ donorHip, donorEffector ]
+    const tlen = lengths.reduce((a, b) => a + b, 0)
+    if (!(tlen > 0) || !(dlen > 0)) continue
+    // Bend direction of the bind pose: the middle joints' offset from the hip→foot line. A straight
+    // chain has none; the solver then falls back to "forward".
+    let pole: Vec3 | null = null
+    {
+      const hip = target.bind.worldPos[legFull[0]], foot = target.bind.worldPos[legFull[legFull.length - 1]]
+      const axis = unit(sub(foot, hip))
+      if (axis) {
+        const acc: Vec3 = [ 0, 0, 0 ]
+        for (let j = 1; j < legFull.length - 1; j++) {
+          const v = sub(target.bind.worldPos[legFull[j]], hip)
+          const d = v[0] * axis[0] + v[1] * axis[1] + v[2] * axis[2]
+          acc[0] += v[0] - axis[0] * d; acc[1] += v[1] - axis[1] * d; acc[2] += v[2] - axis[2] * d
+        }
+        if (len(acc) > 1e-3 * tlen) pole = unit(acc)
+      }
+    }
+    legs.push({
+      chain, effector: e, donorHip: dfull[0], donorEffector: dfull[dfull.length - 1], contact: e, donorContact: dfull[dfull.length - 1], contactRatio: 1, lengths, pole,
+      ratio: tlen / dlen, name: target.names[e], isFoot: true, baseTarget: 0, baseDonor: 0,
+      stanceTarget: [ 0, 0, 0 ], stanceDonor: [ 0, 0, 0 ], refReach: 0,
+    })
+  }
+  return legs
+}
+
+/** Swing-twist split: the angle (rad, signed) `q` turns about the unit axis `a`. */
+const twistAbout = (q: Quat, a: Vec3): number => {
+  const d = q[0] * a[0] + q[1] * a[1] + q[2] * a[2]
+  const ang = 2 * Math.atan2(d, q[3])
+  // Wrap to (−π, π]: the quaternion's double cover otherwise reads a small negative twist as ~2π.
+  return ang > Math.PI ? ang - 2 * Math.PI : ang < -Math.PI ? ang + 2 * Math.PI : ang
+}
+const axisAngle = (a: Vec3, ang: number): Quat => { const s = Math.sin(ang / 2); return [ a[0] * s, a[1] * s, a[2] * s, Math.cos(ang / 2) ] }
+
+/** A twist helper: a child of a limb bone, sitting `t` of the way along it, driven about its axis. */
+interface Twist { bone: number; parent: number; grand: number; child: number; t: number; axisLocal: Vec3; name: string; of: string }
+
+/** Foot-planting state of one leg across a clip's frames. */
+interface Plant { anchor: Vec3 | null; run: number; offset: Vec3; fade: number; since: number }
+
+/**
+ * FABRIK on a chain of joint positions (`p[0]` fixed) with segment lengths `seg`, toward `goal`.
+ * Starts from the given positions, so the bend plane of the FK pose is what gets preserved.
+ */
+const fabrik = (p: Vec3[], seg: number[], goal: Vec3, iterations = 48): void => {
+  const n = p.length
+  const root = p[0]
+  const total = seg.reduce((a, b) => a + b, 0)
+  const toGoal = sub(goal, root)
+  const dist = len(toGoal)
+  if (dist >= total * 0.9995) {
+    // Out of reach: straight line toward the goal (slightly short of full extension).
+    const d = unit(toGoal) ?? [ 0, -1, 0 ]
+    for (let i = 1; i < n; i++) p[i] = add(p[i - 1], scl(d, seg[i - 1] * 0.9995))
+    return
+  }
+  for (let it = 0; it < iterations; it++) {
+    // Backward: end effector onto the goal, pull the chain after it.
+    p[n - 1] = goal
+    for (let i = n - 2; i >= 0; i--) {
+      const d = unit(sub(p[i], p[i + 1])) ?? [ 0, 1, 0 ]
+      p[i] = add(p[i + 1], scl(d, seg[i]))
+    }
+    // Forward: root back home, push the chain after it.
+    p[0] = root
+    for (let i = 1; i < n; i++) {
+      const d = unit(sub(p[i], p[i - 1])) ?? [ 0, -1, 0 ]
+      p[i] = add(p[i - 1], scl(d, seg[i - 1]))
+    }
+    if (len(sub(p[n - 1], goal)) < total * 1e-6) break
+  }
+}
+
+/** Which donor pose the deltas are measured from. */
+export type DonorRef = 'bind' | 'auto' | { clip: string; time?: number }
+
+/**
+ * The donor rig with its `bind` replaced by the REFERENCE pose the deltas are measured against.
+ * The bind pose is the obvious anchor, but an exporter's bind is routinely a posture the clips
+ * never visit: the polyperfect wolf binds upright on vertical thighs and walks 10% lower with its
+ * thighs 30° forward — measured from the bind, every clip reads as "crouch and lean", and a target
+ * that keeps its own stance inherits that crouch. The MEAN pose of a locomotion clip (walk, else idle,
+ * else the longest) is the donor's actual neutral posture, so deltas from it are pure motion.
+ * Returns the rig to use and a label for the report.
+ */
+const donorReference = (donor: Rig, ref: DonorRef, fps: number): { rig: Rig; from: string } => {
+  if (ref === 'bind' || !donor.clips.length) return { rig: donor, from: 'bind' }
+  let clip: Clip | undefined, at: number | undefined
+  if (typeof ref === 'object') {
+    clip = donor.clips.find((c) => c.name === ref.clip)
+    if (!clip) return { rig: donor, from: 'bind' }
+    at = ref.time
+  } else {
+    const pick = (re: RegExp): Clip | undefined => donor.clips.filter((c) => re.test(c.name) && c.duration > 0).sort((a, b) => b.duration - a.duration)[0]
+    // A walk cycle is periodic and symmetric, so its mean is the cleanest neutral stance; an idle may
+    // sit, graze or look around for seconds at a time.
+    clip = pick(/walk/i) ?? pick(/idle|breath|stand/i) ?? [ ...donor.clips ].sort((a, b) => b.duration - a.duration)[0]
+  }
+  const n = donor.names.length
+  const rot: Quat[] = Array.from({ length: n }, () => [ 0, 0, 0, 0 ])
+  const pos: Vec3[] = Array.from({ length: n }, () => [ 0, 0, 0 ])
+  const frames = Math.max(2, Math.round(clip.duration * fps) + 1)
+  const times = at !== undefined ? [ at ] : Array.from({ length: frames }, (_, f) => (f / (frames - 1)) * clip.duration)
+  for (const t of times) {
+    const w = worldOf(donor, clip.sample(t))
+    for (let i = 0; i < n; i++) {
+      const q = w.rot[i], acc = rot[i]
+      // Hemisphere-align on the running sum so the average does not cancel.
+      const s = acc[0] * q[0] + acc[1] * q[1] + acc[2] * q[2] + acc[3] * q[3] < 0 ? -1 : 1
+      acc[0] += s * q[0]; acc[1] += s * q[1]; acc[2] += s * q[2]; acc[3] += s * q[3]
+      pos[i][0] += w.pos[i][0]; pos[i][1] += w.pos[i][1]; pos[i][2] += w.pos[i][2]
+    }
+  }
+  const k = 1 / times.length
+  const bind = { ...donor.bind, worldRot: rot.map((q) => qnorm(q)), worldPos: pos.map((p) => [ p[0] * k, p[1] * k, p[2] * k ] as Vec3) }
+  return { rig: { ...donor, bind }, from: at !== undefined ? `"${clip.name}" @ ${at}s` : `mean of "${clip.name}"` }
+}
+
+/**
+ * Retarget `donor`'s clips onto `target`, adding glTF Animations to the target's Document.
+ * `map` is target-bone -> donor-bone; `rootBone` names the target bone that receives root motion.
+ */
+export function retarget(target: DocRig, donorIn: Rig, map: BoneMap, rootBone: string | null, opts: RetargetOptions = {}): RetargetReport {
+  // A donor that faces another way is turned first, so "world" means the same thing on both sides.
+  const yaw = ((opts.donorYawDeg ?? 0) / DEG) / 2
+  const fps = opts.fps ?? 30
+  const turned = Math.abs(opts.donorYawDeg ?? 0) > 1e-6 ? rotateRig(donorIn, [ 0, Math.sin(yaw), 0, Math.cos(yaw) ]) : donorIn
+  // Key reduction is a size trade against the FEET: a 0.2° slerp tolerance per joint stacks to
+  // ~1 cm of toe motion at the end of a four-joint leg (a locked idle read 2–4 cm/s through it,
+  // 0.0 without, 0.8 at 0.05°). So the bones a foot hangs from — the hips and the leg chains —
+  // are reduced at `epsilonLegDeg` (0.01°: a planted toe stays within a millimetre); everything
+  // else (arms, fingers, spine) keeps the size-friendly tolerance.
+  const eps = opts.epsilon ?? 1e-4
+  const epsDeg = opts.epsilonDeg ?? 0.2
+  const epsLegDeg = opts.epsilonLegDeg ?? 0.01
+  const warn = opts.warn ?? (() => {})
+  const doc = target.doc
+
+  // Resolve the map to indices once, warning about names that do not exist on either side.
+  const pairs: { d: number; s: number; target: string; donor: string }[] = []
+  for (const [ tName, sName ] of Object.entries(map)) {
+    const d = target.index.get(tName), s = turned.index.get(sName)
+    if (d === undefined) { warn(`target has no bone "${tName}" — skipped`); continue }
+    if (s === undefined) { warn(`donor has no bone "${sName}" — target "${tName}" left at rest`); continue }
+    pairs.push({ d, s, target: tName, donor: sName })
+  }
+  const byTarget = new Map(pairs.map((p) => [ p.d, p.s ]))
+
+  const rootIdx = rootBone === null ? -1 : (target.index.get(rootBone) ?? -1)
+  if (rootBone !== null && rootIdx < 0) warn(`target has no root bone "${rootBone}" — no root motion`)
+  const donorRoot = rootIdx >= 0 ? byTarget.get(rootIdx) : undefined
+  // A root that shares its donor bone with another target bone (a `root` above the pelvis, both
+  // mapped to Mixamo's Hips) carries the travel only — the hips rotate, the root must not.
+  const rootTranslateOnly = rootIdx >= 0 && donorRoot !== undefined && pairs.some((p) => p.d !== rootIdx && p.s === donorRoot)
+
+  // Legs are found on the bind pose first: they decide how the donor is referenced and how their
+  // own bones are aligned (see below); their reference-pose geometry is filled in further down.
+  const legs = opts.ik === 'none' ? [] : detectLegs(target, turned, byTarget, target.bind.worldPos, opts.legs, warn)
+  const hum = opts.humanoid
+  const humIdx = (av: Avatar, k: HumanBone): number | undefined => { const n = av.bones[k]; return n === undefined ? undefined : target.index.get(n) }
+  const hipsIdx = hum ? humIdx(hum.target, 'Hips') ?? -1 : -1
+  // A humanoid foot's contact is its ball (header §6): the `Toes` bone right under the ankle, when
+  // both rigs have it mapped.
+  if (hum) for (const leg of legs) for (const s of [ 'Left', 'Right' ] as const) {
+    const foot = humIdx(hum.target, `${s}Foot`), toes = humIdx(hum.target, `${s}Toes`)
+    if (leg.effector === foot && toes !== undefined && byTarget.has(toes) && target.parents[toes] === foot) {
+      leg.contact = toes; leg.donorContact = byTarget.get(toes)!
+      const tf = len(sub(target.bind.worldPos[toes], target.bind.worldPos[foot])), df = len(sub(turned.bind.worldPos[leg.donorContact], turned.bind.worldPos[leg.donorEffector]))
+      leg.contactRatio = tf > 0 && df > 0 ? tf / df : 1
+    }
+  }
+  /** The donor's hip→contact vector scaled segment by segment: the leg by the leg ratio, the foot by its own. */
+  const donorReach = (leg: Leg, pos: Vec3[]): Vec3 => add(scl(sub(pos[leg.donorEffector], pos[leg.donorHip]), leg.ratio), scl(sub(pos[leg.donorContact], pos[leg.donorEffector]), leg.contactRatio))
+
+  // Which effectors are FEET is the donor's call: its effector stands on its ground over the clips
+  // taken (a horse's front leg ends at the wrist, which never does). Stance heights come with it.
+  const wanted = opts.clips?.length ? new Set(opts.clips) : null
+  const clips = turned.clips.filter((c) => !wanted || wanted.has(c.name))
+  let donorGround = 0
+  if (legs.length) {
+    for (const l of legs) l.baseDonor = Infinity
+    for (const clip of clips) {
+      const frames = Math.max(2, Math.round(clip.duration * fps) + 1)
+      for (let f = 0; f < frames; f++) {
+        const dw = worldOf(turned, clip.sample((f / (frames - 1)) * clip.duration))
+        for (const l of legs) l.baseDonor = Math.min(l.baseDonor, dw.pos[l.donorContact][1])
+      }
+    }
+    donorGround = Math.min(...legs.map((l) => l.baseDonor))
+    let dlo = Infinity, dhi = -Infinity
+    for (const p of turned.bind.worldPos) { dlo = Math.min(dlo, p[1]); dhi = Math.max(dhi, p[1]) }
+    for (const l of legs) {
+      // a humanoid's feet are feet by ROLE: on a stair take one foot may never come down to the
+      // clip's lowest ground (the up-loop's left foot lives a tread above it) — judged by reach
+      // it read as a hand, got no lock and no marks, and the staircase fit saw half the plants
+      const byRole = hum ? l.effector === humIdx(hum.target, 'LeftFoot') || l.effector === humIdx(hum.target, 'RightFoot') : false
+      l.isFoot = byRole || l.baseDonor - donorGround < 0.03 * (dhi - dlo || 1)
+    }
+  }
+
+  // Donor reference. If both binds put the legs the same way (same convention), bind-to-bind is the
+  // faithful transfer (an identity retarget reproduces the donor exactly); if they disagree by more
+  // than a few degrees, the conventions differ (an upright A-stance wolf, a naturally posed horse),
+  // and the donor's own standing posture — the mean of its idle/walk — is what the target's stance
+  // corresponds to.
+  let legDisagreement = 0
+  {
+    let n = 0
+    for (const leg of legs) for (const i of [ ...leg.chain, leg.effector ]) {
+      const kid = [ ...leg.chain, leg.effector ].find((c) => target.parents[c] === i || (() => { let p = target.parents[c]; while (p >= 0 && !byTarget.has(p)) p = target.parents[p]; return p === i })())
+      if (kid === undefined || !byTarget.has(kid) || !byTarget.has(i)) continue
+      const ut = unit(sub(target.bind.worldPos[kid], target.bind.worldPos[i]))
+      const us = unit(sub(turned.bind.worldPos[byTarget.get(kid)!], turned.bind.worldPos[byTarget.get(i)!]))
+      if (!ut || !us) continue
+      legDisagreement += Math.acos(Math.max(-1, Math.min(1, ut[0] * us[0] + ut[1] * us[1] + ut[2] * us[2]))) * DEG; n++
+    }
+    if (n) legDisagreement /= n
+  }
+  // A humanoid donor's clips are authored on its bind (Mixamo's T-pose, a pack's A-pose): that IS the reference.
+  const donorRefMode: DonorRef = opts.donorRef ?? (opts.humanoid ? 'bind' : legs.length && legDisagreement > 12 ? 'auto' : 'bind')
+  const { rig: donor, from: donorRefFrom } = donorReference(turned, donorRefMode, fps)
+  // Stance heights are relative to the reference pose too: a foot never lower than its reference.
+  // A humanoid's stance IS its bind (the T-pose stands on the ground): the foot's departure from
+  // that height is what transfers, so a foot planted on the donor lands on the target's own ground
+  // and an identity retarget stays exact (the clip's lowest toe — mid-roll — would put it 8 mm off).
+  for (const l of legs) l.baseDonor = opts.humanoid ? donor.bind.worldPos[l.donorContact][1] : Math.min(l.baseDonor, donor.bind.worldPos[l.donorContact][1])
+  if (legs.length) donorGround = Math.min(...legs.map((l) => l.baseDonor))
+  // …and so is the horizontal stance: where the donor plants its foot under its own hip.
+  for (const l of legs) l.stanceDonor = donorReach(l, donor.bind.worldPos)
+
+  // Alignment default. A target that binds in a STANCE — feet level, legs hanging down — keeps its
+  // bind everywhere: that is its natural posture (legs, neck, tail, ears included) and the donor's
+  // deltas ride on it. A target that binds posed (T-pose, legs folded) has no stance to keep: its
+  // core bones keep, its chains are turned to point the donor's way.
+  const policies: Record<string, AlignPolicy> = { ...(opts.alignTo ?? {}), ...(opts.alignBones ?? {}) }
+  // A person's word on the avatar (`transfer.align`): `keep` = built that way, `align` = posed —
+  // aligned to the donor whatever the threshold says. Bone-name policies above still win.
+  const forced = new Set<number>()
+  if (hum?.target.transfer?.align) for (const [ k, v ] of Object.entries(hum.target.transfer.align)) {
+    const n = hum.target.bones[k as HumanBone]
+    if (!n || n in policies) continue
+    const i = target.index.get(n)
+    if (i === undefined || !byTarget.has(i)) continue
+    if (v === 'keep') policies[n] = 'keep'
+    else forced.add(i)
+  }
+  // Humanoid: references by canonical ROLE (header §5). Torso, head and face keep; the arm chain and
+  // the fingers align to the donor with explicit references — each bone to the next canonical bone
+  // down its chain, the hand to the finger bases. Legs and feet fall to the stance rule below.
+  if (hum) {
+    const T = hum.target
+    const set = (k: HumanBone, pol: AlignPolicy): void => { const n = T.bones[k]; if (n !== undefined && !(n in policies) && target.index.has(n) && byTarget.has(target.index.get(n)!)) policies[n] = pol }
+    for (const k of [ 'Hips', 'Spine', 'Chest', 'UpperChest', 'Neck', 'Head', 'Jaw', 'LeftEye', 'RightEye' ] as HumanBone[]) set(k, 'keep')
+    const refTo = (k: HumanBone, ...tos: HumanBone[]): void => { const names = tos.map((t) => T.bones[t]).filter((n): n is string => !!n); set(k, names.length ? names : 'direction') }
+    for (const s of [ 'Left', 'Right' ] as const) {
+      refTo(`${s}Shoulder`, `${s}UpperArm`); refTo(`${s}UpperArm`, `${s}LowerArm`); refTo(`${s}LowerArm`, `${s}Hand`)
+      refTo(`${s}Hand`, `${s} Index Proximal`, `${s} Middle Proximal`, `${s} Ring Proximal`, `${s} Little Proximal`)
+      for (const f of [ 'Thumb', 'Index', 'Middle', 'Ring', 'Little' ] as const) {
+        refTo(`${s} ${f} Proximal`, `${s} ${f} Intermediate`); refTo(`${s} ${f} Intermediate`, `${s} ${f} Distal`); set(`${s} ${f} Distal`, 'direction')
+      }
+    }
+  }
+  let stance = legs.length > 0
+  if (legs.length) {
+    let lo = Infinity, hi = -Infinity
+    for (let i = 0; i < target.names.length; i++) if (target.bind.fromSkin[i]) { lo = Math.min(lo, target.bind.worldPos[i][1]); hi = Math.max(hi, target.bind.worldPos[i][1]) }
+    const height = hi - lo || 1
+    const footYs = legs.map((l) => target.bind.worldPos[l.contact][1])
+    const lowestFoot = Math.min(...footYs)
+    for (const leg of legs) {
+      const hipY = target.bind.worldPos[leg.chain[0]][1], footY = target.bind.worldPos[leg.contact][1]
+      const L = leg.lengths.reduce((a, b) => a + b, 0)
+      if ((hipY - footY) / L < 0.5) stance = false                               // not hanging down
+      if (leg.isFoot && footY - lowestFoot > 0.05 * height) stance = false       // feet not level
+    }
+  }
+  if (stance) for (const i of byTarget.keys()) { const name = target.names[i]; if (!(name in policies)) policies[name] = 'keep' }
+  else for (const leg of legs) for (const i of [ ...leg.chain, leg.effector ]) { const name = target.names[i]; if (!(name in policies)) policies[name] = 'direction' }
+  // A forced bone that the rules made `keep` (a leg in a stance, a torso bone) aligns by direction.
+  for (const i of forced) if (policies[target.names[i]] === 'keep') policies[target.names[i]] = 'direction'
+  const { ref, A, log: alignLog, kept, under: alignUnder } = alignReference(target, donor, byTarget, rootIdx, opts.align ?? 'bone-direction', policies, hum ? 8 : 0, forced)
+
+  // Hands as effectors (header §6): the same goal machinery as a foot, from the upper arm down,
+  // chain capped at upper + lower arm (the clavicle stays FK). Added after the stance decision —
+  // an arm never hangs like a leg — and never a foot.
+  // …and, on a humanoid, ALWAYS as lock-only effectors: a hand that the marks find on the ground (a
+  // cartwheel, a roll, a vault) is locked there like a foot, and follows FK everywhere else.
+  if (hum && opts.ik !== 'none') {
+    const handNames = [ 'LeftHand', 'RightHand' ].map((k) => hum.target.bones[k as HumanBone]).filter((n): n is string => !!n && byTarget.has(target.index.get(n)!))
+    for (const h of detectLegs(target, turned, byTarget, target.bind.worldPos, handNames, warn, 2)) {
+      h.isFoot = false
+      h.lockOnly = opts.ik !== 'legs+hands'
+      h.baseDonor = donor.bind.worldPos[h.donorContact][1]
+      h.stanceDonor = donorReach(h, donor.bind.worldPos)
+      legs.push(h)
+    }
+  }
+
+  // Bridges: unmapped bones between mapped ones. Their reference follows the chain ends' corrections.
+  const bridges = findBridges(target, byTarget)
+  if (hum) {
+    // A metacarpal is palm, not finger: it bridges hand → proximal phalanx but must ride the HAND
+    // rigidly (u = 0), not lean halfway into the finger's own alignment — that would carry the
+    // knuckles away from the palm and with them the roll readout below.
+    const hands = new Set([ humIdx(hum.target, 'LeftHand'), humIdx(hum.target, 'RightHand') ].filter((i): i is number => i !== undefined))
+    for (const b of bridges.values()) if (hands.has(b.above)) b.u = 0
+  }
+  for (const [ i, b ] of bridges) {
+    const a = qslerp(A[b.above], A[b.below], b.u)
+    A[i] = a
+    ref[i] = qnorm(qmul(a, target.bind.worldRot[i]))
+  }
+
+  // Humanoid palm roll (header §5): direction alignment leaves the roll about the arm wherever the
+  // shortest arc put it. The knuckle line (index base → little base), projected across the forearm
+  // axis, is the one readout of that roll every fingered rig has; the forearm chain turns about the
+  // forearm until the target's line lies where the donor's does. A rig without fingers on either side
+  // keeps whatever the arc gave, with a note.
+  const rollLog: RetargetReport['roll'] = []
+  if (hum && (opts.align ?? 'bone-direction') !== 'none') {
+    const pt = posesFrom(target, ref)
+    const D = hum.donor, T = hum.target
+    const dIdx = (k: HumanBone): number | undefined => { const n = D.bones[k]; return n === undefined ? undefined : donor.index.get(n) }
+    const children = childrenOf(target)
+    for (const s of [ 'Left', 'Right' ] as const) {
+      const tLower = humIdx(T, `${s}LowerArm`), tHand = humIdx(T, `${s}Hand`), dLower = dIdx(`${s}LowerArm`), dHand = dIdx(`${s}Hand`)
+      if (tLower === undefined || tHand === undefined || dLower === undefined || dHand === undefined) continue
+      const axisT = unit(sub(pt[tHand], pt[tLower])), axisD = unit(sub(donor.bind.worldPos[dHand], donor.bind.worldPos[dLower]))
+      if (!axisT || !axisD) continue
+      // Knuckle line on each side; the thumb base off the hand is the fallback readout.
+      const line = (av: Avatar, pos: Vec3[], idx: (k: HumanBone) => number | undefined, hand: number): { v: Vec3; via: string } | null => {
+        const i = idx(`${s} Index Proximal`), l = idx(`${s} Little Proximal`), th = idx(`${s} Thumb Proximal`)
+        if (i !== undefined && l !== undefined) return { v: sub(pos[i], pos[l]), via: 'knuckle line' }
+        if (th !== undefined) return { v: sub(pos[th], pos[hand]), via: 'thumb base' }
+        void av
+        return null
+      }
+      const kt = line(T, pt, (k) => humIdx(T, k), tHand), kd = line(D, donor.bind.worldPos, dIdx, dHand)
+      if (!kt || !kd) { warn(`${s.toLowerCase()} arm: no fingers on the ${kt ? 'donor' : 'target'} — palm roll not corrected`); continue }
+      // Both readouts projected across the DONOR's forearm axis (the target's is aligned to it).
+      const perp = (v: Vec3, ax: Vec3): Vec3 | null => { const d = v[0] * ax[0] + v[1] * ax[1] + v[2] * ax[2]; return unit([ v[0] - ax[0] * d, v[1] - ax[1] * d, v[2] - ax[2] * d ]) }
+      const a = perp(kt.v, axisD), b = perp(kd.v, axisD)
+      if (!a || !b) continue
+      const cross: 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] ]
+      // …plus what a person added on the avatar (`transfer.roll`, degrees, per arm).
+      const ang = Math.atan2(cross[0] * axisD[0] + cross[1] * axisD[1] + cross[2] * axisD[2], a[0] * b[0] + a[1] * b[1] + a[2] * b[2]) + (hum.target.transfer?.roll?.[s] ?? 0) / DEG
+      const deg = Math.abs(ang) * DEG
+      if (deg < 1) { rollLog.push({ side: s, degrees: 0, via: kt.via }); continue }
+      const R: Quat = qnorm([ axisD[0] * Math.sin(ang / 2), axisD[1] * Math.sin(ang / 2), axisD[2] * Math.sin(ang / 2), Math.cos(ang / 2) ])
+      // The forearm and everything below it (hand, fingers, twist helpers by inheritance) — a roll
+      // is forearm pronation, so the elbow, not the shoulder, absorbs it.
+      const stack = [ tLower ]
+      while (stack.length) { const i = stack.pop()!; ref[i] = qnorm(qmul(R, ref[i])); A[i] = qnorm(qmul(ref[i], qinv(target.bind.worldRot[i]))); stack.push(...children[i]) }
+      rollLog.push({ side: s, degrees: deg, via: `${kt.via} vs ${kd.via}` })
+    }
+  }
+
+  // The reference pose on the ground. Straightening a crouched rig lifts it, so the root is first put
+  // back down until the lowest joint sits where the bind's lowest joint did (the ground). Then, with
+  // legs known, every FOOT is planted: the root comes down further if some leg could not reach the
+  // ground even straight, and each leg is bent onto it (`placeLeg`) — a standing reference means
+  // all feet on the ground, not just the lowest one, and the foot goals below assume exactly that.
+  // Which effectors are feet is the DONOR's call: its effector stands on its ground over the clips.
+  const refPos = posesFrom(target, ref)
+  const skinned = target.bind.fromSkin.map((v, i) => (v ? i : -1)).filter((i) => i >= 0)
+  const lowestBind = Math.min(...skinned.map((i) => target.bind.worldPos[i][1]))
+  const donorChildren = childrenOf(donor)
+  const donorSkinned = donor.bind.fromSkin.some(Boolean) ? donor.bind.fromSkin.map((v, i) => (v ? i : -1)).filter((i) => i >= 0) : donor.names.map((_, i) => i)
+  const donorLowestBind = Math.min(...donorSkinned.map((i) => donor.bind.worldPos[i][1]))
+  const ground: { target: number; donor: number } | null = legs.length ? { target: lowestBind, donor: donorGround } : null
+  const feet = legs.filter((l) => l.isFoot)
+  // Where a foot's contact rests above the ground: at its bind height when the target binds in a
+  // stance (a ball sits on the ground; an ankle standing in for it is 10–12 cm up), on the ground
+  // when the bind is posed (nothing to keep — the contact is the lowest bone of its chain anyway).
+  const restAbove = (leg: Leg): number => (stance ? target.bind.worldPos[leg.contact][1] - lowestBind : 0)
+  let groundOffset = feet.length ? lowestBind - Math.min(...feet.map((l) => refPos[l.contact][1] - restAbove(l))) : lowestBind - Math.min(...skinned.map((i) => refPos[i][1]))
+  // A leg that cannot reach the ground even at 98% extension pulls the whole body down — a POSED
+  // bind's problem; a stance bind stands on its own legs, however straight (Mixamo's are).
+  if (!stance) for (const leg of feet) {
+    const hipY = refPos[leg.chain[0]][1] + groundOffset
+    const reach = 0.98 * leg.lengths.reduce((a, b) => a + b, 0)
+    const floor = lowestBind + restAbove(leg)
+    if (hipY - floor > reach) groundOffset -= hipY - floor - reach
+  }
+  const refPosGrounded = refPos.map((p) => [ p[0], p[1] + groundOffset, p[2] ] as Vec3)
+
+  // Bone offsets in the parent's BIND frame — the target's own proportions, re-applied every frame.
+  const localOff: Vec3[] = target.names.map((_, i) => {
+    const p = target.parents[i]
+    if (p < 0) return [ 0, 0, 0 ]
+    return qrot(qinv(target.bind.worldRot[p]), sub(target.bind.worldPos[i], target.bind.worldPos[p]))
+  })
+  const children = childrenOf(target)
+
+  /**
+   * Bend one leg so its effector lands on `goal`, in place: FABRIK from the current joint positions,
+   * then each chain bone turned so its segment points at the solved joint (top-down, so the bend
+   * plane of the starting pose is what survives). The effector keeps its world orientation; the
+   * positions of everything below the chain are re-placed. Returns how far (m) the goal was out of reach.
+   */
+  /** The donor's own bend: its chain's middle joints off its hip→effector line, in WORLD (the donor is
+   *  turned to face the target), and how far off relative to its chain length. Smooth where the FK's
+   *  is noise — a near-straight leg's knee sits millimetres off the line in whatever direction the
+   *  transferred rotations' rounding left it, and that direction swings frame to frame. */
+  const donorBend = (leg: Leg, dpos: Vec3[]): { dir: Vec3; off: number } | null => {
+    const hip = dpos[leg.donorHip], end = dpos[leg.donorEffector]
+    const axis = unit(sub(end, hip))
+    if (!axis) return null
+    const acc: Vec3 = [ 0, 0, 0 ]
+    let n = 0
+    for (let k = 1; k < leg.chain.length; k++) {
+      const d = byTarget.get(leg.chain[k])
+      if (d === undefined) continue
+      const v = sub(dpos[d], hip), t = v[0] * axis[0] + v[1] * axis[1] + v[2] * axis[2]
+      acc[0] += v[0] - axis[0] * t; acc[1] += v[1] - axis[1] * t; acc[2] += v[2] - axis[2] * t; n++
+    }
+    const dir = n ? unit(acc) : null
+    return dir ? { dir, off: len(acc) / n / donorLegLen(leg) } : null
+  }
+  const placeLeg = (leg: Leg, goal: Vec3, rot: Quat[], pos: Vec3[], bend: { dir: Vec3; off: number; axisW?: Vec3; sign?: number } | null = null): number => {
+    const full = [ ...leg.chain, leg.effector ]
+    const hip = pos[leg.chain[0]]
+    const pts = full.map((i) => [ ...pos[i] ] as Vec3)
+    const total = leg.lengths.reduce((a, b) => a + b, 0)
+    const short = len(sub(goal, hip)) - total
+    // FABRIK keeps the bend plane it starts from, and a NEAR-straight chain has no reliable one:
+    // the middle joints sit a millimetre off the hip→foot line in whatever direction the FK's
+    // rounding left them, and a goal a centimetre short of full extension turns that millimetre
+    // into a 20° bend — backwards as readily as forwards (a knee flipping behind the leg for a
+    // whole stance phase). So the bend direction is the BIND pose's (`pole`, turned with the hip)
+    // whenever the chain is nearly straight, the FK's own when it is clearly bent (≥ ~12°, where the
+    // direction is real), blended in between; a bend against the pole never counts — a knee or an
+    // elbow has one way to fold. The middle joints are moved onto that direction, sagged by what
+    // the goal needs, so FABRIK converges instead of crawling off the line.
+    const axis = unit(sub(pts[pts.length - 1], hip))
+    if (axis && short < 0) {
+      const hipTurn = qmul(rot[leg.chain[0]], qinv(target.bind.worldRot[leg.chain[0]]))
+      const pole = leg.pole ? qrot(hipTurn, leg.pole) : [ 0, 0, 1 ] as Vec3
+      const acc: Vec3 = [ 0, 0, 0 ]
+      for (let k = 1; k < pts.length - 1; k++) {
+        const v = sub(pts[k], hip), d = v[0] * axis[0] + v[1] * axis[1] + v[2] * axis[2]
+        acc[0] += v[0] - axis[0] * d; acc[1] += v[1] - axis[1] * d; acc[2] += v[2] - axis[2] * d
+      }
+      // The donor's bend direction where it has one (the knee bends the way the donor's knee bends);
+      // the FK's own otherwise.
+      const off = bend ? bend.off * total : len(acc) / (pts.length - 2)
+      // The bend DIRECTION: from the calibrated HINGE when the leg has one (the knee is a hinge, so
+      // the donor's thigh rotation times the hinge axis is the bend plane — exact however straight
+      // the leg, the engine's method); else the donor's position-derived offset, which is noise on a
+      // straight leg and therefore blended with the bind pole below 12° of bend.
+      let cur: Vec3 | null = null, w = 0
+      if (bend?.axisW) {
+        const toGoal = unit(sub(goal, hip))
+        const c = toGoal ? unit(cross(bend.axisW, toGoal)) : null
+        if (c) { cur = scl(c, bend.sign ?? 1); w = 1 }
+      }
+      if (!cur) {
+        cur = bend ? bend.dir : unit(acc)
+        const against = cur ? cur[0] * pole[0] + cur[1] * pole[1] + cur[2] * pole[2] < 0 : false
+        w = cur && !against ? Math.min(1, off / (BEND_TRUST * total)) : 0
+      }
+      if (w < 1) {
+        const dir = unit(add(scl(pole, 1 - w), scl(cur ?? pole, w))) ?? pole
+        const dist = len(sub(goal, hip))
+        const sag = Math.max(off, 1e-3 * total, 0.5 * Math.sqrt(Math.max(0, total * total - dist * dist)))
+        for (let k = 1; k < pts.length - 1; k++) {
+          const v = sub(pts[k], hip), d = v[0] * axis[0] + v[1] * axis[1] + v[2] * axis[2]
+          pts[k] = add(add(hip, scl(axis, d)), scl(dir, sag))
+        }
+      }
+    }
+    fabrik(pts, leg.lengths, goal)
+    for (let k = 0; k < leg.chain.length; k++) {
+      const i = leg.chain[k], next = full[k + 1]
+      const cur = unit(qrot(rot[i], localOff[next])), want = unit(sub(pts[k + 1], pos[i]))
+      if (cur && want) rot[i] = qnorm(qmul(arc(cur, want), rot[i]))
+      pos[next] = add(pos[i], qrot(rot[i], localOff[next]))
+    }
+    const stack = [ leg.effector ]
+    while (stack.length) {
+      const i = stack.pop()!
+      for (const c of children[i]) { pos[c] = add(pos[i], qrot(rot[i], localOff[c])); stack.push(c) }
+    }
+    return short
+  }
+  // Plant every foot in the reference pose (the chain bones' reference orientations change with it);
+  // every effector's grounded reference height is then its stance height.
+  for (const leg of feet) {
+    const c = refPosGrounded[leg.contact], floor = lowestBind + restAbove(leg)
+    if (Math.abs(c[1] - floor) < 1e-6) continue
+    const e = refPosGrounded[leg.effector]   // the effector moves by what its contact is short of the floor
+    placeLeg(leg, [ e[0], e[1] + floor - c[1], e[2] ], ref, refPosGrounded)
+  }
+  for (const leg of legs) {
+    leg.baseTarget = refPosGrounded[leg.contact][1]
+    leg.stanceTarget = sub(refPosGrounded[leg.contact], refPosGrounded[leg.chain[0]])
+    leg.refReach = len(sub(refPosGrounded[leg.effector], refPosGrounded[leg.chain[0]]))
+  }
+  for (const i of byTarget.keys()) A[i] = qnorm(qmul(ref[i], qinv(target.bind.worldRot[i])))
+
+  // Twist helpers (header §6): the avatar's helpers that are children of a limb bone with a
+  // canonical child to measure the far end's twist against.
+  const twists: Twist[] = []
+  const twistFraction = opts.twist === false ? 0 : opts.twist ?? 0.5
+  if (hum && twistFraction > 0) {
+    const NEXT: Partial<Record<HumanBone, HumanBone>> = {
+      LeftUpperArm: 'LeftLowerArm', LeftLowerArm: 'LeftHand', RightUpperArm: 'RightLowerArm', RightLowerArm: 'RightHand',
+      LeftUpperLeg: 'LeftLowerLeg', LeftLowerLeg: 'LeftFoot', RightUpperLeg: 'RightLowerLeg', RightLowerLeg: 'RightFoot',
+    }
+    for (const [ name, of ] of Object.entries(hum.target.twist)) {
+      const h = target.index.get(name), p = humIdx(hum.target, of), nxt = NEXT[of], c = nxt ? humIdx(hum.target, nxt) : undefined
+      if (h === undefined || p === undefined || c === undefined || target.parents[h] !== p || !byTarget.has(p) || !byTarget.has(c)) continue
+      let g = target.parents[p]
+      while (g >= 0 && !byTarget.has(g)) g = target.parents[g]
+      if (g < 0) continue
+      const axis = unit(sub(target.bind.worldPos[c], target.bind.worldPos[p]))
+      if (!axis) continue
+      const along = sub(target.bind.worldPos[h], target.bind.worldPos[p])
+      const t = Math.max(0, Math.min(1, (along[0] * axis[0] + along[1] * axis[1] + along[2] * axis[2]) / len(sub(target.bind.worldPos[c], target.bind.worldPos[p]))))
+      twists.push({ bone: h, parent: p, grand: g, child: c, t, axisLocal: qrot(qinv(target.bind.worldRot[p]), axis), name, of })
+    }
+  }
+
+  // Where the travel goes (header §6). A root above the hips: the horizontal travel on it, the bob
+  // on the hips; no such root: the hips carry everything as the donor's did.
+  const separateRoot = rootIdx >= 0 && hipsIdx >= 0 && hipsIdx !== rootIdx && donorRoot !== undefined
+  const rootMotion: Exclude<RootMotion, 'auto'> = (opts.rootMotion ?? 'auto') === 'auto' ? (separateRoot ? 'root' : 'hips') : opts.rootMotion as Exclude<RootMotion, 'auto'>
+  // The root's heading (header §6): only a root that takes the hips' travel can take their turn.
+  const donorHipsForYaw = hum ? (() => { const n = hum.donor.bones.Hips; return n === undefined ? undefined : donor.index.get(n) })() : undefined
+  const rootRotation: 'none' | 'yaw' = (opts.rootRotation ?? 'none') === 'yaw' && rootTranslateOnly && donorHipsForYaw !== undefined ? 'yaw' : 'none'
+  if ((opts.rootRotation ?? 'none') === 'yaw' && rootRotation === 'none') warn(`rootRotation 'yaw' needs a target root above the hips mapped to the donor's hips${hum ? '' : ' (humanoid avatars)'} — the root keeps its bind heading`)
+  /** The donor hips' heading about the up axis, from their bind: where the hips' forward points. */
+  const hipsHeading = (dwRot: Quat[]): number => {
+    const q = qmul(dwRot[donorHipsForYaw!], qinv(donor.bind.worldRot[donorHipsForYaw!]))
+    const f = qrot(q, [ 0, 0, 1 ])
+    return Math.atan2(f[0], f[2])
+  }
+  const wrapRad = (a: number): number => Math.atan2(Math.sin(a), Math.cos(a))
+  // A donor whose hips bob relative to their own root (MoCap Central's `root` + `pelvis`) — that bob
+  // is motion the rotation transfer cannot carry, so it is re-applied on the target's hips.
+  const donorHips = hum ? (() => { const n = hum.donor.bones.Hips; return n === undefined ? undefined : donor.index.get(n) })() : undefined
+  const donorBob = separateRoot && donorHips !== undefined && donorHips !== donorRoot && donor.parents[donorHips] >= 0
+  const hipsParent = hipsIdx >= 0 ? target.parents[hipsIdx] : -1
+
+
+  // Root motion is a distance, so it scales with the size difference between the two animals — a
+  // stride is leg length, so legs set it when known; the root heights are the fallback.
+  let rootScaleFrom: RetargetReport['rootScaleFrom'] = 'none'
+  const rootScale = (() => {
+    if (opts.rootScale !== undefined) { rootScaleFrom = 'option'; return opts.rootScale }
+    if (rootIdx < 0 || donorRoot === undefined) return 1
+    // the FEET's ratio: a stride is leg length. The hands are effectors too (`legs` holds them) but
+    // an arm ratio has no say in the travel — averaged in, it scaled Kachujin's ×1.17 down to ×1.10
+    const striders = feet.length ? feet : legs
+    if (striders.length) { rootScaleFrom = 'legs'; return striders.reduce((a, l) => a + l.ratio, 0) / striders.length }
+    const th = target.bind.worldPos[rootIdx][1], dh = donor.bind.worldPos[donorRoot][1]
+    rootScaleFrom = 'height'
+    return dh !== 0 ? th / dh : 1
+  })()
+
+  // The target root's parent is static, so its inverse is computed once and reused every frame.
+  const rootParent = rootIdx >= 0 ? target.parents[rootIdx] : -1
+  const restWorld = worldOf(target, target.rest)
+  const parentRot = rootParent >= 0 ? restWorld.rot[rootParent] : IDENT
+  const parentPos = rootParent >= 0 ? restWorld.pos[rootParent] : ([ 0, 0, 0 ] as Vec3)
+  const parentScale = rootParent >= 0 ? restWorld.scale[rootParent] : 1
+
+  const report: RetargetReport = {
+    bindGap: { donor: bindVsRest(turned), target: bindVsRest(target) },
+    donorRef: donorRefFrom,
+    legDisagreement,
+    stance,
+    align: alignLog,
+    underThreshold: alignUnder,
+    kept,
+    bridges: [ ...bridges.keys() ].map((i) => target.names[i]),
+    groundOffset,
+    ground,
+    legs: legs.map((l) => ({ effector: l.name, donorEffector: donor.names[l.donorEffector], contact: target.names[l.contact], chain: l.chain.map((i) => target.names[i]), ratio: l.ratio, shortfall: 0, isFoot: l.isFoot, planted: 0 })),
+    clips: [],
+    mapped: pairs.map((p) => ({ target: p.target, donor: p.donor })),
+    unmappedTarget: target.names.filter((n, i) => !byTarget.has(i) && !bridges.has(i) && target.nodes[i].getMesh() === null),
+    rootScale,
+    rootScaleFrom,
+    root: rootIdx >= 0 && donorRoot !== undefined ? { target: target.names[rootIdx], donor: donor.names[donorRoot] } : null,
+    rootTranslateOnly,
+    roll: rollLog,
+    rootMotion,
+    rootRotation,
+    hipsBob: separateRoot ? (donorBob ? 'donor' : rootMotion === 'hips' ? null : 'root') : null,
+    twist: twists.map((t) => ({ bone: t.name, of: t.of, at: t.t })),
+  }
+
+  const animated = new Set<number>([ ...byTarget.keys(), ...bridges.keys(), ...twists.map((t) => t.bone) ])
+  const rootRefPos = rootIdx >= 0 ? refPosGrounded[rootIdx] : null
+  const plantOn = opts.plant !== false
+  // Planting thresholds scale with the donor's leg: a foot moving under 30 % of a leg length per
+  // second, within 6 % of a leg length of its stance height, is standing on the ground.
+  const donorLegLen = (l: Leg): number => len(sub(donor.bind.worldPos[l.donorEffector], donor.bind.worldPos[l.donorHip])) || 1
+  // The donor leg's FULL length (its segments summed) — the extension fraction is measured against
+  // this, not against the bind's hip→ankle DISTANCE: a bind with bent knees (the UE4 mannequin,
+  // ~7°) made a relaxed stand read as "fully extended" and the target, whose bind is straight,
+  // reproduced its own bind's straightness instead of the donor's bend (Fidget V1 knees at 0°).
+  const donorLegSum = (l: Leg): number => {
+    const js = [ ...l.chain.map((i) => byTarget.get(i)), l.donorEffector ]
+    let sum = 0
+    for (let k = 1; k < js.length; k++) { const a = js[k - 1], b = js[k]; if (a === undefined || b === undefined) return donorLegLen(l); sum += len(sub(donor.bind.worldPos[b], donor.bind.worldPos[a])) }
+    return sum || donorLegLen(l)
+  }
+  const PLANT_FADE = 4
+
+  const driven = new Set<number>([ ...byTarget.keys(), ...bridges.keys() ])
+  // How far above the FLOOR each rig's hand reaches standing (bind: the hips' height over the
+  // lowest foot + the shoulder's height over the hips + the arm's two segments), target over donor. A PLATFORM a take's hands hold or push on must stay within
+  // this reach: its height comes across scaled by the LEGS (the root's vertical travel), and on a
+  // rig whose legs grew 17 % but whose overhead reach only 3 % the ledge ended 36 cm past the
+  // hands (the hang from the floor). Such takes scale their vertical travel by the smaller ratio.
+  let reachRatio = rootScale
+  if (hum) {
+    const reach = (rig: Rig, av: Avatar): number | null => {
+      const idx = (k: HumanBone): number | undefined => { const n = av.bones[k]; return n === undefined ? undefined : rig.index.get(n) }
+      const hips = idx('Hips'), arm = idx('LeftUpperArm'), fore = idx('LeftLowerArm'), hand = idx('LeftHand'), foot = idx('LeftFoot'), toes = idx('LeftToes')
+      if (hips === undefined || arm === undefined || fore === undefined || hand === undefined || foot === undefined) return null
+      const P = rig.bind.worldPos
+      const floor = Math.min(P[foot][1], toes !== undefined ? P[toes][1] : P[foot][1])
+      return (P[hips][1] - floor) + (P[arm][1] - P[hips][1]) + len(sub(P[fore], P[arm])) + len(sub(P[hand], P[fore]))
+    }
+    const rt = reach(target, hum.target), rd = reach(donor, hum.donor)
+    if (rt && rd) reachRatio = rt / rd
+    if (process.env.LECODES_MARKS_TRACE) console.log(`[marks] standing reach target ${rt?.toFixed(3)} donor ${rd?.toFixed(3)} → ratio ${reachRatio.toFixed(3)} (root scale ${rootScale.toFixed(3)})`)
+  }
+  // the bones a foot's position depends on: the hips / root and every leg chain (tight key reduction)
+  const legBones = new Set<number>()
+  for (const l of legs) { for (const i of l.chain) legBones.add(i); legBones.add(l.effector); legBones.add(l.contact) }
+  if (legBones.size) { if (hipsIdx >= 0) legBones.add(hipsIdx); if (rootIdx >= 0) legBones.add(rootIdx) }
+
+  // ---- knee hinge axes (per leg, once per pack — the engine's calibration, curves.cpp) ----------
+  // The bend plane the leg solver used to derive from the donor's knee POSITION is noise exactly
+  // where a lock operates: a relaxed stand's knee sits millimetres off the hip→ankle line and that
+  // direction swings frame to frame (Fidget V1: the knee flicked 0–9° at 2.3°/frame, the donor's
+  // moved 0.07°/frame). The knee is a hinge, so the axis of ANY delta between two of its local
+  // rotations is the hinge axis in the thigh's frame — exact however small the step. Calibrated
+  // over every clip's knee track (angle-weighted, sign-aligned, measurements > 30° off the mean
+  // trimmed); the bend direction at a frame is then sign · (R_donorThigh · h) × (hip → goal), the
+  // sign fixed once from the frames where the donor's knee is clearly bent.
+  const hinges = new Map<number, { axis: Vec3; sign: number }>()
+  for (const [ li, leg ] of legs.entries()) {
+    if (leg.chain.length < 2) continue
+    const dThigh = byTarget.get(leg.chain[0]), dKnee = byTarget.get(leg.chain[1])
+    if (dThigh === undefined || dKnee === undefined) continue
+    const meas: { axis: Vec3; w: number }[] = []
+    let acc: Vec3 = [ 0, 0, 0 ]
+    const kMinStep = 0.5 * Math.PI / 180
+    for (const clip of clips) {
+      const n = Math.max(2, Math.round(clip.duration * fps) + 1)
+      let prev = clip.sample(0).r[dKnee]
+      for (let k = 1; k < n; k++) {
+        const q = clip.sample((k / (n - 1)) * clip.duration).r[dKnee]
+        let d = qnorm(qmul(q, qinv(prev)))
+        prev = q
+        if (d[3] < 0) d = [ -d[0], -d[1], -d[2], -d[3] ]
+        const sl = Math.hypot(d[0], d[1], d[2])
+        const ang = 2 * Math.atan2(sl, d[3])
+        if (ang < kMinStep || sl < 1e-6) continue
+        let axis: Vec3 = [ d[0] / sl, d[1] / sl, d[2] / sl ]
+        if (axis[0] * acc[0] + axis[1] * acc[1] + axis[2] * acc[2] < 0) axis = scl(axis, -1)
+        acc = add(acc, scl(axis, ang))
+        meas.push({ axis, w: ang })
+      }
+    }
+    if (meas.length < 8 || len(acc) < 1e-5) continue
+    let h = unit(acc)!
+    for (let pass = 0; pass < 2; pass++) {
+      acc = [ 0, 0, 0 ]
+      for (const m of meas) {
+        if (m.axis[0] * h[0] + m.axis[1] * h[1] + m.axis[2] * h[2] < 0) m.axis = scl(m.axis, -1)
+        if (pass === 1 && Math.acos(Math.max(-1, Math.min(1, m.axis[0] * h[0] + m.axis[1] * h[1] + m.axis[2] * h[2]))) > 30 * Math.PI / 180) continue
+        acc = add(acc, scl(m.axis, m.w))
+      }
+      h = unit(acc) ?? h
+    }
+    // the sign: where the donor's knee is clearly off its hip→ankle line, does (axis × line) point to it?
+    let vote = 0
+    const L = donorLegLen(leg)
+    for (const clip of clips) {
+      const n = Math.max(2, Math.round(clip.duration * fps) + 1)
+      for (let k = 0; k < n; k += 4) {
+        const dw = worldOf(donor, clip.sample((k / (n - 1)) * clip.duration))
+        const line = unit(sub(dw.pos[leg.donorEffector], dw.pos[leg.donorHip]))
+        if (!line) continue
+        const v = sub(dw.pos[dKnee], dw.pos[leg.donorHip])
+        const t = v[0] * line[0] + v[1] * line[1] + v[2] * line[2]
+        const offv = sub(v, scl(line, t))
+        if (len(offv) < 0.05 * L) continue
+        const c = cross(qrot(dw.rot[dThigh], h), line)
+        vote += (c[0] * offv[0] + c[1] * offv[1] + c[2] * offv[2]) > 0 ? 1 : -1
+      }
+    }
+    hinges.set(li, { axis: h, sign: vote >= 0 ? 1 : -1 })
+  }
+  /** The bend the leg solver gets: the donor's offset magnitude, and the calibrated hinge's direction when there is one. */
+  const bendOf = (li: number, leg: Leg, dw: ReturnType<typeof worldOf>): { dir: Vec3; off: number; axisW?: Vec3; sign?: number } | null => {
+    const b = donorBend(leg, dw.pos)
+    const hg = hinges.get(li)
+    if (!hg) return b
+    const dThigh = byTarget.get(leg.chain[0])!
+    return { dir: b?.dir ?? [ 0, 0, 1 ], off: b?.off ?? 0, axisW: qrot(dw.rot[dThigh], hg.axis), sign: hg.sign }
+  }
+  const hipsParentScale = hipsParent >= 0 ? restWorld.scale[hipsParent] : 1
+
+  for (const clip of clips) {
+    const frames = Math.max(2, Math.round(clip.duration * fps) + 1)
+    // the vertical scale of this clip's root travel: the legs' (rootScale), except a PLATFORM take,
+    // whose platform must stay within the hands' reach too
+    const vScale = (opts.stairs ? opts.stairs(clip.name) : false) === 'platform' ? Math.min(rootScale, reachRatio) : rootScale
+    const channels = new Map<number, Channel>()
+    const chan = (node: number): Channel => {
+      let c = channels.get(node)
+      if (!c) { c = { node, times: [] }; channels.set(node, c) }
+      return c
+    }
+    const events: RetargetEvent[] = []
+    const open = new Map<string, RetargetEvent>()
+    const mark = (kind: RetargetEvent['kind'], bone: string, time: number, value?: number, at?: Vec3): void => {
+      const key = `${kind}:${bone}`
+      const e = open.get(key)
+      if (e) { e.to = time; if (value !== undefined) e.value = Math.max(e.value ?? 0, value) }
+      else { const n: RetargetEvent = { kind, bone, from: time, to: time, ...(value !== undefined ? { value } : {}), ...(at ? { at } : {}) }; open.set(key, n); events.push(n) }
+    }
+    // the root's horizontal position per frame: contacts are expressed relative to it, the travel is its displacement
+    const rootXZ = (): Vec3 => (rootIdx >= 0 ? wpos[rootIdx] : hipsIdx >= 0 ? wpos[hipsIdx] : [ 0, 0, 0 ])
+    let rootFirst: Vec3 = [ 0, 0, 0 ], rootLast: Vec3 = [ 0, 0, 0 ]
+    // per frame, for the contacts block: the root's position and each foot's contact bone (after placement)
+    const rootTrack: Vec3[] = []
+    const hipsYawTrack: number[] = []   // the hips' world yaw per output frame (radians), for the heading curve
+    const contactTrack = new Map<number, Vec3[]>()
+    // …and the whole body + the pelvis (after placement): the platform's face is fitted on the OUTPUT
+    const bodyTrack: Vec3[][] = [], hipsTrack: Vec3[] = []
+    const ankleTrack = new Map<number, Vec3[]>()   // the feet's ankles (the heel's witness for the ledge)
+    let dHeadingAll: number[] = []   // the donor's heading per frame (pass 1), for the platform fit's facing fallback
+
+    // Per frame: pose the donor, then walk the target top-down so every parent's retargeted world
+    // rotation is already known when its children need it; then place the feet; then emit locals.
+    const wrot: Quat[] = new Array(target.names.length)
+    const wpos: Vec3[] = new Array(target.names.length)
+    const delta: Quat[] = new Array(target.names.length)
+    const timeOf = (f: number): number => (f / (frames - 1)) * clip.duration
+    // The root's turn (rootRotation 'yaw'): the hips' heading since the clip's first frame goes on
+    // the root as a rotation about the up axis; the hips' world rotation is untouched, so their local
+    // rotation loses exactly that turn (the engine takes it off the pose and onto the node).
+    const yaw0 = rootRotation === 'yaw' ? hipsHeading(worldOf(donor, clip.sample(0)).rot) : 0
+    const turn = rootRotation === 'yaw' ? wrapRad(hipsHeading(worldOf(donor, clip.sample(clip.duration)).rot) - yaw0) * DEG : 0
+    /** The donor posed and the target's FK for frame `f` (everything but the effectors). */
+    const frameFK = (f: number): { dw: ReturnType<typeof worldOf> } => {
+      const donorPose: Pose = clip.sample(timeOf(f))
+      const dw = worldOf(donor, donorPose)
+      for (const i of byTarget.keys()) { const s = byTarget.get(i)!; delta[i] = qmul(dw.rot[s], qinv(donor.bind.worldRot[s])) }
+      if (rootTranslateOnly) {
+        if (rootRotation === 'yaw') { const y = wrapRad(hipsHeading(dw.rot) - yaw0); delta[rootIdx] = [ 0, Math.sin(y / 2), 0, Math.cos(y / 2) ] }
+        else delta[rootIdx] = IDENT
+      }
+      for (const [ i, b ] of bridges) delta[i] = qslerp(delta[b.above], delta[b.below], b.u)
+      // The donor's hips bob relative to its root (header §6), scaled, in the world after the root's turn.
+      let bob: Vec3 | null = null
+      if (donorBob && donorRoot !== undefined && donorHips !== undefined) {
+        const v = sub(dw.pos[donorHips], dw.pos[donorRoot])
+        const v0 = sub(donor.bind.worldPos[donorHips], donor.bind.worldPos[donorRoot])
+        const dRoot = qmul(dw.rot[donorRoot], qinv(donor.bind.worldRot[donorRoot]))
+        const bv = sub(v, qrot(dRoot, v0))
+        bob = [ bv[0] * rootScale, bv[1] * vScale, bv[2] * rootScale ]   // the vertical at this clip's scale (a platform's within the hands' reach)
+      }
+      for (const i of target.order) {
+        const p = target.parents[i]
+        if (driven.has(i)) wrot[i] = qnorm(qmul(delta[i], ref[i]))
+        // Unmapped: hold the rest LOCAL rotation, so the bone rides its parent without drifting.
+        else wrot[i] = p >= 0 ? qnorm(qmul(wrot[p], target.rest.r[i])) : qnorm(target.rest.r[i])
+
+        if (i === rootIdx && rootRefPos && donorRoot !== undefined) {
+          // Root translation in WORLD space: the reference position plus the donor's scaled travel.
+          const d = dw.pos[donorRoot], r = donor.bind.worldPos[donorRoot]
+          const tv = sub(d, r)
+          wpos[i] = add(rootRefPos, [ tv[0] * rootScale, tv[1] * vScale, tv[2] * rootScale ])
+        } else if (p < 0) wpos[i] = target.rest.t[i]
+        else wpos[i] = add(wpos[p], qrot(wrot[p], localOff[i]))
+        if (i === hipsIdx && bob) wpos[i] = add(wpos[i], bob)
+      }
+      return { dw }
+    }
+    // Feet: the target's OWN stance plus the donor's scaled departure from ITS stance — on all
+    // three axes. Copying the donor's absolute foot-under-hip offset instead would overwrite the
+    // target's build with the donor's: a fox that tucks its feet inboard gets planted on the
+    // donor's vertical legs and reads as bow-legged in every clip.
+    // Hip-relative on all three axes: the donor's hip→foot vector scaled, plus the stance correction
+    // (where THIS rig rests its foot under its hip, against where the donor does — vertically that
+    // is the target's own ground + the donor's scaled departure from ITS ground, since the hips carry
+    // the scaled bob). The correction is a standing thing: when the donor's leg is near straight it
+    // can ask for more than the leg's length (a running push-off on a rig whose hips sit higher
+    // above its feet), so it is shrunk — never the donor's vector — until the goal is in reach.
+    // The goal is the CONTACT's (the ball of a humanoid foot, header §6); the effector's follows
+    // from it through the foot at its FK orientation — `off` is where the FK put the contact
+    // relative to the effector, and the effector keeps that orientation through the IK.
+    const goalOf = (leg: Leg, dw: ReturnType<typeof worldOf>): { effector: Vec3; contact: Vec3 } => {
+      const hip = wpos[leg.chain[0]]
+      const off = sub(wpos[leg.contact], wpos[leg.effector])
+      const a = sub(donorReach(leg, dw.pos), off)   // hip → effector: the donor's reach scaled, less the foot
+      const c: Vec3 = [ 0, 1, 2 ].map((i) => leg.stanceTarget[i] - leg.stanceDonor[i]) as Vec3
+      if (opts.footStance === 'donor') { c[0] = 0; c[2] = 0 }   // the donor's own foot-under-hip offset, scaled, stands
+      const R = 0.995 * leg.lengths.reduce((x, y) => x + y, 0)
+      let k = 1
+      if (len(add(a, c)) > R) {
+        // Largest k in [0, 1] with |a + k·c| = R (k = 0 if even the donor's vector alone overreaches).
+        const cc = c[0] * c[0] + c[1] * c[1] + c[2] * c[2], ac = a[0] * c[0] + a[1] * c[1] + a[2] * c[2], aa = a[0] * a[0] + a[1] * a[1] + a[2] * a[2] - R * R
+        const disc = ac * ac - cc * aa
+        k = cc > 1e-12 && disc >= 0 ? Math.max(0, Math.min(1, (-ac + Math.sqrt(disc)) / cc)) : 0
+      }
+      let effector = [ 0, 1, 2 ].map((i) => hip[i] + a[i] + c[i] * k) as Vec3
+      // The knee and the ankle are the donor's. Building the ankle from the ball puts the two feet's
+      // SHAPE difference into the goal: this ankle sits lower and further behind its ball than the
+      // donor's (Vex 31° vs Humanoid_F 51° of ankle→ball pitch — a 5 cm vector that turns with the
+      // foot). Spent by the knee it is a 20° wobble through a stance the donor holds straight (a
+      // centimetre short of full extension is 20° of knee); spent by the ankle it is a 6 cm pop at
+      // heel strike, when the extended leg can only swing. So for a foot the goal is the ANKLE's:
+      // direction = the donor's hip→ankle, scaled, plus the stance correction; distance = the
+      // target's own stance reach scaled by how far the donor's leg is extended against its
+      // reference (capped at the chain's full length — the 0.995 alone is a 12° knee). The ball is
+      // then wherever this foot's shape puts it — a constant offset the eye does not catch — and
+      // serves only the planting (horizontal anchor) and the floor (the ankle pitch below).
+      if (leg.isFoot && leg.refReach > 0) {
+        // The stance correction is whole here (not `k`-shrunk): reach is the distance's business
+        // now, and shrinking it only where the leg is straight moved the ankle 6 cm sideways
+        // every time a leg passed through full extension — heel strike and toe-off, twice a stride.
+        const ankle = add(scl(sub(dw.pos[leg.donorEffector], dw.pos[leg.donorHip]), leg.ratio), c)
+        const dir = unit(ankle)
+        // …the donor's extension as a fraction of its FULL leg length, applied to this leg's full
+        // length: the same knee bend, whatever either rig's bind pose does with its knees
+        const ext = len(sub(dw.pos[leg.donorEffector], dw.pos[leg.donorHip])) / donorLegSum(leg)
+        if (dir) effector = add(hip, scl(dir, Math.min(R / 0.995, ext * (R / 0.995))))
+      }
+      return { effector, contact: add(effector, off) }
+    }
+
+    // Pass 1 — MARKS on the donor (marks.ts): where each foot — and each hand — touches, holds still
+    // and lifts, measured on the donor's own limbs (clean by construction: its clips were solved on
+    // it). Every foot's STILL window and every hand's whole TOUCH becomes a LOCK: the target's contact
+    // bone is held at one world point through it (x/z = the mean of where the FK put it — anchoring
+    // on the first frame piles the whole slide onto the lift-off, the mean splits it; y = the target's
+    // ground, its tread on a stair clip, or where the FK put it when that is far from the ground) and
+    // the limb's end keeps one rotation, so the pelvis sway the transfer leaks into the feet (leg
+    // proportions differ, so the donor's own cancellation does not carry over) goes to the knees
+    // instead. Faded in and out over PLANT_FADE frames outside a window, never past its touch. A
+    // window across the loop seam is one window.
+    const dtM = frames > 1 ? clip.duration / (frames - 1) : 1
+    const levelKind: LevelKind = opts.stairs ? opts.stairs(clip.name) : false
+    const sideOfLeg = (li: number): 'l' | 'r' | null => {
+      const n = `${legs[li].name} ${target.names[legs[li].contact]}`
+      if (/left|(^|[_.\s])l([_.\s]|$)/i.test(n)) return 'l'
+      if (/right|(^|[_.\s])r([_.\s]|$)/i.test(n)) return 'r'
+      return null
+    }
+    // `yTrack`: a HEIGHT-ONLY lock — a hand that slides through its contact (a dive roll's hands
+    // travel 25 cm while the fingertips are on the floor) keeps the donor's height above the level
+    // frame by frame, x/z and rotation free
+    type Window = { leg: number; start: number; end: number; touchStart: number; touchEnd: number; anchor: Vec3; rot: Quat; step?: number; openStart?: boolean; openEnd?: boolean; yTrack?: Float32Array }
+    const windows: Window[] = []
+    // per FOOT, per frame: how far the whole foot must shift vertically for its clearance over the
+    // ground to match the donor's (NaN outside the touch spans) — see the block after the windows
+    const heightTracks = new Map<number, Float32Array>()
+    let donorMarks: ReturnType<typeof detectMarks> | null = null
+    const footSide = new Map<number, 'l' | 'r'>(), handSide = new Map<number, 'l' | 'r'>()
+    for (const [ li, leg ] of legs.entries()) { const s = sideOfLeg(li); if (s) (leg.isFoot ? footSide : handSide).set(li, s) }
+    const limbs = [ ...footSide.keys(), ...handSide.keys() ]
+    const marksOf = (li: number): MarkSpan[] => {
+      if (!donorMarks) return []
+      const fs = footSide.get(li); if (fs) return donorMarks[fs]
+      const hs = handSide.get(li); if (hs) return hs === 'l' ? donorMarks.hl : donorMarks.hr
+      return []
+    }
+    let stairsTarget: Stairs | undefined
+    // per frame, per limb, from the FK sweep: the contact goal, the effector goal, the chain root
+    // (hip / shoulder), the effector's rotation, the donor's extension — the lock and the body
+    // drop below are decided from these before any frame is written
+    // BODY ON THE GROUND, per frame: over every mapped joint the DONOR has on its floor (within 5 cm),
+    // how far the target's SAME joint sits above the donor's height over the ground + the clearance —
+    // the largest is what the body must come down (comparing the two rigs' lowest joints instead
+    // matched a hand at 2 cm against the spine and pulled the back onto the floor)
+    const groundDemand = new Float32Array(frames).fill(-Infinity)
+    const bodyClearance = opts.bodyClearance ?? 0.05
+    const dGroundEarly = footSide.size ? Math.min(...[ ...footSide.keys() ].map((li) => donor.bind.worldPos[legs[li].donorContact][1])) : NaN
+    const lockedJoints = new Set<number>()
+    for (const l of legs) { lockedJoints.add(l.effector); lockedJoints.add(l.contact) }
+    const goals = new Map<number, Vec3[]>(), effs = new Map<number, Vec3[]>(), hips = new Map<number, Vec3[]>()
+    const rots = new Map<number, Quat[]>(), exts = new Map<number, number[]>(), rootRel = new Map<number, Vec3[]>()
+    for (const li of limbs) { goals.set(li, []); effs.set(li, []); hips.set(li, []); rots.set(li, []); exts.set(li, []); rootRel.set(li, []) }
+    // the ground a HAND is put on: the feet's (the ball's grounded height; a palm sits ~2 cm higher)
+    const groundY = footSide.size ? [ ...footSide.keys() ].reduce((a, li) => a + legs[li].baseTarget, 0) / footSide.size : 0
+    if (limbs.length) {
+      const dTracks = new Map<number, FootTrack>(limbs.map((li) => [ li, legs[li].isFoot ? { contact: [], ankle: [] } : { contact: [], ankle: [], tip: [] } ]))
+      // the donor effector's world rotation per frame (a foot's heel hangs off the ankle's frame)
+      const dRots = new Map<number, Quat[]>(limbs.map((li) => [ li, [] ]))
+      // the toes, per frame: both rigs' contact (ball) world rotation — a virtual toe is hung off
+      // it, so a dorsiflexed toe at a toe-first landing stays up — and the real toe tips where a
+      // rig has them: the target's lowest descendant of its ball as an offset from the ball (the
+      // placement moves the ball, the foot keeps its FK rotation), the donor's as a height
+      const dBallRots = new Map<number, Quat[]>(limbs.map((li) => [ li, [] ])), tBallRots = new Map<number, Quat[]>(limbs.map((li) => [ li, [] ]))
+      const tToeOff = new Map<number, (Vec3 | null)[]>(limbs.map((li) => [ li, [] ])), dToeY = new Map<number, number[]>(limbs.map((li) => [ li, [] ]))
+      const dRoot: Vec3[] = [], dHeading: number[] = []
+      // the donor's pelvis (the hang rule) and its whole body (the platform's face) per frame
+      const dHips: Vec3[] = [], dBody: Vec3[][] = []
+      for (let f = 0; f < frames; f++) {
+        const { dw } = frameFK(f)
+        dRoot.push(donorRoot !== undefined ? dw.pos[donorRoot] : donorHips !== undefined ? dw.pos[donorHips] : [ 0, 0, 0 ])
+        dHips.push(donorHips !== undefined ? dw.pos[donorHips] : dRoot[f])
+        dBody.push(donorSkinned.map((i) => dw.pos[i]))
+        dHeading.push(donorHipsForYaw !== undefined ? hipsHeading(dw.rot) : 0)
+        if (Number.isFinite(dGroundEarly)) for (const [ i, sIdx ] of byTarget) {
+          if (lockedJoints.has(i) || !wpos[i]) continue
+          const over = dw.pos[sIdx][1] - dGroundEarly
+          if (over > 0.05) continue
+          const d = wpos[i][1] - (groundY + over + bodyClearance)
+          if (d > groundDemand[f]) groundDemand[f] = d
+        }
+        for (const li of limbs) {
+          const leg = legs[li]
+          // the witness above the contact: a foot's ankle, a hand's forearm
+          const witness = leg.isFoot ? leg.donorEffector : (byTarget.get(leg.chain[leg.chain.length - 1]) ?? leg.donorEffector)
+          dTracks.get(li)!.contact.push(dw.pos[leg.donorContact]); dTracks.get(li)!.ankle.push(dw.pos[witness])
+          dRots.get(li)!.push(dw.rot[leg.donorEffector])
+          if (leg.isFoot) {
+            dBallRots.get(li)!.push(dw.rot[leg.donorContact]); tBallRots.get(li)!.push(wrot[leg.contact])
+            let tLow: Vec3 | null = null
+            const st = [ ...children[leg.contact] ]
+            while (st.length) { const c = st.pop()!; if (wpos[c] && (!tLow || wpos[c][1] < tLow[1])) tLow = wpos[c]; st.push(...children[c]) }
+            tToeOff.get(li)!.push(tLow ? sub(tLow, wpos[leg.contact]) : null)
+            let dLow = NaN
+            const ds = [ ...donorChildren[leg.donorContact] ]
+            while (ds.length) { const c = ds.pop()!; if (Number.isNaN(dLow) || dw.pos[c][1] < dLow) dLow = dw.pos[c][1]; ds.push(...donorChildren[c]) }
+            dToeY.get(li)!.push(dLow)
+          }
+          if (!leg.isFoot) {
+            let low = dw.pos[leg.donorEffector]
+            const stack = [ ...donorChildren[leg.donorEffector] ]
+            while (stack.length) { const c = stack.pop()!; if (dw.pos[c][1] < low[1]) low = dw.pos[c]; stack.push(...donorChildren[c]) }
+            dTracks.get(li)!.tip!.push(low)
+          }
+          const g = goalOf(leg, dw)
+          goals.get(li)!.push(g.contact); effs.get(li)!.push(g.effector); hips.get(li)!.push([ ...wpos[leg.chain[0]] ] as Vec3)
+          rots.get(li)!.push(wrot[leg.effector])
+          exts.get(li)!.push(len(sub(dw.pos[leg.donorEffector], dw.pos[leg.donorHip])) / donorLegSum(leg))
+          rootRel.get(li)!.push(sub(dw.pos[leg.donorContact], dw.pos[leg.donorHip]))
+        }
+      }
+      const feetIn: MarksInput['feet'] = {}, handsIn: NonNullable<MarksInput['hands']> = {}
+      for (const [ li, sd ] of footSide) feetIn[sd] = dTracks.get(li)!
+      for (const [ li, sd ] of handSide) handsIn[sd] = dTracks.get(li)!
+      // the donor's ground: its bind's contact height (a platform's level 0)
+      const donorGround = footSide.size ? Math.min(...[ ...footSide.keys() ].map((li) => donor.bind.worldPos[legs[li].donorContact][1])) : undefined
+      dHeadingAll = dHeading
+      donorMarks = detectMarks({ dt: dtM, root: dRoot, heading: dHeading, feet: feetIn, hands: handSide.size ? handsIn : undefined, stairs: levelKind === 'stairs' ? true : levelKind, floor: donorGround, hips: dHips, body: dBody })
+      for (const w of donorMarks.warnings) opts.warn?.(`${clip.name}: ${w}`)
+      if (process.env.LECODES_PLANT_TRACE === clip.name) console.log(`[marks] ${describeMarks(donorMarks)}`)
+      // The target's staircase is FITTED on the target's own plants — the heights the FK put the
+      // donor's plants at, one vote per still window — not scaled from the donor's: the leg ratio
+      // (1.17) is not what the transfer scales the vertical by (the hand-jump's platform came out
+      // at 2.76 m, the scaled riser said 2.94, the tread anchors sat 19 cm too high, the lock
+      // refused them and the feet stood 19 cm under the drawn tread). The donor's step index k
+      // names each plant's level; the target's base + k · riser is where that level actually is.
+      if (donorMarks.stairs && footSide.size) {
+        const feetIdx = [ ...footSide.keys() ]
+        const votes: { y: number; w: number }[] = []
+        const byStep = new Map<number, number[]>()
+        for (const li of feetIdx) for (const sp of donorMarks[footSide.get(li)!]) {
+          if (!sp.still || sp.step === undefined) continue
+          const a = Math.round(sp.still[0] / dtM), b = Math.round(sp.still[1] / dtM)
+          const ys: number[] = []
+          for (let i = a; i <= b; i++) ys.push(goals.get(li)![i][1])
+          const med = [ ...ys ].sort((x, y) => x - y)[ys.length >> 1]
+          votes.push({ y: med, w: ys.length })
+          ;(byStep.get(sp.step) ?? byStep.set(sp.step, []).get(sp.step)!).push(med)
+        }
+        const ks = [ ...byStep.keys() ].sort((a, b) => a - b)
+        let base: number | null = null, riser = 0
+        if (ks.length >= 2) {
+          // the riser from the plants' own levels (median height per step, least squares over k)
+          const pts = ks.map((k) => ({ k, y: [ ...byStep.get(k)! ].sort((a, b) => a - b)[byStep.get(k)!.length >> 1] }))
+          const n = pts.length, sk = pts.reduce((a, p) => a + p.k, 0), sy = pts.reduce((a, p) => a + p.y, 0), skk = pts.reduce((a, p) => a + p.k * p.k, 0), sky = pts.reduce((a, p) => a + p.k * p.y, 0)
+          const det = n * skk - sk * sk
+          if (Math.abs(det) > 1e-9) { riser = (n * sky - sk * sy) / det; base = (sy * skk - sk * sky) / det }
+        }
+        if (base === null || riser < 0.05) {
+          // one level seen on the target: the donor's riser scaled as this clip's vertical travel was
+          riser = donorMarks.stairs.riser * vScale
+          const ys = votes.length ? votes.map((v) => v.y) : [ legs[feetIdx[0]].baseTarget ]
+          const k0 = ks[0] ?? 0
+          base = [ ...ys ].sort((a, b) => a - b)[ys.length >> 1] - k0 * riser
+          // a PLATFORM whose only plants are on the ground (a hang, a drop): the ground IS level 0 —
+          // a fallen body's foot voting 12 cm up must not lift the top by 12 cm
+          if (levelKind === 'platform' && k0 === 0) base = groundY
+        }
+        // a PLATFORM's level 0 is the ground the feet stand on — pinned there (the FK's median can sit
+        // a few cm off it, and a foot locked a few cm under the floor is what the eye catches first)
+        if (levelKind === 'platform') { const top = base + riser; base = groundY; riser = top - base }
+        stairsTarget = { riser, tread: donorMarks.stairs.tread * rootScale, base, dir: donorMarks.stairs.dir }
+        if (process.env.LECODES_MARKS_TRACE) console.log(`[marks] ${clip.name}: target levels ${ks.map((k) => `k${k} ${(byStep.get(k)!.reduce((a, b) => a + b, 0) / byStep.get(k)!.length).toFixed(3)}`).join(' ')} → base ${base.toFixed(3)} riser ${riser.toFixed(3)} (donor ${donorMarks.stairs.riser.toFixed(3)})`)
+      }
+      if (plantOn) for (const li of limbs) {
+        const leg = legs[li]
+        const g = goals.get(li)!, rr = rots.get(li)!
+        const L = donorLegLen(leg)
+        // a foot locks through its STILL windows; a hand through its whole TOUCH (a cartwheel's hand
+        // is down for three frames — there is no still window inside that, and no roll either)
+        // the donor's own contact height over the span, against the level it is on (a hand hangs
+        // 15 cm under a ledge's edge, rests 1–2 cm over a top or a floor): the OFFSET transfers
+        const dTrack = dTracks.get(li)!.contact
+        // the clip's own floor (the lowest a foot got): the level a HAND's offset is measured from
+        const donorFloor = Math.min(...[ ...footSide.keys() ].map((fi) => Math.min(...dTracks.get(fi)!.contact.map((p) => p[1]))))
+        const donorLevel = (step: number | undefined): number => (donorMarks!.stairs && step !== undefined && step >= 0 ? donorMarks!.stairs.base + step * donorMarks!.stairs.riser : donorFloor)
+        // a FOOT's level off a staircase is the donor's BIND ground (the ball's bind height — what
+        // `baseTarget` is on the target), never the clip's lowest: a take whose feet never come
+        // near the ground (a hang) would read as "on the floor", and an identity transfer must
+        // measure both rigs from the same rest height to come out exact
+        const donorFootLevel = (step: number | undefined): number => (donorMarks!.stairs && step !== undefined && step >= 0 ? donorMarks!.stairs.base + step * donorMarks!.stairs.riser : dGroundEarly)
+        const wins = marksOf(li).filter((sp) => leg.isFoot ? !!sp.still : true).map((sp) => {
+          const a = Math.round(sp.from / dtM), b = Math.min(frames - 1, Math.round(sp.to / dtM))
+          // a foot's height over its level is read inside the STILL window — the touch includes the
+          // roll in and out, where the ball is up on a heel strike
+          const [ oa, ob ] = leg.isFoot && sp.still ? [ Math.round(sp.still[0] / dtM), Math.min(frames - 1, Math.round(sp.still[1] / dtM)) ] : [ a, b ]
+          const ys: number[] = []
+          for (let i = oa; i <= ob; i++) ys.push(dTrack[i][1])
+          const donorY = ys.length ? [ ...ys ].sort((x, y) => x - y)[ys.length >> 1] : 0
+          // a hand that TRAVELS through its contact (over 8 cm from where it landed) is sliding /
+          // rolling — it gets the donor's height profile over the level, not a fixed point
+          let slide = 0
+          if (!leg.isFoot) for (let i = a; i <= b; i++) slide = Math.max(slide, Math.hypot(dTrack[i][0] - dTrack[a][0], dTrack[i][2] - dTrack[a][2]))
+          return {
+            start: Math.round((leg.isFoot ? sp.still![0] : sp.from) / dtM),
+            end: Math.min(frames, Math.round((leg.isFoot ? sp.still![1] : sp.to) / dtM) + 1),
+            touchStart: a, touchEnd: Math.min(frames, b + 1), step: sp.step,
+            offset: Number.isFinite(donorFloor) ? Math.max(-0.3, Math.min(0.25, donorY - donorLevel(sp.step))) : 0.02,
+            heightProfile: !leg.isFoot && slide > 0.08 && Number.isFinite(donorFloor) ? Array.from({ length: frames }, (_, i) => dTrack[Math.max(a, Math.min(b, i))][1] - donorLevel(sp.step)) : null,
+          }
+        })
+        // HEIGHT through the whole TOUCH (marks.ts `from`..`to`). Outside the still window the foot
+        // rolls — the heel strike, the toe-off — and the lock is off, but the donor's foot is ON the
+        // ground there and the target's must be too: a walk's heel strike landed 5 cm up and only
+        // came down where the still window's lock faded in. Per frame the foot's CLEARANCE — the
+        // lower of its heel and its ball over where each rests when the foot lies flat (the heel is
+        // virtual: the ankle's bind height hung under the ankle in the ankle's frame — a mannequin
+        // has no heel bone) — is matched to the donor's, scaled: the whole foot shifts vertically,
+        // x/z and rotation stay the FK's. The target's own toes beyond the ball are not compared
+        // (the donor may have none); the floor pitch in pass 2 keeps them out of the ground.
+        // The track holds the ball's ABSOLUTE height (pass-1 goal + the shift): pass 2 lowers the
+        // whole body first (`dropCurve`) and a shift relative to the dropped FK would lower the
+        // foot twice. The toe is virtual on BOTH rigs — the ball pushed along the foot's forward
+        // axis (in the ankle's frame, so it dips with the pitch like a real toe) by the toe's
+        // length: a foot up on its toes has its TIP on the ground, and a mannequin's ball 4 cm up
+        // means its (unmodelled) toe cap is down, not that the foot floats.
+        if (leg.isFoot) {
+          const track = new Float32Array(frames).fill(NaN)
+          const heelT = qrot(qinv(target.bind.worldRot[leg.effector]), [ 0, -(target.bind.worldPos[leg.effector][1] - lowestBind), 0 ])
+          const heelD = qrot(qinv(donor.bind.worldRot[leg.donorEffector]), [ 0, -(donor.bind.worldPos[leg.donorEffector][1] - donorLowestBind), 0 ])
+          const toeReach = (kids: number[][], ball: number, pos: Vec3[]): number => {
+            let r = 0
+            const st = [ ...kids[ball] ]
+            while (st.length) { const c = st.pop()!; r = Math.max(r, Math.hypot(pos[c][0] - pos[ball][0], pos[c][2] - pos[ball][2])); st.push(...kids[c]) }
+            return r
+          }
+          const realT = toeReach(children, leg.contact, target.bind.worldPos), realD = toeReach(donorChildren, leg.donorContact, donor.bind.worldPos)
+          const toeLenT = realT > 0 ? realT : realD * leg.ratio, toeLenD = realD > 0 ? realD : realT / leg.ratio
+          // a virtual toe: the foot's forward (the ankle→ball line, flattened) in the BALL's bind
+          // frame — the ball's rotation carries the toes' flex, so a toe-first landing with the toes
+          // bent up keeps its tip up instead of burying a rigid one 4 cm in the floor
+          const fwdOf = (rig: Rig, ankle: number, ball: number): Vec3 | null => {
+            const v = sub(rig.bind.worldPos[ball], rig.bind.worldPos[ankle])
+            const h = unit([ v[0], 0, v[2] ])
+            return h ? qrot(qinv(rig.bind.worldRot[ball]), h) : null
+          }
+          const fwdT = fwdOf(target, leg.effector, leg.contact), fwdD = fwdOf(donor, leg.donorEffector, leg.donorContact)
+          const dAnkle = dTracks.get(li)!.ankle, dRot = dRots.get(li)!, ef = effs.get(li)!
+          const dBall = dBallRots.get(li)!, tBall = tBallRots.get(li)!, tOff = tToeOff.get(li)!, dToe = dToeY.get(li)!
+          // On flat ground the clearance is matched on EVERY frame, swing included: the body drop
+          // below moves the swing foot down with the hips, and a toe-off 4 cm lower than the
+          // donor's had the toe pinned on the floor by the floor pitch. On stairs only the touch
+          // spans are judged (a foot between two treads has no one level to be measured against).
+          const spans = marksOf(li).map((sp) => ({ a: Math.round(sp.from / dtM), b: Math.min(frames - 1, Math.round(sp.to / dtM)), step: sp.step }))
+          const onLevels = !!donorMarks!.stairs
+          for (let i = 0; i < frames; i++) {
+            const sp = spans.find((s) => i >= s.a && i <= s.b)
+            if (!sp && onLevels) continue
+            const levelD = donorFootLevel(sp?.step)
+            const levelT = stairsTarget && sp?.step !== undefined && sp.step >= 0 ? stairsTarget.base + sp.step * stairsTarget.riser : leg.baseTarget
+            if (!Number.isFinite(levelD)) continue
+            {
+              const dToeAt = !Number.isNaN(dToe[i]) ? dToe[i] : fwdD && toeLenD > 0 ? dTrack[i][1] + qrot(dBall[i], fwdD)[1] * toeLenD : Infinity
+              const tToeAt = tOff[i] ? g[i][1] + tOff[i]![1] : fwdT && toeLenT > 0 ? g[i][1] + qrot(tBall[i], fwdT)[1] * toeLenT : Infinity
+              const want = Math.min(dAnkle[i][1] + qrot(dRot[i], heelD)[1], dTrack[i][1], dToeAt) - levelD
+              const have = Math.min(ef[i][1] + qrot(rr[i], heelT)[1], g[i][1], tToeAt) - levelT
+              // (a donor foot under its own floor carries over, scaled — identity stays exact)
+              const dy = want * leg.ratio - have
+              // a shift past 15 % of the leg is a transfer gone wrong, not a foot to lower
+              if (Math.abs(dy) <= 0.15 * L) track[i] = g[i][1] + dy
+            }
+          }
+          heightTracks.set(li, track)
+          if (process.env.LECODES_PLANT_TRACE === clip.name) console.log(`[height] ${leg.name} ${Array.from(track).map((v, i) => Number.isNaN(v) ? '' : `${i}:${((v - g[i][1]) * 1000).toFixed(0)}`).filter(Boolean).join(' ')}`)
+        }
+        // The last frame of a cycle repeats its first: a window touching both ends is ONE plant
+        // across the seam — held at one place modulo the clip's travel, no fade on the seam side.
+        const rel = rootRel.get(li)!
+        const cyclic = len(sub(rel[0], rel[frames - 1])) < 0.02
+        const head = wins[0], tail = wins[wins.length - 1]
+        const seam = cyclic && wins.length >= 2 && head.start === 0 && tail.end === frames
+        const travel = sub(g[frames - 1], g[0])
+        // the anchor's height: the tread on a fitted staircase; a foot: the target's ground when the
+        // FK put it near it, else where the FK put it (a platform, a stair clip whose staircase did
+        // not fit); a hand: the feet's ground — the FK hand is wherever the arm's proportions left
+        // it, which is the very thing being corrected (24 cm up on the cartwheel)
+        const yOf = (step: number | undefined, fkY: number, offset = 0.02): number => {
+          if (leg.isFoot) {
+            // the target's level — its ground, its tread on a fitted staircase — plus the donor's own
+            // height over ITS level through the window, scaled: a foot the donor holds on the floor
+            // lands on the floor, a foot it dangles 23 cm up (a hang) dangles. Never the FK's
+            // height: the FK is the very thing being corrected (a punch's lunge sat both feet 7 cm
+            // up, and "keep the FK beyond 6 cm" locked them there, in the air)
+            const level = stairsTarget && step !== undefined ? stairsTarget.base + step * stairsTarget.riser : leg.baseTarget
+            return level + Math.max(0, offset) * leg.ratio
+          }
+          // a hand: the level it is on (a platform's top, a tread, the floor) plus the donor's own
+          // offset from that level — a palm rests 1–2 cm over a top, a grip hangs 15 cm under an
+          // edge — so a hang on a rig whose arms reach less far above its hips (Kachujin's hands
+          // hung 50 cm under the ledge) is pulled to the ledge and the body follows up to it
+          const level = stairsTarget && step !== undefined && step >= 0 ? stairsTarget.base + step * stairsTarget.riser : footSide.size ? groundY : null
+          return level === null ? fkY : level + offset
+        }
+        const meanOf = (list: { start: number; end: number; shift: Vec3 }[]): Vec3 => {
+          const acc: Vec3 = [ 0, 0, 0 ]
+          let n = 0
+          for (const r of list) for (let i = r.start; i < r.end; i++) { const p = add(g[i], r.shift); acc[0] += p[0]; acc[1] += p[1]; acc[2] += p[2]; n++ }
+          return scl(acc, 1 / Math.max(1, n))
+        }
+        // a limb the FK puts more than 15 % of its length from its anchor was never planted there —
+        // a transfer gone wrong (a parkour take's hips two metres off), not a lock's business. A hand
+        // is judged horizontally only: its vertical miss is the correction itself.
+        const sane = (r: { start: number; end: number }, anchor: Vec3): boolean => {
+          let worst = 0
+          for (let i = r.start; i < r.end; i++) {
+            const d = leg.isFoot ? len(sub(g[i], anchor)) : Math.hypot(g[i][0] - anchor[0], g[i][2] - anchor[2])
+            worst = Math.max(worst, d)
+          }
+          // a HAND's FK sweeps through its contact while the body passes over it — the arm reaches
+          // 3 % further, the body travels 17 % further — and that sweep IS what the lock corrects:
+          // a cartwheel's hand swept 20 cm (18 at the old, wrong, root scale), so half the arm
+          const limit = (leg.isFoot ? 0.15 : 0.5) * L
+          const ok = worst <= limit
+          if (!ok && process.env.LECODES_PLANT_TRACE === clip.name) console.log(`[sane] ${leg.name} f ${r.start}-${r.end}: FK ${(worst * 1000).toFixed(0)}mm from the anchor (limit ${(limit * 1000).toFixed(0)}mm) — no lock`)
+          return ok
+        }
+        const rotAt = (r: { start: number; end: number }): Quat => rr[Math.min(frames - 1, (r.start + r.end) >> 1)]
+        /** A foot's anchor height: the median of its height track through the window — one rule for
+         *  the roll and the stand — falling back to the level + the donor's offset. */
+        const yWin = (r: { start: number; end: number; step?: number; offset: number }, fkY: number): number => {
+          const tr = heightTracks.get(li)
+          const ys: number[] = []
+          if (tr) for (let i = r.start; i < r.end; i++) if (!Number.isNaN(tr[i])) ys.push(tr[i])
+          return ys.length ? [ ...ys ].sort((x, y) => x - y)[ys.length >> 1] : yOf(r.step, fkY, r.offset)
+        }
+        for (const r of wins) {
+          if (seam && (r === head || r === tail)) continue
+          const m = meanOf([ { ...r, shift: [ 0, 0, 0 ] } ])
+          const anchor: Vec3 = [ m[0], leg.isFoot ? yWin(r, m[1]) : yOf(r.step, m[1], r.offset), m[2] ]
+          // a window at the clip's edge has nothing to fade from: the clip begins / ends planted
+          if (r.heightProfile) {
+            const level = stairsTarget && r.step !== undefined && r.step >= 0 ? stairsTarget.base + r.step * stairsTarget.riser : groundY
+            windows.push({ leg: li, start: r.start, end: r.end, touchStart: r.touchStart, touchEnd: r.touchEnd, anchor, rot: rotAt(r), step: r.step, openStart: r.start === 0, openEnd: r.end === frames, yTrack: Float32Array.from(r.heightProfile.map((h) => level + h)) })
+          } else if (sane(r, anchor)) windows.push({ leg: li, start: r.start, end: r.end, touchStart: r.touchStart, touchEnd: r.touchEnd, anchor, rot: rotAt(r), step: r.step, openStart: r.start === 0, openEnd: r.end === frames })
+        }
+        if (seam) {
+          const m = meanOf([ { ...head, shift: [ 0, 0, 0 ] }, { ...tail, shift: scl(travel, -1) } ])
+          const anchor: Vec3 = [ m[0], leg.isFoot ? yWin(head, m[1]) : yOf(head.step, m[1], head.offset), m[2] ]
+          const tailAnchor: Vec3 = [ anchor[0] + travel[0], stairsTarget ? (leg.isFoot ? yWin(tail, m[1] + travel[1]) : yOf(tail.step, m[1] + travel[1], tail.offset)) : anchor[1], anchor[2] + travel[2] ]
+          if (sane(head, anchor) && sane(tail, tailAnchor)) {
+            windows.push({ leg: li, start: head.start, end: head.end, touchStart: head.touchStart, touchEnd: head.touchEnd, anchor, rot: rotAt(head), step: head.step, openStart: true })
+            windows.push({ leg: li, start: tail.start, end: tail.end, touchStart: tail.touchStart, touchEnd: tail.touchEnd, anchor: tailAnchor, rot: rotAt(head), step: tail.step, openEnd: true })
+          }
+        }
+      }
+    }
+    /** The lock on `leg` at frame `f`: the contact's anchor, the limb end's held rotation and the blend
+     *  weight — 1 through the whole window (that is the promise: the toe does not move), fading in
+     *  over the PLANT_FADE frames BEFORE it and out over the frames AFTER it, i.e. through the
+     *  heel-strike roll-in and the heel-rise roll-out, where the foot moves anyway, and only while the
+     *  marks say the toe is still TOUCHING: past the touch the foot is in the air. */
+    /** the contact bone's offset in the effector's frame — zero when the contact IS the effector (a hand) */
+    const contactOff = (leg: Leg): Vec3 => (leg.contact === leg.effector ? [ 0, 0, 0 ] : localOff[leg.contact])
+    /** A FADING lock (w < 1) engages as the foot ARRIVES: full share within 1 cm of the anchor, none
+     *  beyond 5 cm. Pulling a heel-strike foot still 6 cm up (the walk's f9: 65 mm) pushed the near-
+     *  straight landing leg past its reach and snapped the knee. Inside the window (w = 1) the miss
+     *  IS the transfer error and gets corrected in full. */
+    const proximity = (pl: { anchor: Vec3; w: number }, ball: Vec3, isFoot = true): number =>
+      pl.w >= 1 || !isFoot ? 1 : Math.max(0, Math.min(1, 1 - (len(sub(ball, pl.anchor)) - 0.01) / 0.04))
+    /** The constraint on `leg` at frame `f`, given the FK's contact `fk` and effector rotation: the
+     *  positional lock (its window, faded, proximity-gated for a foot) composed over the foot's
+     *  HEIGHT track — the lock takes its share `w`, the track the rest, so a heel strike lands on
+     *  the ground first and rolls flat into the lock. A foot in a touch span always returns w = 1
+     *  (its height is a promise too); a limb with a lock alone returns the lock's weight. */
+    const plantAt = (li: number, f: number, fk?: Vec3, fkRot?: Quat): { anchor: Vec3; rot: Quat; w: number; heightOnly?: boolean; lockShare?: number } | null => {
+      let best: { anchor: Vec3; rot: Quat; w: number; heightOnly?: boolean; lockShare?: number } | null = null
+      for (const s of windows) {
+        if (s.leg !== li) continue
+        let w = 0
+        if (f >= s.start && f < s.end) w = 1
+        // (a HAND fades over the frames beyond its touch — there is no roll inside a three-frame
+        // contact to fade through, and a hard release popped the hand 20 cm up in one frame)
+        else if (!s.openStart && f < s.start && f >= (legs[s.leg].isFoot ? Math.max(s.touchStart, s.start - PLANT_FADE) : s.start - PLANT_FADE)) w = (f - (s.start - PLANT_FADE) + 1) / (PLANT_FADE + 1)
+        else if (!s.openEnd && f >= s.end && f < (legs[s.leg].isFoot ? Math.min(s.touchEnd, s.end + PLANT_FADE) : s.end + PLANT_FADE)) w = (s.end + PLANT_FADE - f) / (PLANT_FADE + 1)
+        if (w > 0 && (!best || w > best.w)) best = s.yTrack && fk
+          ? { anchor: [ fk[0], s.yTrack[Math.max(0, Math.min(frames - 1, f))], fk[2] ], rot: fkRot ?? s.rot, w, heightOnly: true }
+          : { anchor: s.anchor, rot: s.rot, w }
+      }
+      const isFoot = legs[li].isFoot
+      if (best && fk) { best = { ...best, w: best.w * proximity(best, fk, isFoot) }; if (best.w <= 0) best = null }
+      const hy = fk ? heightTracks.get(li)?.[f] ?? NaN : NaN
+      if (Number.isNaN(hy)) return best
+      const hAnchor: Vec3 = [ fk![0], hy, fk![2] ]
+      const hRot = fkRot ?? best?.rot
+      if (!best || !hRot) return best && !hRot ? best : { anchor: hAnchor, rot: hRot!, w: 1, heightOnly: true, lockShare: 0 }
+      if (best.w >= 1) return best
+      const w = best.w
+      return { anchor: [ 0, 1, 2 ].map((i) => hAnchor[i] + (best!.anchor[i] - hAnchor[i]) * w) as Vec3, rot: qnorm(qslerp(hRot, best.rot, w)), w: 1, lockShare: w }
+    }
+    for (const s of windows) report.legs[s.leg].planted += s.end - s.start
+    /** Is `leg` inside one of its TOUCH spans at frame `f`? */
+    const touching = (li: number, f: number): boolean => marksOf(li).some((sp) => f >= Math.round(sp.from / dtM) && f <= Math.round(sp.to / dtM))
+
+    // ---- the BODY follows the locked limbs: the whole clip's vertical correction, two passes -------
+    // The reference pose is a straight-leg bind and the transfer lands the hips a few millimetres too
+    // high for this leg length — nothing while a foot floats with them, but a locked foot leaves the
+    // knee to absorb it exactly where a two-bone leg cannot (a centimetre short of full length is 20°
+    // of knee: Fidget V1 flicked 0–9° while the donor held 7–10°). And a locked HAND on a rig whose
+    // arms are short for its legs needs the whole body down by decimetres (the cartwheel's hands hung
+    // 24 cm above the floor). So the donor's EXTENSION is the authority: for every locked limb the
+    // chain root must sit at the donor's fraction of the limb's length from the held end; the largest
+    // demand of any frame wins (no limb straighter than the donor's, the others bend a little more)
+    // — capped per limb (feet 2 cm, hands 40 cm; a demand past the cap reduces that lock's weight
+    // instead: the limb is let go, not snapped straight) — and the curve is DILATED at DROP_SLOPE per
+    // frame, so the body descends ahead of a contact and rises after it and is exactly where each
+    // frame asked for when it gets there. A demand to RISE (hips too low) is honoured only where it
+    // was asked, within 2 cm.
+    const wScaleAt = new Map<number, Float32Array>()
+    const dropCurve = new Float32Array(frames)
+    {
+      // per limb, per frame: what the body would have to drop for this lock alone
+      const need = new Map<number, Float64Array>()
+      const demand = new Float64Array(frames).fill(-Infinity)
+      const footDemand = new Float64Array(frames).fill(-Infinity)   // the feet's alone
+      for (const li of limbs) {
+        const leg = legs[li]
+        if (leg.isFoot && leg.refReach <= 0) continue
+        const total = leg.lengths.reduce((x, y) => x + y, 0)
+        const dyOf = new Float64Array(frames).fill(NaN)
+        for (let f = 0; f < frames; f++) {
+          const pl = plantAt(li, f, goals.get(li)![f], rots.get(li)![f])
+          if (!pl) continue
+          // a swing foot held at its clearance asks nothing of the body: the leg bends for it
+          if (pl.lockShare === 0 && leg.isFoot && !touching(li, f)) continue
+          const w = pl.w
+          if (w <= 0) continue
+          const want = Math.min(total, exts.get(li)![f] * total)
+          const rotHeld = qnorm(qslerp(rots.get(li)![f], pl.rot, w))
+          const locked = sub(pl.anchor, qrot(rotHeld, contactOff(leg)))
+          const fk = effs.get(li)![f]
+          // lowering the body by d moves only the locked share of the goal closer: solve for d in
+          // |(1 − w)·a + w·(b − d·ŷ)| = want, i.e. the demand divided by w
+          const ankle: Vec3 = [ 0, 1, 2 ].map((i) => fk[i] + (locked[i] - fk[i]) * w) as Vec3
+          const v = sub(hips.get(li)![f], ankle)
+          const xz2 = v[0] * v[0] + v[2] * v[2]
+          if (want * want <= xz2) continue
+          // a HAND moves the body only when its anchor is OUT OF REACH (a cartwheel's floor, a ledge
+          // above the hands): within reach the arm bends and that is all — a foot's "no straighter
+          // than the donor" rule made a hang from a ledge drop the body 18 cm to straighten the arms
+          if (!leg.isFoot && len(v) <= want) continue
+          // the chain root above its end (a foot under a hip): lower the body so the root sits `want`
+          // above the end; the root BELOW its end (a hand overhead, the body hanging): the other root
+          const r = Math.sqrt(want * want - xz2)
+          let dy = (v[1] >= 0 ? v[1] - r : v[1] + r) / Math.max(0.05, w)
+          // a RAISE (the limb more bent than the donor's) is a positional lock's to ask, by its
+          // share: a foot merely held at its height through a touch does not lift the body — a
+          // toe-first landing 4 cm short of the donor's extension popped the pelvis 2 cm in a frame
+          if (dy < 0) dy *= pl.lockShare ?? 1
+          dyOf[f] = dy
+          if (dy > demand[f]) demand[f] = dy
+          if (leg.isFoot && dy > footDemand[f]) footDemand[f] = dy
+          if (process.env.LECODES_PLANT_TRACE === clip.name) console.log(`[hips] f ${f} ${leg.name} w ${w.toFixed(2)} ext ${exts.get(li)![f].toFixed(3)} want ${(want * 1000).toFixed(0)} total ${(total * 1000).toFixed(0)} xz ${(Math.sqrt(xz2) * 1000).toFixed(0)} vy ${(v[1] * 1000).toFixed(0)} dy ${(dy * 1000).toFixed(1)}`)
+        }
+        need.set(li, dyOf)
+      }
+      // The BODY ON THE GROUND: where the donor's lowest joint lies on its floor (a roll on the back,
+      // a knock-down, getting up) and no foot is planted, the target's lowest joint is brought to the
+      // same height over its ground — the transfer scales the body's arc by the legs (17 %) and the
+      // torso is not 17 % thicker, so a roll floated (owner: "he rolls higher than he should").
+      for (let f = 0; f < frames; f++) if (groundDemand[f] > 0.01 && groundDemand[f] > demand[f]) demand[f] = Math.min(0.4, groundDemand[f])
+      // The body may drop DECIMETRES only while no foot is on the ground (a cartwheel's flight); with
+      // a foot touching it may drop the feet's 2 cm, else the character crouches 30 cm into the run-up
+      // (measured: the feet raised 9–22 cm by the floor clamp for 15 frames before the hands landed).
+      const feetDown = new Uint8Array(frames), feetStill = new Uint8Array(frames)
+      for (const li of footSide.keys()) for (let f = 0; f < frames; f++) if (touching(li, f)) feetDown[f] = 1
+      for (const wn of windows) if (legs[wn.leg].isFoot) for (let f = wn.start; f < wn.end; f++) feetStill[f] = 1
+      // a foot STILL (bearing weight): the feet's 2 cm; a foot touching but rolling (a push-off — the
+      // knee may bend, the toe stays on the floor): 10 cm; in the air: 40 cm. NEAR A HAND CONTACT the
+      // feet's caps open up to 25 cm, decaying at 3 cm per frame away from it: a cartwheel is pushed
+      // off from a bent leg and landed into one, so the body dips through the push-off before the
+      // hands land and stays low through the landing after they leave (measured before this: the
+      // first hand landed 5 frames late and left 3 early, hovering 10 cm over the floor both times).
+      const handNear = new Float64Array(frames)   // the allowance a hand contact grants each frame
+      for (const wn of windows) {
+        if (legs[wn.leg].isFoot) continue
+        for (let f = 0; f < frames; f++) {
+          const d = f < wn.start ? wn.start - f : f >= wn.end ? f - wn.end + 1 : 0
+          handNear[f] = Math.max(handNear[f], Math.max(0, 0.25 - 0.03 * d))
+        }
+      }
+      // A FOOT's own demand — the body down until the leg reaches its anchor at the donor's
+      // extension — may take it FOOT_CAP whatever the caps above say: that demand IS the transfer's
+      // vertical error under a foot that is on the ground (a punch's lunge sat the hips 6 cm high on
+      // Kachujin, her pelvis rides 6 cm over her hip joints where the mannequin's rides 1.4), and
+      // held at 2 cm the lock was let go instead and the foot hovered. A hand's decimetres stay capped.
+      const FOOT_CAP = 0.1
+      const capAt = (f: number): number => Math.max(feetStill[f] ? 0.02 : feetDown[f] ? 0.1 : 0.4, handNear[f], footDemand[f] > 0 ? Math.min(FOOT_CAP, footDemand[f]) : 0)
+      const base = new Float64Array(frames)
+      // a demand to RAISE the body: the feet's 2 cm while a foot is down, else the hands may carry
+      // it (a hang from a ledge, a pull-up) within 40 cm
+      for (let f = 0; f < frames; f++) base[f] = demand[f] > -Infinity ? Math.max(feetDown[f] ? -0.02 : -0.4, Math.min(capAt(f), demand[f])) : 0
+      // DILATION at DROP_SLOPE per frame: the body descends ahead of a contact and rises after it
+      // (positive demands only; a demand to rise is honoured where it was asked)…
+      const DROP_SLOPE = 0.04
+      const dil = new Float64Array(frames)
+      for (let f = 0; f < frames; f++) {
+        let down = 0
+        for (let g = 0; g < frames; g++) if (base[g] > 0) down = Math.max(down, base[g] - DROP_SLOPE * Math.abs(f - g))
+        dil[f] = down > 0 ? down : base[f]   // a raise is honoured where it was asked; the slope passes below smooth it
+      }
+      // …never past a frame's cap (the feet's while they are down), and never STEEPER than the slope
+      // across the cap's boundary: a 2 cm → 24 cm jump the frame the last foot leaves is a pop; the
+      // body dips at the slope from the lift-off on, and a hand whose full drop is not reached by its
+      // landing gets its lock weight reduced to what was (it hovers a little, then settles)
+      // (with a foot down the body moves at the feet's pace — 3 mm per frame — a pelvis that follows
+      // every jump of a fading lock's demand is a knee that jitters)
+      const slopeAt = (f: number): number => (handNear[f] > 0.02 ? 0.03 : feetStill[f] ? 0.003 : feetDown[f] ? 0.02 : DROP_SLOPE)
+      for (let f = 0; f < frames; f++) dil[f] = Math.min(dil[f], capAt(f))
+      // (a RAISE next door does not pull a drop down through the slope: two feet disagreeing — one
+      // leg 2 cm long for the hips, the other 2 cm short — is settled for the short one, whose
+      // foot would float; the long one's knee bends a degree more, which nobody sees. The max
+      // passes below then decay the drop into the raise's frames at the slope instead of a pop.)
+      for (let f = 1; f < frames; f++) dil[f] = Math.min(dil[f], Math.max(0, dil[f - 1]) + slopeAt(f))
+      for (let f = frames - 2; f >= 0; f--) dil[f] = Math.min(dil[f], Math.max(0, dil[f + 1]) + slopeAt(f))
+      for (let f = 1; f < frames; f++) dil[f] = Math.max(dil[f], dil[f - 1] - slopeAt(f))
+      for (let f = frames - 2; f >= 0; f--) dil[f] = Math.max(dil[f], dil[f + 1] - slopeAt(f))
+      for (let f = 0; f < frames; f++) dil[f] = Math.min(dil[f], capAt(f))
+      for (let f = 0; f < frames; f++) dropCurve[f] = dil[f]
+      if (process.env.LECODES_PLANT_TRACE === clip.name) console.log(`[drop] ${Array.from(dropCurve).map((v, i) => `${i}:${(v * 100).toFixed(0)}`).join(' ')}`)
+      for (const [ li, dyOf ] of need) {
+        const ws = new Float32Array(frames).fill(1)
+        for (let f = 0; f < frames; f++) { const dy = dyOf[f]; if (!Number.isNaN(dy) && dy > 0.001 && dropCurve[f] < dy) ws[f] = Math.max(0, dropCurve[f]) / dy }
+        wScaleAt.set(li, ws)
+      }
+    }
+
+    // Pass 2 — the frames.
+    for (let f = 0; f < frames; f++) {
+      const time = timeOf(f)
+      const { dw } = frameFK(f)
+      const active = new Set<string>()
+      if (f === 0) rootFirst = [ ...rootXZ() ]
+      if (f === frames - 1) rootLast = [ ...rootXZ() ]
+
+      if (legs.length) {
+        // the body's vertical correction for this frame (pass 1, `dropCurve`): everything moves
+        {
+          const dy = dropCurve[f]
+          if (dy !== 0) for (let i = 0; i < wpos.length; i++) if (wpos[i]) wpos[i] = [ wpos[i][0], wpos[i][1] - dy, wpos[i][2] ]
+        }
+        for (const [ li, leg ] of legs.entries()) {
+          const g = goalOf(leg, dw)
+          let goal = g.effector
+          let pl = plantAt(li, f, g.contact, wrot[leg.effector])
+          if (pl) { pl.w *= wScaleAt.get(li)?.[f] ?? 1; if (pl.w <= 0) pl = null }
+          // a lock-only hand is FK unless locked
+          if (leg.lockOnly && !pl) continue
+          // a foot in a TOUCH span but not locked never goes UNDER its ground (the body drop for a
+          // hand contact would otherwise push the trailing foot through the floor)
+          const clampBy = leg.isFoot && !pl && g.contact[1] < leg.baseTarget - 0.005 ? leg.baseTarget - g.contact[1] : 0
+          if (clampBy > 0) goal = [ goal[0], goal[1] + clampBy, goal[2] ]
+          if (pl) {
+            // the lock: the foot at its held rotation, the ball at the anchor, the ankle from the two —
+            // and never past the leg's REACH: a share of the pull that would straighten the leg beyond
+            // 99.8 % of its length is cut back until the blended goal is reachable (a snapped-straight
+            // knee is worse than a foot a few millimetres off its anchor for a frame)
+            const rotFK = wrot[leg.effector]
+            const total = leg.lengths.reduce((x, y) => x + y, 0)
+            const hip = wpos[leg.chain[0]]
+            const blend = (w: number): { rot: Quat; goal: Vec3 } => {
+              const rot = qnorm(qslerp(rotFK, pl!.rot, w))
+              const ankle = sub(pl!.anchor, qrot(rot, contactOff(leg)))
+              return { rot, goal: [ 0, 1, 2 ].map((i) => g.effector[i] + (ankle[i] - g.effector[i]) * w) as Vec3 }
+            }
+            let b = blend(pl.w)
+            if (len(sub(b.goal, hip)) > 0.998 * total && len(sub(g.effector, hip)) <= 0.998 * total) {
+              let lo = 0, hi = pl.w
+              for (let it = 0; it < 6; it++) { const mid = (lo + hi) / 2; if (len(sub(blend(mid).goal, hip)) > 0.998 * total) hi = mid; else lo = mid }
+              pl.w = lo; b = blend(lo)
+            }
+            wrot[leg.effector] = b.rot
+            goal = b.goal
+          }
+          // Out of reach: what the LEG cannot do. The two feet differing in shape (the target's ball
+          // elsewhere under its ankle than the donor's, scaled) costs a few cm at full extension and
+          // is nobody's fault — the ball lands short by that much, silently.
+          const slack = len(sub(scl(sub(dw.pos[leg.donorContact], dw.pos[leg.donorEffector]), leg.contactRatio), sub(wpos[leg.contact], wpos[leg.effector])))
+          const short = placeLeg(leg, goal, wrot, wpos, bendOf(li, leg, dw)) - slack
+          if (process.env.LECODES_PLANT_TRACE === clip.name && clampBy > 0) console.log(`[floor] f ${f} ${leg.name} raised ${(clampBy * 1000).toFixed(0)}mm → ball y ${(wpos[leg.contact][1] * 1000).toFixed(0)} (ground ${(leg.baseTarget * 1000).toFixed(0)}) short ${(short * 1000).toFixed(0)}mm drop ${(dropCurve[f] * 1000).toFixed(0)}`)
+          if (process.env.LECODES_PLANT_TRACE === clip.name && leg.chain.length >= 2) { const u = sub(wpos[leg.chain[0]], wpos[leg.chain[1]]), v = sub(wpos[leg.effector], wpos[leg.chain[1]]); console.log(`[knee] f ${f} ${leg.name} bend ${(180 - Math.acos(Math.max(-1, Math.min(1, (u[0] * v[0] + u[1] * v[1] + u[2] * v[2]) / (len(u) * len(v))))) * 180 / Math.PI).toFixed(1)}° dist ${(len(sub(goal, wpos[leg.chain[0]])) * 1000).toFixed(0)} total ${(leg.lengths.reduce((x, y) => x + y, 0) * 1000).toFixed(0)}`) }
+          if (pl && process.env.LECODES_PLANT_TRACE === clip.name) console.log(`[plant] f ${f} ${leg.name} w ${pl.w.toFixed(2)} anchor ${pl.anchor.map((v) => v.toFixed(3)).join(',')} ball ${wpos[leg.contact].map((v) => v.toFixed(3)).join(',')} err ${(len(sub(wpos[leg.contact], pl.anchor)) * 1000).toFixed(1)}mm short ${(short * 1000).toFixed(0)}mm`)
+          if (pl && pl.lockShare !== 0) {
+            // The plant is the CONTACT's (the ball rolls under a rising heel; the ankle moves). Where
+            // it stands is recorded at the strike, relative to the root's horizontal position.
+            // (a foot merely held at its clearance is no plant — the marks carry the touch)
+            const held = target.names[leg.contact]
+            const r = rootXZ(), c = wpos[leg.contact]
+            mark('plant', held, time, undefined, [ c[0] - r[0], c[1], c[2] - r[2] ]); active.add(`plant:${held}`)
+          }
+          if (short > report.legs[li].shortfall) report.legs[li].shortfall = short
+          if (short > 0.005) { mark('reach', leg.name, time, short); active.add(`reach:${leg.name}`) }
+          if (leg.isFoot) {
+            // Everything below the effector — the ball, the toes, their ends — against the ground.
+            const deepest = (): { bone: number; dip: number } => {
+              let worst = { bone: -1, dip: 0 }
+              const below = [ ...children[leg.effector] ]
+              while (below.length) {
+                const c = below.pop()!
+                const dip = lowestBind - wpos[c][1]
+                if (dip > worst.dip) worst = { bone: c, dip }
+                below.push(...children[c])
+              }
+              return worst
+            }
+            // The knee keeps the donor's extension (`goalOf`), so the two feet's shape difference
+            // lands on the ball — a centimetre or two, under the floor when the leg stands on it.
+            // That is the ANKLE's to absorb, as it is on a person: the foot pitches up about the
+            // ankle until the deepest bone is back on the floor (a few degrees of heel-down), the
+            // toes turning with it. Capped: past that the ground really is too far.
+            // Only what the transfer ADDED: the donor's own toes under its own floor (a crouch on
+            // the toe tips, a foot pointed into the ground by its animator) come across scaled and
+            // stay — an identity transfer must be exact.
+            const d = deepest()
+            let donorDip = 0
+            {
+              const stack = [ ...donorChildren[leg.donorEffector] ]
+              let low = Infinity
+              while (stack.length) { const c = stack.pop()!; low = Math.min(low, dw.pos[c][1]); stack.push(...donorChildren[c]) }
+              if (low < Infinity) donorDip = Math.max(0, donorLowestBind - low) * leg.ratio
+            }
+            d.dip -= donorDip
+            if (d.dip > 0.002) {
+              const v = sub(wpos[d.bone], wpos[leg.effector]), r = len(v)
+              const axis = unit(cross(v, [ 0, 1, 0 ]))
+              if (axis && r > 1e-4) {
+                const want = Math.min(1, (v[1] + d.dip) / r), have = v[1] / r
+                let ang = Math.asin(want) - Math.asin(Math.max(-1, Math.min(1, have)))
+                // a locked foot is on its ground already — the floor correction fades out with the lock
+                ang = Math.max(-FOOT_PITCH_CAP, Math.min(FOOT_PITCH_CAP, ang)) * (1 - (pl?.w ?? 0))
+                const tryPitch = (a: number): number => {
+                  const q = axisAngle(axis, a)
+                  const p = qrot(q, v)
+                  return p[1] - v[1]   // how much the deepest bone rises
+                }
+                if (tryPitch(ang) < tryPitch(-ang)) ang = -ang
+                const q = axisAngle(axis, ang)
+                const stack = [ leg.effector ]
+                while (stack.length) {
+                  const i = stack.pop()!
+                  wrot[i] = qnorm(qmul(q, wrot[i]))
+                  for (const c of children[i]) { wpos[c] = add(wpos[i], qrot(wrot[i], localOff[c])); stack.push(c) }
+                }
+              }
+            }
+            const left = deepest()
+            if (left.dip > 0.01) { mark('below', target.names[left.bone], time, left.dip); active.add(`below:${target.names[left.bone]}`) }
+          }
+        }
+      }
+      for (const k of [ ...open.keys() ]) if (!active.has(k)) open.delete(k)
+
+      // Twist helpers (header §6), after the legs settled: the bone's own axial turn relative to
+      // its mapped parent (twistIn) and its canonical child's relative to it (twistOut), both about
+      // the bone's reference axis; the helper rides the bone plus its share of the two.
+      for (const tw of twists) {
+        const aRef = qrot(ref[tw.parent], tw.axisLocal)
+        const dP = qmul(wrot[tw.parent], qinv(ref[tw.parent])), dG = qmul(wrot[tw.grand], qinv(ref[tw.grand])), dC = qmul(wrot[tw.child], qinv(ref[tw.child]))
+        const twistIn = twistAbout(qmul(qinv(dG), dP), aRef), twistOut = twistAbout(qmul(qinv(dP), dC), aRef)
+        const ang = twistFraction * (tw.t * twistOut - (1 - tw.t) * twistIn)
+        const aNow = qrot(wrot[tw.parent], tw.axisLocal)
+        wrot[tw.bone] = qnorm(qmul(axisAngle(aNow, ang), qmul(wrot[tw.parent], target.rest.r[tw.bone])))
+        const stack = [ tw.bone ]
+        while (stack.length) {
+          const i = stack.pop()!
+          for (const c of children[i]) { if (!driven.has(c)) wrot[c] = qnorm(qmul(wrot[i], target.rest.r[c])); wpos[c] = add(wpos[i], qrot(wrot[i], localOff[c])); stack.push(c) }
+        }
+      }
+
+      rootTrack.push([ ...rootXZ() ])
+      { const q = hipsIdx >= 0 ? wrot[hipsIdx] : null; hipsYawTrack.push(q ? Math.atan2(2 * (q[0] * q[2] + q[3] * q[1]), 1 - 2 * (q[0] * q[0] + q[1] * q[1])) : 0) }
+      for (const [ li, leg ] of legs.entries()) {
+        if (!footSide.has(li) && !handSide.has(li)) continue
+        let tr = contactTrack.get(li)
+        if (!tr) { tr = []; contactTrack.set(li, tr) }
+        tr.push([ ...wpos[leg.contact] ])
+      }
+      if (donorMarks?.platform) {
+        bodyTrack.push(skinned.map((i) => [ ...wpos[i] ] as Vec3))
+        hipsTrack.push(hipsIdx >= 0 ? [ ...wpos[hipsIdx] ] as Vec3 : [ ...rootXZ() ])
+        for (const li of footSide.keys()) { let tr = ankleTrack.get(li); if (!tr) { tr = []; ankleTrack.set(li, tr) }; tr.push([ ...wpos[legs[li].effector] ] as Vec3) }
+      }
+
+      for (const i of animated) {
+        const p = target.parents[i]
+        const local = p >= 0 ? qnorm(qmul(qinv(wrot[p]), wrot[i])) : wrot[i]
+        const c = chan(i)
+        if (c.times.length === f) { c.times.push(time); (c.rot ??= []).push(local) }
+      }
+      // Root and hips translation (header §6): what the root channel drops of the travel (`strip`)
+      // shifts everything below it, so the hips' channel adds back what they keep (`keep`).
+      if (rootIdx >= 0 && rootRefPos && donorRoot !== undefined) {
+        const travel = sub(wpos[rootIdx], rootRefPos)
+        let strip: Vec3 = [ 0, 0, 0 ], keep: Vec3 = [ 0, 0, 0 ]
+        if (separateRoot) {
+          if (rootMotion === 'root') { strip = [ 0, travel[1], 0 ]; keep = strip }
+          else if (rootMotion === 'none') { strip = travel; keep = [ 0, travel[1], 0 ] }
+          else { strip = travel; keep = travel }
+        } else if (rootMotion === 'none') strip = [ travel[0], 0, travel[2] ]
+        const rel = sub(sub(wpos[rootIdx], strip), parentPos)
+        const [ x, y, z ] = qrot(qinv(parentRot), rel)
+        ;(chan(rootIdx).pos ??= []).push([ x / parentScale, y / parentScale, z / parentScale ])
+        if (separateRoot && hipsParent >= 0) {
+          const [ hx, hy, hz ] = qrot(qinv(wrot[hipsParent]), add(sub(wpos[hipsIdx], wpos[hipsParent]), keep))
+          ;(chan(hipsIdx).pos ??= []).push([ hx / hipsParentScale, hy / hipsParentScale, hz / hipsParentScale ])
+        }
+      }
+    }
+
+    for (const c of channels.values()) reduce(c, eps, legBones.has(c.node) ? Math.min(epsDeg, epsLegDeg) : epsDeg)
+
+    const anim = doc.createAnimation(opts.rename ? opts.rename(clip.name) : clip.name)
+    let keys = 0
+    for (const c of channels.values()) {
+      const times = doc.createAccessor().setType('SCALAR').setArray(new Float32Array(c.times))
+      if (c.rot) {
+        const sampler = doc.createAnimationSampler().setInput(times).setOutput(
+          doc.createAccessor().setType('VEC4').setArray(new Float32Array(c.rot.flat())))
+        anim.addSampler(sampler).addChannel(doc.createAnimationChannel().setTargetNode(target.nodes[c.node]).setTargetPath('rotation').setSampler(sampler))
+        keys += c.times.length
+      }
+      if (c.pos) {
+        const sampler = doc.createAnimationSampler().setInput(times).setOutput(
+          doc.createAccessor().setType('VEC3').setArray(new Float32Array(c.pos.flat())))
+        anim.addSampler(sampler).addChannel(doc.createAnimationChannel().setTargetNode(target.nodes[c.node]).setTargetPath('translation').setSampler(sampler))
+        keys += c.times.length
+      }
+    }
+    // The marks (marks.ts): the donor's touch spans and still windows — what the lock above
+    // enforced — with `at` read off the OUTPUT (the contact bone where it stands, relative to the
+    // root that frame) and the target's staircase. Written to the animation's extras and the report.
+    const contacts: ClipContacts = { feet: { l: null, r: null }, l: [], r: [], first: null }
+    if (donorMarks) {
+      for (const [ li, side ] of footSide) {
+        const leg = legs[li]
+        const tr = contactTrack.get(li)
+        if (!tr || tr.length < 2) continue
+        contacts.feet[side] = target.names[leg.contact]
+        for (const sp of donorMarks[side]) {
+          const f0 = Math.min(tr.length - 1, Math.round(sp.from / dtM))
+          const r = rootTrack[f0], c = tr[f0]
+          contacts[side].push({ from: sp.from, to: sp.to, still: sp.still, at: [ c[0] - r[0], c[1], c[2] - r[2] ], ...(sp.step !== undefined ? { step: sp.step } : {}) })
+        }
+      }
+      contacts.first = donorMarks.first
+      if (stairsTarget) contacts.stairs = stairsTarget
+      for (const [ li, side ] of handSide) {
+        const leg = legs[li]
+        const tr = contactTrack.get(li)
+        if (!tr || tr.length < 2) continue
+        contacts.hands ??= { l: null, r: null }
+        contacts.hands[side] = target.names[leg.contact]
+        const key = side === 'l' ? 'hl' : 'hr'
+        const list = (contacts[key] ??= [])
+        for (const sp of side === 'l' ? donorMarks.hl : donorMarks.hr) {
+          const f0 = Math.min(tr.length - 1, Math.round(sp.from / dtM))
+          const r = rootTrack[f0], c = tr[f0]
+          list.push({ from: sp.from, to: sp.to, still: sp.still, at: [ c[0] - r[0], c[1], c[2] - r[2] ], ...(sp.step !== undefined ? { step: sp.step } : {}) })
+        }
+      }
+    }
+    const travel: [ number, number ] = [ rootLast[0] - rootFirst[0], rootLast[2] - rootFirst[2] ]
+    // …and the BODY DROP the locks asked for (per frame at the clip's fps, metres, + = down): what the
+    // lab plots against the contacts, and what a later runtime pass could re-derive from
+    const bodyDrop = Array.from(dropCurve).some((v) => Math.abs(v) > 1e-4) ? { fps: frames > 1 ? (frames - 1) / clip.duration : fps, drop: Array.from(dropCurve).map((v) => Math.round(v * 10000) / 10000) } : undefined
+    // The PLATFORM's ledge (marks.ts `fitPlatform`), fitted again on the OUTPUT — the target's own
+    // plants, grips and body against its own levels — so it sits where this rig's hands and feet
+    // actually are. Written beside `contacts` (not inside: the engine parses that block), with
+    // the root's x/z at frame 0 so the edge can be read as an absolute position too.
+    let platform: (PlatformMark & { root0: [ number, number ] }) | undefined
+    if (donorMarks?.platform && stairsTarget && bodyTrack.length === frames) {
+      const feetT = [ ...footSide ].filter(([ li ]) => contactTrack.get(li)?.length === frames).map(([ li, sd ]) => ({ track: { contact: contactTrack.get(li)!, ankle: ankleTrack.get(li) ?? contactTrack.get(li)! }, spans: donorMarks![sd] }))
+      const handsT = [ ...handSide ].filter(([ li ]) => contactTrack.get(li)?.length === frames).map(([ li, sd ]) => ({ track: { contact: contactTrack.get(li)!, ankle: contactTrack.get(li)! }, spans: sd === 'l' ? donorMarks!.hl : donorMarks!.hr }))
+      const pf = fitPlatform({ dt: dtM, root: rootTrack, hips: hipsTrack, heading: dHeadingAll, level0: stairsTarget.base, level1: stairsTarget.base + stairsTarget.riser, feet: feetT, hands: handsT, hang: donorMarks.hang, body: bodyTrack })
+      if (pf) platform = { ...pf, root0: [ rootFirst[0], rootFirst[2] ] }
+      else warn(`${clip.name}: the platform's edge could not be placed on the target`)
+    }
+    // the HEADING curve (heading.ts): the smoothed direction of the root's travel on the OUTPUT
+    const heading = rootTrack.length >= 2 ? headingCurve(rootTrack, hipsYawTrack, dtM, { endAt: opts.headingEnd }) : undefined
+    anim.setExtras({ ...(anim.getExtras() as Record<string, unknown>), lecodes: { contacts, travel, ...(bodyDrop ? { bodyDrop } : {}), ...(platform ? { platform } : {}), ...(heading ? { heading } : {}) } })
+    report.clips.push({ name: anim.getName(), duration: clip.duration, frames, keys, events, turn, contacts, travel, ...(platform ? { platform } : {}) })
+  }
+  return report
+}
+
+/**
+ * World positions implied by a set of world ROTATIONS, keeping the target's own bone offsets — i.e.
+ * "what does the rig look like posed like this".
+ */
+const posesFrom = (target: DocRig, worldRot: Quat[]): Vec3[] => {
+  const pos: Vec3[] = new Array(target.names.length)
+  for (const i of target.order) {
+    const p = target.parents[i]
+    if (p < 0) { pos[i] = target.bind.worldPos[i]; continue }
+    // The bone's offset expressed in its parent's BIND frame, re-applied in the parent's new frame.
+    const off = sub(target.bind.worldPos[i], target.bind.worldPos[p])
+    const local = qrot(qinv(target.bind.worldRot[p]), off)
+    pos[i] = add(pos[p], qrot(worldRot[p], local))
+  }
+  return pos
+}
+
+/** Attach every accessor in the document to a buffer (glTF requires one). */
+export const bindAccessors = (doc: Document): void => {
+  const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
+  for (const acc of doc.getRoot().listAccessors()) if (!acc.getBuffer()) acc.setBuffer(buffer)
+}