@nakednous/host 0.0.1

package/dist/index.js

@@ -0,0 +1,4833 @@
+/**
+ * @file Core constants — zero dependencies.
+ * @module tree/constants
+ * @license AGPL-3.0-only
+ */
+
+// Coordinate spaces
+const WORLD  = 'WORLD';
+const EYE    = 'EYE';
+const NDC    = 'NDC';
+const SCREEN = 'SCREEN';
+const MATRIX = 'MATRIX';
+
+// Integrator frame source (helm `from` only): the construct's own current pose
+// — body-relative; not a general mapDirection space.
+const SELF   = 'SELF';
+
+// NDC Z convention (only difference between backends)
+const WEBGL  = -1;   // z ∈ [−1, 1]
+
+// Handle constraint kinds
+const SPHERE = 0;
+const PLANE  = 1;
+const AXIS   = 2;
+const DIAL   = 3;
+
+// Handle report modes
+const POINT     = 0;
+const DIRECTION = 1;
+
+/** Normalise quaternion in-place. @returns {number[]} out */
+const qNormalize = (out) => {
+  const l = Math.sqrt(out[0]*out[0]+out[1]*out[1]+out[2]*out[2]+out[3]*out[3]) || 1;
+  out[0]/=l; out[1]/=l; out[2]/=l; out[3]/=l; return out;
+};
+
+/** Hamilton product out = a * b. Alias-safe: out may be a or b. @returns {number[]} out */
+const qMul = (out, a, b) => {
+  const ax=a[0],ay=a[1],az=a[2],aw=a[3], bx=b[0],by=b[1],bz=b[2],bw=b[3];
+  out[0]=aw*bx+ax*bw+ay*bz-az*by;
+  out[1]=aw*by-ax*bz+ay*bw+az*bx;
+  out[2]=aw*bz+ax*by-ay*bx+az*bw;
+  out[3]=aw*bw-ax*bx-ay*by-az*bz;
+  return out;
+};
+
+// =========================================================================
+// Interpolation
+// =========================================================================
+
+/** Spherical linear interpolation. @returns {number[]} out */
+const qSlerp = (out, a, b, t) => {
+  let bx=b[0],by=b[1],bz=b[2],bw=b[3];
+  let d = a[0]*bx+a[1]*by+a[2]*bz+a[3]*bw;
+  if (d < 0) { bx=-bx; by=-by; bz=-bz; bw=-bw; d=-d; }
+  let f0, f1;
+  if (1-d > 1e-10) {
+    const th=Math.acos(d), st=Math.sin(th);
+    f0=Math.sin((1-t)*th)/st; f1=Math.sin(t*th)/st;
+  } else {
+    f0=1-t; f1=t;
+  }
+  out[0]=a[0]*f0+bx*f1; out[1]=a[1]*f0+by*f1;
+  out[2]=a[2]*f0+bz*f1; out[3]=a[3]*f0+bw*f1;
+  return qNormalize(out);
+};
+
+/**
+ * Normalised linear interpolation (nlerp).
+ * Cheaper than slerp; slightly non-constant angular velocity.
+ * Handles antipodal quats by flipping b when dot < 0.
+ * @returns {number[]} out
+ */
+const qNlerp = (out, a, b, t) => {
+  let bx=b[0],by=b[1],bz=b[2],bw=b[3];
+  if (a[0]*bx+a[1]*by+a[2]*bz+a[3]*bw < 0) { bx=-bx; by=-by; bz=-bz; bw=-bw; }
+  out[0]=a[0]+t*(bx-a[0]); out[1]=a[1]+t*(by-a[1]);
+  out[2]=a[2]+t*(bz-a[2]); out[3]=a[3]+t*(bw-a[3]);
+  return qNormalize(out);
+};
+
+/**
+ * Build a quaternion from axis-angle.
+ * @param {number[]} out
+ * @param {number} ax @param {number} ay @param {number} az  Axis (need not be unit).
+ * @param {number} angle  Radians.
+ * @returns {number[]} out
+ */
+const qFromAxisAngle = (out, ax, ay, az, angle) => {
+  const half = angle * 0.5;
+  const s    = Math.sin(half);
+  const len  = Math.sqrt(ax*ax + ay*ay + az*az) || 1;
+  out[0] = s * ax / len; out[1] = s * ay / len; out[2] = s * az / len;
+  out[3] = Math.cos(half);
+  return out;
+};
+
+/**
+ * Build a quaternion from a look direction (−Z forward) and optional up (default +Y).
+ * `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].
+ * @returns {number[]} out
+ */
+const qFromLookDir = (out, dir, up) => {
+  let fx=dir[0],fy=dir[1],fz=dir[2];
+  const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
+  fx/=fl; fy/=fl; fz/=fl;
+  let ux=up?up[0]:0, uy=up?up[1]:1, uz=up?up[2]:0;
+  let rx=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=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
+};
+
+/**
+ * Build a quaternion from a 3×3 rotation matrix (9 row-major scalars).
+ * @returns {number[]} out (normalised)
+ */
+const qFromRotMat3x3 = (out, m00,m01,m02, m10,m11,m12, m20,m21,m22) => {
+  const tr = m00+m11+m22;
+  if (tr > 0) {
+    const s=0.5/Math.sqrt(tr+1);
+    out[3]=0.25/s; out[0]=(m21-m12)*s; out[1]=(m02-m20)*s; out[2]=(m10-m01)*s;
+  } else if (m00>m11 && m00>m22) {
+    const s=2*Math.sqrt(1+m00-m11-m22);
+    out[3]=(m21-m12)/s; out[0]=0.25*s; out[1]=(m01+m10)/s; out[2]=(m02+m20)/s;
+  } else if (m11>m22) {
+    const s=2*Math.sqrt(1+m11-m00-m22);
+    out[3]=(m02-m20)/s; out[0]=(m01+m10)/s; out[1]=0.25*s; out[2]=(m12+m21)/s;
+  } else {
+    const s=2*Math.sqrt(1+m22-m00-m11);
+    out[3]=(m10-m01)/s; out[0]=(m02+m20)/s; out[1]=(m12+m21)/s; out[2]=0.25*s;
+  }
+  return qNormalize(out);
+};
+
+/**
+ * Write a quaternion into the rotation block of a column-major mat4.
+ * Translation and perspective rows/cols are set to identity values.
+ * @param {Float32Array|number[]} out  16-element array.
+ * @param {number[]} q  [x,y,z,w].
+ * @returns {Float32Array|number[]} out
+ */
+const qToMat4 = (out, q) => {
+  const x=q[0],y=q[1],z=q[2],w=q[3];
+  const x2=x+x,y2=y+y,z2=z+z;
+  const xx=x*x2,xy=x*y2,xz=x*z2,yy=y*y2,yz=y*z2,zz=z*z2,wx=w*x2,wy=w*y2,wz=w*z2;
+  out[0]=1-(yy+zz); out[1]=xy+wz;     out[2]=xz-wy;     out[3]=0;
+  out[4]=xy-wz;     out[5]=1-(xx+zz); out[6]=yz+wx;     out[7]=0;
+  out[8]=xz+wy;     out[9]=yz-wx;     out[10]=1-(xx+yy); out[11]=0;
+  out[12]=0;        out[13]=0;        out[14]=0;          out[15]=1;
+  return out;
+};
+
+// 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)).
+ * Cheaper than building the eye matrix and inverting.
+ *
+ * @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; re-seeded when
+ *                            parallel to the view direction).
+ */
+function mat4View(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
+  _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;
+  out[12]=-(xx*ex+xy*ey+xz*ez);
+  out[13]=-(yx*ex+yy*ey+yz*ez);
+  out[14]=-(zx*ex+zy*ey+zz*ez);
+  out[15]=1;
+  return out;
+}
+
+/**
+ * Eye matrix (eye→world) from lookat parameters.
+ * Transpose of the rotation block + direct translation column.
+ * Same parameters as mat4View.
+ *
+ * @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 (need not be unit; re-seeded when
+ *                            parallel to the view direction).
+ */
+function mat4Eye(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
+  _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;
+  out[12]=ex; out[13]=ey; out[14]=ez; out[15]=1;
+  return out;
+}
+
+// =========================================================================
+// Projection construction
+// =========================================================================
+
+/**
+ * Orthographic projection matrix.
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} left,right,bottom,top  Frustum extents.
+ * @param {number} near,far              Clip plane distances (positive).
+ * @param {number} ndcZMin               −1 (WEBGL) or 0 (WEBGPU).
+ * @param {number} [ndcYSign=1]          +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
+ */
+function mat4Ortho(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1) {
+  const rl=1/(right-left), tb=1/(top-bottom), fn=1/(far-near);
+  out[0]=2*rl;              out[1]=0;                       out[2]=0;               out[3]=0;
+  out[4]=0;                 out[5]=ndcYSign*2*tb;           out[6]=0;               out[7]=0;
+  out[8]=0;                 out[9]=0;                       out[10]=(ndcZMin-1)*fn; out[11]=0;
+  out[12]=-(right+left)*rl; out[13]=ndcYSign*(-(top+bottom)*tb);
+  out[14]=(ndcZMin*far-near)*fn;
+  out[15]=1;
+  return out;
+}
+
+/**
+ * Perspective projection matrix (general / off-centre frustum).
+ * Symmetric case: left=-right, bottom=-top — derive from fov+aspect in user space:
+ *   top = near * Math.tan(fov / 2);  right = top * aspect
+ *   mat4Persp(out, -right, right, -top, top, near, far, ndcZMin)
+ *
+ * @param {Float32Array|number[]} out  16-element destination.
+ * @param {number} left,right,bottom,top  Near-plane extents (signed, y-up: top>0, bottom<0).
+ * @param {number} near,far              Clip plane distances (positive).
+ * @param {number} ndcZMin               −1 (WEBGL) or 0 (WEBGPU).
+ * @param {number} [ndcYSign=1]          +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
+ */
+function mat4Persp(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1) {
+  const rl=1/(right-left), tb=1/(top-bottom);
+  out[0]=2*near*rl;        out[1]=0;                          out[2]=0;  out[3]=0;
+  out[4]=0;                out[5]=ndcYSign*2*near*tb;         out[6]=0;  out[7]=0;
+  out[8]=(right+left)*rl;  out[9]=ndcYSign*(top+bottom)*tb;
+  out[10]=(ndcZMin*near-far)/(far-near);
+  out[11]=-1;
+  out[12]=0; out[13]=0;
+  out[14]=(ndcZMin-1)*far*near/(far-near);
+  out[15]=0;
+  return out;
+}
+
+/**
+ * @file Matrix arithmetic, space-transform dispatch, and projection queries.
+ * @module tree/query
+ * @license AGPL-3.0-only
+ *
+ * The operative layer — receives matrices and extracts information.
+ * Contrast with form.js which constructs matrices from specs.
+ *
+ *   form.js  — specs  → matrix
+ *   query.js — matrix → information
+ *
+ * Storage: column-major Float32Array / ArrayLike<number>.
+ * Multiply: mat4Mul(out, A, B) = A · B  (standard math order).
+ * Pipeline: clip = P · V · M · v
+ *
+ * ── NDC Z convention ──────────────────────────────────────────────────────
+ * Passed as `ndcZMin` to every space-transform function:
+ *   WEBGL  = −1   z ∈ [−1,  1]
+ *   WEBGPU =  0   z ∈ [ 0,  1]
+ *
+ * ── NDC Y convention ──────────────────────────────────────────────────────
+ * Standard (OpenGL / WebGL / WebGPU browser / Three.js / p5v2):
+ *   NDC y-up  — y = +1 at top, y = −1 at bottom.
+ * Native Vulkan: NDC y-down — projections constructed with ndcYSign = −1
+ * (see form.js).  Query functions are convention-agnostic: they work on
+ * whatever matrices are passed in.
+ *
+ * ── Viewport convention ───────────────────────────────────────────────────
+ * vp = [x, y, w, h] — w and h are SIGNED.
+ *
+ * The sign of h encodes the relationship between NDC y and screen y:
+ *   h < 0 (e.g. −canvasH): screen y-DOWN  (DOM / p5 mouseX·mouseY / Vulkan surface)
+ *                            NDC y=+1 → screen y=0  (top)
+ *                            NDC y=−1 → screen y=H  (bottom)
+ *   h > 0 (e.g. +canvasH): screen y-UP   (OpenGL desktop / WebGL gl_FragCoord)
+ *                            NDC y=−1 → screen y=0  (bottom)
+ *                            NDC y=+1 → screen y=H  (top)
+ *
+ * Pass [0, canvasH, canvasW, −canvasH] for p5/DOM coordinates.
+ * Pass [0, 0, canvasW, canvasH] for WebGL gl_FragCoord / OpenGL bottom-left.
+ * All helpers use vp[2]/vp[3] signed — no Math.abs — so both conventions
+ * work automatically without any branching.
+ *
+ * All functions follow the out-first, zero-allocation contract.
+ * Returns null on degeneracy (singular matrix, etc.).
+ */
+
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Mat4 arithmetic
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** out = A · B  (column-major) */
+function mat4Mul(out, A, B) {
+  const a0=A[0],a1=A[1],a2=A[2],a3=A[3],
+        a4=A[4],a5=A[5],a6=A[6],a7=A[7],
+        a8=A[8],a9=A[9],a10=A[10],a11=A[11],
+        a12=A[12],a13=A[13],a14=A[14],a15=A[15];
+  let b0=B[0],b1=B[1],b2=B[2],b3=B[3];
+  out[0]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[1]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[2]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[3]=a3*b0+a7*b1+a11*b2+a15*b3;
+  b0=B[4];b1=B[5];b2=B[6];b3=B[7];
+  out[4]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[5]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[6]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[7]=a3*b0+a7*b1+a11*b2+a15*b3;
+  b0=B[8];b1=B[9];b2=B[10];b3=B[11];
+  out[8]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[9]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[10]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[11]=a3*b0+a7*b1+a11*b2+a15*b3;
+  b0=B[12];b1=B[13];b2=B[14];b3=B[15];
+  out[12]=a0*b0+a4*b1+a8*b2+a12*b3;
+  out[13]=a1*b0+a5*b1+a9*b2+a13*b3;
+  out[14]=a2*b0+a6*b1+a10*b2+a14*b3;
+  out[15]=a3*b0+a7*b1+a11*b2+a15*b3;
+  return out;
+}
+
+/** out = inverse(src). Returns null if singular (|det| < 1e-12). */
+function mat4Invert(out, src) {
+  const s0=src[0],s1=src[1],s2=src[2],s3=src[3],
+        s4=src[4],s5=src[5],s6=src[6],s7=src[7],
+        s8=src[8],s9=src[9],s10=src[10],s11=src[11],
+        s12=src[12],s13=src[13],s14=src[14],s15=src[15];
+  const b0=s0*s5-s1*s4, b1=s0*s6-s2*s4, b2=s0*s7-s3*s4,
+        b3=s1*s6-s2*s5, b4=s1*s7-s3*s5, b5=s2*s7-s3*s6,
+        b6=s8*s13-s9*s12, b7=s8*s14-s10*s12, b8=s8*s15-s11*s12,
+        b9=s9*s14-s10*s13, b10=s9*s15-s11*s13, b11=s10*s15-s11*s14;
+  let det=b0*b11-b1*b10+b2*b9+b3*b8-b4*b7+b5*b6;
+  if (Math.abs(det) < 1e-12) return null;
+  det = 1/det;
+  out[0]=(s5*b11-s6*b10+s7*b9)*det;
+  out[1]=(s2*b10-s1*b11-s3*b9)*det;
+  out[2]=(s13*b5-s14*b4+s15*b3)*det;
+  out[3]=(s10*b4-s9*b5-s11*b3)*det;
+  out[4]=(s6*b8-s4*b11-s7*b7)*det;
+  out[5]=(s0*b11-s2*b8+s3*b7)*det;
+  out[6]=(s14*b2-s12*b5-s15*b1)*det;
+  out[7]=(s8*b5-s10*b2+s11*b1)*det;
+  out[8]=(s4*b10-s5*b8+s7*b6)*det;
+  out[9]=(s1*b8-s0*b10-s3*b6)*det;
+  out[10]=(s12*b4-s13*b2+s15*b0)*det;
+  out[11]=(s9*b2-s8*b4-s11*b0)*det;
+  out[12]=(s5*b7-s4*b9-s6*b6)*det;
+  out[13]=(s0*b9-s1*b7+s2*b6)*det;
+  out[14]=(s13*b1-s12*b3-s14*b0)*det;
+  out[15]=(s8*b3-s9*b1+s10*b0)*det;
+  return out;
+}
+
+/** out = mat4 * [x,y,z,1], perspective-divides, writes xyz. */
+function mat4MulPoint(out, m, x, y, z) {
+  const rx=m[0]*x+m[4]*y+m[8]*z+m[12], ry=m[1]*x+m[5]*y+m[9]*z+m[13],
+        rz=m[2]*x+m[6]*y+m[10]*z+m[14], rw=m[3]*x+m[7]*y+m[11]*z+m[15];
+  if (rw!==0&&rw!==1) { out[0]=rx/rw; out[1]=ry/rw; out[2]=rz/rw; }
+  else                 { out[0]=rx;    out[1]=ry;    out[2]=rz;    }
+  return out;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Projection queries
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** @returns {boolean} true if orthographic. */
+function projIsOrtho(p) { return p[15] !== 0; }
+
+/**
+ * Near plane distance.
+ * @param {ArrayLike<number>} p       Projection mat4.
+ * @param {number}            ndcZMin WEBGL (−1) or WEBGPU (0).
+ */
+function projNear(p, ndcZMin) {
+  return p[15]===0 ? p[14]/(p[10]+ndcZMin) : (p[14]-ndcZMin)/p[10];
+}
+
+/**
+ * Top extent of the near plane in camera space (y_max, positive for standard y-up camera).
+ * Sign-normalized: returns the larger of the two y boundaries regardless of whether
+ * the projection was built with ndcYSign = +1 or −1.
+ */
+function projTop(p, ndcZMin) {
+  return p[15]===1
+    ? ( Math.sign(p[5]) - p[13]) / p[5]                    // ortho
+    : projNear(p,ndcZMin)*(Math.sign(p[5])+p[9])/p[5];     // perspective
+}
+
+/**
+ * Bottom extent of the near plane in camera space (y_min, negative for standard y-up camera).
+ */
+function projBottom(p, ndcZMin) {
+  return p[15]===1
+    ? (-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). */
+function projFov (p) { return Math.abs(2*Math.atan(1/p[5])); }
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Space transforms — mapLocation / mapDirection
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// Flat dispatch: every from→to pair is a self-contained leaf with only stack
+// locals — no reentrancy, no shared state between calls.
+//
+// Matrices bag `m`:
+//   mat4Proj    Float32Array(16)  projection  (eye → clip)
+//   mat4View    Float32Array(16)  view        (world → eye)
+//   mat4Eye?    Float32Array(16)  eye         (eye → world); caller fills before passing
+//   mat4PV?     Float32Array(16)  P · V;      caller fills or _ensurePV allocates once
+//   mat4PVInv?  Float32Array(16)  inv(P · V); caller fills
+//   fromFrame?  Float32Array(16)  MATRIX source frame
+//   toFrameInv? Float32Array(16)  inv(MATRIX dest frame)
+//
+// Viewport `vp` = [x, y, w, h]:
+//   Use SIGNED h to encode screen-y direction (see module header).
+//   Core formula: screen = (ndc*0.5+0.5)*vp[k] + vp[k-2]  (k=2 for x, k=3 for y)
+//   Inverse:      ndc    = ((screen-vp[k-2])/vp[k])*2 - 1
+//   Negative vp[3] flips NDC y-up to screen y-down automatically.
+//
+
+// ── Location helpers ─────────────────────────────────────────────────────
+
+function _worldToScreen(out, px, py, pz, pv, vp, ndcZMin) {
+  const x=pv[0]*px+pv[4]*py+pv[8]*pz+pv[12], y=pv[1]*px+pv[5]*py+pv[9]*pz+pv[13],
+        z=pv[2]*px+pv[6]*py+pv[10]*pz+pv[14], w=pv[3]*px+pv[7]*py+pv[11]*pz+pv[15];
+  const xi=(w!==0&&w!==1)?1/w:1;
+  out[0]=(x*xi*0.5+0.5)*vp[2]+vp[0];
+  out[1]=(y*xi*0.5+0.5)*vp[3]+vp[1];
+  out[2]=(z*xi-ndcZMin)/(1-ndcZMin);
+  return out;
+}
+
+function _screenToWorld(out, sx, sy, sz, ipv, vp, ndcZMin) {
+  return mat4MulPoint(out, ipv,
+    ((sx-vp[0])/vp[2])*2-1,
+    ((sy-vp[1])/vp[3])*2-1,
+    sz*(1-ndcZMin)+ndcZMin);
+}
+
+function _worldToNDC(out, px, py, pz, pv) {
+  const x=pv[0]*px+pv[4]*py+pv[8]*pz+pv[12], y=pv[1]*px+pv[5]*py+pv[9]*pz+pv[13],
+        z=pv[2]*px+pv[6]*py+pv[10]*pz+pv[14], w=pv[3]*px+pv[7]*py+pv[11]*pz+pv[15];
+  const xi=(w!==0&&w!==1)?1/w:1;
+  out[0]=x*xi; out[1]=y*xi; out[2]=z*xi;
+  return out;
+}
+
+function _ensurePV(m) {
+  if (m.mat4PV) return m.mat4PV;
+  m.mat4PV = new Float32Array(16);
+  mat4Mul(m.mat4PV, m.mat4Proj, m.mat4View);
+  return m.mat4PV;
+}
+
+/**
+ * Map a point between named coordinate spaces.
+ *
+ * @param {number[]} out     3-element destination — written and returned.
+ * @param {number}   px,py,pz Input point.
+ * @param {string}   from    Source space (WORLD, EYE, SCREEN, NDC, MATRIX).
+ * @param {string}   to      Destination space.
+ * @param {object}   m       Matrices bag — see module header.
+ * @param {number[]} vp      Viewport [x, y, w, h]; sign of h encodes screen-y direction.
+ * @param {number}   ndcZMin WEBGL (−1) or WEBGPU (0).
+ * @returns {number[]} out
+ */
+function mapLocation(out, px, py, pz, from, to, m, vp, ndcZMin) {
+  if (to===SCREEN) return _worldToScreen(out,px,py,pz,_ensurePV(m),vp,ndcZMin);
+
+  if (to===NDC)   return _worldToNDC(out,px,py,pz,_ensurePV(m));
+
+  if (to===EYE) return mat4MulPoint(out,m.mat4View,px,py,pz);
+  if (to===MATRIX) return mat4MulPoint(out,m.toFrameInv,px,py,pz);
+
+  out[0]=px; out[1]=py; out[2]=pz;
+  return out;
+}
+
+// ── Direction helpers ────────────────────────────────────────────────────
+//
+// Directions use only the linear 3×3 block — no translation, no w-divide.
+// The signed vp[2]/vp[3] carries the y-convention automatically.
+//
+
+function _applyDir(out, m, dx, dy, dz) {
+  out[0]=m[0]*dx+m[4]*dy+m[8]*dz;
+  out[1]=m[1]*dx+m[5]*dy+m[9]*dz;
+  out[2]=m[2]*dx+m[6]*dy+m[10]*dz;
+  return out;
+}
+
+function _worldToScreenDir(out, dx, dy, dz, proj, view, vpW, vpH, ndcZMin) {
+  const vx=view[0]*dx+view[4]*dy+view[8]*dz,
+        vy=view[1]*dx+view[5]*dy+view[9]*dz,
+        vz=view[2]*dx+view[6]*dy+view[10]*dz;
+  // vpH is signed — negative flips y component automatically.
+  out[0]=(proj[0]*vx+proj[4]*vy+proj[8]*vz)*vpW*0.5;
+  out[1]=(proj[1]*vx+proj[5]*vy+proj[9]*vz)*vpH*0.5;
+  out[2]=(proj[2]*vx+proj[6]*vy+proj[10]*vz)*(1-ndcZMin)*0.5;
+  return out;
+}
+
+function _screenToWorldDir(out, dx, dy, dz, proj, eye, vpW, vpH, ndcZMin) {
+  // 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) {
+  out[0]=dx/(vpW*0.5); out[1]=dy/(vpH*0.5); out[2]=dz/((1-ndcZMin)*0.5);
+  return out;
+}
+
+function _ndcToScreenDir(out, dx, dy, dz, vpW, vpH, ndcZMin) {
+  out[0]=dx*vpW*0.5; out[1]=dy*vpH*0.5; out[2]=dz*(1-ndcZMin)*0.5;
+  return out;
+}
+
+/**
+ * Map a direction between named coordinate spaces.
+ * Same bag and viewport contract as mapLocation.
+ *
+ * @param {number[]} out     3-element destination.
+ * @param {number}   dx,dy,dz Input direction.
+ * @param {string}   from    Source space.
+ * @param {string}   to      Destination space.
+ * @param {object}   m       Matrices bag — see module header.
+ * @param {number[]} vp      Viewport [x, y, w, h]; sign of h encodes screen-y direction.
+ * @param {number}   ndcZMin WEBGL (−1) or WEBGPU (0).
+ * @returns {number[]} out
+ */
+function mapDirection(out, dx, dy, dz, from, to, m, vp, ndcZMin) {
+  const vpW=vp[2], vpH=vp[3];  // signed — carry y-convention through all helpers
+
+  if (from===EYE   && to===WORLD)  return _applyDir(out,m.mat4Eye, dx,dy,dz);
+  if (from===WORLD && to===EYE)    return _applyDir(out,m.mat4View,dx,dy,dz);
+
+  if (from===WORLD  && to===SCREEN) return _worldToScreenDir(out,dx,dy,dz,m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+  if (from===SCREEN && to===WORLD)  return _screenToWorldDir(out,dx,dy,dz,m.mat4Proj,m.mat4Eye, vpW,vpH,ndcZMin);
+
+  if (from===SCREEN && to===NDC)    return _screenToNDCDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+  if (from===NDC    && to===SCREEN) return _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+
+  if (from===WORLD && to===NDC) {
+    _worldToScreenDir(out,dx,dy,dz,m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+    return _screenToNDCDir(out,out[0],out[1],out[2],vpW,vpH,ndcZMin);
+  }
+  if (from===NDC && to===WORLD) {
+    _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+    return _screenToWorldDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+  }
+
+  if (from===EYE && to===SCREEN) {
+    _applyDir(out,m.mat4Eye,dx,dy,dz);
+    return _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+  }
+  if (from===SCREEN && to===EYE) {
+    _screenToWorldDir(out,dx,dy,dz,m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.mat4View,out[0],out[1],out[2]);
+  }
+
+  if (from===EYE && to===NDC) {
+    _applyDir(out,m.mat4Eye,dx,dy,dz);
+    _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+    return _screenToNDCDir(out,out[0],out[1],out[2],vpW,vpH,ndcZMin);
+  }
+  if (from===NDC && to===EYE) {
+    _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+    _screenToWorldDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.mat4View,out[0],out[1],out[2]);
+  }
+
+  if (from===MATRIX && to===WORLD)  return _applyDir(out,m.fromFrame, dx,dy,dz);
+  if (from===WORLD  && to===MATRIX) return _applyDir(out,m.toFrameInv,dx,dy,dz);
+
+  if (from===MATRIX && to===EYE) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    return _applyDir(out,m.mat4View,out[0],out[1],out[2]);
+  }
+  if (from===EYE && to===MATRIX) {
+    _applyDir(out,m.mat4Eye,dx,dy,dz);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
+  }
+
+  if (from===MATRIX && to===SCREEN) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    return _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+  }
+  if (from===SCREEN && to===MATRIX) {
+    _screenToWorldDir(out,dx,dy,dz,m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
+  }
+
+  if (from===MATRIX && to===NDC) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    _worldToScreenDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4View,vpW,vpH,ndcZMin);
+    return _screenToNDCDir(out,out[0],out[1],out[2],vpW,vpH,ndcZMin);
+  }
+  if (from===NDC && to===MATRIX) {
+    _ndcToScreenDir(out,dx,dy,dz,vpW,vpH,ndcZMin);
+    _screenToWorldDir(out,out[0],out[1],out[2],m.mat4Proj,m.mat4Eye,vpW,vpH,ndcZMin);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
+  }
+
+  if (from===MATRIX && to===MATRIX) {
+    _applyDir(out,m.fromFrame,dx,dy,dz);
+    return _applyDir(out,m.toFrameInv,out[0],out[1],out[2]);
+  }
+
+  out[0]=dx; out[1]=dy; out[2]=dz;
+  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;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// pixelRatio
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * World-units-per-pixel at a given eye-space Z depth.
+ * @param {ArrayLike<number>} proj    Projection mat4.
+ * @param {number}            vpH     Viewport height in pixels (positive).
+ * @param {number}            eyeZ    Eye-space Z — negative means in front of camera.
+ * @param {number}            ndcZMin WEBGL (−1) or WEBGPU (0).
+ */
+function pixelRatio(proj, vpH, eyeZ, ndcZMin) {
+  return projIsOrtho(proj)
+    ? Math.abs(projTop(proj,ndcZMin)-projBottom(proj,ndcZMin)) / vpH
+    : 2*Math.abs(eyeZ)*Math.tan(projFov(proj)/2) / vpH;
+}
+
+/**
+ * @file Spline math and keyframe animation state machines.
+ * @module tree/track
+ * @license AGPL-3.0-only
+ *
+ * Quaternion algebra is provided by quat.js; projection matrix construction
+ * by form.js. Spline helpers (hermiteVec3, lerpVec3) and TRS↔mat4 conversions
+ * (transformToMat4, mat4ToTransform) live here because they are tightly
+ * coupled to the PoseTrack keyframe shape.
+ *
+ * Zero dependencies on p5, DOM, WebGL, or WebGPU.
+ *
+ * ── Exports ──────────────────────────────────────────────────────────────
+ *  Quaternion helpers   (re-exported from quat.js)
+ *    qSet qCopy qDot qNormalize qNegate qMul qConjugate qRotateVec3
+ *    qSlerp qNlerp qFromUnitVectors qFromAxisAngle qFromLookDir
+ *    qFromRotMat3x3 qFromMat4 qToMat4 qToAxisAngle
+ *  Spline / vector helpers
+ *    hermiteVec3  lerpVec3
+ *  Transform / mat4 helpers
+ *    transformToMat4  mat4ToTransform
+ *  Tracks
+ *    PoseTrack    — { pos, rot, scl } TRS keyframes
+ *    CameraTrack  — { eye, center, up, fov?, halfHeight?, near, far }
+ *                   lookat keyframes
+ *
+ * ── Public path access (all zero-alloc, no cursor side effects) ──────────
+ *  PoseTrack
+ *    samplePos        (out)  |  (out, seg, t)              vec3
+ *    mat4Model        (out)  |  (out, seg, t)              mat4  — TRS model
+ *    tangents         (outIn, outOut, index)               vec3 × 2 at keyframe
+ *    eval             (out?)                               TRS object at cursor
+ *
+ *  CameraTrack
+ *    sampleEye        (out)  |  (out, seg, t)              vec3
+ *    sampleCenter     (out)  |  (out, seg, t)              vec3
+ *    mat4Eye          (out)  |  (out, seg, t)              mat4  — lookat frame
+ *    eyeTangents      (outIn, outOut, index)               vec3 × 2 at keyframe
+ *    centerTangents   (outIn, outOut, index)               vec3 × 2 at keyframe
+ *    eval             (out?)                               { eye, center, up,
+ *                                                            fov, halfHeight,
+ *                                                            near, far }
+ *
+ *  Two arities for the continuous family:
+ *    (out)          cursor form — reads track.seg / track.f. Useful when the
+ *                   track's own transport is driving the animation.
+ *    (out, seg, t)  explicit form — continuous (seg, t) coordinate, no cursor
+ *                   side effects. seg ∈ [0, segments−1] integer, t ∈ [0, 1]
+ *                   local to that segment. As a convenience, seg === segments
+ *                   is accepted and rewritten to (segments−1, 1) — so the
+ *                   idiom sampleX(out, i, 0) uniformly addresses keyframe i
+ *                   for every i ∈ [0, keyframes.length−1].
+ *
+ *  All honour the track's interpolation mode (hermite / linear / step) and
+ *  the same stored-tangent → centripetal-CR fallback chain that eval() uses.
+ *
+ *  `tangents` / `eyeTangents` / `centerTangents` are keyframe-indexed — a
+ *  keyframe's incoming tangent belongs to the previous segment, outgoing to
+ *  the next. At boundary keyframes the missing side mirrors the present one
+ *  so drawing arrows at endpoints always yields a visible vector.
+ *
+ *  Projection matrices are deliberately not exposed as a track method. Each
+ *  CameraTrack keyframe stores `fov` (perspective) or `halfHeight` (ortho)
+ *  directly on track.keyframes[i] — callers wanting a projection build one
+ *  with the free mat4Persp / mat4Ortho constructors. Animated fov in
+ *  sketches flows through the bridge's camera-binding via eval().fov and
+ *  eval().halfHeight (the bridge calls cam.perspective() / cam.ortho() each
+ *  frame).
+ *
+ * ── Class hierarchy ──────────────────────────────────────────────────────
+ *  Track (unexported, never instantiated directly)
+ *    └── PoseTrack   (exported)
+ *    └── CameraTrack (exported)
+ *
+ * ── Hook architecture ────────────────────────────────────────────────────
+ *  Lib-space hooks (underscore prefix — host layer / UI layer):
+ *    _onActivate / _onDeactivate  — fire on playing false→true / true→false.
+ *    _onPlay / _onEnd / _onStop   — mirror the user-space hooks.
+ *
+ *  User-space hooks:
+ *    onPlay : fires in play()  on false→true transition.
+ *    onEnd  : fires in tick()  at natural boundary (once mode only).
+ *    onStop : fires in stop() / reset().
+ *
+ *  Firing order:
+ *    play()  → onPlay → _onPlay → _onActivate
+ *    tick()  → onEnd  → _onEnd  → _onDeactivate
+ *    stop()  → onStop → _onStop → _onDeactivate
+ *    reset() → onStop → _onStop → _onDeactivate
+ *
+ * ── Loop modes ───────────────────────────────────────────────────────────
+ *  loop:false, bounce:false  — play once, stop at end (fires onEnd)
+ *  loop:true,  bounce:false  — repeat, wrap back to start
+ *  loop:true,  bounce:true   — bounce forever at boundaries
+ *  loop:false, bounce:true   — bounce once: flip at far boundary, stop at origin
+ *
+ * ── Playback semantics (rate + _dir) ─────────────────────────────────────
+ *  rate > 0   forward       rate < 0   backward       rate === 0 frozen
+ *
+ *  play() is the sole setter of playing = true.
+ *  stop() is the sole setter of playing = false.
+ *  Assigning rate never starts or stops playback.
+ *
+ *  _dir (internal, ±1) tracks the current bounce travel direction.
+ *  tick() advances by rate * _dir and flips _dir at boundaries.
+ *  _dir is reset to 1 only in reset().
+ *
+ * ── One-keyframe behaviour ───────────────────────────────────────────────
+ *  play() with exactly one keyframe snaps eval() to that keyframe without
+ *  setting playing = true and without firing hooks.
+ */
+
+
+// =========================================================================
+// S2  Spline / vector helpers
+// =========================================================================
+
+function _dist3(a, b) {
+  const dx=a[0]-b[0], dy=a[1]-b[1], dz=a[2]-b[2];
+  return Math.sqrt(dx*dx+dy*dy+dz*dz);
+}
+
+/**
+ * Cubic Hermite interpolation between p0 and p1 with explicit tangents.
+ * @param {number[]} out  3-element result.
+ * @param {number[]} p0   Segment start.
+ * @param {number[]} m0   Outgoing tangent at p0.
+ * @param {number[]} p1   Segment end.
+ * @param {number[]} m1   Incoming tangent at p1.
+ * @param {number}   t    Blend [0, 1].
+ * @returns {number[]} out
+ */
+const hermiteVec3 = (out, p0, m0, p1, m1, t) => {
+  const t2=t*t, t3=t2*t;
+  const h00=2*t3-3*t2+1, h10=t3-2*t2+t, h01=-2*t3+3*t2, h11=t3-t2;
+  out[0]=h00*p0[0]+h10*m0[0]+h01*p1[0]+h11*m1[0];
+  out[1]=h00*p0[1]+h10*m0[1]+h01*p1[1]+h11*m1[1];
+  out[2]=h00*p0[2]+h10*m0[2]+h01*p1[2]+h11*m1[2];
+  return out;
+};
+
+// Centripetal CR outgoing tangent at p1 for segment p1→p2.
+// Signature: (out, p0, p1, p2). Returns tangent AT p1 (the middle point).
+const _crTanOut = (out, p0, p1, p2) => {
+  const dt0=Math.pow(_dist3(p0,p1),0.5)||1, dt1=Math.pow(_dist3(p1,p2),0.5)||1;
+  for (let i=0;i<3;i++) out[i]=((p1[i]-p0[i])/dt0-(p2[i]-p0[i])/(dt0+dt1)+(p2[i]-p1[i])/dt1)*dt1;
+  return out;
+};
+
+// Centripetal CR incoming tangent at p2 for segment p1→p2.
+// Signature: (out, p1, p2, p3). Returns tangent AT p2 (the middle point).
+const _crTanIn = (out, p1, p2, p3) => {
+  const dt1=Math.pow(_dist3(p1,p2),0.5)||1, dt2=Math.pow(_dist3(p2,p3),0.5)||1;
+  for (let i=0;i<3;i++) out[i]=((p2[i]-p1[i])/dt1-(p3[i]-p1[i])/(dt1+dt2)+(p3[i]-p2[i])/dt2)*dt1;
+  return out;
+};
+
+// Module-level scratch — shared across track instances (non-reentrant hot path).
+const _m0=[0,0,0], _m1=[0,0,0];
+const _trsScratch = { pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] };
+const _eyeScratch = { eye:[0,0,0], center:[0,0,0], up:[0,1,0] };
+
+/**
+ * Linear interpolation between two vec3s.
+ */
+const lerpVec3 = (out, a, b, t) => {
+  out[0]=a[0]+t*(b[0]-a[0]);
+  out[1]=a[1]+t*(b[1]-a[1]);
+  out[2]=a[2]+t*(b[2]-a[2]);
+  return out;
+};
+
+// =========================================================================
+// S2b  Path samplers — shared core
+// =========================================================================
+
+/** @private — sample interpolated vec3 path at (seg, t) into out. */
+function _samplePathCore(out, kfs, interp, field, tanInName, tanOutName, seg, t) {
+  const n = kfs.length;
+  if (n === 0) { out[0]=0; out[1]=0; out[2]=0; return out; }
+  if (n === 1) {
+    const p = kfs[0][field];
+    out[0]=p[0]; out[1]=p[1]; out[2]=p[2];
+    return out;
+  }
+  const nSeg = n - 1;
+  seg = seg | 0;
+  if (seg >= nSeg) { seg = nSeg - 1; t = 1; }
+  else if (seg < 0) { seg = 0; t = 0; }
+  t   = _clamp01(t);
+  const k0 = kfs[seg];
+  const k1 = kfs[seg + 1];
+
+  if (interp === 'step') {
+    const p = k0[field];
+    out[0]=p[0]; out[1]=p[1]; out[2]=p[2];
+    return out;
+  }
+  if (interp === 'linear') {
+    return lerpVec3(out, k0[field], k1[field], t);
+  }
+
+  const p0 = seg > 0      ? kfs[seg - 1][field] : k0[field];
+  const p3 = seg + 2 < n  ? kfs[seg + 2][field] : k1[field];
+  const m0 = k0[tanOutName] != null ? k0[tanOutName]
+           : k0[tanInName]  != null ? k0[tanInName]
+           : _crTanOut(_m0, p0, k0[field], k1[field]);
+  const m1 = k1[tanInName]  != null ? k1[tanInName]
+           : k1[tanOutName] != null ? k1[tanOutName]
+           : _crTanIn(_m1, k0[field], k1[field], p3);
+  return hermiteVec3(out, k0[field], m0, k1[field], m1, t);
+}
+
+/** @private — write effective in/out tangents at keyframe i. */
+function _sampleTangentsCore(outIn, outOut, kfs, field, tanInName, tanOutName, i) {
+  const n = kfs.length;
+  if (n === 0) {
+    outIn[0]=outIn[1]=outIn[2]=0; outOut[0]=outOut[1]=outOut[2]=0;
+    return;
+  }
+  i = _clampS(i | 0, 0, n - 1);
+  const ki = kfs[i];
+  const hasTI = ki[tanInName]  != null;
+  const hasTO = ki[tanOutName] != null;
+
+  if (hasTO) {
+    outOut[0]=ki[tanOutName][0]; outOut[1]=ki[tanOutName][1]; outOut[2]=ki[tanOutName][2];
+  } else if (hasTI) {
+    outOut[0]=ki[tanInName][0];  outOut[1]=ki[tanInName][1];  outOut[2]=ki[tanInName][2];
+  } else if (i < n - 1) {
+    const k1 = kfs[i + 1];
+    const p0 = i > 0 ? kfs[i - 1][field] : ki[field];
+    _crTanOut(outOut, p0, ki[field], k1[field]);
+  } else {
+    outOut[0]=0; outOut[1]=0; outOut[2]=0;
+  }
+
+  if (hasTI) {
+    outIn[0]=ki[tanInName][0];  outIn[1]=ki[tanInName][1];  outIn[2]=ki[tanInName][2];
+  } else if (hasTO) {
+    outIn[0]=ki[tanOutName][0]; outIn[1]=ki[tanOutName][1]; outIn[2]=ki[tanOutName][2];
+  } else if (i > 0) {
+    const k0 = kfs[i - 1];
+    const p3 = i + 1 < n ? kfs[i + 1][field] : ki[field];
+    _crTanIn(outIn, k0[field], ki[field], p3);
+  } else {
+    outIn[0]=outOut[0]; outIn[1]=outOut[1]; outIn[2]=outOut[2];
+  }
+
+  if (i === n - 1 && !hasTO && !hasTI) {
+    outOut[0]=outIn[0]; outOut[1]=outIn[1]; outOut[2]=outIn[2];
+  }
+}
+
+// =========================================================================
+// S3  Transform <-> Mat4
+// =========================================================================
+
+/**
+ * Write a TRS transform into a column-major mat4.
+ */
+const transformToMat4 = (out, xform) => {
+  qToMat4(out, xform.rot);
+  const sx=xform.scl[0], sy=xform.scl[1], sz=xform.scl[2];
+  out[0]*=sx; out[1]*=sx; out[2]*=sx;
+  out[4]*=sy; out[5]*=sy; out[6]*=sy;
+  out[8]*=sz; out[9]*=sz; out[10]*=sz;
+  out[12]=xform.pos[0]; out[13]=xform.pos[1]; out[14]=xform.pos[2];
+  return out;
+};
+
+/**
+ * Decompose a column-major mat4 into a TRS transform.
+ */
+const mat4ToTransform = (out, m) => {
+  out.pos[0]=m[12]; out.pos[1]=m[13]; out.pos[2]=m[14];
+  const sx=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2]);
+  const sy=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6]);
+  const sz=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10]);
+  out.scl[0]=sx; out.scl[1]=sy; out.scl[2]=sz;
+  qFromRotMat3x3(out.rot,
+    m[0]/sx,m[4]/sy,m[8]/sz,
+    m[1]/sx,m[5]/sy,m[9]/sz,
+    m[2]/sx,m[6]/sy,m[10]/sz);
+  return out;
+};
+
+// =========================================================================
+// S4a  Spec parser — PoseTrack
+// =========================================================================
+
+const _isNum$1   = (x) => typeof x === 'number' && Number.isFinite(x);
+const _clamp01 = (x) => x < 0 ? 0 : (x > 1 ? 1 : x);
+const _clampS  = (x, lo, hi) => x < lo ? lo : (x > hi ? hi : x);
+
+function _parseVec3(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 && v.every(n => typeof n === 'number')) return [v[0], v[1], v[2]];
+  if (typeof v === 'object' && 'x' in v) return [v.x || 0, v.y || 0, v.z || 0];
+  return null;
+}
+
+const _EULER_AXES   = { X:[1,0,0], Y:[0,1,0], Z:[0,0,1] };
+const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
+
+/**
+ * Parse any rotation representation into a unit quaternion [x,y,z,w].
+ *
+ * Accepted forms:
+ *   [x,y,z,w]                        — raw quaternion array
+ *   { axis:[x,y,z], angle }          — axis-angle (angle in radians)
+ *   { dir:[x,y,z], up?:[x,y,z] }     — forward direction (−Z) with optional up
+ *   { mat4Eye: mat4 }                — rotation block of an eye matrix
+ *   { mat3: mat3 }                   — column-major 3×3 rotation matrix
+ *   { euler:[rx,ry,rz], order? }     — intrinsic Euler (default order: YXZ)
+ *   { from:[x,y,z], to:[x,y,z] }     — shortest-arc rotation between two vectors
+ *
+ * @param {*} v
+ * @returns {number[]|null}  [x,y,z,w] or null if unparseable.
+ */
+function _parseQuat(v) {
+  if (!v) return null;
+
+  // [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;
+
+  // { axis, angle }
+  if (v.axis != null && v.angle != null) {
+    const ax = Array.isArray(v.axis) ? v.axis : [v.axis.x||0, v.axis.y||0, v.axis.z||0];
+    return qFromAxisAngle([0,0,0,1], ax[0],ax[1],ax[2], v.angle);
+  }
+
+  // { dir, up? }
+  if (v.dir != null) {
+    const d = Array.isArray(v.dir) ? v.dir : [v.dir.x||0, v.dir.y||0, v.dir.z||0];
+    const u = v.up ? (Array.isArray(v.up) ? v.up : [v.up.x||0, v.up.y||0, v.up.z||0]) : null;
+    return qFromLookDir([0,0,0,1], d, u);
+  }
+
+  // { mat4Eye }
+  if (v.mat4Eye != null) {
+    const m = (ArrayBuffer.isView(v.mat4Eye) || Array.isArray(v.mat4Eye))
+      ? v.mat4Eye : (v.mat4Eye.mat4 ?? null);
+    if (!m || m.length < 16) return null;
+    return qFromRotMat3x3([0,0,0,1], m[0],m[4],m[8], m[1],m[5],m[9], m[2],m[6],m[10]);
+  }
+
+  // { mat3 }
+  if (v.mat3 != null) {
+    const m = (ArrayBuffer.isView(v.mat3) || Array.isArray(v.mat3)) ? v.mat3 : null;
+    if (!m || m.length < 9) return null;
+    return qFromRotMat3x3([0,0,0,1], m[0],m[3],m[6], m[1],m[4],m[7], m[2],m[5],m[8]);
+  }
+
+  // { euler, order? }
+  if (v.euler != null) {
+    const e = v.euler;
+    if (!Array.isArray(e) || e.length < 3) return null;
+    const order = (v.order && _EULER_ORDERS.has(v.order)) ? v.order : 'YXZ';
+    const q = [0,0,0,1], s = [0,0,0,1];
+    for (let i = 0; i < 3; i++) {
+      const ax = _EULER_AXES[order[i]];
+      qMul(q, q, qFromAxisAngle(s, ax[0],ax[1],ax[2], e[i]));
+    }
+    return q;
+  }
+
+  // { from, to }
+  if (v.from != null && v.to != null) {
+    const f = Array.isArray(v.from) ? v.from : [v.from.x||0, v.from.y||0, v.from.z||0];
+    const t = Array.isArray(v.to)   ? v.to   : [v.to.x||0,   v.to.y||0,   v.to.z||0];
+    const fl = Math.sqrt(f[0]*f[0]+f[1]*f[1]+f[2]*f[2]) || 1;
+    const tl = Math.sqrt(t[0]*t[0]+t[1]*t[1]+t[2]*t[2]) || 1;
+    const fx=f[0]/fl, fy=f[1]/fl, fz=f[2]/fl;
+    const tx=t[0]/tl, ty=t[1]/tl, tz=t[2]/tl;
+    const dot = fx*tx + fy*ty + fz*tz;
+    if (dot >= 1 - 1e-8) return [0,0,0,1];
+    if (dot <= -1 + 1e-8) {
+      let px=0, py=fz, pz=-fy;
+      let pl = Math.sqrt(px*px+py*py+pz*pz);
+      if (pl < 1e-8) { px=fy; py=-fx; pz=0; pl = Math.sqrt(px*px+py*py+pz*pz); }
+      if (pl < 1e-8) return [0,0,0,1];
+      return qFromAxisAngle([0,0,0,1], px/pl,py/pl,pz/pl, Math.PI);
+    }
+    let ax=fy*tz-fz*ty, ay=fz*tx-fx*tz, az=fx*ty-fy*tx;
+    const al = Math.sqrt(ax*ax+ay*ay+az*az) || 1;
+    return qFromAxisAngle([0,0,0,1], ax/al,ay/al,az/al,
+      Math.acos(Math.max(-1, Math.min(1, dot))));
+  }
+
+  return null;
+}
+
+/**
+ * Parse a PoseTrack keyframe spec into internal form.
+ *
+ * Accepted forms:
+ *   { mat4Model }
+ *     Decompose a column-major mat4 into TRS via mat4ToTransform.
+ *     Float32Array(16), plain Array, or { mat4 } wrapper.
+ *
+ *   { pos?, rot?, scl?, tanIn?, tanOut? }
+ *     Explicit TRS. pos and scl are vec3; rot accepts any form from _parseQuat.
+ *     All fields are optional — missing pos/scl default to [0,0,0] / [1,1,1],
+ *     missing rot defaults to identity.
+ *     tanIn/tanOut are optional vec3 tangents for Hermite interpolation.
+ *
+ * @param {Object} spec
+ * @returns {{ pos:number[], rot:number[], scl:number[],
+ *             tanIn:number[]|null, tanOut:number[]|null } | null}
+ */
+function _parseSpec(spec) {
+  if (!spec || typeof spec !== 'object') return null;
+
+  // { mat4Model } — full TRS decomposition from model matrix
+  if (spec.mat4Model != null) {
+    const m = (ArrayBuffer.isView(spec.mat4Model) || Array.isArray(spec.mat4Model))
+      ? spec.mat4Model : (spec.mat4Model.mat4 ?? null);
+    if (!m || m.length < 16) return null;
+    const kf = mat4ToTransform({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] }, m);
+    kf.tanIn = null; kf.tanOut = null;
+    return kf;
+  }
+
+  // { pos?, rot?, scl?, tanIn?, tanOut? } — explicit TRS
+  const pos    = _parseVec3(spec.pos)    || [0,0,0];
+  const rot    = _parseQuat(spec.rot)    || [0,0,0,1];
+  const scl    = _parseVec3(spec.scl)    || [1,1,1];
+  const tanIn  = _parseVec3(spec.tanIn)  || null;
+  const tanOut = _parseVec3(spec.tanOut) || null;
+  return { pos, rot, scl, tanIn, tanOut };
+}
+
+function _sameTransform(a, b) {
+  for (let i=0;i<3;i++) if (a.pos[i]!==b.pos[i]||a.scl[i]!==b.scl[i]) return false;
+  for (let i=0;i<4;i++) if (a.rot[i]!==b.rot[i]) return false;
+  return true;
+}
+
+// =========================================================================
+// S4b  Spec parser — CameraTrack
+// =========================================================================
+
+// Lens defaults used when a spec omits near/far. Match the three.js /
+// Bevy conventions and are safe for typical p5 v2 scene scales.
+const _DEFAULT_NEAR = 0.1;
+const _DEFAULT_FAR  = 1000;
+
+/**
+ * Parse a CameraTrack keyframe spec into internal form.
+ *
+ * Required: eye (vec3). Everything else is optional.
+ *   center       defaults to [0, 0, 0]
+ *   up           defaults to [0, 1, 0] and is normalised
+ *   fov          vertical fov (radians), perspective only — null if absent
+ *   halfHeight   world-unit half-height of ortho frustum — null if absent
+ *   near         near clip distance (positive) — defaults to 0.1
+ *   far          far  clip distance (positive) — defaults to 1000
+ *   eyeTanIn/Out       optional Hermite tangents for the eye path
+ *   centerTanIn/Out    optional Hermite tangents for the center path
+ *
+ * fov and halfHeight are mutually exclusive (perspective xor ortho) and
+ * therefore left nullable; eval() lerps each only when both adjacent
+ * keyframes carry a non-null value, passing null through otherwise.
+ *
+ * near and far are always meaningful regardless of projection type, so
+ * they receive real defaults and are linearly interpolated unconditionally.
+ *
+ * @param {Object} spec
+ * @returns {Object|null}  Parsed keyframe or null if eye is missing/malformed.
+ */
+function _parseCameraSpec(spec) {
+  if (!spec || typeof spec !== 'object') return null;
+  const eye = _parseVec3(spec.eye);
+  if (!eye) return null;
+  const center = _parseVec3(spec.center) || [0,0,0];
+  const upRaw  = spec.up ? _parseVec3(spec.up) : null;
+  const up     = upRaw || [0,1,0];
+  const ul     = Math.sqrt(up[0]*up[0]+up[1]*up[1]+up[2]*up[2]) || 1;
+  return {
+    eye, center,
+    up: [up[0]/ul, up[1]/ul, up[2]/ul],
+    fov:          typeof spec.fov        === 'number' ? spec.fov        : null,
+    halfHeight:   typeof spec.halfHeight === 'number' ? spec.halfHeight : null,
+    near:         typeof spec.near       === 'number' ? spec.near       : _DEFAULT_NEAR,
+    far:          typeof spec.far        === 'number' ? spec.far        : _DEFAULT_FAR,
+    eyeTanIn:     _parseVec3(spec.eyeTanIn)    || null,
+    eyeTanOut:    _parseVec3(spec.eyeTanOut)   || null,
+    centerTanIn:  _parseVec3(spec.centerTanIn) || null,
+    centerTanOut: _parseVec3(spec.centerTanOut)|| null,
+  };
+}
+
+function _sameCameraKeyframe(a, b) {
+  for (let i=0;i<3;i++) {
+    if (a.eye[i]!==b.eye[i]) return false;
+    if (a.center[i]!==b.center[i]) return false;
+    if (a.up[i]!==b.up[i]) return false;
+  }
+  if (a.fov !== b.fov) return false;
+  if (a.halfHeight !== b.halfHeight) return false;
+  if (a.near !== b.near) return false;
+  if (a.far  !== b.far)  return false;
+  return true;
+}
+
+// =========================================================================
+// S5  Track — unexported base class (transport machinery only)
+// =========================================================================
+
+class Track {
+  constructor() {
+    /** @type {Array} Keyframe array — shape depends on subclass. */
+    this.keyframes = [];
+    /** Whether playback is currently active. @type {boolean} */
+    this.playing   = false;
+    /** Loop at boundaries. @type {boolean} */
+    this.loop      = false;
+    /** Ping-pong bounce at boundaries (independent of loop). @type {boolean} */
+    this.bounce    = false;
+    /** Frames per segment (≥1). @type {number} */
+    this.duration  = 30;
+    /** Current segment index. @type {number} */
+    this.seg       = 0;
+    /** Frame offset within current segment (can be fractional). @type {number} */
+    this.f         = 0;
+
+    // Playback rate (signed: negative = reverse; 0 = frozen).
+    this._rate = 1;
+    // Current bounce travel direction (±1). Reset to 1 only on reset().
+    this._dir  = 1;
+    // Whether a bounce-once has already flipped direction.
+    this._bounced = false;
+
+    /** User hook: fires on play() false→true transition. @type {Function|null} */
+    this.onPlay = null;
+    /** User hook: fires on natural boundary in once mode. @type {Function|null} */
+    this.onEnd  = null;
+    /** User hook: fires on stop() / reset() / end-of-bounce-once. @type {Function|null} */
+    this.onStop = null;
+
+    // Lib-space hooks (underscore prefix — host layer / UI layer only).
+    this._onActivate = null; this._onDeactivate = null;
+    this._onPlay     = null; this._onEnd         = null; this._onStop = null;
+  }
+
+  /** Playback rate. Signed: negative reverses, 0 freezes. Assigning never starts or stops playback. @type {number} */
+  get rate()  { return this._rate; }
+  set rate(v) { this._rate = (_isNum$1(v)) ? v : 1; }
+
+  /** Number of interpolatable segments (keyframes.length − 1, min 0). @type {number} */
+  get segments() { return Math.max(0, this.keyframes.length - 1); }
+
+  /**
+   * @private — resolve cursor (seg, f) into continuous (seg, t).
+   * Shared backing of every cursor-form sampler / matrix method.
+   */
+  _cursorSegT() {
+    const nSeg = this.segments;
+    const dur  = Math.max(1, this.duration | 0);
+    const seg  = nSeg > 0 ? _clampS(this.seg, 0, nSeg - 1) : 0;
+    const t    = _clamp01(this.f / dur);
+    return [seg, t];
+  }
+
+  /**
+   * Start or update playback. Sole setter of `playing = true`.
+   *
+   * Fires `onPlay → _onPlay → _onActivate` only on a false→true transition.
+   * Zero keyframes: no-op. Exactly one keyframe: snaps eval() to it but does
+   * not set `playing` and fires no hooks.
+   *
+   * @param {number|{duration?:number,loop?:boolean,bounce?:boolean,
+   *                 rate?:number,onPlay?:Function,onEnd?:Function,
+   *                 onStop?:Function}} [rateOrOpts]
+   *        A bare number is taken as `rate`; an object configures multiple
+   *        fields in one call.
+   * @returns {Track} this
+   */
+  play(rateOrOpts) {
+    if (this.keyframes.length === 0) return this;
+    if (this.keyframes.length === 1) { this.seg = 0; this.f = 0; return this; }
+
+    if (typeof rateOrOpts === 'number' && Number.isFinite(rateOrOpts)) {
+      this._rate = rateOrOpts;
+    } else if (rateOrOpts && typeof rateOrOpts === 'object') {
+      const o = rateOrOpts;
+      if (_isNum$1(o.duration))             this.duration = Math.max(1, o.duration | 0);
+      if ('loop'   in o) this.loop   = !!o.loop;
+      if ('bounce' in o) this.bounce = !!o.bounce;
+      if (typeof o.onPlay === 'function') this.onPlay = o.onPlay;
+      if (typeof o.onEnd  === 'function') this.onEnd  = o.onEnd;
+      if (typeof o.onStop === 'function') this.onStop = o.onStop;
+      if (_isNum$1(o.rate))                 this._rate  = o.rate;
+    }
+
+    const nSeg = this.segments, dur = Math.max(1, this.duration | 0);
+    if (this.seg < 0)     this.seg = 0;
+    if (this.seg >= nSeg) this.seg = nSeg - 1;
+    if (this.f   < 0)     this.f   = 0;
+    if (this.f   > dur)   this.f   = dur;
+
+    const wasPlaying = this.playing;
+    this.playing = true;
+    if (!wasPlaying) {
+      this._bounced = false;
+      if (typeof this.onPlay === 'function') { try { this.onPlay(this); } catch (_) {} }
+      this._onPlay?.();
+      this._onActivate?.();
+    }
+    return this;
+  }
+
+  /**
+   * Stop playback. Sole setter of `playing = false`. Fires
+   * `onStop → _onStop → _onDeactivate` on a true→false transition.
+   *
+   * @param {boolean} [rewind]  If true, seek to the origin end after stopping
+   *                            (0 when playing forward, 1 when playing backward).
+   * @returns {Track} this
+   */
+  stop(rewind) {
+    const wasPlaying = this.playing;
+    this.playing = false;
+    if (wasPlaying) {
+      this._bounced = false;
+      if (typeof this.onStop === 'function') { try { this.onStop(this); } catch (_) {} }
+      this._onStop?.();
+      this._onDeactivate?.();
+      if (rewind && this.keyframes.length > 1) this.seek(this._rate * this._dir < 0 ? 1 : 0);
+    }
+    return this;
+  }
+
+  /**
+   * Clear all keyframes and stop. Fires stop-side hooks if it was playing.
+   * Unlike stop(), this also resets `_dir` to +1.
+   * @returns {Track} this
+   */
+  reset() {
+    const wasPlaying = this.playing;
+    this.playing = false;
+    if (wasPlaying) {
+      if (typeof this.onStop === 'function') { try { this.onStop(this); } catch (_) {} }
+      this._onStop?.();
+      this._onDeactivate?.();
+    }
+    this.keyframes.length = 0;
+    this.seg = 0; this.f = 0; this._dir = 1; this._bounced = false;
+    return this;
+  }
+
+  /**
+   * Remove the keyframe at `index`. Adjusts the cursor if the removal shrinks
+   * the track below the current segment.
+   * @param {number} index
+   * @returns {boolean}  true if removed; false if index was invalid.
+   */
+  remove(index) {
+    if (!_isNum$1(index)) return false;
+    const i = index | 0;
+    if (i < 0 || i >= this.keyframes.length) return false;
+    this.keyframes.splice(i, 1);
+    const nSeg = this.segments;
+    if (nSeg === 0) { this.seg = 0; this.f = 0; }
+    else if (this.seg >= nSeg) { this.seg = nSeg - 1; }
+    return true;
+  }
+
+  /**
+   * Move the cursor.
+   *   seek(t)            Scrub to normalised position t ∈ [0, 1] across the
+   *                      whole track.
+   *   seek(t, segIndex)  Position within a specific segment — t is local to
+   *                      that segment.
+   * Does not affect `playing`.
+   *
+   * @param {number} t
+   * @param {number} [segIndex]
+   * @returns {Track} this
+   */
+  seek(t, segIndex) {
+    const nSeg = this.segments;
+    if (nSeg === 0) { this.seg = 0; this.f = 0; return this; }
+    const dur = Math.max(1, this.duration | 0);
+    if (_isNum$1(segIndex)) {
+      this.seg = _clampS(segIndex | 0, 0, nSeg - 1);
+      this.f   = _clamp01(t) * dur;
+    } else {
+      this._setCursorFromScalar(_clamp01(t) * nSeg * dur);
+    }
+    return this;
+  }
+
+  /**
+   * Normalised cursor position across the whole track.
+   * @returns {number}  ∈ [0, 1]; 0 when there are no segments.
+   */
+  time() {
+    const nSeg = this.segments;
+    if (nSeg === 0) return 0;
+    const dur = Math.max(1, this.duration | 0);
+    return _clamp01((this.seg * dur + this.f) / (nSeg * dur));
+  }
+
+  /**
+   * Snapshot of transport state. Allocates a new object per call — intended
+   * for UI / debugging, not hot loops.
+   * @returns {{keyframes:number, segments:number, seg:number, f:number,
+   *            playing:boolean, loop:boolean, bounce:boolean, rate:number,
+   *            duration:number, time:number}}
+   */
+  info() {
+    return {
+      keyframes: this.keyframes.length,
+      segments:  this.segments,
+      seg:       this.seg,
+      f:         this.f,
+      playing:   this.playing,
+      loop:      this.loop,
+      bounce:    this.bounce,
+      rate:      this._rate,
+      duration:  this.duration,
+      time:      this.segments > 0 ? this.time() : 0
+    };
+  }
+
+  /**
+   * Advance the cursor by `rate * _dir` in frames. Handles loop / bounce /
+   * once modes per the table in the module header. Fires `onEnd → _onEnd →
+   * _onDeactivate` at a natural boundary in once mode.
+   *
+   * Intended to be called once per animation frame by the bridge / UI layer.
+   * rate === 0 freezes the cursor but keeps `playing` unchanged.
+   *
+   * @returns {boolean}  Current `playing` state after advancing.
+   */
+  tick() {
+    if (!this.playing) return false;
+    const nSeg = this.segments;
+    if (nSeg === 0) { this.playing = false; this._onDeactivate?.(); return false; }
+    if (this._rate === 0) return true;
+
+    const dur   = Math.max(1, this.duration | 0);
+    const total = nSeg * dur;
+    const s     = _clampS(this.seg * dur + this.f, 0, total);
+    const next  = s + this._rate * this._dir;
+
+    if (this.loop && this.bounce) {
+      let pos = next, flips = 0;
+      while (pos < 0 || pos > total) {
+        if (pos < 0) { pos = -pos; flips++; }
+        else         { pos = 2 * total - pos; flips++; }
+      }
+      if (flips & 1) this._dir = -this._dir;
+      this._setCursorFromScalar(pos);
+      return true;
+    }
+
+    if (!this.loop && this.bounce) {
+      if (next >= total) {
+        this._setCursorFromScalar(Math.min(total, 2 * total - next));
+        this._dir = -this._dir;
+        this._bounced = true;
+        return true;
+      }
+      if (next <= 0) {
+        this._setCursorFromScalar(0);
+        this.playing = false;
+        this._dir = 1; this._bounced = false;
+        if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+        this._onEnd?.();
+        this._onDeactivate?.();
+        return false;
+      }
+      this._setCursorFromScalar(next);
+      return true;
+    }
+
+    if (this.loop) {
+      this._setCursorFromScalar(((next % total) + total) % total);
+      return true;
+    }
+
+    if (next <= 0) {
+      this._setCursorFromScalar(0);
+      this.playing = false;
+      if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+      this._onEnd?.();
+      this._onDeactivate?.();
+      return false;
+    }
+    if (next >= total) {
+      this._setCursorFromScalar(total);
+      this.playing = false;
+      if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+      this._onEnd?.();
+      this._onDeactivate?.();
+      return false;
+    }
+
+    this._setCursorFromScalar(next);
+    return true;
+  }
+
+  /** @private */
+  _setCursorFromScalar(s) {
+    const dur  = Math.max(1, this.duration | 0);
+    const nSeg = this.segments;
+    this.seg = Math.floor(s / dur);
+    this.f   = s - this.seg * dur;
+    if (this.seg >= nSeg) { this.seg = nSeg - 1; this.f = dur; }
+    if (this.seg < 0)     { this.seg = 0;         this.f = 0;   }
+  }
+}
+
+// =========================================================================
+// S6  PoseTrack
+// =========================================================================
+
+/**
+ * Renderer-agnostic TRS keyframe track.
+ *
+ * Keyframe shape: { pos:[x,y,z], rot:[x,y,z,w], scl:[x,y,z],
+ *                   tanIn?:[x,y,z], tanOut?:[x,y,z] }
+ *
+ * tanIn  — incoming position tangent at this keyframe (Hermite mode).
+ * tanOut — outgoing position tangent at this keyframe (Hermite mode).
+ * When only one is supplied, the other mirrors it at sample time.
+ * When neither is supplied, centripetal Catmull-Rom tangents are auto-computed.
+ */
+class PoseTrack extends Track {
+  constructor() {
+    super();
+    /**
+     * Position interpolation mode.
+     * - 'hermite' — cubic Hermite; auto-computes centripetal Catmull-Rom
+     *               tangents when none are stored (default)
+     * - 'linear'  — lerp
+     * - 'step'    — snap to k0; useful for discrete state changes
+     * @type {'hermite'|'linear'|'step'}
+     */
+    this.posInterp = 'hermite';
+    /**
+     * Rotation interpolation mode.
+     * - 'slerp'  — constant angular velocity (default)
+     * - 'nlerp'  — normalised lerp; cheaper, slightly non-constant speed
+     * - 'step'   — snap to k0 quaternion
+     * @type {'slerp'|'nlerp'|'step'}
+     */
+    this.rotInterp = 'slerp';
+  }
+
+  /**
+   * Append one or more keyframes. Adjacent duplicates are skipped by default.
+   * Accepts any spec form understood by _parseSpec, or an array of them.
+   * @param {Object|Object[]} spec
+   * @param {{ deduplicate?: boolean }} [opts]
+   */
+  add(spec, opts) {
+    if (Array.isArray(spec)) { for (const s of spec) this.add(s, opts); return; }
+    const kf = _parseSpec(spec);
+    if (!kf) return;
+    const dedup = !opts || opts.deduplicate !== false;
+    if (dedup && this.keyframes.length > 0) {
+      if (_sameTransform(this.keyframes[this.keyframes.length - 1], kf)) return;
+    }
+    this.keyframes.push(kf);
+  }
+
+  /**
+   * Replace the keyframe at `index`, or append at the end if `index` equals
+   * the current keyframe count.
+   * @param {number} index
+   * @param {Object} spec  Any spec form understood by _parseSpec.
+   * @returns {boolean}  true on success; false for invalid index or spec.
+   */
+  set(index, spec) {
+    if (!_isNum$1(index)) return false;
+    const i = index | 0, kf = _parseSpec(spec);
+    if (!kf || i < 0 || i > this.keyframes.length) return false;
+    if (i === this.keyframes.length) this.keyframes.push(kf);
+    else this.keyframes[i] = kf;
+    return true;
+  }
+
+  /**
+   * Sample the position path. Zero-alloc, no cursor side effects. Honours
+   * posInterp and the stored-tangent → auto-CR fallback chain.
+   *
+   * Two signatures:
+   *   samplePos(out)              cursor form — reads current seg/f
+   *   samplePos(out, seg, t)      explicit (seg, t), continuous on the path
+   *
+   * @param {number[]} out  3-element result buffer.
+   * @param {number} [seg]  Segment index in [0, segments−1]. Omit for cursor.
+   * @param {number} [t]    Local parameter in [0, 1]. Omit for cursor.
+   * @returns {number[]} out
+   */
+  samplePos(out, seg, t) {
+    if (arguments.length < 3) [seg, t] = this._cursorSegT();
+    return _samplePathCore(out, this.keyframes, this.posInterp, 'pos', 'tanIn', 'tanOut', seg, t);
+  }
+
+  /**
+   * Write the TRS pose as a column-major model mat4. Zero-alloc, no cursor
+   * side effects.
+   *
+   * Two signatures:
+   *   mat4Model(out)              cursor form — reads current seg/f
+   *   mat4Model(out, seg, t)      explicit (seg, t), continuous on the path
+   *
+   * Replaces the previous toMatrix() method.
+   *
+   * @param {Float32Array|number[]} out  16-element result buffer.
+   * @param {number} [seg]  Segment index in [0, segments−1]. Omit for cursor.
+   * @param {number} [t]    Local parameter in [0, 1]. Omit for cursor.
+   * @returns {Float32Array|number[]} out
+   */
+  mat4Model(out, seg, t) {
+    if (arguments.length < 3) [seg, t] = this._cursorSegT();
+    this._sampleTRS(_trsScratch, seg, t);
+    return transformToMat4(out, _trsScratch);
+  }
+
+  /**
+   * Effective incoming / outgoing position tangents at keyframe `index`.
+   * Stored tanIn/tanOut take precedence; each mirrors the other when only
+   * one is stored; else centripetal Catmull-Rom tangents are auto-computed
+   * from neighbours. Boundary keyframes mirror across the missing side.
+   *
+   * @param {number[]} outIn   3-element result — incoming tangent.
+   * @param {number[]} outOut  3-element result — outgoing tangent.
+   * @param {number} index     Keyframe index.
+   * @returns {PoseTrack} this
+   */
+  tangents(outIn, outOut, index) {
+    _sampleTangentsCore(outIn, outOut, this.keyframes, 'pos', 'tanIn', 'tanOut', index);
+    return this;
+  }
+
+  /** @private — write interpolated TRS at (seg, t). */
+  _sampleTRS(out, seg, t) {
+    const n = this.keyframes.length;
+    if (n === 0) return out;
+    if (n === 1) {
+      const k = this.keyframes[0];
+      out.pos[0]=k.pos[0]; out.pos[1]=k.pos[1]; out.pos[2]=k.pos[2];
+      out.rot[0]=k.rot[0]; out.rot[1]=k.rot[1]; out.rot[2]=k.rot[2]; out.rot[3]=k.rot[3];
+      out.scl[0]=k.scl[0]; out.scl[1]=k.scl[1]; out.scl[2]=k.scl[2];
+      return out;
+    }
+    const nSeg = n - 1;
+    seg = seg | 0;
+    if (seg >= nSeg) { seg = nSeg - 1; t = 1; }
+    else if (seg < 0) { seg = 0; t = 0; }
+    t   = _clamp01(t);
+    const k0 = this.keyframes[seg];
+    const k1 = this.keyframes[seg + 1];
+
+    _samplePathCore(out.pos, this.keyframes, this.posInterp, 'pos', 'tanIn', 'tanOut', seg, t);
+
+    if (this.rotInterp === 'step') {
+      out.rot[0]=k0.rot[0]; out.rot[1]=k0.rot[1]; out.rot[2]=k0.rot[2]; out.rot[3]=k0.rot[3];
+    } else if (this.rotInterp === 'nlerp') {
+      qNlerp(out.rot, k0.rot, k1.rot, t);
+    } else {
+      qSlerp(out.rot, k0.rot, k1.rot, t);
+    }
+
+    lerpVec3(out.scl, k0.scl, k1.scl, t);
+    return out;
+  }
+
+  /**
+   * Evaluate interpolated TRS pose at current cursor.
+   * @param {{ pos:number[], rot:number[], scl:number[] }} [out]
+   * @returns {{ pos:number[], rot:number[], scl:number[] }} out
+   */
+  eval(out) {
+    out = out || { pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] };
+    const n = this.keyframes.length;
+    if (n === 0) return out;
+    if (n === 1) return this._sampleTRS(out, 0, 0);
+    const [seg, t] = this._cursorSegT();
+    return this._sampleTRS(out, seg, t);
+  }
+}
+
+// =========================================================================
+// S7  CameraTrack
+// =========================================================================
+
+/**
+ * Lookat camera keyframe track.
+ *
+ * Keyframe shape: { eye:[x,y,z], center:[x,y,z], up:[x,y,z],
+ *                   fov?:number, halfHeight?:number,
+ *                   near:number, far:number,
+ *                   eyeTanIn?:[x,y,z], eyeTanOut?:[x,y,z],
+ *                   centerTanIn?:[x,y,z], centerTanOut?:[x,y,z] }
+ *
+ * fov        — vertical fov (radians) for perspective cameras; null for ortho.
+ * halfHeight — world-unit half-height of ortho frustum; null for perspective.
+ * Both are optional and nullable because exactly one is meaningful per
+ * keyframe (perspective xor ortho). eval() lerps each only when both
+ * adjacent keyframes carry a non-null value for that field; mixed or
+ * missing entries pass `null` through.
+ *
+ * near, far — clip plane distances (positive, world units). Always real
+ * numbers. Defaults: near = 0.1, far = 1000 (three.js / Bevy convention).
+ * Linearly interpolated between keyframes without null-passthrough.
+ *
+ * eyeTanIn/Out and centerTanIn/Out are optional vec3 tangents for Hermite
+ * interpolation of the eye and center paths respectively. When absent,
+ * centripetal Catmull-Rom tangents are auto-computed at sample time.
+ *
+ * Missing fields default to: center → [0,0,0], up → [0,1,0],
+ * near → 0.1, far → 1000.
+ *
+ * For matrix-based capture of a camera-like pose use
+ * PoseTrack.add({ mat4Model: mat4Eye }) for full TRS fidelity including roll,
+ * or a lookat spec here for camera-style interpolation.
+ */
+class CameraTrack extends Track {
+  constructor() {
+    super();
+    /**
+     * Eye-path interpolation mode.
+     * @type {'hermite'|'linear'|'step'}
+     */
+    this.eyeInterp = 'hermite';
+    /**
+     * Center-path interpolation mode.
+     * @type {'hermite'|'linear'|'step'}
+     */
+    this.centerInterp = 'linear';
+  }
+
+  /**
+   * Append one or more camera keyframes. Adjacent duplicates are skipped by
+   * default.
+   * @param {Object|Object[]} spec
+   * @param {{ deduplicate?: boolean }} [opts]
+   */
+  add(spec, opts) {
+    if (Array.isArray(spec)) { for (const s of spec) this.add(s, opts); return; }
+    const kf = _parseCameraSpec(spec);
+    if (!kf) return;
+    const dedup = !opts || opts.deduplicate !== false;
+    if (dedup && this.keyframes.length > 0) {
+      if (_sameCameraKeyframe(this.keyframes[this.keyframes.length - 1], kf)) return;
+    }
+    this.keyframes.push(kf);
+  }
+
+  /**
+   * Replace the camera keyframe at `index`, or append at the end if `index`
+   * equals the current keyframe count.
+   * @param {number} index
+   * @param {Object} spec
+   * @returns {boolean}
+   */
+  set(index, spec) {
+    if (!_isNum$1(index)) return false;
+    const i = index | 0, kf = _parseCameraSpec(spec);
+    if (!kf || i < 0 || i > this.keyframes.length) return false;
+    if (i === this.keyframes.length) this.keyframes.push(kf);
+    else this.keyframes[i] = kf;
+    return true;
+  }
+
+  /**
+   * Sample the eye path. Zero-alloc, no cursor side effects.
+   *
+   * Two signatures:
+   *   sampleEye(out)              cursor form — reads current seg/f
+   *   sampleEye(out, seg, t)      explicit (seg, t), continuous on the path
+   *
+   * @param {number[]} out
+   * @param {number} [seg]
+   * @param {number} [t]
+   * @returns {number[]} out
+   */
+  sampleEye(out, seg, t) {
+    if (arguments.length < 3) [seg, t] = this._cursorSegT();
+    return _samplePathCore(out, this.keyframes, this.eyeInterp, 'eye', 'eyeTanIn', 'eyeTanOut', seg, t);
+  }
+
+  /**
+   * Sample the center path. Zero-alloc, no cursor side effects.
+   *
+   * Two signatures:
+   *   sampleCenter(out)              cursor form — reads current seg/f
+   *   sampleCenter(out, seg, t)      explicit (seg, t)
+   *
+   * @param {number[]} out
+   * @param {number} [seg]
+   * @param {number} [t]
+   * @returns {number[]} out
+   */
+  sampleCenter(out, seg, t) {
+    if (arguments.length < 3) [seg, t] = this._cursorSegT();
+    return _samplePathCore(out, this.keyframes, this.centerInterp, 'center', 'centerTanIn', 'centerTanOut', seg, t);
+  }
+
+  /**
+   * Write the interpolated lookat eye matrix as a column-major mat4
+   * (eye→world rigid frame). Zero-alloc, no cursor side effects.
+   *
+   * Two signatures:
+   *   mat4Eye(out)              cursor form — reads current seg/f
+   *   mat4Eye(out, seg, t)      explicit (seg, t), continuous on the path
+   *
+   * @param {Float32Array|number[]} out  16-element result buffer.
+   * @param {number} [seg]
+   * @param {number} [t]
+   * @returns {Float32Array|number[]} out
+   */
+  mat4Eye(out, seg, t) {
+    if (arguments.length < 3) [seg, t] = this._cursorSegT();
+    this._sampleEyePose(_eyeScratch, seg, t);
+    const e = _eyeScratch;
+    return mat4Eye(out,
+      e.eye[0], e.eye[1], e.eye[2],
+      e.center[0], e.center[1], e.center[2],
+      e.up[0], e.up[1], e.up[2]);
+  }
+
+  /**
+   * Effective in/out eye tangents at keyframe `index`.
+   */
+  eyeTangents(outIn, outOut, index) {
+    _sampleTangentsCore(outIn, outOut, this.keyframes, 'eye', 'eyeTanIn', 'eyeTanOut', index);
+    return this;
+  }
+
+  /**
+   * Effective in/out center tangents at keyframe `index`.
+   */
+  centerTangents(outIn, outOut, index) {
+    _sampleTangentsCore(outIn, outOut, this.keyframes, 'center', 'centerTanIn', 'centerTanOut', index);
+    return this;
+  }
+
+  /** @private — write interpolated { eye, center, up } at (seg, t). */
+  _sampleEyePose(out, seg, t) {
+    const n = this.keyframes.length;
+    if (n === 0) return out;
+    if (n === 1) {
+      const k = this.keyframes[0];
+      out.eye[0]=k.eye[0];       out.eye[1]=k.eye[1];       out.eye[2]=k.eye[2];
+      out.center[0]=k.center[0]; out.center[1]=k.center[1]; out.center[2]=k.center[2];
+      out.up[0]=k.up[0];         out.up[1]=k.up[1];         out.up[2]=k.up[2];
+      return out;
+    }
+    const nSeg = n - 1;
+    seg = seg | 0;
+    if (seg >= nSeg) { seg = nSeg - 1; t = 1; }
+    else if (seg < 0) { seg = 0; t = 0; }
+    t   = _clamp01(t);
+    const k0 = this.keyframes[seg];
+    const k1 = this.keyframes[seg + 1];
+
+    _samplePathCore(out.eye,    this.keyframes, this.eyeInterp,    'eye',    'eyeTanIn',    'eyeTanOut',    seg, t);
+    _samplePathCore(out.center, this.keyframes, this.centerInterp, 'center', 'centerTanIn', 'centerTanOut', seg, t);
+
+    lerpVec3(out.up, k0.up, k1.up, t);
+    const ul = Math.sqrt(out.up[0]*out.up[0]+out.up[1]*out.up[1]+out.up[2]*out.up[2]) || 1;
+    out.up[0]/=ul; out.up[1]/=ul; out.up[2]/=ul;
+    return out;
+  }
+
+  /**
+   * Evaluate interpolated camera pose at current cursor.
+   *
+   * `fov` / `halfHeight` are lerped only when both adjacent keyframes carry
+   * a non-null value; mixed entries pass `null` through so the bridge can
+   * leave the projection unchanged.
+   *
+   * `near` / `far` are always real numbers and are linearly interpolated
+   * unconditionally.
+   *
+   * @param {{ eye:number[], center:number[], up:number[],
+   *           fov:number|null, halfHeight:number|null,
+   *           near:number, far:number }} [out]
+   * @returns {{ eye:number[], center:number[], up:number[],
+   *             fov:number|null, halfHeight:number|null,
+   *             near:number, far:number }} out
+   */
+  eval(out) {
+    out = out || { eye:[0,0,0], center:[0,0,0], up:[0,1,0],
+                   fov:null, halfHeight:null,
+                   near:_DEFAULT_NEAR, far:_DEFAULT_FAR };
+    const n = this.keyframes.length;
+    if (n === 0) return out;
+    if (n === 1) {
+      const k = this.keyframes[0];
+      this._sampleEyePose(out, 0, 0);
+      out.fov = k.fov; out.halfHeight = k.halfHeight;
+      out.near = k.near; out.far = k.far;
+      return out;
+    }
+    const [seg, t] = this._cursorSegT();
+    const k0 = this.keyframes[seg];
+    const k1 = this.keyframes[seg + 1];
+
+    this._sampleEyePose(out, seg, t);
+
+    out.fov = (k0.fov != null && k1.fov != null)
+      ? k0.fov + t * (k1.fov - k0.fov) : (k0.fov ?? k1.fov ?? null);
+    out.halfHeight = (k0.halfHeight != null && k1.halfHeight != null)
+      ? k0.halfHeight + t * (k1.halfHeight - k0.halfHeight)
+      : (k0.halfHeight ?? k1.halfHeight ?? null);
+
+    // near / far carry real defaults on every keyframe — always lerp.
+    out.near = k0.near + t * (k1.near - k0.near);
+    out.far  = k0.far  + t * (k1.far  - k0.far);
+
+    return out;
+  }
+}
+
+/**
+ * @file Constraint solver, canonical handle state, and ray-primitive
+ *       intersections for interactive manipulators.
+ * @module tree/handle
+ * @license AGPL-3.0-only
+ *
+ * The numeric brain of the manipulator handle. Renderer- and frame-agnostic:
+ * inputs are plain numbers in ONE working space chosen by the caller (the
+ * bridge), and the solver never learns world vs eye — it solves in whatever
+ * space the ray and geometry are expressed in. The bridge converts the pointer
+ * ray into the working frame before calling solve(), and converts the value
+ * back out via mapLocation / mapDirection.
+ *
+ * Zero dependencies on p5, DOM, WebGL, or WebGPU. Out-first throughout; no
+ * allocation in solve() / value(). Vectors are passed as flat scalars (matching
+ * form.js), state is held as plain number[] (matching track.js keyframes).
+ *
+ * ── Storage convention ─────────────────────────────────────────────────────
+ * The core distinguishes two value shapes deliberately:
+ *   mat4   — 16-element ArrayLike, typically Float32Array, because matrices
+ *            cross the GL boundary (contiguous f32 is what the renderer wants).
+ *   vec3 / quat — plain number[] (f64), because they are authoring/state values
+ *            and because the frozen basis-vector constants (i, j, k, ORIGIN)
+ *            cannot be expressed as frozen typed arrays. Handle state follows
+ *            the vec3 rule.
+ *
+ * ── Constraint kinds ───────────────────────────────────────────────────────
+ *   SPHERE  2-DOF heading on a sphere of radius r about an anchor.
+ *           Canonical state is a UNIT DIRECTION (renormalised every solve) —
+ *           no stored Euler angles, so no gimbal degeneracy at the poles.
+ *           az/el are derived on request via azEl().
+ *   PLANE   2-DOF point on a fixed plane (anchor + unit normal).
+ *   AXIS    1-DOF point on a line (anchor + unit dir), scalar t clamped to extent.
+ *   DIAL    1-DOF angle on a circle of radius r in the plane (anchor, axis).
+ *           Canonical state is an ACCUMULATED angle θ (multi-turn winding is
+ *           preserved: each solve applies the smaller signed arc, so θ counts
+ *           full turns — essential for bind targets like "rotate this 720°").
+ *           θ=0 sits at the reference direction `zero` (derived from the axis
+ *           when not supplied); θ grows right-handed about the axis. Near
+ *           edge-on view (the ray almost parallel to the dial plane, where a
+ *           plane hit races to infinity — the classic rotate-gizmo failure)
+ *           the solve falls back to the TANGENT LINE of the circle at the
+ *           current angle, converting linear drag to dθ: bounded, monotone,
+ *           and still pure ray geometry.
+ *
+ *   VIEW (the camera-facing free-translate constraint) is NOT a core kind: the
+ *   bridge implements it with PLANE, feeding a fresh camera-derived normal and
+ *   anchor each frame. The core stays oblivious to the camera.
+ *
+ * ── Report modes ───────────────────────────────────────────────────────────
+ *   DIRECTION  value() writes the unit direction: SPHERE → the heading;
+ *              DIAL → the radial unit at θ.
+ *   POINT      value() writes a position: SPHERE → anchor + dir·radius;
+ *              DIAL → the point on the circle; PLANE / AXIS → the constrained
+ *              point.
+ *
+ * ── State ownership & portability ──────────────────────────────────────────
+ * Each Constraint owns its own state; there is no module-level scratch. solve()
+ * writes into instance fields, never shared globals. This keeps the type a
+ * plain-data state machine: it ports 1:1 to a Rust enum + impl that is
+ * `Send + Sync` for free, with `&mut self` on solve() making concurrent
+ * mutation a compile error. The binding closure deliberately lives in the
+ * bridge, not here — a stored callback would forfeit that guarantee.
+ *
+ * ── Extension contract ─────────────────────────────────────────────────────
+ * 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 — 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
+ * normals and directions are normalised at construction. The angular utilities
+ * use a right-handed convention: az about +Y, el measured from the XZ plane.
+ * solve() does NOT depend on this convention — it stores the hit direction
+ * directly; az/el are a readout/authoring convenience only. DIAL's θ is
+ * right-handed about its own axis, measured from `zero`.
+ */
+
+
+const EPS = 1e-6;
+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.
+// ≈ 4.6° of incidence. Tune empirically (handle-experiments/e2).
+const DIAL_EDGE = 0.08;
+
+// =========================================================================
+// H1  Small private helpers
+// =========================================================================
+
+const _isNum = (x) => typeof x === 'number' && Number.isFinite(x);
+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$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$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]];
+  if (typeof v === 'object' && 'x' in v) return [v.x || 0, v.y || 0, v.z || 0];
+  return null;
+}
+
+/** Normalise a vec3 in place; zero-length falls back to the given default axis. */
+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;
+  return v;
+}
+
+/**
+ * Orthonormal in-plane basis for a unit normal n, written into ub, vb. Seeds
+ * from the world axis least aligned with n so the first cross can't degenerate.
+ * (Same derivation the p5 bridge uses for its plane quad — duplicated here
+ * because the core cannot depend on the bridge.)
+ */
+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$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];
+}
+
+// =========================================================================
+// H2  Ray-primitive intersections (pure, out-first, scalar params)
+// =========================================================================
+
+/**
+ * Nearest ray–sphere intersection. The ray direction is assumed unit, so the
+ * quadratic's leading coefficient is 1. On a miss, writes the closest-approach
+ * point projected onto the sphere (so the handle tracks the limb gracefully
+ * rather than snapping away).
+ *
+ * @param {number[]} out  3-element destination (hit point).
+ * @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} Ray parameter t at the written hit.
+ */
+function raySphere(out, 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;
+  let t;
+  if (disc >= 0) {
+    const s = Math.sqrt(disc);
+    t = -b - s;
+    if (t < 0) t = -b + s;              // origin inside the sphere: take far root
+    out[0]=ox+t*dx; out[1]=oy+t*dy; out[2]=oz+t*dz;
+  } else {
+    t = -b;                             // closest approach along the ray
+    let hx=ox+t*dx-cx, hy=oy+t*dy-cy, hz=oz+t*dz-cz;
+    const hl = Math.sqrt(hx*hx + hy*hy + hz*hz) || 1;
+    const k = r/hl;
+    out[0]=cx+hx*k; out[1]=cy+hy*k; out[2]=cz+hz*k;
+  }
+  return t;
+}
+
+/**
+ * Ray–plane intersection. A near-parallel ray (|d·n| < EPS) returns Infinity
+ * and leaves `out` untouched — the caller keeps the previous value.
+ *
+ * @param {number[]} out  3-element destination (hit point).
+ * @param {number} ox,oy,oz  Ray origin.
+ * @param {number} dx,dy,dz  Ray direction (unit).
+ * @param {number} px,py,pz  A point on the plane.
+ * @param {number} nx,ny,nz  Plane normal (unit).
+ * @returns {number} Ray parameter t, or Infinity if parallel.
+ */
+function rayPlane(out, ox,oy,oz, dx,dy,dz, px,py,pz, nx,ny,nz) {
+  const den = dx*nx + dy*ny + dz*nz;
+  if (den < EPS && den > -EPS) return Infinity;
+  const t = ((px-ox)*nx + (py-oy)*ny + (pz-oz)*nz) / den;
+  out[0]=ox+t*dx; out[1]=oy+t*dy; out[2]=oz+t*dz;
+  return t;
+}
+
+/**
+ * Closest point on the infinite line (p, u) to the ray (o, d). Both `d` and
+ * `u` are assumed unit. For a ray parallel to the line, projects the ray
+ * origin onto the line.
+ *
+ * @param {number[]} out  3-element destination (closest point on the line).
+ * @param {number} ox,oy,oz  Ray origin.
+ * @param {number} dx,dy,dz  Ray direction (unit).
+ * @param {number} px,py,pz  A point on the line.
+ * @param {number} ux,uy,uz  Line direction (unit).
+ * @returns {number} Signed parameter s along u at the written point (unclamped).
+ */
+function rayClosestPointOnAxis(out, ox,oy,oz, dx,dy,dz, px,py,pz, ux,uy,uz) {
+  const wx=ox-px, wy=oy-py, wz=oz-pz;
+  const b  = dx*ux + dy*uy + dz*uz;     // d·u
+  const dd = dx*wx + dy*wy + dz*wz;     // d·w
+  const e  = ux*wx + uy*wy + uz*wz;     // u·w
+  const den = 1 - b*b;                  // (d·d)(u·u) − (d·u)² with d,u unit
+  const s = (den > EPS) ? (e - b*dd) / den : e;
+  out[0]=px+s*ux; out[1]=py+s*uy; out[2]=pz+s*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)
+// =========================================================================
+
+/**
+ * Unit direction from azimuth/elevation (right-handed: az about +Y, el from XZ).
+ * @param {number[]} out  3-element destination.
+ * @param {number} az  Azimuth (radians).
+ * @param {number} el  Elevation (radians).
+ * @returns {number[]} out
+ */
+function dirFromAzEl(out, az, el) {
+  const ce = Math.cos(el);
+  out[0]=ce*Math.cos(az); out[1]=Math.sin(el); out[2]=ce*Math.sin(az);
+  return out;
+}
+
+/**
+ * Azimuth/elevation from a unit direction. Inverse of dirFromAzEl.
+ * @param {number[]} out2  2-element destination [az, el] (radians).
+ * @param {number} dx,dy,dz  Unit direction.
+ * @returns {number[]} out2
+ */
+function azElFromDir(out2, dx, dy, dz) {
+  out2[0] = Math.atan2(dz, dx);                 // az
+  out2[1] = Math.asin(_clamp(dy, -1, 1));       // el
+  return out2;
+}
+
+// =========================================================================
+// H4  Constraint — tagged state machine (one class, kind discriminant)
+// =========================================================================
+
+/**
+ * A draggable constraint: maps a ray to a constrained value and holds the
+ * canonical state between drags. One class with a `kind` discriminant (never
+ * per-constraint subclasses) so it maps cleanly to a Rust enum.
+ *
+ * Construction options (all optional unless noted):
+ *   SPHERE — { radius = 1, report = DIRECTION, anchor = [0,0,0] }
+ *   PLANE  — { anchor = [0,0,0], normal = [0,1,0] }
+ *   AXIS   — { anchor = [0,0,0], axis = [1,0,0], extent = [-1, 1] }
+ *   DIAL   — { anchor = [0,0,0], axis = [0,1,0], radius = 1, zero?,
+ *              extent = [-∞, ∞] }
+ *            `axis` is the dial-plane normal (θ is right-handed about it);
+ *            `zero` is the in-plane reference direction for θ=0 (projected
+ *            onto the plane and normalised; derived from the axis when
+ *            absent); `extent` clamps θ in radians — unbounded by default,
+ *            so the dial winds multiple turns.
+ *
+ * @param {number} kind  SPHERE | PLANE | AXIS | DIAL.
+ * @param {Object} [opts]
+ */
+class Constraint {
+  constructor(kind, opts = {}) {
+    /** Constraint kind discriminant. @type {number} */
+    this.kind = kind;
+
+    /** Constraint origin (sphere centre / plane point / axis anchor / dial centre). @type {number[]} */
+    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$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$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;
+
+    // DIAL in-plane basis: r0 (the θ=0 reference) and r1 = u × r0, so the
+    // point at θ is anchor + radius·(cosθ·r0 + sinθ·r1) — right-handed about u.
+    /** θ=0 reference direction (unit, in-plane) — DIAL. @type {number[]} */
+    this.r0 = [1, 0, 0];
+    /** In-plane binormal u × r0 (unit) — DIAL. @type {number[]} */
+    this.r1 = [0, 0, 1];
+    if (kind === DIAL) {
+      const z = _vec3$1(opts.zero);
+      this._dialBasis(z ? z[0] : NaN, z ? z[1] : NaN, z ? z[2] : NaN);
+    }
+
+    // Extent: AXIS clamps t (default [-1, 1]); DIAL clamps θ in radians
+    // (default unbounded, so the dial winds freely).
+    const ext = Array.isArray(opts.extent) ? opts.extent : null;
+    const dial = kind === DIAL;
+    /** Minimum scalar parameter. @type {number} */
+    this.min = ext && _isNum(ext[0]) ? ext[0] : (dial ? -Infinity : -1);
+    /** Maximum scalar parameter. @type {number} */
+    this.max = ext && _isNum(ext[1]) ? ext[1] : (dial ?  Infinity :  1);
+
+    // Sphere / dial radius (private backing — see radius getter/setter).
+    this._radius = _num(opts.radius, 1);
+
+    /**
+     * Default report mode. SPHERE defaults to DIRECTION; PLANE / AXIS / DIAL
+     * report a POINT.
+     * @type {number}
+     */
+    this.report = (opts.report === POINT || opts.report === DIRECTION)
+      ? opts.report
+      : (kind === SPHERE ? DIRECTION : POINT);
+
+    if (kind === DIAL) this._dialPoint();
+  }
+
+  /** Sphere / dial radius. @type {number} */
+  get radius()  { return this._radius; }
+  set radius(r) { this._radius = _isNum(r) ? r : this._radius; if (this.kind === DIAL) this._dialPoint(); }
+
+  // Recompute the DIAL point from θ (anchor + ρ(cosθ·r0 + sinθ·r1)).
+  _dialPoint() {
+    const c = Math.cos(this.s) * this._radius, sn = Math.sin(this.s) * this._radius;
+    this.pt[0] = this.anchor[0] + c*this.r0[0] + sn*this.r1[0];
+    this.pt[1] = this.anchor[1] + c*this.r0[1] + sn*this.r1[1];
+    this.pt[2] = this.anchor[2] + c*this.r0[2] + sn*this.r1[2];
+  }
+
+  // Build the DIAL in-plane basis (r0, r1) from the current axis u and an
+  // optional θ=0 reference (zx,zy,zz): the reference is projected onto the
+  // dial plane and normalised; absent (NaN) or degenerate, r0 derives from u
+  // via the least-aligned-axis seed. r1 = u × r0, right-handed about u.
+  _dialBasis(zx, zy, zz) {
+    if (_isNum(zx) && _isNum(zy) && _isNum(zz)) {
+      const d = zx*this.u[0] + zy*this.u[1] + zz*this.u[2];
+      this.r0[0] = zx - d*this.u[0];
+      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$1(this.u, this.r0, this.r1);
+      else { this.r0[0]/=l; this.r0[1]/=l; this.r0[2]/=l; }
+    } else {
+      _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];
+    this.r1[1] = this.u[2]*this.r0[0] - this.u[0]*this.r0[2];
+    this.r1[2] = this.u[0]*this.r0[1] - this.u[1]*this.r0[0];
+  }
+
+  /**
+   * Update the canonical state from a ray in the working space. The ray
+   * direction is assumed unit. Chainable.
+   *
+   * @param {number} ox,oy,oz  Ray origin.
+   * @param {number} dx,dy,dz  Ray direction (unit).
+   * @returns {Constraint} this
+   */
+  solve(ox, oy, oz, dx, dy, dz) {
+    if (this.kind === SPHERE) {
+      // Hit the sphere into pt, then derive the unit heading from the anchor.
+      raySphere(this.pt, ox,oy,oz, dx,dy,dz,
+                this.anchor[0], this.anchor[1], this.anchor[2], this._radius);
+      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$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,
+               this.anchor[0], this.anchor[1], this.anchor[2],
+               this.n[0], this.n[1], this.n[2]);
+    } else if (this.kind === AXIS) {
+      let s = rayClosestPointOnAxis(this.pt, ox,oy,oz, dx,dy,dz,
+                                    this.anchor[0], this.anchor[1], this.anchor[2],
+                                    this.u[0], this.u[1], this.u[2]);
+      s = _clamp(s, this.min, this.max);
+      this.s = s;
+      this.pt[0] = this.anchor[0] + s*this.u[0];   // clamped point
+      this.pt[1] = this.anchor[1] + s*this.u[1];
+      this.pt[2] = this.anchor[2] + s*this.u[2];
+    } else if (this.kind === DIAL) {
+      this._solveDial(ox, oy, oz, dx, dy, dz);
+    }
+    return this;
+  }
+
+  // DIAL solve. Face-on: hit the dial plane, derive the raw angle of the hit
+  // about the anchor, and accumulate the smaller signed arc into θ (winding
+  // preserved). Edge-on (|d·u| < DIAL_EDGE): the plane hit diverges, so solve
+  // the ray against the TANGENT LINE of the circle at the current θ instead —
+  // the signed tangent parameter over the radius is dθ, bounded and monotone.
+  _solveDial(ox, oy, oz, dx, dy, dz) {
+    const u = this.u, r0 = this.r0, r1 = this.r1, a = this.anchor;
+    const den = dx*u[0] + dy*u[1] + dz*u[2];
+    let dth;
+    if (den >= DIAL_EDGE || den <= -DIAL_EDGE) {
+      // Well-conditioned: plane hit → raw angle → smaller signed arc.
+      const t = rayPlane(this.pt, ox,oy,oz, dx,dy,dz,
+                         a[0], a[1], a[2], u[0], u[1], u[2]);
+      if (t === Infinity) return;                  // keep last (paranoia; den guards)
+      const vx = this.pt[0]-a[0], vy = this.pt[1]-a[1], vz = this.pt[2]-a[2];
+      const raw = Math.atan2(vx*r1[0] + vy*r1[1] + vz*r1[2],
+                             vx*r0[0] + vy*r0[1] + vz*r0[2]);
+      dth = _wrapPi(raw - _wrapPi(this.s));
+    } else {
+      // Edge-on fallback: tangent at the current point, w = −sinθ·r0 + cosθ·r1.
+      const cs = Math.cos(this.s), sn = Math.sin(this.s);
+      const wx = -sn*r0[0] + cs*r1[0];
+      const wy = -sn*r0[1] + cs*r1[1];
+      const wz = -sn*r0[2] + cs*r1[2];
+      this._dialPoint();                           // tangent anchored at the current point
+      const sl = rayClosestPointOnAxis(this.pt, ox,oy,oz, dx,dy,dz,
+                                       this.pt[0], this.pt[1], this.pt[2],
+                                       wx, wy, wz);
+      dth = sl / (this._radius || 1);
+    }
+    this.s = _clamp(this.s + dth, this.min, this.max);
+    this._dialPoint();
+  }
+
+  /**
+   * Write the current value into `out`. `report` overrides the default for
+   * this call (e.g. read a SPHERE's point even when its default is DIRECTION).
+   * SPHERE+POINT and DIAL+POINT are derived from the angle/heading and the
+   * live radius, so they stay correct after a radius change without
+   * re-solving. DIAL+DIRECTION writes the radial unit at θ.
+   *
+   * @param {number[]} out  3-element destination.
+   * @param {number} [report]  POINT | DIRECTION override.
+   * @returns {number[]} out
+   */
+  value(out, report) {
+    const r = (report === POINT || report === DIRECTION) ? report : this.report;
+    if (this.kind === SPHERE) {
+      if (r === DIRECTION) {
+        out[0]=this.dir[0]; out[1]=this.dir[1]; out[2]=this.dir[2];
+      } else {
+        out[0]=this.anchor[0]+this.dir[0]*this._radius;
+        out[1]=this.anchor[1]+this.dir[1]*this._radius;
+        out[2]=this.anchor[2]+this.dir[2]*this._radius;
+      }
+    } else if (this.kind === DIAL) {
+      const cs = Math.cos(this.s), sn = Math.sin(this.s);
+      if (r === DIRECTION) {
+        out[0]=cs*this.r0[0]+sn*this.r1[0];
+        out[1]=cs*this.r0[1]+sn*this.r1[1];
+        out[2]=cs*this.r0[2]+sn*this.r1[2];
+      } else {
+        out[0]=this.anchor[0]+(cs*this.r0[0]+sn*this.r1[0])*this._radius;
+        out[1]=this.anchor[1]+(cs*this.r0[1]+sn*this.r1[1])*this._radius;
+        out[2]=this.anchor[2]+(cs*this.r0[2]+sn*this.r1[2])*this._radius;
+      }
+    } else {
+      out[0]=this.pt[0]; out[1]=this.pt[1]; out[2]=this.pt[2];
+    }
+    return out;
+  }
+
+  /**
+   * Current scalar parameter: AXIS → signed t along the line; DIAL →
+   * accumulated angle θ in radians (multi-turn).
+   * @returns {number} The parameter, or NaN for non-scalar constraints.
+   */
+  scalar() {
+    return (this.kind === AXIS || this.kind === DIAL) ? this.s : NaN;
+  }
+
+  /**
+   * Derive [az, el] from the current SPHERE direction (SPHERE only).
+   * @param {number[]} out2  2-element destination [az, el].
+   * @returns {number[]} out2
+   */
+  azEl(out2) {
+    return azElFromDir(out2, this.dir[0], this.dir[1], this.dir[2]);
+  }
+
+  /**
+   * Seed the canonical state from a value (used by the bridge on bind() so the
+   * handle starts at the bound target's value). Chainable.
+   *   SPHERE — sets the unit direction (a point value recovers its heading).
+   *   PLANE  — projects the value onto the plane.
+   *   AXIS   — projects the value onto the line, clamped to extent.
+   *   DIAL   — projects the value onto the dial plane, derives the wrapped
+   *            angle, and picks the WINDING NEAREST the current θ (so an
+   *            external sync doesn't unwind accumulated turns), clamped.
+   *
+   * @param {number} x,y,z  Seed value.
+   * @returns {Constraint} this
+   */
+  seed(x, y, z) {
+    if (this.kind === SPHERE) {
+      const vx=x-this.anchor[0], vy=y-this.anchor[1], vz=z-this.anchor[2];
+      const l = Math.sqrt(vx*vx + vy*vy + vz*vz);
+      if (l >= EPS) { this.dir[0]=vx/l; this.dir[1]=vy/l; this.dir[2]=vz/l; }
+    } else if (this.kind === PLANE) {
+      const wx=x-this.anchor[0], wy=y-this.anchor[1], wz=z-this.anchor[2];
+      const d = wx*this.n[0] + wy*this.n[1] + wz*this.n[2];
+      this.pt[0]=x-d*this.n[0]; this.pt[1]=y-d*this.n[1]; this.pt[2]=z-d*this.n[2];
+    } else if (this.kind === AXIS) {
+      const wx=x-this.anchor[0], wy=y-this.anchor[1], wz=z-this.anchor[2];
+      const s = _clamp(wx*this.u[0] + wy*this.u[1] + wz*this.u[2], this.min, this.max);
+      this.s = s;
+      this.pt[0]=this.anchor[0]+s*this.u[0];
+      this.pt[1]=this.anchor[1]+s*this.u[1];
+      this.pt[2]=this.anchor[2]+s*this.u[2];
+    } else if (this.kind === DIAL) {
+      const wx=x-this.anchor[0], wy=y-this.anchor[1], wz=z-this.anchor[2];
+      const px = wx*this.r0[0] + wy*this.r0[1] + wz*this.r0[2];
+      const py = wx*this.r1[0] + wy*this.r1[1] + wz*this.r1[2];
+      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$1 * Math.round((this.s - a) / TWO_PI$1),
+                        this.min, this.max);
+      }
+      this._dialPoint();
+    }
+    return this;
+  }
+
+  /**
+   * Re-aim the constraint basis in the working space — the deferred-frame
+   * seam (the p5.tree bridge's `from` opt resolves its symbolic basis through
+   * mapDirection and calls this). Per kind:
+   *   PLANE  — new normal; the point is re-projected onto the new plane.
+   *   AXIS   — new direction; the scalar t is preserved, the point recomputed.
+   *   DIAL   — new plane normal + optional θ=0 reference; θ is preserved, the
+   *            in-plane basis rebuilt (reference re-derived when omitted),
+   *            the point recomputed.
+   *   SPHERE — no basis; no-op.
+   * Inputs are normalised; a zero-length axis keeps the previous one.
+   * Chainable.
+   *
+   * @param {number} ax,ay,az  New normal (PLANE) / direction (AXIS) / dial-plane normal (DIAL).
+   * @param {number} [zx,zy,zz]  DIAL only — θ=0 reference (re-derived when omitted).
+   * @returns {Constraint} this
+   */
+  aim(ax, ay, az, zx, zy, zz) {
+    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$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$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$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);
+  }
+}
+
+/**
+ * Convenience factory mirroring the constructor. Handy for headless tests and
+ * for the bridge, which otherwise calls `new Constraint(...)` directly.
+ * @param {number} kind  SPHERE | PLANE | AXIS | DIAL.
+ * @param {Object} [opts]
+ * @returns {Constraint}
+ */
+function createConstraint(kind, opts) {
+  return new Constraint(kind, opts);
+}
+
+/**
+ * @file Source-agnostic 6-DOF pose helm — integrates a live rate stream into a
+ *       { pos, rot } pose. Renderer- and transport-agnostic. Zero dependencies.
+ * @module tree/helm
+ * @license AGPL-3.0-only
+ *
+ * A helm is the rate-stream sibling of the Track family: where a Track produces
+ * a pose from keyframes over time, a helm produces a pose from a live 6-DOF
+ * delta stream (a SpaceNavigator, a tracked hand, an agent policy). It is NOT a
+ * handle — a handle reports a `vec3` solved from a pointer ray; a helm reports a
+ * pose (position + orientation).
+ *
+ * Family placement (peer of PoseTrack, NOT a Track subclass — no timeline):
+ *   feed(translation, rotation)  push the latest raw device rate (input, as Track.add)
+ *   step(out, dt, basis)         integrate the rate by dt into the pose (BRIDGE-DRIVEN,
+ *                                as Track.tick) — writes the new pose into out
+ *   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
+ * the frozen basis-vector constants.
+ *
+ * ── Frame discipline (`from` / `basis`) ──────────────────────────────────────
+ * The space the rates are interpreted in is named by `from` (WORLD | EYE | mat4),
+ * a declaration the BRIDGE reads — the core never learns about a camera. The
+ * resolved orientation arrives per-step as `basis`: an eye→world mat4 (or null
+ * for WORLD ≡ the identity basis). Both the linear and angular rates are rotated
+ * through that basis, then the quaternion is composed world-frame. This is the
+ * single code path that covers both manipulation conventions:
+ *
+ *   - camera body-fly  — basis is the driven camera's own eye matrix (which this
+ *                        helm produced last frame ⇒ equals the integrated `q`,
+ *                        zero staleness); rotating a body delta through `q` then
+ *                        world-composing is algebraically a body-frame compose.
+ *   - screen-relative  — basis is the *viewing* camera's eye matrix (an external
+ *                        frame); a push moves the target relative to the screen.
+ *
+ * Per-channel `from` ({ translation, rotation }) is a deferred, non-breaking
+ * extension (one basis suffices today — pose-helm-design.md §8.3).
+ */
+
+
+// =========================================================================
+// Module-level scratch — shared across helm instances (non-reentrant; step
+// is synchronous and called at most once per helm per frame).
+// =========================================================================
+
+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;
+
+/**
+ * Build the canonical default profile. SpaceNavigator-tuned lane permutation
+ * and the eye-frame manipulation feel found in the e7 experiments; it is the
+ * per-app / per-device mapping layer and is meant to be overwritten wholesale
+ * (`helm.profile = { … }`) for a different transport.
+ *
+ *   sign  — per-app direction (camera-fly vs object-grab invert; flip live).
+ *   sens  — per-axis sensitivity (tame roll without touching the rest).
+ *   lane  — input-channel permutation: which fed channel drives this DOF.
+ *           T* lanes index the translation triple; R* lanes the rotation triple.
+ */
+function _defaultProfile() {
+  return {
+    Tx: { sign:  1, sens: 0.30,   lane: 0 },
+    Ty: { sign:  1, sens: 0.30,   lane: 2 },
+    Tz: { sign: -1, sens: 0.30,   lane: 1 },
+    Rp: { sign: -1, sens: 0.0025, lane: 0 },
+    Ry: { sign: -1, sens: 0.0025, lane: 2 },
+    Rr: { sign:  1, sens: 0.0018, lane: 1 },
+  };
+}
+
+// =========================================================================
+// PoseHelm
+// =========================================================================
+
+/**
+ * Source-agnostic 6-DOF pose producer. Holds a profile + the integrated pose;
+ * no timeline (no keyframes, no play/seek/loop).
+ */
+class PoseHelm {
+  constructor() {
+    /**
+     * DOF mapping table. Six channels, each `{ sign, sens, lane }`.
+     * Public and mutable — set wholesale to re-map a device or app.
+     * @type {{ Tx:Object, Ty:Object, Tz:Object, Rp:Object, Ry:Object, Rr:Object }}
+     */
+    this.profile = _defaultProfile();
+
+    /**
+     * Rest-drift floor. A fed rate with |value| ≤ deadzone reads as 0. Devices
+     * that rest at exact 0 need only a small floor. @type {number}
+     */
+    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
+     * per-step `basis`; the core stays camera-agnostic. @type {string|ArrayLike<number>}
+     */
+    this.from = 'EYE';
+
+    // Latest fed raw rates (refreshed by feed; persist until the next feed —
+    // the transport is responsible for feeding 0 when motion should stop).
+    this._lin = [0, 0, 0];
+    this._ang = [0, 0, 0];
+
+    // Integrated pose — the source of truth.
+    this._pos = [0, 0, 0];
+    this._q   = [0, 0, 0, 1];
+  }
+
+  /**
+   * Push the latest raw 6-DOF device rate. Either argument may be omitted to
+   * leave that half unchanged (devices report the two halves on separate
+   * frames). The value persists until the next feed. Raw device units — the
+   * profile's `sens` does the scaling, so the same feed() suits any transport.
+   *
+   * @param {ArrayLike<number>} [translation]  [tx, ty, tz] raw lane rates.
+   * @param {ArrayLike<number>} [rotation]     [rx, ry, rz] raw lane rates.
+   * @returns {PoseHelm} this
+   */
+  feed(translation, rotation) {
+    if (translation) {
+      this._lin[0] = translation[0] || 0;
+      this._lin[1] = translation[1] || 0;
+      this._lin[2] = translation[2] || 0;
+    }
+    if (rotation) {
+      this._ang[0] = rotation[0] || 0;
+      this._ang[1] = rotation[1] || 0;
+      this._ang[2] = rotation[2] || 0;
+    }
+    return this;
+  }
+
+  /**
+   * Integrate the latest fed rate by `dt` seconds into the pose, then write the
+   * pose into `out`. Bridge-driven (the player calls it each frame; a sketch
+   * never does, as it never calls track.tick()).
+   *
+   * `basis` is the resolved `from` frame: an eye→world column-major mat4
+   * (16-element ArrayLike), or null/omitted for WORLD (the identity basis). Its
+   * columns supply the right/up/back axes; forward is −col2. Both the linear and
+   * angular rates are rotated through it, then `q` is composed world-frame.
+   *
+   * Zero-allocation. `out` is `{ pos:number[3], rot:number[4] }`; omit it for a
+   * fresh object.
+   *
+   * @param {{ pos:number[], rot:number[] }} [out]
+   * @param {number} dt       Elapsed time in seconds.
+   * @param {ArrayLike<number>} [basis]  Eye→world mat4, or null for WORLD.
+   * @returns {{ pos:number[], rot:number[] }} out
+   */
+  step(out, dt, basis) {
+    const p = this.profile, dz = this.deadzone;
+    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
+    // the camera's BACK in col2), and the identity's col2 is +Z, so forward is
+    // −Z — making step(out, dt, null) identical to step(out, dt, IDENTITY_MAT4),
+    // as the `from` contract ("null ≡ the identity basis") promises.
+    let rX = 1, rY = 0, rZ =  0;
+    let uX = 0, uY = 1, uZ =  0;
+    let fX = 0, fY = 0, fZ = -1;
+    if (basis) {
+      rX =  basis[0]; rY =  basis[1]; rZ =  basis[2];
+      uX =  basis[4]; uY =  basis[5]; uZ =  basis[6];
+      fX = -basis[8]; fY = -basis[9]; fZ = -basis[10];
+    }
+
+    // Angular: three rates → one delta quat, rotated into world, world-composed.
+    const wx = _dz(ang[p.Rp.lane], dz) * p.Rp.sign * p.Rp.sens;
+    const wy = _dz(ang[p.Ry.lane], dz) * p.Ry.sign * p.Ry.sens;
+    const wz = _dz(ang[p.Rr.lane], dz) * p.Rr.sign * p.Rr.sens;
+    const w  = Math.sqrt(wx * wx + wy * wy + wz * wz);
+    if (w > 0) {
+      // Axis in world = basis · (wx,wy,wz); its length is w (basis orthonormal),
+      // so the rotation angle is w·dt. qFromAxisAngle renormalizes the axis.
+      const ax = wx * rX + wy * uX + wz * fX;
+      const ay = wx * rY + wy * uY + wz * fY;
+      const az = wx * rZ + wy * uZ + wz * fZ;
+      qFromAxisAngle(_dq, ax, ay, az, w * dt);
+      qMul(this._q, _dq, this._q);        // delta already in world → world-frame compose
+      qNormalize(this._q);
+    }
+
+    // Linear: three rates rotated into world, integrated by dt.
+    const tx = _dz(lin[p.Tx.lane], dz) * p.Tx.sign * p.Tx.sens;
+    const ty = _dz(lin[p.Ty.lane], dz) * p.Ty.sign * p.Ty.sens;
+    const tz = _dz(lin[p.Tz.lane], dz) * p.Tz.sign * p.Tz.sens;
+    this._pos[0] += (tx * rX + ty * uX + tz * fX) * dt;
+    this._pos[1] += (tx * rY + ty * uY + tz * fY) * dt;
+    this._pos[2] += (tx * rZ + ty * uZ + tz * fZ) * dt;
+
+    return this.eval(out);
+  }
+
+  /**
+   * Read the current pose into `out` (zero-alloc). The shared output contract
+   * that feeds applyPose — mirrors Track.eval.
+   *
+   * @param {{ pos:number[], rot:number[] }} [out]
+   * @returns {{ pos:number[], rot:number[] }} out
+   */
+  eval(out) {
+    out = out || { pos: [0, 0, 0], rot: [0, 0, 0, 1] };
+    out.pos[0] = this._pos[0]; out.pos[1] = this._pos[1]; out.pos[2] = this._pos[2];
+    out.rot[0] = this._q[0];   out.rot[1] = this._q[1];
+    out.rot[2] = this._q[2];   out.rot[3] = this._q[3];
+    return out;
+  }
+
+  /**
+   * Write the six effective channel rates (post deadzone·sign·sens) into `out6`,
+   * in channel order [Tx, Ty, Tz, Rp, Ry, Rr]. The gizmo reads this to light the
+   * DOFs being driven; readouts can show signed magnitudes. Zero-alloc.
+   *
+   * @param {number[]} out6  6-element destination.
+   * @returns {number[]} out6
+   */
+  activity(out6) {
+    const p = this.profile, dz = this.deadzone, lin = this._lin, ang = this._ang;
+    out6[0] = _dz(lin[p.Tx.lane], dz) * p.Tx.sign * p.Tx.sens;
+    out6[1] = _dz(lin[p.Ty.lane], dz) * p.Ty.sign * p.Ty.sens;
+    out6[2] = _dz(lin[p.Tz.lane], dz) * p.Tz.sign * p.Tz.sens;
+    out6[3] = _dz(ang[p.Rp.lane], dz) * p.Rp.sign * p.Rp.sens;
+    out6[4] = _dz(ang[p.Ry.lane], dz) * p.Ry.sign * p.Ry.sens;
+    out6[5] = _dz(ang[p.Rr.lane], dz) * p.Rr.sign * p.Rr.sens;
+    return out6;
+  }
+
+  /**
+   * Re-home the integrated pose. Sets position + orientation to `pose` (or the
+   * identity pose when omitted) and clears any pending rate so the helm rests at
+   * a clean, known state. NOT a reset — there are no keyframes to clear.
+   *
+   * @param {{ pos?:ArrayLike<number>, rot?:ArrayLike<number> }} [pose]
+   * @returns {PoseHelm} this
+   */
+  home(pose) {
+    if (pose && pose.pos) {
+      this._pos[0] = pose.pos[0]; this._pos[1] = pose.pos[1]; this._pos[2] = pose.pos[2];
+    } else {
+      this._pos[0] = 0; this._pos[1] = 0; this._pos[2] = 0;
+    }
+    if (pose && pose.rot) {
+      this._q[0] = pose.rot[0]; this._q[1] = pose.rot[1];
+      this._q[2] = pose.rot[2]; this._q[3] = pose.rot[3];
+    } else {
+      this._q[0] = 0; this._q[1] = 0; this._q[2] = 0; this._q[3] = 1;
+    }
+    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;
+  }
+}
+const _d = [0, 0, 0];              // view-direction scratch
+
+/** 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;
+}
+
+// =========================================================================
+// 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * @file The view bag — the matrices every pick, solve, label and orbit reads.
+ * @module host/view
+ * @license AGPL-3.0-only
+ *
+ * The matrices bag mapLocation takes, plus the signed viewport and the NDC
+ * convention:
+ *
+ *   view = {
+ *     mat4Proj, mat4View, mat4PV, mat4PVInv,   // Float32Array(16) each, host-owned
+ *     mat4Eye,                                 // inverse of mat4View — EYE → WORLD
+ *     vp,                                      // [0, h, w, −h] — y-down, logical canvas px
+ *     ndcZMin,                                 // WEBGL | WEBGPU, set once at creation
+ *     stale,                                   // true until a set() with an invertible P · V
+ *     set(P, V)                                // copy P and V, recompute PV and PVInv
+ *     setCamera(cam)                           // build V and P from a camera state, then set
+ *     resize(width, height)                    // the canvas observer's write into vp
+ *   }
+ *
+ * mat4PVInv and mat4Eye are recomputed on set, once per frame, so unproject
+ * and every mapping from SCREEN or EYE share them. A degenerate P · V or V
+ * leaves the previous inverses and marks the bag stale; consumers treat a
+ * stale bag as "no pick this frame".
+ */
+
+
+const _inv = new Float32Array(16);   // inverse scratch: the bag keeps its previous inverse on failure
+const _P   = new Float32Array(16);   // setCamera's projection
+const _V   = new Float32Array(16);   // setCamera's view
+
+function _identity(m) {
+  m.fill(0);
+  m[0] = m[5] = m[10] = m[15] = 1;
+  return m;
+}
+
+/**
+ * Create a view bag. The matrices start at identity and the bag stale, so a
+ * consumer reading it before the first set() picks nothing.
+ *
+ * @param {{ ndcZMin?:number, width?:number, height?:number }} [opts]
+ *        ndcZMin: WEBGL (−1, default) or WEBGPU (0) — written once here, never
+ *        detected. width / height: the initial logical canvas size.
+ * @returns {object} The view bag.
+ */
+function createView(opts) {
+  const o = opts || {};
+  const w = o.width || 0, h = o.height || 0;
+  const view = {
+    mat4Proj:  _identity(new Float32Array(16)),
+    mat4View:  _identity(new Float32Array(16)),
+    mat4PV:    _identity(new Float32Array(16)),
+    mat4PVInv: _identity(new Float32Array(16)),
+    mat4Eye:   _identity(new Float32Array(16)),
+    vp: [0, h, w, -h],
+    ndcZMin: o.ndcZMin === 0 ? 0 : WEBGL,
+    stale: true,
+
+    /**
+     * Install a projection and a view: both copied, P · V with its inverse
+     * and the eye matrix (V's inverse) recomputed. A singular product or
+     * view keeps the previous inverses and marks the bag stale.
+     * @param {ArrayLike<number>} P  Projection mat4.
+     * @param {ArrayLike<number>} V  View mat4 (world → eye).
+     * @returns {object} this
+     */
+    set(P, V) {
+      for (let i = 0; i < 16; i++) { view.mat4Proj[i] = P[i]; view.mat4View[i] = V[i]; }
+      mat4Mul(view.mat4PV, view.mat4Proj, view.mat4View);
+      if (mat4Invert(_inv, view.mat4PV) === null) { view.stale = true; return view; }
+      view.mat4PVInv.set(_inv);
+      if (mat4Invert(_inv, view.mat4View) === null) { view.stale = true; return view; }
+      view.mat4Eye.set(_inv);
+      view.stale = false;
+      return view;
+    },
+
+    /**
+     * Install a camera state: cameraView and cameraProj at the viewport's
+     * aspect under the bag's ndcZMin, then set(). A state with both fov and
+     * halfHeight null keeps the projection already installed.
+     * @param {object} cam  Camera state.
+     * @returns {object} this
+     */
+    setCamera(cam) {
+      const aspect = view.vp[3] !== 0 ? view.vp[2] / -view.vp[3] : 1;
+      cameraView(_V, cam);
+      const P = cameraProj(_P, cam, aspect, view.ndcZMin) || view.mat4Proj;
+      return view.set(P, _V);
+    },
+
+    /**
+     * Write a new logical canvas size into vp: [0, height, width, −height].
+     * @param {number} width
+     * @param {number} height
+     * @returns {object} this
+     */
+    resize(width, height) {
+      view.vp[1] = height; view.vp[2] = width; view.vp[3] = -height;
+      return view;
+    },
+  };
+  return view;
+}
+
+/**
+ * @file The canvas observer — logical size and device pixel ratio.
+ * @module host/canvas
+ * @license AGPL-3.0-only
+ *
+ * A ResizeObserver on the canvas element plus devicePixelRatio tracking:
+ * on change the observer reports the logical size in CSS px and the dpr to
+ * its callback, which the context uses to update host.width / host.height /
+ * host.dpr, the view bag's vp, the label layer and the bridge's onSize. The
+ * observer never touches canvas.width / canvas.height — that is the
+ * renderer's decision.
+ *
+ * Without a ResizeObserver (a headless run) the size is measured once from
+ * the element's bounding rectangle, falling back to its width / height
+ * attributes.
+ */
+
+
+/**
+ * Measure a canvas: logical CSS size from its bounding rectangle when laid
+ * out, else its width / height attributes; dpr from the window.
+ * @param {HTMLCanvasElement} canvas
+ * @param {number[]} out3  [width, height, dpr] destination.
+ * @returns {number[]} out3
+ */
+function measureCanvas(canvas, out3) {
+  const r = typeof canvas.getBoundingClientRect === 'function' ? canvas.getBoundingClientRect() : null;
+  const laidOut = r && r.width > 0 && r.height > 0;
+  out3[0] = laidOut ? r.width  : (canvas.width  || 0);
+  out3[1] = laidOut ? r.height : (canvas.height || 0);
+  out3[2] = (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
+  return out3;
+}
+
+/**
+ * Observe a canvas's logical size and dpr. `onChange(width, height, dpr)`
+ * fires once immediately with the current measure and again on every
+ * change; a change is reported only when a value differs.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {function(number, number, number):void} onChange
+ * @returns {{ width:number, height:number, dpr:number, measure():void, dispose():void }}
+ */
+function observeCanvas(canvas, onChange) {
+  const m = [0, 0, 1];
+  const obs = { width: -1, height: 0, dpr: 1, measure, dispose };
+  let ro = null;
+  const onWindow = () => measure();
+
+  function measure() {
+    measureCanvas(canvas, m);
+    if (m[0] === obs.width && m[1] === obs.height && m[2] === obs.dpr) return;
+    obs.width = m[0]; obs.height = m[1]; obs.dpr = m[2];
+    onChange(obs.width, obs.height, obs.dpr);
+  }
+
+  function dispose() {
+    if (ro) { ro.disconnect(); ro = null; }
+    if (typeof window !== 'undefined' && window.removeEventListener) window.removeEventListener('resize', onWindow);
+  }
+
+  measure();                                   // width −1 makes the first measure report
+  if (typeof ResizeObserver !== 'undefined') {
+    ro = new ResizeObserver(() => measure());
+    ro.observe(canvas);
+  }
+  // A zoom changes devicePixelRatio and fires resize; the observer alone would miss it.
+  if (typeof window !== 'undefined' && window.addEventListener) window.addEventListener('resize', onWindow);
+  return obs;
+}
+
+/**
+ * @file The pointer source — a typed event buffer with claims, one per canvas.
+ * @module host/pointer
+ * @license AGPL-3.0-only
+ *
+ * Shared by every handle, router and orbit on a canvas. Listeners only
+ * record; nothing solves in a listener:
+ *
+ * - pointerdown · pointermove · pointerup · pointercancel on the canvas,
+ *   keydown (Esc) on the window.
+ * - Coordinates in logical canvas px through the element's bounding
+ *   rectangle — (clientX − rect.left) · (width / rect.width), the logical
+ *   size read off the view bag's vp — the numbers mapLocation(SCREEN) and vp
+ *   expect, so a CSS-scaled canvas maps correctly.
+ * - Per pointer: an entry { id, x, y, seq, down, up, cancel, owner }, kept
+ *   from its press until the frame after its release; `seq` counts moves,
+ *   so a consumer remembers the last seq it consumed and reads only new
+ *   motion. Multitouch is per-pointer by construction; the mouse is one
+ *   more pointer.
+ * - Presses queue in order for the frame (`presses`); consumers read the
+ *   queue inside the frame and claim what they take. Several same-frame
+ *   presses on different members all land.
+ * - Claims: claim(id, owner) captures the pointer on the canvas so a drag
+ *   that leaves it keeps flowing; release(id), up and cancel release the
+ *   capture. An unclaimed pointer is what the orbit sees.
+ * - Esc sets the cancel flag on every claimed pointer.
+ * - flush() ends the frame: the press queue empties and released pointers
+ *   leave the map. The loop calls it after onFrame; an external loop calls
+ *   it after its consumers ran (the p5 adapter from postdraw).
+ */
+
+
+/**
+ * Create the pointer source of a canvas.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {object} view  The view bag; vp[2] and −vp[3] are the logical size.
+ * @returns {object} The source: { presses, pointers, get, claim, release,
+ *          ownerOf, flush, dispose }.
+ */
+function createPointer(canvas, view) {
+  const pointers = new Map();          // id → entry
+  const presses  = [];                 // this frame's presses, in order: { id, x, y }
+  const xy = [0, 0];
+
+  const toCanvas = (e, out) => {
+    const r = canvas.getBoundingClientRect ? canvas.getBoundingClientRect() : null;
+    const w = view.vp[2], h = -view.vp[3];
+    if (r && r.width > 0 && r.height > 0 && w > 0 && h > 0) {
+      out[0] = (e.clientX - r.left) * (w / r.width);
+      out[1] = (e.clientY - r.top)  * (h / r.height);
+    } else {
+      out[0] = e.clientX; out[1] = e.clientY;
+    }
+    return out;
+  };
+
+  const entry = (id) => {
+    let p = pointers.get(id);
+    if (!p) { p = { id, x: 0, y: 0, seq: 0, down: false, up: false, cancel: false, owner: null }; pointers.set(id, p); }
+    return p;
+  };
+
+  const capture = (id, on) => {
+    const f = on ? canvas.setPointerCapture : canvas.releasePointerCapture;
+    if (typeof f !== 'function') return;
+    try { f.call(canvas, id); } catch (_) { /* best effort: a synthetic or already-released id */ }
+  };
+
+  const onDown = (e) => {
+    const p = entry(e.pointerId);
+    toCanvas(e, xy);
+    p.x = xy[0]; p.y = xy[1]; p.seq++;
+    p.down = true; p.up = false; p.cancel = false;
+    presses.push({ id: p.id, x: p.x, y: p.y });
+  };
+  const onMove = (e) => {
+    const p = entry(e.pointerId);
+    toCanvas(e, xy);
+    p.x = xy[0]; p.y = xy[1]; p.seq++;
+  };
+  const onUp = (e) => {
+    const p = pointers.get(e.pointerId);
+    if (!p) return;
+    toCanvas(e, xy);
+    p.x = xy[0]; p.y = xy[1]; p.seq++;
+    p.up = true;
+    capture(p.id, false);
+  };
+  const onCancel = (e) => {
+    const p = pointers.get(e.pointerId);
+    if (!p) return;
+    p.cancel = true;
+    capture(p.id, false);
+  };
+  const onKey = (e) => {
+    if (e.key !== 'Escape') return;
+    for (const p of pointers.values()) if (p.owner !== null) p.cancel = true;
+  };
+
+  canvas.addEventListener('pointerdown',   onDown);
+  canvas.addEventListener('pointermove',   onMove);
+  canvas.addEventListener('pointerup',     onUp);
+  canvas.addEventListener('pointercancel', onCancel);
+  if (typeof window !== 'undefined' && window.addEventListener) window.addEventListener('keydown', onKey);
+
+  const source = {
+    /** This frame's presses in order, each { id, x, y }; emptied by flush(). */
+    presses,
+    /** The live pointer entries by id. */
+    pointers,
+
+    /**
+     * The entry of a pointer, or null when it is not on the canvas.
+     * @param {number} id
+     * @returns {object|null}
+     */
+    get(id) { return pointers.get(id) || null; },
+
+    /**
+     * Claim a pointer for an owner and capture it on the canvas. Fails when
+     * another owner holds it or the pointer is unknown.
+     * @param {number} id
+     * @param {object} owner
+     * @returns {boolean} claimed
+     */
+    claim(id, owner) {
+      const p = pointers.get(id);
+      if (!p || (p.owner !== null && p.owner !== owner)) return false;
+      p.owner = owner;
+      capture(id, true);
+      return true;
+    },
+
+    /**
+     * Release a claim and the capture with it. No-op for an unclaimed id.
+     * @param {number} id
+     */
+    release(id) {
+      const p = pointers.get(id);
+      if (!p || p.owner === null) return;
+      p.owner = null;
+      capture(id, false);
+    },
+
+    /**
+     * The owner holding a pointer, or null.
+     * @param {number} id
+     * @returns {object|null}
+     */
+    ownerOf(id) { const p = pointers.get(id); return p ? p.owner : null; },
+
+    /**
+     * End the frame: the press queue empties; pointers that released or
+     * cancelled leave the map (their claims dropped), the rest keep their
+     * position and seq.
+     */
+    flush() {
+      presses.length = 0;
+      for (const [id, p] of pointers) {
+        if (p.up || p.cancel) { p.owner = null; pointers.delete(id); }
+      }
+    },
+
+    /** Remove every listener and release every capture. */
+    dispose() {
+      canvas.removeEventListener('pointerdown',   onDown);
+      canvas.removeEventListener('pointermove',   onMove);
+      canvas.removeEventListener('pointerup',     onUp);
+      canvas.removeEventListener('pointercancel', onCancel);
+      if (typeof window !== 'undefined' && window.removeEventListener) window.removeEventListener('keydown', onKey);
+      for (const p of pointers.values()) if (p.owner !== null) capture(p.id, false);
+      pointers.clear();
+      presses.length = 0;
+    },
+  };
+  return source;
+}
+
+/**
+ * @file The players registry and the frame loop.
+ * @module host/loop
+ * @license AGPL-3.0-only
+ *
+ * A player is { tick(dt) → boolean }, removed from the registry when it
+ * returns false. Iteration snapshots the set, so a player may remove itself
+ * or add another during a tick. Tracks register through their activation
+ * hooks, helms until disposed.
+ *
+ * The loop is optional: with it, requestAnimationFrame (overridable — the
+ * seam a WebXR session fills) drives onFrame(dt) with dt in seconds clamped
+ * to 50 ms, the stalled-tab guard; without it the application ticks the
+ * players from its own loop.
+ */
+
+
+/**
+ * Create a players registry.
+ * @returns {{ add(player):object, remove(player):object, has(player):boolean,
+ *             tick(dt:number):void, size:number, clear():void }}
+ */
+function createPlayers() {
+  const set = new Set();
+  const players = {
+    /** Register a player; adding one already present is a no-op. */
+    add(player) { if (player) set.add(player); return players; },
+    /** Unregister a player. */
+    remove(player) { set.delete(player); return players; },
+    /** Whether a player is registered. */
+    has(player) { return set.has(player); },
+    /** Tick every player with dt (seconds); one returning false is removed. */
+    tick(dt) {
+      for (const p of [...set]) {
+        if (!set.has(p)) continue;                 // removed by an earlier player this tick
+        if (p.tick(dt) === false) set.delete(p);
+      }
+    },
+    /** Registered count. */
+    get size() { return set.size; },
+    /** Unregister every player. */
+    clear() { set.clear(); },
+  };
+  return players;
+}
+
+const _now$1 = () => (typeof performance !== 'undefined' && performance.now) ? performance.now() : Date.now();
+
+/**
+ * Create a frame loop. `onFrame(dt)` runs once per animation frame with the
+ * clamped period in seconds; start() schedules, stop() cancels.
+ *
+ * @param {{ onFrame:function(number):void, raf?:function, caf?:function,
+ *           clampMs?:number, now?:function():number }} opts
+ *        raf / caf default to the window's requestAnimationFrame /
+ *        cancelAnimationFrame; clampMs defaults to 50.
+ * @returns {{ start():object, stop():object, running:boolean, dt:number }}
+ */
+function createLoop(opts) {
+  const o = opts || {};
+  const raf = o.raf || ((cb) => requestAnimationFrame(cb));
+  const caf = o.caf || ((id) => cancelAnimationFrame(id));
+  const now = o.now || _now$1;
+  const clamp = (o.clampMs ?? 50) / 1000;
+  let handle = null, last = 0;
+  const loop = {
+    running: false,
+    dt: 0,
+    start() {
+      if (loop.running) return loop;
+      loop.running = true;
+      last = now();
+      const frame = () => {
+        if (!loop.running) return;
+        const t = now();
+        loop.dt = Math.min((t - last) / 1000, clamp);
+        last = t;
+        o.onFrame(loop.dt);
+        if (loop.running) handle = raf(frame);
+      };
+      handle = raf(frame);
+      return loop;
+    },
+    stop() {
+      loop.running = false;
+      if (handle !== null) { caf(handle); handle = null; }
+      return loop;
+    },
+  };
+  return loop;
+}
+
+/**
+ * @file The handle controller — a draggable constraint driven from the pointer source.
+ * @module host/handle
+ * @license AGPL-3.0-only
+ *
+ * Wraps a core Constraint (@nakednous/tree) with the transport a draggable
+ * 3D control needs: presses, moves and releases from the host's pointer
+ * source, a pixel → ray unprojection through the host's view bag, an
+ * analytic pick against the constraint's proxy, and a host-driven update()
+ * lifecycle. No drawing: a bridge draws the locus (locusLines) and the dot.
+ *
+ * ── update() ordering contract ─────────────────────────────────────────────
+ * update() is host-driven, before the orbit, because the orbit gate depends
+ * on the grab resolving first:
+ *
+ *   onFrame() { setCamera(cam); if (!h.update()) orbit.update(); scene() }
+ *
+ * ── Pick ───────────────────────────────────────────────────────────────────
+ * The pointer's ray is unproject(x, y, view) in WORLD; the grab size is
+ * grabPx converted to world units through pixelRatio at the proxy's depth;
+ * the constraint's proxy(ray, radius) answers t or Infinity. Built-in kinds
+ * carry their proxy (a sphere at the point, the DIAL's ring); a custom kind
+ * supplies one or gets the sphere. solve() runs in WORLD; value() converts.
+ *
+ * ── Pointer source ─────────────────────────────────────────────────────────
+ * update() reads the frame's press queue and the tracked pointer's entry
+ * (seq counts moves; up / cancel end the gesture; Esc cancels every claimed
+ * pointer). A grab claims the pointer, which captures it on the canvas; a
+ * miss leaves it unclaimed for the orbit. The whole gesture keys to one
+ * pointerId, so on a shared surface each handle tracks its own finger.
+ *
+ * ── Constraint kinds ───────────────────────────────────────────────────────
+ * Core SPHERE / PLANE / AXIS / DIAL pass straight through. VIEW is a core
+ * PLANE re-aimed at the camera each solve — a screen-parallel drag plane
+ * through the current point — reported as a world position; its constraint
+ * carries `view: true`, the flag locusLines reads. A custom kind is a
+ * contract-conforming object (kind / solve / value / seed, optional scalar /
+ * azEl / aim / proxy / locus) passed as `constraint`.
+ *
+ * ── Snap / hover / cancel / from ───────────────────────────────────────────
+ * snap quantises at the solve seam: an angular step for SPHERE (az/el) and
+ * DIAL (θ), a world grid for PLANE / AXIS / VIEW (PLANE re-projecting).
+ * hover is a lone-handle opt-in (a router provides it shared). Cancel — Esc,
+ * pointercancel, cancel() — reverts to the value captured at grab, restores
+ * the binding and fires onCancel instead of onRelease. `from` names the space
+ * the symbolic basis (axis / normal / zero) resolves FROM into WORLD each idle
+ * frame through mapDirection on the view bag — WORLD, EYE, or a mat4 —
+ * frozen at grab.
+ */
+
+
+/** The screen-parallel free-translate constraint (a core PLANE re-aimed each solve). */
+const VIEW = 4;
+
+// Module-level scratch — update() and value() run to completion within one
+// frame with no reentrancy across handles.
+const _rayO = [0, 0, 0];             // pick ray origin, WORLD
+const _rayD = [0, 0, 0];             // pick ray unit direction, WORLD
+/** The ray scratch a handle's _ray(x, y) fills — the router's shared pick reads it. */
+const rayScratch = { o: _rayO, d: _rayD };
+const _v3   = [0, 0, 0];             // value() extraction scratch
+const _q2   = [0, 0];                // az/el snap scratch
+const _b0   = [0, 0, 0];             // resolved θ = 0 reference
+const _b2   = [0, 0, 0];             // resolved axis / normal
+const _frameInv = new Float32Array(16);
+
+// The mapping bag mapLocation / mapDirection take: the view's matrices plus
+// the frames a call names (a mat4 `from` or `to` is the MATRIX space).
+const _bag = { mat4Proj: null, mat4View: null, mat4PV: null, mat4PVInv: null, mat4Eye: null,
+               fromFrame: null, toFrame: null, toFrameInv: null };
+const _isMat = (s) => s != null && typeof s !== 'string';
+const _space = (s) => (_isMat(s) ? MATRIX : s);
+
+function _bagOf(view, from, to) {
+  _bag.mat4Proj = view.mat4Proj; _bag.mat4View = view.mat4View;
+  _bag.mat4PV = view.mat4PV; _bag.mat4PVInv = view.mat4PVInv; _bag.mat4Eye = view.mat4Eye;
+  _bag.fromFrame = _isMat(from) ? from : null;
+  if (_isMat(to)) { _bag.toFrame = to; _bag.toFrameInv = mat4Invert(_frameInv, to) ? _frameInv : null; }
+  else { _bag.toFrame = null; _bag.toFrameInv = null; }
+  return _bag;
+}
+
+const _norm3 = (o) => {
+  const l = Math.hypot(o[0], o[1], o[2]) || 1;
+  o[0] /= l; o[1] /= l; o[2] /= l;
+  return o;
+};
+
+// Orthonormal in-plane basis for a unit normal n, seeded from the world axis
+// least aligned with it (a DIAL's θ = 0 reference when `from` gives none).
+const _basisFromNormal = (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];
+  _norm3(ub);
+  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];
+};
+
+// Read component i of an array or {x, y, z}, falling back to d.
+const _vx$1 = (v, i, d) => {
+  if (v == null) return d;
+  const c = i === 0 ? v.x : i === 1 ? v.y : v.z;
+  return c ?? v[i] ?? d;
+};
+
+/** Contract check for a custom constraint object. */
+const isConstraint = (c) =>
+  c && typeof c === 'object' &&
+  typeof c.solve === 'function' &&
+  typeof c.value === 'function' &&
+  typeof c.seed  === 'function';
+
+/**
+ * The handle controller. Stateful and long-lived, like a track; driven from
+ * the frame through update(), read with value(out, opts).
+ */
+class Handle {
+  /**
+   * @param {object} host  The host context (its pointer source and view bag).
+   * @param {object} opts  See host.handle().
+   */
+  constructor(host, opts) {
+    this._host = host;
+    this._pointer = host.pointer;
+    this._view = host.view;
+
+    const kind = opts.constraint;
+    this._isView = (kind === VIEW);
+    if (isConstraint(kind)) {
+      this._constraint = kind;
+    } else {
+      const coreKind = this._isView ? PLANE : kind;
+      // Vector opts pass straight through — the core duck-types arrays and {x, y, z}.
+      this._constraint = createConstraint(coreKind, {
+        radius: opts.radius, report: opts.report, anchor: opts.anchor,
+        normal: opts.normal, axis: opts.axis, zero: opts.zero, extent: opts.extent,
+      });
+      if (this._isView) this._constraint.view = true;   // the flag locusLines reads
+    }
+
+    // Deferred constraint frame: the symbolic basis and the space it resolves from.
+    this._from = null; this._fromDir = null; this._fromZero = null;
+    if (opts.from != null && opts.from !== WORLD) {
+      const custom = isConstraint(kind);
+      const dirOpt = (kind === PLANE) ? opts.normal : (opts.axis ?? opts.normal);
+      const ok = !this._isView &&
+                 (kind === PLANE || kind === AXIS || kind === DIAL ||
+                  (custom && typeof this._constraint.aim === 'function'));
+      if (!ok) {
+        console.error('[host] handle: `from` needs an aimable constraint — PLANE, AXIS, DIAL, or a custom kind exposing aim(); ignoring.');
+      } else if (custom && dirOpt == null) {
+        console.error('[host] handle: `from` on a custom kind needs a symbolic `axis` (or `normal`) to resolve; ignoring.');
+      } else {
+        this._from = opts.from;
+        this._fromDir = [_vx$1(dirOpt, 0, kind === AXIS ? 1 : 0), _vx$1(dirOpt, 1, kind === AXIS ? 0 : 1), _vx$1(dirOpt, 2, 0)];
+        if (opts.zero != null) {
+          this._fromZero = [_vx$1(opts.zero, 0, 1), _vx$1(opts.zero, 1, 0), _vx$1(opts.zero, 2, 0)];
+        } else if (kind === DIAL) {
+          // Derive the θ = 0 reference once, in the FROM space, so axis and zero co-rotate.
+          _b2[0] = this._fromDir[0]; _b2[1] = this._fromDir[1]; _b2[2] = this._fromDir[2];
+          _norm3(_b2);
+          const r0 = [0, 0, 0], r1 = [0, 0, 0];
+          _basisFromNormal(_b2, r0, r1);
+          this._fromZero = r0;
+        }
+      }
+    }
+
+    this._enabled = opts.enabled !== false;
+    this._grabPx  = Number.isFinite(opts.grabPx) ? opts.grabPx : 12;
+    this._snap    = opts.snap ?? null;
+    this._hover   = opts.hover === true;
+    this._hovered = false;
+    this._hid = null; this._hseq = -1;       // the pointer last hover-tested, and its seq then
+
+    // Transport state: one pointerId per gesture, its last consumed move seq
+    // and its position in logical canvas px; _routed hands the down step to a router.
+    this._grabbed = false;
+    this._pid = null;
+    this._seq = -1;
+    this._ptr = [0, 0];
+    this._routed = false;
+
+    // The proxy: its world position and the grab radius in world units.
+    this._proxyPos = [0, 0, 0];
+    this._proxyRad = 0;
+
+    // Cancel state — the value (and scalar, for winding) captured at grab.
+    this._saved = [0, 0, 0];
+    this._savedS = 0;
+
+    // Hooks — user-facing, then the lib-space seams a router or a track owns.
+    this.onGrab    = typeof opts.onGrab    === 'function' ? opts.onGrab    : null;
+    this.onRelease = typeof opts.onRelease === 'function' ? opts.onRelease : null;
+    this.onChange  = typeof opts.onChange  === 'function' ? opts.onChange  : null;
+    this.onCancel  = typeof opts.onCancel  === 'function' ? opts.onCancel  : null;
+    this._onGrab = null; this._onRelease = null; this._onChange = null; this._onCancel = null;
+
+    // Binding — a normalised { get, set } accessor; _bindVal the reused value array.
+    this._binder = null;
+    this._bindVal = [0, 0, 0];
+
+    if (opts.bind != null) this.bind(opts.bind);
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────
+
+  /**
+   * Resolve the grab and re-solve from the pointer. Call first in the frame,
+   * before the orbit; a routed handle is updated by its router. Returns the
+   * grabbed state so the orbit gate can short-circuit; a disabled handle
+   * returns false.
+   * @returns {boolean} grabbed
+   */
+  update() {
+    if (!this._enabled) {
+      if (this._pid !== null && this._pointer) this._pointer.release(this._pid);
+      this._grabbed = false; this._hovered = false; this._pid = null;
+      return false;
+    }
+    const src = this._pointer;
+    if (!src) return false;
+    if (this._from && !this._grabbed) this._resolveFrame();
+
+    // Fresh press (unrouted): the first unclaimed press this frame is
+    // hit-tested at its pixel; a hit claims the pointer, a miss leaves it.
+    if (!this._routed && this._pid === null) {
+      for (const pr of src.presses) {
+        if (src.ownerOf(pr.id) !== null) continue;
+        this._ptr[0] = pr.x; this._ptr[1] = pr.y;
+        if (this._pickAt(pr.x, pr.y)) { this._adopt(pr.id, pr.x, pr.y); break; }
+      }
+    }
+
+    if (this._pid !== null) {
+      const e = src.get(this._pid);
+      if (!e) {
+        this._cancelNow();                       // the entry left before this handle saw its end
+      } else {
+        if (this._grabbed && e.seq !== this._seq && !e.cancel) {
+          this._seq = e.seq;
+          this._ptr[0] = e.x; this._ptr[1] = e.y;
+          this._solveFromPointer(e.x, e.y);
+          this._applySnap();
+          this._afterSolve();
+        }
+        if (e.cancel) {
+          this._cancelNow();
+        } else if (e.up) {
+          src.release(this._pid);
+          this._grabbed = false;
+          this._pid = null;
+          this.onRelease  && this.onRelease(this);
+          this._onRelease && this._onRelease(this);
+        }
+      }
+    }
+
+    // Hover: a lone handle tests the latest unclaimed pointer motion.
+    if (this._grabbed) {
+      this._hovered = true;
+    } else if (this._hover && !this._routed) {
+      for (const e of src.pointers.values()) {
+        if (e.owner !== null) continue;
+        if (e.id === this._hid && e.seq === this._hseq) continue;
+        this._hid = e.id; this._hseq = e.seq;
+        this._hovered = this._pickAt(e.x, e.y);
+        break;
+      }
+    }
+    return this._grabbed;
+  }
+
+  _beginGrab() {
+    const c = this._constraint;
+    c.value(this._saved, POINT);
+    this._savedS = typeof c.scalar === 'function' ? c.scalar() : 0;
+    this._grabbed = true;
+    this.onGrab  && this.onGrab(this);
+    this._onGrab && this._onGrab(this);
+  }
+
+  /** Router seam: adopt a pointer a shared pick decided; claims it through the source. */
+  _adopt(pointerId, x, y) {
+    const e = this._pointer.get(pointerId);
+    this._pid = pointerId;
+    this._seq = e ? e.seq : -1;
+    this._ptr[0] = x; this._ptr[1] = y;
+    this._pointer.claim(pointerId, this);
+    this._beginGrab();
+  }
+
+  /**
+   * Revert the drag in flight to the value captured at grab (exact θ winding
+   * included), restore the binding, fire onCancel. No-op when not grabbed.
+   * Chainable.
+   * @returns {Handle} this
+   */
+  cancel() {
+    if (this._grabbed) this._cancelNow();
+    return this;
+  }
+
+  _cancelNow() {
+    const c = this._constraint;
+    if (this._isView) {
+      c.pt[0] = this._saved[0]; c.pt[1] = this._saved[1]; c.pt[2] = this._saved[2];
+    } else if (c.kind === DIAL) {
+      c.s = this._savedS;
+      c._dialPoint();
+    } else {
+      c.seed(this._saved[0], this._saved[1], this._saved[2]);
+    }
+    if (this._binder) this._binder.set(this.value(this._bindVal));
+    this._grabbed = false;
+    if (this._pid !== null && this._pointer) this._pointer.release(this._pid);
+    this._pid = null;
+    this.onCancel  && this.onCancel(this);
+    this._onCancel && this._onCancel(this);
+  }
+
+  // ── Frame, pick, solve ──────────────────────────────────────────────────
+
+  // Resolve the symbolic basis from its space into WORLD through the view
+  // bag and re-aim the constraint; idle frames only.
+  _resolveFrame() {
+    const v = this._view, bag = _bagOf(v, this._from, null), from = _space(this._from);
+    const d = this._fromDir;
+    mapDirection(_b2, d[0], d[1], d[2], from, WORLD, bag, v.vp, v.ndcZMin);
+    if (this._fromZero) {
+      const z = this._fromZero;
+      mapDirection(_b0, z[0], z[1], z[2], from, WORLD, bag, v.vp, v.ndcZMin);
+      this._constraint.aim(_b2[0], _b2[1], _b2[2], _b0[0], _b0[1], _b0[2]);
+    } else {
+      this._constraint.aim(_b2[0], _b2[1], _b2[2]);
+    }
+  }
+
+  // The proxy's world position and its grab radius in world units — a
+  // constant grabPx screen size at the proxy's depth.
+  _proxyPrep() {
+    const c = this._constraint, v = this._view, p = this._proxyPos;
+    if (this._from && !this._grabbed) this._resolveFrame();
+    if (c.kind === DIAL && !this._isView) {
+      p[0] = c.anchor[0]; p[1] = c.anchor[1]; p[2] = c.anchor[2];
+    } else {
+      c.value(p, POINT);
+    }
+    const V = v.mat4View;
+    const eyeZ = V[2]*p[0] + V[6]*p[1] + V[10]*p[2] + V[14];
+    this._proxyRad = this._grabPx * pixelRatio(v.mat4Proj, -v.vp[3], eyeZ, v.ndcZMin);
+  }
+
+  // The analytic pick: t along the ray, or Infinity.
+  _proxyT(o, d) {
+    this._proxyPrep();
+    const c = this._constraint;
+    if (typeof c.proxy === 'function') return c.proxy(o[0], o[1], o[2], d[0], d[1], d[2], this._proxyRad);
+    const p = this._proxyPos;
+    return rayHitSphere(o[0], o[1], o[2], d[0], d[1], d[2], p[0], p[1], p[2], this._proxyRad);
+  }
+
+  /** Unproject a canvas pixel into the ray scratch; false on a stale view. */
+  _ray(x, y) {
+    const v = this._view;
+    if (v.stale) return false;
+    return unproject(_rayO, _rayD, x, y, v, v.vp, v.ndcZMin) !== null;
+  }
+
+  /** Hit-test the proxy at a canvas pixel. */
+  _pickAt(x, y) {
+    return this._ray(x, y) && this._proxyT(_rayO, _rayD) < Infinity;
+  }
+
+  _solveFromPointer(x, y) {
+    if (!this._ray(x, y)) return;
+    if (this._isView) this._viewUpdatePlane();
+    this._constraint.solve(_rayO[0], _rayO[1], _rayO[2], _rayD[0], _rayD[1], _rayD[2]);
+  }
+
+  // VIEW: re-aim the plane at the camera through the current point — its
+  // normal the look direction (−Z of the eye matrix), its anchor the point.
+  _viewUpdatePlane() {
+    const c = this._constraint, E = this._view.mat4Eye;
+    c.n[0] = -E[8]; c.n[1] = -E[9]; c.n[2] = -E[10];
+    _norm3(c.n);
+    c.anchor[0] = c.pt[0]; c.anchor[1] = c.pt[1]; c.anchor[2] = c.pt[2];
+  }
+
+  // ── Snap ────────────────────────────────────────────────────────────────
+
+  /** Snap step — angular (rad) for SPHERE / DIAL, a world grid for PLANE / AXIS / VIEW; null off. */
+  get snap()  { return this._snap; }
+  set snap(v) { this._snap = v ?? null; }
+
+  _applySnap() {
+    const sn = this._snap;
+    if (sn == null) return;
+    const c = this._constraint;
+    if (this._isView || c.kind === PLANE) {
+      const gx = Array.isArray(sn) ? sn[0] : sn, gy = Array.isArray(sn) ? sn[1] : sn, gz = Array.isArray(sn) ? sn[2] : sn;
+      _v3[0] = gx > 0 ? Math.round(c.pt[0] / gx) * gx : c.pt[0];
+      _v3[1] = gy > 0 ? Math.round(c.pt[1] / gy) * gy : c.pt[1];
+      _v3[2] = gz > 0 ? Math.round(c.pt[2] / gz) * gz : c.pt[2];
+      if (this._isView) { c.pt[0] = _v3[0]; c.pt[1] = _v3[1]; c.pt[2] = _v3[2]; }
+      else c.seed(_v3[0], _v3[1], _v3[2]);
+    } else if (c.kind === AXIS || c.kind === DIAL) {
+      const step = Array.isArray(sn) ? sn[0] : sn;
+      if (!(step > 0)) return;
+      const q = Math.round(c.s / step) * step;
+      c.s = q < c.min ? c.min : (q > c.max ? c.max : q);
+      if (c.kind === DIAL) c._dialPoint();
+      else {
+        c.pt[0] = c.anchor[0] + c.s * c.u[0];
+        c.pt[1] = c.anchor[1] + c.s * c.u[1];
+        c.pt[2] = c.anchor[2] + c.s * c.u[2];
+      }
+    } else if (c.kind === SPHERE) {
+      const step = Array.isArray(sn) ? sn[0] : sn;
+      if (!(step > 0)) return;
+      c.azEl(_q2);
+      dirFromAzEl(c.dir, Math.round(_q2[0] / step) * step, Math.round(_q2[1] / step) * step);
+    }
+  }
+
+  // ── Value and binding ───────────────────────────────────────────────────
+
+  /**
+   * Write the current value into `out`. `report` overrides the constraint's
+   * (POINT | DIRECTION); `to` converts from WORLD to EYE, SCREEN, NDC, or a
+   * mat4 frame through the view bag. Out-first, out required.
+   * @param {number[]} out  3-element destination.
+   * @param {{ to?:string|ArrayLike<number>, report?:number }} [opts]
+   * @returns {number[]} out
+   */
+  value(out, opts) {
+    const o = opts || {}, c = this._constraint;
+    const report = (o.report === POINT || o.report === DIRECTION) ? o.report : c.report;
+    const to = o.to ?? WORLD;
+    c.value(_v3, report);
+    if (to === WORLD) { out[0] = _v3[0]; out[1] = _v3[1]; out[2] = _v3[2]; return out; }
+    const v = this._view, bag = _bagOf(v, null, to), space = _space(to);
+    return report === DIRECTION
+      ? mapDirection(out, _v3[0], _v3[1], _v3[2], WORLD, space, bag, v.vp, v.ndcZMin)
+      : mapLocation(out, _v3[0], _v3[1], _v3[2], WORLD, space, bag, v.vp, v.ndcZMin);
+  }
+
+  /**
+   * Bind the handle to a target it drives while dragging: a `{ get, set }`
+   * accessor, or a vec3 array mutated in place (a camera state's eye or
+   * center is one). get() seeds the constraint now; each solve calls
+   * set(value) with the reused value array, then fires onChange. Chainable.
+   * @param {number[]|{ get:Function, set:Function }} target
+   * @returns {Handle} this
+   */
+  bind(target) {
+    let binder = null;
+    if (target && typeof target.get === 'function' && typeof target.set === 'function') {
+      binder = target;
+    } else if (target && typeof target === 'object' && typeof target.length === 'number' && target.length >= 3) {
+      binder = { get: () => target, set: (v) => { target[0] = v[0]; target[1] = v[1]; target[2] = v[2]; } };
+    } else {
+      console.error('[host] handle.bind: unrecognised target — pass a vec3 array or an { get, set } accessor. Leaving unbound.');
+      return this;
+    }
+    this._binder = binder;
+    if (this._from && !this._grabbed) this._resolveFrame();
+    this._seedFromBinding();
+    return this;
+  }
+
+  /** Re-seed the constraint from the bound target after it changed externally. Chainable. */
+  sync() {
+    if (this._binder) this._seedFromBinding();
+    return this;
+  }
+
+  _seedFromBinding() {
+    const g = this._binder.get();
+    if (g == null) return;
+    const x = _vx$1(g, 0, 0), y = _vx$1(g, 1, 0), z = _vx$1(g, 2, 0);
+    if (this._isView) { const pt = this._constraint.pt; pt[0] = x; pt[1] = y; pt[2] = z; }
+    else this._constraint.seed(x, y, z);
+  }
+
+  // Push the freshly solved value to the binding and fire onChange, once per solve.
+  _afterSolve() {
+    const bound = this._binder !== null;
+    const notify = !!(this.onChange || this._onChange);
+    if (!bound && !notify) return;
+    const v = this.value(this._bindVal);
+    if (bound) this._binder.set(v);
+    if (notify) {
+      this.onChange  && this.onChange(v, this);
+      this._onChange && this._onChange(v, this);
+    }
+  }
+
+  // ── Readouts and edits ──────────────────────────────────────────────────
+
+  /** AXIS: the signed distance along the rail; DIAL: the accumulated angle; NaN otherwise. */
+  scalar() { return typeof this._constraint.scalar === 'function' ? this._constraint.scalar() : NaN; }
+
+  /** SPHERE: [az, el] of the current direction, into out2. */
+  azEl(out2) {
+    const o = out2 || [0, 0];
+    return typeof this._constraint.azEl === 'function' ? this._constraint.azEl(o) : o;
+  }
+
+  /** True between grab and release. */
+  grabbed() { return this._grabbed; }
+
+  /** True while the pointer rests on the proxy, and while grabbed. */
+  hovered() { return this._hovered; }
+
+  /**
+   * Move the reference point — sphere centre, plane point, axis anchor,
+   * dial centre, or a VIEW handle's point; the stored point rides along.
+   * Chainable.
+   * @param {number[]|{x:number,y:number,z:number}} v
+   * @returns {Handle} this
+   */
+  anchor(v) {
+    const c = this._constraint;
+    const t = this._isView ? c.pt : c.anchor;
+    if (!t) return this;
+    t[0] = _vx$1(v, 0, t[0]); t[1] = _vx$1(v, 1, t[1]); t[2] = _vx$1(v, 2, t[2]);
+    if (!this._isView) {
+      if (c.kind === DIAL) c._dialPoint();
+      else if (c.kind === AXIS) {
+        c.pt[0] = c.anchor[0] + c.s * c.u[0];
+        c.pt[1] = c.anchor[1] + c.s * c.u[1];
+        c.pt[2] = c.anchor[2] + c.s * c.u[2];
+      } else if (c.kind === PLANE) c.seed(c.pt[0], c.pt[1], c.pt[2]);
+    }
+    return this;
+  }
+
+  /** Runtime gate — false suspends grab / solve without disposing. */
+  get enabled() { return this._enabled; }
+  set enabled(v) {
+    this._enabled = !!v;
+    if (!this._enabled) {
+      if (this._pid !== null && this._pointer) this._pointer.release(this._pid);
+      this._grabbed = false; this._hovered = false; this._pid = null;
+    }
+  }
+
+  /** Release the pointer claim and leave the host. */
+  dispose() {
+    if (this._pid !== null && this._pointer) this._pointer.release(this._pid);
+    this._pid = null;
+    this._grabbed = false;
+    this._pointer = null;
+    this._host.unregister(this);
+  }
+}
+
+/**
+ * Validate the constraint option: a built-in kind, VIEW, or a contract object.
+ * @param {*} kind
+ * @returns {boolean}
+ */
+function validConstraint(kind) {
+  return kind === SPHERE || kind === PLANE || kind === AXIS || kind === DIAL || kind === VIEW || !!isConstraint(kind);
+}
+
+/**
+ * @file The pointer router — shared arbitration for overlapping handles.
+ * @module host/router
+ * @license AGPL-3.0-only
+ *
+ * Per-handle self-picking double-grabs on overlap: two proxies under one
+ * finger each test only themselves and both hit. The router replaces the
+ * members' down step with one shared pick: the pointer's ray once, every
+ * enabled member's proxy tested, the nearest t wins (a tie keeps the
+ * earlier member, as draw order would). Members keep their own move /
+ * solve / release machinery, grabbed through their injected _adopt; every
+ * unclaimed press of the frame resolves, so several same-frame presses on
+ * different members all land. Hover is the same test on unclaimed pointer
+ * motion, shared, setting at most one hovered member.
+ */
+
+
+/** Shared pick over a set of handles on one host. */
+class PointerRouter {
+  /**
+   * @param {object}   host     The host context.
+   * @param {object[]} handles  Members.
+   * @param {{ hover?:boolean }} [opts]  hover defaults to true.
+   */
+  constructor(host, handles, opts) {
+    const o = opts || {};
+    this._host = host;
+    this._pointer = host.pointer;
+    this._handles = [];
+    this._hover = o.hover !== false;
+    this._hoveredH = null;
+    this._hid = null; this._hseq = -1;
+    for (const h of handles || []) this.add(h);
+  }
+
+  /**
+   * Route a handle: its own pointerdown adoption is disabled and the shared
+   * pick grabs it through _adopt. Chainable.
+   * @param {object} h
+   * @returns {PointerRouter} this
+   */
+  add(h) {
+    if (!h || typeof h._proxyT !== 'function') {
+      console.error('[host] router.add: not a handle — ignoring.');
+      return this;
+    }
+    if (this._handles.includes(h)) return this;
+    h._routed = true;
+    h._onRelease = h._onCancel = () => this._unclaim(h);
+    this._handles.push(h);
+    return this;
+  }
+
+  /**
+   * Un-route a handle; it self-picks again. Chainable.
+   * @param {object} h
+   * @returns {PointerRouter} this
+   */
+  remove(h) {
+    const i = this._handles.indexOf(h);
+    if (i < 0) return this;
+    this._handles.splice(i, 1);
+    this._unclaim(h);
+    h._routed = false;
+    h._onRelease = h._onCancel = null;
+    if (this._hoveredH === h) { this._hoveredH = null; h._hovered = false; }
+    return this;
+  }
+
+  /**
+   * Resolve the frame's presses with one shared pick each, refresh hover on
+   * pointer motion, then update every member. Call first in the frame, in
+   * place of the members' own updates.
+   * @returns {boolean} true if any member is grabbed.
+   */
+  update() {
+    const hs = this._handles, src = this._pointer;
+    if (!src) return false;
+    for (const pr of src.presses) {
+      if (src.ownerOf(pr.id) !== null) continue;
+      const win = this._sharedPick(pr.x, pr.y);
+      if (win && win._pid === null && win.enabled) win._adopt(pr.id, pr.x, pr.y);
+    }
+    if (this._hover) {
+      for (const e of src.pointers.values()) {
+        if (e.owner !== null) continue;
+        if (e.id === this._hid && e.seq === this._hseq) continue;
+        this._hid = e.id; this._hseq = e.seq;
+        const win = this._sharedPick(e.x, e.y);
+        this._hoveredH = win;
+        for (const h of hs) h._hovered = (h === win) || h._grabbed;
+        break;
+      }
+    }
+    let g = false;
+    for (const h of hs) g = h.update() || g;
+    return g;
+  }
+
+  // One ray, every enabled member's proxy, the nearest t.
+  _sharedPick(x, y) {
+    const hs = this._handles;
+    const first = hs.find((h) => h.enabled);
+    if (!first || !first._ray(x, y)) return null;
+    let win = null, best = Infinity;
+    for (const h of hs) {
+      if (!h.enabled) continue;
+      const t = h._proxyT(rayScratch.o, rayScratch.d);
+      if (t < best) { best = t; win = h; }
+    }
+    return win;
+  }
+
+  _unclaim(h) {
+    const src = this._pointer;
+    if (!src) return;
+    for (const e of src.pointers.values()) if (e.owner === h) src.release(e.id);
+  }
+
+  /** The member under the pointer, or null. */
+  hovered() { return this._hoveredH; }
+
+  /** Un-route every member and leave the host. */
+  dispose() {
+    for (const h of [...this._handles]) this.remove(h);
+    this._pointer = null;
+    this._host.unregister(this);
+  }
+}
+
+/**
+ * @file Helm factories — a core PoseHelm driven from the host's players.
+ * @module host/helm
+ * @license AGPL-3.0-only
+ *
+ * cameraHelm(host, cam, opts) flies a camera state body-relative: the helm is
+ * seeded from the state through cameraToPose, integrates each tick in the
+ * state's own eye matrix (which equals the pose written last tick, so a
+ * forward push flies forward) and writes back through cameraFromPose at the
+ * state's gaze distance. poseHelm(host, opts) produces a pose in a declared
+ * frame — WORLD, EYE (the host's view bag), SELF (its own pose) or a mat4 —
+ * and drives whatever bind() names: a camera state, an { applyPose } sink, a
+ * { get, set } accessor or a { pos, rot } object. Both register a player
+ * with the host until disposed.
+ */
+
+
+const _pose = { pos: [0, 0, 0], rot: [0, 0, 0, 1] };   // step() output
+const _self = { pos: [0, 0, 0], rot: [0, 0, 0, 1] };   // eval() readout for SELF
+const _em   = new Float32Array(16);                    // the resolved basis
+
+const _rawMat4 = (m) => (m != null && m.mat4 != null) ? m.mat4 : m;
+const _isCameraState = (c) => !!(c && c.eye && c.center && c.up);
+
+function _applyOpts(helm, opts) {
+  if (!opts) return;
+  if (opts.profile)          helm.profile  = opts.profile;
+  if (opts.deadzone != null) helm.deadzone = opts.deadzone;
+  if (opts.filter != null)   helm.filter   = opts.filter;
+  if (opts.fullScale != null) helm.fullScale = opts.fullScale;
+}
+
+/**
+ * The basis a pose helm's `from` resolves to: null for WORLD, the view bag's
+ * eye matrix for EYE, the helm's own rotation for SELF, a mat4 as given.
+ * Exported for a bridge's rig gizmo.
+ * @param {PoseHelm} helm
+ * @param {object} view  The host's view bag.
+ * @param {Float32Array} em  16-element scratch.
+ * @returns {ArrayLike<number>|null}
+ */
+function helmBasis(helm, view, em) {
+  const from = helm.from;
+  if (from != null && typeof from !== 'string') return _rawMat4(from);
+  if (from === EYE)  return view ? view.mat4Eye : null;
+  if (from === SELF) return qToMat4(em, helm.eval(_self).rot);
+  if (from === WORLD || from == null) return null;
+  console.error('[host] poseHelm: `from` must be EYE, WORLD, SELF, or a mat4 frame. Falling back to WORLD.');
+  return null;
+}
+
+/**
+ * Fly a camera state from a live 6-DOF rate stream, body-relative.
+ * @param {object} host
+ * @param {object} cam   A camera state ({ eye, center, up, … }).
+ * @param {{ profile?:object, deadzone?:number, filter?:object, fullScale?:number }} [opts]
+ * @returns {PoseHelm} The helm, with dispose().
+ */
+function cameraHelm(host, cam, opts) {
+  const helm = new PoseHelm();
+  _applyOpts(helm, opts);
+  if (opts && opts.from != null) {
+    console.error('[host] cameraHelm: a camera helm is always body-fly and has no `from`. Ignoring it; bind the camera to a poseHelm for screen- or world-relative motion.');
+  }
+  if (_isCameraState(cam)) helm.home(cameraToPose(_pose, cam));
+  const player = {
+    tick(dt) {
+      helm.step(_pose, dt, _isCameraState(cam) ? cameraEye(_em, cam) : null);
+      if (_isCameraState(cam)) {
+        cameraFromPose(cam, _pose);
+        if (helm._onApply) helm._onApply(cam);
+      }
+      return true;
+    },
+  };
+  helm._onApply = null;   // lib-space seam: a bridge pushes the written state to its camera
+  host.players.add(player);
+  helm.dispose = () => { host.players.remove(player); host.unregister(helm); return helm; };
+  return host.register(helm);
+}
+
+/**
+ * Integrate a live 6-DOF rate stream into a pose in a declared frame and
+ * drive a bound target with it.
+ * @param {object} host
+ * @param {{ profile?:object, deadzone?:number, filter?:object, fullScale?:number,
+ *           from?:string|ArrayLike<number>, bind?:object }} [opts]
+ * @returns {PoseHelm} The helm, with bind() and dispose().
+ */
+function poseHelm(host, opts) {
+  const o = opts || {};
+  const helm = new PoseHelm();
+  _applyOpts(helm, o);
+  if (o.from != null) helm.from = o.from;
+  let sink = null;
+
+  const player = {
+    tick(dt) {
+      if (sink) {
+        helm.step(_pose, dt, helmBasis(helm, host.view, _em));
+        sink(_pose);
+      }
+      return true;
+    },
+  };
+  host.players.add(player);
+
+  /**
+   * Bind the target the helm drives: a camera state (seeded from it, written
+   * through cameraFromPose), an { applyPose } sink, a { get, set } accessor
+   * (get() seeds, set(pose) writes) or a { pos, rot } object mutated in
+   * place. Chainable.
+   * @param {object} target
+   * @returns {PoseHelm} this
+   */
+  helm.bind = (target) => {
+    if (_isCameraState(target)) {
+      helm.home(cameraToPose(_pose, target));
+      sink = (pose) => cameraFromPose(target, pose);
+    } else if (target && typeof target.get === 'function' && typeof target.set === 'function') {
+      helm.home(target.get());
+      sink = (pose) => target.set(pose);
+    } else if (target && typeof target.applyPose === 'function') {
+      sink = (pose) => target.applyPose(pose);
+    } else if (target && target.pos && target.rot) {
+      helm.home(target);
+      sink = (pose) => {
+        target.pos[0] = pose.pos[0]; target.pos[1] = pose.pos[1]; target.pos[2] = pose.pos[2];
+        target.rot[0] = pose.rot[0]; target.rot[1] = pose.rot[1];
+        target.rot[2] = pose.rot[2]; target.rot[3] = pose.rot[3];
+      };
+    } else {
+      console.error('[host] poseHelm: bind() target must be a camera state, an { applyPose } sink, a { get, set } accessor, or a { pos, rot } object. Leaving unbound.');
+    }
+    return helm;
+  };
+  helm.dispose = () => { host.players.remove(player); host.unregister(helm); return helm; };
+  if (o.bind != null) helm.bind(o.bind);
+  return host.register(helm);
+}
+
+/**
+ * @file Track factories and TrackHandles — core tracks wired to the host's players.
+ * @module host/track
+ * @license AGPL-3.0-only
+ *
+ * poseTrack(host, opts) is a core PoseTrack whose activation hooks add and
+ * remove its player. cameraTrack(host, cam, opts) is a core CameraTrack whose
+ * player evaluates straight into the camera state `cam` — the state is the
+ * keyframe shape, so track.eval(cam) is the write — and once more on
+ * deactivate so the camera rests on the path; add() with no argument
+ * captures `cam`, add({ camera }) any camera-state object. { handles } on
+ * either decorates the track with TrackHandles: one VIEW handle per
+ * draggable keyframe field (pos / eye / center), an optional rot DIAL per
+ * keyframe about a declared axis, all on one router.
+ */
+
+
+// ── Players ────────────────────────────────────────────────────────────────
+
+function _wirePoseTrack(host, track) {
+  let player = null;
+  track._onActivate = () => {
+    player = player || { tick() { track.tick(); return track.playing; } };
+    host.players.add(player);
+  };
+  track._onDeactivate = () => { if (player) host.players.remove(player); };
+}
+
+/**
+ * A core PoseTrack ticked by the host while it plays.
+ * @param {object} host
+ * @param {{ handles?:boolean|object }} [opts]
+ * @returns {PoseTrack}
+ */
+function poseTrack(host, opts) {
+  const o = opts || {};
+  const track = new PoseTrack();
+  _wirePoseTrack(host, track);
+  if (o.handles) track.handles = new TrackHandles(host, track, o.handles, false);
+  return track;
+}
+
+/**
+ * A core CameraTrack evaluating into the camera state `cam` while it plays.
+ * @param {object} host
+ * @param {object} cam   A camera state ({ eye, center, up, fov, halfHeight, near, far }).
+ * @param {{ handles?:boolean|object }} [opts]
+ * @returns {CameraTrack}
+ */
+function cameraTrack(host, cam, opts) {
+  const o = opts || {};
+  const track = new CameraTrack();
+  const state = cam || null;   // the evaluation target; track.camera is informational
+  track.camera = state;
+  track._onApply = null;       // lib-space seam: a bridge pushes the evaluated state to its camera
+
+  const coreAdd = track.add.bind(track);
+  track.add = function (spec, addOpts) {
+    if (spec == null) {
+      if (!state) return;
+      spec = state;
+    } else if (Array.isArray(spec)) {
+      for (const s of spec) track.add(s, addOpts);
+      return;
+    } else if (spec.camera != null) {
+      spec = spec.camera;
+    }
+    coreAdd(spec, addOpts);
+  };
+
+  const apply = () => {
+    if (!state || track.keyframes.length === 0) return;
+    track.eval(state);
+    if (track._onApply) track._onApply(state);
+  };
+  const player = {
+    tick() {
+      if (!track.playing) return false;
+      track.tick();
+      apply();
+      return track.playing;
+    },
+  };
+  track._onActivate   = () => host.players.add(player);
+  track._onDeactivate = () => { host.players.remove(player); apply(); };
+
+  if (o.handles) track.handles = new TrackHandles(host, track, o.handles, true);
+  return track;
+}
+
+// ── TrackHandles ───────────────────────────────────────────────────────────
+
+const _vx = (v, i) => (v[i] !== undefined ? v[i] : (i === 0 ? v.x : i === 1 ? v.y : v.z));
+
+/**
+ * Per-keyframe manipulators of a track — the factories' `handles` opt,
+ * stored at track.handles. Members are internal handles on one router;
+ * their hooks are re-exposed with keyframe coordinates: onGrab(index, field,
+ * h) / onChange(value, index, field, h) / onRelease / onCancel, field one of
+ * 'pos' | 'eye' | 'center' | 'rot'. update() rebuilds the members when the
+ * keyframe count changes and re-seeds every idle member from its keyframe.
+ * A bridge draws the members itself (`members`).
+ */
+class TrackHandles {
+  /**
+   * @param {object} host
+   * @param {object} track       PoseTrack | CameraTrack.
+   * @param {true|object} opts   `true` for the defaults, or
+   *        { center?, rot?, rotRadius?, rotSnap?, grabPx?, snap?, hover? }.
+   * @param {boolean} isCamera   CameraTrack (eye / center) vs PoseTrack (pos / rot).
+   */
+  constructor(host, track, opts, isCamera) {
+    const o = opts === true ? {} : (opts || {});
+    this._host     = host;
+    this._track    = track;
+    this._isCamera = !!isCamera;
+    this._members    = [];
+    this._rotByIndex = new Map();
+    this._n          = -1;
+    this._enabled    = true;
+    /** Last-grabbed keyframe index, null until a grab. @type {number|null} */
+    this.selected = null;
+
+    this._grabPx  = Number.isFinite(o.grabPx) ? o.grabPx : 12;
+    this._snap    = o.snap    ?? null;
+    this._rotSnap = o.rotSnap ?? null;
+    this._center  = this._isCamera ? (o.center !== false) : false;
+    if (!this._isCamera && o.center !== undefined) console.error('[host] track handles: `center` is CameraTrack-only — ignoring.');
+    this._rotAxis   = null;
+    this._rotRadius = Number.isFinite(o.rotRadius) ? o.rotRadius : 40;
+    if (o.rot != null) {
+      if (this._isCamera) {
+        console.error('[host] track handles: `rot` is PoseTrack-only — a camera keyframe\'s orientation is its center; drag that instead. Ignoring.');
+      } else {
+        const ax = _vx(o.rot, 0) ?? 0, ay = _vx(o.rot, 1) ?? 1, az = _vx(o.rot, 2) ?? 0;
+        const l = Math.hypot(ax, ay, az) || 1;
+        this._rotAxis = [ax / l, ay / l, az / l];
+      }
+    }
+
+    this.onGrab = null; this.onChange = null; this.onRelease = null; this.onCancel = null;
+    this._hover  = o.hover !== false;
+    this._router = null;   // made on the first rebuild, once a subclass is constructed
+  }
+
+  // The construction seams a bridge subclass overrides so the members are
+  // handles it can draw.
+  _makeHandle(opts) { return this._host.handle(opts); }
+  _makeRouter(opts) { return this._host.router([], opts); }
+
+  /** The members, { h, index, field } each, for a bridge's draw. */
+  get members() { return this._members; }
+  /** Dot radius in pixels, the members' grabPx. */
+  get grabPx() { return this._grabPx; }
+
+  /**
+   * Rebuild if the keyframe count changed, re-seed idle members, then route.
+   * Call first in the frame, before the orbit.
+   * @returns {boolean} true while any member is grabbed.
+   */
+  update() {
+    if (this._track.keyframes.length !== this._n) this._rebuild();
+    if (this._enabled) this._syncIdle();
+    return this._router.update();
+  }
+
+  /** The members' router, made on the first update(). */
+  get router() { return this._router; }
+
+  /** Runtime gate — false suspends grab / solve and empties the pick. */
+  get enabled() { return this._enabled; }
+  set enabled(v) {
+    this._enabled = !!v;
+    for (const m of this._members) m.h.enabled = this._enabled;
+  }
+
+  /** True while any member is grabbed. */
+  grabbed() {
+    for (const m of this._members) if (m.h.grabbed()) return true;
+    return false;
+  }
+
+  /** The keyframe index under the pointer (or grabbed), else null. */
+  hovered() {
+    for (const m of this._members) if (m.h.hovered()) return m.index;
+    return null;
+  }
+
+  /** Re-seed every idle member from its keyframe. Chainable. */
+  sync() { this._syncIdle(); return this; }
+
+  /** Dispose the members and the router, detach from the track. */
+  dispose() {
+    this._teardown();
+    if (this._router) this._router.dispose();
+    if (this._track.handles === this) this._track.handles = null;
+  }
+
+  _rebuild() {
+    if (!this._router) this._router = this._makeRouter({ hover: this._hover });
+    this._teardown();
+    const n = this._track.keyframes.length;
+    this._n = n;
+    for (let i = 0; i < n; i++) {
+      this._addViewMember(i, this._isCamera ? 'eye' : 'pos');
+      if (this._center)  this._addViewMember(i, 'center');
+      if (this._rotAxis) this._addRotMember(i);
+    }
+    if (this.selected != null && this.selected >= n) this.selected = null;
+  }
+
+  _teardown() {
+    for (const m of this._members) { this._router.remove(m.h); m.h.dispose(); }
+    this._members.length = 0;
+    this._rotByIndex.clear();
+  }
+
+  // A VIEW member bound to kf[field] by index, so set(i, spec) replacing the
+  // keyframe never strands it.
+  _addViewMember(index, field) {
+    const track = this._track;
+    const h = this._makeHandle({
+      constraint: VIEW, grabPx: this._grabPx, snap: this._snap,
+      bind: {
+        get: () => track.keyframes[index] ? track.keyframes[index][field] : null,
+        set: (v) => {
+          const k = track.keyframes[index];
+          if (!k) return;
+          const a = k[field];
+          a[0] = _vx(v, 0); a[1] = _vx(v, 1); a[2] = _vx(v, 2);
+        },
+      },
+    });
+    if (!h) return;
+    this._wire(h, index, field);
+    this._members.push({ h, index, field });
+    this._router.add(h);
+  }
+
+  // A rot member: one DIAL about the declared axis at the keyframe's
+  // position, unbound — θ lands in kf.rot through the hooks.
+  _addRotMember(index) {
+    const kf = this._track.keyframes[index];
+    const h = this._makeHandle({
+      constraint: DIAL, anchor: [kf.pos[0], kf.pos[1], kf.pos[2]],
+      axis: this._rotAxis, radius: this._rotRadius, grabPx: this._grabPx, snap: this._rotSnap,
+    });
+    if (!h) return;
+    this._wire(h, index, 'rot');
+    const m = { h, index, field: 'rot' };
+    this._members.push(m);
+    this._rotByIndex.set(index, m);
+    this._router.add(h);
+    this._syncRot(m);
+  }
+
+  _wire(h, index, field) {
+    const rotWrite = () => {
+      const k = this._track.keyframes[index];
+      if (k) { const u = this._rotAxis; qFromAxisAngle(k.rot, u[0], u[1], u[2], h.scalar()); }
+    };
+    h.onGrab = () => {
+      this.selected = index;
+      if (this.onGrab) this.onGrab(index, field, h);
+    };
+    h.onChange = (v) => {
+      if (field === 'rot') rotWrite();
+      else if (field === 'pos') {
+        // Forward the dragged position into the keyframe's rot ring now, so
+        // the ring never trails the dot by a frame.
+        const rm = this._rotByIndex.get(index);
+        const k = this._track.keyframes[index];
+        if (rm && k) rm.h.anchor(k.pos);
+      }
+      if (this.onChange) this.onChange(v, index, field, h);
+    };
+    h.onRelease = () => { if (this.onRelease) this.onRelease(index, field, h); };
+    h.onCancel = () => {
+      if (field === 'rot') rotWrite();   // a DIAL is unbound: re-derive from the reverted θ
+      if (this.onCancel) this.onCancel(index, field, h);
+    };
+  }
+
+  _syncIdle() {
+    for (const m of this._members) {
+      if (m.h.grabbed()) continue;
+      if (m.field === 'rot') this._syncRot(m);
+      else m.h.sync();
+    }
+  }
+
+  // Anchor the ring at the live keyframe position and set θ to the twist of
+  // kf.rot about the axis: θ = 2·atan2(q.xyz · u, q.w).
+  _syncRot(m) {
+    const k = this._track.keyframes[m.index];
+    if (!k) return;
+    m.h.anchor(k.pos);
+    const u = this._rotAxis;
+    const th = 2 * Math.atan2(k.rot[0] * u[0] + k.rot[1] * u[1] + k.rot[2] * u[2], k.rot[3]);
+    const c = m.h._constraint;
+    if (c.s !== th) { c.s = th; c._dialPoint(); }
+  }
+}
+
+/**
+ * @file The host context — one per canvas: pointer, view bag, players, loop, observer.
+ * @module host
+ * @license AGPL-3.0-only
+ *
+ * The signal host of a program: what it needs from the browser that is
+ * neither math nor GPU — a canvas element's pointer input, the frame clock,
+ * its size — and the registry its constructs tick from. Pure vanilla DOM;
+ * everything it computes goes through @nakednous/tree, nothing it draws.
+ *
+ *   const host = createHost(canvas, { onFrame })
+ *   host.pointer · host.view · host.players
+ *   host.width · host.height · host.dpr · host.dt · host.clock()
+ *   host.handle(opts) · host.router(handles, opts)
+ *   host.cameraHelm(cam, opts) · host.poseHelm(opts)
+ *   host.poseTrack(opts) · host.cameraTrack(cam, opts)
+ *   host.tick(dt)      // external-loop mode
+ *   host.dispose()
+ *
+ * Two loop modes. With { onFrame } the host runs requestAnimationFrame
+ * (overridable through { raf, caf }): each frame computes dt (clamped to
+ * 50 ms), ticks the players, calls onFrame(dt, host), then flushes the
+ * pointer source. Without it the application, or the p5 adapter from
+ * predraw, calls host.tick(dt) = players.tick(dt) and host.pointer.flush()
+ * once its consumers ran. Nothing else in the host cares who owns the loop.
+ *
+ * The frame order inside onFrame: install the camera (which fills
+ * host.view), update handles or routers, fall through to the orbit when
+ * nothing grabbed, draw.
+ */
+
+
+const _now = () => (typeof performance !== 'undefined' && performance.now) ? performance.now() : Date.now();
+
+/**
+ * Create the host context of a canvas.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {{ ndcZMin?:number, onFrame?:function(number, object):void, raf?:function,
+ *           caf?:function, onSize?:function(number, number, number):void }} [opts]
+ *        ndcZMin: the GPU API's NDC-z convention, WEBGL (default) or WEBGPU —
+ *        written once, never detected. onFrame: the host's own loop; absent,
+ *        external-tick mode. onSize(width, height, dpr): the bridge's chance
+ *        to resize its drawing buffer.
+ * @returns {object} The host.
+ */
+function createHost(canvas, opts) {
+  const o = opts || {};
+  const t0 = _now();
+  const constructs = new Set();
+  let loop = null, observer = null;
+  const host = {
+    canvas,
+    width: 0, height: 0, dpr: 1,
+    dt: 0,
+    view: null, pointer: null, players: null,
+
+    /** Seconds since the host was created. */
+    clock() { return (_now() - t0) / 1000; },
+
+    /**
+     * External-loop mode: tick the players with dt (seconds). The caller
+     * flushes the pointer source once its consumers ran.
+     * @param {number} dt
+     */
+    tick(dt) { host.dt = dt; host.players.tick(dt); },
+
+    /**
+     * A draggable handle on this canvas — see host/handle. Returns null on
+     * an invalid `constraint`.
+     * @param {object} opts
+     * @returns {Handle|null}
+     */
+    handle(opts) {
+      const o = opts || {};
+      if (!validConstraint(o.constraint)) {
+        console.error('[host] handle: `constraint` must be SPHERE, PLANE, AXIS, DIAL, VIEW, or a contract-conforming constraint object; got ' + String(o.constraint) + '.');
+        return null;
+      }
+      return host.register(new Handle(host, o));
+    },
+
+    /**
+     * A shared pick over overlapping handles — see host/router.
+     * @param {Handle[]} handles
+     * @param {{ hover?:boolean }} [opts]
+     * @returns {PointerRouter}
+     */
+    router(handles, opts) { return host.register(new PointerRouter(host, handles, opts)); },
+
+    /** Fly a camera state body-relative from a 6-DOF rate stream — see host/helm. */
+    cameraHelm(cam, opts) { return cameraHelm(host, cam, opts); },
+    /** Integrate a 6-DOF rate stream into a pose in a declared frame — see host/helm. */
+    poseHelm(opts) { return poseHelm(host, opts); },
+    /** A core PoseTrack ticked while it plays — see host/track. */
+    poseTrack(opts) { return poseTrack(host, opts); },
+    /** A core CameraTrack evaluating into a camera state while it plays — see host/track. */
+    cameraTrack(cam, opts) { return cameraTrack(host, cam, opts); },
+
+    /** Register a construct with dispose() so host.dispose() releases it. */
+    register(c) { if (c) constructs.add(c); return c; },
+    /** Unregister a construct. */
+    unregister(c) { constructs.delete(c); },
+
+    /** Stop the loop, disconnect the observer, remove every listener, dispose every construct. */
+    dispose() {
+      if (loop) loop.stop();
+      for (const c of [...constructs]) { if (typeof c.dispose === 'function') c.dispose(); }
+      constructs.clear();
+      observer.dispose();
+      host.pointer.dispose();
+      host.players.clear();
+    },
+  };
+
+  host.view = createView({ ndcZMin: o.ndcZMin });
+  host.players = createPlayers();
+  host.pointer = createPointer(canvas, host.view);
+  observer = observeCanvas(canvas, (w, h, dpr) => {
+    host.width = w; host.height = h; host.dpr = dpr;
+    host.view.resize(w, h);
+    if (typeof o.onSize === 'function') o.onSize(w, h, dpr);
+  });
+
+  if (typeof o.onFrame === 'function') {
+    loop = createLoop({
+      raf: o.raf, caf: o.caf,
+      onFrame: (dt) => {
+        host.dt = dt;
+        host.players.tick(dt);
+        o.onFrame(dt, host);
+        host.pointer.flush();
+      },
+    });
+    loop.start();
+  }
+  return host;
+}
+
+export { Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createHost, createLoop, createPlayers, createPointer, createView, helmBasis, isConstraint, measureCanvas, observeCanvas, poseHelm, poseTrack, validConstraint };
+//# sourceMappingURL=index.js.map