lecodes-gl-lite 2.0.0

package/src/vendor/creator-anim/js/index.ts

@@ -0,0 +1,656 @@
+// creator-anim's TypeScript side over the wasm build (dist/creatorAnim.js): the animation bridge the
+// WEB hosts (viewer-lite's WebGL engine, lecodes-headless headless) hand to the app — the same
+// `_creator` animation method shapes creator-gl exposes natively, so the SDK never knows which host
+// it runs on, and the SAME evaluator (one C++ implementation, no TS twin).
+//
+// The host supplies its scene graph (`AnimHost`): entity lookup with a local matrix per node, a
+// "local matrix changed" notification, the fetch store for loadClips, and the two sinks the
+// evaluator's outputs go to (morph weights, root motion for a character controller).
+//
+// `loadCreatorAnim()` must have resolved before `createAnimBridge` — the web hosts await it in their
+// async setup (createViewerLite / runProject) so the SDK's first animator call finds the module ready.
+
+import createCreatorAnim, { type CreatorAnimModule } from "../dist/creatorAnim.js"
+
+export type Mat4Like = Float32Array | number[]
+
+export type AnimHost = {
+  /** Entity lookup (undefined when unknown). `skinJoint` marks joints of a GLB skin. */
+  get(id: number): { id: number, name: string, m: Mat4Like, parent: number, children: number[], skinJoint?: boolean } | undefined
+  /** A joint's local matrix was rewritten (WebGL: worldMatrixNeedsUpdate). */
+  localMatrixChanged(id: number): void
+  /** Fetched buffer for a systemId (loadClips). */
+  getBuffer(systemId: number): ArrayBuffer | undefined
+  /** Morph-target weights sampled for an entity (WebGL: the node's blendshape weights). */
+  setMorphWeights?(entityId: number, weights: Float32Array): void
+  /** World matrix of a node — footsteps are reported in world space. Without it the animator node's
+   *  own local matrix is used (right whenever the character hangs directly off the scene root). */
+  world?(entityId: number): Mat4Like | undefined
+  /** Root motion for a CharacterController on the node or an ancestor: the node-local delta this frame.
+   *  Return true when a controller took it (as a velocity); false → the evaluator moves the node. */
+  applyRootMotion?(entityId: number, dx: number, dy: number, dz: number, dt: number, yaw: number): boolean
+}
+
+export type ClipInfo = { name: string, duration: number, trackCount: number }
+
+let modulePromise: Promise<CreatorAnimModule> | null = null
+let loaded: CreatorAnimModule | null = null
+/** The wasm module, loaded once per process. */
+export const loadCreatorAnim = (): Promise<CreatorAnimModule> => (modulePromise ??= createCreatorAnim().then((m) => (loaded = m)))
+export const isCreatorAnimLoaded = (): boolean => loaded !== null
+
+// ---- heap helpers --------------------------------------------------------------------------------
+
+const withF32 = <T>(mod: CreatorAnimModule, values: ArrayLike<number>, fn: (ptr: number) => T): T => {
+  const ptr = mod._malloc(Math.max(4, values.length * 4))
+  mod.HEAPF32.set(values, ptr >> 2)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+const withU16 = <T>(mod: CreatorAnimModule, values: ArrayLike<number>, fn: (ptr: number) => T): T => {
+  const ptr = mod._malloc(Math.max(4, values.length * 2))
+  mod.HEAPU16.set(values, ptr >> 1)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+const withString = <T>(mod: CreatorAnimModule, s: string, fn: (ptr: number) => T): T => {
+  const n = mod.lengthBytesUTF8(s) + 1
+  const ptr = mod._malloc(n)
+  mod.stringToUTF8(s, ptr, n)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+const withBytes = <T>(mod: CreatorAnimModule, bytes: Uint8Array, fn: (ptr: number) => T): T => {
+  const ptr = mod._malloc(Math.max(1, bytes.length))
+  mod.HEAPU8.set(bytes, ptr)
+  try { return fn(ptr) } finally { mod._free(ptr) }
+}
+
+// ---- matrix helpers (column-major 4×4) -----------------------------------------------------------
+
+/** T·R·S into a column-major 4×4 (no allocation). */
+const composeInto = (m: Mat4Like, tx: number, ty: number, tz: number, x: number, y: number, z: number, w: number, sx: number, sy: number, sz: number): void => {
+  const x2 = x + x, y2 = y + y, z2 = z + z
+  const xx = x * x2, xy = x * y2, xz = x * z2, yy = y * y2, yz = y * z2, zz = z * z2, wx = w * x2, wy = w * y2, wz = w * z2
+  const a = m as number[]
+  a[0] = (1 - (yy + zz)) * sx; a[1] = (xy + wz) * sx; a[2] = (xz - wy) * sx; a[3] = 0
+  a[4] = (xy - wz) * sy; a[5] = (1 - (xx + zz)) * sy; a[6] = (yz + wx) * sy; a[7] = 0
+  a[8] = (xz + wy) * sz; a[9] = (yz - wx) * sz; a[10] = (1 - (xx + yy)) * sz; a[11] = 0
+  a[12] = tx; a[13] = ty; a[14] = tz; a[15] = 1
+}
+
+/** Column-major 4×4 → translation, rotation quat (x,y,z,w), scale. */
+export const decomposeTRS = (m: Mat4Like): { t: [number, number, number], r: [number, number, number, number], s: [number, number, number] } => {
+  const a = m as ArrayLike<number>
+  let sx = Math.hypot(a[0], a[1], a[2]), sy = Math.hypot(a[4], a[5], a[6]), sz = Math.hypot(a[8], a[9], a[10])
+  const det = a[0] * (a[5] * a[10] - a[6] * a[9]) - a[4] * (a[1] * a[10] - a[2] * a[9]) + a[8] * (a[1] * a[6] - a[2] * a[5])
+  if (det < 0) sx = -sx
+  const ix = sx !== 0 ? 1 / sx : 0, iy = sy !== 0 ? 1 / sy : 0, iz = sz !== 0 ? 1 / sz : 0
+  const m00 = a[0] * ix, m10 = a[1] * ix, m20 = a[2] * ix
+  const m01 = a[4] * iy, m11 = a[5] * iy, m21 = a[6] * iy
+  const m02 = a[8] * iz, m12 = a[9] * iz, m22 = a[10] * iz
+  const trace = m00 + m11 + m22
+  let x: number, y: number, z: number, w: number
+  if (trace > 0) {
+    const s = 0.5 / Math.sqrt(trace + 1)
+    w = 0.25 / s; x = (m21 - m12) * s; y = (m02 - m20) * s; z = (m10 - m01) * s
+  } else if (m00 > m11 && m00 > m22) {
+    const s = 2 * Math.sqrt(1 + m00 - m11 - m22)
+    w = (m21 - m12) / s; x = 0.25 * s; y = (m01 + m10) / s; z = (m02 + m20) / s
+  } else if (m11 > m22) {
+    const s = 2 * Math.sqrt(1 + m11 - m00 - m22)
+    w = (m02 - m20) / s; x = (m01 + m10) / s; y = 0.25 * s; z = (m12 + m21) / s
+  } else {
+    const s = 2 * Math.sqrt(1 + m22 - m00 - m11)
+    w = (m10 - m01) / s; x = (m02 + m20) / s; y = (m12 + m21) / s; z = 0.25 * s
+  }
+  return { t: [ a[12], a[13], a[14] ], r: [ x, y, z, w ], s: [ sx, sy, sz ] }
+}
+
+/** m = m · R_y(a): a turn about the matrix's own up axis. */
+const rotateLocalY = (m: Mat4Like, a: number): void => {
+  const c = Math.cos(a), s = Math.sin(a)
+  const x0 = m[0], x1 = m[1], x2 = m[2], z0 = m[8], z1 = m[9], z2 = m[10]
+  m[0] = x0 * c - z0 * s; m[1] = x1 * c - z1 * s; m[2] = x2 * c - z2 * s
+  m[8] = x0 * s + z0 * c; m[9] = x1 * s + z1 * c; m[10] = x2 * s + z2 * c
+}
+
+// ---- the bridge ----------------------------------------------------------------------------------
+
+type Rec = {
+  rootId: number
+  entities: number[]   // library joint index → entity id (the pre-order the skeleton was described in)
+  trs: number          // heap: 10 floats per joint
+  write: number        // heap: 1 byte per joint
+  n: number
+  feetOn: boolean      // the feet stage (lock / ground IK) is on: answer its ground probes each frame
+  // IK chains: the library handle, the nodes read each late pass (0 = none), the parameter shadow the
+  // node reads are merged into before every solve (CANIM_IK_* order)
+  iks: { ik: number, target: number, pole: number, rotation: number, params: Float32Array }[]
+  // node-driven sockets: the empty read each late pass
+  sockets: { set: string, name: string, node: number }[]
+}
+
+// A wasm predating the chains (the vendored build not yet rebuilt): warn once, keep the chains inert.
+let warnedStale = false
+const hasChains = (mod: CreatorAnimModule): boolean => {
+  if (typeof mod._canimAnimatorLateSolve === "function") return true
+  if (!warnedStale) { warnedStale = true; console.warn("creator-anim: this wasm predates IK chains / sockets — rebuild it (build-wasm.sh + vendor:creator); chains are inert") }
+  return false
+}
+
+const IK_COUNT = 19
+const IK = { TARGET_X: 0, POLE_X: 3, HAS_POLE: 6, ROT_X: 8 }
+
+const MAX_EVENTS = 64
+const IDENTITY: Mat4Like = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+
+export function createAnimBridge(host: AnimHost) {
+  const mod = loaded
+  if (!mod) throw new Error("creator-anim: await loadCreatorAnim() before createAnimBridge()")
+  const animators = new Map<number, Rec>()
+  let onEvent: ((animatorId: number, slot: number, type: number) => void) | null = null
+  // scratch heap cells, allocated once
+  const out4 = mod._malloc(16)
+  const out3 = mod._malloc(12)
+  const m16 = mod._malloc(64)                           // the animator node's world matrix, handed over per frame
+  const probeFrom = mod._malloc(12), probeTo = mod._malloc(12), out8 = mod._malloc(32)
+  const i32a = mod._malloc(4), u32a = mod._malloc(4)
+  const evPairs = mod._malloc(MAX_EVENTS * 4)
+  const pending: { id: number, slot: number, type: number }[] = []
+  const steps: { id: number, side: number, x: number, y: number, z: number }[] = []
+  let onStep: ((animatorId: number, side: number, x: number, y: number, z: number) => void) | null = null
+
+  const loadSet = (buf: ArrayBuffer | Uint8Array): number => {
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf)
+    return withBytes(mod, bytes, (ptr) => mod._canimClipsLoad(ptr, bytes.length))
+  }
+
+  const freeRec = (rec: Rec): void => { mod._free(rec.trs); mod._free(rec.write) }
+
+  const methods = {
+    loadClips(systemId: number, onComplete: (clipSetId: number) => void, onReject: (err: unknown) => void): void {
+      const buf = host.getBuffer(systemId)
+      const set = buf ? loadSet(buf) : 0
+      if (!set) { onReject(new Error("loadClips: not a GLB with animations")); return }
+      onComplete(set)
+    },
+    createClipFromTracks(names: string, data: Float32Array): number {
+      return withString(mod, names, (np) => withF32(mod, data, (dp) => mod._canimClipsFromTracks(np, dp, data.length)))
+    },
+    getClipSetInfo(clipSetId: number): ClipInfo[] {
+      const n = mod._canimClipsCount(clipSetId)
+      const out: ClipInfo[] = []
+      for (let i = 0; i < n; i++) {
+        const np = mod._canimClipName(clipSetId, i)
+        out.push({ name: np ? mod.UTF8ToString(np) : "", duration: mod._canimClipDuration(clipSetId, i), trackCount: mod._canimClipTrackCount(clipSetId, i) })
+      }
+      return out
+    },
+    sliceClip(clipSetId: number, clip: number, start: number, end: number): number { return mod._canimClipsSlice(clipSetId, clip, start, end) },
+    /** The hosts' one derivation (`AnimationClip.from`): the mirror if `mirror`, then the [start, end] window
+     *  (start < 0 = whole, end < 0 = the clip's end), as a NEW single-clip set. 0 = bad id / range / no rig. */
+    deriveClip(clipSetId: number, clip: number, mirror: boolean, start: number, end: number): number {
+      return mod._canimClipsDerive(clipSetId, clip, mirror ? 1 : 0, start, end)
+    },
+    destroyClipSet(clipSetId: number): void { mod._canimClipsDestroy(clipSetId) },
+    animatorCreate(entityId: number): number {
+      const root = host.get(entityId)
+      if (!root) return 0
+      const entities: number[] = [], parents: number[] = [], names: string[] = [], rest: number[] = [], skin: number[] = []
+      const collect = (id: number, parent: number): void => {
+        const e = host.get(id)
+        if (!e) return
+        const index = entities.length
+        entities.push(id); parents.push(parent); names.push(e.name ?? ""); skin.push(e.skinJoint ? 1 : 0)
+        const { t, r, s } = decomposeTRS(e.m)
+        rest.push(t[0], t[1], t[2], r[0], r[1], r[2], r[3], s[0], s[1], s[2])
+        for (const c of e.children) collect(c, index)
+      }
+      collect(entityId, -1)
+      const n = entities.length
+      const parentsPtr = mod._malloc(Math.max(4, n * 4))
+      mod.HEAP32.set(parents, parentsPtr >> 2)
+      const skinPtr = mod._malloc(Math.max(1, n))
+      mod.HEAPU8.set(skin, skinPtr)
+      let id = 0
+      try {
+        id = withString(mod, names.join("\n"), (np) => withF32(mod, rest, (rp) => mod._canimAnimatorCreate(n, parentsPtr, np, rp, skinPtr, entityId)))
+      } finally { mod._free(parentsPtr); mod._free(skinPtr) }
+      if (!id) return 0
+      const shadowed = mod._canimAnimatorShadowedNames(id)
+      if (shadowed > 0) console.warn(`[Animator] ${shadowed} bone name(s) exist twice under this model (a leftover skeleton copy?) — bound to the skinned ones; run 'lecodes assets doctor' on the GLB`)
+      animators.set(id, { rootId: entityId, entities, trs: mod._malloc(Math.max(4, n * 40)), write: mod._malloc(Math.max(1, n)), n, feetOn: false, iks: [], sockets: [] })
+      return id
+    },
+    animatorDestroy(animatorId: number): void {
+      const rec = animators.get(animatorId)
+      if (!rec) { mod._canimAnimatorDestroy(animatorId); return }
+      // Leave the skeleton in rest pose (the next animator snapshots it as its rest pose).
+      mod._canimAnimatorRest(animatorId, rec.trs, rec.write)
+      const f = mod.HEAPF32, u = mod.HEAPU8, base = rec.trs >> 2
+      for (let j = 0; j < rec.n; j++) {
+        if (!u[rec.write + j]) continue
+        const e = host.get(rec.entities[j])
+        if (!e) continue
+        const o = base + j * 10
+        composeInto(e.m, f[o], f[o + 1], f[o + 2], f[o + 3], f[o + 4], f[o + 5], f[o + 6], f[o + 7], f[o + 8], f[o + 9])
+        host.localMatrixChanged(rec.entities[j])
+      }
+      mod._canimAnimatorDestroy(animatorId)
+      freeRec(rec)
+      animators.delete(animatorId)
+    },
+    animatorBind(animatorId: number, clipSetId: number, clipIndex: number, layer: number): number { return mod._canimAnimatorBind(animatorId, clipSetId, clipIndex, layer) },
+    animatorBindMirror(animatorId: number, clipSetId: number, clipIndex: number, layer: number): number { return mod._canimAnimatorBindMirror ? mod._canimAnimatorBindMirror(animatorId, clipSetId, clipIndex, layer) : -1 },
+    animatorBoundTracks(animatorId: number, slot: number): number { return mod._canimAnimatorBoundTracks(animatorId, slot) },
+    setClipEvents(clipSetId: number, clip: number, times: Float32Array): void {
+      withF32(mod, times, (tp) => mod._canimClipsSetEvents(clipSetId, clip, tp, times.length))
+    },
+    animatorSetBlend(animatorId: number, layer: number, dims: number, slots: Uint16Array, positions: Float32Array, fade: number, speed: number, phases?: Float32Array): void {
+      const d = dims > 1 ? 2 : 1
+      const n = Math.min(slots.length, Math.floor(positions.length / d))
+      const ph = phases && phases.length >= n * 2 ? phases : null
+      withU16(mod, slots, (sp) => withF32(mod, positions, (pp) => {
+        if (ph) withF32(mod, ph, (hp) => mod._canimAnimatorSetBlend(animatorId, layer, d, sp, pp, hp, n, fade, speed))
+        else mod._canimAnimatorSetBlend(animatorId, layer, d, sp, pp, 0, n, fade, speed)
+      }))
+    },
+    animatorSetBlendValue(animatorId: number, layer: number, x: number, y: number): void { mod._canimAnimatorSetBlendValue(animatorId, layer, x, y) },
+    animatorSlotSetTurn(animatorId: number, slot: number, radians: number, enabled: boolean): void { mod._canimAnimatorSlotSetTurn(animatorId, slot, radians, enabled ? 1 : 0) },
+    animatorSlotSetWindow(animatorId: number, slot: number, start: number, end: number): void { mod._canimAnimatorSlotSetWindow(animatorId, slot, start, end) },
+    animatorPlay(animatorId: number, slot: number, loop: boolean, speed: number, fadeIn: number, fadeOut: number, restart: boolean): void {
+      mod._canimAnimatorPlay(animatorId, slot, loop ? 1 : 0, speed, fadeIn, fadeOut, restart ? 1 : 0)
+    },
+    animatorStop(animatorId: number, layer: number, slot: number, fade: number): void { mod._canimAnimatorStop(animatorId, layer, slot, fade) },
+    animatorSeek(animatorId: number, slot: number, time: number): void { mod._canimAnimatorSeek(animatorId, slot, time) },
+    animatorGetSlotTime(animatorId: number, slot: number): number { return mod._canimAnimatorSlotTime(animatorId, slot) },
+    animatorGetSlotWeight(animatorId: number, slot: number): number { return mod._canimAnimatorSlotWeight(animatorId, slot) },
+    animatorSetLayer(animatorId: number, layer: number, weight: number, additive: boolean, maskRoot: string): void {
+      withString(mod, maskRoot ?? "", (mp) => mod._canimAnimatorSetLayer(animatorId, layer, weight, additive ? 1 : 0, mp))
+    },
+    animatorSetLayerAnticipation(animatorId: number, layer: number, amount: number): void { mod._canimAnimatorSetLayerAnticipation(animatorId, layer, amount) },
+    animatorSetGlobal(animatorId: number, speed: number, paused: boolean): void { mod._canimAnimatorSetGlobal(animatorId, speed, paused ? 1 : 0) },
+    /** How far joints rotate over every clip bound to the animator that drives `jointEntityId`, per
+     *  (child entity, parent entity) pair against `frames` (8 per pair: the reference relative rotation
+     *  xyzw, the measuring frame xyzw in the parent's space) — creator-anim's canimAnimatorJointRanges.
+     *  Returns 6 radians per pair (twist / plane / normal min-max), or null when no animator carries
+     *  the joint or nothing is bound yet. */
+    animatorJointRanges(jointEntityId: number, pairs: ArrayLike<number>, frames: Float32Array): Float32Array | null {
+      for (const [ id, rec ] of animators) {
+        if (!rec.entities.includes(jointEntityId)) continue
+        const count = pairs.length >> 1
+        const idx = new Int32Array(count * 2)
+        for (let i = 0; i < count * 2; i++) idx[i] = rec.entities.indexOf(pairs[i])
+        const out = new Float32Array(count * 6)
+        const ptrI = mod._malloc(Math.max(4, count * 8))
+        mod.HEAP32.set(idx, ptrI >> 2)
+        const ptrO = mod._malloc(Math.max(4, count * 24))
+        let sampled = 0
+        try {
+          sampled = withF32(mod, frames, (fp) => mod._canimAnimatorJointRanges(id, ptrI, count, fp, ptrO))
+          if (sampled > 0) out.set(mod.HEAPF32.subarray(ptrO >> 2, (ptrO >> 2) + count * 6))
+        } finally { mod._free(ptrI); mod._free(ptrO) }
+        return sampled > 0 ? out : null
+      }
+      return null
+    },
+    /** The joints' CURRENT locals become what the animator driving `jointEntityId` showed: the next
+     *  evaluation transitions from them over `blend` seconds (a ragdoll let go — creator-gl's
+     *  seedAnimatorFromEntities). No animator carries the joint = nothing happens. */
+    animatorSeedPose(jointEntityId: number, blend: number): void {
+      for (const [ id, rec ] of animators) {
+        if (!rec.entities.includes(jointEntityId)) continue
+        const trs = new Float32Array(rec.n * 10)
+        for (let j = 0; j < rec.n; j++) {
+          const e = host.get(rec.entities[j])
+          const { t, r, s } = decomposeTRS(e ? e.m : IDENTITY)
+          trs.set([ t[0], t[1], t[2], r[0], r[1], r[2], r[3], s[0], s[1], s[2] ], j * 10)
+        }
+        withF32(mod, trs, (tp) => mod._canimAnimatorSeedPose(id, tp, blend))
+        return
+      }
+    },
+    animatorSetRootMotion(animatorId: number, bone: string, apply: number): void {
+      withString(mod, bone ?? "", (bp) => mod._canimAnimatorSetRootMotion(animatorId, bp, (apply | 0) & 255))
+    },
+    animatorGetRootMotion(animatorId: number, out: Float32Array): void {
+      mod._canimAnimatorRootMotion(animatorId, out3)
+      const f = mod.HEAPF32, o = out3 >> 2
+      out[0] = f[o]; out[1] = f[o + 1]; out[2] = f[o + 2]
+    },
+    setOnAnimatorEvent(callback: (animatorId: number, slot: number, type: number) => void): void { onEvent = callback },
+
+    // ---- contacts, phase, root curves (docs/animation-v2-plan.md §2.5-2.6) ----
+    animatorSetFeet(animatorId: number, left: string, right: string): void {
+      withString(mod, left, (l) => withString(mod, right, (r) => mod._canimAnimatorSetFeet(animatorId, l, r)))
+    },
+    animatorSlotCurveAt(animatorId: number, slot: number, which: number, time: number): number {
+      return mod._canimAnimatorSlotCurveAt(animatorId, slot, which, time)
+    },
+    animatorSlotCurveInfo(animatorId: number, slot: number, out: Float32Array): boolean {
+      const ok = mod._canimAnimatorSlotCurveInfo(animatorId, slot, out4)
+      if (ok) out.set(mod.HEAPF32.subarray(out4 >> 2, (out4 >> 2) + Math.min(4, out.length)))
+      return ok !== 0
+    },
+    animatorSlotTurn(animatorId: number, slot: number): number { return mod._canimAnimatorSlotTurn(animatorId, slot) },
+    animatorSlotTimeAtTurn(animatorId: number, slot: number, yaw: number): number { return mod._canimAnimatorSlotTimeAtTurn(animatorId, slot, yaw) },
+    animatorLayerPhase(animatorId: number, layer: number): number { return mod._canimAnimatorLayerPhase(animatorId, layer) },
+    animatorSeekPhase(animatorId: number, slot: number, phase: number): void { mod._canimAnimatorSeekPhase(animatorId, slot, phase) },
+    animatorSlotContacts(animatorId: number, slot: number, out: Float32Array): number {
+      const maxSpans = Math.floor(out.length / 8)   // stride 8 since 2026-09-01 (+ stillFrom/stillTo)
+      if (maxSpans === 0) return mod._canimAnimatorSlotContacts(animatorId, slot, 0, 0)
+      const ptr = mod._malloc(maxSpans * 8 * 4)
+      const n = mod._canimAnimatorSlotContacts(animatorId, slot, ptr, maxSpans)
+      out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + Math.min(n, maxSpans) * 8))
+      mod._free(ptr)
+      return n
+    },
+    animatorSlotTreads(animatorId: number, slot: number, out: Float32Array): number {
+      if (out.length === 0) return mod._canimAnimatorSlotTreads(animatorId, slot, 0, 0)
+      const ptr = mod._malloc(out.length * 4)
+      const n = mod._canimAnimatorSlotTreads(animatorId, slot, ptr, out.length)
+      out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + Math.min(n + 1, out.length)))
+      mod._free(ptr)
+      return n
+    },
+    animatorSlotPhysics(animatorId: number, slot: number, time: number, out: Float32Array): number {
+      const ptr = mod._malloc(11 * 4)
+      const n = mod._canimAnimatorSlotPhysics(animatorId, slot, time, ptr)
+      if (n) out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + Math.min(11, out.length)))
+      mod._free(ptr)
+      return n
+    },
+    animatorSlotFeatures(animatorId: number, slot: number, time: number, out: Float32Array): number {
+      const ptr = mod._malloc(37 * 4)
+      const n = mod._canimAnimatorSlotFeatures(animatorId, slot, time, ptr)
+      if (n) out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + Math.min(37, out.length)))
+      mod._free(ptr)
+      return n
+    },
+    animatorKneeAxis(animatorId: number, side: number, out: Float32Array): number {
+      const n = mod._canimAnimatorKneeAxis(animatorId, side, out8)
+      if (n) out.set(mod.HEAPF32.subarray(out8 >> 2, (out8 >> 2) + Math.min(8, out.length)))
+      return n
+    },
+    animatorSlotKneePole(animatorId: number, slot: number, side: number, time: number, out: Float32Array): number {
+      const n = mod._canimAnimatorSlotKneePole(animatorId, slot, side, time, out8)
+      if (n) out.set(mod.HEAPF32.subarray(out8 >> 2, (out8 >> 2) + Math.min(6, out.length)))
+      return n
+    },
+    animatorSetStepWarp(animatorId: number, on: boolean, stride: number, lift: number, pitchDeg: number, slopeDeg: number): void {
+      mod._canimAnimatorSetStepWarp(animatorId, on ? 1 : 0, stride, lift, pitchDeg, slopeDeg)
+    },
+    animatorSlotFit(animatorId: number, slot: number, target: number, align: number, out: Float32Array): number {
+      if (out.length === 0) return mod._canimAnimatorSlotFit(animatorId, slot, target, align, 0, 0)
+      const ptr = mod._malloc(out.length * 4)
+      const n = mod._canimAnimatorSlotFit(animatorId, slot, target, align, ptr, out.length)
+      out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + Math.min(n, out.length)))
+      mod._free(ptr)
+      return n
+    },
+    animatorSlotExit(animatorId: number, slot: number, target: number, tolerance: number, atContact: boolean, align: number): number {
+      return mod._canimAnimatorSlotExit(animatorId, slot, target, tolerance, atContact ? 1 : 0, align)
+    },
+    animatorSlotAlign(animatorId: number, a: number, b: number, offA: number, cyclesA: number, out: Float32Array): number {
+      if (out.length < 4) return 0
+      const ptr = mod._malloc(16)
+      const ok = mod._canimAnimatorSlotAlign(animatorId, a, b, offA, cyclesA, ptr)
+      if (ok) out.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + 4))
+      mod._free(ptr)
+      return ok
+    },
+    setOnAnimatorStep(callback: (animatorId: number, side: number, x: number, y: number, z: number) => void): void { onStep = callback },
+
+    // ---- feet: foot lock + ground IK (docs/animation-v2-plan.md §2.9) ----
+    animatorSetFeetParams(animatorId: number, params: Float32Array): void {
+      withF32(mod, params, (p) => mod._canimAnimatorSetFeetParams(animatorId, p, params.length))
+      const rec = animators.get(animatorId)
+      if (rec) rec.feetOn = (params.length > 0 && params[0] > 0.5) || (params.length > 1 && params[1] > 0.5)
+    },
+    animatorFootState(animatorId: number, side: number, out: Float32Array): boolean {
+      const ok = mod._canimAnimatorFootState(animatorId, side, out8)
+      if (ok) out.set(mod.HEAPF32.subarray(out8 >> 2, (out8 >> 2) + Math.min(8, out.length)))
+      return ok !== 0
+    },
+
+    // ---- IK chains + sockets (creator-anim anchors.cpp): solved in the LATE pass (lateSolve below) ----
+    /** kind 0 two-bone (the end entity, its parent, its grandparent) / 1 look-at. 0 = no such joint. */
+    animatorIkCreate(animatorId: number, kind: number, endEntityId: number): number {
+      const rec = animators.get(animatorId)
+      if (!rec || !hasChains(mod)) return 0
+      const end = rec.entities.indexOf(endEntityId)
+      if (end < 0) return 0
+      let mid = -1, root = -1
+      if (kind === 0) {
+        const midE = host.get(endEntityId)?.parent ?? 0
+        mid = rec.entities.indexOf(midE)
+        if (mid < 0) return 0
+        root = rec.entities.indexOf(host.get(midE)?.parent ?? 0)
+        if (root < 0) return 0
+      }
+      const ik = mod._canimAnimatorIkCreateJoints(animatorId, kind, root, mid, end)
+      if (!ik) return 0
+      const params = new Float32Array(IK_COUNT)
+      const ptr = mod._malloc(IK_COUNT * 4)
+      mod._canimAnimatorIkGet(animatorId, ik, ptr, IK_COUNT)
+      params.set(mod.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + IK_COUNT))
+      mod._free(ptr)
+      rec.iks.push({ ik, target: 0, pole: 0, rotation: 0, params })
+      return ik
+    },
+    animatorIkDestroy(animatorId: number, ik: number): void {
+      mod._canimAnimatorIkDestroy(animatorId, ik)
+      const rec = animators.get(animatorId)
+      if (rec) rec.iks = rec.iks.filter((r) => r.ik !== ik)
+    },
+    animatorIkSet(animatorId: number, ik: number, params: Float32Array): void {
+      withF32(mod, params, (p) => mod._canimAnimatorIkSet(animatorId, ik, p, params.length))
+      const r = animators.get(animatorId)?.iks.find((x) => x.ik === ik)
+      if (r) r.params.set(params.subarray(0, Math.min(params.length, IK_COUNT)))
+    },
+    animatorIkNodes(animatorId: number, ik: number, targetEntity: number, poleEntity: number, rotationEntity: number): void {
+      const r = animators.get(animatorId)?.iks.find((x) => x.ik === ik)
+      if (r) { r.target = targetEntity; r.pole = poleEntity; r.rotation = rotationEntity }
+    },
+    animatorIkAnchor(animatorId: number, ik: number, socket: string): void {
+      withString(mod, socket ?? "", (sp) => mod._canimAnimatorIkAnchor(animatorId, ik, sp))
+    },
+    animatorIkState(animatorId: number, ik: number, out: Float32Array): boolean {
+      const ok = mod._canimAnimatorIkState(animatorId, ik, out4)
+      if (ok) out.set(mod.HEAPF32.subarray(out4 >> 2, (out4 >> 2) + Math.min(4, out.length)))
+      return ok !== 0
+    },
+    /** A socket on joint `jointEntityId`: a NODE socket (nodeEntityId != 0) is read every late pass, else
+     *  `trs` (7 floats) fixed in the joint's space; neither = remove. */
+    animatorSetSocket(animatorId: number, set: string, name: string, jointEntityId: number, nodeEntityId: number, trs: Float32Array | null): void {
+      const rec = animators.get(animatorId)
+      if (!rec || !hasChains(mod)) return
+      rec.sockets = rec.sockets.filter((s) => !(s.set === set && s.name === name))
+      const call = (joint: number, values: ArrayLike<number> | null): void => {
+        withString(mod, set, (sp) => withString(mod, name, (np) => {
+          if (values) withF32(mod, values, (vp) => mod._canimAnimatorSetSocket(animatorId, sp, np, joint, vp))
+          else mod._canimAnimatorSetSocket(animatorId, sp, np, joint, 0)
+        }))
+      }
+      if (nodeEntityId === 0 && !trs) { call(-1, null); return }
+      const joint = rec.entities.indexOf(jointEntityId)
+      if (joint < 0) { console.warn(`[Animator] socket '${name}': the joint is no bone of this animator`); return }
+      call(joint, trs ?? [ 0, 0, 0, 0, 0, 0, 1 ])
+      if (nodeEntityId !== 0) rec.sockets.push({ set, name, node: nodeEntityId })
+    },
+    setClipAnchors(clipSetId: number, clip: number, bone: string, donor: string, sockets: string, spans: Float32Array): void {
+      if (!hasChains(mod)) return
+      withString(mod, bone, (bp) => withString(mod, donor ?? "", (dp) => withString(mod, sockets ?? "", (sp) =>
+        withF32(mod, spans, (vp) => mod._canimClipsSetAnchors(clipSetId, clip, bp, dp, sp, vp, Math.floor(spans.length / 4))))))
+    },
+
+    // ---- drives + warping (docs/animation-v2-plan.md §2.6 / §2.7) — the same `_creator` shapes creator-pkg exposes ----
+    /** The body's world velocity this frame: the game side of the stride / orientation warps' fit. */
+    animatorSetMotion(animatorId: number, vx: number, vy: number, vz: number): void {
+      mod._canimAnimatorSetMotion(animatorId, vx, vy, vz)
+    },
+    /** Cumulative capsule travel (m) and yaw (rad) — what distance / angle drives read. */
+    animatorSetDriveInput(animatorId: number, distance: number, angle: number): void {
+      mod._canimAnimatorSetDriveInput(animatorId, distance, angle)
+    },
+    /** A slot's clock driven by a quantity: mode 0 time / 1 distance / 2 angle, `entry` = the curve value at NOW. */
+    animatorSetSlotDrive(animatorId: number, slot: number, mode: number, entry: number): void {
+      mod._canimAnimatorSetSlotDrive(animatorId, slot, mode, entry)
+    },
+    /** Stride / orientation warping, as the engine's fixed-order CANIM_WARP_* parameter array. */
+    animatorSetWarpParams(animatorId: number, params: Float32Array): void {
+      withF32(mod, params, (p) => mod._canimAnimatorSetWarpParams(animatorId, p, params.length))
+    },
+  }
+
+  const evaluateOne = (id: number, rec: Rec, dt: number): void => {
+    // The frame the library's pose is in, before the evaluation that uses it: the post-process stage
+    // (warps, the feet) works in world space, and the pose includes joint 0 — the animator node's own
+    // local transform — so the frame is the node's PARENT world (identity for a node at the root). The
+    // host's `world` when it has one, else the parent's local matrix (exact whenever that parent hangs
+    // directly off the scene root).
+    const node = host.get(rec.rootId)
+    const parent = node && node.parent ? host.get(node.parent) : undefined
+    const W: Mat4Like = parent ? (host.world?.(parent.id) ?? parent.m) : IDENTITY
+    mod.HEAPF32.set(W as ArrayLike<number>, m16 >> 2); mod._canimAnimatorSetWorld(id, m16)
+    const evCount = mod._canimAnimatorEvaluate(id, dt, 0, rec.trs, rec.write)
+    // The feet stage's ground for the NEXT evaluation. The lite core has no raycast, so the ground is
+    // the plane at the node's height, normal up — enough for the lock and to keep the pelvis where it
+    // is; stairs and slopes are a later lite-core addition.
+    if (rec.feetOn && node) {
+      const groundY = (host.world?.(rec.rootId) ?? node.m)[13]
+      for (let side = 0; side < 2; side++) {
+        if (!mod._canimAnimatorFootProbe(id, side, probeFrom, probeTo)) continue
+        const f = mod.HEAPF32, o = probeFrom >> 2
+        mod._canimAnimatorSetGround(id, side, 1, f[o], groundY, f[o + 2], 0, 1, 0)
+      }
+    }
+    const f = mod.HEAPF32, u = mod.HEAPU8, base = rec.trs >> 2
+    for (let j = 0; j < rec.n; j++) {
+      if (!u[rec.write + j]) continue
+      const e = host.get(rec.entities[j])
+      if (!e) continue
+      const o = base + j * 10
+      composeInto(e.m, f[o], f[o + 1], f[o + 2], f[o + 3], f[o + 4], f[o + 5], f[o + 6], f[o + 7], f[o + 8], f[o + 9])
+      host.localMatrixChanged(rec.entities[j])
+    }
+    if (host.setMorphWeights) {
+      const morphs = mod._canimAnimatorMorphCount(id)
+      for (let i = 0; i < morphs; i++) {
+        const wp = mod._canimAnimatorMorph(id, i, i32a, u32a)
+        const joint = mod.HEAP32[i32a >> 2], count = mod.HEAPU32[u32a >> 2]
+        if (!wp || joint < 0 || count === 0) continue
+        host.setMorphWeights(rec.entities[joint], Float32Array.from(mod.HEAPF32.subarray(wp >> 2, (wp >> 2) + count)))
+      }
+    }
+    // root motion: apply this frame's horizontal travel (animator-node frame) + yaw per the apply mode
+    const mode = mod._canimAnimatorRootMotionFrame(id, out4)
+    if (mode !== 0) {
+      const g = mod.HEAPF32, o = out4 >> 2
+      const dx = g[o], dy = g[o + 1], dz = g[o + 2], yaw = g[o + 3]
+      let applied = false
+      if (mode === 2 && host.applyRootMotion) applied = host.applyRootMotion(rec.rootId, dx, dy, dz, dt, yaw)
+      if (!applied && (dx !== 0 || dy !== 0 || dz !== 0 || yaw !== 0)) {
+        const e = host.get(rec.rootId)
+        if (e) {
+          const m = e.m   // → the parent's space (rotation + scale of the local matrix)
+          if (yaw !== 0) rotateLocalY(m, yaw)   // the turn first: the travel follows the new heading
+          const px = m[0] * dx + m[4] * dy + m[8] * dz, py = m[1] * dx + m[5] * dy + m[9] * dz, pz = m[2] * dx + m[6] * dy + m[10] * dz
+          m[12] += px; m[13] += py; m[14] += pz
+          host.localMatrixChanged(rec.rootId)
+        }
+      }
+    }
+    // footsteps: contacts that began this evaluation, model space → world
+    if (onStep) {
+      const n = mod._canimAnimatorStepCount(id)
+      for (let i = 0; i < n; i++) {
+        const side = mod._canimAnimatorStep(id, i, out3)
+        if (side < 0) continue
+        const f = mod.HEAPF32, o = out3 >> 2
+        const x = f[o], y = f[o + 1], z = f[o + 2]
+        const m = W   // the pose's frame (the node's parent), the same one the evaluation was handed
+        steps.push({ id, side,
+          x: m[0] * x + m[4] * y + m[8] * z + m[12],
+          y: m[1] * x + m[5] * y + m[9] * z + m[13],
+          z: m[2] * x + m[6] * y + m[10] * z + m[14] })
+      }
+    }
+    if (evCount > 0) {
+      const n = mod._canimAnimatorEvents(id, evPairs, MAX_EVENTS)
+      const p = mod.HEAPU16, o = evPairs >> 1
+      for (let i = 0; i < n; i++) pending.push({ id, slot: p[o + i * 2], type: p[o + i * 2 + 1] })
+    }
+  }
+
+  // The LATE pass (creator-gl's lateSolveAnimators): after the app's late phase, every animator with IK
+  // chains hands the library its joints AS THEY ARE NOW plus this frame's node targets and node sockets;
+  // the chains solve on that pose and only the joints they rotated are written back.
+  const worldOf = (id: number): Mat4Like | undefined => host.world?.(id) ?? host.get(id)?.m
+  const lateSolveOne = (id: number, rec: Rec): void => {
+    if (rec.iks.length === 0) return
+    const node = host.get(rec.rootId)
+    if (!node) return
+    const W: Mat4Like = node.parent ? (worldOf(node.parent) ?? IDENTITY) : IDENTITY
+    for (const r of rec.iks) {
+      if (!r.target && !r.pole && !r.rotation) continue
+      const tw = r.target ? worldOf(r.target) : undefined
+      if (tw) { r.params[IK.TARGET_X] = tw[12]; r.params[IK.TARGET_X + 1] = tw[13]; r.params[IK.TARGET_X + 2] = tw[14] }
+      const pw = r.pole ? worldOf(r.pole) : undefined
+      if (pw) { r.params[IK.POLE_X] = pw[12]; r.params[IK.POLE_X + 1] = pw[13]; r.params[IK.POLE_X + 2] = pw[14]; r.params[IK.HAS_POLE] = 1 }
+      const rw = r.rotation ? worldOf(r.rotation) : undefined
+      if (rw) { const q = decomposeTRS(rw).r; r.params[IK.ROT_X] = q[0]; r.params[IK.ROT_X + 1] = q[1]; r.params[IK.ROT_X + 2] = q[2]; r.params[IK.ROT_X + 3] = q[3] }
+      withF32(mod, r.params, (p) => mod._canimAnimatorIkSet(id, r.ik, p, IK_COUNT))
+    }
+    for (const s of rec.sockets) {
+      const m = worldOf(s.node)
+      if (!m) continue
+      mod.HEAPF32.set(m as ArrayLike<number>, m16 >> 2)
+      withString(mod, s.set, (sp) => withString(mod, s.name, (np) => mod._canimAnimatorSocketSetWorld(id, sp, np, m16)))
+    }
+    const f = mod.HEAPF32, base = rec.trs >> 2
+    for (let j = 0; j < rec.n; j++) {
+      const e = host.get(rec.entities[j])
+      const { t, r, s } = decomposeTRS(e ? e.m : IDENTITY)
+      const o = base + j * 10
+      f[o] = t[0]; f[o + 1] = t[1]; f[o + 2] = t[2]; f[o + 3] = r[0]; f[o + 4] = r[1]; f[o + 5] = r[2]; f[o + 6] = r[3]; f[o + 7] = s[0]; f[o + 8] = s[1]; f[o + 9] = s[2]
+    }
+    mod.HEAPF32.set(W as ArrayLike<number>, m16 >> 2)
+    if (mod._canimAnimatorLateSolve(id, m16, rec.trs, rec.write) === 0) return
+    const u = mod.HEAPU8
+    for (let j = 0; j < rec.n; j++) {
+      if (!u[rec.write + j]) continue
+      const e = host.get(rec.entities[j])
+      if (!e) continue
+      const o = base + j * 10
+      composeInto(e.m, f[o], f[o + 1], f[o + 2], f[o + 3], f[o + 4], f[o + 5], f[o + 6], f[o + 7], f[o + 8], f[o + 9])
+      host.localMatrixChanged(rec.entities[j])
+    }
+  }
+
+  return {
+    methods,
+    /** Register a GLB's embedded clips (parsed from its bytes) — returns the set id, 0 if none. */
+    registerGlbClips(buf: ArrayBuffer): number { return loadSet(buf) },
+    /** The late pass: solve every animator's IK chains on the joints as the app's late phase left them. */
+    lateSolve(): void { for (const [ id, rec ] of animators) lateSolveOne(id, rec) },
+    /** Advance every animator by dt (after physics, before the late phase). Events fire after every
+     *  animator has been evaluated (a handler may play / stop / destroy animators). */
+    evaluate(dt: number): void {
+      for (const [ id, rec ] of animators) evaluateOne(id, rec, dt)
+      if (steps.length > 0) {
+        const batch = steps.splice(0, steps.length)
+        if (onStep) for (const s of batch) onStep(s.id, s.side, s.x, s.y, s.z)
+      }
+      if (pending.length > 0 && onEvent) {
+        const batch = pending.splice(0, pending.length)
+        for (const e of batch) onEvent(e.id, e.slot, e.type)
+      } else pending.length = 0
+    },
+    /** destroyEntity hook. */
+    onEntityDestroyed(entityId: number): void {
+      mod._canimAnimatorsDestroyTagged(entityId)
+      for (const [ id, rec ] of animators) if (rec.rootId === entityId) { freeRec(rec); animators.delete(id) }
+    },
+  }
+}
+
+export type AnimBridge = ReturnType<typeof createAnimBridge>