@nakednous/host 0.0.8 → 0.0.9

package/dist/index.js

@@ -186,10 +186,11 @@ function observeCanvas(canvas, onChange) {
  *
  * - 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.
+ * - Coordinates in screen space — the surface's logical pixels, top-left, y
+ *   down — through the element's bounding rectangle: (clientX − rect.left) ·
+ *   (width / rect.width), the logical size read off the view bag's vp. These
+ *   are the numbers mapLocation(SCREEN) and vp expect (a viewport of negative
+ *   height), 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
@@ -787,7 +788,7 @@ class Handle {
   }
 
   // The proxy's world position and its grab radius in world units — a
-  // constant grabPx screen size at the proxy's depth.
+  // constant grabPx canvas size at the proxy's depth.
   _proxyPrep() {
     const c = this._constraint, v = this._view, p = this._proxyPos;
     if (this._from && !this._grabbed) this._resolveFrame();
@@ -810,14 +811,14 @@ class Handle {
     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. */
+  /** Unproject a screen-space 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. */
+  /** Hit-test the proxy at a screen-space pixel. */
   _pickAt(x, y) {
     return this._ray(x, y) && this._proxyT(_rayO, _rayD) < Infinity;
   }
@@ -1207,7 +1208,7 @@ 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.');
+    console.error('[host] cameraHelm: a camera helm is always body-fly and has no `from`. Ignoring it; bind the camera to a poseHelm for view- or world-relative motion.');
   }
   if (_isCameraState(cam)) helm.home(cameraToPose(_pose, cam));
   const player = {
@@ -1294,8 +1295,14 @@ function poseHelm(host, opts) {
  * 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
+ * keyframe shape, so track.eval(cam) is the write — while the track plays, and
+ * once more on deactivate so the camera rests on the path. That bound is the
+ * point: a stopped track's camera belongs to whoever else drives it — the
+ * reader's orbit, the figure's own camera code — so a consumer that renders
+ * from the state derives it instead, one evaluation per frame after the tick
+ * that advances the transport, which carries a seek, a dragged keyframe and a
+ * capture into the state as well and repeats the player's write harmlessly
+ * while the track plays. 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
@@ -1401,7 +1408,17 @@ function poseTrack(host, opts) {
 }
 
 /**
- * A core CameraTrack evaluating into the camera state `cam` while it plays.
+ * A core CameraTrack evaluating into the camera state `cam` while it plays, and
+ * once when it stops, so the camera rests on the path.
+ *
+ * The write is bounded by playback on purpose: while a track is stopped the
+ * camera it names belongs to whoever else drives it — the reader's orbit, the
+ * figure's own camera code — and a factory writing every frame would fight
+ * them. A consumer that renders *from* the state therefore derives it: evaluate
+ * the track once per frame, after the tick that advances the transport. A seek,
+ * a dragged keyframe and a capture reach the state that way too, and the
+ * evaluation repeats the player's own write harmlessly while the track plays.
+ *
  * @param {object} host
  * @param {object} cam   A camera state ({ eye, center, up, fov, halfHeight, near, far }).
  * @param {{ handles?:boolean|object }} [opts]
@@ -2491,7 +2508,7 @@ function raster(draw, w, h, opts) {
  * class — a CSS class beside the layer's own 'host-label', frame — a
  * transient label that lives for the frame it was set in: a gizmo re-sets
  * it every draw and tick() removes it once a frame passes without. A label
- * whose screen depth leaves [0, 1] or whose anchor leaves the canvas is
+ * whose window depth leaves [0, 1] or whose anchor leaves the canvas is
  * hidden, not clamped. Elements are reused by id; tick() writes transforms
  * only, text when the string changed.
  */
@@ -2684,7 +2701,7 @@ function createLabels(host, opts) {
  * what is still draining, so do home() and enabled = false. The default is
  * 0.2 s; 0 makes the orbit exact.
  *
- * Screen y runs down; which world direction that is depends on the
+ * Canvas y runs down; which world direction that is depends on the
  * projection installed in the view bag: a y-up projection (GL's, tree's
  * default) maps a downward drag to the eye's −up, a y-flipped one (p5's,
  * mat4Proj[5] < 0) to +up. The orbit reads that sign off the bag each
@@ -2799,7 +2816,7 @@ function createOrbit(host, cam, opts) {
       let moved = false;
       let az = 0, el = 0, px = 0, py = 0, ld = 0;   // this frame's step
       const view = host.view;
-      const ys = view.mat4Proj[5] < 0 ? -1 : 1;   // screen-down is the eye's −up under a y-up projection, +up under p5's flip
+      const ys = view.mat4Proj[5] < 0 ? -1 : 1;   // canvas-down is the eye's −up under a y-up projection, +up under p5's flip
       if (a !== null && b === null) {
         const t = tracked.get(a.id);
         if (t) {