@nakednous/host 0.0.11 → 0.0.13

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

@@ -3098,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
@@ -3115,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) {
@@ -3128,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,
@@ -3209,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();
@@ -3237,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();