@nakednous/tree 0.0.26 → 0.0.28

package/dist/index.js

@@ -44,6 +44,59 @@ const DIAL   = 3;
 const POINT     = 0;
 const DIRECTION = 1;
 
+// Pointer-hit shapes (pointerHit); bullsEyeLines' shape
+const CIRCLE = 0;
+const SQUARE = 1;
+
+// Gizmo bits — one namespace per generator. The same value means different
+// things to different generators, and no generator reads another's bits.
+const NONE = 0;
+
+// axesLines
+const X      = 1 << 0;
+const _X     = 1 << 1;
+const Y      = 1 << 2;
+const _Y     = 1 << 3;
+const Z      = 1 << 4;
+const _Z     = 1 << 5;
+const LABELS = 1 << 6;
+
+// frustumLines (LEFT … TOP also key a bounds object's planes)
+const NEAR   = 1 << 0;
+const FAR    = 1 << 1;
+const LEFT   = 1 << 2;
+const RIGHT  = 1 << 3;
+const BOTTOM = 1 << 4;
+const TOP    = 1 << 5;
+const BODY   = 1 << 6;
+const APEX   = 1 << 7;
+
+// pathLines
+const PATH         = 1 << 0;
+const CENTER       = 1 << 1;
+const CONTROLS     = 1 << 2;
+const TANGENTS_IN  = 1 << 3;
+const TANGENTS_OUT = 1 << 4;
+const TANGENTS     = TANGENTS_IN | TANGENTS_OUT;
+const HANDLES      = 1 << 5;
+
+// helmRigLines
+const TRANSLATE = 1 << 0;
+const ROTATE    = 1 << 1;
+
+// locusLines (HANDLE is the bridge's dot, not a line)
+const HANDLE = 1 << 0;
+const AIM    = 1 << 1;
+const LOCUS  = 1 << 2;
+const RING   = 1 << 3;
+
+// Semantic palette — normalised RGBA: red, lime, dodger blue; COLOR_DIM is
+// the alpha of a dimmed stroke (the helm rig's baseline).
+const COLOR_X   = Object.freeze([1, 0, 0, 1]);
+const COLOR_Y   = Object.freeze([0, 1, 0, 1]);
+const COLOR_Z   = Object.freeze([30 / 255, 144 / 255, 1, 1]);
+const COLOR_DIM = 110 / 255;
+
 /**
  * @file Quaternion algebra and mat4/mat3 conversions.
  * @module tree/quat
@@ -207,6 +260,10 @@ const qFromAxisAngle = (out, ax, ay, az, angle) => {
 
 /**
  * Build a quaternion from a look direction (−Z forward) and optional up (default +Y).
+ * `dir` need not be unit. Right = dir × up, up re-orthogonalised as right × dir;
+ * when `dir` is parallel to `up` the up hint is re-seeded from the world axis
+ * least aligned with `dir` (the same seed qFromUnitVectors uses), so every
+ * direction yields a proper rotation.
  * @param {number[]} out
  * @param {number[]} dir  Forward direction [x,y,z].
  * @param {number[]} [up] Up vector [x,y,z].
@@ -217,11 +274,18 @@ const qFromLookDir = (out, dir, up) => {
   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;
+  let rx=fy*uz-fz*uy, ry=fz*ux-fx*uz, rz=fx*uy-fy*ux;          // right = dir × up
+  let rl=Math.sqrt(rx*rx+ry*ry+rz*rz);
+  if (rl < 1e-8) {                                              // dir ∥ up: re-seed up
+    const ax=Math.abs(fx), ay=Math.abs(fy), az=Math.abs(fz);
+    ux=0; uy=0; uz=0;
+    if (ax <= ay && ax <= az) ux=1; else if (ay <= az) uy=1; else uz=1;
+    rx=fy*uz-fz*uy; ry=fz*ux-fx*uz; rz=fx*uy-fy*ux;
+    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);
+  ux=ry*fz-rz*fy; uy=rz*fx-rx*fz; uz=rx*fy-ry*fx;              // up = right × dir
+  return qFromRotMat3x3(out, rx,ux,-fx, ry,uy,-fy, rz,uz,-fz);   // columns: right, up, back
 };
 
 /**
@@ -293,6 +357,117 @@ const qToAxisAngle = (q, out) => {
   return out;
 };
 
+/**
+ * @file 1€ input filter — speed-adaptive first-order low-pass for noisy input.
+ * @module tree/filter
+ * @license AGPL-3.0-only
+ *
+ * A jitter conditioner for noisy / absolute input streams (the helm's optional
+ * `filter` slot; sketch-side handle conditioning). It is NOT a deadzone
+ * replacement: a low-pass passes DC, so a constant rest bias survives it and
+ * still integrates to creep — only the deadzone's exact-zero clamp removes that.
+ * The 1€ removes zero-mean jitter; the two are orthogonal and coexist, applied
+ * filter → deadzone (condition the continuous signal first, then gate to zero).
+ *
+ * First-order low-pass whose cutoff rises with the signal's speed: slow (rest)
+ * → low cutoff → heavy smoothing; fast (motion) → high cutoff → low lag. Tuned
+ * by `minCutoff` (Hz, the rest cutoff) and `beta` (how fast the cutoff opens
+ * with speed). Reimplemented from the paper's equations — `tree` is zero-dep, so
+ * the ~one-page primitive is vendored, not depended on (the same call made for
+ * quaternions over gl-matrix).
+ *
+ * Reference: Casiez, G., Roussel, N., & Vogel, D. (2012). 1€ Filter: A Simple
+ * Speed-based Low-pass Filter for Noisy Input in Interactive Systems. CHI '12,
+ * 2527–2530. DOI 10.1145/2207676.2208639 · https://gery.casiez.net/1euro/
+ */
+
+
+/**
+ * Build a stateful 1€ filter as an out-first carrying function.
+ *
+ * The returned `f` carries the previous filtered value and derivative across
+ * calls (one state slot per vector component), and is used in one of two forms:
+ *
+ *   - vec form    `f(out, raw, dt)` — `out`/`raw` are equal-length ArrayLikes;
+ *                 writes the filtered vector into `out` and returns it.
+ *                 Zero-allocation after the first call (state sized to `raw`).
+ *   - scalar form `f(raw, dt)` — `raw` is a number; returns the filtered number.
+ *
+ * The form is chosen by the first argument's type (number ⇒ scalar). `minCutoff`,
+ * `beta`, and `dCutoff` are live-mutable on the returned function (`f.minCutoff`,
+ * `f.beta`, `f.dCutoff`) and read every call, so a panel can tune them against
+ * live noise. `f.reset()` drops the carried state at a discontinuity (a
+ * re-acquired source, a helm `home()`); smear across one and the output lurches.
+ *
+ * @param {Object}  [opts]
+ * @param {number}  [opts.minCutoff=1]  Minimum (rest) cutoff frequency, in Hz.
+ * @param {number}  [opts.beta=0]       Speed coefficient (cutoff = minCutoff +
+ *                                       beta·|filtered derivative|); unitless.
+ * @param {number}  [opts.dCutoff=1]    Derivative cutoff frequency, in Hz.
+ * @returns {Function} A carrying filter `f(out, raw, dt)` / `f(raw, dt)` with a
+ *                      `reset()` method and live `minCutoff` / `beta` / `dCutoff`.
+ */
+function oneEuro(opts) {
+  opts = opts || {};
+
+  // Carried state: previous filtered value + previous filtered derivative.
+  // number (scalar form) | number[] (vec form). primed = state is seeded.
+  let xPrev = null;
+  let dxPrev = null;
+  let primed = false;
+
+  // Low-pass smoothing factor for a sample period `dt` and a cutoff frequency
+  // (the paper's α = 1 / (1 + τ/Te), τ = 1 / (2π·cutoff)).
+  const alpha = (dt, cutoff) => {
+    const tau = 1 / (2 * Math.PI * cutoff);
+    return 1 / (1 + tau / dt);
+  };
+  const smooth = (a, x, xp) => a * x + (1 - a) * xp;
+
+  const scalar = (x, dt) => {
+    if (!primed) { xPrev = x; dxPrev = 0; primed = true; return x; }
+    const dx  = (x - xPrev) / dt;
+    const edx = smooth(alpha(dt, f.dCutoff), dx, dxPrev);
+    const a   = alpha(dt, f.minCutoff + f.beta * Math.abs(edx));
+    const xh  = smooth(a, x, xPrev);
+    xPrev = xh; dxPrev = edx;
+    return xh;
+  };
+
+  const vec = (out, raw, dt) => {
+    const n = raw.length;
+    if (!primed) {
+      if (!Array.isArray(xPrev) || xPrev.length !== n) {
+        xPrev = new Array(n); dxPrev = new Array(n);
+      }
+      for (let i = 0; i < n; i++) { xPrev[i] = raw[i]; dxPrev[i] = 0; out[i] = raw[i]; }
+      primed = true;
+      return out;
+    }
+    for (let i = 0; i < n; i++) {
+      const dx  = (raw[i] - xPrev[i]) / dt;
+      const edx = smooth(alpha(dt, f.dCutoff), dx, dxPrev[i]);
+      const a   = alpha(dt, f.minCutoff + f.beta * Math.abs(edx));
+      const xh  = smooth(a, raw[i], xPrev[i]);
+      xPrev[i] = xh; dxPrev[i] = edx;
+      out[i] = xh;
+    }
+    return out;
+  };
+
+  const f = (out, raw, dt) =>
+    (typeof out === 'number') ? scalar(out, raw) : vec(out, raw, dt);
+
+  f.minCutoff = (opts.minCutoff != null) ? opts.minCutoff : 1;
+  f.beta      = (opts.beta      != null) ? opts.beta      : 0;
+  f.dCutoff   = (opts.dCutoff   != null) ? opts.dCutoff   : 1;
+
+  /** Drop the carried state — call at a discontinuity (re-acquire / home). */
+  f.reset = () => { primed = false; return f; };
+
+  return f;
+}
+
 /**
  * @file Matrix construction from geometric specs and partial decomposition.
  * @module tree/form
@@ -352,6 +527,34 @@ function mat4FromBasis(out, rx,ry,rz, ux,uy,uz, fx,fy,fz, tx,ty,tz) {
   return out;
 }
 
+// Lookat basis scratch — right (0–2), up (3–5), back (6–8): unit, world space.
+const _lb = new Float64Array(9);
+
+/**
+ * Orthonormal lookat basis into `_lb`: back = eye − center, right = up × back,
+ * up = back × right. When the view direction is parallel to the up hint the
+ * hint is re-seeded from the world axis least aligned with it — the seed
+ * qFromUnitVectors and qFromLookDir use — so the basis is always a rotation.
+ */
+function _lookBasis(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;
+  let xx=uy*zz-uz*zy, xy=uz*zx-ux*zz, xz=ux*zy-uy*zx;
+  let xl=Math.sqrt(xx*xx+xy*xy+xz*xz);
+  if (xl < 1e-8) {                                              // view ∥ up: re-seed up
+    const ax=Math.abs(zx), ay=Math.abs(zy), az=Math.abs(zz);
+    ux=0; uy=0; uz=0;
+    if (ax <= ay && ax <= az) ux=1; else if (ay <= az) uy=1; else uz=1;
+    xx=uy*zz-uz*zy; xy=uz*zx-ux*zz; xz=ux*zy-uy*zx;
+    xl=Math.sqrt(xx*xx+xy*xy+xz*xz)||1;
+  }
+  xx/=xl; xy/=xl; xz/=xl;
+  _lb[0]=xx; _lb[1]=xy; _lb[2]=xz;
+  _lb[3]=zy*xz-zz*xy; _lb[4]=zz*xx-zx*xz; _lb[5]=zx*xy-zy*xx;
+  _lb[6]=zx; _lb[7]=zy; _lb[8]=zz;
+}
+
 /**
  * View matrix (world→eye) from lookat parameters.
  * Camera looks along −Z in eye space; right = normalize(up × (−Z)).
@@ -360,16 +563,12 @@ function mat4FromBasis(out, rx,ry,rz, ux,uy,uz, fx,fy,fz, tx,ty,tz) {
  * @param {Float32Array|number[]} out  16-element destination.
  * @param {number} ex,ey,ez   Eye (camera) position.
  * @param {number} cx,cy,cz   Look-at target.
- * @param {number} ux,uy,uz   World up hint (need not be unit).
+ * @param {number} ux,uy,uz   World up hint (need not be unit; re-seeded when
+ *                            parallel to the view direction).
  */
 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;
-  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;
+  _lookBasis(ex,ey,ez, cx,cy,cz, ux,uy,uz);
+  const xx=_lb[0],xy=_lb[1],xz=_lb[2], yx=_lb[3],yy=_lb[4],yz=_lb[5], zx=_lb[6],zy=_lb[7],zz=_lb[8];
   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;
@@ -388,16 +587,12 @@ function mat4View(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
  * @param {Float32Array|number[]} out  16-element destination.
  * @param {number} ex,ey,ez   Eye position.
  * @param {number} cx,cy,cz   Look-at target.
- * @param {number} ux,uy,uz   World up hint.
+ * @param {number} ux,uy,uz   World up hint (need not be unit; re-seeded when
+ *                            parallel to the view direction).
  */
 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;
-  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;
+  _lookBasis(ex,ey,ez, cx,cy,cz, ux,uy,uz);
+  const xx=_lb[0],xy=_lb[1],xz=_lb[2], yx=_lb[3],yy=_lb[4],yz=_lb[5], zx=_lb[6],zy=_lb[7],zz=_lb[8];
   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;
@@ -734,8 +929,8 @@ function projRight (p, ndcZMin) { return p[15]===1 ?  (1-p[12])/p[0]  : projNear
  */
 function projTop(p, ndcZMin) {
   return p[15]===1
-    ? ( Math.sign(p[5]) - p[13]) / p[5]   // ortho
-    : projNear(p,ndcZMin)*(1+p[9])/p[5];  // perspective (p[5]>0 in practice)
+    ? ( Math.sign(p[5]) - p[13]) / p[5]                    // ortho
+    : projNear(p,ndcZMin)*(Math.sign(p[5])+p[9])/p[5];     // perspective
 }
 
 /**
@@ -743,8 +938,8 @@ function projTop(p, ndcZMin) {
  */
 function projBottom(p, ndcZMin) {
   return p[15]===1
-    ? (-Math.sign(p[5]) - p[13]) / p[5]   // ortho
-    : projNear(p,ndcZMin)*(p[9]-1)/p[5];  // perspective
+    ? (-Math.sign(p[5]) - p[13]) / p[5]                    // ortho
+    : projNear(p,ndcZMin)*(p[9]-Math.sign(p[5]))/p[5];     // perspective
 }
 
 /** Vertical field of view in radians (perspective only). */
@@ -772,9 +967,10 @@ function mat4MV(out, model, view) { return mat4Mul(out, view, model); }
  */
 function mat4Location(out, from, to) {
   // Same as: return mat4Invert(out, to) && mat4Mul(out, out, from);
-  const a00=to[0],a01=to[1],a02=to[2],
-        a10=to[4],a11=to[5],a12=to[6],
-        a20=to[8],a21=to[9],a22=to[10];
+  // a_rc reads column-major: element (row r, column c) is to[c*4 + r].
+  const a00=to[0],a01=to[4],a02=to[8],
+        a10=to[1],a11=to[5],a12=to[9],
+        a20=to[2],a21=to[6],a22=to[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;
@@ -794,14 +990,17 @@ function mat4Location(out, from, to) {
 }
 
 /**
- * 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.
+ * Direction transform between frames: out = inv(to₃) · from₃ — a direction's
+ * coordinates in `from` become its coordinates in `to`, the same conversion
+ * mat4Location and mapDirection perform, on the upper-left 3×3 blocks only
+ * (rotation / scale, no translation).
+ * @returns {ArrayLike<number>|null} out, or null if `to` 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];
+  // a_rc reads column-major: element (row r, column c) is to[c*4 + r].
+  const a00=to[0],a01=to[4],a02=to[8],
+        a10=to[1],a11=to[5],a12=to[9],
+        a20=to[2],a21=to[6],a22=to[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;
@@ -809,10 +1008,13 @@ function mat3Direction(out, from, to) {
   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;
+  // out = inv(to₃) · from₃, column by column of from.
+  for (let c = 0; c < 3; c++) {
+    const f0=from[c*4], f1=from[c*4+1], f2=from[c*4+2];
+    out[c*3]   = i00*f0 + i01*f1 + i02*f2;
+    out[c*3+1] = i10*f0 + i11*f1 + i12*f2;
+    out[c*3+2] = i20*f0 + i21*f1 + i22*f2;
+  }
   return out;
 }
 
@@ -1010,9 +1212,13 @@ function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
 }
 
 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;
+  // Inverse of _worldToScreenDir: undo the viewport scale, then the projection's
+  // upper-triangular 3×3 block (p[8], p[9] carry an off-centre frustum), then
+  // rotate eye→world. Signed vpW/vpH cancel the y-flip.
+  const cz = dz/((1-ndcZMin)*0.5)/proj[10];
+  const cy = (dy/(vpH*0.5) - proj[9]*cz)/proj[5];
+  const cx = (dx/(vpW*0.5) - proj[8]*cz)/proj[0];
+  return _applyDir(out, eye, cx, cy, cz);
 }
 
 function _screenToNDCDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
@@ -1120,6 +1326,63 @@ function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
   return out;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Rays and pointer hits
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Screen point → world ray: origin on the near plane (screen depth 0), unit
+ * direction toward the far plane (depth 1). Same bag and viewport contract as
+ * mapLocation; `m.mat4PVInv` must be filled by the caller.
+ *
+ * @param {number[]} outO    3-element origin.
+ * @param {number[]} outD    3-element unit direction.
+ * @param {number}   sx,sy   Screen point.
+ * @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[]|null} outD, or null when the bag carries no mat4PVInv
+ *                          (singular P·V) or the ray has no length.
+ */
+function unproject(outO, outD, sx, sy, m, vp, ndcZMin) {
+  const ipv = m.mat4PVInv;
+  if (!ipv) return null;
+  _screenToWorld(outO, sx, sy, 0, ipv, vp, ndcZMin);
+  _screenToWorld(outD, sx, sy, 1, ipv, vp, ndcZMin);
+  const dx=outD[0]-outO[0], dy=outD[1]-outO[1], dz=outD[2]-outO[2];
+  const l=Math.sqrt(dx*dx+dy*dy+dz*dz);
+  if (!(l > 0)) return null;
+  outD[0]=dx/l; outD[1]=dy/l; outD[2]=dz/l;
+  return outD;
+}
+
+const _hit = [0, 0, 0];   // pointerHit screen scratch
+
+/**
+ * Is the pointer within `radius` px of the projected world point (x, y, z)?
+ * `shape` is CIRCLE (Euclidean, default) or SQUARE (Chebyshev); the boundary
+ * hits. A point whose screen depth falls outside [0, 1] — behind the camera,
+ * before the near plane or beyond the far plane — never hits.
+ *
+ * @param {number}   px,py   Pointer, screen px.
+ * @param {number}   x,y,z   World point.
+ * @param {number}   radius  Hit radius, px.
+ * @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).
+ * @param {number}   [shape=CIRCLE]  CIRCLE or SQUARE.
+ * @returns {boolean}
+ */
+function pointerHit(px, py, x, y, z, radius, m, vp, ndcZMin, shape = CIRCLE) {
+  _worldToScreen(_hit, x, y, z, _ensurePV(m), vp, ndcZMin);
+  const d = _hit[2];
+  if (!(d >= 0 && d <= 1)) return false;
+  const dx = px - _hit[0], dy = py - _hit[1];
+  return shape === SQUARE
+    ? Math.abs(dx) <= radius && Math.abs(dy) <= radius
+    : dx*dx + dy*dy <= radius*radius;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // pixelRatio
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1173,6 +1436,34 @@ function mat4Pick(proj, px, py, vp) {
   }
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Pick-id codec
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pick id → colour: the 24-bit id packed into r, g, b as normalised floats,
+ * R the low byte, alpha 1. Id 0 is the background; ids run 1 … 2²⁴ − 1.
+ * @param {number[]} out  4-element destination.
+ * @param {number}   id   Integer id.
+ * @returns {number[]} out
+ */
+function idToRgba(out, id) {
+  out[0] = (id & 255) / 255;
+  out[1] = ((id >> 8) & 255) / 255;
+  out[2] = ((id >> 16) & 255) / 255;
+  out[3] = 1;
+  return out;
+}
+
+/**
+ * Colour bytes → pick id, the inverse of idToRgba on a readback.
+ * @param {number} r,g,b  Bytes 0 … 255 (fractions truncated).
+ * @returns {number} id
+ */
+function rgbaToId(r, g, b) {
+  return (r & 255) | ((g & 255) << 8) | ((b & 255) << 16);
+}
+
 // =========================================================================
 // Decomposition
 // =========================================================================
@@ -1540,9 +1831,9 @@ const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
 function _parseQuat(v) {
   if (!v) return null;
 
-  // [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]];
+  // [x,y,z,w] — normalised like every other form
+  if (Array.isArray(v) && v.length === 4) return qNormalize([v[0],v[1],v[2],v[3]]);
+  if (ArrayBuffer.isView(v) && v.length >= 4) return qNormalize([v[0],v[1],v[2],v[3]]);
 
   if (typeof v !== 'object') return null;
 
@@ -2511,13 +2802,15 @@ class CameraTrack extends Track {
  * A constraint is any object exposing: `kind` (integer discriminant),
  * `solve(ox,oy,oz, dx,dy,dz)`, `value(out, report)`, `seed(x,y,z)`, and
  * optionally `scalar()` / `azEl(out2)` / `aim(ax,ay,az[, zx,zy,zz])` — the
- * basis re-aim seam the bridge's deferred `from` frame drives (§4.13).
- * The p5.tree handle controller drives
- * any conforming constraint (lifecycle, frame conversion, bind, hooks, pick);
- * a new kind — 6-DOF, or app-specific — implements this contract here
- * (portable, draw-free) plus a bridge-side locus/pick draw (`drawLocus` /
- * `pickProxy` on createHandle), rather than forking the controller. The
- * classes below are the reference implementation. See handle-design.md §9.
+ * basis re-aim seam the bridge's deferred `from` frame drives — and
+ * `proxy(ox,oy,oz, dx,dy,dz, radius)`, the analytic pick: the ray parameter
+ * at which a ray in the working space meets the grab proxy of `radius`
+ * working units, or Infinity (a kind without one gets a sphere at its
+ * POINT). The handle controller drives any conforming constraint
+ * (lifecycle, frame conversion, bind, hooks, pick); a new kind — 6-DOF, or
+ * app-specific — implements this contract here (portable, draw-free) plus a
+ * bridge-side locus draw, rather than forking the controller. The classes
+ * below are the reference implementation. See handle-design.md §9–§10.
  *
  * ── Conventions ────────────────────────────────────────────────────────────
  * Ray direction `d` is assumed unit (the bridge normalises). Plane / axis
@@ -2530,7 +2823,7 @@ class CameraTrack extends Track {
 
 
 const EPS = 1e-6;
-const TWO_PI = Math.PI * 2;
+const TWO_PI$1 = Math.PI * 2;
 
 // Edge-on threshold for DIAL: below this |d·n| the plane hit is ill-conditioned
 // (dθ per pixel diverges) and the solve switches to the tangent-line fallback.
@@ -2546,10 +2839,10 @@ const _clamp = (x, lo, hi) => x < lo ? lo : (x > hi ? hi : x);
 const _num   = (x, d) => _isNum(x) ? x : d;
 
 /** Wrap an angle to (−π, π]. */
-const _wrapPi = (a) => a - TWO_PI * Math.round(a / TWO_PI);
+const _wrapPi = (a) => a - TWO_PI$1 * Math.round(a / TWO_PI$1);
 
 /** Parse a vec3 from array / typed array / {x,y,z}. Returns a fresh [x,y,z] or null. */
-function _vec3(v) {
+function _vec3$1(v) {
   if (!v) return null;
   if (ArrayBuffer.isView(v) && v.length >= 3) return [v[0], v[1], v[2]];
   if (Array.isArray(v) && v.length >= 3) return [v[0], v[1], v[2]];
@@ -2558,7 +2851,7 @@ function _vec3(v) {
 }
 
 /** Normalise a vec3 in place; zero-length falls back to the given default axis. */
-function _unit(v, dx, dy, dz) {
+function _unit$1(v, dx, dy, dz) {
   const l = Math.sqrt(v[0]*v[0] + v[1]*v[1] + v[2]*v[2]);
   if (l < EPS) { v[0]=dx; v[1]=dy; v[2]=dz; return v; }
   v[0]/=l; v[1]/=l; v[2]/=l;
@@ -2571,12 +2864,12 @@ function _unit(v, dx, dy, dz) {
  * (Same derivation the p5 bridge uses for its plane quad — duplicated here
  * because the core cannot depend on the bridge.)
  */
-function _basis(n, ub, vb) {
+function _basis$1(n, ub, vb) {
   const ax = Math.abs(n[0]), ay = Math.abs(n[1]), az = Math.abs(n[2]);
   let rx = 0, ry = 0, rz = 0;
   if (ax <= ay && ax <= az) rx = 1; else if (ay <= az) ry = 1; else rz = 1;
   ub[0] = ry*n[2] - rz*n[1]; ub[1] = rz*n[0] - rx*n[2]; ub[2] = rx*n[1] - ry*n[0];
-  _unit(ub, 1, 0, 0);
+  _unit$1(ub, 1, 0, 0);
   vb[0] = n[1]*ub[2] - n[2]*ub[1]; vb[1] = n[2]*ub[0] - n[0]*ub[2]; vb[2] = n[0]*ub[1] - n[1]*ub[0];
 }
 
@@ -2660,6 +2953,132 @@ function rayClosestPointOnAxis(out, ox,oy,oz, dx,dy,dz, px,py,pz, ux,uy,uz) {
   return s;
 }
 
+// =========================================================================
+// H2b Ray-primitive hit tests (pure, no out: the nearest t, or Infinity)
+// =========================================================================
+//
+// Beside the solve primitives above, which always write a point, these are
+// TESTS: they write nothing and return the ray parameter of the nearest hit
+// with t ≥ 0, or Infinity on a miss. A ray whose origin lies inside the
+// primitive hits at its exit, so a press from inside a proxy still grabs.
+// The ray direction is assumed unit.
+
+/**
+ * Ray–sphere hit test.
+ * @param {number} ox,oy,oz  Ray origin.
+ * @param {number} dx,dy,dz  Ray direction (unit).
+ * @param {number} cx,cy,cz  Sphere centre.
+ * @param {number} r         Sphere radius.
+ * @returns {number} The nearest t ≥ 0, or Infinity.
+ */
+function rayHitSphere(ox,oy,oz, dx,dy,dz, cx,cy,cz, r) {
+  const lx=ox-cx, ly=oy-cy, lz=oz-cz;
+  const b  = lx*dx + ly*dy + lz*dz;
+  const cc = lx*lx + ly*ly + lz*lz - r*r;
+  const disc = b*b - cc;
+  if (disc < 0) return Infinity;
+  const s = Math.sqrt(disc);
+  let t = -b - s;
+  if (t < 0) t = -b + s;                // origin inside: the exit
+  return t < 0 ? Infinity : t;          // both roots behind the origin
+}
+
+// One end cap of a capsule: the sphere at (cx,cy,cz), a root accepted only
+// where the hit's axial coordinate h = wu + t·du lies beyond the segment on
+// that cap's side (h ≤ 0 at A, h ≥ L at B), so the point is on the capsule's
+// surface and not inside its cylinder.
+function _capHit(ox,oy,oz, dx,dy,dz, cx,cy,cz, r, wu, du, lim, endB) {
+  const lx=ox-cx, ly=oy-cy, lz=oz-cz;
+  const b  = lx*dx + ly*dy + lz*dz;
+  const cc = lx*lx + ly*ly + lz*lz - r*r;
+  const disc = b*b - cc;
+  if (disc < 0) return Infinity;
+  const s = Math.sqrt(disc);
+  let t = -b - s, h = wu + t*du;
+  if (t < 0 || (endB ? h < lim : h > lim)) { t = -b + s; h = wu + t*du; }
+  return (t >= 0 && (endB ? h >= lim : h <= lim)) ? t : Infinity;
+}
+
+/**
+ * Ray–capsule hit test: the segment A→B swept by radius r. The cylinder wall
+ * counts within the segment's extent, each end sphere beyond it; the nearest
+ * of the three wins. A zero-length segment is the sphere at A.
+ * @param {number} ox,oy,oz  Ray origin.
+ * @param {number} dx,dy,dz  Ray direction (unit).
+ * @param {number} ax,ay,az  Segment start.
+ * @param {number} bx,by,bz  Segment end.
+ * @param {number} r         Capsule radius.
+ * @returns {number} The nearest t ≥ 0, or Infinity.
+ */
+function rayHitCapsule(ox,oy,oz, dx,dy,dz, ax,ay,az, bx,by,bz, r) {
+  let ux=bx-ax, uy=by-ay, uz=bz-az;
+  const L = Math.sqrt(ux*ux + uy*uy + uz*uz);
+  if (L < EPS) return rayHitSphere(ox,oy,oz, dx,dy,dz, ax,ay,az, r);
+  ux/=L; uy/=L; uz/=L;
+  const wx=ox-ax, wy=oy-ay, wz=oz-az;
+  const du = dx*ux + dy*uy + dz*uz;     // d·u
+  const wu = wx*ux + wy*uy + wz*uz;     // w·u
+  let best = Infinity;
+  // Cylinder wall: the quadratic in the components perpendicular to u.
+  const a = 1 - du*du;
+  if (a > EPS) {
+    const b = (dx*wx + dy*wy + dz*wz) - du*wu;
+    const c = (wx*wx + wy*wy + wz*wz) - wu*wu - r*r;
+    const disc = b*b - a*c;
+    if (disc >= 0) {
+      const s = Math.sqrt(disc);
+      let t = (-b - s)/a, h = wu + t*du;
+      if (t < 0 || h < 0 || h > L) { t = (-b + s)/a; h = wu + t*du; }
+      if (t >= 0 && h >= 0 && h <= L) best = t;
+    }
+  }
+  const ta = _capHit(ox,oy,oz, dx,dy,dz, ax,ay,az, r, wu, du, 0, false);
+  if (ta < best) best = ta;
+  const tb = _capHit(ox,oy,oz, dx,dy,dz, bx,by,bz, r, wu, du, L, true);
+  if (tb < best) best = tb;
+  return best;
+}
+
+// Ring scratch — the plane normal and its in-plane basis. Function-local
+// working values, never state: rayHitRing runs to completion.
+const _rn = [0, 0, 1], _r0 = [1, 0, 0], _r1 = [0, 1, 0];
+
+/**
+ * Ray–ring hit test: the circle of radius R about c in the plane
+ * perpendicular to u, swept by tube radius r — the analytic torus proxy as a
+ * capsule chain, the circle polygonised into `detail` segments and each
+ * tested with rayHitCapsule. The chain has volume in every direction, so it
+ * never degenerates edge-on; the chordal error is R · (1 − cos(π / detail)).
+ * @param {number} ox,oy,oz  Ray origin.
+ * @param {number} dx,dy,dz  Ray direction (unit).
+ * @param {number} cx,cy,cz  Ring centre.
+ * @param {number} ux,uy,uz  Ring plane normal (normalised here).
+ * @param {number} R         Ring radius.
+ * @param {number} r         Tube radius.
+ * @param {number} [detail=32]  Chain segments (at least 3).
+ * @returns {number} The nearest t ≥ 0, or Infinity.
+ */
+function rayHitRing(ox,oy,oz, dx,dy,dz, cx,cy,cz, ux,uy,uz, R, r, detail = 32) {
+  const n = _isNum(detail) && detail >= 3 ? Math.floor(detail) : 32;
+  _rn[0]=ux; _rn[1]=uy; _rn[2]=uz;
+  _unit$1(_rn, 0, 0, 1);
+  _basis$1(_rn, _r0, _r1);
+  const step = TWO_PI$1 / n;
+  let best = Infinity;
+  let ax = cx + R*_r0[0], ay = cy + R*_r0[1], az = cz + R*_r0[2];   // vertex at angle 0
+  for (let i = 1; i <= n; i++) {
+    const th = i === n ? 0 : i*step;                                 // close the chain exactly
+    const cs = Math.cos(th)*R, sn = Math.sin(th)*R;
+    const bx = cx + cs*_r0[0] + sn*_r1[0];
+    const by = cy + cs*_r0[1] + sn*_r1[1];
+    const bz = cz + cs*_r0[2] + sn*_r1[2];
+    const t = rayHitCapsule(ox,oy,oz, dx,dy,dz, ax,ay,az, bx,by,bz, r);
+    if (t < best) best = t;
+    ax = bx; ay = by; az = bz;
+  }
+  return best;
+}
+
 // =========================================================================
 // H3  Angular utilities (readout / authoring convenience)
 // =========================================================================
@@ -2719,17 +3138,17 @@ class Constraint {
     this.kind = kind;
 
     /** Constraint origin (sphere centre / plane point / axis anchor / dial centre). @type {number[]} */
-    this.anchor = _vec3(opts.anchor) || [0, 0, 0];
+    this.anchor = _vec3$1(opts.anchor) || [0, 0, 0];
     /** Canonical unit direction — SPHERE. @type {number[]} */
     this.dir = [0, 0, 1];
     /** Constrained point — PLANE / AXIS / DIAL (and SPHERE scratch). @type {number[]} */
     this.pt = [this.anchor[0], this.anchor[1], this.anchor[2]];
     /** Plane normal (unit) — PLANE. @type {number[]} */
-    this.n = _unit(_vec3(opts.normal) || [0, 1, 0], 0, 1, 0);
+    this.n = _unit$1(_vec3$1(opts.normal) || [0, 1, 0], 0, 1, 0);
     /** Axis / dial-plane normal (unit) — AXIS / DIAL. @type {number[]} */
     this.u = kind === DIAL
-      ? _unit(_vec3(opts.axis) || [0, 1, 0], 0, 1, 0)
-      : _unit(_vec3(opts.axis) || [1, 0, 0], 1, 0, 0);
+      ? _unit$1(_vec3$1(opts.axis) || [0, 1, 0], 0, 1, 0)
+      : _unit$1(_vec3$1(opts.axis) || [1, 0, 0], 1, 0, 0);
     /** Current scalar parameter — AXIS: t along the line; DIAL: accumulated θ. @type {number} */
     this.s = 0;
 
@@ -2740,7 +3159,7 @@ class Constraint {
     /** In-plane binormal u × r0 (unit) — DIAL. @type {number[]} */
     this.r1 = [0, 0, 1];
     if (kind === DIAL) {
-      const z = _vec3(opts.zero);
+      const z = _vec3$1(opts.zero);
       this._dialBasis(z ? z[0] : NaN, z ? z[1] : NaN, z ? z[2] : NaN);
     }
 
@@ -2791,10 +3210,10 @@ class Constraint {
       this.r0[1] = zy - d*this.u[1];
       this.r0[2] = zz - d*this.u[2];
       const l = Math.sqrt(this.r0[0]**2 + this.r0[1]**2 + this.r0[2]**2);
-      if (l < EPS) _basis(this.u, this.r0, this.r1);
+      if (l < EPS) _basis$1(this.u, this.r0, this.r1);
       else { this.r0[0]/=l; this.r0[1]/=l; this.r0[2]/=l; }
     } else {
-      _basis(this.u, this.r0, this.r1);
+      _basis$1(this.u, this.r0, this.r1);
     }
     // r1 = u × r0 (recomputed even when _basis ran — same result, one rule).
     this.r1[0] = this.u[1]*this.r0[2] - this.u[2]*this.r0[1];
@@ -2818,7 +3237,7 @@ class Constraint {
       this.dir[0] = this.pt[0] - this.anchor[0];
       this.dir[1] = this.pt[1] - this.anchor[1];
       this.dir[2] = this.pt[2] - this.anchor[2];
-      _unit(this.dir, this.dir[0], this.dir[1], this.dir[2]);
+      _unit$1(this.dir, this.dir[0], this.dir[1], this.dir[2]);
     } else if (this.kind === PLANE) {
       // Parallel ray returns Infinity and leaves pt unchanged (keep last).
       rayPlane(this.pt, ox,oy,oz, dx,dy,dz,
@@ -2965,7 +3384,7 @@ class Constraint {
       if (px*px + py*py >= EPS*EPS) {
         const a = Math.atan2(py, px);
         // Nearest winding to the current θ preserves accumulated turns.
-        this.s = _clamp(a + TWO_PI * Math.round((this.s - a) / TWO_PI),
+        this.s = _clamp(a + TWO_PI$1 * Math.round((this.s - a) / TWO_PI$1),
                         this.min, this.max);
       }
       this._dialPoint();
@@ -2994,24 +3413,54 @@ class Constraint {
     if (this.kind === PLANE) {
       const px = this.n[0], py = this.n[1], pz = this.n[2];
       this.n[0] = ax; this.n[1] = ay; this.n[2] = az;
-      _unit(this.n, px, py, pz);
+      _unit$1(this.n, px, py, pz);
       this.seed(this.pt[0], this.pt[1], this.pt[2]);
     } else if (this.kind === AXIS) {
       const px = this.u[0], py = this.u[1], pz = this.u[2];
       this.u[0] = ax; this.u[1] = ay; this.u[2] = az;
-      _unit(this.u, px, py, pz);
+      _unit$1(this.u, px, py, pz);
       this.pt[0] = this.anchor[0] + this.s*this.u[0];
       this.pt[1] = this.anchor[1] + this.s*this.u[1];
       this.pt[2] = this.anchor[2] + this.s*this.u[2];
     } else if (this.kind === DIAL) {
       const px = this.u[0], py = this.u[1], pz = this.u[2];
       this.u[0] = ax; this.u[1] = ay; this.u[2] = az;
-      _unit(this.u, px, py, pz);
+      _unit$1(this.u, px, py, pz);
       this._dialBasis(zx, zy, zz);
       this._dialPoint();
     }
     return this;
   }
+
+  /**
+   * The analytic pick proxy: the ray parameter t at which a ray in the
+   * working space meets the grab proxy, or Infinity. `radius` is the grab
+   * size in working-space units — a constant pixel size the caller converted
+   * through pixelRatio at the proxy's depth. SPHERE / PLANE / AXIS: a sphere
+   * of `radius` at the reported POINT. DIAL: the ring at the anchor with
+   * tube radius `radius` (rayHitRing), so a grab lands anywhere on the ring.
+   *
+   * @param {number} ox,oy,oz  Ray origin.
+   * @param {number} dx,dy,dz  Ray direction (unit).
+   * @param {number} radius    Grab radius, working units.
+   * @returns {number} The nearest t ≥ 0, or Infinity.
+   */
+  proxy(ox, oy, oz, dx, dy, dz, radius) {
+    const a = this.anchor;
+    if (this.kind === DIAL) {
+      return rayHitRing(ox,oy,oz, dx,dy,dz, a[0], a[1], a[2],
+                        this.u[0], this.u[1], this.u[2], this._radius, radius);
+    }
+    let px, py, pz;
+    if (this.kind === SPHERE) {
+      px = a[0] + this.dir[0]*this._radius;
+      py = a[1] + this.dir[1]*this._radius;
+      pz = a[2] + this.dir[2]*this._radius;
+    } else {
+      px = this.pt[0]; py = this.pt[1]; pz = this.pt[2];
+    }
+    return rayHitSphere(ox,oy,oz, dx,dy,dz, px,py,pz, radius);
+  }
 }
 
 /**
@@ -3044,6 +3493,12 @@ function createConstraint(kind, opts) {
  *   eval(out)                    read the current { pos, rot } (zero-alloc, as Track.eval)
  *   home(pose?)                  re-home the integrated pose (NOT reset — no keyframes to clear)
  *
+ * Value layer (opt-in, §10): a per-helm `fullScale` keeps the read-outs honest
+ * across input scales; an opt-in `filter` (oneEuro) conditions the fed rates
+ * before the deadzone inside step; `poseDelta` differences two absolute poses
+ * into a feedable rate. With `filter` null and the default `fullScale`, the
+ * clean rate-native path is unchanged.
+ *
  * Quaternion algebra is provided by quat.js. Out-first throughout; no allocation
  * in feed/step/eval. Storage convention (matches the rest of the core): vec3 and
  * quat state are plain number[] (f64) — the same shape as track.js keyframes and
@@ -3076,6 +3531,23 @@ function createConstraint(kind, opts) {
 
 const _dq = [0, 0, 0, 1];
 
+// Scratch for the optional input filter (helm.filter). The fed rates are packed
+// into one 6-vector, conditioned, and unpacked to lin/ang triples before the
+// deadzone — so a single filter carries one state per helm. Shared across
+// instances (step is synchronous, at most once per helm per frame).
+const _f6raw = [0, 0, 0, 0, 0, 0];
+const _f6out = [0, 0, 0, 0, 0, 0];
+const _fLin  = [0, 0, 0];
+const _fAng  = [0, 0, 0];
+
+/**
+ * Default full-deflection input magnitude — the fed rate a read-out shows as
+ * full (the SpaceNavigator's saturated lane). Private to core: a transport on a
+ * different raw scale sets helm.fullScale and never reads this, so there is no
+ * public HELM_FULL export. Display-only; integration uses profile.sens directly.
+ */
+const HELM_FULL_SCALE = 500;
+
 // Deadzone gate — |v| > dz keeps v, else 0. Module-level so step allocates no
 // closure. Strictly-greater matches the e7 reference (rest reads exact 0).
 const _dz = (v, dz) => (v > dz || v < -dz) ? v : 0;
@@ -3128,6 +3600,24 @@ class PoseHelm {
      */
     this.deadzone = 8;
 
+    /**
+     * Full-deflection input magnitude for the read-outs (gizmo overlay + panel
+     * meters): a fed rate of |fullScale| reads as a full bar / arrow. Set by a
+     * transport whose saturated rate differs from the default (a gamepad stick
+     * that saturates at 1 sets fullScale = 1). Display-only — integration uses
+     * profile.sens directly, so this never affects flight. @type {number}
+     */
+    this.fullScale = HELM_FULL_SCALE;
+
+    /**
+     * Optional input conditioner applied to the fed rates BEFORE the deadzone,
+     * inside step — a oneEuro filter, or any f(out, raw, dt) carrying function
+     * with a reset(). null (the default) is the clean rate-native path: the
+     * filter branch is skipped, so a clean device pays nothing. Set for noisy /
+     * absolute sources; home() resets it. @type {?Function}
+     */
+    this.filter = null;
+
     /**
      * The space fed rates are interpreted in: a space constant (WORLD | EYE) or
      * a mat4 frame. Declarative only — the bridge reads this to resolve the
@@ -3189,7 +3679,22 @@ class PoseHelm {
    */
   step(out, dt, basis) {
     const p = this.profile, dz = this.deadzone;
-    const lin = this._lin, ang = this._ang;
+    let lin = this._lin, ang = this._ang;
+
+    // Value layer — condition the fed rates BEFORE the deadzone (the filter
+    // narrows the jitter band; the deadzone then gates the residual to exact
+    // zero). The filter carries state, so it is ticked exactly once per step;
+    // activity() reads the raw fed rate and is left unfiltered (the read-out
+    // shows device input, normalized by fullScale). Skipped when filter is null.
+    const filter = this.filter;
+    if (filter) {
+      _f6raw[0] = lin[0]; _f6raw[1] = lin[1]; _f6raw[2] = lin[2];
+      _f6raw[3] = ang[0]; _f6raw[4] = ang[1]; _f6raw[5] = ang[2];
+      filter(_f6out, _f6raw, dt);
+      _fLin[0] = _f6out[0]; _fLin[1] = _f6out[1]; _fLin[2] = _f6out[2];
+      _fAng[0] = _f6out[3]; _fAng[1] = _f6out[4]; _fAng[2] = _f6out[5];
+      lin = _fLin; ang = _fAng;
+    }
 
     // Basis axes (right / up / forward). No basis ⇒ the identity eye matrix:
     // right +X, up +Y, forward −Z. Forward is −col2 (an eye→world matrix stores
@@ -3288,10 +3793,76 @@ class PoseHelm {
     }
     this._lin[0] = this._lin[1] = this._lin[2] = 0;
     this._ang[0] = this._ang[1] = this._ang[2] = 0;
+    if (this.filter) this.filter.reset();   // drop filter state at the discontinuity
     return this;
   }
 }
 
+// =========================================================================
+// poseDelta — absolute pose → 6-DOF rate
+// =========================================================================
+
+/**
+ * Difference two consecutive absolute poses into a 6-DOF rate the helm can be
+ * fed — the bridge for absolute-pose transports (gesture / landmark / marker /
+ * IMU) into feed(lin, ang). Out-first, zero-allocation.
+ *
+ * Linear rate is (cur.pos − prev.pos) / dt. Angular rate is the world-frame
+ * angular velocity ω carrying prev.rot onto cur.rot over dt: the relative
+ * rotation r = cur · conj(prev) (so cur = r · prev, the world-frame compose the
+ * step integrates), read as axis · angle / dt.
+ *
+ * The double-cover guard is the whole reason to ship this rather than inline it:
+ * a quaternion and its negation are the same orientation, so when
+ * dot(prev.rot, cur.rot) < 0 the two samples sit on opposite hemispheres and a
+ * naive difference takes the long way round — the angular rate spikes at the
+ * crossing. Flipping cur into prev's hemisphere first keeps r the shortest arc.
+ *
+ * Fed through a helm in WORLD whose profile has unit `sens`, in-order lanes and
+ * `Tz` / `Rr` signs of −1 — the helm's lanes are eye-frame and the null basis
+ * is the identity eye matrix (forward −Z), so the two Z channels flip against
+ * world axes — the integrated pose retraces the source (the round-trip e9
+ * asserts). A 1:1, non-integrated consumer skips the helm and applyPoses the
+ * absolute pose directly.
+ *
+ * @param {{ lin:number[], ang:number[] }} [out]  Destination; omit for a fresh one.
+ * @param {{ pos:ArrayLike<number>, rot:ArrayLike<number> }} prev  Previous pose.
+ * @param {{ pos:ArrayLike<number>, rot:ArrayLike<number> }} cur   Current pose.
+ * @param {number} dt  Elapsed seconds between the two samples.
+ * @returns {{ lin:number[], ang:number[] }} out
+ */
+function poseDelta(out, prev, cur, dt) {
+  out = out || { lin: [0, 0, 0], ang: [0, 0, 0] };
+  const inv = 1 / dt;
+
+  out.lin[0] = (cur.pos[0] - prev.pos[0]) * inv;
+  out.lin[1] = (cur.pos[1] - prev.pos[1]) * inv;
+  out.lin[2] = (cur.pos[2] - prev.pos[2]) * inv;
+
+  const px = prev.rot[0], py = prev.rot[1], pz = prev.rot[2], pw = prev.rot[3];
+  let   cx = cur.rot[0],  cy = cur.rot[1],  cz = cur.rot[2],  cw = cur.rot[3];
+
+  // Double-cover guard: bring cur into prev's hemisphere so r is the short arc.
+  if (px * cx + py * cy + pz * cz + pw * cw < 0) { cx = -cx; cy = -cy; cz = -cz; cw = -cw; }
+
+  // Relative rotation r = cur · conj(prev), conj(prev) = (−px, −py, −pz, pw).
+  const rx = -cw * px + cx * pw - cy * pz + cz * py;
+  const ry = -cw * py + cx * pz + cy * pw - cz * px;
+  const rz = -cw * pz - cx * py + cy * px + cz * pw;
+  const rw =  cw * pw + cx * px + cy * py + cz * pz;   // = dot(prev, cur) ≥ 0 → angle ≤ π
+
+  // Axis · angle of r → ω = axis · angle / dt. Below the threshold the rotation
+  // is negligible (no well-defined axis) and the angular rate is exact zero.
+  const sinHalf = Math.sqrt(rx * rx + ry * ry + rz * rz);
+  if (sinHalf < 1e-8) {
+    out.ang[0] = 0; out.ang[1] = 0; out.ang[2] = 0;
+  } else {
+    const k = (2 * Math.atan2(sinHalf, rw)) * inv / sinHalf;
+    out.ang[0] = rx * k; out.ang[1] = ry * k; out.ang[2] = rz * k;
+  }
+  return out;
+}
+
 /**
  * @file Frustum planes and visibility tests — zero allocations.
  * @module tree/visibility
@@ -3451,5 +4022,1081 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   return allIn ? VISIBLE : SEMIVISIBLE;
 }
 
-export { AXIS, CameraTrack, Constraint, DIAL, DIRECTION, EYE, HELM_CHANNELS, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, POINT, PoseHelm, PoseTrack, SCREEN, SELF, SEMIVISIBLE, SPHERE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, azElFromDir, boxVisibility, createConstraint, dirFromAzEl, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4Eye, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Persp, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, mat4View, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qConjugate, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qFromUnitVectors, qMul, qNegate, qNlerp, qNormalize, qRotateVec3, qSet, qSlerp, qToAxisAngle, qToMat4, rayClosestPointOnAxis, rayPlane, raySphere, sphereVisibility, transformToMat4 };
+/**
+ * @file Camera state ↔ matrices: builders, decomposers, and in-place edits.
+ * @module tree/camera
+ * @license AGPL-3.0-only
+ *
+ * The camera is plain data — the CameraTrack keyframe shape:
+ *
+ *   cam = {
+ *     eye:        [x, y, z],       // position
+ *     center:     [x, y, z],       // lookat target; |center − eye| is the gaze distance
+ *     up:         [x, y, z],       // up hint, need not be unit
+ *     fov:        number | null,   // vertical field of view, radians — perspective
+ *     halfHeight: number | null,   // world-unit half-height at the near plane — orthographic
+ *     near:       number,          // > 0
+ *     far:        number,          // > near
+ *   }
+ *
+ * Exactly one of fov / halfHeight is meaningful; fov wins when both are set.
+ * With both null the lens is "unchanged": cameraProj and cameraPlanes return
+ * null and leave their output untouched, so a track that evaluates null into
+ * the state keeps the last projection installed. A track writes the state
+ * directly — `track.eval(cam)` — and a pose drives it through cameraFromPose.
+ *
+ * The state carries no aspect ratio — the viewport owns it — so one state is
+ * portable between targets of different sizes; every builder that needs it
+ * takes it as an argument.
+ *
+ * Vectors are plain number[] (f64, authoring state); matrices are written into
+ * whatever 16-element buffer the caller passes. createCamera is the one
+ * allocating call; everything else is out-first (or in-place) and zero-alloc.
+ *
+ * Every function that needs the camera frame derives it through mat4Eye, so
+ * planes and edits agree with cameraEye / cameraView exactly — including the
+ * up re-seed when the view direction is parallel to the up hint.
+ */
+
+
+const _E$1 = new Float64Array(16);   // eye→world frame scratch: right 0–2, up 4–6, back 8–10
+const _d = [0, 0, 0];              // view-direction scratch
+
+/** Eye→world frame of `cam` into `_E`. */
+function _frame(cam) {
+  const e = cam.eye, c = cam.center, u = cam.up;
+  mat4Eye(_E$1, e[0],e[1],e[2], c[0],c[1],c[2], u[0],u[1],u[2]);
+}
+
+/** Gaze distance |center − eye|, or 1 when the state is degenerate. */
+function _gaze(cam) {
+  const dx = cam.center[0]-cam.eye[0], dy = cam.center[1]-cam.eye[1], dz = cam.center[2]-cam.eye[2];
+  const d = Math.sqrt(dx*dx+dy*dy+dz*dz);
+  return d > 0 ? d : 1;
+}
+
+function _vec3(v, x, y, z) { return v != null ? [v[0], v[1], v[2]] : [x, y, z]; }
+
+// =========================================================================
+// State
+// =========================================================================
+
+/**
+ * Allocate a camera state — the one allocating call, setup-time.
+ * Defaults: eye [0, 0, 500], center [0, 0, 0], up [0, 1, 0], fov π/3,
+ * halfHeight null, near 0.1, far 1000. Passing halfHeight without fov yields
+ * an orthographic state (fov null).
+ *
+ * @param {{ eye?:number[], center?:number[], up?:number[], fov?:number|null,
+ *           halfHeight?:number|null, near?:number, far?:number }} [opts]
+ * @returns {{ eye:number[], center:number[], up:number[], fov:number|null,
+ *             halfHeight:number|null, near:number, far:number }}
+ */
+function createCamera(opts) {
+  const o = opts || {};
+  const ortho = o.halfHeight != null && o.fov === undefined;
+  return {
+    eye:        _vec3(o.eye,    0, 0, 500),
+    center:     _vec3(o.center, 0, 0, 0),
+    up:         _vec3(o.up,     0, 1, 0),
+    fov:        o.fov        !== undefined ? o.fov        : (ortho ? null : Math.PI / 3),
+    halfHeight: o.halfHeight !== undefined ? o.halfHeight : null,
+    near:       typeof o.near === 'number' ? o.near : 0.1,
+    far:        typeof o.far  === 'number' ? o.far  : 1000,
+  };
+}
+
+/**
+ * Copy one camera state into another (an orbit's home, a track's capture).
+ * @param {object} out  Destination state.
+ * @param {object} cam  Source state.
+ * @returns {object} out
+ */
+function cameraCopy(out, cam) {
+  out.eye[0]=cam.eye[0];       out.eye[1]=cam.eye[1];       out.eye[2]=cam.eye[2];
+  out.center[0]=cam.center[0]; out.center[1]=cam.center[1]; out.center[2]=cam.center[2];
+  out.up[0]=cam.up[0];         out.up[1]=cam.up[1];         out.up[2]=cam.up[2];
+  out.fov = cam.fov; out.halfHeight = cam.halfHeight;
+  out.near = cam.near; out.far = cam.far;
+  return out;
+}
+
+// =========================================================================
+// Builders — state → matrices
+// =========================================================================
+
+/**
+ * View matrix (world→eye) from the state's lookat.
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {object} cam
+ * @returns {Float32Array|number[]} out
+ */
+function cameraView(out, cam) {
+  const e = cam.eye, c = cam.center, u = cam.up;
+  return mat4View(out, e[0],e[1],e[2], c[0],c[1],c[2], u[0],u[1],u[2]);
+}
+
+/**
+ * Eye matrix (eye→world) from the state's lookat.
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {object} cam
+ * @returns {Float32Array|number[]} out
+ */
+function cameraEye(out, cam) {
+  const e = cam.eye, c = cam.center, u = cam.up;
+  return mat4Eye(out, e[0],e[1],e[2], c[0],c[1],c[2], u[0],u[1],u[2]);
+}
+
+/**
+ * Projection matrix from the state's lens: mat4Persp from fov, or mat4Ortho
+ * from halfHeight, with symmetric extents (top = near · tan(fov / 2) or
+ * halfHeight; right = top · aspect).
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {object} cam
+ * @param {number} aspect        Viewport width / height.
+ * @param {number} ndcZMin       WEBGL (−1) or WEBGPU (0).
+ * @param {number} [ndcYSign=1]  +1 NDC y-up; −1 NDC y-down.
+ * @returns {Float32Array|number[]|null} out, or null (out untouched) when
+ *          both fov and halfHeight are null.
+ */
+function cameraProj(out, cam, aspect, ndcZMin, ndcYSign = 1) {
+  const near = cam.near, far = cam.far;
+  if (cam.fov != null) {
+    const top = near * Math.tan(cam.fov / 2), right = top * aspect;
+    return mat4Persp(out, -right, right, -top, top, near, far, ndcZMin, ndcYSign);
+  }
+  if (cam.halfHeight != null) {
+    const top = cam.halfHeight, right = top * aspect;
+    return mat4Ortho(out, -right, right, -top, top, near, far, ndcZMin, ndcYSign);
+  }
+  return null;
+}
+
+/**
+ * The six frustum planes of the state, world space — frustumPlanes over the
+ * lookat basis and the symmetric extents cameraProj uses, so visibility tests
+ * run against a camera state without any matrix.
+ *
+ * @param {Float64Array} planes  24-element destination.
+ * @param {object} cam
+ * @param {number} aspect        Viewport width / height.
+ * @returns {Float64Array|null} planes, or null (planes untouched) when both
+ *          fov and halfHeight are null.
+ */
+function cameraPlanes(planes, cam, aspect) {
+  const ortho = cam.fov == null;
+  if (ortho && cam.halfHeight == null) return null;
+  const top = ortho ? cam.halfHeight : cam.near * Math.tan(cam.fov / 2), right = top * aspect;
+  _frame(cam);
+  const e = cam.eye;
+  return frustumPlanes(planes,
+    e[0], e[1], e[2],
+    -_E$1[8], -_E$1[9], -_E$1[10],
+    _E$1[4], _E$1[5], _E$1[6],
+    _E$1[0], _E$1[1], _E$1[2],
+    ortho, cam.near, cam.far, -right, right, top, -top);
+}
+
+// =========================================================================
+// Decomposers — matrices and poses → state
+// =========================================================================
+
+/**
+ * Read a state back from an eye matrix and a projection: eye ← column 3,
+ * up ← column 1, forward ← −column 2 of E; center ← eye + forward · d with d
+ * the state's current gaze distance (1 when degenerate), so the distance
+ * survives a round trip. The lens comes from the projection queries: fov or
+ * halfHeight by projIsOrtho, near and far under `ndcZMin`.
+ *
+ * @param {object} cam                 State written in place.
+ * @param {ArrayLike<number>} E        Eye matrix (eye→world), 16 elements.
+ * @param {ArrayLike<number>} P        Projection matrix, 16 elements.
+ * @param {number} ndcZMin             WEBGL (−1) or WEBGPU (0).
+ * @returns {object} cam
+ */
+function cameraFromMat4(cam, E, P, ndcZMin) {
+  const d = _gaze(cam);
+  let fx = -E[8], fy = -E[9], fz = -E[10];
+  const fl = Math.sqrt(fx*fx+fy*fy+fz*fz) || 1;
+  fx /= fl; fy /= fl; fz /= fl;
+  cam.eye[0]=E[12]; cam.eye[1]=E[13]; cam.eye[2]=E[14];
+  cam.up[0]=E[4];   cam.up[1]=E[5];   cam.up[2]=E[6];
+  cam.center[0]=cam.eye[0]+fx*d; cam.center[1]=cam.eye[1]+fy*d; cam.center[2]=cam.eye[2]+fz*d;
+  if (projIsOrtho(P)) { cam.fov = null;       cam.halfHeight = projTop(P, ndcZMin); }
+  else                { cam.fov = projFov(P); cam.halfHeight = null; }
+  cam.near = projNear(P, ndcZMin);
+  cam.far  = projFar(P);
+  return cam;
+}
+
+/**
+ * Drive the lookat from a TRS pose: eye ← pos, up and forward from the
+ * rotation's columns 1 and −2, center ← eye + forward · d with d the current
+ * gaze distance (1 when degenerate). The lens is untouched; `scl` is ignored.
+ *
+ * @param {object} cam                            State written in place.
+ * @param {{ pos:number[], rot:number[] }} pose   rot is a unit quaternion [x,y,z,w].
+ * @returns {object} cam
+ */
+function cameraFromPose(cam, pose) {
+  const d = _gaze(cam);
+  const q = pose.rot, 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;
+  const ux=xy-wz, uy=1-(xx+zz), uz=yz+wx;        // column 1 of qToMat4(rot): up
+  const bx=xz+wy, by=yz-wx, bz=1-(xx+yy);        // column 2: back
+  cam.eye[0]=pose.pos[0]; cam.eye[1]=pose.pos[1]; cam.eye[2]=pose.pos[2];
+  cam.up[0]=ux; cam.up[1]=uy; cam.up[2]=uz;
+  cam.center[0]=cam.eye[0]-bx*d; cam.center[1]=cam.eye[1]-by*d; cam.center[2]=cam.eye[2]-bz*d;
+  return cam;
+}
+
+/**
+ * The lookat as a TRS pose: pos ← eye, rot ← qFromLookDir(center − eye, up) —
+ * the rotation of cameraEye, so a helm seeded from it continues the frame.
+ *
+ * @param {{ pos:number[], rot:number[] }} pose  Written in place.
+ * @param {object} cam
+ * @returns {{ pos:number[], rot:number[] }} pose
+ */
+function cameraToPose(pose, cam) {
+  pose.pos[0]=cam.eye[0]; pose.pos[1]=cam.eye[1]; pose.pos[2]=cam.eye[2];
+  _d[0]=cam.center[0]-cam.eye[0]; _d[1]=cam.center[1]-cam.eye[1]; _d[2]=cam.center[2]-cam.eye[2];
+  qFromLookDir(pose.rot, _d, cam.up);
+  return pose;
+}
+
+// =========================================================================
+// Edits — in place, chainable, zero-alloc
+// =========================================================================
+
+/**
+ * Orbit the eye about the center: `dAz` rotates it about the up hint
+ * (right-handed); `dEl` raises its elevation above the plane through the
+ * center perpendicular to the hint, clamped to ±opts.maxEl so the view
+ * direction never reaches the hint (the pole guard). `up` is left as the hint
+ * it was, so an orbit never rolls. A state already at the pole is pulled
+ * inside the guard by its first non-zero edit; (0, 0) is a no-op.
+ *
+ * @param {object} cam
+ * @param {number} dAz  Azimuth delta, radians.
+ * @param {number} dEl  Elevation delta, radians.
+ * @param {{ maxEl?:number }} [opts]  Elevation limit; default π/2 − 1e-3.
+ * @returns {object} cam
+ */
+function cameraOrbit(cam, dAz, dEl, opts) {
+  if (dAz === 0 && dEl === 0) return cam;
+  const maxEl = opts && typeof opts.maxEl === 'number' ? opts.maxEl : Math.PI / 2 - 1e-3;
+  const e = cam.eye, c = cam.center;
+  let ux=cam.up[0], uy=cam.up[1], uz=cam.up[2];
+  const ul = Math.sqrt(ux*ux+uy*uy+uz*uz) || 1;
+  ux/=ul; uy/=ul; uz/=ul;
+  const dx=e[0]-c[0], dy=e[1]-c[1], dz=e[2]-c[2];
+  const r = Math.sqrt(dx*dx+dy*dy+dz*dz);
+  _frame(cam);
+  const px=_E$1[4], py=_E$1[5], pz=_E$1[6];            // the eye's up
+  const bx=_E$1[8], by=_E$1[9], bz=_E$1[10];           // back: center → eye, unit
+  // elevation: raise by θ within the (back, up) plane, clamped
+  const el  = Math.asin(Math.max(-1, Math.min(1, bx*ux+by*uy+bz*uz)));
+  const th  = Math.max(-maxEl, Math.min(maxEl, el + dEl)) - el;
+  const ct = Math.cos(th), st = Math.sin(th);
+  const ox = r*(bx*ct+px*st), oy = r*(by*ct+py*st), oz = r*(bz*ct+pz*st);
+  // azimuth: rotate about the hint (Rodrigues)
+  const ca = Math.cos(dAz), sa = Math.sin(dAz), k = (ux*ox+uy*oy+uz*oz)*(1-ca);
+  e[0] = c[0] + ox*ca + (uy*oz-uz*oy)*sa + ux*k;
+  e[1] = c[1] + oy*ca + (uz*ox-ux*oz)*sa + uy*k;
+  e[2] = c[2] + oz*ca + (ux*oy-uy*ox)*sa + uz*k;
+  return cam;
+}
+
+/**
+ * Dolly: scale the gaze distance by `factor` — the eye moves along the view
+ * direction under perspective; under orthographic (fov null, halfHeight set)
+ * halfHeight is scaled instead, since moving the eye changes nothing on
+ * screen. opts.min / opts.max clamp the scaled quantity. An edit that would
+ * make it non-positive is a no-op.
+ *
+ * @param {object} cam
+ * @param {number} factor
+ * @param {{ min?:number, max?:number }} [opts]
+ * @returns {object} cam
+ */
+function cameraDolly(cam, factor, opts) {
+  const min = opts && typeof opts.min === 'number' ? opts.min : 0;
+  const max = opts && typeof opts.max === 'number' ? opts.max : Infinity;
+  if (cam.fov == null && cam.halfHeight != null) {
+    const h = Math.max(min, Math.min(max, cam.halfHeight * factor));
+    if (h > 0) cam.halfHeight = h;
+    return cam;
+  }
+  const e = cam.eye, c = cam.center;
+  const dx=e[0]-c[0], dy=e[1]-c[1], dz=e[2]-c[2];
+  const r = Math.sqrt(dx*dx+dy*dy+dz*dz);
+  if (r === 0) return cam;
+  const r1 = Math.max(min, Math.min(max, r * factor));
+  if (!(r1 > 0)) return cam;
+  const s = r1 / r;
+  e[0]=c[0]+dx*s; e[1]=c[1]+dy*s; e[2]=c[2]+dz*s;
+  return cam;
+}
+
+/**
+ * Pan: translate eye and center by `dx` along the eye's right and `dy` along
+ * its up, world units. The caller converts pixels through pixelRatio at the
+ * center's depth so a pan tracks the pointer.
+ *
+ * @param {object} cam
+ * @param {number} dx
+ * @param {number} dy
+ * @returns {object} cam
+ */
+function cameraPan(cam, dx, dy) {
+  _frame(cam);
+  const tx=_E$1[0]*dx+_E$1[4]*dy, ty=_E$1[1]*dx+_E$1[5]*dy, tz=_E$1[2]*dx+_E$1[6]*dy;
+  const e = cam.eye, c = cam.center;
+  e[0]+=tx; e[1]+=ty; e[2]+=tz;
+  c[0]+=tx; c[1]+=ty; c[2]+=tz;
+  return cam;
+}
+
+/**
+ * @file Gizmo line generators in the arrays shape.
+ * @module tree/gizmo
+ * @license AGPL-3.0-only
+ *
+ * A gizmo is geometry that explains: axes, a grid, a frustum, a path, a rig,
+ * a handle's locus. This module generates its vertices — renderer-free, into
+ * caller-owned arrays shaped the way twgl's createBufferInfoFromArrays
+ * consumes them and a WebGPU vertex buffer is filled from — and nothing
+ * else. Drawing, colour state, HUD mode, textures, the dot at a handle's
+ * point, text: all the bridge's or the host's.
+ *
+ * ── The arrays shape ───────────────────────────────────────────────────────
+ *
+ *   out = {
+ *     position: { numComponents: 3, data: Float32Array(3 · capacity) },
+ *     color:    { numComponents: 4, data: Float32Array(4 · capacity) },   // optional
+ *     texcoord: { numComponents: 2, data: Float32Array(2 · capacity) },   // optional — panes
+ *     count:    0,                                                        // vertices written
+ *     labels:   [],                                                       // optional — { x, y, z, text }
+ *   }
+ *
+ * Line generators write line lists — vertex pairs, no indices; paneTris
+ * writes two triangles. capacity is position.data.length / 3.
+ *
+ * ── The contract — snprintf-style ──────────────────────────────────────────
+ * Every generator gen(out, …) → n returns the vertex count it needs, writes
+ * min(n, capacity) vertices, and sets out.count to what it wrote. A caller
+ * sizes once and grows never in steady state:
+ *
+ *   let n = axesLines(out, opts)
+ *   if (n > capacityOf(out)) { growArrays(out, n); axesLines(out, opts) }
+ *
+ * Each generator states its count formula so a caller can pre-size exactly.
+ *
+ * ── Colour ─────────────────────────────────────────────────────────────────
+ * If out.color exists, every vertex written gets a colour: a generator with
+ * semantic colouring (axes, the helm rig) writes its palette, every other
+ * generator writes opts.color (default white). If out.color is absent
+ * nothing is written and the bridge draws with a uniform colour.
+ *
+ * ── Frames ─────────────────────────────────────────────────────────────────
+ * A generator writes in the frame the caller means — model space for scene
+ * gizmos (the bridge's M places them), screen pixels for HUD gizmos.
+ * Nothing here consults a camera except locusLines and frustumLines, which
+ * take what they need explicitly. Signatures: out first, the subject second
+ * where there is one, options last.
+ */
+
+
+const TWO_PI = Math.PI * 2;
+const _AXIS_COLORS = [COLOR_X, COLOR_Y, COLOR_Z];
+const _U = [1, 0, 0], _V = [0, 1, 0];          // the HUD plane's basis
+const _E   = new Float64Array(16);             // a camera state's eye matrix
+const _p3  = [0, 0, 0];                        // a transformed corner / a sampled point
+const _q3  = [0, 0, 0];                        // the previous sampled point
+const _c24 = new Float64Array(24);             // frustum corners scratch
+const _tIn = [0, 0, 0], _tOut = [0, 0, 0];     // a keyframe's tangents
+const _act = [0, 0, 0, 0, 0, 0];               // a helm's activity
+const _tip = [0, 0, 0], _ha = [0, 0, 0];       // an arrow's tip and head base
+const _AXES = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+const _b0 = [0, 0, 0], _b1 = [0, 0, 0], _b2 = [0, 0, 0];   // a locus basis
+const _UV_DEFAULT = [0, 1, 1, 1, 1, 0, 0, 0];  // paneTris: p0 top-left → (0, 1), clockwise
+
+// =========================================================================
+// G1  Arrays — the one allocating call, growth, capacity
+// =========================================================================
+
+/**
+ * Allocate an arrays object of `capacity` vertices — the one allocating
+ * call, setup-time. Flags add the optional attributes and the label list.
+ *
+ * @param {number} capacity  Vertices.
+ * @param {{ color?:boolean, texcoord?:boolean, labels?:boolean }} [opts]
+ * @returns {{ position:{numComponents:number,data:Float32Array},
+ *             color?:{numComponents:number,data:Float32Array},
+ *             texcoord?:{numComponents:number,data:Float32Array},
+ *             count:number, labels?:object[] }}
+ */
+function createArrays(capacity, opts) {
+  const o = opts || {};
+  const n = Math.max(0, capacity | 0);
+  const out = { position: { numComponents: 3, data: new Float32Array(3 * n) } };
+  if (o.color)    out.color    = { numComponents: 4, data: new Float32Array(4 * n) };
+  if (o.texcoord) out.texcoord = { numComponents: 2, data: new Float32Array(2 * n) };
+  out.count = 0;
+  if (o.labels) out.labels = [];
+  return out;
+}
+
+/**
+ * Reallocate an arrays object to a new capacity, keeping its attribute set;
+ * the data is fresh (a generator refills it) and count is 0.
+ *
+ * @param {object} out       An arrays object from createArrays.
+ * @param {number} capacity  Vertices.
+ * @returns {object} out
+ */
+function growArrays(out, capacity) {
+  const n = Math.max(0, capacity | 0);
+  out.position.data = new Float32Array(3 * n);
+  if (out.color)    out.color.data    = new Float32Array(4 * n);
+  if (out.texcoord) out.texcoord.data = new Float32Array(2 * n);
+  out.count = 0;
+  if (out.labels) out.labels.length = 0;
+  return out;
+}
+
+/**
+ * The vertex capacity of an arrays object: position.data.length / 3.
+ * @param {object} out
+ * @returns {number}
+ */
+function capacityOf(out) {
+  return (out.position.data.length / 3) | 0;
+}
+
+// =========================================================================
+// G2  The writer — a cursor over out; counts every vertex, writes those
+//     within capacity. Module-level scratch: a generator runs to completion.
+// =========================================================================
+
+const _w = { pos: null, col: null, tex: null, cap: 0, n: 0, r: 1, g: 1, b: 1, a: 1 };
+const _WHITE = [1, 1, 1, 1];
+
+function _begin(out) {
+  _w.pos = out.position.data;
+  _w.col = out.color ? out.color.data : null;
+  _w.tex = out.texcoord ? out.texcoord.data : null;
+  _w.cap = (_w.pos.length / 3) | 0;
+  _w.n = 0;
+  if (out.labels) out.labels.length = 0;
+}
+
+/** Set the current colour from an RGB(A) array, with an alpha override. */
+function _color(c, alpha) {
+  const v = c || _WHITE;
+  _w.r = v[0]; _w.g = v[1]; _w.b = v[2];
+  _w.a = alpha != null ? alpha : (v.length > 3 ? v[3] : 1);
+}
+
+function _vertex(x, y, z) {
+  const n = _w.n++;
+  if (n >= _w.cap) return;
+  const p = _w.pos, i = 3 * n;
+  p[i] = x; p[i + 1] = y; p[i + 2] = z;
+  const c = _w.col;
+  if (c) { const j = 4 * n; c[j] = _w.r; c[j + 1] = _w.g; c[j + 2] = _w.b; c[j + 3] = _w.a; }
+}
+
+function _line(x0, y0, z0, x1, y1, z1) {
+  _vertex(x0, y0, z0);
+  _vertex(x1, y1, z1);
+}
+
+/** A vertex with a texture coordinate (written when out.texcoord exists). */
+function _vertexUV(x, y, z, u, v) {
+  const n = _w.n;
+  _vertex(x, y, z);
+  if (_w.tex && n < _w.cap) { _w.tex[2*n] = u; _w.tex[2*n + 1] = v; }
+}
+
+/** Normalise v in place; a zero vector becomes (dx, dy, dz). */
+function _unit(v, dx, dy, dz) {
+  const l = Math.sqrt(v[0]*v[0] + v[1]*v[1] + v[2]*v[2]);
+  if (l < 1e-9) { v[0] = dx; v[1] = dy; v[2] = dz; return v; }
+  v[0] /= l; v[1] /= l; v[2] /= l;
+  return v;
+}
+
+/** Orthonormal in-plane basis (ub, vb) for a unit normal n, seeded from the least-aligned axis. */
+function _basis(n, ub, vb) {
+  const ax = Math.abs(n[0]), ay = Math.abs(n[1]), az = Math.abs(n[2]);
+  let rx = 0, ry = 0, rz = 0;
+  if (ax <= ay && ax <= az) rx = 1; else if (ay <= az) ry = 1; else rz = 1;
+  ub[0] = ry*n[2] - rz*n[1]; ub[1] = rz*n[0] - rx*n[2]; ub[2] = rx*n[1] - ry*n[0];
+  _unit(ub, 1, 0, 0);
+  vb[0] = n[1]*ub[2] - n[2]*ub[1]; vb[1] = n[2]*ub[0] - n[0]*ub[2]; vb[2] = n[0]*ub[1] - n[1]*ub[0];
+}
+
+/** The four edges of a square of half-extent h at c, spanned by u, v. */
+function _square(c, u, v, h) {
+  const x0 = c[0] - h*u[0] - h*v[0], y0 = c[1] - h*u[1] - h*v[1], z0 = c[2] - h*u[2] - h*v[2];
+  const x1 = c[0] + h*u[0] - h*v[0], y1 = c[1] + h*u[1] - h*v[1], z1 = c[2] + h*u[2] - h*v[2];
+  const x2 = c[0] + h*u[0] + h*v[0], y2 = c[1] + h*u[1] + h*v[1], z2 = c[2] + h*u[2] + h*v[2];
+  const x3 = c[0] - h*u[0] + h*v[0], y3 = c[1] - h*u[1] + h*v[1], z3 = c[2] - h*u[2] + h*v[2];
+  _line(x0, y0, z0, x1, y1, z1);
+  _line(x1, y1, z1, x2, y2, z2);
+  _line(x2, y2, z2, x3, y3, z3);
+  _line(x3, y3, z3, x0, y0, z0);
+}
+
+/** Close the write: count ← what fits; return what was needed. */
+function _end(out) {
+  out.count = _w.n < _w.cap ? _w.n : _w.cap;
+  return _w.n;
+}
+
+/** A sampled circle (or arc of `sweep`) of radius r at c, spanned by u, v: n segments. */
+function _ring(cx, cy, cz, r, u, v, n, sweep) {
+  let px = 0, py = 0, pz = 0;
+  for (let i = 0; i <= n; i++) {
+    const t = (i / n) * sweep;
+    const ct = Math.cos(t) * r, st = Math.sin(t) * r;
+    const x = cx + ct*u[0] + st*v[0];
+    const y = cy + ct*u[1] + st*v[1];
+    const z = cz + ct*u[2] + st*v[2];
+    if (i > 0) _line(px, py, pz, x, y, z);
+    px = x; py = y; pz = z;
+  }
+}
+
+// =========================================================================
+// G3  Axes, grid, cross, bulls-eye, ring
+// =========================================================================
+
+/**
+ * A coordinate frame at the origin: six half-axes by bit and, with LABELS,
+ * the X (2 lines) · Y (4) · Z (3) glyphs at 1.04 · size, sized size / 40 ×
+ * size / 30. Semantic colour per axis and its glyph (COLOR_X / Y / Z), or
+ * opts.color when `semantic` is false.
+ *
+ * Count: 2 · axes + 18 · (LABELS ? 1 : 0), at most 30.
+ *
+ * @param {object} out  Arrays object.
+ * @param {{ size?:number, bits?:number, semantic?:boolean, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function axesLines(out, opts) {
+  const o = opts || {};
+  const size = o.size ?? 100;
+  const bits = o.bits ?? (LABELS | X | Y | Z);
+  const semantic = o.semantic !== false;
+  const axis = (i) => _color(semantic ? _AXIS_COLORS[i] : o.color);
+  _begin(out);
+  if (bits & LABELS) {
+    const cw = size/40, ch = size/30, cs = 1.04*size;
+    axis(0);
+    _line(cs,  cw, -ch, cs, -cw,  ch);
+    _line(cs, -cw, -ch, cs,  cw,  ch);
+    axis(1);
+    _line( cw, cs,  ch,  0, cs,   0);
+    _line(  0, cs,   0, -cw, cs,  ch);
+    _line(-cw, cs,  ch,  0, cs,   0);
+    _line(  0, cs,   0,  0, cs, -ch);
+    axis(2);
+    _line(-cw, -ch, cs,  cw, -ch, cs);
+    _line( cw, -ch, cs, -cw,  ch, cs);
+    _line(-cw,  ch, cs,  cw,  ch, cs);
+  }
+  axis(0);
+  if (bits & X)  _line(0, 0, 0,  size, 0, 0);
+  if (bits & _X) _line(0, 0, 0, -size, 0, 0);
+  axis(1);
+  if (bits & Y)  _line(0, 0, 0, 0,  size, 0);
+  if (bits & _Y) _line(0, 0, 0, 0, -size, 0);
+  axis(2);
+  if (bits & Z)  _line(0, 0, 0, 0, 0,  size);
+  if (bits & _Z) _line(0, 0, 0, 0, 0, -size);
+  return _end(out);
+}
+
+/**
+ * A grid in the XY plane: subdivisions + 1 lines each way spanning ±size.
+ * Orientation is the caller's M (a ground plane is a rotation about X).
+ *
+ * Count: 4 · (subdivisions + 1).
+ *
+ * @param {object} out  Arrays object.
+ * @param {{ size?:number, subdivisions?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function gridLines(out, opts) {
+  const o = opts || {};
+  const size = o.size ?? 100;
+  const sub = Math.max(1, (o.subdivisions ?? 10) | 0);
+  _begin(out);
+  _color(o.color);
+  for (let i = 0; i <= sub; i++) {
+    const pos = size * (2*i/sub - 1);
+    _line(pos, -size, 0, pos, size, 0);
+    _line(-size, pos, 0, size, pos, 0);
+  }
+  return _end(out);
+}
+
+/**
+ * A crosshair in HUD space (z = 0, target pixels): two lines of `size`
+ * through (x, y). The bridge projects a model origin and converts a world
+ * size to pixels before this call.
+ *
+ * Count: 4.
+ *
+ * @param {object} out  Arrays object.
+ * @param {{ x?:number, y?:number, size?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function crossLines(out, opts) {
+  const o = opts || {};
+  const x = o.x ?? 0, y = o.y ?? 0, half = (o.size ?? 50) / 2;
+  _begin(out);
+  _color(o.color);
+  _line(x - half, y, 0, x + half, y, 0);
+  _line(x, y - half, 0, x, y + half, 0);
+  return _end(out);
+}
+
+/**
+ * A bulls-eye in HUD space (z = 0, target pixels): a sampled circle of
+ * radius size / 2 (`detail` segments) or the cornered square (8 lines),
+ * plus the central cross at 0.6 · half.
+ *
+ * Count: 2 · detail + 4 (CIRCLE) or 20 (SQUARE).
+ *
+ * @param {object} out  Arrays object.
+ * @param {{ x?:number, y?:number, size?:number, shape?:number, detail?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function bullsEyeLines(out, opts) {
+  const o = opts || {};
+  const x = o.x ?? 0, y = o.y ?? 0, half = (o.size ?? 50) / 2;
+  const shape = o.shape ?? CIRCLE;
+  const detail = Math.max(3, (o.detail ?? 50) | 0);
+  _begin(out);
+  _color(o.color);
+  if (shape === CIRCLE) {
+    _ring(x, y, 0, half, _U, _V, detail, TWO_PI);
+  } else {
+    const c = 0.6 * half;
+    _line(x-half, y-half+c, 0, x-half, y-half, 0);
+    _line(x-half, y-half, 0, x-half+c, y-half, 0);
+    _line(x+half-c, y-half, 0, x+half, y-half, 0);
+    _line(x+half, y-half, 0, x+half, y-half+c, 0);
+    _line(x+half, y+half-c, 0, x+half, y+half, 0);
+    _line(x+half, y+half, 0, x+half-c, y+half, 0);
+    _line(x-half+c, y+half, 0, x-half, y+half, 0);
+    _line(x-half, y+half, 0, x-half, y+half-c, 0);
+  }
+  const ch = 0.6 * half;
+  _line(x - ch, y, 0, x + ch, y, 0);
+  _line(x, y - ch, 0, x, y + ch, 0);
+  return _end(out);
+}
+
+/**
+ * A sampled circle of radius r at (cx, cy, cz) spanned by the orthonormal
+ * u, v — the shared primitive; a partial `sweep` gives an arc from u.
+ *
+ * Count: 2 · detail.
+ *
+ * @param {object} out  Arrays object.
+ * @param {number} cx,cy,cz  Centre.
+ * @param {number} r         Radius.
+ * @param {number[]} u,v     Orthonormal in-plane basis.
+ * @param {{ detail?:number, sweep?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function ringLines(out, cx, cy, cz, r, u, v, opts) {
+  const o = opts || {};
+  const detail = Math.max(1, (o.detail ?? 48) | 0);
+  const sweep = o.sweep ?? TWO_PI;
+  _begin(out);
+  _color(o.color);
+  _ring(cx, cy, cz, r, u, v, detail, sweep);
+  return _end(out);
+}
+
+// =========================================================================
+// G4  Frustum and Hermite
+// =========================================================================
+
+const _isMat = (cam) => cam != null && cam.mat4Eye != null && cam.mat4Proj != null;
+
+/** Corner i of out24 ← E · (x, y, z). */
+function _corner(out24, i, E, x, y, z) {
+  mat4MulPoint(_p3, E, x, y, z);
+  out24[3*i] = _p3[0]; out24[3*i + 1] = _p3[1]; out24[3*i + 2] = _p3[2];
+}
+
+/**
+ * The eight world-space corners of a camera's frustum: the near face 0–3
+ * counter-clockwise from bottom-left (BL, BR, TR, TL), then the far face
+ * 4–7 in the same order — so corners 3, 2, 1, 0 are a pane's TL, TR, BR,
+ * BL. `cam` is a camera state (its symmetric extents from fov or
+ * halfHeight and `aspect`), or { mat4Eye, mat4Proj, ndcZMin? } for a
+ * matrix-captured camera (the extents read off the projection). The far
+ * extents follow by similar triangles, or equal the near ones under
+ * orthographic.
+ *
+ * @param {Float64Array|number[]} out24  24-element destination.
+ * @param {object} cam       Camera state, or { mat4Eye, mat4Proj, ndcZMin? }.
+ * @param {number} [aspect=1]  Viewport width / height (state form).
+ * @param {number} [ndcZMin=WEBGL]  NDC-z convention when the matrix form carries none.
+ * @returns {Float64Array|number[]|null} out24, or null when the state's lens is unset.
+ */
+function frustumCorners(out24, cam, aspect, ndcZMin) {
+  let E, n, f, l, r, t, b, ortho;
+  if (_isMat(cam)) {
+    E = cam.mat4Eye;
+    const P = cam.mat4Proj, z = cam.ndcZMin ?? ndcZMin ?? WEBGL;
+    ortho = projIsOrtho(P);
+    n = projNear(P, z); f = projFar(P);
+    l = projLeft(P, z); r = projRight(P, z); t = projTop(P, z); b = projBottom(P, z);
+  } else {
+    ortho = cam.fov == null;
+    if (ortho && cam.halfHeight == null) return null;
+    n = cam.near; f = cam.far;
+    t = ortho ? cam.halfHeight : n * Math.tan(cam.fov / 2);
+    r = t * (aspect ?? 1);
+    b = -t; l = -r;
+    E = cameraEye(_E, cam);
+  }
+  const k = ortho ? 1 : f / n;
+  _corner(out24, 0, E,   l,   b, -n);
+  _corner(out24, 1, E,   r,   b, -n);
+  _corner(out24, 2, E,   r,   t, -n);
+  _corner(out24, 3, E,   l,   t, -n);
+  _corner(out24, 4, E, k*l, k*b, -f);
+  _corner(out24, 5, E, k*r, k*b, -f);
+  _corner(out24, 6, E, k*r, k*t, -f);
+  _corner(out24, 7, E, k*l, k*t, -f);
+  return out24;
+}
+
+/** Line between corners i and j of the scratch corners. */
+function _edge(i, j) {
+  _line(_c24[3*i], _c24[3*i + 1], _c24[3*i + 2], _c24[3*j], _c24[3*j + 1], _c24[3*j + 2]);
+}
+
+/**
+ * A camera's frustum as edges by bit: NEAR and FAR the two rectangles,
+ * BODY the four edges joining them, APEX (perspective only) the eye to
+ * the near corners. `cam` as frustumCorners takes it.
+ *
+ * Count: 8 · (NEAR + FAR + BODY + APEX), at most 32.
+ *
+ * @param {object} out  Arrays object.
+ * @param {object} cam  Camera state, or { mat4Eye, mat4Proj, ndcZMin? }.
+ * @param {{ aspect?:number, ndcZMin?:number, bits?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed (0 when the state's lens is unset).
+ */
+function frustumLines(out, cam, opts) {
+  const o = opts || {};
+  const bits = o.bits ?? (NEAR | FAR | BODY | APEX);
+  _begin(out);
+  _color(o.color);
+  if (frustumCorners(_c24, cam, o.aspect ?? 1, o.ndcZMin ?? WEBGL) === null) return _end(out);
+  if (bits & NEAR) { _edge(0, 1); _edge(1, 2); _edge(2, 3); _edge(3, 0); }
+  if (bits & FAR)  { _edge(4, 5); _edge(5, 6); _edge(6, 7); _edge(7, 4); }
+  if (bits & BODY) { _edge(0, 4); _edge(1, 5); _edge(2, 6); _edge(3, 7); }
+  const persp = _isMat(cam) ? !projIsOrtho(cam.mat4Proj) : cam.fov != null;
+  if ((bits & APEX) && persp) {
+    const E = _isMat(cam) ? cam.mat4Eye : null;
+    const ex = E ? E[12] : cam.eye[0], ey = E ? E[13] : cam.eye[1], ez = E ? E[14] : cam.eye[2];
+    for (let i = 0; i < 4; i++) _line(ex, ey, ez, _c24[3*i], _c24[3*i + 1], _c24[3*i + 2]);
+  }
+  return _end(out);
+}
+
+/**
+ * One cubic Hermite segment through hermiteVec3, as a polyline of
+ * `samples` steps.
+ *
+ * Count: 2 · samples.
+ *
+ * @param {object} out  Arrays object.
+ * @param {number[]} p0,t0  Start point and its outgoing tangent.
+ * @param {number[]} p1,t1  End point and its incoming tangent.
+ * @param {{ samples?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function hermiteLines(out, p0, t0, p1, t1, opts) {
+  const o = opts || {};
+  const N = Math.max(1, (o.samples ?? 32) | 0);
+  _begin(out);
+  _color(o.color);
+  for (let i = 0; i <= N; i++) {
+    hermiteVec3(_p3, p0, t0, p1, t1, i / N);
+    if (i > 0) _line(_q3[0], _q3[1], _q3[2], _p3[0], _p3[1], _p3[2]);
+    _q3[0] = _p3[0]; _q3[1] = _p3[1]; _q3[2] = _p3[2];
+  }
+  return _end(out);
+}
+
+// =========================================================================
+// G5  Path, helm rig, locus, pane
+// =========================================================================
+
+/**
+ * A PoseTrack or CameraTrack's path by bit, over the track's own samplers
+ * (samplePos / sampleEye / sampleCenter and the tangent readers), so the
+ * interpolation modes are honoured: PATH the sampled polyline, `samples`
+ * per segment; CONTROLS the straight control polygon; TANGENTS_IN /
+ * TANGENTS_OUT the tangent at each keyframe scaled by `tangentScale`;
+ * CENTER (camera tracks) the gaze line eye → center per keyframe and a
+ * three-axis star of half-size `centerSize` at the center. `target`
+ * ('eye' or 'center') picks a camera track's path for the first three
+ * bits. Markers and handles are the bridge's composition.
+ *
+ * Count: 2 · samples · segments (PATH) + 2 · segments (CONTROLS) +
+ * 2 · keyframes per tangent bit + 8 · keyframes (CENTER).
+ *
+ * @param {object} out    Arrays object.
+ * @param {object} track  PoseTrack or CameraTrack.
+ * @param {{ bits?:number, samples?:number, tangentScale?:number, target?:string,
+ *           centerSize?:number, color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function pathLines(out, track, opts) {
+  const o = opts || {};
+  const bits = o.bits ?? (PATH | CONTROLS | TANGENTS_IN | TANGENTS_OUT);
+  const N = Math.max(1, (o.samples ?? 32) | 0);
+  const ts = o.tangentScale ?? 0.25;
+  const cs = o.centerSize ?? 4;
+  const kfs = track.keyframes, n = kfs.length;
+  const isCamera = typeof track.sampleEye === 'function';
+  const useCenter = isCamera && o.target === 'center';
+  const field    = isCamera ? (useCenter ? 'center'         : 'eye')         : 'pos';
+  const sampler  = isCamera ? (useCenter ? 'sampleCenter'   : 'sampleEye')   : 'samplePos';
+  const tangents = isCamera ? (useCenter ? 'centerTangents' : 'eyeTangents') : 'tangents';
+  _begin(out);
+  _color(o.color);
+  if ((bits & PATH) && n > 1) {
+    for (let seg = 0; seg < n - 1; seg++) {
+      for (let i = 0; i <= N; i++) {
+        track[sampler](_p3, seg, i / N);
+        if (i > 0) _line(_q3[0], _q3[1], _q3[2], _p3[0], _p3[1], _p3[2]);
+        _q3[0] = _p3[0]; _q3[1] = _p3[1]; _q3[2] = _p3[2];
+      }
+    }
+  }
+  if (bits & CONTROLS) {
+    for (let i = 0; i < n - 1; i++) {
+      const a = kfs[i][field], b = kfs[i + 1][field];
+      _line(a[0], a[1], a[2], b[0], b[1], b[2]);
+    }
+  }
+  if (bits & (TANGENTS_IN | TANGENTS_OUT)) {
+    for (let i = 0; i < n; i++) {
+      track[tangents](_tIn, _tOut, i);
+      const k = kfs[i][field];
+      if (bits & TANGENTS_IN)  _line(k[0] - ts*_tIn[0], k[1] - ts*_tIn[1], k[2] - ts*_tIn[2], k[0], k[1], k[2]);
+      if (bits & TANGENTS_OUT) _line(k[0], k[1], k[2], k[0] + ts*_tOut[0], k[1] + ts*_tOut[1], k[2] + ts*_tOut[2]);
+    }
+  }
+  if ((bits & CENTER) && isCamera) {
+    for (let i = 0; i < n; i++) {
+      const e = kfs[i].eye, c = kfs[i].center;
+      _line(e[0], e[1], e[2], c[0], c[1], c[2]);
+      _line(c[0] - cs, c[1], c[2], c[0] + cs, c[1], c[2]);
+      _line(c[0], c[1] - cs, c[2], c[0], c[1] + cs, c[2]);
+      _line(c[0], c[1], c[2] - cs, c[0], c[1], c[2] + cs);
+    }
+  }
+  return _end(out);
+}
+
+/** An arrow along principal axis `axis` (0 X, 1 Y, 2 Z): signed length L, head size h — 5 lines. */
+function _arrow(axis, L, h) {
+  const a = (axis + 1) % 3, b = (axis + 2) % 3;
+  _tip[0] = _tip[1] = _tip[2] = 0; _tip[axis] = L;
+  _line(0, 0, 0, _tip[0], _tip[1], _tip[2]);
+  const s = Math.sign(L) || 1;
+  _ha[0] = _ha[1] = _ha[2] = 0; _ha[axis] = L - s*h;
+  _ha[a] =  h*0.5; _line(_tip[0], _tip[1], _tip[2], _ha[0], _ha[1], _ha[2]);
+  _ha[a] = -h*0.5; _line(_tip[0], _tip[1], _tip[2], _ha[0], _ha[1], _ha[2]);
+  _ha[a] = 0;
+  _ha[b] =  h*0.5; _line(_tip[0], _tip[1], _tip[2], _ha[0], _ha[1], _ha[2]);
+  _ha[b] = -h*0.5; _line(_tip[0], _tip[1], _tip[2], _ha[0], _ha[1], _ha[2]);
+}
+
+/**
+ * A helm's rig, colour always semantic: per translation channel a dim
+ * baseline arrow of signed length sign · size · sens / 0.30 and, while the
+ * channel's activity is non-zero, a bright arrow of length ∝ |activity| /
+ * (sens · fullScale); per rotation channel a dim ring of radius size / 2 ·
+ * sens / 0.0025 and a bright arc sweeping π · f in the live direction.
+ * Dim and bright are the alpha of the written colour (COLOR_DIM, 1). With
+ * `identify`, one anchor per channel goes to out.labels as { x, y, z,
+ * text: 'L' + lane }. Orientation is the caller's M.
+ *
+ * Count: 10 · 3 · 2 (arrows) + 96 · 3 (rings) + 48 · 3 (arcs), at most 492;
+ * the bright half only while a channel is active.
+ *
+ * @param {object} out   Arrays object.
+ * @param {object} helm  A PoseHelm (profile, fullScale, activity).
+ * @param {{ size?:number, bits?:number, identify?:boolean }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function helmRigLines(out, helm, opts) {
+  const o = opts || {};
+  const size = o.size ?? 100;
+  const bits = o.bits ?? (TRANSLATE | ROTATE);
+  const identify = o.identify === true;
+  const prof = helm.profile;
+  const head = size * 0.08, ringR0 = size * 0.5;
+  const TREF = 0.30, RREF = 0.0025, FULL = helm.fullScale, ARC_FULL = Math.PI;
+  helm.activity(_act);
+  _begin(out);
+  const labels = identify && out.labels ? out.labels : null;
+  if (bits & TRANSLATE) {
+    const T = [prof.Tx, prof.Ty, prof.Tz];
+    for (let ax = 0; ax < 3; ax++) {
+      const ch = T[ax];
+      const L = ch.sign * size * (ch.sens / TREF);
+      _color(_AXIS_COLORS[ax], COLOR_DIM);
+      _arrow(ax, L, head);
+      const a = _act[ax];
+      if (a !== 0) {
+        const f = Math.min(Math.abs(a) / (ch.sens * FULL), 1);
+        _color(_AXIS_COLORS[ax], 1);
+        _arrow(ax, Math.sign(a) * f * Math.abs(L), head);
+      }
+      if (labels) {
+        const lp = [0, 0, 0]; lp[ax] = L + ch.sign * head * 1.5;
+        labels.push({ x: lp[0], y: lp[1], z: lp[2], text: 'L' + ch.lane });
+      }
+    }
+  }
+  if (bits & ROTATE) {
+    const R = [prof.Rp, prof.Ry, prof.Rr];       // pitch ⊥ X, yaw ⊥ Y, roll ⊥ Z
+    for (let ax = 0; ax < 3; ax++) {
+      const ch = R[ax];
+      const r = ringR0 * (ch.sens / RREF);
+      const u = _AXES[(ax + 1) % 3], v = _AXES[(ax + 2) % 3];
+      _color(_AXIS_COLORS[ax], COLOR_DIM);
+      _ring(0, 0, 0, r, u, v, 48, TWO_PI);
+      const a = _act[3 + ax];
+      if (a !== 0) {
+        const f = Math.min(Math.abs(a) / (ch.sens * FULL), 1);
+        _color(_AXIS_COLORS[ax], 1);
+        _ring(0, 0, 0, r, u, v, 24, Math.sign(a) * f * ARC_FULL);
+      }
+      if (labels) {
+        const lp = [0, 0, 0]; lp[(ax + 1) % 3] = r;
+        labels.push({ x: lp[0], y: lp[1], z: lp[2], text: 'L' + ch.lane });
+      }
+    }
+  }
+  return _end(out);
+}
+
+/**
+ * A handle's stroked parts by bit. AIM: anchor → `point` (the handle's
+ * current point, read by the caller with value). LOCUS by constraint.kind:
+ * SPHERE three great circles about the anchor; PLANE a square of
+ * half-extent 100 in the plane's basis; AXIS the segment anchor + [min,
+ * max] · u; DIAL the ring in the dial plane; a constraint flagged `view`
+ * (the host's VIEW) a screen-aligned square of half-extent 100 at `point`,
+ * its basis the camera's right and up read off `mat4View`. RING: SPHERE
+ * the view-facing limb, a ring perpendicular to anchor − eye (the eye from
+ * `mat4View`); PLANE the border of the locus square (written once when
+ * both bits ask for it). A constraint supplying locus(out, opts) is
+ * dispatched to it. The HANDLE dot is not a line and not generated here.
+ *
+ * Count: AIM 2; LOCUS SPHERE 288 · PLANE 8 · AXIS 2 · DIAL 96 · view 8;
+ * RING SPHERE 96 · PLANE 8 (shared with LOCUS); at most 386.
+ *
+ * @param {object} out         Arrays object.
+ * @param {object} constraint  A contract-conforming constraint.
+ * @param {{ bits?:number, mat4View?:ArrayLike<number>, point?:number[], color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function locusLines(out, constraint, opts) {
+  const o = opts || {};
+  if (typeof constraint.locus === 'function') return constraint.locus(out, o);
+  const bits = o.bits ?? (AIM | LOCUS);
+  const c = constraint, a = c.anchor, pt = o.point, V = o.mat4View;
+  _begin(out);
+  _color(o.color);
+  if ((bits & AIM) && a && pt) _line(a[0], a[1], a[2], pt[0], pt[1], pt[2]);
+  if (c.view === true) {
+    if ((bits & LOCUS) && pt && V) {
+      _b0[0] = V[0]; _b0[1] = V[4]; _b0[2] = V[8];      // the camera's right
+      _b1[0] = V[1]; _b1[1] = V[5]; _b1[2] = V[9];      // the camera's up
+      _square(pt, _b0, _b1, 100);
+    }
+  } else if (c.kind === SPHERE && a) {
+    if (bits & LOCUS) {
+      _ring(a[0], a[1], a[2], c.radius, _AXES[0], _AXES[1], 48, TWO_PI);
+      _ring(a[0], a[1], a[2], c.radius, _AXES[1], _AXES[2], 48, TWO_PI);
+      _ring(a[0], a[1], a[2], c.radius, _AXES[2], _AXES[0], 48, TWO_PI);
+    }
+    if ((bits & RING) && V) {
+      // eye = −Rᵀ t of the view matrix; the limb is ⊥ anchor − eye
+      const tx = V[12], ty = V[13], tz = V[14];
+      _b2[0] = a[0] + (V[0]*tx + V[1]*ty + V[2]*tz);
+      _b2[1] = a[1] + (V[4]*tx + V[5]*ty + V[6]*tz);
+      _b2[2] = a[2] + (V[8]*tx + V[9]*ty + V[10]*tz);
+      _unit(_b2, 0, 0, 1);
+      _basis(_b2, _b0, _b1);
+      _ring(a[0], a[1], a[2], c.radius, _b0, _b1, 48, TWO_PI);
+    }
+  } else if (c.kind === PLANE && a) {
+    if (bits & (LOCUS | RING)) {
+      _basis(c.n, _b0, _b1);
+      _square(a, _b0, _b1, 100);
+    }
+  } else if (c.kind === AXIS && a) {
+    if (bits & LOCUS) {
+      const u = c.u;
+      _line(a[0] + c.min*u[0], a[1] + c.min*u[1], a[2] + c.min*u[2],
+            a[0] + c.max*u[0], a[1] + c.max*u[1], a[2] + c.max*u[2]);
+    }
+  } else if (c.kind === DIAL && a) {
+    if (bits & LOCUS) _ring(a[0], a[1], a[2], c.radius, c.r0, c.r1, 48, TWO_PI);
+  }
+  return _end(out);
+}
+
+/**
+ * A textured quad as two triangles (p0, p1, p2) (p0, p2, p3) — the winding
+ * of the corner order — with texcoord written when the array exists.
+ * Default uvs: p0 (top-left) → (0, 1), p1 → (1, 1), p2 → (1, 0), p3 →
+ * (0, 0), so a texture in GL's bottom-up space reads upright with no
+ * flip; `opts.uvs` overrides, four pairs flat in corner order.
+ *
+ * Count: 6.
+ *
+ * @param {object} out  Arrays object.
+ * @param {number[]} p0,p1,p2,p3  Corners, top-left clockwise.
+ * @param {{ uvs?:number[], color?:number[] }} [opts]
+ * @returns {number} Vertices needed.
+ */
+function paneTris(out, p0, p1, p2, p3, opts) {
+  const o = opts || {};
+  const uv = o.uvs || _UV_DEFAULT;
+  _begin(out);
+  _color(o.color);
+  _vertexUV(p0[0], p0[1], p0[2], uv[0], uv[1]);
+  _vertexUV(p1[0], p1[1], p1[2], uv[2], uv[3]);
+  _vertexUV(p2[0], p2[1], p2[2], uv[4], uv[5]);
+  _vertexUV(p0[0], p0[1], p0[2], uv[0], uv[1]);
+  _vertexUV(p2[0], p2[1], p2[2], uv[4], uv[5]);
+  _vertexUV(p3[0], p3[1], p3[2], uv[6], uv[7]);
+  return _end(out);
+}
+
+export { AIM, APEX, AXIS, BODY, BOTTOM, CENTER, CIRCLE, COLOR_DIM, COLOR_X, COLOR_Y, COLOR_Z, CONTROLS, CameraTrack, Constraint, DIAL, DIRECTION, EYE, FAR, HANDLE, HANDLES, HELM_CHANNELS, INVISIBLE, LABELS, LEFT, LOCUS, MATRIX, MODEL, NDC, NEAR, NONE, ORIGIN, PATH, PLANE, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, POINT, PoseHelm, PoseTrack, RIGHT, RING, ROTATE, SCREEN, SELF, SEMIVISIBLE, SPHERE, SQUARE, TANGENTS, TANGENTS_IN, TANGENTS_OUT, TOP, TRANSLATE, VISIBLE, WEBGL, WEBGPU, WORLD, X, Y, Z, _X, _Y, _Z, _i, _j, _k, axesLines, azElFromDir, boxVisibility, bullsEyeLines, cameraCopy, cameraDolly, cameraEye, cameraFromMat4, cameraFromPose, cameraOrbit, cameraPan, cameraPlanes, cameraProj, cameraToPose, cameraView, capacityOf, createArrays, createCamera, createConstraint, crossLines, dirFromAzEl, distanceToPlane, frustumCorners, frustumLines, frustumPlanes, gridLines, growArrays, helmRigLines, hermiteLines, hermiteVec3, i, idToRgba, j, k, lerpVec3, locusLines, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4Eye, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Persp, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, mat4View, oneEuro, paneTris, pathLines, pixelRatio, pointVisibility, pointerHit, poseDelta, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qConjugate, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qFromUnitVectors, qMul, qNegate, qNlerp, qNormalize, qRotateVec3, qSet, qSlerp, qToAxisAngle, qToMat4, rayClosestPointOnAxis, rayHitCapsule, rayHitRing, rayHitSphere, rayPlane, raySphere, rgbaToId, ringLines, sphereVisibility, transformToMat4, unproject };
 //# sourceMappingURL=index.js.map