@nakednous/tree 0.0.11 → 0.0.13

package/dist/index.js

@@ -238,23 +238,27 @@ const quatToAxisAngle = (q, out) => {
  * 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; mat4LookAt and mat4EyeMatrix 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.
+ * ── NDC Z convention ──────────────────────────────────────────────────────
+ * Controlled by `ndcZMin` in every projection constructor:
+ *   WEBGL  = −1   near → NDC z = −1,  far → NDC z = +1
+ *   WEBGPU =  0   near → NDC z =  0,  far → NDC z = +1
+ *
+ * ── NDC Y convention ──────────────────────────────────────────────────────
+ * Controlled by `ndcYSign` in every projection constructor (default +1):
+ *   +1  NDC y-up   — standard: OpenGL / WebGL / WebGPU browser / Three.js / p5v2
+ *   −1  NDC y-down — native Vulkan clip space
+ *
+ * Negating ndcYSign flips row 1 of the projection matrix (elements
+ * out[1], out[5], out[9], out[13]), reversing the y-axis in clip space.
+ * mat4View, mat4Eye, and all non-projection constructors are convention-
+ * agnostic — they produce the same matrix regardless of the NDC y direction.
+ *
+ * ── Screen Y convention ───────────────────────────────────────────────────
+ * Screen-y direction (DOM y-down vs OpenGL y-up) is a separate concern from
+ * NDC-y direction and is handled in query.js via the signed viewport height.
+ * See the query.js module header for details.
  *
  * All functions follow the out-first, zero-allocation contract.
- * Returns null on degeneracy where applicable.
  */
 
 
@@ -264,8 +268,6 @@ const quatToAxisAngle = (q, out) => {
 
 /**
  * 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.
@@ -273,7 +275,6 @@ const quatToAxisAngle = (q, out) => {
  * @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;
@@ -285,28 +286,22 @@ function mat4FromBasis(out, rx,ry,rz, ux,uy,uz, fx,fy,fz, tx,ty,tz) {
 
 /**
  * View matrix (world→eye) from lookat parameters.
+ * Camera looks along −Z in eye space; right = normalize(up × (−Z)).
  * 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} cx,cy,cz   Look-at target.
  * @param {number} ux,uy,uz   World up hint (need not be unit).
- * @returns {Float32Array|number[]} out
  */
-function mat4LookAt(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
-  // z = normalize(eye - center)  (camera +Z away from target)
+function mat4View(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
   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;
@@ -320,16 +315,14 @@ function mat4LookAt(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
 /**
  * Eye matrix (eye→world) from lookat parameters.
  * Transpose of the rotation block + direct translation column.
- * Same inputs as mat4LookAt.
+ * Same parameters 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
+ * @param {number} ex,ey,ez   Eye position.
+ * @param {number} cx,cy,cz   Look-at target.
+ * @param {number} ux,uy,uz   World up hint.
  */
-function mat4EyeMatrix(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
-  // Same basis computation as mat4LookAt.
+function mat4Eye(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
   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;
@@ -337,7 +330,6 @@ function mat4EyeMatrix(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
   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;
@@ -350,22 +342,20 @@ function mat4EyeMatrix(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
 // =========================================================================
 
 /**
- * Column-major mat4 from flat TRS scalars.
- * No struct allocation — all components passed as plain numbers.
+ * Column-major mat4 from flat TRS scalars. No struct allocation.
  *
  * @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[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;
 }
@@ -374,12 +364,11 @@ function mat4FromTRS(out, tx,ty,tz, qx,qy,qz,qw, sx,sy,sz) {
  * 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[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;
 }
@@ -388,11 +377,10 @@ function mat4FromTranslation(out, tx,ty,tz) {
  * 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[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;
@@ -405,22 +393,19 @@ function mat4FromScale(out, sx,sy,sz) {
 /**
  * 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
+ * @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).
+ * @param {number} [ndcYSign=1]  +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
  */
-function mat4Perspective(out, fov, aspect, near, far, ndcZMin) {
+function mat4Perspective(out, fov, aspect, near, far, ndcZMin, ndcYSign=1) {
   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[0]=f/aspect;       out[1]=0;              out[2]=0;  out[3]=0;
+  out[4]=0;              out[5]=ndcYSign*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;
@@ -432,22 +417,18 @@ function mat4Perspective(out, fov, aspect, near, far, ndcZMin) {
 /**
  * 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
+ * @param {number} ndcZMin               −1 (WEBGL) or 0 (WEBGPU).
+ * @param {number} [ndcYSign=1]          +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
  */
-function mat4Ortho(out, left, right, bottom, top, near, far, ndcZMin) {
+function mat4Ortho(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1) {
   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[0]=2*rl;              out[1]=0;                       out[2]=0;               out[3]=0;
+  out[4]=0;                 out[5]=ndcYSign*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]=ndcYSign*(-(top+bottom)*tb);
   out[14]=(ndcZMin*far-near)*fn;
   out[15]=1;
   return out;
@@ -456,19 +437,17 @@ function mat4Ortho(out, left, right, bottom, top, near, far, ndcZMin) {
 /**
  * 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
+ * @param {number} ndcZMin               −1 (WEBGL) or 0 (WEBGPU).
+ * @param {number} [ndcYSign=1]          +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
  */
-function mat4Frustum(out, left, right, bottom, top, near, far, ndcZMin) {
+function mat4Frustum(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1) {
   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[0]=2*near*rl;        out[1]=0;                          out[2]=0;  out[3]=0;
+  out[4]=0;                out[5]=ndcYSign*2*near*tb;         out[6]=0;  out[7]=0;
+  out[8]=(right+left)*rl;  out[9]=ndcYSign*(top+bottom)*tb;
   out[10]=(ndcZMin*near-far)/(far-near);
   out[11]=-1;
   out[12]=0; out[13]=0;
@@ -482,29 +461,25 @@ function mat4Frustum(out, left, right, bottom, top, near, far, ndcZMin) {
 // =========================================================================
 
 /**
- * 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   ]
+ * Bias matrix: remaps xyz from NDC to texture/UV space [0, 1].
+ * xy remap from [−1, 1]; z remaps from [ndcZMin, 1].
+ * Used to convert light-space NDC coordinates to shadow map UV.
+ *
+ * Convention note: the standard bias maps NDC y = −1 → texture v = 0 and
+ * NDC y = +1 → texture v = 1. This is correct for both NDC y-up and y-down
+ * conventions because the shadow map was rendered with the same projection.
+ *
+ * Column-major (WEBGL, ndcZMin=−1):   Column-major (WEBGPU, ndcZMin=0):
+ *   [ 0.5  0    0    0.5 ]              [ 0.5  0    0    0.5 ]
+ *   [ 0    0.5  0    0.5 ]              [ 0    0.5  0    0.5 ]
+ *   [ 0    0    0.5  0.5 ]              [ 0    0    1    0   ]
+ *   [ 0    0    0    1   ]              [ 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);
+  const sz=1/(1-ndcZMin), 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;
@@ -519,13 +494,12 @@ function mat4Bias(out, ndcZMin) {
  * @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;
+  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;
 }
 
@@ -537,7 +511,6 @@ function mat4Reflect(out, nx,ny,nz,d) {
  * 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];
@@ -545,11 +518,10 @@ function mat4ToTranslation(out3, m) {
 }
 
 /**
- * Extract scale from a column-major mat4 (column lengths of rotation block).
+ * Extract scale from a column-major mat4 (column lengths of the 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]);
@@ -560,11 +532,9 @@ function mat4ToScale(out3, m) {
 
 /**
  * Extract rotation as a unit quaternion from a column-major mat4.
- * Scale is factored out from each column before extraction.
- * Assumes no shear.
+ * Scale is factored out from each column. 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;
@@ -581,28 +551,43 @@ function mat4ToRotation(out4, m) {
  * @module tree/query
  * @license AGPL-3.0-only
  *
- * The operative layer — receives existing matrices and extracts information.
+ * The operative layer — receives 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
- *
- * No dependency on form.js. Operating on matrices requires no knowledge
- * of how they were constructed.
+ *   form.js  — specs  → matrix
+ *   query.js — matrix → information
  *
  * Storage: column-major Float32Array / ArrayLike<number>.
- * Element [col*4 + row] = M[row, col].
- *
  * Multiply: mat4Mul(out, A, B) = A · B  (standard math order).
- *
  * Pipeline: clip = P · V · M · v
- *   P = projection (eye → clip)
- *   V = view       (world → eye)
- *   M = model      (local → world)
  *
- * NDC convention parameter (ndcZMin):
- *   WEBGL  = -1   z ∈ [−1, 1]
- *   WEBGPU =  0   z ∈ [0, 1]
+ * ── NDC Z convention ──────────────────────────────────────────────────────
+ * Passed as `ndcZMin` to every space-transform function:
+ *   WEBGL  = −1   z ∈ [−1,  1]
+ *   WEBGPU =  0   z ∈ [ 0,  1]
+ *
+ * ── NDC Y convention ──────────────────────────────────────────────────────
+ * Standard (OpenGL / WebGL / WebGPU browser / Three.js / p5v2):
+ *   NDC y-up  — y = +1 at top, y = −1 at bottom.
+ * Native Vulkan: NDC y-down — projections constructed with ndcYSign = −1
+ * (see form.js).  Query functions are convention-agnostic: they work on
+ * whatever matrices are passed in.
+ *
+ * ── Viewport convention ───────────────────────────────────────────────────
+ * vp = [x, y, w, h] — w and h are SIGNED.
+ *
+ * The sign of h encodes the relationship between NDC y and screen y:
+ *   h < 0 (e.g. −canvasH): screen y-DOWN  (DOM / p5 mouseX·mouseY / Vulkan surface)
+ *                            NDC y=+1 → screen y=0  (top)
+ *                            NDC y=−1 → screen y=H  (bottom)
+ *   h > 0 (e.g. +canvasH): screen y-UP   (OpenGL desktop / WebGL gl_FragCoord)
+ *                            NDC y=−1 → screen y=0  (bottom)
+ *                            NDC y=+1 → screen y=H  (top)
+ *
+ * Pass [0, canvasH, canvasW, −canvasH] for p5/DOM coordinates.
+ * Pass [0, 0, canvasW, canvasH] for WebGL gl_FragCoord / OpenGL bottom-left.
+ * All helpers use vp[2]/vp[3] signed — no Math.abs — so both conventions
+ * work automatically without any branching.
  *
  * All functions follow the out-first, zero-allocation contract.
  * Returns null on degeneracy (singular matrix, etc.).
@@ -610,10 +595,10 @@ function mat4ToRotation(out4, m) {
 
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Mat4 math
+// Mat4 arithmetic
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** out = A · B  (column-major, standard math order) */
+/** 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],
@@ -642,229 +627,150 @@ function mat4Mul(out, A, B) {
   return out;
 }
 
-/** out = inverse(src).  Returns null if singular. */
+/** out = inverse(src). Returns null if singular (|det| < 1e-12). */
 function mat4Invert(out, src) {
-  const s=src;
-  const a00=s[0],a01=s[1],a02=s[2],a03=s[3],
-        a10=s[4],a11=s[5],a12=s[6],a13=s[7],
-        a20=s[8],a21=s[9],a22=s[10],a23=s[11],
-        a30=s[12],a31=s[13],a32=s[14],a33=s[15];
-  const b00=a00*a11-a01*a10,b01=a00*a12-a02*a10,
-        b02=a00*a13-a03*a10,b03=a01*a12-a02*a11,
-        b04=a01*a13-a03*a11,b05=a02*a13-a03*a12,
-        b06=a20*a31-a21*a30,b07=a20*a32-a22*a30,
-        b08=a20*a33-a23*a30,b09=a21*a32-a22*a31,
-        b10=a21*a33-a23*a31,b11=a22*a33-a23*a32;
-  let det=b00*b11-b01*b10+b02*b09+b03*b08-b04*b07+b05*b06;
+  const s0=src[0],s1=src[1],s2=src[2],s3=src[3],
+        s4=src[4],s5=src[5],s6=src[6],s7=src[7],
+        s8=src[8],s9=src[9],s10=src[10],s11=src[11],
+        s12=src[12],s13=src[13],s14=src[14],s15=src[15];
+  const b0=s0*s5-s1*s4, b1=s0*s6-s2*s4, b2=s0*s7-s3*s4,
+        b3=s1*s6-s2*s5, b4=s1*s7-s3*s5, b5=s2*s7-s3*s6,
+        b6=s8*s13-s9*s12, b7=s8*s14-s10*s12, b8=s8*s15-s11*s12,
+        b9=s9*s14-s10*s13, b10=s9*s15-s11*s13, b11=s10*s15-s11*s14;
+  let det=b0*b11-b1*b10+b2*b9+b3*b8-b4*b7+b5*b6;
   if (Math.abs(det) < 1e-12) return null;
-  det=1/det;
-  out[0]=(a11*b11-a12*b10+a13*b09)*det;
-  out[1]=(a02*b10-a01*b11-a03*b09)*det;
-  out[2]=(a31*b05-a32*b04+a33*b03)*det;
-  out[3]=(a22*b04-a21*b05-a23*b03)*det;
-  out[4]=(a12*b08-a10*b11-a13*b07)*det;
-  out[5]=(a00*b11-a02*b08+a03*b07)*det;
-  out[6]=(a32*b02-a30*b05-a33*b01)*det;
-  out[7]=(a20*b05-a22*b02+a23*b01)*det;
-  out[8]=(a10*b10-a11*b08+a13*b06)*det;
-  out[9]=(a01*b08-a00*b10-a03*b06)*det;
-  out[10]=(a30*b04-a31*b02+a33*b00)*det;
-  out[11]=(a21*b02-a20*b04-a23*b00)*det;
-  out[12]=(a11*b07-a10*b09-a12*b06)*det;
-  out[13]=(a00*b09-a01*b07+a02*b06)*det;
-  out[14]=(a31*b01-a30*b03-a32*b00)*det;
-  out[15]=(a20*b03-a21*b01+a22*b00)*det;
-  return out;
-}
-
-/** out = transpose(src) */
-function mat4Transpose(out, src) {
-  if (out === src) {
-    let t;
-    t=src[1];out[1]=src[4];out[4]=t;
-    t=src[2];out[2]=src[8];out[8]=t;
-    t=src[3];out[3]=src[12];out[12]=t;
-    t=src[6];out[6]=src[9];out[9]=t;
-    t=src[7];out[7]=src[13];out[13]=t;
-    t=src[11];out[11]=src[14];out[14]=t;
-  } else {
-    out[0]=src[0];out[1]=src[4];out[2]=src[8];out[3]=src[12];
-    out[4]=src[1];out[5]=src[5];out[6]=src[9];out[7]=src[13];
-    out[8]=src[2];out[9]=src[6];out[10]=src[10];out[11]=src[14];
-    out[12]=src[3];out[13]=src[7];out[14]=src[11];out[15]=src[15];
-  }
+  det = 1/det;
+  out[0]=(s5*b11-s6*b10+s7*b9)*det;
+  out[1]=(s2*b10-s1*b11-s3*b9)*det;
+  out[2]=(s13*b5-s14*b4+s15*b3)*det;
+  out[3]=(s10*b4-s9*b5-s11*b3)*det;
+  out[4]=(s6*b8-s4*b11-s7*b7)*det;
+  out[5]=(s0*b11-s2*b8+s3*b7)*det;
+  out[6]=(s14*b2-s12*b5-s15*b1)*det;
+  out[7]=(s8*b5-s10*b2+s11*b1)*det;
+  out[8]=(s4*b10-s5*b8+s7*b6)*det;
+  out[9]=(s1*b8-s0*b10-s3*b6)*det;
+  out[10]=(s12*b4-s13*b2+s15*b0)*det;
+  out[11]=(s9*b2-s8*b4-s11*b0)*det;
+  out[12]=(s5*b7-s4*b9-s6*b6)*det;
+  out[13]=(s0*b9-s1*b7+s2*b6)*det;
+  out[14]=(s13*b1-s12*b3-s14*b0)*det;
+  out[15]=(s8*b3-s9*b1+s10*b0)*det;
   return out;
 }
 
-/** out[0..8] = inverseTranspose(upper3×3(src))  (normal matrix) */
+/**
+ * Normal matrix: inverseTranspose(upper-left 3×3 of src).
+ * On degeneracy writes zeros and returns out.
+ * @param {Float32Array|number[]} out  9-element destination.
+ * @param {Float32Array|number[]} src  16-element mat4.
+ */
 function mat3NormalFromMat4(out, src) {
   const a00=src[0],a01=src[1],a02=src[2],
         a10=src[4],a11=src[5],a12=src[6],
         a20=src[8],a21=src[9],a22=src[10];
-  const b01=a22*a11-a12*a21,
-        b11=-a22*a01+a02*a21,
-        b21=a12*a01-a02*a11;
+  const b01=a22*a11-a12*a21, b11=-a22*a01+a02*a21, b21=a12*a01-a02*a11;
   let det=a00*b01+a10*b11+a20*b21;
   if (Math.abs(det) < 1e-12) { for(let i=0;i<9;i++)out[i]=0; return out; }
   det=1/det;
-  out[0]=b01*det;
-  out[1]=(-a22*a10+a12*a20)*det;
-  out[2]=(a21*a10-a11*a20)*det;
-  out[3]=b11*det;
-  out[4]=(a22*a00-a02*a20)*det;
-  out[5]=(-a21*a00+a01*a20)*det;
-  out[6]=b21*det;
-  out[7]=(-a12*a00+a02*a10)*det;
-  out[8]=(a11*a00-a01*a10)*det;
+  out[0]=b01*det;           out[1]=(-a22*a10+a12*a20)*det; out[2]=(a21*a10-a11*a20)*det;
+  out[3]=b11*det;           out[4]=(a22*a00-a02*a20)*det;  out[5]=(-a21*a00+a01*a20)*det;
+  out[6]=b21*det;           out[7]=(-a12*a00+a02*a10)*det; out[8]=(a11*a00-a01*a10)*det;
   return out;
 }
 
-/** out = mat4 * [x,y,z,1], perspective-divides, writes xyz */
+/** out = mat4 * [x,y,z,1], perspective-divides, writes xyz. */
 function mat4MulPoint(out, m, x, y, z) {
-  const rx = m[0]*x + m[4]*y + m[8]*z  + m[12];
-  const ry = m[1]*x + m[5]*y + m[9]*z  + m[13];
-  const rz = m[2]*x + m[6]*y + m[10]*z + m[14];
-  const rw = m[3]*x + m[7]*y + m[11]*z + m[15];
-  if (rw !== 0 && rw !== 1) {
-    out[0] = rx/rw; out[1] = ry/rw; out[2] = rz/rw;
-  } else {
-    out[0] = rx; out[1] = ry; out[2] = rz;
-  }
+  const rx=m[0]*x+m[4]*y+m[8]*z+m[12], ry=m[1]*x+m[5]*y+m[9]*z+m[13],
+        rz=m[2]*x+m[6]*y+m[10]*z+m[14], rw=m[3]*x+m[7]*y+m[11]*z+m[15];
+  if (rw!==0&&rw!==1) { out[0]=rx/rw; out[1]=ry/rw; out[2]=rz/rw; }
+  else                 { out[0]=rx;    out[1]=ry;    out[2]=rz;    }
   return out;
 }
 
 /**
- * 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
+ * Apply only the 3×3 linear block of a mat4 to a direction (no translation,
+ * no perspective divide). Use mat3NormalFromMat4 for normals under non-uniform scale.
  */
 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;
+  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)
+// Projection queries
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** @returns {boolean} true if orthographic */
+/** @returns {boolean} true if orthographic. */
 function projIsOrtho(p) { return p[15] !== 0; }
 
 /**
  * Near plane distance.
- * @param {ArrayLike<number>} p  Projection Mat4.
- * @param {number} ndcZMin  WEBGL (−1) or WEBGPU (0).
+ * @param {ArrayLike<number>} p       Projection mat4.
+ * @param {number}            ndcZMin WEBGL (−1) or WEBGPU (0).
  */
 function projNear(p, ndcZMin) {
-  return p[15] === 0
-    ? p[14] / (p[10] + ndcZMin)
-    : (p[14] - ndcZMin) / p[10];
+  return p[15]===0 ? p[14]/(p[10]+ndcZMin) : (p[14]-ndcZMin)/p[10];
 }
 
-/** Far plane distance (convention-independent: far always maps to NDC z=1). */
+/** Far plane distance (far always maps to NDC z = 1, convention-independent). */
 function projFar(p) {
-  return p[15] === 0
-    ? p[14] / (1 + p[10])
-    : (p[14] - 1) / p[10];
-}
-
-function projLeft(p, ndcZMin) {
-  return p[15] === 1
-    ? -(1 + p[12]) / p[0]
-    : projNear(p, ndcZMin) * (p[8] - 1) / p[0];
+  return p[15]===0 ? p[14]/(1+p[10]) : (p[14]-1)/p[10];
 }
 
-function projRight(p, ndcZMin) {
-  return p[15] === 1
-    ? (1 - p[12]) / p[0]
-    : projNear(p, ndcZMin) * (1 + p[8]) / p[0];
-}
+function projLeft  (p, ndcZMin) { return p[15]===1 ? -(1+p[12])/p[0]  : projNear(p,ndcZMin)*(p[8]-1)/p[0];  }
+function projRight (p, ndcZMin) { return p[15]===1 ?  (1-p[12])/p[0]  : projNear(p,ndcZMin)*(1+p[8])/p[0];  }
+function projTop   (p, ndcZMin) { return p[15]===1 ?  (p[13]-1)/p[5]  : projNear(p,ndcZMin)*(p[9]-1)/p[5];  }
+function projBottom(p, ndcZMin) { return p[15]===1 ?  (1+p[13])/p[5]  : projNear(p,ndcZMin)*(1+p[9])/p[5];  }
 
-function projTop(p, ndcZMin) {
-  return p[15] === 1
-    ? (p[13] - 1) / p[5]
-    : projNear(p, ndcZMin) * (p[9] - 1) / p[5];
-}
-
-function projBottom(p, ndcZMin) {
-  return p[15] === 1
-    ? (1 + p[13]) / p[5]
-    : projNear(p, ndcZMin) * (1 + p[9]) / p[5];
-}
-
-/** Vertical fov (radians, perspective only). */
-function projFov(p) {
-  return Math.abs(2 * Math.atan(1 / p[5]));
-}
-
-/** Horizontal fov (radians, perspective only). */
-function projHfov(p) {
-  return Math.abs(2 * Math.atan(1 / p[0]));
-}
+/** Vertical field of view in radians (perspective only). */
+function projFov (p) { return Math.abs(2*Math.atan(1/p[5])); }
+/** Horizontal field of view in radians (perspective only). */
+function projHfov(p) { return Math.abs(2*Math.atan(1/p[0])); }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Derived matrices (convenience)
+// Derived matrices
 // ═══════════════════════════════════════════════════════════════════════════
 
 /** out = P · V */
-function mat4PV(out, proj, view) { return mat4Mul(out, proj, view); }
-
+function mat4PV(out, proj, view)  { return mat4Mul(out, proj, view); }
 /** out = V · M */
 function mat4MV(out, model, view) { return mat4Mul(out, view, model); }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Location / Direction transforms
+// Frame-relative transforms
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * 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.
+ * Location transform between frames: out = inv(to) · from.
+ * @returns {ArrayLike<number>|null} out, or null if `to` is singular.
  */
 function mat4Location(out, from, to) {
   return mat4Invert(out, to) && mat4Mul(out, out, from);
 }
 
 /**
- * Relative transform for directions (vectors): out = to₃ · inv(from₃).
- * Uses only the upper-left 3×3 blocks, ignoring translation.
- * @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.
+ * Direction transform between frames: out = to₃ · inv(from₃).
+ * Uses only the upper-left 3×3 blocks (rotation/scale, no translation).
+ * @returns {ArrayLike<number>|null} out, or null if `from` is singular.
  */
 function mat3Direction(out, from, to) {
-  const a00=from[0], a01=from[1], a02=from[2],
-        a10=from[4], a11=from[5], a12=from[6],
-        a20=from[8], a21=from[9], a22=from[10];
-  const b01=a22*a11-a12*a21,
-        b11=a12*a20-a22*a10,
-        b21=a21*a10-a11*a20;
+  const a00=from[0],a01=from[1],a02=from[2],
+        a10=from[4],a11=from[5],a12=from[6],
+        a20=from[8],a21=from[9],a22=from[10];
+  const b01=a22*a11-a12*a21, b11=a12*a20-a22*a10, b21=a21*a10-a11*a20;
   let det=a00*b01+a01*b11+a02*b21;
   if (Math.abs(det) < 1e-12) return null;
   det=1/det;
-  const i00=b01*det, 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, 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;
+  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];
+  out[0]=t00*i00+t10*i01+t20*i02; out[1]=t01*i00+t11*i01+t21*i02; out[2]=t02*i00+t12*i01+t22*i02;
+  out[3]=t00*i10+t10*i11+t20*i12; out[4]=t01*i10+t11*i11+t21*i12; out[5]=t02*i10+t12*i11+t22*i12;
+  out[6]=t00*i20+t10*i21+t20*i22; out[7]=t01*i20+t11*i21+t21*i22; out[8]=t02*i20+t12*i21+t22*i22;
   return out;
 }
 
@@ -872,215 +778,177 @@ function mat3Direction(out, from, to) {
 // 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).
+// Flat dispatch: every from→to pair is a self-contained leaf with only stack
+// locals — no reentrancy, no shared state between calls.
 //
-// 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)
-//   }
+// Matrices bag `m`:
+//   mat4Proj    Float32Array(16)  projection  (eye → clip)
+//   mat4View    Float32Array(16)  view        (world → eye)
+//   mat4Eye?    Float32Array(16)  eye         (eye → world); caller fills before passing
+//   mat4PV?     Float32Array(16)  P · V;      caller fills or _ensurePV allocates once
+//   mat4PVInv?  Float32Array(16)  inv(P · V); caller fills
+//   fromFrame?  Float32Array(16)  MATRIX source frame
+//   toFrameInv? Float32Array(16)  inv(MATRIX dest frame)
+//
+// Viewport `vp` = [x, y, w, h]:
+//   Use SIGNED h to encode screen-y direction (see module header).
+//   Core formula: screen = (ndc*0.5+0.5)*vp[k] + vp[k-2]  (k=2 for x, k=3 for y)
+//   Inverse:      ndc    = ((screen-vp[k-2])/vp[k])*2 - 1
+//   Negative vp[3] flips NDC y-up to screen y-down automatically.
 //
 
-// ── Location leaf helpers ────────────────────────────────────────────────
+// ── Location helpers ─────────────────────────────────────────────────────
 
 function _worldToScreen(out, px, py, pz, pv, vp, ndcZMin) {
-  const x = pv[0]*px+pv[4]*py+pv[8]*pz+pv[12];
-  const y = pv[1]*px+pv[5]*py+pv[9]*pz+pv[13];
-  const z = pv[2]*px+pv[6]*py+pv[10]*pz+pv[14];
-  const w = pv[3]*px+pv[7]*py+pv[11]*pz+pv[15];
-  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);
+  const x=pv[0]*px+pv[4]*py+pv[8]*pz+pv[12], y=pv[1]*px+pv[5]*py+pv[9]*pz+pv[13],
+        z=pv[2]*px+pv[6]*py+pv[10]*pz+pv[14], 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*0.5+0.5)*vp[2]+vp[0];
+  out[1]=(y*xi*0.5+0.5)*vp[3]+vp[1];
+  out[2]=(z*xi-ndcZMin)/(1-ndcZMin);
   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);
+  return mat4MulPoint(out, ipv,
+    ((sx-vp[0])/vp[2])*2-1,
+    ((sy-vp[1])/vp[3])*2-1,
+    sz*(1-ndcZMin)+ndcZMin);
 }
 
 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];
-  const xi = (w !== 0 && w !== 1) ? 1/w : 1;
+  const x=pv[0]*px+pv[4]*py+pv[8]*pz+pv[12], y=pv[1]*px+pv[5]*py+pv[9]*pz+pv[13],
+        z=pv[2]*px+pv[6]*py+pv[10]*pz+pv[14], 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, nx, ny, nz, ipv) {
-  return mat4MulPoint(out, ipv, nx, ny, nz);
-}
+function _ndcToWorld(out, nx, ny, nz, ipv) { return mat4MulPoint(out,ipv,nx,ny,nz); }
 
 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;
+  out[0]=((sx-vp[0])/vp[2])*2-1;
+  out[1]=((sy-vp[1])/vp[3])*2-1;
+  out[2]=sz*(1-ndcZMin)+ndcZMin;
   return out;
 }
 
 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);
+  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)/(1-ndcZMin);
   return out;
 }
 
 function _ensurePV(m) {
-  if (m.pvMatrix) return m.pvMatrix;
-  m.pvMatrix = new Float32Array(16);
-  mat4Mul(m.pvMatrix, m.pMatrix, m.vMatrix);
-  return m.pvMatrix;
+  if (m.mat4PV) return m.mat4PV;
+  m.mat4PV = new Float32Array(16);
+  mat4Mul(m.mat4PV, m.mat4Proj, m.mat4View);
+  return m.mat4PV;
 }
 
 /**
  * Map a point between named coordinate spaces.
  *
- * @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).
+ * @param {number[]} out     3-element destination — written and returned.
+ * @param {number}   px,py,pz Input point.
+ * @param {string}   from    Source space (WORLD, EYE, SCREEN, NDC, MATRIX).
+ * @param {string}   to      Destination space.
+ * @param {object}   m       Matrices bag — see module header.
+ * @param {number[]} vp      Viewport [x, y, w, h]; sign of h encodes screen-y direction.
+ * @param {number}   ndcZMin WEBGL (−1) or WEBGPU (0).
+ * @returns {number[]} out
  */
 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.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.ipvMatrix);
-
-  // SCREEN ↔ NDC
-  if (from === SCREEN && to === NDC)
-    return _screenToNDC(out, px,py,pz, vp, ndcZMin);
-  if (from === NDC && to === SCREEN)
-    return _ndcToScreen(out, px,py,pz, vp, ndcZMin);
-
-  // WORLD ↔ EYE
-  if (from === WORLD && to === EYE)
-    return mat4MulPoint(out, m.vMatrix, px,py,pz);
-  if (from === EYE && to === WORLD)
-    return mat4MulPoint(out, m.eMatrix, px,py,pz);
-
-  // EYE ↔ SCREEN
-  if (from === EYE && to === SCREEN) {
-    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===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.mat4PVInv,vp,ndcZMin);
+
+  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.mat4PVInv);
+
+  if (from===SCREEN && to===NDC)    return _screenToNDC(out,px,py,pz,vp,ndcZMin);
+  if (from===NDC    && to===SCREEN) return _ndcToScreen(out,px,py,pz,vp,ndcZMin);
+
+  if (from===WORLD && to===EYE) return mat4MulPoint(out,m.mat4View,px,py,pz);
+  if (from===EYE && to===WORLD) return mat4MulPoint(out,m.mat4Eye,px,py,pz);
+
+  if (from===EYE && to===SCREEN) {
+    const e=m.mat4Eye;
+    return _worldToScreen(out,e[0]*px+e[4]*py+e[8]*pz+e[12],
+                              e[1]*px+e[5]*py+e[9]*pz+e[13],
+                              e[2]*px+e[6]*py+e[10]*pz+e[14],_ensurePV(m),vp,ndcZMin);
   }
-  if (from === SCREEN && to === EYE) {
-    _screenToWorld(out, px,py,pz, m.ipvMatrix, vp, ndcZMin);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return mat4MulPoint(out, m.vMatrix, wx,wy,wz);
+  if (from===SCREEN && to===EYE) {
+    _screenToWorld(out,px,py,pz,m.mat4PVInv,vp,ndcZMin);
+    return mat4MulPoint(out,m.mat4View,out[0],out[1],out[2]);
   }
 
-  // EYE ↔ NDC
-  if (from === EYE && to === NDC) {
-    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===EYE && to===NDC) {
+    const e=m.mat4Eye;
+    return _worldToNDC(out,e[0]*px+e[4]*py+e[8]*pz+e[12],
+                           e[1]*px+e[5]*py+e[9]*pz+e[13],
+                           e[2]*px+e[6]*py+e[10]*pz+e[14],_ensurePV(m));
   }
-  if (from === NDC && to === EYE) {
-    _ndcToWorld(out, px,py,pz, m.ipvMatrix);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return mat4MulPoint(out, m.vMatrix, wx,wy,wz);
+  if (from===NDC && to===EYE) {
+    _ndcToWorld(out,px,py,pz,m.mat4PVInv);
+    return mat4MulPoint(out,m.mat4View,out[0],out[1],out[2]);
   }
 
-  // MATRIX (custom frame) ↔ WORLD
-  if (from === MATRIX && to === WORLD)
-    return mat4MulPoint(out, m.fromFrame, px,py,pz);
-  if (from === WORLD && to === MATRIX)
-    return mat4MulPoint(out, m.toFrameInv, px,py,pz);
-
-  // MATRIX ↔ EYE
-  if (from === MATRIX && to === EYE) {
-    const 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===MATRIX && to===WORLD) return mat4MulPoint(out,m.fromFrame,px,py,pz);
+  if (from===WORLD && to===MATRIX) return mat4MulPoint(out,m.toFrameInv,px,py,pz);
+
+  if (from===MATRIX && to===EYE) {
+    const f=m.fromFrame;
+    return mat4MulPoint(out,m.mat4View,f[0]*px+f[4]*py+f[8]*pz+f[12],
+                                       f[1]*px+f[5]*py+f[9]*pz+f[13],
+                                       f[2]*px+f[6]*py+f[10]*pz+f[14]);
   }
-  if (from === EYE && to === MATRIX) {
-    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);
+  if (from===EYE && to===MATRIX) {
+    const e=m.mat4Eye;
+    return mat4MulPoint(out,m.toFrameInv,e[0]*px+e[4]*py+e[8]*pz+e[12],
+                                         e[1]*px+e[5]*py+e[9]*pz+e[13],
+                                         e[2]*px+e[6]*py+e[10]*pz+e[14]);
   }
 
-  // MATRIX ↔ SCREEN
-  if (from === MATRIX && to === SCREEN) {
-    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===MATRIX && to===SCREEN) {
+    const f=m.fromFrame;
+    return _worldToScreen(out,f[0]*px+f[4]*py+f[8]*pz+f[12],
+                              f[1]*px+f[5]*py+f[9]*pz+f[13],
+                              f[2]*px+f[6]*py+f[10]*pz+f[14],_ensurePV(m),vp,ndcZMin);
   }
-  if (from === SCREEN && to === MATRIX) {
-    _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);
+  if (from===SCREEN && to===MATRIX) {
+    _screenToWorld(out,px,py,pz,m.mat4PVInv,vp,ndcZMin);
+    return mat4MulPoint(out,m.toFrameInv,out[0],out[1],out[2]);
   }
 
-  // MATRIX ↔ NDC
-  if (from === MATRIX && to === NDC) {
-    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===MATRIX && to===NDC) {
+    const f=m.fromFrame;
+    return _worldToNDC(out,f[0]*px+f[4]*py+f[8]*pz+f[12],
+                           f[1]*px+f[5]*py+f[9]*pz+f[13],
+                           f[2]*px+f[6]*py+f[10]*pz+f[14],_ensurePV(m));
   }
-  if (from === NDC && to === MATRIX) {
-    _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);
+  if (from===NDC && to===MATRIX) {
+    _ndcToWorld(out,px,py,pz,m.mat4PVInv);
+    return mat4MulPoint(out,m.toFrameInv,out[0],out[1],out[2]);
   }
 
-  // MATRIX ↔ MATRIX
-  if (from === MATRIX && to === MATRIX) {
-    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);
+  if (from===MATRIX && to===MATRIX) {
+    const f=m.fromFrame;
+    return mat4MulPoint(out,m.toFrameInv,f[0]*px+f[4]*py+f[8]*pz+f[12],
+                                         f[1]*px+f[5]*py+f[9]*pz+f[13],
+                                         f[2]*px+f[6]*py+f[10]*pz+f[14]);
   }
 
-  // Fallback
   out[0]=px; out[1]=py; out[2]=pz;
   return out;
 }
 
-// ── Direction leaf helpers ───────────────────────────────────────────────
+// ── Direction helpers ────────────────────────────────────────────────────
+//
+// Directions use only the linear 3×3 block — no translation, no w-divide.
+// The signed vp[2]/vp[3] carries the y-convention automatically.
+//
 
-/** Apply the 3×3 linear part of a mat4 (rotation/scale, no translation). */
 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;
@@ -1089,157 +957,123 @@ function _applyDir(out, m, dx, dy, dz) {
 }
 
 function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
-  // 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;
+  const vx=view[0]*dx+view[4]*dy+view[8]*dz,
+        vy=view[1]*dx+view[5]*dy+view[9]*dz,
+        vz=view[2]*dx+view[6]*dy+view[10]*dz;
+  // vpH is signed — negative flips y component automatically.
+  out[0]=(proj[0]*vx+proj[4]*vy+proj[8]*vz)*vpW*0.5;
+  out[1]=(proj[1]*vx+proj[5]*vy+proj[9]*vz)*vpH*0.5;
+  out[2]=(proj[2]*vx+proj[6]*vy+proj[10]*vz)*(1-ndcZMin)*0.5;
   return out;
 }
 
-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);
+function _screenToWorldDir(out, dx, dy, dz, proj, eye, vpW, vpH, ndcZMin) {
+  // Inverse of _worldToScreenDir; signed vpW/vpH cancel the y-flip.
+  _applyDir(out, eye, dx/(vpW*0.5)/proj[0], dy/(vpH*0.5)/proj[5], dz/((1-ndcZMin)*0.5));
   return out;
 }
 
 function _screenToNDCDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
-  out[0]=dx/(vpW*0.5); out[1]=-dy/(vpH*0.5);
-  out[2]=dz/((1-ndcZMin)*0.5);
+  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) {
-  out[0]=dx*vpW*0.5; out[1]=-dy*vpH*0.5;
-  out[2]=dz*(1-ndcZMin)*0.5;
+  out[0]=dx*vpW*0.5; out[1]=dy*vpH*0.5; out[2]=dz*(1-ndcZMin)*0.5;
   return out;
 }
 
 /**
  * Map a direction between named coordinate spaces.
- * Same bag contract as mapLocation.
+ * Same bag and viewport contract as mapLocation.
+ *
+ * @param {number[]} out     3-element destination.
+ * @param {number}   dx,dy,dz Input direction.
+ * @param {string}   from    Source space.
+ * @param {string}   to      Destination space.
+ * @param {object}   m       Matrices bag — see module header.
+ * @param {number[]} vp      Viewport [x, y, w, h]; sign of h encodes screen-y direction.
+ * @param {number}   ndcZMin WEBGL (−1) or WEBGPU (0).
+ * @returns {number[]} out
  */
 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)
-  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.pMatrix, m.vMatrix, vpW, vpH, ndcZMin);
-  if (from === SCREEN && to === WORLD)
-    return _screenToWorldDir(out, dx,dy,dz, m.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
-
-  // SCREEN ↔ NDC
-  if (from === SCREEN && to === NDC)
-    return _screenToNDCDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
-  if (from === NDC && to === SCREEN)
-    return _ndcToScreenDir(out, dx,dy,dz, vpW, vpH, ndcZMin);
-
-  // WORLD ↔ NDC
-  if (from === WORLD && to === NDC) {
-    _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);
+  const vpW=vp[2], vpH=vp[3];  // signed — carry y-convention through all helpers
+
+  if (from===EYE   && to===WORLD)  return _applyDir(out,m.mat4Eye, dx,dy,dz);
+  if (from===WORLD && to===EYE)    return _applyDir(out,m.mat4View,dx,dy,dz);
+
+  if (from===WORLD  && to===SCREEN) return _worldToScreenDir(out,dx,dy,dz,m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+  if (from===SCREEN && to===WORLD)  return _screenToWorldDir(out,dx,dy,dz,m.mat4Proj,m.mat4Eye, vpW,vpH,ndcZMin);
+
+  if (from===SCREEN && to===NDC)    return _screenToNDCDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+  if (from===NDC    && to===SCREEN) return _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+
+  if (from===WORLD && to===NDC) {
+    _worldToScreenDir(out,dx,dy,dz,m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+    return _screenToNDCDir(out,out[0],out[1],out[2],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.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
+  if (from===NDC && to===WORLD) {
+    _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+    return _screenToWorldDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
   }
 
-  // EYE ↔ SCREEN
-  if (from === EYE && to === SCREEN) {
-    _applyDir(out, m.eMatrix, dx,dy,dz);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return _worldToScreenDir(out, wx,wy,wz, m.pMatrix, m.vMatrix, vpW, vpH, ndcZMin);
+  if (from===EYE && to===SCREEN) {
+    _applyDir(out,m.mat4Eye,dx,dy,dz);
+    return _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
   }
-  if (from === SCREEN && to === EYE) {
-    _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);
+  if (from===SCREEN && to===EYE) {
+    _screenToWorldDir(out,dx,dy,dz,m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.mat4View,out[0],out[1],out[2]);
   }
 
-  // EYE ↔ NDC
-  if (from === EYE && to === NDC) {
-    _applyDir(out, m.eMatrix, dx,dy,dz);
-    const wx=out[0],wy=out[1],wz=out[2];
-    _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===EYE && to===NDC) {
+    _applyDir(out,m.mat4Eye,dx,dy,dz);
+    _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+    return _screenToNDCDir(out,out[0],out[1],out[2],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.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return _applyDir(out, m.vMatrix, wx,wy,wz);
+  if (from===NDC && to===EYE) {
+    _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+    _screenToWorldDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.mat4View,out[0],out[1],out[2]);
   }
 
-  // MATRIX ↔ WORLD
-  if (from === MATRIX && to === WORLD) return _applyDir(out, m.fromFrame, dx,dy,dz);
-  if (from === WORLD && to === MATRIX) return _applyDir(out, m.toFrameInv, dx,dy,dz);
+  if (from===MATRIX && to===WORLD)  return _applyDir(out,m.fromFrame, dx,dy,dz);
+  if (from===WORLD  && to===MATRIX) return _applyDir(out,m.toFrameInv,dx,dy,dz);
 
-  // MATRIX ↔ EYE
-  if (from === MATRIX && to === EYE) {
-    _applyDir(out, m.fromFrame, dx,dy,dz);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return _applyDir(out, m.vMatrix, wx,wy,wz);
+  if (from===MATRIX && to===EYE) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    return _applyDir(out,m.mat4View,out[0],out[1],out[2]);
   }
-  if (from === EYE && to === MATRIX) {
-    _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);
+  if (from===EYE && to===MATRIX) {
+    _applyDir(out,m.mat4Eye,dx,dy,dz);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
   }
 
-  // MATRIX ↔ SCREEN
-  if (from === MATRIX && to === SCREEN) {
-    _applyDir(out, m.fromFrame, dx,dy,dz);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return _worldToScreenDir(out, wx,wy,wz, m.pMatrix, m.vMatrix, vpW, vpH, ndcZMin);
+  if (from===MATRIX && to===SCREEN) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    return _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
   }
-  if (from === SCREEN && to === MATRIX) {
-    _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);
+  if (from===SCREEN && to===MATRIX) {
+    _screenToWorldDir(out,dx,dy,dz,m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
   }
 
-  // MATRIX ↔ NDC
-  if (from === MATRIX && to === NDC) {
-    _applyDir(out, m.fromFrame, dx,dy,dz);
-    const wx=out[0],wy=out[1],wz=out[2];
-    _worldToScreenDir(out, wx,wy,wz, m.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===MATRIX && to===NDC) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+    return _screenToNDCDir(out,out[0],out[1],out[2],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.pMatrix, m.eMatrix, vpW, vpH, ndcZMin);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return _applyDir(out, m.toFrameInv, wx,wy,wz);
+  if (from===NDC && to===MATRIX) {
+    _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+    _screenToWorldDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
   }
 
-  // MATRIX ↔ MATRIX
-  if (from === MATRIX && to === MATRIX) {
-    _applyDir(out, m.fromFrame, dx,dy,dz);
-    const wx=out[0],wy=out[1],wz=out[2];
-    return _applyDir(out, m.toFrameInv, wx,wy,wz);
+  if (from===MATRIX && to===MATRIX) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
   }
 
-  // Fallback
   out[0]=dx; out[1]=dy; out[2]=dz;
   return out;
 }
@@ -1250,16 +1084,15 @@ 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 {number} vpH      Viewport height (pixels).
- * @param {number} eyeZ     Eye-space Z (negative for in-front-of camera).
- * @param {number} ndcZMin  WEBGL or WEBGPU.
+ * @param {ArrayLike<number>} proj    Projection mat4.
+ * @param {number}            vpH     Viewport height in pixels (positive).
+ * @param {number}            eyeZ    Eye-space Z — negative means in front of camera.
+ * @param {number}            ndcZMin WEBGL (−1) or WEBGPU (0).
  */
 function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
-  if (projIsOrtho(proj)) {
-    return Math.abs(projTop(proj, ndcZMin) - projBottom(proj, ndcZMin)) / vpH;
-  }
-  return 2 * Math.abs(eyeZ) * Math.tan(projFov(proj) / 2) / vpH;
+  return projIsOrtho(proj)
+    ? Math.abs(projTop(proj,ndcZMin)-projBottom(proj,ndcZMin)) / vpH
+    : 2*Math.abs(eyeZ)*Math.tan(projFov(proj)/2) / vpH;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1267,40 +1100,35 @@ function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Apply the pick-matrix in-place:  proj ← M_pick · proj
+ * Mutate a projection matrix in-place so that the pixel at (px, py) maps to
+ * the full NDC square — making a 1×1 FBO render contain exactly that pixel.
+ *
+ * Premultiplies by M_pick (column-major, rows 2 and 3 unchanged):
  *
- * Zooms the frustum so that pixel (px, py) maps to the full NDC square,
- * making a 1×1 framebuffer render contain exactly that pixel's content.
- * Convention-independent — correct for both perspective and orthographic.
+ *   ┌  sx   0   0   tx ┐     sx = |vp[2]|,   sy = |vp[3]|
+ *   │   0  sy   0   ty │     cx = ((px−vp[0])/vp[2])·2 − 1   (NDC x of pixel centre)
+ *   │   0   0   1    0 │     cy = ((py−vp[1])/vp[3])·2 − 1   (NDC y, sign-aware)
+ *   └   0   0   0    1 ┘     tx = −cx·sx,  ty = −cy·sy
  *
- * M_pick (column-major):
- *   [ sx   0   0   tx ]     sx = W,  sy = H
- *   [  0  sy   0   ty ]     cx = NDC X of pixel centre =  2*(px+0.5)/W − 1
- *   [  0   0   1    0 ]     cy = NDC Y of pixel centre =  1 − 2*(py+0.5)/H
- *   [  0   0   0    1 ]     tx = −cx·W,  ty = −cy·H
+ * Result: P_pick = M_pick · P_original.
+ * The viewport sign convention (vp[3] < 0 for screen y-down) is preserved
+ * automatically through cx/cy — no separate flip needed.
  *
  * @param {Float32Array} proj  Projection mat4 — mutated in place.
- * @param {number} px  Query X (CSS pixels).
- * @param {number} py  Query Y (CSS pixels).
- * @param {number} W   Canvas width  (CSS pixels).
- * @param {number} H   Canvas height (CSS pixels).
- * @returns {Float32Array} proj (same reference)
+ * @param {number} px  Query pixel X in screen coordinates.
+ * @param {number} py  Query pixel Y in screen coordinates.
+ * @param {number[]} vp  Viewport [x, y, w, h]; same signed convention as mapLocation.
  */
-function mat4Pick(proj, px, py, W, H) {
-  const cx =  2 * (px + 0.5) / W - 1;
-  const cy = -2 * (py + 0.5) / H + 1;
-  const sx = W;
-  const sy = H;
-  const tx = -cx * W;
-  const ty = -cy * H;
-  for (let j = 0; j < 4; j++) {
-    const a = proj[j * 4];
-    const b = proj[j * 4 + 1];
-    const d = proj[j * 4 + 3];
-    proj[j * 4]     = sx * a + tx * d;
-    proj[j * 4 + 1] = sy * b + ty * d;
+function mat4Pick(proj, px, py, vp) {
+  const cx=((px-vp[0])/vp[2])*2-1;
+  const cy=((py-vp[1])/vp[3])*2-1;
+  const sx=Math.abs(vp[2]), sy=Math.abs(vp[3]);
+  const tx=-cx*sx, ty=-cy*sy;
+  for (let j=0; j<4; j++) {
+    const a=proj[j*4], b=proj[j*4+1], d=proj[j*4+3];
+    proj[j*4]   = sx*a + tx*d;
+    proj[j*4+1] = sy*b + ty*d;
   }
-  return proj;
 }
 
 /**
@@ -2445,5 +2273,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, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4EyeMatrix, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Frustum, mat4Invert, mat4Location, mat4LookAt, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Perspective, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, 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, 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