@nakednous/tree 0.0.24 → 0.0.25

package/README.md

@@ -376,19 +376,19 @@ Three-state result: `VISIBLE` (fully inside), `SEMIVISIBLE` (intersecting), `INV
 `handle.js` is the renderer-agnostic core of an interactive manipulator: ray-primitive intersections, az/el utilities, and a `Constraint` state machine. The `p5.tree` bridge wraps these into a draggable handle; this package supplies the math and the **contract** that makes the handle extensible.
 
 ```js
-import { createConstraint, SPHERE, PLANE, AXIS, POINT, DIRECTION,
+import { createConstraint, SPHERE, PLANE, AXIS, DIAL, POINT, DIRECTION,
          raySphere, rayPlane, rayClosestPointOnAxis,
          dirFromAzEl, azElFromDir } from '@nakednous/tree'
 
-const c = createConstraint(SPHERE, { radius: 1 })  // or PLANE / AXIS
+const c = createConstraint(SPHERE, { radius: 1 })  // or PLANE / AXIS / DIAL
 const out = [0, 0, 0]
 c.solve(ox,oy,oz, dx,dy,dz)   // ray (working space) → canonical state; chainable
 c.value(out, DIRECTION)       // write the reported value into out(3)
 ```
 
-`SPHERE` stores a unit direction (gimbal-free); `PLANE` / `AXIS` store a constrained point. `value` reports a `DIRECTION` (unit) or a `POINT` per kind. Ray primitives are out-first and assume a unit ray direction; `rayPlane` returns `Infinity` when the ray is parallel.
+`SPHERE` stores a unit direction (gimbal-free); `PLANE` / `AXIS` store a constrained point; `DIAL` stores an accumulated angle θ (multi-turn winding preserved). `value` reports a `DIRECTION` (unit) or a `POINT` per kind. `aim(ax,ay,az[, zx,zy,zz])` re-aims the constraint basis in the working space — `PLANE` takes a new normal (point re-projected), `AXIS` a new direction (`t` preserved), `DIAL` a new plane normal plus optional θ=0 reference (θ preserved) — the seam the `p5.tree` bridge's deferred `from` frame drives. Ray primitives are out-first and assume a unit ray direction; `rayPlane` returns `Infinity` when the ray is parallel.
 
-**Constraint contract (extension seam).** A constraint is any object exposing `kind`, `solve(ox,oy,oz, dx,dy,dz)`, `value(out, report)`, `seed(x,y,z)`, and optionally `scalar()` / `azEl(out2)`. The handle controller drives any conforming constraint, so a new kind — rotation, 6-DOF, or app-specific — implements this contract (portable, draw-free) plus a bridge-side locus draw, rather than forking the controller. The built-in `Constraint` is the reference implementation. Full design: [`handle-design.md`](./handle-design.md).
+**Constraint contract (extension seam).** A constraint is any object exposing `kind`, `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 handle controller drives any conforming constraint, so a new kind — rotation, 6-DOF, or app-specific — implements this contract (portable, draw-free) plus a bridge-side locus draw, rather than forking the controller. The built-in `Constraint` is the reference implementation. Full design: [`handle-design.md`](./handle-design.md).
 
 ---
 
@@ -463,7 +463,7 @@ WEBGPU  //  0  (z ∈ [0, 1])
 INVISIBLE, VISIBLE, SEMIVISIBLE
 
 // Manipulator constraint kinds & report modes
-SPHERE, PLANE, AXIS
+SPHERE, PLANE, AXIS, DIAL
 POINT, DIRECTION
 
 // Basis vectors (frozen)

package/dist/index.js

@@ -2506,7 +2506,9 @@ class CameraTrack extends Track {
  * ── 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)`. The p5.tree handle controller drives
+ * optionally `scalar()` / `azEl(out2)` / `aim(ax,ay,az[, zx,zy,zz])` — the
+ * basis re-aim seam the bridge's deferred `from` frame drives (§4.13).
+ * The p5.tree handle controller drives
  * any conforming constraint (lifecycle, frame conversion, bind, hooks, pick);
  * a new kind — 6-DOF, or app-specific — implements this contract here
  * (portable, draw-free) plus a bridge-side locus/pick draw (`drawLocus` /
@@ -2735,22 +2737,7 @@ class Constraint {
     this.r1 = [0, 0, 1];
     if (kind === DIAL) {
       const z = _vec3(opts.zero);
-      if (z) {
-        // Project the supplied reference onto the dial plane.
-        const d = z[0]*this.u[0] + z[1]*this.u[1] + z[2]*this.u[2];
-        this.r0[0] = z[0] - d*this.u[0];
-        this.r0[1] = z[1] - d*this.u[1];
-        this.r0[2] = z[2] - d*this.u[2];
-        const l = Math.sqrt(this.r0[0]**2 + this.r0[1]**2 + this.r0[2]**2);
-        if (l < EPS) _basis(this.u, this.r0, this.r1);
-        else { this.r0[0]/=l; this.r0[1]/=l; this.r0[2]/=l; }
-      } else {
-        _basis(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];
+      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
@@ -2789,6 +2776,28 @@ class Constraint {
     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(this.u, this.r0, this.r1);
+      else { this.r0[0]/=l; this.r0[1]/=l; this.r0[2]/=l; }
+    } else {
+      _basis(this.u, this.r0, this.r1);
+    }
+    // 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.
@@ -2959,6 +2968,46 @@ class Constraint {
     }
     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(this.n, px, py, pz);
+      this.seed(this.pt[0], this.pt[1], this.pt[2]);
+    } else if (this.kind === AXIS) {
+      const px = this.u[0], py = this.u[1], pz = this.u[2];
+      this.u[0] = ax; this.u[1] = ay; this.u[2] = az;
+      _unit(this.u, px, py, pz);
+      this.pt[0] = this.anchor[0] + this.s*this.u[0];
+      this.pt[1] = this.anchor[1] + this.s*this.u[1];
+      this.pt[2] = this.anchor[2] + this.s*this.u[2];
+    } else if (this.kind === DIAL) {
+      const px = this.u[0], py = this.u[1], pz = this.u[2];
+      this.u[0] = ax; this.u[1] = ay; this.u[2] = az;
+      _unit(this.u, px, py, pz);
+      this._dialBasis(zx, zy, zz);
+      this._dialPoint();
+    }
+    return this;
+  }
 }
 
 /**