@displayxr/inline3d 1.49.1 → 1.49.3

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.
 
+## 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`)
+
+Preview tier. In a DisplayXR Browser the runtime lists its 3D camera lazily. On a phone it is
+missing from the list right after a runtime restart, or after the camera service restarted. With
+the 3D camera absent, `camera: 'auto'` read the list once more and then opened the plain front lens.
+On some phones that open crashes the camera HAL while head tracking streams. The HAL restart takes
+the 3D camera down again, so the call never got it back: the self view stayed 2D, or the call
+reported "Camera busy".
+
+- **The wait:** with camera labels visible and no stereo-named device listed, `'auto'` / `'stereo'`
+  now wait up to `stereoWaitMs` (new option, default **2500 ms in a DisplayXR Browser**, 0
+  elsewhere) before opening any plain lens. They re-read the list on every `devicechange` and every
+  500 ms, and open the 3D camera as soon as it appears. `'mono'`, an explicit `deviceId` and
+  `label:` never wait. The rule is in [`docs/camera.md`](docs/camera.md), "Waiting for the 3D camera".
+- **No shape probe of a second lens in a DisplayXR Browser:** once a plain lens is in hand, the
+  last-resort probe no longer opens the other plain lenses to test whether one is a side-by-side
+  pair. There, a stereo webcam (a USB SBS one included, through the runtime's UVC source) is the
+  runtime's named "3D Camera". The extra open is the one that can crash a phone's camera HAL. Other
+  browsers keep the shape probe, which is how a USB stereo webcam is found there.
+- **Pinned:** when the default camera opens but delivers no picture (0x0), a lens that opens by id
+  is kept as the fallback, never stopped and reported as busy. This has worked since 1.48.0; a test
+  now covers it.
+
 ## 1.49.1 — 2026-11-03
 
 ### Fixed — app share on browsers without the app-share device patch (`./call`, `./camera`)

package/camera.d.ts

@@ -73,6 +73,13 @@ export interface CameraOptions {
    * list off. An explicit `deviceId` or `label:` (`prefer`) is your choice and is opened regardless.
    */
   exclude?: ReadonlyArray<string | RegExp> | false;
+  /**
+   * `'auto'` / `'stereo'` with labels visible and no 3D camera listed: how long (ms) to wait for
+   * the runtime's 3D camera to be listed before any plain lens is opened. Default 2500 in a
+   * DisplayXR Browser, 0 elsewhere (one re-read of the list). Opening a phone lens while head
+   * tracking streams can crash the camera HAL on some devices and take the 3D camera down with it.
+   */
+  stereoWaitMs?: number;
   /** Verbose console logging. */
   debug?: boolean;
 }
@@ -278,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}. */