lecodes-sdk 0.19.1 → 0.20.0

package/src/gl/animation/core.ts

@@ -1,670 +1,736 @@
-// The engine-facing core behind Animator / Layer / Loop / Playback. NOT exported from the SDK: the
-// public classes are thin views over the records here. The engine (creator-anim) runs the whole
-// per-frame loop — sources, INERTIALIZED transitions, blend spaces, root motion — and this file only
-// binds clips, issues play / stop / blend calls and routes the engine's slot events back to playbacks.
-//
-// A layer shows exactly ONE source at a time: its one-shot, its loop, or nothing. A transition is not
-// a crossfade — the engine records the offset between the pose it SHOWED and the pose the new source
-// shows, and decays that offset away over `fade`. So the SDK keeps no fade bookkeeping and no slot
-// pool: a slot is simply a clip bound to a layer, restartable at will (docs/animation-v2-plan.md).
-
-import { AnimationClip } from "./AnimationClip"
-import { Loop } from "./Loop"
-import { Layer } from "./Layer"
-import { Playback } from "./Playback"
-import { Vec3 } from "../../math/vec"
-import type { Node } from "../Node"
-
-/** A position on a blend axis (1D) or plane (2D). */
-export type BlendPosition = number | readonly [number, number]
-
-/** The transition time (seconds) a play / playLoop without `fade` uses. */
-export const DEFAULT_FADE = 0.2
-
-export type PlayOptions = {
-  /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
-   *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
-  fade?: number
-  /** Transition seconds for the way in only (overrides `fade`). */
-  fadeIn?: number
-  /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
-   *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
-   *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
-   *  holding the last frame. */
-  fadeOut?: number
-  /** Playback rate for this clip (default 1). */
-  speed?: number
-  /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
-  restart?: boolean
-  /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
-   *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
-   *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
-  phase?: number | "match"
-  /** TURN WARP (degrees, + = left): the node turns this much in total over the clip instead of what the
-   *  clip's baked heading says — its turn curve scaled, so the difference grows where the clip turns and
-   *  pivots about the planted foot. A 45° start played with `turn: 60` turns 60; played with `turn: 45`
-   *  it lands on 45 exactly whatever the clip's own run-off. Needs `rootMotion` + `rootRotation` and a
-   *  clip with a baked heading (`lecodes assets marks` / `retarget`); a clip that turns under 10° is
-   *  left alone. Ignored by hosts without it. */
-  turn?: number
-}
-
-export type StopOptions = { fade?: number }
-
-export type LoopOptions = {
-  /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
-   *  playing (default 0.2; `0` = cut). */
-  fade?: number
-  /** Playback rate of the loop's clips (default 1). */
-  speed?: number
-  /** Where in the CYCLE to start, 0–1, or `'match'` = where the layer is now (what a gait loop taking
-   *  over from a start / turn clip wants). The members share one clock, so this is every member's phase. */
-  phase?: number | "match"
-}
-/** What a layer loops: one clip (name / index), or a blend space `{ name: position }`. */
-export type LoopDef = string | number | Record<string, BlendPosition>
-
-/** One clip the layer shows this frame — `layer.active` / `anim.active` (a debug overlay's list). */
-export type ActiveClip = {
-  name: string
-  clip: AnimationClip
-  /** contribution to the pose, 0–1: the shown one-shot 1, a loop member its blend share */
-  weight: number
-  /** clock (s) */
-  time: number
-  /** a member of the layer's loop (else the layer's one-shot) */
-  loop: boolean
-}
-
-export type LayerOptions = {
-  /** Bone name(s): the layer drives only these subtrees (`'Spine1'` = upper body). Default: the whole rig. */
-  mask?: string | string[]
-  /** Blend each clip's DELTA from its own first frame on top of the layers below (lean, breathe, recoil)
-   *  instead of overriding them. */
-  additive?: boolean
-  /** Layer contribution 0–1 (default 1). */
-  weight?: number
-}
-
-export type ClipEventHandler = (clip: string, layer: Layer) => void
-/** A foot planted: which one, and where in the world it landed. */
-export type StepHandler = (side: "left" | "right", position: Vec3) => void
-
-/** What the engine measured on a clip once it was bound to this skeleton (`anim.curves('Walk')`).
- *  The root curves are of the clip's ROOT bone — its travel is what root motion would move. */
-export type ClipCurves = {
-  /** total horizontal root travel, metres */
-  travel: number
-  /** mean root speed over the clip, m/s */
-  speed: number
-  /** total root yaw, radians (+ = left) */
-  turn: number
-  /** the root barely moves — an in-place clip */
-  inPlace: boolean
-  /** the clip has a gait cycle (feet planting in turn) — `phaseAt` is meaningful */
-  hasPhase: boolean
-  /** When each foot TOUCHES the ground, seconds — the phase anchor. `still` is the window inside it
-   *  where the foot is genuinely STATIONARY (a touching foot still rolls for its first beats, and a
-   *  stop take's final plant touches long before the body has braked); absent = never still.
-   *  `at` = where the foot is at the touch's start ([x, y, z], model space). */
-  contacts: { side: "left" | "right", from: number, to: number, at: [number, number, number], still?: { from: number, to: number } }[]
-  /** the HANDS on the ground (a cartwheel, a roll, a vault) — from the clip's marks in the GLB; empty when none */
-  hands: { side: "left" | "right", from: number, to: number, at: [number, number, number], still?: { from: number, to: number } }[]
-  /** A CLIMBING clip's tread levels (a stair or slope take): the model-space heights its feet plant
-   *  at, sorted ascending, with the riser (median level spacing — the step height the clip was
-   *  authored for). Absent on a flat clip. */
-  treads?: { riser: number, levels: number[] }
-  /** the gait phase at `time`: 0 at a left-foot-down, 0.5 at a right-foot-down; -1 without a cycle */
-  phaseAt(time: number): number
-  /** cumulative root travel (m) at `time` */
-  travelAt(time: number): number
-  /** cumulative root yaw (rad, + = left) at `time` */
-  turnAt(time: number): number
-  /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
-  speedAt(time: number): number
-  /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
-   *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
-  directionAt(time: number): [number, number]
-  /** the first time the clip has turned `yaw` radians (+ = left): where to enter a turn a body has
-   *  already begun, so the clip continues the move instead of restarting it */
-  timeAtTurn(yaw: number): number
-  /** How far this clip's pose is from `target`'s, in metres — the joint distance plus the velocity
-   *  difference over a tenth of a second, the planted foot weighted most. That difference is exactly
-   *  what a hand-over hands the transition to decay away, so it says what switching to `target` would
-   *  cost at `time`. The two are lined up by cycle PHASE (a clip that continues the walk) or by TIME
-   *  (`align: 'time'` — two clips that both begin from standing share no cycle). */
-  fitTo(target: string | number, time: number, options?: { align?: "phase" | "time" }): number | undefined
-  /** The earliest moment (seconds) at which handing over to `target` costs no more than `within`
-   *  metres — a start's last steps ARE the walk, so this is where it stops being worth playing.
-   *  `atContact` (default true) snaps to the next foot-down: a switch under a planted foot is the one
-   *  the eye forgives. -1 = the clip never gets that close. */
-  exitTo(target: string | number, options?: { within?: number, atContact?: boolean, align?: "phase" | "time" }): number
-  /** The knee's bend plane at `time`, predicted from the skeleton's calibrated hinge axis carried by
-   *  this clip's own thigh rotation — continuous even where the leg is straight (where a plane
-   *  derived from positions is pure noise). `pole` = unit direction from the hip→ankle line toward
-   *  the knee (a two-bone solver's bend direction), `normal` = the plane's normal; both in the model
-   *  pose's frame. Undefined = no leg chain, or no knee motion bound to calibrate from. */
-  kneePoleAt(side: "left" | "right", time: number): { pole: [number, number, number], normal: [number, number, number] } | undefined
-  /** The clip's baked physics at `time` (unit body mass, model space): `com` = the body's center of
-   *  mass (biomechanical segment fractions on the classified bones), `velocity` = its velocity
-   *  (= linear momentum per kg), `angular` = the angular momentum about the COM (m²/s per kg,
-   *  low-passed ~0.5 s — the REGULATED component, e.g. a turn's sustained yaw; the per-stride
-   *  pitch/roll exchange between the limbs and the trunk is filtered out),
-   *  `support` = per-foot load [left, right] — contact-gated, split by where the COM stands between
-   *  the feet, scaled by the vertical force proxy (above 1 on a landing impact, 0 in flight).
-   *  A model, not a measurement — meant for ranking transitions and display, both sides of any
-   *  comparison sharing the same model. Undefined = nothing classified on this skeleton. */
-  physicsAt(time: number): { com: [number, number, number], velocity: [number, number, number], angular: [number, number, number], support: [number, number] } | undefined
-  /** The clip's MATCHING FEATURE ROW at `time` — a fresh Float32Array(37) in the clip's heading
-   *  frame at that time (x lateral, + left; y up; z forward): 0–5 feet positions relative to the
-   *  pelvis' ground point, 6–11 feet velocities, 12–14 pelvis velocity, 15 pelvis height, 16–18
-   *  COM velocity, 19–20 support L/R, 21–22 contact phase L/R, 23 yaw angular momentum, 24–31 the
-   *  clip's own path 0.3/0.6/1.0/1.5 s ahead as (lateral, forward) pairs, 32–35 facing change at
-   *  those horizons (rad, + = left), 36 cyclic flag. What a trajectory-and-state matcher compares.
-   *  Undefined = no leg chain. */
-  featuresAt(time: number): Float32Array | undefined
-  /** The take is a LOOP by measurement: its seam is continuous (feet back where they started
-   *  relative to the root, no turn). Starts, stops and turns are not. */
-  cyclic: boolean
-}
-
-/** The calibrated knee hinge-axis report (`anim.kneeAxis('left')`): the axis in the thigh's local
- *  frame, and the calibration's own confidence — the angular spread of its measurements (radians;
- *  a real knee comes in at a few degrees) over `samples` consecutive-frame deltas of the pack.
- *  `plant` = the calibrated PLANT HEIGHTS (model space): where the ankle / toe actually sit under
- *  full weight, the median of the pack's still-window lows — absent when nothing plants. */
-export type KneeAxisReport = { axis: [number, number, number], spreadMean: number, spreadMax: number, samples: number, plant?: { ankleY: number, toeY: number } }
-
-// ---- records -------------------------------------------------------------------------------------
-
-/** A clip bound to a layer — one per (clip, layer), reused by every play. `playback` = the most recent
- *  one-shot on it (`playing` while it still owns the layer; kept after that so its handle can still be
- *  read — a restart re-enters the same slot with a new record). */
-export type SlotRec = { name: string, clip: AnimationClip, slot: number, layer: LayerRec, inBlend: boolean, playback?: PlaybackRec }
-export type PlaybackRec = { slot: SlotRec, playing: boolean, done: Promise<boolean>, resolve: (natural: boolean) => void }
-export type LayerRec = { index: number, view: Layer, slots: SlotRec[], loop?: LoopRec, weight: number, mask: string, additive: boolean }
-export type LoopRec = { layer: LayerRec, members: { name: string, slot: SlotRec }[], value: BlendPosition, view: Loop, dead: boolean }
-
-const handlers = new Map<number, (slot: number, type: number) => void>()
-const stepHandlers = new Map<number, (side: number, x: number, y: number, z: number) => void>()
-let eventsInstalled = false
-const ensureEvents = (): void => {
-  if (eventsInstalled) return
-  eventsInstalled = true
-  _creator.setOnAnimatorEvent((animatorId, slot, type) => handlers.get(animatorId)?.(slot, type))
-  _creator.setOnAnimatorStep((animatorId, side, x, y, z) => stepHandlers.get(animatorId)?.(side, x, y, z))
-}
-
-const settled = (slot: SlotRec): PlaybackRec => {
-  let resolve = (_n: boolean): void => {}
-  const done = new Promise<boolean>((r) => { resolve = r })
-  resolve(false)
-  return { slot, playing: false, done, resolve }
-}
-
-const curveInfo = new Float32Array(4)
-const kneeOut = new Float32Array(8)
-const physOut = new Float32Array(11)
-
-export class Core {
-  id = 0
-  /** Added clips by name (`addClip`) — the lookup index; an added name overrides an embedded one. */
-  readonly table = new Map<string, AnimationClip>()
-  readonly layers: LayerRec[] = []
-  speed = 1
-  private _embedded?: AnimationClip[]
-  private readonly _added: { name: string, clip: AnimationClip }[] = []
-  private _list?: AnimationClip[]
-  private readonly _listeners = new Map<string, Set<ClipEventHandler>>()
-
-  readonly node: Node
-  constructor(node: Node) { this.node = node; this.layers.push(this.newLayer()) }
-
-  // ---- clips ----
-  embedded(): AnimationClip[] {
-    if (!this._embedded) {
-      this._embedded = AnimationClip._ofSet(_creator.getGlbClipSet(this.node.id))
-      const seen = new Set<string>()
-      for (const c of this._embedded) {
-        if (seen.has(c.name)) console.warn(`Animator: ${this.node.name || "the node"} has several clips named '${c.name}' — by name you get the first; reach the others by index (anim.clip(n))`)
-        seen.add(c.name)
-      }
-    }
-    return this._embedded
-  }
-  /** The ordered clip list: the GLB's clips in file order (an added clip of the same name takes the
-   *  embedded one's place), then the remaining added clips in insertion order. Cached until addClip. */
-  clips(): AnimationClip[] {
-    if (this._list) return this._list
-    const out: AnimationClip[] = []
-    const placed = new Set<string>()
-    for (const c of this.embedded()) {
-      const override = this.table.get(c.name)
-      if (override && !placed.has(c.name)) { out.push(override); placed.add(c.name) }
-      else out.push(c)
-    }
-    for (const a of this._added) if (!placed.has(a.name)) { out.push(a.clip); placed.add(a.name) }
-    return this._list = out
-  }
-  addClip(name: string, clip: AnimationClip): void {
-    const i = this._added.findIndex((a) => a.name === name)
-    if (i >= 0) this._added[i] = { name, clip }
-    else this._added.push({ name, clip })
-    this.table.set(name, clip)
-    this._list = undefined
-  }
-  /** A clip by name (added first, then embedded), or by index into `clips()` (none = the first). */
-  resolveClip(ref: string | number | undefined): [string, AnimationClip] | undefined {
-    if (ref === undefined || typeof ref === "number") { const c = this.clips()[ref ?? 0]; return c ? [ c.name, c ] : undefined }
-    const c = this.table.get(ref) ?? this.embedded().find((e) => e.name === ref)
-    return c ? [ ref, c ] : undefined
-  }
-  private clipNames(): string { return this.clips().map((c) => c.name).join(", ") || "(empty)" }
-
-  // ---- lifecycle ----
-  /** Create the native animator on demand. False = nothing to animate (warned). */
-  ensure(): boolean {
-    if (this.id) return true
-    if (this.embedded().length === 0 && this.table.size === 0) { console.warn(`Animator: no clips on ${this.node.name || "the node"} — nothing to play`); return false }
-    ensureEvents()
-    this.id = _creator.animatorCreate(this.node.id)
-    if (!this.id) { console.warn("Animator: node has no transform hierarchy"); return false }
-    handlers.set(this.id, (slot, type) => this.onEvent(slot, type))
-    stepHandlers.set(this.id, (side, x, y, z) => this.onStep(side, x, y, z))
-    if (this._feet) _creator.animatorSetFeet(this.id, this._feet[0], this._feet[1])
-    if (this._warp) _creator.animatorSetWarpParams(this.id, this._warp)
-    if (this._feetParams && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, this._feetParams)
-    if (this.speed !== 1) _creator.animatorSetGlobal(this.id, this.speed, false)
-    for (const L of this.layers) if (L.index > 0) this.pushLayer(L)
-    return true
-  }
-  destroy(): void {
-    for (const L of this.layers) this.settleLayer(L)
-    if (this.id) { _creator.animatorDestroy(this.id); handlers.delete(this.id); stepHandlers.delete(this.id); this.id = 0 }
-    for (const L of this.layers) { L.slots = []; if (L.loop) { L.loop.dead = true; L.loop = undefined } }
-  }
-
-  // ---- layers ----
-  newLayer(options?: LayerOptions): LayerRec {
-    const rec: LayerRec = { index: this.layers.length, view: undefined as unknown as Layer, slots: [], weight: options?.weight ?? 1, mask: "", additive: options?.additive ?? false }
-    if (options?.mask !== undefined) rec.mask = Array.isArray(options.mask) ? options.mask.join("\n") : options.mask
-    rec.view = new Layer(rec, this)
-    return rec
-  }
-  addLayer(options: LayerOptions): Layer {
-    if (this.layers.length >= 255) { console.warn("Animator: too many layers"); return this.layers[this.layers.length - 1].view }
-    const rec = this.newLayer(options)
-    this.layers.push(rec)
-    if (this.id) this.pushLayer(rec)
-    return rec.view
-  }
-  /** Arm the layer's next transition with a wind-up: see `Layer.anticipate`. */
-  anticipate(L: LayerRec, amount: number): void { if (this.id) _creator.animatorSetLayerAnticipation?.(this.id, L.index, amount) }
-
-  pushLayer(L: LayerRec): void {
-    if (!this.id) return
-    for (const m of L.mask.split("\n")) if (m && !this.node.bone(m)) console.warn(`Animator: layer mask bone '${m}' not found under ${this.node.name || "the node"}`)
-    _creator.animatorSetLayer(this.id, L.index, L.weight, L.additive, L.mask)
-  }
-
-  // ---- slots ----
-  /** The layer's slot for the clip — bound on first use, reused after that. */
-  slotFor(L: LayerRec, name: string, clip: AnimationClip): SlotRec | undefined {
-    const have = L.slots.find((s) => s.name === name && s.clip === clip)
-    if (have) return have
-    const slot = _creator.animatorBind(this.id, clip._set, clip._index, L.index)
-    if (slot < 0) { console.warn(`Animator: could not bind clip '${name}'`); return undefined }
-    const bound = _creator.animatorBoundTracks(this.id, slot)
-    if (clip.trackCount > 0 && bound === 0) console.warn(`Animator: '${name}' — no track matched a node name under ${this.node.name || "the node"} (different rig?)`)
-    else if (bound < clip.trackCount) console.warn(`Animator: '${name}' — ${clip.trackCount - bound}/${clip.trackCount} tracks unbound (bone names not found)`)
-    const rec: SlotRec = { name, clip, slot, layer: L, inBlend: false }
-    L.slots.push(rec)
-    return rec
-  }
-
-  /** The base layer's native slot for a clip, bound on first ask (-1 = no such clip / no animator). */
-  slotIndex(ref: string | number): number {
-    const found = this.resolveClip(ref)
-    if (!found || !this.ensure()) return -1
-    return this.slotFor(this.layers[0], found[0], found[1])?.slot ?? -1
-  }
-
-  // ---- play / stop ----
-  play(L: LayerRec, ref: string | number | undefined, o: PlayOptions): Playback {
-    const found = this.resolveClip(ref)
-    if (!found) {
-      console.warn(`Animator: no clip ${ref === undefined ? "to play" : JSON.stringify(ref)} on ${this.node.name || "the node"} — table: ${this.clipNames()}`)
-      return new Playback(settled({ name: "", clip: AnimationClip._none(), slot: -1, layer: L, inBlend: false }), this)
-    }
-    const [name, clip] = found
-    if (!this.ensure()) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
-    const s = this.slotFor(L, name, clip)
-    if (!s) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
-    if (s.inBlend) { console.warn(`Animator: '${name}' is part of this layer's loop — use playLoop() to change what it rests on`); return new Playback(settled(s), this) }
-    const fadeIn = o.fadeIn ?? o.fade ?? DEFAULT_FADE
-    const fadeOut = o.fadeOut ?? o.fade ?? DEFAULT_FADE
-    const phase = this.entryPhase(L, o.phase)   // read BEFORE the play: what the layer shows now
-    this.settleLayer(L)   // the layer had one source: whatever it was, this play takes over from it
-    let resolve = (_n: boolean): void => {}
-    const done = new Promise<boolean>((r) => { resolve = r })
-    const rec: PlaybackRec = { slot: s, playing: true, done, resolve }
-    s.playback = rec
-    _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
-    if (o.turn !== undefined) _creator.animatorSlotSetTurn?.(this.id, s.slot, o.turn * Math.PI / 180, true)
-    if (phase !== undefined) _creator.animatorSeekPhase(this.id, s.slot, phase)
-    return new Playback(rec, this)
-  }
-  /** A one-shot on the layer hasn't handed over yet. */
-  busy(L: LayerRec): boolean { return L.slots.some((s) => s.playback?.playing === true) }
-  settle(p: PlaybackRec, natural: boolean): void {
-    p.playing = false
-    p.resolve(natural)
-  }
-  /** Resolve every pending playback on the layer as cut short. */
-  private settleLayer(L: LayerRec): void { for (const s of L.slots) if (s.playback?.playing) this.settle(s.playback, false) }
-  stopSlot(s: SlotRec, fade: number): void {
-    if (s.playback?.playing) this.settle(s.playback, false)
-    if (this.id && s.slot >= 0) _creator.animatorStop(this.id, s.layer.index, s.slot, fade)
-  }
-  stopLayer(L: LayerRec, fade: number): void {
-    this.settleLayer(L)
-    if (L.loop) { L.loop.dead = true; L.loop = undefined }
-    if (this.id) _creator.animatorStop(this.id, L.index, -1, fade)
-  }
-  stopAll(fade: number): void { for (const L of this.layers) this.stopLayer(L, fade) }
-
-  // ---- loop ----
-  loop(L: LayerRec, def: LoopDef, o: LoopOptions): Loop | undefined {
-    if (!this.ensure()) return undefined
-    const fade = o.fade ?? DEFAULT_FADE
-    const phase = this.entryPhase(L, o.phase)   // read BEFORE the members replace the layer's source
-    if (L.loop) { L.loop.dead = true; for (const m of L.loop.members) m.slot.inBlend = false; L.loop = undefined }
-    this.settleLayer(L)   // a one-shot on the layer is cut short by the new loop
-    const space: Record<string, BlendPosition> = typeof def === "object" ? def : {}
-    if (typeof def !== "object") {
-      const found = this.resolveClip(def)
-      if (!found) { console.warn(`Animator: no clip ${JSON.stringify(def)} to loop — table: ${this.clipNames()}`); return undefined }
-      space[found[0]] = 0
-    }
-    const rec: LoopRec = { layer: L, members: [], value: 0, view: undefined as unknown as Loop, dead: false }
-    rec.view = new Loop(rec, this)
-    const slots: number[] = [], positions: number[] = []
-    const is2D = Object.values(space).some((p) => typeof p !== "number")
-    for (const [name, at] of Object.entries(space)) {
-      const found = this.resolveClip(name)
-      if (!found) { console.warn(`Animator: loop clip '${name}' is not in the clip table`); continue }
-      const s = this.slotFor(L, name, found[1])
-      if (!s) continue
-      s.inBlend = true
-      rec.members.push({ name, slot: s })
-      slots.push(s.slot)
-      if (is2D) positions.push(typeof at === "number" ? at : at[0], typeof at === "number" ? 0 : at[1])
-      else positions.push(at as number)
-    }
-    L.loop = rec
-    _creator.animatorSetBlend(this.id, L.index, is2D ? 2 : 1, new Uint16Array(slots), new Float32Array(positions), fade, o.speed ?? 1)
-    if (phase !== undefined) this.setLoopPhase(rec, phase)
-    return rec.view
-  }
-  /** The phase the layer shows, 0–1 through the gait cycle (-1 = nothing / no cycle). */
-  layerPhase(L: LayerRec): number { return this.id ? _creator.animatorLayerPhase(this.id, L.index) : -1 }
-  /** The entry phase of a play / playLoop: a number as given, `'match'` = what the layer shows now
-   *  (undefined when it shows no cycle — then the clip starts at its own beginning). */
-  private entryPhase(L: LayerRec, want: number | "match" | undefined): number | undefined {
-    if (want === undefined) return undefined
-    if (typeof want === "number") return want
-    if (!this.id) return undefined
-    const p = this.layerPhase(L)
-    return p < 0 ? undefined : p
-  }
-  /** The loop's phase through its cycle, 0–1 (the members share one clock). */
-  loopPhase(b: LoopRec): number {
-    if (b.dead || b.layer.loop !== b) return 0
-    const p = this.layerPhase(b.layer)
-    return p < 0 ? 0 : p
-  }
-  setLoopPhase(b: LoopRec, phase: number): void {
-    const m = b.members[0]
-    if (!m || b.dead || !this.id) return
-    _creator.animatorSeekPhase(this.id, m.slot.slot, phase)   // seeking one member moves the group
-  }
-  setLoopValue(b: LoopRec, v: BlendPosition): void {
-    if (b.dead) { console.warn("Animator: this loop was replaced — use the object the latest playLoop() returned"); return }
-    b.value = v
-    if (!this.id) return
-    const [x, y] = typeof v === "number" ? [ v, 0 ] : [ v[0], v[1] ]
-    _creator.animatorSetBlendValue(this.id, b.layer.index, x, y)
-  }
-  /** What the layer shows this frame: its source — the one-shot, or the loop's members with their
-   *  blend shares — in binding order (stable rows). */
-  active(L: LayerRec): ActiveClip[] {
-    const out: ActiveClip[] = []
-    for (const s of L.slots) {
-      const weight = this.slotWeight(s)
-      if (weight <= 0) continue
-      out.push({ name: s.name, clip: s.clip, weight, time: this.slotTime(s), loop: s.inBlend })
-    }
-    return out
-  }
-  slotWeight(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotWeight(this.id, s.slot) : 0 }
-  /** The slot's gait phase now, wrapped into 0–1 (-1 without a cycle). */
-  slotPhase(s: SlotRec): number {
-    if (!this.id || s.slot < 0) return -1
-    const p = _creator.animatorSlotCurveAt(this.id, s.slot, 0, -1)
-    return p < 0 ? -1 : p - Math.floor(p)
-  }
-  /** A baked curve of the slot at its current time: 1 travel (m) / 2 yaw (rad) / 3 speed (m/s). */
-  slotCurveAt(s: SlotRec, which: 1 | 2 | 3): number { return this.id && s.slot >= 0 ? _creator.animatorSlotCurveAt(this.id, s.slot, which, -1) : 0 }
-  /** The clip's total root yaw, radians (+ = left). */
-  slotTurn(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorSlotTurn(this.id, s.slot) : 0 }
-  slotTime(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotTime(this.id, s.slot) : 0 }
-  seek(s: SlotRec, time: number): void { if (this.id && s.slot >= 0) _creator.animatorSeek(this.id, s.slot, time) }
-
-  /** Scrub: set a bound clip's playhead directly, seconds — an inspector's tool. */
-  seekTime(ref: string | number, time: number): void {
-    const found = this.resolveClip(ref)
-    if (!found || !this.ensure()) return
-    const s = this.slotFor(this.layers[0], found[0], found[1])
-    if (s) this.seek(s, time)
-  }
-  /** Re-aim a playing clip's TURN WARP (see `PlayOptions.turn`): the clip's baked heading is scaled so that the
-   *  whole clip turns `deg` — set mid-play, the scale applies to what is still to come, so a controller that
-   *  wants a different heading while a turn plays asks for (the clip's total × what it still needs / what
-   *  the clip still turns). Undefined `deg` switches the warp off. */
-  setTurnOf(ref: string | number, deg: number | undefined): void {
-    const found = this.resolveClip(ref)
-    if (!found || !this.ensure()) return
-    const s = this.slotFor(this.layers[0], found[0], found[1])
-    if (s) _creator.animatorSlotSetTurn?.(this.id, s.slot, (deg ?? 0) * Math.PI / 180, deg !== undefined)
-  }
-  /** A bound clip's current playhead, seconds (-1 = not bound). */
-  timeOf(ref: string | number): number {
-    const found = this.resolveClip(ref)
-    if (!found || !this.ensure()) return -1
-    const s = this.slotFor(this.layers[0], found[0], found[1])
-    return s ? this.slotTime(s) : -1
-  }
-
-  // ---- contacts, phase, root curves ----
-  /** What the engine measured on the clip once it was bound to this skeleton — binds it if needed. */
-  curves(ref: string | number): ClipCurves | undefined {
-    const found = this.resolveClip(ref)
-    if (!found || !this.ensure()) return undefined
-    const s = this.slotFor(this.layers[0], found[0], found[1])
-    if (!s) return undefined
-    const id = this.id, slot = s.slot
-    _creator.animatorSlotCurveInfo(id, slot, curveInfo)
-    const spans = _creator.animatorSlotContacts(id, slot, new Float32Array(0))
-    const buf = new Float32Array(spans * 8)   // stride 8: side, from, to, at xyz, stillFrom, stillTo
-    if (spans > 0) _creator.animatorSlotContacts(id, slot, buf)
-    const contacts: ClipCurves["contacts"] = [], hands: ClipCurves["hands"] = []
-    for (let i = 0; i < spans; i++) {
-      const still = buf[i * 8 + 6]! >= 0 ? { from: buf[i * 8 + 6]!, to: buf[i * 8 + 7]! } : undefined
-      // side 0 / 1 = the feet, 2 / 3 = the hands
-      const code = Math.round(buf[i * 8]!)
-      ;(code >= 2 ? hands : contacts).push({ side: code % 2 === 0 ? "left" : "right", from: buf[i * 8 + 1]!, to: buf[i * 8 + 2]!,
-        at: [ buf[i * 8 + 3]!, buf[i * 8 + 4]!, buf[i * 8 + 5]! ], still })
-    }
-    const nTreads = _creator.animatorSlotTreads(id, slot, new Float32Array(0))
-    let treads: ClipCurves["treads"]
-    if (nTreads > 0) {
-      const tBuf = new Float32Array(nTreads + 1)   // [0] = riser, then the levels
-      _creator.animatorSlotTreads(id, slot, tBuf)
-      treads = { riser: tBuf[0]!, levels: Array.from(tBuf.subarray(1)) }
-    }
-    const featuresAt = (time: number): Float32Array | undefined => {
-      const row = new Float32Array(37)
-      return _creator.animatorSlotFeatures(id, slot, time, row) ? row : undefined
-    }
-    const first = featuresAt(0)
-    return {
-      travel: curveInfo[1], speed: curveInfo[2], turn: _creator.animatorSlotTurn(id, slot),
-      inPlace: curveInfo[3] > 0.5, hasPhase: _creator.animatorSlotCurveAt(id, slot, 0, 0) >= 0, contacts, hands, treads,
-      featuresAt, cyclic: !!first && first[36]! > 0.5,
-      fitTo: (target: string | number, time: number, options: { align?: "phase" | "time" } = {}) => {
-        const c = this.fitCurve(s, target, options.align === "time" ? 1 : 0)
-        if (!c) return undefined
-        const f = Math.max(0, Math.min(c.values.length - 1, time / c.dt))
-        const k = Math.floor(f), u = f - k
-        return k + 1 >= c.values.length ? c.values[c.values.length - 1] : c.values[k] + (c.values[k + 1] - c.values[k]) * u
-      },
-      exitTo: (target: string | number, options: { within?: number, atContact?: boolean, align?: "phase" | "time" } = {}) =>
-        this.fitExit(s, target, options.within ?? 0.05, options.atContact ?? true, options.align === "time" ? 1 : 0),
-      phaseAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 0, time),
-      travelAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 1, time),
-      turnAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 2, time),
-      speedAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 3, time),
-      directionAt: (time: number) => [ _creator.animatorSlotCurveAt(id, slot, 4, time), _creator.animatorSlotCurveAt(id, slot, 5, time) ] as [number, number],
-      timeAtTurn: (yaw: number) => _creator.animatorSlotTimeAtTurn(id, slot, yaw),
-      kneePoleAt: (side: "left" | "right", time: number) => {
-        const ok = _creator.animatorSlotKneePole(id, slot, side === "left" ? 0 : 1, time, kneeOut)
-        if (!ok) return undefined
-        return { pole: [ kneeOut[0]!, kneeOut[1]!, kneeOut[2]! ] as [number, number, number], normal: [ kneeOut[3]!, kneeOut[4]!, kneeOut[5]! ] as [number, number, number] }
-      },
-      physicsAt: (time: number) => {
-        const ok = _creator.animatorSlotPhysics(id, slot, time, physOut)
-        if (!ok) return undefined
-        return {
-          com: [ physOut[0]!, physOut[1]!, physOut[2]! ] as [number, number, number],
-          velocity: [ physOut[3]!, physOut[4]!, physOut[5]! ] as [number, number, number],
-          angular: [ physOut[6]!, physOut[7]!, physOut[8]! ] as [number, number, number],
-          support: [ physOut[9]!, physOut[10]! ] as [number, number],
-        }
-      },
-    }
-  }
-  /** The skeleton's calibrated knee hinge axis for a side, with its confidence report — measured once
-   *  over every bound clip's knee rotation track. Undefined = no leg chain / no knee motion bound. */
-  kneeAxis(side: "left" | "right"): KneeAxisReport | undefined {
-    if (!this.ensure()) return undefined
-    const ok = _creator.animatorKneeAxis(this.id, side === "left" ? 0 : 1, kneeOut)
-    if (!ok) return undefined
-    const r: KneeAxisReport = { axis: [ kneeOut[0]!, kneeOut[1]!, kneeOut[2]! ], spreadMean: kneeOut[3]!, spreadMax: kneeOut[4]!, samples: kneeOut[5]! }
-    if (kneeOut[6]! > -1e8) r.plant = { ankleY: kneeOut[6]!, toeY: kneeOut[7]! }
-    return r
-  }
-  /** STEP WARP v2 (the warp rewrite's knobs): `stride` scales each foot's travel-direction offset
-   *  from its hip — the step shortens or lengthens, uniformly through stance and swing; `lift` is
-   *  METRES added to each foot's height, gated to the swing by the contact marks (0 = neutral,
-   *  negative = a shuffle — no probing), and half of what it adds raises the pelvis so the body
-   *  steps higher with the foot; `pitch` (degrees, + = toes up) rotates each foot about its
-   *  own lateral axis — a slope's foot rotation; `slope` (degrees, + = ascending) is the INVISIBLE
-   *  STAIRCASE: foot heights follow the incline (leading foot higher) and the feet auto-pitch by
-   *  the same angle — pair it with raising the character by tan(slope) × the stride-scaled clip
-   *  travel (`curves(clip).travelAt`), which holds every planted foot's world height constant on
-   *  its own tread. Solved in the calibrated knee hinge plane with a SOFT reach (a leg at its limit
-   *  keeps a residual knee bend instead of popping against the clamp), and whenever a leg would
-   *  overreach — a descent, a long stride — the pelvis lowers by exactly the excess (weighted by
-   *  the contact marks, spring-followed; zero when nothing overreaches, so an ascent or a shorter
-   *  stride is untouched). Omit / null = stage off. */
-  setStepWarp(options?: { stride?: number, lift?: number, pitch?: number, slope?: number } | null): void {
-    if (!this.ensure()) return
-    _creator.animatorSetStepWarp(this.id, !!options, options?.stride ?? 1, options?.lift ?? 0, options?.pitch ?? 0, options?.slope ?? 0)
-  }
-  /** A slot for a clip on the base layer, bound on demand — what the pair-wise measures address. */
-  private slotOf(ref: string | number): SlotRec | undefined {
-    const found = this.resolveClip(ref)
-    if (!found || !this.ensure()) return undefined
-    return this.slotFor(this.layers[0], found[0], found[1])
-  }
-  /** The baked distance curve between two clips, cached per pair (the engine caches the bake itself;
-   *  this keeps the samples on the JS side so a controller can read them per frame without copying). */
-  private readonly _fit = new Map<string, { dt: number, values: Float32Array }>()
-  private fitCurve(src: SlotRec, target: string | number, align: 0 | 1): { dt: number, values: Float32Array } | undefined {
-    const t = this.slotOf(target)
-    if (!t) return undefined
-    const key = `${src.slot}>${t.slot}:${align}`
-    const have = this._fit.get(key)
-    if (have) return have
-    const n = _creator.animatorSlotFit(this.id, src.slot, t.slot, align, new Float32Array(0))
-    if (n === 0) return undefined
-    const values = new Float32Array(n)
-    _creator.animatorSlotFit(this.id, src.slot, t.slot, align, values)
-    _creator.animatorSlotCurveInfo(this.id, src.slot, curveInfo)
-    const curve = { dt: curveInfo[0] || 1 / 60, values }
-    this._fit.set(key, curve)
-    return curve
-  }
-  /** The earliest moment handing `src` over to `target` costs no more than `within` metres. */
-  private fitExit(src: SlotRec, target: string | number, within: number, atContact: boolean, align: 0 | 1): number {
-    const t = this.slotOf(target)
-    return t ? _creator.animatorSlotExit(this.id, src.slot, t.slot, within, atContact, align) : -1
-  }
-
-  /** The contact bones, '
-'-joined per side ("" = classify by name). */
-  private _feet?: [string, string]
-  setFeet(left: string, right: string): void {
-    this._feet = [ left, right ]
-    if (this.id) _creator.animatorSetFeet(this.id, left, right)
-  }
-  /** Stride / orientation warping, as the engine's fixed-order parameter array. */
-  private _warp?: Float32Array
-  setWarp(params: Float32Array): void {
-    this._warp = params
-    if (this.id) _creator.animatorSetWarpParams(this.id, params)
-  }
-  /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
-  private _feetParams?: Float32Array
-  setFeetParams(params: Float32Array): void {
-    this._feetParams = params
-    if (this.id && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, params)
-  }
-  /** One foot's lock state after this frame's evaluation into `out` (8 floats); false = no such foot
-   *  or no feet stage on this host. */
-  footState(side: 0 | 1, out: Float32Array): boolean {
-    return this.id !== 0 && _creator.animatorFootState !== undefined && _creator.animatorFootState(this.id, side, out)
-  }
-  private readonly _steps = new Set<StepHandler>()
-  onStepHandler(cb: StepHandler): void { this._steps.add(cb) }
-  offStepHandler(cb: StepHandler): void { this._steps.delete(cb) }
-  private onStep(side: number, x: number, y: number, z: number): void {
-    if (this._steps.size === 0) return
-    const at = new Vec3(x, y, z)
-    for (const cb of [ ...this._steps ]) cb(side === 0 ? "left" : "right", at)
-  }
-
-  // ---- props ----
-  setSpeed(v: number): void { this.speed = v; if (this.id) _creator.animatorSetGlobal(this.id, v, false) }
-  setRootMotion(on: boolean, rotation = false): void { if (this.ensure()) _creator.animatorSetRootMotion(this.id, on ? "*" : "", (on ? 2 : 0) | (on && rotation ? 4 : 0)) }
-
-  // ---- events ----
-  on(event: string, cb: ClipEventHandler): void { (this._listeners.get(event) ?? this._listeners.set(event, new Set()).get(event)!).add(cb) }
-  off(event: string, cb: ClipEventHandler): void { this._listeners.get(event)?.delete(cb) }
-  /** Native slot event: 0 completed / 1 loop / 2 settled (no longer a source) / 3 hand-over / 4+i clip event i. */
-  private onEvent(slotIndex: number, type: number): void {
-    let s: SlotRec | undefined
-    for (const L of this.layers) { s = L.slots.find((x) => x.slot === slotIndex); if (s) break }
-    if (!s) return
-    if (type >= 4) {
-      const name = s.clip._events[type - 4]?.name
-      const cbs = name ? this._listeners.get(name) : undefined
-      if (cbs) for (const cb of [ ...cbs ]) cb(s.name, s.layer.view)
-      return
-    }
-    const p = s.playback
-    if (!p?.playing) return
-    if (type === 3) this.settle(p, true)          // hand-over: the clip is over; what the app starts now takes over from it
-    else if (type === 2) this.settle(p, false)    // dropped by the engine without the SDK asking (backstop)
-  }
-}
+// The engine-facing core behind Animator / Layer / Loop / Playback. NOT exported from the SDK: the
+// public classes are thin views over the records here. The engine (creator-anim) runs the whole
+// per-frame loop — sources, INERTIALIZED transitions, blend spaces, root motion — and this file only
+// binds clips, issues play / stop / blend calls and routes the engine's slot events back to playbacks.
+//
+// A layer shows exactly ONE source at a time: its one-shot, its loop, or nothing. A transition is not
+// a crossfade — the engine records the offset between the pose it SHOWED and the pose the new source
+// shows, and decays that offset away over `fade`. So the SDK keeps no fade bookkeeping and no slot
+// pool: a slot is simply a clip bound to a layer, restartable at will (docs/animation-v2-plan.md).
+
+import { AnimationClip } from "./AnimationClip"
+import { Loop } from "./Loop"
+import { Layer } from "./Layer"
+import { Playback } from "./Playback"
+import { Vec3 } from "../../math/vec"
+import type { Node } from "../Node"
+
+/** A position on a blend axis (1D) or plane (2D). */
+export type BlendPosition = number | readonly [number, number]
+
+/** The transition time (seconds) a play / playLoop without `fade` uses. */
+export const DEFAULT_FADE = 0.2
+
+export type PlayOptions = {
+  /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
+   *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
+  fade?: number
+  /** Transition seconds for the way in only (overrides `fade`). */
+  fadeIn?: number
+  /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
+   *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
+   *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
+   *  holding the last frame. */
+  fadeOut?: number
+  /** Playback rate for this clip (default 1). */
+  speed?: number
+  /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
+  restart?: boolean
+  /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
+   *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
+   *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
+  phase?: number | "match"
+  /** TURN WARP (degrees, + = left): the node turns this much in total over the clip instead of what the
+   *  clip's baked heading says — its turn curve scaled, so the difference grows where the clip turns and
+   *  pivots about the planted foot. A 45° start played with `turn: 60` turns 60; played with `turn: 45`
+   *  it lands on 45 exactly whatever the clip's own run-off. Needs `rootMotion` + `rootRotation` and a
+   *  clip with a baked heading (`lecodes assets marks` / `retarget`); a clip that turns under 10° is
+   *  left alone. Ignored by hosts without it. */
+  turn?: number
+}
+
+export type StopOptions = { fade?: number }
+
+export type LoopOptions = {
+  /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
+   *  playing (default 0.2; `0` = cut). */
+  fade?: number
+  /** Playback rate of the loop's clips (default 1). */
+  speed?: number
+  /** Where in the CYCLE to start, 0–1, or `'match'` = where the layer is now (what a gait loop taking
+   *  over from a start / turn clip wants). The members share one clock, so this is every member's phase. */
+  phase?: number | "match"
+}
+/** A blend member with its CYCLE given explicitly: `at` = its position, `offset` = its gait phase at t = 0
+ *  (0 = a left-foot-down, 0.5 = a right-foot-down, 0–1), `cycles` = how many gait cycles the clip holds
+ *  (a two-stride loop: 2). Both are measured offline from the clip's foot marks. Members given as a
+ *  bare position run in normalized time and have no cycle (nothing phase-matches to them). */
+export type BlendMember = { at: BlendPosition, offset?: number, cycles?: number }
+/** What a layer loops: one clip (name / index), or a blend space `{ name: position | { at, offset, cycles } }`. */
+export type LoopDef = string | number | Record<string, BlendPosition | BlendMember>
+
+/** One clip the layer shows this frame — `layer.active` / `anim.active` (a debug overlay's list). */
+export type ActiveClip = {
+  name: string
+  clip: AnimationClip
+  /** contribution to the pose, 0–1: the shown one-shot 1, a loop member its blend share */
+  weight: number
+  /** clock (s) */
+  time: number
+  /** a member of the layer's loop (else the layer's one-shot) */
+  loop: boolean
+}
+
+export type LayerOptions = {
+  /** Bone name(s): the layer drives only these subtrees (`'Spine1'` = upper body). Default: the whole rig. */
+  mask?: string | string[]
+  /** Blend each clip's DELTA from its own first frame on top of the layers below (lean, breathe, recoil)
+   *  instead of overriding them. */
+  additive?: boolean
+  /** Layer contribution 0–1 (default 1). */
+  weight?: number
+}
+
+export type ClipEventHandler = (clip: string, layer: Layer) => void
+/** A foot planted: which one, and where in the world it landed. */
+export type StepHandler = (side: "left" | "right", position: Vec3) => void
+
+/** A loop's GAIT CYCLE as two numbers — what a blend member's `{ offset, cycles }` wants: φ(t) = offset +
+ *  cycles · t / duration, 0 = a left-foot-down. `residual` = the worst foot-down's distance from that line
+ *  (cycles; a clean loop sits under 0.03), `steps` = the foot-downs it was fitted through. */
+export type ClipCycle = { offset: number, cycles: number, residual: number, steps: number }
+/** A loop's cycle found by POSE against a reference loop (`clipInfo(clip).alignTo(ref)`): the `{ offset,
+ *  cycles }` under which it shows the reference's pose at the reference's phase. `score` = the fit at that
+ *  alignment (metres, the joint distance + velocity measure), `margin` = how much worse the runner-up
+ *  alignment ≥ 0.2 cycle away is — near 0 means ambiguous (a mirror pair, an in-place idle). */
+export type ClipAlign = { offset: number, cycles: number, score: number, margin: number }
+
+/** What the engine measured on a clip once it was bound to this skeleton (`anim.clipInfo('Walk')`).
+ *  The root curves are of the clip's ROOT bone — its travel is what root motion would move. */
+export type ClipInfo = {
+  /** total horizontal root travel, metres */
+  travel: number
+  /** mean root speed over the clip, m/s */
+  speed: number
+  /** total root yaw, radians (+ = left) */
+  turn: number
+  /** the root barely moves — an in-place clip */
+  inPlace: boolean
+  /** The gait cycle fitted through the foot contacts (a foot already down at t = 0 is not a step) —
+   *  the numbers a blend member takes as `{ offset, cycles }`. Undefined: no steps. */
+  cycle(): ClipCycle | undefined
+  /** This loop's cycle found by POSE against `reference` (its cycle given, else `reference`'s `cycle()`,
+   *  else offset 0 / one cycle — the answer is then relative to the reference's own time). Reads no marks:
+   *  a markless loop (swimming, breathing, an upper-body sway) gets a cycle, and a marked one gets a
+   *  second opinion — a mirrored anchor shows as a 0.5 disagreement with `cycle()`. Undefined: nothing to compare. */
+  alignTo(reference: string | number, cycle?: { offset: number, cycles: number }): ClipAlign | undefined
+  /** the clip has a gait cycle (feet planting in turn) — `phaseAt` is meaningful */
+  hasPhase: boolean
+  /** When each foot TOUCHES the ground, seconds — the phase anchor. `still` is the window inside it
+   *  where the foot is genuinely STATIONARY (a touching foot still rolls for its first beats, and a
+   *  stop take's final plant touches long before the body has braked); absent = never still.
+   *  `at` = where the foot is at the touch's start ([x, y, z], model space). */
+  contacts: { side: "left" | "right", from: number, to: number, at: [number, number, number], still?: { from: number, to: number } }[]
+  /** the HANDS on the ground (a cartwheel, a roll, a vault) — from the clip's marks in the GLB; empty when none */
+  hands: { side: "left" | "right", from: number, to: number, at: [number, number, number], still?: { from: number, to: number } }[]
+  /** A CLIMBING clip's tread levels (a stair or slope take): the model-space heights its feet plant
+   *  at, sorted ascending, with the riser (median level spacing — the step height the clip was
+   *  authored for). Absent on a flat clip. */
+  treads?: { riser: number, levels: number[] }
+  /** the gait phase at `time`: 0 at a left-foot-down, 0.5 at a right-foot-down; -1 without a cycle */
+  phaseAt(time: number): number
+  /** cumulative root travel (m) at `time` */
+  travelAt(time: number): number
+  /** cumulative root yaw (rad, + = left) at `time` */
+  turnAt(time: number): number
+  /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
+  speedAt(time: number): number
+  /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
+   *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
+  directionAt(time: number): [number, number]
+  /** the first time the clip has turned `yaw` radians (+ = left): where to enter a turn a body has
+   *  already begun, so the clip continues the move instead of restarting it */
+  timeAtTurn(yaw: number): number
+  /** How far this clip's pose is from `target`'s, in metres — the joint distance plus the velocity
+   *  difference over a tenth of a second, the planted foot weighted most. That difference is exactly
+   *  what a hand-over hands the transition to decay away, so it says what switching to `target` would
+   *  cost at `time`. The two are lined up by cycle PHASE (a clip that continues the walk) or by TIME
+   *  (`align: 'time'` — two clips that both begin from standing share no cycle). */
+  fitTo(target: string | number, time: number, options?: { align?: "phase" | "time" }): number | undefined
+  /** The earliest moment (seconds) at which handing over to `target` costs no more than `within`
+   *  metres — a start's last steps ARE the walk, so this is where it stops being worth playing.
+   *  `atContact` (default true) snaps to the next foot-down: a switch under a planted foot is the one
+   *  the eye forgives. -1 = the clip never gets that close. */
+  exitTo(target: string | number, options?: { within?: number, atContact?: boolean, align?: "phase" | "time" }): number
+  /** The knee's bend plane at `time`, predicted from the skeleton's calibrated hinge axis carried by
+   *  this clip's own thigh rotation — continuous even where the leg is straight (where a plane
+   *  derived from positions is pure noise). `pole` = unit direction from the hip→ankle line toward
+   *  the knee (a two-bone solver's bend direction), `normal` = the plane's normal; both in the model
+   *  pose's frame. Undefined = no leg chain, or no knee motion bound to calibrate from. */
+  kneePoleAt(side: "left" | "right", time: number): { pole: [number, number, number], normal: [number, number, number] } | undefined
+  /** The clip's baked physics at `time` (unit body mass, model space): `com` = the body's center of
+   *  mass (biomechanical segment fractions on the classified bones), `velocity` = its velocity
+   *  (= linear momentum per kg), `angular` = the angular momentum about the COM (m²/s per kg,
+   *  low-passed ~0.5 s — the REGULATED component, e.g. a turn's sustained yaw; the per-stride
+   *  pitch/roll exchange between the limbs and the trunk is filtered out),
+   *  `support` = per-foot load [left, right] — contact-gated, split by where the COM stands between
+   *  the feet, scaled by the vertical force proxy (above 1 on a landing impact, 0 in flight).
+   *  A model, not a measurement — meant for ranking transitions and display, both sides of any
+   *  comparison sharing the same model. Undefined = nothing classified on this skeleton. */
+  physicsAt(time: number): { com: [number, number, number], velocity: [number, number, number], angular: [number, number, number], support: [number, number] } | undefined
+  /** The clip's MATCHING FEATURE ROW at `time` — a fresh Float32Array(37) in the clip's heading
+   *  frame at that time (x lateral, + left; y up; z forward): 0–5 feet positions relative to the
+   *  pelvis' ground point, 6–11 feet velocities, 12–14 pelvis velocity, 15 pelvis height, 16–18
+   *  COM velocity, 19–20 support L/R, 21–22 contact phase L/R, 23 yaw angular momentum, 24–31 the
+   *  clip's own path 0.3/0.6/1.0/1.5 s ahead as (lateral, forward) pairs, 32–35 facing change at
+   *  those horizons (rad, + = left), 36 cyclic flag. What a trajectory-and-state matcher compares.
+   *  Undefined = no leg chain. */
+  featuresAt(time: number): Float32Array | undefined
+  /** The take is a LOOP by measurement: its seam is continuous (feet back where they started
+   *  relative to the root, no turn). Starts, stops and turns are not. */
+  cyclic: boolean
+}
+
+/** The calibrated knee hinge-axis report (`anim.feet.kneeAxis('left')`): the axis in the thigh's local
+ *  frame, and the calibration's own confidence — the angular spread of its measurements (radians;
+ *  a real knee comes in at a few degrees) over `samples` consecutive-frame deltas of the pack.
+ *  `plant` = the calibrated PLANT HEIGHTS (model space): where the ankle / toe actually sit under
+ *  full weight, the median of the pack's still-window lows — absent when nothing plants. */
+export type KneeAxisReport = { axis: [number, number, number], spreadMean: number, spreadMax: number, samples: number, plant?: { ankleY: number, toeY: number } }
+
+// ---- records -------------------------------------------------------------------------------------
+
+/** A clip bound to a layer — one per (clip, layer), reused by every play. `playback` = the most recent
+ *  one-shot on it (`playing` while it still owns the layer; kept after that so its handle can still be
+ *  read — a restart re-enters the same slot with a new record). */
+export type SlotRec = { name: string, clip: AnimationClip, slot: number, layer: LayerRec, inBlend: boolean, playback?: PlaybackRec }
+export type PlaybackRec = { slot: SlotRec, playing: boolean, done: Promise<boolean>, resolve: (natural: boolean) => void }
+export type LayerRec = { index: number, view: Layer, slots: SlotRec[], loop?: LoopRec, weight: number, mask: string, additive: boolean }
+export type LoopRec = { layer: LayerRec, members: { name: string, slot: SlotRec }[], value: BlendPosition, view: Loop, dead: boolean }
+
+const handlers = new Map<number, (slot: number, type: number) => void>()
+const stepHandlers = new Map<number, (side: number, x: number, y: number, z: number) => void>()
+let eventsInstalled = false
+const ensureEvents = (): void => {
+  if (eventsInstalled) return
+  eventsInstalled = true
+  _creator.setOnAnimatorEvent((animatorId, slot, type) => handlers.get(animatorId)?.(slot, type))
+  _creator.setOnAnimatorStep((animatorId, side, x, y, z) => stepHandlers.get(animatorId)?.(side, x, y, z))
+}
+
+const settled = (slot: SlotRec): PlaybackRec => {
+  let resolve = (_n: boolean): void => {}
+  const done = new Promise<boolean>((r) => { resolve = r })
+  resolve(false)
+  return { slot, playing: false, done, resolve }
+}
+
+const curveInfo = new Float32Array(4)
+const kneeOut = new Float32Array(8)
+const physOut = new Float32Array(11)
+
+export class Core {
+  id = 0
+  /** Added clips by name (`addClip`) — the lookup index; an added name overrides an embedded one. */
+  readonly table = new Map<string, AnimationClip>()
+  readonly layers: LayerRec[] = []
+  speed = 1
+  private _embedded?: AnimationClip[]
+  private readonly _added: { name: string, clip: AnimationClip }[] = []
+  private _list?: AnimationClip[]
+  private readonly _listeners = new Map<string, Set<ClipEventHandler>>()
+
+  readonly node: Node
+  constructor(node: Node) { this.node = node; this.layers.push(this.newLayer()) }
+
+  // ---- clips ----
+  embedded(): AnimationClip[] {
+    if (!this._embedded) {
+      this._embedded = AnimationClip._ofSet(_creator.getGlbClipSet(this.node.id))
+      const seen = new Set<string>()
+      for (const c of this._embedded) {
+        if (seen.has(c.name)) console.warn(`Animator: ${this.node.name || "the node"} has several clips named '${c.name}' — by name you get the first; reach the others by index (anim.clip(n))`)
+        seen.add(c.name)
+      }
+    }
+    return this._embedded
+  }
+  /** The ordered clip list: the GLB's clips in file order (an added clip of the same name takes the
+   *  embedded one's place), then the remaining added clips in insertion order. Cached until addClip. */
+  clips(): AnimationClip[] {
+    if (this._list) return this._list
+    const out: AnimationClip[] = []
+    const placed = new Set<string>()
+    for (const c of this.embedded()) {
+      const override = this.table.get(c.name)
+      if (override && !placed.has(c.name)) { out.push(override); placed.add(c.name) }
+      else out.push(c)
+    }
+    for (const a of this._added) if (!placed.has(a.name)) { out.push(a.clip); placed.add(a.name) }
+    return this._list = out
+  }
+  addClip(name: string, clip: AnimationClip): void {
+    const i = this._added.findIndex((a) => a.name === name)
+    if (i >= 0) this._added[i] = { name, clip }
+    else this._added.push({ name, clip })
+    this.table.set(name, clip)
+    this._list = undefined
+  }
+  /** A clip by name (added first, then embedded), or by index into `clips()` (none = the first). */
+  resolveClip(ref: string | number | undefined): [string, AnimationClip] | undefined {
+    if (ref === undefined || typeof ref === "number") { const c = this.clips()[ref ?? 0]; return c ? [ c.name, c ] : undefined }
+    const c = this.table.get(ref) ?? this.embedded().find((e) => e.name === ref)
+    return c ? [ ref, c ] : undefined
+  }
+  private clipNames(): string { return this.clips().map((c) => c.name).join(", ") || "(empty)" }
+
+  // ---- lifecycle ----
+  /** Create the native animator on demand. False = nothing to animate (warned). */
+  ensure(): boolean {
+    if (this.id) return true
+    if (this.embedded().length === 0 && this.table.size === 0) { console.warn(`Animator: no clips on ${this.node.name || "the node"} — nothing to play`); return false }
+    ensureEvents()
+    this.id = _creator.animatorCreate(this.node.id)
+    if (!this.id) { console.warn("Animator: node has no transform hierarchy"); return false }
+    handlers.set(this.id, (slot, type) => this.onEvent(slot, type))
+    stepHandlers.set(this.id, (side, x, y, z) => this.onStep(side, x, y, z))
+    if (this._feet) _creator.animatorSetFeet(this.id, this._feet[0], this._feet[1])
+    if (this._warp) _creator.animatorSetWarpParams(this.id, this._warp)
+    if (this._feetParams && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, this._feetParams)
+    if (this.speed !== 1) _creator.animatorSetGlobal(this.id, this.speed, false)
+    for (const L of this.layers) if (L.index > 0) this.pushLayer(L)
+    return true
+  }
+  destroy(): void {
+    for (const L of this.layers) this.settleLayer(L)
+    if (this.id) { _creator.animatorDestroy(this.id); handlers.delete(this.id); stepHandlers.delete(this.id); this.id = 0 }
+    for (const L of this.layers) { L.slots = []; if (L.loop) { L.loop.dead = true; L.loop = undefined } }
+  }
+
+  // ---- layers ----
+  newLayer(options?: LayerOptions): LayerRec {
+    const rec: LayerRec = { index: this.layers.length, view: undefined as unknown as Layer, slots: [], weight: options?.weight ?? 1, mask: "", additive: options?.additive ?? false }
+    if (options?.mask !== undefined) rec.mask = Array.isArray(options.mask) ? options.mask.join("\n") : options.mask
+    rec.view = new Layer(rec, this)
+    return rec
+  }
+  addLayer(options: LayerOptions): Layer {
+    if (this.layers.length >= 255) { console.warn("Animator: too many layers"); return this.layers[this.layers.length - 1].view }
+    const rec = this.newLayer(options)
+    this.layers.push(rec)
+    if (this.id) this.pushLayer(rec)
+    return rec.view
+  }
+  /** Arm the layer's next transition with a wind-up: see `Layer.anticipate`. */
+  anticipate(L: LayerRec, amount: number): void { if (this.id) _creator.animatorSetLayerAnticipation?.(this.id, L.index, amount) }
+
+  pushLayer(L: LayerRec): void {
+    if (!this.id) return
+    for (const m of L.mask.split("\n")) if (m && !this.node.bone(m)) console.warn(`Animator: layer mask bone '${m}' not found under ${this.node.name || "the node"}`)
+    _creator.animatorSetLayer(this.id, L.index, L.weight, L.additive, L.mask)
+  }
+
+  // ---- slots ----
+  /** The layer's slot for the clip — bound on first use, reused after that. */
+  slotFor(L: LayerRec, name: string, clip: AnimationClip): SlotRec | undefined {
+    const have = L.slots.find((s) => s.name === name && s.clip === clip)
+    if (have) return have
+    const slot = _creator.animatorBind(this.id, clip._set, clip._index, L.index)
+    if (slot < 0) { console.warn(`Animator: could not bind clip '${name}'`); return undefined }
+    const bound = _creator.animatorBoundTracks(this.id, slot)
+    if (clip.trackCount > 0 && bound === 0) console.warn(`Animator: '${name}' — no track matched a node name under ${this.node.name || "the node"} (different rig?)`)
+    else if (bound < clip.trackCount) console.warn(`Animator: '${name}' — ${clip.trackCount - bound}/${clip.trackCount} tracks unbound (bone names not found)`)
+    const rec: SlotRec = { name, clip, slot, layer: L, inBlend: false }
+    L.slots.push(rec)
+    return rec
+  }
+
+  /** The base layer's native slot for a clip, bound on first ask (-1 = no such clip / no animator). */
+  slotIndex(ref: string | number): number {
+    const found = this.resolveClip(ref)
+    if (!found || !this.ensure()) return -1
+    return this.slotFor(this.layers[0], found[0], found[1])?.slot ?? -1
+  }
+
+  // ---- play / stop ----
+  play(L: LayerRec, ref: string | number | undefined, o: PlayOptions): Playback {
+    const found = this.resolveClip(ref)
+    if (!found) {
+      console.warn(`Animator: no clip ${ref === undefined ? "to play" : JSON.stringify(ref)} on ${this.node.name || "the node"} — table: ${this.clipNames()}`)
+      return new Playback(settled({ name: "", clip: AnimationClip._none(), slot: -1, layer: L, inBlend: false }), this)
+    }
+    const [name, clip] = found
+    if (!this.ensure()) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
+    const s = this.slotFor(L, name, clip)
+    if (!s) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
+    if (s.inBlend) { console.warn(`Animator: '${name}' is part of this layer's loop — use playLoop() to change what it rests on`); return new Playback(settled(s), this) }
+    const fadeIn = o.fadeIn ?? o.fade ?? DEFAULT_FADE
+    const fadeOut = o.fadeOut ?? o.fade ?? DEFAULT_FADE
+    const phase = this.entryPhase(L, o.phase)   // read BEFORE the play: what the layer shows now
+    this.settleLayer(L)   // the layer had one source: whatever it was, this play takes over from it
+    let resolve = (_n: boolean): void => {}
+    const done = new Promise<boolean>((r) => { resolve = r })
+    const rec: PlaybackRec = { slot: s, playing: true, done, resolve }
+    s.playback = rec
+    _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
+    if (o.turn !== undefined) _creator.animatorSlotSetTurn?.(this.id, s.slot, o.turn * Math.PI / 180, true)
+    if (phase !== undefined) _creator.animatorSeekPhase(this.id, s.slot, phase)
+    return new Playback(rec, this)
+  }
+  /** A one-shot on the layer hasn't handed over yet. */
+  busy(L: LayerRec): boolean { return L.slots.some((s) => s.playback?.playing === true) }
+  settle(p: PlaybackRec, natural: boolean): void {
+    p.playing = false
+    p.resolve(natural)
+  }
+  /** Resolve every pending playback on the layer as cut short. */
+  private settleLayer(L: LayerRec): void { for (const s of L.slots) if (s.playback?.playing) this.settle(s.playback, false) }
+  stopSlot(s: SlotRec, fade: number): void {
+    if (s.playback?.playing) this.settle(s.playback, false)
+    if (this.id && s.slot >= 0) _creator.animatorStop(this.id, s.layer.index, s.slot, fade)
+  }
+  stopLayer(L: LayerRec, fade: number): void {
+    this.settleLayer(L)
+    if (L.loop) { L.loop.dead = true; L.loop = undefined }
+    if (this.id) _creator.animatorStop(this.id, L.index, -1, fade)
+  }
+  stopAll(fade: number): void { for (const L of this.layers) this.stopLayer(L, fade) }
+
+  // ---- loop ----
+  loop(L: LayerRec, def: LoopDef, o: LoopOptions): Loop | undefined {
+    if (!this.ensure()) return undefined
+    const fade = o.fade ?? DEFAULT_FADE
+    const phase = this.entryPhase(L, o.phase)   // read BEFORE the members replace the layer's source
+    if (L.loop) { L.loop.dead = true; for (const m of L.loop.members) m.slot.inBlend = false; L.loop = undefined }
+    this.settleLayer(L)   // a one-shot on the layer is cut short by the new loop
+    const space: Record<string, BlendPosition | BlendMember> = typeof def === "object" ? def : {}
+    if (typeof def !== "object") {
+      const found = this.resolveClip(def)
+      if (!found) { console.warn(`Animator: no clip ${JSON.stringify(def)} to loop — table: ${this.clipNames()}`); return undefined }
+      space[found[0]] = 0
+    }
+    const rec: LoopRec = { layer: L, members: [], value: 0, view: undefined as unknown as Loop, dead: false }
+    rec.view = new Loop(rec, this)
+    const slots: number[] = [], positions: number[] = [], phases: number[] = []
+    const posOf = (m: BlendPosition | BlendMember): BlendPosition => typeof m === "object" && !Array.isArray(m) ? (m as BlendMember).at : m as BlendPosition
+    const is2D = Object.values(space).some((m) => typeof posOf(m) !== "number")
+    for (const [name, m] of Object.entries(space)) {
+      const found = this.resolveClip(name)
+      if (!found) { console.warn(`Animator: loop clip '${name}' is not in the clip table`); continue }
+      const s = this.slotFor(L, name, found[1])
+      if (!s) continue
+      s.inBlend = true
+      rec.members.push({ name, slot: s })
+      slots.push(s.slot)
+      const at = posOf(m)
+      if (is2D) positions.push(typeof at === "number" ? at : at[0], typeof at === "number" ? 0 : at[1])
+      else positions.push(at as number)
+      // (offset, cycles) — cycles 0 = normalized time, no cycle
+      const cyc = typeof m === "object" && !Array.isArray(m) ? (m as BlendMember) : undefined
+      phases.push(cyc?.cycles && cyc.cycles > 0 ? (cyc.offset ?? 0) : 0, cyc?.cycles && cyc.cycles > 0 ? cyc.cycles : 0)
+    }
+    L.loop = rec
+    _creator.animatorSetBlend(this.id, L.index, is2D ? 2 : 1, new Uint16Array(slots), new Float32Array(positions), fade, o.speed ?? 1, new Float32Array(phases))
+    if (phase !== undefined) this.setLoopPhase(rec, phase)
+    return rec.view
+  }
+  /** The phase the layer shows, 0–1 through the gait cycle (-1 = nothing / no cycle). */
+  layerPhase(L: LayerRec): number { return this.id ? _creator.animatorLayerPhase(this.id, L.index) : -1 }
+  /** The entry phase of a play / playLoop: a number as given, `'match'` = what the layer shows now
+   *  (undefined when it shows no cycle — then the clip starts at its own beginning). */
+  private entryPhase(L: LayerRec, want: number | "match" | undefined): number | undefined {
+    if (want === undefined) return undefined
+    if (typeof want === "number") return want
+    if (!this.id) return undefined
+    const p = this.layerPhase(L)
+    return p < 0 ? undefined : p
+  }
+  /** The loop's phase through its cycle, 0–1 (the members share one clock). */
+  loopPhase(b: LoopRec): number {
+    if (b.dead || b.layer.loop !== b) return 0
+    const p = this.layerPhase(b.layer)
+    return p < 0 ? 0 : p
+  }
+  setLoopPhase(b: LoopRec, phase: number): void {
+    const m = b.members[0]
+    if (!m || b.dead || !this.id) return
+    _creator.animatorSeekPhase(this.id, m.slot.slot, phase)   // seeking one member moves the group
+  }
+  setLoopValue(b: LoopRec, v: BlendPosition): void {
+    if (b.dead) { console.warn("Animator: this loop was replaced — use the object the latest playLoop() returned"); return }
+    b.value = v
+    if (!this.id) return
+    const [x, y] = typeof v === "number" ? [ v, 0 ] : [ v[0], v[1] ]
+    _creator.animatorSetBlendValue(this.id, b.layer.index, x, y)
+  }
+  /** What the layer shows this frame: its source — the one-shot, or the loop's members with their
+   *  blend shares — in binding order (stable rows). */
+  active(L: LayerRec): ActiveClip[] {
+    const out: ActiveClip[] = []
+    for (const s of L.slots) {
+      const weight = this.slotWeight(s)
+      if (weight <= 0) continue
+      out.push({ name: s.name, clip: s.clip, weight, time: this.slotTime(s), loop: s.inBlend })
+    }
+    return out
+  }
+  slotWeight(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotWeight(this.id, s.slot) : 0 }
+  /** The slot's gait phase now, wrapped into 0–1 (-1 without a cycle). */
+  slotPhase(s: SlotRec): number {
+    if (!this.id || s.slot < 0) return -1
+    const p = _creator.animatorSlotCurveAt(this.id, s.slot, 0, -1)
+    return p < 0 ? -1 : p - Math.floor(p)
+  }
+  /** A baked curve of the slot at its current time: 1 travel (m) / 2 yaw (rad) / 3 speed (m/s). */
+  slotCurveAt(s: SlotRec, which: 1 | 2 | 3): number { return this.id && s.slot >= 0 ? _creator.animatorSlotCurveAt(this.id, s.slot, which, -1) : 0 }
+  /** The clip's total root yaw, radians (+ = left). */
+  slotTurn(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorSlotTurn(this.id, s.slot) : 0 }
+  slotTime(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotTime(this.id, s.slot) : 0 }
+  seek(s: SlotRec, time: number): void { if (this.id && s.slot >= 0) _creator.animatorSeek(this.id, s.slot, time) }
+
+  /** Scrub: set a bound clip's playhead directly, seconds — an inspector's tool. */
+  seekTime(ref: string | number, time: number): void {
+    const found = this.resolveClip(ref)
+    if (!found || !this.ensure()) return
+    const s = this.slotFor(this.layers[0], found[0], found[1])
+    if (s) this.seek(s, time)
+  }
+  /** Re-aim a playing clip's TURN WARP (see `PlayOptions.turn`): the clip's baked heading is scaled so that the
+   *  whole clip turns `deg` — set mid-play, the scale applies to what is still to come, so a controller that
+   *  wants a different heading while a turn plays asks for (the clip's total × what it still needs / what
+   *  the clip still turns). Undefined `deg` switches the warp off. */
+  setTurnOf(ref: string | number, deg: number | undefined): void {
+    const found = this.resolveClip(ref)
+    if (!found || !this.ensure()) return
+    const s = this.slotFor(this.layers[0], found[0], found[1])
+    if (s) _creator.animatorSlotSetTurn?.(this.id, s.slot, (deg ?? 0) * Math.PI / 180, deg !== undefined)
+  }
+  /** A bound clip's current playhead, seconds (-1 = not bound). */
+  timeOf(ref: string | number): number {
+    const found = this.resolveClip(ref)
+    if (!found || !this.ensure()) return -1
+    const s = this.slotFor(this.layers[0], found[0], found[1])
+    return s ? this.slotTime(s) : -1
+  }
+
+  // ---- contacts, phase, root curves ----
+  // The linear gait cycle through a clip's foot-downs — the bake's anchor rule (the first step: left → 0,
+  // right → 0.5; +0.5 per change of foot, +1 for the same foot again) fitted with the cycle count fixed at
+  // steps / 2 (every foot lands once per cycle): offset = the mean residual, wrapped. A span starting at
+  // t = 0 is a foot already down, not a step — unless the foot is airborne at the clip's end (the seam of a
+  // loop is its landing) while the clip does not start with both feet down.
+  /** What the engine measured on the clip once it was bound to this skeleton — binds it if needed. */
+  clipInfo(ref: string | number): ClipInfo | undefined {
+    const found = this.resolveClip(ref)
+    if (!found || !this.ensure()) return undefined
+    const s = this.slotFor(this.layers[0], found[0], found[1])
+    if (!s) return undefined
+    const id = this.id, slot = s.slot
+    _creator.animatorSlotCurveInfo(id, slot, curveInfo)
+    const spans = _creator.animatorSlotContacts(id, slot, new Float32Array(0))
+    const buf = new Float32Array(spans * 8)   // stride 8: side, from, to, at xyz, stillFrom, stillTo
+    if (spans > 0) _creator.animatorSlotContacts(id, slot, buf)
+    const contacts: ClipInfo["contacts"] = [], hands: ClipInfo["hands"] = []
+    for (let i = 0; i < spans; i++) {
+      const still = buf[i * 8 + 6]! >= 0 ? { from: buf[i * 8 + 6]!, to: buf[i * 8 + 7]! } : undefined
+      // side 0 / 1 = the feet, 2 / 3 = the hands
+      const code = Math.round(buf[i * 8]!)
+      ;(code >= 2 ? hands : contacts).push({ side: code % 2 === 0 ? "left" : "right", from: buf[i * 8 + 1]!, to: buf[i * 8 + 2]!,
+        at: [ buf[i * 8 + 3]!, buf[i * 8 + 4]!, buf[i * 8 + 5]! ], still })
+    }
+    const nTreads = _creator.animatorSlotTreads(id, slot, new Float32Array(0))
+    let treads: ClipInfo["treads"]
+    if (nTreads > 0) {
+      const tBuf = new Float32Array(nTreads + 1)   // [0] = riser, then the levels
+      _creator.animatorSlotTreads(id, slot, tBuf)
+      treads = { riser: tBuf[0]!, levels: Array.from(tBuf.subarray(1)) }
+    }
+    const featuresAt = (time: number): Float32Array | undefined => {
+      const row = new Float32Array(37)
+      return _creator.animatorSlotFeatures(id, slot, time, row) ? row : undefined
+    }
+    const first = featuresAt(0)
+    return {
+      travel: curveInfo[1], speed: curveInfo[2], turn: _creator.animatorSlotTurn(id, slot),
+      inPlace: curveInfo[3] > 0.5, hasPhase: _creator.animatorSlotCurveAt(id, slot, 0, 0) >= 0, contacts, hands, treads,
+      featuresAt, cyclic: !!first && first[36]! > 0.5,
+      fitTo: (target: string | number, time: number, options: { align?: "phase" | "time" } = {}) => {
+        const c = this.fitCurve(s, target, options.align === "time" ? 1 : 0)
+        if (!c) return undefined
+        const f = Math.max(0, Math.min(c.values.length - 1, time / c.dt))
+        const k = Math.floor(f), u = f - k
+        return k + 1 >= c.values.length ? c.values[c.values.length - 1] : c.values[k] + (c.values[k + 1] - c.values[k]) * u
+      },
+      exitTo: (target: string | number, options: { within?: number, atContact?: boolean, align?: "phase" | "time" } = {}) =>
+        this.fitExit(s, target, options.within ?? 0.05, options.atContact ?? true, options.align === "time" ? 1 : 0),
+      cycle: () => fitCycle(contacts, found[1].duration),
+      alignTo: (reference: string | number, cycle?: { offset: number, cycles: number }) => {
+        const r = this.slotOf(reference)
+        if (!r) return undefined
+        const rc = cycle ?? this.clipInfo(reference)?.cycle() ?? { offset: 0, cycles: 1 }
+        const out = new Float32Array(4)
+        if (!_creator.animatorSlotAlign(id, r.slot, slot, rc.offset, rc.cycles, out)) return undefined
+        return { offset: out[0]!, cycles: out[1]!, score: out[2]!, margin: out[3]! }
+      },
+      phaseAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 0, time),
+      travelAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 1, time),
+      turnAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 2, time),
+      speedAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 3, time),
+      directionAt: (time: number) => [ _creator.animatorSlotCurveAt(id, slot, 4, time), _creator.animatorSlotCurveAt(id, slot, 5, time) ] as [number, number],
+      timeAtTurn: (yaw: number) => _creator.animatorSlotTimeAtTurn(id, slot, yaw),
+      kneePoleAt: (side: "left" | "right", time: number) => {
+        const ok = _creator.animatorSlotKneePole(id, slot, side === "left" ? 0 : 1, time, kneeOut)
+        if (!ok) return undefined
+        return { pole: [ kneeOut[0]!, kneeOut[1]!, kneeOut[2]! ] as [number, number, number], normal: [ kneeOut[3]!, kneeOut[4]!, kneeOut[5]! ] as [number, number, number] }
+      },
+      physicsAt: (time: number) => {
+        const ok = _creator.animatorSlotPhysics(id, slot, time, physOut)
+        if (!ok) return undefined
+        return {
+          com: [ physOut[0]!, physOut[1]!, physOut[2]! ] as [number, number, number],
+          velocity: [ physOut[3]!, physOut[4]!, physOut[5]! ] as [number, number, number],
+          angular: [ physOut[6]!, physOut[7]!, physOut[8]! ] as [number, number, number],
+          support: [ physOut[9]!, physOut[10]! ] as [number, number],
+        }
+      },
+    }
+  }
+  /** The skeleton's calibrated knee hinge axis for a side, with its confidence report — measured once
+   *  over every bound clip's knee rotation track. Undefined = no leg chain / no knee motion bound. */
+  kneeAxis(side: "left" | "right"): KneeAxisReport | undefined {
+    if (!this.ensure()) return undefined
+    const ok = _creator.animatorKneeAxis(this.id, side === "left" ? 0 : 1, kneeOut)
+    if (!ok) return undefined
+    const r: KneeAxisReport = { axis: [ kneeOut[0]!, kneeOut[1]!, kneeOut[2]! ], spreadMean: kneeOut[3]!, spreadMax: kneeOut[4]!, samples: kneeOut[5]! }
+    if (kneeOut[6]! > -1e8) r.plant = { ankleY: kneeOut[6]!, toeY: kneeOut[7]! }
+    return r
+  }
+  /** STEP WARP v2 (the warp rewrite's knobs): `stride` scales each foot's travel-direction offset
+   *  from its hip — the step shortens or lengthens, uniformly through stance and swing; `lift` is
+   *  METRES added to each foot's height, gated to the swing by the contact marks (0 = neutral,
+   *  negative = a shuffle — no probing), and half of what it adds raises the pelvis so the body
+   *  steps higher with the foot; `pitch` (degrees, + = toes up) rotates each foot about its
+   *  own lateral axis — a slope's foot rotation; `slope` (degrees, + = ascending) is the INVISIBLE
+   *  STAIRCASE: foot heights follow the incline (leading foot higher) and the feet auto-pitch by
+   *  the same angle — pair it with raising the character by tan(slope) × the stride-scaled clip
+   *  travel (`clipInfo(clip).travelAt`), which holds every planted foot's world height constant on
+   *  its own tread. Solved in the calibrated knee hinge plane with a SOFT reach (a leg at its limit
+   *  keeps a residual knee bend instead of popping against the clamp), and whenever a leg would
+   *  overreach — a descent, a long stride — the pelvis lowers by exactly the excess (weighted by
+   *  the contact marks, spring-followed; zero when nothing overreaches, so an ascent or a shorter
+   *  stride is untouched). Omit / null = stage off. */
+  setStepWarp(options?: { stride?: number, lift?: number, pitch?: number, slope?: number } | null): void {
+    if (!this.ensure()) return
+    _creator.animatorSetStepWarp(this.id, !!options, options?.stride ?? 1, options?.lift ?? 0, options?.pitch ?? 0, options?.slope ?? 0)
+  }
+  /** A slot for a clip on the base layer, bound on demand — what the pair-wise measures address. */
+  private slotOf(ref: string | number): SlotRec | undefined {
+    const found = this.resolveClip(ref)
+    if (!found || !this.ensure()) return undefined
+    return this.slotFor(this.layers[0], found[0], found[1])
+  }
+  /** The baked distance curve between two clips, cached per pair (the engine caches the bake itself;
+   *  this keeps the samples on the JS side so a controller can read them per frame without copying). */
+  private readonly _fit = new Map<string, { dt: number, values: Float32Array }>()
+  private fitCurve(src: SlotRec, target: string | number, align: 0 | 1): { dt: number, values: Float32Array } | undefined {
+    const t = this.slotOf(target)
+    if (!t) return undefined
+    const key = `${src.slot}>${t.slot}:${align}`
+    const have = this._fit.get(key)
+    if (have) return have
+    const n = _creator.animatorSlotFit(this.id, src.slot, t.slot, align, new Float32Array(0))
+    if (n === 0) return undefined
+    const values = new Float32Array(n)
+    _creator.animatorSlotFit(this.id, src.slot, t.slot, align, values)
+    _creator.animatorSlotCurveInfo(this.id, src.slot, curveInfo)
+    const curve = { dt: curveInfo[0] || 1 / 60, values }
+    this._fit.set(key, curve)
+    return curve
+  }
+  /** The earliest moment handing `src` over to `target` costs no more than `within` metres. */
+  private fitExit(src: SlotRec, target: string | number, within: number, atContact: boolean, align: 0 | 1): number {
+    const t = this.slotOf(target)
+    return t ? _creator.animatorSlotExit(this.id, src.slot, t.slot, within, atContact, align) : -1
+  }
+
+  /** The contact bones, '
+'-joined per side ("" = classify by name). */
+  private _feet?: [string, string]
+  setFeet(left: string, right: string): void {
+    this._feet = [ left, right ]
+    if (this.id) _creator.animatorSetFeet(this.id, left, right)
+  }
+  /** Stride / orientation warping, as the engine's fixed-order parameter array. */
+  private _warp?: Float32Array
+  setWarp(params: Float32Array): void {
+    this._warp = params
+    if (this.id) _creator.animatorSetWarpParams(this.id, params)
+  }
+  /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
+  private _feetParams?: Float32Array
+  setFeetParams(params: Float32Array): void {
+    this._feetParams = params
+    if (this.id && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, params)
+  }
+  /** One foot's lock state after this frame's evaluation into `out` (8 floats); false = no such foot
+   *  or no feet stage on this host. */
+  footState(side: 0 | 1, out: Float32Array): boolean {
+    return this.id !== 0 && _creator.animatorFootState !== undefined && _creator.animatorFootState(this.id, side, out)
+  }
+  private readonly _steps = new Set<StepHandler>()
+  onStepHandler(cb: StepHandler): void { this._steps.add(cb) }
+  offStepHandler(cb: StepHandler): void { this._steps.delete(cb) }
+  private onStep(side: number, x: number, y: number, z: number): void {
+    if (this._steps.size === 0) return
+    const at = new Vec3(x, y, z)
+    for (const cb of [ ...this._steps ]) cb(side === 0 ? "left" : "right", at)
+  }
+
+  // ---- props ----
+  setSpeed(v: number): void { this.speed = v; if (this.id) _creator.animatorSetGlobal(this.id, v, false) }
+  setRootMotion(on: boolean, rotation = false): void { if (this.ensure()) _creator.animatorSetRootMotion(this.id, on ? "*" : "", (on ? 2 : 0) | (on && rotation ? 4 : 0)) }
+
+  // ---- events ----
+  on(event: string, cb: ClipEventHandler): void { (this._listeners.get(event) ?? this._listeners.set(event, new Set()).get(event)!).add(cb) }
+  off(event: string, cb: ClipEventHandler): void { this._listeners.get(event)?.delete(cb) }
+  /** Native slot event: 0 completed / 1 loop / 2 settled (no longer a source) / 3 hand-over / 4+i clip event i. */
+  private onEvent(slotIndex: number, type: number): void {
+    let s: SlotRec | undefined
+    for (const L of this.layers) { s = L.slots.find((x) => x.slot === slotIndex); if (s) break }
+    if (!s) return
+    if (type >= 4) {
+      const name = s.clip._events[type - 4]?.name
+      const cbs = name ? this._listeners.get(name) : undefined
+      if (cbs) for (const cb of [ ...cbs ]) cb(s.name, s.layer.view)
+      return
+    }
+    const p = s.playback
+    if (!p?.playing) return
+    if (type === 3) this.settle(p, true)          // hand-over: the clip is over; what the app starts now takes over from it
+    else if (type === 2) this.settle(p, false)    // dropped by the engine without the SDK asking (backstop)
+  }
+}
+
+function fitCycle(contacts: ClipInfo["contacts"], duration: number): ClipCycle | undefined {
+  if (!(duration > 0)) return undefined
+  const sides = [ "left", "right" ] as const
+  const bothDown = sides.every((side) => contacts.some((c) => c.side === side && c.from <= 0.02))
+  const steps: { t: number, side: 0 | 1 }[] = []
+  for (let side = 0; side < 2; side++) {
+    const spans = contacts.filter((c) => c.side === sides[side]).sort((a, b) => a.from - b.from)
+    const airborneAtEnd = spans.length > 0 && spans[spans.length - 1]!.to < duration * 0.85
+    for (const sp of spans) if (sp.from > 0.02 || (airborneAtEnd && !bothDown)) steps.push({ t: sp.from, side: side as 0 | 1 })
+  }
+  steps.sort((a, b) => a.t - b.t)
+  if (steps.length === 0) return undefined
+  const phi: number[] = []
+  for (let i = 0; i < steps.length; i++) phi.push(i === 0 ? (steps[0]!.side === 0 ? 0 : 0.5) : phi[i - 1]! + (steps[i]!.side !== steps[i - 1]!.side ? 0.5 : 1))
+  const cycles = steps.length / 2
+  let offset = 0
+  for (let i = 0; i < steps.length; i++) offset += phi[i]! - cycles * steps[i]!.t / duration
+  offset /= steps.length
+  offset -= Math.floor(offset)
+  let residual = 0
+  for (let i = 0; i < steps.length; i++) { let d = phi[i]! - (offset + cycles * steps[i]!.t / duration); d -= Math.round(d); residual = Math.max(residual, Math.abs(d)) }
+  return { offset, cycles, residual, steps: steps.length }
+}