bridge: move out into opts on mapLocation / mapDirection

mapLocation(point?, opts?) and mapDirection(dir?, opts?) no longer take
out as a positional first argument. opts.out accepts the same types as
before (Float32Array | ArrayLike | p5.Vector). When opts.out is absent
a fresh p5.Vector is allocated and returned, giving an ergonomic
non-hot-path call style with no ambiguity.

Internal callers in gizmos.js and picking.js updated: _sl and _wl
scratch buffers are now passed as opts.out, preserving zero-alloc.

_resolveOut(opts) extracted as a shared one-liner inside installMatrix.

Author: nakednous

README.md

@@ -244,31 +244,31 @@ Accepted types for `out` and override params: `Float32Array` | `ArrayLike` | `p5
 **Simple queries** — read from live renderer state:
 
 ```js
-eMatrix(out)   // eye matrix (inverse view) — eye→world
-pMatrix(out)   // projection matrix
-vMatrix(out)   // view matrix — world→eye
-mMatrix(out)   // model matrix — local→world
+mat4Eye(out)    // eye matrix (inverse view) — eye→world
+mat4Proj(out)   // projection matrix
+mat4View(out)   // view matrix — world→eye
+mat4Model(out)  // model matrix — local→world
 ```
 
 **Composite queries** — `out` first, optional overrides in an opts object:
 
 ```js
-pvMatrix(out,  [{ pMatrix, vMatrix }])
-ipvMatrix(out, [{ pMatrix, vMatrix, pvMatrix }])
-mvMatrix(out,  [{ mMatrix, vMatrix }])
-pmvMatrix(out, [{ pMatrix, mMatrix, vMatrix }])
-nMatrix(out,   [{ mMatrix, vMatrix, mvMatrix }])  // 9-element out
+mat4PV(out,    [{ mat4Proj, mat4View }])
+mat4PVInv(out, [{ mat4Proj, mat4View, mat4PV }])
+mat4MV(out,    [{ mat4Model, mat4View }])
+mat4PMV(out,   [{ mat4Proj, mat4Model, mat4View }])
+mat3Normal(out,[{ mat4Model, mat4View, mat4MV }])  // 9-element out
 mat4Location(out, from, to)   // location transform: inv(to) · from
 mat3Direction(out, from, to)  // direction transform: to₃ · inv(from₃), 9-element out
 ```
 
 **Raw matrix math** — forwarded from `@nakednous/tree`, same out-first contract:
 
 ```js
-mat4Mul(out, A, B)          // out = A · B  (column-major)
-mat4Invert(out, src)        // out = inv(src), null if singular
-mat4MulPoint(out, m, point) // out = m · [x,y,z,1] perspective-divided
-                            // point: Float32Array | ArrayLike | p5.Vector
+mat4Mul(out, A, B)           // out = A · B  (column-major)
+mat4Invert(out, src)         // out = inv(src), null if singular
+mat4MulPoint(out, m, point)  // out = m · [x,y,z,1] perspective-divided
+                             // point: Float32Array | ArrayLike | p5.Vector
 mat4MulDir(out, m, dx,dy,dz) // out = 3×3 block of m applied to direction
                              // no translation, no perspective divide
 ```
@@ -284,62 +284,71 @@ const wlm = new Float32Array(16)   // e.g. bias · lightPV for shadow mapping
 const pt  = new Float32Array(3)
 
 // draw — zero allocations
-eMatrix(e)
-pMatrix(pm)
-pvMatrix(pv)
+mat4Eye(e)
+mat4Proj(pm)
+mat4PV(pv)
 mat4Mul(wlm, biasMatrix, pv)
 mat4MulPoint(pt, wlm, lightPosition)
-viewFrustum({ eMatrix: e, pMatrix: pm })
-mouseHit({ pvMatrix: pv, eMatrix: e })
+viewFrustum({ mat4Eye: e, mat4Proj: pm })
+mouseHit({ mat4PV: pv, mat4Eye: e })
 ```
 
 ## Frustum queries
 
 Scalars read directly from the projection matrix — no buffer needed:
 
 ```js
-lPlane()   rPlane()   bPlane()   tPlane()   // side planes
-nPlane()   fPlane()                          // near / far
-fov()      hfov()                            // field of view (radians)
-isOrtho()                                    // true for orthographic
+projLeft()   projRight()   projBottom()   projTop()   // side planes
+projNear()   projFar()                                // near / far
+projFov()    projHfov()                               // field of view (radians)
+projIsOrtho()                                         // true for orthographic
 
-pixelRatio([worldPos], [{ pMatrix, vMatrix }])
+pixelRatio([worldPos], [{ mat4Proj, mat4View }])
 // world-units-per-pixel at worldPos (defaults to camera position)
 ```
 
 ## Coordinate space conversions
 
+`out` is opt-in. When provided via `opts.out` the result is written into it (zero-alloc hot path). When omitted a fresh `p5.Vector` is allocated and returned. Return type matches `opts.out`.
+
 ```js
-mapLocation(out, point, [opts])   // map a point between spaces
-mapLocation(out, [opts])          // input defaults to p5.Tree.ORIGIN
-mapLocation(out)                  // defaults to ORIGIN, EYE → WORLD
+mapLocation([point], [opts])   // map a point between spaces
+mapLocation([opts])            // input defaults to p5.Tree.ORIGIN
+mapLocation()                  // ORIGIN, EYE → WORLD → p5.Vector
 
-mapDirection(out, vector, [opts]) // map a direction between spaces
-mapDirection(out, [opts])         // input defaults to p5.Tree._k
-mapDirection(out)                 // defaults to _k, EYE → WORLD
+mapDirection([dir], [opts])    // map a direction between spaces
+mapDirection([opts])           // input defaults to p5.Tree._k
+mapDirection()                 // _k, EYE → WORLD → p5.Vector
 ```
 
-`out` is a 3-element `Float32Array`, `ArrayLike`, or `p5.Vector`.
+`point` / `dir` accept `Float32Array` | `ArrayLike` | `p5.Vector`.
 
-| Option      | Default           | Description                             |
-|-------------|-------------------|-----------------------------------------|
-| `from`      | `p5.Tree.EYE`     | Source space (constant or matrix).      |
-| `to`        | `p5.Tree.WORLD`   | Target space (constant or matrix).      |
-| `eMatrix`   | current eye       | Pre-computed eye matrix.                |
-| `pMatrix`   | current proj      | Override projection matrix.             |
-| `vMatrix`   | current view      | Override view matrix.                   |
-| `pvMatrix`  | P·V               | Pre-computed PV — skips multiply.       |
-| `ipvMatrix` | inv(PV)           | Pre-computed IPV — skips inversion.     |
+| Option       | Default           | Description                                     |
+|--------------|-------------------|-------------------------------------------------|
+| `out`        | new p5.Vector()   | Destination buffer — omit to allocate p5.Vector.|
+| `from`       | `p5.Tree.EYE`     | Source space (constant or matrix).              |
+| `to`         | `p5.Tree.WORLD`   | Target space (constant or matrix).              |
+| `mat4Eye`    | current eye       | Pre-computed eye matrix.                        |
+| `mat4Proj`   | current proj      | Override projection matrix.                     |
+| `mat4View`   | current view      | Override view matrix.                           |
+| `mat4PV`     | P·V               | Pre-computed PV — skips multiply.               |
+| `mat4PVInv`  | inv(PV)           | Pre-computed IPV — skips inversion.             |
 
 `from` / `to` accept: `p5.Tree.WORLD`, `EYE`, `SCREEN`, `NDC`, `MODEL`, or a mat4 for a custom local frame.
 
 ```js
-const loc = new Float32Array(3)
-const dir = new Float32Array(3)
+// ergonomic — allocates p5.Vector
+const eye = mapLocation()                                      // camera world position
+const fwd = mapDirection()                                     // camera look direction
+const scr = mapLocation([100,0,0], { from: p5.Tree.WORLD,
+                                     to:   p5.Tree.SCREEN })
 
-mapLocation(loc)                                                    // camera world position
-mapDirection(dir)                                                   // camera view direction
-mapLocation(loc, [100,0,0], { from: p5.Tree.WORLD, to: p5.Tree.SCREEN })
+// hot path — zero allocation
+const loc = new Float32Array(3)
+const pv  = new Float32Array(16)
+mat4PV(pv)
+mapLocation([100,0,0], { from: p5.Tree.WORLD, to: p5.Tree.SCREEN,
+                         out: loc, mat4PV: pv })
 ```
 
 Constants: `p5.Tree.ORIGIN`, `p5.Tree.i`, `p5.Tree.j`, `p5.Tree.k`, `p5.Tree._i`, `p5.Tree._j`, `p5.Tree._k`.
@@ -566,15 +575,15 @@ pop()
 
 Both accept the same options object:
 
-| Option     | Default          | Description                                    |
-|------------|------------------|------------------------------------------------|
-| `mMatrix`  | current model    | Override model matrix.                         |
-| `size`     | `50`             | Hit radius (world units, auto-scaled by depth).|
-| `shape`    | `p5.Tree.CIRCLE` | `CIRCLE` or `SQUARE`.                          |
-| `eMatrix`  | current eye      | Pre-computed eye matrix.                       |
-| `pMatrix`  | current proj     | Override projection.                           |
-| `vMatrix`  | current view     | Override view.                                 |
-| `pvMatrix` | P·V              | Pre-computed PV.                               |
+| Option      | Default          | Description                                    |
+|-------------|------------------|------------------------------------------------|
+| `mat4Model` | current model    | Override model matrix.                         |
+| `size`      | `50`             | Hit radius (world units, auto-scaled by depth).|
+| `shape`     | `p5.Tree.CIRCLE` | `CIRCLE` or `SQUARE`.                          |
+| `mat4Eye`   | current eye      | Pre-computed eye matrix.                       |
+| `mat4Proj`  | current proj     | Override projection.                           |
+| `mat4View`  | current view     | Override view.                                 |
+| `mat4PV`    | P·V              | Pre-computed PV.                               |
 
 ---
 
@@ -630,11 +639,11 @@ p5.Tree.INVISIBLE
 Scene-space diagnostic helpers — drawn to understand the scene, not to build it.
 
 ```js
-axes([{ size, bits, mMatrix, eMatrix, pMatrix, vMatrix, pvMatrix }])
+axes([{ size, bits, mat4Model, mat4Eye, mat4Proj, mat4View, mat4PV }])
 grid([{ size, subdivisions }])
 bullsEye([{ size, shape }])
 cross([{ size }])
-viewFrustum({ pg, eMatrix, pMatrix, vMatrix, bits, viewer })
+viewFrustum({ pg, mat4Eye, mat4Proj, mat4View, bits, viewer })
 ```
 
 `axes` bits: `p5.Tree.X`, `p5.Tree._X`, `p5.Tree.Y`, `p5.Tree._Y`, `p5.Tree.Z`, `p5.Tree._Z`, `p5.Tree.LABELS`.

deps/tree/README.md

@@ -219,24 +219,48 @@ One-keyframe behaviour: `play()` with exactly one keyframe snaps `eval()` to tha
 
 **Spaces:** `WORLD`, `EYE`, `SCREEN`, `NDC`, `MODEL`, `MATRIX` (custom frame).
 
-**NDC convention:** `WEBGL = -1` (z ∈ [−1,1]), `WEBGPU = 0` (z ∈ [0,1]).
+#### Conventions
+
+Three independent conventions are controlled by caller-supplied parameters:
+
+**NDC Z** — passed as `ndcZMin`:
+```
+WEBGL  = −1   z ∈ [−1,  1]
+WEBGPU =  0   z ∈ [ 0,  1]
+```
+
+**Viewport** — `vp = [x, y, w, h]` with signed `h`:
+```
+h < 0  screen y-down (DOM / p5 mouseX·mouseY)  →  [0, canvasH, canvasW, −canvasH]
+h > 0  screen y-up   (OpenGL gl_FragCoord)     →  [0, 0, canvasW, canvasH]
+```
+The sign of `h` is the only thing that differs — no branching, no flags.
+
+**NDC Y** — controlled by `ndcYSign` in the projection constructors (`form.js`):
+```
++1  NDC y-up   (default) — OpenGL / WebGL / WebGPU / Three.js / p5v2
+−1  NDC y-down           — native Vulkan clip space
+```
+
+#### Usage
 
 ```js
 import { mapLocation, mapDirection, WORLD, SCREEN, WEBGL } from '@nakednous/tree'
 
 const out = new Float32Array(3)
 const m = {
-  pMatrix:   /* Float32Array(16) — projection */,
-  vMatrix:   /* Float32Array(16) — view (world→eye) */,
-  pvMatrix:  /* pMatrix × vMatrix — optional, computed if absent */,
-  ipvMatrix: /* inv(pvMatrix)    — optional, computed if absent */,
+  mat4Proj:   /* Float32Array(16) — projection (eye → clip) */,
+  mat4View:   /* Float32Array(16) — view (world → eye) */,
+  mat4PV?:    /* mat4Proj × mat4View — optional, computed if absent */,
+  mat4PVInv?: /* inv(mat4PV)         — optional, computed if absent */,
 }
-const vp = [0, height, width, -height]
+const vp = [0, height, width, -height]  // signed h = screen y-down
 
 mapLocation(out, worldX, worldY, worldZ, WORLD, SCREEN, m, vp, WEBGL)
 ```
 
-The matrices bag `m` is assembled by the host (p5.tree reads live renderer state into it). All pairs are supported: WORLD↔EYE, WORLD↔SCREEN, WORLD↔NDC, EYE↔SCREEN, SCREEN↔NDC, WORLD↔MATRIX, and their reverses.
+The matrices bag `m` is assembled by the host. All pairs are supported:
+WORLD↔EYE, WORLD↔SCREEN, WORLD↔NDC, EYE↔SCREEN, SCREEN↔NDC, WORLD↔MATRIX, and their reverses.
 
 ---
 
@@ -289,14 +313,14 @@ mat4PV  mat4MV
 **Matrix construction from specs** (`form.js`):
 ```
 mat4FromBasis        — rigid frame from orthonormal basis + translation
-mat4View           — view matrix (world→eye) from lookat params
-mat4Eye        — eye matrix (eye→world) from lookat params
+mat4View             — view matrix (world→eye) from lookat params
+mat4Eye              — eye matrix (eye→world) from lookat params
 mat4FromTRS          — column-major mat4 from flat TRS scalars
 mat4FromTranslation  — translation-only mat4
 mat4FromScale        — scale-only mat4
-mat4Perspective      — perspective projection
-mat4Ortho            — orthographic projection
-mat4Frustum          — off-centre perspective projection
+mat4Perspective      — perspective projection  (ndcZMin, ndcYSign)
+mat4Ortho            — orthographic projection (ndcZMin, ndcYSign)
+mat4Frustum          — off-centre perspective  (ndcZMin, ndcYSign)
 mat4Bias             — NDC→texture/UV remap [0,1] for shadow mapping
 mat4Reflect          — reflection across a plane
 mat4ToTranslation    — extract translation (col 3)
@@ -312,7 +336,7 @@ projLeft  projRight  projTop  projBottom
 
 **Pixel ratio:** `pixelRatio(proj, vpH, eyeZ, ndcZMin)` — world-units-per-pixel at a given depth, handles both perspective and orthographic.
 
-**Pick matrix:** `mat4Pick(proj, px, py, W, H)` — mutates a projection mat4 in-place so that pixel `(px, py)` maps to the full NDC square. Used by the p5.tree GPU color-ID picking implementation. Convention-independent (perspective and orthographic).
+**Pick matrix:** `mat4Pick(proj, px, py, vp)` — mutates 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. Takes the same signed viewport `vp` as `mapLocation` — the y-convention is preserved automatically.
 
 ---
 
@@ -337,7 +361,7 @@ ORIGIN, i, j, k, _i, _j, _k
 
 ## Performance contract
 
-All hot-path functions follow an **out-first, zero-allocation** contract:
+All functions in this package follow an **out-first, zero-allocation** contract:
 
 - `out` is the first parameter — the caller owns the buffer
 - the function writes into `out` and returns it
@@ -346,15 +370,15 @@ All hot-path functions follow an **out-first, zero-allocation** contract:
 
 ```js
 // allocate once
-const out      = new Float32Array(3)
-const pvMatrix = new Float32Array(16)
-const ipvMatrix= new Float32Array(16)
+const out       = new Float32Array(3)
+const mat4PV    = new Float32Array(16)
+const mat4PVInv = new Float32Array(16)
 
 // per frame — zero allocation
-mat4Mul(pvMatrix, proj, view)
-mat4Invert(ipvMatrix, pvMatrix)
+mat4Mul(mat4PV, proj, view)
+mat4Invert(mat4PVInv, mat4PV)
 mapLocation(out, px, py, pz, WORLD, SCREEN,
-  { pMatrix: proj, vMatrix: view, pvMatrix, ipvMatrix }, vp, WEBGL)
+  { mat4Proj: proj, mat4View: view, mat4PV, mat4PVInv }, vp, WEBGL)
 ```
 
 ---