@nakednous/host 0.0.10 → 0.0.12

package/README.md

@@ -70,7 +70,7 @@ dependency first and an options object last, and registers with the context so
 
 | member | what it is |
 |---|---|
-| `createHost(canvas, opts)` | the context: `ndcZMin` (WEBGL default, or WEBGPU), `onFrame(dt, host)` for the host's own loop, `onSize(w, h, dpr)` for the bridge's buffer, `raf` / `caf` overrides |
+| `createHost(canvas, opts)` | the context: `ndcZMin` (WEBGL default, or WEBGPU), `onFrame(dt, host)` for the host's own loop, `afterFrame(dt, host)` after the pointer flush — the frame's last draw, a pointer handler's included, where a WebGPU bridge submits its command encoder — `onSize(w, h, dpr)` for the bridge's buffer, `raf` / `caf` overrides |
 | `host.view` | the view bag — `mat4Proj` · `mat4View` · `mat4PV` · `mat4PVInv` · `mat4Eye`, `vp`, `ndcZMin`, `stale`; `set(P, V)`, `setCamera(cam)`, `resize(w, h)` |
 | `host.pointer` | the pointer source — presses queued per frame, per-pointer entries with a move counter, claims that capture on the canvas, Esc cancel, `flush()` |
 | `host.players` | the registry ticked each frame — `{ tick(dt) → boolean }`, removed on `false` |
@@ -116,6 +116,10 @@ one wrote:
 5. **draw** — the bridge reads the camera state, the handles' values, the tracks' paths.
 6. **labels tick** — world anchors projected through the current bag, transforms written.
 7. **pointer flush** — the press queue empties, released pointers leave.
+8. **the post-frame hook** — `afterFrame(dt, host)`, when it was given: the frame's last draw,
+   a pointer handler's included, so a WebGPU bridge submits its command encoder there. It is
+   the host's loop's step and nothing in external tick — there the caller writes the frame's
+   end — and `host.dispose()` clears it.
 
 `dt` is seconds, clamped to 50 ms so a stalled tab never integrates a leap.
 
@@ -126,6 +130,7 @@ one wrote:
 | seam | direction | contract |
 |---|---|---|
 | view bag | bridge → host | the bridge's `setCamera(cam)` also calls `host.view.setCamera(cam)`; without a host the bridge keeps its own matrices |
+| frame end | host → bridge | `afterFrame(dt, host)` runs after `pointer.flush()`; a WebGPU bridge submits its command encoder there, and without the hook the application calls the bridge's `endFrame` itself |
 | external tick | adapter → host | `host.tick(dt)` from the adapter's predraw; `host.labels.tick()` after the adapter set `host.view` from renderer state |
 | proxies · locus | tree → host → bridge | constraint objects carry `proxy` and `locus`; the host tests, the bridge draws |
 | label anchors | tree → bridge → host | a generator writes `out.labels`; the bridge forwards each to `labels.set` |

package/dist/index.js

@@ -760,7 +760,7 @@ class Handle {
       c.s = this._savedS;
       c._dialPoint();
     } else {
-      c.seed(this._saved[0], this._saved[1], this._saved[2]);
+      c.seed(this._saved[0], this._saved[1], this._saved[2], POINT);
     }
     if (this._binder) this._binder.set(this.value(this._bindVal));
     this._grabbed = false;
@@ -854,7 +854,7 @@ class Handle {
       _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 c.seed(_v3[0], _v3[1], _v3[2], POINT);
     } else if (c.kind === AXIS || c.kind === DIAL) {
       const step = Array.isArray(sn) ? sn[0] : sn;
       if (!(step > 0)) return;
@@ -901,6 +901,11 @@ class Handle {
    * 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.
+   *
+   * The array lives in the handle's `report` space, both ways: a SPHERE handle
+   * (DIRECTION by default) binds and receives a **unit heading**, not a point on
+   * its sphere; a PLANE / AXIS handle binds and receives a world point. Construct
+   * the handle with `report: POINT` to bind a point to a sphere instead.
    * @param {number[]|{ get:Function, set:Function }} target
    * @returns {Handle} this
    */
@@ -920,7 +925,9 @@ class Handle {
     return this;
   }
 
-  /** Re-seed the constraint from the bound target after it changed externally. Chainable. */
+  /** Re-seed the constraint from the bound target after it changed externally —
+   *  the target holds the handle's own `report` space, as the write-back does, so
+   *  seed → solve → write never changes what the array means. Chainable. */
   sync() {
     if (this._binder) this._seedFromBinding();
     return this;
@@ -931,7 +938,7 @@ class Handle {
     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);
+    else this._constraint.seed(x, y, z, this._constraint.report);
   }
 
   // Push the freshly solved value to the binding and fire onChange, once per solve.
@@ -982,7 +989,7 @@ class Handle {
         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]);
+      } else if (c.kind === PLANE) c.seed(c.pt[0], c.pt[1], c.pt[2], POINT);
     }
     return this;
   }
@@ -3091,10 +3098,14 @@ function decodeRGBE(bytes, opts) {
  *
  * 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.
+ * 50 ms), ticks the players, calls onFrame(dt, host), flushes the pointer
+ * source, then calls afterFrame(dt, host) when one was given — the frame's
+ * last draw, a pointer handler's included, which is where a WebGPU bridge
+ * submits its command encoder. 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: external tick gains no
+ * frame end, so afterFrame belongs to the host's own loop. 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
@@ -3108,12 +3119,18 @@ const _now = () => (typeof performance !== 'undefined' && performance.now) ? per
  * Create the host context of a canvas.
  *
  * @param {HTMLCanvasElement} canvas
- * @param {{ ndcZMin?:number, onFrame?:function(number, object):void, raf?:function,
+ * @param {{ ndcZMin?:number, onFrame?:function(number, object):void,
+ *           afterFrame?: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.
+ *        external-tick mode. afterFrame: called after the pointer source
+ *        flushes, so the frame's last draw — a pointer handler's included —
+ *        is behind it; the submit seam of a WebGPU bridge, which ends its
+ *        command encoder there. The host's loop only: an external tick has
+ *        no frame end but the one its caller writes. dispose() clears it.
+ *        onSize(width, height, dpr): the bridge's chance to resize its
+ *        drawing buffer.
  * @returns {object} The host.
  */
 function createHost(canvas, opts) {
@@ -3121,6 +3138,7 @@ function createHost(canvas, opts) {
   const t0 = _now();
   const constructs = new Set();
   let loop = null, observer = null, labels = null;
+  let afterFrame = typeof o.afterFrame === 'function' ? o.afterFrame : null;
   const host = {
     canvas,
     width: 0, height: 0, dpr: 1,
@@ -3202,6 +3220,7 @@ function createHost(canvas, opts) {
 
     /** Stop the loop, disconnect the observer, remove every listener, dispose every construct. */
     dispose() {
+      afterFrame = null;
       if (loop) loop.stop();
       for (const c of [...constructs]) { if (typeof c.dispose === 'function') c.dispose(); }
       constructs.clear();
@@ -3230,6 +3249,7 @@ function createHost(canvas, opts) {
         host.players.tick(dt);
         o.onFrame(dt, host);
         host.pointer.flush();
+        if (afterFrame !== null) afterFrame(dt, host);
       },
     });
     loop.start();