@nakednous/tree 0.0.1

package/dist/index.js

@@ -0,0 +1,1819 @@
+/**
+ * @file Core constants — zero dependencies.
+ * @module tree/constants
+ * @license GPL-3.0-only
+ */
+
+// Coordinate spaces
+const WORLD  = 'WORLD';
+const EYE    = 'EYE';
+const NDC    = 'NDC';
+const SCREEN = 'SCREEN';
+const MODEL  = 'MODEL';
+const MATRIX = 'MATRIX';
+
+// NDC Z convention (only difference between backends)
+const WEBGL  = -1;   // z ∈ [−1, 1]
+const WEBGPU =  0;   // z ∈ [0, 1]
+
+// Visibility results
+const INVISIBLE   = 0;
+const VISIBLE     = 1;
+const SEMIVISIBLE = 2;
+
+// Basis vectors (frozen plain arrays — duck-typed Vec3)
+const ORIGIN = Object.freeze([0, 0, 0]);
+const i  = Object.freeze([1, 0, 0]);
+const j  = Object.freeze([0, 1, 0]);
+const k  = Object.freeze([0, 0, 1]);
+const _i = Object.freeze([-1, 0, 0]);
+const _j = Object.freeze([0, -1, 0]);
+const _k = Object.freeze([0, 0, -1]);
+
+/**
+ * @file Pure numeric math — mat4, mat3, projection queries, space transforms.
+ * @module tree/math
+ * @license GPL-3.0-only
+ *
+ * CONVENTIONS (all functions in this module follow these):
+ *
+ *   Storage:    Column-major Float32Array / ArrayLike<number>.
+ *               Element [col*4 + row] = M[row, col].
+ *
+ *   Multiply:   mat4Mul(out, A, B) = A · B   (standard math order).
+ *
+ *   Pipeline:   clip = P · V · M · v
+ *               P = projection (eye → clip)
+ *               V = view       (world → eye)
+ *               M = model      (local → world)
+ *
+ *   PV:         All functions expecting a "pv" matrix receive P · V.
+ *               This is what _worldToScreen, _ensurePV, etc. compute.
+ *
+ *   Matrix stack (translate/rotate/scale in p5):
+ *     Each call post-multiplies: M = M · T, so:
+ *       translate(tx,ty,tz); rotateY(a); scale(s);
+ *     yields M = T · R · S. A vertex v is transformed as M·v = T·R·S·v
+ *     (scaled first, then rotated, then translated — last-written-first-applied).
+ *
+ *   p5 bridge note (for implementors of host layers):
+ *     p5.Matrix.mult(B) computes  B · this  (pre-multiply, arg on LEFT).
+ *     p5 translate/rotate/scale do this · T  (post-multiply, GL stack).
+ *     So p5's pvMatrix() = V.clone().mult(P) = P · V — same as ours.
+ *     The bridge extracts .mat4 (Float32Array) and feeds it directly,
+ *     or uses mat4Mul(out, proj, view) for the non-cached path.
+ *
+ * Every function uses only stack locals for intermediates (zero shared state).
+ * Every mutating function writes to a caller-provided `out` and returns `out`.
+ */
+
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Mat4 operations
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** out = identity 4×4 */
+function mat4Identity(out) {
+  out[0]=1;out[1]=0;out[2]=0;out[3]=0;
+  out[4]=0;out[5]=1;out[6]=0;out[7]=0;
+  out[8]=0;out[9]=0;out[10]=1;out[11]=0;
+  out[12]=0;out[13]=0;out[14]=0;out[15]=1;
+  return out;
+}
+
+/** out = a * b  (column-major) */
+function mat4Mul(out, a, b) {
+  const a0=a[0],a1=a[1],a2=a[2],a3=a[3],
+        a4=a[4],a5=a[5],a6=a[6],a7=a[7],
+        a8=a[8],a9=a[9],a10=a[10],a11=a[11],
+        a12=a[12],a13=a[13],a14=a[14],a15=a[15];
+  let b0,b1,b2,b3;
+  b0=b[0];b1=b[1];b2=b[2];b3=b[3];
+  out[0]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[1]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[2]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[3]=a3*b0+a7*b1+a11*b2+a15*b3;
+  b0=b[4];b1=b[5];b2=b[6];b3=b[7];
+  out[4]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[5]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[6]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[7]=a3*b0+a7*b1+a11*b2+a15*b3;
+  b0=b[8];b1=b[9];b2=b[10];b3=b[11];
+  out[8]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[9]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[10]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[11]=a3*b0+a7*b1+a11*b2+a15*b3;
+  b0=b[12];b1=b[13];b2=b[14];b3=b[15];
+  out[12]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[13]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[14]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[15]=a3*b0+a7*b1+a11*b2+a15*b3;
+  return out;
+}
+
+/** out = inverse(src). Returns null if singular. */
+function mat4Invert(out, src) {
+  const s=src;
+  const a00=s[0],a01=s[1],a02=s[2],a03=s[3],
+        a10=s[4],a11=s[5],a12=s[6],a13=s[7],
+        a20=s[8],a21=s[9],a22=s[10],a23=s[11],
+        a30=s[12],a31=s[13],a32=s[14],a33=s[15];
+  const b00=a00*a11-a01*a10,b01=a00*a12-a02*a10,
+        b02=a00*a13-a03*a10,b03=a01*a12-a02*a11,
+        b04=a01*a13-a03*a11,b05=a02*a13-a03*a12,
+        b06=a20*a31-a21*a30,b07=a20*a32-a22*a30,
+        b08=a20*a33-a23*a30,b09=a21*a32-a22*a31,
+        b10=a21*a33-a23*a31,b11=a22*a33-a23*a32;
+  let det=b00*b11-b01*b10+b02*b09+b03*b08-b04*b07+b05*b06;
+  if (Math.abs(det) < 1e-12) return null;
+  det=1/det;
+  out[0]=(a11*b11-a12*b10+a13*b09)*det;
+  out[1]=(a02*b10-a01*b11-a03*b09)*det;
+  out[2]=(a31*b05-a32*b04+a33*b03)*det;
+  out[3]=(a22*b04-a21*b05-a23*b03)*det;
+  out[4]=(a12*b08-a10*b11-a13*b07)*det;
+  out[5]=(a00*b11-a02*b08+a03*b07)*det;
+  out[6]=(a32*b02-a30*b05-a33*b01)*det;
+  out[7]=(a20*b05-a22*b02+a23*b01)*det;
+  out[8]=(a10*b10-a11*b08+a13*b06)*det;
+  out[9]=(a01*b08-a00*b10-a03*b06)*det;
+  out[10]=(a30*b04-a31*b02+a33*b00)*det;
+  out[11]=(a21*b02-a20*b04-a23*b00)*det;
+  out[12]=(a11*b07-a10*b09-a12*b06)*det;
+  out[13]=(a00*b09-a01*b07+a02*b06)*det;
+  out[14]=(a31*b01-a30*b03-a32*b00)*det;
+  out[15]=(a20*b03-a21*b01+a22*b00)*det;
+  return out;
+}
+
+/** out = transpose(src) */
+function mat4Transpose(out, src) {
+  if (out === src) {
+    let t;
+    t=src[1];out[1]=src[4];out[4]=t;
+    t=src[2];out[2]=src[8];out[8]=t;
+    t=src[3];out[3]=src[12];out[12]=t;
+    t=src[6];out[6]=src[9];out[9]=t;
+    t=src[7];out[7]=src[13];out[13]=t;
+    t=src[11];out[11]=src[14];out[14]=t;
+  } else {
+    out[0]=src[0];out[1]=src[4];out[2]=src[8];out[3]=src[12];
+    out[4]=src[1];out[5]=src[5];out[6]=src[9];out[7]=src[13];
+    out[8]=src[2];out[9]=src[6];out[10]=src[10];out[11]=src[14];
+    out[12]=src[3];out[13]=src[7];out[14]=src[11];out[15]=src[15];
+  }
+  return out;
+}
+
+/** out[0..8] = inverseTranspose(upper3×3(src))  (normal matrix) */
+function mat3NormalFromMat4(out, src) {
+  const a00=src[0],a01=src[1],a02=src[2],
+        a10=src[4],a11=src[5],a12=src[6],
+        a20=src[8],a21=src[9],a22=src[10];
+  const b01=a22*a11-a12*a21,
+        b11=-a22*a01+a02*a21,
+        b21=a12*a01-a02*a11;
+  let det=a00*b01+a10*b11+a20*b21;
+  if (Math.abs(det) < 1e-12) { for(let i=0;i<9;i++)out[i]=0; return out; }
+  det=1/det;
+  out[0]=b01*det;
+  out[1]=(-a22*a10+a12*a20)*det;
+  out[2]=(a21*a10-a11*a20)*det;
+  out[3]=b11*det;
+  out[4]=(a22*a00-a02*a20)*det;
+  out[5]=(-a21*a00+a01*a20)*det;
+  out[6]=b21*det;
+  out[7]=(-a12*a00+a02*a10)*det;
+  out[8]=(a11*a00-a01*a10)*det;
+  return out;
+}
+
+/** out = mat4 * [x,y,z,1], perspective-divides, writes xyz */
+function mat4MulPoint(out, m, x, y, z) {
+  const rx = m[0]*x + m[4]*y + m[8]*z  + m[12];
+  const ry = m[1]*x + m[5]*y + m[9]*z  + m[13];
+  const rz = m[2]*x + m[6]*y + m[10]*z + m[14];
+  const rw = m[3]*x + m[7]*y + m[11]*z + m[15];
+  if (rw !== 0 && rw !== 1) {
+    out[0] = rx/rw; out[1] = ry/rw; out[2] = rz/rw;
+  } else {
+    out[0] = rx; out[1] = ry; out[2] = rz;
+  }
+  return out;
+}
+
+/** out = mat4 * [x,y,z,0]  (direction, no translation) */
+function mat4MulDir(out, m, x, y, z) {
+  out[0] = m[0]*x + m[4]*y + m[8]*z;
+  out[1] = m[1]*x + m[5]*y + m[9]*z;
+  out[2] = m[2]*x + m[6]*y + m[10]*z;
+  return out;
+}
+
+/** out = upper-left 3×3 transposed from mat4 (direction / dMatrix extraction) */
+function mat3FromMat4T(out, m) {
+  out[0]=m[0]; out[1]=m[4]; out[2]=m[8];
+  out[3]=m[1]; out[4]=m[5]; out[5]=m[9];
+  out[6]=m[2]; out[7]=m[6]; out[8]=m[10];
+  return out;
+}
+
+/** out = mat3 * vec3 */
+function mat3MulVec3(out, m, x, y, z) {
+  out[0] = m[0]*x + m[3]*y + m[6]*z;
+  out[1] = m[1]*x + m[4]*y + m[7]*z;
+  out[2] = m[2]*x + m[5]*y + m[8]*z;
+  return out;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Projection queries
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** @returns {boolean} true if orthographic */
+function projIsOrtho(p) { return p[15] !== 0; }
+
+/**
+ * Near plane distance.
+ * @param {ArrayLike<number>} p  Projection Mat4
+ * @param {number} ndcZMin  WEBGL (−1) or WEBGPU (0)
+ */
+function projNear(p, ndcZMin) {
+  return p[15] === 0
+    ? p[14] / (p[10] + ndcZMin)
+    : (p[14] - ndcZMin) / p[10];
+}
+
+/** Far plane distance (convention-independent: far always maps to NDC z=1). */
+function projFar(p) {
+  return p[15] === 0
+    ? p[14] / (1 + p[10])
+    : (p[14] - 1) / p[10];
+}
+
+function projLeft(p, ndcZMin) {
+  return p[15] === 1
+    ? -(1 + p[12]) / p[0]
+    : projNear(p, ndcZMin) * (p[8] - 1) / p[0];
+}
+
+function projRight(p, ndcZMin) {
+  return p[15] === 1
+    ? (1 - p[12]) / p[0]
+    : projNear(p, ndcZMin) * (1 + p[8]) / p[0];
+}
+
+function projTop(p, ndcZMin) {
+  return p[15] === 1
+    ? (p[13] - 1) / p[5]
+    : projNear(p, ndcZMin) * (p[9] - 1) / p[5];
+}
+
+function projBottom(p, ndcZMin) {
+  return p[15] === 1
+    ? (1 + p[13]) / p[5]
+    : projNear(p, ndcZMin) * (1 + p[9]) / p[5];
+}
+
+/** Vertical fov (radians, perspective only). */
+function projFov(p) {
+  return Math.abs(2 * Math.atan(1 / p[5]));
+}
+
+/** Horizontal fov (radians, perspective only). */
+function projHfov(p) {
+  return Math.abs(2 * Math.atan(1 / p[0]));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Derived matrices (convenience)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** out = proj * view = P · V  (standard GL) */
+function mat4PV(out, proj, view) { return mat4Mul(out, proj, view); }
+
+/** out = view * model = V · M  (standard GL) */
+function mat4MV(out, model, view) { return mat4Mul(out, view, model); }
+
+/** out = proj * view * model = P · V · M  (standard GL) */
+function mat4PMV(out, proj, model, view) {
+  // MV = view * model (V · M)
+  const t0=view[0],t1=view[1],t2=view[2],t3=view[3],
+        t4=view[4],t5=view[5],t6=view[6],t7=view[7],
+        t8=view[8],t9=view[9],t10=view[10],t11=view[11],
+        t12=view[12],t13=view[13],t14=view[14],t15=view[15];
+  let b0,b1,b2,b3;
+  b0=model[0];b1=model[1];b2=model[2];b3=model[3];
+  const mv0=t0*b0+t4*b1+t8*b2+t12*b3, mv1=t1*b0+t5*b1+t9*b2+t13*b3,
+        mv2=t2*b0+t6*b1+t10*b2+t14*b3, mv3=t3*b0+t7*b1+t11*b2+t15*b3;
+  b0=model[4];b1=model[5];b2=model[6];b3=model[7];
+  const mv4=t0*b0+t4*b1+t8*b2+t12*b3, mv5=t1*b0+t5*b1+t9*b2+t13*b3,
+        mv6=t2*b0+t6*b1+t10*b2+t14*b3, mv7=t3*b0+t7*b1+t11*b2+t15*b3;
+  b0=model[8];b1=model[9];b2=model[10];b3=model[11];
+  const mv8=t0*b0+t4*b1+t8*b2+t12*b3, mv9=t1*b0+t5*b1+t9*b2+t13*b3,
+        mv10=t2*b0+t6*b1+t10*b2+t14*b3, mv11=t3*b0+t7*b1+t11*b2+t15*b3;
+  b0=model[12];b1=model[13];b2=model[14];b3=model[15];
+  const mv12=t0*b0+t4*b1+t8*b2+t12*b3, mv13=t1*b0+t5*b1+t9*b2+t13*b3,
+        mv14=t2*b0+t6*b1+t10*b2+t14*b3, mv15=t3*b0+t7*b1+t11*b2+t15*b3;
+  // PMV = proj * MV  (P · V · M)
+  const p0=proj[0],p1=proj[1],p2=proj[2],p3=proj[3],
+        p4=proj[4],p5=proj[5],p6=proj[6],p7=proj[7],
+        p8=proj[8],p9=proj[9],p10=proj[10],p11=proj[11],
+        p12=proj[12],p13=proj[13],p14=proj[14],p15=proj[15];
+  out[0]=p0*mv0+p4*mv1+p8*mv2+p12*mv3;
+  out[1]=p1*mv0+p5*mv1+p9*mv2+p13*mv3;
+  out[2]=p2*mv0+p6*mv1+p10*mv2+p14*mv3;
+  out[3]=p3*mv0+p7*mv1+p11*mv2+p15*mv3;
+  out[4]=p0*mv4+p4*mv5+p8*mv6+p12*mv7;
+  out[5]=p1*mv4+p5*mv5+p9*mv6+p13*mv7;
+  out[6]=p2*mv4+p6*mv5+p10*mv6+p14*mv7;
+  out[7]=p3*mv4+p7*mv5+p11*mv6+p15*mv7;
+  out[8]=p0*mv8+p4*mv9+p8*mv10+p12*mv11;
+  out[9]=p1*mv8+p5*mv9+p9*mv10+p13*mv11;
+  out[10]=p2*mv8+p6*mv9+p10*mv10+p14*mv11;
+  out[11]=p3*mv8+p7*mv9+p11*mv10+p15*mv11;
+  out[12]=p0*mv12+p4*mv13+p8*mv14+p12*mv15;
+  out[13]=p1*mv12+p5*mv13+p9*mv14+p13*mv15;
+  out[14]=p2*mv12+p6*mv13+p10*mv14+p14*mv15;
+  out[15]=p3*mv12+p7*mv13+p11*mv14+p15*mv15;
+  return out;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Space transforms — mapLocation / mapDirection
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// FLAT DISPATCH: every from→to pair is a self-contained leaf.
+// No path calls back into mapLocation/mapDirection (no reentrancy).
+// All intermediates are stack locals (zero shared state).
+//
+
+// ── Location Transform ───────────────────────────────────────────────────
+
+/**
+ * Relative transform for locations (points).
+ *
+ * out = inv(to) · from
+ *
+ * Maps a point from the `from` frame into the `to` frame:
+ *
+ *   p_to = out · p_from
+ *
+ * @param {ArrayLike<number>} out Destination 4×4 matrix (length 16).
+ * @param {ArrayLike<number>} from Source frame transform.
+ * @param {ArrayLike<number>} to Destination frame transform.
+ * @returns {ArrayLike<number>|null} `out`, or `null` if `to` is singular.
+ */
+function mat4Location(out, from, to) {
+  return mat4Invert(out, to) && mat4Mul(out, out, from);
+}
+
+// ── Direction Transform ──────────────────────────────────────────────────
+
+/**
+ * Relative transform for directions (vectors).
+ *
+ * Uses only the upper-left 3×3 blocks, ignoring translation.
+ *
+ * Corresponds to:
+ *
+ *   out = to₃ · inv(from₃)
+ *
+ * and maps directions as:
+ *
+ *   d_to = out · d_from
+ *
+ * Note: the final write is transposed so the result matches this module's
+ * matrix layout and multiplication convention.
+ *
+ * @param {ArrayLike<number>} out Destination 3×3 matrix (length 9).
+ * @param {ArrayLike<number>} from Source frame transform.
+ * @param {ArrayLike<number>} to Destination frame transform.
+ * @returns {ArrayLike<number>|null} `out`, or `null` if `from` is singular.
+ */
+function mat3Direction(out, from, to) {
+  const a00=from[0], a01=from[1], a02=from[2],
+        a10=from[4], a11=from[5], a12=from[6],
+        a20=from[8], a21=from[9], a22=from[10];
+  const b01=a22*a11-a12*a21,
+        b11=a12*a20-a22*a10,
+        b21=a21*a10-a11*a20;
+  let det=a00*b01+a01*b11+a02*b21;
+  if (Math.abs(det) < 1e-12) return null;
+  det=1/det;
+  const i00=b01*det;
+  const i01=(a02*a21-a22*a01)*det;
+  const i02=(a12*a01-a02*a11)*det;
+  const i10=b11*det;
+  const i11=(a22*a00-a02*a20)*det;
+  const i12=(a02*a10-a12*a00)*det;
+  const i20=b21*det;
+  const i21=(a01*a20-a21*a00)*det;
+  const i22=(a11*a00-a01*a10)*det;
+  const t00=to[0], t01=to[1], t02=to[2],
+        t10=to[4], t11=to[5], t12=to[6],
+        t20=to[8], t21=to[9], t22=to[10];
+  const m00=t00*i00+t10*i01+t20*i02;
+  const m01=t01*i00+t11*i01+t21*i02;
+  const m02=t02*i00+t12*i01+t22*i02;
+  const m10=t00*i10+t10*i11+t20*i12;
+  const m11=t01*i10+t11*i11+t21*i12;
+  const m12=t02*i10+t12*i11+t22*i12;
+  const m20=t00*i20+t10*i21+t20*i22;
+  const m21=t01*i20+t11*i21+t21*i22;
+  const m22=t02*i20+t12*i21+t22*i22;
+  out[0]=m00; out[1]=m10; out[2]=m20;
+  out[3]=m01; out[4]=m11; out[5]=m21;
+  out[6]=m02; out[7]=m12; out[8]=m22;
+  return out;
+}
+
+// ── Location leaf helpers ────────────────────────────────────────────────
+
+function _worldToScreen(out, px, py, pz, pv, vp, ndcZMin) {
+  const x = pv[0]*px+pv[4]*py+pv[8]*pz+pv[12];
+  const y = pv[1]*px+pv[5]*py+pv[9]*pz+pv[13];
+  const z = pv[2]*px+pv[6]*py+pv[10]*pz+pv[14];
+  const w = pv[3]*px+pv[7]*py+pv[11]*pz+pv[15];
+  if (w === 0) { out[0]=px; out[1]=py; out[2]=pz; return out; }
+  const nx=x/w, ny=y/w, nz=z/w;
+  const ndcZRange = 1 - ndcZMin;
+  out[0] = (nx*0.5+0.5)*vp[2]+vp[0];
+  out[1] = (ny*0.5+0.5)*vp[3]+vp[1];
+  out[2] = (nz - ndcZMin) / ndcZRange;
+  return out;
+}
+
+function _screenToWorld(out, px, py, pz, ipv, vp, ndcZMin) {
+  const sx=(px-vp[0])/vp[2], sy=(py-vp[1])/vp[3];
+  const nx=sx*2-1, ny=sy*2-1;
+  const ndcZRange = 1 - ndcZMin;
+  const nz = pz * ndcZRange + ndcZMin;
+  const x=ipv[0]*nx+ipv[4]*ny+ipv[8]*nz+ipv[12];
+  const y=ipv[1]*nx+ipv[5]*ny+ipv[9]*nz+ipv[13];
+  const z=ipv[2]*nx+ipv[6]*ny+ipv[10]*nz+ipv[14];
+  const w=ipv[3]*nx+ipv[7]*ny+ipv[11]*nz+ipv[15];
+  if (w === 0) { out[0]=px; out[1]=py; out[2]=pz; return out; }
+  out[0]=x/w; out[1]=y/w; out[2]=z/w;
+  return out;
+}
+
+function _worldToNDC(out, px, py, pz, pv) {
+  const x=pv[0]*px+pv[4]*py+pv[8]*pz+pv[12];
+  const y=pv[1]*px+pv[5]*py+pv[9]*pz+pv[13];
+  const z=pv[2]*px+pv[6]*py+pv[10]*pz+pv[14];
+  const w=pv[3]*px+pv[7]*py+pv[11]*pz+pv[15];
+  if (w === 0) { out[0]=px; out[1]=py; out[2]=pz; return out; }
+  out[0]=x/w; out[1]=y/w; out[2]=z/w;
+  return out;
+}
+
+function _ndcToWorld(out, px, py, pz, ipv) {
+  const x=ipv[0]*px+ipv[4]*py+ipv[8]*pz+ipv[12];
+  const y=ipv[1]*px+ipv[5]*py+ipv[9]*pz+ipv[13];
+  const z=ipv[2]*px+ipv[6]*py+ipv[10]*pz+ipv[14];
+  const w=ipv[3]*px+ipv[7]*py+ipv[11]*pz+ipv[15];
+  if (w === 0) { out[0]=px; out[1]=py; out[2]=pz; return out; }
+  out[0]=x/w; out[1]=y/w; out[2]=z/w;
+  return out;
+}
+
+function _screenToNDC(out, px, py, pz, vp, ndcZMin) {
+  const ndcZRange = 1 - ndcZMin;
+  out[0] = ((px-vp[0])/vp[2])*2-1;
+  out[1] = ((py-vp[1])/vp[3])*2-1;
+  out[2] = pz * ndcZRange + ndcZMin;
+  return out;
+}
+
+function _ndcToScreen(out, px, py, pz, vp, ndcZMin) {
+  const ndcZRange = 1 - ndcZMin;
+  out[0] = (px*0.5+0.5)*vp[2]+vp[0];
+  out[1] = (py*0.5+0.5)*vp[3]+vp[1];
+  out[2] = (pz - ndcZMin) / ndcZRange;
+  return out;
+}
+
+// ── Inline PV and IPV helpers (stack-local, for paths that need them) ────
+
+function _ensurePV(m) {
+  if (m.pv) return m.pv;
+  // Inline P · V (standard GL: clip = P · V · world_point)
+  const p = m.proj, v = m.view;
+  return [
+    p[0]*v[0]+p[4]*v[1]+p[8]*v[2]+p[12]*v[3],
+    p[1]*v[0]+p[5]*v[1]+p[9]*v[2]+p[13]*v[3],
+    p[2]*v[0]+p[6]*v[1]+p[10]*v[2]+p[14]*v[3],
+    p[3]*v[0]+p[7]*v[1]+p[11]*v[2]+p[15]*v[3],
+    p[0]*v[4]+p[4]*v[5]+p[8]*v[6]+p[12]*v[7],
+    p[1]*v[4]+p[5]*v[5]+p[9]*v[6]+p[13]*v[7],
+    p[2]*v[4]+p[6]*v[5]+p[10]*v[6]+p[14]*v[7],
+    p[3]*v[4]+p[7]*v[5]+p[11]*v[6]+p[15]*v[7],
+    p[0]*v[8]+p[4]*v[9]+p[8]*v[10]+p[12]*v[11],
+    p[1]*v[8]+p[5]*v[9]+p[9]*v[10]+p[13]*v[11],
+    p[2]*v[8]+p[6]*v[9]+p[10]*v[10]+p[14]*v[11],
+    p[3]*v[8]+p[7]*v[9]+p[11]*v[10]+p[15]*v[11],
+    p[0]*v[12]+p[4]*v[13]+p[8]*v[14]+p[12]*v[15],
+    p[1]*v[12]+p[5]*v[13]+p[9]*v[14]+p[13]*v[15],
+    p[2]*v[12]+p[6]*v[13]+p[10]*v[14]+p[14]*v[15],
+    p[3]*v[12]+p[7]*v[13]+p[11]*v[14]+p[15]*v[15],
+  ];
+}
+
+/**
+ * Map a point between coordinate spaces.
+ *
+ * @param {Vec3}   out        Result written here.
+ * @param {number} px,py,pz   Input point.
+ * @param {string} from       Source space.
+ * @param {string} to         Target space.
+ * @param {object} m          Matrices bag { proj, view, eye?, pv?, ipv?, model?,
+ *                             fromFrame?, toFrameInv? }.
+ * @param {Vec4}   vp         Viewport [x, y, width, height].
+ * @param {number} ndcZMin    WEBGL (−1) or WEBGPU (0).
+ */
+function mapLocation(out, px, py, pz, from, to, m, vp, ndcZMin) {
+  // WORLD ↔ SCREEN
+  if (from === WORLD && to === SCREEN)
+    return _worldToScreen(out, px,py,pz, _ensurePV(m), vp, ndcZMin);
+  if (from === SCREEN && to === WORLD)
+    return _screenToWorld(out, px,py,pz, m.ipv, vp, ndcZMin);
+
+  // WORLD ↔ NDC
+  if (from === WORLD && to === NDC)
+    return _worldToNDC(out, px,py,pz, _ensurePV(m));
+  if (from === NDC && to === WORLD)
+    return _ndcToWorld(out, px,py,pz, m.ipv);
+
+  // SCREEN ↔ NDC
+  if (from === SCREEN && to === NDC)
+    return _screenToNDC(out, px,py,pz, vp, ndcZMin);
+  if (from === NDC && to === SCREEN)
+    return _ndcToScreen(out, px,py,pz, vp, ndcZMin);
+
+  // WORLD ↔ EYE
+  if (from === WORLD && to === EYE)
+    return mat4MulPoint(out, m.view, px,py,pz);
+  if (from === EYE && to === WORLD)
+    return mat4MulPoint(out, m.eye, px,py,pz);
+
+  // EYE ↔ SCREEN (inline: eye→world→screen / screen→world→eye)
+  if (from === EYE && to === SCREEN) {
+    const ex=m.eye[0]*px+m.eye[4]*py+m.eye[8]*pz+m.eye[12],
+          ey=m.eye[1]*px+m.eye[5]*py+m.eye[9]*pz+m.eye[13],
+          ez=m.eye[2]*px+m.eye[6]*py+m.eye[10]*pz+m.eye[14];
+    return _worldToScreen(out, ex,ey,ez, _ensurePV(m), vp, ndcZMin);
+  }
+  if (from === SCREEN && to === EYE) {
+    _screenToWorld(out, px,py,pz, m.ipv, vp, ndcZMin);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return mat4MulPoint(out, m.view, wx,wy,wz);
+  }
+
+  // EYE ↔ NDC (inline: eye→world→ndc / ndc→world→eye)
+  if (from === EYE && to === NDC) {
+    const ex=m.eye[0]*px+m.eye[4]*py+m.eye[8]*pz+m.eye[12],
+          ey=m.eye[1]*px+m.eye[5]*py+m.eye[9]*pz+m.eye[13],
+          ez=m.eye[2]*px+m.eye[6]*py+m.eye[10]*pz+m.eye[14];
+    return _worldToNDC(out, ex,ey,ez, _ensurePV(m));
+  }
+  if (from === NDC && to === EYE) {
+    _ndcToWorld(out, px,py,pz, m.ipv);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return mat4MulPoint(out, m.view, wx,wy,wz);
+  }
+
+  // MATRIX (custom frame) ↔ WORLD
+  if (from === MATRIX && to === WORLD)
+    return mat4MulPoint(out, m.fromFrame, px,py,pz);
+  if (from === WORLD && to === MATRIX)
+    return mat4MulPoint(out, m.toFrameInv, px,py,pz);
+
+  // MATRIX ↔ EYE
+  if (from === MATRIX && to === EYE) {
+    const fx=m.fromFrame[0]*px+m.fromFrame[4]*py+m.fromFrame[8]*pz+m.fromFrame[12],
+          fy=m.fromFrame[1]*px+m.fromFrame[5]*py+m.fromFrame[9]*pz+m.fromFrame[13],
+          fz=m.fromFrame[2]*px+m.fromFrame[6]*py+m.fromFrame[10]*pz+m.fromFrame[14];
+    return mat4MulPoint(out, m.view, fx,fy,fz);
+  }
+  if (from === EYE && to === MATRIX) {
+    const ex=m.eye[0]*px+m.eye[4]*py+m.eye[8]*pz+m.eye[12],
+          ey=m.eye[1]*px+m.eye[5]*py+m.eye[9]*pz+m.eye[13],
+          ez=m.eye[2]*px+m.eye[6]*py+m.eye[10]*pz+m.eye[14];
+    return mat4MulPoint(out, m.toFrameInv, ex,ey,ez);
+  }
+
+  // MATRIX ↔ SCREEN
+  if (from === MATRIX && to === SCREEN) {
+    const fx=m.fromFrame[0]*px+m.fromFrame[4]*py+m.fromFrame[8]*pz+m.fromFrame[12],
+          fy=m.fromFrame[1]*px+m.fromFrame[5]*py+m.fromFrame[9]*pz+m.fromFrame[13],
+          fz=m.fromFrame[2]*px+m.fromFrame[6]*py+m.fromFrame[10]*pz+m.fromFrame[14];
+    return _worldToScreen(out, fx,fy,fz, _ensurePV(m), vp, ndcZMin);
+  }
+  if (from === SCREEN && to === MATRIX) {
+    _screenToWorld(out, px,py,pz, m.ipv, vp, ndcZMin);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return mat4MulPoint(out, m.toFrameInv, wx,wy,wz);
+  }
+
+  // MATRIX ↔ NDC
+  if (from === MATRIX && to === NDC) {
+    const fx=m.fromFrame[0]*px+m.fromFrame[4]*py+m.fromFrame[8]*pz+m.fromFrame[12],
+          fy=m.fromFrame[1]*px+m.fromFrame[5]*py+m.fromFrame[9]*pz+m.fromFrame[13],
+          fz=m.fromFrame[2]*px+m.fromFrame[6]*py+m.fromFrame[10]*pz+m.fromFrame[14];
+    return _worldToNDC(out, fx,fy,fz, _ensurePV(m));
+  }
+  if (from === NDC && to === MATRIX) {
+    _ndcToWorld(out, px,py,pz, m.ipv);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return mat4MulPoint(out, m.toFrameInv, wx,wy,wz);
+  }
+
+  // MATRIX ↔ MATRIX
+  if (from === MATRIX && to === MATRIX) {
+    const fx=m.fromFrame[0]*px+m.fromFrame[4]*py+m.fromFrame[8]*pz+m.fromFrame[12],
+          fy=m.fromFrame[1]*px+m.fromFrame[5]*py+m.fromFrame[9]*pz+m.fromFrame[13],
+          fz=m.fromFrame[2]*px+m.fromFrame[6]*py+m.fromFrame[10]*pz+m.fromFrame[14];
+    return mat4MulPoint(out, m.toFrameInv, fx,fy,fz);
+  }
+
+  // Fallback
+  out[0]=px; out[1]=py; out[2]=pz;
+  return out;
+}
+
+// ── Direction helpers ────────────────────────────────────────────────────
+
+/** Apply the 3×3 linear part of a mat4 (rotation/scale, no translation) */
+function _applyDir(out, mat, dx, dy, dz) {
+  out[0]=mat[0]*dx+mat[4]*dy+mat[8]*dz;
+  out[1]=mat[1]*dx+mat[5]*dy+mat[9]*dz;
+  out[2]=mat[2]*dx+mat[6]*dy+mat[10]*dz;
+  return out;
+}
+
+/**
+ * World→Screen direction. Self-contained: reads proj scalars + view mat.
+ * The existing p5.tree code nested _direction and _location calls here;
+ * this version inlines all math with stack locals.
+ */
+function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
+  // 1. World → Eye direction: R · d (standard column-major mat × vec)
+  const edx = view[0]*dx + view[4]*dy + view[8]*dz;
+  const edy = view[1]*dx + view[5]*dy + view[9]*dz;
+  const edz = view[2]*dx + view[6]*dy + view[10]*dz;
+
+  const isPersp = proj[15] === 0;
+  let sdx = edx, sdy = edy;
+
+  if (isPersp) {
+    // Camera-eye Z of world origin (inline WORLD→EYE for [0,0,0]):
+    // view * [0,0,0,1] = column 3 of view
+    const zEye = view[8]*0 + view[9]*0 + view[10]*0 + view[14]; // = view[14]
+    const halfTan = Math.tan(projFov(proj) / 2);
+    const k = Math.abs(zEye * halfTan);
+    const pixPerUnit = vpH / (2 * k);
+    sdx *= pixPerUnit;
+    sdy *= pixPerUnit;
+  } else {
+    // Ortho: pixels per world unit along X/Y
+    const orthoW = Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin));
+    sdx *= vpW / orthoW;
+    sdy *= vpH / Math.abs(projTop(proj, ndcZMin) - projBottom(proj, ndcZMin));
+  }
+
+  // Z: map eye-space dz to screen-space dz
+  const near = projNear(proj, ndcZMin), far = projFar(proj);
+  const depthRange = near - far;
+  let sdz;
+  if (isPersp) {
+    sdz = edz / (depthRange / Math.tan(projFov(proj) / 2));
+  } else {
+    sdz = edz / (depthRange / (Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin)) / vpW));
+  }
+
+  out[0] = sdx; out[1] = sdy; out[2] = sdz;
+  return out;
+}
+
+function _screenToWorldDir(out, dx, dy, dz, proj, view, eye, vpW, vpH, ndcZMin) {
+  const isPersp = proj[15] === 0;
+  let edx = dx, edy = dy;
+
+  if (isPersp) {
+    const zEye = view[14];
+    const halfTan = Math.tan(projFov(proj) / 2);
+    const k = Math.abs(zEye * halfTan);
+    edx *= 2 * k / vpH;
+    edy *= 2 * k / vpH;
+  } else {
+    const orthoW = Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin));
+    edx *= orthoW / vpW;
+    edy *= Math.abs(projTop(proj, ndcZMin) - projBottom(proj, ndcZMin)) / vpH;
+  }
+
+  const near = projNear(proj, ndcZMin), far = projFar(proj);
+  const depthRange = near - far;
+  let edz;
+  if (isPersp) {
+    edz = dz * (depthRange / Math.tan(projFov(proj) / 2));
+  } else {
+    edz = dz * (depthRange / (Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin)) / vpW));
+  }
+
+  // Eye → World direction (dMatrix = upper-left 3×3 of eye = inv(view))
+  _applyDir(out, eye, edx, edy, edz);
+  return out;
+}
+
+function _screenToNDCDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
+  const ndcZRange = 1 - ndcZMin;
+  out[0] = 2 * dx / vpW;
+  out[1] = 2 * dy / vpH;
+  out[2] = dz * ndcZRange;
+  return out;
+}
+
+function _ndcToScreenDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
+  const ndcZRange = 1 - ndcZMin;
+  out[0] = vpW * dx / 2;
+  out[1] = vpH * dy / 2;
+  out[2] = dz / ndcZRange;
+  return out;
+}
+
+/**
+ * Map a direction between coordinate spaces.
+ * Same flat-dispatch as mapLocation.
+ */
+function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
+  const vpW = Math.abs(vp[2]), vpH = Math.abs(vp[3]);
+
+  // EYE ↔ WORLD (most common: dMatrix operation)
+  if (from === EYE && to === WORLD) return _applyDir(out, m.eye, dx, dy, dz);
+  if (from === WORLD && to === EYE) return _applyDir(out, m.view, dx, dy, dz);
+
+  // WORLD ↔ SCREEN
+  if (from === WORLD && to === SCREEN)
+    return _worldToScreenDir(out, dx,dy,dz, m.proj, m.view, vpW, vpH, ndcZMin);
+  if (from === SCREEN && to === WORLD)
+    return _screenToWorldDir(out, dx,dy,dz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+
+  // SCREEN ↔ NDC
+  if (from === SCREEN && to === NDC)
+    return _screenToNDCDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
+  if (from === NDC && to === SCREEN)
+    return _ndcToScreenDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
+
+  // WORLD ↔ NDC (chain: world→screen→ndc / ndc→screen→world)
+  if (from === WORLD && to === NDC) {
+    _worldToScreenDir(out, dx,dy,dz, m.proj, m.view, vpW, vpH, ndcZMin);
+    const sx=out[0],sy=out[1],sz=out[2];
+    return _screenToNDCDir(out, sx,sy,sz, vpW, vpH, ndcZMin);
+  }
+  if (from === NDC && to === WORLD) {
+    _ndcToScreenDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
+    const sx=out[0],sy=out[1],sz=out[2];
+    return _screenToWorldDir(out, sx,sy,sz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+  }
+
+  // EYE ↔ SCREEN
+  if (from === EYE && to === SCREEN) {
+    // eye→world→screen
+    _applyDir(out, m.eye, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _worldToScreenDir(out, wx,wy,wz, m.proj, m.view, vpW, vpH, ndcZMin);
+  }
+  if (from === SCREEN && to === EYE) {
+    _screenToWorldDir(out, dx,dy,dz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.view, wx,wy,wz);
+  }
+
+  // EYE ↔ NDC
+  if (from === EYE && to === NDC) {
+    _applyDir(out, m.eye, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    _worldToScreenDir(out, wx,wy,wz, m.proj, m.view, vpW, vpH, ndcZMin);
+    const sx=out[0],sy=out[1],sz=out[2];
+    return _screenToNDCDir(out, sx,sy,sz, vpW, vpH, ndcZMin);
+  }
+  if (from === NDC && to === EYE) {
+    _ndcToScreenDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
+    const sx=out[0],sy=out[1],sz=out[2];
+    _screenToWorldDir(out, sx,sy,sz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.view, wx,wy,wz);
+  }
+
+  // MATRIX ↔ WORLD
+  if (from === MATRIX && to === WORLD) return _applyDir(out, m.fromFrame, dx,dy,dz);
+  if (from === WORLD && to === MATRIX) return _applyDir(out, m.toFrameInv, dx,dy,dz);
+
+  // MATRIX ↔ EYE
+  if (from === MATRIX && to === EYE) {
+    _applyDir(out, m.fromFrame, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.view, wx,wy,wz);
+  }
+  if (from === EYE && to === MATRIX) {
+    _applyDir(out, m.eye, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.toFrameInv, wx,wy,wz);
+  }
+
+  // MATRIX ↔ SCREEN
+  if (from === MATRIX && to === SCREEN) {
+    _applyDir(out, m.fromFrame, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _worldToScreenDir(out, wx,wy,wz, m.proj, m.view, vpW, vpH, ndcZMin);
+  }
+  if (from === SCREEN && to === MATRIX) {
+    _screenToWorldDir(out, dx,dy,dz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.toFrameInv, wx,wy,wz);
+  }
+
+  // MATRIX ↔ NDC
+  if (from === MATRIX && to === NDC) {
+    _applyDir(out, m.fromFrame, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    _worldToScreenDir(out, wx,wy,wz, m.proj, m.view, vpW, vpH, ndcZMin);
+    const sx=out[0],sy=out[1],sz=out[2];
+    return _screenToNDCDir(out, sx,sy,sz, vpW, vpH, ndcZMin);
+  }
+  if (from === NDC && to === MATRIX) {
+    _ndcToScreenDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
+    const sx=out[0],sy=out[1],sz=out[2];
+    _screenToWorldDir(out, sx,sy,sz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.toFrameInv, wx,wy,wz);
+  }
+
+  // MATRIX ↔ MATRIX
+  if (from === MATRIX && to === MATRIX) {
+    _applyDir(out, m.fromFrame, dx,dy,dz);
+    const wx=out[0],wy=out[1],wz=out[2];
+    return _applyDir(out, m.toFrameInv, wx,wy,wz);
+  }
+
+  // Fallback
+  out[0]=dx; out[1]=dy; out[2]=dz;
+  return out;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// pixelRatio
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * World-units-per-pixel at a given eye-space Z depth.
+ * @param {ArrayLike<number>} proj  Projection Mat4.
+ * @param {number} vpH      Viewport height (pixels).
+ * @param {number} eyeZ     Eye-space Z of the point (negative for in-front-of camera).
+ * @param {number} ndcZMin  WEBGL or WEBGPU.
+ */
+function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
+  if (projIsOrtho(proj)) {
+    return Math.abs(projTop(proj, ndcZMin) - projBottom(proj, ndcZMin)) / vpH;
+  }
+  return 2 * Math.abs(eyeZ) * Math.tan(projFov(proj) / 2) / vpH;
+}
+
+/**
+ * @file Pure quaternion/spline math + PoseTrack state machine.
+ * @module tree/track
+ * @license GPL-3.0-only
+ *
+ * Zero dependencies.  No p5, DOM, WebGL, or WebGPU usage.
+ * All quaternion operations use flat [x,y,z,w] arrays (w-last = glTF layout).
+ * PoseTrack is a pure state machine that stores {pos,rot,scl} keyframes
+ * and advances a cursor via tick().
+ *
+ * ── Exports ──────────────────────────────────────────────────────────────────
+ *  Quaternion helpers
+ *    qSet qCopy qDot qNormalize qNegate qMul qSlerp
+ *    qFromAxisAngle qFromLookDir qFromRotMat3x3 qFromMat4 qToMat4
+ *    quatToAxisAngle
+ *  Spline / vector helpers
+ *    catmullRomVec3  lerpVec3
+ *  Transform / mat4 helpers
+ *    transformToMat4  mat4ToTransform
+ *  Track
+ *    PoseTrack
+ *
+ * ── Hook architecture ─────────────────────────────────────────────────────────
+ *  _onActivate / _onDeactivate  — lib-space (underscore, set by host layer)
+ *    Fire exactly on playing transitions: false→true / true→false.
+ *    Used by the addon to register/unregister from the draw-loop tick set.
+ *
+ *  onPlay / onEnd               — user-space (public, set by user)
+ *    onPlay : fires in play()  when playback actually starts (transition).
+ *    onEnd  : fires in tick()  when cursor reaches a natural boundary.
+ *    onEnd does NOT fire on explicit stop() / reset().
+ *
+ *  Firing order:
+ *    play()  → user onPlay → lib _onActivate
+ *    tick()  → user onEnd  → lib _onDeactivate
+ *    stop()  →               lib _onDeactivate  (no user hook)
+ *    reset() →               lib _onDeactivate  (no user hook)
+ *
+ * ── Playback semantics (rate) ─────────────────────────────────────────────────
+ *  rate > 0   forward playback
+ *  rate < 0   backward playback
+ *  rate === 0 frozen: tick() is a no-op; the playing flag is NOT changed.
+ *
+ *  play()  is the sole method that sets playing = true.
+ *  stop()  is the sole method that sets playing = false.
+ *  Assigning rate never implicitly starts or stops playback.
+ *
+ * ── One-keyframe behaviour ────────────────────────────────────────────────────
+ *  play() with exactly one keyframe snaps eval() to that keyframe without
+ *  setting playing = true and without animating.
+ */
+
+
+// =========================================================================
+// S1  Quaternion helpers  (flat [x, y, z, w], w-last)
+// =========================================================================
+
+/** Set all four components. @returns {number[]} out */
+const qSet = (out, x, y, z, w) => {
+  out[0] = x; out[1] = y; out[2] = z; out[3] = w; return out;
+};
+
+/** Copy quaternion a into out. @returns {number[]} out */
+const qCopy = (out, a) => {
+  out[0] = a[0]; out[1] = a[1]; out[2] = a[2]; out[3] = a[3]; return out;
+};
+
+/** Dot product of two quaternions. */
+const qDot = (a, b) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3];
+
+/** Normalise in-place. @returns {number[]} out */
+const qNormalize = (out) => {
+  const len = Math.sqrt(qDot(out, out)) || 1;
+  out[0] /= len; out[1] /= len; out[2] /= len; out[3] /= len;
+  return out;
+};
+
+/** Negate all components in-place. @returns {number[]} out */
+const qNegate = (out) => {
+  out[0] = -out[0]; out[1] = -out[1]; out[2] = -out[2]; out[3] = -out[3];
+  return out;
+};
+
+/** out = a * b (Hamilton product). @returns {number[]} out */
+const qMul = (out, a, b) => {
+  const ax = a[0], ay = a[1], az = a[2], aw = a[3];
+  const bx = b[0], by = b[1], bz = b[2], bw = b[3];
+  out[0] = aw*bx + ax*bw + ay*bz - az*by;
+  out[1] = aw*by - ax*bz + ay*bw + az*bx;
+  out[2] = aw*bz + ax*by - ay*bx + az*bw;
+  out[3] = aw*bw - ax*bx - ay*by - az*bz;
+  return out;
+};
+
+/**
+ * SLERP between quaternions a and b at parameter t.
+ * Shortest-arc: negates b when dot < 0.
+ * Near-equal fallback: nlerp when dot ~= 1.
+ * @param {number[]} out  4-element result array.
+ * @param {number[]} a    Start quaternion [x,y,z,w].
+ * @param {number[]} b    End quaternion [x,y,z,w].
+ * @param {number}   t    Blend [0, 1].
+ * @returns {number[]} out
+ */
+const qSlerp = (out, a, b, t) => {
+  let d = qDot(a, b);
+  let bx = b[0], by = b[1], bz = b[2], bw = b[3];
+  if (d < 0) { d = -d; bx = -bx; by = -by; bz = -bz; bw = -bw; }
+  if (d > 0.9995) {
+    out[0] = a[0] + t*(bx - a[0]);
+    out[1] = a[1] + t*(by - a[1]);
+    out[2] = a[2] + t*(bz - a[2]);
+    out[3] = a[3] + t*(bw - a[3]);
+    return qNormalize(out);
+  }
+  const theta = Math.acos(d), sinT = Math.sin(theta);
+  const s0 = Math.sin((1 - t) * theta) / sinT;
+  const s1 = Math.sin(t * theta) / sinT;
+  out[0] = s0*a[0] + s1*bx;
+  out[1] = s0*a[1] + s1*by;
+  out[2] = s0*a[2] + s1*bz;
+  out[3] = s0*a[3] + s1*bw;
+  return out;
+};
+
+/**
+ * Build a quaternion from an axis-angle rotation.
+ * The axis need not be normalised.
+ * @returns {number[]} out
+ */
+const qFromAxisAngle = (out, ax, ay, az, angle) => {
+  const half = angle * 0.5;
+  const s    = Math.sin(half);
+  const len  = Math.sqrt(ax*ax + ay*ay + az*az) || 1;
+  out[0] = s * ax / len;
+  out[1] = s * ay / len;
+  out[2] = s * az / len;
+  out[3] = Math.cos(half);
+  return out;
+};
+
+/**
+ * Build a quaternion from a look direction (negative-Z forward convention)
+ * and an optional up vector (defaults to +Y).
+ * @param {number[]} out
+ * @param {number[]} dir  Forward direction [x,y,z].
+ * @param {number[]} [up] Up vector [x,y,z].
+ * @returns {number[]} out
+ */
+const qFromLookDir = (out, dir, up) => {
+  let fx = dir[0], fy = dir[1], fz = dir[2];
+  const fLen = Math.sqrt(fx*fx + fy*fy + fz*fz) || 1;
+  fx /= fLen; fy /= fLen; fz /= fLen;
+  let ux = up ? up[0] : 0, uy = up ? up[1] : 1, uz = up ? up[2] : 0;
+  let rx = uy*fz - uz*fy, ry = uz*fx - ux*fz, rz = ux*fy - uy*fx;
+  const rLen = Math.sqrt(rx*rx + ry*ry + rz*rz) || 1;
+  rx /= rLen; ry /= rLen; rz /= rLen;
+  ux = fy*rz - fz*ry; uy = fz*rx - fx*rz; uz = fx*ry - fy*rx;
+  return qFromRotMat3x3(out, rx, ry, rz, ux, uy, uz, -fx, -fy, -fz);
+};
+
+/**
+ * Build a quaternion from a 3x3 rotation matrix supplied as 9 row-major scalars.
+ * @returns {number[]} out (normalised)
+ */
+const qFromRotMat3x3 = (out, m00, m01, m02, m10, m11, m12, m20, m21, m22) => {
+  const tr = m00 + m11 + m22;
+  if (tr > 0) {
+    const s = 0.5 / Math.sqrt(tr + 1);
+    out[3] = 0.25 / s;
+    out[0] = (m21 - m12) * s;
+    out[1] = (m02 - m20) * s;
+    out[2] = (m10 - m01) * s;
+  } else if (m00 > m11 && m00 > m22) {
+    const s = 2 * Math.sqrt(1 + m00 - m11 - m22);
+    out[3] = (m21 - m12) / s;
+    out[0] = 0.25 * s;
+    out[1] = (m01 + m10) / s;
+    out[2] = (m02 + m20) / s;
+  } else if (m11 > m22) {
+    const s = 2 * Math.sqrt(1 + m11 - m00 - m22);
+    out[3] = (m02 - m20) / s;
+    out[0] = (m01 + m10) / s;
+    out[1] = 0.25 * s;
+    out[2] = (m12 + m21) / s;
+  } else {
+    const s = 2 * Math.sqrt(1 + m22 - m00 - m11);
+    out[3] = (m10 - m01) / s;
+    out[0] = (m02 + m20) / s;
+    out[1] = (m12 + m21) / s;
+    out[2] = 0.25 * s;
+  }
+  return qNormalize(out);
+};
+
+/**
+ * Extract a unit quaternion from the upper-left 3x3 of a column-major mat4.
+ * @param {number[]} out
+ * @param {Float32Array|number[]} m  Column-major mat4.
+ * @returns {number[]} out
+ */
+const qFromMat4 = (out, m) =>
+  qFromRotMat3x3(out, m[0], m[4], m[8], m[1], m[5], m[9], m[2], m[6], m[10]);
+
+/**
+ * Write a quaternion into a column-major mat4 (rotation block only;
+ * translation and perspective rows/cols are set to identity values).
+ * @param {Float32Array|number[]} out  16-element array.
+ * @param {number[]} q  [x,y,z,w].
+ * @returns {Float32Array|number[]} out
+ */
+const qToMat4 = (out, q) => {
+  const x = q[0], y = q[1], z = q[2], w = q[3];
+  const x2 = x+x, y2 = y+y, z2 = z+z;
+  const xx = x*x2, xy = x*y2, xz = x*z2;
+  const yy = y*y2, yz = y*z2, zz = z*z2;
+  const wx = w*x2, wy = w*y2, wz = w*z2;
+  out[0]  = 1-(yy+zz); out[1]  = xy+wz;     out[2]  = xz-wy;     out[3]  = 0;
+  out[4]  = xy-wz;     out[5]  = 1-(xx+zz); out[6]  = yz+wx;     out[7]  = 0;
+  out[8]  = xz+wy;     out[9]  = yz-wx;     out[10] = 1-(xx+yy); out[11] = 0;
+  out[12] = 0;         out[13] = 0;         out[14] = 0;         out[15] = 1;
+  return out;
+};
+
+/**
+ * Decompose a unit quaternion into { axis:[x,y,z], angle } (radians).
+ * out is optional; a new object is returned if omitted.
+ * @param {number[]} q  [x,y,z,w].
+ * @param {Object}  [out]
+ * @returns {{ axis: number[], angle: number }}
+ */
+const quatToAxisAngle = (q, out) => {
+  out = out || {};
+  const x = q[0], y = q[1], z = q[2], w = q[3];
+  const sinHalf = Math.sqrt(x*x + y*y + z*z);
+  if (sinHalf < 1e-8) { out.axis = [0, 1, 0]; out.angle = 0; return out; }
+  out.angle = 2 * Math.atan2(sinHalf, w);
+  out.axis  = [x / sinHalf, y / sinHalf, z / sinHalf];
+  return out;
+};
+
+// =========================================================================
+// S2  Spline / vector helpers
+// =========================================================================
+
+function _dist3(a, b) {
+  const dx = a[0]-b[0], dy = a[1]-b[1], dz = a[2]-b[2];
+  return Math.sqrt(dx*dx + dy*dy + dz*dz);
+}
+
+/**
+ * Centripetal Catmull-Rom interpolation (alpha = 0.5, Barry-Goldman).
+ * out = interp(p0, p1, p2, p3, t) where t in [0,1] maps p1 -> p2.
+ * When p0 === p1 or p2 === p3 (boundary), the chord is reused, giving
+ * zero-tension clamped end tangents.
+ * @param {number[]} out  3-element result.
+ * @param {number[]} p0   Control point before p1.
+ * @param {number[]} p1   Start of this segment.
+ * @param {number[]} p2   End of this segment.
+ * @param {number[]} p3   Control point after p2.
+ * @param {number}   t    Blend [0, 1].
+ * @returns {number[]} out
+ */
+const catmullRomVec3 = (out, p0, p1, p2, p3, t) => {
+  const alpha = 0.5;
+  const dt0   = Math.pow(_dist3(p0, p1), alpha) || 1;
+  const dt1   = Math.pow(_dist3(p1, p2), alpha) || 1;
+  const dt2   = Math.pow(_dist3(p2, p3), alpha) || 1;
+  for (let i = 0; i < 3; i++) {
+    const t1_0 = (p1[i]-p0[i])/dt0 - (p2[i]-p0[i])/(dt0+dt1) + (p2[i]-p1[i])/dt1;
+    const t2_0 = (p2[i]-p1[i])/dt1 - (p3[i]-p1[i])/(dt1+dt2) + (p3[i]-p2[i])/dt2;
+    const m1   = t1_0 * dt1;
+    const m2   = t2_0 * dt1;
+    const a    =  2*p1[i] - 2*p2[i] + m1 + m2;
+    const b    = -3*p1[i] + 3*p2[i] - 2*m1 - m2;
+    out[i]     = a*t*t*t + b*t*t + m1*t + p1[i];
+  }
+  return out;
+};
+
+/**
+ * Linear interpolation between two vec3s.
+ * @param {number[]} out
+ * @param {number[]} a
+ * @param {number[]} b
+ * @param {number}   t  Blend [0, 1].
+ * @returns {number[]} out
+ */
+const lerpVec3 = (out, a, b, t) => {
+  out[0] = a[0] + t*(b[0]-a[0]);
+  out[1] = a[1] + t*(b[1]-a[1]);
+  out[2] = a[2] + t*(b[2]-a[2]);
+  return out;
+};
+
+// =========================================================================
+// S3  Transform <-> Mat4
+// =========================================================================
+
+/**
+ * Write a TRS transform into a column-major mat4.
+ * Rotation is encoded as a quaternion; scale is baked into rotation columns.
+ * @param {Float32Array|number[]} out  16-element column-major mat4.
+ * @param {{ pos:number[], rot:number[], scl:number[] }} xform
+ * @returns {Float32Array|number[]} out
+ */
+const transformToMat4 = (out, xform) => {
+  qToMat4(out, xform.rot);
+  const sx = xform.scl[0], sy = xform.scl[1], sz = xform.scl[2];
+  out[0]  *= sx; out[1]  *= sx; out[2]  *= sx;
+  out[4]  *= sy; out[5]  *= sy; out[6]  *= sy;
+  out[8]  *= sz; out[9]  *= sz; out[10] *= sz;
+  out[12] = xform.pos[0];
+  out[13] = xform.pos[1];
+  out[14] = xform.pos[2];
+  return out;
+};
+
+/**
+ * Decompose a column-major mat4 into a TRS transform.
+ * Assumes no shear. Scale is extracted from column lengths.
+ * @param {{ pos:number[], rot:number[], scl:number[] }} out
+ * @param {Float32Array|number[]} m  Column-major mat4.
+ * @returns {{ pos:number[], rot:number[], scl:number[] }} out
+ */
+const mat4ToTransform = (out, m) => {
+  out.pos[0] = m[12]; out.pos[1] = m[13]; out.pos[2] = m[14];
+  const sx = Math.sqrt(m[0]*m[0] + m[1]*m[1] + m[2]*m[2]);
+  const sy = Math.sqrt(m[4]*m[4] + m[5]*m[5] + m[6]*m[6]);
+  const sz = Math.sqrt(m[8]*m[8] + m[9]*m[9] + m[10]*m[10]);
+  out.scl[0] = sx; out.scl[1] = sy; out.scl[2] = sz;
+  qFromRotMat3x3(out.rot,
+    m[0]/sx, m[4]/sy, m[8]/sz,
+    m[1]/sx, m[5]/sy, m[9]/sz,
+    m[2]/sx, m[6]/sy, m[10]/sz);
+  return out;
+};
+
+// =========================================================================
+// S4  Spec parser (keyframe input normalisation)
+// =========================================================================
+
+const _isNum   = (x) => typeof x === 'number' && Number.isFinite(x);
+const _clamp01 = (x) => x < 0 ? 0 : (x > 1 ? 1 : x);
+const _clampS  = (x, lo, hi) => x < lo ? lo : (x > hi ? hi : x);
+
+function _parseVec3(v) {
+  if (!v) return null;
+  if (Array.isArray(v) && v.length >= 3 && v.every(n => typeof n === 'number')) return [v[0], v[1], v[2]];
+  if (typeof v === 'object' && 'x' in v) return [v.x || 0, v.y || 0, v.z || 0];
+  return null;
+}
+
+function _parseQuat(v) {
+  if (!v) return null;
+  if (Array.isArray(v) && v.length === 4 && v.every(n => typeof n === 'number')) return [v[0], v[1], v[2], v[3]];
+  if (v.axis && typeof v.angle === 'number') {
+    const a = Array.isArray(v.axis) ? v.axis : [v.axis.x || 0, v.axis.y || 0, v.axis.z || 0];
+    return qFromAxisAngle([0, 0, 0, 1], a[0], a[1], a[2], v.angle);
+  }
+  if (v.dir) {
+    const d = Array.isArray(v.dir) ? v.dir : [v.dir.x || 0, v.dir.y || 0, v.dir.z || 0];
+    const u = v.up ? (Array.isArray(v.up) ? v.up : [v.up.x || 0, v.up.y || 0, v.up.z || 0]) : null;
+    return qFromLookDir([0, 0, 0, 1], d, u);
+  }
+  return null;
+}
+
+function _parseSpec(spec) {
+  if (!spec || typeof spec !== 'object') return null;
+  const pos = _parseVec3(spec.pos) || [0, 0, 0];
+  const rot = _parseQuat(spec.rot) || [0, 0, 0, 1];
+  const scl = _parseVec3(spec.scl) || [1, 1, 1];
+  return { pos, rot, scl };
+}
+
+function _sameTransform(a, b) {
+  for (let i = 0; i < 3; i++) if (a.pos[i] !== b.pos[i] || a.scl[i] !== b.scl[i]) return false;
+  for (let i = 0; i < 4; i++) if (a.rot[i] !== b.rot[i]) return false;
+  return true;
+}
+
+// =========================================================================
+// S5  PoseTrack
+// =========================================================================
+
+/**
+ * Renderer-agnostic keyframe animation track.
+ *
+ * Keyframes are TRS pose objects: { pos:[x,y,z], rot:[x,y,z,w], scl:[x,y,z] }.
+ * The track maintains a scalar cursor (seg, f) that advances each tick().
+ *
+ * Position uses centripetal Catmull-Rom spline by default (posInterp = 'catmullrom');
+ * set posInterp = 'linear' to switch to lerp. Rotation uses SLERP. Scale uses LERP.
+ *
+ * Rate semantics:
+ *   rate > 0   forward
+ *   rate < 0   backward
+ *   rate === 0 frozen: tick() is a no-op; playing is NOT changed
+ *
+ * Assigning rate never starts or stops playback.
+ * Only play() sets playing = true. Only stop() / reset() set it to false.
+ *
+ * One-keyframe behaviour:
+ *   play() with exactly one keyframe snaps eval() to that keyframe
+ *   without setting playing = true and without firing hooks.
+ */
+class PoseTrack {
+  constructor() {
+    /** @type {Array<{pos:number[],rot:number[],scl:number[]}>} */
+    this.keyframes = [];
+    /** Whether playback is active. @type {boolean} */
+    this.playing   = false;
+    /** Loop flag (overridden by pingPong). @type {boolean} */
+    this.loop      = false;
+    /** Ping-pong bounce mode (takes precedence over loop). @type {boolean} */
+    this.pingPong  = false;
+    /** Frames per segment (>=1). @type {number} */
+    this.duration  = 30;
+    /** Current segment index. @type {number} */
+    this.seg       = 0;
+    /** Frame offset within current segment (can be fractional). @type {number} */
+    this.f         = 0;
+    /**
+     * Position interpolation mode.
+     * @type {'catmullrom'|'linear'}
+     */
+    this.posInterp = 'catmullrom';
+
+    // Scratch arrays reused by eval() / toMatrix() — avoids hot-path allocations
+    this._pos = [0, 0, 0];
+    this._rot = [0, 0, 0, 1];
+    this._scl = [1, 1, 1];
+
+    // Internal rate — assigning never touches playing
+    this._rate = 1;
+
+    // User-space hooks
+    /** Called once when play() starts a false->true transition. @type {Function|null} */
+    this.onPlay = null;
+    /** Called once by tick() when cursor reaches a natural boundary (once mode). @type {Function|null} */
+    this.onEnd  = null;
+
+    // Lib-space hooks (set by host layer — e.g. p5 bridge)
+    /** @type {Function|null} */
+    this._onActivate   = null;
+    /** @type {Function|null} */
+    this._onDeactivate = null;
+  }
+
+  // ── rate ────────────────────────────────────────────────────────────────
+  // Getter/setter so future consumers get the right value from track.rate,
+  // while the setter intentionally has NO side effects on playing.
+
+  /** Playback rate. 0 = frozen (playing flag unchanged). @type {number} */
+  get rate()  { return this._rate; }
+  set rate(v) {
+    this._rate = (typeof v === 'number' && Number.isFinite(v)) ? v : 1;
+    // Intentionally does NOT start or stop playback.
+  }
+
+  /** Number of interpolatable segments (keyframes.length - 1, min 0). @type {number} */
+  get segments() { return Math.max(0, this.keyframes.length - 1); }
+
+  // ── Keyframe management ──────────────────────────────────────────────────
+
+  /**
+   * Append a keyframe. Adjacent duplicates are skipped by default.
+   * @param {{ pos?, rot?, scl? }} spec  pos/rot/scl arrays, {x,y,z}, axis-angle, look-dir.
+   * @param {{ deduplicate?: boolean }} [opts]
+   */
+  add(spec, opts) {
+    const kf = _parseSpec(spec);
+    if (!kf) return;
+    const dedup = !opts || opts.deduplicate !== false;
+    if (dedup && this.keyframes.length > 0) {
+      if (_sameTransform(this.keyframes[this.keyframes.length - 1], kf)) return;
+    }
+    this.keyframes.push(kf);
+  }
+
+  /**
+   * Replace (or append at end) the keyframe at index.
+   * @param {number} index  Existing index or keyframes.length to append.
+   * @param {{ pos?, rot?, scl? }} spec
+   * @returns {boolean}
+   */
+  set(index, spec) {
+    if (!_isNum(index)) return false;
+    const i  = index | 0;
+    const kf = _parseSpec(spec);
+    if (!kf || i < 0 || i > this.keyframes.length) return false;
+    if (i === this.keyframes.length) { this.keyframes.push(kf); }
+    else { this.keyframes[i] = kf; }
+    return true;
+  }
+
+  /**
+   * Remove the keyframe at index. Adjusts cursor if needed.
+   * @param {number} index
+   * @returns {boolean}
+   */
+  remove(index) {
+    if (!_isNum(index)) return false;
+    const i = index | 0;
+    if (i < 0 || i >= this.keyframes.length) return false;
+    this.keyframes.splice(i, 1);
+    const nSeg = this.segments;
+    if (nSeg === 0) { this.seg = 0; this.f = 0; }
+    else if (this.seg >= nSeg) { this.seg = nSeg - 1; }
+    return true;
+  }
+
+  // ── Transport ────────────────────────────────────────────────────────────
+
+  /**
+   * Start or update playback.
+   * Accepts a numeric rate or an options object: { rate, duration, loop, pingPong, onPlay, onEnd }.
+   *
+   * Zero keyframes: no-op.
+   * One keyframe: snaps cursor (seg=0, f=0); no playing=true, no hooks.
+   * Already playing: updates params in place; hooks are not re-fired.
+   * rate=0 is valid: track will be playing but frozen until rate changes.
+   *
+   * @param {number|Object} [rateOrOpts]
+   * @returns {PoseTrack} this
+   */
+  play(rateOrOpts) {
+    if (this.keyframes.length === 0) return this;
+
+    // One keyframe: snap only, no animation, no hooks
+    if (this.keyframes.length === 1) {
+      this.seg = 0; this.f = 0;
+      return this;
+    }
+
+    if (typeof rateOrOpts === 'number' && Number.isFinite(rateOrOpts)) {
+      this._rate = rateOrOpts;
+    } else if (rateOrOpts && typeof rateOrOpts === 'object') {
+      const o = rateOrOpts;
+      if (_isNum(o.duration))             this.duration = Math.max(1, o.duration | 0);
+      if ('loop'     in o)                this.loop     = !!o.loop;
+      if ('pingPong' in o)                this.pingPong = !!o.pingPong;
+      if (typeof o.onPlay === 'function') this.onPlay   = o.onPlay;
+      if (typeof o.onEnd  === 'function') this.onEnd    = o.onEnd;
+      if (_isNum(o.rate))                 this._rate    = o.rate;
+    }
+
+    // Clamp cursor into valid range
+    const nSeg = this.segments;
+    const dur  = Math.max(1, this.duration | 0);
+    if (this.seg < 0)     this.seg = 0;
+    if (this.seg >= nSeg) this.seg = nSeg - 1;
+    if (this.f   < 0)     this.f   = 0;
+    if (this.f   > dur)   this.f   = dur;
+
+    const wasPlaying = this.playing;
+    this.playing = true;
+
+    if (!wasPlaying) {
+      if (typeof this.onPlay === 'function') { try { this.onPlay(this); } catch (_) {} }
+      this._onActivate?.();
+    }
+    return this;
+  }
+
+  /**
+   * Stop playback. Does NOT reset time unless reset is true.
+   * @param {boolean} [reset=false]  If true, seek to start or end based on rate direction.
+   * @returns {PoseTrack} this
+   */
+  stop(reset) {
+    const wasPlaying = this.playing;
+    this.playing = false;
+    if (wasPlaying) this._onDeactivate?.();
+    if (!reset || this.keyframes.length <= 1) return this;
+    this.seek(this._rate < 0 ? 1 : 0);
+    return this;
+  }
+
+  /**
+   * Clear all keyframes and stop. Fires _onDeactivate if was playing.
+   * @returns {PoseTrack} this
+   */
+  reset() {
+    const wasPlaying = this.playing;
+    this.playing = false;
+    if (wasPlaying) this._onDeactivate?.();
+    this.keyframes.length = 0;
+    this.seg = 0; this.f = 0;
+    return this;
+  }
+
+  /**
+   * Seek to a normalised position [0,1] across the full path.
+   * Can optionally target a specific segment (t is then local to that segment).
+   * Does not change the playing flag.
+   * @param {number} t           Normalised time [0, 1].
+   * @param {number} [segIndex]  Optional segment override.
+   * @returns {PoseTrack} this
+   */
+  seek(t, segIndex) {
+    const nSeg = this.segments;
+    if (nSeg === 0) { this.seg = 0; this.f = 0; return this; }
+    const dur = Math.max(1, this.duration | 0);
+    if (_isNum(segIndex)) {
+      this.seg = _clampS(segIndex | 0, 0, nSeg - 1);
+      this.f   = _clamp01(t) * dur;
+    } else {
+      this._setCursorFromScalar(_clamp01(t) * nSeg * dur);
+    }
+    return this;
+  }
+
+  /**
+   * Normalised playback time across the full path [0, 1].
+   * Returns 0 when fewer than 2 keyframes exist.
+   * @returns {number}
+   */
+  time() {
+    const nSeg = this.segments;
+    if (nSeg === 0) return 0;
+    const dur = Math.max(1, this.duration | 0);
+    return _clamp01((this.seg * dur + this.f) / (nSeg * dur));
+  }
+
+  /**
+   * Snapshot of the current transport state.
+   * @returns {{ keyframes:number, segments:number, seg:number, f:number,
+   *             time:number, playing:boolean, loop:boolean, pingPong:boolean,
+   *             rate:number, duration:number }}
+   */
+  info() {
+    return {
+      keyframes: this.keyframes.length,
+      segments:  this.segments,
+      seg:       this.seg,
+      f:         this.f,
+      playing:   this.playing,
+      loop:      this.loop,
+      pingPong:  this.pingPong,
+      rate:      this._rate,
+      duration:  this.duration,
+      time:      this.segments > 0 ? this.time() : 0
+    };
+  }
+
+  /**
+   * Advance the cursor by rate frames.
+   *
+   * rate === 0: frozen — returns this.playing without moving (no-op).
+   * Returns false and fires onEnd/_onDeactivate when a once-mode boundary is hit.
+   * Returns true while playing and continuing.
+   *
+   * @returns {boolean}
+   */
+  tick() {
+    if (!this.playing) return false;
+    const nSeg = this.segments;
+    if (nSeg === 0) {
+      this.playing = false; this._onDeactivate?.(); return false;
+    }
+
+    // Frozen: position does not advance, playing stays true
+    if (this._rate === 0) return true;
+
+    const dur   = Math.max(1, this.duration | 0);
+    const total = nSeg * dur;
+    const s     = _clampS(this.seg * dur + this.f, 0, total);
+    const next  = s + this._rate;
+
+    // ── pingPong ──
+    if (this.pingPong) {
+      let pos = next, flips = 0;
+      while (pos < 0 || pos > total) {
+        if (pos < 0)     { pos = -pos;            flips++; }
+        else             { pos = 2 * total - pos; flips++; }
+      }
+      if (flips & 1) this._rate = -this._rate;
+      this._setCursorFromScalar(pos);
+      return true;
+    }
+
+    // ── loop ──
+    if (this.loop) {
+      this._setCursorFromScalar(((next % total) + total) % total);
+      return true;
+    }
+
+    // ── once — boundary check ──
+    if (next <= 0) {
+      this._setCursorFromScalar(0);
+      this.playing = false;
+      if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+      this._onDeactivate?.();
+      return false;
+    }
+    if (next >= total) {
+      this._setCursorFromScalar(total);
+      this.playing = false;
+      if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+      this._onDeactivate?.();
+      return false;
+    }
+
+    this._setCursorFromScalar(next);
+    return true;
+  }
+
+  /**
+   * Evaluate the interpolated pose at the current cursor into out.
+   * If out is omitted a new object is allocated (avoid in hot paths).
+   * Uses centripetal Catmull-Rom for position (posInterp === 'catmullrom') or lerp.
+   * @param {{ pos:number[], rot:number[], scl:number[] }} [out]
+   * @returns {{ pos:number[], rot:number[], scl:number[] }} out
+   */
+  eval(out) {
+    out = out || { pos: [0, 0, 0], rot: [0, 0, 0, 1], scl: [1, 1, 1] };
+    const n = this.keyframes.length;
+    if (n === 0) return out;
+
+    if (n === 1) {
+      const k = this.keyframes[0];
+      out.pos[0]=k.pos[0]; out.pos[1]=k.pos[1]; out.pos[2]=k.pos[2];
+      out.rot[0]=k.rot[0]; out.rot[1]=k.rot[1]; out.rot[2]=k.rot[2]; out.rot[3]=k.rot[3];
+      out.scl[0]=k.scl[0]; out.scl[1]=k.scl[1]; out.scl[2]=k.scl[2];
+      return out;
+    }
+
+    const nSeg = n - 1;
+    const dur  = Math.max(1, this.duration | 0);
+    const seg  = _clampS(this.seg, 0, nSeg - 1);
+    const t    = _clamp01(this.f / dur);
+    const k0   = this.keyframes[seg];
+    const k1   = this.keyframes[seg + 1];
+
+    // Position
+    if (this.posInterp === 'catmullrom') {
+      const p0 = seg > 0     ? this.keyframes[seg - 1].pos : k0.pos;
+      const p3 = seg + 2 < n ? this.keyframes[seg + 2].pos : k1.pos;
+      catmullRomVec3(out.pos, p0, k0.pos, k1.pos, p3, t);
+    } else {
+      lerpVec3(out.pos, k0.pos, k1.pos, t);
+    }
+
+    // Rotation — SLERP
+    qSlerp(out.rot, k0.rot, k1.rot, t);
+
+    // Scale — LERP
+    lerpVec3(out.scl, k0.scl, k1.scl, t);
+
+    return out;
+  }
+
+  /**
+   * Evaluate the current cursor into an existing column-major mat4.
+   * Reuses internal scratch arrays — no allocation per call.
+   * @param {Float32Array|number[]} outMat4  16-element array.
+   * @returns {Float32Array|number[]} outMat4
+   */
+  toMatrix(outMat4) {
+    const xf = this.eval({ pos: this._pos, rot: this._rot, scl: this._scl });
+    return transformToMat4(outMat4, xf);
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────
+
+  /** @private */
+  _setCursorFromScalar(s) {
+    const dur  = Math.max(1, this.duration | 0);
+    const nSeg = this.segments;
+    this.seg = Math.floor(s / dur);
+    this.f   = s - this.seg * dur;
+    if (this.seg >= nSeg) { this.seg = nSeg - 1; this.f = dur; }
+    if (this.seg < 0)     { this.seg = 0;         this.f = 0;   }
+  }
+}
+
+/**
+ * @file Frustum planes and visibility tests — zero allocations.
+ * @module tree/visibility
+ * @license GPL-3.0-only
+ *
+ * Planes are a flat Float64Array(24): 6 planes × 4 floats [a, b, c, d].
+ * All inputs are scalars. All outputs are INVISIBLE | VISIBLE | SEMIVISIBLE.
+ */
+
+
+// Plane indices
+const PLANE_LEFT = 0, PLANE_RIGHT = 1, PLANE_NEAR = 2,
+             PLANE_FAR = 3, PLANE_TOP = 4, PLANE_BOTTOM = 5;
+
+/**
+ * Compute 6 frustum planes from camera basis (world space) + projection params.
+ * All inputs are scalars — the addon extracts them from the inverse view matrix
+ * and projection queries before calling.
+ *
+ * @param {Float64Array} out  24-float output.
+ * @param {number} posX,posY,posZ  Camera world position.
+ * @param {number} vdX,vdY,vdZ    View direction (−Z in eye space, world).
+ * @param {number} upX,upY,upZ    Camera up.
+ * @param {number} rtX,rtY,rtZ    Camera right.
+ * @param {boolean} ortho         true if orthographic.
+ * @param {number} near,far,left,right,top,bottom  Projection plane values.
+ */
+function frustumPlanes(
+  out,
+  posX, posY, posZ,
+  vdX, vdY, vdZ,
+  upX, upY, upZ,
+  rtX, rtY, rtZ,
+  ortho,
+  near, far, left, right, top, bottom
+) {
+  const posViewDir = posX*vdX + posY*vdY + posZ*vdZ;
+  const posRight   = posX*rtX + posY*rtY + posZ*rtZ;
+  const posUp      = posX*upX + posY*upY + posZ*upZ;
+
+  if (ortho) {
+    // Left: normal = −right
+    out[0] = -rtX; out[1] = -rtY; out[2] = -rtZ;
+    out[3] = -(posRight - left) * -1; // dot(pos - right*left, -right) ... simplified:
+    // Actually: d = dot(pointOnPlane, normal)
+    // pointOnPlane = pos + right*left (left is negative for standard ortho)
+    // normal = -right
+    // d = dot(pos + right*left, -right) = -posRight - left
+    out[3] = -posRight - left;
+
+    // Right: normal = right
+    out[4] = rtX; out[5] = rtY; out[6] = rtZ;
+    out[7] = posRight + right;
+
+    // Top: normal = up
+    out[16] = upX; out[17] = upY; out[18] = upZ;
+    out[19] = posUp - bottom; // note: p5 top/bottom are swapped in sign convention
+
+    // Bottom: normal = -up
+    out[20] = -upX; out[21] = -upY; out[22] = -upZ;
+    out[23] = -posUp + top;
+  } else {
+    // Left
+    const hfovl = Math.atan2(left, near);
+    const shfovl = Math.sin(hfovl), chfovl = Math.cos(hfovl);
+    out[0] = vdX*shfovl - rtX*chfovl;
+    out[1] = vdY*shfovl - rtY*chfovl;
+    out[2] = vdZ*shfovl - rtZ*chfovl;
+    out[3] = shfovl*posViewDir - chfovl*posRight;
+
+    // Right
+    const hfovr = Math.atan2(right, near);
+    const shfovr = Math.sin(hfovr), chfovr = Math.cos(hfovr);
+    out[4] = -vdX*shfovr + rtX*chfovr;
+    out[5] = -vdY*shfovr + rtY*chfovr;
+    out[6] = -vdZ*shfovr + rtZ*chfovr;
+    out[7] = -shfovr*posViewDir + chfovr*posRight;
+
+    // Top
+    const fovt = Math.atan2(top, near);
+    const sfovt = Math.sin(fovt), cfovt = Math.cos(fovt);
+    out[16] = -vdX*sfovt + upX*cfovt;
+    out[17] = -vdY*sfovt + upY*cfovt;
+    out[18] = -vdZ*sfovt + upZ*cfovt;
+    out[19] = -sfovt*posViewDir + cfovt*posUp;
+
+    // Bottom
+    const fovb = Math.atan2(bottom, near);
+    const sfovb = Math.sin(fovb), cfovb = Math.cos(fovb);
+    out[20] = vdX*sfovb - upX*cfovb;
+    out[21] = vdY*sfovb - upY*cfovb;
+    out[22] = vdZ*sfovb - upZ*cfovb;
+    out[23] = sfovb*posViewDir - cfovb*posUp;
+  }
+
+  // Near plane: normal = −viewDir
+  out[8]  = -vdX; out[9]  = -vdY; out[10] = -vdZ;
+  out[11] = -posViewDir - near;
+
+  // Far plane: normal = viewDir
+  out[12] = vdX; out[13] = vdY; out[14] = vdZ;
+  out[15] = posViewDir + far;
+
+  return out;
+}
+
+/**
+ * Signed distance from point to one frustum plane.
+ * @param {Float64Array} planes  24-float planes buffer.
+ * @param {number} planeIdx  0–5 (LEFT, RIGHT, NEAR, FAR, TOP, BOTTOM).
+ * @param {number} px,py,pz  Point coordinates.
+ * @returns {number}
+ */
+function distanceToPlane(planes, planeIdx, px, py, pz) {
+  const b = planeIdx * 4;
+  return planes[b]*px + planes[b+1]*py + planes[b+2]*pz - planes[b+3];
+}
+
+/** @returns {number} INVISIBLE | VISIBLE | SEMIVISIBLE */
+function pointVisibility(planes, px, py, pz) {
+  for (let i = 0; i < 6; i++) {
+    if (distanceToPlane(planes, i, px, py, pz) > 0) return INVISIBLE;
+  }
+  return VISIBLE;
+}
+
+/** @returns {number} INVISIBLE | VISIBLE | SEMIVISIBLE */
+function sphereVisibility(planes, cx, cy, cz, radius) {
+  let allIn = true;
+  for (let i = 0; i < 6; i++) {
+    const d = distanceToPlane(planes, i, cx, cy, cz);
+    if (d > radius) return INVISIBLE;
+    if (d > 0 || -d < radius) allIn = false;
+  }
+  return allIn ? VISIBLE : SEMIVISIBLE;
+}
+
+/** @returns {number} INVISIBLE | VISIBLE | SEMIVISIBLE */
+function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
+  let allIn = true;
+  for (let i = 0; i < 6; i++) {
+    const b = i * 4;
+    const a = planes[b], bv = planes[b+1], c = planes[b+2], d = planes[b+3];
+    let allOut = true;
+    for (let corner = 0; corner < 8; corner++) {
+      const cx = (corner & 4) ? x0 : x1;
+      const cy = (corner & 2) ? y0 : y1;
+      const cz = (corner & 1) ? z0 : z1;
+      const dist = a*cx + bv*cy + c*cz - d;
+      if (dist > 0) { allIn = false; }
+      else { allOut = false; }
+    }
+    if (allOut) return INVISIBLE;
+  }
+  return allIn ? VISIBLE : SEMIVISIBLE;
+}
+
+export { EYE, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, PoseTrack, SCREEN, SEMIVISIBLE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, boxVisibility, catmullRomVec3, distanceToPlane, frustumPlanes, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3FromMat4T, mat3MulVec3, mat3NormalFromMat4, mat4Identity, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4PMV, mat4PV, mat4ToTransform, mat4Transpose, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qMul, qNegate, qNormalize, qSet, qSlerp, qToMat4, quatToAxisAngle, sphereVisibility, transformToMat4 };
+//# sourceMappingURL=index.js.map