@displayxr/inline3d 1.49.3 → 1.51.0

package/docs/making-3d-look-right.md

@@ -3,15 +3,22 @@
 The SDK's defaults already give comfortable, real-looking 3D. These rules cover the mistakes seen
 on real panels; everything else about how your scene looks is your call.
 
-1. **Objects: keep the viewer's placement, and frame the first view.** `addModel`, `addSplat` and
-   `SceneViewer` scale the subject to its real proportions and centre it on the glass. That gives
-   it the smallest spread of disparity it can have. Don't push it back, shrink it or flatten it to
-   make it "more comfortable". The first view shows the whole subject, centred: a globe or a tank
+1. **The default depth is the glass. Keep the viewer's placement, and frame the first view.**
+   Centre your subject on z = 0 so it straddles the screen: a little in front, most of it just
+   behind, with as little total disparity as its shape allows. `addModel`, `addSplat` and
+   `SceneViewer` do this for you: they scale the subject to its real proportions and centre it on
+   the glass. A scene you build yourself follows the same rule. Don't push it back, shrink it or
+   flatten it to make it "more comfortable": recession costs disparity and crosstalk like pop-out
+   does, and only buys softness. Recede content only where it must clear something flat in front
+   of it (an HTML label over the scene), and only that part; HTML beside the scene needs no room.
+   The first view shows the whole subject, centred: a globe or a tank
    that starts low and cut off by the frame reads as broken. If the user can zoom, cap zoom-in
    before the subject comes uncomfortably far out, and leave room to zoom out.
-2. **Lay flat arrangements back into depth.** Orbits, a map, a board game: tilt the plane they lie
-   in back from the glass so it recedes, rather than looking straight down on it, where it reads
-   as flat circles. A chart, a figure or a building starts upright.
+2. **Tilt flat arrangements; don't push them back.** Orbits, a map, a board game: tilt the plane
+   they lie in about an axis through the glass (about 25–40° from face-on is plenty), so its near
+   edge comes slightly forward, its far edge recedes and its centre stays on the glass. Only the
+   exactly face-on view reads as flat circles; a fairly top-down view is fine. A chart, a figure
+   or a building starts upright.
 3. **Moving things: keep the forward swing small.** Objects that orbit, fly or swing toward the
    viewer are where pop-out becomes uncomfortable. Keep their paths mostly at or behind the glass,
    and fade them out as they come close to the viewer. A follow camera keeps its subject in frame

package/docs/woven-canvas-rules.md

@@ -159,7 +159,16 @@ one region are **refused as ambiguous**, and neither is drawn from. Cut between
 two pictures, blend them **inside one canvas**
 ([motion, §3 Crossfade](authoring-motion-and-effects.md#crossfade)).
 
-Many woven canvases in one frame (a gallery wall) are fine. Each one joins by its own identity.
+Many woven canvases in one frame (a gallery wall) are fine. Each one joins by its own identity,
+**as long as no two of them overlap.**
+
+**Never leave two woven canvases overlapping.** This is the static case of the crossfade: a splat
+canvas laid over a full-page scene canvas, both live. The Android DisplayXR Browser logs
+`[DisplayXR] inline-3D OVERLAPPING tiles …` and an `inline-3D recovery draw`; on a
+tablet the top canvas head-tracked but showed no stereo, and adding a second splat crashed the tab.
+The same page looked fine on a Windows panel, so a desktop check does not clear it. Hide the canvas
+underneath with `display: none` while the other one shows, and restore it when that one goes, so
+only one woven tile covers any point of the screen.
 
 ### 7. No CSS effects on a woven canvas or on any of its ancestors
 
@@ -362,6 +371,26 @@ like a runtime or browser bug on the panel and turned out to be the page.
   `wall.hardwareDisplayState === '2d'`. The SDK's eased mode switch ramps disparity out before the
   panel flips and in only after it reports 3D. The mode is display-wide: every woven tile goes flat
   while it is in force.
+- **A 2D/3D toggle: try the mode switch, then fall back.** Not every browser can forward a mode
+  request yet. The DisplayXR Browser for Android rejects `setStereoEnabled` /
+  `requestRenderingMode` with a `NotSupportedError` while still listing its modes as
+  `isRequestable: true`. You can't detect this in advance:
+  `isRequestable` overstates it, and the Android browser sends a desktop user agent. So call
+  `setStereoEnabled(false)` and, if it rejects with a `NotSupportedError`, flatten the image
+  yourself: ease your rig's `ipdFactor` and `parallaxFactor` to 0 over ~300 ms (the SDK's own
+  ramp length), and back to your values for 3D. Both views become identical and the image reads
+  flat, though the panel's lens stays on, so it is a softer 2D than the real 1-view mode. Keep
+  the button visible either way; only a different rejection (no 1-view mode listed at all) is a
+  reason to hide it.
+  ```js
+  async function setFlat(flat) {
+    try { await wall.setStereoEnabled(!flat); }
+    catch (e) {
+      if (e.name !== 'NotSupportedError') throw e;
+      easeRigFactors(flat ? 0 : 1, 300);   // your rig: ipdFactor / parallaxFactor × k
+    }
+  }
+  ```
 - **Keep the frames after `setSource` resolves free of per-splat CPU work.** A slideshow ran 105
   `pick()` calls (24 to plan an animation path, 81 for a diagnostic depth grid) right after every
   swap. On the Windows panel that was a 1.3 s main-thread stall at the end of every transition,

package/hands.d.ts

@@ -0,0 +1,198 @@
+// Type definitions for @displayxr/inline3d/hands.
+// EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
+//
+// Tracked hands on an inline-3D session (WebXR Hand Input, DisplayXR Browser 1.8.0+ on Windows
+// with a hand provider), and the pinch gestures that drive a viewer's orbit from them. Inert
+// everywhere else: `watchHands` reports no hands and `handControls` moves nothing.
+
+import type { Inline3D, Inline3DUnsupported } from './index.js';
+
+/** The 25 WebXR hand joint names, in `XRHand` iteration order. */
+export const HAND_JOINTS: ReadonlyArray<string>;
+
+/** Gesture tuning. Metres in the joints' frame (the rig frame), radians. */
+export interface HandGestureConfig {
+  /** Thumb-tip to index-tip distance that starts a pinch, for a hand of `referencePalmM` (default 0.025). */
+  pinchEnterM: number;
+  /** Distance that ends it, > enter (default 0.04). */
+  pinchExitM: number;
+  /**
+   * Palm length every distance here is stated for; a sample's own palm length scales them (pinch
+   * thresholds, orbit gain, separation guard), so a scaled hand behaves the same. 0 = never scale
+   * (default 0.095).
+   */
+  referencePalmM: number;
+  /** Radians of orbit per metre of pinch-point drag, for a reference-size hand (default 10). */
+  orbitRadPerM: number;
+  /** EMA time constant on the pinch point, seconds; 0 = off (default 0.05). */
+  smoothTauS: number;
+  /** Per-frame zoom ratio clamp, both ways (default 1.25). */
+  maxZoomStep: number;
+  /** Two-hand gestures are ignored while the hands are further apart than this (default 1.2). */
+  maxHandSeparationM: number;
+}
+export const HAND_GESTURE_DEFAULTS: Readonly<HandGestureConfig>;
+
+/** Two-threshold pinch state. */
+export declare class PinchDetector {
+  readonly pinched: boolean;
+  reset(): void;
+  /** `tracked: false` releases regardless of distance. Returns the new state. */
+  update(tracked: boolean, tipDistance: number, enter: number, exit: number): boolean;
+}
+
+/** One hand's input to the gesture controller. Positions `[x, y, z]`, metres. */
+export interface HandGestureSample {
+  tracked?: boolean;
+  thumbTip: ArrayLike<number>;
+  indexTip: ArrayLike<number>;
+  /** Wrist → middle knuckle, metres; 0 / absent = unknown (the metre thresholds apply as given). */
+  palmLength?: number;
+}
+
+/**
+ * The pose delta for one frame, in the SUBJECT's convention (what `SceneViewer.nudgePose` takes):
+ * yaw / pitch / roll in radians to ADD, zoom a ratio to MULTIPLY. A pinch dragged right → yaw +;
+ * dragged up → pitch −; two hands turning counter-clockwise → roll +; spreading → zoom > 1.
+ */
+export interface HandGestureDelta {
+  yaw: number;
+  pitch: number;
+  roll: number;
+  zoom: number;
+  /** Exactly one hand pinched this frame. */
+  oneHand: boolean;
+  /** Both hands pinched this frame. */
+  twoHand: boolean;
+  any: boolean;
+}
+
+/**
+ * Pinch gestures → pose deltas, per frame. Pure arithmetic (no DOM, no WebXR): a port of the
+ * DisplayXR Model Viewer's controls. Hand-relative pinch (thresholds scale by palm length), one
+ * pinched hand orbits, two pinched hands zoom (separation ratio), roll (twist in the display
+ * plane) and orbit (midpoint drag). The first frame of a gesture anchors; a hand gained or lost
+ * re-anchors, so a mode change never jumps.
+ */
+export declare class HandGestureController {
+  constructor(config?: Partial<HandGestureConfig>);
+  config: HandGestureConfig;
+  update(frame: {
+    /** Seconds, any origin (drives the EMA). */
+    time?: number;
+    left?: HandGestureSample | null;
+    right?: HandGestureSample | null;
+    /** Multiplies every position first (default 1). */
+    lengthScale?: number;
+  }): HandGestureDelta;
+  /** Pinch state after the last update: `0` / `'left'`, `1` / `'right'`. */
+  pinched(hand: 0 | 1 | 'left' | 'right'): boolean;
+  /** Last thumb-index tip distance, metres; < 0 when untracked. */
+  tipDistance(hand: 0 | 1 | 'left' | 'right'): number;
+  /** Forget every anchor. */
+  reset(): void;
+}
+
+/** Can this document deliver hand sources at all (`XRHand` present)? */
+export function handInputAvailable(): boolean;
+
+/**
+ * The browser's per-frame hand gate: `'available'`, a withheld reason (`'camera-rig'`,
+ * `'posed-rig'`, `'rig-factors'`, `'no-canvas'`, `'not-fullscreen'`, `'scaled-rig'`), or
+ * `'unknown'` where the session has no such surface.
+ */
+export function handGate(session: XRSession | null | undefined): string;
+
+/** One tracked hand as `watchHands` reports it. Positions `[x, y, z]` metres in the watch's reference space. */
+export interface HandSample {
+  readonly tracked: boolean;
+  readonly handedness: 'left' | 'right' | 'none';
+  /** 25 × 16 column-major joint transforms (`XRFrame.fillPoses`). */
+  readonly poses: Float32Array;
+  /** 25 joint radii, metres. */
+  readonly radii: Float32Array;
+  /** Position of a joint by WebXR name, or null for an unknown name. */
+  joint(name: string): number[] | null;
+  readonly wrist: number[];
+  readonly thumbTip: number[];
+  readonly indexTip: number[];
+  /** Wrist → middle knuckle, metres. */
+  readonly palmLength: number;
+  readonly source: XRInputSource;
+}
+
+export interface HandsFrame {
+  /** Seconds (the session frame time / 1000). */
+  time: number;
+  /** As `handGate()`. */
+  gate: string;
+  left: HandSample | null;
+  right: HandSample | null;
+  /** Hands tracked this frame. */
+  hands: number;
+  frame: XRFrame;
+}
+
+export interface HandsWatch {
+  stop(): void;
+  readonly running: boolean;
+  readonly state: { gate: string; hands: number; supported: boolean };
+}
+
+export interface WatchHandsOptions {
+  /** Joints are located in this space (default: the wall's `refSpace`). */
+  referenceSpace?: XRReferenceSpace;
+  /** `inputsourceschange`, hand sources only. */
+  onChange?: (e: { added: XRInputSource[]; removed: XRInputSource[] }) => void;
+}
+
+/**
+ * Watch the hands on an inline-3D session: `onFrame` every session frame with the tracked hands
+ * (or none). Runs its own `session.requestAnimationFrame` loop beside the SDK's; stops itself
+ * when the session ends.
+ */
+export function watchHands(
+  wall: Inline3D | Inline3DUnsupported | null | undefined,
+  onFrame: (f: HandsFrame) => void,
+  opts?: WatchHandsOptions,
+): HandsWatch;
+
+export interface HandControlOptions extends WatchHandsOptions {
+  /** Controller tuning. */
+  gestures?: Partial<HandGestureConfig>;
+  /** Multiplies every hand position before the gesture math (default 1). */
+  lengthScale?: number;
+  /** Apply the two-hand roll where the viewer has a roll axis (default true). */
+  roll?: boolean;
+  /** Apply the two-hand zoom (default true). */
+  zoom?: boolean;
+  /** After each frame: the hands frame and the gesture delta. */
+  onFrame?: (f: HandsFrame, d: HandGestureDelta) => void;
+}
+
+/** What `handControls` returns, and what `handle.hands` is on an `addModel` / `addSplat` handle. */
+export interface HandControls {
+  stop(): void;
+  readonly running: boolean;
+  readonly controller: HandGestureController;
+  readonly state: { gate: string; hands: number; supported: boolean };
+}
+
+/** Anything with the viewer pose surface: a SceneViewer, the PlayCanvas viewer, or a handle whose `viewer` is one. */
+export interface HandControlTarget {
+  nudgePose?(delta: { yaw?: number; pitch?: number; zoom?: number; roll?: number }): void;
+  getPose?(opts?: { target?: boolean }): { yaw: number; pitch: number; zoom: number; roll?: number };
+  setPose?(pose: { yaw?: number; pitch?: number; zoom?: number; roll?: number }): void;
+  readonly viewer?: HandControlTarget | null;
+}
+
+/**
+ * Drive a viewer's orbit from the hands: one pinch dragged turns it, two pinches spread / twist
+ * / dragged zoom / roll / turn it. Prefers `viewer.nudgePose()` (eased, counts as input for the
+ * idle turntable), falls back to `getPose` + `setPose`. Pointer and wheel keep working.
+ */
+export function handControls(
+  wall: Inline3D | Inline3DUnsupported | null | undefined,
+  target: HandControlTarget,
+  opts?: HandControlOptions,
+): HandControls;

package/index.d.ts

@@ -522,6 +522,10 @@ export interface TileHandle {
    * its layer, and a window that never set a rig at all.
    *
    * Rejects with an `Error` when no such mode is listed, otherwise as `requestRenderingMode` does.
+   * A browser that cannot forward mode requests (the Android DisplayXR Browser today)
+   * rejects with a `NotSupportedError` even though its modes read
+   * `isRequestable: true`. Try, then fall back to easing your rig's `ipdFactor`/`parallaxFactor`
+   * to 0 — docs/woven-canvas-rules.md, "A 2D/3D toggle".
    */
   setStereoEnabled(enabled: boolean): Promise<boolean>;
   /** Listen for one display event, re-emitted on this handle. Returns an unsubscribe function. */

package/js/call/share.js

@@ -24,6 +24,7 @@
 
 import { isAppShareDevice, isAppShareHint, legacyAppCandidate, appNameFromLabel, APP_SHARE_ID_PREFIX, APP_SHARE_LABEL_RE, APP_SHARE_LEGACY_LABEL_RE } from '../camera/app-share.js';
 import { sanitizeName, CONV_MAX_FRAC } from './wire.js';
+import { unsqueezeTrack } from '../camera/half-sbs.js';
 
 export { isAppShareDevice, isAppShareHint, legacyAppCandidate, appNameFromLabel, APP_SHARE_ID_PREFIX, APP_SHARE_LABEL_RE, APP_SHARE_LEGACY_LABEL_RE };
 
@@ -177,3 +178,92 @@ export async function openAppShare(deviceId, o = {}) {
   }
   return { stream, track, descriptor: describeAppShare(track) };
 }
+
+/** The hint layout of a stereo tab capture: each eye squeezed to half the frame's width. */
+export const TAB_SHARE_LAYOUT = 'side-by-side-half';
+
+/** Does this `displayxrStereo` hint describe a stereo tab capture? Pure. */
+export function isTabShareHint(hint) {
+  return !!hint && typeof hint === 'object' && hint.source === 'tab' && hint.layout === TAB_SHARE_LAYOUT;
+}
+
+/**
+ * Let the user pick a browser tab to share, in 3D where the browser can. The browser's own picker
+ * is the consent. On a browser that captures tabs in stereo, a picked tab comes back as a true
+ * side-by-side track (`format: 'sbs'`), the same shape an app share has, so receivers need nothing
+ * new. A window or a screen, or a browser without stereo capture, comes back flat (`format: 'mono'`).
+ * The track ends when the sharing stops or the tab closes. Stop it yourself when you stop sharing.
+ *
+ * Cancelling the picker rejects with `code: 'share-denied'`; anything else with `'share-failed'`.
+ *
+ * @param {{ width?: number, frameRate?: number, mediaDevices?: MediaDevices, unsqueeze?: typeof unsqueezeTrack }} [o]
+ */
+export async function openTabShare(o = {}) {
+  const md = o.mediaDevices || (typeof navigator !== 'undefined' ? navigator.mediaDevices : null);
+  if (!md || typeof md.getDisplayMedia !== 'function') {
+    throw Object.assign(new Error('this browser cannot share a tab'), { code: 'share-failed' });
+  }
+  const frameRate = o.frameRate > 0 ? o.frameRate : SHARE_CONSTRAINTS.frameRate;
+  let stream;
+  try {
+    stream = await md.getDisplayMedia({
+      video: { width: { ideal: o.width > 0 ? o.width : SHARE_CONSTRAINTS.width }, frameRate: { ideal: frameRate } },
+      audio: false,
+      displayxrStereo: true,
+    });
+  } catch (err) {
+    const denied = err && (err.name === 'NotAllowedError' || err.name === 'AbortError');
+    throw Object.assign(new Error(denied ? 'the share was declined' : 'the tab could not be shared'), {
+      code: denied ? 'share-denied' : 'share-failed',
+      cause: err,
+    });
+  }
+  const source = stream.getVideoTracks()[0];
+  const st = (source && typeof source.getSettings === 'function' && source.getSettings()) || {};
+  const hint = st.displayxrStereo;
+  const flat = {
+    stream,
+    track: source,
+    stereo: false,
+    descriptor: {
+      kind: 'content',
+      format: 'mono',
+      width: st.width > 0 ? st.width : 0,
+      height: st.height > 0 ? st.height : 0,
+      convergence: { known: true, frac: 0 },
+      appName: null,
+    },
+  };
+  let out = flat;
+  if (isTabShareHint(hint)) {
+    const pair = (o.unsqueeze || unsqueezeTrack)(source, st.width, st.height, st.frameRate > 0 ? st.frameRate : frameRate);
+    if (!pair) {
+      // Sent as it is, every receiver would see two squeezed halves: refuse instead.
+      stream.getTracks().forEach((t) => t.stop());
+      throw Object.assign(new Error('this browser cannot convert a stereo tab capture'), { code: 'share-failed' });
+    }
+    const z = hint.zeroDisparityShiftFrac;
+    out = {
+      stream: pair.stream,
+      track: pair.track,
+      stereo: true,
+      descriptor: {
+        kind: 'content',
+        format: 'sbs',
+        width: pair.width,
+        height: pair.height,
+        convergence: {
+          known: true,
+          frac: typeof z === 'number' && Number.isFinite(z) ? Math.max(-CONV_MAX_FRAC, Math.min(CONV_MAX_FRAC, z)) : 0,
+        },
+        appName: null,
+      },
+    };
+  }
+  try {
+    out.track.contentHint = 'detail'; // text and resolution over frame rate
+  } catch {
+    /* older engines */
+  }
+  return out;
+}

package/js/camera/capture.js

@@ -41,6 +41,7 @@
 // `(stream, info) => MediaStream | Promise<MediaStream>`, returning a rectified SBS stream.
 
 import { looksSbs } from './geometry.js';
+import { isHalfSbsCamera, unsqueezeHalfSbs } from './half-sbs.js';
 import { isAppShareDevice, isAppShareHint } from './app-share.js';
 
 const MONO_CONSTRAINTS = { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } };
@@ -213,6 +214,14 @@ export async function openCamera(want = 'auto', o = {}) {
     // or — on a browser without the app-share device patch, which lists the app as a "3D Camera
     // (DisplayXR) - <app>" — baseline 0 and FOV 0, which no real camera advertises. Every probe
     // path checks this on the OPENED track (rejectOpened), since the label cannot tell them apart.
+    // A half-SBS webcam: send true side-by-side eyes, whichever path opened it. 'mono' stays raw.
+    if (want !== 'mono' && isHalfSbsCamera(t.label)) {
+      const pair = await unsqueezeHalfSbs(t);
+      if (pair) {
+        log('camera-half-sbs', { label: t.label, width: pair.width, height: pair.height });
+        return { ...pair, deviceId: st.deviceId || null, label: t.label, stereo: null, appShare: false };
+      }
+    }
     const appShare = isAppShareDevice({ label: t.label || '', deviceId: st.deviceId || '' }) || isAppShareHint(st.displayxrStereo);
     return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '', stereo, appShare };
   };

package/js/camera/half-sbs.js

@@ -0,0 +1,109 @@
+// camera/half-sbs.js — USB stereo webcams that send a half-width side-by-side frame: one 16:9
+// image whose left and right halves are each an eye squeezed 2:1 in width.
+//
+// Shape cannot identify these: a 3840x2160 half-SBS frame looks exactly like a 4K webcam's, so they
+// are listed by USB id. Asking one for a wide mode does not help either: the browser reaches
+// 3840x1080 by cropping the middle rows of 3840x2160, which still reads as a pair but leaves each
+// eye 2x too tall with half the vertical view. So the camera is read in its native mode and every
+// frame is redrawn, eyes un-squeezed, into a true side-by-side track.
+
+/** USB `vvvv:pppp` ids of cameras that send half-SBS (the browser's label ends with the id). */
+export const HALF_SBS_USB_IDS = Object.freeze(['0733:011a']);
+
+/** The widest eye sent: the runtime's own output for such a camera (2560x720 side by side). */
+const MAX_EYE_WIDTH = 1280;
+const NATIVE_CONSTRAINTS = { width: { ideal: 3840 }, height: { ideal: 2160 }, frameRate: { ideal: 30 }, resizeMode: 'none' };
+
+/** Does this device label name a half-SBS camera? */
+export function isHalfSbsCamera(label) {
+  const l = String(label || '').toLowerCase();
+  return HALF_SBS_USB_IDS.some((id) => l.includes(`(${id})`));
+}
+
+/** The full-SBS frame size for a half-SBS source: square-pixel eyes, no upscaling, even numbers. */
+export function unsqueezedSize(width, height) {
+  const eyeW = Math.min(MAX_EYE_WIDTH, width);
+  const eyeH = Math.max(2, Math.round((eyeW * height) / width / 2) * 2);
+  return { width: eyeW * 2, height: eyeH };
+}
+
+/**
+ * Put `source` in its native mode and return a side-by-side track with the eyes un-squeezed, or
+ * null when that cannot be done here (the engine has no MediaStreamTrackProcessor or the camera
+ * refuses a 16:9 mode); the source is then left open as it is. Stopping the returned track stops
+ * the source.
+ *
+ * @param {MediaStreamTrack} source
+ * @returns {Promise<{stream: MediaStream, track: MediaStreamTrack, width: number, height: number}|null>}
+ */
+export async function unsqueezeHalfSbs(source) {
+  if (typeof MediaStreamTrackProcessor !== 'function' || typeof document === 'undefined') return null;
+  try {
+    await source.applyConstraints(NATIVE_CONSTRAINTS);
+  } catch {
+    return null;
+  }
+  const st = source.getSettings();
+  if (!(st.width > 0) || !(st.height > 0) || Math.abs(st.width / st.height - 16 / 9) > 0.01) return null;
+  return unsqueezeTrack(source, st.width, st.height, st.frameRate);
+}
+
+/**
+ * Redraw a half-width side-by-side `source` of `srcW`x`srcH` into a true side-by-side track, or null
+ * when the engine cannot. Each eye keeps the frame's aspect. Stopping the returned track stops the
+ * source; the source ending ends the returned track.
+ *
+ * @param {MediaStreamTrack} source
+ * @param {number} srcW
+ * @param {number} srcH
+ * @param {number} [frameRate]
+ * @returns {{stream: MediaStream, track: MediaStreamTrack, width: number, height: number}|null}
+ */
+export function unsqueezeTrack(source, srcW, srcH, frameRate) {
+  if (typeof MediaStreamTrackProcessor !== 'function' || typeof document === 'undefined') return null;
+  let { width, height } = unsqueezedSize(srcW, srcH);
+  let srcSeenW = srcW;
+  let srcSeenH = srcH;
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext('2d', { alpha: false });
+  if (!ctx) return null;
+  const stream = canvas.captureStream(frameRate > 0 ? frameRate : 30);
+  const track = stream.getVideoTracks()[0];
+  const reader = new MediaStreamTrackProcessor({ track: source }).readable.getReader();
+
+  let stopped = false;
+  const stopTrack = track.stop.bind(track);
+  track.stop = () => {
+    stopped = true;
+    reader.cancel().catch(() => {});
+    source.stop();
+    stopTrack();
+  };
+  (async () => {
+    for (;;) {
+      const { value: frame, done } = await reader.read();
+      if (done) break;
+      // Follow the frames, not the settings: a captured tab's frames are not the size its track
+      // reports, and it changes when the tab resizes.
+      if (frame.displayWidth > 0 && frame.displayHeight > 0 && (frame.displayWidth !== srcSeenW || frame.displayHeight !== srcSeenH)) {
+        srcSeenW = frame.displayWidth;
+        srcSeenH = frame.displayHeight;
+        const next = unsqueezedSize(srcSeenW, srcSeenH);
+        canvas.width = width = next.width;
+        canvas.height = height = next.height;
+      }
+      ctx.drawImage(frame, 0, 0, width, height);
+      frame.close();
+    }
+  })()
+    .catch(() => {})
+    .finally(() => {
+      if (stopped) return;
+      // The camera went away: this track ends with it, like the device's own would.
+      track.stop();
+      track.dispatchEvent(new Event('ended'));
+    });
+  return { stream, track, width, height };
+}

package/js/inline3d-call.js

@@ -116,7 +116,7 @@ export { DxrCallElement, defineCallElement, attrsToOpts, CALL_EVENT_PREFIX } fro
 export { dxrSignaling, DXR_SIGNAL_DEFAULT } from './call/signaling.js';
 export { parseInviteLink };
 // 3D screen share (runtime ADR-061): find and open a running DisplayXR app as content.
-export { isAppShareDevice, listShareableApps, watchShareableApps, openAppShare } from './call/share.js';
+export { isAppShareDevice, listShareableApps, watchShareableApps, openAppShare, openTabShare } from './call/share.js';
 
 const TAG = '[inline3d/call]';
 const HELLO_WAIT_MS = 2000;