@nakednous/host 0.0.2 → 0.0.3

package/dist/index.js

@@ -2043,7 +2043,7 @@ const DIAL_EDGE = 0.08;
 // =========================================================================
 
 const _isNum = (x) => typeof x === 'number' && Number.isFinite(x);
-const _clamp = (x, lo, hi) => x < lo ? lo : (x > hi ? hi : x);
+const _clamp$1 = (x, lo, hi) => x < lo ? lo : (x > hi ? hi : x);
 const _num   = (x, d) => _isNum(x) ? x : d;
 
 /** Wrap an angle to (−π, π]. */
@@ -2312,7 +2312,7 @@ function dirFromAzEl(out, az, el) {
  */
 function azElFromDir(out2, dx, dy, dz) {
   out2[0] = Math.atan2(dz, dx);                 // az
-  out2[1] = Math.asin(_clamp(dy, -1, 1));       // el
+  out2[1] = Math.asin(_clamp$1(dy, -1, 1));       // el
   return out2;
 }
 
@@ -2455,7 +2455,7 @@ class Constraint {
       let s = rayClosestPointOnAxis(this.pt, ox,oy,oz, dx,dy,dz,
                                     this.anchor[0], this.anchor[1], this.anchor[2],
                                     this.u[0], this.u[1], this.u[2]);
-      s = _clamp(s, this.min, this.max);
+      s = _clamp$1(s, this.min, this.max);
       this.s = s;
       this.pt[0] = this.anchor[0] + s*this.u[0];   // clamped point
       this.pt[1] = this.anchor[1] + s*this.u[1];
@@ -2496,7 +2496,7 @@ class Constraint {
                                        wx, wy, wz);
       dth = sl / (this._radius || 1);
     }
-    this.s = _clamp(this.s + dth, this.min, this.max);
+    this.s = _clamp$1(this.s + dth, this.min, this.max);
     this._dialPoint();
   }
 
@@ -2580,7 +2580,7 @@ class Constraint {
       this.pt[0]=x-d*this.n[0]; this.pt[1]=y-d*this.n[1]; this.pt[2]=z-d*this.n[2];
     } else if (this.kind === AXIS) {
       const wx=x-this.anchor[0], wy=y-this.anchor[1], wz=z-this.anchor[2];
-      const s = _clamp(wx*this.u[0] + wy*this.u[1] + wz*this.u[2], this.min, this.max);
+      const s = _clamp$1(wx*this.u[0] + wy*this.u[1] + wz*this.u[2], this.min, this.max);
       this.s = s;
       this.pt[0]=this.anchor[0]+s*this.u[0];
       this.pt[1]=this.anchor[1]+s*this.u[1];
@@ -2592,7 +2592,7 @@ class Constraint {
       if (px*px + py*py >= EPS*EPS) {
         const a = Math.atan2(py, px);
         // Nearest winding to the current θ preserves accumulated turns.
-        this.s = _clamp(a + TWO_PI$1 * Math.round((this.s - a) / TWO_PI$1),
+        this.s = _clamp$1(a + TWO_PI$1 * Math.round((this.s - a) / TWO_PI$1),
                         this.min, this.max);
       }
       this._dialPoint();
@@ -3002,8 +3002,53 @@ class PoseHelm {
     return this;
   }
 }
+
+/**
+ * @file Camera state ↔ matrices: builders, decomposers, and in-place edits.
+ * @module tree/camera
+ * @license AGPL-3.0-only
+ *
+ * The camera is plain data — the CameraTrack keyframe shape:
+ *
+ *   cam = {
+ *     eye:        [x, y, z],       // position
+ *     center:     [x, y, z],       // lookat target; |center − eye| is the gaze distance
+ *     up:         [x, y, z],       // up hint, need not be unit
+ *     fov:        number | null,   // vertical field of view, radians — perspective
+ *     halfHeight: number | null,   // world-unit half-height at the near plane — orthographic
+ *     near:       number,          // > 0
+ *     far:        number,          // > near
+ *   }
+ *
+ * Exactly one of fov / halfHeight is meaningful; fov wins when both are set.
+ * With both null the lens is "unchanged": cameraProj and cameraPlanes return
+ * null and leave their output untouched, so a track that evaluates null into
+ * the state keeps the last projection installed. A track writes the state
+ * directly — `track.eval(cam)` — and a pose drives it through cameraFromPose.
+ *
+ * The state carries no aspect ratio — the viewport owns it — so one state is
+ * portable between targets of different sizes; every builder that needs it
+ * takes it as an argument.
+ *
+ * Vectors are plain number[] (f64, authoring state); matrices are written into
+ * whatever 16-element buffer the caller passes. createCamera is the one
+ * allocating call; everything else is out-first (or in-place) and zero-alloc.
+ *
+ * Every function that needs the camera frame derives it through mat4Eye, so
+ * planes and edits agree with cameraEye / cameraView exactly — including the
+ * up re-seed when the view direction is parallel to the up hint.
+ */
+
+
+const _E$1 = new Float64Array(16);   // eye→world frame scratch: right 0–2, up 4–6, back 8–10
 const _d = [0, 0, 0];              // view-direction scratch
 
+/** Eye→world frame of `cam` into `_E`. */
+function _frame(cam) {
+  const e = cam.eye, c = cam.center, u = cam.up;
+  mat4Eye(_E$1, e[0],e[1],e[2], c[0],c[1],c[2], u[0],u[1],u[2]);
+}
+
 /** Gaze distance |center − eye|, or 1 when the state is degenerate. */
 function _gaze(cam) {
   const dx = cam.center[0]-cam.eye[0], dy = cam.center[1]-cam.eye[1], dz = cam.center[2]-cam.eye[2];
@@ -3011,6 +3056,52 @@ function _gaze(cam) {
   return d > 0 ? d : 1;
 }
 
+function _vec3(v, x, y, z) { return v != null ? [v[0], v[1], v[2]] : [x, y, z]; }
+
+// =========================================================================
+// State
+// =========================================================================
+
+/**
+ * Allocate a camera state — the one allocating call, setup-time.
+ * Defaults: eye [0, 0, 500], center [0, 0, 0], up [0, 1, 0], fov π/3,
+ * halfHeight null, near 0.1, far 1000. Passing halfHeight without fov yields
+ * an orthographic state (fov null).
+ *
+ * @param {{ eye?:number[], center?:number[], up?:number[], fov?:number|null,
+ *           halfHeight?:number|null, near?:number, far?:number }} [opts]
+ * @returns {{ eye:number[], center:number[], up:number[], fov:number|null,
+ *             halfHeight:number|null, near:number, far:number }}
+ */
+function createCamera(opts) {
+  const o = {};
+  const ortho = o.halfHeight != null && o.fov === undefined;
+  return {
+    eye:        _vec3(o.eye,    0, 0, 500),
+    center:     _vec3(o.center, 0, 0, 0),
+    up:         _vec3(o.up,     0, 1, 0),
+    fov:        o.fov        !== undefined ? o.fov        : (ortho ? null : Math.PI / 3),
+    halfHeight: o.halfHeight !== undefined ? o.halfHeight : null,
+    near:       typeof o.near === 'number' ? o.near : 0.1,
+    far:        typeof o.far  === 'number' ? o.far  : 1000,
+  };
+}
+
+/**
+ * Copy one camera state into another (an orbit's home, a track's capture).
+ * @param {object} out  Destination state.
+ * @param {object} cam  Source state.
+ * @returns {object} out
+ */
+function cameraCopy(out, cam) {
+  out.eye[0]=cam.eye[0];       out.eye[1]=cam.eye[1];       out.eye[2]=cam.eye[2];
+  out.center[0]=cam.center[0]; out.center[1]=cam.center[1]; out.center[2]=cam.center[2];
+  out.up[0]=cam.up[0];         out.up[1]=cam.up[1];         out.up[2]=cam.up[2];
+  out.fov = cam.fov; out.halfHeight = cam.halfHeight;
+  out.near = cam.near; out.far = cam.far;
+  return out;
+}
+
 // =========================================================================
 // Builders — state → matrices
 // =========================================================================
@@ -3100,6 +3191,99 @@ function cameraToPose(pose, cam) {
   return pose;
 }
 
+// =========================================================================
+// Edits — in place, chainable, zero-alloc
+// =========================================================================
+
+/**
+ * Orbit the eye about the center: `dAz` rotates it about the up hint
+ * (right-handed); `dEl` raises its elevation above the plane through the
+ * center perpendicular to the hint, clamped to ±opts.maxEl so the view
+ * direction never reaches the hint (the pole guard). `up` is left as the hint
+ * it was, so an orbit never rolls. A state already at the pole is pulled
+ * inside the guard by its first non-zero edit; (0, 0) is a no-op.
+ *
+ * @param {object} cam
+ * @param {number} dAz  Azimuth delta, radians.
+ * @param {number} dEl  Elevation delta, radians.
+ * @param {{ maxEl?:number }} [opts]  Elevation limit; default π/2 − 1e-3.
+ * @returns {object} cam
+ */
+function cameraOrbit(cam, dAz, dEl, opts) {
+  if (dAz === 0 && dEl === 0) return cam;
+  const maxEl = Math.PI / 2 - 1e-3;
+  const e = cam.eye, c = cam.center;
+  let ux=cam.up[0], uy=cam.up[1], uz=cam.up[2];
+  const ul = Math.sqrt(ux*ux+uy*uy+uz*uz) || 1;
+  ux/=ul; uy/=ul; uz/=ul;
+  const dx=e[0]-c[0], dy=e[1]-c[1], dz=e[2]-c[2];
+  const r = Math.sqrt(dx*dx+dy*dy+dz*dz);
+  _frame(cam);
+  const px=_E$1[4], py=_E$1[5], pz=_E$1[6];            // the eye's up
+  const bx=_E$1[8], by=_E$1[9], bz=_E$1[10];           // back: center → eye, unit
+  // elevation: raise by θ within the (back, up) plane, clamped
+  const el  = Math.asin(Math.max(-1, Math.min(1, bx*ux+by*uy+bz*uz)));
+  const th  = Math.max(-maxEl, Math.min(maxEl, el + dEl)) - el;
+  const ct = Math.cos(th), st = Math.sin(th);
+  const ox = r*(bx*ct+px*st), oy = r*(by*ct+py*st), oz = r*(bz*ct+pz*st);
+  // azimuth: rotate about the hint (Rodrigues)
+  const ca = Math.cos(dAz), sa = Math.sin(dAz), k = (ux*ox+uy*oy+uz*oz)*(1-ca);
+  e[0] = c[0] + ox*ca + (uy*oz-uz*oy)*sa + ux*k;
+  e[1] = c[1] + oy*ca + (uz*ox-ux*oz)*sa + uy*k;
+  e[2] = c[2] + oz*ca + (ux*oy-uy*ox)*sa + uz*k;
+  return cam;
+}
+
+/**
+ * Dolly: scale the gaze distance by `factor` — the eye moves along the view
+ * direction under perspective; under orthographic (fov null, halfHeight set)
+ * halfHeight is scaled instead, since moving the eye changes nothing on
+ * screen. opts.min / opts.max clamp the scaled quantity. An edit that would
+ * make it non-positive is a no-op.
+ *
+ * @param {object} cam
+ * @param {number} factor
+ * @param {{ min?:number, max?:number }} [opts]
+ * @returns {object} cam
+ */
+function cameraDolly(cam, factor, opts) {
+  const min = opts && typeof opts.min === 'number' ? opts.min : 0;
+  const max = opts && typeof opts.max === 'number' ? opts.max : Infinity;
+  if (cam.fov == null && cam.halfHeight != null) {
+    const h = Math.max(min, Math.min(max, cam.halfHeight * factor));
+    if (h > 0) cam.halfHeight = h;
+    return cam;
+  }
+  const e = cam.eye, c = cam.center;
+  const dx=e[0]-c[0], dy=e[1]-c[1], dz=e[2]-c[2];
+  const r = Math.sqrt(dx*dx+dy*dy+dz*dz);
+  if (r === 0) return cam;
+  const r1 = Math.max(min, Math.min(max, r * factor));
+  if (!(r1 > 0)) return cam;
+  const s = r1 / r;
+  e[0]=c[0]+dx*s; e[1]=c[1]+dy*s; e[2]=c[2]+dz*s;
+  return cam;
+}
+
+/**
+ * Pan: translate eye and center by `dx` along the eye's right and `dy` along
+ * its up, world units. The caller converts pixels through pixelRatio at the
+ * center's depth so a pan tracks the pointer.
+ *
+ * @param {object} cam
+ * @param {number} dx
+ * @param {number} dy
+ * @returns {object} cam
+ */
+function cameraPan(cam, dx, dy) {
+  _frame(cam);
+  const tx=_E$1[0]*dx+_E$1[4]*dy, ty=_E$1[1]*dx+_E$1[5]*dy, tz=_E$1[2]*dx+_E$1[6]*dy;
+  const e = cam.eye, c = cam.center;
+  e[0]+=tx; e[1]+=ty; e[2]+=tz;
+  c[0]+=tx; c[1]+=ty; c[2]+=tz;
+  return cam;
+}
+
 /**
  * @file The view bag — the matrices every pick, solve, label and orbit reads.
  * @module host/view
@@ -4690,6 +4874,738 @@ class TrackHandles {
   }
 }
 
+/**
+ * @file Device streams — WebHID and Gamepad rate sources that feed a helm.
+ * @module host/stream
+ * @license AGPL-3.0-only
+ *
+ * The measure-by-subscription transports. Each yields lin[3] / ang[3] in raw
+ * device units and, once bind(helm) ran, calls helm.feed(lin, ang) every
+ * tick of the host's players — the helm's profile does all scaling, so a
+ * stream carries no configuration beyond identification and decoding.
+ *
+ *   hid     — WebHID. connect() must run from a user gesture; reports land
+ *             out of band into the stream's buffers and the frame reads the
+ *             latest (last-write-wins). Permissions-Policy gates
+ *             requestDevice to top-level documents: a stream in an iframe
+ *             without allow="hid" reports available === false and never
+ *             prompts.
+ *   gamepad — the Gamepad API, polled once per tick from
+ *             navigator.getGamepads(); an absent axis reads exactly 0.
+ *
+ * Both expose available and connected for a UI to reflect, and bind(helm),
+ * unbind(), dispose().
+ */
+
+
+const _nav = () => (typeof navigator !== 'undefined' ? navigator : null);
+
+/** The 3Dconnexion vendor ids: the SpaceNavigator and its successors. */
+const HID_FILTERS = [{ vendorId: 0x046d }, { vendorId: 0x256f }];
+
+/**
+ * The SpaceNavigator decode: report 1 carries translation, report 2
+ * rotation, each three int16 little-endian lanes; a firmware that packs all
+ * six lanes into one report fills both halves from it.
+ * @param {DataView} report   The report's data (the id byte excluded).
+ * @param {number} reportId
+ * @param {number[]} lin  Translation lanes, written.
+ * @param {number[]} ang  Rotation lanes, written.
+ */
+function decodeSpaceNavigator(report, reportId, lin, ang) {
+  if (report.byteLength >= 12) {
+    for (let i = 0; i < 3; i++) { lin[i] = report.getInt16(2 * i, true); ang[i] = report.getInt16(6 + 2 * i, true); }
+    return;
+  }
+  if (report.byteLength < 6) return;
+  const t = reportId === 1 ? lin : reportId === 2 ? ang : null;
+  if (!t) return;
+  for (let i = 0; i < 3; i++) t[i] = report.getInt16(2 * i, true);
+}
+
+/** Whether WebHID's requestDevice is allowed in this document. */
+function _hidAllowed() {
+  if (typeof document !== 'undefined' && document.featurePolicy && typeof document.featurePolicy.allowsFeature === 'function') {
+    return document.featurePolicy.allowsFeature('hid');
+  }
+  if (typeof window !== 'undefined' && 'top' in window) return window.top === window.self;
+  return true;
+}
+
+function _stream(host, lin, ang) {
+  let helm = null;
+  const s = {
+    /** The latest translation lanes, raw device units. */
+    lin,
+    /** The latest rotation lanes, raw device units. */
+    ang,
+    /** The bound helm, or null. */
+    get helm() { return helm; },
+    /**
+     * Feed a helm every tick. Chainable.
+     * @param {object} target  A PoseHelm (anything with feed(lin, ang)).
+     * @returns {object} this
+     */
+    bind(target) {
+      if (!target || typeof target.feed !== 'function') {
+        console.error('[host] stream: bind() target must have feed(lin, ang). Leaving unbound.');
+        return s;
+      }
+      helm = target;
+      return s;
+    },
+    /** Stop feeding; the helm sees its last rate until it is fed again. */
+    unbind() { helm = null; return s; },
+  };
+  const feed = () => { if (helm) helm.feed(lin, ang); };
+  return { s, feed };
+}
+
+/**
+ * A WebHID rate stream.
+ *
+ * @param {object} host
+ * @param {{ filters?:object[], decode?:function, bind?:object, resume?:boolean,
+ *           hid?:object }} [opts]
+ *        filters: the requestDevice filters (default HID_FILTERS). decode:
+ *        decode(report, reportId, lin, ang) (default decodeSpaceNavigator).
+ *        bind: a helm to bind at once. resume (default true): attach a device
+ *        this origin was already granted, without a prompt. hid: the WebHID
+ *        interface (default navigator.hid) — the seam a test fills.
+ * @returns {object} The stream: { available, connected, device, lin, ang,
+ *          connect(), bind(helm), unbind(), dispose() }.
+ */
+function createHid(host, opts) {
+  const o = opts || {};
+  const hid = o.hid || (_nav() && _nav().hid) || null;
+  const filters = o.filters || HID_FILTERS;
+  const decode = typeof o.decode === 'function' ? o.decode : decodeSpaceNavigator;
+  const lin = [0, 0, 0], ang = [0, 0, 0];
+  const { s, feed } = _stream(host, lin, ang);
+  let device = null;
+
+  const onReport = (e) => decode(e.data, e.reportId, lin, ang);
+  const onDisconnect = (e) => { if (device && e.device === device) detach(); };
+  const matches = (d) => filters.length === 0 || filters.some((f) =>
+    (f.vendorId == null || f.vendorId === d.vendorId) && (f.productId == null || f.productId === d.productId));
+
+  function detach() {
+    if (!device) return;
+    device.removeEventListener('inputreport', onReport);
+    if (device.opened && typeof device.close === 'function') device.close().catch(() => {});
+    device = null;
+    s.connected = false;
+    lin[0] = lin[1] = lin[2] = ang[0] = ang[1] = ang[2] = 0;
+  }
+
+  async function attach(d) {
+    detach();
+    try { if (!d.opened) await d.open(); }
+    catch (e) { console.error('[host] hid: open() failed: ' + e.message + '.'); return false; }
+    device = d;
+    d.addEventListener('inputreport', onReport);
+    s.connected = true;
+    return true;
+  }
+
+  Object.assign(s, {
+    /** Whether WebHID exists and requestDevice is allowed here. */
+    available: !!(hid && typeof hid.requestDevice === 'function') && _hidAllowed(),
+    /** Whether a device is open and reporting. */
+    connected: false,
+
+    /**
+     * Prompt for a device (a user gesture is required) and attach the choice.
+     * @returns {Promise<boolean>} attached
+     */
+    async connect() {
+      if (!s.available) { console.error('[host] hid: WebHID is unavailable here (a top-level Chromium document over https or localhost).'); return false; }
+      let devices;
+      try { devices = await hid.requestDevice({ filters }); }
+      catch (e) { console.error('[host] hid: requestDevice rejected: ' + e.message + '.'); return false; }
+      if (!devices || !devices.length) return false;
+      return attach(devices[0]);
+    },
+
+    /**
+     * Attach a device this origin was already granted, without a prompt.
+     * @returns {Promise<boolean>} attached
+     */
+    async resume() {
+      if (!hid || typeof hid.getDevices !== 'function') return false;
+      let devices;
+      try { devices = await hid.getDevices(); } catch (_) { return false; }
+      const d = (devices || []).find(matches);
+      return d ? attach(d) : false;
+    },
+
+    /** Close the device, remove every listener, unregister from the host. */
+    dispose() {
+      detach();
+      if (hid && typeof hid.removeEventListener === 'function') hid.removeEventListener('disconnect', onDisconnect);
+      host.players.remove(player);
+      host.unregister(s);
+      return s;
+    },
+  });
+
+  /** The open HIDDevice, or null. */
+  Object.defineProperty(s, 'device', { get: () => device, enumerable: true });
+
+  const player = { tick() { feed(); return true; } };
+  host.players.add(player);
+  if (hid && typeof hid.addEventListener === 'function') hid.addEventListener('disconnect', onDisconnect);
+  if (o.bind) s.bind(o.bind);
+  if (s.available && o.resume !== false) s.resume();
+  return host.register(s);
+}
+
+/**
+ * The default gamepad map, the standard layout: left stick → lin[0] / lin[1],
+ * right stick → ang[1] / ang[0], the triggers → lin[2] (right minus left).
+ */
+const GAMEPAD_MAP = { lin: [0, 1, { buttons: [6, 7] }], ang: [3, 2, null] };
+
+function _lane(gp, spec) {
+  if (spec == null) return 0;
+  if (typeof spec === 'number') { const v = gp.axes[spec]; return typeof v === 'number' ? v : 0; }
+  if (spec.buttons) {
+    const n = gp.buttons[spec.buttons[0]], p = gp.buttons[spec.buttons[1]];
+    return (p ? p.value : 0) - (n ? n.value : 0);
+  }
+  if (spec.button) { const b = gp.buttons[spec.button]; return b ? b.value : 0; }
+  return 0;
+}
+
+/**
+ * A Gamepad rate stream, polled once per tick.
+ *
+ * @param {object} host
+ * @param {{ index?:number, map?:object, bind?:object, gamepads?:function }} [opts]
+ *        index: which gamepad (default: the first connected). map: { lin,
+ *        ang }, each three lane specs — an axis index, { buttons: [neg,
+ *        pos] }, { button } or null (default GAMEPAD_MAP). bind: a helm to
+ *        bind at once. gamepads: the poll (default navigator.getGamepads) —
+ *        the seam a test fills.
+ * @returns {object} The stream: { available, connected, index, lin, ang,
+ *          bind(helm), unbind(), dispose() }.
+ */
+function createGamepad(host, opts) {
+  const o = opts || {};
+  const nav = _nav();
+  const poll = o.gamepads || (nav && typeof nav.getGamepads === 'function' ? () => nav.getGamepads() : null);
+  const map = o.map || GAMEPAD_MAP;
+  const lin = [0, 0, 0], ang = [0, 0, 0];
+  const { s, feed } = _stream(host, lin, ang);
+
+  Object.assign(s, {
+    /** Whether the Gamepad API exists. */
+    available: !!poll,
+    /** Whether the last poll found a gamepad. */
+    connected: false,
+    /** The gamepad index polled, or null for the first connected. */
+    index: o.index ?? null,
+    /** Stop polling, unregister from the host. */
+    dispose() { host.players.remove(player); host.unregister(s); return s; },
+  });
+
+  const player = {
+    tick() {
+      let gp = null;
+      if (poll) {
+        const list = poll() || [];
+        if (s.index != null) gp = list[s.index] || null;
+        else for (let i = 0; i < list.length; i++) if (list[i]) { gp = list[i]; break; }
+      }
+      s.connected = !!gp;
+      for (let i = 0; i < 3; i++) {
+        lin[i] = gp ? _lane(gp, map.lin[i]) : 0;
+        ang[i] = gp ? _lane(gp, map.ang[i]) : 0;
+      }
+      feed();
+      return true;
+    },
+  };
+  host.players.add(player);
+  if (o.bind) s.bind(o.bind);
+  return host.register(s);
+}
+
+/**
+ * @file Media sources — images, video and Canvas2D rasters for a bridge's textures.
+ * @module host/media
+ * @license AGPL-3.0-only
+ *
+ * What a texture upload reads from: an ImageBitmap fetched from a URL, a
+ * hidden <video> element from a file or the user's camera, a bitmap drawn
+ * through a 2D context (the text path — glyph strips, billboard tags,
+ * anything Canvas2D can typeset). No orientation option anywhere: whether
+ * rows flip is the bridge's upload, since it depends on the GPU API's
+ * texture space.
+ */
+
+
+/**
+ * Fetch an image into an ImageBitmap.
+ * @param {string} url
+ * @param {{ fetch?:object, bitmap?:object }} [opts]
+ *        fetch: the fetch init (credentials, mode, …). bitmap: the
+ *        createImageBitmap options (premultiplyAlpha, colorSpaceConversion, …).
+ * @returns {Promise<ImageBitmap>}
+ */
+async function loadImage(url, opts) {
+  const o = opts || {};
+  const res = await fetch(url, o.fetch);
+  if (!res.ok) throw new Error('[host] image: ' + url + ' → ' + res.status);
+  const blob = await res.blob();
+  return o.bitmap ? createImageBitmap(blob, o.bitmap) : createImageBitmap(blob);
+}
+
+/**
+ * A hidden, muted, inline <video> element from a file or the user's camera.
+ * `ready` resolves once metadata arrived (width / height known); a camera
+ * denial rejects it. Inside an iframe a camera source needs allow="camera"
+ * on the frame.
+ *
+ * @param {{ src?:string, camera?:boolean|object, loop?:boolean, autoplay?:boolean,
+ *           document?:object, media?:object }} opts
+ *        src: a media URL. camera: true or getUserMedia video constraints
+ *        ({ facingMode, width, height }). loop (default true for src).
+ *        autoplay (default true): start() once ready. document / media: the
+ *        Document and MediaDevices to use (defaults: the globals) — the seam
+ *        a test fills.
+ * @returns {{ el:HTMLVideoElement, ready:Promise<object>, width:number, height:number,
+ *             start():Promise<void>, stop():object, dispose():object }}
+ */
+function createVideo(opts) {
+  const o = opts || {};
+  const doc = o.document || (typeof document !== 'undefined' ? document : null);
+  if (!doc) { console.error('[host] video: no document.'); return null; }
+  const el = doc.createElement('video');
+  el.muted = true;
+  el.playsInline = true;
+  el.setAttribute('playsinline', '');
+  el.setAttribute('muted', '');
+  el.style.display = 'none';
+  let stream = null;
+
+  const v = {
+    /** The <video> element — the bridge's upload source, refreshed each frame. */
+    el,
+    /** Intrinsic size, known once `ready` resolved. */
+    width: 0, height: 0,
+    /** Resolves with this source once metadata arrived; rejects on a camera denial or a load error. */
+    ready: null,
+    /** Play; resolves when playback began. */
+    start() { const p = el.play(); return p && typeof p.catch === 'function' ? p.catch((e) => console.error('[host] video: play() failed: ' + e.message + '.')) : Promise.resolve(); },
+    /** Pause. Chainable. */
+    stop() { el.pause(); return v; },
+    /** Stop, release the camera tracks, detach the element. */
+    dispose() {
+      el.pause();
+      if (stream) { for (const t of stream.getTracks()) t.stop(); stream = null; }
+      el.removeAttribute('src');
+      el.srcObject = null;
+      if (typeof el.remove === 'function') el.remove();
+      return v;
+    },
+  };
+
+  v.ready = new Promise((resolve, reject) => {
+    const unlisten = () => { el.removeEventListener('loadedmetadata', onMeta); el.removeEventListener('error', onErr); };
+    const fail = (msg) => { unlisten(); reject(new Error('[host] video: ' + msg)); };
+    const onMeta = () => {
+      v.width = el.videoWidth || 0; v.height = el.videoHeight || 0;
+      unlisten();
+      if (o.autoplay !== false) v.start();
+      resolve(v);
+    };
+    const onErr = () => fail('failed to load ' + (o.src || 'the source') + '.');
+    el.addEventListener('loadedmetadata', onMeta);
+    el.addEventListener('error', onErr);
+    if (o.camera) {
+      const media = o.media || (typeof navigator !== 'undefined' && navigator.mediaDevices) || null;
+      if (!media || typeof media.getUserMedia !== 'function') { fail('getUserMedia is unavailable here.'); return; }
+      media.getUserMedia({ video: o.camera === true ? true : o.camera, audio: false })
+        .then((s) => { stream = s; el.srcObject = s; })
+        .catch((e) => fail('camera denied: ' + e.message + '.'));
+    } else if (o.src) {
+      el.loop = o.loop !== false;
+      el.src = o.src;
+    } else {
+      fail('needs { src } or { camera }.');
+    }
+  });
+  v.ready.catch(() => {});   // an unobserved rejection is the caller's to observe, not a crash
+  return v;
+}
+
+/**
+ * Draw through a 2D context and hand the result back as a texture source: an
+ * ImageBitmap where OffscreenCanvas exists, else the canvas element itself.
+ *
+ * @param {function(CanvasRenderingContext2D, number, number):void} draw
+ * @param {number} w  Pixel width.
+ * @param {number} h  Pixel height.
+ * @param {{ document?:object }} [opts]  The Document for the fallback canvas.
+ * @returns {ImageBitmap|HTMLCanvasElement|null}
+ */
+function raster(draw, w, h, opts) {
+  const o = opts || {};
+  if (typeof OffscreenCanvas !== 'undefined') {
+    const c = new OffscreenCanvas(w, h);
+    draw(c.getContext('2d'), w, h);
+    return c.transferToImageBitmap();
+  }
+  const doc = o.document || (typeof document !== 'undefined' ? document : null);
+  if (!doc) { console.error('[host] raster: no OffscreenCanvas and no document.'); return null; }
+  const c = doc.createElement('canvas');
+  c.width = w; c.height = h;
+  draw(c.getContext('2d'), w, h);
+  return c;
+}
+
+/**
+ * @file The label layer — DOM text over the canvas, anchored in world or screen space.
+ * @module host/labels
+ * @license AGPL-3.0-only
+ *
+ * The replacement for WEBGL text() in HUDs, gizmo labels and formula
+ * readouts, with the browser's own shaping. One absolutely positioned <div>
+ * overlays the canvas as its next sibling, pointer-events: none, sized by
+ * the canvas observer; the host sets the canvas parent to position:
+ * relative when it is static, and says so in the console once.
+ *
+ *   labels.set(id, text, x, y, z, opts)     // a world anchor, projected each tick()
+ *   labels.setScreen(id, text, sx, sy, opts) // canvas px, the HUD form
+ *   labels.remove(id) · labels.clear() · labels.visible
+ *   labels.tick()                            // after the view bag is current
+ *
+ * opts: dx / dy pixel offsets, anchor ('center' default, 'left', 'right'),
+ * 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
+ * hidden, not clamped. Elements are reused by id; tick() writes transforms
+ * only, text when the string changed.
+ */
+
+
+const _p = [0, 0, 0];
+const _ANCHOR = { center: -50, left: 0, right: -100 };
+const _NO_OPTS = {};
+
+/**
+ * Create the label layer of a canvas. The layer is inserted at once; it
+ * needs a parent, so create it after the canvas is in the document.
+ *
+ * @param {object} host  Its canvas, view bag and size are read.
+ * @param {{ document?:object }} [opts]  The Document (default: the global).
+ * @returns {object|null} The layer, or null without a document or a parent.
+ */
+function createLabels(host, opts) {
+  const o = opts || {};
+  const doc = o.document || (typeof document !== 'undefined' ? document : null);
+  const canvas = host.canvas;
+  const parent = canvas && canvas.parentNode;
+  if (!doc || !parent) { console.error('[host] labels: the canvas needs a parent element.'); return null; }
+
+  const el = doc.createElement('div');
+  el.className = 'host-labels';
+  Object.assign(el.style, {
+    position: 'absolute', left: '0px', top: '0px', width: '0px', height: '0px',
+    pointerEvents: 'none', overflow: 'hidden',
+  });
+  const cs = typeof getComputedStyle === 'function' ? getComputedStyle(parent) : null;
+  if (cs && cs.position === 'static') {
+    parent.style.position = 'relative';
+    console.info('[host] labels: set the canvas parent to position: relative for the label layer.');
+  }
+  parent.insertBefore(el, canvas.nextSibling);
+
+  const entries = new Map();   // id → { el, text, x, y, z, dx, dy, ax, screen, cls, sx, sy, shown }
+  let width = 0, height = 0, left = -1, top = -1, visible = true;
+
+  const entry = (id, text, o) => {
+    let e = entries.get(id);
+    if (!e) {
+      const span = doc.createElement('span');
+      Object.assign(span.style, { position: 'absolute', left: '0px', top: '0px', whiteSpace: 'nowrap', willChange: 'transform' });
+      span.style.visibility = 'hidden';
+      el.appendChild(span);
+      e = { el: span, text: null, x: 0, y: 0, z: 0, dx: 0, dy: 0, ax: -50, screen: false, cls: null, sx: NaN, sy: NaN, shown: false, frame: false, fresh: false };
+      entries.set(id, e);
+    }
+    if (e.text !== text) { e.text = text; e.el.textContent = text; }
+    const c = o.class || null;
+    if (e.cls !== c) { e.cls = c; e.el.className = c ? 'host-label ' + c : 'host-label'; }
+    e.ax = _ANCHOR[o.anchor] ?? -50;
+    e.dx = o.dx || 0; e.dy = o.dy || 0;
+    e.frame = !!o.frame; e.fresh = true;
+    return e;
+  };
+  const place = (e, sx, sy) => {
+    if (sx === e.sx && sy === e.sy) return;
+    e.sx = sx; e.sy = sy;
+    e.el.style.transform = 'translate(' + sx + 'px, ' + sy + 'px) translate(' + e.ax + '%, -50%)';
+  };
+  const show = (e, on) => {
+    if (e.shown === on) return;
+    e.shown = on;
+    e.el.style.visibility = on ? '' : 'hidden';
+  };
+
+  const labels = {
+    /** The layer element. */
+    el,
+    /** Whether the layer shows; false hides every label at once. */
+    get visible() { return visible; },
+    set visible(v) { visible = !!v; el.style.display = visible ? '' : 'none'; },
+    /** Live label count. */
+    get size() { return entries.size; },
+
+    /**
+     * Place a label at a world anchor, projected each tick().
+     * @param {string} id
+     * @param {string} text
+     * @param {number} x, y, z  World anchor.
+     * @param {{ dx?:number, dy?:number, anchor?:string, class?:string, frame?:boolean }} [opts]
+     * @returns {object} this
+     */
+    set(id, text, x, y, z, opts) {
+      const e = entry(id, text, opts || _NO_OPTS);
+      e.screen = false; e.x = x; e.y = y; e.z = z;
+      return labels;
+    },
+
+    /**
+     * Place a label in canvas px — the HUD form.
+     * @param {string} id
+     * @param {string} text
+     * @param {number} sx, sy  Canvas px, y down.
+     * @param {{ dx?:number, dy?:number, anchor?:string, class?:string, frame?:boolean }} [opts]
+     * @returns {object} this
+     */
+    setScreen(id, text, sx, sy, opts) {
+      const e = entry(id, text, opts || _NO_OPTS);
+      e.screen = true; e.x = sx; e.y = sy; e.z = 0;
+      return labels;
+    },
+
+    /** Remove a label. */
+    remove(id) {
+      const e = entries.get(id);
+      if (e) { el.removeChild(e.el); entries.delete(id); }
+      return labels;
+    },
+
+    /** Remove every label. */
+    clear() { for (const id of [...entries.keys()]) labels.remove(id); return labels; },
+
+    /**
+     * Project every world label through the view bag and write the
+     * transforms; hide what falls outside the canvas or the depth range.
+     * Call after the view bag is current for the frame.
+     * @returns {object} this
+     */
+    tick() {
+      const ol = canvas.offsetLeft || 0, ot = canvas.offsetTop || 0;
+      if (ol !== left || ot !== top) { left = ol; top = ot; el.style.left = ol + 'px'; el.style.top = ot + 'px'; }
+      const view = host.view;
+      for (const [id, e] of entries) {
+        if (e.frame && !e.fresh) { labels.remove(id); continue; }
+        e.fresh = false;
+        let sx, sy, on;
+        if (e.screen) { sx = e.x; sy = e.y; on = true; }
+        else if (!view || view.stale) { on = false; }
+        else {
+          mapLocation(_p, e.x, e.y, e.z, WORLD, SCREEN, view, view.vp, view.ndcZMin);
+          sx = _p[0]; sy = _p[1];
+          on = _p[2] >= 0 && _p[2] <= 1 && sx >= 0 && sx <= width && sy >= 0 && sy <= height;
+        }
+        if (on) place(e, sx + e.dx, sy + e.dy);
+        show(e, on);
+      }
+      return labels;
+    },
+
+    /**
+     * The observer's write: the layer's size in CSS px.
+     * @param {number} w
+     * @param {number} h
+     * @returns {object} this
+     */
+    resize(w, h) {
+      width = w; height = h;
+      el.style.width = w + 'px'; el.style.height = h + 'px';
+      return labels;
+    },
+
+    /** Remove the layer and its labels. */
+    dispose() {
+      entries.clear();
+      if (el.parentNode) el.parentNode.removeChild(el);
+      host.unregister(labels);
+      return labels;
+    },
+  };
+  labels.resize(host.width || 0, host.height || 0);
+  return host.register(labels);
+}
+
+/**
+ * @file The orbit — the fall-through camera gesture on unclaimed pointers.
+ * @module host/orbit
+ * @license AGPL-3.0-only
+ *
+ * What the handle gate yields to: one pointer orbits the camera state about
+ * its center, two pointers dolly by their distance and pan by their
+ * midpoint, the wheel dollies. update() consumes only unclaimed pointers and
+ * returns true when it moved the camera, so
+ *
+ *   if (!h.update()) orbit.update()
+ *
+ * reads as the gate. It writes cam only; the next setCamera(cam) installs it.
+ * Two-pointer motion is computed from the pointers' own coordinates, never
+ * from a browser's pinch synthesis, so it reads the same on every platform;
+ * the canvas gets touch-action: none while the orbit lives so the browser
+ * does not scroll or zoom the page instead. No damping, no inertia: direct
+ * manipulation wants exactness, and a sketch that wants smoothing lerps the
+ * camera it owns.
+ *
+ * Screen 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
+ * update, so a drag down always brings the scene down.
+ */
+
+
+const _clamp = { min: 0, max: Infinity };
+
+/**
+ * Create an orbit on a camera state.
+ *
+ * @param {object} host
+ * @param {object} cam  The camera state written.
+ * @param {{ rotate?:number, pan?:number, zoom?:number, wheel?:number,
+ *           minDistance?:number, maxDistance?:number, enabled?:boolean }} [opts]
+ *        rotate: radians per pixel (default 0.005). pan / zoom / wheel:
+ *        scalars on the two-pointer pan, the pinch and the wheel dolly
+ *        (default 1). minDistance / maxDistance: gaze-distance clamps.
+ * @returns {object} The orbit: { cam, enabled, rotate, pan, zoom, wheel,
+ *          minDistance, maxDistance, update(), home(), dispose() }.
+ */
+function createOrbit(host, cam, opts) {
+  const o = opts || {};
+  const canvas = host.canvas;
+  const home = cameraCopy(createCamera(), cam);
+  const tracked = new Map();   // pointer id → { x, y } as last consumed
+  let wheelAcc = 0;
+
+  const onWheel = (e) => {
+    if (typeof e.preventDefault === 'function') e.preventDefault();
+    const unit = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? (host.height || 1) : 1;
+    wheelAcc += (e.deltaY || 0) * unit;
+  };
+  canvas.addEventListener('wheel', onWheel, { passive: false });
+  const touchAction = canvas.style ? canvas.style.touchAction : undefined;
+  if (canvas.style) canvas.style.touchAction = 'none';
+
+  const track = (p) => {
+    let t = tracked.get(p.id);
+    if (!t) { t = { x: p.x, y: p.y }; tracked.set(p.id, t); }
+    else { t.x = p.x; t.y = p.y; }
+  };
+  const distance = () => {
+    const e = cam.eye, c = cam.center;
+    return Math.hypot(e[0] - c[0], e[1] - c[1], e[2] - c[2]);
+  };
+  const dolly = (factor) => {
+    _clamp.min = orbit.minDistance; _clamp.max = orbit.maxDistance;
+    cameraDolly(cam, factor, _clamp);
+  };
+
+  const orbit = {
+    /** The camera state written. */
+    cam,
+    /** False makes update() a no-op that drops its pointer memory. */
+    enabled: o.enabled !== false,
+    /** Radians per pixel of one-pointer drag. */
+    rotate: o.rotate ?? 0.005,
+    /** Scalar on the two-pointer pan. */
+    pan: o.pan ?? 1,
+    /** Scalar on the pinch dolly's exponent. */
+    zoom: o.zoom ?? 1,
+    /** Scalar on the wheel dolly. */
+    wheel: o.wheel ?? 1,
+    /** Gaze-distance clamps for every dolly. */
+    minDistance: o.minDistance ?? 0,
+    maxDistance: o.maxDistance ?? Infinity,
+
+    /**
+     * Consume this frame's unclaimed pointer motion and wheel into cam.
+     * @returns {boolean} Whether the camera moved.
+     */
+    update() {
+      if (!orbit.enabled) { tracked.clear(); wheelAcc = 0; return false; }
+      const src = host.pointer;
+      let a = null, b = null;
+      for (const p of src.pointers.values()) {
+        if (p.owner !== null || p.up || p.cancel) { tracked.delete(p.id); continue; }
+        if (a === null || p.id < a.id) { b = a; a = p; }
+        else if (b === null || p.id < b.id) b = p;
+      }
+      for (const id of tracked.keys()) {
+        if ((a === null || id !== a.id) && (b === null || id !== b.id)) tracked.delete(id);
+      }
+      let moved = false;
+      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
+      if (a !== null && b === null) {
+        const t = tracked.get(a.id);
+        if (t) {
+          const dx = a.x - t.x, dy = a.y - t.y;
+          if (dx !== 0 || dy !== 0) { cameraOrbit(cam, -dx * orbit.rotate, ys * dy * orbit.rotate); moved = true; }
+        }
+        track(a);
+      } else if (a !== null && b !== null) {
+        const ta = tracked.get(a.id), tb = tracked.get(b.id);
+        if (ta && tb) {
+          const dmx = (a.x + b.x - ta.x - tb.x) / 2, dmy = (a.y + b.y - ta.y - tb.y) / 2;
+          if (dmx !== 0 || dmy !== 0) {
+            const ratio = pixelRatio(view.mat4Proj, -view.vp[3] || 1, -distance(), view.ndcZMin);
+            cameraPan(cam, -dmx * ratio * orbit.pan, ys * dmy * ratio * orbit.pan);
+            moved = true;
+          }
+          const d0 = Math.hypot(ta.x - tb.x, ta.y - tb.y), d1 = Math.hypot(a.x - b.x, a.y - b.y);
+          if (d0 > 0 && d1 > 0 && d0 !== d1) { dolly(Math.pow(d0 / d1, orbit.zoom)); moved = true; }
+        }
+        track(a); track(b);
+      }
+      if (wheelAcc !== 0) {
+        dolly(Math.exp(wheelAcc * 0.001 * orbit.wheel));
+        wheelAcc = 0;
+        moved = true;
+      }
+      return moved;
+    },
+
+    /** Restore the pose captured at creation. */
+    home() { cameraCopy(cam, home); return orbit; },
+
+    /** Remove the wheel listener, restore touch-action, unregister from the host. */
+    dispose() {
+      canvas.removeEventListener('wheel', onWheel);
+      if (canvas.style) canvas.style.touchAction = touchAction;
+      tracked.clear();
+      host.unregister(orbit);
+      return orbit;
+    },
+  };
+  return host.register(orbit);
+}
+
 /**
  * @file The host context — one per canvas: pointer, view bag, players, loop, observer.
  * @module host
@@ -4706,6 +5622,10 @@ class TrackHandles {
  *   host.handle(opts) · host.router(handles, opts)
  *   host.cameraHelm(cam, opts) · host.poseHelm(opts)
  *   host.poseTrack(opts) · host.cameraTrack(cam, opts)
+ *   host.hid(opts) · host.gamepad(opts)
+ *   host.image(url) · host.video(opts) · host.raster(draw, w, h)
+ *   host.labels        // the DOM label layer, created on first access
+ *   host.orbit(cam, opts)
  *   host.tick(dt)      // external-loop mode
  *   host.dispose()
  *
@@ -4740,7 +5660,7 @@ function createHost(canvas, opts) {
   const o = opts || {};
   const t0 = _now();
   const constructs = new Set();
-  let loop = null, observer = null;
+  let loop = null, observer = null, labels = null;
   const host = {
     canvas,
     width: 0, height: 0, dpr: 1,
@@ -4788,6 +5708,28 @@ function createHost(canvas, opts) {
     poseTrack(opts) { return poseTrack(host, opts); },
     /** A core CameraTrack evaluating into a camera state while it plays — see host/track. */
     cameraTrack(cam, opts) { return cameraTrack(host, cam, opts); },
+    /** A WebHID 6-DOF rate stream — see host/stream. */
+    hid(opts) { return createHid(host, opts); },
+    /** A Gamepad rate stream, polled each tick — see host/stream. */
+    gamepad(opts) { return createGamepad(host, opts); },
+    /** Fetch an image into an ImageBitmap — see host/media. */
+    image(url, opts) { return loadImage(url, opts); },
+    /** A hidden <video> from a file or the camera, disposed with the host — see host/media. */
+    video(opts) { return host.register(createVideo(opts)); },
+    /** Draw through a 2D context into a texture source — see host/media. */
+    raster(draw, w, h, opts) { return raster(draw, w, h, opts); },
+    /**
+     * The label layer — see host/labels. Created on first access, so a
+     * canvas that never labels never gets a layer nor a repositioned parent.
+     */
+    get labels() {
+      if (labels === null) labels = createLabels(host);
+      return labels;
+    },
+    /** Whether the label layer exists, without creating it. */
+    get hasLabels() { return labels !== null; },
+    /** The fall-through camera gesture on unclaimed pointers — see host/orbit. */
+    orbit(cam, opts) { return createOrbit(host, cam, opts); },
 
     /** Register a construct with dispose() so host.dispose() releases it. */
     register(c) { if (c) constructs.add(c); return c; },
@@ -4799,6 +5741,7 @@ function createHost(canvas, opts) {
       if (loop) loop.stop();
       for (const c of [...constructs]) { if (typeof c.dispose === 'function') c.dispose(); }
       constructs.clear();
+      labels = null;
       observer.dispose();
       host.pointer.dispose();
       host.players.clear();
@@ -4811,6 +5754,7 @@ function createHost(canvas, opts) {
   observer = observeCanvas(canvas, (w, h, dpr) => {
     host.width = w; host.height = h; host.dpr = dpr;
     host.view.resize(w, h);
+    if (labels) labels.resize(w, h);
     if (typeof o.onSize === 'function') o.onSize(w, h, dpr);
   });
 
@@ -4829,5 +5773,5 @@ function createHost(canvas, opts) {
   return host;
 }
 
-export { Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createHost, createLoop, createPlayers, createPointer, createView, helmBasis, isConstraint, measureCanvas, observeCanvas, poseHelm, poseTrack, validConstraint };
+export { GAMEPAD_MAP, HID_FILTERS, Handle, PointerRouter, TrackHandles, VIEW, cameraHelm, cameraTrack, createGamepad, createHid, createHost, createLabels, createLoop, createOrbit, createPlayers, createPointer, createVideo, createView, decodeSpaceNavigator, helmBasis, isConstraint, loadImage, measureCanvas, observeCanvas, poseHelm, poseTrack, raster, validConstraint };
 //# sourceMappingURL=index.js.map