@nakednous/host 0.0.6 → 0.0.9

package/README.md

@@ -79,7 +79,7 @@ dependency first and an options object last, and registers with the context so
 | `host.handle(opts)` | `Handle` — a draggable core constraint (`SPHERE` · `PLANE` · `AXIS` · `DIAL` · `VIEW`, or a contract object); `update()`, `value(out, opts)`, snap, hover, cancel, `from` |
 | `host.router(handles, opts)` | `PointerRouter` — one shared pick over overlapping handles, nearest proxy wins; shared hover |
 | `host.cameraHelm(cam, opts)` · `host.poseHelm(opts)` | a core `PoseHelm` on the players: body-fly a camera state, or integrate into a pose in `WORLD` · `EYE` · `SELF` · a mat4 and `bind()` a target |
-| `host.poseTrack(opts)` · `host.cameraTrack(cam, opts)` | core tracks ticked while they play; `{ handles }` builds `TrackHandles`, one handle per keyframe |
+| `host.poseTrack(opts)` · `host.cameraTrack(cam, opts)` | core tracks ticked while they play; `{ handles }` builds `TrackHandles`, one handle per keyframe. `add(depth)` — the transport panel's `+` — authors where the camera is looking: a pose track places the pose at the centre of the installed camera's frustum, `depth` `0`…`1` from the near plane to the far one, aimed along that camera (the view bag's matrices; never deduplicated), a camera track captures its camera state, a placement depth being nothing a camera keyframe could use. `remove()` — the transport panel's `−` — retracts the last keyframe, one per call; `remove(i)` is the core track's own |
 | `host.hid(opts)` · `host.gamepad(opts)` | rate streams — `lin[3]` / `ang[3]` in raw device units, `bind(helm)` feeds it each tick; `available`, `connected` |
 | `host.image(url)` · `host.video(opts)` · `host.raster(draw, w, h)` | texture sources — an `ImageBitmap`, a hidden `<video>` from a file or the camera with a `ready` promise, a Canvas2D drawing |
 | `host.mesh(url, opts)` | one mesh — the arrays shape `{ position, indices, normal?, tangent?, texcoord?, color?, joints?, weights? }` with its `bounds` `{ min, max, center, diag }` beside them — from an OBJ file, a one-part glTF 2.0 file (`.glb`, `.gltf`), or any format through `{ parse: (arrayBuffer) => arrays }`; what a bridge's buffer upload takes as it is, and `size / mesh.bounds.diag` fits any file to `size`. A file of several parts rejects, naming `model`. `{ format }` when the URL does not say. **`normals`**: left out, the file's normals are kept and a mesh without any gets smooth ones; `'smooth'` always recomputes them, summed per position, so a faceted file or a texture seam smooths too; `'flat'` always recomputes them on the flattened mesh (every triangle owning its vertices: more vertices, indices counting up); `false` computes nothing. The procedure, its limits and sources are tree's `mesh` module's; glTF viewers compute flat normals for a file without any — here that is `'flat'` |

package/dist/index.js

@@ -1,4 +1,4 @@
-import { WEBGL, cameraView, cameraProj, mat4Mul, mat4Invert, PLANE, createConstraint, WORLD, AXIS, DIAL, POINT, mapDirection, pixelRatio, rayHitSphere, unproject, SPHERE, dirFromAzEl, DIRECTION, mapLocation, MATRIX, PoseHelm, cameraToPose, EYE, SELF, qToMat4, cameraEye, cameraFromPose, CameraTrack, PoseTrack, qFromAxisAngle, mat4ToTransform, meshBounds, meshFlatten, meshNormals, meshGroups, SCREEN, cameraCopy, createCamera, coastAlive, coastStep, cameraOrbit, cameraPan, cameraDolly } from '@nakednous/tree';
+import { WEBGL, cameraView, cameraProj, mat4Mul, mat4Invert, PLANE, createConstraint, WORLD, AXIS, DIAL, POINT, mapDirection, pixelRatio, rayHitSphere, unproject, SPHERE, dirFromAzEl, DIRECTION, mapLocation, MATRIX, PoseHelm, cameraToPose, EYE, SELF, qToMat4, cameraEye, cameraFromPose, CameraTrack, PoseTrack, qFromAxisAngle, NDC, mat4ToTransform, meshBounds, meshFlatten, meshNormals, meshGroups, SCREEN, cameraCopy, createCamera, coastAlive, coastStep, cameraOrbit, cameraPan, cameraDolly } from '@nakednous/tree';
 
 /**
  * @file The view bag — the matrices every pick, solve, label and orbit reads.
@@ -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,17 +1295,81 @@ 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
  * keyframe about a declared axis, all on one router.
+ *
+ * add(depth) — the transport panel's + button, which passes its depth slider
+ * (ui's contract) — authors a keyframe where the camera is looking: on a pose
+ * track the pose lands at the centre of the installed camera's frustum at
+ * that depth, aimed along the camera's own eye frame; on a camera track the
+ * camera state is captured, the depth having nothing to place. A panel whose
+ * depth row is hidden passes no depth, which reads the panel's default, 0.5.
+ * The frame is the host's view bag — the matrices the last setCamera
+ * installed — so the placement is the same on every bridge and needs no
+ * renderer here. remove() is the panel's −: no argument retracts the last
+ * keyframe, one per call, an index staying the core track's own remove.
  */
 
 
+// ── Placement — the + button's depth ───────────────────────────────────────
+//
+// The transport panel hands add() a depth in [0, 1] and expects a keyframe in
+// front of the camera. Writer-free placement: unproject the frustum's centre
+// through the view bag's P · V inverse and aim the pose along the bag's eye
+// frame (E = V⁻¹, its columns right / up / back). The depth is NDC-linear, as
+// the p5 transport's was — 0 the near plane's centre, 1 the far plane's — so
+// every bridge's own ndcZMin maps it without the caller knowing the API.
+
+const _at  = [0, 0, 0];   // the unprojected frustum centre
+const _dir = [0, 0, 0];   // the camera's forward
+const _up  = [0, 0, 0];   // the camera's up
+
+/**
+ * Append a pose at the centre of the installed camera's frustum, `depth` of
+ * the way from the near plane to the far one.
+ *
+ * @param {object} host
+ * @param {function} add    The track's core add, already bound.
+ * @param {number} [depth]  NDC-linear depth in [0, 1]; clamped, absent or NaN
+ *                          reads the panel's own default, 0.5.
+ * @returns {boolean} false when no camera is installed (a stale view bag).
+ */
+function _addInFront(host, add, depth) {
+  const view = host.view;
+  if (!view || view.stale) return false;
+  const d    = Number.isFinite(depth) ? (depth < 0 ? 0 : depth > 1 ? 1 : depth) : 0.5;
+  const ndcZ = view.ndcZMin + d * (1 - view.ndcZMin);
+  mapLocation(_at, 0, 0, ndcZ, NDC, WORLD, view, view.vp, view.ndcZMin);
+  const e = view.mat4Eye;                        // columns: right · up · back · eye
+  _dir[0] = -e[8];  _dir[1] = -e[9];  _dir[2] = -e[10];
+  _up[0]  =  e[4];  _up[1]  =  e[5];  _up[2]  =  e[6];
+  add({ pos: [_at[0], _at[1], _at[2]], rot: { dir: _dir, up: _up } }, { deduplicate: false });
+  return true;
+}
+
 // ── Players ────────────────────────────────────────────────────────────────
 
+// remove(): the panel's −, retracting the last authored keyframe — one per
+// click, either kind of track. An index stays the core track's own remove, so
+// a caller editing by index is unaffected; an empty track removes nothing.
+function _wireRemove(track) {
+  const coreRemove = track.remove.bind(track);
+  track.remove = function (index) {
+    return coreRemove(index == null ? track.keyframes.length - 1 : index);
+  };
+  return track;
+}
+
 function _wirePoseTrack(host, track) {
   let player = null;
   track._onActivate = () => {
@@ -1324,12 +1389,36 @@ function poseTrack(host, opts) {
   const o = opts || {};
   const track = new PoseTrack();
   _wirePoseTrack(host, track);
+
+  // add(depth): the transport's + (see the module header). A spec, or an array
+  // of specs, is the core track's own; no argument — the panel with its depth
+  // row hidden — places at the panel's default depth, 0.5.
+  const coreAdd = track.add.bind(track);
+  let warned = false;
+  track.add = function (spec, addOpts) {
+    if (spec != null && typeof spec !== 'number') return coreAdd(spec, addOpts);
+    if (!_addInFront(host, coreAdd, spec) && !warned) {
+      warned = true;
+      console.warn('[host] poseTrack: add(depth) places a pose against the installed camera, and the view bag is stale — no keyframe added. Call the bridge\'s setCamera first.');
+    }
+  };
+
   if (o.handles) track.handles = new TrackHandles(host, track, o.handles, false);
-  return track;
+  return _wireRemove(track);
 }
 
 /**
- * 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]
@@ -1344,7 +1433,9 @@ function cameraTrack(host, cam, opts) {
 
   const coreAdd = track.add.bind(track);
   track.add = function (spec, addOpts) {
-    if (spec == null) {
+    // No spec, or the transport panel's depth: a camera keyframe *is* the
+    // camera, so there is nothing a placement depth could move — capture.
+    if (spec == null || typeof spec === 'number') {
       if (!state) return;
       spec = state;
     } else if (Array.isArray(spec)) {
@@ -1373,7 +1464,7 @@ function cameraTrack(host, cam, opts) {
   track._onDeactivate = () => { host.players.remove(player); apply(); };
 
   if (o.handles) track.handles = new TrackHandles(host, track, o.handles, true);
-  return track;
+  return _wireRemove(track);
 }
 
 // ── TrackHandles ───────────────────────────────────────────────────────────
@@ -2417,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.
  */
@@ -2610,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
@@ -2725,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) {