@nakednous/tree 0.0.3 → 0.0.5

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) {
@@ -1211,46 +1098,165 @@ 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 (ArrayBuffer.isView(v) && v.length >= 3) return [v[0], v[1], v[2]];
+  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] — plain array or typed array
+  if ((Array.isArray(v) || ArrayBuffer.isView(v)) && v.length === 4) 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);
   }
+
+  // { 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);
   }
-  // { view } — column-major mat4 or {mat4} wrapper
-  if (v.view != null) {
-    const m = (ArrayBuffer.isView(v.view) || Array.isArray(v.view)) ? v.view : (v.view.mat4 ?? null);
-    if (m && m.length === 16) return qFromMat4([0,0,0,1], m);
-  }
-  // { eye, center, up? } — lookat shorthand matching CameraTrack input
-  if (v.eye && v.center) {
-    const eye = _parseVec3(v.eye), ctr = _parseVec3(v.center);
-    if (eye && ctr) {
-      const up  = (v.up ? _parseVec3(v.up) : null) || [0,1,0];
-      let fx=ctr[0]-eye[0], fy=ctr[1]-eye[1], fz=ctr[2]-eye[2];
-      const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1; fx/=fl; fy/=fl; fz/=fl;
-      let rx=fy*up[2]-fz*up[1], ry=fz*up[0]-fx*up[2], rz=fx*up[1]-fy*up[0];
-      const rl=Math.sqrt(rx*rx+ry*ry+rz*rz)||1; rx/=rl; ry/=rl; rz/=rl;
-      const ux=ry*fz-rz*fy, uy=rz*fx-rx*fz, uz=rx*fy-ry*fx;
-      return qFromRotMat3x3([0,0,0,1], rx,ux,-fx, ry,uy,-fy, rz,uz,-fz);
+
+  // { 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;
+
+  // { 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];
@@ -1272,17 +1278,22 @@ function _sameTransform(a, b) {
  *
  * Accepted forms:
  *
- *   { eye, center, up? }
- *     Explicit lookat.  up defaults to [0,1,0] and is normalised on storage.
+ *   { eye, center?, up? }
+ *     Explicit lookat.  center defaults to [0,0,0], up defaults to [0,1,0].
+ *     Both are normalised/stored as-is.  eye must be a vec3.
+ *
+ *   { 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.
  *
- *   { view: mat4 }
- *     Column-major view matrix (Float32Array(16), plain Array, or {mat4} wrapper).
- *     eye is extracted from the matrix translation block.
- *     center = eye + forward * 1 (unit distance — sufficient for interpolation).
- *     up defaults to [0,1,0]. The matrix's up_ortho (col1) is intentionally
- *     NOT extracted; using up_ortho as the hint causes orbitControl drift.
- *     If you need to preserve roll from a rolled camera, pass the live
- *     camera's up hint via capturePose() instead of using { view }.
+ *   { 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.
  *
  * @param {Object} spec
  * @returns {{ eye:number[], center:number[], up:number[] }|null}
@@ -1290,34 +1301,38 @@ function _sameTransform(a, b) {
 function _parseCameraSpec(spec) {
   if (!spec || typeof spec !== 'object') return null;
 
-  // { view } form
-  if (spec.view != null) {
-    const m = (ArrayBuffer.isView(spec.view) || Array.isArray(spec.view))
-      ? spec.view
-      : (spec.view.mat4 ?? 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;
-    // Extract eye position: eye = -R^T * t
-    // Column-major view mat: col0=right, col1=up_ortho, col2=-fwd, col3=translation
     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]);
-    // forward = -col2 = [-m[8], -m[9], -m[10]]
     const fx=-m[8], fy=-m[9], fz=-m[10];
     const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
-    // center = eye + normalized_fwd * 1
-    const cx=ex+fx/fl, cy=ey+fy/fl, cz=ez+fz/fl;
-    return { eye:[ex,ey,ez], center:[cx,cy,cz], up:[0,1,0] };
+    return { eye:[ex,ey,ez], center:[ex+fx/fl,ey+fy/fl,ez+fz/fl], up:[0,1,0] };
   }
 
-  // { eye, center, up? } form
-  const eye    = _parseVec3(spec.eye);
-  const center = _parseVec3(spec.center);
-  if (!eye || !center) return null;
+  // { 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);
+  if (!eye) return null;
+  const center = _parseVec3(spec.center) || [0,0,0];
   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] };
+  return { eye, center, up:[up[0]/ul, up[1]/ul, up[2]/ul] };
 }
 
 function _sameCameraKeyframe(a, b) {
@@ -1584,13 +1599,19 @@ class 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:
- *   { 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 (object orientation)
- *   { pos, rot: { view: mat4 } }         from view matrix rotation block
- *   { pos, rot: { eye, center, up? } }   lookat shorthand
- *   [ spec, spec, ... ]                  bulk
+ *
+ *   { mMatrix }                           — full TRS from model matrix
+ *   { pos?, rot?, scl? }                  — direct TRS; all fields optional
+ *   { 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
+ *
+ * Missing fields default to: pos → [0,0,0], rot → [0,0,0,1], scl → [1,1,1].
  *
  * eval() writes { pos, rot, scl }:
  *   pos — Catmull-Rom (posInterp='catmullrom') or lerp
@@ -1599,8 +1620,10 @@ class Track {
  *
  * @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:[0,0,0,1], scl:[1,1,1] })
+ * track.add({ pos:[0,0,0] })                           // identity rot, uniform scl
+ * track.add({ pos:[100,0,0], rot: { euler:[0, Math.PI/2, 0] } })
+ * track.add({ rot: { axis:[0,1,0], angle: Math.PI } }) // pos defaults to [0,0,0]
+ * track.add({ mMatrix: someModelMatrix })
  * track.play({ loop: true })
  * // per frame:
  * track.tick()
@@ -1733,18 +1756,21 @@ class PoseTrack extends Track {
  * 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.
+ * 
+ * Missing fields default to: center → [0,0,0], up → [0,1,0].
  *
  * add() accepts individual specs or a bulk array of specs:
- *   { eye, center, up? }    explicit lookat; up defaults to [0,1,0]
- *   { view: mat4 }          view matrix; eye extracted, center = eye+fwd*1,
- *                           up = [0,1,0] (safe default — see note below)
- *   [ spec, spec, ... ]     bulk
  *
- * Note on up for { view: mat4 }:
- *   The view matrix's col1 (up_ortho) is intentionally not used as up.
- *   For upright cameras up_ortho differs from the hint [0,1,0], and
- *   passing it to cam.camera() would shift orbitControl's orbit reference.
- *   Use capturePose() when you need to preserve the real up hint.
+ *   { eye, center?, up? }  explicit lookat; center defaults to [0,0,0], up 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
@@ -1753,8 +1779,10 @@ class PoseTrack extends Track {
  *
  * @example
  * const track = new CameraTrack()
- * track.add({ eye:[0,0,500], center:[0,0,0] })
+ * track.add({ eye:[0,0,500] })                 // center defaults to [0,0,0]
  * track.add({ eye:[300,-150,0], center:[0,0,0] })
+ * track.add({ eMatrix: myEyeMatrix })
+ * track.add({ vMatrix: myViewMatrix })
  * track.play({ loop: true })
  * // per frame:
  * track.tick()
@@ -1789,7 +1817,7 @@ class CameraTrack extends Track {
    * Append one or more camera keyframes. Adjacent duplicates are skipped by default.
    *
    * @param {Object|Object[]} spec
-   *   { eye, center, up? }  or  { view: mat4 }  or  an array of either.
+   *   { eye, center?, up? }  or  { vMatrix: mat4 }  or  { eMatrix: mat4 }  or  an array of either.
    * @param {{ deduplicate?: boolean }} [opts]
    */
   add(spec, opts) {
@@ -2033,5 +2061,5 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   return allIn ? VISIBLE : SEMIVISIBLE;
 }
 
-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, 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, qNlerp, 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