@displayxr/inline3d 1.49.2 → 1.50.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## Unreleased
+
+## 1.50.0 — 2026-11-04
+
+### Fixed — `./camera`, `./call`: half-width side-by-side webcams keep their aspect ratio
+
+A USB stereo webcam that sends 3840x2160 half-SBS came through as a 3840x1080 centre crop: each eye
+2x too tall, with half the vertical view. Such a camera (listed by USB id, since its shape matches
+a 4K webcam's) is now read in its native mode and sent as 2560x720 with square-pixel eyes. Needs
+`MediaStreamTrackProcessor`; without it the camera opens as before. `prefer: 'mono'` stays raw.
+
+### Added — `@displayxr/inline3d/hands`: tracked hands, and pinch controls for every viewer (`./hands`, `./viewer`, `./model`, `./splat`)
+
+Preview tier. The DisplayXR Browser 1.8.0+ (Windows, with a hand provider such as an Ultraleap
+tracker) exposes standard WebXR Hand Input on an inline-3D session: one `XRInputSource` per hand
+with a 25-joint `XRHand`, located in the same rig frame as the eye views. The new subpath reads it
+and turns it into controls:
+
+- `watchHands(wall, onFrame)` — the tracked hands every session frame (`poses`, `radii`,
+  `joint(name)`, `thumbTip`, `indexTip`, `palmLength`), the browser's per-frame gate
+  (`state.gate`: `'available'` or why hands are withheld) and the hand `inputsourceschange`.
+- `HandGestureController` / `PinchDetector` — the DisplayXR Model Viewer's gesture math, ported:
+  hand-relative throughout — the pinch thresholds (2.5 cm enter / 4 cm exit), the orbit gain
+  (10 rad/m) and the two-hand separation guard are all stated for a 9.5 cm palm and scale by the
+  hand's own palm length, so a hand that arrives scaled turns the subject by the same angle for
+  the same finger travel; one pinched hand orbits, two pinched hands zoom (separation ratio), roll
+  (twist) and orbit (midpoint drag); EMA-smoothed, anchored on every mode change.
+- `handControls(wall, target)` — drives anything with the viewer pose surface from those
+  gestures; and the option **`hands: true`** on `addModel` / `addSplat` (both engines, every
+  entry) wires it for you, exposed as `handle.hands`. Pointer and wheel keep working alongside.
+- `SceneViewer.nudgePose(delta)` and `PlayCanvasSplatViewer.nudgePose(delta)` — move the pose by
+  an eased delta, counting as input for the idle turntable (what the hands call; a page may too).
+- `OrbitPose.roll` on both viewers — degrees about the view axis, outside yaw and pitch (Euler
+  order `'ZXY'`; the PlayCanvas pivot quaternion gains the same Rz factor), bit-identical to
+  before at roll 0; `getPose()` now reports `roll`. (The first cut left the PlayCanvas viewer
+  without a roll axis, so the two-hand twist did nothing on the default engine — found on the
+  panel 2026-11-04.)
+
+Inert everywhere else: no hands, nothing moves, no errors. New sample `samples/hands/` (the raw
+surface), and `?hands` on `samples/model/` and `samples/splat/`. The porting guide's "no input
+sources" row is corrected (web#229). Tracks DisplayXR/displayxr-web#228.
+## 1.49.3 — 2026-11-04
+
+### Fixed — a camera view is not "woven" before the camera's first frame; `frameAgeMs` tells a stalled track (`.`, `./camera`, `./call`)
+
+Core and preview tier. A camera view (`addCameraView`, and the call's self view, which is one)
+registers its tile on the wall with an SBS buffer it fills from the camera. That buffer started
+as a blank default 300x150 canvas, and the wall counted any image source as a stereo frame, so
+`firstWoven` settled `woven: true` (`hold-elapsed`) on a tile that had never shown the camera.
+On an Android 3D tablet whose camera track was `live` but delivered no frames, the call reported
+the self view woven over a black tile.
+
+- **Core:** an `addImage` source that is a canvas or image with no pixels (0x0) is not a stereo
+  frame: `firstWoven` / `rewoven()` wait for one. Sources that report no size keep the old rule.
+- **`./camera`:** the woven buffer starts 0x0 until the first camera frame is painted into it.
+- **New: `view.frameAgeMs`** and `weaveState().frameAgeMs` (also `call.diagnostics().self`): ms
+  since the camera last delivered a new frame to the view, null before the first. A stalled track
+  keeps its last frame on screen; a growing age is how a page shows "no video".
+
 ## 1.49.2 — 2026-11-04
 
 ### Fixed — the camera probe waits for the DisplayXR 3D camera before opening a plain lens (`./camera`, `./call`)

package/README.md

@@ -35,6 +35,9 @@ import { addModel } from '@displayxr/inline3d/model';               // experimen
 import { addPlayer } from '@displayxr/inline3d/player';             // preview: a media player, built
                                                                     //   on addVideo, with transport
 import { SceneViewer } from '@displayxr/inline3d/viewer';           // experimental: framing + orbit
+import { handControls } from '@displayxr/inline3d/hands';          // experimental: tracked hands,
+                                                                    //   pinch to orbit (or `hands: true`
+                                                                    //   on addModel / addSplat)
 ```
 
 No build step or bundler required — it's plain ES modules. You can also import a pinned version by

package/camera.d.ts

@@ -285,6 +285,11 @@ export interface CameraViewWeaveState {
   firstWoven: { woven: boolean; confirmed: boolean; reason: string | null; ms: number } | 'pending' | null;
   /** Layer re-registrations attempted after a `'layer-failed'` (bounded; reset by a woven result). */
   layerRetries: number;
+  /**
+   * Milliseconds since the camera last delivered a new frame to the view, or null before the first.
+   * A stalled track keeps its last frame on screen; a growing age is how a page shows "no video".
+   */
+  frameAgeMs: number | null;
 }
 
 /** A self view from {@link addCameraView}. */