@nakednous/tree 0.0.10 → 0.0.12

package/dist/index.js

@@ -31,40 +31,580 @@ const _j = Object.freeze([0, -1, 0]);
 const _k = Object.freeze([0, 0, -1]);
 
 /**
- * @file Pure numeric math — mat4, mat3, projection queries, space transforms.
- * @module tree/math
+ * @file Quaternion algebra and mat4/mat3 conversions.
+ * @module tree/quat
  * @license AGPL-3.0-only
  *
- * CONVENTIONS (all functions in this module follow these):
+ * Quaternions are stored as flat [x, y, z, w] arrays (w-last, glTF layout).
  *
- *   Storage:    Column-major Float32Array / ArrayLike<number>.
- *               Element [col*4 + row] = M[row, col].
+ * All functions follow the out-first, zero-allocation contract.
+ * Conversion functions bridge between quaternion and matrix representations
+ * but do not perform any higher-level graphics operations — those belong
+ * in form.js (matrix construction from specs) or track.js (animation).
+ */
+
+
+// =========================================================================
+// Basic ops
+// =========================================================================
+
+/** Set all four components. @returns {number[]} out */
+const qSet = (out, x, y, z, w) => {
+  out[0] = x; out[1] = y; out[2] = z; out[3] = w; return out;
+};
+
+/** Copy quaternion a into out. @returns {number[]} out */
+const qCopy = (out, a) => {
+  out[0] = a[0]; out[1] = a[1]; out[2] = a[2]; out[3] = a[3]; return out;
+};
+
+/** Dot product of two quaternions. */
+const qDot = (a, b) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3];
+
+/** Normalise quaternion in-place. @returns {number[]} out */
+const qNormalize = (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 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;
+};
+
+/** 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], 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;
+};
+
+// =========================================================================
+// Interpolation
+// =========================================================================
+
+/** 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);
+};
+
+/**
+ * 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 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);
+};
+
+// =========================================================================
+// Construction
+// =========================================================================
+
+/**
+ * Build a quaternion from axis-angle.
+ * @param {number[]} out
+ * @param {number} ax @param {number} ay @param {number} az  Axis (need not be unit).
+ * @param {number} angle  Radians.
+ * @returns {number[]} out
+ */
+const qFromAxisAngle = (out, ax, ay, az, angle) => {
+  const half = angle * 0.5;
+  const s    = Math.sin(half);
+  const len  = Math.sqrt(ax*ax + ay*ay + az*az) || 1;
+  out[0] = s * ax / len; out[1] = s * ay / len; out[2] = s * az / len;
+  out[3] = Math.cos(half);
+  return out;
+};
+
+/**
+ * Build a quaternion from a look direction (−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 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 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;
+  if (tr > 0) {
+    const s=0.5/Math.sqrt(tr+1);
+    out[3]=0.25/s; out[0]=(m21-m12)*s; out[1]=(m02-m20)*s; out[2]=(m10-m01)*s;
+  } else if (m00>m11 && m00>m22) {
+    const s=2*Math.sqrt(1+m00-m11-m22);
+    out[3]=(m21-m12)/s; out[0]=0.25*s; out[1]=(m01+m10)/s; out[2]=(m02+m20)/s;
+  } else if (m11>m22) {
+    const s=2*Math.sqrt(1+m11-m00-m22);
+    out[3]=(m02-m20)/s; out[0]=(m01+m10)/s; out[1]=0.25*s; out[2]=(m12+m21)/s;
+  } else {
+    const s=2*Math.sqrt(1+m22-m00-m11);
+    out[3]=(m10-m01)/s; out[0]=(m02+m20)/s; out[1]=(m12+m21)/s; out[2]=0.25*s;
+  }
+  return qNormalize(out);
+};
+
+/**
+ * Extract a unit quaternion from the upper-left 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]);
+
+/**
+ * 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,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;
+};
+
+// =========================================================================
+// Decomposition
+// =========================================================================
+
+/**
+ * Decompose a unit quaternion into { axis:[x,y,z], angle } (radians).
+ * @param {number[]} q  [x,y,z,w].
+ * @param {Object}  [out]
+ * @returns {{ axis: number[], angle: number }}
+ */
+const quatToAxisAngle = (q, out) => {
+  out = out || {};
+  const x=q[0],y=q[1],z=q[2],w=q[3];
+  const sinHalf = Math.sqrt(x*x+y*y+z*z);
+  if (sinHalf < 1e-8) { out.axis=[0,1,0]; out.angle=0; return out; }
+  out.angle = 2*Math.atan2(sinHalf, w);
+  out.axis  = [x/sinHalf, y/sinHalf, z/sinHalf];
+  return out;
+};
+
+/**
+ * @file Matrix construction from geometric specs and partial decomposition.
+ * @module tree/form
+ * @license AGPL-3.0-only
+ *
+ * Constructs mat4s from higher-level specs: TRS transforms, orthonormal
+ * bases, lookat parameters, projection parameters, and special-purpose
+ * matrices (bias, reflection).
+ *
+ * Design invariant: form.js has no dependency on query.js. Construction
+ * from specs requires only scalar arithmetic and quaternion conversions.
+ * Callers compose the resulting matrices using query.js (mat4Mul etc.).
+ *
+ * Lookat constructors live here because a camera is just a frame — the eye
+ * matrix is the camera object's model matrix, not a camera-specific concept.
+ * There is no camera module; mat4View and mat4Eye are frame
+ * constructions that happen to use lookat parameterisation.
+ *
+ * Projection constructors live here because they construct matrices from
+ * geometric parameters. Projection scalar reads (projNear, projFov, etc.)
+ * live in query.js — they interrogate an existing projection matrix.
+ *
+ * Partial decomposers (mat4To___) are the inverse of construction — they
+ * extract a single component from an existing matrix. Kept alongside
+ * constructors because they are paired operations on the same components.
+ *
+ * Imports quat.js only. No dependency on query.js, visibility.js, or track.js.
+ *
+ * All functions follow the out-first, zero-allocation contract.
+ * Returns null on degeneracy where applicable.
+ */
+
+
+// =========================================================================
+// Frame construction
+// =========================================================================
+
+/**
+ * Rigid frame from orthonormal basis + translation.
+ * The primitive that lookat constructors use internally.
+ *
+ * Column-major layout: col0=right, col1=up, col2=forward, col3=translation.
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} rx,ry,rz  Right vector (col 0).
+ * @param {number} ux,uy,uz  Up vector    (col 1).
+ * @param {number} fx,fy,fz  Forward vec  (col 2).
+ * @param {number} tx,ty,tz  Translation  (col 3).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4FromBasis(out, rx,ry,rz, ux,uy,uz, fx,fy,fz, tx,ty,tz) {
+  out[0]=rx;  out[1]=ry;  out[2]=rz;  out[3]=0;
+  out[4]=ux;  out[5]=uy;  out[6]=uz;  out[7]=0;
+  out[8]=fx;  out[9]=fy;  out[10]=fz; out[11]=0;
+  out[12]=tx; out[13]=ty; out[14]=tz; out[15]=1;
+  return out;
+}
+
+/**
+ * View matrix (world→eye) from lookat parameters.
+ * Cheaper than building the eye matrix and inverting.
+ *
+ * Convention: −Z axis points toward center (camera looks along −Z in eye space).
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} ex,ey,ez   Eye (camera) position.
+ * @param {number} cx,cy,cz   Center (look-at target).
+ * @param {number} ux,uy,uz   World up hint (need not be unit).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4View(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
+  // z = normalize(eye - center)  (camera +Z away from target)
+  let zx=ex-cx, zy=ey-cy, zz=ez-cz;
+  const zl=Math.sqrt(zx*zx+zy*zy+zz*zz)||1;
+  zx/=zl; zy/=zl; zz/=zl;
+  // x = normalize(up × z)  (right)
+  let xx=uy*zz-uz*zy, xy=uz*zx-ux*zz, xz=ux*zy-uy*zx;
+  const xl=Math.sqrt(xx*xx+xy*xy+xz*xz)||1;
+  xx/=xl; xy/=xl; xz/=xl;
+  // y = z × x  (up_ortho, guaranteed perpendicular)
+  const yx=zy*xz-zz*xy, yy=zz*xx-zx*xz, yz=zx*xy-zy*xx;
+  // View = [R | -R·t]  (column-major)
+  out[0]=xx;              out[1]=yx;              out[2]=zx;              out[3]=0;
+  out[4]=xy;              out[5]=yy;              out[6]=zy;              out[7]=0;
+  out[8]=xz;              out[9]=yz;              out[10]=zz;             out[11]=0;
+  out[12]=-(xx*ex+xy*ey+xz*ez);
+  out[13]=-(yx*ex+yy*ey+yz*ez);
+  out[14]=-(zx*ex+zy*ey+zz*ez);
+  out[15]=1;
+  return out;
+}
+
+/**
+ * Eye matrix (eye→world) from lookat parameters.
+ * Transpose of the rotation block + direct translation column.
+ * Same inputs as mat4View.
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} ex,ey,ez   Eye (camera) position.
+ * @param {number} cx,cy,cz   Center (look-at target).
+ * @param {number} ux,uy,uz   World up hint (need not be unit).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4Eye(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
+  // Same basis computation as mat4View.
+  let zx=ex-cx, zy=ey-cy, zz=ez-cz;
+  const zl=Math.sqrt(zx*zx+zy*zy+zz*zz)||1;
+  zx/=zl; zy/=zl; zz/=zl;
+  let xx=uy*zz-uz*zy, xy=uz*zx-ux*zz, xz=ux*zy-uy*zx;
+  const xl=Math.sqrt(xx*xx+xy*xy+xz*xz)||1;
+  xx/=xl; xy/=xl; xz/=xl;
+  const yx=zy*xz-zz*xy, yy=zz*xx-zx*xz, yz=zx*xy-zy*xx;
+  // Eye matrix = [R^T | t]  (rotation transposed, translation = eye position)
+  out[0]=xx;  out[1]=xy;  out[2]=xz;  out[3]=0;
+  out[4]=yx;  out[5]=yy;  out[6]=yz;  out[7]=0;
+  out[8]=zx;  out[9]=zy;  out[10]=zz; out[11]=0;
+  out[12]=ex; out[13]=ey; out[14]=ez; out[15]=1;
+  return out;
+}
+
+// =========================================================================
+// TRS construction
+// =========================================================================
+
+/**
+ * Column-major mat4 from flat TRS scalars.
+ * No struct allocation — all components passed as plain numbers.
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} tx,ty,tz      Translation.
+ * @param {number} qx,qy,qz,qw  Rotation quaternion [x,y,z,w].
+ * @param {number} sx,sy,sz      Scale.
+ * @returns {Float32Array|number[]} out
+ */
+function mat4FromTRS(out, tx,ty,tz, qx,qy,qz,qw, sx,sy,sz) {
+  const x2=qx+qx,y2=qy+qy,z2=qz+qz;
+  const xx=qx*x2,xy=qx*y2,xz=qx*z2,yy=qy*y2,yz=qy*z2,zz=qz*z2;
+  const wx=qw*x2,wy=qw*y2,wz=qw*z2;
+  out[0]=(1-(yy+zz))*sx; out[1]=(xy+wz)*sx;     out[2]=(xz-wy)*sx;     out[3]=0;
+  out[4]=(xy-wz)*sy;     out[5]=(1-(xx+zz))*sy; out[6]=(yz+wx)*sy;     out[7]=0;
+  out[8]=(xz+wy)*sz;     out[9]=(yz-wx)*sz;     out[10]=(1-(xx+yy))*sz; out[11]=0;
+  out[12]=tx; out[13]=ty; out[14]=tz; out[15]=1;
+  return out;
+}
+
+/**
+ * Translation-only mat4.
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} tx,ty,tz
+ * @returns {Float32Array|number[]} out
+ */
+function mat4FromTranslation(out, tx,ty,tz) {
+  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]=tx; out[13]=ty; out[14]=tz; out[15]=1;
+  return out;
+}
+
+/**
+ * Scale-only mat4.
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} sx,sy,sz
+ * @returns {Float32Array|number[]} out
+ */
+function mat4FromScale(out, sx,sy,sz) {
+  out[0]=sx; out[1]=0;  out[2]=0;  out[3]=0;
+  out[4]=0;  out[5]=sy; out[6]=0;  out[7]=0;
+  out[8]=0;  out[9]=0;  out[10]=sz; out[11]=0;
+  out[12]=0; out[13]=0; out[14]=0;  out[15]=1;
+  return out;
+}
+
+// =========================================================================
+// Projection construction
+// =========================================================================
+
+/**
+ * Perspective projection matrix.
+ *
+ * NDC convention: ndcZMin = WEBGL (−1) or WEBGPU (0).
+ * near maps to ndcZMin, far maps to +1.
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} fov      Vertical field of view (radians).
+ * @param {number} aspect   Width / height.
+ * @param {number} near     Near plane distance (positive).
+ * @param {number} far      Far plane distance (positive, > near).
+ * @param {number} ndcZMin  -1 (WEBGL) or 0 (WEBGPU).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4Perspective(out, fov, aspect, near, far, ndcZMin) {
+  const f = 1 / Math.tan(fov * 0.5);
+  out[0]=f/aspect; out[1]=0; out[2]=0;  out[3]=0;
+  out[4]=0;        out[5]=f; out[6]=0;  out[7]=0;
+  out[8]=0;        out[9]=0;
+  out[10]=(ndcZMin*near-far)/(far-near);
+  out[11]=-1;
+  out[12]=0; out[13]=0;
+  out[14]=(ndcZMin-1)*far*near/(far-near);
+  out[15]=0;
+  return out;
+}
+
+/**
+ * Orthographic projection matrix.
+ *
+ * NDC convention: ndcZMin = WEBGL (−1) or WEBGPU (0).
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} left,right,bottom,top  Frustum extents.
+ * @param {number} near,far              Clip plane distances (positive).
+ * @param {number} ndcZMin               -1 (WEBGL) or 0 (WEBGPU).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4Ortho(out, left, right, bottom, top, near, far, ndcZMin) {
+  const rl=1/(right-left), tb=1/(top-bottom), fn=1/(far-near);
+  out[0]=2*rl;              out[1]=0;                out[2]=0;                     out[3]=0;
+  out[4]=0;                 out[5]=2*tb;             out[6]=0;                     out[7]=0;
+  out[8]=0;                 out[9]=0;
+  out[10]=(ndcZMin-1)*fn;
+  out[11]=0;
+  out[12]=-(right+left)*rl; out[13]=-(top+bottom)*tb;
+  out[14]=(ndcZMin*far-near)*fn;
+  out[15]=1;
+  return out;
+}
+
+/**
+ * Frustum (off-centre perspective) projection matrix.
+ *
+ * NDC convention: ndcZMin = WEBGL (−1) or WEBGPU (0).
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} left,right,bottom,top  Near-plane extents.
+ * @param {number} near,far              Clip plane distances (positive).
+ * @param {number} ndcZMin               -1 (WEBGL) or 0 (WEBGPU).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4Frustum(out, left, right, bottom, top, near, far, ndcZMin) {
+  const rl=1/(right-left), tb=1/(top-bottom);
+  out[0]=2*near*rl;         out[1]=0;               out[2]=0;  out[3]=0;
+  out[4]=0;                 out[5]=2*near*tb;       out[6]=0;  out[7]=0;
+  out[8]=(right+left)*rl;   out[9]=(top+bottom)*tb;
+  out[10]=(ndcZMin*near-far)/(far-near);
+  out[11]=-1;
+  out[12]=0; out[13]=0;
+  out[14]=(ndcZMin-1)*far*near/(far-near);
+  out[15]=0;
+  return out;
+}
+
+// =========================================================================
+// Special-purpose construction
+// =========================================================================
+
+/**
+ * Bias matrix: remaps xyz from NDC to texture/UV space [0,1].
+ * xy always remap from [−1,1]; z remaps from [ndcZMin,1].
+ * Used to transform light-space NDC coordinates for shadow map sampling.
+ *
+ * Column-major (WebGL, ndcZMin=−1):
+ *   [ 0.5  0    0    0.5 ]
+ *   [ 0    0.5  0    0.5 ]
+ *   [ 0    0    0.5  0.5 ]
+ *   [ 0    0    0    1   ]
+ *
+ * Column-major (WebGPU, ndcZMin=0):
+ *   [ 0.5  0    0    0.5 ]
+ *   [ 0    0.5  0    0.5 ]
+ *   [ 0    0    1    0   ]
+ *   [ 0    0    0    1   ]
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} ndcZMin  WEBGL (−1) or WEBGPU (0).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4Bias(out, ndcZMin) {
+  const sz = 1 / (1 - ndcZMin);
+  const tz = -ndcZMin / (1 - ndcZMin);
+  out[0]=0.5; out[1]=0;   out[2]=0;   out[3]=0;
+  out[4]=0;   out[5]=0.5; out[6]=0;   out[7]=0;
+  out[8]=0;   out[9]=0;   out[10]=sz; out[11]=0;
+  out[12]=0.5; out[13]=0.5; out[14]=tz; out[15]=1;
+  return out;
+}
+
+/**
+ * Reflection matrix across a plane ax + by + cz = d.
+ * [nx, ny, nz] must be a unit normal.
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} nx,ny,nz  Unit plane normal.
+ * @param {number} d         Plane offset (dot(point_on_plane, normal)).
+ * @returns {Float32Array|number[]} out
+ */
+function mat4Reflect(out, nx,ny,nz,d) {
+  out[0]=1-2*nx*nx; out[1]=-2*ny*nx; out[2]=-2*nz*nx; out[3]=0;
+  out[4]=-2*nx*ny;  out[5]=1-2*ny*ny; out[6]=-2*nz*ny; out[7]=0;
+  out[8]=-2*nx*nz;  out[9]=-2*ny*nz; out[10]=1-2*nz*nz; out[11]=0;
+  out[12]=2*d*nx;   out[13]=2*d*ny;  out[14]=2*d*nz;   out[15]=1;
+  return out;
+}
+
+// =========================================================================
+// Partial decomposition  (mat4To___ mirrors mat4From___)
+// =========================================================================
+
+/**
+ * Extract translation from a column-major mat4 (column 3).
+ * @param {Float32Array|number[]} out3  3-element destination.
+ * @param {Float32Array|number[]} m     16-element source.
+ * @returns {Float32Array|number[]} out3
+ */
+function mat4ToTranslation(out3, m) {
+  out3[0]=m[12]; out3[1]=m[13]; out3[2]=m[14];
+  return out3;
+}
+
+/**
+ * Extract scale from a column-major mat4 (column lengths of rotation block).
+ * Assumes no shear.
+ * @param {Float32Array|number[]} out3  3-element destination.
+ * @param {Float32Array|number[]} m     16-element source.
+ * @returns {Float32Array|number[]} out3
+ */
+function mat4ToScale(out3, m) {
+  out3[0]=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2]);
+  out3[1]=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6]);
+  out3[2]=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10]);
+  return out3;
+}
+
+/**
+ * Extract rotation as a unit quaternion from a column-major mat4.
+ * Scale is factored out from each column before extraction.
+ * Assumes no shear.
+ * @param {number[]} out4  4-element [x,y,z,w] destination.
+ * @param {Float32Array|number[]} m  16-element source.
+ * @returns {number[]} out4
+ */
+function mat4ToRotation(out4, m) {
+  const sx=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2])||1;
+  const sy=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6])||1;
+  const sz=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10])||1;
+  return qFromRotMat3x3(out4,
+    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);
+}
+
+/**
+ * @file Matrix arithmetic, space-transform dispatch, and projection queries.
+ * @module tree/query
+ * @license AGPL-3.0-only
+ *
+ * The operative layer — receives existing matrices and extracts information.
+ * Contrast with form.js which constructs matrices from specs.
+ *
+ *   form.js  — you have specs, you want a matrix
+ *   query.js  — you have a matrix, you want information
  *
- *   Multiply:   mat4Mul(out, A, B) = A · B   (standard math order).
+ * No dependency on form.js. Operating on matrices requires no knowledge
+ * of how they were constructed.
  *
- *   Pipeline:   clip = P · V · M · v
- *               P = projection (eye → clip)
- *               V = view       (world → eye)
- *               M = model      (local → world)
+ * Storage: column-major Float32Array / ArrayLike<number>.
+ * Element [col*4 + row] = M[row, col].
  *
- *   PV:         All functions expecting a "pv" matrix receive P · V.
- *               This is what _worldToScreen, _ensurePV, etc. compute.
+ * Multiply: mat4Mul(out, A, B) = A · B  (standard math order).
  *
- *   Matrix stack (translate/rotate/scale in p5):
- *     Each call post-multiplies: M = M · T, so:
- *       translate(tx,ty,tz); rotateY(a); scale(s);
- *     yields M = T · R · S. A vertex v is transformed as M·v = T·R·S·v
- *     (scaled first, then rotated, then translated — last-written-first-applied).
+ * Pipeline: clip = P · V · M · v
+ *   P = projection (eye → clip)
+ *   V = view       (world → eye)
+ *   M = model      (local → world)
  *
- *   p5 bridge note (for implementors of host layers):
- *     p5.Matrix.mult(B) computes  B · this  (pre-multiply, arg on LEFT).
- *     p5 translate/rotate/scale do this · T  (post-multiply, GL stack).
- *     So p5's pvMatrix() = V.clone().mult(P) = P · V — same as ours.
- *     The bridge extracts .mat4 (Float32Array) and feeds it directly,
- *     or uses mat4Mul(out, proj, view) for the non-cached path.
+ * NDC convention parameter (ndcZMin):
+ *   WEBGL  = -1   z ∈ [−1, 1]
+ *   WEBGPU =  0   z ∈ [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`.
+ * All functions follow the out-first, zero-allocation contract.
  * Returns null on degeneracy (singular matrix, etc.).
  */
 
@@ -193,6 +733,24 @@ function mat4MulPoint(out, m, x, y, z) {
   return out;
 }
 
+/**
+ * Apply only the 3×3 linear block of a mat4 to a direction vector.
+ * No translation, no perspective divide. Suitable for directions and normals
+ * when the matrix is known to be orthogonal (use mat3NormalFromMat4 for normals
+ * under non-uniform scale).
+ *
+ * @param {Float32Array|number[]} out  3-element destination.
+ * @param {Float32Array|number[]} m    16-element mat4.
+ * @param {number} dx,dy,dz           Input direction.
+ * @returns {Float32Array|number[]} out
+ */
+function mat4MulDir(out, m, dx, dy, dz) {
+  out[0] = m[0]*dx + m[4]*dy + m[8]*dz;
+  out[1] = m[1]*dx + m[5]*dy + m[9]*dz;
+  out[2] = m[2]*dx + m[6]*dy + m[10]*dz;
+  return out;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Projection queries  (read scalars from a projection mat4)
 // ═══════════════════════════════════════════════════════════════════════════
@@ -320,13 +878,13 @@ function mat3Direction(out, from, to) {
 //
 // 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)
+//     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)
 //   }
 //
 
@@ -337,90 +895,62 @@ 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];
-  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] = (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;
+  const xi = (w !== 0 && w !== 1) ? 1/w : 1;
+  const nx = x*xi, ny = y*xi, nz = z*xi;
+  const vpX=vp[0], vpY=vp[1], vpW=Math.abs(vp[2]), vpH=Math.abs(vp[3]);
+  out[0] = vpX + vpW * (nx + 1) * 0.5;
+  out[1] = vpY + vpH * (1 - (ny + 1) * 0.5);
+  out[2] = (nz - ndcZMin) / (1 - ndcZMin);
   return out;
 }
 
-function _screenToWorld(out, px, py, pz, ipv, vp, ndcZMin) {
-  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];
-  out[0]=x/w; out[1]=y/w; out[2]=z/w;
-  return out;
+function _screenToWorld(out, sx, sy, sz, ipv, vp, ndcZMin) {
+  const vpX=vp[0], vpY=vp[1], vpW=Math.abs(vp[2]), vpH=Math.abs(vp[3]);
+  const nx = (sx - vpX) / vpW * 2 - 1;
+  const ny = 1 - (sy - vpY) / vpH * 2;
+  const nz = sz * (1 - ndcZMin) + ndcZMin;
+  return mat4MulPoint(out, ipv, nx, ny, nz);
 }
 
 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];
-  out[0]=x/w; out[1]=y/w; out[2]=z/w;
+  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];
+  const xi = (w !== 0 && w !== 1) ? 1/w : 1;
+  out[0]=x*xi; out[1]=y*xi; out[2]=z*xi;
   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];
-  out[0]=x/w; out[1]=y/w; out[2]=z/w;
-  return out;
+function _ndcToWorld(out, nx, ny, nz, ipv) {
+  return mat4MulPoint(out, ipv, nx, ny, nz);
 }
 
-function _screenToNDC(out, px, py, pz, vp, ndcZMin) {
-  const ndcZRange = 1 - ndcZMin;
-  out[0] = ((px-vp[0])/vp[2])*2-1;
-  out[1] = ((py-vp[1])/vp[3])*2-1;
-  out[2] = pz * ndcZRange + ndcZMin;
+function _screenToNDC(out, sx, sy, sz, vp, ndcZMin) {
+  const vpX=vp[0], vpY=vp[1], vpW=Math.abs(vp[2]), vpH=Math.abs(vp[3]);
+  out[0] = (sx - vpX) / vpW * 2 - 1;
+  out[1] = 1 - (sy - vpY) / vpH * 2;
+  out[2] = sz * (1 - ndcZMin) + ndcZMin;
   return out;
 }
 
-function _ndcToScreen(out, px, py, pz, vp, ndcZMin) {
-  const ndcZRange = 1 - ndcZMin;
-  out[0] = (px*0.5+0.5)*vp[2]+vp[0];
-  out[1] = (py*0.5+0.5)*vp[3]+vp[1];
-  out[2] = (pz - ndcZMin) / ndcZRange;
+function _ndcToScreen(out, nx, ny, nz, vp, ndcZMin) {
+  const vpX=vp[0], vpY=vp[1], vpW=Math.abs(vp[2]), vpH=Math.abs(vp[3]);
+  out[0] = vpX + vpW * (nx + 1) * 0.5;
+  out[1] = vpY + vpH * (1 - (ny + 1) * 0.5);
+  out[2] = (nz - ndcZMin) / (1 - ndcZMin);
   return out;
 }
 
-// ── _ensurePV — return pvMatrix from bag, computing inline if absent ──────
-
 function _ensurePV(m) {
   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],
-    p[2]*v[0]+p[6]*v[1]+p[10]*v[2]+p[14]*v[3],
-    p[3]*v[0]+p[7]*v[1]+p[11]*v[2]+p[15]*v[3],
-    p[0]*v[4]+p[4]*v[5]+p[8]*v[6]+p[12]*v[7],
-    p[1]*v[4]+p[5]*v[5]+p[9]*v[6]+p[13]*v[7],
-    p[2]*v[4]+p[6]*v[5]+p[10]*v[6]+p[14]*v[7],
-    p[3]*v[4]+p[7]*v[5]+p[11]*v[6]+p[15]*v[7],
-    p[0]*v[8]+p[4]*v[9]+p[8]*v[10]+p[12]*v[11],
-    p[1]*v[8]+p[5]*v[9]+p[9]*v[10]+p[13]*v[11],
-    p[2]*v[8]+p[6]*v[9]+p[10]*v[10]+p[14]*v[11],
-    p[3]*v[8]+p[7]*v[9]+p[11]*v[10]+p[15]*v[11],
-    p[0]*v[12]+p[4]*v[13]+p[8]*v[14]+p[12]*v[15],
-    p[1]*v[12]+p[5]*v[13]+p[9]*v[14]+p[13]*v[15],
-    p[2]*v[12]+p[6]*v[13]+p[10]*v[14]+p[14]*v[15],
-    p[3]*v[12]+p[7]*v[13]+p[11]*v[14]+p[15]*v[15],
-  ];
+  m.pvMatrix = new Float32Array(16);
+  mat4Mul(m.pvMatrix, m.pMatrix, m.vMatrix);
+  return m.pvMatrix;
 }
 
 /**
- * Map a point between coordinate spaces.
+ * Map a point between named coordinate spaces.
  *
  * @param {Vec3}   out         Result written here.
  * @param {number} px,py,pz    Input point.
@@ -548,90 +1078,55 @@ function mapLocation(out, px, py, pz, from, to, m, vp, ndcZMin) {
   return out;
 }
 
-// ── Direction helpers ────────────────────────────────────────────────────
+// ── Direction leaf helpers ───────────────────────────────────────────────
 
 /** Apply the 3×3 linear part of a mat4 (rotation/scale, no translation). */
-function _applyDir(out, mat, dx, dy, dz) {
-  out[0]=mat[0]*dx+mat[4]*dy+mat[8]*dz;
-  out[1]=mat[1]*dx+mat[5]*dy+mat[9]*dz;
-  out[2]=mat[2]*dx+mat[6]*dy+mat[10]*dz;
+function _applyDir(out, m, dx, dy, dz) {
+  out[0]=m[0]*dx+m[4]*dy+m[8]*dz;
+  out[1]=m[1]*dx+m[5]*dy+m[9]*dz;
+  out[2]=m[2]*dx+m[6]*dy+m[10]*dz;
   return out;
 }
 
 function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
-  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) {
-    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 {
-    const orthoW = Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin));
-    sdx *= vpW / orthoW;
-    sdy *= vpH / Math.abs(projTop(proj, ndcZMin) - projBottom(proj, ndcZMin));
-  }
-  const near = projNear(proj, ndcZMin), far = projFar(proj);
-  const depthRange = near - far;
-  let sdz;
-  if (isPersp) {
-    sdz = edz / (depthRange / Math.tan(projFov(proj) / 2));
-  } else {
-    sdz = edz / (depthRange / (Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin)) / vpW));
-  }
-  out[0] = sdx; out[1] = sdy; out[2] = sdz;
+  // Transform to clip space (no w divide for direction).
+  const vx=view[0]*dx+view[4]*dy+view[8]*dz;
+  const vy=view[1]*dx+view[5]*dy+view[9]*dz;
+  const vz=view[2]*dx+view[6]*dy+view[10]*dz;
+  const cx=proj[0]*vx+proj[4]*vy+proj[8]*vz;
+  const cy=proj[1]*vx+proj[5]*vy+proj[9]*vz;
+  const cz=proj[2]*vx+proj[6]*vy+proj[10]*vz;
+  // NDC→screen scale (direction, no offset).
+  out[0]=cx*vpW*0.5; out[1]=-cy*vpH*0.5;
+  out[2]=cz*(1-ndcZMin)*0.5;
   return out;
 }
 
-function _screenToWorldDir(out, dx, dy, dz, proj, view, eye, vpW, vpH, ndcZMin) {
-  const isPersp = proj[15] === 0;
-  let edx = dx, edy = dy;
-  if (isPersp) {
-    const zEye = view[14];
-    const halfTan = Math.tan(projFov(proj) / 2);
-    const k = Math.abs(zEye * halfTan);
-    edx *= 2 * k / vpH;
-    edy *= 2 * k / vpH;
-  } else {
-    const orthoW = Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin));
-    edx *= orthoW / vpW;
-    edy *= Math.abs(projTop(proj, ndcZMin) - projBottom(proj, ndcZMin)) / vpH;
-  }
-  const near = projNear(proj, ndcZMin), far = projFar(proj);
-  const depthRange = near - far;
-  let edz;
-  if (isPersp) {
-    edz = dz * (depthRange / Math.tan(projFov(proj) / 2));
-  } else {
-    edz = dz * (depthRange / (Math.abs(projRight(proj, ndcZMin) - projLeft(proj, ndcZMin)) / vpW));
-  }
-  _applyDir(out, eye, edx, edy, edz);
+function _screenToWorldDir(out, dx, dy, dz, proj, eMatrix, vpW, vpH, ndcZMin) {
+  // Screen direction → NDC direction.
+  const nx=dx/(vpW*0.5), ny=-dy/(vpH*0.5);
+  const nz=dz/((1-ndcZMin)*0.5);
+  // NDC direction → eye direction (inverse projection, linear only).
+  const ex=nx/proj[0], ey=ny/proj[5], ez=nz;
+  // Eye direction → world direction.
+  _applyDir(out, eMatrix, ex, ey, ez);
   return out;
 }
 
 function _screenToNDCDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
-  const ndcZRange = 1 - ndcZMin;
-  out[0] = 2 * dx / vpW;
-  out[1] = 2 * dy / vpH;
-  out[2] = dz * ndcZRange;
+  out[0]=dx/(vpW*0.5); out[1]=-dy/(vpH*0.5);
+  out[2]=dz/((1-ndcZMin)*0.5);
   return out;
 }
 
 function _ndcToScreenDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
-  const ndcZRange = 1 - ndcZMin;
-  out[0] = vpW * dx / 2;
-  out[1] = vpH * dy / 2;
-  out[2] = dz / ndcZRange;
+  out[0]=dx*vpW*0.5; out[1]=-dy*vpH*0.5;
+  out[2]=dz*(1-ndcZMin)*0.5;
   return out;
 }
 
 /**
- * Map a direction vector between coordinate spaces.
+ * Map a direction between named coordinate spaces.
  * Same bag contract as mapLocation.
  */
 function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
@@ -645,7 +1140,7 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
   if (from === WORLD && to === SCREEN)
     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.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+    return _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
 
   // SCREEN ↔ NDC
   if (from === SCREEN && to === NDC)
@@ -662,7 +1157,7 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, 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.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+    return _screenToWorldDir(out, sx,sy,sz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
   }
 
   // EYE ↔ SCREEN
@@ -672,7 +1167,7 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, 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.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+    _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.vMatrix, wx,wy,wz);
   }
@@ -688,7 +1183,7 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, 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.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+    _screenToWorldDir(out, sx,sy,sz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.vMatrix, wx,wy,wz);
   }
@@ -716,7 +1211,7 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, 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.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+    _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.toFrameInv, wx,wy,wz);
   }
@@ -732,7 +1227,7 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, 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.pMatrix, m.vMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+    _screenToWorldDir(out, sx,sy,sz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
     const wx=out[0],wy=out[1],wz=out[2];
     return _applyDir(out, m.toFrameInv, wx,wy,wz);
   }
@@ -791,14 +1286,13 @@ function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
  * @param {number} H   Canvas height (CSS pixels).
  * @returns {Float32Array} proj (same reference)
  */
-function applyPickMatrix(proj, px, py, W, H) {
+function mat4Pick(proj, px, py, W, H) {
   const cx =  2 * (px + 0.5) / W - 1;
-  const cy = -2 * (py + 0.5) / H + 1;   // Y flip: screen-down → NDC-up
+  const cy = -2 * (py + 0.5) / H + 1;
   const sx = W;
   const sy = H;
   const tx = -cx * W;
   const ty = -cy * H;
-  // P_pick = M_pick * P_orig  (rows 2 and 3 are unchanged)
   for (let j = 0; j < 4; j++) {
     const a = proj[j * 4];
     const b = proj[j * 4 + 1];
@@ -810,14 +1304,19 @@ function applyPickMatrix(proj, px, py, W, H) {
 }
 
 /**
- * @file Pure quaternion/spline math + track state machines.
+ * @file Spline math and keyframe animation state machines.
  * @module tree/track
  * @license AGPL-3.0-only
  *
- * Zero dependencies.  No p5, DOM, WebGL, or WebGPU usage.
+ * Quaternion algebra is provided by quat.js — this module imports and uses
+ * it but does not define it. Spline helpers (hermiteVec3, lerpVec3) and
+ * TRS↔mat4 conversions (transformToMat4, mat4ToTransform) remain here
+ * because they are tightly coupled to the PoseTrack keyframe shape.
+ *
+ * Zero dependencies on p5, DOM, WebGL, or WebGPU.
  *
  * ── Exports ──────────────────────────────────────────────────────────────────
- *  Quaternion helpers
+ *  Quaternion helpers  (re-exported from quat.js)
  *    qSet qCopy qDot qNormalize qNegate qMul qSlerp qNlerp
  *    qFromAxisAngle qFromLookDir qFromRotMat3x3 qFromMat4 qToMat4
  *    quatToAxisAngle
@@ -857,13 +1356,12 @@ function applyPickMatrix(proj, px, py, W, H) {
  *    reset() → onStop → _onStop → _onDeactivate
  *
  * ── Loop modes ────────────────────────────────────────────────────────────────
- *  once     loop=false, bounce=false  — stop at end (fires onEnd)
- *  repeat   loop=true,  bounce=false  — wrap back to start
- *  bounce loop=true,  bounce=true   — bounce at boundaries
+ *  loop:false, bounce:false  — play once, stop at end (fires onEnd)
+ *  loop:true,  bounce:false  — repeat, wrap back to start
+ *  loop:true,  bounce:true   — bounce forever at boundaries
+ *  loop:false, bounce:true   — bounce once: flip at far boundary, stop at origin
  *
- *  Exclusivity enforced in play():
- *    bounce: true  → loop is also set true
- *    loop: false     → bounce is also cleared
+ *  bounce and loop are fully independent flags — no exclusivity enforced.
  *
  * ── Playback semantics (rate + _dir) ─────────────────────────────────────────
  *  rate > 0   forward
@@ -886,175 +1384,6 @@ function applyPickMatrix(proj, px, py, W, H) {
  */
 
 
-// =========================================================================
-// S1  Quaternion helpers  (flat [x, y, z, w], w-last)
-// =========================================================================
-
-/** Set all four components. @returns {number[]} out */
-const qSet = (out, x, y, z, w) => {
-  out[0] = x; out[1] = y; out[2] = z; out[3] = w; return out;
-};
-
-/** Copy quaternion a into out. @returns {number[]} out */
-const qCopy = (out, a) => {
-  out[0] = a[0]; out[1] = a[1]; out[2] = a[2]; out[3] = a[3]; return out;
-};
-
-/** Dot product of two quaternions. */
-const qDot = (a, b) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3];
-
-/** Normalise quaternion in-place. @returns {number[]} out */
-const qNormalize = (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 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;
-};
-
-/** 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], 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);
-};
-
-/**
- * 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 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 axis-angle.
- * @param {number[]} out
- * @param {number} ax @param {number} ay @param {number} az  Axis (need not be unit).
- * @param {number} angle  Radians.
- * @returns {number[]} out
- */
-const qFromAxisAngle = (out, ax, ay, az, angle) => {
-  const half = angle * 0.5;
-  const s    = Math.sin(half);
-  const len  = Math.sqrt(ax*ax + ay*ay + az*az) || 1;
-  out[0] = s * ax / len; out[1] = s * ay / len; out[2] = s * az / len;
-  out[3] = Math.cos(half);
-  return out;
-};
-
-/**
- * Build a quaternion from a look direction (−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 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 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;
-  if (tr > 0) {
-    const s=0.5/Math.sqrt(tr+1);
-    out[3]=0.25/s; out[0]=(m21-m12)*s; out[1]=(m02-m20)*s; out[2]=(m10-m01)*s;
-  } else if (m00>m11 && m00>m22) {
-    const s=2*Math.sqrt(1+m00-m11-m22);
-    out[3]=(m21-m12)/s; out[0]=0.25*s; out[1]=(m01+m10)/s; out[2]=(m02+m20)/s;
-  } else if (m11>m22) {
-    const s=2*Math.sqrt(1+m11-m00-m22);
-    out[3]=(m02-m20)/s; out[0]=(m01+m10)/s; out[1]=0.25*s; out[2]=(m12+m21)/s;
-  } else {
-    const s=2*Math.sqrt(1+m22-m00-m11);
-    out[3]=(m10-m01)/s; out[0]=(m02+m20)/s; out[1]=(m12+m21)/s; out[2]=0.25*s;
-  }
-  return qNormalize(out);
-};
-
-/**
- * Extract a unit quaternion from the upper-left 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]);
-
-/**
- * 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,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;
-};
-
-/**
- * Decompose a unit quaternion into { axis:[x,y,z], angle } (radians).
- * @param {number[]} q  [x,y,z,w].
- * @param {Object}  [out]
- * @returns {{ axis: number[], angle: number }}
- */
-const quatToAxisAngle = (q, out) => {
-  out = out || {};
-  const x=q[0],y=q[1],z=q[2],w=q[3];
-  const sinHalf = Math.sqrt(x*x+y*y+z*z);
-  if (sinHalf < 1e-8) { out.axis=[0,1,0]; out.angle=0; return out; }
-  out.angle = 2*Math.atan2(sinHalf, w);
-  out.axis  = [x/sinHalf, y/sinHalf, z/sinHalf];
-  return out;
-};
-
 // =========================================================================
 // S2  Spline / vector helpers
 // =========================================================================
@@ -1086,14 +1415,13 @@ const hermiteVec3 = (out, p0, m0, p1, m1, t) => {
 
 // Centripetal CR outgoing tangent at p1 for segment p1→p2, scaled by dt1.
 const _crTanOut = (out, p0, p1, p2, p3) => {
-  const dt0=Math.pow(_dist3(p0,p1),0.5)||1, dt1=Math.pow(_dist3(p1,p2),0.5)||1; Math.pow(_dist3(p2,p3),0.5)||1;
+  const dt0=Math.pow(_dist3(p0,p1),0.5)||1, dt1=Math.pow(_dist3(p1,p2),0.5)||1;
   for (let i=0;i<3;i++) out[i]=((p1[i]-p0[i])/dt0-(p2[i]-p0[i])/(dt0+dt1)+(p2[i]-p1[i])/dt1)*dt1;
   return out;
 };
 
-// Centripetal CR incoming tangent at p2 for segment p1→p2, scaled by dt1.
 const _crTanIn = (out, p0, p1, p2, p3) => {
-  Math.pow(_dist3(p0,p1),0.5)||1; const dt1=Math.pow(_dist3(p1,p2),0.5)||1, dt2=Math.pow(_dist3(p2,p3),0.5)||1;
+  const dt1=Math.pow(_dist3(p1,p2),0.5)||1, dt2=Math.pow(_dist3(p2,p3),0.5)||1;
   for (let i=0;i<3;i++) out[i]=((p2[i]-p1[i])/dt1-(p3[i]-p1[i])/(dt1+dt2)+(p3[i]-p2[i])/dt2)*dt1;
   return out;
 };
@@ -1181,33 +1509,13 @@ const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
  *
  * 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.
+ *   [x,y,z,w]                        — raw quaternion array
+ *   { axis:[x,y,z], angle }          — axis-angle
+ *   { dir:[x,y,z], up?:[x,y,z] }    — forward direction (−Z) with optional up
+ *   { eMatrix: mat4 }                — rotation block of an eye matrix
+ *   { mat3: mat3 }                   — column-major 3×3 rotation matrix
+ *   { euler:[rx,ry,rz], order? }     — intrinsic Euler (default order: YXZ)
+ *   { from:[x,y,z], to:[x,y,z] }    — shortest-arc rotation
  *
  * @param {*} v
  * @returns {number[]|null}  [x,y,z,w] or null if unparseable.
@@ -1215,46 +1523,48 @@ const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
 function _parseQuat(v) {
   if (!v) return null;
 
-  // 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]];
+  // Raw array [x,y,z,w]
+  if (Array.isArray(v) && v.length === 4) return [v[0],v[1],v[2],v[3]];
+  if (ArrayBuffer.isView(v) && v.length >= 4) return [v[0],v[1],v[2],v[3]];
+
+  if (typeof v !== 'object') return null;
 
   // { 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);
+  if (v.axis != null && v.angle != null) {
+    const ax = Array.isArray(v.axis) ? v.axis : [v.axis.x||0, v.axis.y||0, v.axis.z||0];
+    return qFromAxisAngle([0,0,0,1], ax[0],ax[1],ax[2], v.angle);
   }
 
   // { dir, up? }
-  if (v.dir) {
+  if (v.dir != null) {
     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
+  // { eMatrix }
   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);
+    if (!m || m.length < 16) return null;
+    return qFromRotMat3x3([0,0,0,1], m[0],m[4],m[8], m[1],m[5],m[9], m[2],m[6],m[10]);
   }
 
-  // { 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]
+  // { mat3 }
   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]);
+    const m = (ArrayBuffer.isView(v.mat3) || Array.isArray(v.mat3))
+      ? v.mat3 : null;
+    if (!m || m.length < 9) return null;
+    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
+  // { euler, order? }
   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 order = (v.order && _EULER_ORDERS.has(v.order)) ? v.order : 'YXZ';
     const q = [0,0,0,1];
-    const s = [0,0,0,1]; // scratch — reused each step
+    const s = [0,0,0,1];
     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]));
@@ -1262,7 +1572,7 @@ function _parseQuat(v) {
     return q;
   }
 
-  // { from, to } — shortest-arc rotation from one direction onto another
+  // { from, to }
   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];
@@ -1271,22 +1581,14 @@ function _parseQuat(v) {
     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) { 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,
@@ -1304,14 +1606,12 @@ function _parseQuat(v) {
  *   { 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?, tanIn?, tanOut? }
  *     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.
  *     tanIn/tanOut are optional vec3 tangents for Hermite interpolation.
- *     When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
  *
  * @param {Object} spec
  * @returns {{ pos:number[], rot:number[], scl:number[], tanIn:number[]|null, tanOut:number[]|null }|null}
@@ -1355,22 +1655,12 @@ function _sameTransform(a, b) {
  *   { eye, center?, up?, fov?, halfHeight?,
  *     eyeTanIn?, eyeTanOut?, centerTanIn?, centerTanOut? }
  *     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.
  *     eyeTanIn/Out and centerTanIn/Out are optional vec3 tangents for Hermite.
  *     When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
  *
- *   { 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.
- *
- *   { 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.
+ *   Removed forms (task 2):
+ *     { vMatrix } and { eMatrix } — use PoseTrack.add({ mMatrix: eMatrix }) for
+ *     full-fidelity capture including roll, or cam.capturePose() for lookat-style.
  *
  * @param {Object} spec
  * @returns {{ eye:number[], center:number[], up:number[],
@@ -1381,36 +1671,8 @@ function _sameTransform(a, b) {
 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],
-             fov:null, halfHeight:null,
-             eyeTanIn:null, eyeTanOut:null, centerTanIn:null, centerTanOut: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],
-             fov:null, halfHeight:null,
-             eyeTanIn:null, eyeTanOut:null, centerTanIn:null, centerTanOut:null };
-  }
-
-  // { eye, center?, up? } — explicit lookat (eye is a vec3, not a mat4)
-  const eye    = _parseVec3(spec.eye);
+  // { eye, center?, up? } — explicit lookat
+  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;
@@ -1452,7 +1714,7 @@ class Track {
     /** Loop at boundaries. @type {boolean} */
     this.loop      = false;
     /** Ping-pong bounce (takes precedence over loop). @type {boolean} */
-    this.bounce  = false;
+    this.bounce    = false;
     /** Frames per segment (≥1). @type {number} */
     this.duration  = 30;
     /** Current segment index. @type {number} */
@@ -1463,9 +1725,9 @@ class Track {
     // Internal rate — never directly starts/stops playback
     this._rate = 1;
     // Internal bounce direction: +1 forward, -1 backward.
-    // Flipped by tick() at boundaries. Never exposed publicly.
-    // rate always holds the user-set value — only _dir changes.
     this._dir  = 1;
+    // Scratch: true once _dir has been flipped in bounce-once mode.
+    this._bounced = false;
 
     // User-space hooks
     /** @type {Function|null} */ this.onPlay = null;
@@ -1508,8 +1770,8 @@ class Track {
     } else if (rateOrOpts && typeof rateOrOpts === 'object') {
       const o = rateOrOpts;
       if (_isNum(o.duration))             this.duration  = Math.max(1, o.duration | 0);
-      if ('loop'     in o) { this.loop     = !!o.loop;     if (!this.loop)     this.bounce = false; }
-      if ('bounce' in o) { this.bounce = !!o.bounce; if (this.bounce)  this.loop     = true;  }
+      if ('loop'   in o) this.loop   = !!o.loop;
+      if ('bounce' in o) this.bounce = !!o.bounce;
       if (typeof o.onPlay === 'function') this.onPlay   = o.onPlay;
       if (typeof o.onEnd  === 'function') this.onEnd    = o.onEnd;
       if (typeof o.onStop === 'function') this.onStop   = o.onStop;
@@ -1525,6 +1787,7 @@ class Track {
     const wasPlaying = this.playing;
     this.playing = true;
     if (!wasPlaying) {
+      this._bounced = false;
       if (typeof this.onPlay === 'function') { try { this.onPlay(this); } catch (_) {} }
       this._onPlay?.();
       this._onActivate?.();
@@ -1541,6 +1804,7 @@ class Track {
     const wasPlaying = this.playing;
     this.playing = false;
     if (wasPlaying) {
+      this._bounced = false;
       if (typeof this.onStop === 'function') { try { this.onStop(this); } catch (_) {} }
       this._onStop?.();
       this._onDeactivate?.();
@@ -1562,7 +1826,7 @@ class Track {
       this._onDeactivate?.();
     }
     this.keyframes.length = 0;
-    this.seg = 0; this.f = 0; this._dir = 1;
+    this.seg = 0; this.f = 0; this._dir = 1; this._bounced = false;
     return this;
   }
 
@@ -1624,7 +1888,7 @@ class Track {
       f:         this.f,
       playing:   this.playing,
       loop:      this.loop,
-      bounce:  this.bounce,
+      bounce:    this.bounce,
       rate:      this._rate,
       duration:  this.duration,
       time:      this.segments > 0 ? this.time() : 0
@@ -1649,7 +1913,8 @@ class Track {
     const s     = _clampS(this.seg * dur + this.f, 0, total);
     const next  = s + this._rate * this._dir;
 
-    if (this.bounce) {
+    // ── loop:true, bounce:true — bounce forever ───────────────────────────
+    if (this.loop && this.bounce) {
       let pos = next, flips = 0;
       while (pos < 0 || pos > total) {
         if (pos < 0) { pos = -pos; flips++; }
@@ -1660,11 +1925,36 @@ class Track {
       return true;
     }
 
+    // ── loop:false, bounce:true — bounce once, stop at origin ────────────
+    if (!this.loop && this.bounce) {
+      if (next >= total) {
+        // far boundary: reflect and flip direction once
+        this._setCursorFromScalar(Math.min(total, 2 * total - next));
+        this._dir = -this._dir;
+        this._bounced = true;
+        return true;
+      }
+      if (next <= 0) {
+        // origin: stop (whether we bounced or started backward)
+        this._setCursorFromScalar(0);
+        this.playing = false;
+        this._dir = 1; this._bounced = false;
+        if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+        this._onEnd?.();
+        this._onDeactivate?.();
+        return false;
+      }
+      this._setCursorFromScalar(next);
+      return true;
+    }
+
+    // ── loop:true, bounce:false — repeat forever ──────────────────────────
     if (this.loop) {
       this._setCursorFromScalar(((next % total) + total) % total);
       return true;
     }
 
+    // ── loop:false, bounce:false — play once, stop at boundary ───────────
     if (next <= 0) {
       this._setCursorFromScalar(0);
       this.playing = false;
@@ -1711,47 +2001,16 @@ class Track {
  * tanOut — outgoing position tangent at this keyframe (Hermite mode).
  * When only one is supplied, the other mirrors it.
  * When neither is supplied, centripetal Catmull-Rom tangents are auto-computed.
- *
- * add() accepts individual specs or a bulk array of specs:
- *
- *   { mMatrix }                           — full TRS from model matrix
- *   { pos?, rot?, scl?, tanIn?, tanOut? } — 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 — Hermite (tanIn/tanOut per keyframe; auto-CR when absent) or linear or step
- *   rot — slerp (rotInterp='slerp') or nlerp or step
- *   scl — lerp
- *
- * @example
- * const track = new PoseTrack()
- * track.add({ pos:[0,0,0] })
- * track.add({ pos:[100,0,0], tanOut:[0,50,0] })   // leave heading +Y
- * track.add({ pos:[200,0,0] })
- * 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.
-     * - 'hermite' — cubic Hermite; uses tanIn/tanOut per keyframe when present,
-     *               auto-computes centripetal Catmull-Rom tangents when absent (default)
+     * - 'hermite' — cubic Hermite; auto-computes centripetal Catmull-Rom tangents
+     *               when none are stored (default)
      * - 'linear'  — lerp
-     * - 'step'    — snap to k0 value; useful for discrete state changes
+     * - 'step'    — snap to k0; useful for discrete state changes
      * @type {'hermite'|'linear'|'step'}
      */
     this.posInterp = 'hermite';
@@ -1836,11 +2095,9 @@ class PoseTrack extends Track {
     } else {
       const p0 = seg > 0      ? this.keyframes[seg - 1].pos : k0.pos;
       const p3 = seg + 2 < n ? this.keyframes[seg + 2].pos  : k1.pos;
-      // tanOut on k0: use stored, else symmetric from tanIn, else auto-CR
       const m0 = k0.tanOut != null ? k0.tanOut
                : k0.tanIn  != null ? k0.tanIn
-               : _crTanOut(_m0, p0, k0.pos, k1.pos, p3);
-      // tanIn on k1: use stored, else symmetric from tanOut, else auto-CR
+               : _crTanOut(_m0, p0, k0.pos, k1.pos);
       const m1 = k1.tanIn  != null ? k1.tanIn
                : k1.tanOut != null ? k1.tanOut
                : _crTanIn(_m1, p0, k0.pos, k1.pos, p3);
@@ -1894,83 +2151,34 @@ class PoseTrack extends Track {
  * interpolation of the eye and center paths respectively.
  * When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
  *
- * 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.
- *
  * 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?, fov?, halfHeight?,
  *     eyeTanIn?, eyeTanOut?, centerTanIn?, centerTanOut? }
- *                         explicit lookat; center defaults to [0,0,0], up to [0,1,0].
- *                         fov and halfHeight are mutually exclusive nullable scalars.
- *   { 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, fov, halfHeight }:
- *   eye        — Hermite (auto-CR when no tangents stored) or linear or step
- *   center     — Hermite (auto-CR when no tangents stored) or linear or step
- *   up         — nlerp (normalize-after-lerp on unit sphere)
- *   fov        — lerp when both keyframes carry non-null fov; else null
- *   halfHeight — lerp when both keyframes carry non-null halfHeight; else null
- *
- * @example
- * const track = new CameraTrack()
- * 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()
- * 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])
+ *
+ * To capture a matrix-based pose, use PoseTrack.add({ mMatrix: eMatrix })
+ * for full-fidelity including roll, or cam.capturePose() for lookat-style.
  */
 class CameraTrack extends Track {
   constructor() {
     super();
     /**
-     * Eye position interpolation mode.
-     * - 'hermite' — cubic Hermite; auto-CR tangents when none stored (default)
-     * - 'linear'  — lerp
-     * - 'step'    — snap to k0 eye
+     * Eye-path interpolation mode.
      * @type {'hermite'|'linear'|'step'}
      */
     this.eyeInterp = 'hermite';
     /**
-     * Center (lookat target) interpolation mode.
-     * 'linear' suits fixed or predictably moving targets (default).
-     * 'hermite' gives smoother paths when center is also flying freely.
-     * - 'hermite' — cubic Hermite; auto-CR tangents when none stored
-     * - 'linear'  — lerp
-     * - 'step'    — snap to k0 center
+     * Center-path interpolation mode.
      * @type {'hermite'|'linear'|'step'}
      */
     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) {
@@ -1988,7 +2196,7 @@ class CameraTrack extends Track {
   }
 
   /**
-   * Replace (or append at end) the keyframe at index.
+   * Replace (or append at end) the camera keyframe at index.
    * @param {number} index
    * @param {Object} spec
    * @returns {boolean}
@@ -2040,7 +2248,7 @@ class CameraTrack extends Track {
       const p3 = seg + 2 < n ? this.keyframes[seg + 2].eye  : k1.eye;
       const m0 = k0.eyeTanOut != null ? k0.eyeTanOut
                : k0.eyeTanIn  != null ? k0.eyeTanIn
-               : _crTanOut(_m0, p0, k0.eye, k1.eye, p3);
+               : _crTanOut(_m0, p0, k0.eye, k1.eye);
       const m1 = k1.eyeTanIn  != null ? k1.eyeTanIn
                : k1.eyeTanOut != null ? k1.eyeTanOut
                : _crTanIn(_m1, p0, k0.eye, k1.eye, p3);
@@ -2050,33 +2258,31 @@ class CameraTrack extends Track {
     // center — Hermite, linear, or step (independent lookat target)
     if (this.centerInterp === 'step') {
       out.center[0]=k0.center[0]; out.center[1]=k0.center[1]; out.center[2]=k0.center[2];
-    } else if (this.centerInterp === 'linear') {
-      lerpVec3(out.center, k0.center, k1.center, t);
-    } else {
+    } else if (this.centerInterp === 'hermite') {
       const c0 = seg > 0      ? this.keyframes[seg - 1].center : k0.center;
       const c3 = seg + 2 < n ? this.keyframes[seg + 2].center  : k1.center;
       const m0 = k0.centerTanOut != null ? k0.centerTanOut
                : k0.centerTanIn  != null ? k0.centerTanIn
-               : _crTanOut(_m0, c0, k0.center, k1.center, c3);
+               : _crTanOut(_m0, c0, k0.center, k1.center);
       const m1 = k1.centerTanIn  != null ? k1.centerTanIn
                : k1.centerTanOut != null ? k1.centerTanOut
                : _crTanIn(_m1, c0, k0.center, k1.center, c3);
       hermiteVec3(out.center, k0.center, m0, k1.center, m1, 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;
+    // up — nlerp on unit sphere
+    lerpVec3(out.up, k0.up, k1.up, t);
+    const ul=Math.sqrt(out.up[0]*out.up[0]+out.up[1]*out.up[1]+out.up[2]*out.up[2])||1;
+    out.up[0]/=ul; out.up[1]/=ul; out.up[2]/=ul;
 
-    // fov — lerp (perspective); null when either keyframe lacks it
-    out.fov        = (k0.fov        !== null && k1.fov        !== null)
-      ? k0.fov        + t * (k1.fov        - k0.fov)        : null;
-    // halfHeight — lerp (ortho); null when either keyframe lacks it
-    out.halfHeight = (k0.halfHeight !== null && k1.halfHeight !== null)
-      ? k0.halfHeight + t * (k1.halfHeight - k0.halfHeight) : null;
+    // fov / halfHeight — lerp when both keyframes carry non-null values
+    out.fov = (k0.fov != null && k1.fov != null)
+      ? k0.fov + t * (k1.fov - k0.fov) : (k0.fov ?? k1.fov ?? null);
+    out.halfHeight = (k0.halfHeight != null && k1.halfHeight != null)
+      ? k0.halfHeight + t * (k1.halfHeight - k0.halfHeight)
+      : (k0.halfHeight ?? k1.halfHeight ?? null);
 
     return out;
   }
@@ -2239,5 +2445,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, applyPickMatrix, boxVisibility, distanceToPlane, frustumPlanes, hermiteVec3, 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 };
+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, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4Eye, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Frustum, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Perspective, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, mat4Transpose, mat4View, 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