@nakednous/tree 0.0.2 → 0.0.4

package/dist/index.js

@@ -65,45 +65,36 @@ const _k = Object.freeze([0, 0, -1]);
  *
  * Every function uses only stack locals for intermediates (zero shared state).
  * Every mutating function writes to a caller-provided `out` and returns `out`.
+ * Returns null on degeneracy (singular matrix, etc.).
  */
 
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Mat4 operations
+// Mat4 math
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** 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 = A · B  (column-major, standard math order) */
+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=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];
+  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];
+  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];
+  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;
@@ -111,7 +102,7 @@ function mat4Mul(out, a, b) {
   return out;
 }
 
-/** out = inverse(src). Returns null if singular. */
+/** 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],
@@ -202,32 +193,8 @@ function mat4MulPoint(out, m, x, y, z) {
   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
+// Projection queries  (read scalars from a projection mat4)
 // ═══════════════════════════════════════════════════════════════════════════
 
 /** @returns {boolean} true if orthographic */
@@ -235,8 +202,8 @@ function projIsOrtho(p) { return p[15] !== 0; }
 
 /**
  * Near plane distance.
- * @param {ArrayLike<number>} p  Projection Mat4
- * @param {number} ndcZMin  WEBGL (−1) or WEBGPU (0)
+ * @param {ArrayLike<number>} p  Projection Mat4.
+ * @param {number} ndcZMin  WEBGL (−1) or WEBGPU (0).
  */
 function projNear(p, ndcZMin) {
   return p[15] === 0
@@ -289,107 +256,34 @@ function projHfov(p) {
 // Derived matrices (convenience)
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** out = proj * view = P · V  (standard GL) */
+/** out = P · V */
 function mat4PV(out, proj, view) { return mat4Mul(out, proj, view); }
 
-/** out = view * model = V · M  (standard GL) */
+/** out = V · M */
 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
+// Location / Direction transforms
 // ═══════════════════════════════════════════════════════════════════════════
-//
-// 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.
+ * Relative transform for locations (points): out = inv(to) · from.
+ * @param {ArrayLike<number>} out   16-element destination.
+ * @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).
- *
+ * Relative transform for directions (vectors): out = to₃ · inv(from₃).
  * 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.
+ * @param {ArrayLike<number>} out   9-element destination.
+ * @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],
@@ -401,33 +295,41 @@ function mat3Direction(out, from, to) {
   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 i00=b01*det, i01=(a02*a21-a22*a01)*det, i02=(a12*a01-a02*a11)*det;
+  const i10=b11*det, i11=(a22*a00-a02*a20)*det, i12=(a02*a10-a12*a00)*det;
+  const i20=b21*det, i21=(a01*a20-a21*a00)*det, 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;
+  const m00=t00*i00+t10*i01+t20*i02, m01=t01*i00+t11*i01+t21*i02, m02=t02*i00+t12*i01+t22*i02;
+  const m10=t00*i10+t10*i11+t20*i12, m11=t01*i10+t11*i11+t21*i12, m12=t02*i10+t12*i11+t22*i12;
+  const m20=t00*i20+t10*i21+t20*i22, m21=t01*i20+t11*i21+t21*i22, 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;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// 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).
+//
+// Matrices bag m:
+//   {
+//     pMatrix:   Float32Array(16)  — projection (eye → clip)
+//     vMatrix:   Float32Array(16)  — view        (world → eye)
+//     eMatrix?:  Float32Array(16)  — eye         (eye → world, inv view); lazy
+//     pvMatrix?: Float32Array(16)  — P · V;      lazy
+//     ipvMatrix?:Float32Array(16)  — inv(P · V); lazy
+//     fromFrame?:Float32Array(16)  — MATRIX source frame (custom space)
+//     toFrameInv?:Float32Array(16) — inv(MATRIX dest frame)
+//   }
+//
+
 // ── Location leaf helpers ────────────────────────────────────────────────
 
 function _worldToScreen(out, px, py, pz, pv, vp, ndcZMin) {
@@ -435,45 +337,43 @@ function _worldToScreen(out, px, py, pz, pv, vp, ndcZMin) {
   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 xi = (w !== 0 && w !== 1) ? x/w : x;
+  const yi = (w !== 0 && w !== 1) ? y/w : y;
+  const zi = (w !== 0 && w !== 1) ? z/w : z;
   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;
+  out[0] = (xi*0.5+0.5)*vp[2]+vp[0];
+  out[1] = (yi*0.5+0.5)*vp[3]+vp[1];
+  out[2] = (zi - 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 nx = ((px-vp[0])/vp[2])*2-1;
+  const ny = ((py-vp[1])/vp[3])*2-1;
   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; }
+  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];
   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; }
+  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];
   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; }
+  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];
   out[0]=x/w; out[1]=y/w; out[2]=z/w;
   return out;
 }
@@ -494,12 +394,11 @@ function _ndcToScreen(out, px, py, pz, vp, ndcZMin) {
   return out;
 }
 
-// ── Inline PV and IPV helpers (stack-local, for paths that need them) ────
+// ── _ensurePV — return pvMatrix from bag, computing inline if absent ──────
 
 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;
+  if (m.pvMatrix) return m.pvMatrix;
+  const p = m.pMatrix, v = m.vMatrix;
   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],
@@ -523,27 +422,27 @@ function _ensurePV(m) {
 /**
  * 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).
+ * @param {Vec3}   out         Result written here.
+ * @param {number} px,py,pz    Input point.
+ * @param {string} from        Source space constant.
+ * @param {string} to          Target space constant.
+ * @param {object} m           Matrices bag:
+ *   { pMatrix, vMatrix, eMatrix?, pvMatrix?, ipvMatrix?, 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);
+    return _screenToWorld(out, px,py,pz, m.ipvMatrix, 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);
+    return _ndcToWorld(out, px,py,pz, m.ipvMatrix);
 
   // SCREEN ↔ NDC
   if (from === SCREEN && to === NDC)
@@ -553,34 +452,36 @@ function mapLocation(out, px, py, pz, from, to, m, vp, ndcZMin) {
 
   // WORLD ↔ EYE
   if (from === WORLD && to === EYE)
-    return mat4MulPoint(out, m.view, px,py,pz);
+    return mat4MulPoint(out, m.vMatrix, px,py,pz);
   if (from === EYE && to === WORLD)
-    return mat4MulPoint(out, m.eye, px,py,pz);
+    return mat4MulPoint(out, m.eMatrix, px,py,pz);
 
-  // EYE ↔ SCREEN (inline: eye→world→screen / screen→world→eye)
+  // EYE ↔ SCREEN
   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];
+    const e = m.eMatrix;
+    const ex=e[0]*px+e[4]*py+e[8]*pz+e[12],
+          ey=e[1]*px+e[5]*py+e[9]*pz+e[13],
+          ez=e[2]*px+e[6]*py+e[10]*pz+e[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);
+    _screenToWorld(out, px,py,pz, m.ipvMatrix, vp, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
-    return mat4MulPoint(out, m.view, wx,wy,wz);
+    return mat4MulPoint(out, m.vMatrix, wx,wy,wz);
   }
 
-  // EYE ↔ NDC (inline: eye→world→ndc / ndc→world→eye)
+  // EYE ↔ NDC
   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];
+    const e = m.eMatrix;
+    const ex=e[0]*px+e[4]*py+e[8]*pz+e[12],
+          ey=e[1]*px+e[5]*py+e[9]*pz+e[13],
+          ez=e[2]*px+e[6]*py+e[10]*pz+e[14];
     return _worldToNDC(out, ex,ey,ez, _ensurePV(m));
   }
   if (from === NDC && to === EYE) {
-    _ndcToWorld(out, px,py,pz, m.ipv);
+    _ndcToWorld(out, px,py,pz, m.ipvMatrix);
     const wx=out[0],wy=out[1],wz=out[2];
-    return mat4MulPoint(out, m.view, wx,wy,wz);
+    return mat4MulPoint(out, m.vMatrix, wx,wy,wz);
   }
 
   // MATRIX (custom frame) ↔ WORLD
@@ -591,49 +492,54 @@ function mapLocation(out, px, py, pz, from, to, m, vp, ndcZMin) {
 
   // 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);
+    const f = m.fromFrame;
+    const fx=f[0]*px+f[4]*py+f[8]*pz+f[12],
+          fy=f[1]*px+f[5]*py+f[9]*pz+f[13],
+          fz=f[2]*px+f[6]*py+f[10]*pz+f[14];
+    return mat4MulPoint(out, m.vMatrix, 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];
+    const e = m.eMatrix;
+    const ex=e[0]*px+e[4]*py+e[8]*pz+e[12],
+          ey=e[1]*px+e[5]*py+e[9]*pz+e[13],
+          ez=e[2]*px+e[6]*py+e[10]*pz+e[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];
+    const f = m.fromFrame;
+    const fx=f[0]*px+f[4]*py+f[8]*pz+f[12],
+          fy=f[1]*px+f[5]*py+f[9]*pz+f[13],
+          fz=f[2]*px+f[6]*py+f[10]*pz+f[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);
+    _screenToWorld(out, px,py,pz, m.ipvMatrix, 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];
+    const f = m.fromFrame;
+    const fx=f[0]*px+f[4]*py+f[8]*pz+f[12],
+          fy=f[1]*px+f[5]*py+f[9]*pz+f[13],
+          fz=f[2]*px+f[6]*py+f[10]*pz+f[14];
     return _worldToNDC(out, fx,fy,fz, _ensurePV(m));
   }
   if (from === NDC && to === MATRIX) {
-    _ndcToWorld(out, px,py,pz, m.ipv);
+    _ndcToWorld(out, px,py,pz, m.ipvMatrix);
     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];
+    const f = m.fromFrame;
+    const fx=f[0]*px+f[4]*py+f[8]*pz+f[12],
+          fy=f[1]*px+f[5]*py+f[9]*pz+f[13],
+          fz=f[2]*px+f[6]*py+f[10]*pz+f[14];
     return mat4MulPoint(out, m.toFrameInv, fx,fy,fz);
   }
 
@@ -644,7 +550,7 @@ function mapLocation(out, px, py, pz, from, to, m, vp, ndcZMin) {
 
 // ── Direction helpers ────────────────────────────────────────────────────
 
-/** Apply the 3×3 linear part of a mat4 (rotation/scale, no translation) */
+/** 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;
@@ -652,37 +558,24 @@ function _applyDir(out, mat, dx, dy, 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 zEye = 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;
@@ -691,7 +584,6 @@ function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
   } else {
     sdz = edz / (depthRange / (Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin)) / vpW));
   }
-
   out[0] = sdx; out[1] = sdy; out[2] = sdz;
   return out;
 }
@@ -699,7 +591,6 @@ function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
 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);
@@ -711,7 +602,6 @@ function _screenToWorldDir(out, dx, dy, dz, proj, view, eye, vpW, vpH, 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;
@@ -720,8 +610,6 @@ function _screenToWorldDir(out, dx, dy, dz, proj, view, eye, vpW, vpH, ndcZMin)
   } 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;
 }
@@ -743,21 +631,21 @@ function _ndcToScreenDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
 }
 
 /**
- * Map a direction between coordinate spaces.
- * Same flat-dispatch as mapLocation.
+ * Map a direction vector between coordinate spaces.
+ * Same bag contract 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);
+  // EYE ↔ WORLD (most common)
+  if (from === EYE && to === WORLD) return _applyDir(out, m.eMatrix, dx, dy, dz);
+  if (from === WORLD && to === EYE) return _applyDir(out, m.vMatrix, dx, dy, dz);
 
   // WORLD ↔ SCREEN
   if (from === WORLD && to === SCREEN)
-    return _worldToScreenDir(out, dx,dy,dz, m.proj, m.view, vpW, vpH, ndcZMin);
+    return _worldToScreenDir(out, dx,dy,dz, m.pMatrix, m.vMatrix, vpW, vpH, ndcZMin);
   if (from === SCREEN && to === WORLD)
-    return _screenToWorldDir(out, dx,dy,dz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    return _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
 
   // SCREEN ↔ NDC
   if (from === SCREEN && to === NDC)
@@ -765,45 +653,44 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
   if (from === NDC && to === SCREEN)
     return _ndcToScreenDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
 
-  // WORLD ↔ NDC (chain: world→screen→ndc / ndc→screen→world)
+  // WORLD ↔ NDC
   if (from === WORLD && to === NDC) {
-    _worldToScreenDir(out, dx,dy,dz, m.proj, m.view, vpW, vpH, ndcZMin);
+    _worldToScreenDir(out, dx,dy,dz, m.pMatrix, m.vMatrix, 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);
+    return _screenToWorldDir(out, sx,sy,sz, m.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
   }
 
   // EYE ↔ SCREEN
   if (from === EYE && to === SCREEN) {
-    // eye→world→screen
-    _applyDir(out, m.eye, dx,dy,dz);
+    _applyDir(out, m.eMatrix, 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);
+    return _worldToScreenDir(out, wx,wy,wz, m.pMatrix, m.vMatrix, vpW, vpH, ndcZMin);
   }
   if (from === SCREEN && to === EYE) {
-    _screenToWorldDir(out, dx,dy,dz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
-    return _applyDir(out, m.view, wx,wy,wz);
+    return _applyDir(out, m.vMatrix, wx,wy,wz);
   }
 
   // EYE ↔ NDC
   if (from === EYE && to === NDC) {
-    _applyDir(out, m.eye, dx,dy,dz);
+    _applyDir(out, m.eMatrix, 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);
+    _worldToScreenDir(out, wx,wy,wz, m.pMatrix, m.vMatrix, 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);
+    _screenToWorldDir(out, sx,sy,sz, m.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
-    return _applyDir(out, m.view, wx,wy,wz);
+    return _applyDir(out, m.vMatrix, wx,wy,wz);
   }
 
   // MATRIX ↔ WORLD
@@ -814,10 +701,10 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
   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);
+    return _applyDir(out, m.vMatrix, wx,wy,wz);
   }
   if (from === EYE && to === MATRIX) {
-    _applyDir(out, m.eye, dx,dy,dz);
+    _applyDir(out, m.eMatrix, dx,dy,dz);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.toFrameInv, wx,wy,wz);
   }
@@ -826,10 +713,10 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
   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);
+    return _worldToScreenDir(out, wx,wy,wz, m.pMatrix, m.vMatrix, vpW, vpH, ndcZMin);
   }
   if (from === SCREEN && to === MATRIX) {
-    _screenToWorldDir(out, dx,dy,dz, m.proj, m.view, m.eye, vpW, vpH, ndcZMin);
+    _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.toFrameInv, wx,wy,wz);
   }
@@ -838,14 +725,14 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
   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);
+    _worldToScreenDir(out, wx,wy,wz, m.pMatrix, m.vMatrix, 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);
+    _screenToWorldDir(out, sx,sy,sz, m.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.toFrameInv, wx,wy,wz);
   }
@@ -868,9 +755,9 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
 
 /**
  * World-units-per-pixel at a given eye-space Z depth.
- * @param {ArrayLike<number>} proj  Projection Mat4.
+ * @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} eyeZ     Eye-space Z (negative for in-front-of camera).
  * @param {number} ndcZMin  WEBGL or WEBGPU.
  */
 function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
@@ -881,58 +768,62 @@ function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
 }
 
 /**
- * @file Pure quaternion/spline math + PoseTrack state machine.
+ * @file Pure quaternion/spline math + track state machines.
  * @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
+ *    qSet qCopy qDot qNormalize qNegate qMul qSlerp qNlerp
  *    qFromAxisAngle qFromLookDir qFromRotMat3x3 qFromMat4 qToMat4
  *    quatToAxisAngle
  *  Spline / vector helpers
  *    catmullRomVec3  lerpVec3
  *  Transform / mat4 helpers
  *    transformToMat4  mat4ToTransform
- *  Track
- *    PoseTrack
+ *  Tracks
+ *    PoseTrack    — { pos, rot, scl } TRS keyframes
+ *    CameraTrack  — { eye, center, up } lookat keyframes
+ *
+ * ── Class hierarchy ───────────────────────────────────────────────────────────
+ *  Track (unexported, never instantiated directly)
+ *    └── PoseTrack   (exported)
+ *    └── CameraTrack (exported)
+ *
+ *  Track holds all transport machinery: cursor, play/stop/seek/tick,
+ *  hooks, rate semantics.  Subclasses add only keyframe storage and
+ *  add() / eval() for their respective data shape.
  *
  * ── 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.
+ *    Fire on playing transitions: false→true / true→false.
  *
- *  onPlay / onEnd / onStop      — user-space (public, set by user)
- *    onPlay : fires in play()  when playback starts   (false→true transition).
- *    onEnd  : fires in tick()  when cursor reaches a natural boundary (once mode).
- *    onStop : fires in stop()  and reset() — explicit, user-initiated deactivation.
- *
- *    onEnd and onStop are mutually exclusive per deactivation event.
- *    To react to any deactivation, chain both.
+ *  onPlay / onEnd / onStop      — user-space (public)
+ *    onPlay : fires in play()  on false→true transition.
+ *    onEnd  : fires in tick()  at natural boundary (once mode only).
+ *    onStop : fires in stop() / reset() — explicit deactivation.
+ *    onEnd and onStop are mutually exclusive per event.
  *
  *  Firing order:
  *    play()  → onPlay → _onActivate
- *    tick()  → onEnd  → _onDeactivate   (natural boundary, once mode)
+ *    tick()  → onEnd  → _onDeactivate
  *    stop()  → onStop → _onDeactivate
  *    reset() → onStop → _onDeactivate
  *
  * ── 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.
+ *  rate > 0   forward
+ *  rate < 0   backward
+ *  rate === 0 frozen: tick() no-op; playing unchanged
  *
- *  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.
+ *  play() is the sole setter of playing = true.
+ *  stop() is the sole setter of playing = false.
+ *  Assigning rate never starts or stops playback.
  *
  * ── One-keyframe behaviour ────────────────────────────────────────────────────
  *  play() with exactly one keyframe snaps eval() to that keyframe without
- *  setting playing = true and without animating.
+ *  setting playing = true and without firing hooks.
  */
 
 
@@ -953,68 +844,62 @@ const qCopy = (out, a) => {
 /** 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 */
+/** Normalise quaternion 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;
+  const l = Math.sqrt(out[0]*out[0]+out[1]*out[1]+out[2]*out[2]+out[3]*out[3]) || 1;
+  out[0]/=l; out[1]/=l; out[2]/=l; out[3]/=l; 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;
+/** Negate quaternion (same rotation, different hemisphere). @returns {number[]} out */
+const qNegate = (out, a) => {
+  out[0]=-a[0]; out[1]=-a[1]; out[2]=-a[2]; out[3]=-a[3]; return out;
 };
 
-/** out = a * b (Hamilton product). @returns {number[]} out */
+/** Hamilton product out = a * b. @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;
+  const ax=a[0],ay=a[1],az=a[2],aw=a[3], 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;
 };
 
+/** Spherical linear interpolation. @returns {number[]} out */
+const qSlerp = (out, a, b, t) => {
+  let bx=b[0],by=b[1],bz=b[2],bw=b[3];
+  let d = a[0]*bx+a[1]*by+a[2]*bz+a[3]*bw;
+  if (d < 0) { bx=-bx; by=-by; bz=-bz; bw=-bw; d=-d; }
+  let f0, f1;
+  if (1-d > 1e-10) {
+    const th=Math.acos(d), st=Math.sin(th);
+    f0=Math.sin((1-t)*th)/st; f1=Math.sin(t*th)/st;
+  } else {
+    f0=1-t; f1=t;
+  }
+  out[0]=a[0]*f0+bx*f1; out[1]=a[1]*f0+by*f1;
+  out[2]=a[2]*f0+bz*f1; out[3]=a[3]*f0+bw*f1;
+  return qNormalize(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].
+ * Normalised linear interpolation (nlerp).
+ * Cheaper than slerp; slightly non-constant angular velocity.
+ * Handles antipodal quats by flipping b when dot < 0.
  * @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;
+const qNlerp = (out, a, b, t) => {
+  let bx=b[0],by=b[1],bz=b[2],bw=b[3];
+  if (a[0]*bx+a[1]*by+a[2]*bz+a[3]*bw < 0) { bx=-bx; by=-by; bz=-bz; bw=-bw; }
+  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);
 };
 
 /**
- * Build a quaternion from an axis-angle rotation.
- * The axis need not be normalised.
+ * Build a quaternion from axis-angle.
  * @param {number[]} out
- * @param {number} ax  Axis x.
- * @param {number} ay  Axis y.
- * @param {number} az  Axis z.
+ * @param {number} ax @param {number} ay @param {number} az  Axis (need not be unit).
  * @param {number} angle  Radians.
  * @returns {number[]} out
  */
@@ -1022,93 +907,76 @@ 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[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).
+ * Build a quaternion from a look direction (−Z forward) and optional up (default +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);
+  let fx=dir[0],fy=dir[1],fz=dir[2];
+  const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
+  fx/=fl; fy/=fl; fz/=fl;
+  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 rl=Math.sqrt(rx*rx+ry*ry+rz*rz)||1;
+  rx/=rl; ry/=rl; rz/=rl;
+  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.
+ * Build a quaternion from a 3×3 rotation matrix (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;
+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;
+    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;
+    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.
+ * Extract a unit quaternion from the upper-left 3×3 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]);
+  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).
+ * Write a quaternion into the rotation block of a column-major mat4.
+ * 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;
+  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,yy=y*y2,yz=y*z2,zz=z*z2,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;
 };
 
@@ -1120,11 +988,11 @@ const qToMat4 = (out, q) => {
  */
 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];
+  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;
 };
 
@@ -1133,35 +1001,34 @@ const quatToAxisAngle = (q, out) => {
 // =========================================================================
 
 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);
+  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.
- * Boundary: when p0===p1 or p2===p3 the chord is reused (clamped end tangents).
+ * Centripetal Catmull-Rom interpolation (alpha=0.5, Barry-Goldman).
+ * out = interp(p0, p1, p2, p3, t) where t∈[0,1] maps p1→p2.
+ * Boundary: p0===p1 or p2===p3 clamps the end tangent.
  * @param {number[]} out  3-element result.
- * @param {number[]} p0   Control point before p1.
- * @param {number[]} p1   Segment start.
- * @param {number[]} p2   Segment end.
- * @param {number[]} p3   Control point after p2.
- * @param {number}   t    Blend [0, 1].
+ * @param {number[]} p0  Control point before p1.
+ * @param {number[]} p1  Segment start.
+ * @param {number[]} p2  Segment end.
+ * @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;
+  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];
+    const m1=t1_0*dt1, 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;
 };
@@ -1175,9 +1042,9 @@ const catmullRomVec3 = (out, p0, p1, p2, p3, t) => {
  * @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]);
+  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;
 };
 
@@ -1187,45 +1054,42 @@ const lerpVec3 = (out, a, b, t) => {
 
 /**
  * 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];
+  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.
+ * Assumes no shear. Scale 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;
+  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);
+    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)
+// S4a  Spec parser — PoseTrack
 // =========================================================================
 
 const _isNum   = (x) => typeof x === 'number' && Number.isFinite(x);
@@ -1234,198 +1098,303 @@ 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];
+  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;
 }
 
+// Euler: unit axis vectors and the six valid intrinsic orderings.
+const _EULER_AXES   = { X:[1,0,0], Y:[0,1,0], Z:[0,0,1] };
+const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
+
+/**
+ * Parse any rotation representation into a unit quaternion [x,y,z,w].
+ *
+ * Accepted forms:
+ *
+ *   [x,y,z,w]
+ *     Raw quaternion array.
+ *
+ *   { axis:[x,y,z], angle }
+ *     Axis-angle.  Axis need not be unit.
+ *
+ *   { dir:[x,y,z], up?:[x,y,z] }
+ *     Object orientation — forward direction (−Z) with optional up hint.
+ *
+ *   { eMatrix: mat4 }
+ *     Extract rotation block from an eye (eye→world) matrix.
+ *     Column-major Float32Array(16), plain Array, or { mat4 } wrapper.
+ *
+ *   { mat3: mat3 }
+ *     Column-major 3×3 rotation matrix — Float32Array(9) or plain Array.
+ *
+ *   { euler:[rx,ry,rz], order?:'YXZ' }
+ *     Intrinsic Euler angles (radians).  Angles are indexed by order position:
+ *     e[0] rotates around order[0] axis, e[1] around order[1], e[2] around order[2].
+ *     Supported orders: YXZ (default), XYZ, ZYX, ZXY, XZY, YZX.
+ *     Note: intrinsic ABC = extrinsic CBA with the same angles — to use
+ *     extrinsic order ABC, reverse the string and use intrinsic CBA.
+ *
+ *   { from:[x,y,z], to:[x,y,z] }
+ *     Shortest-arc rotation from one direction onto another.
+ *     Both vectors are normalised internally.
+ *     Antiparallel input: 180° rotation around a perpendicular axis.
+ *
+ * @param {*} v
+ * @returns {number[]|null}  [x,y,z,w] or null if unparseable.
+ */
 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]];
+
+  // raw [x,y,z,w]
+  if (Array.isArray(v) && v.length === 4 && v.every(n => typeof n === 'number'))
+    return [v[0],v[1],v[2],v[3]];
+
+  // { axis, angle }
   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);
+    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);
   }
+
+  // { dir, up? }
   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);
+    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);
+  }
+
+  // { eMatrix } — rotation block from eye (eye→world) matrix, col-major mat4
+  if (v.eMatrix != null) {
+    const m = (ArrayBuffer.isView(v.eMatrix) || Array.isArray(v.eMatrix))
+      ? v.eMatrix : (v.eMatrix.mat4 ?? null);
+    if (m && m.length >= 16) return qFromMat4([0,0,0,1], m);
+  }
+
+  // { mat3 } — column-major 3×3 rotation matrix
+  // col0=[m0,m1,m2], col1=[m3,m4,m5], col2=[m6,m7,m8]
+  // row-major for qFromRotMat3x3: row0=[m0,m3,m6], row1=[m1,m4,m7], row2=[m2,m5,m8]
+  if (v.mat3 != null) {
+    const m = v.mat3;
+    if ((ArrayBuffer.isView(m) || Array.isArray(m)) && m.length >= 9)
+      return qFromRotMat3x3([0,0,0,1], m[0],m[3],m[6], m[1],m[4],m[7], m[2],m[5],m[8]);
+  }
+
+  // { euler, order? } — intrinsic Euler angles (radians), default order YXZ
+  if (v.euler != null) {
+    const e = v.euler;
+    if (!Array.isArray(e) || e.length < 3) return null;
+    const order = (typeof v.order === 'string' && _EULER_ORDERS.has(v.order))
+      ? v.order : 'YXZ';
+    const q = [0,0,0,1];
+    const s = [0,0,0,1]; // scratch — reused each step
+    for (let i = 0; i < 3; i++) {
+      const ax = _EULER_AXES[order[i]];
+      qMul(q, q, qFromAxisAngle(s, ax[0],ax[1],ax[2], e[i]));
+    }
+    return q;
   }
+
+  // { from, to } — shortest-arc rotation from one direction onto another
+  if (v.from != null && v.to != null) {
+    const f = Array.isArray(v.from) ? v.from : [v.from.x||0, v.from.y||0, v.from.z||0];
+    const t = Array.isArray(v.to)   ? v.to   : [v.to.x||0,   v.to.y||0,   v.to.z||0];
+    const fl = Math.sqrt(f[0]*f[0]+f[1]*f[1]+f[2]*f[2]) || 1;
+    const tl = Math.sqrt(t[0]*t[0]+t[1]*t[1]+t[2]*t[2]) || 1;
+    const fx=f[0]/fl, fy=f[1]/fl, fz=f[2]/fl;
+    const tx=t[0]/tl, ty=t[1]/tl, tz=t[2]/tl;
+    const dot = fx*tx + fy*ty + fz*tz;
+    // parallel — identity
+    if (dot >= 1 - 1e-8) return [0,0,0,1];
+    // antiparallel — 180° around any perpendicular axis
+    if (dot <= -1 + 1e-8) {
+      // cross(from, X=[1,0,0]) = [0, fz, -fy]
+      let px=0, py=fz, pz=-fy;
+      let pl = Math.sqrt(px*px+py*py+pz*pz);
+      if (pl < 1e-8) {
+        // from ≈ ±X; try cross(from, Z=[0,0,1]) = [fy, -fx, 0]
+        px=fy; py=-fx; pz=0;
+        pl = Math.sqrt(px*px+py*py+pz*pz);
+      }
+      if (pl < 1e-8) return [0,0,0,1];
+      return qFromAxisAngle([0,0,0,1], px/pl,py/pl,pz/pl, Math.PI);
+    }
+    // general case — axis = normalize(cross(from, to))
+    let ax=fy*tz-fz*ty, ay=fz*tx-fx*tz, az=fx*ty-fy*tx;
+    const al = Math.sqrt(ax*ax+ay*ay+az*az) || 1;
+    return qFromAxisAngle([0,0,0,1], ax/al,ay/al,az/al,
+      Math.acos(Math.max(-1, Math.min(1, dot))));
+  }
+
   return null;
 }
 
+/**
+ * Parse a PoseTrack keyframe spec.
+ *
+ * Accepted forms:
+ *
+ *   { mMatrix }
+ *     Decompose a column-major mat4 into TRS via mat4ToTransform.
+ *     Float32Array(16), plain Array, or { mat4 } wrapper.
+ *     pos from col3, scl from column lengths, rot from normalised rotation block.
+ *
+ *   { pos, rot, scl }
+ *     Explicit TRS.  pos and scl are vec3, rot accepts any form from _parseQuat.
+ *     All fields are optional — missing pos/scl default to [0,0,0] / [1,1,1],
+ *     missing rot defaults to identity.
+ *
+ * @param {Object} spec
+ * @returns {{ pos:number[], rot:number[], scl:number[] }|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];
+
+  // { mMatrix } — full TRS decomposition from model matrix
+  if (spec.mMatrix != null) {
+    const m = (ArrayBuffer.isView(spec.mMatrix) || Array.isArray(spec.mMatrix))
+      ? spec.mMatrix : (spec.mMatrix.mat4 ?? null);
+    if (!m || m.length < 16) return null;
+    return mat4ToTransform({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] }, m);
+  }
+
+  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;
+  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
+// S4b  Spec parser — CameraTrack
 // =========================================================================
 
 /**
- * Renderer-agnostic keyframe animation track.
+ * Parse a camera keyframe spec into internal { eye, center, up } form.
  *
- * 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().
+ * Accepted forms:
  *
- * Position uses centripetal Catmull-Rom spline by default (posInterp = 'catmullrom');
- * set posInterp = 'linear' to switch to lerp. Rotation uses SLERP. Scale uses LERP.
+ *   { eye, center, up? }
+ *     Explicit lookat.  up defaults to [0,1,0] and is normalised on storage.
+ *     Note: eye here is a vec3 — distinguished from { eMatrix } by length.
  *
- * Rate semantics:
- *   rate > 0   forward
- *   rate < 0   backward
- *   rate === 0 frozen: tick() is a no-op; playing is NOT changed
+ *   { vMatrix: mat4 }
+ *     Column-major view matrix (world→eye).
+ *     eye reconstructed via -R^T·t; center = eye + forward·1; up = [0,1,0].
+ *     The matrix's up_ortho (col1) is intentionally NOT used as up —
+ *     passing it to cam.camera() shifts orbitControl's orbit reference.
+ *     Float32Array(16), plain Array, or { mat4 } wrapper.
  *
- * Assigning rate never starts or stops playback.
- * Only play() sets playing = true. Only stop() / reset() set it to false.
+ *   { eMatrix: mat4 }
+ *     Column-major eye matrix (eye→world, i.e. inverse view).
+ *     eye read directly from col3; center = eye + forward·1; up = [0,1,0].
+ *     Simpler extraction than vMatrix; prefer this form when eMatrix is available.
+ *     Float32Array(16), plain Array, or { mat4 } wrapper.
  *
- * One-keyframe behaviour:
- *   play() with exactly one keyframe snaps eval() to that keyframe
- *   without setting playing = true and without firing hooks.
- *
- * @example
- * const track = new PoseTrack()
- * track.add({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] })
- * track.add({ pos:[0,100,0], rot:[0,0,0,1], scl:[1,1,1] })
- * track.play({ loop: true, onStop: t => console.log('stopped at', t.time()) })
+ * @param {Object} spec
+ * @returns {{ eye:number[], center:number[], up:number[] }|null}
  */
-class PoseTrack {
+function _parseCameraSpec(spec) {
+  if (!spec || typeof spec !== 'object') return null;
+
+  // { vMatrix } — view matrix (world→eye); reconstruct eye via -R^T·t
+  if (spec.vMatrix != null) {
+    const m = (ArrayBuffer.isView(spec.vMatrix) || Array.isArray(spec.vMatrix))
+      ? spec.vMatrix : (spec.vMatrix.mat4 ?? null);
+    if (!m || m.length < 16) return null;
+    const ex = -(m[0]*m[12] + m[4]*m[13] + m[8]*m[14]);
+    const ey = -(m[1]*m[12] + m[5]*m[13] + m[9]*m[14]);
+    const ez = -(m[2]*m[12] + m[6]*m[13] + m[10]*m[14]);
+    const fx=-m[8], fy=-m[9], fz=-m[10];
+    const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
+    return { eye:[ex,ey,ez], center:[ex+fx/fl,ey+fy/fl,ez+fz/fl], up:[0,1,0] };
+  }
+
+  // { eMatrix } — eye matrix (eye→world); eye = col3, forward = -col2
+  if (spec.eMatrix != null) {
+    const m = (ArrayBuffer.isView(spec.eMatrix) || Array.isArray(spec.eMatrix))
+      ? spec.eMatrix : (spec.eMatrix.mat4 ?? null);
+    if (!m || m.length < 16) return null;
+    const ex=m[12], ey=m[13], ez=m[14];
+    const fx=-m[8], fy=-m[9], fz=-m[10];
+    const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
+    return { eye:[ex,ey,ez], center:[ex+fx/fl,ey+fy/fl,ez+fz/fl], up:[0,1,0] };
+  }
+
+  // { eye, center, up? } — explicit lookat (eye is a vec3, not a mat4)
+  const eye    = _parseVec3(spec.eye);
+  const center = _parseVec3(spec.center);
+  if (!eye || !center) return null;
+  const upRaw = spec.up ? _parseVec3(spec.up) : null;
+  const up    = upRaw || [0,1,0];
+  const ul    = Math.sqrt(up[0]*up[0]+up[1]*up[1]+up[2]*up[2]) || 1;
+  return { eye, center, up:[up[0]/ul, up[1]/ul, up[2]/ul] };
+}
+
+function _sameCameraKeyframe(a, b) {
+  for (let i=0;i<3;i++) {
+    if (a.eye[i]!==b.eye[i]) return false;
+    if (a.center[i]!==b.center[i]) return false;
+    if (a.up[i]!==b.up[i]) return false;
+  }
+  return true;
+}
+
+// =========================================================================
+// S5  Track — unexported base class (transport machinery only)
+// =========================================================================
+
+class Track {
   constructor() {
-    /** @type {Array<{pos:number[],rot:number[],scl:number[]}>} */
+    /** @type {Array} Keyframe array — shape depends on subclass. */
     this.keyframes = [];
     /** Whether playback is active. @type {boolean} */
     this.playing   = false;
-    /** Loop flag (overridden by pingPong). @type {boolean} */
+    /** Loop at boundaries. @type {boolean} */
     this.loop      = false;
-    /** Ping-pong bounce mode (takes precedence over loop). @type {boolean} */
+    /** Ping-pong bounce (takes precedence over loop). @type {boolean} */
     this.pingPong  = false;
-    /** Frames per segment (>=1). @type {number} */
+    /** 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} */
+    /** Frame offset within 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
+    // Internal rate — never directly starts/stops playback
     this._rate = 1;
 
-    // User-space hooks — fired on playback state transitions
-    /** Fires when play() starts a false→true transition. @type {Function|null} */
-    this.onPlay = null;
-    /** Fires in tick() when cursor hits a natural boundary (once mode only). @type {Function|null} */
-    this.onEnd  = null;
-    /** Fires on explicit stop() or reset(). Mutually exclusive with onEnd per event. @type {Function|null} */
-    this.onStop = null;
+    // User-space hooks
+    /** @type {Function|null} */ this.onPlay = null;
+    /** @type {Function|null} */ this.onEnd  = null;
+    /** @type {Function|null} */ this.onStop = null;
 
-    // Lib-space hooks (set by host layer — e.g. p5 bridge)
-    /** @type {Function|null} */
-    this._onActivate   = null;
-    /** @type {Function|null} */
-    this._onDeactivate = 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} */
+  /** Playback rate. Assigning never starts/stops playback. @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.
-  }
+  set rate(v) { this._rate = (_isNum(v)) ? v : 1; }
 
-  /** Number of interpolatable segments (keyframes.length - 1, min 0). @type {number} */
+  /** 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, onStop }.
-   *
-   * 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
+   * @param {number|Object} [rateOrOpts]  Numeric rate or options object:
+   *   { rate, duration, loop, pingPong, onPlay, onEnd, onStop }
+   * @returns {Track} this
    */
   play(rateOrOpts) {
     if (this.keyframes.length === 0) return this;
 
-    // One keyframe: snap only, no animation, no hooks
+    // One keyframe: snap cursor, no animation
     if (this.keyframes.length === 1) {
       this.seg = 0; this.f = 0;
       return this;
@@ -1444,9 +1413,7 @@ class PoseTrack {
       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);
+    const nSeg = this.segments, 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;
@@ -1454,7 +1421,6 @@ class PoseTrack {
 
     const wasPlaying = this.playing;
     this.playing = true;
-
     if (!wasPlaying) {
       if (typeof this.onPlay === 'function') { try { this.onPlay(this); } catch (_) {} }
       this._onActivate?.();
@@ -1463,11 +1429,9 @@ class PoseTrack {
   }
 
   /**
-   * Stop playback. No-op if already stopped.
-   * Fires `onStop` → `_onDeactivate`, then optionally seeks to the
-   * logical start (rate > 0 → t=0, rate < 0 → t=1).
-   * @param {boolean} [rewind=false]  Seek to playback origin after stopping.
-   * @returns {PoseTrack} this
+   * Stop playback.
+   * @param {boolean} [rewind=false]  Seek to origin after stopping.
+   * @returns {Track} this
    */
   stop(rewind) {
     const wasPlaying = this.playing;
@@ -1482,8 +1446,7 @@ class PoseTrack {
 
   /**
    * Clear all keyframes and stop.
-   * Fires `onStop` then `_onDeactivate` if was playing.
-   * @returns {PoseTrack} this
+   * @returns {Track} this
    */
   reset() {
     const wasPlaying = this.playing;
@@ -1497,13 +1460,27 @@ class PoseTrack {
     return this;
   }
 
+  /**
+   * 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;
+  }
+
   /**
    * 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
+   * @returns {Track} this
    */
   seek(t, segIndex) {
     const nSeg = this.segments;
@@ -1519,8 +1496,7 @@ class PoseTrack {
   }
 
   /**
-   * Normalised playback time across the full path [0, 1].
-   * Returns 0 when fewer than 2 keyframes exist.
+   * Normalised playback position [0,1].
    * @returns {number}
    */
   time() {
@@ -1531,10 +1507,8 @@ class PoseTrack {
   }
 
   /**
-   * 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 }}
+   * Snapshot of transport state.
+   * @returns {Object}
    */
   info() {
     return {
@@ -1552,12 +1526,8 @@ class PoseTrack {
   }
 
   /**
-   * 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.
-   *
+   * Advance cursor by rate frames.
+   * Returns true while playing, false when stopping.
    * @returns {boolean}
    */
   tick() {
@@ -1566,8 +1536,6 @@ class PoseTrack {
     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);
@@ -1575,25 +1543,22 @@ class PoseTrack {
     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 (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;
@@ -1613,15 +1578,117 @@ class PoseTrack {
     return true;
   }
 
+  /** @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;   }
+  }
+}
+
+// =========================================================================
+// S6  PoseTrack
+// =========================================================================
+
+/**
+ * Renderer-agnostic TRS keyframe track.
+ *
+ * Keyframe shape: { pos:[x,y,z], rot:[x,y,z,w], scl:[x,y,z] }
+ *
+ * add() accepts individual specs or a bulk array of specs:
+ *
+ *   { mMatrix }                          — full TRS from model matrix
+ *   { pos, rot, scl }                    — direct TRS
+ *   { pos, rot: [x,y,z,w] }             — explicit quaternion
+ *   { pos, rot: { axis, angle } }        — axis-angle
+ *   { pos, rot: { dir, up? } }           — look direction
+ *   { pos, rot: { eMatrix: mat4 } }      — rotation from eye matrix
+ *   { pos, rot: { mat3 } }               — column-major 3×3 rotation matrix
+ *   { pos, rot: { euler, order? } }      — intrinsic Euler angles (default YXZ)
+ *   { pos, rot: { from, to } }           — shortest-arc between two directions
+ *   [ spec, spec, ... ]                  — bulk
+ *
+ * eval() writes { pos, rot, scl }:
+ *   pos — Catmull-Rom (posInterp='catmullrom') or lerp
+ *   rot — slerp (rotInterp='slerp') or nlerp
+ *   scl — lerp
+ *
+ * @example
+ * const track = new PoseTrack()
+ * track.add({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] })
+ * track.add({ pos:[100,0,0], rot: { euler:[0, Math.PI/2, 0] } })
+ * track.add({ mMatrix: someModelMatrix })
+ * track.play({ loop: true })
+ * // per frame:
+ * track.tick()
+ * const out = { pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] }
+ * track.eval(out)
+ */
+class PoseTrack extends Track {
+  constructor() {
+    super();
+    /**
+     * Position interpolation mode.
+     * @type {'catmullrom'|'linear'}
+     */
+    this.posInterp = 'catmullrom';
+    /**
+     * Rotation interpolation mode.
+     * - 'slerp'  — constant angular velocity (default)
+     * - 'nlerp'  — normalised lerp; cheaper, slightly non-constant speed
+     * @type {'slerp'|'nlerp'}
+     */
+    this.rotInterp = 'slerp';
+    // Scratch for toMatrix() — avoids hot-path allocations
+    this._pos = [0,0,0];
+    this._rot = [0,0,0,1];
+    this._scl = [1,1,1];
+  }
+
+  /**
+   * Append one or more keyframes. Adjacent duplicates are skipped by default.
+   * @param {Object|Object[]} spec
+   * @param {{ deduplicate?: boolean }} [opts]
+   */
+  add(spec, opts) {
+    if (Array.isArray(spec)) {
+      for (const s of spec) this.add(s, opts);
+      return;
+    }
+    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
+   * @param {Object} spec
+   * @returns {boolean}
+   */
+  set(index, spec) {
+    if (!_isNum(index)) return false;
+    const i = index | 0, 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;
+  }
+
   /**
-   * 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.
+   * Evaluate interpolated TRS pose at current cursor.
    * @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] };
+    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;
 
@@ -1640,27 +1707,30 @@ class PoseTrack {
     const k0   = this.keyframes[seg];
     const k1   = this.keyframes[seg + 1];
 
-    // Position
+    // pos — Catmull-Rom or lerp
     if (this.posInterp === 'catmullrom') {
-      const p0 = seg > 0     ? this.keyframes[seg - 1].pos : k0.pos;
+      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);
+    // rot — slerp or nlerp
+    if (this.rotInterp === 'nlerp') {
+      qNlerp(out.rot, k0.rot, k1.rot, t);
+    } else {
+      qSlerp(out.rot, k0.rot, k1.rot, t);
+    }
 
-    // Scale — LERP
+    // scl — 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.
+   * Evaluate into an existing column-major mat4.
    * @param {Float32Array|number[]} outMat4  16-element array.
    * @returns {Float32Array|number[]} outMat4
    */
@@ -1668,17 +1738,163 @@ class PoseTrack {
     const xf = this.eval({ pos: this._pos, rot: this._rot, scl: this._scl });
     return transformToMat4(outMat4, xf);
   }
+}
 
-  // ── Private ──────────────────────────────────────────────────────────────
+// =========================================================================
+// S7  CameraTrack
+// =========================================================================
 
-  /** @private */
-  _setCursorFromScalar(s) {
+/**
+ * Lookat camera keyframe track.
+ *
+ * Keyframe shape: { eye:[x,y,z], center:[x,y,z], up:[x,y,z] }
+ *
+ * Each field is independently interpolated — eye and center along their
+ * own paths, up nlerped on the unit sphere. This correctly handles cameras
+ * that always look at a fixed target (center stays at origin throughout)
+ * as well as free-fly paths where center moves independently.
+ *
+ * add() accepts individual specs or a bulk array of specs:
+ *
+ *   { eye, center, up? }   explicit lookat; up defaults to [0,1,0]
+ *   { vMatrix: mat4 }      view matrix (world→eye); eye reconstructed via -R^T·t
+ *   { eMatrix: mat4 }      eye matrix (eye→world); eye read from col3 directly
+ *   [ spec, spec, ... ]    bulk
+ *
+ * Note on up for matrix forms:
+ *   up is always [0,1,0].  The matrix's col1 (up_ortho) is intentionally
+ *   not used — it differs from the hint [0,1,0] for upright cameras and
+ *   passing it to cam.camera() shifts orbitControl's orbit reference.
+ *   Use capturePose() (p5.tree bridge) when the real up hint is needed.
+ *
+ * eval() writes { eye, center, up }:
+ *   eye    — Catmull-Rom (eyeInterp='catmullrom') or lerp
+ *   center — Catmull-Rom (centerInterp='catmullrom') or lerp
+ *   up     — nlerp (normalize-after-lerp on unit sphere)
+ *
+ * @example
+ * const track = new CameraTrack()
+ * track.add({ eye:[0,0,500], center:[0,0,0] })
+ * track.add({ eMatrix: myEyeMatrix })
+ * track.add({ vMatrix: myViewMatrix })
+ * track.play({ loop: true })
+ * // per frame:
+ * track.tick()
+ * const out = { eye:[0,0,0], center:[0,0,0], up:[0,1,0] }
+ * track.eval(out)
+ * cam.camera(out.eye[0],out.eye[1],out.eye[2],
+ *            out.center[0],out.center[1],out.center[2],
+ *            out.up[0],out.up[1],out.up[2])
+ */
+class CameraTrack extends Track {
+  constructor() {
+    super();
+    /**
+     * Eye position interpolation mode.
+     * @type {'catmullrom'|'linear'}
+     */
+    this.eyeInterp = 'catmullrom';
+    /**
+     * Center (lookat target) interpolation mode.
+     * 'linear' suits fixed or predictably moving targets.
+     * 'catmullrom' gives smoother paths when center is also flying freely.
+     * @type {'catmullrom'|'linear'}
+     */
+    this.centerInterp = 'linear';
+    // Scratch for toCamera() — avoids hot-path allocations
+    this._eye    = [0,0,0];
+    this._center = [0,0,0];
+    this._up     = [0,1,0];
+  }
+
+  /**
+   * Append one or more camera keyframes. Adjacent duplicates are skipped by default.
+   *
+   * @param {Object|Object[]} spec
+   *   { eye, center, up? }  or  { vMatrix: mat4 }  or  { eMatrix: mat4 }  or  an array of either.
+   * @param {{ deduplicate?: boolean }} [opts]
+   */
+  add(spec, opts) {
+    if (Array.isArray(spec)) {
+      for (const s of spec) this.add(s, opts);
+      return;
+    }
+    const kf = _parseCameraSpec(spec);
+    if (!kf) return;
+    const dedup = !opts || opts.deduplicate !== false;
+    if (dedup && this.keyframes.length > 0) {
+      if (_sameCameraKeyframe(this.keyframes[this.keyframes.length - 1], kf)) return;
+    }
+    this.keyframes.push(kf);
+  }
+
+  /**
+   * Replace (or append at end) the keyframe at index.
+   * @param {number} index
+   * @param {Object} spec
+   * @returns {boolean}
+   */
+  set(index, spec) {
+    if (!_isNum(index)) return false;
+    const i = index | 0, kf = _parseCameraSpec(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;
+  }
+
+  /**
+   * Evaluate interpolated camera pose at current cursor.
+   *
+   * @param {{ eye:number[], center:number[], up:number[] }} [out]
+   * @returns {{ eye:number[], center:number[], up:number[] }} out
+   */
+  eval(out) {
+    out = out || { eye:[0,0,0], center:[0,0,0], up:[0,1,0] };
+    const n = this.keyframes.length;
+    if (n === 0) return out;
+
+    if (n === 1) {
+      const k = this.keyframes[0];
+      out.eye[0]=k.eye[0];       out.eye[1]=k.eye[1];       out.eye[2]=k.eye[2];
+      out.center[0]=k.center[0]; out.center[1]=k.center[1]; out.center[2]=k.center[2];
+      out.up[0]=k.up[0];         out.up[1]=k.up[1];         out.up[2]=k.up[2];
+      return out;
+    }
+
+    const nSeg = n - 1;
     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;   }
+    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];
+
+    // eye — Catmull-Rom or lerp
+    if (this.eyeInterp === 'catmullrom') {
+      const p0 = seg > 0      ? this.keyframes[seg - 1].eye : k0.eye;
+      const p3 = seg + 2 < n ? this.keyframes[seg + 2].eye : k1.eye;
+      catmullRomVec3(out.eye, p0, k0.eye, k1.eye, p3, t);
+    } else {
+      lerpVec3(out.eye, k0.eye, k1.eye, t);
+    }
+
+    // center — Catmull-Rom or lerp (independent lookat target)
+    if (this.centerInterp === 'catmullrom') {
+      const c0 = seg > 0      ? this.keyframes[seg - 1].center : k0.center;
+      const c3 = seg + 2 < n ? this.keyframes[seg + 2].center : k1.center;
+      catmullRomVec3(out.center, c0, k0.center, k1.center, c3, t);
+    } else {
+      lerpVec3(out.center, k0.center, k1.center, t);
+    }
+
+    // up — nlerp (normalize after lerp; correct for typical near-upright cameras)
+    const ux = k0.up[0] + t*(k1.up[0]-k0.up[0]);
+    const uy = k0.up[1] + t*(k1.up[1]-k0.up[1]);
+    const uz = k0.up[2] + t*(k1.up[2]-k0.up[2]);
+    const ul = Math.sqrt(ux*ux+uy*uy+uz*uz) || 1;
+    out.up[0]=ux/ul; out.up[1]=uy/ul; out.up[2]=uz/ul;
+
+    return out;
   }
 }
 
@@ -1839,5 +2055,5 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   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 };
+export { CameraTrack, 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, mat3NormalFromMat4, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulPoint, mat4PV, mat4ToTransform, mat4Transpose, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qMul, qNegate, qNlerp, qNormalize, qSet, qSlerp, qToMat4, quatToAxisAngle, sphereVisibility, transformToMat4 };
 //# sourceMappingURL=index.js.map